From 18264605c5d2b2f229a8cc79adbeaabddbe06445 Mon Sep 17 00:00:00 2001 From: citron Date: Thu, 30 Apr 2026 02:36:31 +0800 Subject: [PATCH 1/3] feat: prepare for npm publish + GitHub Release binaries (Phase 10) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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--` 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) Co-authored-by: Orca --- .github/workflows/release-binaries.yaml | 85 ++++++++++ .github/workflows/release.yaml | 33 ++++ LICENSE | 21 +++ README.md | 196 +++++++++++++++++++++++- package.json | 42 ++++- 5 files changed, 363 insertions(+), 14 deletions(-) create mode 100644 .github/workflows/release-binaries.yaml create mode 100644 .github/workflows/release.yaml create mode 100644 LICENSE diff --git a/.github/workflows/release-binaries.yaml b/.github/workflows/release-binaries.yaml new file mode 100644 index 0000000..9126f0d --- /dev/null +++ b/.github/workflows/release-binaries.yaml @@ -0,0 +1,85 @@ +name: Release Binaries + +# Build standalone `photon` binaries (no Bun runtime required) and +# attach them to the GitHub Release that the `release.yaml` workflow +# created. Runs on `release: created` so it stays decoupled from the +# npm publish flow — npm consumers get the Bun bundle, Release-page +# downloaders get a self-contained executable. + +on: + release: + types: [created] + workflow_dispatch: + inputs: + tag: + type: string + description: "Existing release tag to attach binaries to" + required: true + +permissions: + contents: write + +jobs: + build: + strategy: + fail-fast: false + matrix: + include: + - os: macos-latest + target: bun-darwin-arm64 + asset: photon-darwin-arm64 + - os: macos-13 + target: bun-darwin-x64 + asset: photon-darwin-x64 + - os: ubuntu-latest + target: bun-linux-x64 + asset: photon-linux-x64 + - os: ubuntu-latest + target: bun-linux-arm64 + asset: photon-linux-arm64 + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v5 + - uses: oven-sh/setup-bun@v2 + with: + bun-version: latest + + - name: Install + run: bun install --frozen-lockfile + + - name: Compile binary + run: | + bun build ./src/index.ts \ + --compile \ + --target=${{ matrix.target }} \ + --outfile dist/${{ matrix.asset }} + + - name: Smoke test (native targets only) + if: matrix.target == 'bun-darwin-arm64' || matrix.target == 'bun-linux-x64' + run: ./dist/${{ matrix.asset }} --version + + - name: Compute SHA256 + run: | + if command -v shasum >/dev/null 2>&1; then + shasum -a 256 dist/${{ matrix.asset }} > dist/${{ matrix.asset }}.sha256 + else + sha256sum dist/${{ matrix.asset }} > dist/${{ matrix.asset }}.sha256 + fi + + - name: Resolve release tag + id: tag + run: | + if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then + echo "tag=${{ github.event.inputs.tag }}" >> "$GITHUB_OUTPUT" + else + echo "tag=${{ github.event.release.tag_name }}" >> "$GITHUB_OUTPUT" + fi + + - name: Upload to release + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + gh release upload "${{ steps.tag.outputs.tag }}" \ + "dist/${{ matrix.asset }}" \ + "dist/${{ matrix.asset }}.sha256" \ + --clobber diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml new file mode 100644 index 0000000..bda6199 --- /dev/null +++ b/.github/workflows/release.yaml @@ -0,0 +1,33 @@ +name: Release + +on: + pull_request: + types: [closed] + branches: [main] + workflow_dispatch: + inputs: + release: + type: boolean + description: "Force release (skip the PR-label check)" + default: false + dry-run: + type: boolean + description: "Run without publishing" + default: false + +jobs: + release: + # Only fire when the PR was actually merged (not just closed). + if: ${{ github.event_name == 'workflow_dispatch' || github.event.pull_request.merged == true }} + uses: photon-hq/buildspace/.github/workflows/typescript-service-release.yaml@main + permissions: + contents: write + pull-requests: read + with: + service-name: photon-cli + build-command: "bun run build" + release: ${{ github.event_name == 'workflow_dispatch' && inputs.release || false }} + dry-run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry-run || false }} + secrets: + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..af5ddd3 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Photon + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index c6ffeaf..f09b625 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,195 @@ -# dashboard-cli +# Photon CLI -To install dependencies: +Typed terminal UI for the [Photon Dashboard](https://photon.codes). Replaces the web UI for everyday work — manage projects, Spectrum users / lines / platforms, billing, and your developer profile from a terminal. -```bash -bun install +```sh +bun add -g @photon-ai/cli +photon login +photon projects ls +``` + +> **Bun required.** This CLI ships as a Bun bundle. Install Bun: `curl -fsSL https://bun.sh/install | bash`. Standalone binaries (no Bun needed) are attached to each [GitHub Release](https://github.com/photon-hq/cli/releases) for macOS (arm64 / x64) and Linux (x64 / arm64). + +--- + +## Quickstart + +```sh +# 1. Install +bun add -g @photon-ai/cli + +# 2. Log in (opens a browser to approve the device) +photon login + +# 3. Link a project so future commands default to it +photon projects ls +photon link + +# 4. Off you go +photon projects show +photon spectrum users ls +photon billing show +``` + +`pho` is an alias for `photon` for high-frequency commands: + +```sh +pho ls # photon projects ls +pho whoami +``` + +--- + +## Concepts + +### Environments + +Every command operates against an **environment** (production by default). Built-ins: + +| Name | URL | +|---|---| +| `production` | `https://app.photon.codes` | +| `staging` | `https://staging-app.photon.codes` | +| `dev` | `http://localhost:3001` | + +```sh +photon env list # show all +photon env use staging # persist as default +photon env add my-test https://my.test.tld # add a custom env +photon --env staging projects ls # one-off override +PHOTON_ENV=staging photon projects ls # same, via env var +``` + +Credentials are stored **per environment** (`~/.config/photon/credentials/.json`, mode 600), so you can be logged into prod and dev simultaneously. + +### Project linking + +Most commands operate on a single project. Rather than passing `--project ` every time, link a project for the current env: + +```sh +photon link abc123 # writes ~/.config/photon/links/.json +photon spectrum users ls # implicit project from link +photon projects show # same +photon link:status # see what's linked across envs +photon unlink # clear the link +``` + +Resolution order: `--project ` flag → `$PHOTON_PROJECT_ID` → linked project → friendly error. + +### CI / scripting + +Authenticate once locally, copy the token from `~/.config/photon/credentials/.json`, and use it in CI: + +```sh +photon --token "$PHOTON_TOKEN" projects ls +# or +PHOTON_TOKEN=… photon projects ls +``` + +Pair with `--json` for machine-readable output: + +```sh +photon projects ls --json | jq '.[] | .id' +photon billing show --json +``` + +`PHOTON_TOKEN` reuses the same access token issued by the device flow (default 7d expiry — re-run `photon login` when it expires). A long-lived API-key path is on the roadmap. + +--- + +## Command reference + +```text +photon +├── ping hit /api/health +├── env list/use/add/remove/current env management +├── login [--env] [--no-browser] device-auth login +├── logout [--env] clear creds +├── whoami [--env] who am I on this env +├── auth status login state across envs +├── config show dump active config +├── link link project for env +├── unlink clear link +├── link:status linked projects (all envs) +├── projects +│ ├── ls list projects +│ ├── show [id] project detail +│ ├── create [-n --location --spectrum ...] [--link] new project +│ ├── update [id] [...] rename / toggle flags +│ ├── delete [id] [-y] permanent delete +│ ├── regenerate-secret [id] [-y] rotate Spectrum secret +│ ├── open [id] open dashboard in browser +│ └── check-phone availability check +├── profile show / init / update developer / org profile +├── spectrum +│ ├── users ls / add / remove +│ ├── lines ls / add / remove +│ ├── platforms ls / enable / disable +│ ├── profile show / update +│ └── avatar upload +└── billing + ├── plans available plans + ├── show current subscription + ├── checkout --plan Stripe Checkout (browser) + └── manage Stripe Customer Portal ``` -To run: +Run `photon --help` for the full flag list of any command. + +--- + +## Global flags + +| Flag | Env var | Effect | +|---|---|---| +| `-e, --env ` | `PHOTON_ENV` | override active env | +| `-p, --project ` | `PHOTON_PROJECT_ID` | override linked project (per-command) | +| `-t, --token ` | `PHOTON_TOKEN` | bypass stored creds (CI) | +| `--json` | — | structured output (per-command, opt-in) | +| `--yes`, `-y` | — | skip destructive-action confirmation | +| `--no-browser` | — | don't auto-open browser (login, billing, projects open) | +| `--no-color` | `NO_COLOR=1`, `PHOTON_NO_COLOR=1` | disable colors (NO_COLOR standard) | +| `--debug` | `PHOTON_DEBUG=1` | verbose HTTP logs to stderr | + +Other env vars: `PHOTON_CONFIG_DIR` (defaults to `~/.config/photon/`), `PHOTON_TYPES_SRC` (maintainer-only, for `bun run sync:api`), `PHOTON_NO_UPDATE_NOTIFIER=1` (mute update prompt). + +--- -```bash -bun run index.ts +## Development + +```sh +git clone https://github.com/photon-hq/cli +cd cli +bun install + +# Run from source +bun run src/index.ts --help + +# Watch +bun run dev + +# Typecheck +bun run typecheck + +# Build (produces dist/photon.js) +bun run build + +# Sync API types from a sibling `dashboard` checkout (maintainer) +bun run sync:api ``` -This project was created using `bun init` in bun v1.3.13. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime. +The CLI's API contract comes from the `@photon-ai/api-public` type bundle, vendored at `types/api.d.ts`. To refresh after the dashboard's API surface changes, run `bun run sync:api` (looks for the sibling checkout by default; set `PHOTON_TYPES_SRC` to override). + +See [`docs/cli-design.md`](docs/cli-design.md) and [`docs/cli-build-plan.md`](docs/cli-build-plan.md) for the full architecture notes. + +--- + +## Releases + +Tagged via PR labels. Add the `release` label to any PR; on merge, the [Release workflow](.github/workflows/release.yaml) (a thin caller of [`photon-hq/buildspace`'s `typescript-service-release`](https://github.com/photon-hq/buildspace)) generates a version + notes, bumps `package.json`, creates a GitHub Release, and publishes to npm. Standalone binaries are uploaded by [`release-binaries.yaml`](.github/workflows/release-binaries.yaml) on each release. + +--- + +## License + +[MIT](./LICENSE). diff --git a/package.json b/package.json index d77795b..dfbf1c7 100644 --- a/package.json +++ b/package.json @@ -1,20 +1,50 @@ { - "name": "dashboard-cli", + "name": "@photon-ai/cli", "version": "0.0.1", "description": "Photon CLI — typed terminal UI for the Photon Dashboard. Binary: `photon` (alias `pho`).", + "keywords": [ + "photon", + "cli", + "dashboard", + "spectrum", + "messaging", + "imessage", + "developer-tools" + ], + "license": "MIT", + "author": "Photon", + "homepage": "https://github.com/photon-hq/cli#readme", + "repository": { + "type": "git", + "url": "git+https://github.com/photon-hq/cli.git" + }, + "bugs": { + "url": "https://github.com/photon-hq/cli/issues" + }, "type": "module", - "private": true, "bin": { - "photon": "./src/index.ts", - "pho": "./src/index.ts" + "photon": "./dist/photon.js", + "pho": "./dist/photon.js" + }, + "files": [ + "dist", + "README.md", + "LICENSE" + ], + "publishConfig": { + "access": "public" + }, + "engines": { + "bun": ">=1.3.0" }, "scripts": { "start": "bun run src/index.ts", "dev": "bun run --watch src/index.ts", - "build": "bun build ./src/index.ts --outfile dist/photon.js --target bun --minify", + "build": "bun build ./src/index.ts --outfile dist/photon.js --target bun --minify && chmod +x dist/photon.js", "compile": "bun build ./src/index.ts --compile --outfile dist/photon", "typecheck": "tsc --noEmit", - "sync:api": "bun run scripts/sync-api-types.ts" + "sync:api": "bun run scripts/sync-api-types.ts", + "prepublishOnly": "bun run typecheck && bun run build" }, "devDependencies": { "@types/bun": "latest", From 9c451da9e836dcb17deb27eeca4fa026debe5173 Mon Sep 17 00:00:00 2001 From: citron Date: Thu, 30 Apr 2026 02:40:48 +0800 Subject: [PATCH 2/3] fix: align release workflow with photon-hq pattern, drop license MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Co-authored-by: Orca --- .github/workflows/release.yaml | 16 ++++++++-------- LICENSE | 21 --------------------- README.md | 8 +------- package.json | 4 +--- 4 files changed, 10 insertions(+), 39 deletions(-) delete mode 100644 LICENSE diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index bda6199..cd0a8e1 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -1,8 +1,12 @@ name: Release +# Mirrors the photon-hq pattern (see spectrum-ts, uri): push to main, +# let buildspace's PR-label gate look back at the merge commit and +# decide whether to actually release. `secrets: inherit` passes +# org-level OPENAI_API_KEY + NPM_TOKEN through automatically. + on: - pull_request: - types: [closed] + push: branches: [main] workflow_dispatch: inputs: @@ -17,17 +21,13 @@ on: jobs: release: - # Only fire when the PR was actually merged (not just closed). - if: ${{ github.event_name == 'workflow_dispatch' || github.event.pull_request.merged == true }} uses: photon-hq/buildspace/.github/workflows/typescript-service-release.yaml@main permissions: contents: write pull-requests: read with: - service-name: photon-cli + service-name: "@photon-ai/cli" build-command: "bun run build" release: ${{ github.event_name == 'workflow_dispatch' && inputs.release || false }} dry-run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry-run || false }} - secrets: - OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} - NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + secrets: inherit diff --git a/LICENSE b/LICENSE deleted file mode 100644 index af5ddd3..0000000 --- a/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2026 Photon - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/README.md b/README.md index f09b625..b495573 100644 --- a/README.md +++ b/README.md @@ -186,10 +186,4 @@ See [`docs/cli-design.md`](docs/cli-design.md) and [`docs/cli-build-plan.md`](do ## Releases -Tagged via PR labels. Add the `release` label to any PR; on merge, the [Release workflow](.github/workflows/release.yaml) (a thin caller of [`photon-hq/buildspace`'s `typescript-service-release`](https://github.com/photon-hq/buildspace)) generates a version + notes, bumps `package.json`, creates a GitHub Release, and publishes to npm. Standalone binaries are uploaded by [`release-binaries.yaml`](.github/workflows/release-binaries.yaml) on each release. - ---- - -## License - -[MIT](./LICENSE). +Tagged via PR labels. Add the `release` label to any PR; on merge to `main`, the [Release workflow](.github/workflows/release.yaml) (a thin caller of [`photon-hq/buildspace`'s `typescript-service-release`](https://github.com/photon-hq/buildspace)) generates a version + notes, bumps `package.json`, creates a GitHub Release, and publishes to npm. Standalone binaries are uploaded by [`release-binaries.yaml`](.github/workflows/release-binaries.yaml) on each release. diff --git a/package.json b/package.json index dfbf1c7..c2afc0b 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,6 @@ "imessage", "developer-tools" ], - "license": "MIT", "author": "Photon", "homepage": "https://github.com/photon-hq/cli#readme", "repository": { @@ -28,8 +27,7 @@ }, "files": [ "dist", - "README.md", - "LICENSE" + "README.md" ], "publishConfig": { "access": "public" From 5752678a814a58e9974609bac3a77bd82b56f931 Mon Sep 17 00:00:00 2001 From: citron <45784494+lcandy2@users.noreply.github.com> Date: Thu, 30 Apr 2026 02:53:51 +0800 Subject: [PATCH 3/3] fix(publish): rename to @photon-ai/photon + address review feedback 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) Co-authored-by: Orca --- .github/workflows/release-binaries.yaml | 6 ++- .github/workflows/release.yaml | 4 +- README.md | 63 +++++++++++++++++-------- package.json | 6 +-- 4 files changed, 52 insertions(+), 27 deletions(-) diff --git a/.github/workflows/release-binaries.yaml b/.github/workflows/release-binaries.yaml index 9126f0d..970bf0d 100644 --- a/.github/workflows/release-binaries.yaml +++ b/.github/workflows/release-binaries.yaml @@ -28,7 +28,7 @@ jobs: - os: macos-latest target: bun-darwin-arm64 asset: photon-darwin-arm64 - - os: macos-13 + - os: macos-15-intel target: bun-darwin-x64 asset: photon-darwin-x64 - os: ubuntu-latest @@ -42,7 +42,9 @@ jobs: - uses: actions/checkout@v5 - uses: oven-sh/setup-bun@v2 with: - bun-version: latest + # Pinned for reproducibility — matches the lower bound in + # package.json#engines.bun. Bump intentionally when upgrading. + bun-version: "1.3.13" - name: Install run: bun install --frozen-lockfile diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index cd0a8e1..40e1143 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -26,8 +26,8 @@ jobs: contents: write pull-requests: read with: - service-name: "@photon-ai/cli" + service-name: "@photon-ai/photon" build-command: "bun run build" release: ${{ github.event_name == 'workflow_dispatch' && inputs.release || false }} - dry-run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry-run || false }} + dry-run: ${{ github.event_name == 'workflow_dispatch' && inputs['dry-run'] || false }} secrets: inherit diff --git a/README.md b/README.md index b495573..699a72d 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Typed terminal UI for the [Photon Dashboard](https://photon.codes). Replaces the web UI for everyday work — manage projects, Spectrum users / lines / platforms, billing, and your developer profile from a terminal. ```sh -bun add -g @photon-ai/cli +bun add -g @photon-ai/photon photon login photon projects ls ``` @@ -16,7 +16,7 @@ photon projects ls ```sh # 1. Install -bun add -g @photon-ai/cli +bun add -g @photon-ai/photon # 2. Log in (opens a browser to approve the device) photon login @@ -38,6 +38,14 @@ pho ls # photon projects ls pho whoami ``` +Or run one-off commands without installing via `npx` / `bunx`: + +```sh +bunx @photon-ai/photon login +bunx @photon-ai/photon projects ls +npx @photon-ai/photon whoami # also works +``` + --- ## Concepts @@ -56,18 +64,18 @@ Every command operates against an **environment** (production by default). Built photon env list # show all photon env use staging # persist as default photon env add my-test https://my.test.tld # add a custom env -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 ``` -Credentials are stored **per environment** (`~/.config/photon/credentials/.json`, mode 600), so you can be logged into prod and dev simultaneously. +Credentials are stored **per environment** (`$PHOTON_CONFIG_DIR/credentials/.json` by default — see [config dir](#config-dir) below — mode 600), so you can be logged into prod and dev simultaneously. ### Project linking Most commands operate on a single project. Rather than passing `--project ` every time, link a project for the current env: ```sh -photon link abc123 # writes ~/.config/photon/links/.json +photon link abc123 # writes $PHOTON_CONFIG_DIR/links/.json photon spectrum users ls # implicit project from link photon projects show # same photon link:status # see what's linked across envs @@ -78,10 +86,10 @@ Resolution order: `--project ` flag → `$PHOTON_PROJECT_ID` → linked proj ### CI / scripting -Authenticate once locally, copy the token from `~/.config/photon/credentials/.json`, and use it in CI: +Authenticate once locally, copy the token from your credentials file (under `$PHOTON_CONFIG_DIR/credentials/.json`), and use it in CI: ```sh -photon --token "$PHOTON_TOKEN" projects ls +photon projects ls --token "$PHOTON_TOKEN" # or PHOTON_TOKEN=… photon projects ls ``` @@ -138,20 +146,37 @@ Run `photon --help` for the full flag list of any command. --- -## Global flags +## Flags + +Only `--debug` is truly **program-level** (works in any position). Every other flag is **per-command** and must come after the subcommand: + +```sh +photon --debug projects ls --env staging --json # ✓ --debug global, others per-cmd +photon --env staging projects ls # ✗ won't work (--env is per-cmd) +``` + +| Flag | Env var | Scope | Effect | +|---|---|---|---| +| `--debug` | `PHOTON_DEBUG=1` | program | verbose HTTP logs to stderr | +| `-e, --env ` | `PHOTON_ENV` | per-cmd | override active env | +| `-p, --project ` | `PHOTON_PROJECT_ID` | per-cmd | override linked project | +| `-t, --token ` | `PHOTON_TOKEN` | per-cmd | bypass stored creds (CI) | +| `--json` | — | per-cmd | structured output (opt-in) | +| `--yes`, `-y` | — | per-cmd | skip destructive-action confirmation | +| `--no-browser` | — | per-cmd | don't auto-open browser (login, billing, projects open) | +| `--no-color` | `NO_COLOR=1`, `PHOTON_NO_COLOR=1` | program (env-driven) | disable colors (NO_COLOR standard) | + +### config dir + +The CLI's config root is resolved in this order: + +1. `$PHOTON_CONFIG_DIR` (explicit override) +2. `$XDG_CONFIG_HOME/photon` (XDG standard) +3. `~/.config/photon/` (default) -| Flag | Env var | Effect | -|---|---|---| -| `-e, --env ` | `PHOTON_ENV` | override active env | -| `-p, --project ` | `PHOTON_PROJECT_ID` | override linked project (per-command) | -| `-t, --token ` | `PHOTON_TOKEN` | bypass stored creds (CI) | -| `--json` | — | structured output (per-command, opt-in) | -| `--yes`, `-y` | — | skip destructive-action confirmation | -| `--no-browser` | — | don't auto-open browser (login, billing, projects open) | -| `--no-color` | `NO_COLOR=1`, `PHOTON_NO_COLOR=1` | disable colors (NO_COLOR standard) | -| `--debug` | `PHOTON_DEBUG=1` | verbose HTTP logs to stderr | +If a legacy `~/.config/photon-dashboard/` directory exists from a prior pre-rename install, it migrates automatically to the new path on first run. -Other env vars: `PHOTON_CONFIG_DIR` (defaults to `~/.config/photon/`), `PHOTON_TYPES_SRC` (maintainer-only, for `bun run sync:api`), `PHOTON_NO_UPDATE_NOTIFIER=1` (mute update prompt). +Other env vars: `PHOTON_TYPES_SRC` (maintainer-only, for `bun run sync:api`), `PHOTON_NO_UPDATE_NOTIFIER=1` (mute update prompt). --- diff --git a/package.json b/package.json index c2afc0b..e75f7f6 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "@photon-ai/cli", + "name": "@photon-ai/photon", "version": "0.0.1", "description": "Photon CLI — typed terminal UI for the Photon Dashboard. Binary: `photon` (alias `pho`).", "keywords": [ @@ -47,9 +47,7 @@ "devDependencies": { "@types/bun": "latest", "@types/update-notifier": "^6.0.8", - "elysia": "1.4.28" - }, - "peerDependencies": { + "elysia": "1.4.28", "typescript": "^5" }, "dependencies": {