@dylanpiercey/work 0.2.17 → 0.2.19

package/bin/work.mjs

@@ -6,17 +6,26 @@
 //                 it otherwise offers when Tailscale is logged in; --no-tailscale skips that;
 //                 --firewall adds a `work` rule for direct connections' UDP port to a host
 //                 firewall that may drop it, or on macOS lets the service's node in,
-//                 which it otherwise offers; --no-firewall skips that)
+//                 which it otherwise offers; --no-firewall skips that;
+//                 --allow-host <name> / --disallow-host <name>, repeated, put one name
+//                 in or out of WORK_ALLOWED_HOSTS and keep the rest; --json prints
+//                 what it did as JSON on stdout, its progress on stderr)
 //   work doctor   report machine readiness (--json, --fix to install what's missing)
 //   work start    run the server in the foreground
-//   work update   upgrade the npm package and refresh the service
+//   work update   upgrade the npm package and refresh the service (--yes, --json as setup's)
 //   work usage    print agent plan/quota usage
 //   work workspaces           list workspaces (name, branch, sessions, ports)
-//   work workspace [id|name]  one workspace: repos, PRs, sessions, procs (default: the current one)
+//   work workspace [id|name]  one workspace: repos, PRs, sessions, procs (default: the current one;
+//                             --fresh asks GitHub again rather than the PR cache, ~2 min old)
 //   work repos [id|name]      a workspace's repos with base branch and open PRs
-//   work procs [id|name]      a workspace's running processes and ports
-//   work review [id|name]     pending review comments as markdown (--json for rows)
-//   work export [file]        write a backup manifest (workspaces, settings, skills, tool pins)
+//   work procs [id|name]      a workspace's running processes and ports, each port with
+//                             the link that opens it from the user's browser (through the
+//                             address it last reached work by)
+//   work review [id|name]     pending review comments as markdown (--json for rows;
+//                             --take also clears exactly those from the review, as its
+//                             Send does, once acted on, so a later Send cannot repeat them)
+//   work export [file]        write a backup manifest (workspaces, settings, skills, tool pins;
+//                             --json says what it wrote)
 //   work restore <file>       bring a manifest's workspaces and machine setup back (--yes to run;
 //                             --allow <spec|host>, repeated, for each tool outside work's catalog
 //                             or new GitHub host it names — skipped otherwise)
@@ -26,7 +35,13 @@
 //
 // The read commands ask the running server (same data as the UI) and take
 // --json for machine-readable output — agents inside a workspace should
