vibe-forge 0.4.0 → 0.8.1

package/bin/lib/frontmatter.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * frontmatter.js - Safe YAML frontmatter field extractor
+ *
+ * Replaces grep/cut pipelines for extracting frontmatter fields from
+ * task and attention markdown files (RT-20260405-001 MEDIUM-5).
+ *
+ * Usage:
+ *   node frontmatter.js <file> <field1> [field2] ...
+ *   node frontmatter.js --section <file> <heading>
+ *
+ * Output (field mode):
+ *   field1=value1
+ *   field2=value2
+ *
+ * Output (section mode):
+ *   First non-heading line under the matched ## heading
+ *
+ * Values are sanitized for safe shell consumption:
+ *   - Shell metacharacters removed
+ *   - Length capped at 200 chars
+ *   - Missing fields output as empty: field=
+ */
+
+'use strict';
+
+const fs = require('fs');
+const yaml = require('js-yaml');
+
+const MAX_VALUE_LENGTH = 200;
+
+// Strip characters unsafe for shell interpolation
+function sanitize(val) {
+    if (val == null) return '';
+    const str = String(val)
+        .replace(/[\0\r]/g, '')
+        .replace(/[\n]/g, ' ')
+        .replace(/[$`"'\\(){}[\]!#;|&<>]/g, '')
+        .trim();
+    return str.substring(0, MAX_VALUE_LENGTH);
+}
+
+function extractFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match) return {};
+    try {
+        const parsed = yaml.load(match[1]);
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    } catch (_) {
+        return {};
+    }
+}
+
+function extractSection(content, heading) {
+    const pattern = new RegExp(`^## ${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'im');
+    const idx = content.search(pattern);
+    if (idx === -1) return '';
+    const after = content.substring(idx).split('\n').slice(1);
+    for (const line of after) {
+        if (line.startsWith('## ')) break;
+        const trimmed = line.trim();
+        if (trimmed) return sanitize(trimmed);
+    }
+    return '';
+}
+
+// Main
+const args = process.argv.slice(2);
+
+if (args.length < 2) {
+    process.stderr.write('Usage: node frontmatter.js <file> <field1> [field2] ...\n');
+    process.stderr.write('       node frontmatter.js --section <file> <heading>\n');
+    process.exit(1);
+}
+
+// Section mode: --section <file> <heading>
+if (args[0] === '--section') {
+    const file = args[1];
+    const heading = args[2];
+    if (!file || !heading) {
+        process.stderr.write('Usage: node frontmatter.js --section <file> <heading>\n');
+        process.exit(1);
+    }
+    let content;
+    try { content = fs.readFileSync(file, 'utf8'); } catch (_) { process.exit(0); }
+    process.stdout.write(extractSection(content, heading) + '\n');
+    process.exit(0);
+}
+
+// Field mode: <file> <field1> [field2] ...
+const file = args[0];
+const fields = args.slice(1);
+
+let content;
+try { content = fs.readFileSync(file, 'utf8'); } catch (_) {
+    // File unreadable: output empty values
+    for (const f of fields) process.stdout.write(`${f}=\n`);
+    process.exit(0);
+}
+
+const data = extractFrontmatter(content);
+
+for (const field of fields) {
+    const val = sanitize(data[field]);
+    process.stdout.write(`${field}=${val}\n`);
+}

package/bin/lib/heimdall-setup.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Heimdall Setup -- writes .claude/settings.local.json into a worker's
+ * working directory to register Heimdall as a PreToolUse hook.
+ *
+ * Called by the forge daemon at inbox-write time, before the worker
+ * picks up a lab task.
+ *
+ * Uses a merge strategy: if settings.local.json already exists, the
+ * Heimdall hooks are merged into the existing PreToolUse array rather
+ * than overwriting the file.
+ */
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+// Absolute path to heimdall.js -- resolvable from any working directory
+const HEIMDALL_PATH = path.resolve(__dirname, 'heimdall.js').replace(/\\/g, '/')
+
+const HEIMDALL_HOOKS = ['Bash', 'Write', 'Edit'].map(matcher => ({
+  matcher,
+  hooks: [{ type: 'command', command: `node "${HEIMDALL_PATH}"` }],
+}))
+
+/**
+ * writeHeimdallHooks(worktreePath)
+ *
+ * Writes or merges Heimdall PreToolUse hooks into:
+ *   <worktreePath>/.claude/settings.local.json
+ *
+ * Safe to call multiple times -- idempotent.
+ *
+ * @param {string} worktreePath  Absolute path to the worker's worktree root
+ */
+function writeHeimdallHooks(worktreePath) {
+  const claudeDir = path.join(worktreePath, '.claude')
+  const settingsPath = path.join(claudeDir, 'settings.local.json')
+
+  // Ensure .claude/ exists
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true })
+  }
+
+  // Read existing settings if present
+  let existing = {}
+  if (fs.existsSync(settingsPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(settingsPath, 'utf8'))
+    } catch (_) {
+      // Corrupt file -- start fresh
+      existing = {}
+    }
+  }
+
+  // Ensure hooks structure exists
+  if (!existing.hooks) existing.hooks = {}
+  if (!existing.hooks.PreToolUse) existing.hooks.PreToolUse = []
+
+  // Merge: add Heimdall hook entries for matchers not already registered
+  const existingMatchers = new Set(
+    existing.hooks.PreToolUse.map(h => h.matcher)
+  )
+
+  for (const heimdallHook of HEIMDALL_HOOKS) {
+    if (!existingMatchers.has(heimdallHook.matcher)) {
+      existing.hooks.PreToolUse.push(heimdallHook)
+    }
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + '\n')
+}
+
+/**
+ * writeContextFile(worktreePath, context)
+ *
+ * Writes the Heimdall context file to the worktree root so Heimdall
+ * can read per-task policy on every invocation.
+ *
+ * @param {string} worktreePath  Absolute path to the worker's worktree root
+ * @param {object} context       Context object matching the schema below
+ *
+ * Context schema:
+ * {
+ *   story_id:       string   -- lab story ID (e.g. "FORGE-3")
+ *   agent:          string   -- worker name (e.g. "anvil")
+ *   worktree_path:  string   -- absolute path to worktree (same as worktreePath)
+ *   assigned_branch: string  -- git branch for this story
+ *   handoff_dir:    string   -- absolute path to _vibe-chain-output/handoffs/
+ *   escalation_dir: string   -- absolute path to worker-inbox/<agent>/ dir
+ *   audit_log:      string   -- absolute path to heimdall-audit.log
+ *   has_db_migration: boolean
+ *   has_api_changes:  boolean
+ *   allowed_paths:  string[] -- absolute paths the worker may read/write
+ * }
+ */
+function writeContextFile(worktreePath, context) {
+  const contextPath = path.join(worktreePath, '.context.json')
+  fs.writeFileSync(contextPath, JSON.stringify(context, null, 2) + '\n')
+}
+
+/**
+ * setup(worktreePath, context)
+ *
+ * Convenience function: writes both hooks and context file in one call.
+ */
+function setup(worktreePath, context) {
+  writeHeimdallHooks(worktreePath)
+  writeContextFile(worktreePath, context)
+}
+
+module.exports = { setup, writeHeimdallHooks, writeContextFile, HEIMDALL_PATH }

