@crouton-kit/crouter 0.3.33 → 0.3.35

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/crtr-commands/index.ts

@@ -0,0 +1,174 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const exec = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// crtr-commands: auto-generates a slash command for every node in the crtr
+// CLI tree. `/node:new` runs `crtr node new -h`; `/node:list`
+// runs `crtr node list -h`, and so on.
+//
+// Discovery is help-only (parses `-h` output), so walking the tree never
+// executes a real crtr command. The tree is cached to tree-cache.json next
+// to this file; rebuild it with `/crtr-refresh`.
+// ---------------------------------------------------------------------------
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CACHE_PATH = join(HERE, "tree-cache.json");
+const FILTERS_PATH = join(HERE, "filters.json");
+const CRTR = "crtr";
+const MAX_DEPTH = 6;
+
+// When true, injecting the output triggers an immediate agent response.
+// When false (default), the output is loaded into context and the agent
+// responds on your next message — closer to a prompt-template that primes
+// context without forcing a turn.
+const TRIGGER_TURN = false;
+
+type Cache = { version: number; builtAt: number; nodes: string[][] };
+type Filters = { include?: string[]; exclude?: string[] };
+
+function loadFilters(): Filters {
+  if (!existsSync(FILTERS_PATH)) return {};
+  try {
+    const f = JSON.parse(readFileSync(FILTERS_PATH, "utf8")) as Filters;
+    return { include: f.include ?? [], exclude: f.exclude ?? [] };
+  } catch {
+    return {};
+  }
+}
+
+// An entry matches a node when it equals the node's colon-path OR is an
+// ancestor prefix of it (entry "node" matches "node", "node:new", ...).
+function matchesAny(name: string, entries: string[]): boolean {
+  return entries.some((e) => name === e || name.startsWith(e + ":"));
+}
+
+function isAllowed(name: string, filters: Filters): boolean {
+  const include = filters.include ?? [];
+  const exclude = filters.exclude ?? [];
+  if (include.length > 0 && !matchesAny(name, include)) return false;
+  if (exclude.length > 0 && matchesAny(name, exclude)) return false;
+  return true;
+}
+
+async function runCrtr(args: string[]): Promise<string> {
+  try {
+    const { stdout } = await exec(CRTR, args, { maxBuffer: 8 * 1024 * 1024 });
+    return stdout;
+  } catch (err: any) {
+    // crtr exits non-zero on errors but still prints to stdout.
+    return (err?.stdout as string) ?? `crtr ${args.join(" ")} failed: ${err?.message ?? err}`;
+  }
+}
+
+// Parse child command names from a node's `-h` output (help-only, no execution).
+function parseChildren(path: string[], helpText: string): string[] {
+  if (path.length === 0) {
+    // Root uses <command name="X"> tags.
+    return [...helpText.matchAll(/<command name="([^"]+)">/g)].map((m) => m[1]);
+  }
+  // Sub-nodes use a "Branches" block of indented rows.
+  const kids: string[] = [];
+  let inBranches = false;
+  for (const line of helpText.split("\n")) {
+    if (line.trim() === "Branches") {
+      inBranches = true;
+      continue;
+    }
+    if (inBranches) {
+      if (line.trim() === "") break;
+      if (!/^\s/.test(line)) break;
+      kids.push(line.trim().split(/\s+/)[0]);
+    }
+  }
+  return kids;
+}
+
+async function walkTree(): Promise<string[][]> {
+  const nodes: string[][] = [];
+  async function walk(path: string[], depth: number): Promise<void> {
+    if (path.length > 0) nodes.push(path);
+    if (depth > MAX_DEPTH) return;
+    const help = await runCrtr([...path, "-h"]);
+    for (const child of parseChildren(path, help)) {
+      if (child.startsWith("_")) continue; // skip internal commands
+      await walk([...path, child], depth + 1);
+    }
+  }
+  await walk([], 0);
+  return nodes;
+}
+
+function loadCache(): Cache | null {
+  if (!existsSync(CACHE_PATH)) return null;
+  try {
+    return JSON.parse(readFileSync(CACHE_PATH, "utf8")) as Cache;
+  } catch {
+    return null;
+  }
+}
+
+function saveCache(nodes: string[][]): void {
+  const cache: Cache = { version: 1, builtAt: Date.now(), nodes };
+  writeFileSync(CACHE_PATH, JSON.stringify(cache, null, 2));
+}
+
+export default async function (pi: ExtensionAPI) {
+  let cache = loadCache();
+  if (!cache || !Array.isArray(cache.nodes) || cache.nodes.length === 0) {
+    const nodes = await walkTree();
+    saveCache(nodes);
+    cache = { version: 1, builtAt: Date.now(), nodes };
+  }
+
+  const register = (path: string[]) => {
+    const name = path.join(":"); // e.g. ["node","new"] -> "node:new"
+    pi.registerCommand(name, {
+      description: `Run \`crtr ${path.join(" ")} -h\` (pass args to run the real command)`,
+      handler: async (args, ctx) => {
+        const extra = (args ?? "").trim();
+        // No args -> show help. With args -> run the real command.
+        const argv = extra ? [...path, ...extra.split(/\s+/)] : [...path, "-h"];
+        ctx.ui.setStatus("crtr-commands", `running crtr ${argv.join(" ")}`);
+        const output = await runCrtr(argv);
+        ctx.ui.setStatus("crtr-commands", "");
+        pi.sendMessage(
+          {
+            customType: "crtr-output",
+            content: `$ crtr ${argv.join(" ")}\n\n${output.trimEnd()}`,
+            display: true,
+          },
+          { triggerTurn: TRIGGER_TURN },
+        );
+      },
+    });
+  };
+
+  const filters = loadFilters();
+  let count = 0;
+  for (const path of cache.nodes) {
+    if (!isAllowed(path.join(":"), filters)) continue;
+    register(path);
+    count++;
+  }
+
+  pi.on("session_start", async (_e, ctx) => {
+    ctx.ui.setStatus("crtr-commands", `${count} crtr commands`);
+  });
+
+  pi.registerCommand("crtr-refresh", {
+    description: "Rebuild the crtr command tree cache (then run /reload)",
+    handler: async (_args, ctx) => {
+      ctx.ui.setStatus("crtr-commands", "walking crtr tree...");
+      const nodes = await walkTree();
+      saveCache(nodes);
+      ctx.ui.setStatus("crtr-commands", "");
+      ctx.ui.notify(`crtr-commands: cached ${nodes.length} commands. Run /reload to apply.`, "info");
+    },
+  });
+}

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/crtr-help-gate.ts

