# guard **Category:** πŸ’» Developer Tools **Repository:** https://github.com/codapult/codapult-guard **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/guard ## Description Local-first architecture guardrails and project context for JS/TS AI coding agents. ## Claude Desktop Quick Installation Heuristic fallback β€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "guard": { "command": "npx", "args": ["-y","guard"] } } ``` ## Documentation & README # @codapult/guard [![CI](https://github.com/codapult/codapult-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/codapult/codapult-guard/actions/workflows/ci.yml) [![Fixtures](https://github.com/codapult/codapult-guard/actions/workflows/guard-fixtures.yml/badge.svg)](https://github.com/codapult/codapult-guard/actions/workflows/guard-fixtures.yml) [![npm](https://img.shields.io/npm/v/@codapult/guard?logo=npm)](https://www.npmjs.com/package/@codapult/guard) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Node.js >=20.19](https://img.shields.io/badge/node-%3E%3D20.19-339933.svg?logo=node.js&logoColor=white)](package.json) [![TypeScript](https://img.shields.io/badge/TypeScript-first-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) ## Architecture guardrails for AI coding agents `@codapult/guard` is a local-first, model-agnostic architecture guard for JavaScript and TypeScript projects. It learns what already exists, records the project’s architectural memory, and can protect future changes from introducing regressions covered by the project’s approved policy. ### See the value in one change Suppose a SaaS project has an established boundary: ```text Client β†’ Server Action β†’ Service β†’ Repository β†’ Database ``` An AI agent can still produce code that is valid TypeScript but crosses that boundary: ```text Client β†’ Database ``` After the project has explicitly approved a matching import rule or deterministic contract, Guard checks the changed files and reports matching violations deterministically: ```text Codapult Guard (changed files) Scanned 1 source file(s); suppressed 12 baseline finding(s). src/app/settings/page.tsx:1 [client-no-persistence-import] Client modules should not import persistence-layer modules. import: @/lib/db/client βœ— 1 issue(s) found Exit code: 1 ``` The file path, rule ID, message, and counts depend on the project. This is the actual CLI output shape: Guard does not infer that every `Client β†’ Database` edge is forbidden, and it does not activate proposals silently. The team approves the relevant policy first; then existing findings can be baselined while newly matching violations fail the gate and give the agent bounded evidence to repair. > **Guard does not tell every project to use the same architecture.** > It discovers the architecture that is already there, then lets the team decide what becomes policy. The core is universal. The strongest first-class scenarios are Next.js SaaS and AI-assisted development, including server/client boundaries, routes, persistence, authentication, billing, background jobs, environment configuration, and AI integrations. ## Part of the Codapult ecosystem Guard is an independent open-source project from [Codapult](https://codapult.dev). It does not require Codapult and can be installed in any JavaScript or TypeScript repository. The relationship is complementary: | Project | Role | | --------------------- | ---------------------------------------------------------------------------------------- | | **`@codapult/guard`** | Universal architecture guardrails, project memory, contracts, MCP, and AI-agent context. | | **`@codapult/cli`** | Codapult SaaS project CLI that includes Guard through a thin adapter. | | **Codapult** | Full-source Next.js SaaS foundation with conventions Guard can discover and protect. | Use standalone Guard for any compatible project. Use the Codapult CLI when working on a Codapult SaaS project and you want project management, database, plugins, deployment, MCP, and Guard in one CLI. ```text Existing project β”‚ β–Ό deterministic discovery AST Β· files Β· imports Β· Git β”‚ β–Ό project architecture capabilities Β· graph Β· impact paths β”‚ β–Ό approved project policy rules Β· contracts Β· conventions Β· baseline β”‚ β–Ό change verification check Β· review packet Β· verify Β· CI ``` ## Why Guard exists AI agents can produce syntactically valid code that still violates the architecture of a real project: a client component imports server-only code, a new action bypasses the established auth boundary, a route writes to the database directly, or a change duplicates a service that already exists. Existing tools remain essential, but they solve different problems: | Tool category | Primary question | Guard’s relationship | | -------------------------- | -------------------------------------------------- | --------------------------------------------------------------------- | | TypeScript | Is the code type-correct? | Uses the project’s typecheck as an optional gate. | | ESLint / Biome | Does code follow language and style rules? | Does not duplicate their lint rules. | | Tests | Does behavior match executable expectations? | Runs configured checks when enabled; does not replace tests. | | SAST / dependency scanners | Is there a known security or dependency risk? | Can connect adapters; focuses on architecture and change impact. | | PR review services | What semantic concerns should a reviewer consider? | Produces a bounded, redacted review packet for the selected AI host. | | **Guard** | Is the project becoming architecturally worse? | Maintains project-specific architectural memory and regression gates. | ## Install Requirements: Node.js `>=20.19` and a JavaScript or TypeScript project. ```bash pnpm add -D @codapult/guard # or npm install --save-dev @codapult/guard ``` The package exposes the `codapult-guard` binary: ```bash pnpm exec codapult-guard init ``` The npm package is scoped as `@codapult/guard`; the executable intentionally remains `codapult-guard` for discoverability and consistency with the standalone product name. ## 60-second quick start Run from the project root: ```bash # 1. Build the initial project model and baseline pnpm exec codapult-guard init # 2. Inspect only new and changed architecture findings pnpm exec codapult-guard check --changed # 3. Prepare deterministic context for an AI review pnpm exec codapult-guard review --requirement docs/acceptance.md # 4. Run the configured completion gate pnpm exec codapult-guard verify --json ``` `init` is protected and refuses to overwrite an existing baseline. Use `init --force` only when deliberately replacing the project memory. Use `analyze` to refresh discovered facts without resetting the baseline. ## The operating model Guard separates facts, policy, verification, and decision: | Layer | Contains | How it is produced | | ---------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------- | | **Facts** | AST, files, imports, dependencies, routes, calls, capabilities, graph, Git history | Deterministic local discovery | | **Policy** | Rules, contracts, conventions, baseline | Observed proposals plus explicit team approval | | **Verification** | Changed-file checks, impact analysis, contracts, project checks, review packet | Local CLI, MCP, CI, and existing project tools | | **Decision** | Pass, fail, warning, needs-review, not-configured | Developer or AI host using Guard evidence | Guard does not assume a fixed `UI β†’ actions β†’ services β†’ repositories β†’ database` architecture. It can discover that shape when the project exhibits it, but observed patterns become enforceable only after explicit approval. Policy paths are validated as project-relative paths. Guard rejects traversal, absolute paths, and symlinks escaping the project root; import-boundary checks include imports, re-exports, and literal dynamic imports. ## What Guard discovers The model is framework-aware without being framework-dependent: | Area | Examples of discovered evidence | | ----------------------- | ---------------------------------------------------------------------------------- | | JavaScript / TypeScript | AST modules, declarations, calls, directives, aliases, re-exports, dynamic imports | | Next.js / React | App Router routes, route methods, Server Actions, client/server boundaries | | API boundaries | Route handlers, API modules, entrypoints, impact paths | | Data | ORM packages, schemas, migrations, repositories, persistence boundaries | | Capabilities | Auth, payments, email, AI/RAG, queues, storage, cache, search, analytics, content | | Operations | Environment references, configs, deployment, observability, webhooks | | Repository shape | Workspaces, package scripts, dependencies, cycles, import hotspots, Git history | | Testing | Test files, test scripts, workspace checks, changed files | Capabilities are evidence, not requirements. A Vite app, Express service, Hono project, Node package, monorepo, or Next.js SaaS can all use the same Guard core. ## What Guard is β€” and is not Guard is an architecture control plane for AI-assisted development. It protects project-specific boundaries and change impact using local facts, approved policy, and deterministic verification. Guard is not a replacement for ESLint, TypeScript, tests, SAST, or a general-purpose PR bot. Those tools answer different questions; Guard connects their results with the architectural memory that an AI coding agent needs before and after changing a repository. ## The normal loop ```text init once β†’ edit β†’ check --changed β†’ review β†’ verify β†’ commit / merge β†˜ analyze after structural changes ``` 1. `init` builds project memory and establishes the initial baseline. 2. `check --changed` is the fast deterministic architecture gate. 3. `review` prepares a bounded and redacted diff packet for an AI host; it does not call an LLM. 4. `verify` runs Guard policy, configured project checks, adapters, runtime diagnostics, and contract validation. 5. `audit` inspects the complete current state, including findings accepted by the baseline. For a focused change explanation, use `codapult-guard impact ` or the equivalent `codapult_guard_impact` MCP tool. It reports both directions of the dependency graph: what the changed module uses and which transitive callers may be affected. `review` includes the same impact packet plus typed Git changes (`added`, `modified`, `deleted`, and `renamed`) for the AI host. Guard state is stored in `.codapult/guard/`: ```text .codapult/guard/ β”œβ”€β”€ project.json discovered project model β”œβ”€β”€ architecture.json observed architecture and capabilities β”œβ”€β”€ conventions.json recurring project conventions β”œβ”€β”€ rules.json active and proposed deterministic rules β”œβ”€β”€ contracts.json project-specific boundaries and required calls β”œβ”€β”€ proposals.json evidence and approval history β”œβ”€β”€ baseline.json accepted pre-existing findings β”œβ”€β”€ agent.json AI-host completion-gate configuration └── history/ project snapshots and local verification run manifests ``` Commit policy and baseline files when the team wants shared guardrails. Treat cache artifacts as disposable according to the project’s policy, and never commit secrets. ### Optional scoped budgets Budgets are policy, not a universal style rule. Add them only for a named risk boundary such as a service, route handler, or dependency-heavy module: ```json { "id": "service-lines", "description": "Services must remain reviewable.", "metric": "lines", "scope": ["src/services"], "limit": 300, "severity": "warning", "reason": "Keep service changes reviewable by one owner.", "status": "active" } ``` Place budgets in the `budgets` array in `.codapult/guard/rules.json`. Supported metrics are `lines`, `bytes`, and `imports`. Generated files, schemas, migrations, and other paths are not checked unless they are explicitly included in `scope`; a wildcard such as `*` can intentionally cover the project root. Invalid, absolute, parent-directory, or nonexistent scopes fail the Guard gate. Changing a budget is a policy decision: review the diff and update its written `reason` rather than silently increasing the limit. ## AI agents and MCP Guard is deliberately model-agnostic. It does not send source code to a remote LLM and does not edit source files by itself. The AI host owns the model call, permissions, repair loop, and final decision. Start the standalone MCP server over stdio: ```bash pnpm exec codapult-guard mcp-server ``` Register that command in the MCP client from the project root. For example, Cursor can use `.cursor/mcp.json`: ```json { "mcpServers": { "codapult-guard": { "command": "pnpm", "args": ["exec", "codapult-guard", "mcp-server"], "cwd": "." } } } ``` For clients that accept a generic stdio server, use the same command and set its working directory to the project root. Guard reads local files only; no API key or model provider is required. Host-specific examples are in [`docs/integrations/`](https://github.com/codapult/codapult-guard/blob/HEAD/docs/integrations/). Recommended agent loop: ```text task finished β†’ codapult_guard_next_action β†’ codapult_guard_context β†’ codapult_guard_review(requirement, diff) β†’ codapult_guard_verify β†’ repair reported failures β†’ repeat until pass or bounded iteration limit ``` For Cursor, Claude Code, Codex, Gemini CLI, GitHub Copilot, and generic hosts, see [`docs/integrations/`](https://github.com/codapult/codapult-guard/blob/HEAD/docs/integrations/). ### MCP Registry Guard is also prepared for discovery through the official [MCP Registry](https://registry.modelcontextprotocol.io/). The Registry entry points to the published `@codapult/guard` npm package and its stdio MCP server; it does not replace npm installation or the host-specific configuration above. Registry metadata is validated during CI and published after npm in the release workflow. The Registry is currently in preview, so the canonical installation path remains npm. For workflows where the authoring agent must not approve its own policy proposals, set Guard to protected mode in `rules.json`: ```json { "approval": { "mode": "protected", "allowMcpApproval": false, "requireDistinctActor": true } } ``` MCP can then read and propose policy, while approval happens through the CLI or a protected CI/PR process. With `requireDistinctActor`, CLI and permitted MCP approvals require `GUARD_APPROVER`, and Guard rejects the same declared actor when a proposal was generated with `GUARD_PROPOSER`. These variables provide declared provenance only; external branch protection or signed identity remains responsible for proving who approved the change. See [the extension map](https://github.com/codapult/codapult-guard/blob/HEAD/docs/extensions.md) for the supported AI-host, CI/PR, policy-pack, tool adapter, approval-governance, and observability integrations. ## CI Copy the consumer workflow into a project that has installed and initialized Guard: ```bash cp node_modules/@codapult/guard/docs/guard-ci.yml .github/workflows/guard.yml ``` Or copy it from [`docs/guard-ci.yml`](https://github.com/codapult/codapult-guard/blob/HEAD/docs/guard-ci.yml). It runs project verification and exports Guard findings as SARIF for GitHub code scanning. The package repository separately runs its own unit, typecheck, build, and packaging checks in [`.github/workflows/ci.yml`](https://github.com/codapult/codapult-guard/blob/HEAD/.github/workflows/ci.yml), while the fixture workflow tests Guard on real project shapes. ## CLI surface | Command | Purpose | | -------------------------- | ------------------------------------------------------------------------------------------- | | `init` | Create project memory and the initial baseline. | | `analyze` | Refresh facts without changing policy or baseline. | | `propose` | Generate evidence-based rule and contract proposals. | | `check --changed` | Enforce active policy on changed and untracked files. | | `audit` | Scan the complete current project, including baseline findings. | | `review` | Create a bounded semantic-review packet for an AI host. | | `verify` | Run the configured completion gate. | | `doctor` | Diagnose invalid or missing Guard artifacts. | | `history` / `history-diff` | Inspect project model, module graph, and architecture-edge evolution. | | `impact ` | Explain dependencies, transitive dependents, capabilities, and contracts affected by files. | | `policy explain ` | Explain a policy item, its evidence, and approval history. | | `rules` / `contracts` | Approve or reject proposed policy. | | `baseline` | Review or intentionally accept existing findings. | Use `analyze --refresh` after a structural change. `doctor --fix-cache` removes only the disposable discovery cache; it does not change rules, contracts, baseline, or source files. Guard state is safe for concurrent CLI/MCP readers and writers: derived facts are published as an atomic generation, policy updates use revisions, and short write contention is waited out. A process that dies while holding the state lock is detected by its local PID and the lock is recovered; use `--no-wait` when an integration needs immediate contention feedback. Run `pnpm exec codapult-guard --help` for command-specific options. Every `verify` run also writes a local manifest under `.codapult/guard/history/runs/.json`. It records stage durations, the outcome, and the policy gate that decided the result. It contains no source code or external telemetry. These manifests make a failed run explainable without turning Guard into a production tracing system. ## Security and data handling - Deterministic discovery and checks run locally. - Review packets are bounded and redact common secrets before they are returned to an AI host. - Guard does not invoke an LLM or require a provider API key. - Project commands and external adapters run only when enabled by the project configuration. - Existing findings can be baselined, but new regressions remain visible. ## Verification and proof The repository validates the product through multiple layers: - unit and integration tests for discovery, policy, baseline, verification, MCP, and output; - AST adversarial cases for aliases, re-exports, dynamic imports, and route boundaries; - golden end-to-end flow from violation to repair; - mutation regression checks across real Next.js, React/Vite, Node, Hono, monorepo, and Express repositories; - npm pack checks to ensure the published artifact contains only the intended build output. Run the maintainer checks locally: ```bash pnpm test pnpm test:guard:golden pnpm test:guard:fixtures pnpm test:guard:fixtures:regression pnpm release:check ``` ## Documentation - [Complete Guard guide](https://github.com/codapult/codapult-guard/blob/HEAD/docs/guard.md) - [AI-agent integration](https://github.com/codapult/codapult-guard/blob/HEAD/docs/guard-agent-integration.md) - [Host integrations](https://github.com/codapult/codapult-guard/blob/HEAD/docs/integrations/) - [CI consumer workflow](https://github.com/codapult/codapult-guard/blob/HEAD/docs/guard-ci.yml) - [Fixture matrix](https://github.com/codapult/codapult-guard/blob/HEAD/docs/guard-fixtures.md) - [Release process](https://github.com/codapult/codapult-guard/blob/HEAD/docs/releasing.md) ## Project status `@codapult/guard` starts at `0.1.0` as a public alpha. The deterministic core is usable, tested, and intended for real projects, while policy schema and integration surfaces may still evolve before `1.0.0`. ## License MIT. See [LICENSE](https://github.com/codapult/codapult-guard/blob/HEAD/LICENSE).