pylot-cli 0.1.1 → 0.1.2

package/README.md

@@ -116,18 +116,33 @@ The operator image bakes the bundle in as `/usr/local/bin/pylot`
 
 ## Publishing to npm (maintainers)
 
-The package is public on npm as `pylot-cli`. To cut a release:
-
-1. Bump `version` in `modules/cli/package.json` (semver — the bundle embeds it
-   via `__CLI_VERSION__`, so `pylot --version` reports whatever you publish).
-2. From `modules/cli/`: `npm publish --access public`. The `prepublishOnly`
-   hook runs the typecheck and a fresh build, and the `files` allowlist keeps
-   the tarball to `dist/index.mjs` + README only — no source, no lockfile.
-3. Publishing requires an npm token with publish rights on `pylot-cli` — use
-   an **Automation** token (or a granular token with 2FA bypass) in CI;
-   interactive publishes prompt for the account OTP.
-4. Verify: `npm view pylot-cli version` and
-   `npx -y pylot-cli@latest --version`.
+The package is public on npm as `pylot-cli`. Releases are pipeline-driven:
+
+1. In your PR, bump `version` in `modules/cli/package.json` (semver — the
+   bundle embeds it via `__CLI_VERSION__`, so `pylot --version` reports
+   whatever you publish). A PreToolUse hook (`.claude/doc-coverage.json`)
+   reminds any agent editing gateway route files to do this.
+2. Merge → deploy. Every **prod** deploy ends with a drift check
+   (`scripts/ci-cli-publish-trigger.sh` in `buildspec-cdk-deploy.yml`): if the
+   deployed tree's version isn't on npm, it triggers the publish build
+   automatically. Nothing to do.
+3. Manual trigger (same build): `pylot deploy publish-cli --wait`
+   (POST `/admin/publish-cli` → `buildspec-cli-publish.yml` →
+   `scripts/publish-cli.sh` on the pylot-builder CodeBuild project).
+   Idempotent — if the version is already on npm it no-ops. `--dry-run`
+   rehearses without the token; staging builders are always forced dry-run
+   (npm `latest` tracks prod/main only).
+4. Verify: `npm view pylot-cli version` and `npx -y pylot-cli@latest --version`.
+
+Credentials: `NPM_TOKEN` (npm **Automation** token — bypasses 2FA, publish
+rights on `pylot-cli`) lives in ASM **`pylot/npm`**; the CodeBuild service
+role reads it at run time. That bundle is deliberately outside the gateway
+secrets hierarchy (the 4-layer path validator rejects `pylot/npm`), so no
+team/role/repo scope — and therefore no mission container — can ever resolve
+it. It is never a repo secret, never an env override, and never logged. Local manual publish still works from `modules/cli/` with
+`NPM_TOKEN` in your env (`npm publish --access public` — `prepublishOnly`
+runs typecheck + fresh build; the `files` allowlist keeps the tarball to
+`dist/index.mjs` + README).
 
 Version discipline: any change to gateway routes that the CLI wraps should
 land with a CLI bump in the same PR train, so the published CLI never lags

package/dist/index.mjs

@@ -15382,6 +15382,17 @@ async function waitForBuild(opts, cfg, buildId, { timeoutMs, promoteKey }) {
   emit(opts, resp);
   process.exit(ok ? 0 : 1);
 }
