@crouton-kit/crouter 0.3.42 → 0.3.44

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

@@ -0,0 +1,166 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+
+const exec = promisify(execFile);
+const CRTR = "crtr";
+
+// ---------------------------------------------------------------------------
+// memory-slash-commands: any memory doc frontmatter-flagged `slash: true`
+// becomes an invocable slash command (`/<name>`). This mirrors Hermes Agent's
+// "every skill is automatically a slash command" — /research-alpha injects
+// the doc body (plus the user's free-text args) as a normal turn instead of
+// requiring a separate skill-invocation mechanism.
+//
+// Discovery shells out to `crtr memory list --json`, which already resolves
+// the substrate's scope precedence (project stack > profile > user >
+// builtin) — this file does not walk memory/ directories or reimplement scope
+// resolution. `list`'s JSON items are already scope-precedence sorted (see
+// `scopeRank` in crouter's memory/shared.ts), so first-occurrence-wins per doc
+// name reproduces the resolver's identity precedence for free.
+// ---------------------------------------------------------------------------
+
+const FRONTMATTER_RE = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n?/;
+
+interface MemoryListItem {
+  name: string;
+  path: string;
+  is_dir: boolean;
+}
+
+export interface SlashDoc {
+  /** Path-derived doc name, e.g. "research-alpha" or "taste/foo" — what
+   *  `crtr memory read` resolves. */
+  name: string;
+  /** `name` with `/` -> `:` — the registered command name (a flat name is
+   *  unchanged). */
+  commandName: string;
+}
+
+async function defaultListMemoryDocs(): Promise<MemoryListItem[]> {
+  const { stdout } = await exec(CRTR, ["memory", "list", "--json"], { maxBuffer: 8 * 1024 * 1024 });
+  const parsed = JSON.parse(stdout) as { items: MemoryListItem[] };
+  return parsed.items;
+}
+
+async function defaultReadMemoryDoc(name: string): Promise<string> {
+  const { stdout } = await exec(CRTR, ["memory", "read", name, "--json"], { maxBuffer: 8 * 1024 * 1024 });
+  const parsed = JSON.parse(stdout) as { content: string };
+  return parsed.content;
+}
+
+let listMemoryDocsImpl = defaultListMemoryDocs;
+let readMemoryDocImpl = defaultReadMemoryDoc;
+
+/** Test seam: override doc discovery so tests never shell out to `crtr`. */
+export function __setListMemoryDocsForTest(fn?: typeof listMemoryDocsImpl): void {
+  listMemoryDocsImpl = fn ?? defaultListMemoryDocs;
+}
+
+/** Test seam: override doc-body reads so tests never shell out to `crtr`. */
+export function __setReadMemoryDocForTest(fn?: typeof readMemoryDocImpl): void {
+  readMemoryDocImpl = fn ?? defaultReadMemoryDoc;
+}
+
+/** Read a memory doc's raw frontmatter directly off its already-resolved
+ *  `path` (from `crtr memory list`) and report whether `slash` is `true`.
+ *  No directory walk, no scope reasoning — the path is already resolved. */
+function isSlashFlagged(path: string): boolean {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return false;
+  }
+  const match = raw.match(FRONTMATTER_RE);
+  if (!match) return false;
+  let data: unknown;
+  try {
+    data = parseYaml(match[1]);
+  } catch {
+    return false;
+  }
+  if (data === null || typeof data !== "object" || Array.isArray(data)) return false;
+  return (data as Record<string, unknown>).slash === true;
+}
+
+/** `/`-joined path-derived doc name -> the registered slash-command name. */
+export function slashCommandName(docName: string): string {
+  return docName.split("/").join(":");
+}
+
+/** Every `slash: true` memory doc, scope-precedence-deduped by name (see
+ *  module header). Directory INDEX entries never register as commands. A doc
+ *  without `slash` (or `slash: false`) is silently excluded. */
+export async function discoverSlashDocs(): Promise<SlashDoc[]> {
+  let items: MemoryListItem[];
+  try {
+    items = await listMemoryDocsImpl();
+  } catch {
+    return [];
+  }
+  const seen = new Set<string>();
+  const out: SlashDoc[] = [];
+  for (const item of items) {
+    if (item.is_dir) continue;
+    if (seen.has(item.name)) continue;
+    seen.add(item.name);
+    if (isSlashFlagged(item.path)) {
+      out.push({ name: item.name, commandName: slashCommandName(item.name) });
+    }
+  }
+  return out;
+}
+
+/** Compose the invocation prompt from the freshly-read doc body plus the
+ *  user's raw invocation args, following Claude Code's `$ARGUMENTS`
+ *  convention. When the body contains `$ARGUMENTS`, every occurrence is
+ *  replaced with the trimmed args (empty string when none were given) and the
+ *  substituted body is injected AS-IS — the doc placed its own args, so no
+ *  extra header is added. Otherwise: a short invocation header naming the
+ *  command and the raw args (both the given-args and no-args cases are
+ *  load-bearing, per the Hermes /learn prompt pattern this mirrors), followed
+ *  by the full doc body as the instructions to follow. */
+export function composeSlashPrompt(commandName: string, rawArgs: string, body: string): string {
+  const args = rawArgs.trim();
+  if (body.includes("$ARGUMENTS")) {
+    return body.split("$ARGUMENTS").join(args);
+  }
+  const header =
+    args === ""
+      ? `You invoked /${commandName} with no arguments.`
+      : `You invoked /${commandName} with: ${args}`;
+  return `${header}\n\nFollow the instructions below exactly as written — every part, including the presence or absence of arguments above, is a load-bearing requirement.\n\n${body}`;
+}
+
+export default async function (pi: ExtensionAPI) {
+  const docs = await discoverSlashDocs();
+  for (const doc of docs) {
+    pi.registerCommand(doc.commandName, {
+      description: `/${doc.commandName} — memory doc slash command (${doc.name})`,
+      handler: async (args, ctx) => {
+        let body: string;
+        try {
+          body = await readMemoryDocImpl(doc.name);
+        } catch (err) {
+          ctx.ui.notify(
+            `/${doc.commandName}: failed to read memory doc "${doc.name}": ${err instanceof Error ? err.message : String(err)}`,
+            "error",
+          );
+          return;
+        }
+        const prompt = composeSlashPrompt(doc.commandName, args ?? "", body);
+        pi.sendMessage(
+          {
+            customType: "memory-slash-command",
+            content: prompt,
+            display: true,
+          },
+          { triggerTurn: true },
+        );
+      },
+    });
+  }
+}