@codapult/guard

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:

Client → Server Action → Service → Repository → Database

An AI agent can still produce code that is valid TypeScript but crosses that boundary:

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:

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. It does not require Codapult and can be installed in any JavaScript or TypeScript repository.

The relationship is complementary:

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.

        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:

Install

Requirements: Node.js >=20.19 and a JavaScript or TypeScript project.

pnpm add -D @codapult/guard
# or
npm install --save-dev @codapult/guard

The package exposes the codapult-guard binary:

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:

# 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:

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:

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.