mcpill 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.10.0
+
+- `mcpill compile` emits `.mcpill/dist/<pill>/` — a standalone npm package containing `install.js`, `index.js`, `tools.js`, `package.json`, and (for blocking pills) `hooks/pre-tool-gate.js` + `hooks/post-analysis-flag.js`
+- `<pill> install --agent <target>` wires the MCP server and blocking hooks into the target agent's config; supports `claude-code`, `cursor`, `windsurf`, `github-copilot`, `codex`; idempotent
+- `<pill> uninstall --agent <target>` reverses the install cleanly
+- `hooks/pre-tool-gate.js` normalises stdin from all four agent input shapes (Claude Code, Cursor, Windsurf, GitHub Copilot) and branches exit code / output per agent (exit 1, exit 2, or JSON deny)
+- `index.js` in the standalone package wraps `required_tool` handlers to write the flag file, enabling enforcement on agents with no `PostToolUse` hook (Windsurf)
+- Opt-in `postinstall: true` and `version` fields in `PILL.md ## Server` block
+- `<pill> install` writes `~/.{pillName}/state.json { enabled: true }` so gate enforcement is active immediately after install; `uninstall` removes it
+- `mcpill init` scaffolds `README.md` with a quickstart guide covering project layout and tool-editing workflow
+
+## 1.9.0
+
+- `blocking: true` field on `PILL.md` `## Hook:` blocks; `mcpill compile` generates a `.mjs` `PreToolUse` gate script (exits 1 until a required tool has run) and a `PostToolUse` flag script
+- `required_tool`, `gate_window_seconds` (default 120 s), and multiline `instructions` fields supported on blocking hooks
+- Compile-time validation: `required_tool` must name a known tool; error surfaced during `mcpill compile`
+
 ## 1.8.0
 
 - `mcpill run` (stdio) now auto-registers the server in Claude config on start and auto-unregisters on SIGINT, SIGTERM, and process exit — no manual step required

package/README.md

@@ -78,6 +78,25 @@ Compile also writes a `PreToolUse` hook into `.claude/settings.json` that warns
 
 - **`AGENT.md`** — a `## Tools` table with a `Replaces` column (existing format). AGENT.md wins on name conflicts.
 
+#### Blocking hooks
+
+For mandatory workflow steps, add a `## Hook:` section to `PILL.md` with `blocking: true`. Compile generates a hard-enforcement gate instead of a soft reminder:
+
+```markdown
+## Hook: my-hook
+
+trigger: PreToolUse
+blocking: true
+required_tool: analyze-english
+gate_window_seconds: 120
+instructions: |
+  Before calling any other tool, call mcp__my-pill__analyze-english first.
+```
+
+At runtime the gate script exits 1 (blocking the tool call) until `mcp__{pill}__analyze-english` has run within the window. After it runs, the flag script records the timestamp and the gate passes for `gate_window_seconds` seconds (default 120). Pill's own MCP tools are always allowed through. The gate is fail-open — if the pill's state file is missing, the gate passes.
+
+`required_tool` must name a tool defined in the same pill; `mcpill compile` aborts with an error if it doesn't.
+
 ### `mcpill validate`
 
 Validates all pill directories (`.<name>/`) in the project root.

package/dist/cli.js

@@ -3,7 +3,7 @@
 // src/cli.ts
 import { Command } from "commander";
 import { fileURLToPath } from "url";
-import { dirname, join as join6 } from "path";
+import { dirname, join as join7 } from "path";
 import { readFileSync as readFileSync5 } from "fs";
 
 // src/commands/init.ts
@@ -756,12 +756,45 @@ function extractFencedBlock(body, lang) {
 }
 function parseKvBlock(body) {
   const result = {};
-  for (const line of body.split("\n")) {
+  const lines = body.split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
     const colonIdx = line.indexOf(":");
-    if (colonIdx === -1) continue;
+    if (colonIdx === -1) {
+      i++;
+      continue;
+    }
     const key = line.slice(0, colonIdx).trim();
     const value = line.slice(colonIdx + 1).trim();
-    if (key) result[key] = value;
+    if (!key) {
+      i++;
+      continue;
+    }
+    if (value === "|") {
+      i++;
+      const blockLines = [];
+      let baseIndent = -1;
+      while (i < lines.length) {
+        const nextLine = lines[i];
+        const trimmed = nextLine.trimStart();
+        if (trimmed === "") {
+          blockLines.push("");
+          i++;
+          continue;
+        }
+        const indent = nextLine.length - trimmed.length;
+        if (baseIndent === -1) baseIndent = indent;
+        if (indent < baseIndent) break;
+        blockLines.push(nextLine.slice(baseIndent));
+        i++;
+      }
+      while (blockLines.length > 0 && blockLines[blockLines.length - 1] === "") blockLines.pop();
+      result[key] = blockLines.join("\n");
+    } else {
+      result[key] = value;
+      i++;
+    }
   }
   return result;
 }
@@ -976,13 +1009,31 @@ function parsePillMdHooks(content) {
   for (const piece of pieces) {
     if (!piece.toLowerCase().startsWith("hook:")) continue;
     const nlIdx = piece.indexOf("\n");
+    const sectionTitle = (nlIdx === -1 ? piece : piece.slice(0, nlIdx)).trim();
+    const hookName = sectionTitle.slice("hook:".length).trim();
     const body = nlIdx === -1 ? "" : piece.slice(nlIdx + 1);
     const kv = parseKvBlock(body);
     const trigger = kv["trigger"]?.trim();
     const matcher = kv["matcher"]?.trim();
     const command = kv["command"]?.trim();
-    if (!trigger || !command) continue;
-    hooks.push({ event: trigger, ...matcher ? { matcher } : {}, command });
+    const blocking = kv["blocking"]?.trim().toLowerCase() === "true";
+    if (!trigger || !command && !blocking) continue;
+    const entry = {
+      ...hookName ? { name: hookName } : {},
+      event: trigger,
+      ...matcher ? { matcher } : {},
+      ...command ? { command } : {},
+      ...blocking ? { blocking: true } : {}
+    };
+    if (blocking) {
+      const requiredTool = kv["required_tool"]?.trim();
+      if (requiredTool) entry.required_tool = requiredTool;
+      const windowRaw = kv["gate_window_seconds"]?.trim();
+      if (windowRaw) entry.gate_window_seconds = parseInt(windowRaw, 10);
+      const instructions = kv["instructions"]?.trim();
+      if (instructions) entry.instructions = instructions;
+    }
+    hooks.push(entry);
   }
   return hooks;
 }
