@lovrozagar/grunt 0.2.0 → 0.3.1

package/cli/init.test.ts

@@ -4,7 +4,9 @@ import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   init,
+  mergeClaudeSettings,
   mergeGitignore,
+  mergeGuardedMarkdown,
   mergePackageJson,
   samePath,
 } from "./init.mjs";
@@ -23,13 +25,17 @@ function tmp(prefix: string) {
 }
 
 const COPY_DIRS = [".rulesync", ".grok", ".codex", ".claude", ".agents"];
-const COPY_FILES = ["AGENTS.md", "CLAUDE.md", ".mcp.json"];
+const GUARDED_MD_FILES = ["AGENTS.md", "CLAUDE.md"];
 const PRODUCT_FILES = [
   "check-globals.mjs",
+  "emit-agent-shell-tools.mjs",
+  "emit-gemini.mjs",
   "emit-mcp-policy.mjs",
   "gate-fat-tools.mjs",
+  "hooks-union.mjs",
   "grunt-job.mjs",
   "parse-need.mjs",
+  "persist-handoff.mjs",
   "persist-plan.mjs",
   "purge-global-mcps.mjs",
   "scrub-spawn-prompt.mjs",
@@ -38,6 +44,46 @@ const PRODUCT_FILES = [
   "telemetry.mjs",
 ];
 
+const SRC_CLAUDE_SETTINGS = {
+  permissions: {
+    deny: ["Agent(Explore)", "Agent(orchestrator)", "mcp__*"],
+  },
+  hooks: {
+    PreToolUse: [
+      {
+        matcher: "spawn",
+        hooks: [
+          {
+            type: "command",
+            command: 'node "${ROOT}/scripts/scrub-spawn-prompt.mjs"',
+          },
+        ],
+      },
+      {
+        matcher: "fat",
+        hooks: [
+          {
+            type: "command",
+            command: 'node "${ROOT}/scripts/gate-fat-tools.mjs"',
+          },
+        ],
+      },
+    ],
+    Stop: [
+      {
+        hooks: [
+          {
+            type: "command",
+            command: 'node "${ROOT}/.grok/hooks/orchestrate-parent.js"',
+          },
+        ],
+      },
+    ],
+  },
+  enableAllProjectMcpServers: false,
+  enabledMcpjsonServers: [],
+};
+
 function stubPkgRoot(pkg: Record<string, unknown> = {
   name: "fixture-pkg",
   scripts: {
@@ -57,8 +103,12 @@ function stubPkgRoot(pkg: Record<string, unknown> = {
     fs.mkdirSync(path.join(root, d));
     fs.writeFileSync(path.join(root, d, "marker"), d);
   }
-  for (const f of COPY_FILES) {
-    fs.writeFileSync(path.join(root, f), f);
+  fs.writeFileSync(
+    path.join(root, ".claude", "settings.json"),
+    `${JSON.stringify(SRC_CLAUDE_SETTINGS, null, 2)}\n`,
+  );
+  for (const f of GUARDED_MD_FILES) {
+    fs.writeFileSync(path.join(root, f), `${f} content`);
   }
   fs.mkdirSync(path.join(root, "scripts"));
   for (const name of PRODUCT_FILES) {
@@ -132,6 +182,205 @@ describe("mergeGitignore", () => {
   });
 });
 
+describe("mergeGuardedMarkdown", () => {
+  it("self: dest === src is a no-op", () => {
+    const dir = tmp("md-self-");
+    fs.writeFileSync(path.join(dir, "CLAUDE.md"), "raw content");
+    mergeGuardedMarkdown(dir, dir, "CLAUDE.md");
+    expect(fs.readFileSync(path.join(dir, "CLAUDE.md"), "utf8")).toBe("raw content");
+  });
+
+  it("dest absent: writes package copy wrapped in sentinels", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("md-absent-");
+    mergeGuardedMarkdown(dest, pkgRoot, "CLAUDE.md");
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8")).toBe(
+      "<!-- grunt:begin -->\nCLAUDE.md content\n<!-- grunt:end -->\n",
+    );
+  });
+
+  it("dest exists without sentinel: writes CLAUDE.grunt.md, leaves original untouched", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("md-nosentinel-");
+    fs.writeFileSync(path.join(dest, "CLAUDE.md"), "hand-written consumer doc\n");
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    mergeGuardedMarkdown(dest, pkgRoot, "CLAUDE.md");
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8")).toBe(
+      "hand-written consumer doc\n",
+    );
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.grunt.md"), "utf8")).toBe("CLAUDE.md content");
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(logSpy.mock.calls[0][0]).toContain("CLAUDE.grunt.md");
+    logSpy.mockRestore();
+  });
+
+  it("dest exists with sentinel: replaces only the marked region", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("md-sentinel-");
+    fs.writeFileSync(
+      path.join(dest, "CLAUDE.md"),
+      "before\n<!-- grunt:begin -->\nold generated stuff\n<!-- grunt:end -->\nafter\n",
+    );
+    mergeGuardedMarkdown(dest, pkgRoot, "CLAUDE.md");
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8")).toBe(
+      "before\n<!-- grunt:begin -->\nCLAUDE.md content\n<!-- grunt:end -->\nafter\n",
+    );
+    expect(fs.existsSync(path.join(dest, "CLAUDE.grunt.md"))).toBe(false);
+  });
+});
+
+describe("mergeClaudeSettings", () => {
+  it("dest .claude/settings.json absent: plain copy", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-absent-");
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const out = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(out).toEqual(SRC_CLAUDE_SETTINGS);
+  });
+
+  it("malformed dest JSON throws with the path in the message", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-malformed-");
+    const destSettingsPath = path.join(destRoot, ".claude", "settings.json");
+    fs.mkdirSync(path.join(destRoot, ".claude"), { recursive: true });
+    fs.writeFileSync(destSettingsPath, "{ not valid json");
+    expect(() => mergeClaudeSettings(destRoot, pkgRoot)).toThrowError(
+      new RegExp(destSettingsPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")),
+    );
+  });
+
+  it("consumer hook group with only OWNED commands is replaced", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-owned-");
+    fs.mkdirSync(path.join(destRoot, ".claude"), { recursive: true });
+    fs.writeFileSync(
+      path.join(destRoot, ".claude", "settings.json"),
+      JSON.stringify({
+        permissions: { deny: ["Agent(Explore)"] },
+        hooks: {
+          PreToolUse: [
+            {
+              matcher: "spawn",
+              hooks: [
+                {
+                  type: "command",
+                  command: 'node "${OLD_ROOT}/scripts/scrub-spawn-prompt.mjs"',
+                },
+              ],
+            },
+          ],
+        },
+        enableAllProjectMcpServers: true,
+        enabledMcpjsonServers: ["stale"],
+      }),
+    );
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const out = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(out.hooks.PreToolUse).toEqual(SRC_CLAUDE_SETTINGS.hooks.PreToolUse);
+    expect(out.hooks.Stop).toEqual(SRC_CLAUDE_SETTINGS.hooks.Stop);
+    expect(out.enableAllProjectMcpServers).toBe(false);
+    expect(out.enabledMcpjsonServers).toEqual([]);
+  });
+
+  it("consumer hook group with only consumer commands survives", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-consumer-");
+    fs.mkdirSync(path.join(destRoot, ".claude"), { recursive: true });
+    const consumerGroup = {
+      matcher: "custom",
+      hooks: [{ type: "command", command: "node scripts/my-custom-hook.mjs" }],
+    };
+    fs.writeFileSync(
+      path.join(destRoot, ".claude", "settings.json"),
+      JSON.stringify({
+        permissions: { deny: ["Agent(Explore)"] },
+        hooks: { PreToolUse: [consumerGroup] },
+      }),
+    );
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const out = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(out.hooks.PreToolUse).toEqual([consumerGroup, ...SRC_CLAUDE_SETTINGS.hooks.PreToolUse]);
+    // event absent from dest entirely still gets appended
+    expect(out.hooks.Stop).toEqual(SRC_CLAUDE_SETTINGS.hooks.Stop);
+  });
+
+  it("MIXED group (one OWNED + one consumer command) survives intact", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-mixed-");
+    fs.mkdirSync(path.join(destRoot, ".claude"), { recursive: true });
+    const mixedGroup = {
+      matcher: "mixed",
+      hooks: [
+        { type: "command", command: 'node "${OLD_ROOT}/scripts/gate-fat-tools.mjs"' },
+        { type: "command", command: "node scripts/my-custom-hook.mjs" },
+      ],
+    };
+    fs.writeFileSync(
+      path.join(destRoot, ".claude", "settings.json"),
+      JSON.stringify({
+        permissions: { deny: [] },
+        hooks: { PreToolUse: [mixedGroup] },
+      }),
+    );
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const out = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(out.hooks.PreToolUse).toEqual([mixedGroup, ...SRC_CLAUDE_SETTINGS.hooks.PreToolUse]);
+  });
+
+  it("permissions.deny union does not grow on a second run (idempotency)", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-idempotent-");
+    fs.mkdirSync(path.join(destRoot, ".claude"), { recursive: true });
+    fs.writeFileSync(
+      path.join(destRoot, ".claude", "settings.json"),
+      JSON.stringify({
+        permissions: { deny: ["Agent(Explore)", "Agent(orchestrator)"] },
+        hooks: {},
+      }),
+    );
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const first = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const second = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(second.permissions.deny).toEqual(first.permissions.deny);
+    expect(second.permissions.deny).toEqual([
+      "Agent(Explore)",
+      "Agent(orchestrator)",
+      "mcp__*",
+    ]);
+    expect(second.permissions.allow).toEqual(first.permissions.allow);
+  });
+
+  it("unknown consumer top-level key preserved; missing hooks/permissions default to empty", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-unknown-key-");
+    fs.mkdirSync(path.join(destRoot, ".claude"), { recursive: true });
+    fs.writeFileSync(
+      path.join(destRoot, ".claude", "settings.json"),
+      JSON.stringify({ someCustomFlag: true }),
+    );
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const out = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(out.someCustomFlag).toBe(true);
+    expect(out.hooks).toEqual(SRC_CLAUDE_SETTINGS.hooks);
+    expect(out.permissions.deny).toEqual(SRC_CLAUDE_SETTINGS.permissions.deny);
+  });
+});
+
 describe("mergePackageJson", () => {
   it("creates {} dest and merges scripts skipping test, injects deps, sorts keys", () => {
     const pkgRoot = stubPkgRoot();
@@ -208,20 +457,37 @@ describe("init", () => {
     expect(fs.readFileSync(path.join(pkgRoot, "scripts", "telemetry.mjs"), "utf8")).toBe(
       "telemetry.mjs",
     );
+    // self-skip: markdown/settings stay exactly as-is, no sentinel wrap
+    expect(fs.readFileSync(path.join(pkgRoot, "CLAUDE.md"), "utf8")).toBe("CLAUDE.md content");
+    const settings = JSON.parse(
+      fs.readFileSync(path.join(pkgRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(settings).toEqual(SRC_CLAUDE_SETTINGS);
   });
 
-  it("non-self: file vs dir product scripts, then npm pipeline in order", () => {
+  it("non-self: file vs dir product scripts, guarded md + settings merge, then npm pipeline in order", () => {
     const pkgRoot = stubPkgRoot();
     const dest = tmp("grunt-dest-");
     const exec = vi.fn();
     init(dest, { pkgRoot, execFileSync: exec });
 
     for (const d of COPY_DIRS) {
+      if (d === ".claude") continue;
       expect(fs.readFileSync(path.join(dest, d, "marker"), "utf8")).toBe(d);
     }
-    for (const f of COPY_FILES) {
-      expect(fs.readFileSync(path.join(dest, f), "utf8")).toBe(f);
+    expect(fs.readFileSync(path.join(dest, ".claude", "marker"), "utf8")).toBe(".claude");
+    const settings = JSON.parse(
+      fs.readFileSync(path.join(dest, ".claude", "settings.json"), "utf8"),
+    );
+    expect(settings).toEqual(SRC_CLAUDE_SETTINGS);
+
+    for (const f of GUARDED_MD_FILES) {
+      expect(fs.readFileSync(path.join(dest, f), "utf8")).toBe(
+        `<!-- grunt:begin -->\n${f} content\n<!-- grunt:end -->\n`,
+      );
     }
+    expect(fs.existsSync(path.join(dest, ".mcp.json"))).toBe(false);
+
     for (const name of PRODUCT_FILES) {
       expect(fs.statSync(path.join(dest, "scripts", name)).isFile()).toBe(true);
     }
@@ -245,6 +511,36 @@ describe("init", () => {
     }
   });
 
+  it("re-running init on an already-initialized dest merges settings.json instead of clobbering", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-rerun-");
+    const exec = vi.fn();
+    fs.mkdirSync(path.join(dest, ".claude"), { recursive: true });
+    const consumerGroup = {
+      matcher: "custom",
+      hooks: [{ type: "command", command: "node scripts/my-custom-hook.mjs" }],
+    };
+    fs.writeFileSync(
+      path.join(dest, ".claude", "settings.json"),
+      JSON.stringify({
+        permissions: { deny: ["Agent(Explore)"] },
+        hooks: { PreToolUse: [consumerGroup] },
+        someCustomFlag: true,
+      }),
+    );
+    init(dest, { pkgRoot, execFileSync: exec });
+    const settings = JSON.parse(
+      fs.readFileSync(path.join(dest, ".claude", "settings.json"), "utf8"),
+    );
+    expect(settings.someCustomFlag).toBe(true);
+    expect(settings.hooks.PreToolUse).toEqual([
+      consumerGroup,
+      ...SRC_CLAUDE_SETTINGS.hooks.PreToolUse,
+    ]);
+    expect(settings.permissions.deny).toContain("Agent(Explore)");
+    expect(settings.permissions.deny).toContain("mcp__*");
+  });
+
   it("omitted execFileSync uses default; self-skip never invokes it", () => {
     const pkgRoot = stubPkgRoot();
     init(pkgRoot, { pkgRoot });
@@ -258,6 +554,7 @@ describe("init", () => {
     init(dest, { execFileSync: exec });
     expect(fs.existsSync(path.join(dest, "AGENTS.md"))).toBe(true);
     expect(fs.existsSync(path.join(dest, "scripts", "scrub-text"))).toBe(true);
+    expect(fs.existsSync(path.join(dest, ".claude", "settings.json"))).toBe(true);
     expect(exec.mock.calls.map((c) => c[1])).toEqual([
       ["install"],
       ["run", "rulesync:generate"],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lovrozagar/grunt",
-  "version": "0.2.0",
-  "description": "Multi-agent orchestrator SoT — deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo",
+  "version": "0.3.1",
+  "description": "Multi-agent orchestrator SoT \u2014 deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo",
   "keywords": [
     "agents",
     "grunt",
@@ -25,10 +25,14 @@
     "bin/grunt.js",
     "cli",
     "scripts/check-globals.mjs",
+    "scripts/emit-agent-shell-tools.mjs",
+    "scripts/emit-gemini.mjs",
     "scripts/emit-mcp-policy.mjs",
     "scripts/gate-fat-tools.mjs",
+    "scripts/hooks-union.mjs",
     "scripts/grunt-job.mjs",
     "scripts/parse-need.mjs",
+    "scripts/persist-handoff.mjs",
     "scripts/persist-plan.mjs",
     "scripts/purge-global-mcps.mjs",
     "scripts/scrub-spawn-prompt.mjs",
@@ -52,9 +56,11 @@
     "access": "public"
   },
   "scripts": {
-    "rulesync:generate": "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents && rulesync generate -t claudecode,codexcli,antigravity-cli -f hooks && node scripts/emit-mcp-policy.mjs",
-    "rulesync:watch": "node scripts/emit-mcp-policy.mjs && rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents --watch",
-    "rulesync:check": "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents --check && rulesync generate -t claudecode,codexcli,antigravity-cli -f hooks --check && node scripts/emit-mcp-policy.mjs --check && node scripts/check-globals.mjs",
+    "rulesync:generate": "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents,skills && rulesync generate -t claudecode,codexcli,antigravity-cli -f hooks && node scripts/emit-mcp-policy.mjs && node scripts/emit-gemini.mjs && node scripts/emit-agent-shell-tools.mjs && node scripts/hooks-union.mjs",
+    "rulesync:watch": "node scripts/emit-mcp-policy.mjs && node scripts/emit-gemini.mjs && node scripts/emit-agent-shell-tools.mjs && rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents,skills --watch",
+    "rulesync:check": "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,skills --check && rulesync generate -t codexcli,antigravity-cli,grokcli -f subagents --check && rulesync generate -t claudecode,codexcli,antigravity-cli -f hooks --check && node scripts/emit-mcp-policy.mjs --check && node scripts/emit-gemini.mjs --check && node scripts/emit-agent-shell-tools.mjs --check && node scripts/check-globals.mjs && node scripts/hooks-union.mjs --check",
+    "hooks:union": "node scripts/hooks-union.mjs",
+    "hooks:check": "node scripts/hooks-union.mjs --check",
     "rulesync:doctor": "rulesync doctor",
     "sync:globals": "node scripts/sync-global-settings.mjs",
     "sync:globals:check": "node scripts/check-globals.mjs",
@@ -66,7 +72,7 @@
   "devDependencies": {
     "@types/node": "^24.13.3",
     "@vitest/coverage-v8": "^3.2.7",
-    "rulesync": "latest",
+    "rulesync": "16.17.0",
     "smol-toml": "^1.8.0",
     "typescript": "^5.9.3",
     "vitest": "^3.2.7"

package/scripts/emit-agent-shell-tools.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/** After rulesync subagent emit: Claude grunt body uses Bash; other targets keep run_terminal_command. */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export const SSOT_REL = ".rulesync/subagents/grunt.md";
+export const CLAUDE_GRUNT_REL = ".claude/agents/grunt.md";
+
+export const GENERIC_TOOL_LIST =
+  "read_file, grep, list_dir, run_terminal_command, write, search_replace, web_search, web_fetch";
+export const CLAUDE_TOOL_LIST = "Read, Grep, Glob, Bash, Write, Edit, Web";
+
+export function parseArgv(argv) {
+  const args = Array.isArray(argv) ? argv : [];
+  let check = false;
+  for (const a of args) {
+    if (a === "--check") {
+      check = true;
+      continue;
+    }
+    return { ok: false, error: `unknown flag: ${a}` };
+  }
+  return { ok: true, check };
+}
+
+export function splitFrontmatter(text) {
+  const src = String(text ?? "");
+  if (!src.startsWith("---")) return { ok: false, error: "missing frontmatter" };
+  const rest = src.slice(3).replace(/^\r?\n/, "");
+  const m = rest.match(/\r?\n---\s*(?:\r?\n|$)/);
+  if (!m || m.index == null) return { ok: false, error: "missing frontmatter close" };
+  return { ok: true, fm: rest.slice(0, m.index), body: rest.slice(m.index + m[0].length) };
+}
+
+export function toClaudeShellBody(body) {
+  return String(body)
+    .split(GENERIC_TOOL_LIST)
+    .join(CLAUDE_TOOL_LIST)
+    .split("web_search/web_fetch")
+    .join("WebSearch/WebFetch")
+    .split("run_terminal_command")
+    .join("Bash");
+}
+
+function readText(abs) {
+  try {
+    return fs.readFileSync(abs, "utf8");
+  } catch (err) {
+    if (err && err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+function joinMarkdown(fm, body) {
+  const b = body.endsWith("\n") || body === "" ? body : `${body}\n`;
+  return `---\n${fm}\n---\n${b}`;
+}
+
+export function emitAgentShellTools({ workspaceRoot, check = false } = {}) {
+  const ws = workspaceRoot || process.cwd();
+  const ssotAbs = path.join(ws, SSOT_REL);
+  const claudeAbs = path.join(ws, CLAUDE_GRUNT_REL);
+  const ssotRaw = readText(ssotAbs);
+  if (ssotRaw == null) {
+    return { ok: false, check, error: `missing ${SSOT_REL}` };
+  }
+  const ssot = splitFrontmatter(ssotRaw);
+  if (!ssot.ok) {
+    return { ok: false, check, error: `ssot: ${ssot.error}` };
+  }
+  const claudeRaw = readText(claudeAbs);
+  if (claudeRaw == null) {
+    return { ok: false, check, error: `missing ${CLAUDE_GRUNT_REL}` };
+  }
+  const claude = splitFrontmatter(claudeRaw);
+  if (!claude.ok) {
+    return { ok: false, check, error: `claude grunt: ${claude.error}` };
+  }
+  const next = joinMarkdown(claude.fm, toClaudeShellBody(ssot.body));
+  if (check) {
+    if (claudeRaw !== next) {
+      return { ok: false, check: true, error: `drift: ${CLAUDE_GRUNT_REL}`, drift: [CLAUDE_GRUNT_REL] };
+    }
+    return { ok: true, check: true, drift: [] };
+  }
+  fs.mkdirSync(path.dirname(claudeAbs), { recursive: true });
+  fs.writeFileSync(claudeAbs, next);
+  return { ok: true, check: false };
+}
+
+function main() {
+  try {
+    const parsed = parseArgv(process.argv.slice(2));
+    if (!parsed.ok) {
+      process.stderr.write((parsed.error || "invalid argv") + "\n");
+      return 1;
+    }
+    const result = emitAgentShellTools({
+      workspaceRoot: process.cwd(),
+      check: parsed.check,
+    });
+    if (!result.ok) {
+      process.stderr.write((result.error || "emit failed") + "\n");
+      return 1;
+    }
+    return 0;
+  } catch (err) {
+    process.stderr.write(String(err && err.message ? err.message : err) + "\n");
+    return 1;
+  }
+}
+
+const thisFile = fileURLToPath(import.meta.url);
+const invoked = process.argv[1] ? path.resolve(process.argv[1]) : "";
+if (invoked === thisFile || import.meta.url === pathToFileURL(invoked).href) {
+  process.exit(main());
+}