+function withParentBuildOpts(flags, cmd) {
+  const parent = cmd.parent;
+  if (!parent) return flags;
+  const parentOpts = parent.opts();
+  for (const key of ["sourceVersion", "wait", "timeout"]) {
+    if (cmd.getOptionValueSource(key) !== "cli" && parent.getOptionValueSource(key) === "cli") {
+      flags[key] = parentOpts[key];
+    }
+  }
+  return flags;
+}
 function registerDeploy(program3) {
   const deploy = program3.command("deploy").description(
     "trigger a cdk deploy via CodeBuild (POST /admin/deploy) \u2014 a 409 means a deploy is already running (deploy lock held: {stage, held_by, since, build_id}); wait for it or poll `pylot deploy status`"
@@ -15418,6 +15429,7 @@ function registerDeploy(program3) {
   deploy.command("build-operator").description(
     'rebuild the operator image (POST /admin/build-operator). With --wait: SUCCEEDED alone is not "promoted" \u2014 completion requires operator_promote with no failures'
   ).option("--source-version <ref>", "git ref to build (default: gateway's stage branch)").option("--wait", "poll until promoted (exit 0 only on SUCCEEDED + clean operator_promote)").option("--timeout <seconds>", "max seconds to wait (default 1500)", (v) => parseInt(v, 10), 1500).action(async (flags, cmd) => {
+    flags = withParentBuildOpts(flags, cmd);
     const { opts, cfg } = await ctx(cmd);
     const body = {};
     if (flags.sourceVersion) body.source_version = flags.sourceVersion;
@@ -15434,9 +15446,31 @@ function registerDeploy(program3) {
     note(opts, `operator build started: ${buildId}`);
     await waitForBuild(opts, cfg, buildId, { timeoutMs: flags.timeout * 1e3, promoteKey: "operator_promote" });
   });
+  deploy.command("publish-cli").description(
+    "publish modules/cli to npm as pylot-cli (POST /admin/publish-cli). Idempotent: no-ops when the tree's version is already on npm. Staging builders always dry-run"
+  ).option("--source-version <ref>", "git ref to publish from (default: gateway's stage branch)").option("--dry-run", "typecheck + build + npm publish --dry-run (no token, nothing published)").option("--wait", "poll until the build finishes (exit 0 only on SUCCEEDED)").option("--timeout <seconds>", "max seconds to wait (default 900)", (v) => parseInt(v, 10), 900).action(async (flags, cmd) => {
+    flags = withParentBuildOpts(flags, cmd);
+    const { opts, cfg } = await ctx(cmd);
+    const body = {};
+    if (flags.sourceVersion) body.source_version = flags.sourceVersion;
+    if (flags.dryRun) body.dry_run = true;
+    const resp = await request(cfg, "/admin/publish-cli", { method: "POST", body });
+    if (!flags.wait) {
+      emit(opts, resp);
+      return;
+    }
+    const buildId = resp.json?.build_id;
+    if (!buildId) {
+      emit(opts, resp);
+      process.exit(1);
+    }
+    note(opts, `pylot-cli publish build started: ${buildId}`);
+    await waitForBuild(opts, cfg, buildId, { timeoutMs: flags.timeout * 1e3 });
+  });
   deploy.command("build-worker").description(
     "build a repo's worker image (POST /admin/build-worker, body {repo}); --batch --file posts {repos: [...]} to /admin/build-worker/batch. With --wait: completion requires worker_promote with no failures"
   ).argument("[org/repo]", "repo to build (omit with --batch)").option("--source-version <ref>", "git ref to build the worker overlay from").option("--batch", "batch mode (POST /admin/build-worker/batch)").option("--file <path>", "JSON body from file ('-' for stdin; required with --batch)").option("--wait", "poll until promoted (exit 0 only on SUCCEEDED + clean worker_promote)").option("--timeout <seconds>", "max seconds to wait (default 1500)", (v) => parseInt(v, 10), 1500).action(async (repo, flags, cmd) => {
+    flags = withParentBuildOpts(flags, cmd);
     const { opts, cfg } = await ctx(cmd);
     if (flags.batch) {
       if (!flags.file) throw new UsageError('--batch requires --file <path|-> with {repos: ["org/repo", ...]}');
@@ -15760,12 +15794,12 @@ function registerAssets(program3) {
 }
 
 // src/index.mts
-var VERSION = true ? "0.1.1" : "0.0.0-dev";
+var VERSION = true ? "0.1.2" : "0.0.0-dev";
 installEpipeGuard();
 var program2 = new Command();
 program2.name("pylot").description(
   "Pylot gateway CLI \u2014 dispatch missions, tail logs, manage teams/admin/secrets without curl.\nJSON on non-TTY stdout (pipe-friendly for agents and jq); tables on TTY."
-).configureHelp({ sortSubcommands: true }).version(VERSION).option("--url <url>", "gateway base URL (default: PYLOT_DISPATCH_URL / PYLOT_API_URL / PYLOT_GATEWAY_URL)").option("--token <token>", "bearer token (default: PYLOT_API_TOKEN / PYLOT_SESSION_JWT / PYLOT_BROKER_TOKEN / PYLOT_DISPATCH_TOKEN)").option("--env <env>", "target environment: prod | staging (staging uses PYLOT_STAGING_URL + PYLOT_STAGING_DISPATCH_TOKEN)").option("--json", "force JSON output even on a TTY").option("-q, --quiet", "suppress progress notes on stderr");
+).allowExcessArguments(false).configureHelp({ sortSubcommands: true }).version(VERSION).option("--url <url>", "gateway base URL (default: PYLOT_DISPATCH_URL / PYLOT_API_URL / PYLOT_GATEWAY_URL)").option("--token <token>", "bearer token (default: PYLOT_API_TOKEN / PYLOT_SESSION_JWT / PYLOT_BROKER_TOKEN / PYLOT_DISPATCH_TOKEN)").option("--env <env>", "target environment: prod | staging (staging uses PYLOT_STAGING_URL + PYLOT_STAGING_DISPATCH_TOKEN)").option("--json", "force JSON output even on a TTY").option("-q, --quiet", "suppress progress notes on stderr");
 program2.exitOverride();
 program2.configureOutput({ outputError: (str, write) => write(str) });
 registerCore(program2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pylot-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "pylot — first-class CLI for the Pylot gateway API. Replaces curl workflows for operators and humans.",
   "bin": {