@whitehatd/crag 0.0.1 → 0.2.1

package/src/commands/workspace.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { detectWorkspace } = require('../workspace/detect');
+const { enumerateMembers } = require('../workspace/enumerate');
+const { loadGovernanceHierarchy } = require('../workspace/governance');
+
+/**
+ * crag workspace — inspect the detected workspace.
+ * Prints workspace type, root, all members with their stacks and governance status.
+ */
+function workspace(args) {
+  const json = args.includes('--json');
+  const cwd = process.cwd();
+
+  const ws = detectWorkspace(cwd);
+
+  if (ws.type === 'none') {
+    if (json) {
+      console.log(JSON.stringify({ type: 'none', root: ws.root, members: [] }, null, 2));
+      return;
+    }
+    console.log(`\n  No workspace detected.`);
+    console.log(`  Root: ${ws.root}`);
+    console.log(`  crag works fine without a workspace — it just won't enumerate members.\n`);
+    return;
+  }
+
+  const members = enumerateMembers(ws);
+  const hierarchy = loadGovernanceHierarchy(ws, members);
+
+  if (json) {
+    const output = {
+      type: ws.type,
+      root: ws.root,
+      configFile: ws.configFile,
+      memberCount: members.length,
+      warnings: ws.warnings || [],
+      members: members.map(m => ({
+        name: m.name,
+        path: m.relativePath,
+        stack: m.stack,
+        hasGovernance: m.hasGovernance,
+        hasGit: m.hasGit,
+        inheritsFromRoot: hierarchy.members[m.name]?.inherit === 'root',
+      })),
+      rootGovernance: hierarchy.root ? {
+        name: hierarchy.root.name,
+        gatesCount: Object.keys(hierarchy.root.gates).length,
+        runtimes: hierarchy.root.runtimes,
+      } : null,
+    };
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  console.log(`\n  Workspace: \x1b[36m${ws.type}\x1b[0m`);
+  console.log(`  Root: ${ws.root}`);
+  if (ws.configFile) console.log(`  Config: ${ws.configFile}`);
+  console.log(`  Members: ${members.length}`);
+
+  if (ws.warnings && ws.warnings.length > 0) {
+    console.log(`  \x1b[33mWarnings:\x1b[0m`);
+    for (const w of ws.warnings) console.log(`    ! ${w}`);
+  }
+
+  if (hierarchy.root) {
+    const gates = Object.keys(hierarchy.root.gates).length;
+    console.log(`  Root governance: ${gates} gate section(s), runtimes: ${hierarchy.root.runtimes.join(', ') || 'none'}`);
+  } else {
+    console.log(`  Root governance: \x1b[90m(none)\x1b[0m`);
+  }
+
+  if (members.length === 0) {
+    console.log(`\n  (No members found — check workspace config.)\n`);
+    return;
+  }
+
+  console.log(`\n  Members:`);
+  for (const m of members) {
+    const govIcon = m.hasGovernance ? '\x1b[32m✓\x1b[0m' : '\x1b[90m○\x1b[0m';
+    const gitIcon = m.hasGit ? ' \x1b[33m[git]\x1b[0m' : '';
+    const stack = m.stack.length > 0 ? `[${m.stack.join(', ')}]` : '[empty]';
+    const inherit = hierarchy.members[m.name]?.inherit === 'root' ? ' \x1b[36m(inherits)\x1b[0m' : '';
+    console.log(`    ${govIcon} ${m.name.padEnd(30)} ${stack}${gitIcon}${inherit}`);
+    console.log(`      ${m.relativePath}`);
+  }
+
+  console.log('');
+  console.log(`  Legend: \x1b[32m✓\x1b[0m has governance  \x1b[90m○\x1b[0m no governance  \x1b[33m[git]\x1b[0m independent repo  \x1b[36m(inherits)\x1b[0m merges with root\n`);
+}
+
+module.exports = { workspace };

package/src/compile/agents-md.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { flattenGates } = require('../governance/parse');
+const { atomicWrite } = require('./atomic-write');
+
+function generateAgentsMd(cwd, parsed) {
+  const flat = flattenGates(parsed.gates);
+
+  let gatesSection = '';
+  for (const [section, cmds] of Object.entries(flat)) {
+    gatesSection += `### ${section.charAt(0).toUpperCase() + section.slice(1)}\n`;
+    cmds.forEach((cmd, i) => {
+      gatesSection += `${i + 1}. \`${cmd}\`\n`;
+    });
+    gatesSection += '\n';
+  }
+
+  // Extract security section from governance content if available
+  const securitySection = parsed.security || 'No hardcoded secrets or API keys in source.';
+
+  const content = [
+    '# AGENTS.md',
+    '',
+    `> Generated from governance.md by crag. Regenerate: \`crag compile --target agents-md\``,
+    '',
+    `## Project: ${parsed.name || 'Unnamed'}`,
+    '',
+    parsed.description ? `${parsed.description}\n` : '',
+    '## Quality Gates',
+    '',
+    'All changes must pass these checks before commit:',
+    '',
+    gatesSection.trim(),
+    '',
+    '## Coding Standards',
+    '',
+    `- Runtimes: ${parsed.runtimes.join(', ') || 'auto-detected'}`,
+    '- Follow conventional commits (feat:, fix:, docs:, etc.)',
+    '- No hardcoded secrets — grep for sk_live, AKIA, password= before commit',
+    '',
+    '## Architecture',
+    '',
+    'Run `/pre-start-context` at the start of every session to discover the project stack, load governance rules, and prepare for work.',
+    '',
+    '## Validation',
+    '',
+    'Run `/post-start-validation` after completing any task to validate changes, run gates, capture knowledge, and commit.',
+    '',
+  ].join('\n');
+
+  const outPath = path.join(cwd, 'AGENTS.md');
+  atomicWrite(outPath, content);
+  console.log(`  \x1b[32m✓\x1b[0m ${path.relative(cwd, outPath)}`);
+}
+
+module.exports = { generateAgentsMd };

package/src/compile/atomic-write.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Write `content` to `filePath` atomically:
+ *   1. Ensure parent directory exists
+ *   2. Write to a sibling tempfile
+ *   3. Rename tempfile over destination
+ *
+ * If any step fails, the tempfile is cleaned up and the original destination
+ * remains untouched. Prevents partial-write state if the process is killed
+ * mid-write or the filesystem runs out of space.
+ */
+function atomicWrite(filePath, content) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const tmp = filePath + '.tmp.' + process.pid + '.' + Date.now();
+
+  try {
+    fs.writeFileSync(tmp, content);
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    // Best-effort cleanup
+    try { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); } catch {}
+    throw err;
+  }
+}
+
+module.exports = { atomicWrite };

