pylot-cli 0.1.1 → 0.1.3

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

@@ -14921,7 +14921,7 @@ function registerObservability(program3) {
     const { opts, cfg } = await ctx(cmd);
     emit(opts, await request(cfg, "/logs/router", { query: { lines: flags.lines } }));
   });
-  logs.command("admin").description("gateway Lambda CloudWatch logs by source (GET /admin/logs/:source)").argument("<source>", "api | ingress | processor | executor | notifier | scheduler | chat").option("--minutes <n>", "lookback minutes (max 180)", (v) => parseInt(v, 10)).option("--grep <pattern>", "filter pattern").option("--limit <n>", "max entries (max 1000)", (v) => parseInt(v, 10)).action(async (source, flags, cmd) => {
+  logs.command("admin").description("gateway Lambda CloudWatch logs by source (GET /admin/logs/:source)").argument("<source>", "api | ingress | processor | executor | notifier | scheduler | chat | proxy | slack-events | slack-processor").option("--minutes <n>", "lookback minutes (max 180)", (v) => parseInt(v, 10)).option("--grep <pattern>", "filter pattern").option("--limit <n>", "max entries (max 1000)", (v) => parseInt(v, 10)).action(async (source, flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
     emit(
       opts,
@@ -15358,7 +15358,7 @@ function printNewPhases(opts, body, seen) {
     note(opts, `phase ${p.phase}${p.status ? ` ${p.status}` : ""}`);
   }
 }
-async function waitForBuild(opts, cfg, buildId, { timeoutMs, promoteKey }) {
+async function waitForBuild(opts, cfg, buildId, { timeoutMs }) {
   const seenPhases = /* @__PURE__ */ new Set();
   const resp = await pollUntil(
     () => request(cfg, `/admin/build-worker/${encodeURIComponent(buildId)}`),
@@ -15372,16 +15372,35 @@ async function waitForBuild(opts, cfg, buildId, { timeoutMs, promoteKey }) {
   printNewPhases(opts, resp.json, seenPhases);
   const body = resp.json;
   const status = String(body?.status ?? "");
-  let ok = status === "SUCCEEDED";
-  if (ok && promoteKey) {
-    const promote = body?.[promoteKey];
-    ok = promote != null && (promote.failed ?? []).length === 0;
-    if (!ok) note(opts, `${buildId} SUCCEEDED but ${promoteKey} reported failures \u2014 NOT promoted`);
+  note(opts, `${buildId} ${status}${status === "SUCCEEDED" ? "" : " (failed)"}`);
+  if (status !== "SUCCEEDED") {
+    emit(opts, resp);
+    process.exit(1);
   }
-  note(opts, `${buildId} ${status}${ok ? "" : " (failed)"}`);
+  return resp;
+}
+async function promoteBuild(opts, cfg, buildId, { promoteKey, smoke = false }) {
+  const resp = await request(cfg, `/admin/build-worker/${encodeURIComponent(buildId)}/promote`, {
+    method: "POST",
+    body: promoteKey === "worker_promote" ? { smoke } : {}
+  });
+  const promote = resp.json?.[promoteKey];
+  const ok = resp.status >= 200 && resp.status < 300 && promote != null && (promote.failed ?? []).length === 0;
+  if (!ok) note(opts, `${buildId} ${promoteKey} failed`);
   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`"
@@ -15406,6 +15425,13 @@ function registerDeploy(program3) {
     const { opts, cfg } = await ctx(cmd);
     emit(opts, await request(cfg, `/admin/build-worker/${encodeURIComponent(buildId)}`));
   });
+  deploy.command("promote").description("promote a successful operator/worker image build (POST /admin/build-worker/:build_id/promote)").argument("<build_id>").option("--smoke", "for worker builds, run the live Fargate smoke gate before pinning").action(async (buildId, flags, cmd) => {
+    const { opts, cfg } = await ctx(cmd);
+    emit(opts, await request(cfg, `/admin/build-worker/${encodeURIComponent(buildId)}/promote`, {
+      method: "POST",
+      body: flags.smoke ? { smoke: true } : {}
+    }));
+  });
   deploy.command("logs").description("CodeBuild log tail via CloudWatch (GET /admin/deploy/logs/:build_id)").argument("<build_id>").option("--stage <stage>", "staging | production (default staging)").action(async (buildId, flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
     emit(
@@ -15416,8 +15442,9 @@ 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) => {
+    "rebuild the operator image (POST /admin/build-operator). With --wait: poll to SUCCEEDED, then explicitly promote"
+  ).option("--source-version <ref>", "git ref to build (default: gateway's stage branch)").option("--wait", "poll until SUCCEEDED, then promote (exit 0 only on 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;
@@ -15432,11 +15459,34 @@ function registerDeploy(program3) {
       process.exit(1);
     }
     note(opts, `operator build started: ${buildId}`);
-    await waitForBuild(opts, cfg, buildId, { timeoutMs: flags.timeout * 1e3, promoteKey: "operator_promote" });
+    await waitForBuild(opts, cfg, buildId, { timeoutMs: flags.timeout * 1e3 });
+    await promoteBuild(opts, cfg, buildId, { 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) => {
+    "build a repo's worker image (POST /admin/build-worker, body {repo}); --batch --file posts {repos: [...]} to /admin/build-worker/batch. With --wait: poll to SUCCEEDED, then explicitly promote"
+  ).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 SUCCEEDED, then promote (exit 0 only on clean worker_promote)").option("--smoke", "with --wait, run the live Fargate smoke gate before pinning").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", ...]}');
@@ -15458,7 +15508,8 @@ function registerDeploy(program3) {
       process.exit(1);
     }
     note(opts, `worker build started: ${buildId}`);
-    await waitForBuild(opts, cfg, buildId, { timeoutMs: flags.timeout * 1e3, promoteKey: "worker_promote" });
+    await waitForBuild(opts, cfg, buildId, { timeoutMs: flags.timeout * 1e3 });
+    await promoteBuild(opts, cfg, buildId, { promoteKey: "worker_promote", smoke: flags.smoke === true });
   });
   deploy.command("ensure-taskdefs").description("backfill per-role operator task definitions (POST /admin/operators/ensure-taskdefs)").action(async (_flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
@@ -15549,9 +15600,9 @@ function registerSkills(program3) {
     const { opts, cfg } = await ctx(cmd);
     emit(opts, await request(cfg, "/admin/skills/lock"));
   });
-  skills.command("staleness").description("SHA-mismatch report vs origin HEAD (GET /admin/skills/staleness)").action(async (_flags, cmd) => {
+  skills.command("staleness").description("SHA-mismatch report vs origin HEAD (GET /admin/skills/staleness?org=<org>)").requiredOption("--org <org>", "GitHub org to check (staleness is per-org, #1919)").action(async (flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
-    emit(opts, await request(cfg, "/admin/skills/staleness"));
+    emit(opts, await request(cfg, "/admin/skills/staleness", { query: { org: flags.org } }));
   });
   skills.command("sync").description(
     "trigger the CodeBuild skills-sync job for one org (POST /admin/skills/sync, body {org}) or every installed org (--all \u2192 POST /admin/skills/sync-all)"
@@ -15760,12 +15811,12 @@ function registerAssets(program3) {
 }
 
 // src/index.mts
-var VERSION = true ? "0.1.1" : "0.0.0-dev";
+var VERSION = true ? "0.1.3" : "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.3",
   "type": "module",
   "description": "pylot — first-class CLI for the Pylot gateway API. Replaces curl workflows for operators and humans.",
   "bin": {