feat: add /egc-grok — full-repo audit using 1M context

commands/egc-grok.toml

@@ -0,0 +1,83 @@
+description = "Grok the entire repo: architecture map, circular deps, dead-file candidates"
+prompt = '''
+# /egc-grok
+
+Run a deterministic, full-repo audit using Gemini's 1M context window.
+Produces:
+
+- File inventory and language breakdown
+- JS/TS module dependency graph (relative imports)
+- Circular dependency detection (Tarjan SCC)
+- Dead-file candidates (no incoming imports, not entry points)
+- Synthesized architectural narrative + Top 3 actions
+
+## Usage
+
+`/egc-grok [scope] [--format text|json]`
+
+- `scope` (optional): path to analyze (defaults to repo root)
+- `--format`: `text` (default) or `json`
+
+## Deterministic Engine
+
+Always run:
+
+```bash
+node scripts/grok.js [scope] --format <text|json>
+```
+
+This script is the single source of truth for the inventory, graph,
+cycles, and dead-file analysis. Do not re-derive these dimensions in
+prose and do not invent file paths, counts, or cycles that the script
+did not emit.
+
+## Synthesis Contract
+
+After running the script, produce a synthesis section ABOVE the raw
+report:
+
+1. **Architecture map** — 2-3 sentence narrative of the repo's
+   structure, anchored in the script's directory and language stats.
+2. **Hotspots** — concrete findings keyed to script output:
+   - Each circular dependency (cite the files exactly)
+   - Up to 10 dead-file candidates (cite paths exactly)
+3. **Top 3 actions** — prioritized, each with: (a) what to do,
+   (b) which files, (c) why this beats the alternatives.
+
+## Rules
+
+- Use script output verbatim for all file paths and counts.
+- If `--format json` was requested, return the script JSON unchanged
+  with no synthesis layer.
+- If text was requested, prepend the synthesis above the raw report.
+- Do not score or assign severity beyond what the script emits.
+- Do not propose fixes that touch files outside the dead-file or
+  cycle lists unless the user asks.
+
+## Example Result (text)
+
+```text
+## Architecture map
+Node.js CLI bundle. 481 files (most JS + markdown), JS code lives under
+scripts/ and hooks/. Tests are co-located in tests/lib/.
+
+## Hotspots
+- Cycle: scripts/lib/a.js -> scripts/lib/b.js -> scripts/lib/a.js
+- Dead candidates (3): scripts/old-helper.js, ...
+
+## Top 3 actions
+1. Break the lib/a <-> lib/b cycle by ... (scripts/lib/a.js, b.js).
+2. Delete or wire up scripts/old-helper.js ...
+3. ...
+
+# Repo Grok: everything-gemini-code
+... (raw script output) ...
+```
+
+## Arguments
+
+$ARGUMENTS:
+- `scope` (optional path)
+- `--format text|json` (optional output format)
+
+'''

scripts/grok.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const engine = require('./lib/grok-engine');
+
+const REPO_ROOT = path.join(__dirname, '..');
+
+function valueAfterEquals(arg) {
+  return arg.slice(arg.indexOf('=') + 1);
+}
+
+function requireValue(flag, value) {
+  if (typeof value !== 'string' || value.length === 0 || value.startsWith('-')) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  return value;
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const parsed = {
+    scope: REPO_ROOT,
+    format: 'text',
+    help: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+      continue;
+    }
+
+    if (arg === '--format') {
+      parsed.format = requireValue('--format', args[index + 1]).toLowerCase();
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--scope') {
+      parsed.scope = path.resolve(requireValue('--scope', args[index + 1]));
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--format=')) {
+      parsed.format = valueAfterEquals(arg).toLowerCase();
+      continue;
+    }
+
+    if (arg.startsWith('--scope=')) {
+      parsed.scope = path.resolve(valueAfterEquals(arg));
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+
+    parsed.scope = path.resolve(arg);
+  }
+
+  if (!['text', 'json'].includes(parsed.format)) {
+    throw new Error(`Invalid format: ${parsed.format}. Use text or json.`);
+  }
+
+  return parsed;
+}
+
+function ensureDirectory(scopePath) {
+  let stat;
+  try {
+    stat = fs.statSync(scopePath);
+  } catch (err) {
+    throw new Error(`Scope path not found: ${scopePath} (${err.code || err.message})`);
+  }
+  if (!stat.isDirectory()) {
+    throw new Error(`Scope path is not a directory: ${scopePath}`);
+  }
+}
+
+function printHelp() {
+  const lines = [
+    'Usage: node scripts/grok.js [scope] [--format text|json]',
+    '',
+    'Run a deterministic, full-repo audit and emit an architecture map,',
+    'circular dependency report, and dead-file candidates.',
+    '',
+    'Arguments:',
+    '  scope            Directory to analyze (default: repo root)',
+    '  --scope <dir>    Same, as a flag',
+    '  --format <fmt>   text (default) or json',
+    '  --help, -h       Show this help',
+  ];
+  console.log(lines.join('\n'));
+}
+
+function main() {
+  let parsed;
+  try {
+    parsed = parseArgs(process.argv);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  try {
+    ensureDirectory(parsed.scope);
+    const report = engine.buildReport(parsed.scope);
+    const output = parsed.format === 'json' ? engine.formatJson(report) : engine.formatText(report);
+    console.log(output);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { parseArgs, ensureDirectory };