Skip to content

crag v0.2.0 — The bedrock layer for AI coding agents

Choose a tag to compare

View all tags
@WhitehatD WhitehatD released this 04 Apr 22:51
· 275 commits to master since this release
v0.2.0
03440f7

First public release on npm. Install: npm install -g @whitehatd/crag

Write your AI agent rules once. Enforce them in Claude Code, Cursor, Copilot, Codex, Gemini, Aider, Cline, Continue, Windsurf, Zed, and Sourcegraph Cody — plus your CI pipeline and git hooks. From a single 20-line governance.md.

🎯 What makes this release

crag inverts how AI coding setups work. Every other tool ships static config files (CLAUDE.md, AGENTS.md, .cursor/rules) that hardcode your project's current shape — they rot the moment facts change. crag ships a runtime discovery engine that reads the filesystem every session (never goes stale) plus a single governance.md that holds your rules (changes only when you say).

🆕 Four new commands (vs scaffold-cli era)

  • crag analyze — zero-interview governance generation. Reads CI workflows (recursively, incl. run: | blocks), package.json scripts, linter configs (ESLint/Biome/Prettier/Ruff/Clippy/Rustfmt/Mypy/TypeScript), git log for branch/commit patterns, deployment configs (Docker/k8s/Vercel/Fly/Netlify/Render/Terraform).
  • crag diff — governance vs reality comparison with MATCH/DRIFT/MISSING/EXTRA verdicts. Memoized file reads. Command alias normalization (npm test ⇔ npm run test, ./gradlew ⇔ gradlew).
  • crag upgrade — version-tracked skill updates. Skills carry version + source_hash (SHA-256 CRLF-normalized). Only overwrites unmodified skills unless --force (with backup).
  • crag workspace — workspace inspector with human + --json output modes.

🎛️ 12 compile targets (vs 3 before)

Single governance.md → CI configs, git hooks, and 9 AI coding agent configs:

Group Targets
CI / git hooks github, husky, pre-commit
AI native agents-md (Codex/Aider/Factory), cursor, gemini
AI extras copilot, cline, continue, windsurf, zed, cody

Run crag compile --target all to regenerate all 12 at once. The generator detects Node/Python/Java/Go versions from your project files (package.json engines.node, pyproject.toml requires-python, build.gradle.kts toolchain, go.mod directive) instead of hardcoding defaults.

🌳 Workspace detection — 11+ types

Walks up from CWD to find any of: pnpm-workspace.yaml, npm/yarn workspaces, Cargo.toml [workspace], go.work, settings.gradle.kts include(), pom.xml <modules>, nx.json, turbo.json, Bazel WORKSPACE/MODULE.bazel, .gitmodules, independent nested .git dirs. Enumerates members with glob expansion (incl. negation patterns), detects tech stack per member, loads multi-level governance via ## Gates (inherit: root).

📝 Governance v2 format (backward-compatible)

Optional annotations that existing v1 files ignore:

```markdown

Frontend (path: frontend/) # cd before running

  • npx biome check . # [MANDATORY] (default)
  • npx tsc --noEmit # [OPTIONAL] — warn but don't fail

TypeScript (if: tsconfig.json) # skip if file missing

  • tsc --noEmit

Audit

  • npm audit # [ADVISORY] — informational only

Gates (inherit: root) # merge with root governance

```

Classifications wired end-to-end: GitHub Actions continue-on-error: true, husky/pre-commit wrapper scripts, post-start-validation skill runtime instructions.

🔒 Security hardening

  • Shell injection — gateToShell() escapes \, `, $, " in interpolated values
  • Path traversal — expandGlobs() uses fs.realpathSync + rejects .. patterns
  • Symlink attack — isTrustedSource() requires regular file inside src/skills/
  • YAML injection — block scalars for run:, yamlDqEscape() for labels, yamlScalar() quotes colons/newlines/boolean-like
  • ReDoS — 256 KB input cap, line-scan extractSection() replaces regex
  • HTTPS cleanup — req.unref(), timeout, 100 KB response cap
  • CRLF hash mismatch — same content hashes identically on Windows/Unix

🏗️ Architecture

  • 24 modules across 6 directories (was a 397-line single file)
  • Zero dependencies — pure Node.js built-ins (fs, path, crypto, https, child_process, os)
  • Node 18+ required
  • 159 tests across 11 test files, runs via npm test or node test/all.js
  • 12 governance gates pass (tool dogfoods itself)

🤖 CI/CD included

  • .github/workflows/test.yml — 3×3 matrix (Ubuntu/macOS/Windows × Node 18/20/22), runs all gates + tests + compiles all 12 targets on every push/PR
  • .github/workflows/publish.yml — auto-publishes to npm on release tag with SLSA provenance attestation
  • .github/workflows/stale.yml — daily issue/PR hygiene

📦 Install

```bash

Global install (recommended)

npm install -g @whitehatd/crag

Or one-off via npx

npx @whitehatd/crag init
```

The package is scoped (@whitehatd/crag) but the binary is named crag — after install, all commands are plain crag init, crag analyze, crag compile, etc.

🛣️ What's next

  • v0.3.0 — cross-repo benchmark, drift resilience tests, scaffold diff deeper integration with Git
  • crag Cloud — hosted governance registry, cross-repo dashboard, team library, compliance templates (paid tier, separate repo, coming soon)

📚 Docs

Full docs and user guide: README.md

Changelog: CHANGELOG.md

Contributing: CONTRIBUTING.md

🙏 Credits

Built by Alexandru Cioc (WhitehatD) with assistance from Claude Opus 4.6.

Assets 2
Loading