package/src/compile/cline.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const path = require('path');
+const { flattenGatesRich } = require('../governance/parse');
+const { atomicWrite } = require('./atomic-write');
+
+/**
+ * Compile governance.md to Cline rules.
+ * Output: .clinerules
+ *
+ * Cline is a VS Code extension that runs agentic coding loops locally.
+ * It reads `.clinerules` at the workspace root automatically.
+ *
+ * Reference:
+ *   https://docs.cline.bot/features/cline-rules
+ */
+function generateCline(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}`);
+          const tagStr = tags.length > 0 ? ` [${tags.join(', ')}]` : '';
+          return `- ${g.cmd}${tagStr}`;
+        })
+        .join('\n');
+
+  const content = `# Cline Rules — ${parsed.name || 'project'}
+
+Generated from governance.md by crag. Regenerate with: \`crag compile --target cline\`
+
+## About this project
+
+${parsed.description || '(No description)'}
+
+Runtimes: ${parsed.runtimes.join(', ') || 'auto-detected'}
+
+## Mandatory behavior
+
+1. Read this file at the start of every session. Read \`governance.md\` for full context.
+2. Run all mandatory quality gates before proposing a commit.
+3. If a gate fails, attempt an automatic fix (lint/format) with bounded retry (max 2 attempts). If it still fails, escalate to the user.
+4. Never modify files outside this repository.
+5. Never run destructive system commands (rm -rf /, DROP TABLE, force-push to main, curl|bash).
+6. Use conventional commits.
+
+## Quality gates
+
+Run these in order, stop on first MANDATORY failure:
+
+${gatesList}
+
+## Security
+
+- Never commit hardcoded secrets (grep for sk_live, sk_test, AKIA, password=)
+- Validate all user input at system boundaries
+- Use parameterized queries for database access
+
+## Workflow
+
+For every task:
+1. Read the governance.md file first
+2. Understand which files need to change
+3. Make minimal, focused changes
+4. Run all mandatory gates
+5. Commit with a conventional commit message
+
+## Tool context
+
+This project uses **crag** — the bedrock layer for AI coding agents. https://www.npmjs.com/package/@whitehatd/crag
+`;
+
+  const outPath = path.join(cwd, '.clinerules');
+  atomicWrite(outPath, content);
+  console.log(`  \x1b[32m✓\x1b[0m ${path.relative(cwd, outPath)}`);
+}
+
+module.exports = { generateCline };

