@entelligentsia/forgecli 0.11.2 → 0.15.0

package/dist/forge-payload/hooks/forge-permissions.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// Forge permission auto-approver — runs on PermissionRequest events.
+//
+// Purpose: eliminate the permission prompt storm (BUG-014) by auto-approving
+// known Forge tool patterns and persisting allow rules to localSettings.
+//
+// Protocol (Claude Code PermissionRequest hook):
+//   - stdin: JSON envelope { tool_name, tool_input, permission_suggestions }
+//   - stdout: { hookSpecificOutput: { hookEventName, decision: { behavior,
+//     updatedPermissions } } } to allow and persist rules
+//   - exit 0 with no output: let normal permission flow proceed
+//   - exit 2 with stderr: block the tool call
+//
+// Security model:
+//   - This hook can only ALLOW, never DENY
+//   - User deny rules always take precedence over hook allows
+//   - Rules persist to .claude/settings.local.json (gitignored, per-project)
+//   - Users can inspect/remove rules via /permissions
+
+'use strict';
+
+process.on('uncaughtException', (err) => {
+  try { process.stderr.write(`forge-permissions: internal error (fail-open): ${err.message}\n`); } catch (_) {}
+  process.exit(0);
+});
+
+// ── Pattern registry ──────────────────────────────────────────────
+// Each entry: { pattern: RegExp, rule: string }
+// pattern matches against the tool input string (Bash command, file path, or URL)
+// rule is the allow rule content to persist via updatedPermissions
+
+const BASH_PATTERNS = [
+  // Node tool invocations — covers $FORGE_ROOT/tools/*.cjs and $CLAUDE_PLUGIN_ROOT
+  { pattern: /^node\s+.*\/tools\/[\w-]+\.(cjs|js)\b/, rule: 'node ~/.claude/plugins/cache/forge/forge/*/tools/*' },
+  // NOTE: node -e and node -p removed — arbitrary code execution must not be auto-approved.
+  // Forge workflows use node .../tools/*.cjs for tool invocations; inline node -e/p requires
+  // explicit user approval each time.
+  // Shell commands used by Forge workflows
+  { pattern: /^mkdir\s+-p\s+/, rule: 'mkdir -p .forge/*' },
+  { pattern: /^mkdir\s+-p\s+\S+/, rule: 'mkdir -p .forge/*' },
+  { pattern: /^cp\s+/, rule: 'cp */schemas/*.schema.json .forge/schemas/' },
+  { pattern: /^ls\s+/, rule: 'ls *' },
+  { pattern: /^cat\s+/, rule: 'cat .forge/*' },
+  { pattern: /^date\s+-u\s+/, rule: 'date -u *' },
+  { pattern: /^date\s+/, rule: 'date -u *' },
+  { pattern: /^jq\s+/, rule: 'jq *' },
+  { pattern: /^touch\s+/, rule: 'touch .forge/*' },
+  { pattern: /^uname\s+/, rule: 'uname *' },
+  { pattern: /^rm\s+\.forge/, rule: 'rm .forge/*' },
+  { pattern: /^rm\s+-rf\s+\.forge/, rule: 'rm -rf .forge/*' },
+  { pattern: /^rmdir\s+/, rule: 'rmdir .forge/*' },
+  { pattern: /^gh\s+auth\s+/, rule: 'gh auth status *' },
+  { pattern: /^gh\s+issue\s+/, rule: 'gh issue create *' },
+  // git read-only commands (already auto-approved by Claude Code, but belt-and-suspenders)
+  { pattern: /^git\s+status\b/, rule: 'git status *' },
+  { pattern: /^git\s+log\b/, rule: 'git log *' },
+  { pattern: /^git\s+diff\b/, rule: 'git diff *' },
+  { pattern: /^git\s+add\s+/, rule: 'git add *' },
+  { pattern: /^git\s+commit\s+-m\s+/, rule: 'git commit -m *' },
+  { pattern: /^git\s+push\b/, rule: 'git push *' },
+  { pattern: /^git\s+checkout\s+/, rule: 'git checkout *' },
+  { pattern: /^git\s+branch\s+/, rule: 'git branch *' },
+  { pattern: /^git\s+stash\b/, rule: 'git stash *' },
+  { pattern: /^git\s+worktree\s+/, rule: 'git worktree *' },
+];
+
+const WRITE_PATTERNS = [
+  { pattern: /^\.forge\//, rule: '.forge/**' },
+  { pattern: /^\.claude\/commands\//, rule: '.claude/commands/**' },
+  { pattern: /^engineering\//, rule: 'engineering/**' },
+  { pattern: /^CLAUDE\.md$/i, rule: 'CLAUDE.md' },
+  { pattern: /^AGENTS\.md$/i, rule: 'AGENTS.md' },
+  { pattern: /^\.gitignore$/, rule: '.gitignore' },
+];
+
+const EDIT_PATTERNS = [
+  { pattern: /^\.forge\//, rule: '.forge/**' },
+  { pattern: /^\.claude\/commands\//, rule: '.claude/commands/**' },
+  { pattern: /^engineering\//, rule: 'engineering/**' },
+  { pattern: /^CLAUDE\.md$/i, rule: 'CLAUDE.md' },
+  { pattern: /^AGENTS\.md$/i, rule: 'AGENTS.md' },
+];
+
+const WEBFETCH_PATTERNS = [
+  { pattern: /^https:\/\/raw\.githubusercontent\.com\/Entelligentsia\/forge\//, rule: 'domain:raw.githubusercontent.com' },
+];
+
+const PATTERN_MAP = {
+  Bash: BASH_PATTERNS,
+  Write: WRITE_PATTERNS,
+  Edit: EDIT_PATTERNS,
+  MultiEdit: EDIT_PATTERNS,
+  WebFetch: WEBFETCH_PATTERNS,
+};
+
+// ── Core logic ─────────────────────────────────────────────────────
+
+function matchTool(toolName, toolInput) {
+  const patterns = PATTERN_MAP[toolName];
+  if (!patterns) return null;
+
+  const input = toolName === 'Bash' ? (toolInput.command || '')
+    : (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') ? (toolInput.file_path || '')
+    : toolName === 'WebFetch' ? (toolInput.url || '')
+    : '';
+
+  for (const { pattern, rule } of patterns) {
+    if (pattern.test(input)) return rule;
+  }
+  return null;
+}
+
+// ── Export for testing ─────────────────────────────────────────────
+module.exports = { matchTool, BASH_PATTERNS, WRITE_PATTERNS, EDIT_PATTERNS, WEBFETCH_PATTERNS };
+
+// ── Main (hook runner) ────────────────────────────────────────────
+if (require.main === module) {
+let input = '';
+process.stdin.on('data', (d) => { input += d; });
+process.stdin.on('end', () => {
+  let event;
+  try {
+    event = JSON.parse(input);
+  } catch (_) {
+    // Unparseable input — fail open, let normal permission flow handle it
+    process.exit(0);
+  }
+
+  const { tool_name, tool_input } = event;
+  if (!tool_name || !tool_input) {
+    process.exit(0);
+  }
+
+  const matchedRule = matchTool(tool_name, tool_input || {});
+  if (matchedRule) {
+    // Persist only the matched rule — never bulk-approve all rules at once.
+    const response = {
+      hookSpecificOutput: {
+        hookEventName: 'PermissionRequest',
+        decision: {
+          behavior: 'allow',
+          updatedPermissions: [{
+            type: 'addRules',
+            rules: [{ toolName: tool_name, ruleContent: matchedRule }],
+            behavior: 'allow',
+            destination: 'localSettings',
+          }],
+        },
+      },
+    };
+    process.stdout.write(JSON.stringify(response));
+    process.exit(0);
+  }
+
+  // Not a Forge pattern — exit 0 with no output to let normal permission flow proceed
+  process.exit(0);
+});
+} // end require.main === module

package/dist/forge-payload/hooks/triage-error.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Forge PostToolUse hook — error triage
+//
+// Fires after every Bash tool call. If the command is Forge-related and
+// exits non-zero, injects an additionalContext prompt asking Claude to offer
+// the user the option to file a bug via /forge:report-bug.
+//
+// Uses only Node.js built-ins — no npm dependencies required.
+
+'use strict';
+
+const FORGE_PATTERNS = [
+  /manage-config/,
+  /\.forge\//,
+  /CLAUDE_PLUGIN_ROOT/,
+  /FORGE_ROOT/,
+  /MANAGE_CONFIG/,
+  /engineering\/tools\//,
+  /forge:init/,
+  /forge:health/,
+  /forge:regenerate/,
+  /forge:update/,
+  /forge:add-pipeline/,
+];
+
+function isForgeRelated(command) {
+  return FORGE_PATTERNS.some(p => p.test(command));
+}
+
+// The hook must never exit non-zero — a hook failure would surface as noise to
+// the user and defeat the purpose of silent triage. Wrap everything so that any
+// unexpected error causes a clean no-op exit instead of a crash report.
+process.on('uncaughtException', () => process.exit(0));
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { raw += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const event = JSON.parse(raw);
+
+    if (event.tool_name !== 'Bash') return;
+
+    const command = event.tool_input?.command || '';
+    const exitCode = event.tool_response?.exitCode;
+
+    // Only act on non-zero exits for Forge-related commands.
+    if (!isForgeRelated(command)) return;
+    if (exitCode === 0 || exitCode === undefined) return;
+
+    const stderr = event.tool_response?.stderr || '';
+    const output = event.tool_response?.output || '';
+    const errorSnippet = (stderr || output).split('\n').slice(0, 3).join(' ').trim();
+
+    const context =
+      `FORGE_ERROR_TRIAGE: A Forge command just failed (exit ${exitCode}). ` +
+      (errorSnippet ? `First error line: "${errorSnippet}". ` : '') +
+      `Tell the user what went wrong, then ask: ` +
+      `"Would you like to file this as a Forge bug to help improve the tool? ` +
+      `Run /forge:report-bug and I will pre-fill the report from this conversation."`;
+
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: context,
+      },
+    }) + '\n');
+  } catch {
+    // Swallow all errors — this hook must never become the problem.
+  }
+});

package/dist/forge-payload/hooks/validate-write.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+// Forge write-boundary hook — runs PreToolUse on Write / Edit / MultiEdit.
+//
+// Purpose: enforce Forge schemas at the filesystem boundary so agents remain
+// free to bypass deterministic tools (store-cli), as long as any write they
+// do against Forge-owned paths honors the schema contract.
+//
+// Protocol (Claude Code PreToolUse hook):
+//   - stdin: JSON envelope { tool_name, tool_input, ... }
+//   - exit 0: allow the tool call
+//   - exit 2 with stderr payload: block the tool call and surface the message
+//
+// Fail-open philosophy: any internal error (unreadable schema, parse bug,
+// unexpected tool input shape) exits 0 with a stderr warning. A broken
+// validator must never block legitimate work — validate-store.cjs remains
+// as a post-hoc auditor.
+
+'use strict';
+
+process.on('uncaughtException', (err) => {
+  try { process.stderr.write(`forge validate-write: internal error (fail-open): ${err.message}\n`); } catch (_) {}
+  process.exit(0);
+});
+
+const fs = require('fs');
+const path = require('path');
+
+const { matchRegistry } = require('./lib/write-registry.js');
+
+// Schema resolution order mirrors store-cli.cjs so the hook sees the exact
+// same schemas as tool writes do.
+const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || path.join(__dirname, '..');
+
+function resolveValidator() {
+  // store-cli's shared validator lives at forge/tools/lib/validate.js. Require
+  // it relative to the plugin root so the hook works from both dev tree and
+  // installed plugin cache.
+  const candidates = [
+    path.join(PLUGIN_ROOT, 'tools', 'lib', 'validate.js'),
+    path.join(__dirname, '..', 'tools', 'lib', 'validate.js'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return require(c);
+  }
+  throw new Error(`validate.js not found (looked in: ${candidates.join(', ')})`);
+}
+
+function loadSchema(filename) {
+  const candidates = [
+    path.join(process.cwd(), '.forge', 'schemas', filename),
+    path.join(process.cwd(), 'forge', 'schemas', filename),
+    path.join(PLUGIN_ROOT, 'schemas', filename),
+    path.join(__dirname, '..', 'schemas', filename),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) {
+      return JSON.parse(fs.readFileSync(c, 'utf8'));
+    }
+  }
+  throw new Error(`schema not found: ${filename}`);
+}
+
+function readStdinSync() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch (_) {
+    return '';
+  }
+}
+
+// Apply Edit semantics: replace old_string with new_string in contents.
+// If replace_all is true, replace every occurrence; otherwise replace the
+// first (and only) occurrence. Errors if old_string is absent or ambiguous
+// when replace_all is false — mirrors the Edit tool contract.
+function applyEdit(contents, oldStr, newStr, replaceAll) {
+  if (oldStr === '' && contents === '') return newStr; // new-file Edit
+  if (oldStr === '') throw new Error('Edit: old_string is empty');
+  if (replaceAll) return contents.split(oldStr).join(newStr);
+  const idx = contents.indexOf(oldStr);
+  if (idx === -1) throw new Error('Edit: old_string not found in file');
+  const next = contents.indexOf(oldStr, idx + oldStr.length);
+  if (next !== -1) throw new Error('Edit: old_string is ambiguous (appears more than once)');
+  return contents.slice(0, idx) + newStr + contents.slice(idx + oldStr.length);
+}
+
+function computePostEditContents(toolName, toolInput) {
+  const filePath = toolInput.file_path;
+  if (toolName === 'Write') {
+    return { filePath, contents: toolInput.content != null ? String(toolInput.content) : '' };
+  }
+  const prior = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  if (toolName === 'Edit') {
+    return {
+      filePath,
+      contents: applyEdit(prior, toolInput.old_string || '', toolInput.new_string || '', !!toolInput.replace_all),
+    };
+  }
+  // MultiEdit
+  let cur = prior;
+  const edits = Array.isArray(toolInput.edits) ? toolInput.edits : [];
+  for (const e of edits) {
+    cur = applyEdit(cur, e.old_string || '', e.new_string || '', !!e.replace_all);
+  }
+  return { filePath, contents: cur, prior };
+}
+
+function parseProgressLine(line) {
+  // timestamp|agentName|bannerKey|status|detail
+  const parts = line.split('|');
+  if (parts.length < 4) return null;
+  return {
+    timestamp: parts[0],
+    agentName: parts[1],
+    bannerKey: parts[2],
+    status:    parts[3],
+    detail:    parts.slice(4).join('|'),
+  };
+}
+
+function validateProgressAppend(prior, proposed, validator, schema) {
+  // Only validate lines that are NEW — anything already on disk is grandfathered.
+  if (!proposed.startsWith(prior)) {
+    // Wholesale rewrite, not an append. Validate every non-empty line.
+    const lines = proposed.split('\n').filter(l => l.length > 0);
+    return lines.flatMap((l, i) => annotateLine(validator, schema, l, i));
+  }
+  const suffix = proposed.slice(prior.length);
+  const newLines = suffix.split('\n').filter(l => l.length > 0);
+  return newLines.flatMap((l, i) => annotateLine(validator, schema, l, i));
+}
+
+function annotateLine(validator, schema, line, idx) {
+  const rec = parseProgressLine(line);
+  if (!rec) return [`line ${idx + 1}: malformed (expected 4+ pipe-delimited fields)`];
+  const errors = validator.validateRecord(rec, schema);
+  return errors.map(e => `line ${idx + 1}: ${e}`);
+}
+
+function writeBypassAudit(filePath, reason) {
+  try {
+    const m = /\/\.forge\/store\/events\/([^/]+)\//.exec(filePath) || /\.forge\/store\/events\/([^/]+)\//.exec(filePath);
+    const bucket = m ? m[1] : 'unknown';
+    const logPath = path.join(process.cwd(), '.forge', 'store', 'events', bucket, 'progress.log');
+    if (!fs.existsSync(path.dirname(logPath))) return;
+    const ts = new Date().toISOString();
+    const line = `${ts}|forge-hook|write-boundary|progress|${reason}\n`;
+    fs.appendFileSync(logPath, line, 'utf8');
+  } catch (_) { /* audit best-effort */ }
+}
+
+function block(message) {
+  process.stderr.write(message + '\n');
+  process.exit(2);
+}
+
+function main() {
+  const raw = readStdinSync();
+  if (!raw) process.exit(0);
+
+  let envelope;
+  try { envelope = JSON.parse(raw); } catch (_) { process.exit(0); }
+
+  const toolName = envelope.tool_name;
+  if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) process.exit(0);
+
+  const toolInput = envelope.tool_input || {};
+  const filePath = toolInput.file_path;
+  if (!filePath || typeof filePath !== 'string') process.exit(0);
+
+  const entry = matchRegistry(filePath);
+  if (!entry) process.exit(0);
+
+  if (process.env.FORGE_SKIP_WRITE_VALIDATION === '1') {
+    writeBypassAudit(filePath, `FORGE_SKIP_WRITE_VALIDATION=1 bypass on ${toolName} ${path.relative(process.cwd(), filePath)}`);
+    process.exit(0);
+  }
+
+  let validator, schema, post;
+  try {
+    validator = resolveValidator();
+    schema = loadSchema(entry.schema);
+    post = computePostEditContents(toolName, toolInput);
+  } catch (err) {
+    process.stderr.write(`forge validate-write: setup error (fail-open): ${err.message}\n`);
+    process.exit(0);
+  }
+
+  const relPath = path.relative(process.cwd(), post.filePath);
+
+  if (entry.format === 'line-pipe-delimited') {
+    const prior = post.prior != null ? post.prior : (fs.existsSync(post.filePath) ? fs.readFileSync(post.filePath, 'utf8') : '');
+    const errs = validateProgressAppend(prior, post.contents, validator, schema);
+    if (errs.length > 0) {
+      block(
+        '❌ Forge schema violation — write blocked\n' +
+        `Path: ${relPath}\n` +
+        `Kind: ${entry.kind}\n` +
+        `Violations:\n  - ${errs.join('\n  - ')}\n` +
+        `Hint: progress.log lines must be "timestamp|agentName|bannerKey|status|detail"; see forge/schemas/${entry.schema}.\n` +
+        'To bypass for one turn (emergency repair): FORGE_SKIP_WRITE_VALIDATION=1.'
+      );
+    }
+    process.exit(0);
+  }
+
+  // JSON payloads
+  let parsed;
+  try {
+    parsed = JSON.parse(post.contents);
+  } catch (err) {
+    block(
+      '❌ Forge schema violation — write blocked\n' +
+      `Path: ${relPath}\n` +
+      `Kind: ${entry.kind}\n` +
+      `Violation: Invalid JSON: ${err.message}\n` +
+      `Hint: see forge/schemas/${entry.schema} for the expected shape.\n` +
+      'To bypass for one turn (emergency repair): FORGE_SKIP_WRITE_VALIDATION=1.'
+    );
+  }
+
+  const errs = validator.validateRecord(parsed, schema);
+  if (errs.length > 0) {
+    block(
+      '❌ Forge schema violation — write blocked\n' +
+      `Path: ${relPath}\n` +
+      `Kind: ${entry.kind}\n` +
+      `Violations:\n  - ${errs.join('\n  - ')}\n` +
+      `Hint: see forge/schemas/${entry.schema} for the full shape.\n` +
+      'To bypass for one turn (emergency repair): FORGE_SKIP_WRITE_VALIDATION=1.'
+    );
+  }
+
+  process.exit(0);
+}
+
+main();

