@north-light/cli 0.0.0-stage → 0.3.413

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

@@ -0,0 +1,440 @@
+import { envProfileId, isSandboxedNode } from '../../../shared/env.js';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import {
+  readFileSync,
+  readdirSync,
+  existsSync,
+  statSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  realpathSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, dirname, sep } from 'node:path';
+import { loadProfileManifest } from '../../../core/profiles/manifest.js';
+import { stripMarkdownComments } from '../../../core/runtime/command-expansion.js';
+import { expandShellBlocks, DEFAULT_SHELL_TIMEOUT_MS } from '../../../core/runtime/shell-expansion.js';
+import { piShellRunner } from './pi-shell-runner.js';
+
+// claude-plugin-commands: surfaces Claude Code commands AND skills as pi slash
+// commands, with Claude's `plugin:command` namespacing AND full runtime
+// behavior: `$1/$ARGUMENTS` argument substitution and `!`cmd` / ```! shell
+// execution.
+//
+// Sources scanned (commands from `commands/`, skills from `skills/`):
+//   - User:    ~/.claude/commands, ~/.claude/skills
+//   - Project: <ancestor>/.claude/commands|skills from cwd and every project in
+//              the selected crouter profile, with cwd taking precedence
+//   - Plugins: <installPath>/commands|skills for each installed plugin
+//
+// Names: commands and skills are namespaced by their path under the source
+// root, joined with `:` (e.g. `git-smart:commit`, `skill:headless`,
+// `skill:grove:configuration`). Skills all carry a leading `skill:`; plugin
+// entries are additionally prefixed with the plugin name.
+//
+// Two pieces:
+//   1. Shim files (for discovery/autocomplete). A flat dir of namespaced .md
+//      files, e.g. `git-smart:commit.md`, contributed via `resources_discover`.
+//      Frontmatter is sanitized so pi's strict YAML parser doesn't drop them.
+//   2. An `input` hook (the real execution). Pi's built-in template expansion
+//      substitutes $ARGUMENTS but never runs the `!`git ...`` context blocks
+//      Claude commands depend on. So we intercept `/<plugin>:<command> args`
+//      BEFORE expansion, read the ORIGINAL source file, substitute args, run
+//      the embedded shell, and `transform` the input to the resolved text.
+//      Shell-execution logic mirrors @juicesharp/rpiv-args.
+
+const HOME = homedir();
+const CLAUDE = join(HOME, ".claude");
+const USER_COMMANDS = join(CLAUDE, "commands");
+const USER_SKILLS = join(CLAUDE, "skills");
+const INSTALLED = join(CLAUDE, "plugins", "installed_plugins.json");
+const SHIM_DIR = join(HOME, ".pi", "agent", ".plugin-command-shims");
+const PI_PROMPTS = join(HOME, ".pi", "agent", "prompts");
+const PROJECT_PI_PROMPTS = ".pi/prompts";
+
+const EXCLUDE_NAMES = new Set(["claude.md", "agents.md", "readme.md", "index.md"]);
+
+type Kind = "command" | "skill";
+type IndexRecord = { file: string; kind: Kind; baseDir: string };
+
+// name -> original source. Built alongside the shims; consulted by the input
+// hook to find the file to expand+execute (and how to frame it).
+const commandIndex = new Map<string, IndexRecord>();
+
+type InstallRecord = { installPath?: string };
+type InstalledPlugins = { plugins?: Record<string, InstallRecord[]> };
+type Shim = { name: string; target: string; kind: Kind; baseDir: string };
+
+// discovery
+
+function collectCommands(root: string, prefix: string[], rel: string[], out: Shim[]): void {
+  if (!existsSync(root)) return;
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const lower = e.name.toLowerCase();
+    if (e.isFile() && lower.endsWith(".md") && !EXCLUDE_NAMES.has(lower)) {
+      const name = [...prefix, ...rel, e.name.slice(0, -3)].join(":");
+      out.push({ name, target: join(root, e.name), kind: "command", baseDir: root });
+    } else if (e.isDirectory() && !e.name.startsWith(".")) {
+      collectCommands(join(root, e.name), prefix, [...rel, e.name], out);
+    }
+  }
+}
+
+// Skills are directories containing SKILL.md. A directory WITHOUT a SKILL.md is
+// a grouping dir we recurse into; once SKILL.md is found we stop (its subdirs
+// are scripts/references/assets). Name mirrors collectCommands: path segments
+// from the skills root, joined with `:`.
+function collectSkills(root: string, prefix: string[], rel: string[], out: Shim[]): void {
+  if (!existsSync(root)) return;
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith(".")) continue;
+    const dir = join(root, e.name);
+    const skillFile = join(dir, "SKILL.md");
+    if (existsSync(skillFile)) {
+      const name = [...prefix, ...rel, e.name].join(":");
+      out.push({ name, target: skillFile, kind: "skill", baseDir: dir });
+    } else {
+      collectSkills(dir, prefix, [...rel, e.name], out);
+    }
+  }
+}
+
+// Ancestor `.claude` dirs from one project pointer up to (and including) its
+// git root, skipping the user-level ~/.claude (handled separately).
+function ancestorClaudeDirs(pointer: string): string[] {
+  const out: string[] = [];
+  let cur = resolve(pointer);
+  while (true) {
+    const claude = join(cur, ".claude");
+    if (resolve(claude) !== resolve(CLAUDE)) {
+      try {
+        if (existsSync(claude) && statSync(claude).isDirectory()) out.push(claude);
+      } catch {
+        /* ignore */
+      }
+    }
+    if (existsSync(join(cur, ".git"))) break; // stop at git root
+    const parent = dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return out;
+}
+
+function canonicalDir(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+/** Every project `.claude` directory visible to this engine. The cwd pointer
+ *  and its ancestors come first; selected-profile project pointers widen the
+ *  search without letting a duplicate profile entry displace the local copy. */
+export function projectClaudeDirs(cwd: string, profileProjectDirs: readonly string[]): string[] {
+  if (isSandboxedNode()) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const pointer of [cwd, ...profileProjectDirs]) {
+    for (const claude of ancestorClaudeDirs(pointer)) {
+      const key = canonicalDir(claude);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(claude);
+    }
+  }
+  return out;
+}
+
+function selectedProfileProjects(): string[] {
+  if (isSandboxedNode()) return [];
+  const profileId = envProfileId() ?? "";
+  if (profileId === "") return [];
+  try {
+    return loadProfileManifest(profileId).manifest.projects.map((project) => project.path);
+  } catch {
+    // A deleted or invalid selected profile must not hide cwd-local commands.
+    return [];
+  }
+}
+
+// Installed plugins as { name, installPath } pairs.
+function pluginDirs(): { name: string; installPath: string }[] {
+  if (!existsSync(INSTALLED)) return [];
+  let data: InstalledPlugins;
+  try {
+    data = JSON.parse(readFileSync(INSTALLED, "utf8")) as InstalledPlugins;
+  } catch {
+    return [];
+  }
+  const out: { name: string; installPath: string }[] = [];
+  for (const [key, records] of Object.entries(data.plugins ?? {})) {
+    const name = key.split("@")[0];
+    for (const rec of records ?? []) {
+      if (!rec.installPath) continue;
+      const installPath = resolve(rec.installPath);
+      if (isSandboxedNode() && !installPath.startsWith(resolve(HOME) + sep)) continue;
+      out.push({ name, installPath });
+    }
+  }
+  return out;
+}
+
+function dirIf(p: string): boolean {
+  try {
+    return existsSync(p) && statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// Quote frontmatter scalar values pi's strict YAML would misread (leading
+// flow/indicator chars), so the shim still loads into autocomplete.
+function sanitizeFrontmatter(content: string): string {
+  if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) return content;
+  const nl = content.indexOf("\n");
+  const rest = content.slice(nl + 1);
+  const end = rest.search(/^---\s*$/m);
+  if (end === -1) return content;
+  const block = rest.slice(0, end);
+  const after = rest.slice(end);
+  const RISKY = new Set(["[", "]", "{", "}", ",", "&", "*", "!", "@", "`", "%", "?"]);
+  const fixed = block
+    .split("\n")
+    .map((line) => {
+      const m = line.match(/^([A-Za-z0-9_-]+):[ \t]+(.+?)\s*$/);
+      if (!m) return line;
+      const [, key, value] = m;
+      if (value[0] === '"' || value[0] === "'" || !RISKY.has(value[0])) return line;
+      const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+      return `${key}: "${escaped}"`;
+    })
+    .join("\n");
+  return content.slice(0, nl + 1) + fixed + after;
+}
+
+// Prompt stems pi already loads natively from ~/.pi/agent/prompts. A shim of
+// the same name collides with the native prompt (pi keeps the prompt, skips the
+// shim, and warns), so we never emit one. This happens because crtr exports its
+// slash commands to BOTH ~/.claude/commands and ~/.pi/agent/prompts; without
+// this, we'd re-shim the claude copy back into pi on top of the native prompt.
+function nativePiPromptStems(): Set<string> {
+  const out = new Set<string>();
+  try {
+    for (const e of readdirSync(PI_PROMPTS, { withFileTypes: true })) {
+      if (e.isFile() && e.name.toLowerCase().endsWith(".md")) out.add(e.name.slice(0, -3));
+    }
+  } catch {
+    /* ignore */
+  }
+  return out;
+}
+
+function buildShims(cwd: string): string {
+  const shims: Shim[] = [];
+  const nativeStems = nativePiPromptStems();
+  const projectDirs = projectClaudeDirs(cwd, selectedProfileProjects());
+  const plugins = pluginDirs();
+
+  // Commands: user, project ancestors, then plugins.
+  collectCommands(USER_COMMANDS, [], [], shims);
+  for (const cd of projectDirs) collectCommands(join(cd, "commands"), [], [], shims);
+  for (const p of plugins) {
+    const cmds = join(p.installPath, "commands");
+    if (dirIf(cmds)) collectCommands(cmds, [p.name], [], shims);
+  }
+
+  // Skills: user, project ancestors, then plugins. All namespaced under
+  // `skill:` so they group separately from commands in autocomplete.
+  collectSkills(USER_SKILLS, ["skill"], [], shims);
+  for (const cd of projectDirs) collectSkills(join(cd, "skills"), ["skill"], [], shims);
+  for (const p of plugins) {
+    const sk = join(p.installPath, "skills");
+    if (dirIf(sk)) collectSkills(sk, ["skill", p.name], [], shims);
+  }
+
+  try {
+    rmSync(SHIM_DIR, { recursive: true, force: true });
+  } catch {
+    /* ignore */
+  }
+  mkdirSync(SHIM_DIR, { recursive: true });
+  commandIndex.clear();
+
+  const used = new Set<string>();
+  for (const { name, target, kind, baseDir } of shims) {
+    if (nativeStems.has(name)) continue; // pi serves this prompt natively — a shim would just collide
+    let linkName = name;
+    let n = 1;
+    while (used.has(linkName)) linkName = `${name}~${n++}`;
+    used.add(linkName);
+    commandIndex.set(linkName, { file: target, kind, baseDir });
+    try {
+      writeFileSync(join(SHIM_DIR, `${linkName}.md`), sanitizeFrontmatter(readFileSync(target, "utf8")));
+    } catch {
+      /* ignore */
+    }
+  }
+  return SHIM_DIR;
+}
+
+// argument substitution (mirrors pi's prompt-template engine)
+
+function parseCommandArgs(s: string): string[] {
+  const args: string[] = [];
+  let cur = "";
+  let q: string | null = null;
+  for (const ch of s) {
+    if (q) {
+      if (ch === q) q = null;
+      else cur += ch;
+    } else if (ch === '"' || ch === "'") q = ch;
+    else if (ch === " " || ch === "\t") {
+      if (cur) {
+        args.push(cur);
+        cur = "";
+      }
+    } else cur += ch;
+  }
+  if (cur) args.push(cur);
+  return args;
+}
+
+function substituteArgs(content: string, args: string[]): string {
+  const all = args.join(" ");
+  return content.replace(/\$\{(\d+):-([^}]*)\}|\$\{@:(\d+)(?::(\d+))?\}|\$(ARGUMENTS|@|\d+)/g, (_, defaultNum, defaultValue, sliceStart, sliceLength, simple) => {
+    if (defaultNum) return args[parseInt(defaultNum, 10) - 1] || defaultValue;
+    if (sliceStart) {
+      const start = Math.max(0, parseInt(sliceStart, 10) - 1);
+      return sliceLength ? args.slice(start, start + parseInt(sliceLength, 10)).join(" ") : args.slice(start).join(" ");
+    }
+    if (simple === "ARGUMENTS" || simple === "@") return all;
+    return args[parseInt(simple, 10) - 1] ?? "";
+  });
+}
+
+const TOKEN_REGEX = /\$(?:\{\d+:-[^}]*\}|\{@:\d+(?::\d+)?\}|\d+|ARGUMENTS|@)/;
+
+/** Pi loads user prompts before project prompts. Resolve only those native
+ * Markdown templates here; resource-contributed templates have their own input
+ * handler (such as the command shim path above). */
+function nativePromptBody(name: string, cwd: string): string | undefined {
+  if (name.includes("/") || name.includes("\\") || name.includes("\0")) return undefined;
+  for (const dir of isSandboxedNode() ? [PI_PROMPTS] : [PI_PROMPTS, join(cwd, PROJECT_PI_PROMPTS)]) {
+    try {
+      const raw = readFileSync(join(dir, `${name}.md`), "utf8");
+      return splitFrontmatter(raw).body;
+    } catch {
+      // A missing/unreadable prompt is Pi's normal fallthrough path.
+    }
+  }
+  return undefined;
+}
+
+// Split leading `---` frontmatter from body WITHOUT parsing YAML. Claude's
+// loose frontmatter (e.g. `argument-hint: [a] [b]`) makes pi's parseFrontmatter
+// and stripFrontmatter both throw, so we delimiter-split ourselves.
+function splitFrontmatter(content: string): { fm: string; body: string } {
+  if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+    return { fm: "", body: content };
+  }
+  const nl = content.indexOf("\n");
+  const rest = content.slice(nl + 1);
+  const end = rest.search(/^---\s*$/m);
+  if (end === -1) return { fm: "", body: content };
+  const fm = rest.slice(0, end);
+  const afterIdx = rest.indexOf("\n", end);
+  const body = afterIdx === -1 ? "" : rest.slice(afterIdx + 1);
+  return { fm, body };
+}
+
+function shellTimeoutMs(fm: string): number {
+  const m = fm.match(/^shell-timeout:[ \t]*([0-9]+(?:\.[0-9]+)?)\s*$/m);
+  if (!m) return DEFAULT_SHELL_TIMEOUT_MS;
+  const v = parseFloat(m[1]);
+  if (!Number.isFinite(v) || v < 0) return DEFAULT_SHELL_TIMEOUT_MS;
+  return v === 0 ? 0 : v * 1000;
+}
+
+// shell execution (mirrors @juicesharp/rpiv-args)
+//
+// The `!`cmd`` / ```! grammar and substitution order are shared with every
+// other surface that expands a Markdown body (`core/runtime/shell-expansion`);
+// the pi-engine execution strategy is shared through `pi-shell-runner`.
+
+async function executeShell(body: string, pi: ExtensionAPI, cwd: string, timeoutMs: number): Promise<string> {
+  return expandShellBlocks(body, piShellRunner(pi, cwd, timeoutMs));
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("resources_discover", async (event: { cwd?: string }) => {
+    const dir = buildShims(event?.cwd ?? process.cwd());
+    return { promptPaths: [dir] };
+  });
+
+  pi.on("input", async (event: any, ctx: any) => {
+    if (event.source === "extension") return { action: "continue" };
+    const text: string = event.text ?? "";
+    if (!text.startsWith("/")) return { action: "continue" };
+
+    const sp = text.indexOf(" ");
+    const name = sp === -1 ? text.slice(1) : text.slice(1, sp);
+    const argsString = sp === -1 ? "" : text.slice(sp + 1).trim();
+
+    const rec = commandIndex.get(name);
+    if (!rec) return { action: "continue" }; // not one of ours — let pi handle it
+
+    let raw: string;
+    try {
+      raw = readFileSync(rec.file, "utf8");
+    } catch {
+      return { action: "continue" };
+    }
+
+    const { fm, body: rawBody } = splitFrontmatter(raw);
+    const body = stripMarkdownComments(rawBody).trim();
+    const hadTokens = TOKEN_REGEX.test(body);
+
+    let processed = hadTokens ? substituteArgs(body, parseCommandArgs(argsString)) : body;
+    processed = await executeShell(processed, pi, ctx.cwd ?? process.cwd(), shellTimeoutMs(fm));
+    if (!hadTokens && argsString) processed = `${processed}\n\n${argsString}`;
+
+    // Skills lean on relative paths (scripts/, references/, assets/). Pin the
+    // base dir so the model can resolve them regardless of cwd.
+    if (rec.kind === "skill") {
+      processed = `[Skill: ${name}. Base directory: ${rec.baseDir}. Resolve relative paths (scripts, references, assets) referenced below against this directory.]\n\n${processed}`;
+    }
+
+    return { action: "transform", text: processed };
+  });
+
+  // Native pi prompt templates bypass the command index above. Intercept their
+  // source Markdown before Pi expands it so author-only HTML comments never
+  // become a user message. Extension commands execute before input hooks, and
+  // resource-contributed templates are already handled by their own hooks.
+  pi.on("input", async (event: any, ctx: any) => {
+    if (event.source === "extension") return { action: "continue" };
+    const match = (event.text ?? "").match(/^\/([^\s]+)(?:\s+([\s\S]*))?$/);
+    if (match === null || commandIndex.has(match[1]!)) return { action: "continue" };
+    const body = nativePromptBody(match[1]!, ctx.cwd ?? process.cwd());
+    if (body === undefined) return { action: "continue" };
+    return {
+      action: "transform",
+      text: substituteArgs(stripMarkdownComments(body).trim(), parseCommandArgs(match[2] ?? "")),
+    };
+  });
+}

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/crtr-commands/filters.json