package/src/compile/cody.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const path = require('path');
+const { flattenGatesRich } = require('../governance/parse');
+const { atomicWrite } = require('./atomic-write');
+
+/**
+ * Compile governance.md to Sourcegraph Cody instructions.
+ * Output: .sourcegraph/cody-instructions.md
+ *
+ * Cody is Sourcegraph's AI coding assistant. It reads project-level
+ * instructions from `.sourcegraph/cody-instructions.md` to provide
+ * repo-wide context to its chat, edit, and autocomplete features.
+ *
+ * Reference:
+ *   https://sourcegraph.com/docs/cody/capabilities/custom-commands
+ */
+function generateCody(cwd, parsed) {
+  const gates = flattenGatesRich(parsed.gates);
+
+  const gatesList = gates.length === 0
+    ? '- _(none defined — add gates to governance.md)_'
+    : gates
+        .map((g) => {
+          const annotations = [];
+          if (g.classification !== 'MANDATORY') annotations.push(g.classification);
+          if (g.path) annotations.push(`scope: ${g.path}`);
+          if (g.condition) annotations.push(`if: ${g.condition}`);
+          const tagStr = annotations.length > 0 ? ` — ${annotations.join(' · ')}` : '';
+          return `- \`${g.cmd}\`${tagStr}`;
+        })
+        .join('\n');
+
+  const content = `# Cody Instructions — ${parsed.name || 'project'}
+
+> Generated from governance.md by crag. Regenerate: \`crag compile --target cody\`
+
+## About
+
+${parsed.description || '(No description)'}
+
+**Runtimes detected:** ${parsed.runtimes.join(', ') || 'polyglot'}
+
+## How Cody Should Behave on This Project
+
+### Code Generation
+
+1. **Run governance gates before suggesting commits.** The gates below define the quality bar.
+2. **Respect classifications:** MANDATORY (default) blocks on failure; OPTIONAL warns; ADVISORY is informational only.
+3. **Respect scopes:** Path-scoped gates run from that directory. Conditional gates skip when their file does not exist.
+4. **No secrets.** Never generate code containing \`sk_live\`, \`sk_test\`, \`AKIA\`, or plaintext credentials.
+5. **Minimal diffs.** Prefer editing existing code over creating new files. Do not refactor unrelated areas.
+
+### Quality Gates
+
+${gatesList}
+
+### Commit Style
+
+Use conventional commits: \`feat(scope): description\`, \`fix(scope): description\`, \`docs: description\`, etc.
+
+### Boundaries
+
+- All file operations must stay within this repository.
+- No destructive shell commands (rm -rf above repo root, DROP TABLE without confirmation, force-push to main).
+- No new dependencies without an explicit reason.
+
+## Authoritative Source
+
+When these instructions seem to conflict with something in the repo, **\`.claude/governance.md\` is the source of truth**. This file is a compiled view.
+
+---
+
+**Tool:** crag — https://www.npmjs.com/package/@whitehatd/crag
+`;
+
+  const outPath = path.join(cwd, '.sourcegraph', 'cody-instructions.md');
+  atomicWrite(outPath, content);
+  console.log(`  \x1b[32m✓\x1b[0m ${path.relative(cwd, outPath)}`);
+}
+
+module.exports = { generateCody };

