pylot-cli 0.1.0 → 0.1.2

package/README.md

@@ -1,7 +1,7 @@
 # pylot — the Pylot gateway CLI
 
 First-class CLI for the Pylot gateway API (epic #1802). Replaces every curl
-workflow — dispatching missions, tailing logs, crew/admin/secrets management —
+workflow — dispatching missions, tailing logs, team/admin/secrets management —
 for both AI operators (`claude -p` sessions, subagents) and humans.
 
 ```
@@ -41,7 +41,8 @@ the bundle in at `/usr/local/bin/pylot`.
 - **Destructive commands** (`kill`, `cancel`, `delete`, `revoke`, …) require
   `--force` and send nothing without it.
 - Single-file bundle (`dist/index.mjs`, esbuild) — no runtime `node_modules`.
-  Runtime deps are `commander` + `conf` only; no interactive/prompt libraries.
+  `commander` + `conf` are compiled in (a global install pulls zero packages);
+  no interactive/prompt libraries.
 
 ## Configuration
 
@@ -78,7 +79,7 @@ Run `pylot --help` (or `pylot <group> --help`) for the full tree.
 | `costs` `executor` `audits` `pricing` `logs` | cost reporting, executor sweeps, audit corpus, model pricing, infra logs |
 | `workers` `devboxes` | devbox workers and standalone devboxes |
 | `conversations` (`convo`) | full conversation surface: messages, wakes, subscriptions, resources, devboxes, analytics |
-| `crew` `route` | team config, operator instructions, role skills, crons, ledger, playbooks, goals |
+| `teams` `route` | team config, operator instructions, role skills, crons, ledger, playbooks, goals |
 | `admin` | config, audit, org caps, migrations |
 | `deploy` | POST /admin/deploy + CodeBuild polling (`--wait`), image builds |
 | `secrets` | path-based ASM bundle/key operations |
@@ -115,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

@@ -15177,23 +15177,23 @@ function registerConversations(program3) {
   });
 }
 
-// src/commands/crew.mts
+// src/commands/teams.mts
 async function readText(file) {
   const { readFileSync } = await import("node:fs");
   return file === "-" ? readFileSync(0, "utf8") : readFileSync(file, "utf8");
 }
-function registerCrew(program3) {
-  const crew = program3.command("crew").description("team config, operators, playbooks, goals, ledger");
-  crew.command("list").description("crew roster (GET /crew); --db for the raw DB view (GET /crew/_db)").option("--db", "DB-authoritative view (GET /crew/_db)").action(async (flags, cmd) => {
+function registerTeams(program3) {
+  const teams = program3.command("teams").description("team config, operators, playbooks, goals, ledger");
+  teams.command("list").description("team roster (GET /crew); --db for the raw DB view (GET /crew/_db)").option("--db", "DB-authoritative view (GET /crew/_db)").action(async (flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
     emit(opts, await request(cfg, flags.db ? "/crew/_db" : "/crew"));
   });
-  crew.command("update").description("patch team config fields (PATCH /admin/crew/:team)").argument("<team>").argument("[fields...]", "key=value pairs (e.g. max_concurrent=3 enabled=true)").option("--file <path>", "JSON body from file ('-' for stdin)").action(async (team, fields, flags, cmd) => {
+  teams.command("update").description("patch team config fields (PATCH /admin/crew/:team)").argument("<team>").argument("[fields...]", "key=value pairs (e.g. max_concurrent=3 enabled=true)").option("--file <path>", "JSON body from file ('-' for stdin)").action(async (team, fields, flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
     const body = await bodyFromArgs(fields, flags.file);
     emit(opts, await request(cfg, `/admin/crew/${encodeURIComponent(team)}`, { method: "PATCH", body }));
   });
-  crew.command("delete").description("delete a team (DELETE /admin/crew/:team?confirm=true)").argument("<team>").option("--force", "required to confirm deletion").action(async (team, flags, cmd) => {
+  teams.command("delete").description("delete a team (DELETE /admin/crew/:team?confirm=true)").argument("<team>").option("--force", "required to confirm deletion").action(async (team, flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
     if (!flags.force) throw new UsageError("deleting a team is destructive \u2014 re-run with --force");
     emit(
@@ -15204,7 +15204,7 @@ function registerCrew(program3) {
       })
     );
   });
-  crew.command("instructions").description("operator instructions text (GET /admin/crew/:team/operators/:role/instructions); --set --file to replace").argument("<team>").argument("<role>").option("--set", "replace the instructions (PUT, raw text body)").option("--file <path>", "text from file ('-' for stdin; required with --set)").action(async (team, role, flags, cmd) => {
+  teams.command("instructions").description("operator instructions text (GET /admin/crew/:team/operators/:role/instructions); --set --file to replace").argument("<team>").argument("<role>").option("--set", "replace the instructions (PUT, raw text body)").option("--file <path>", "text from file ('-' for stdin; required with --set)").action(async (team, role, flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
     const path5 = `/admin/crew/${encodeURIComponent(team)}/operators/${encodeURIComponent(role)}/instructions`;
     if (flags.set) {
@@ -15214,7 +15214,7 @@ function registerCrew(program3) {
     }
     emit(opts, await request(cfg, path5));
   });
-  crew.command("skills-add").description("add one skill to an operator (POST /admin/crew/:team/operators/:role/skills, body {skill, repo?, ref?})").argument("<team>").argument("<role>").argument("<skill>").option("--repo <org/repo>", "source repo \u2014 required when the skill is not yet in the org catalog").option("--ref <ref>", "source ref for fetch-on-add").action(async (team, role, skill, flags, cmd) => {
+  teams.command("skills-add").description("add one skill to an operator (POST /admin/crew/:team/operators/:role/skills, body {skill, repo?, ref?})").argument("<team>").argument("<role>").argument("<skill>").option("--repo <org/repo>", "source repo \u2014 required when the skill is not yet in the org catalog").option("--ref <ref>", "source ref for fetch-on-add").action(async (team, role, skill, flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
     const body = { skill };
     if (flags.repo) body.repo = flags.repo;
@@ -15227,7 +15227,7 @@ function registerCrew(program3) {
       })
     );
   });
-  crew.command("skills-remove").description("remove one skill from an operator (DELETE /admin/crew/:team/operators/:role/skills/:name)").argument("<team>").argument("<role>").argument("<skill>").option("--force", "required to confirm removal").action(async (team, role, skill, flags, cmd) => {
+  teams.command("skills-remove").description("remove one skill from an operator (DELETE /admin/crew/:team/operators/:role/skills/:name)").argument("<team>").argument("<role>").argument("<skill>").option("--force", "required to confirm removal").action(async (team, role, skill, flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
     if (!flags.force) throw new UsageError("removing a skill is destructive \u2014 re-run with --force");
     emit(
@@ -15239,7 +15239,7 @@ function registerCrew(program3) {
       )
     );
   });
-  crew.command("crons").description("enable/disable one named cron entry (PATCH /admin/crew/:team/crons/:name)").argument("<team>").argument("<name>").option("--enable", "set enabled: true").option("--disable", "set enabled: false").action(async (team, name, flags, cmd) => {
+  teams.command("crons").description("enable/disable one named cron entry (PATCH /admin/crew/:team/crons/:name)").argument("<team>").argument("<name>").option("--enable", "set enabled: true").option("--disable", "set enabled: false").action(async (team, name, flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
     if (Boolean(flags.enable) === Boolean(flags.disable)) {
       throw new UsageError("pass exactly one of --enable / --disable");
@@ -15252,7 +15252,7 @@ function registerCrew(program3) {
       })
     );
   });
-  crew.command("ledger").description("query team ledger entries (GET /admin/crew/:team/ledger)").argument("<team>").option("--type <type>", "heartbeat | dispatch | completion | event").option("--actor <actor>", "filter by actor").option("--days <n>", "lookback days (default 1)", (v) => parseInt(v, 10)).option("--limit <n>", "max rows (default 20)", (v) => parseInt(v, 10)).action(async (team, flags, cmd) => {
+  teams.command("ledger").description("query team ledger entries (GET /admin/crew/:team/ledger)").argument("<team>").option("--type <type>", "heartbeat | dispatch | completion | event").option("--actor <actor>", "filter by actor").option("--days <n>", "lookback days (default 1)", (v) => parseInt(v, 10)).option("--limit <n>", "max rows (default 20)", (v) => parseInt(v, 10)).action(async (team, flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
     emit(
       opts,
@@ -15261,14 +15261,14 @@ function registerCrew(program3) {
       })
     );
   });
-  crew.command("ledger-add").description("insert a ledger entry (POST /admin/crew/:team/ledger)").argument("<team>").requiredOption("--type <type>", "heartbeat | dispatch | completion | event").requiredOption("--summary <text>", "entry summary").option("--actor <actor>", "attributed actor").option("--metadata-file <path>", "JSON metadata from file ('-' for stdin)").action(async (team, flags, cmd) => {
+  teams.command("ledger-add").description("insert a ledger entry (POST /admin/crew/:team/ledger)").argument("<team>").requiredOption("--type <type>", "heartbeat | dispatch | completion | event").requiredOption("--summary <text>", "entry summary").option("--actor <actor>", "attributed actor").option("--metadata-file <path>", "JSON metadata from file ('-' for stdin)").action(async (team, flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
     const body = { type: flags.type, summary: flags.summary };
     if (flags.actor) body.actor = flags.actor;
     if (flags.metadataFile) body.metadata = JSON.parse(await readText(flags.metadataFile));
     emit(opts, await request(cfg, `/admin/crew/${encodeURIComponent(team)}/ledger`, { method: "POST", body }));
   });
-  crew.command("playbook").description("repo playbook text (GET /admin/playbooks/:org/repo); --set --file to replace").argument("<org/repo>").option("--set", "replace the playbook (PUT, raw text body)").option("--file <path>", "text from file ('-' for stdin; required with --set)").action(async (repo, flags, cmd) => {
+  teams.command("playbook").description("repo playbook text (GET /admin/playbooks/:org/repo); --set --file to replace").argument("<org/repo>").option("--set", "replace the playbook (PUT, raw text body)").option("--file <path>", "text from file ('-' for stdin; required with --set)").action(async (repo, flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
     const path5 = `/admin/playbooks/${repo}`;
     if (flags.set) {
@@ -15278,7 +15278,7 @@ function registerCrew(program3) {
     }
     emit(opts, await request(cfg, path5));
   });
-  crew.command("goals").description(
+  teams.command("goals").description(
     "team goals text (GET /admin/goals/:team); --set --file replaces (PUT raw text), --update --file appends the file text (PATCH JSON {append})"
   ).argument("<team>").option("--set", "replace the goals (PUT, raw text body)").option("--update", "append to the goals (PATCH, JSON {append: <file text>})").option("--file <path>", "text from file ('-' for stdin; required with --set/--update)").action(async (team, flags, cmd) => {
     const { opts, cfg } = await ctx(cmd);
@@ -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.0" : "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 crew/admin/secrets without curl.\nJSON on non-TTY stdout (pipe-friendly for agents and jq); tables on TTY."
-).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");
+  "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."
+).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);
@@ -15777,7 +15811,7 @@ registerObservability(program2);
 registerWorkers(program2);
 registerDevboxes(program2);
 registerConversations(program2);
-registerCrew(program2);
+registerTeams(program2);
 registerAdmin(program2);
 registerDeploy(program2);
 registerSecrets(program2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pylot-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "pylot — first-class CLI for the Pylot gateway API. Replaces curl workflows for operators and humans.",
   "bin": {
@@ -34,12 +34,10 @@
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck && npm run build"
   },
-  "dependencies": {
-    "commander": "^12.1.0",
-    "conf": "^13.1.0"
-  },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "commander": "^12.1.0",
+    "conf": "^13.1.0",
     "esbuild": "^0.25.0",
     "typescript": "^5.7.2"
   }