mcpill 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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

@@ -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) {
@@ -1549,9 +1700,26 @@ async function runCompile(opts) {
     }
   }
   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)`);
   }
 }
 

package/package.json

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