package/src/compile/continue.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const path = require('path');
+const { flattenGatesRich } = require('../governance/parse');
+const { atomicWrite } = require('./atomic-write');
+
+/**
+ * Compile governance.md to Continue.dev rules.
+ * Output: .continuerules (a markdown file) + companion block for config.yaml
+ *
+ * Continue is an open-source AI code assistant that supports custom rules
+ * at the project level. It reads `.continuerules` and project-level
+ * `config.yaml` fragments.
+ *
+ * Reference:
+ *   https://docs.continue.dev/customize/deep-dives/rules
+ */
+function generateContinue(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}`);
+          return `  - ${g.cmd}${tags.length > 0 ? ` (${tags.join(', ')})` : ''}`;
+        })
+        .join('\n');
+
+  const content = `# Continue Rules — ${parsed.name || 'project'}
+
+> Generated from governance.md by crag. Regenerate: \`crag compile --target continue\`
+
+${parsed.description || ''}
+
+## Project Context
+
+- **Runtimes:** ${parsed.runtimes.join(', ') || 'polyglot'}
+- **Governance source:** \`.claude/governance.md\` (single source of truth)
+
+## Coding Rules
+
+Always follow these when generating or modifying code:
+
+1. **Run gates before committing.** Every change must pass the mandatory gates below.
+2. **Classifications matter:**
+   - \`MANDATORY\` — must pass (default)
+   - \`OPTIONAL\` — should pass, warn on failure
+   - \`ADVISORY\` — informational only
+3. **Path-scoped gates** run from their declared directory.
+4. **Conditional gates** only run when their referenced file exists.
+5. **No secrets.** Reject any code containing \`sk_live\`, \`sk_test\`, \`AKIA\`, or plaintext passwords.
+6. **Conventional commits.** Format: \`<type>(<scope>): <description>\`
+
+## Quality Gates
+
+${gatesList}
+
+## Boundaries
+
+- All file operations stay within this repository
+- No destructive shell commands
+- No new dependencies without justification
+- Prefer editing existing files over creating new ones
+
+## Powered by crag
+
+This rule file is auto-generated from a single \`governance.md\` via **crag** (https://www.npmjs.com/package/@whitehatd/crag) — the bedrock layer for AI coding agents. To update these rules, edit governance.md and re-run \`crag compile --target continue\`.
+`;
+
+  const outPath = path.join(cwd, '.continuerules');
+  atomicWrite(outPath, content);
+  console.log(`  \x1b[32m✓\x1b[0m ${path.relative(cwd, outPath)}`);
+}
+
+module.exports = { generateContinue };

package/src/compile/copilot.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const path = require('path');
+const { flattenGatesRich } = require('../governance/parse');
+const { atomicWrite } = require('./atomic-write');
+
+/**
+ * Compile governance.md to GitHub Copilot Workspace instructions.
+ * Output: .github/copilot-instructions.md
+ *
+ * Copilot Workspace reads this file automatically. It's supported by
+ * Copilot in VS Code, JetBrains IDEs, Visual Studio, and the Copilot
+ * Workspace web experience.
+ *
+ * Reference:
+ *   https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot
+ */
+function generateCopilot(cwd, parsed) {
+  const gates = flattenGatesRich(parsed.gates);
+
+  const gatesBlock = gates.length === 0
+    ? '_No quality gates defined — add them to governance.md._'
+    : gates
+        .map((g) => {
+          const prefix = g.classification !== 'MANDATORY' ? ` (${g.classification.toLowerCase()})` : '';
+          const scope = g.path ? ` in \`${g.path}\`` : '';
+          return `- **${g.section}**${scope}${prefix}: \`${g.cmd}\``;
+        })
+        .join('\n');
+
+  const runtimesBlock = parsed.runtimes.length > 0
+    ? parsed.runtimes.join(', ')
+    : 'polyglot (detected from files at runtime)';
+
+  const content = `# Copilot Instructions — ${parsed.name || 'project'}
+
+> Generated from governance.md by crag. Regenerate: \`crag compile --target copilot\`
+
+${parsed.description || ''}
+
+## Runtimes
+
+${runtimesBlock}
+
+## Quality Gates
+
+When you propose changes, the following checks must pass before commit:
+
+${gatesBlock}
+
+## Expectations for AI-Assisted Code
+
+1. **Run gates before suggesting a commit.** If you cannot run them (no shell access), explicitly remind the human to run them.
+2. **Respect classifications.** \`MANDATORY\` gates must pass. \`OPTIONAL\` gates should pass but may be overridden with a note. \`ADVISORY\` gates are informational only.
+3. **Respect workspace paths.** When a gate is scoped to a subdirectory, run it from that directory.
+4. **No hardcoded secrets.** Never commit values matching \`sk_live\`, \`sk_test\`, \`AKIA\`, or \`password = "…"\`.
+5. **Conventional commits** for all changes.
+6. **Conservative changes.** Do not rewrite unrelated files. Do not add new dependencies without explaining why.
+
+## Tool Context
+
+This project uses **crag** (https://www.npmjs.com/package/@whitehatd/crag) as its AI-agent governance layer. The \`governance.md\` file is the authoritative source. If you have shell access, run \`crag check\` to verify the infrastructure and \`crag diff\` to detect drift.
+`;
+
+  const outPath = path.join(cwd, '.github', 'copilot-instructions.md');
+  atomicWrite(outPath, content);
+  console.log(`  \x1b[32m✓\x1b[0m ${path.relative(cwd, outPath)}`);
+}
+
+module.exports = { generateCopilot };

