refactor: rename package to @photon-ai/cli

[citron (lcandy2)]

Why

@photon-ai/photon was redundant — the binary is photon and the package name shouldn't repeat the binary name. Industry convention (@vercel/cli, @supabase/cli, @dokploy/cli) is @<scope>/cli, which reads more naturally and avoids the doubled-up phrasing.

The npm-11-npx caveat that almost blocked this

In PR #12 we discovered that npm 11's npx <scoped-pkg> (no version pin) only auto-resolves the binary under specific conditions, and we attributed it to "post-scope segment must match the bin name". On that reading, renaming to @photon-ai/cli (with bin photon) would break unpinned npx — so I asked before doing the rename.

Researching prior art with @dokploy/cli — bin dokploy, post-scope cli, names don't match, but npx @dokploy/cli works unpinned — proved that reading wrong. The actual npm 11 rule is simpler: single-bin auto-resolves regardless of name match. PR #12's bug was specifically the multi-bin shape ({ photon, pho }), not the post-scope mismatch.

So this rename is safe as long as we keep bin to a single entry. Switching from string-form to single-key object:

-  "bin": "./dist/photon.js"
+  "bin": { "photon": "./dist/photon.js" }

The string form would have made npm register the binary under the post-scope name (cli) — which would break every existing photon / pho user invocation. The explicit object pins the binary name back to photon.

Verified locally with @photon-ai/cli@0.1.3 tarball

$ npm pack
photon-ai-cli-0.1.3.tgz

# bin shape in the published manifest:
{ "name": "@photon-ai/cli", "bin": { "photon": "./dist/photon.js" } }

# bun add -g (primary install path)
$ bun add -g ./photon-ai-cli-0.1.3.tgz
$ photon --version
0.1.3
$ photon ...        # first run creates ~/.bun/bin/pho symlink
$ pho --version
0.1.3

# npm install (local, npx-resolution proxy)
$ npm install ./photon-ai-cli-0.1.3.tgz
$ ./node_modules/.bin/photon --version
0.1.3

After publish, the empirical test of unpinned npx will be npx @photon-ai/cli --version from a clean directory.

Files changed

• package.json — name, bin
• .github/workflows/release.yaml — service-name
• README.md — install snippets (npx, bunx, bun add -g examples)
• src/lib/pho-alias.ts — comment updated to reflect single-entry-object shape

Migration

@photon-ai/photon@0.1.3 becomes the final version on the old name. Existing users re-install with bun add -g @photon-ai/cli. After this PR ships, npm deprecate @photon-ai/photon "moved to @photon-ai/cli" is a one-liner follow-up.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith with what you need.}

• Let Codesmith autofix CI failures and bot reviews

Summary by CodeRabbit

• Chores
  • Package renamed from @photon-ai/photon to @photon-ai/cli across release workflow, documentation, and configuration files

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8674c2a6-1b96-48bb-9419-02f60fd44194

📥 Commits

Reviewing files that changed from the base of the PR and between d553de5 and 57f70c6.

📒 Files selected for processing (4)

• .github/workflows/release.yaml
• README.md
• package.json
• src/lib/pho-alias.ts

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (4)

package.json

📄 CodeRabbit inference engine (CLAUDE.md)

package.json: Use bun install instead of npm install, yarn install, or pnpm install in package.json
Use bun run <script> instead of npm run <script>, yarn run <script>, or pnpm run <script>

Files:

• package.json

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx,js,jsx}: Use bun <file> instead of node <file> or ts-node <file>
Bun automatically loads .env, so don't use dotenv
Use Bun.serve() with WebSockets, HTTPS, and routes instead of express
Use bun:sqlite for SQLite instead of better-sqlite3
Use Bun.redis for Redis instead of ioredis
Use Bun.sql for Postgres instead of pg or postgres.js
Use built-in WebSocket instead of ws package
Prefer Bun.file over node:fs's readFile/writeFile for file operations
Use Bun.$ template literal for shell commands instead of execa
Use bun --hot to run server files with hot module reloading

Files:

• src/lib/pho-alias.ts