@@ -0,0 +1,7 @@
+{
+  "_help": "Controls which crtr nodes become slash commands. Edit, then /reload. Matching is by colon-joined path; an entry matches that node AND all descendants. e.g. 'node' matches node, node:new, node:list. When 'include' is non-empty, EVERYTHING is excluded by default and only matching nodes are registered. 'exclude' always wins.",
+  "include": [
+    "node:new"
+  ],
+  "exclude": []
+}

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

@@ -0,0 +1,214 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFileSync, existsSync, realpathSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+import type { ChatCommandMetadata } from '../../../../core/runtime/command-surface.js';
+
+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 IN-PROCESS: crtr's own command tree is imported from its
+// selected runtime generation (`buildRoot()`) and walked in memory — the same
+// technique crtr-help-gate.ts uses. It spawns NOTHING at setup and writes
+// NOTHING to disk. (An earlier version crawled the surface with one
+// `crtr X -h` subprocess per node and cached the result next to its own
+// install dir; every build wiped that cache, so the next broker boot blocked
+// >30s on the crawl and the daemon's readiness reaper killed the node.)
+//
+// Fail-quiet: if crtr's dist can't be located/imported, no commands are
+// registered and the status line says so — it must never brick the agent.
+//
+// Registered handlers still shell out to the real `crtr` binary, but only
+// when the user invokes one — never on the boot path.
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FILTERS_PATH = join(HERE, "filters.json");
+const CRTR = "crtr";
+
+// 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 Filters = { include?: string[]; exclude?: string[] };
+
+/** The slice of crtr's command tree this extension reads. */
+type CrtrTreeNode = {
+  kind: "branch" | "leaf";
+  name: string;
+  description?: string;
+  tier?: string;
+  children?: CrtrTreeNode[];
+};
+type CrtrRoot = { kind: "root"; subtrees: CrtrTreeNode[] };
+
+type CommandNode = { path: string[]; description?: 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 + ":"));
+}
+
+export 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;
+}
+
+// Locate + import crtr's real command tree (mirrors crtr-help-gate.ts).
+
+async function resolveCrtrDist(): Promise<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); // stable <package>/bin/crtr shim
+      const selector = (await import(pathToFileURL(join(dirname(real), "runtime-selector.mjs")).href)) as {
+        tryResolveRuntime: (entryName: string) => { ok: true; runtime: { entryPath: string } } | { ok: false; error: string };
+      };
+      const result = selector.tryResolveRuntime("cli");
+      if (!result.ok) continue;
+      const dist = dirname(result.runtime.entryPath);
+      if (existsSync(join(dist, "build-root.js"))) return dist;
+    } catch {
+      /* keep scanning */
+    }
+  }
+  return null;
+}
+
+/** The core top-level commands an include filter is limited to, or null when
+ *  the filter can match anything (no include list, or an entry naming a
+ *  non-core command such as a provider or plugin). */
+export function coreSubtreesFor(filters: Filters, coreNames: readonly string[]): string[] | null {
+  const include = filters.include ?? [];
+  if (include.length === 0) return null;
+  const tops = [...new Set(include.map((entry) => entry.split(":")[0]!))];
+  return tops.every((top) => coreNames.includes(top)) ? tops : null;
+}
+
+async function loadCrtrRoot(filters: Filters): Promise<CrtrRoot | null> {
+  const dist = await resolveCrtrDist();
+  if (!dist) return null;
+  try {
+    const brMod = (await import(pathToFileURL(join(dist, "build-root.js")).href)) as {
+      buildRoot: () => Promise<CrtrRoot>;
+      resolveCoreRoot?: (first: string) => Promise<CrtrRoot | null>;
+      SUBTREE_NAMES?: readonly string[];
+    };
+    if (typeof brMod.buildRoot !== "function") return null;
+    // The full tree includes every granted provider's catalog, which a
+    // sandboxed broker fetches from the daemon (megabytes for Integrations).
+    // When the include filter names only core commands, load just those
+    // subtrees: the same nodes, without that fetch on the boot path.
+    const core = brMod.SUBTREE_NAMES && typeof brMod.resolveCoreRoot === "function" ? coreSubtreesFor(filters, brMod.SUBTREE_NAMES) : null;
+    if (core !== null) {
+      const roots = await Promise.all(core.map((name) => brMod.resolveCoreRoot!(name)));
+      return { kind: "root", subtrees: roots.flatMap((root) => root?.subtrees ?? []) };
+    }
+    const root = await brMod.buildRoot();
+    return Array.isArray(root?.subtrees) ? root : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Every addressable command path in the tree, depth-first. Hidden-tier and
+ *  `_`-prefixed nodes are internal and stay out of the slash surface. */
+export function enumerateCommands(root: CrtrRoot): CommandNode[] {
+  const out: CommandNode[] = [];
+  const visit = (node: CrtrTreeNode, prefix: string[]): void => {
+    if (node.tier === "hidden" || node.name.startsWith("_")) return;
+    const path = [...prefix, node.name];
+    out.push({ path, description: node.description });
+    if (node.kind === "branch") for (const child of node.children ?? []) visit(child, path);
+  };
+  for (const subtree of root.subtrees) visit(subtree, []);
+  return out;
+}
+
+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}`;
+  }
+}
+
+export default async function (pi: ExtensionAPI) {
+  const filters = loadFilters();
+  const root = await loadCrtrRoot(filters);
+
+  const register = (node: CommandNode) => {
+    const { path } = node;
+    const name = path.join(":"); // e.g. ["node","new"] -> "node:new"
+    const invocation = `Run \`crtr ${path.join(" ")} -h\` (pass args to run the real command)`;
+    pi.registerCommand(name, {
+      description: node.description ? `${node.description} — ${invocation}` : invocation,
+      // Chat-capable: the handler's outcome is the command's output placed into
+      // the conversation as a displayed message. The transient status line is
+      // decoration a surface without one simply does not show.
+      gateway: true as const,
+      argumentHint: "[args]",
+      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 },
+        );
+      },
+    } as Parameters<ExtensionAPI["registerCommand"]>[1] & ChatCommandMetadata);
+  };
+
+  let count = 0;
+  for (const node of root ? enumerateCommands(root) : []) {
+    if (!isAllowed(node.path.join(":"), filters)) continue;
+    register(node);
+    count++;
+  }
+
+  let warned = false;
+  pi.on("session_start", async (_e, ctx) => {
+    if (!root) {
+      if (!warned) {
+        ctx.ui.notify("crtr-commands: crtr dist not found — no crtr slash commands registered.", "warning");
+        warned = true;
+      }
+      ctx.ui.setStatus("crtr-commands", "crtr-commands off");
+      return;
+    }
+    ctx.ui.setStatus("crtr-commands", `${count} crtr commands`);
+  });
+}