package/bin/lib/heimdall.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+/**
+ * Heimdall -- Forge worker pre-tool hook interceptor (PLAT-1)
+ *
+ * Guards the Bifrost: intercepts every tool call before execution,
+ * checks it against per-task policy, and blocks or allows.
+ *
+ * Registered as a PreToolUse hook via .claude/settings.local.json
+ * written by the forge daemon at worker startup.
+ *
+ * Exit codes:
+ *   0 -- allow (optionally with audit log entry)
+ *   2 -- block (explanation written to stdout, fed back to model)
+ *
+ * Context file (.context.json in process.cwd()) is written by the forge
+ * daemon alongside each inbox task. If absent, Heimdall exits 0 immediately
+ * -- forge-native tasks are not restricted.
+ */
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+// ── Input ─────────────────────────────────────────────────────────────────────
+
+let input
+try {
+  input = JSON.parse(fs.readFileSync(0, 'utf8'))
+} catch (e) {
+  // Malformed input -- allow and exit rather than blocking the worker
+  process.exit(0)
+}
+
+const { tool_name, tool_input } = input
+
+// ── Context file ──────────────────────────────────────────────────────────────
+
+const contextPath = path.join(process.cwd(), '.context.json')
+
+// No context file = forge-native task. Heimdall does not restrict forge-native work.
+if (!fs.existsSync(contextPath)) {
+  process.exit(0)
+}
+
+let ctx
+try {
+  ctx = JSON.parse(fs.readFileSync(contextPath, 'utf8'))
+} catch (e) {
+  // Unreadable context -- fail open to avoid blocking forge-native work
+  process.exit(0)
+}
+
+const {
+  story_id,
+  agent,
+  worktree_path,
+  has_db_migration,
+  allowed_paths,
+  escalation_dir,
+  audit_log: ctxAuditLog,
+} = ctx
+
+// ── Logging ───────────────────────────────────────────────────────────────────
+
+const AUDIT_LOG = ctxAuditLog
+  || path.join(process.cwd(), '_vibe-chain-output', 'heimdall-audit.log')
+
+const MAX_VIOLATIONS = parseInt(process.env.HEIMDALL_MAX_VIOLATIONS || '3', 10)
+
+// Violation tracking lives in the worktree root (process.cwd())
+const VIOLATION_FILE = path.join(process.cwd(), `.${story_id}.violations`)
+
+// Escalation signal written to the inbox agent dir so the daemon detects it
+const ESCALATION_DIR = escalation_dir || process.cwd()
+
+function timestamp() {
+  return new Date().toISOString()
+}
+
+function audit(level, message) {
+  const line = `[${timestamp()}] HEIMDALL ${level} ${agent}/${story_id}: ${message}\n`
+  try {
+    const dir = path.dirname(AUDIT_LOG)
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+    fs.appendFileSync(AUDIT_LOG, line)
+  } catch (_) {
+    // Audit log write failure must never block or crash the hook
+  }
+}
+
+function block(reason) {
+  audit('BLOCKED', reason)
+
+  // Track violations
+  let violations = 0
+  try {
+    if (fs.existsSync(VIOLATION_FILE)) {
+      violations = parseInt(fs.readFileSync(VIOLATION_FILE, 'utf8').trim(), 10) || 0
+    }
+  } catch (_) {}
+
+  violations++
+
+  try {
+    fs.writeFileSync(VIOLATION_FILE, String(violations))
+  } catch (_) {}
+
+  if (violations >= MAX_VIOLATIONS) {
+    // Sound the Gjallarhorn
+    const escalationFile = path.join(ESCALATION_DIR, `${story_id}.escalation`)
+    try {
+      fs.writeFileSync(escalationFile, JSON.stringify({
+        story_id,
+        agent,
+        violations,
+        last_reason: reason,
+        timestamp: timestamp(),
+      }, null, 2))
+    } catch (_) {}
+
+    audit('SOUNDED', `${violations} violations -- escalating to human review`)
+
+    console.log(
+      `[HEIMDALL] Action blocked: ${reason}\n` +
+      `[HEIMDALL] GJALLARHORN SOUNDED: ${violations} violations recorded.\n` +
+      `[HEIMDALL] Story ${story_id} has been escalated to human review. Stop working on this story.`
+    )
+  } else {
+    console.log(
+      `[HEIMDALL] Action blocked: ${reason}\n` +
+      `[HEIMDALL] Violation ${violations}/${MAX_VIOLATIONS}. Self-correct and continue.`
+    )
+  }
+
+  process.exit(2)
+}
+
+function allow(note) {
+  if (note) audit('ALLOWED', note)
+  process.exit(0)
+}
+
+// ── Path helpers ──────────────────────────────────────────────────────────────
+
+function isOutsideAllowedPaths(targetPath) {
+  if (!targetPath) return false
+  try {
+    const resolved = path.resolve(targetPath)
+    return !allowed_paths.some(p => resolved.startsWith(path.resolve(p)))
+  } catch (_) {
+    return true // Unresolvable path -- treat as outside
+  }
+}
+
+// ── Bash tool checks ──────────────────────────────────────────────────────────
+
+if (tool_name === 'Bash') {
+  const cmd = (tool_input && tool_input.command || '').trim()
+
+  // Destructive rm -- check if target escapes worktree
+  if (/rm\s+-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r/.test(cmd) && /\brm\b/.test(cmd)) {
+    // Extract everything after the flags as the target
+    const rmMatch = cmd.match(/rm\s+(?:-\S+\s+)(.+)/)
+    const rmTarget = rmMatch ? rmMatch[1].trim().replace(/^['"]|['"]$/g, '') : ''
+
+    const isRootTarget = /^(\/|~)/.test(rmTarget) || rmTarget === '' || rmTarget.includes('..')
+    const isOutside = !rmTarget || isRootTarget || isOutsideAllowedPaths(rmTarget)
+
+    if (isOutside) {
+      block(`destructive rm outside worktree: ${cmd}`)
+    }
+  }
+
+  // Credential access
+  if (/\.(env|pem|key|cert)\b/.test(cmd) && !/\.env\.(example|sample|template)/.test(cmd)) {
+    block(`credential file access: ${cmd}`)
+  }
+  if (/~\/\.(ssh|aws|gnupg)\b/.test(cmd)) {
+    block(`credential directory access: ${cmd}`)
+  }
+  // Echoing or exporting secrets (but not reading them as part of build)
+  if (/(echo|printf|export)\s+.*\b(TOKEN|SECRET|PASSWORD|API_KEY)\s*=/.test(cmd)) {
+    block(`credential assignment in shell: ${cmd}`)
+  }
+
+  // Dangerous git operations
+  if (/git\s+push\b.*--force(-with-lease)?/.test(cmd)) {
+    block(`force push blocked: ${cmd}`)
+  }
+  if (/git\s+reset\s+--hard\s+HEAD~[2-9]/.test(cmd)) {
+    block(`multi-commit hard reset blocked: ${cmd}`)
+  }
+  if (/git\s+clean\s+-[a-zA-Z]*f[a-zA-Z]*d|-[a-zA-Z]*d[a-zA-Z]*f/.test(cmd) && /\bgit\b/.test(cmd)) {
+    block(`git clean -fd blocked: ${cmd}`)
+  }
+  // Push to a non-origin remote (e.g. git push upstream)
+  if (/git\s+push\s+(?!origin\b)(\S+)/.test(cmd)) {
+    const remoteMatch = cmd.match(/git\s+push\s+(\S+)/)
+    if (remoteMatch && remoteMatch[1] !== 'origin' && !remoteMatch[1].startsWith('-')) {
+      block(`push to non-origin remote blocked: ${cmd}`)
+    }
+  }
+  // Direct push to main/master — all changes must go through PRs
+  if (/git\s+push\b/.test(cmd) && /\b(main|master)\b/.test(cmd)) {
+    block(`direct push to main/master blocked — create a feature branch and open a PR`)
+  }
+
+  // DB destructive operations without authorization
+  if (/(DROP\s+TABLE|TRUNCATE\s+TABLE)/i.test(cmd) && !has_db_migration) {
+    block(`DROP/TRUNCATE requires has_db_migration: true on the story`)
+  }
+  if (/DELETE\s+FROM\s+\S+\s*;?\s*$/i.test(cmd) && !/WHERE\s+/i.test(cmd)) {
+    block(`DELETE without WHERE clause blocked: ${cmd}`)
+  }
+
+  // High-risk but legitimate -- audit log only
+  if (/\b(npm|yarn|pnpm)\s+(install|add|ci)\b/.test(cmd)) {
+    allow(`dependency install: ${cmd}`)
+  }
+  if (/\b(pip|pip3)\s+install\b/.test(cmd)) {
+    allow(`pip install: ${cmd}`)
+  }
+  if (/\bcargo\s+(build|install)\b/.test(cmd)) {
+    allow(`cargo build: ${cmd}`)
+  }
+  if (/\b(curl|wget)\b/.test(cmd)) {
+    allow(`network request: ${cmd}`)
+  }
+  if (/git\s+commit\s+--amend/.test(cmd)) {
+    allow(`git commit --amend`)
+  }
+}
+
+// ── Write / Edit tool checks ──────────────────────────────────────────────────
+
+if (tool_name === 'Write' || tool_name === 'Edit') {
+  const filePath = tool_input && (tool_input.file_path || tool_input.path) || ''
+
+  if (filePath) {
+    // Credential files
+    if (/\.(env|pem|key|cert)$/.test(filePath) && !/\.(example|sample|template)$/.test(filePath)) {
+      block(`write to credential file: ${filePath}`)
+    }
+
+    // Settings that could override Heimdall
+    if (/\.claude[/\\]settings(\.local)?\.json$/.test(filePath)) {
+      block(`write to .claude/settings blocked -- Heimdall config is daemon-managed`)
+    }
+
+    // Path escape check
+    if (isOutsideAllowedPaths(filePath)) {
+      block(`path escape: ${filePath} is outside allowed paths`)
+    }
+
+    // Pipeline output writes -- allowed but logged
+    if (filePath.includes('_vibe-chain-output')) {
+      allow(`pipeline output write: ${filePath}`)
+    }
+  }
+}
+
+// ── Default: allow ────────────────────────────────────────────────────────────
+
+allow(null)