-// use them instead of poking at the filesystem or GitHub.
+// use them instead of poking at the filesystem or GitHub. Nothing prompts
+// under --json, --non-interactive or WORK_NONINTERACTIVE=1: a question is
+// answered no, as --yes answers setup's optional ones.
+//
+// Commands beyond these live one file each under bin/cli/ (a file there
+// exports `commands`; see bin/cli/README.md), found at run time, and
+// `work help` lists them all: this header's own lines, then theirs.
 import { execFileSync, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
@@ -55,6 +70,7 @@ import { dialHost, listenStream } from "../lib/setup/listen.mjs";
 import { commentMarkdown } from "../lib/review/markdown.mjs";
 import { formatInvite, parseInvite } from "../lib/share/manifest.mjs";
 import { duration, pctText } from "../lib/usage/format.mjs";
+import { locOf, portBlockedAt, portUrlAt } from "../lib/ports/url.mjs";
 
 const pkgRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const pkg = JSON.parse(
@@ -63,7 +79,10 @@ const pkg = JSON.parse(
 const distEntry = path.join(pkgRoot, "dist", "index.mjs");
 const appPort = process.env.WORK_APP_PORT || "7171";
 
-const log = (msg) => console.log(`==> ${msg}`);
+// Under --json, stdout is the JSON alone: what a command says along the
+// way goes to stderr.
+const log = (msg) => (jsonOut ? console.error : console.log)(`==> ${msg}`);
+const say = (msg) => (jsonOut ? console.error : console.log)(msg);
 const warn = (msg) => console.warn(`warning: ${msg}`);
 const die = (msg) => {
   console.error(`error: ${msg}`);
@@ -79,6 +98,12 @@ const sh = (cmd, args, opts = {}) =>
 const [, , command = "help", ...args] = process.argv;
 const yes = args.includes("--yes") || args.includes("-y");
 const jsonOut = args.includes("--json");
+/** Whether a question may be asked at all: an agent's shell often has a
+ * controlling terminal it cannot answer on, and a prompt there hangs it. */
+const interactive =
+  !jsonOut &&
+  !args.includes("--non-interactive") &&
+  !process.env.WORK_NONINTERACTIVE;
 /** `--name <value>` style flags take the next arg; keep it out of the
  * positionals so `work join --name x` still reads stdin. */
 const VALUED = new Set(["--name", "--allow"]);
@@ -101,7 +126,22 @@ const flagValues = (flag) =>
     return [args[i + 1]];
   });
 
-switch (command) {
+// A command of bin/cli/ (`workspace create`: a word of the core's, then
+// its own) is looked for first, so one can extend a core command with
+// verbs of its own without a case here.
+const cli = await cliCommand(command, positional[0]);
+
+switch (cli ? "" : command) {
+  case "":
+    // `work session --help` is what an agent tries before `work help`.
+    if (args.includes("--help") || args.includes("-h")) await helpCmd(command);
+    else await cli.cmd.run(cliContext(cli.words));
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+    await helpCmd(positional[0]);
+    break;
   case "start":
     await start();
     break;
@@ -169,9 +209,10 @@ switch (command) {
     console.log(pkg.version);
     break;
   default:
-    console.log(
-      `work ${pkg.version}\n\nusage: work <setup|install-service|doctor|start|update|usage|workspaces|workspace|repos|procs|review|export|restore|share|join|version> [--json]`,
-    );
+    // A typo must fail: an agent reads the exit code, and usage on stdout
+    // with 0 read as the command having run.
+    console.error(`error: no command \`${command}\` (see: work help)`);
+    process.exitCode = 2;
 }
 
 async function start() {
@@ -232,18 +273,45 @@ function serverUrl() {
   return `http://${dialHost(env.WORK_LISTEN)}:${env.PORT}`;
 }
 
-async function apiGet(path) {
+/** One request to the running server: its JSON, or the command dies with
+ * the server's own reason (`{error}`), never only its status. */
+async function apiCall(method, path, body, timeoutMs = 30_000) {
   const port = serviceEnv().PORT;
+  let res;
   try {
-    const res = await fetch(`${serverUrl()}${path}`, {
-      signal: AbortSignal.timeout(30_000),
+    res = await fetch(`${serverUrl()}${path}`, {
+      method,
+      headers:
+        body === undefined ? undefined : { "content-type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
     });
-    if (!res.ok) die(`server answered ${res.status} for ${path}`);
-    return await res.json();
-  } catch (err) {
-    if (err?.message?.startsWith("server answered")) throw err;
+  } catch {
+    // Codex runs commands in a sandbox with no network, a local socket
+    // included: the server is up, the command has to run outside it,
+    // which the agent asks the user for.
+    if (process.env.CODEX_SANDBOX_NETWORK_DISABLED)
+      die(
+        "work cannot reach its server from inside Codex's sandbox (no network there): run this command outside the sandbox, with escalated permissions",
+      );
     die(`no work server on port ${port}. Start one with: work start`);
   }
+  const text = await res.text();
+  let data = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {}
+  if (!res.ok || (data && typeof data === "object" && data.error)) {
+    die(
+      (data && data.error) ||
+        `server answered ${res.status} for ${method} ${path}`,
+    );
+  }
+  return data;
+}
+
+function apiGet(path) {
+  return apiCall("GET", path);
 }
 
 /**
@@ -255,7 +323,7 @@ async function apiGet(path) {
 async function resolveWorkspace(arg) {
   const [list, status] = await Promise.all([
     apiGet("/api/workspaces"),
-    apiGet("/api/status"),
+    apiGet(statusPath()),
   ]);
   let ws;
   if (arg) {
@@ -294,10 +362,17 @@ function pad(s, n) {
   return String(s ?? "").padEnd(n);
 }
 
+/** The status snapshot, or with --fresh one that asks GitHub again: a PR
+ * made a moment ago (`gh pr create`) is otherwise missing for as long as
+ * the PR cache keeps its last answer. */
+function statusPath() {
+  return args.includes("--fresh") ? "/api/status?fresh" : "/api/status";
+}
+
 async function workspacesCmd() {
   const [list, status] = await Promise.all([
     apiGet("/api/workspaces"),
-    apiGet("/api/status"),
+    apiGet(statusPath()),
   ]);
   const rows = list.map((w) => ({ ...w, ...(status[w.id] || {}) }));
   if (jsonOut) return console.log(JSON.stringify(rows, null, 2));
@@ -323,21 +398,26 @@ function prLine(pr) {
         : pr.isDraft
           ? "draft"
           : "open";
-  return `#${pr.number} ${state}  ${pr.title}  ${pr.url}`;
+  return `#${pr.number} ${state}  ${pr.title}${pr.headRefName ? `  (${pr.headRefName})` : ""}  ${pr.url}`;
 }
 
 async function workspaceCmd() {
   const { ws, status } = await resolveWorkspace(positional[0]);
   const procs = await apiGet(`/api/workspaces/${ws.id}/procs`).catch(() => []);
-  const [sessions] = await Promise.all([
+  const [sessions, linkPort] = await Promise.all([
     apiGet(`/api/workspaces/${ws.id}/sessions`).catch(() => []),
+    portLinker(),
   ]);
+  const me = process.env.WORK_SESSION_ID;
   const out = {
     ...ws,
-    ports: status.ports,
+    ports: (status.ports || []).map((p) => ({
+      ...p,
+      ...linkPort(p.port, p.local),
+    })),
     repos: mergeRepos(ws, status),
-    sessions,
-    procs,
+    sessions: sessions.map((s) => (s.id === me ? { ...s, self: true } : s)),
+    procs: procs.map((p) => withUrls(p, linkPort)),
   };
   if (jsonOut) return console.log(JSON.stringify(out, null, 2));
   console.log(`${ws.name}  (${ws.status})`);
@@ -352,16 +432,58 @@ async function workspaceCmd() {
     console.log(`  sessions:`);
     for (const s of sessions) {
       const phase = s.state?.phase || (s.state?.alive ? "idle" : "off");
-      console.log(`    ${pad(s.agent, 10)} ${pad(phase, 8)} ${s.title || ""}`);
+      console.log(
+        `    ${pad(s.id, 9)} ${pad(s.agent, 10)} ${pad(phase, 8)} ${s.title || ""}${s.id === me ? "  (this session)" : ""}`,
+      );
     }
   }
   if (procs.length) {
     console.log(`  running:`);
-    for (const p of procs)
-      console.log(
-        `    ${pad(p.pid, 7)} ${p.cmd}${p.ports?.length ? "  " + p.ports.map((x) => `:${x}`).join(" ") : ""}`,
-      );
-  }
+    for (const p of out.procs)
+      console.log(`    ${pad(p.pid, 7)} ${p.cmd}${portsText(p)}`);
+  }
+}
+
+/** How a port opens for the user: through the address their browser last
+ * reached work by (`/api/boot`'s `origin`) as the page's port chip would
+ * (lib/ports/url), or this machine's own when no browser has yet. `blocked`
+ * says why that link cannot work (a port bound to loopback, a page on a
+ * direct address). */
+async function portLinker() {
+  const boot = await apiGet("/api/boot");
+  const loc = boot.origin ? locOf(boot.origin) : null;
+  return (port, local) => {
+    if (!loc) return { url: `http://localhost:${port}` };
+    const blocked = portBlockedAt(port, local, loc);
+    return {
+      url: portUrlAt(port, loc, boot.portHosts),
+      ...(blocked && { blocked }),
+    };
+  };
+}
+
+/** A process with each of its ports' links (`urls`, by port). */
+function withUrls(p, linkPort) {
+  if (!p.ports?.length) return p;
+  const local = new Set(p.local || []);
+  return {
+    ...p,
+    urls: Object.fromEntries(
+      p.ports.map((port) => [port, linkPort(port, local.has(port))]),
+    ),
+  };
+}
+
+/** A process's ports for a line of text, each with where it opens. */
+function portsText(p) {
+  if (!p.ports?.length) return "";
+  return `  ${p.ports
+    .map((port) => {
+      const link = p.urls?.[port];
+      if (!link) return `:${port}`;
+      return `:${port} ${link.url}${link.blocked ? ` (${link.blocked})` : ""}`;
+    })
+    .join("  ")}`;
 }
 
 /** Workspace repos joined with the status snapshot's PRs per repo. */
@@ -387,13 +509,15 @@ async function reposCmd() {
 
 async function procsCmd() {
   const { ws } = await resolveWorkspace(positional[0]);
-  const procs = await apiGet(`/api/workspaces/${ws.id}/procs`);
+  const [raw, linkPort] = await Promise.all([
+    apiGet(`/api/workspaces/${ws.id}/procs`),
+    portLinker(),
+  ]);
+  const procs = raw.map((p) => withUrls(p, linkPort));
   if (jsonOut) return console.log(JSON.stringify(procs, null, 2));
   if (!procs.length) return console.log("nothing running");
   for (const p of procs)
-    console.log(
-      `${pad(p.pid, 7)} ${p.cmd}${p.ports?.length ? "  " + p.ports.map((x) => `:${x}`).join(" ") : ""}`,
-    );
+    console.log(`${pad(p.pid, 7)} ${p.cmd}${portsText(p)}`);
 }
 
 /** Comments left on the review page but not yet sent: an agent can pull
@@ -402,9 +526,23 @@ async function procsCmd() {
 async function reviewCmd() {
   const { ws } = await resolveWorkspace(positional[0]);
   const { comments = [] } = await apiGet(`/api/workspaces/${ws.id}/review`);
-  if (jsonOut) return console.log(JSON.stringify(comments, null, 2));
-  if (!comments.length) return console.log("no pending review comments");
-  console.log(commentMarkdown(comments, await reviewSections(ws.id, comments)));
+  if (jsonOut) console.log(JSON.stringify(comments, null, 2));
+  else if (!comments.length) console.log("no pending review comments");
+  else
+    console.log(
+      commentMarkdown(comments, await reviewSections(ws.id, comments)),
+    );
+  // Taken, the comments leave the review as a Send takes them: exactly the
+  // ones printed, so one written meanwhile stays for the next look.
+  if (args.includes("--take") && comments.length) {
+    await apiPost(`/api/workspaces/${ws.id}/review`, {
+      action: "clear",
+      ids: comments.map((c) => c.id),
+    });
+    console.error(
+      `took ${comments.length} comment${comments.length === 1 ? "" : "s"} off the review`,
+    );
+  }
 }
 
 /** The diff's sections, which say which lane or PR a comment's lines are
@@ -413,41 +551,25 @@ async function reviewCmd() {
  * comments then read as the checkout's rather than failing the command. */
 async function reviewSections(wsId, comments) {
   if (!comments.some((c) => c.head)) return null;
-  const port = serviceEnv().PORT;
   try {
-    const res = await fetch(
-      `http://127.0.0.1:${port}/api/workspaces/${wsId}/diff`,
-      { signal: AbortSignal.timeout(60_000) },
-    );
+    const res = await fetch(`${serverUrl()}/api/workspaces/${wsId}/diff`, {
+      signal: AbortSignal.timeout(60_000),
+    });
     return res.ok ? ((await res.json()).sections ?? null) : null;
   } catch {
     return null;
   }
 }
 
-async function apiPost(path, body) {
-  const port = serviceEnv().PORT;
-  let res;
-  try {
-    res = await fetch(`${serverUrl()}${path}`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: body === undefined ? undefined : JSON.stringify(body),
-      signal: AbortSignal.timeout(15 * 60_000),
-    });
-  } catch {
-    die(`no work server on port ${port}. Start one with: work start`);
-  }
-  const data = await res.json().catch(() => ({}));
-  if (!res.ok || data.error)
-    die(data.error || `server answered ${res.status} for ${path}`);
-  return data;
+/** A write: as long as a clone can take (a create, a restore). */
+function apiPost(path, body) {
+  return apiCall("POST", path, body ?? {}, 15 * 60_000);
 }
 
 /** One line per workspace/repo of what the file will not carry. */
 function printPreflight(found) {
   for (const w of found.workspaces) {
-    console.log(w.name);
+    say(w.name);
     for (const r of w.repos) {
       const parts = [];
       for (const b of r.unpushed)
@@ -456,10 +578,10 @@ function printPreflight(found) {
       if (r.untracked.length) parts.push(`${r.untracked.length} untracked`);
       if (r.ignored.length) parts.push(`${r.ignored.length} ignored`);
       if (r.more) parts.push(`+${r.more} more`);
-      console.log(`  ${r.worktree}/  ${parts.join(", ")}`);
-      for (const f of r.modified) console.log(`    M ${f}`);
-      for (const f of r.untracked) console.log(`    ? ${f}`);
-      for (const f of r.ignored) console.log(`    ! ${f}`);
+      say(`  ${r.worktree}/  ${parts.join(", ")}`);
+      for (const f of r.modified) say(`    M ${f}`);
+      for (const f of r.untracked) say(`    ? ${f}`);
+      for (const f of r.ignored) say(`    ! ${f}`);
     }
   }
 }
@@ -477,7 +599,7 @@ async function exportCmd() {
     );
   }
   if (found.workspaces.length) {
-    console.log("not in the backup:");
+    say("not in the backup:");
     printPreflight(found);
     if (!yes) {
       console.log("");
@@ -498,6 +620,18 @@ async function exportCmd() {
     "work-backup.json";
   fs.writeFileSync(name, await res.text());
   log(`wrote ${name}`);
+  if (jsonOut)
+    console.log(
+      JSON.stringify(
+        {
+          file: path.resolve(name),
+          contents: c ?? null,
+          left_out: found.workspaces,
+        },
+        null,
+        2,
+      ),
+    );
 }
 
 function readManifest(file) {
@@ -658,6 +792,8 @@ function until(iso) {
 }
 
 async function setup() {
+  // First: a bad name fails before anything is touched.
+  editAllowedHosts();
   await bridge();
   const d = await doctor(doctorOpts());
   await fix(d);
@@ -670,13 +806,30 @@ async function setup() {
   const port = serviceEnv().PORT;
   if (!tailnet) maybeTunnel(port);
   if (running) {
-    if (await waitForServer()) log(`done — http://localhost:${port}`);
-    else
+    const answered = await waitForServer();
+    if (answered) log(`done — http://localhost:${port}`);
+    else {
       warn(
         `service started but nothing answered on port ${port} within 30s — check the logs`,
       );
+      // A setup that left no server is a failed one, to whatever ran it.
+      process.exitCode = 1;
+    }
     if (tailnet)
       log(`on your phone and other devices on the tailnet: ${tailnet}`);
+    if (jsonOut)
+      console.log(
+        JSON.stringify(
+          {
+            ok: answered,
+            version: pkg.version,
+            url: `http://localhost:${port}`,
+            tailnet: tailnet || null,
+          },
+          null,
+          2,
+        ),
+      );
   } else {
     // A fresh install's shell may not have mise on PATH yet — name the shim.
     const shim = path.join(
@@ -694,6 +847,34 @@ async function setup() {
   }
 }
 
+/** `--allow-host <name>` / `--disallow-host <name>`, each repeatable: one
+ * name in or out of the service's WORK_ALLOWED_HOSTS, the rest kept —
+ * `WORK_ALLOWED_HOSTS=… work setup` replaces the whole list, which an
+ * agent adding one proxy's name would otherwise have to read back first.
+ * Applied before anything writes the service, which carries what this
+ * leaves in the environment (`serviceEnv`). */
+function editAllowedHosts() {
+  const allow = flagValues("--allow-host");
+  const disallow = flagValues("--disallow-host");
+  if (!allow.length && !disallow.length) return;
+  for (const name of [...allow, ...disallow]) {
+    if (!/^[A-Za-z0-9.-]+$/.test(name))
+      die(
+        `not a host name: ${name} (one name per flag, e.g. work.example.com)`,
+      );
+  }
+  const before = serviceEnv().WORK_ALLOWED_HOSTS || "";
+  let next = before;
+  for (const name of allow) next = allowHost(next, name, true);
+  for (const name of disallow) next = allowHost(next, name, false);
+  process.env.WORK_ALLOWED_HOSTS = next;
+  log(
+    next === before
+      ? `WORK_ALLOWED_HOSTS unchanged: ${next || "(none)"}`
+      : `WORK_ALLOWED_HOSTS=${next || "(none)"}`,
+  );
+}
+
 /** Bring a database from before 0.1 to the baseline this release starts
  * from (lib/setup/bridge.mjs), before anything touches the service: the
  * server it would restart refuses such a database. Run with the settings
@@ -745,22 +926,35 @@ async function update() {
   // `--prefer-online`: npm serves `latest` from a cached packument for a
   // few minutes after a publish, so an update right behind a release
   // reinstalled the version already running.
-  sh("npm", [
-    "install",
-    "-g",
-    "--prefer-online",
-    ...allowScriptsArgs(),
-    "@dylanpiercey/work@latest",
-  ]);
+  // Under --json, npm's own output goes to stderr: stdout is setup's JSON.
+  const stdio = jsonOut ? ["inherit", 2, 2] : "inherit";
+  sh(
+    "npm",
+    [
+      "install",
+      "-g",
+      "--prefer-online",
+      ...allowScriptsArgs(),
+      "@dylanpiercey/work@latest",
+    ],
+    { stdio },
+  );
   // Re-exec the (possibly new) CLI to finish with fresh code.
   sh("work", [
     "setup",
     ...(yes ? ["--yes"] : []),
     ...args.filter((a) =>
-      ["--tailscale", "--no-tailscale", "--firewall", "--no-firewall"].includes(
-        a,
-      ),
+      [
+        "--tailscale",
+        "--no-tailscale",
+        "--firewall",
+        "--no-firewall",
+        "--json",
+        "--non-interactive",
+      ].includes(a),
     ),
+    ...flagValues("--allow-host").flatMap((h) => ["--allow-host", h]),
+    ...flagValues("--disallow-host").flatMap((h) => ["--disallow-host", h]),
   ]);
 }
 
@@ -976,7 +1170,7 @@ async function fix(d) {
     }
     log(`installing ${tool.label} via ${tool.mise ? "mise" : "gh"}`);
     try {
-      await installTool(tool.id, { log: (l) => console.log(`    ${l}`) });
+      await installTool(tool.id, { log: (l) => say(`    ${l}`) });
     } catch (err) {
       if (tool.required) die(`${tool.label} install failed: ${err.message}`);
       warn(`${tool.label} install failed (non-fatal)`);
@@ -1741,6 +1935,7 @@ function allowTailnet(serve) {
  * controlling terminal, since the curl installer pipes its script into the
  * shell this runs under. Null with no terminal at all. */
 function terminal() {
+  if (!interactive) return null;
   if (process.stdin.isTTY) return process.stdin;
   try {
     return new tty.ReadStream(fs.openSync("/dev/tty", "r"));
@@ -1763,3 +1958,139 @@ async function confirm(input, question) {
     rl.close();
   }
 }
+
+// -- commands of bin/cli/ and help ------------------------------------------
+
+/** Every command a file of bin/cli/ exports (`_`-prefixed files are its
+ * helpers), loaded once. (Kept on the function: the dispatch above runs
+ * before a top-level `let` here would be initialised.) */
+async function cliCommands() {
+  if (cliCommands.cache) return cliCommands.cache;
+  const dir = path.join(pkgRoot, "bin", "cli");
+  const files = fs.existsSync(dir)
+    ? fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".mjs") && !f.startsWith("_"))
+        .sort()
+    : [];
+  const all = [];
+  for (const f of files) {
+    const mod = await import(path.join(dir, f));
+    for (const c of mod.commands || []) all.push(c);
+  }
+  cliCommands.cache = all;
+  return all;
+}
+
+/** A core command's other name, which a bin/cli/ command's first word may
+ * be spelled with (`work ws create` is `workspace create`). */
+function canonical(word) {
+  return word === "ws" ? "workspace" : word;
+}
+
+/** The bin/cli/ command `argv` names: two words (`workspace create`)
+ * before one, so a verb of its own wins over the word alone. */
+async function cliCommand(first, second) {
+  const all = await cliCommands();
+  const head = canonical(first);
+  const names = (c) => [c.name, ...(c.aliases || [])];
+  if (second) {
+    const two = `${head} ${second}`;
+    const cmd = all.find((c) => names(c).includes(two));
+    if (cmd) return { cmd, words: 2 };
+  }
+  const cmd = all.find((c) => names(c).includes(head));
+  return cmd ? { cmd, words: 1 } : null;
+}
+
+/** What a bin/cli/ command is handed: its own argv, the CLI's flags, and
+ * the helpers every command shares — the running server (`api`), which
+ * workspace is meant, and how to say something or fail. */
+function cliContext(words) {
+  const own = args.slice(0);
+  // The words that named it are not its positionals.
+  const pos = positional.slice(words - 1);
+  return {
+    pkg,
+    args: own,
+    positional: pos,
+    json: jsonOut,
+    yes,
+    has: (flag) => args.includes(flag),
+    flag: flagValue,
+    flags: flagValues,
+    /** Positionals with `valued` flags' values left out (`--agent x`). */
+    parse(valued = []) {
+      const set = new Set([...VALUED, ...valued]);
+      return args
+        .filter(
+          (a, i) => a === "-" || (!a.startsWith("-") && !set.has(args[i - 1])),
+        )
+        .slice(words - 1);
+    },
+    api: {
+      get: (p) => apiCall("GET", p),
+      post: (p, body) => apiPost(p, body),
+      put: (p, body) => apiCall("PUT", p, body ?? {}),
+      patch: (p, body) => apiCall("PATCH", p, body ?? {}),
+      del: (p, body) => apiCall("DELETE", p, body),
+    },
+    serverUrl,
+    resolveWorkspace,
+    /** `data` as JSON under --json, else what `text` prints. */
+    out(data, text) {
+      if (jsonOut) console.log(JSON.stringify(data, null, 2));
+      else text?.(data);
+    },
+    pad,
+    log,
+    warn,
+    die,
+  };
+}
+
+/** The header's own lines for the core commands: `work <name>` and what
+ * continues it, as written at the top of this file. */
+function coreHelp() {
+  const src = fs.readFileSync(fileURLToPath(import.meta.url), "utf8");
+  const lines = [];
+  for (const line of src.split("\n").slice(1)) {
+    if (!line.startsWith("//")) break;
+    const text = line.replace(/^\/\/ ?/, "");
+    // The list starts at its first `work …` line and ends at a blank one.
+    if (!lines.length && !/^ {2}work /.test(text)) continue;
+    if (!text.trim()) break;
+    lines.push(text.replace(/^ {2}/, ""));
+  }
+  return lines;
+}
+
+/** `work help`: every command, the core's then bin/cli/'s; `work help
+ * <cmd>` that one's whole text. */
+async function helpCmd(topic) {
+  const all = await cliCommands();
+  const core = coreHelp();
+  if (topic) {
+    const head = canonical(topic);
+    const own = all.filter(
+      (c) => c.name === head || c.name.startsWith(`${head} `),
+    );
+    const start = core.findIndex((l) => new RegExp(`^work ${head}\\b`).test(l));
+    if (start < 0 && !own.length)
+      die(`no command \`${topic}\` (see: work help)`);
+    if (start >= 0) {
+      let end = start + 1;
+      while (end < core.length && !core[end].startsWith("work ")) end++;
+      console.log(core.slice(start, end).join("\n"));
+    }
+    for (const c of own) console.log(`\n${c.help || c.summary}`);
+    return;
+  }
+  console.log(`work ${pkg.version}\n`);
+  console.log(core.join("\n"));
+  for (const c of all) console.log(`work ${c.name.padEnd(22)} ${c.summary}`);
+  console.log(
+    "\nwork help <command> for one command's whole text. Most take --json;",
+  );
+  console.log("under it stdout is JSON alone and progress goes to stderr.");
+}