package/src/compile/cursor-rules.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { flattenGates } = require('../governance/parse');
+const { atomicWrite } = require('./atomic-write');
+
+function generateCursorRules(cwd, parsed) {
+  const dir = path.join(cwd, '.cursor', 'rules');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const flat = flattenGates(parsed.gates);
+
+  let gatesList = '';
+  for (const [section, cmds] of Object.entries(flat)) {
+    gatesList += `\n### ${section.charAt(0).toUpperCase() + section.slice(1)}\n`;
+    for (const cmd of cmds) {
+      gatesList += `- \`${cmd}\`\n`;
+    }
+  }
+
+  // Determine globs from runtimes
+  const globs = [];
+  if (parsed.runtimes.includes('node')) globs.push('"**/*.ts"', '"**/*.tsx"', '"**/*.js"', '"**/*.jsx"');
+  if (parsed.runtimes.includes('rust')) globs.push('"**/*.rs"');
+  if (parsed.runtimes.includes('python')) globs.push('"**/*.py"');
+  if (parsed.runtimes.includes('java')) globs.push('"**/*.java"', '"**/*.kt"');
+  if (parsed.runtimes.includes('go')) globs.push('"**/*.go"');
+  if (globs.length === 0) globs.push('"**/*"');
+
+  const content = [
+    '---',
+    `description: Governance rules for ${parsed.name || 'this project'} — quality gates, security, conventions`,
+    'globs:',
+    ...globs.map(g => `  - ${g}`),
+    'alwaysApply: true',
+    '---',
+    '',
+    `# Governance — ${parsed.name || 'Project'}`,
+    '',
+    `> Generated from governance.md by crag. Regenerate: \`crag compile --target cursor\``,
+    '',
+    '## Quality Gates',
+    '',
+    'Run these checks in order before committing:',
+    gatesList.trim(),
+    '',
+    '## Security',
+    '',
+    '- No hardcoded secrets — grep for sk_live, AKIA, password= before commit',
+    '- Validate all user input at system boundaries',
+    '- Use parameterized queries for database access',
+    '',
+    '## Conventions',
+    '',
+    '- Follow conventional commits (feat:, fix:, docs:, etc.)',
+    `- Runtimes: ${parsed.runtimes.join(', ') || 'auto-detected'}`,
+    '',
+  ].join('\n');
+
+  const outPath = path.join(dir, 'governance.mdc');
+  atomicWrite(outPath, content);
+  console.log(`  \x1b[32m✓\x1b[0m ${path.relative(cwd, outPath)}`);
+}
+
+module.exports = { generateCursorRules };

package/src/compile/gemini-md.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { flattenGates } = require('../governance/parse');
+const { atomicWrite } = require('./atomic-write');
+
+function generateGeminiMd(cwd, parsed) {
+  const flat = flattenGates(parsed.gates);
+
+  let gatesList = '';
+  let i = 1;
+  for (const [section, cmds] of Object.entries(flat)) {
+    for (const cmd of cmds) {
+      gatesList += `${i}. [${section}] \`${cmd}\`\n`;
+      i++;
+    }
+  }
+
+  const content = [
+    '# GEMINI.md',
+    '',
+    `> Generated from governance.md by crag. Regenerate: \`crag compile --target gemini\``,
+    '',
+    '## Project Context',
+    '',
+    `- **Name:** ${parsed.name || 'Unnamed'}`,
+    parsed.description ? `- **Description:** ${parsed.description}` : '',
+    `- **Runtimes:** ${parsed.runtimes.join(', ') || 'auto-detected'}`,
+    '',
+    '## Rules',
+    '',
+    '### Quality Gates',
+    '',
+    'Run these checks in order before committing any changes:',
+    '',
+    gatesList.trim(),
+    '',
+    '### Security',
+    '',
+    '- Never hardcode secrets, API keys, or credentials in source code',
+    '- Grep for sk_live, AKIA, password= before every commit',
+    '- Validate all user input at system boundaries',
+    '',
+    '### Workflow',
+    '',
+    '- Use conventional commits (feat:, fix:, docs:, chore:, etc.)',
+    '- Run quality gates before committing',
+    '- Review security implications of all changes',
+    '',
+  ].join('\n');
+
+  const outPath = path.join(cwd, 'GEMINI.md');
+  atomicWrite(outPath, content);
+  console.log(`  \x1b[32m✓\x1b[0m ${path.relative(cwd, outPath)}`);
+}
+
+module.exports = { generateGeminiMd };