@azure-id/orc 1.2.1 → 1.4.0

package/bin/verify-contracts.js

@@ -837,6 +837,26 @@ const CONTRACTS = [
       "skills/_shared/phases/preflight.md",
     ],
   },
+  {
+    // v1.3.0 W1 — the CLI Hook Interface. The compiled program is the ONE thing
+    // that crosses the wall between the CLI and the hook, so both halves have
+    // to name the same file. The AUTHORED layout is deliberately NOT registered
+    // here: the hook must never name it, because it must never read it.
+    name: "the compiled status-line program (the CLI compiles, the hook renders)",
+    token: "statusline-compiled.json",
+    binFiles: ["bin/cli.js"],
+    files: ["hooks/orc-statusline.js", "hooks/orc-statusline-render.js", "hooks/README.md"],
+  },
+  {
+    // The board rule, stated ONCE so the CLI, the hook and the panel all cite
+    // the same sentence. It is the thing a user most needs to understand about
+    // the board and the thing most likely to be paraphrased into three
+    // different half-truths.
+    name: "the dense-prefix invariant (the status-line board)",
+    token: "A line may hold a component only if every line above it holds at least one.",
+    binFiles: ["bin/cli.js"],
+    files: ["hooks/README.md", "hooks/orc-statusline.js"],
+  },
   {
     name: "behavior-trace run pointer (every ORC entry point writes .current)",
     token: ".current",
@@ -1371,7 +1391,11 @@ const CONTRACTS = [
     // wiki-meta.json lives under.
     name: "the challenge ledger (v0.47.0 — CLI-only writer)",
     token: "challenge.json",
-    files: ["skills/orc-challenge/references/cycle-state.md"],
+    files: [
+      "skills/orc-challenge/references/cycle-state.md",
+      // the `challenge` component reads it (v1.3.0)
+      "hooks/orc-statusline.js",
+    ],
     binFiles: ["bin/cli.js"],
   },
   {
@@ -1474,6 +1498,8 @@ const CONTRACTS = [
     token: "RESUME.md",
     binFiles: ["bin/cli.js"],
     files: [
+      // the `resume` / `open-runs` components read its one byte-stable line (v1.3.0)
+      "hooks/orc-statusline.js",
       // v1.0.0 W5 — the demotion's run-scoped record lives BESIDE it, in
       // {run_dir}/{slug}/, and is deleted with the run. A move of one is a move
       // of the other.
@@ -1966,6 +1992,8 @@ const CONTRACTS = [
     token: "orc-crosslink.config.yaml",
     binFiles: ["bin/cli.js"],
     files: [
+      // the `crosslink` component counts its peers (v1.3.0)
+      "hooks/orc-statusline.js",
       "skills/orc-poly/SKILL.md",
       "skills/orc-wiki/README.md",
       "skills/orc-wiki/SKILL.md",
@@ -3642,6 +3670,12 @@ for (const b of BUDGETS) {
     // spine reads `extra_timeout_s`. An empty lanes[] here is an ANSWER.
     "wait_hop_minutes",
     "wait_max_hops",
+    // v1.3.0 — an operating key of the STATUSLINE HOOK. A hook has no lane and
+    // cannot resolve config, so no spine reads this; the hook reads the raw key
+    // off the file, exactly as it already does for `log_dir` and
+    // `extra_enabled`. An empty lanes[] here is an ANSWER.
+    "statusline_custom",
+    "subagent_line_custom",
   ]);
   for (const e of metaEntries) {
     if (!e.lanes) {

package/bin/verify-package.js

@@ -47,6 +47,7 @@ const required = [
   "bin/webui/css/panels/pact.css",
   "bin/webui/css/panels/boundary.css",
   "bin/webui/css/panels/wait.css",
+  "bin/webui/css/panels/hookui.css",
   "bin/webui/css/panels/handoff.css",
   "bin/webui/css/panels/challenge.css",
   "bin/webui/css/panels/docs.css",
@@ -76,6 +77,7 @@ const required = [
   "bin/webui/js/panels/pact.js",
   "bin/webui/js/panels/boundary.js",
   "bin/webui/js/panels/wait.js",
+  "bin/webui/js/panels/hookui.js",
   "bin/webui/js/panels/handoff.js",
   "bin/webui/js/panels/challenge.js",
   "bin/webui/js/panels/docs.js",
@@ -95,6 +97,7 @@ const required = [
   "bin/webui/fixtures/pact.js",
   "bin/webui/fixtures/boundary.js",
   "bin/webui/fixtures/wait.js",
+  "bin/webui/fixtures/hookui.js",
   "bin/webui/fixtures/handoff.js",
   "bin/webui/fixtures/maintenance.js",
   "bin/webui/fixtures/challenge.js",
@@ -127,6 +130,7 @@ const required = [
   "bin/webui/i18n/en/pact.json",
   "bin/webui/i18n/en/boundary.json",
   "bin/webui/i18n/en/wait.json",
+  "bin/webui/i18n/en/hookui.json",
   "bin/webui/i18n/en/handoff.json",
   "bin/webui/i18n/en/challenge.json",
   "bin/webui/i18n/en/docs.json",
@@ -150,6 +154,7 @@ const required = [
   "bin/webui/i18n/id/pact.json",
   "bin/webui/i18n/id/boundary.json",
   "bin/webui/i18n/id/wait.json",
+  "bin/webui/i18n/id/hookui.json",
   "bin/webui/i18n/id/handoff.json",
   "bin/webui/i18n/id/challenge.json",
   "bin/webui/i18n/id/docs.json",
@@ -451,6 +456,16 @@ const required = [
   "templates/hooks/README.md",
   "templates/hooks/orc-effort-guard.js",
   "templates/hooks/orc-statusline.js",
+  // v1.3.0 — THE RENDER ENGINE, and it is required by BOTH halves: the hook
+  // requires it as a sibling out of .claude/hooks/, and bin/cli.js requires it
+  // out of templates/hooks/ for `orc statusline preview`. That is what makes
+  // the panel's preview and the bar's real output byte-identical BY
+  // CONSTRUCTION. A missing file here breaks the status line AND the panel.
+  "templates/hooks/orc-statusline-render.js",
+  // v1.4.0 — the SECOND board, and the per-agent token record that rides with
+  // it. Wired even with the board off, because the measurement is handed over
+  // either way.
+  "templates/hooks/orc-subagent-line.js",
   "templates/hooks/orc-trace.js",
 ];
 

package/bin/webui/api.js

@@ -45,6 +45,14 @@ function clearCache() {
   cache.clear();
 }
 
+// v1.4.0 — the board a statusline request is about. A value this server does
+// not recognise is DROPPED rather than forwarded: the CLI would refuse it, and
+// a query string is user input like any other.
+function slBoard(q) {
+  const b = q && q.board ? String(q.board) : "";
+  return b === "subagent" ? ["--board", "subagent"] : [];
+}
+
 // ── running the CLI ─────────────────────────────────────────────────────────
 
 // Several commands use a NON-ZERO exit as a normal answer, not a failure:
@@ -243,6 +251,27 @@ const READS = {
   // a wait — a wait lives in a Claude Code session, and `orc ui` never runs a
   // lane. It configures the defaults, shows a wait, and cancels one.
   "/api/usage": () => ["usage", "check"],
+  // v1.3.0 — the CLI Hook Interface. THE PANEL DRAWS THE CATALOGUE AND DERIVES
+  // NONE OF IT: the groups, the renderers, their option sets and the rendered
+  // sample per renderer all come from `statusline components --json`, and a
+  // test greps the panel for component ids, renderer names, glyph-set names,
+  // ramp names, colour tokens and state words. It must name none of them.
+  //
+  // `preview` is the one that earns the panel its place: it renders through the
+  // SAME engine the hook does, so what you see is what the bar will print.
+  // v1.4.0 — TWO BOARDS through one set of routes. `--board` is passed
+  // through verbatim; the CLI owns which boards exist and which components
+  // each may hold, and the panel — as everywhere else — decides none of it.
+  "/api/statusline/components": (q) => ["statusline", "components", ...slBoard(q)],
+  "/api/statusline/show": (q) => ["statusline", "show", ...slBoard(q)],
+  "/api/statusline/presets": (q) => ["statusline", "presets", ...slBoard(q)],
+  "/api/statusline/preview": (q) => {
+    const argv = ["statusline", "preview", ...slBoard(q)];
+    if (q.width) argv.push("--width", String(q.width));
+    if (q.state) argv.push("--state", String(q.state));
+    return argv;
+  },
+  "/api/statusline/explain": (q) => ["statusline", "explain", String(q.at || "1:1"), ...slBoard(q)],
   "/api/wait/lanes": () => ["wait", "lanes"],
   "/api/wait/status": (q) => (q.slug ? ["wait", "status", String(q.slug)] : ["wait", "status"]),
   "/api/pact": () => ["pact", "status"],
@@ -421,6 +450,48 @@ const WRITES = {
   // already running. A BLOCK cannot be created here on purpose: it needs a
   // reason typed in the moment, and a reason typed into a settings page days
   // later is not the record that makes the risk demonstrably the user's.
+  // v1.3.0 — the layout's writers. Every one shells the same validator the CLI
+  // uses, so an illegal placement is refused BY NAME here exactly as it is
+  // there. The board makes the illegal drop impossible; this is the guarantee.
+  "/api/statusline/set": (b) => {
+    const argv = ["statusline", "set", String(b.line), String(b.pos)];
+    if (b.type) argv.push(String(b.type));
+    for (const [k, f] of [
+      ["render", "--render"], ["label", "--label"], ["color", "--color"],
+      ["label_color", "--label-color"], ["value_color", "--value-color"],
+      ["bg", "--bg"], ["ramp", "--ramp"], ["glyphs", "--glyphs"],
+      ["format", "--format"], ["case", "--case"], ["truncate", "--truncate"],
+      ["compact", "--compact"], ["prefix", "--prefix"], ["suffix", "--suffix"],
+      ["emphasis", "--emphasis"], ["hide_when", "--hide-when"],
+      ["width", "--width"], ["precision", "--precision"],
+      ["min_width", "--min-width"], ["min_cols", "--min-cols"],
+      ["max_cols", "--max-cols"], ["priority", "--priority"],
+    ]) {
+      if (b[k] !== undefined && b[k] !== null && b[k] !== "") argv.push(f, String(b[k]));
+    }
+    if (b.draw_empty) argv.push("--draw-empty");
+    return argv.concat(slBoard(b));
+  },
+  "/api/statusline/move": (b) => ["statusline", "move", String(b.from), String(b.to), ...slBoard(b)],
+  "/api/statusline/remove": (b) => ["statusline", "remove", String(b.at), ...slBoard(b)],
+  "/api/statusline/line": (b) => {
+    const argv = ["statusline", "line", String(b.line)];
+    if (b.separator !== undefined) argv.push("--separator", String(b.separator));
+    if (b.theme) argv.push("--theme", String(b.theme));
+    if (b.max_width !== undefined) argv.push("--max-width", String(b.max_width));
+    return argv.concat(slBoard(b));
+  },
+  // A preset REPLACES the layout, so the panel always confirms it and names
+  // the loss — the `orc diy init --force` rule.
+  "/api/statusline/apply": (b) => ["statusline", "apply", String(b.name), ...slBoard(b)],
+  // v1.3.0 W5. `group` wraps 2-4 as one object, `expand` is its inverse and is
+  // also how a composite becomes editable, `clone` is for two `config` chips on
+  // different keys — a normal thing to want.
+  "/api/statusline/group": (b) => ["statusline", "group", ...(b.refs || []).map(String), ...slBoard(b)],
+  "/api/statusline/expand": (b) => ["statusline", "expand", String(b.at), ...slBoard(b)],
+  "/api/statusline/clone": (b) => ["statusline", "clone", String(b.at), ...slBoard(b)],
+  "/api/statusline/reset": (b) => ["statusline", "reset", ...slBoard(b)],
+  "/api/statusline/compile": (b) => ["statusline", "compile", ...slBoard(b)],
   "/api/wait/unblock": (b) => (b.slug ? ["wait", "unblock", String(b.slug)] : ["wait", "unblock"]),
   "/api/wait/cancel": (b) => (b.slug ? ["wait", "cancel", String(b.slug)] : ["wait", "cancel"]),
   "/api/wiki/sync": () => ["wiki", "sync"],