@whitehatd/crag 0.0.1 → 0.2.0

package/src/compile/github-actions.js

@@ -0,0 +1,165 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { gateToShell } = require('../governance/gate-to-shell');
+const { flattenGatesRich } = require('../governance/parse');
+const { atomicWrite } = require('./atomic-write');
+
+/**
+ * Extract the major Node version from package.json engines.node field.
+ * Handles formats: ">=18.0.0", "^18", "18.x", "18.0.0", ">=18 <21".
+ * Returns a string like "18" or null if not found.
+ */
+function detectNodeVersion(cwd) {
+  try {
+    const pkgPath = path.join(cwd, 'package.json');
+    if (!fs.existsSync(pkgPath)) return null;
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    const engines = pkg.engines?.node;
+    if (!engines || typeof engines !== 'string') return null;
+    const m = engines.match(/(\d+)/);
+    return m ? m[1] : null;
+  } catch { return null; }
+}
+
+/**
+ * Detect Python version from pyproject.toml requires-python field.
+ */
+function detectPythonVersion(cwd) {
+  try {
+    const pyprojectPath = path.join(cwd, 'pyproject.toml');
+    if (!fs.existsSync(pyprojectPath)) return null;
+    const content = fs.readFileSync(pyprojectPath, 'utf-8');
+    const m = content.match(/requires-python\s*=\s*["'][^0-9]*(\d+\.\d+)/);
+    return m ? m[1] : null;
+  } catch { return null; }
+}
+
+/**
+ * Detect Java version from build.gradle.kts or pom.xml.
+ */
+function detectJavaVersion(cwd) {
+  try {
+    const gradle = path.join(cwd, 'build.gradle.kts');
+    if (fs.existsSync(gradle)) {
+      const content = fs.readFileSync(gradle, 'utf-8');
+      const m = content.match(/JavaVersion\.VERSION_(\d+)|languageVersion\s*=\s*JavaLanguageVersion\.of\((\d+)\)|jvmToolchain\((\d+)\)/);
+      if (m) return m[1] || m[2] || m[3];
+    }
+    const pom = path.join(cwd, 'pom.xml');
+    if (fs.existsSync(pom)) {
+      const content = fs.readFileSync(pom, 'utf-8');
+      const m = content.match(/<maven\.compiler\.source>(\d+)|<java\.version>(\d+)/);
+      if (m) return m[1] || m[2];
+    }
+  } catch { /* skip */ }
+  return null;
+}
+
+/**
+ * Detect Go version from go.mod.
+ */
+function detectGoVersion(cwd) {
+  try {
+    const goMod = path.join(cwd, 'go.mod');
+    if (!fs.existsSync(goMod)) return null;
+    const content = fs.readFileSync(goMod, 'utf-8');
+    const m = content.match(/^go\s+(\d+\.\d+)/m);
+    return m ? m[1] : null;
+  } catch { return null; }
+}
+
+function generateGitHubActions(cwd, parsed) {
+  const dir = path.join(cwd, '.github', 'workflows');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  // Detect versions from project files, fall back to current LTS defaults
+  const nodeVersion = detectNodeVersion(cwd) || '22';
+  const pythonVersion = detectPythonVersion(cwd) || '3.12';
+  const javaVersion = detectJavaVersion(cwd) || '21';
+  const goVersion = detectGoVersion(cwd) || '1.22';
+
+  let setupSteps = '';
+  if (parsed.runtimes.includes('node')) {
+    setupSteps += '      - name: Setup Node.js\n';
+    setupSteps += '        uses: actions/setup-node@v4\n';
+    setupSteps += `        with:\n          node-version: '${nodeVersion}'\n`;
+    setupSteps += '      - run: npm ci\n';
+  }
+  if (parsed.runtimes.includes('rust')) {
+    setupSteps += '      - name: Setup Rust\n';
+    setupSteps += '        uses: dtolnay/rust-toolchain@stable\n';
+  }
+  if (parsed.runtimes.includes('python')) {
+    setupSteps += '      - name: Setup Python\n';
+    setupSteps += '        uses: actions/setup-python@v5\n';
+    setupSteps += `        with:\n          python-version: '${pythonVersion}'\n`;
+    setupSteps += '      - run: pip install -r requirements.txt 2>/dev/null || true\n';
+  }
+  if (parsed.runtimes.includes('java')) {
+    setupSteps += '      - name: Setup Java\n';
+    setupSteps += '        uses: actions/setup-java@v4\n';
+    setupSteps += `        with:\n          distribution: temurin\n          java-version: '${javaVersion}'\n`;
+  }
+  if (parsed.runtimes.includes('go')) {
+    setupSteps += '      - name: Setup Go\n';
+    setupSteps += '        uses: actions/setup-go@v5\n';
+    setupSteps += `        with:\n          go-version: '${goVersion}'\n`;
+  }
+
+  // Escape for YAML double-quoted scalar: \, ", and control chars.
+  const yamlDqEscape = (s) => String(s)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\r/g, '\\r')
+    .replace(/\n/g, '\\n')
+    .replace(/\t/g, '\\t');
+
+  let gateSteps = '';
+  for (const gate of flattenGatesRich(parsed.gates)) {
+    const shell = gateToShell(gate.cmd);
+    const label = gate.cmd.length > 60 ? gate.cmd.substring(0, 57) + '...' : gate.cmd;
+    const prefix = gate.classification !== 'MANDATORY' ? `[${gate.classification}] ` : '';
+    const condExpr = gate.condition ? ` (if: ${gate.condition})` : '';
+    const workDir = gate.path ? `\n        working-directory: ${gate.path}` : '';
+    const contOnErr = (gate.classification === 'OPTIONAL' || gate.classification === 'ADVISORY')
+      ? '\n        continue-on-error: true' : '';
+    const ifGuard = gate.condition
+      ? `\n        if: hashFiles('${gate.condition}') != ''` : '';
+    gateSteps += `      - name: "${prefix}${yamlDqEscape(gate.section)}: ${yamlDqEscape(label)}${yamlDqEscape(condExpr)}"${ifGuard}${workDir}${contOnErr}\n`;
+    gateSteps += `        run: |\n          ${shell.replace(/\n/g, '\n          ')}\n`;
+  }
+
+  const yaml = [
+    '# Generated from governance.md by crag',
+    '# Regenerate: crag compile --target github',
+    'name: Governance Gates',
+    '',
+    'on:',
+    '  push:',
+    '    branches: [main, master]',
+    '  pull_request:',
+    '    branches: [main, master]',
+    '',
+    'jobs:',
+    '  gates:',
+    '    name: Governance Gates',
+    '    runs-on: ubuntu-latest',
+    '    steps:',
+    '      - uses: actions/checkout@v4',
+    setupSteps + gateSteps,
+  ].join('\n');
+
+  const outPath = path.join(dir, 'gates.yml');
+  atomicWrite(outPath, yaml);
+  console.log(`  \x1b[32m✓\x1b[0m ${path.relative(cwd, outPath)}`);
+}
+
+module.exports = {
+  generateGitHubActions,
+  detectNodeVersion,
+  detectPythonVersion,
+  detectJavaVersion,
+  detectGoVersion,
+};

package/src/compile/husky.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { gateToShell } = require('../governance/gate-to-shell');
+const { flattenGatesRich } = require('../governance/parse');
+const { atomicWrite } = require('./atomic-write');
+
+function generateHusky(cwd, parsed) {
+  const dir = path.join(cwd, '.husky');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  // Group gates by section for readable output
+  const sections = new Map();
+  for (const gate of flattenGatesRich(parsed.gates)) {
+    if (!sections.has(gate.section)) sections.set(gate.section, []);
+    sections.get(gate.section).push(gate);
+  }
+
+  let body = '';
+  for (const [section, gates] of sections) {
+    body += `# ${section}\n`;
+    for (const gate of gates) {
+      const shell = gateToShell(gate.cmd);
+      // Quote path/condition for shell safety
+      const quotedPath = gate.path ? gate.path.replace(/"/g, '\\"') : null;
+      const quotedCond = gate.condition ? gate.condition.replace(/"/g, '\\"') : null;
+
+      // Build the core command (with cd if path-scoped)
+      const coreCmd = quotedPath ? `(cd "${quotedPath}" && ${shell})` : shell;
+
+      // Build failure handler based on classification
+      let onFail;
+      if (gate.classification === 'OPTIONAL' || gate.classification === 'ADVISORY') {
+        const escLabel = shell.replace(/"/g, '\\"');
+        onFail = `echo "  [${gate.classification}] Gate failed: ${escLabel}"`;
+      } else {
+        onFail = 'exit 1';
+      }
+
+      // Wrap in conditional if section has `if:` annotation — skip cleanly if file missing
+      if (quotedCond) {
+        body += `if [ -e "${quotedCond}" ]; then ${coreCmd} || ${onFail}; fi\n`;
+      } else {
+        body += `${coreCmd} || ${onFail}\n`;
+      }
+    }
+    body += '\n';
+  }
+
+  const script = [
+    '#!/bin/sh',
+    '# Generated from governance.md by crag',
+    '# Regenerate: crag compile --target husky',
+    'set -e',
+    '',
+    body.trim(),
+    '',
+  ].join('\n');
+
+  const outPath = path.join(dir, 'pre-commit');
+  atomicWrite(outPath, script);
+  console.log(`  \x1b[32m✓\x1b[0m ${path.relative(cwd, outPath)}`);
+}
+
+module.exports = { generateHusky };

package/src/compile/pre-commit.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { gateToShell } = require('../governance/gate-to-shell');
+const { flattenGatesRich } = require('../governance/parse');
+const { atomicWrite } = require('./atomic-write');
+
+function generatePreCommitConfig(cwd, parsed) {
+  const gates = flattenGatesRich(parsed.gates);
+
+  let hooks = '';
+  gates.forEach((gate, i) => {
+    const id = `gate-${i + 1}`;
+    const prefix = gate.classification !== 'MANDATORY' ? `[${gate.classification}] ` : '';
+    const name = `${prefix}${gate.section}: ${gate.cmd}`;
+    const truncated = name.length > 60 ? name.substring(0, 57) + '...' : name;
+
+    let shell = gateToShell(gate.cmd);
+    if (gate.path) shell = `cd "${gate.path}" && ${shell}`;
+    if (gate.condition) shell = `[ -e "${gate.condition}" ] && (${shell}) || true`;
+    // For OPTIONAL/ADVISORY: never fail the hook
+    if (gate.classification === 'OPTIONAL' || gate.classification === 'ADVISORY') {
+      shell = `(${shell}) || echo "[${gate.classification}] failed — continuing"`;
+    }
+
+    hooks += `      - id: ${id}\n`;
+    hooks += `        name: "${truncated.replace(/"/g, '\\"')}"\n`;
+    hooks += `        entry: bash -c '${shell.replace(/'/g, "'\\''")}'\n`;
+    hooks += '        language: system\n';
+    hooks += '        pass_filenames: false\n';
+    hooks += '        always_run: true\n';
+  });
+
+  const yaml = [
+    '# Generated from governance.md by crag',
+    '# Regenerate: crag compile --target pre-commit',
+    'repos:',
+    '  - repo: local',
+    '    hooks:',
+    hooks.trimEnd(),
+    '',
+  ].join('\n');
+
+  const outPath = path.join(cwd, '.pre-commit-config.yaml');
+  atomicWrite(outPath, yaml);
+  console.log(`  \x1b[32m✓\x1b[0m ${path.relative(cwd, outPath)}`);
+}
+
+module.exports = { generatePreCommitConfig };

package/src/compile/windsurf.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const path = require('path');
+const { flattenGatesRich } = require('../governance/parse');
+const { atomicWrite } = require('./atomic-write');
+
+/**
+ * Compile governance.md to Windsurf rules.
+ * Output: .windsurfrules
+ *
+ * Windsurf (by Codeium) is an AI-native IDE with a Cascade agent mode.
+ * It reads `.windsurfrules` at the workspace root for project-level guidance.
+ *
+ * Reference:
+ *   https://docs.windsurf.com/windsurf/cascade/memories#rules
+ */
+function generateWindsurf(cwd, parsed) {
+  const gates = flattenGatesRich(parsed.gates);
+
+  const gatesList = gates.length === 0
+    ? '(none defined)'
+    : gates
+        .map((g, i) => {
+          const prefix = g.classification !== 'MANDATORY' ? ` [${g.classification}]` : '';
+          const scope = g.path ? ` (in ${g.path})` : '';
+          return `${i + 1}. \`${g.cmd}\`${scope}${prefix}`;
+        })
+        .join('\n');
+
+  const content = `# Windsurf Rules — ${parsed.name || 'project'}
+
+Generated from governance.md by crag. Regenerate: \`crag compile --target windsurf\`
+
+## Project
+
+${parsed.description || '(No description)'}
+
+## Runtimes
+
+${parsed.runtimes.join(', ') || 'polyglot — detected at runtime'}
+
+## Cascade Behavior
+
+When Windsurf's Cascade agent operates on this project:
+
+- **Always read governance.md first.** It is the single source of truth for quality gates and policies.
+- **Run all mandatory gates before proposing changes.** Stop on first failure.
+- **Respect classifications.** OPTIONAL gates warn but don't block. ADVISORY gates are informational.
+- **Respect path scopes.** Gates with a \`path:\` annotation must run from that directory.
+- **No destructive commands.** Never run rm -rf, dd, DROP TABLE, force-push to main, curl|bash, docker system prune.
+- **No secrets.** Reject any code matching \`sk_live\`, \`sk_test\`, \`AKIA\`, or plaintext credentials.
+- **Conventional commits.** Every commit must follow \`<type>(<scope>): <description>\`.
+
+## Quality Gates (run in order)
+
+${gatesList}
+
+## Rules of Engagement
+
+1. **Minimal changes.** Don't rewrite files that weren't asked to change.
+2. **No new dependencies** without explicit approval.
+3. **Prefer editing** existing files over creating new ones.
+4. **Always explain** non-obvious changes in commit messages.
+5. **Ask before** destructive operations (delete, rename, migrate schema).
+
+---
+
+**Tool:** crag — https://www.npmjs.com/package/@whitehatd/crag
+`;
+
+  const outPath = path.join(cwd, '.windsurfrules');
+  atomicWrite(outPath, content);
+  console.log(`  \x1b[32m✓\x1b[0m ${path.relative(cwd, outPath)}`);
+}
+
+module.exports = { generateWindsurf };

package/src/compile/zed.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const path = require('path');
+const { flattenGatesRich } = require('../governance/parse');
+const { atomicWrite } = require('./atomic-write');
+
+/**
+ * Compile governance.md to Zed Editor assistant prompts.
+ * Output: .zed/rules.md (read by Zed's AI assistant as project context)
+ *
+ * Zed is a high-performance multiplayer code editor with an integrated
+ * AI assistant. Project-level rules live in `.zed/` configuration.
+ *
+ * Reference:
+ *   https://zed.dev/docs/assistant/assistant
+ */
+function generateZed(cwd, parsed) {
+  const gates = flattenGatesRich(parsed.gates);
+
+  const gatesList = gates.length === 0
+    ? '_(none defined)_'
+    : gates
+        .map((g) => {
+          const tags = [];
+          if (g.classification !== 'MANDATORY') tags.push(g.classification);
+          if (g.path) tags.push(`path:${g.path}`);
+          if (g.condition) tags.push(`if:${g.condition}`);
+          return `- \`${g.cmd}\`${tags.length > 0 ? ` _(${tags.join(', ')})_` : ''}`;
+        })
+        .join('\n');
+
+  const content = `# Zed Assistant Rules — ${parsed.name || 'project'}
+
+> Generated from governance.md by crag. Regenerate: \`crag compile --target zed\`
+
+## Project Summary
+
+${parsed.description || '(No description)'}
+
+**Runtimes:** ${parsed.runtimes.join(', ') || 'polyglot'}
+
+## Rules for Zed AI Assistant
+
+When suggesting edits or running the inline assistant:
+
+### 1. Quality Gates
+
+These must pass before any commit. Run them via Zed's terminal integration:
+
+${gatesList}
+
+### 2. Classification Semantics
+
+- **MANDATORY** — stop if this fails
+- **OPTIONAL** — warn and continue
+- **ADVISORY** — log and continue (informational)
+
+### 3. Scope Rules
+
+- \`path:dir/\` — run the gate from that directory
+- \`if:file\` — skip the gate's section when the file does not exist
+
+### 4. Behavior Boundaries
+
+- All file operations must stay within this repository.
+- Never run destructive system commands (\`rm -rf /\`, \`DROP TABLE\`, \`curl|bash\`, force-push to main).
+- Never commit hardcoded secrets. Grep for \`sk_live\`, \`sk_test\`, \`AKIA\`, \`password=\` before commit.
+- Use conventional commits (\`feat:\`, \`fix:\`, \`docs:\`, etc.).
+
+### 5. Authoritative Source
+
+When these rules conflict with ad-hoc instructions, **governance.md wins**. It is the single source of truth for this project's policies.
+
+---
+
+**Generated by crag** — https://www.npmjs.com/package/@whitehatd/crag
+
+To update these rules, edit \`.claude/governance.md\` and re-run \`crag compile --target zed\`.
+`;
+
+  const outPath = path.join(cwd, '.zed', 'rules.md');
+  atomicWrite(outPath, content);
+  console.log(`  \x1b[32m✓\x1b[0m ${path.relative(cwd, outPath)}`);
+}
+
+module.exports = { generateZed };