@crewhaus/slash-commands 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@crewhaus/slash-commands",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Markdown-templated slash commands with $ARGUMENTS substitution",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0",
+    "yaml": "^2.6.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/slash-commands"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/slash-commands#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,250 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type SlashCommand, expand, loadCommands, parseCommandFile } from "./index";
+
+function withTempCwd(
+  setup: (cwd: string) => void,
+  body: (cwd: string) => Promise<void> | void,
+): Promise<void> {
+  const cwd = mkdtempSync(join(tmpdir(), "slash-cwd-"));
+  try {
+    setup(cwd);
+    return Promise.resolve(body(cwd)).finally(() => {
+      rmSync(cwd, { recursive: true, force: true });
+    });
+  } catch (err) {
+    rmSync(cwd, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+function writeCommand(cwd: string, name: string, content: string): string {
+  const dir = join(cwd, ".crewhaus", "commands");
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, `${name}.md`);
+  writeFileSync(file, content);
+  return file;
+}
+
+describe("loadCommands", () => {
+  test("returns empty map when no directory", async () => {
+    await withTempCwd(
+      () => {},
+      async (cwd) => {
+        const cmds = await loadCommands({ cwd });
+        expect(cmds.size).toBe(0);
+      },
+    );
+  });
+
+  test("loads body-only files (no frontmatter)", async () => {
+    await withTempCwd(
+      (cwd) => {
+        writeCommand(cwd, "explain", "Explain $ARGUMENTS in two sentences.");
+      },
+      async (cwd) => {
+        const cmds = await loadCommands({ cwd });
+        expect(cmds.size).toBe(1);
+        const cmd = cmds.get("explain");
+        expect(cmd?.body).toBe("Explain $ARGUMENTS in two sentences.");
+        expect(cmd?.description).toBeUndefined();
+      },
+    );
+  });
+
+  test("parses optional frontmatter (description, argument-hint)", async () => {
+    await withTempCwd(
+      (cwd) => {
+        writeCommand(
+          cwd,
+          "review",
+          `---\ndescription: code review on a PR\nargument-hint: "<pr-number>"\n---\nReview PR $ARGUMENTS.`,
+        );
+      },
+      async (cwd) => {
+        const cmds = await loadCommands({ cwd });
+        const cmd = cmds.get("review");
+        expect(cmd?.description).toBe("code review on a PR");
+        expect(cmd?.argumentHint).toBe("<pr-number>");
+        expect(cmd?.body).toBe("Review PR $ARGUMENTS.");
+      },
+    );
+  });
+
+  test("supports camelCase alias `argumentHint`", async () => {
+    await withTempCwd(
+      (cwd) => {
+        writeCommand(cwd, "alias", `---\nargumentHint: "<x>"\n---\nbody`);
+      },
+      async (cwd) => {
+        const cmds = await loadCommands({ cwd });
+        expect(cmds.get("alias")?.argumentHint).toBe("<x>");
+      },
+    );
+  });
+
+  test("ignores non-md files and subdirectories", async () => {
+    await withTempCwd(
+      (cwd) => {
+        mkdirSync(join(cwd, ".crewhaus", "commands", "subdir"), { recursive: true });
+        writeFileSync(join(cwd, ".crewhaus", "commands", "notmd.txt"), "ignored");
+        writeCommand(cwd, "real", "body");
+      },
+      async (cwd) => {
+        const cmds = await loadCommands({ cwd });
+        expect([...cmds.keys()]).toEqual(["real"]);
+      },
+    );
+  });
+
+  test("treats unterminated frontmatter as plain body (defensive)", async () => {
+    await withTempCwd(
+      (cwd) => {
+        writeCommand(cwd, "rule", "---\nthis is not really frontmatter\nstill the body");
+      },
+      async (cwd) => {
+        const cmds = await loadCommands({ cwd });
+        const cmd = cmds.get("rule");
+        expect(cmd?.body.startsWith("---\n")).toBe(true);
+      },
+    );
+  });
+});
+
+describe("expand — non-slash and unknown", () => {
+  test("non-slash input passes through unchanged", () => {
+    const cmds = new Map<string, SlashCommand>([["x", { name: "x", body: "B", filePath: "/x" }]]);
+    const r = expand("hello world", cmds);
+    expect(r.handled).toBe(false);
+    expect(r.expanded).toBe("hello world");
+  });
+
+  test("unknown command name passes through", () => {
+    const cmds = new Map<string, SlashCommand>([["x", { name: "x", body: "B", filePath: "/x" }]]);
+    const r = expand("/missing some args", cmds);
+    expect(r.handled).toBe(false);
+    expect(r.expanded).toBe("/missing some args");
+  });
+
+  test("empty commands map → not handled", () => {
+    const r = expand("/anything", new Map());
+    expect(r.handled).toBe(false);
+  });
+});
+
+describe("expand — known command", () => {
+  const cmds = new Map<string, SlashCommand>([
+    [
+      "explain",
+      {
+        name: "explain",
+        body: "Explain $ARGUMENTS in two sentences.",
+        filePath: "/x",
+      },
+    ],
+  ]);
+
+  test("substitutes simple args", () => {
+    const r = expand("/explain quicksort", cmds);
+    expect(r.handled).toBe(true);
+    expect(r.expanded).toBe("Explain quicksort in two sentences.");
+    expect(r.arguments).toBe("quicksort");
+    expect(r.command?.name).toBe("explain");
+  });
+
+  test("empty args become empty string", () => {
+    const r = expand("/explain", cmds);
+    expect(r.handled).toBe(true);
+    expect(r.expanded).toBe("Explain  in two sentences.");
+    expect(r.arguments).toBe("");
+  });
+
+  test("multi-line args preserved", () => {
+    const r = expand("/explain a\nmulti\nline", cmds);
+    expect(r.expanded).toBe("Explain a\nmulti\nline in two sentences.");
+  });
+
+  test("leading whitespace before slash is allowed", () => {
+    const r = expand("   /explain trimmed", cmds);
+    expect(r.handled).toBe(true);
+    expect(r.expanded).toContain("trimmed");
+  });
+});
+
+describe("expand — $ARGUMENTS property test (T9)", () => {
+  // Generate random body fragments and args, assert the algebraic property:
+  //   expanded === body.split("$ARGUMENTS").join(args)
+  // Charset deliberately includes the placeholder, regex specials, $, \, \n.
+  const CHARS = "abc 123 \n\t  \\ $ARGUMENTS .*+?^${}()|[]{} 你好 emoji $$$ \" '";
+
+  function randomString(maxLen: number): string {
+    const len = Math.floor(Math.random() * maxLen);
+    let out = "";
+    for (let i = 0; i < len; i++) {
+      out += CHARS.charAt(Math.floor(Math.random() * CHARS.length));
+    }
+    return out;
+  }
+
+  function randomBody(): string {
+    // Drop in 0–4 placeholders interleaved with random text.
+    const placeholders = Math.floor(Math.random() * 5);
+    let out = randomString(20);
+    for (let i = 0; i < placeholders; i++) {
+      out += "$ARGUMENTS";
+      out += randomString(10);
+    }
+    return out;
+  }
+
+  test("substitution matches body.split($ARGUMENTS).join(extracted-args) for 200 random pairs", () => {
+    for (let i = 0; i < 200; i++) {
+      const body = randomBody();
+      const args = randomString(30);
+      const cmds = new Map<string, SlashCommand>([["t", { name: "t", body, filePath: "/x" }]]);
+      const result = expand(`/t ${args}`, cmds);
+      // Property is keyed on `result.arguments` (the canonical extraction)
+      // so we don't pre-suppose anything about how the separator between
+      // command name and args is parsed. The invariant under test is the
+      // substitution algebra: every literal `$ARGUMENTS` in the body is
+      // replaced with whatever extracted args was, and nothing else.
+      const expected = body.split("$ARGUMENTS").join(result.arguments ?? "");
+      expect(result.handled).toBe(true);
+      expect(result.expanded).toBe(expected);
+    }
+  });
+
+  test("args containing $ARGUMENTS are NOT recursively expanded", () => {
+    const cmds = new Map<string, SlashCommand>([
+      ["t", { name: "t", body: "before $ARGUMENTS after", filePath: "/x" }],
+    ]);
+    const result = expand("/t $ARGUMENTS-literal", cmds);
+    // Single non-recursive substitution: args land verbatim, $ARGUMENTS in
+    // the args is NOT re-substituted.
+    expect(result.expanded).toBe("before $ARGUMENTS-literal after");
+  });
+
+  test("regex specials in args are not interpreted", () => {
+    const cmds = new Map<string, SlashCommand>([
+      ["t", { name: "t", body: "[$ARGUMENTS]", filePath: "/x" }],
+    ]);
+    const result = expand("/t .*+?^${}()|[]\\", cmds);
+    expect(result.expanded).toBe("[.*+?^${}()|[]\\]");
+  });
+});
+
+describe("parseCommandFile direct", () => {
+  test("body-only", () => {
+    const r = parseCommandFile("plain body");
+    expect(r.body).toBe("plain body");
+    expect(r.description).toBeUndefined();
+  });
+
+  test("frontmatter then body", () => {
+    const r = parseCommandFile("---\ndescription: d\n---\nbody here");
+    expect(r.description).toBe("d");
+    expect(r.body).toBe("body here");
+  });
+});

package/src/index.ts

@@ -0,0 +1,191 @@
+/**
+ * Catalog R9 `slash-commands` — markdown-templated user-input shortcuts
+ * loaded from `<cwd>/.crewhaus/commands/<name>.md`.
+ *
+ * Each file is a markdown body with optional YAML frontmatter:
+ *
+ *     ---
+ *     description: explain X in two sentences
+ *     argument-hint: "<topic>"
+ *     ---
+ *     Explain $ARGUMENTS in two sentences.
+ *
+ * The basename (without `.md`) is the command name. When the user types
+ * `/<name> <args...>`, `expand()` replaces every literal `$ARGUMENTS` token
+ * with whatever followed the command name. Substitution is non-recursive
+ * and uses `String.prototype.replaceAll` (string form), so args containing
+ * `$ARGUMENTS`, regex specials, or newlines pass through untouched.
+ *
+ * `expand` returns `{ handled: false, expanded: input }` when:
+ *   - input does not start with `/`
+ *   - the command name is not in the loaded map
+ * Otherwise: `{ handled: true, expanded, command, arguments }`.
+ *
+ * Hook integration (`pre-slash`) fires in `runtime-core`, not here. This
+ * package is pure: filesystem read + string templating, no I/O elsewhere.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+import { parse as parseYaml } from "yaml";
+
+const COMMANDS_RELATIVE = ".crewhaus/commands";
+const COMMAND_PLACEHOLDER = "$ARGUMENTS";
+
+export type SlashCommand = {
+  readonly name: string;
+  readonly description?: string;
+  readonly argumentHint?: string;
+  readonly body: string;
+  readonly filePath: string;
+};
+
+export type LoadCommandsOptions = {
+  readonly cwd?: string;
+};
+
+export type ExpandResult = {
+  readonly handled: boolean;
+  readonly expanded: string;
+  readonly command?: SlashCommand;
+  readonly arguments?: string;
+};
+
+export class SlashCommandError extends CrewhausError {
+  override readonly name = "SlashCommandError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+/**
+ * Read every `.md` file directly under `<cwd>/.crewhaus/commands/`. Each
+ * file's basename (sans extension) becomes its key in the returned map.
+ * Subdirectories are not currently walked (v1 keeps the namespace flat).
+ */
+export async function loadCommands(
+  opts: LoadCommandsOptions = {},
+): Promise<Map<string, SlashCommand>> {
+  const cwd = opts.cwd ?? process.cwd();
+  const root = join(cwd, COMMANDS_RELATIVE);
+  if (!existsSync(root)) return new Map();
+  const out = new Map<string, SlashCommand>();
+  let entries: string[];
+  try {
+    entries = readdirSync(root);
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith(".md")) continue;
+    const file = join(root, entry);
+    let st: ReturnType<typeof statSync>;
+    try {
+      st = statSync(file);
+    } catch {
+      continue;
+    }
+    if (!st.isFile()) continue;
+    const name = basename(entry, ".md");
+    if (name.length === 0) continue;
+    let raw: string;
+    try {
+      raw = readFileSync(file, "utf8");
+    } catch (err) {
+      throw new SlashCommandError(`failed to read ${file}: ${(err as Error).message}`, err);
+    }
+    let parsed: ParsedCommand;
+    try {
+      parsed = parseCommandFile(raw);
+    } catch (err) {
+      throw new SlashCommandError(`failed to parse ${file}: ${(err as Error).message}`, err);
+    }
+    out.set(name, {
+      name,
+      body: parsed.body,
+      filePath: file,
+      ...(parsed.description !== undefined ? { description: parsed.description } : {}),
+      ...(parsed.argumentHint !== undefined ? { argumentHint: parsed.argumentHint } : {}),
+    });
+  }
+  return out;
+}
+
+type ParsedCommand = {
+  description?: string;
+  argumentHint?: string;
+  body: string;
+};
+
+/**
+ * Split a slash-command markdown file into its optional frontmatter and
+ * its body. Frontmatter is optional — files without a leading `---` are
+ * treated as all-body, and the description / argumentHint stay undefined.
+ *
+ * Exported for tests. Mirrors `parseSkillFile` from `skills-registry` but
+ * scoped to slash-command frontmatter shape.
+ */
+export function parseCommandFile(content: string): ParsedCommand {
+  const trimmed = content.replace(/^/, "");
+  if (!trimmed.startsWith("---")) {
+    return { body: trimmed };
+  }
+  const endIdx = findFrontmatterEnd(trimmed);
+  if (endIdx === -1) {
+    // No closing delimiter — treat as a plain body (don't throw; users may
+    // legitimately put a `---` horizontal rule at the top of a free-form
+    // command body without intending it as frontmatter).
+    return { body: trimmed };
+  }
+  const fmRaw = trimmed.slice(trimmed.indexOf("\n") + 1, endIdx).trimEnd();
+  const bodyStart = trimmed.indexOf("\n", endIdx + 3);
+  const body = bodyStart === -1 ? "" : trimmed.slice(bodyStart + 1);
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(fmRaw);
+  } catch {
+    return { body };
+  }
+  if (typeof parsed !== "object" || parsed === null) return { body };
+  const v = parsed as Record<string, unknown>;
+  const description = typeof v["description"] === "string" ? v["description"] : undefined;
+  const hintRaw = v["argument-hint"] ?? v["argumentHint"];
+  const argumentHint = typeof hintRaw === "string" ? hintRaw : undefined;
+  return {
+    body,
+    ...(description !== undefined ? { description } : {}),
+    ...(argumentHint !== undefined ? { argumentHint } : {}),
+  };
+}
+
+function findFrontmatterEnd(content: string): number {
+  let from = 3;
+  while (from < content.length) {
+    const idx = content.indexOf("\n---", from);
+    if (idx === -1) return -1;
+    const after = content.charAt(idx + 4);
+    if (after === "\n" || after === "" || after === "\r") return idx + 1;
+    from = idx + 4;
+  }
+  return -1;
+}
+
+/**
+ * Try to interpret `input` as a slash-command invocation. Returns
+ * `{ handled: false, expanded: input }` when there's no leading slash or
+ * the command name doesn't resolve. Substitution is `replaceAll` with the
+ * literal placeholder — no recursive interpretation of args.
+ */
+export function expand(input: string, commands: ReadonlyMap<string, SlashCommand>): ExpandResult {
+  if (commands.size === 0) return { handled: false, expanded: input };
+  const trimmed = input.trimStart();
+  if (!trimmed.startsWith("/")) return { handled: false, expanded: input };
+  const m = trimmed.match(/^\/(\S+)\s*([\s\S]*)$/);
+  if (m === null) return { handled: false, expanded: input };
+  const name = m[1] ?? "";
+  const args = m[2] ?? "";
+  const command = commands.get(name);
+  if (!command) return { handled: false, expanded: input };
+  const expanded = command.body.split(COMMAND_PLACEHOLDER).join(args);
+  return { handled: true, expanded, command, arguments: args };
+}