**/*.{html,ts,tsx,css}

📄 CodeRabbit inference engine (CLAUDE.md)

Use bun build <file.html|file.ts|file.css> instead of webpack or esbuild

Files:

• src/lib/pho-alias.ts

**/*.{html,ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

Use HTML imports with Bun.serve() for frontend instead of Vite

Files:

• src/lib/pho-alias.ts

🔍 Remote MCP Linear

Based on my search of Linear, I found relevant context about similar package renaming patterns in the Photon ecosystem. Here's what I discovered:

Additional Context for PR Review

Similar Package Renaming Pattern Found

ENG-1006 completed a similar package rename for the Cosmos CLI package, changing it from a generic name to cosmos-cli to clearly indicate it is a CLI client. This establishes a precedent within the Photon organization for this naming convention.

Applicable Scoped Package Publishing Standard

ENG-1262 demonstrates the organization's standard approach to publishing under the @photon-ai npm organization, including setting publishConfig.access to "public" for scoped packages, which default to private otherwise. This context helps validate that the publishing configuration approach in this PR follows established practices.

Package Publishing Process

The PR's migration strategy (keeping @photon-ai/photon@0.1.3 as the final version, with deprecation planned after publishing the new package name) aligns with industry standard npm package transition practices, though the Linear search did not surface a specific documented policy for this workflow.

bin Field Convention

The change from bin: "./dist/photon.js" (string form) to bin: { "photon": "./dist/photon.js" } (explicit object form) is a valid npm package configuration pattern. The PR description clarifies that npm 11's unpinned npx auto-resolution behavior works correctly for single-bin packages regardless of the post-scope segment name, supporting the effectiveness of this approach.,

🔇 Additional comments (4)

package.json (1)

2-2: Package rename + single-bin mapping look correct.

This preserves the photon executable while moving the package identity to @photon-ai/cli, matching the migration goal cleanly.

Also applies to: 24-26

.github/workflows/release.yaml (1)

29-29: Release workflow is correctly aligned with the new package name.

service-name now matches @photon-ai/cli, so release automation stays consistent with the rename.

src/lib/pho-alias.ts (1)

10-11: Comment update is accurate and helpful.

The explanation now matches the new package name and documented single-entry bin strategy.

README.md (1)

6-7: README install examples are updated consistently.

The renamed package appears correctly across quick-start and install snippets while preserving photon command usage.

Also applies to: 19-20, 32-32

---

📝 Walkthrough

Walkthrough

The package name is renamed from @photon-ai/photon to @photon-ai/cli, with the bin field updated from a string to an object form. The release workflow, README, and code comments are updated to reflect this naming change across documentation and configuration.

Changes

Package Rename to @photon-ai/cli

Layer / File(s)	Summary
Package Configuration package.json	Package name changed from @photon-ai/photon to @photon-ai/cli; bin field changed from "./dist/photon.js" to { "photon": "./dist/photon.js" }.
Release Workflow .github/workflows/release.yaml	Service name input to typescript-service-release.yaml reusable workflow updated from @photon-ai/photon to @photon-ai/cli.
Documentation & Comments README.md, src/lib/pho-alias.ts	Installation examples and inline documentation updated to reference @photon-ai/cli package; comment in pho-alias.ts clarified bin declaration format and updated npx usage examples.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• photon-hq/cli#12: Modifies the same package.json bin setup and src/lib/pho-alias.ts logic.
• photon-hq/cli#11: Updates package name/bin entries and the release workflow service-name configuration identically.
• photon-hq/cli#13: Updates README and src/lib/pho-alias.ts comments for the CLI naming change.

Poem

🐰 A new name gleams in the CLI dawn,
From photon to cli, the old guard withdrawn.
Binaries bundled, docs freshly penned,
The package renamed—a bright rebrand! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'refactor: rename package to @photon-ai/cli' is concise, clear, and directly summarizes the main change in the changeset—renaming the package from @photon-ai/photon to @photon-ai/cli.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

Warning

Review ran into problems

🔥 Problems

These MCP integrations need to be re-authenticated in the Integrations settings: Linear

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR renames the published npm package from @photon-ai/photon to @photon-ai/cli while preserving the photon binary name (and continuing to rely on the runtime-created pho alias) to maintain expected install and npx behavior.

Changes:

• Renamed the npm package to @photon-ai/cli and changed bin to a single-key object mapping (photon → ./dist/photon.js).
• Updated release workflow metadata to publish under the new package name.
• Updated README install/usage snippets and the pho alias rationale comment to reflect the new package name and bin shape.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
package.json	Renames package to @photon-ai/cli and pins the binary name via single-key bin object.
.github/workflows/release.yaml	Updates release workflow service-name to match the new npm package name.
README.md	Updates install/usage examples to use @photon-ai/cli.
src/lib/pho-alias.ts	Updates documentation comment to reflect new bin shape and package name in npx examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.