@@ -0,0 +1,408 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, realpathSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const exec = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// crtr-help-gate: refuse to let the agent EXECUTE a crtr leaf command until it
+// has read that command's `-h` (its contract) in this pi session.
+//
+// Why: crtr's whole interface contract is "read the schema, then invoke". This
+// guard makes that mechanical — a crtr method (a leaf like `node new`,
+// `human ask`, `skill read`) cannot run until `crtr <that path> -h` (or
+// `--help`) has been seen this session. The first blind attempt is BLOCKED:
+// the agent gets the command's `-h` output inline plus the instruction to read
+// it. So the method is never executed without its contract already in context.
+//
+// Scope of the gate:
+//   - Only LEAF executions are gated. `crtr`, `crtr node`, `crtr node -h`,
+//     `crtr node new -h` are all help/listing surfaces (crtr just prints help
+//     and exits) — they are allowed and the leaf-targeted ones record a bless.
+//   - Resolution uses crtr's OWN argv walker (`walk` + `buildRoot` from its
+//     installed dist), so a path resolves exactly the way `crtr` itself would:
+//     `crtr skill read some-skill` resolves to the leaf `skill read`, NOT to a
+//     bogus `skill read some-skill`.
+//   - "Help seen" survives /reload, /resume, /fork because it is rebuilt from
+//     the session's own command history on session_start.
+//
+// Fail-open: if crtr's dist can't be located/imported, the gate disables
+// itself and never blocks anything (it must never brick the agent).
+// ---------------------------------------------------------------------------
+
+// When true (default): the block dumps the help AND blesses the path, so the
+//   immediate retry runs. Still guarantees the method never executes without
+//   its help already shown — just without an explicit extra `-h` call, and no
+//   risk of a re-block loop.
+// When false (strict): a blocked command is NOT auto-blessed. The agent must
+//   run `crtr <path> -h` itself (which the gate allows + blesses), then
+//   re-issue — the help text is then shown twice.
+const BLESS_ON_BLOCK = true;
+
+const HELP_MAX = 16_000; // cap embedded -h output
+
+type CrtrNode = { kind: "root" | "branch" | "leaf"; help?: { params?: unknown[] } };
+type WalkResult = { node: CrtrNode; path: string[]; remaining: string[] };
+type WalkFn = (root: unknown, tokens: string[]) => WalkResult;
+
+let crtrRoot: unknown = null;
+let walk: WalkFn | null = null;
+
+// ---------------------------------------------------------------------------
+// Locate + import crtr's real command tree and argv walker.
+// ---------------------------------------------------------------------------
+
+function resolveCrtrDist(): string | null {
+  const dirs = (process.env.PATH ?? "").split(":");
+  for (const d of dirs) {
+    if (!d) continue;
+    const cand = join(d, "crtr");
+    try {
+      if (!existsSync(cand)) continue;
+      const real = realpathSync(cand); // <checkout>/bin/crtr
+      const dist = join(dirname(real), "..", "dist");
+      if (existsSync(join(dist, "build-root.js")) && existsSync(join(dist, "core", "command.js"))) {
+        return dist;
+      }
+    } catch {
+      /* keep scanning */
+    }
+  }
+  return null;
+}
+
+async function loadCrtr(): Promise<boolean> {
+  const dist = resolveCrtrDist();
+  if (!dist) return false;
+  try {
+    const cmdMod = (await import(pathToFileURL(join(dist, "core", "command.js")).href)) as {
+      walk: WalkFn;
+    };
+    const brMod = (await import(pathToFileURL(join(dist, "build-root.js")).href)) as {
+      buildRoot: () => unknown;
+    };
+    if (typeof cmdMod.walk !== "function" || typeof brMod.buildRoot !== "function") return false;
+    walk = cmdMod.walk;
+    crtrRoot = brMod.buildRoot();
+    return crtrRoot != null;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shell-aware tokenizer + crtr-invocation finder.
+// ---------------------------------------------------------------------------
+
+type Tok = { value: string; op: boolean };
+
+// Opening half of a heredoc redirect: `<<DELIM`, `<<-DELIM`, `<< DELIM`,
+// `<<'DELIM'`, `<<"DELIM"`. Group 1 = the `-` (strip-leading-tabs) variant;
+// group 2 = the quote (if any); group 3 = the delimiter word. Deliberately does
+// NOT match `<<<` (here-string) or `x << 2` (no word delimiter).
+const HEREDOC_OPEN = /<<(-?)\s*(["']?)([A-Za-z_][A-Za-z0-9_]*)\2/g;
+
+/** Remove heredoc BODIES (the stdin data between `<<DELIM` and its closing
+ *  `DELIM` line) from a bash command before it is tokenized. The opening line
+ *  is kept — `crtr push final <<'EOF'` is still a real `push final` invocation
+ *  we want to gate — but the body lines, which are data fed on stdin and never
+ *  executed as commands, are dropped. Without this the tokenizer's newline=
+ *  command-separator rule would read every `crtr <leaf>` line inside a heredoc
+ *  body (a spawn prompt, a push report) as a real invocation and gate it. */
+export function stripHeredocs(cmd: string): string {
+  const lines = cmd.split("\n");
+  const out: string[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    out.push(line);
+    i++;
+    // Collect every heredoc opened on this line, in left-to-right order; their
+    // bodies stack and are consumed in that order.
+    const delims: { name: string; dash: boolean }[] = [];
+    HEREDOC_OPEN.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = HEREDOC_OPEN.exec(line)) !== null) {
+      delims.push({ name: m[3], dash: m[1] === "-" });
+    }
+    for (const d of delims) {
+      while (i < lines.length) {
+        const body = lines[i];
+        // `<<-` strips leading TABS from the body and the closing delimiter.
+        const probe = d.dash ? body.replace(/^\t+/, "") : body;
+        i++;
+        if (probe === d.name) break; // closing delimiter line — drop it, stop
+        // body line: dropped (not pushed to out)
+      }
+    }
+  }
+  return out.join("\n");
+}
+
+function tokenize(cmd: string): Tok[] {
+  const out: Tok[] = [];
+  let cur = "";
+  let hasContent = false;
+  let quote: string | null = null;
+  const pushCur = (): void => {
+    if (hasContent) out.push({ value: cur, op: false });
+    cur = "";
+    hasContent = false;
+  };
+  const pushOp = (v: string): void => {
+    pushCur();
+    out.push({ value: v, op: true });
+  };
+  for (let i = 0; i < cmd.length; i++) {
+    const c = cmd[i];
+    if (quote) {
+      if (c === quote) {
+        quote = null;
+      } else if (quote === '"' && c === "\\" && i + 1 < cmd.length) {
+        cur += cmd[++i];
+        hasContent = true;
+      } else {
+        cur += c;
+        hasContent = true;
+      }
+      continue;
+    }
+    if (c === "'" || c === '"') {
+      quote = c;
+      hasContent = true; // an empty "" is still a token
+      continue;
+    }
+    if (c === "\\" && i + 1 < cmd.length) {
+      cur += cmd[++i];
+      hasContent = true;
+      continue;
+    }
+    if (c === "&" && cmd[i + 1] === "&") {
+      pushOp("&&");
+      i++;
+      continue;
+    }
+    if (c === "|" && cmd[i + 1] === "|") {
+      pushOp("||");
+      i++;
+      continue;
+    }
+    if (c === "&" || c === "|" || c === ";" || c === "\n" || c === "(" || c === ")" || c === "`") {
+      pushOp(c);
+      continue;
+    }
+    if (c === " " || c === "\t" || c === "\r") {
+      pushCur();
+      continue;
+    }
+    cur += c;
+    hasContent = true;
+  }
+  pushCur();
+  return out;
+}
+
+function baseName(tok: string): string {
+  const parts = tok.split("/");
+  return parts[parts.length - 1] ?? tok;
+}
+
+const ENV_ASSIGN = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+/** Return the argv (tokens after the binary) of every `crtr`/`crouter`
+ *  invocation that sits in command position (start, after a shell operator, or
+ *  after env-assignments / a command substitution opener). */
+function findCrtrInvocations(tokens: Tok[]): string[][] {
+  const invs: string[][] = [];
+  let cmdPos = true;
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t.op) {
+      cmdPos = true; // every operator (incl. `(`, `)`, backtick) opens command position
+      continue;
+    }
+    if (!cmdPos) continue;
+    if (ENV_ASSIGN.test(t.value)) continue; // env prefix — stay in command position
+    const base = baseName(t.value);
+    if (base === "crtr" || base === "crouter") {
+      const args: string[] = [];
+      let j = i + 1;
+      for (; j < tokens.length && !tokens[j].op; j++) args.push(tokens[j].value);
+      invs.push(args);
+      i = j - 1;
+    }
+    cmdPos = false; // consumed a command word
+  }
+  return invs;
+}
+
+// ---------------------------------------------------------------------------
+// Gate logic.
+// ---------------------------------------------------------------------------
+
+type InvKind = { kind: "help-leaf" | "exec-leaf" | "other"; path: string };
+
+function evaluate(args: string[]): InvKind {
+  // `--json` is a crtr global stripped before its own walk; mirror that.
+  const toks = args.filter((a) => a !== "--json");
+  const { node, path, remaining } = walk!(crtrRoot, toks);
+  const help = remaining.some((t) => t === "-h" || t === "--help");
+  const key = path.join(" ");
+  if (node.kind === "leaf") {
+    // A leaf with no declared params has no input contract to read — there is
+    // nothing -h would teach beyond the name. Don't gate it.
+    const hasParams = (node.help?.params?.length ?? 0) > 0;
+    if (!hasParams) return { kind: "other", path: key };
+    return { kind: help ? "help-leaf" : "exec-leaf", path: key };
+  }
+  return { kind: "other", path: key };
+}
+
+/** Evaluate one bash command. Mutates `blessed` (commits help-read blessings)
+ *  ONLY when the command is allowed to run; a blocked command commits nothing
+ *  (it never executes, so its help never prints) — except the offending path
+ *  itself when BLESS_ON_BLOCK is set. */
+export function processCommand(command: string, blessed: Set<string>): { block: false } | { block: true; path: string } {
+  const invs = findCrtrInvocations(tokenize(stripHeredocs(command)));
+  const localBless: string[] = [];
+  for (const args of invs) {
+    const r = evaluate(args);
+    if (r.kind === "help-leaf") {
+      localBless.push(r.path);
+    } else if (r.kind === "exec-leaf") {
+      if (!blessed.has(r.path) && !localBless.includes(r.path)) {
+        if (BLESS_ON_BLOCK) blessed.add(r.path);
+        return { block: true, path: r.path };
+      }
+    }
+  }
+  for (const p of localBless) blessed.add(p);
+  return { block: false };
+}
+
+async function captureHelp(pathKey: string): Promise<string> {
+  const parts = pathKey.split(" ").filter(Boolean);
+  try {
+    const { stdout } = await exec("crtr", [...parts, "-h"], { maxBuffer: 8 * 1024 * 1024, timeout: 10_000 });
+    return stdout.trim();
+  } catch (err) {
+    const out = (err as { stdout?: string })?.stdout;
+    return (out ?? "").trim() || `(could not capture \`crtr ${parts.join(" ")} -h\`)`;
+  }
+}
+
+/** A blocked command is discarded IN FULL — pi executes NONE of it. When that
+ *  same command also built the body (a heredoc, or output redirected to a file),
+ *  a naive retry of ONLY the crtr call reads STALE/missing state. This is issue
+ *  #5: `cat > /tmp/f <<EOF…EOF; crtr push final "$(cat /tmp/f)"` was blocked, the
+ *  heredoc never wrote /tmp/f, and the retry `push final < /tmp/f` then published
+ *  a days-old report a DIFFERENT node had left in that shared path. So the block
+ *  reason MUST steer a re-issue of the WHOLE command and call out the discarded
+ *  write — never let the agent believe only the crtr call needs re-issuing. */
+function hasDiscardedWrite(command: string): boolean {
+  HEREDOC_OPEN.lastIndex = 0;
+  if (HEREDOC_OPEN.test(command)) return true;
+  // An output redirect to a FILE (`> f` / `>> f`), ignoring fd-dup forms
+  // (`>&2`, `2>&1`) that write no standalone file a retry would read back.
+  return /(?:^|\s)\d?>>?\s*(?![&])\S/.test(stripHeredocs(command));
+}
+
+export function buildReason(pathKey: string, help: string, command: string): string {
+  const cmd = `crtr ${pathKey}`;
+  const helpBlock = help.length > HELP_MAX ? `${help.slice(0, HELP_MAX)}\n…(truncated)` : help;
+  const discardLine = hasDiscardedWrite(command)
+    ? "Your ENTIRE bash command was discarded before anything ran — the heredoc/redirect (`<<`, `cat >`, `>`, `>>`) that built the body did NOT execute and its output was NEVER written. Re-issue the WHOLE command (the setup AND the crtr call together), not just the crtr call — any file or `$(…)` the crtr call reads is now stale or missing, so re-issuing the crtr call alone would publish the wrong data."
+    : "Your ENTIRE bash command was discarded — nothing in it ran. Re-issue the WHOLE command, not just the crtr call.";
+  const next = BLESS_ON_BLOCK
+    ? `The schema is shown below. ${discardLine} Re-issue the SAME command as-is, or adjust it based on the schema below — it runs on the second attempt.`
+    : `Run \`${cmd} -h\` yourself, read the schema, then re-issue your whole command. ${discardLine}`;
+  return [
+    `crtr help-gate: blocked \`${cmd}\`.`,
+    ``,
+    `You have not run \`${cmd} -h\` in this pi session. Policy: read a crtr command's contract before invoking it — never call a method blindly.`,
+    ``,
+    `Call a command with -h before trying to use it. ${next}`,
+    ``,
+    `Output of \`${cmd} -h\`:`,
+    ``,
+    helpBlock,
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Wiring.
+// ---------------------------------------------------------------------------
+
+export default async function (pi: ExtensionAPI) {
+  const ready = await loadCrtr();
+  const blessed = new Set<string>();
+  let warned = false;
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (!ready) {
+      if (!warned) {
+        ctx.ui.notify("crtr-help-gate: crtr dist not found — gate disabled.", "warn");
+        warned = true;
+      }
+      ctx.ui.setStatus("crtr-gate", "crtr-gate off");
+      return;
+    }
+    // Rebuild "help seen" from this session's own bash history so the gate
+    // survives /reload, /resume, /fork.
+    blessed.clear();
+    try {
+      for (const entry of ctx.sessionManager.getEntries() as Array<{ message?: unknown }>) {
+        const msg = entry.message as { role?: string; content?: unknown } | undefined;
+        if (!msg || msg.role !== "assistant" || !Array.isArray(msg.content)) continue;
+        for (const part of msg.content as Array<Record<string, unknown>>) {
+          if (part?.type === "toolCall" && part?.name === "bash") {
+            const command = (part.arguments as { command?: unknown } | undefined)?.command;
+            if (typeof command === "string") processCommand(command, blessed);
+          }
+        }
+      }
+    } catch {
+      /* best-effort replay */
+    }
+    ctx.ui.setStatus("crtr-gate", `crtr-gate: ${blessed.size} helped`);
+  });
+
+  pi.on("tool_call", async (event) => {
+    if (!ready) return;
+    if ((event.toolName ?? "").toLowerCase() !== "bash") return;
+    const command = (event.input as { command?: unknown } | undefined)?.command;
+    if (typeof command !== "string") return;
+    if (!command.includes("crtr") && !command.includes("crouter")) return;
+
+    const res = processCommand(command, blessed);
+    if (!res.block) return;
+    const help = await captureHelp(res.path);
+    return { block: true, reason: buildReason(res.path, help, command) };
+  });
+
+  // Visibility / escape hatch.
+  pi.registerCommand("crtr-gate", {
+    description: "crtr help-gate: show or reset which crtr commands have been -h'd this session",
+    handler: async (args, ctx) => {
+      const arg = (args ?? "").trim();
+      if (!ready) {
+        ctx.ui.notify("crtr-help-gate is disabled (crtr dist not found).", "warn");
+        return;
+      }
+      if (arg === "reset") {
+        blessed.clear();
+        ctx.ui.setStatus("crtr-gate", "crtr-gate: 0 helped");
+        ctx.ui.notify("crtr-help-gate: cleared. All crtr commands now require -h again.", "info");
+        return;
+      }
+      const list = [...blessed].sort();
+      ctx.ui.notify(
+        list.length ? `crtr commands -h'd this session:\n  ${list.join("\n  ")}` : "No crtr commands -h'd yet this session.",
+        "info",
+      );
+    },
+  });
+}