@azx-pbc/helix-cli 0.3.0 → 0.5.0

package/README.md

@@ -21,17 +21,23 @@ is wherever you're standing.
 Each setting is resolved **flags → environment → `helix.json` → built-in default**
 (first match wins):
 
-| Setting    | Flag           | Env                | `helix.json` key | Default                    |
-| ---------- | -------------- | ------------------ | ---------------- | -------------------------- |
-| App slug   | `--slug`       | —                  | `slug`           | _(required)_               |
-| Portal URL | `--portal-url` | `HELIX_PORTAL_URL` | `portalUrl`      | `http://localhost:3001`    |
-| Build dir  | `--dir`        | —                  | `dir`            | `dist`                     |
-| Auth token | `--token`      | `HELIX_TOKEN`      | —                | _(`helix login` if unset)_ |
+| Setting     | Flag            | Env                | `helix.json` key | Default                    |
+| ----------- | --------------- | ------------------ | ---------------- | -------------------------- |
+| App slug    | `--slug`        | —                  | `slug`           | _(required)_               |
+| Portal URL  | `--portal-url`  | `HELIX_PORTAL_URL` | `portalUrl`      | `http://localhost:3001`    |
+| Build dir   | `--dir`         | —                  | `dir`            | `dist`                     |
+| Auth token  | `--token`       | `HELIX_TOKEN`      | —                | _(`helix login` if unset)_ |
+| Description | `--description` | —                  | `description`    | —                          |
 
 A `helix.json` looks like:
 
 ```json
-{ "slug": "my-app", "dir": "dist", "portalUrl": "https://portal.example.com" }
+{
+  "slug": "my-app",
+  "dir": "dist",
+  "portalUrl": "https://portal.example.com",
+  "description": "Tracks Q3 cloud spend by team."
+}
 ```
 
 **`portalUrl` is the one you cannot leave to the default.** `http://localhost:3001`
@@ -55,12 +61,14 @@ would be wrong for every deployment but one — so to deploy an example, add
 helix login                                                   # browser sign-in (OIDC device flow)
 helix logout                                                  # forget the cached tokens
 helix whoami                                                  # who the portal thinks you are
-helix create   [--display-name <name>] [--visibility <v>]   # register the app
+helix create   [--display-name <name>] [--description <text>] [--visibility <v>]   # register the app
 helix deploy   [--dir <dir>] [--bundle <zip>] [--promote]    # upload a version
 helix versions                                               # list versions
 helix promote  <number>                                      # make a version live
 helix rollback [number]                                      # revert the live pointer
 helix skill    [--path <file>]                               # write this deployment's agent skill to disk
+helix ci init  [--repo <owner/name>] [--branch <b>] [--reusable] [--force]   # deploy from GitHub Actions
+helix ci show | helix ci remove                              # the app's repo binding
 ```
 
 `deploy` uploads the bundle as a **preview**; `--promote` flips it live in the
@@ -74,6 +82,36 @@ in. It needs no app slug or `helix.json`, only a portal URL and a token. Default
 `./SKILL.md`; `--path .claude/skills/helix/SKILL.md` drops it where a Claude Code
 agent reads it off disk.
 
+### Deploying from GitHub Actions
+
+`helix ci init`, run signed in from the app's directory in its repo checkout,
+connects the app to the repo and branch. The repo comes from `origin`; the
+branch is the remote's default branch. `--repo` and `--branch` override either.
+It then writes `.github/workflows/helix-deploy.yml` and merges `slug`,
+`portalUrl` and `dir` into `helix.json`, or into a legacy `azx.json` if that's
+the file in use. Commit both. Each push to the branch then lands a preview
+(ADR-0051). Re-running it keeps any environment or workflow limit set on the
+Repository tab, and refuses to replace a workflow pin unless you pass `--force`.
+
+The generated workflow has two jobs. `build` installs and builds with no
+`id-token` permission. `deploy` downloads the output and runs only the pinned
+CLI. Code from the repo or its dependencies never runs where it could mint a
+deploy token.
+
+The workflow needs no secret. Inside GitHub Actions, when `HELIX_TOKEN` is not
+set and the job has `permissions: id-token: write`, `helix deploy` asks GitHub
+for an OIDC token whose audience is the portal (read from `GET /api/v1/config`)
+and uploads to `POST /api/v1/apps/:slug/ci/versions`. CI deploys always land as
+a preview, so `--promote` is refused there. It refuses to send the token to a
+plain-`http` portal other than one on `localhost`.
+
+`--reusable` writes a caller of the public reusable workflow
+(`AZX-PBC-OSS/helix-actions`, source in `integrations/helix-actions/`) instead
+of a self-contained one. It also pins the binding to that workflow, so no other
+workflow on the branch can deploy. `helix ci show` prints the binding,
+including the repo ids pinned by the first deploy. `helix ci remove` disconnects
+the app.
+
 > **Breaking in 0.2.0:** the `private` visibility mode was renamed to `internal`.
 > It never checked _which_ user signed in, only that someone had. Passing the old
 > value now **errors** rather than mapping to the new one, deliberately: the name
@@ -85,9 +123,11 @@ agent reads it off disk.
 Two paths, in precedence order:
 
 1. **Static token** — `HELIX_TOKEN` / `--token`. Sends the value as a bearer
-   token verbatim. This is the CI/scripts path, and also how the portal's
-   dev-token stub keeps working (`HELIX_TOKEN=$PORTAL_DEV_TOKEN`). It is never
-   accepted by a production portal.
+   token verbatim. This is the local scripts path, and also how the portal's
+   dev-token stub keeps working (`HELIX_TOKEN=$PORTAL_DEV_TOKEN`). The dev token
+   is never accepted by a production portal. A stored token is not a supported
+   way to deploy from CI; repo-backed deploys use the workflow's GitHub Actions
+   OIDC token instead (ADR-0051).
 2. **`helix login`** — the OIDC device flow. The CLI asks the portal
    (`GET /api/v1/auth/config`) which issuer to use (the local dev IdP on
    `:3002` in dev; Entra later), prints a verification URL + code, and polls