@acsetra/runner 0.1.82 → 0.1.83

package/bin/runner.js

@@ -70,13 +70,43 @@ async function signin(rest) {
   return 1;
 }
 
+function verTuple(v) { return String(v).split(".").map(x => parseInt(x, 10) || 0); }
+function verBelow(a, b) {  // is version a < version b (numeric, per segment)
+  const [ta, tb] = [verTuple(a), verTuple(b)];
+  for (let i = 0; i < Math.max(ta.length, tb.length); i++) {
+    const d = (ta[i] || 0) - (tb[i] || 0);
+    if (d) return d < 0;
+  }
+  return false;
+}
+
+// The version handshake: the pack carries the server docs' grammar hash + client
+// version bounds. Matching grammar → silent; old-but-compatible → one concise
+// note; below the minimum → strong warning before authoring. Never a hard fail.
+async function warnGrammarDrift(pack) {
+  const g = await import("../lib/grammar_info.js");
+  const server = pack.grammar_version;
+  if (!server || server === g.grammarHash()) return;
+  const minimum = pack.minimum_cli_version;
+  const hint = pack.recommended_cli_version ? ` (recommended: ${pack.recommended_cli_version})` : "";
+  if (minimum && verBelow(g.CLI_VERSION, minimum)) {
+    console.error(`WARNING: this CLI (${g.CLI_VERSION}) is below the server's minimum (${minimum}) — its grammar is missing arguments the server accepts. Upgrade BEFORE authoring: npm i -g @acsetra/runner${hint}`);
+  } else {
+    console.error(`note: installed CLI grammar differs from the server's docs grammar — upgrade when convenient: npm i -g @acsetra/runner${hint}`);
+  }
+}
+
 async function docsPull(rest) {
   const scope = opt(rest, "-S") || opt(rest, "--scope") || config.defaultScope();
   let pack;
-  // runtime: "npm" picks the npx/node_modules-specific wire-in block in CLAUDE.md.
-  const params = scope ? { scope, runtime: "npm" } : { runtime: "npm" };
+  // runtime: "npm" picks the npx/node_modules-specific wire-in block in CLAUDE.md;
+  // cli_version + grammar_version are the client half of the version handshake.
+  const g = await import("../lib/grammar_info.js");
+  const params = { runtime: "npm", cli_version: g.CLI_VERSION, grammar_version: g.grammarHash() };
+  if (scope) params.scope = scope;
   try { pack = await api.get("/api/v1/context-pack", params); }
   catch (e) { console.error("docs pull failed: " + e.message); return 1; }
+  await warnGrammarDrift(pack);
   let n = 0;
   for (const [rel, content] of Object.entries(pack.files)) {
     if (path.basename(rel).endsWith(".local.md")) continue;
@@ -160,7 +190,7 @@ async function main() {
   const argv = process.argv.slice(2);
   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.82"); return 0; }
+  if (["version", "--version", "-V"].includes(cmd)) { console.log("runner (@acsetra/runner) 0.1.83"); return 0; }
 
   // help — top-level, `help <topic>`, and per-verb `<cmd> … --help` (lexical, before toOp)
   if (cmd === "help") {
@@ -177,6 +207,13 @@ async function main() {
   if (cmd === "use") { if (!rest[0]) return fail("usage: runner use <org-slug>   (home org for bare-leaf scopes; full <org>.<app> paths need no `use`)"); config.setProject({ workspace: rest[0] }); console.error("home org -> " + rest[0] + " (bare-leaf default only)"); 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 === "grammar") {
+    // local machine-readable grammar dump — reads the installed manifest, no network
+    const g = await import("../lib/grammar_info.js");
+    const name = rest.find(a => !a.startsWith("-")) || null;
+    try { console.log(JSON.stringify(g.payload(name), null, 2)); return 0; }
+    catch (e) { return fail(e.message, 2); }
+  }
   if (cmd === "checkout" || cmd === "co") return checkout(rest);
 
   try {

package/lib/grammar.json

@@ -886,7 +886,11 @@
     },
     "docs": {
       "usage": "docs pull [-S scope]",
-      "desc": "refresh CLAUDE.md + .runner/docs/* (this app's context)"
+      "desc": "refresh CLAUDE.md + AGENTS.md + .runner/docs/* (this app's context)"
+    },
+    "grammar": {
+      "usage": "grammar [<op>] [--json]",
+      "desc": "dump the installed CLI grammar as JSON (local manifest; no network). With <op>, just that operation."
     },
     "dev": {
       "usage": "dev <app> [--no-browser]",
@@ -1000,5 +1004,58 @@
     "login": "signin",
     "signout": "logout",
     "co": "checkout"
+  },
+  "doc_sections": {
+    "_comment": "Documentation coverage map for scripts/render_hosted_cli_docs.py: every group in `groups` and every verb in `verbs_doc` must be assigned to EXACTLY ONE hosted doc (design.md or backend.md). Tests reject duplicates and omissions.",
+    "design": {
+      "groups": [
+        "component",
+        "css",
+        "asset",
+        "behavior",
+        "head"
+      ],
+      "verbs": [
+        "dev",
+        "open",
+        "focus",
+        "compile",
+        "doctor",
+        "verify"
+      ]
+    },
+    "backend": {
+      "groups": [
+        "set"
+      ],
+      "verbs": [
+        "signin",
+        "whoami",
+        "workspaces",
+        "use",
+        "logout",
+        "usage",
+        "tokens",
+        "docs",
+        "grammar",
+        "notify",
+        "tabs",
+        "devices",
+        "checkout",
+        "app",
+        "apps",
+        "auth",
+        "ls",
+        "inspect",
+        "read",
+        "show",
+        "run",
+        "runs",
+        "pipe",
+        "pipes",
+        "w",
+        "op"
+      ]
+    }
   }
 }

package/lib/grammar_info.js

@@ -0,0 +1,57 @@
+// r grammar — the machine-readable grammar dump (local; no network).
+// Node mirror of acsetra_cli/grammar_info.py: reads the INSTALLED manifest
+// (lib/grammar.json), renders one JSON payload with every operation's positional
+// order, the named argument a bare `--json` fills, `-b` bodies, flag coercion
+// types, and short aliases. grammar_version is the sha256 of the manifest bytes
+// — the same hash the server's context pack reports.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { GRAMMAR, JSON_ARGS, INT_ARGS, FLOAT_ARGS, BOOL_ARGS } from "./verbs.js";
+
+const GRAMMAR_BYTES = fs.readFileSync(new URL("./grammar.json", import.meta.url));
+export const CLI_VERSION = JSON.parse(
+  fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+export function grammarHash() {
+  return "sha256:" + crypto.createHash("sha256").update(GRAMMAR_BYTES).digest("hex");
+}
+
+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 opEntry(op) {
+  const doc = GRAMMAR.ops_doc[op] || {};
+  const rev = Object.fromEntries(Object.entries(GRAMMAR.short).map(([s, l]) => [l, s]));
+  const kw = doc.kw || [];
+  return {
+    desc: doc.desc || "",
+    pos: [...(GRAMMAR.pos[op] || [])],
+    json: op in GRAMMAR.primary_json ? GRAMMAR.primary_json[op] : null,
+    body: Boolean(doc.body),
+    flags: Object.fromEntries(kw.map(k => [k, vtype(k)])),
+    short: Object.fromEntries(kw.filter(k => k in rev)
+      .map(k => ["-" + rev[k], "--" + k.replace(/_/g, "-")])),
+  };
+}
+
+export function payload(op = null) {
+  if (op) {
+    if (!(op in GRAMMAR.ops_doc)) throw new Error(`unknown op '${op}' — run \`r grammar\` for the full manifest`);
+    return { cli_version: CLI_VERSION, grammar_version: grammarHash(), operation: op, ...opEntry(op) };
+  }
+  return {
+    cli_version: CLI_VERSION,
+    grammar_version: grammarHash(),
+    groups: Object.fromEntries(Object.entries(GRAMMAR.groups)
+      .map(([g, subs]) => [g, subs.map(([sub]) => sub)])),
+    verbs: GRAMMAR.verbs_doc,
+    operations: Object.fromEntries(Object.keys(GRAMMAR.ops_doc).map(name => [name, opEntry(name)])),
+    group_aliases: GRAMMAR.group_aliases,
+    verb_aliases: GRAMMAR.verb_aliases,
+  };
+}

package/lib/help.js

@@ -105,7 +105,7 @@ export function renderTop() {
   out.push("Session",
            "  r signin / whoami / workspaces / logout / usage / tokens",
            "  r use <slug>           optional home org for bare-leaf scopes (full paths need none)",
-           "  r docs pull            refresh CLAUDE.md + .runner/docs/*",
+           "  r docs pull            refresh CLAUDE.md + AGENTS.md + .runner/docs/*",
            "  r dev <app>            open your app's hosted surface in the browser",
            "  r open / focus <scope> paired Chrome scope navigation",
            "  r notify <scope>       native notification → scope tab",
@@ -125,6 +125,7 @@ export function renderTop() {
            "  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`",
+           "  r grammar [<op>]              machine-readable grammar dump (local JSON)",
            "");
   out.push("Env: ACSETRA_API_BASE, ACSETRA_TOKEN, ACSETRA_WORKSPACE, ACSETRA_SCOPE");
   return out.join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acsetra/runner",
-  "version": "0.1.82",
+  "version": "0.1.83",
   "description": "Runner CLI — author and run hosted Runner apps from your terminal (the `runner` command).",
   "keywords": ["runner", "acsetra", "cli", "agent", "low-code"],
   "license": "MIT",