@@ -992,8 +1043,23 @@ function parseHookFile(content) {
   const trigger = kv["trigger"]?.trim();
   const matcher = kv["matcher"]?.trim();
   const command = kv["command"]?.trim();
-  if (!trigger || !command) return null;
-  return { event: trigger, ...matcher ? { matcher } : {}, command };
+  const blocking = kv["blocking"]?.trim().toLowerCase() === "true";
+  if (!trigger || !command && !blocking) return null;
+  const entry = {
+    event: trigger,
+    ...matcher ? { matcher } : {},
+    ...command ? { command } : {},
+    ...blocking ? { blocking: true } : {}
+  };
+  if (blocking) {
+    const requiredTool = kv["required_tool"]?.trim();
+    if (requiredTool) entry.required_tool = requiredTool;
+    const windowRaw = kv["gate_window_seconds"]?.trim();
+    if (windowRaw) entry.gate_window_seconds = parseInt(windowRaw, 10);
+    const instructions = kv["instructions"]?.trim();
+    if (instructions) entry.instructions = instructions;
+  }
+  return entry;
 }
 function mergeUserHooksIntoSettings(baseDir, hookBlocks) {
   if (hookBlocks.length === 0) return;
@@ -1040,6 +1106,91 @@ function mergeHookIntoSettings(baseDir, hookEntry) {
   mkdirSync(claudeDir, { recursive: true });
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
 }
+function generateGateScript(pillName, requiredTool, windowSeconds, instructions) {
+  const instrJson = JSON.stringify(instructions);
+  return [
+    `import { readFileSync, existsSync } from 'fs';`,
+    `import { homedir } from 'os';`,
+    `import { join } from 'path';`,
+    ``,
+    `const PILL_NAME = ${JSON.stringify(pillName)};`,
+    `const REQUIRED_TOOL = ${JSON.stringify(requiredTool)};`,
+    `const GATE_WINDOW_SECONDS = ${windowSeconds};`,
+    `const INSTRUCTIONS = ${instrJson};`,
+    ``,
+    `const raw = readFileSync(0, 'utf-8');`,
+    `const input = JSON.parse(raw);`,
+    `const toolName = input.tool_name ?? '';`,
+    ``,
+    `if (toolName.startsWith(\`mcp__\${PILL_NAME}__\`)) process.exit(0);`,
+    ``,
+    `const stateFile = join(homedir(), \`.\${PILL_NAME}\`, 'state.json');`,
+    `if (!existsSync(stateFile)) process.exit(0);`,
+    ``,
+    `const state = JSON.parse(readFileSync(stateFile, 'utf-8'));`,
+    `if (state.enabled === false) process.exit(0);`,
+    ``,
+    `const flagFile = join(homedir(), \`.\${PILL_NAME}\`, \`last_\${REQUIRED_TOOL}_run.json\`);`,
+    `if (existsSync(flagFile)) {`,
+    `  const flag = JSON.parse(readFileSync(flagFile, 'utf-8'));`,
+    `  const elapsedMs = Date.now() - new Date(flag.timestamp).getTime();`,
+    `  if (elapsedMs <= GATE_WINDOW_SECONDS * 1000) process.exit(0);`,
+    `}`,
+    ``,
+    `process.stderr.write(INSTRUCTIONS + '\\n');`,
+    `process.exit(1);`,
+    ``
+  ].join("\n");
+}
+function generateFlagScript(pillName, requiredTool) {
+  return [
+    `import { writeFileSync, mkdirSync } from 'fs';`,
+    `import { homedir } from 'os';`,
+    `import { join } from 'path';`,
+    ``,
+    `const PILL_NAME = ${JSON.stringify(pillName)};`,
+    `const REQUIRED_TOOL = ${JSON.stringify(requiredTool)};`,
+    ``,
+    `const dir = join(homedir(), \`.\${PILL_NAME}\`);`,
+    `const flagFile = join(dir, \`last_\${REQUIRED_TOOL}_run.json\`);`,
+    ``,
+    `try {`,
+    `  mkdirSync(dir, { recursive: true });`,
+    `  writeFileSync(flagFile, JSON.stringify({ timestamp: new Date().toISOString() }));`,
+    `} catch (e) {`,
+    `  process.stderr.write(\`[\${PILL_NAME}] warning: could not write flag file: \${e.message}\\n\`);`,
+    `}`,
+    ``
+  ].join("\n");
+}
+function applyBlockingHookScripts(baseDir, pillName, hook) {
+  const hooksDir = join3(baseDir, ".mcpill", "server", "hooks");
+  mkdirSync(hooksDir, { recursive: true });
+  const hookName = hook.name;
+  const requiredTool = hook.required_tool;
+  const windowSeconds = hook.gate_window_seconds ?? 120;
+  const instructions = hook.instructions ?? `[mcpill:${pillName}] Run mcp__${pillName}__${requiredTool} before calling other tools.`;
+  writeFileSync(
+    join3(hooksDir, `${hookName}-gate.mjs`),
+    generateGateScript(pillName, requiredTool, windowSeconds, instructions)
+  );
+  writeFileSync(
+    join3(hooksDir, `${hookName}-flag.mjs`),
+    generateFlagScript(pillName, requiredTool)
+  );
+  return [
+    {
+      event: "PreToolUse",
+      matcher: ".*",
+      command: `node .mcpill/server/hooks/${hookName}-gate.mjs`
+    },
+    {
+      event: "PostToolUse",
+      matcher: `mcp__${pillName}__${requiredTool}`,
+      command: `node .mcpill/server/hooks/${hookName}-flag.mjs`
+    }
+  ];
+}
 
 // src/commands/validate.ts
 async function validateOne(mcpillDir) {
@@ -1224,8 +1375,8 @@ async function runServer(opts) {
 }
 
 // src/commands/compile.ts
-import { resolve, join as join5 } from "path";
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, existsSync as existsSync3, readdirSync as readdirSync2 } from "fs";
+import { resolve, join as join6 } from "path";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync4, mkdirSync as mkdirSync4, existsSync as existsSync3, readdirSync as readdirSync2 } from "fs";
 import { pathToFileURL as pathToFileURL2 } from "url";
 
 // src/compiler/serialize.ts
