@serranolabs.io/munchkins 0.1.1 → 0.1.3

package/{agents/refactor/prompts/refactor.md → skills/munchkins-refactor/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: munchkins:refactor
+description: Behavior-preserving refactor of a target via the munchkins refactor agent — runs in a fresh worktree, applies DRY/clarity changes inside the named scope, gates with lint/typecheck/scenario, then merges or opens a PR. Use when the user wants refactoring done via the deterministic agent rather than inline editing.
+---
+
 # refactor subagent
 
 You are the refactor subagent. The user prompt contains a description of what to refactor in this repository — a target (file, directory, module) and a smell or improvement goal.

package/src/cmux-launcher.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, test } from "bun:test";
+import { buildCmuxCommand, shouldDelegateToCmux } from "./cmux-launcher.js";
+
+const NORMAL_ARGV = ["bun", "/abs/index.ts", "bug-fix", "--user-message=./bug.md"];
+
+describe("shouldDelegateToCmux", () => {
+  test("returns false when hasCmux is false even with otherwise valid inputs", () => {
+    expect(
+      shouldDelegateToCmux({
+        argv: NORMAL_ARGV,
+        env: {},
+        hasCmux: false,
+      }),
+    ).toBe(false);
+  });
+
+  test("returns false when MUNCHKINS_NO_CMUX=1", () => {
+    expect(
+      shouldDelegateToCmux({
+        argv: NORMAL_ARGV,
+        env: { MUNCHKINS_NO_CMUX: "1" },
+        hasCmux: true,
+      }),
+    ).toBe(false);
+  });
+
+  test("returns false when --no-cmux is in argv", () => {
+    expect(
+      shouldDelegateToCmux({
+        argv: [...NORMAL_ARGV, "--no-cmux"],
+        env: {},
+        hasCmux: true,
+      }),
+    ).toBe(false);
+  });
+
+  test.each([
+    ["--help"],
+    ["-h"],
+    ["--version"],
+    ["-v"],
+    ["--dry-run"],
+  ])("returns false when %s is in argv", (flag) => {
+    expect(
+      shouldDelegateToCmux({
+        argv: ["bun", "/abs/index.ts", "bug-fix", flag],
+        env: {},
+        hasCmux: true,
+      }),
+    ).toBe(false);
+  });
+
+  test("returns false when argv[2] is missing", () => {
+    expect(
+      shouldDelegateToCmux({
+        argv: ["bun", "/abs/index.ts"],
+        env: {},
+        hasCmux: true,
+      }),
+    ).toBe(false);
+  });
+
+  test("returns false when argv[2] starts with '-'", () => {
+    expect(
+      shouldDelegateToCmux({
+        argv: ["bun", "/abs/index.ts", "--something"],
+        env: {},
+        hasCmux: true,
+      }),
+    ).toBe(false);
+  });
+
+  test.each([
+    ["daemon"],
+    ["resume"],
+    ["status"],
+    ["skills"],
+  ])("returns false when argv[2] is meta-subcommand %s", (sub) => {
+    expect(
+      shouldDelegateToCmux({
+        argv: ["bun", "/abs/index.ts", sub],
+        env: {},
+        hasCmux: true,
+      }),
+    ).toBe(false);
+  });
+
+  test("returns true for normal agent invocation with cmux installed and clean env", () => {
+    expect(
+      shouldDelegateToCmux({
+        argv: NORMAL_ARGV,
+        env: {},
+        hasCmux: true,
+      }),
+    ).toBe(true);
+  });
+});
+
+function getInnerCommand(command: string[]): string {
+  return command[command.indexOf("--command") + 1];
+}
+
+describe("buildCmuxCommand", () => {
+  test("formats workspace name as <agent>-<now>", () => {
+    const { workspaceName } = buildCmuxCommand({
+      argv: NORMAL_ARGV,
+      cwd: "/repo",
+      now: 1700000000000,
+    });
+    expect(workspaceName).toBe("bug-fix-1700000000000");
+  });
+
+  test("includes --cwd from input", () => {
+    const { command } = buildCmuxCommand({
+      argv: NORMAL_ARGV,
+      cwd: "/some/where",
+      now: 1,
+    });
+    const cwdIdx = command.indexOf("--cwd");
+    expect(cwdIdx).toBeGreaterThan(-1);
+    expect(command[cwdIdx + 1]).toBe("/some/where");
+  });
+
+  test("--command starts with MUNCHKINS_NO_CMUX=1, single-quotes every argv element, uses argv[1] absolute script path", () => {
+    const { command } = buildCmuxCommand({
+      argv: ["bun", "/abs/index.ts", "bug-fix", "--user-message=./bug.md"],
+      cwd: "/repo",
+      now: 42,
+    });
+    const inner = getInnerCommand(command);
+    expect(inner.startsWith("MUNCHKINS_NO_CMUX=1 ")).toBe(true);
+    expect(inner).toBe(
+      "MUNCHKINS_NO_CMUX=1 'bun' 'run' '/abs/index.ts' 'bug-fix' '--user-message=./bug.md'",
+    );
+  });
+
+  test("strips --no-cmux from inner command", () => {
+    const { command } = buildCmuxCommand({
+      argv: ["bun", "/abs/index.ts", "bug-fix", "--no-cmux", "--user-message=./bug.md"],
+      cwd: "/repo",
+      now: 1,
+    });
+    const inner = getInnerCommand(command);
+    expect(inner).not.toContain("--no-cmux");
+    expect(inner).toContain("'bug-fix'");
+    expect(inner).toContain("'--user-message=./bug.md'");
+  });
+
+  test("escapes literal single quotes using POSIX '\\'' wrap", () => {
+    const { command } = buildCmuxCommand({
+      argv: ["bun", "/abs/index.ts", "bug-fix", "--user-message=can't stop"],
+      cwd: "/repo",
+      now: 1,
+    });
+    const inner = getInnerCommand(command);
+    expect(inner).toContain("'--user-message=can'\\''t stop'");
+  });
+});

