@acsetra/runner 0.1.0 → 0.1.5

package/bin/runner.js

@@ -3,38 +3,11 @@
 // commands (signin, whoami, docs, dev), everything else serialized to /api/v1/op.
 import fs from "node:fs";
 import path from "node:path";
-import http from "node:http";
-import https from "node:https";
 import { setTimeout as sleep } from "node:timers/promises";
 import * as config from "../lib/config.js";
 import * as api from "../lib/api.js";
 import { toOp, VerbError } from "../lib/verbs.js";
-
-const HELP = `runner — author and run hosted Runner apps.
-
-Session
-  runner signin [--api URL]      sign in (device flow); caches a token
-  runner whoami                  show the signed-in user + workspace
-  runner workspaces [--use SLUG] list workspaces; --use switches the active one
-  runner use <slug>              set the active workspace for this project
-  runner logout                  forget the cached token
-  runner usage [--days N]        metered usage vs your plan caps
-  runner tokens [new|list|revoke <id>]
-
-Context + dev
-  runner docs pull [-S scope]    refresh CLAUDE.md + .runner/docs/*
-  runner dev <app> [--hosted]    localhost surface proxied to hosted Runner
-
-Authoring (serialized to /api/v1/op)
-  runner app create <name>; runner apps
-  runner ls | inspect <set>      (-S scope)
-  runner set put <set> <row> --json '{…}'
-  runner pipe <code> -S <scope> --writes c:l ; runner w <code> snippet -b -
-  runner css|component|asset|behavior|head <sub> …
-  runner read <code> ; runner run <pipeline> -i '{…}' ; runner runs <id>
-  runner doctor <app> ; runner compile <app> ; runner op <name> --json '{…}'
-
-Env: ACSETRA_API_BASE, ACSETRA_TOKEN, ACSETRA_WORKSPACE, ACSETRA_SCOPE`;
+import { dispatchHelp, renderTop } from "../lib/help.js";
 
 function emit(result) {
   if (result && typeof result === "object" && "result" in result &&
@@ -95,48 +68,59 @@ async function docsPull(rest) {
   return 0;
 }
 
-async function dev(rest) {
-  const app = rest.find(a => !a.startsWith("-")) || config.defaultScope();
-  if (!app) return fail("runner dev: which app? e.g. `runner dev acme.crm`", 2);
-  const base = config.apiBase();
-  if (rest.includes("--hosted")) {
-    const url = `${base}/?scope=${app}`;
-    console.error("Opening hosted app: " + url);
-    if (!rest.includes("--no-browser")) openUrl(url);
-    return 0;
+// runner checkout <app> — hosted mirror of `./r checkout`: the server serializes
+// the scope subtree and we write the returned files under ./.tmp/<scope>/ so
+// native file tooling works. Disposable copy; the DB stays the source of truth.
+async function checkout(rest) {
+  const scope = rest.find(a => !a.startsWith("-")) || config.defaultScope();
+  if (!scope) return fail("runner checkout: which app? e.g. `runner checkout acme.crm`", 2);
+  let payload;
+  try { payload = await api.get("/api/v1/checkout", { scope }); }
+  catch (e) { console.error("checkout failed: " + e.message); return 1; }
+  const root = payload.root || scope;
+  const dest = path.join(opt(rest, "-o") || opt(rest, "--out") || ".tmp", root);
+  if (!prepareDest(dest, rest.includes("--force"))) return 1;
+  const files = { ...(payload.files || {}) };
+  files["manifest.json"] = JSON.stringify(payload.manifest, null, 2) + "\n";
+  files["INDEX.md"] = payload.index;
+  let written = 0;
+  for (const [rel, content] of Object.entries(files)) {
+    const full = safeJoin(dest, rel);
+    if (!full) { console.error("  ! skipped unsafe path " + rel); continue; }
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content); written++;
+  }
+  console.error(`checkout: wrote ${written} files to ${dest} (${payload.rows} rows)`);
+  console.error("  grep/read/edit the files; the DB stays source of truth (write back with the typed verbs).");
+  return 0;
+}
+
+// Clear a PRIOR checkout (recognised by manifest.json); refuse any other non-empty dir unless --force.
+function prepareDest(dest, force) {
+  if (fs.existsSync(dest)) {
+    if (fs.existsSync(path.join(dest, "manifest.json")) || force) fs.rmSync(dest, { recursive: true, force: true });
+    else if (fs.readdirSync(dest).length) {
+      console.error(`REJECTED: ${dest} exists and isn't a prior checkout — pass --force`); return false;
+    }
   }
-  const port = parseInt(opt(rest, "--port") || "8787", 10);
-  let sess;
-  try { sess = await api.post("/api/v1/dev/session", { scope: app }); }
-  catch (e) { return fail("runner dev: could not open a dev session: " + e.message); }
-  const cookie = `${sess.cookie_name}=${sess.cookie_value}`;
-  const upstream = new URL(base);
-  const server = http.createServer((req, res) => proxy(req, res, upstream, cookie));
-  server.listen(port, "127.0.0.1", () => {
-    const local = `http://127.0.0.1:${port}${sess.prefix || ""}/?scope=${app}`;
-    console.error(`runner dev: proxying ${app} → ${upstream.origin}`);
-    console.error(`  open  ${local}\n  (Ctrl-C to stop)`);
-    if (!rest.includes("--no-browser")) setTimeout(() => openUrl(local), 600);
-  });
-  return new Promise(() => {}); // serve until Ctrl-C
+  fs.mkdirSync(dest, { recursive: true });
+  return true;
 }
 
-function proxy(req, res, upstream, cookie) {
-  const chunks = [];
-  req.on("data", c => chunks.push(c));
-  req.on("end", () => {
-    const headers = { ...req.headers, host: upstream.host };
-    headers.cookie = cookie + (req.headers.cookie ? "; " + req.headers.cookie : "");
-    delete headers["accept-encoding"];
-    const opts = { protocol: upstream.protocol, hostname: upstream.hostname,
-      port: upstream.port || (upstream.protocol === "https:" ? 443 : 80),
-      method: req.method, path: req.url, headers };
-    const lib = upstream.protocol === "https:" ? https : http;
-    const up = lib.request(opts, r => { res.writeHead(r.statusCode, r.headers); r.pipe(res); });
-    up.on("error", e => { res.writeHead(502); res.end("dev proxy error: " + e.message); });
-    if (chunks.length) up.write(Buffer.concat(chunks));
-    up.end();
-  });
+// Resolve rel under dest, refusing any path that escapes it (defense in depth).
+function safeJoin(dest, rel) {
+  const full = path.resolve(dest, rel);
+  const base = path.resolve(dest);
+  return full === base || full.startsWith(base + path.sep) ? full : null;
+}
+
+async function dev(rest) {
+  const app = rest.find(a => !a.startsWith("-")) || config.defaultScope();
+  if (!app) return fail("runner dev: which app? e.g. `runner dev acme.crm`", 2);
+  const url = `${config.apiBase()}/?scope=${app}`;
+  console.log(url);
+  if (!rest.includes("--no-browser")) openUrl(url);
+  return 0;
 }
 
 function openUrl(url) {
@@ -146,14 +130,25 @@ function openUrl(url) {
 
 async function main() {
   const argv = process.argv.slice(2);
-  if (!argv.length || ["help", "-h", "--help"].includes(argv[0])) { console.log(HELP); return 0; }
+  if (!argv.length || ["-h", "--help"].includes(argv[0])) { console.log(renderTop()); return 0; }
   const [cmd, ...rest] = argv;
-  if (["version", "--version", "-V"].includes(cmd)) { console.log("runner (@acsetra/runner) 0.1.0"); return 0; }
+  if (["version", "--version", "-V"].includes(cmd)) { console.log("runner (@acsetra/runner) 0.1.5"); return 0; }
+
+  // help — top-level, `help <topic>`, and per-verb `<cmd> … --help` (lexical, before toOp)
+  if (cmd === "help") {
+    const out = rest.length ? dispatchHelp(rest[0], rest.slice(1)) : null;
+    console.log(out != null ? out : renderTop()); return 0;
+  }
+  if (rest.includes("--help") || rest.includes("-h")) {
+    const out = dispatchHelp(cmd, rest);
+    if (out != null) { console.log(out); return 0; }
+  }
   if (cmd === "signin" || cmd === "login") return signin(rest);
   if (cmd === "logout" || cmd === "signout") { const c = config.loadUser(); delete c.token; config.saveUser(c); console.error("logged out"); return 0; }
   if (cmd === "use") { if (!rest[0]) return fail("usage: runner use <slug>"); config.setProject({ workspace: rest[0] }); console.error("workspace -> " + rest[0]); return 0; }
   if (cmd === "dev") return dev(rest);
   if (cmd === "docs") { if (rest[0] === "pull") return docsPull(rest); return fail("usage: runner docs pull [-S scope]"); }
+  if (cmd === "checkout" || cmd === "co") return checkout(rest);
 
   try {
     if (cmd === "whoami") return emit(await api.get("/api/v1/whoami"));

package/lib/api.js

@@ -55,6 +55,42 @@ export async function del(path) {
   return check(r);
 }
 
+// surface access (runtime routes: /bundle, /read, /run, /feed) — these are
+// COOKIE-authed, not bearer-authed. Trade the signed-in bearer for a per-app
+// session cookie via /api/v1/dev/session and attach it directly. No localhost
+// proxy: an agent is an HTTP client and sets its own Cookie header. The cookie is
+// scoped to ONE in-tenant app (least-privilege); the bearer is strictly stronger.
+const _sess = {};
+
+export async function surfaceSession(scope, refresh = false) {
+  if (!scope) throw new ApiError("surface access needs an app scope");
+  if (refresh || !_sess[scope]) {
+    const s = await post("/api/v1/dev/session", { scope });
+    _sess[scope] = { cookie: `${s.cookie_name}=${s.cookie_value}`, prefix: s.prefix || "" };
+  }
+  return _sess[scope];
+}
+
+export async function surfaceRequest(method, scope, path, { params, body } = {}) {
+  const send = (sess) => {
+    const url = new URL(config.apiBase() + sess.prefix + path);
+    url.searchParams.set("scope", scope);
+    for (const [k, v] of Object.entries(params || {})) url.searchParams.set(k, v);
+    return fetch(url, {
+      method,
+      headers: { Cookie: sess.cookie, ...(body ? { "Content-Type": "application/json" } : {}) },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  };
+  let r = await send(await surfaceSession(scope));
+  if (r.status === 401) r = await send(await surfaceSession(scope, true));
+  return check(r);
+}
+
+export async function surfaceGet(scope, path, params) {
+  return surfaceRequest("GET", scope, path, { params });
+}
+
 // device flow (no bearer yet) — returns {status, body} without throwing on poll codes
 export async function deviceStart(tokenName = "cli") {
   const r = await fetch(config.apiBase() + "/api/v1/auth/device/start", {

package/lib/help.js

@@ -0,0 +1,299 @@
+// Per-group / per-verb `--help` — Node mirror of acsetra_cli/help_text.py.
+// Rendered from the verb grammar itself (POS / PRIMARY_JSON / SHORT / coercion
+// sets) so it can't drift from what `toOp` actually dispatches. Output is kept
+// byte-identical to the Python client. dispatchHelp returns text, or null when
+// the command isn't one we document (so bin/runner.js falls through unchanged).
+import { POS, PRIMARY_JSON, SHORT, JSON_ARGS, INT_ARGS, FLOAT_ARGS, BOOL_ARGS } from "./verbs.js";
+
+const PROG = "r"; // docs lead with `r`; `runner` / `acsetra` are aliases
+
+export const GROUPS = {
+  set: [["create", "set.create"], ["put", "set.put"],
+        ["declare_schema", "set.declare_schema"], ["fetch_url", "set.fetch_url"],
+        ["remove_row", "set.remove_row"], ["drop", "set.drop"],
+        ["list", "set.list"], ["describe", "set.describe"],
+        ["rows", "set.rows"], ["validate", "set.validate"]],
+  css: [["init", "css.init"], ["set_class", "css.set_class"],
+        ["set_rule", "css.set_rule"], ["clear_rule", "css.clear_rule"],
+        ["attach", "css.attach"], ["detach", "css.detach"],
+        ["list_classes", "css.list_classes"], ["list_rules", "css.list_rules"],
+        ["list_attachments", "css.list_attachments"], ["describe", "css.describe"],
+        ["resolve", "css.resolve"], ["validate", "css.validate"]],
+  asset: [["init", "asset.init"], ["add", "asset.add"], ["attach", "asset.attach"],
+          ["detach", "asset.detach"], ["list", "asset.list"],
+          ["list_attachments", "asset.list_attachments"], ["describe", "asset.describe"],
+          ["resolve", "asset.resolve"], ["validate", "asset.validate"],
+          ["check", "asset.check"]],
+  behavior: [["init", "behavior.init"], ["add", "behavior.add"],
+             ["set_enabled", "behavior.set_enabled"], ["remove", "behavior.remove"],
+             ["attach", "behavior.attach"],
+             ["set_attachment_enabled", "behavior.set_attachment_enabled"],
+             ["detach", "behavior.detach"], ["list", "behavior.list"],
+             ["list_attachments", "behavior.list_attachments"],
+             ["describe", "behavior.describe"], ["validate", "behavior.validate"]],
+  component: [["init", "component.init"], ["set", "component.set"],
+              ["remove", "component.remove"], ["set_route", "component.set_route"],
+              ["remove_route", "component.remove_route"], ["list", "component.list"],
+              ["list_routes", "component.list_routes"], ["describe", "component.describe"],
+              ["validate", "component.validate"]],
+  head: [["init", "head.init"], ["set", "head.set"], ["remove", "head.remove"],
+         ["list", "head.list"], ["validate", "head.validate"]],
+};
+
+export const GROUP_ALIASES = { css: { class: "set_class", rule: "set_rule" } };
+
+export const OPS_DOC = {
+  "set.create": { desc: "create a value set (mint your own plane/registry)", kw: ["label", "kind", "schema"] },
+  "set.put": { desc: "write/merge a row (--json is the row meta; MERGES unless --replace)", kw: ["label", "ordinal", "enabled", "replace"] },
+  "set.declare_schema": { desc: "declare/replace a set's row-meta JSON-Schema contract", kw: [] },
+  "set.fetch_url": { desc: "import remote TEXT into a row (SSRF-guarded https GET)", kw: ["key", "label", "max_bytes", "allow_hosts", "replace", "ordinal"] },
+  "set.remove_row": { desc: "delete one row from a set", kw: [] },
+  "set.drop": { desc: "drop a whole value set", kw: ["force"] },
+  "set.list": { desc: "list value sets at the scope", kw: [] },
+  "set.describe": { desc: "show a set's schema + metadata", kw: [] },
+  "set.rows": { desc: "list a set's rows", kw: [] },
+  "set.validate": { desc: "re-check every set (grammar, bounds, declared schema)", kw: [] },
+
+  "css.init": { desc: "bootstrap the css plane for a scope", kw: [] },
+  "css.set_class": { desc: "create/define a css class (identity)", kw: ["label", "description", "enabled", "ordinal"] },
+  "css.set_rule": { desc: "set a class's declarations for a variant (--json is the decls)", kw: ["ordinal"] },
+  "css.clear_rule": { desc: "clear a class's rule (one variant or all)", kw: ["variant"] },
+  "css.attach": { desc: "attach a class to a surface (component:/instance:/part:/raw:/page:)", kw: ["label", "ordinal"] },
+  "css.detach": { desc: "remove a css attachment", kw: [] },
+  "css.list_classes": { desc: "list css classes", kw: [] },
+  "css.list_rules": { desc: "list css rules", kw: ["class_code"] },
+  "css.list_attachments": { desc: "list css attachments", kw: [] },
+  "css.describe": { desc: "show a class's rules + attachments", kw: [] },
+  "css.resolve": { desc: "show the resolved cascade for a page", kw: ["app"] },
+  "css.validate": { desc: "re-check every class/rule/attachment", kw: [] },
+
+  "asset.init": { desc: "bootstrap the asset plane", kw: [] },
+  "asset.add": { desc: "register a media asset (image/svg/icon/video/iframe)", kw: ["url", "name", "alt", "provider", "svg", "fit", "controls", "muted", "autoplay", "poster", "ordinal", "storage", "probe"] },
+  "asset.attach": { desc: "fill a named slot on a target with an asset", kw: ["page", "component", "raw", "type_", "part", "app", "ordinal"] },
+  "asset.detach": { desc: "remove an asset attachment", kw: [] },
+  "asset.list": { desc: "list assets", kw: [] },
+  "asset.list_attachments": { desc: "list asset attachments", kw: [] },
+  "asset.describe": { desc: "show an asset + its attachments", kw: [] },
+  "asset.resolve": { desc: "show resolved asset slots for a page", kw: ["app"] },
+  "asset.validate": { desc: "re-check every asset/attachment (shape only)", kw: [] },
+  "asset.check": { desc: "probe registered asset URLs (HEAD) for liveness", kw: ["code", "allow_hosts"] },
+
+  "behavior.init": { desc: "bootstrap the behavior plane", kw: [] },
+  "behavior.add": { desc: "add a browser ability (mount(ctx) JS body via -b -)", kw: ["label", "config_schema", "enabled", "ordinal"], body: true },
+  "behavior.set_enabled": { desc: "enable/disable a behavior definition", kw: [] },
+  "behavior.remove": { desc: "remove a behavior", kw: [] },
+  "behavior.attach": { desc: "mount a behavior on a target (--json is the config)", kw: ["label", "enabled", "ordinal"] },
+  "behavior.set_attachment_enabled": { desc: "enable/disable one placed mount", kw: [] },
+  "behavior.detach": { desc: "remove a behavior attachment", kw: [] },
+  "behavior.list": { desc: "list behaviors", kw: [] },
+  "behavior.list_attachments": { desc: "list behavior attachments", kw: [] },
+  "behavior.describe": { desc: "show a behavior + its mounts", kw: [] },
+  "behavior.validate": { desc: "re-check every behavior/attachment", kw: [] },
+
+  "component.init": { desc: "bootstrap the component+route plane", kw: [] },
+  "component.set": { desc: "author a component's node tree (--json is the tree)", kw: ["parts", "label", "ordinal"] },
+  "component.remove": { desc: "remove a component", kw: [] },
+  "component.set_route": { desc: "mount a component on a page (--json is route props)", kw: ["instance", "label", "ordinal"] },
+  "component.remove_route": { desc: "remove a route", kw: [] },
+  "component.list": { desc: "list components", kw: [] },
+  "component.list_routes": { desc: "list routes (pages)", kw: [] },
+  "component.describe": { desc: "show a component's refs + mounting routes", kw: [] },
+  "component.validate": { desc: "re-check every tree + ref", kw: [] },
+
+  "head.init": { desc: "bootstrap document_head (title/viewport/favicon)", kw: [] },
+  "head.set": { desc: "set/merge a <head> entry (--json is its attrs)", kw: ["tag", "text", "enabled", "ordinal", "label"] },
+  "head.remove": { desc: "remove a head entry", kw: [] },
+  "head.list": { desc: "list head entries in order", kw: [] },
+  "head.validate": { desc: "re-check every head entry", kw: [] },
+};
+
+export const VERBS_DOC = {
+  signin: { usage: "signin [--api URL] [--no-browser]", desc: "device-flow sign-in; caches a token" },
+  whoami: { usage: "whoami", desc: "show the signed-in user + workspace" },
+  workspaces: { usage: "workspaces [--use SLUG]", desc: "list workspaces; --use switches the active one" },
+  use: { usage: "use <slug>", desc: "set the active workspace for this project" },
+  logout: { usage: "logout", desc: "forget the cached token" },
+  usage: { usage: "usage [--days N]", desc: "metered usage vs your plan caps" },
+  tokens: { usage: "tokens [new [--name N] | list | revoke <id>]", desc: "manage API tokens" },
+  docs: { usage: "docs pull [-S scope]", desc: "refresh CLAUDE.md + .runner/docs/* (this app's context)" },
+  dev: { usage: "dev <app> [--no-browser]", desc: "open your app's hosted surface in the browser" },
+  checkout: { usage: "checkout <app> [-o dir] [--force]", desc: "materialize a scope subtree as local files in .tmp/ (read-only; grep/edit, write back with the typed verbs)" },
+  app: { usage: "app create <name> [--label L]  |  app list", desc: "create / list app scopes" },
+  apps: { usage: "apps", desc: "list app scopes (alias of `app list`)" },
+  ls: { usage: "ls [-S scope]", desc: "list value sets" },
+  inspect: { usage: "inspect [<set>] [-S scope]", desc: "read a set's rows (alias: i); no set => list" },
+  read: { usage: "read <code> [-S scope]", desc: "read a value set (me_* = your own per-user zone)" },
+  show: { usage: "show <pipeline>", desc: "reconstruct a pipeline from its rows" },
+  run: { usage: "run <pipeline> -i '{json}'", desc: "test-run a pipeline with input" },
+  runs: { usage: "runs <launch_id>", desc: "poll a launch's status/output" },
+  compile: { usage: "compile <app>", desc: "link the bundle + cross-plane diagnostics + content hash" },
+  doctor: { usage: "doctor <app>", desc: "full static gate over the subtree: validate every plane + link refs + compile code (non-zero exit = broken)" },
+  pipe: {
+    usage: "pipe <code> -S <scope> [-w code:label] [--rate N] [--timeout N] [--keep]\n" +
+           "       pipe show <code>  |  pipe list  |  pipe remove <code>",
+    desc: "create/upsert a pipeline envelope (resets workers unless --keep)",
+  },
+  pipes: { usage: "pipes", desc: "list pipelines (alias of `pipe list`)" },
+  w: {
+    usage: "w <pipeline> <tier> [flags]  [-w code:label] [--at N] [-S scope]",
+    desc: "add a worker to a pipeline (alias: work)",
+    extra: [
+      "Tiers:",
+      "  snippet   -b <code|->                       DB-isolated Python (sets output / output={'rows':[…]})",
+      "  internal  -H/--handler NAME                 a vetted internal handler",
+      "  httpx     -u/--url URL [-X METHOD]          call a service; keys injected server-side",
+      "            [-k/--keys a,b] [-f/--body-from K]",
+      "  read      --set CODE [--mode latest]        resolve a value set into the run data",
+      "            [--key K] [--as NAME] [--read-scope S]",
+      "  llm       [--provider openai] [--model M]   one model call (keys injected server-side)",
+      "            [--system-from K] [--user-from ask] [-k/--keys a,b]",
+    ],
+  },
+  op: {
+    usage: "op <name> [--json '{full args bag}'] [--flag value] [-S scope]",
+    desc: "call any op directly. Here --json IS the full args bag (never a single arg).",
+  },
+};
+
+export const VERB_ALIASES = { i: "inspect", work: "w", login: "signin", signout: "logout", co: "checkout" };
+
+const REV_SHORT = Object.fromEntries(Object.entries(SHORT).map(([s, l]) => [l, s]));
+
+const flagName = (name) => name.replace(/_/g, "-");
+
+function alias(name) {
+  const s = REV_SHORT[name];
+  return s ? `-${s}/--${flagName(name)}` : `--${flagName(name)}`;
+}
+
+function vtype(name) {
+  if (BOOL_ARGS.has(name)) return "flag";
+  if (JSON_ARGS.has(name)) return "json";
+  if (INT_ARGS.has(name)) return "int";
+  if (FLOAT_ARGS.has(name)) return "float";
+  return "str";
+}
+
+function usageFlag(name) {
+  const t = vtype(name);
+  const base = `--${flagName(name)}`;
+  if (t === "flag") return `[${base}]`;
+  if (t === "json") return `[${base} '{…}']`;
+  return `[${base} ${t === "int" || t === "float" ? "N" : "V"}]`;
+}
+
+const pad = (s, n) => (s.length >= n ? s : s + " ".repeat(n - s.length));
+
+export function renderOp(op) {
+  const pos = POS[op] || [];
+  const prim = PRIMARY_JSON[op];
+  const doc = OPS_DOC[op] || {};
+  const kw = doc.kw || [];
+  const body = doc.body || false;
+  const dot = op.indexOf(".");
+  const group = op.slice(0, dot), sub = op.slice(dot + 1);
+
+  const parts = [`${PROG} ${group} ${sub}`, ...pos.map((p) => `<${p}>`)];
+  if (prim) parts.push(`--json '{${prim}}'`);
+  if (body) parts.push("-b <code|->");
+  for (const k of kw) parts.push(usageFlag(k));
+  parts.push("[-S scope]");
+
+  const out = ["Usage:", "  " + parts.join(" "), ""];
+  if (doc.desc) out.push(doc.desc, "");
+  if (pos.length) {
+    out.push("Positional order:");
+    pos.forEach((p, i) => out.push(`  ${i + 1}. ${p}`));
+    out.push("");
+  }
+  if (prim) {
+    out.push(`--json  → sets ONLY the \`${prim}\` arg (this op's payload), NOT the whole args bag.`,
+             `        Other args come from positionals/flags. For the full bag: ${PROG} op ${op} --json '{…}'`, "");
+  } else {
+    out.push("--json  → merges its keys into the args bag.", "");
+  }
+  if (body) out.push("-b      body from an inline string, or '-' to read stdin (never escape code into JSON).", "");
+  if (kw.length) {
+    out.push("Flags:");
+    for (const k of kw) out.push(`  ${pad(alias(k), 22)} ${vtype(k)}`);
+    out.push("");
+  }
+  out.push(`Raw op: ${PROG} op ${op} …   ·   authoritative args: .runner/docs/commands.md`);
+  return out.join("\n");
+}
+
+export function renderGroup(group) {
+  const out = [`${PROG} ${group} — subcommands:`, ""];
+  for (const [sub, op] of GROUPS[group]) out.push(`  ${pad(sub, 22)} ${(OPS_DOC[op] || {}).desc || ""}`);
+  const al = GROUP_ALIASES[group];
+  if (al) out.push("", "Aliases: " + Object.entries(al).map(([a, c]) => `${a} → ${c}`).join(", "));
+  out.push("", `Run \`${PROG} ${group} <sub> --help\` for exact usage of a subcommand.`);
+  return out.join("\n");
+}
+
+export function renderVerb(verb) {
+  const doc = VERBS_DOC[verb];
+  const out = ["Usage:", "  " + PROG + " " + doc.usage, ""];
+  if (doc.desc) out.push(doc.desc, "");
+  if (doc.extra) out.push(...doc.extra, "");
+  out.push(`More: \`${PROG} help\` · grammar: .runner/docs/commands.md`);
+  return out.join("\n").replace(/\s+$/, "");
+}
+
+export function renderTop() {
+  const out = [`${PROG} — author and run hosted Runner apps.  (also installed as \`runner\`, \`acsetra\`)`, ""];
+  out.push("Session",
+           "  r signin / whoami / workspaces / use <slug> / logout / usage / tokens",
+           "  r docs pull            refresh CLAUDE.md + .runner/docs/*",
+           "  r dev <app>            open your app's hosted surface in the browser",
+           "  r checkout <app>       materialize the app as local files in .tmp/",
+           "");
+  out.push("Authoring (planes — run `r <group> --help` for subcommands)",
+           "  r app create <name> ; r apps",
+           "  r set | css | asset | behavior | component | head  <subverb> …",
+           "  r pipe <code> -S <scope> -w c:l ; r w <code> <tier> …",
+           "  r ls | inspect <set> | read <code> | show <pipe>",
+           "  r run <pipe> -i '{…}' ; r runs <id> ; r doctor <app> ; r compile <app>",
+           "  r op <name> --json '{…}'   call any op directly",
+           "");
+  out.push("Help",
+           "  r <group> --help              list a plane's subcommands",
+           "  r <group> <subverb> --help    exact usage, positional order, the --json rule",
+           "  r <verb> --help               e.g. `r w --help`, `r op --help`",
+           "");
+  out.push("Env: ACSETRA_API_BASE, ACSETRA_TOKEN, ACSETRA_WORKSPACE, ACSETRA_SCOPE");
+  return out.join("\n");
+}
+
+function firstToken(rest) {
+  for (const t of rest) if (!t.startsWith("-")) return t;
+  return null;
+}
+
+export function dispatchHelp(cmd, rest) {
+  cmd = cmd.replace(/-/g, "_");
+  cmd = VERB_ALIASES[cmd] || cmd;
+
+  if (cmd === "op") {
+    const name = firstToken(rest);
+    if (name && name in OPS_DOC) return renderOp(name);
+    if (name && name.includes(".")) return renderOp(name);
+    return renderVerb("op");
+  }
+  if (cmd === "help") {
+    const nxt = firstToken(rest);
+    return nxt ? dispatchHelp(nxt, rest.slice(1)) : renderTop();
+  }
+  if (cmd in GROUPS) {
+    let sub = firstToken(rest);
+    if (sub) {
+      sub = sub.replace(/-/g, "_");
+      sub = (GROUP_ALIASES[cmd] || {})[sub] || sub;
+      const op = `${cmd}.${sub}`;
+      if (op in OPS_DOC || GROUPS[cmd].some(([, o]) => o === op)) return renderOp(op);
+    }
+    return renderGroup(cmd);
+  }
+  if (cmd in VERBS_DOC) return renderVerb(cmd);
+  return null;
+}

package/lib/verbs.js

@@ -1,17 +1,17 @@
 // The verb grammar — argv -> {op, args}. Node mirror of acsetra_cli/verbs.py.
 import fs from "node:fs";
 
-const JSON_ARGS = new Set(["meta", "schema", "decls", "tree", "props", "parts", "input",
+export const JSON_ARGS = new Set(["meta", "schema", "decls", "tree", "props", "parts", "input",
   "attrs", "config", "config_schema", "storage", "allow_hosts", "spec"]);
-const INT_ARGS = new Set(["ordinal", "rate", "timeout", "retries", "at", "max_bytes", "ttl_days", "days"]);
-const FLOAT_ARGS = new Set(["backoff"]);
-const BOOL_ARGS = new Set(["replace", "force", "keep", "probe", "enabled", "muted", "autoplay", "controls", "auth_flow"]);
-const PRIMARY_JSON = {
+export const INT_ARGS = new Set(["ordinal", "rate", "timeout", "retries", "at", "max_bytes", "ttl_days", "days"]);
+export const FLOAT_ARGS = new Set(["backoff"]);
+export const BOOL_ARGS = new Set(["replace", "force", "keep", "probe", "enabled", "muted", "autoplay", "controls", "auth_flow"]);
+export const PRIMARY_JSON = {
   "set.put": "meta", "set.fetch_url": "meta", "set.declare_schema": "schema",
   "css.set_rule": "decls", "component.set": "tree", "component.set_route": "props",
   "behavior.attach": "config", "head.set": "attrs",
 };
-const POS = {
+export const POS = {
   "set.create": ["code"], "set.put": ["set_code", "row_code"], "set.declare_schema": ["code"],
   "set.fetch_url": ["set_code", "row_code", "url"], "set.remove_row": ["set_code", "row_code"],
   "set.drop": ["set_code"], "set.describe": ["set_code"], "set.rows": ["set_code"],
@@ -27,8 +27,8 @@ const POS = {
   "component.remove_route": ["code"], "component.describe": ["code"],
   "head.set": ["code"], "head.remove": ["code"],
 };
-const PLANES = new Set(["set", "css", "asset", "behavior", "component", "head"]);
-const SHORT = { w: "writes", k: "keys", u: "url", f: "body_from", H: "handler", X: "method", s: "spec", l: "label", i: "input" };
+export const PLANES = new Set(["set", "css", "asset", "behavior", "component", "head"]);
+export const SHORT = { w: "writes", k: "keys", u: "url", f: "body_from", H: "handler", X: "method", s: "spec", l: "label", i: "input" };
 
 export class VerbError extends Error {}
 
@@ -144,7 +144,7 @@ export function toOp(verb, rest) {
     const args = {};
     if (positionals.length) args.scope = positionals[0];
     if ("scope" in flags) args.scope = flags.scope;
-    return [verb === "compile" ? "bundle.compile" : "doctor.compile", args];
+    return [verb === "compile" ? "bundle.compile" : "doctor.check", args];
   }
   if (verb === "app") {
     if (rest[0] === "create") {

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@acsetra/runner",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "Runner CLI — author and run hosted Runner apps from your terminal (the `runner` command).",
   "keywords": ["runner", "acsetra", "cli", "agent", "low-code"],
   "license": "MIT",
   "type": "module",
   "bin": {
     "runner": "bin/runner.js",
-    "acsetra": "bin/runner.js"
+    "acsetra": "bin/runner.js",
+    "r": "bin/runner.js"
   },
   "engines": {
     "node": ">=18"