@codapult/guard 0.2.0 → 0.3.0

package/README.md

@@ -168,6 +168,10 @@ Guard does not assume a fixed `UI → actions → services → repositories →
 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:
@@ -186,6 +190,15 @@ 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.
+
+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
@@ -259,6 +272,7 @@ Recommended agent loop:
 
 ```text
 task finished
+  → codapult_guard_next_action
   → codapult_guard_context
   → codapult_guard_review(requirement, diff)
   → codapult_guard_verify
@@ -298,9 +312,13 @@ real project shapes.
 | `doctor`                   | Diagnose invalid or missing Guard artifacts.                                                |
 | `history` / `history-diff` | Inspect project model, module graph, and architecture-edge evolution.                       |
 | `impact <files...>`        | Explain dependencies, transitive dependents, capabilities, and contracts affected by files. |
+| `policy explain <id>`      | 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.
+
 Run `pnpm exec codapult-guard <command> --help` for command-specific options.
 
 ## Security and data handling

package/dist/adapters/command.js

@@ -1,4 +1,4 @@
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 const MAX_OUTPUT_CHARS = 20_000;
 const MAX_BUFFER_BYTES = 2_000_000;
 function redactOutput(value) {
@@ -13,9 +13,30 @@ function captureOutput(value) {
         ? { value: `${redacted.slice(0, MAX_OUTPUT_CHARS)}\n[output truncated]`, truncated: true }
         : { value: redacted, truncated: false };
 }
+function parseCommand(command) {
+    const parts = command.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0 || parts.some((part) => /[;&|<>`$()]/.test(part)))
+        return undefined;
+    const [executable, ...args] = parts;
+    const windowsExecutable = process.platform === 'win32' && /^(?:npm|npx|pnpm|yarn|bun)$/.test(executable)
+        ? `${executable}.cmd`
+        : executable;
+    return { executable: windowsExecutable, args };
+}
 export function runProjectCommand(command, cwd, options = {}) {
+    const parsed = parseCommand(command);
+    if (!parsed) {
+        return {
+            command,
+            status: 'failed',
+            passed: false,
+            exitCode: 2,
+            stdout: '',
+            stderr: 'Unsafe or empty project command rejected.',
+        };
+    }
     try {
-        const stdout = execSync(command, {
+        const stdout = execFileSync(parsed.executable, parsed.args, {
             cwd,
             env: { ...process.env, ...options.env },
             stdio: 'pipe',

package/dist/cli/commands/guard.d.ts

@@ -2,7 +2,9 @@ import { type GuardToolMode } from '../../core/guard.js';
 export declare function guardInitCommand(options?: {
     force?: boolean;
 }): void;
-export declare function guardAnalyzeCommand(): void;
+export declare function guardAnalyzeCommand(_options?: {
+    refresh?: boolean;
+}): void;
 export declare function guardProposeCommand(options?: {
     json?: boolean;
 }): void;
@@ -11,6 +13,7 @@ export declare function guardInstallAgentCommand(target?: string, options?: {
 }): void;
 export declare function guardDoctorCommand(options?: {
     json?: boolean;
+    fixCache?: boolean;
 }): void;
 export declare function guardHistoryCommand(): void;
 export declare function guardImpactCommand(files: string[], options?: {
@@ -44,6 +47,9 @@ export declare function guardBaselineCommand(action: 'list' | 'accept' | 'remove
 export declare function guardRulesApproveCommand(ids?: string, options?: {
     all?: boolean;
 }): void;
+export declare function guardPolicyExplainCommand(id: string, options?: {
+    json?: boolean;
+}): void;
 export declare function guardContractsApproveCommand(ids?: string, options?: {
     all?: boolean;
 }): void;

package/dist/cli/commands/guard.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { relative, resolve } from 'node:path';
-import { GUARD_BASELINE_FILE, GUARD_BASELINE_META_FILE, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, GUARD_AGENT_FILE, GUARD_CONTRACTS_FILE, GUARD_PROPOSALS_FILE, GUARD_PROJECT_FILE, GUARD_HISTORY_DIR, GUARD_RULES_FILE, findGuardRoot, discoverProjectWithMetrics, buildGuardReviewPacket, buildGuardProposals, buildGeneratedGuardConfig, discoverProject, GuardAlreadyInitializedError, initializeGuard, loadBaseline, updateBaseline, loadGuardConfig, loadGuardProposals, writeGuardConfig, writeGuardProposals, recordGuardProposalDecision, getGuardProposalFreshness, scanGuard, classifyGuardOutcome, validateGuardContracts, writeProjectModel, writeGuardMemory, writeProjectSnapshot, } from '../../core/guard.js';
+import { GUARD_BASELINE_FILE, GUARD_BASELINE_META_FILE, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, GUARD_AGENT_FILE, GUARD_CONTRACTS_FILE, GUARD_PROPOSALS_FILE, GUARD_PROJECT_FILE, GUARD_HISTORY_DIR, GUARD_RULES_FILE, findGuardRoot, discoverProjectWithMetrics, clearDiscoveryCache, buildGuardReviewPacket, buildGuardProposals, buildGeneratedGuardConfig, discoverProject, GuardAlreadyInitializedError, initializeGuard, loadBaseline, updateBaseline, loadGuardConfig, loadGuardProposals, writeGuardConfig, writeGuardProposals, recordGuardProposalDecision, getGuardProposalFreshness, scanGuard, classifyGuardOutcome, validateGuardContracts, writeProjectModel, writeGuardMemory, writeProjectSnapshot, } from '../../core/guard.js';
+import { guardErrorPayload } from '../../core/errors.js';
 import { runGuardVerification, } from '../../core/verification/verify.js';
 import { diagnoseGuard } from '../../core/analysis/doctor.js';
 import { diffGuardSnapshots, listGuardSnapshots } from '../../core/history/history.js';
@@ -13,11 +14,33 @@ function renderFindings(findings) {
         const printer = finding.severity === 'error' ? fail : finding.severity === 'warning' ? warn : info;
         printer(`${finding.file}:${finding.line} [${finding.ruleId}] ${finding.message}`);
         dim(`  import: ${finding.importPath}`);
+        if (finding.resolvedPath)
+            dim(`  resolved: ${finding.resolvedPath}`);
     }
 }
 function getRoot() {
     return findGuardRoot();
 }
+function loadConfigSafely(root, options = {}) {
+    try {
+        return { config: loadGuardConfig(root), invalid: false };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Guard configuration is invalid.';
+        const payload = guardErrorPayload('GUARD_CONFIG_INVALID', message, {
+            configured: false,
+            outcome: 'error',
+            recoverable: true,
+            hint: 'Repair or remove the invalid Guard artifact, then run `codapult-guard doctor`.',
+        });
+        if (options.json || options.machine)
+            console.log(JSON.stringify(payload, null, 2));
+        else
+            fail(`${payload.message} Run \`codapult-guard doctor\` for details.`);
+        process.exitCode = 1;
+        return { invalid: true };
+    }
+}
 function readRequirement(root, file) {
     if (!file)
         return undefined;
@@ -74,7 +97,7 @@ export function guardInitCommand(options = {}) {
     info(`${config.rules.length} rule(s) generated (${proposedRules} proposed); ${report.scannedFiles} source file(s) scanned.`);
     dim('Existing findings are baselined. New violations will be reported by `codapult-guard check`.');
 }
-export function guardAnalyzeCommand() {
+export function guardAnalyzeCommand(_options = {}) {
     const root = getRoot();
     const { model: projectModel, metrics } = discoverProjectWithMetrics(root, {
         persistCache: true,
@@ -91,7 +114,10 @@ export function guardAnalyzeCommand() {
 export function guardProposeCommand(options = {}) {
     const root = getRoot();
     const model = discoverProject(root);
-    const config = loadGuardConfig(root) ?? buildGeneratedGuardConfig(model);
+    const loaded = loadConfigSafely(root, options);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config ?? buildGeneratedGuardConfig(model);
     const proposals = buildGuardProposals(model, config);
     const previous = loadGuardProposals(root);
     writeGuardProposals(root, {
@@ -135,9 +161,12 @@ export function guardInstallAgentCommand(target = 'generic', options = {}) {
     process.exitCode = 0;
 }
 export function guardDoctorCommand(options = {}) {
+    if (options.fixCache)
+        clearDiscoveryCache(getRoot());
     const report = diagnoseGuard(getRoot());
+    const result = options.fixCache ? { ...report, cacheFixed: true } : report;
     if (options.json) {
-        console.log(JSON.stringify(report, null, 2));
+        console.log(JSON.stringify(result, null, 2));
     }
     else {
         heading('Codapult Guard Doctor');
@@ -154,7 +183,7 @@ export function guardDoctorCommand(options = {}) {
         else
             success('Guard state is healthy.');
     }
-    process.exitCode = report.status === 'fail' ? 1 : 0;
+    process.exitCode = result.status === 'fail' ? 1 : 0;
 }
 export function guardHistoryCommand() {
     const snapshots = listGuardSnapshots(getRoot());
@@ -174,7 +203,10 @@ export function guardImpactCommand(files, options = {}) {
         process.exitCode = 1;
         return;
     }
-    const result = analyzeProjectImpact(discoverProject(root), files, loadGuardConfig(root)?.contracts ?? []);
+    const loaded = loadConfigSafely(root, options);
+    if (loaded.invalid)
+        return;
+    const result = analyzeProjectImpact(discoverProject(root), files, loaded.config?.contracts ?? []);
     if (options.json) {
         console.log(JSON.stringify({ status: 'ok', ...result }, null, 2));
         return;
@@ -268,10 +300,20 @@ export function guardVerifyCommand(options = {}) {
 }
 export function guardCheckCommand(options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root, { ...options, machine: options.json || options.sarif });
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         if (options.json) {
-            console.log(JSON.stringify({ configured: false, error: 'Guard is not initialized' }));
+            console.log(JSON.stringify({
+                status: 'error',
+                outcome: 'not-configured',
+                configured: false,
+                errorCode: 'GUARD_NOT_CONFIGURED',
+                message: 'Guard is not initialized.',
+                recoverable: true,
+            }));
             process.exitCode = 1;
             return;
         }
@@ -328,10 +370,20 @@ export function guardCheckCommand(options = {}) {
 }
 export function guardAuditCommand(options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root, options);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         if (options.json) {
-            console.log(JSON.stringify({ configured: false, error: 'Guard is not initialized' }));
+            console.log(JSON.stringify({
+                status: 'error',
+                outcome: 'not-configured',
+                configured: false,
+                errorCode: 'GUARD_NOT_CONFIGURED',
+                message: 'Guard is not initialized.',
+                recoverable: true,
+            }));
             process.exitCode = 1;
             return;
         }
@@ -388,9 +440,12 @@ export function guardBaselineCommand(action, ids, options = {}) {
         process.exitCode = 0;
         return;
     }
+    const loaded = options.all ? loadConfigSafely(root, options) : { invalid: false };
+    if (loaded.invalid)
+        return;
     const selected = options.all
         ? [
-            ...scanGuard(root, loadGuardConfig(root) ?? buildGeneratedGuardConfig(discoverProject(root)), {
+            ...scanGuard(root, loaded.config ?? buildGeneratedGuardConfig(discoverProject(root)), {
                 includeArchitectureInsights: true,
             }).findings.map((finding) => finding.fingerprint),
         ]
@@ -415,7 +470,10 @@ export function guardBaselineCommand(action, ids, options = {}) {
 }
 export function guardRulesApproveCommand(ids, options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         fail('Guard is not initialized. Run `codapult-guard init` first.');
         process.exitCode = 1;
@@ -442,9 +500,55 @@ export function guardRulesApproveCommand(ids, options = {}) {
         success(`Activated ${rule.id}`);
     process.exitCode = 0;
 }
+export function guardPolicyExplainCommand(id, options = {}) {
+    const root = getRoot();
+    const loaded = loadConfigSafely(root, options);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
+    const proposals = loadGuardProposals(root);
+    if (!config) {
+        fail('Guard is not initialized. Run `codapult-guard init` first.');
+        process.exitCode = 1;
+        return;
+    }
+    const item = [...config.rules, ...(config.contracts ?? [])].find((entry) => entry.id === id);
+    const proposed = [...(proposals?.rules ?? []), ...(proposals?.contracts ?? [])].find((entry) => entry.id === id);
+    if (!item && !proposed) {
+        fail(`Policy item not found: ${id}`);
+        process.exitCode = 1;
+        return;
+    }
+    const result = {
+        id,
+        active: item?.status !== 'proposed' && item !== undefined,
+        definition: item ?? proposed,
+        proposal: proposed,
+        decisions: proposals?.decisions?.filter((decision) => decision.id === id) ?? [],
+    };
+    if (options.json)
+        console.log(JSON.stringify(result, null, 2));
+    else {
+        heading(`Guard Policy: ${id}`);
+        info(`Status: ${result.active ? 'active' : 'proposed'}`);
+        const definition = result.definition;
+        if (definition && 'description' in definition)
+            dim(definition.description);
+        if (definition && 'statement' in definition)
+            dim(definition.statement);
+        if ((definition?.evidence?.length ?? 0) > 0)
+            dim(`Evidence: ${definition?.evidence?.join(', ')}`);
+        if (result.decisions.length > 0)
+            dim(`Decisions: ${result.decisions.length}`);
+    }
+    process.exitCode = 0;
+}
 export function guardContractsApproveCommand(ids, options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         fail('Guard is not initialized. Run `codapult-guard init` first.');
         process.exitCode = 1;
@@ -477,7 +581,10 @@ export function guardContractsApproveCommand(ids, options = {}) {
 }
 export function guardContractsRejectCommand(ids, options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         fail('Guard is not initialized. Run `codapult-guard init` first.');
         process.exitCode = 1;
@@ -512,7 +619,10 @@ export function guardReviewCommand(options = {}) {
     const requirement = readRequirement(root, options.requirement);
     if (options.requirement && !requirement)
         return;
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         fail(`Guard is not initialized. Run \`codapult-guard init\` first.`);
         process.exitCode = 1;

package/dist/cli/index.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import pc from 'picocolors';
-import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardImpactCommand, guardInitCommand, guardInstallAgentCommand, guardProposeCommand, guardReviewCommand, guardRulesApproveCommand, guardVerifyCommand, } from './commands/guard.js';
+import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardImpactCommand, guardInitCommand, guardInstallAgentCommand, guardPolicyExplainCommand, guardProposeCommand, guardReviewCommand, guardRulesApproveCommand, guardVerifyCommand, } from './commands/guard.js';
 import { config } from '../core/config.js';
+import { GuardConfigError, GuardStateBusyError } from '../core/guard.js';
+import { guardErrorPayload } from '../core/errors.js';
 const program = new Command()
     .name(config.commandName)
     .description('Local-first architecture guardrails for JavaScript and TypeScript projects')
@@ -15,10 +17,10 @@ const program = new Command()
 // `codapult-guard init`, not `codapult-guard guard init`.
 const guard = program;
 guard.command('init').option('--force').action(guardInitCommand);
-guard.command('analyze').action(guardAnalyzeCommand);
+guard.command('analyze').option('--refresh').action(guardAnalyzeCommand);
 guard.command('propose').option('--json').action(guardProposeCommand);
 guard.command('install-agent [target]').option('--json').action(guardInstallAgentCommand);
-guard.command('doctor').option('--json').action(guardDoctorCommand);
+guard.command('doctor').option('--json').option('--fix-cache').action(guardDoctorCommand);
 guard.command('history').action(guardHistoryCommand);
 guard.command('history-diff <from> <to>').option('--json').action(guardHistoryDiffCommand);
 guard.command('impact <files...>').option('--json').action(guardImpactCommand);
@@ -47,6 +49,8 @@ guard
     .action(guardReviewCommand);
 const rules = guard.command('rules');
 rules.command('approve [ids]').option('--all').action(guardRulesApproveCommand);
+const policy = guard.command('policy');
+policy.command('explain <id>').option('--json').action(guardPolicyExplainCommand);
 const contracts = guard.command('contracts');
 contracts.command('approve [ids]').option('--all').action(guardContractsApproveCommand);
 contracts.command('reject [ids]').option('--all').action(guardContractsRejectCommand);
@@ -73,4 +77,23 @@ program
     .action(async () => {
     await import('../mcp/server.js');
 });
-program.parse();
+try {
+    program.parse();
+}
+catch (error) {
+    if (error instanceof GuardConfigError || error instanceof GuardStateBusyError) {
+        const isBusy = error instanceof GuardStateBusyError;
+        console.error(JSON.stringify(guardErrorPayload(isBusy ? 'GUARD_STATE_BUSY' : 'GUARD_CONFIG_INVALID', error.message, {
+            configured: !isBusy,
+            outcome: 'error',
+            recoverable: true,
+            hint: isBusy
+                ? 'Retry after the other Guard process finishes.'
+                : 'Repair the invalid Guard artifact, then run codapult-guard doctor.',
+        }), null, 2));
+        process.exitCode = 1;
+    }
+    else {
+        throw error;
+    }
+}

package/dist/core/analysis/doctor.js

@@ -22,12 +22,18 @@ function parseJson(root, path) {
 export function diagnoseGuard(root) {
     const initialized = existsSync(resolve(root, GUARD_BASELINE_FILE));
     const items = requiredArtifacts.map((path) => {
-        const guardConfig = path === GUARD_CONTRACTS_FILE ? loadGuardConfig(root) : undefined;
         if (!existsSync(resolve(root, path))) {
             return { path, status: 'missing', message: 'Artifact is missing.' };
         }
-        if (path === GUARD_RULES_FILE && !loadGuardConfig(root)) {
-            return { path, status: 'invalid', message: 'Guard rules are invalid or unsupported.' };
+        if (path === GUARD_RULES_FILE) {
+            try {
+                if (!loadGuardConfig(root)) {
+                    return { path, status: 'invalid', message: 'Guard rules are invalid or unsupported.' };
+                }
+            }
+            catch {
+                return { path, status: 'invalid', message: 'Guard rules are invalid or unsupported.' };
+            }
         }
         if (path === GUARD_PROJECT_FILE && !loadProjectModel(root)) {
             return { path, status: 'invalid', message: 'Project model is invalid or unsupported.' };
@@ -39,8 +45,16 @@ export function diagnoseGuard(root) {
             return { path, status: 'invalid', message: 'Guard contracts are invalid or unsupported.' };
         }
         if (path === GUARD_CONTRACTS_FILE &&
-            guardConfig &&
-            validateGuardContracts(root, guardConfig.contracts).length > 0) {
+            (() => {
+                try {
+                    const guardConfig = loadGuardConfig(root);
+                    return (guardConfig !== undefined &&
+                        validateGuardContracts(root, guardConfig.contracts).length > 0);
+                }
+                catch {
+                    return true;
+                }
+            })()) {
             return { path, status: 'invalid', message: 'Guard contract scopes or references are stale.' };
         }
         if (path === GUARD_PROPOSALS_FILE && !isGuardProposalFile(parseJson(root, path))) {

package/dist/core/discovery/discovery.d.ts

@@ -11,6 +11,7 @@ export interface ModuleRecord {
     exports: string[];
     calls: string[];
     resolvedImports: string[];
+    resolvedImportMap?: Record<string, string>;
     dynamicImports: string[];
     declarations: {
         classes: number;
@@ -44,6 +45,8 @@ export interface ProjectModel {
             private: boolean;
             scripts: Record<string, string>;
             dependencies: string[];
+            exports?: string[];
+            projectReferences?: string[];
         }[];
     };
     files: ProjectFileRecord[];
@@ -122,6 +125,17 @@ export interface DiscoveryMetrics {
     changedFiles: number;
     reusedModules: number;
 }
+export interface DiscoveryOptions {
+    persistCache?: boolean;
+    /** Maximum number of files included in one model. */
+    maxFiles?: number;
+    /** Maximum size of one included file in bytes. */
+    maxFileBytes?: number;
+}
+export declare class DiscoveryLimitError extends Error {
+    constructor(message: string);
+}
+export declare function clearDiscoveryCache(root: string): void;
 export declare function findGuardRoot(from?: string): string;
 /** Build the internal module graph from AST resolution plus conservative fallback resolution.
  *
@@ -130,12 +144,8 @@ export declare function findGuardRoot(from?: string): string;
  * no resolved imports silently drops unresolved edges from mixed projects.
  */
 export declare function buildModuleTargetGraph(modules: ModuleRecord[]): Map<string, string[]>;
-export declare function discoverProject(root: string, options?: {
-    persistCache?: boolean;
-}): ProjectModel;
-export declare function discoverProjectWithMetrics(root: string, options?: {
-    persistCache?: boolean;
-}): {
+export declare function discoverProject(root: string, options?: DiscoveryOptions): ProjectModel;
+export declare function discoverProjectWithMetrics(root: string, options?: DiscoveryOptions): {
     model: ProjectModel;
     metrics: DiscoveryMetrics;
 };