package/src/cmux-launcher.ts

@@ -0,0 +1,70 @@
+const NON_AGENT_SUBCOMMANDS: ReadonlySet<string> = new Set([
+  "daemon",
+  "resume",
+  "status",
+  "skills",
+]);
+
+const ARGV_SKIP_FLAGS: ReadonlySet<string> = new Set([
+  "--no-cmux",
+  "--help",
+  "-h",
+  "--version",
+  "-v",
+  "--dry-run",
+]);
+
+interface DelegateDecisionInput {
+  argv: readonly string[];
+  env: NodeJS.ProcessEnv;
+  hasCmux: boolean;
+}
+
+export function shouldDelegateToCmux(input: DelegateDecisionInput): boolean {
+  if (!input.hasCmux) return false;
+  if (input.env.MUNCHKINS_NO_CMUX === "1") return false;
+  for (const arg of input.argv) {
+    if (ARGV_SKIP_FLAGS.has(arg)) return false;
+  }
+  const sub = input.argv[2];
+  if (!sub) return false;
+  if (sub.startsWith("-")) return false;
+  if (NON_AGENT_SUBCOMMANDS.has(sub)) return false;
+  return true;
+}
+
+interface BuildCmuxCommandInput {
+  argv: readonly string[];
+  cwd: string;
+  now: number;
+}
+
+export interface CmuxCommand {
+  command: string[];
+  workspaceName: string;
+}
+
+export function buildCmuxCommand(input: BuildCmuxCommandInput): CmuxCommand {
+  const agentName = input.argv[2];
+  const workspaceName = `${agentName}-${input.now}`;
+  const innerArgs = input.argv.slice(2).filter((a) => a !== "--no-cmux");
+  const inner = ["bun", "run", input.argv[1], ...innerArgs];
+  const innerCommand = `MUNCHKINS_NO_CMUX=1 ${inner.map(shellEscape).join(" ")}`;
+  return {
+    command: [
+      "cmux",
+      "new-workspace",
+      "--name",
+      workspaceName,
+      "--cwd",
+      input.cwd,
+      "--command",
+      innerCommand,
+    ],
+    workspaceName,
+  };
+}
+
+function shellEscape(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/src/index.ts

@@ -1,21 +1,42 @@
+#!/usr/bin/env bun
 export * from "@serranolabs.io/munchkins-core";
 import "../agents/bugfix/bugfix-agent.js";
+import "../agents/director/director-agent.js";
 import "../agents/feat-small/feat-small-agent.js";
 import "../agents/refactor/refactor-agent.js";
+import { buildCmuxCommand, shouldDelegateToCmux } from "./cmux-launcher.js";
 
 if (import.meta.main) {
+  const hasCmux = Bun.which("cmux") !== null;
+  if (shouldDelegateToCmux({ argv: process.argv, env: process.env, hasCmux })) {
+    const { command, workspaceName } = buildCmuxCommand({
+      argv: process.argv,
+      cwd: process.cwd(),
+      now: Date.now(),
+    });
+    const agentName = process.argv[2];
+    process.stdout.write(`Launching ${agentName} in cmux workspace: ${workspaceName}\n`);
+    const proc = Bun.spawn(command, { stdout: "inherit", stderr: "inherit" });
+    process.exit(await proc.exited);
+  }
+
+  const argv = process.argv.filter((a) => a !== "--no-cmux");
   const { registry } = await import("@serranolabs.io/munchkins-core");
-  if (process.argv[2] === "daemon") {
+  if (argv[2] === "daemon") {
     const { runDaemon } = await import("@serranolabs.io/munchkins-core");
     await runDaemon();
-  } else if (process.argv[2] === "resume") {
+  } else if (argv[2] === "resume") {
     const { runResume } = await import("@serranolabs.io/munchkins-core");
-    const result = await runResume(process.argv.slice(3));
+    const result = await runResume(argv.slice(3));
+    process.exit(result.exitCode);
+  } else if (argv[2] === "status") {
+    const { runStatus } = await import("@serranolabs.io/munchkins-core");
+    const result = await runStatus(argv.slice(3));
     process.exit(result.exitCode);
-  } else if (process.argv[2] === "skills" && process.argv[3] === "install") {
+  } else if (argv[2] === "skills" && argv[3] === "install") {
     const { runSkillsInstall } = await import("./skills-install.js");
-    runSkillsInstall(process.argv.slice(4));
+    runSkillsInstall(argv.slice(4));
   } else {
-    await registry.cli().parseAsync(process.argv);
+    await registry.cli().parseAsync(argv);
   }
 }

package/src/skills-install.test.ts

@@ -0,0 +1,186 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { _resolveTarget, _runSkillsInstall } from "./skills-install.js";
+
+class ProcessExitError extends Error {
+  constructor(public code: number) {
+    super(`process.exit(${code})`);
+  }
+}
+
+let tmp: string;
+const stdout: string[] = [];
+const stderr: string[] = [];
+const originalLog = console.log;
+const originalError = console.error;
+const originalExit = process.exit;
+
+beforeEach(() => {
+  tmp = mkdtempSync(join(tmpdir(), "skills-install-test-"));
+  stdout.length = 0;
+  stderr.length = 0;
+  console.log = (...args: unknown[]) => {
+    stdout.push(args.map(String).join(" "));
+  };
+  console.error = (...args: unknown[]) => {
+    stderr.push(args.map(String).join(" "));
+  };
+  process.exit = ((code?: number): never => {
+    throw new ProcessExitError(code ?? 0);
+  }) as typeof process.exit;
+});
+
+afterEach(() => {
+  console.log = originalLog;
+  console.error = originalError;
+  process.exit = originalExit;
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+function writeSkill(root: string, pkg: string, slug: string, body = `# ${slug}`): string {
+  const skillDir = join(root, "node_modules", ...pkg.split("/"), "skills", slug);
+  mkdirSync(skillDir, { recursive: true });
+  const file = join(skillDir, "SKILL.md");
+  writeFileSync(file, body);
+  return file;
+}
+
+function targetDir(): string {
+  return join(tmp, ".claude", "skills");
+}
+
+function findLine(prefix: string): string {
+  return stdout.find((l) => l.startsWith(prefix)) ?? "";
+}
+
+describe("_runSkillsInstall — multi-package discovery", () => {
+  test("walks every node_modules package that ships a skills/ dir", () => {
+    writeSkill(tmp, "@scope/a", "foo");
+    writeSkill(tmp, "pkg-b", "bar");
+
+    _runSkillsInstall({ cwd: tmp, target: targetDir(), packageRoot: null });
+
+    expect(existsSync(join(targetDir(), "foo", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(targetDir(), "bar", "SKILL.md"))).toBe(true);
+
+    const installedLine = findLine("installed:");
+    expect(installedLine).toContain("foo");
+    expect(installedLine).toContain("bar");
+  });
+
+  test("skips existing target files (records as kept, not installed)", () => {
+    writeSkill(tmp, "@scope/a", "foo", "from-package");
+    mkdirSync(join(targetDir(), "foo"), { recursive: true });
+    writeFileSync(join(targetDir(), "foo", "SKILL.md"), "existing");
+
+    _runSkillsInstall({ cwd: tmp, target: targetDir(), packageRoot: null });
+
+    expect(readFileSync(join(targetDir(), "foo", "SKILL.md"), "utf8")).toBe("existing");
+    expect(findLine("installed:")).not.toContain("foo");
+    expect(findLine("kept")).toContain("foo");
+  });
+
+  test("never silently overwrites a consumer-edited file", () => {
+    writeSkill(tmp, "@scope/a", "foo", "shipped-version");
+    mkdirSync(join(targetDir(), "foo"), { recursive: true });
+    const userFile = join(targetDir(), "foo", "SKILL.md");
+    writeFileSync(userFile, "user-edit");
+    const before = readFileSync(userFile, "utf8");
+
+    _runSkillsInstall({ cwd: tmp, target: targetDir(), packageRoot: null });
+
+    expect(readFileSync(userFile, "utf8")).toBe(before);
+  });
+
+  test("warns about slug collisions before the copy phase, first wins", () => {
+    writeSkill(tmp, "@scope/a", "bar", "from-a");
+    writeSkill(tmp, "pkg-b", "bar", "from-b");
+
+    _runSkillsInstall({ cwd: tmp, target: targetDir(), packageRoot: null });
+
+    const warning = findLine("⚠ slug collision");
+    expect(warning).toContain("bar");
+    expect(warning).toContain("@scope/a");
+    expect(warning).toContain("pkg-b");
+    expect(warning).toContain("first wins");
+
+    const warningIdx = stdout.indexOf(warning);
+    const installedIdx = stdout.indexOf(findLine("installed:"));
+    expect(warningIdx).toBeLessThan(installedIdx);
+
+    expect(readFileSync(join(targetDir(), "bar", "SKILL.md"), "utf8")).toBe("from-a");
+  });
+
+  test("ignores a skills/ directory that contains no SKILL.md subdirs", () => {
+    mkdirSync(join(tmp, "node_modules", "noisy-pkg", "skills"), { recursive: true });
+    writeSkill(tmp, "@scope/a", "foo");
+
+    _runSkillsInstall({ cwd: tmp, target: targetDir(), packageRoot: null });
+
+    expect(existsSync(join(targetDir(), "foo", "SKILL.md"))).toBe(true);
+    expect(findLine("installed:")).toContain("foo");
+  });
+
+  test("exits 1 with a clear error when no skills exist anywhere", () => {
+    mkdirSync(join(tmp, "node_modules"), { recursive: true });
+
+    let caught: ProcessExitError | null = null;
+    try {
+      _runSkillsInstall({ cwd: tmp, target: targetDir(), packageRoot: null });
+    } catch (err) {
+      if (err instanceof ProcessExitError) caught = err;
+      else throw err;
+    }
+
+    expect(caught).not.toBeNull();
+    expect(caught?.code).toBe(1);
+    expect(stderr.join("\n")).toContain("no skills found in any installed package");
+  });
+
+  test("respects a custom target dir (--dest)", () => {
+    writeSkill(tmp, "@scope/a", "foo");
+    const customTarget = join(tmp, "custom-dest");
+
+    _runSkillsInstall({ cwd: tmp, target: customTarget, packageRoot: null });
+
+    expect(existsSync(join(customTarget, "foo", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(targetDir(), "foo", "SKILL.md"))).toBe(false);
+  });
+
+  test("source-repo mode discovers <packageRoot>/skills/", () => {
+    const fakePackageRoot = join(tmp, "fake-package");
+    mkdirSync(join(fakePackageRoot, "skills", "src-only"), { recursive: true });
+    writeFileSync(join(fakePackageRoot, "skills", "src-only", "SKILL.md"), "src-bundled");
+    mkdirSync(join(tmp, "node_modules"), { recursive: true });
+
+    _runSkillsInstall({ cwd: tmp, target: targetDir(), packageRoot: fakePackageRoot });
+
+    expect(existsSync(join(targetDir(), "src-only", "SKILL.md"))).toBe(true);
+    expect(findLine("installed:")).toContain("src-only");
+  });
+
+  test("summary always emits 'installed:' and omits 'kept' when zero kept", () => {
+    writeSkill(tmp, "@scope/a", "foo");
+
+    _runSkillsInstall({ cwd: tmp, target: targetDir(), packageRoot: null });
+
+    expect(stdout.some((l) => l.startsWith("installed:"))).toBe(true);
+    expect(stdout.some((l) => l.startsWith("kept"))).toBe(false);
+  });
+});
+
+describe("_resolveTarget", () => {
+  test("returns <cwd>/.claude/skills by default", () => {
+    expect(_resolveTarget([], "/repo")).toBe("/repo/.claude/skills");
+  });
+
+  test("honors --dest <dir>", () => {
+    expect(_resolveTarget(["--dest", "/elsewhere"], "/repo")).toBe("/elsewhere");
+  });
+
+  test("honors -d <dir>", () => {
+    expect(_resolveTarget(["-d", "/elsewhere"], "/repo")).toBe("/elsewhere");
+  });
+});