package/dist/forge-payload/integrity.json

@@ -0,0 +1,32 @@
+{
+  "version": "0.46.1",
+  "generated": "2026-05-22",
+  "note": "Tamper-evident only. Authoritative source: /forge:update from remote.",
+  "files": {
+    "commands/add-pipeline.md": "402c1deb6f19ad99561b48548ad89e3e1f625b827dce633eb84317556c0a1a4a",
+    "commands/add-task.md": "b2640c4b3c8c4fb9d4a82633d8c4d8fcd13bd63d4d6deb2c5c6a2008508de770",
+    "commands/ask.md": "df15f0aa68c93d65bfef05adb514c377bfc65617cafcd79534eb9b4149302657",
+    "commands/calibrate.md": "c764e735c9212eaf785d3d0afaf926f536fef099421b2b1bde7a4b1e3114d443",
+    "commands/config.md": "67251316b806d706bb77f063128e29995c6b4abaf554f4d5558bd97a1a6cfcfe",
+    "commands/enhance.md": "4bbfc05cf85c862c49883bc36f1272f87cd49c8cbe00f9196e76d542e6eaa720",
+    "commands/health.md": "cf8a59cfb403ba268922bc60abcdd9255a3b5690ae0175bb2819b3f6789debc0",
+    "commands/init.md": "3c0522294c692e8fbb75f925370caee66f54b23d7dd3a692bedcd69f95718b28",
+    "commands/materialize.md": "195292c9e98f50773c1b0c84f9bbc42438c4c8c989a84bd98092f6692799d6d6",
+    "commands/migrate.md": "b226f10a6f202bfd4a840314f34d503da34a077abbf1dff8d2b40f864474a76b",
+    "commands/quiz-agent.md": "ed261a5c8ac7cd3a1d7c8b372c9bf099bba9a4f9dc0a41cb5c80f22b57a133a1",
+    "commands/regenerate.md": "7c14f87b1bb178dd98ebdf0efafb86792c2b8b079bc5052d02a7e618165ec525",
+    "commands/remove.md": "de8802ee8ad5db4c4f3d0f526eb8735ab7de1a4b8ad307355d11dac5e1e04fc6",
+    "commands/report-bug.md": "af8a54bf8887b35e5c880898dd45783f6c2e80d3dc031d6479a6be613ac43053",
+    "commands/store-query.md": "28925bd257ceb6645254628abf0e76524481460382192ea00081b17310b88fed",
+    "commands/store-repair.md": "9317be65deb400953b8642b4d353d5583d3b032546c0b8f73d6c3a9b3445ebdd",
+    "commands/update-tools.md": "768c0d7ec07a17055c3d4b1b31370812f4292e03b1496723ba36f8caf596a609",
+    "commands/update.md": "6f7be76884888b0cbbe5e60a6926bbaa368f2ee3191f2be40adc8d263ad414aa",
+    "agents/store-query-validator.md": "f4c3573edcf6e28809515705362df611806a805c5269404fb17e31433cf3a81c",
+    "agents/tomoshibi.md": "0112604af0856235d7f028683dbfa3f4af63355cb2dd79d26592e983a6ecec8b",
+    "hooks/check-update.js": "75a70718d088b7c92ac0343908d07c2eb3bb334c427947490af1d775790859e1",
+    "hooks/forge-permissions.js": "d72fe4a7f010d363798680fa6afeb004f8747e2479ebdf653bc2200c9be073dc",
+    "hooks/triage-error.js": "b1e9c1c9a9f3e4868fff295f2caf87a2a72a817ee767af35f6334c88e45e16d4",
+    "hooks/validate-write.js": "bf17f740ae43d85a7f4b18bc08e2628534c3698ec5202cb51ebd3f0792375f24",
+    "tools/verify-integrity.cjs": "3ec3c970dd3d7c3001f8f373bcc40556803eadd2fc2afafb14f1c232cba4cc3f"
+  }
+}