@@ -1397,6 +1548,514 @@ function mergeHandlers(doc, existing) {
   return { doc: { ...doc, tools }, stubbed };
 }
 
+// src/compiler/standalone.ts
+import { writeFileSync as writeFileSync3, mkdirSync as mkdirSync3 } from "fs";
+import { join as join5 } from "path";
+function generateStandaloneIndexJs(pillName, version, prompts, resources, blockingHookTools) {
+  const promptsJson = JSON.stringify(prompts, null, 2);
+  const resourcesJson = JSON.stringify(resources, null, 2);
+  const lines = [
+    `#!/usr/bin/env node`,
+    `import { createServer } from 'mcpster';`,
+    `import { z } from 'mcpill-runtime';`,
+    `import { writeFileSync, mkdirSync } from 'fs';`,
+    `import { homedir } from 'os';`,
+    `import { join } from 'path';`,
+    `import tools from './tools.js';`,
+    ``,
+    `const PILL_NAME = ${JSON.stringify(pillName)};`,
+    `const PILL_VERSION = ${JSON.stringify(version)};`,
+    `const REQUIRED_TOOLS = ${JSON.stringify(blockingHookTools)};`,
+    ``,
+    `const prompts = ${promptsJson};`,
+    `const resources = ${resourcesJson};`
+  ];
+  if (blockingHookTools.length > 0) {
+    lines.push(
+      ``,
+      `const _writeFlagFile = (pillName, toolName) => {`,
+      `  const dir = join(homedir(), '.' + pillName);`,
+      `  try {`,
+      `    mkdirSync(dir, { recursive: true });`,
+      `    writeFileSync(join(dir, 'last_' + toolName + '_run.json'), JSON.stringify({ timestamp: new Date().toISOString() }));`,
+      `  } catch {}`,
+      `};`
+    );
+  }
+  lines.push(
+    ``,
+    `const server = createServer({ name: PILL_NAME, version: PILL_VERSION, transport: 'stdio' });`,
+    ``,
+    `for (const { name, description, schema, handler } of tools) {`,
+    `  server.defineTool({`,
+    `    name,`,
+    `    description,`,
+    `    schema: z.object(schema),`
+  );
+  if (blockingHookTools.length > 0) {
+    lines.push(
+      `    handler: REQUIRED_TOOLS.includes(name)`,
+      `      ? async (args) => { const r = await handler(args); _writeFlagFile(PILL_NAME, name); return r; }`,
+      `      : handler,`
+    );
+  } else {
+    lines.push(`    handler,`);
+  }
+  lines.push(
+    `  });`,
+    `}`,
+    ``,
+    `for (const { name: promptName, description, messages } of prompts) {`,
+    `  server.definePrompt({`,
+    `    name: promptName,`,
+    `    description,`,
+    `    handler: async (args) =>`,
+    `      messages.map(m => m.content.replace(/{{(\\w+)}}/g, (_, k) => String(args[k] ?? ''))).join('\\n'),`,
+    `  });`,
+    `}`,
+    ``,
+    `for (const { uri, name: resourceName, content } of resources) {`,
+    `  server.defineResource({`,
+    `    uri,`,
+    `    description: resourceName ?? uri,`,
+    `    resolver: async () => content,`,
+    `  });`,
+    `}`,
+    ``,
+    `await server.start();`,
+    ``
+  );
+  return lines.join("\n");
+}
+function generateStandaloneGateScript(pillName, blockingHooks) {
+  const hooksData = blockingHooks.map((h) => ({
+    required_tool: h.required_tool,
+    gate_window_seconds: h.gate_window_seconds ?? 120,
+    instructions: h.instructions ?? `[mcpill:${pillName}] Run mcp__${pillName}__${h.required_tool} before calling other tools.`
+  }));
+  return [
+    `#!/usr/bin/env node`,
+    `import { readFileSync, existsSync } from 'fs';`,
+    `import { homedir } from 'os';`,
+    `import { join } from 'path';`,
+    ``,
+    `const PILL_NAME = ${JSON.stringify(pillName)};`,
+    `const HOOKS = ${JSON.stringify(hooksData, null, 2)};`,
+    ``,
+    `const raw = readFileSync(0, 'utf-8');`,
+    `const input = JSON.parse(raw);`,
+    ``,
+    `// Agent detection + tool name normalization`,
+    `let toolName;`,
+    `if (typeof input.tool_info === 'object' && input.tool_info !== null && typeof input.tool_info.mcp_tool_name === 'string') {`,
+    `  toolName = input.tool_info.mcp_tool_name; // Windsurf`,
+    `} else if (typeof input.toolName === 'string') {`,
+    `  toolName = input.toolName; // GitHub Copilot`,
+    `} else {`,
+    `  toolName = input.tool_name ?? ''; // Claude Code, Cursor, Codex`,
+    `}`,
+    ``,
+    `if (toolName.startsWith('mcp__' + PILL_NAME + '__')) process.exit(0);`,
+    ``,
+    `const unsatisfied = [];`,
+    `for (const hook of HOOKS) {`,
+    `  const stateFile = join(homedir(), '.' + PILL_NAME, 'state.json');`,
+    `  if (!existsSync(stateFile)) continue;`,
+    `  const state = JSON.parse(readFileSync(stateFile, 'utf-8'));`,
+    `  if (state.enabled === false) continue;`,
+    `  const flagFile = join(homedir(), '.' + PILL_NAME, 'last_' + hook.required_tool + '_run.json');`,
+    `  if (existsSync(flagFile)) {`,
+    `    const flag = JSON.parse(readFileSync(flagFile, 'utf-8'));`,
+    `    const elapsedMs = Date.now() - new Date(flag.timestamp).getTime();`,
+    `    if (elapsedMs <= hook.gate_window_seconds * 1000) continue;`,
+    `  }`,
+    `  unsatisfied.push(hook.instructions);`,
+    `}`,
+    ``,
+    `if (unsatisfied.length === 0) process.exit(0);`,
+    ``,
+    `const blockMsg = unsatisfied.join('\\n');`,
+    ``,
+    `// Per-agent output format`,
+    `if (typeof input.tool_info === 'object' && input.tool_info !== null && typeof input.tool_info.mcp_tool_name === 'string') {`,
+    `  // Windsurf: exit 2`,
+    `  process.stderr.write(blockMsg + '\\n');`,
+    `  process.exit(2);`,
+    `} else if (typeof input.toolName === 'string') {`,
+    `  // GitHub Copilot: JSON deny`,
+    `  process.stdout.write(JSON.stringify({ permissionDecision: 'deny', permissionDecisionReason: blockMsg }));`,
+    `  process.exit(0);`,
+    `} else if (input.workspace_roots !== undefined || typeof input.conversation_id === 'string') {`,
+    `  // Cursor: JSON deny`,
+    `  process.stdout.write(JSON.stringify({ permission: 'deny', agentMessage: blockMsg }));`,
+    `  process.exit(0);`,
+    `} else {`,
+    `  // Claude Code / Codex: exit 1`,
+    `  process.stderr.write(blockMsg + '\\n');`,
+    `  process.exit(1);`,
+    `}`,
+    ``
+  ].join("\n");
+}
+function generateStandaloneFlagScript(pillName) {
+  return [
+    `#!/usr/bin/env node`,
+    `import { writeFileSync, mkdirSync } from 'fs';`,
+    `import { homedir } from 'os';`,
+    `import { join } from 'path';`,
+    ``,
+    `const PILL_NAME = ${JSON.stringify(pillName)};`,
+    ``,
+    `const toolIdx = process.argv.indexOf('--tool');`,
+    `const toolName = toolIdx !== -1 ? process.argv[toolIdx + 1] : null;`,
+    ``,
+    `if (!toolName) {`,
+    `  process.stderr.write('[' + PILL_NAME + '] error: --tool <name> required\\n');`,
+    `  process.exit(1);`,
+    `}`,
+    ``,
+    `const dir = join(homedir(), '.' + PILL_NAME);`,
+    `const flagFile = join(dir, 'last_' + toolName + '_run.json');`,
+    ``,
+    `try {`,
+    `  mkdirSync(dir, { recursive: true });`,
+    `  writeFileSync(flagFile, JSON.stringify({ timestamp: new Date().toISOString() }));`,
+    `} catch (e) {`,
+    `  process.stderr.write('[' + PILL_NAME + '] warning: could not write flag file: ' + e.message + '\\n');`,
+    `}`,
+    ``
+  ].join("\n");
+}
+var INSTALL_JS_BODY = `
+function readJson(filePath) {
+  if (!existsSync(filePath)) return {};
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch {
+    const bakPath = filePath + '.bak';
+    try { writeFileSync(bakPath, readFileSync(filePath)); } catch {}
+    process.stderr.write('[mcpill] warning: ' + filePath + ' was not valid JSON \u2014 backed up to ' + bakPath + ' and recreated\\n');
+    return {};
+  }
+}
+
+function writeJson(filePath, obj) {
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(filePath, JSON.stringify(obj, null, 2) + '\\n');
+}
+
+function activatePill() {
+  mkdirSync(dirname(STATE_FILE), { recursive: true });
+  writeJson(STATE_FILE, { enabled: true });
+}
+
+function deactivatePill() {
+  try { rmSync(STATE_FILE, { force: true }); } catch {}
+}
+
+function installClaudeCode() {
+  const settingsPath = join(homedir(), '.claude', 'settings.json');
+  const wasInstalled = existsSync(settingsPath) && (readJson(settingsPath).mcpServers || {})[PILL_NAME] !== undefined;
+  const s = readJson(settingsPath);
+  if (!s.mcpServers) s.mcpServers = {};
+  s.mcpServers[PILL_NAME] = MCP_ENTRY;
+  if (HAS_BLOCKING_HOOKS) {
+    if (!s.hooks) s.hooks = {};
+    if (!s.hooks.PreToolUse) s.hooks.PreToolUse = [];
+    if (!s.hooks.PostToolUse) s.hooks.PostToolUse = [];
+    const gateMarker = '/' + PILL_NAME + '/hooks/';
+    s.hooks.PreToolUse = s.hooks.PreToolUse.filter(e => !e.hooks?.[0]?.command?.includes(gateMarker));
+    s.hooks.PostToolUse = s.hooks.PostToolUse.filter(e => !e.matcher?.startsWith('mcp__' + PILL_NAME + '__'));
+    s.hooks.PreToolUse.push({ matcher: '.*', hooks: [{ type: 'command', command: 'node "' + GATE_PATH + '"' }] });
+    for (const hook of HOOKS) {
+      s.hooks.PostToolUse.push({
+        matcher: 'mcp__' + PILL_NAME + '__' + hook.required_tool,
+        hooks: [{ type: 'command', command: 'node "' + FLAG_PATH + '" --tool ' + hook.required_tool }],
+      });
+    }
+  }
+  writeJson(settingsPath, s);
+  activatePill();
+  if (!silent) process.stdout.write('[mcpill] info: ' + (wasInstalled ? 'reinstalled' : 'installed') + ' ' + PILL_NAME + (HAS_BLOCKING_HOOKS ? '' : ' (no blocking hooks \u2014 MCP server only)') + ' for claude-code\\n');
+}
+
+function uninstallClaudeCode() {
+  const settingsPath = join(homedir(), '.claude', 'settings.json');
+  if (!existsSync(settingsPath)) return;
+  const s = readJson(settingsPath);
+  if (s.mcpServers) delete s.mcpServers[PILL_NAME];
+  if (s.hooks) {
+    const gateMarker = '/' + PILL_NAME + '/hooks/';
+    if (s.hooks.PreToolUse) s.hooks.PreToolUse = s.hooks.PreToolUse.filter(e => !e.hooks?.[0]?.command?.includes(gateMarker));
+    if (s.hooks.PostToolUse) s.hooks.PostToolUse = s.hooks.PostToolUse.filter(e => !e.matcher?.startsWith('mcp__' + PILL_NAME + '__'));
+  }
+  writeJson(settingsPath, s);
+  deactivatePill();
+  if (!silent) process.stdout.write('[mcpill] info: uninstalled ' + PILL_NAME + ' from claude-code\\n');
+}
+
+function installCursor() {
+  const mcpPath = join(homedir(), '.cursor', 'mcp.json');
+  const mcp = readJson(mcpPath);
+  if (!mcp.mcpServers) mcp.mcpServers = {};
+  mcp.mcpServers[PILL_NAME] = MCP_ENTRY;
+  writeJson(mcpPath, mcp);
+  if (HAS_BLOCKING_HOOKS) {
+    const hooksPath = join(homedir(), '.cursor', 'hooks.json');
+    const h = readJson(hooksPath);
+    if (!h.hooks) h.hooks = {};
+    if (!h.hooks.beforeMCPExecution) h.hooks.beforeMCPExecution = [];
+    if (!h.hooks.afterMCPExecution) h.hooks.afterMCPExecution = [];
+    const gateMarker = '/' + PILL_NAME + '/hooks/';
+    h.hooks.beforeMCPExecution = h.hooks.beforeMCPExecution.filter(e => !e.command?.includes(gateMarker));
+    h.hooks.afterMCPExecution = h.hooks.afterMCPExecution.filter(e => !e.command?.includes(gateMarker));
+    h.hooks.beforeMCPExecution.push({ command: 'node "' + GATE_PATH + '"', type: 'command', matcher: '.*' });
+    for (const hook of HOOKS) {
+      h.hooks.afterMCPExecution.push({
+        command: 'node "' + FLAG_PATH + '" --tool ' + hook.required_tool,
+        type: 'command',
+        matcher: 'mcp__' + PILL_NAME + '__' + hook.required_tool,
+      });
+    }
+    writeJson(hooksPath, h);
+  }
+  activatePill();
+  if (!silent) process.stdout.write('[mcpill] info: installed ' + PILL_NAME + ' for cursor\\n');
+}
+
+function uninstallCursor() {
+  const mcpPath = join(homedir(), '.cursor', 'mcp.json');
+  if (existsSync(mcpPath)) {
+    const mcp = readJson(mcpPath);
+    if (mcp.mcpServers) delete mcp.mcpServers[PILL_NAME];
+    writeJson(mcpPath, mcp);
+  }
+  const hooksPath = join(homedir(), '.cursor', 'hooks.json');
+  if (existsSync(hooksPath)) {
+    const h = readJson(hooksPath);
+    const gateMarker = '/' + PILL_NAME + '/hooks/';
+    if (h.hooks?.beforeMCPExecution) h.hooks.beforeMCPExecution = h.hooks.beforeMCPExecution.filter(e => !e.command?.includes(gateMarker));
+    if (h.hooks?.afterMCPExecution) h.hooks.afterMCPExecution = h.hooks.afterMCPExecution.filter(e => !e.command?.includes(gateMarker));
+    writeJson(hooksPath, h);
+  }
+  deactivatePill();
+  if (!silent) process.stdout.write('[mcpill] info: uninstalled ' + PILL_NAME + ' from cursor\\n');
+}
+
+function installWindsurf() {
+  const mcpPath = join(homedir(), '.codeium', 'windsurf', 'mcp_config.json');
+  const mcp = readJson(mcpPath);
+  if (!mcp.mcpServers) mcp.mcpServers = {};
+  mcp.mcpServers[PILL_NAME] = MCP_ENTRY;
+  writeJson(mcpPath, mcp);
+  if (HAS_BLOCKING_HOOKS) {
+    const hooksPath = join(homedir(), '.codeium', 'windsurf', 'hooks.json');
+    const h = readJson(hooksPath);
+    if (!h.hooks) h.hooks = {};
+    if (!h.hooks.pre_mcp_tool_use) h.hooks.pre_mcp_tool_use = [];
+    const gateMarker = '/' + PILL_NAME + '/hooks/';
+    h.hooks.pre_mcp_tool_use = h.hooks.pre_mcp_tool_use.filter(e => !e.command?.includes(gateMarker));
+    h.hooks.pre_mcp_tool_use.push({ command: 'node "' + GATE_PATH + '"' });
+    writeJson(hooksPath, h);
+  }
+  activatePill();
+  if (!silent) process.stdout.write('[mcpill] info: installed ' + PILL_NAME + ' for windsurf\\n');
+}
+
+function uninstallWindsurf() {
+  const mcpPath = join(homedir(), '.codeium', 'windsurf', 'mcp_config.json');
+  if (existsSync(mcpPath)) {
+    const mcp = readJson(mcpPath);
+    if (mcp.mcpServers) delete mcp.mcpServers[PILL_NAME];
+    writeJson(mcpPath, mcp);
+  }
+  const hooksPath = join(homedir(), '.codeium', 'windsurf', 'hooks.json');
+  if (existsSync(hooksPath)) {
+    const h = readJson(hooksPath);
+    const gateMarker = '/' + PILL_NAME + '/hooks/';
+    if (h.hooks?.pre_mcp_tool_use) h.hooks.pre_mcp_tool_use = h.hooks.pre_mcp_tool_use.filter(e => !e.command?.includes(gateMarker));
+    writeJson(hooksPath, h);
+  }
+  deactivatePill();
+  if (!silent) process.stdout.write('[mcpill] info: uninstalled ' + PILL_NAME + ' from windsurf\\n');
+}
+
+function installCopilot() {
+  const mcpPath = join(homedir(), '.vscode', 'mcp.json');
+  const mcp = readJson(mcpPath);
+  if (!mcp.mcpServers) mcp.mcpServers = {};
+  mcp.mcpServers[PILL_NAME] = MCP_ENTRY;
+  writeJson(mcpPath, mcp);
+  if (HAS_BLOCKING_HOOKS) {
+    const hooksPath = join(homedir(), '.copilot', 'settings.json');
+    const h = readJson(hooksPath);
+    if (!h.hooks) h.hooks = {};
+    if (!h.hooks.preToolUse) h.hooks.preToolUse = [];
+    if (!h.hooks.postToolUse) h.hooks.postToolUse = [];
+    const gateMarker = '/' + PILL_NAME + '/hooks/';
+    h.hooks.preToolUse = h.hooks.preToolUse.filter(e => !e.bash?.includes(gateMarker));
+    h.hooks.postToolUse = h.hooks.postToolUse.filter(e => !e.bash?.includes(gateMarker));
+    h.hooks.preToolUse.push({ type: 'command', bash: 'node "' + GATE_PATH + '"', timeoutSec: 30 });
+    for (const hook of HOOKS) {
+      h.hooks.postToolUse.push({
+        type: 'command',
+        bash: 'node "' + FLAG_PATH + '" --tool ' + hook.required_tool,
+        timeoutSec: 30,
+      });
+    }
+    writeJson(hooksPath, h);
+  }
+  activatePill();
+  if (!silent) process.stdout.write('[mcpill] info: installed ' + PILL_NAME + ' for github-copilot\\n');
+}
+
+function uninstallCopilot() {
+  const mcpPath = join(homedir(), '.vscode', 'mcp.json');
+  if (existsSync(mcpPath)) {
+    const mcp = readJson(mcpPath);
+    if (mcp.mcpServers) delete mcp.mcpServers[PILL_NAME];
+    writeJson(mcpPath, mcp);
+  }
+  const hooksPath = join(homedir(), '.copilot', 'settings.json');
+  if (existsSync(hooksPath)) {
+    const h = readJson(hooksPath);
+    const gateMarker = '/' + PILL_NAME + '/hooks/';
+    if (h.hooks?.preToolUse) h.hooks.preToolUse = h.hooks.preToolUse.filter(e => !e.bash?.includes(gateMarker));
+    if (h.hooks?.postToolUse) h.hooks.postToolUse = h.hooks.postToolUse.filter(e => !e.bash?.includes(gateMarker));
+    writeJson(hooksPath, h);
+  }
+  deactivatePill();
+  if (!silent) process.stdout.write('[mcpill] info: uninstalled ' + PILL_NAME + ' from github-copilot\\n');
+}
+
+function installCodex() {
+  const configPath = join(homedir(), '.codex', 'config.toml');
+  mkdirSync(join(homedir(), '.codex'), { recursive: true });
+  let existing = '';
+  if (existsSync(configPath)) {
+    try { existing = readFileSync(configPath, 'utf-8'); } catch {}
+  }
+  // Remove existing entry for this pill
+  const pat = new RegExp('\\\\[mcp_servers\\\\.' + PILL_NAME.replace(/[.*+?^\${}()|[\\]\\\\]/g, '\\\\$&') + '\\\\][\\\\s\\\\S]*?(?=\\\\[|$)', 'g');
+  existing = existing.replace(pat, '').trimEnd();
+  if (!existing.includes('[mcp_servers]')) existing += '\\n[mcp_servers]';
+  existing += '\\n\\n[mcp_servers.' + PILL_NAME + ']\\ncommand = "node"\\nargs = [' + JSON.stringify(INDEX_PATH) + ']\\n';
+  writeFileSync(configPath, existing.trim() + '\\n');
+  activatePill();
+  if (!silent) process.stdout.write('[mcpill] info: installed ' + PILL_NAME + ' for codex (MCP server only \u2014 hooks not yet supported for codex)\\n');
+}
+
+function uninstallCodex() {
+  const configPath = join(homedir(), '.codex', 'config.toml');
+  if (!existsSync(configPath)) return;
+  let content = readFileSync(configPath, 'utf-8');
+  const pat = new RegExp('\\\\[mcp_servers\\\\.' + PILL_NAME.replace(/[.*+?^\${}()|[\\]\\\\]/g, '\\\\$&') + '\\\\][\\\\s\\\\S]*?(?=\\\\[|$)', 'g');
+  content = content.replace(pat, '').trim() + '\\n';
+  writeFileSync(configPath, content);
+  deactivatePill();
+  if (!silent) process.stdout.write('[mcpill] info: uninstalled ' + PILL_NAME + ' from codex\\n');
+}
+
+if (command === 'install') {
+  switch (agent) {
+    case 'claude-code': installClaudeCode(); break;
+    case 'cursor': installCursor(); break;
+    case 'windsurf': installWindsurf(); break;
+    case 'github-copilot': installCopilot(); break;
+    case 'codex': installCodex(); break;
+  }
+} else {
+  switch (agent) {
+    case 'claude-code': uninstallClaudeCode(); break;
+    case 'cursor': uninstallCursor(); break;
+    case 'windsurf': uninstallWindsurf(); break;
+    case 'github-copilot': uninstallCopilot(); break;
+    case 'codex': uninstallCodex(); break;
+  }
+}
+`;
+function generateStandaloneInstallJs(pillName, version, blockingHooks) {
+  const hooksData = blockingHooks.map((h) => ({
+    required_tool: h.required_tool
+  }));
+  const constants = [
+    `#!/usr/bin/env node`,
+    `import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'fs';`,
+    `import { homedir } from 'os';`,
+    `import { join, dirname, resolve } from 'path';`,
+    `import { fileURLToPath } from 'url';`,
+    ``,
+    `const __filename = fileURLToPath(import.meta.url);`,
+    `const __dirname = dirname(__filename);`,
+    ``,
+    `const PILL_NAME = ${JSON.stringify(pillName)};`,
+    `const PILL_VERSION = ${JSON.stringify(version)};`,
+    `const HAS_BLOCKING_HOOKS = ${blockingHooks.length > 0};`,
+    `const HOOKS = ${JSON.stringify(hooksData, null, 2)};`,
+    `const VALID_AGENTS = ['claude-code', 'cursor', 'windsurf', 'github-copilot', 'codex'];`,
+    ``,
+    `const argv = process.argv.slice(2);`,
+    `const command = argv[0];`,
+    `const agentIdx = argv.indexOf('--agent');`,
+    `const agent = agentIdx !== -1 ? argv[agentIdx + 1] : null;`,
+    `const silent = argv.includes('--silent');`,
+    ``,
+    `if (!['install', 'uninstall'].includes(command)) {`,
+    `  process.stderr.write('[mcpill] error: expected \\'install\\' or \\'uninstall\\', got \\'' + command + '\\'\\n');`,
+    `  process.exit(1);`,
+    `}`,
+    `if (!agent) {`,
+    `  process.stderr.write('[mcpill] error: --agent <target> is required\\n');`,
+    `  process.exit(1);`,
+    `}`,
+    `if (!VALID_AGENTS.includes(agent)) {`,
+    `  process.stderr.write('[mcpill] error: unknown agent \\'' + agent + '\\'. Valid targets: ' + VALID_AGENTS.join(', ') + '\\n');`,
+    `  process.exit(1);`,
+    `}`,
+    ``,
+    `const INDEX_PATH = resolve(__dirname, 'index.js');`,
+    `const GATE_PATH = resolve(__dirname, 'hooks', 'pre-tool-gate.js');`,
+    `const FLAG_PATH = resolve(__dirname, 'hooks', 'post-analysis-flag.js');`,
+    `const MCP_ENTRY = { command: 'node', args: [INDEX_PATH] };`,
+    `const STATE_FILE = join(homedir(), '.' + PILL_NAME, 'state.json');`
+  ].join("\n");
+  return constants + "\n" + INSTALL_JS_BODY;
+}
+function generateDistPackageJson(pillName, version, opts) {
+  const pkg2 = {
+    name: pillName,
+    version,
+    type: "module",
+    bin: { [pillName]: "install.js" },
+    dependencies: {
+      "mcpster": "*",
+      "mcpill-runtime": "*"
+    }
+  };
+  if (opts.postinstall) {
+    pkg2.scripts = { postinstall: `node install.js --agent claude-code --silent` };
+  }
+  return JSON.stringify(pkg2, null, 2) + "\n";
+}
+function emitStandalonePackage(baseDir, pillName, version, toolsJsContent, doc, blockingHooks, opts = {}) {
+  const distDir = join5(baseDir, ".mcpill", "dist", pillName);
+  const hooksDir = join5(distDir, "hooks");
+  mkdirSync3(hooksDir, { recursive: true });
+  const blockingHookTools = blockingHooks.filter((h) => h.required_tool).map((h) => h.required_tool);
+  writeFileSync3(join5(distDir, "package.json"), generateDistPackageJson(pillName, version, opts));
+  writeFileSync3(join5(distDir, "tools.js"), toolsJsContent);
+  writeFileSync3(
+    join5(distDir, "index.js"),
+    generateStandaloneIndexJs(pillName, version, doc.prompts, doc.resources, blockingHookTools)
+  );
+  writeFileSync3(join5(distDir, "install.js"), generateStandaloneInstallJs(pillName, version, blockingHooks));
+  if (blockingHooks.length > 0) {
+    writeFileSync3(join5(hooksDir, "pre-tool-gate.js"), generateStandaloneGateScript(pillName, blockingHooks));
+    writeFileSync3(join5(hooksDir, "post-analysis-flag.js"), generateStandaloneFlagScript(pillName));
+  }
+}
+
 // src/commands/compile.ts
 var zodTypeNameMap = {
   ZodString: "string",
@@ -1446,18 +2105,18 @@ ${r.content}`;
 }
 async function runCompile(opts) {
   const baseDir = resolve(opts.dir ?? process.cwd());
-  const mcpillDir = join5(baseDir, ".mcpill");
-  const serverDir = join5(mcpillDir, "server");
+  const mcpillDir = join6(baseDir, ".mcpill");
+  const serverDir = join6(mcpillDir, "server");
   if (opts.toMd) {
-    const configPath = join5(serverDir, "mcpill.config.json");
+    const configPath = join6(serverDir, "mcpill.config.json");
     if (!existsSync3(configPath)) {
       throw new Error("No pill found \u2014 run mcpill compile first");
     }
     const config = await loadConfig(serverDir);
     const resources = await loadResources(serverDir);
-    const promptsPath = join5(serverDir, "prompts.json");
+    const promptsPath = join6(serverDir, "prompts.json");
     const prompts = JSON.parse(readFileSync4(promptsPath, "utf-8"));
-    const toolsPath = join5(serverDir, "tools.js");
+    const toolsPath = join6(serverDir, "tools.js");
     const handlers = existsSync3(toolsPath) ? extractHandlers(readFileSync4(toolsPath, "utf-8")) : /* @__PURE__ */ new Map();
     let tools = [];
     if (existsSync3(toolsPath)) {
@@ -1491,11 +2150,13 @@ async function runCompile(opts) {
     return;
   }
   const doc = parseServerDir(mcpillDir);
-  const toolsJsPath = join5(serverDir, "tools.js");
+  const toolsJsPath = join6(serverDir, "tools.js");
   const existing = existsSync3(toolsJsPath) ? extractHandlers(readFileSync4(toolsJsPath, "utf-8")) : /* @__PURE__ */ new Map();
   const { doc: mergedDoc, stubbed } = mergeHandlers(doc, existing);
-  const pillMdPath = join5(baseDir, "PILL.md");
+  const pillMdPath = join6(baseDir, "PILL.md");
   let pillContent = null;
+  let pillVersion = "0.1.0";
+  let pillPostinstall = false;
   if (existsSync3(pillMdPath)) {
     pillContent = readFileSync4(pillMdPath, "utf-8");
     const serverSection = ("\n" + pillContent).split("\n## ").find((s) => s.startsWith("Server\n"));
@@ -1505,6 +2166,8 @@ async function runCompile(opts) {
       if (kv["transport"] === "stdio" || kv["transport"] === "http") {
         mergedDoc.config.transport = kv["transport"];
       }
+      if (kv["version"]) pillVersion = kv["version"].trim();
+      if (kv["postinstall"]?.trim().toLowerCase() === "true") pillPostinstall = true;
     }
   }
   if (opts.strict && stubbed.length > 0) {
@@ -1513,18 +2176,21 @@ async function runCompile(opts) {
   for (const name of stubbed) {
     console.warn(`\u26A0  Stub generated for tool: ${name}`);
   }
-  mkdirSync3(serverDir, { recursive: true });
-  writeFileSync3(join5(serverDir, "mcpill.config.json"), JSON.stringify(mergedDoc.config, null, 2));
-  writeFileSync3(join5(serverDir, "prompts.json"), JSON.stringify(mergedDoc.prompts, null, 2));
-  writeFileSync3(join5(serverDir, "resources.md"), serializeResourcesMd(mergedDoc.resources));
-  writeFileSync3(toolsJsPath, generateToolsJs(mergedDoc.tools));
+  mkdirSync4(serverDir, { recursive: true });
+  writeFileSync4(join6(serverDir, "mcpill.config.json"), JSON.stringify(mergedDoc.config, null, 2));
+  writeFileSync4(join6(serverDir, "prompts.json"), JSON.stringify(mergedDoc.prompts, null, 2));
+  writeFileSync4(join6(serverDir, "resources.md"), serializeResourcesMd(mergedDoc.resources));
+  const toolsJsContent = generateToolsJs(mergedDoc.tools);
+  writeFileSync4(toolsJsPath, toolsJsContent);
   ensureDeps(serverDir);
   console.log(`\u2713 .mcpill/server/ updated from .mcpill/server.md, .mcpill/server/tools/, .mcpill/server/prompts/`);
   if (opts.noHooks) {
-    writeFileSync3(join5(mcpillDir, ".no-hooks"), "");
+    writeFileSync4(join6(mcpillDir, ".no-hooks"), "");
+    emitStandalonePackage(baseDir, mergedDoc.config.name, pillVersion, toolsJsContent, mergedDoc, [], { postinstall: false });
+    console.log(`\u2713 .mcpill/dist/${mergedDoc.config.name}/ updated`);
     return;
   }
-  const agentMdPath = existsSync3(join5(baseDir, "AGENT.md")) ? join5(baseDir, "AGENT.md") : existsSync3(join5(mcpillDir, "AGENT.md")) ? join5(mcpillDir, "AGENT.md") : null;
+  const agentMdPath = existsSync3(join6(baseDir, "AGENT.md")) ? join6(baseDir, "AGENT.md") : existsSync3(join6(mcpillDir, "AGENT.md")) ? join6(mcpillDir, "AGENT.md") : null;
   const pillTools = pillContent ? parsePillMdTools(pillContent) : [];
   const agentTools = agentMdPath ? parseAgentMdTools(readFileSync4(agentMdPath, "utf-8")) : [];
   const toolMap = new Map([...pillTools, ...agentTools].map((t) => [t.name, t]));
@@ -1535,7 +2201,7 @@ async function runCompile(opts) {
     console.log(`\u2713 .claude/settings.json updated with PreToolUse hook`);
   }
   const pillHooks = pillContent ? parsePillMdHooks(pillContent) : [];
-  const hooksDir = join5(mcpillDir, "server", "hooks");
+  const hooksDir = join6(mcpillDir, "server", "hooks");
   const fileHooks = [];
   if (existsSync3(hooksDir)) {
     let hookFiles = [];
@@ -1544,15 +2210,34 @@ async function runCompile(opts) {
     } catch {
     }
     for (const file of hookFiles) {
-      const entry = parseHookFile(readFileSync4(join5(hooksDir, file), "utf-8"));
+      const entry = parseHookFile(readFileSync4(join6(hooksDir, file), "utf-8"));
       if (entry) fileHooks.push(entry);
     }
   }
   const allUserHooks = [...pillHooks, ...fileHooks];
-  if (allUserHooks.length > 0) {
-    mergeUserHooksIntoSettings(baseDir, allUserHooks);
-    console.log(`\u2713 .claude/settings.json updated with ${allUserHooks.length} user-defined hook(s)`);
+  const blockingHooks = allUserHooks.filter((h) => h.blocking);
+  const regularHooks = allUserHooks.filter((h) => !h.blocking);
+  for (const hook of blockingHooks) {
+    if (!hook.name) throw new Error(`blocking hook is missing a name`);
+    if (!hook.required_tool) throw new Error(`blocking hook '${hook.name}' is missing required_tool`);
+    const toolExists = mergedDoc.tools.some((t) => t.name === hook.required_tool);
+    if (!toolExists) {
+      throw new Error(`blocking hook '${hook.name}' references unknown tool '${hook.required_tool}'`);
+    }
+  }
+  if (regularHooks.length > 0) {
+    mergeUserHooksIntoSettings(baseDir, regularHooks);
+    console.log(`\u2713 .claude/settings.json updated with ${regularHooks.length} user-defined hook(s)`);
+  }
+  if (blockingHooks.length > 0) {
+    const generatedEntries = blockingHooks.flatMap(
+      (hook) => applyBlockingHookScripts(baseDir, mergedDoc.config.name, hook)
+    );
+    mergeUserHooksIntoSettings(baseDir, generatedEntries);
+    console.log(`\u2713 .claude/settings.json updated with ${blockingHooks.length} blocking hook(s)`);
   }
+  emitStandalonePackage(baseDir, mergedDoc.config.name, pillVersion, toolsJsContent, mergedDoc, blockingHooks, { postinstall: pillPostinstall });
+  console.log(`\u2713 .mcpill/dist/${mergedDoc.config.name}/ updated`);
 }
 
 // src/commands/pack.ts
@@ -1601,7 +2286,7 @@ async function runPublish(dir, access) {
 // src/cli.ts
 var pkgDir = dirname(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync5(join6(pkgDir, "../package.json"), "utf-8")
+  readFileSync5(join7(pkgDir, "../package.json"), "utf-8")
 );
 var program = new Command();
 program.name("mcpill").version(pkg.version);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpill",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "type": "module",
   "description": "CLI for building, validating, and publishing MCP servers using the pill format.",
   "homepage": "https://mcpill.ruco.dev",