feat: prepare for npm publish + binary releases (Phase 10)#11
Merged
Conversation
Phase 10 — distribution. After this lands, adding the `release` label to a PR runs the full pipeline: AI-generated release notes, version bump, GitHub Release, npm publish (@photon-ai/cli), and cross-platform binary uploads. package.json - name: dashboard-cli → @photon-ai/cli (matches the existing @photon-ai npm scope; binary stays bare as `photon`). - private: true → dropped (now publishable). - bin: { photon, pho } now point at dist/photon.js (built artifact) rather than src/index.ts. Bun build preserves the #!/usr/bin/env bun shebang so the bundled file is directly executable. - Added: license: MIT, repository, homepage, bugs, keywords, author, files: ["dist", "README.md", "LICENSE"], publishConfig.access: public, engines.bun: ">=1.3.0". - build script now `chmod +x` the output. - prepublishOnly runs typecheck + build so a stale dist/ never ships. Verified: `bun run build` produces dist/photon.js (381 KB), running it directly prints the version. LICENSE - MIT, 2026 Photon. README.md - Full end-user rewrite: quickstart, environments + per-env creds, project linking, CI/scripting via $PHOTON_TOKEN, full command tree, global flags table, dev workflow, release process. - Replaces the bun-init placeholder. .github/workflows/release.yaml (NEW) - Thin caller of photon-hq/buildspace's typescript-service-release.yaml. - Triggers on PR merge (closed + merged=true) — `release` label on the PR drives the actual publish via buildspace's PR-label gate. - workflow_dispatch input for manual force-release / dry-run. - Wires through OPENAI_API_KEY (release notes) and NPM_TOKEN secrets. .github/workflows/release-binaries.yaml (NEW) - Triggers on `release: created` (after release.yaml's GitHub Release is published). Decoupled from the npm publish flow — npm consumers get the Bun bundle, Release-page downloaders get a self-contained executable. - Matrix: macOS arm64 / macOS x64 / linux x64 / linux arm64. Uses `bun build --compile --target=bun-<os>-<arch>` for each. - Smoke-tests native targets (we can run macOS-arm64 on macos-latest and linux-x64 on ubuntu-latest; cross targets ship without run-test). - Computes SHA256 alongside each binary for verification. - workflow_dispatch input for re-attaching binaries to an existing tag. Required secrets (must be set on the repo before the first release): - OPENAI_API_KEY (release notes generation) - NPM_TOKEN (npm publish — automation token from npmjs.com) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Orca <help@stably.ai>
📝 WalkthroughWalkthroughAdds two release workflows (binary build + reusable release), rebrands/publishes the package as Changes
Sequence Diagram(s)sequenceDiagram
participant User as Release Event / Manual Trigger
participant GA as GitHub Actions Runner (matrix)
participant Bun as bun build
participant Smoke as Smoke Test (--version)
participant Shasum as shasum/sha256sum
participant GH as GitHub Releases (gh CLI / API)
User->>GA: release.created or workflow_dispatch(tag)
GA->>Bun: bun build --compile (per-target, outputs to dist/)
Bun-->>GA: compiled binary artifact
GA->>Smoke: run binary --version (selected targets)
Smoke-->>GA: smoke test result
GA->>Shasum: compute SHA256 .sha256
Shasum-->>GA: checksum file
GA->>GH: resolve release tag (event vs input) & gh release upload (binary + .sha256)
GH-->>User: release assets updated
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Warning Review ran into problems🔥 ProblemsThese MCP integrations need to be re-authenticated in the Integrations settings: Linear Review rate limit: 3/5 reviews remaining, refill in 18 minutes and 6 seconds. Comment |
After researching how spectrum-ts and uri consume buildspace: release.yaml - Switch trigger from `pull_request: closed` to `push: branches: [main]` (matches both reference repos). Buildspace's PR-label gate looks back at the merge commit's PR for the `release` label, so the trigger doesn't need its own filter. - Replace explicit `secrets:` block with `secrets: inherit`. Both reference workflows use this pattern — org-level OPENAI_API_KEY + NPM_TOKEN are configured at photon-hq and inherit automatically. No need for the calling workflow to forward them by name. - service-name now uses the full scoped npm name "@photon-ai/cli" (matches uri's "@photon-ai/uri"). License - Removed LICENSE file and dropped the `license` field from package.json + the README section (per user direction). Removed "LICENSE" from package.json `files`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Orca <help@stably.ai>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/release-binaries.yaml:
- Line 31: Replace the deprecated runner label by updating the YAML key "os:
macos-13" to a supported macOS runner label (e.g., "os: macos-15-intel") in the
workflow; locate the occurrence of the string "os: macos-13" in the workflow
step and change it to the chosen supported label so the GitHub Actions runner is
valid.
In `@README.md`:
- Around line 59-60: Update the README examples and flags section so non-global
flags appear after the subcommand: change examples like "photon --env staging
projects ls" and "photon --token XYZ ..." to the correct form "photon projects
ls --env staging" (or keep "PHOTON_ENV=staging photon projects ls" for env var
usage) and ensure only "--debug" is described as a global flag; rename or reword
the "Global flags" heading (and move flag descriptions) to indicate which flags
are per-command vs truly global (e.g., mark "--token", "--env", etc. as
per-command flags and keep "--debug" as the lone global flag).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 35d2f51c-69e8-42fd-b66a-0fc0ecd82cf4
📒 Files selected for processing (5)
.github/workflows/release-binaries.yaml.github/workflows/release.yamlLICENSEREADME.mdpackage.json
📜 Review details
🧰 Additional context used
📓 Path-based instructions (1)
package.json
📄 CodeRabbit inference engine (CLAUDE.md)
package.json: Usebun installinstead ofnpm install,yarn install, orpnpm installin package.json
Usebun run <script>instead ofnpm run <script>,yarn run <script>, orpnpm run <script>
Files:
package.json
🧠 Learnings (8)
📚 Learning: 2026-04-05T00:07:13.859Z
Learnt from: qwerzl
Repo: photon-hq/buildspace PR: 62
File: .github/workflows/update-docs.yaml:164-167
Timestamp: 2026-04-05T00:07:13.859Z
Learning: In photon-hq/buildspace, all reusable workflow blocks are intentionally referenced using `main` (e.g., `photon-hq/buildspace/.github/blocks/check-pr-labelmain`, `photon-hq/buildspace/.github/blocks/update-docsmain`). This is by design: the blocks and workflows ship together in the same repo and stay in sync. Do not flag these as version-pinning issues; pinning to a release tag would add unnecessary maintenance burden on every buildspace release.
Applied to files:
.github/workflows/release-binaries.yamlREADME.md.github/workflows/release.yaml
📚 Learning: 2026-04-04T19:01:14.591Z
Learnt from: CR
Repo: photon-hq/explore-send-imessage-app PR: 0
File: .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2026-04-04T19:01:14.591Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Use `bun <file>` instead of `node <file>` or `ts-node <file>`
Applied to files:
README.md
📚 Learning: 2026-04-04T19:01:14.591Z
Learnt from: CR
Repo: photon-hq/explore-send-imessage-app PR: 0
File: .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2026-04-04T19:01:14.591Z
Learning: Applies to package.json : Use `bun install` instead of `npm install`, `yarn install`, or `pnpm install`
Applied to files:
README.md
📚 Learning: 2026-04-21T18:03:17.985Z
Learnt from: lcandy2
Repo: photon-hq/dashboard PR: 40
File: apps/web/next.config.ts:6-8
Timestamp: 2026-04-21T18:03:17.985Z
Learning: In the photon-hq/dashboard repo (`apps/web/next.config.ts`), `typescript.ignoreBuildErrors: true` is intentional. Eden's `import type { App }` (cross-workspace type import from `photon-dashboard/api`) triggers unresolvable type resolution issues during `next build` in the Turborepo monorepo. Runtime behavior is correct and types resolve at dev time via the separate `typecheck` turbo task. Do not flag this as an issue.
Applied to files:
README.mdpackage.json
📚 Learning: 2026-03-10T22:49:19.048Z
Learnt from: CR
Repo: photon-hq/advanced-imessage-kit PR: 0
File: .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2026-03-10T22:49:19.048Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Use `bun <file>` instead of `node <file>` or `ts-node <file>` for running TypeScript and JavaScript files
Applied to files:
README.md
📚 Learning: 2026-04-28T03:08:36.661Z
Learnt from: CR
Repo: photon-hq/cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-28T03:08:36.661Z
Learning: Applies to package.json : Use `bun install` instead of `npm install`, `yarn install`, or `pnpm install` in package.json
Applied to files:
README.md
📚 Learning: 2026-04-16T22:15:43.439Z
Learnt from: CR
Repo: photon-hq/spectrum-cloud PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-16T22:15:43.439Z
Learning: Applies to **/*.ts?(x) : Use `Bun.$` for shell commands instead of `execa`
Applied to files:
README.md
📚 Learning: 2026-03-10T22:49:19.048Z
Learnt from: CR
Repo: photon-hq/advanced-imessage-kit PR: 0
File: .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2026-03-10T22:49:19.048Z
Learning: Applies to package.json : Use `bun install` instead of `npm install`, `yarn install`, or `pnpm install` in package.json scripts
Applied to files:
README.md
🪛 actionlint (1.7.12)
.github/workflows/release-binaries.yaml
[error] 31-31: label "macos-13" is unknown. available labels are "windows-latest", "windows-latest-8-cores", "windows-2025", "windows-2025-vs2026", "windows-2022", "windows-11-arm", "ubuntu-slim", "ubuntu-latest", "ubuntu-latest-4-cores", "ubuntu-latest-8-cores", "ubuntu-latest-16-cores", "ubuntu-24.04", "ubuntu-24.04-arm", "ubuntu-22.04", "ubuntu-22.04-arm", "macos-latest", "macos-latest-xlarge", "macos-latest-large", "macos-26-intel", "macos-26-xlarge", "macos-26-large", "macos-26", "macos-15-intel", "macos-15-xlarge", "macos-15-large", "macos-15", "macos-14-xlarge", "macos-14-large", "macos-14", "self-hosted", "x64", "arm", "arm64", "linux", "macos", "windows". if it is a custom label for self-hosted runner, set list of labels in actionlint.yaml config file
(runner-label)
🪛 LanguageTool
README.md
[uncategorized] ~189-~189: The official name of this software platform is spelled with a capital “H”.
Context: ... any PR; on merge, the Release workflow (a thin caller ...
(GITHUB)
[uncategorized] ~189-~189: The official name of this software platform is spelled with a capital “H”.
Context: ...pm. Standalone binaries are uploaded by release-binaries.yaml on eac...
(GITHUB)
🔍 Remote MCP Linear
Based on my search results, I have gathered sufficient context. Let me provide a summary of the relevant findings:
Summary of Additional Context for PR Review
Related Issue Structure & Publishing Pattern
The Linear workspace shows a consistent pattern for npm publishing workflows across multiple repositories in the photon-hq organization. Relevant precedent issues include:
- ENG-1262 (uri project): Package renamed to
@photon-ai/uri, configured withpublishConfig.access: "public", using the buildspace reusable workflow - ENG-1263 (uri project): CI/CD setup using
photon-hq/buildspacereusable workflows withbun run typecheck,bun run lint,bun test, andbun run buildsteps
Buildspace Integration Pattern
The reusable workflow delegation pattern (.github/workflows/release.yaml invoking photon-hq/buildspace/.github/workflows/typescript-service-release.yaml@main) is established and documented in multiple completed projects, indicating this is a standardized organizational practice. The workflow accepts configuration for:
- Service name (
photon-cli) - Build command (
bun run build) - Secret forwarding (OPENAI_API_KEY, NPM_TOKEN)
Binary Release Workflow Precedent
- ENG-837 (BuildSpace project): "Build block for publishing binary to public homebrew" indicates there is organizational experience with binary distribution, though homebrew publishing appears to be a separate future task from the current GitHub Release asset attachment approach
Critical Assumptions for Review
The PR assumes the following are already in place or will be configured post-merge:
- Repository Secrets: OPENAI_API_KEY and NPM_TOKEN must be set before triggering the first release
- Buildspace Workflow Access: The
photon-hq/buildspacerepository must be accessible and thetypescript-service-releaseworkflow must exist - Bun Compilation Targets: The bun version (>=1.3.0 as specified in
engines) must support--target=bun-darwin-arm64,bun-darwin-x64,bun-linux-x64, andbun-linux-arm64for cross-platform binary builds
Key Publishing Configuration Details
From the related ENG-1262 issue pattern:
- Scoped packages under
@photon-ainpm org default to private, requiring explicitpublishConfig.access: "public" - Binary names should align across
binentries anddist/output names for consistency prepublishOnlyscripts ensure built artifacts are typecheck + build verified before publishing
🔇 Additional comments (3)
LICENSE (1)
1-22: MIT license addition looks good.The license text is complete and correctly included for public distribution.
.github/workflows/release.yaml (1)
21-33: Release workflow wiring is solid.Merge gating, manual overrides, and secret forwarding are set up cleanly.
Based on learnings, referencing
photon-hq/buildspacereusable workflows on@mainis intentional and should not be flagged as a pinning issue.package.json (1)
41-47: Publish/build scripts are aligned for Bun-first release flow.
prepublishOnlyguard plus Bun-based scripts look correct for npm publish readiness.As per coding guidelines,
package.jsonshould use Bun commands (bun install/bun run <script>), and this segment complies.
There was a problem hiding this comment.
Pull request overview
Prepares the Photon CLI for public distribution via npm (@photon-ai/cli) and GitHub Releases, including automated release workflows and end-user documentation updates.
Changes:
- Updates
package.jsonfor npm publishing (scoped name, publish metadata, bin points to built artifact, prepublish build/typecheck). - Replaces the placeholder README with end-user docs (install, concepts, command reference, dev + release process).
- Adds GitHub Actions workflows to automate releases and attach compiled standalone binaries to GitHub Releases.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| package.json | Makes the package publishable and points bin to dist/photon.js; adds publish metadata and prepublish script. |
| README.md | New user-facing documentation covering install, environments, linking, CI usage, commands, and release process. |
| LICENSE | Adds MIT license text for distribution. |
| .github/workflows/release.yaml | Adds a reusable-workflow-based release pipeline on merge / manual dispatch. |
| .github/workflows/release-binaries.yaml | Builds and uploads platform binaries + SHA256 to GitHub Releases. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
README.md (1)
59-60:⚠️ Potential issue | 🟠 MajorNon-global flags are documented in an invalid CLI position.
--envand--tokenare shown before subcommands (Line 59, Line 84), and theGlobal flagssection title (Line 141) overstates scope for per-command flags.✏️ Proposed README fix
-photon --env staging projects ls # one-off override +photon projects ls --env staging # one-off override PHOTON_ENV=staging photon projects ls # same, via env var @@ -photon --token "$PHOTON_TOKEN" projects ls +photon projects ls --token "$PHOTON_TOKEN" # or PHOTON_TOKEN=… photon projects ls @@ -## Global flags +## Common command flagsAlso applies to: 84-87, 141-153
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 59 - 60, The README incorrectly documents non-global flags (--env, --token) as if they are global and shows them before subcommands; update examples and sections so that --env and --token are documented in the per-command examples where they apply (e.g., under the "projects" command examples and any other affected command blocks around the examples at lines showing 'photon --env staging projects ls' and 'PHOTON_ENV=staging photon projects ls'), and change the "Global flags" section title/content (referenced as 'Global flags') to only list truly global options; move any per-command flags out of that global section and into the specific command documentation or examples.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Line 63: Wording implies a fixed config directory; update the three README
occurrences that show "~/.config/photon/..." (the lines containing
"~/.config/photon/credentials/<env>.json", "~/.config/photon/..." and similar)
to present these as default locations rather than hardcoded paths and mention
that they can be overridden via PHOTON_CONFIG_DIR (refer to the existing
PHOTON_CONFIG_DIR note at Line 154), e.g. replace absolute-path phrasing with
"by default" or "defaults to" and add a short parenthetical pointing to
PHOTON_CONFIG_DIR as the override.
---
Duplicate comments:
In `@README.md`:
- Around line 59-60: The README incorrectly documents non-global flags (--env,
--token) as if they are global and shows them before subcommands; update
examples and sections so that --env and --token are documented in the
per-command examples where they apply (e.g., under the "projects" command
examples and any other affected command blocks around the examples at lines
showing 'photon --env staging projects ls' and 'PHOTON_ENV=staging photon
projects ls'), and change the "Global flags" section title/content (referenced
as 'Global flags') to only list truly global options; move any per-command flags
out of that global section and into the specific command documentation or
examples.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: dda80707-0ddb-4d86-9414-47b194d5eb38
📒 Files selected for processing (3)
.github/workflows/release.yamlREADME.mdpackage.json
✅ Files skipped from review due to trivial changes (1)
- .github/workflows/release.yaml
🚧 Files skipped from review as they are similar to previous changes (1)
- package.json
📜 Review details
🧰 Additional context used
🧠 Learnings (7)
📓 Common learnings
Learnt from: qwerzl
Repo: photon-hq/buildspace PR: 62
File: .github/workflows/update-docs.yaml:164-167
Timestamp: 2026-04-05T00:07:13.859Z
Learning: In photon-hq/buildspace, all reusable workflow blocks are intentionally referenced using `main` (e.g., `photon-hq/buildspace/.github/blocks/check-pr-labelmain`, `photon-hq/buildspace/.github/blocks/update-docsmain`). This is by design: the blocks and workflows ship together in the same repo and stay in sync. Do not flag these as version-pinning issues; pinning to a release tag would add unnecessary maintenance burden on every buildspace release.
📚 Learning: 2026-04-05T00:07:13.859Z
Learnt from: qwerzl
Repo: photon-hq/buildspace PR: 62
File: .github/workflows/update-docs.yaml:164-167
Timestamp: 2026-04-05T00:07:13.859Z
Learning: In photon-hq/buildspace, all reusable workflow blocks are intentionally referenced using `main` (e.g., `photon-hq/buildspace/.github/blocks/check-pr-labelmain`, `photon-hq/buildspace/.github/blocks/update-docsmain`). This is by design: the blocks and workflows ship together in the same repo and stay in sync. Do not flag these as version-pinning issues; pinning to a release tag would add unnecessary maintenance burden on every buildspace release.
Applied to files:
README.md
📚 Learning: 2026-04-04T19:01:14.591Z
Learnt from: CR
Repo: photon-hq/explore-send-imessage-app PR: 0
File: .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2026-04-04T19:01:14.591Z
Learning: Applies to package.json : Use `bun install` instead of `npm install`, `yarn install`, or `pnpm install`
Applied to files:
README.md
📚 Learning: 2026-03-10T22:49:19.048Z
Learnt from: CR
Repo: photon-hq/advanced-imessage-kit PR: 0
File: .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2026-03-10T22:49:19.048Z
Learning: Applies to package.json : Use `bun install` instead of `npm install`, `yarn install`, or `pnpm install` in package.json scripts
Applied to files:
README.md
📚 Learning: 2026-04-28T03:08:36.661Z
Learnt from: CR
Repo: photon-hq/cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-28T03:08:36.661Z
Learning: Applies to package.json : Use `bun install` instead of `npm install`, `yarn install`, or `pnpm install` in package.json
Applied to files:
README.md
📚 Learning: 2026-04-21T18:03:17.985Z
Learnt from: lcandy2
Repo: photon-hq/dashboard PR: 40
File: apps/web/next.config.ts:6-8
Timestamp: 2026-04-21T18:03:17.985Z
Learning: In the photon-hq/dashboard repo (`apps/web/next.config.ts`), `typescript.ignoreBuildErrors: true` is intentional. Eden's `import type { App }` (cross-workspace type import from `photon-dashboard/api`) triggers unresolvable type resolution issues during `next build` in the Turborepo monorepo. Runtime behavior is correct and types resolve at dev time via the separate `typecheck` turbo task. Do not flag this as an issue.
Applied to files:
README.md
📚 Learning: 2026-04-04T19:01:14.591Z
Learnt from: CR
Repo: photon-hq/explore-send-imessage-app PR: 0
File: .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2026-04-04T19:01:14.591Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Use `bun <file>` instead of `node <file>` or `ts-node <file>`
Applied to files:
README.md
🪛 LanguageTool
README.md
[uncategorized] ~189-~189: The official name of this software platform is spelled with a capital “H”.
Context: ...n merge to main, the Release workflow (a thin caller ...
(GITHUB)
[uncategorized] ~189-~189: The official name of this software platform is spelled with a capital “H”.
Context: ...pm. Standalone binaries are uploaded by release-binaries.yaml on eac...
(GITHUB)
🔍 Remote MCP Linear
Additional context relevant to reviewing this PR
-
ENG-1262: precedent for renaming packages to the
@photon-aiscope, adding publishConfig.access: "public", updating README/install/imports, and verifying npm publish dry-run + CI release workflow use the scoped name. Confirms the package rename + publishConfig change in this PR matches an established repo pattern. -
ENG-837: prior work that implemented a "build block for publishing binary" (completed). Attached link to buildspace PR for homebrew support — indicates org experience with binary build + distribution, and that GitHub Release attachment (current PR) is consistent with earlier binary-release groundwork.
Rename: - Package name @photon-ai/cli -> @photon-ai/photon so the post-scope segment matches the `photon` binary. Lets `npx @photon-ai/photon` and `bunx @photon-ai/photon` resolve directly without --package. Unscoped `photon` and `photon-cli` are both taken on npm. - README quickstart updated; new bunx/npx one-off section added. Review fixes (Copilot + CodeRabbit on PR #11): - release-binaries.yaml: macos-13 -> macos-15-intel (deprecated runner label) and pin bun-version to 1.3.13 for reproducibility. - release.yaml: use bracket notation inputs['dry-run'] to avoid hyphen parsing ambiguity. - package.json: move typescript from peerDependencies to devDependencies now that the package is publishable. - README: use \$PHOTON_CONFIG_DIR/... in path examples instead of hardcoded ~/.config/photon/...; fix flag positioning (only --debug is program-level, all others must follow the subcommand). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Orca <help@stably.ai>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
README.md (1)
41-47: Prefer Bun-only one-off examples in docs.Given the Bun-first posture, keep this section on
bunxand drop thenpxline to avoid mixed guidance.✏️ Suggested patch
bunx `@photon-ai/photon` login bunx `@photon-ai/photon` projects ls -npx `@photon-ai/photon` whoami # also worksBased on learnings: Use
bunx <package> <command>instead ofnpx <package> <command>.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 41 - 47, The README examples show both bunx and npx; remove the npx example to keep Bun-first guidance: edit the code block with the one-off command examples (the lines containing "bunx `@photon-ai/photon` login", "bunx `@photon-ai/photon` projects ls", and "npx `@photon-ai/photon` whoami") and delete the "npx `@photon-ai/photon` whoami" line so only bunx examples remain, preserving formatting and surrounding fenced code block.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@package.json`:
- Around line 14-23: The package.json is missing explicit SPDX license metadata;
add a top-level "license": "MIT" field to package.json (alongside existing keys
like "author", "homepage", "repository", "bugs", and "type") so npm and tooling
can detect the repository's license (the project already contains a LICENSE file
to justify using "MIT").
---
Nitpick comments:
In `@README.md`:
- Around line 41-47: The README examples show both bunx and npx; remove the npx
example to keep Bun-first guidance: edit the code block with the one-off command
examples (the lines containing "bunx `@photon-ai/photon` login", "bunx
`@photon-ai/photon` projects ls", and "npx `@photon-ai/photon` whoami") and delete
the "npx `@photon-ai/photon` whoami" line so only bunx examples remain,
preserving formatting and surrounding fenced code block.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 22e1370a-5d00-4ad3-87d7-58efca26fd4d
📒 Files selected for processing (4)
.github/workflows/release-binaries.yaml.github/workflows/release.yamlREADME.mdpackage.json
✅ Files skipped from review due to trivial changes (1)
- .github/workflows/release.yaml
🚧 Files skipped from review as they are similar to previous changes (1)
- .github/workflows/release-binaries.yaml
📜 Review details
🧰 Additional context used
📓 Path-based instructions (1)
package.json
📄 CodeRabbit inference engine (CLAUDE.md)
package.json: Usebun installinstead ofnpm install,yarn install, orpnpm installin package.json
Usebun run <script>instead ofnpm run <script>,yarn run <script>, orpnpm run <script>
Files:
package.json
🧠 Learnings (12)
📓 Common learnings
Learnt from: qwerzl
Repo: photon-hq/buildspace PR: 62
File: .github/workflows/update-docs.yaml:164-167
Timestamp: 2026-04-05T00:07:13.859Z
Learning: In photon-hq/buildspace, all reusable workflow blocks are intentionally referenced using `main` (e.g., `photon-hq/buildspace/.github/blocks/check-pr-labelmain`, `photon-hq/buildspace/.github/blocks/update-docsmain`). This is by design: the blocks and workflows ship together in the same repo and stay in sync. Do not flag these as version-pinning issues; pinning to a release tag would add unnecessary maintenance burden on every buildspace release.
📚 Learning: 2026-04-21T18:03:17.985Z
Learnt from: lcandy2
Repo: photon-hq/dashboard PR: 40
File: apps/web/next.config.ts:6-8
Timestamp: 2026-04-21T18:03:17.985Z
Learning: In the photon-hq/dashboard repo (`apps/web/next.config.ts`), `typescript.ignoreBuildErrors: true` is intentional. Eden's `import type { App }` (cross-workspace type import from `photon-dashboard/api`) triggers unresolvable type resolution issues during `next build` in the Turborepo monorepo. Runtime behavior is correct and types resolve at dev time via the separate `typecheck` turbo task. Do not flag this as an issue.
Applied to files:
package.jsonREADME.md
📚 Learning: 2026-04-01T08:18:18.974Z
Learnt from: CR
Repo: photon-hq/advanced-imessage-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-01T08:18:18.974Z
Learning: Applies to **/*.{tsx,jsx} : Specify all dependencies in hook dependency arrays correctly
Applied to files:
package.json
📚 Learning: 2026-04-01T08:18:18.974Z
Learnt from: CR
Repo: photon-hq/advanced-imessage-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-01T08:18:18.974Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Leverage TypeScript's type narrowing instead of type assertions
Applied to files:
package.json
📚 Learning: 2026-04-17T02:57:19.075Z
Learnt from: CR
Repo: photon-hq/billing PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-17T02:57:19.075Z
Learning: Applies to **/*.{tsx,jsx} : Specify all dependencies in hook dependency arrays correctly in React
Applied to files:
package.json
📚 Learning: 2026-04-15T02:30:10.124Z
Learnt from: CR
Repo: photon-hq/whatsapp-business-ts PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-15T02:30:10.124Z
Learning: Applies to **/*.{jsx,tsx} : Specify all dependencies in hook dependency arrays correctly
Applied to files:
package.json
📚 Learning: 2026-04-05T00:07:13.859Z
Learnt from: qwerzl
Repo: photon-hq/buildspace PR: 62
File: .github/workflows/update-docs.yaml:164-167
Timestamp: 2026-04-05T00:07:13.859Z
Learning: In photon-hq/buildspace, all reusable workflow blocks are intentionally referenced using `main` (e.g., `photon-hq/buildspace/.github/blocks/check-pr-labelmain`, `photon-hq/buildspace/.github/blocks/update-docsmain`). This is by design: the blocks and workflows ship together in the same repo and stay in sync. Do not flag these as version-pinning issues; pinning to a release tag would add unnecessary maintenance burden on every buildspace release.
Applied to files:
README.md
📚 Learning: 2026-04-04T19:01:14.591Z
Learnt from: CR
Repo: photon-hq/explore-send-imessage-app PR: 0
File: .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2026-04-04T19:01:14.591Z
Learning: Applies to package.json : Use `bun install` instead of `npm install`, `yarn install`, or `pnpm install`
Applied to files:
README.md
📚 Learning: 2026-03-10T22:49:19.048Z
Learnt from: CR
Repo: photon-hq/advanced-imessage-kit PR: 0
File: .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2026-03-10T22:49:19.048Z
Learning: Applies to package.json : Use `bun install` instead of `npm install`, `yarn install`, or `pnpm install` in package.json scripts
Applied to files:
README.md
📚 Learning: 2026-04-28T03:08:36.661Z
Learnt from: CR
Repo: photon-hq/cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-28T03:08:36.661Z
Learning: Applies to package.json : Use `bun install` instead of `npm install`, `yarn install`, or `pnpm install` in package.json
Applied to files:
README.md
📚 Learning: 2026-04-04T19:01:14.591Z
Learnt from: CR
Repo: photon-hq/explore-send-imessage-app PR: 0
File: .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2026-04-04T19:01:14.591Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Use `bun <file>` instead of `node <file>` or `ts-node <file>`
Applied to files:
README.md
📚 Learning: 2026-04-04T19:01:14.591Z
Learnt from: CR
Repo: photon-hq/explore-send-imessage-app PR: 0
File: .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2026-04-04T19:01:14.591Z
Learning: Use `bunx <package> <command>` instead of `npx <package> <command>`
Applied to files:
README.md
🪛 LanguageTool
README.md
[uncategorized] ~214-~214: The official name of this software platform is spelled with a capital “H”.
Context: ...n merge to main, the Release workflow (a thin caller ...
(GITHUB)
[uncategorized] ~214-~214: The official name of this software platform is spelled with a capital “H”.
Context: ...pm. Standalone binaries are uploaded by release-binaries.yaml on eac...
(GITHUB)
🔇 Additional comments (2)
package.json (1)
25-46: Publish/build wiring is clean and release-ready.
binpoints to built output,buildmarks the artifact executable, andprepublishOnlygates publish on typecheck + build. Nice setup for npm + release automation.README.md (1)
151-168: Flag semantics are clearly documented now.Great clarification that only
--debugis program-level and others are per-command, with concrete valid/invalid examples.
This was referenced Apr 29, 2026
citron (lcandy2)
added a commit
that referenced
this pull request
May 5, 2026
Aligns with industry convention (@vercel/cli, @supabase/cli, @dokploy/cli, etc.) and matches the binary's role rather than duplicating the name. The previous reasoning behind @photon-ai/photon (PR #11) was that the post-scope segment must match the bin name for unpinned `npx <pkg>` to auto-resolve. That turns out to have been an overly strict reading of PR #12's findings — the actual rule npm 11 uses is "single bin auto-resolves regardless of name match." Confirmed empirically against @dokploy/cli, which has bin `dokploy` (not `cli`) and works unpinned. Bin shape switches from string-form to single-key object: "bin": "./dist/photon.js" → "bin": { "photon": "./dist/photon.js" } This keeps the binary registered as `photon` (string form would have made it `cli`, breaking every existing user invocation). Verified locally against @photon-ai/cli@0.1.3 tarball: - bun add -g: installs `photon`, lazy `pho` symlink fires on first run - npm install (local): same - `npx --yes <tarball>` resolves to 0.1.3 via single-bin auto-resolve Existing `@photon-ai/photon` users will keep getting 0.1.3 (final version on the old name). Migration path: re-install with `bun add -g @photon-ai/cli`.
This was referenced May 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Phase 10 — distribution. After this lands, adding the
releaselabel to a PR runs the full pipeline: AI-generated release notes, version bump, GitHub Release, npm publish to@photon-ai/photon, and cross-platform binary uploads.What's new
package.jsonname:dashboard-cli→@photon-ai/photon. Post-scope segment matches thephotonbinary, sonpx @photon-ai/photon …andbunx @photon-ai/photon …resolve directly without--package. Unscopedphotonandphoton-cliare both taken on npm.private: true→ publishable.bin: { photon, pho }points atdist/photon.js(built artifact). The Bun bundle preserves#!/usr/bin/env bunso it's directly executable.repository,homepage,bugs,keywords,author,files: ["dist", "README.md"],publishConfig.access: public,engines.bun: ">=1.3.0".buildnowchmod +x's the output.prepublishOnlyrunstypecheck+buildso a staledist/never ships.typescriptlives indevDependencies(not peerDeps) — avoids peer-dep noise for consumers.README.mdFull end-user rewrite: quickstart,
npx/bunxone-off usage, environments + per-env creds ($PHOTON_CONFIG_DIR-aware), project linking, CI/scripting viaPHOTON_TOKEN, full command tree, flag-scope table (program-level vs per-cmd), dev workflow, release process..github/workflows/release.yaml(new)Thin caller of
photon-hq/buildspace'stypescript-service-release.yaml@main— matches the photon-hq convention used byspectrum-tsanduri. Triggers on push tomain; buildspace'sreleasePR-label gate decides whether to actually publish.workflow_dispatchfor manual force-release / dry-run. Usessecrets: inheritso org-levelOPENAI_API_KEY+NPM_TOKENflow through automatically..github/workflows/release-binaries.yaml(new)Triggers on
release: created(afterrelease.yaml's GitHub Release is published). Decoupled from the npm publish — npm consumers get the Bun bundle, Release-page downloaders get a self-contained executable.Matrix:
macos-latest(arm64),macos-15-intel(x64),ubuntu-latest(x64 + arm64).bun-versionpinned to1.3.13(trackspackage.json#engines.bunlower bound). Usesbun build --compile --target=bun-<os>-<arch>per platform. Smoke-tests native targets. Computes SHA256 alongside each binary.workflow_dispatchfor re-attaching to an existing tag.Required secrets
Both are org-level at
photon-hqand pass through viasecrets: inherit— nothing to configure on this repo.OPENAI_API_KEY— buildspace'sgenerate-release-infoblock uses it for AI-generated release notes.NPM_TOKEN— npm automation token (publishes to@photon-ai).Test plan
bun run buildproducesdist/photon.js(~381 KB) and it's executable../dist/photon.js --versionprints0.0.1../dist/photon.js --helpshows all 13 top-level commands.bunx tsc --noEmitclean.releaselabel to a test PR to dry-run the publish.bun add -g @photon-ai/photonworks on a fresh machine.npx @photon-ai/photon --versionresolves the binary directly.How to actually publish (after this PR merges)
releaselabel. Merge.release.yamlpublishes to npm + creates the Release;release-binaries.yamlattachesphoton-darwin-arm64/photon-darwin-x64/photon-linux-x64/photon-linux-arm64(+.sha256s).Phase status
After this merges, every command in the build plan is shipped; the CLI is publish-ready.
🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
Chores