@codapult/guard 0.3.0 → 0.5.0

package/dist/mcp/resources.js

@@ -1,23 +1,57 @@
-import { buildArchitectureMemory, buildConventionsMemory, discoverProject, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadGuardAgentConfig, loadGuardArtifact, loadGuardConfig, loadGuardProposals, } from '../core/guard.js';
+import { buildArchitectureMemory, buildConventionsMemory, discoverProject, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadGuardAgentConfig, loadGuardArtifact, loadGuardConfig, loadGuardProposals, GuardStateBusyError, GuardStateStaleError, } from '../core/guard.js';
+import { guardErrorPayload } from '../core/errors.js';
+import { DiscoveryStaleError } from '../core/discovery/discovery.js';
+import { listGuardRuns, summarizeGuardRuns } from '../core/history/runs.js';
 function jsonResource(uri, value) {
     return {
         contents: [{ uri, text: JSON.stringify(value, null, 2), mimeType: 'application/json' }],
     };
 }
+function resourceError(uri, error) {
+    const errorCode = error instanceof GuardStateBusyError
+        ? 'GUARD_STATE_BUSY'
+        : error instanceof GuardStateStaleError || error instanceof DiscoveryStaleError
+            ? 'GUARD_STATE_STALE'
+            : 'GUARD_CONFIG_INVALID';
+    return jsonResource(uri, guardErrorPayload(errorCode, error instanceof Error ? error.message : String(error), {
+        configured: errorCode !== 'GUARD_CONFIG_INVALID',
+        outcome: 'error',
+        recoverable: true,
+        hint: 'Repair the invalid Guard artifact, then run codapult-guard doctor.',
+    }));
+}
 export function registerGuardResources(server) {
+    server.registerResource('codapult_guard_runs', 'codapult://guard/runs', {
+        title: 'Guard Run History',
+        description: 'Local verification outcomes, gates, and stage timings.',
+        mimeType: 'application/json',
+    }, () => {
+        const root = findGuardRoot();
+        return jsonResource('codapult://guard/runs', {
+            version: 1,
+            root,
+            summary: summarizeGuardRuns(root),
+            runs: listGuardRuns(root),
+        });
+    });
     server.registerResource('codapult_guard_rules', 'codapult://guard/rules', {
         title: 'Architecture Guard Rules',
         description: 'Local architecture invariants available to CLI checks and AI agents',
         mimeType: 'application/json',
     }, () => {
         const root = findGuardRoot();
-        const config = loadGuardConfig(root);
-        return jsonResource('codapult://guard/rules', {
-            configured: config !== undefined,
-            rules: config?.rules ?? [],
-            contracts: config?.contracts ?? [],
-            project: discoverProject(root),
-        });
+        try {
+            const config = loadGuardConfig(root);
+            return jsonResource('codapult://guard/rules', {
+                configured: config !== undefined,
+                rules: config?.rules ?? [],
+                contracts: config?.contracts ?? [],
+                project: discoverProject(root),
+            });
+        }
+        catch (error) {
+            return resourceError('codapult://guard/rules', error);
+        }
     });
     server.registerResource('codapult_guard_context', 'codapult://guard/context', {
         title: 'Guard Project Context',
@@ -25,19 +59,24 @@ export function registerGuardResources(server) {
         mimeType: 'application/json',
     }, () => {
         const root = findGuardRoot();
-        const project = discoverProject(root);
-        const config = loadGuardConfig(root);
-        return jsonResource('codapult://guard/context', {
-            version: 1,
-            root,
-            configured: config !== undefined,
-            project,
-            architecture: loadGuardArtifact(root, GUARD_ARCHITECTURE_FILE) ?? buildArchitectureMemory(project),
-            conventions: loadGuardArtifact(root, GUARD_CONVENTIONS_FILE) ?? buildConventionsMemory(project),
-            rules: config?.rules ?? [],
-            contracts: config?.contracts ?? [],
-            agent: loadGuardAgentConfig(root),
-        });
+        try {
+            const project = discoverProject(root);
+            const config = loadGuardConfig(root);
+            return jsonResource('codapult://guard/context', {
+                version: 1,
+                root,
+                configured: config !== undefined,
+                project,
+                architecture: loadGuardArtifact(root, GUARD_ARCHITECTURE_FILE) ?? buildArchitectureMemory(project),
+                conventions: loadGuardArtifact(root, GUARD_CONVENTIONS_FILE) ?? buildConventionsMemory(project),
+                rules: config?.rules ?? [],
+                contracts: config?.contracts ?? [],
+                agent: loadGuardAgentConfig(root),
+            });
+        }
+        catch (error) {
+            return resourceError('codapult://guard/context', error);
+        }
     });
     server.registerResource('codapult_guard_architecture', 'codapult://guard/architecture', {
         title: 'Guard Architecture Map',
@@ -45,13 +84,18 @@ export function registerGuardResources(server) {
         mimeType: 'application/json',
     }, () => {
         const root = findGuardRoot();
-        const project = discoverProject(root);
-        return jsonResource('codapult://guard/architecture', {
-            version: 1,
-            root,
-            architecture: loadGuardArtifact(root, GUARD_ARCHITECTURE_FILE) ?? buildArchitectureMemory(project),
-            conventions: loadGuardArtifact(root, GUARD_CONVENTIONS_FILE) ?? buildConventionsMemory(project),
-        });
+        try {
+            const project = discoverProject(root);
+            return jsonResource('codapult://guard/architecture', {
+                version: 1,
+                root,
+                architecture: loadGuardArtifact(root, GUARD_ARCHITECTURE_FILE) ?? buildArchitectureMemory(project),
+                conventions: loadGuardArtifact(root, GUARD_CONVENTIONS_FILE) ?? buildConventionsMemory(project),
+            });
+        }
+        catch (error) {
+            return resourceError('codapult://guard/architecture', error);
+        }
     });
     server.registerResource('codapult_guard_proposals', 'codapult://guard/proposals', {
         title: 'Architecture Guard Proposals',
@@ -59,6 +103,11 @@ export function registerGuardResources(server) {
         mimeType: 'application/json',
     }, () => {
         const root = findGuardRoot();
-        return jsonResource('codapult://guard/proposals', loadGuardProposals(root) ?? { version: 1, rules: [], contracts: [], questions: [] });
+        try {
+            return jsonResource('codapult://guard/proposals', loadGuardProposals(root) ?? { version: 1, rules: [], contracts: [], questions: [] });
+        }
+        catch (error) {
+            return resourceError('codapult://guard/proposals', error);
+        }
     });
 }

package/dist/mcp/tools/guard.js

@@ -1,4 +1,4 @@
-import { buildArchitectureMemory, buildConventionsMemory, buildGeneratedGuardConfig, buildGuardProposals, buildGuardReviewPacket, discoverProject, discoverProjectWithMetrics, fingerprintProjectModel, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadBaseline, loadGuardArtifact, loadGuardConfig, loadGuardAgentConfig, loadGuardProposals, getPendingGuardProposals, getGuardProposalFreshness, loadProjectModel, writeGuardProposals, initializeGuard, GuardAlreadyInitializedError, recordGuardProposalDecision, writeGuardConfig, writeGuardMemory, writeProjectModel, writeProjectSnapshot, scanGuard, validateGuardContracts, classifyGuardOutcome, } from '../../core/guard.js';
+import { buildArchitectureMemory, buildConventionsMemory, buildGeneratedGuardConfig, buildGuardProposals, buildGuardReviewPacket, discoverProject, discoverProjectWithMetrics, fingerprintProjectModel, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadBaseline, loadGuardArtifact, loadGuardConfig, loadGuardAgentConfig, loadGuardProposals, getPendingGuardProposals, getGuardProposalFreshness, loadProjectModel, writeGuardProposals, initializeGuard, GuardAlreadyInitializedError, GuardStateBusyError, GuardStateStaleError, applyGuardProposalDecision, validateGuardProposalApproval, writeProjectState, scanGuard, validateGuardPolicy, classifyGuardOutcome, } from '../../core/guard.js';
 import { guardErrorPayload } from '../../core/errors.js';
 import { analyzeProjectImpact } from '../../core/analysis/impact.js';
 import { z } from 'zod';
@@ -38,6 +38,63 @@ function loadConfigSafely(root) {
         };
     }
 }
+function loadBaselineSafely(root) {
+    try {
+        return { baseline: loadBaseline(root) };
+    }
+    catch (error) {
+        return {
+            error: jsonToolResult(guardErrorPayload('GUARD_CONFIG_INVALID', error instanceof Error ? error.message : String(error), {
+                configured: true,
+                outcome: 'error',
+                recoverable: true,
+                hint: 'Repair baseline.json, then run codapult-guard doctor.',
+            }), true),
+        };
+    }
+}
+function stateErrorResult(error) {
+    const isBusy = error instanceof GuardStateBusyError;
+    const isStale = error instanceof GuardStateStaleError;
+    if (!isBusy && !isStale)
+        return undefined;
+    return jsonToolResult(guardErrorPayload(isBusy ? 'GUARD_STATE_BUSY' : 'GUARD_STATE_STALE', String(error), {
+        configured: true,
+        outcome: 'error',
+        recoverable: true,
+        hint: 'Re-read Guard state and retry the operation.',
+    }), true);
+}
+function loadAgentSafely(root) {
+    try {
+        return { config: loadGuardAgentConfig(root) };
+    }
+    catch (error) {
+        return {
+            error: jsonToolResult(guardErrorPayload('GUARD_CONFIG_INVALID', error instanceof Error ? error.message : String(error), {
+                configured: false,
+                outcome: 'error',
+                recoverable: true,
+                hint: 'Repair agent.json, then run codapult-guard doctor.',
+            }), true),
+        };
+    }
+}
+function loadProposalsSafely(root) {
+    try {
+        return { proposals: loadGuardProposals(root) };
+    }
+    catch (error) {
+        return {
+            error: jsonToolResult(guardErrorPayload('GUARD_CONFIG_INVALID', error instanceof Error ? error.message : String(error), {
+                configured: false,
+                outcome: 'error',
+                recoverable: true,
+                hint: 'Repair proposals.json, then run codapult-guard doctor.',
+            }), true),
+        };
+    }
+}
 export function registerGuardTools(server) {
     server.registerTool('codapult_guard_analyze', {
         title: 'Refresh Guard Model',
@@ -48,15 +105,25 @@ export function registerGuardTools(server) {
                 .boolean()
                 .default(false)
                 .describe('Required before writing refreshed Guard state.'),
+            wait_ms: z.number().int().min(0).max(120_000).default(30_000),
+            no_wait: z.boolean().default(false),
         },
-    }, ({ root: requestedRoot, confirm }) => {
+    }, ({ root: requestedRoot, confirm, wait_ms, no_wait }) => {
         const root = getGuardRoot(requestedRoot);
         if (!confirm)
             return jsonToolResult({ status: 'needs-confirmation', action: 'analyze' });
         const discovery = discoverProjectWithMetrics(root, { persistCache: true });
-        writeProjectModel(root, discovery.model);
-        writeGuardMemory(root, discovery.model);
-        const revision = writeProjectSnapshot(root, discovery.model);
+        let revision;
+        try {
+            revision = writeProjectState(root, discovery.model, {
+                waitMs: wait_ms,
+                noWait: no_wait,
+            });
+        }
+        catch (error) {
+            return (stateErrorResult(error) ??
+                jsonToolResult({ status: 'fail', message: String(error) }, true));
+        }
         return jsonToolResult({
             status: 'ok',
             action: 'analyze',
@@ -93,7 +160,10 @@ export function registerGuardTools(server) {
                 canRetry: false,
             });
         }
-        const proposals = loadGuardProposals(root);
+        const loadedProposals = loadProposalsSafely(root);
+        if ('error' in loadedProposals)
+            return loadedProposals.error;
+        const proposals = loadedProposals.proposals;
         const proposedCount = getPendingGuardProposals(proposals).length;
         if (proposals && getGuardProposalFreshness(project, proposals) === 'stale') {
             return jsonToolResult({
@@ -111,12 +181,15 @@ export function registerGuardTools(server) {
                 canRetry: false,
             });
         }
+        const loadedBaseline = loadBaselineSafely(root);
+        if (loadedBaseline.error)
+            return loadedBaseline.error;
         const report = scanGuard(root, config, {
             changedOnly: true,
-            baseline: loadBaseline(root),
+            baseline: loadedBaseline.baseline,
             includeArchitectureInsights: true,
         });
-        const contractIssues = validateGuardContracts(root, config.contracts ?? []);
+        const contractIssues = validateGuardPolicy(root, config);
         if (report.findings.some((finding) => finding.severity === 'error')) {
             return jsonToolResult({
                 status: 'needs-repair',
@@ -158,7 +231,10 @@ export function registerGuardTools(server) {
         if (loaded.error)
             return loaded.error;
         const config = loaded.config;
-        const agentConfig = loadGuardAgentConfig(root);
+        const agent = loadAgentSafely(root);
+        if ('error' in agent)
+            return agent.error;
+        const agentConfig = agent.config;
         const discovery = refresh
             ? discoverProjectWithMetrics(root, { persistCache: true })
             : { model: loadProjectModel(root) ?? discoverProject(root), metrics: undefined };
@@ -210,7 +286,10 @@ export function registerGuardTools(server) {
             return loaded.error;
         const config = loaded.config ?? buildGeneratedGuardConfig(project);
         const proposals = buildGuardProposals(project, config);
-        const previous = loadGuardProposals(root);
+        const loadedPrevious = loadProposalsSafely(root);
+        if ('error' in loadedPrevious)
+            return loadedPrevious.error;
+        const previous = loadedPrevious.proposals;
         if (persist) {
             writeGuardProposals(root, {
                 ...proposals,
@@ -243,16 +322,21 @@ export function registerGuardTools(server) {
                 .boolean()
                 .default(false)
                 .describe('Replace existing Guard state; requires confirm.'),
+            wait_ms: z.number().int().min(0).max(120_000).default(30_000),
+            no_wait: z.boolean().default(false),
         },
-    }, ({ root: requestedRoot, confirm, force }) => {
+    }, ({ root: requestedRoot, confirm, force, wait_ms, no_wait }) => {
         const root = getGuardRoot(requestedRoot);
         if (!confirm)
             return jsonToolResult({ status: 'needs-confirmation', root, force });
         try {
-            const result = initializeGuard(root, { force });
+            const result = initializeGuard(root, { force, waitMs: wait_ms, noWait: no_wait });
             return jsonToolResult({ status: 'ok', root, report: result.report });
         }
         catch (error) {
+            const stateError = stateErrorResult(error);
+            if (stateError)
+                return stateError;
             const status = error instanceof GuardAlreadyInitializedError ? 'already-initialized' : 'fail';
             return jsonToolResult({ status, root, message: error instanceof Error ? error.message : String(error) }, true);
         }
@@ -268,7 +352,10 @@ export function registerGuardTools(server) {
         },
     }, ({ root: requestedRoot, ids, decision, confirm }) => {
         const root = getGuardRoot(requestedRoot);
-        const proposals = loadGuardProposals(root);
+        const loadedProposals = loadProposalsSafely(root);
+        if ('error' in loadedProposals)
+            return loadedProposals.error;
+        const proposals = loadedProposals.proposals;
         if (!proposals)
             return jsonToolResult({ status: 'not-configured', message: 'No proposals found.' }, true);
         const project = discoverProject(root);
@@ -279,13 +366,28 @@ export function registerGuardTools(server) {
         const missing = ids.filter((id) => !selected.some((item) => item.id === id));
         if (missing.length > 0)
             return jsonToolResult({ status: 'invalid', missing }, true);
+        const loadedConfig = loadConfigSafely(root);
+        if (loadedConfig.error)
+            return loadedConfig.error;
+        const approval = loadedConfig.config?.approval;
+        if (decision === 'approved' && approval?.mode === 'protected' && !approval.allowMcpApproval) {
+            return jsonToolResult({
+                status: 'approval-required',
+                message: 'Protected Guard policy requires approval outside the MCP agent surface.',
+                source: 'mcp',
+                ids,
+            }, true);
+        }
+        if (decision === 'approved') {
+            const approvalError = validateGuardProposalApproval(approval, proposals);
+            if (approvalError) {
+                return jsonToolResult({ status: 'approval-required', message: approvalError, source: 'mcp', ids }, true);
+            }
+        }
         if (!confirm)
             return jsonToolResult({ status: 'needs-confirmation', decision, ids });
         if (decision === 'approved') {
-            const loaded = loadConfigSafely(root);
-            if (loaded.error)
-                return loaded.error;
-            const config = loaded.config ?? { version: 1, rules: [], contracts: [] };
+            const config = loadedConfig.config ?? { version: 1, rules: [], contracts: [] };
             const nextRules = [...config.rules];
             const nextContracts = [...(config.contracts ?? [])];
             for (const item of selected) {
@@ -306,13 +408,19 @@ export function registerGuardTools(server) {
                         nextRules.push(active);
                 }
             }
-            writeGuardConfig(root, { version: 1, rules: nextRules, contracts: nextContracts });
+            applyGuardProposalDecision(root, { version: 1, rules: nextRules, contracts: nextContracts }, selected.map((item) => ({
+                id: item.id,
+                type: 'statement' in item ? 'contract' : 'rule',
+                decision,
+            })), { source: 'mcp' });
+        }
+        else {
+            applyGuardProposalDecision(root, loadedConfig.config ?? { version: 1, rules: [], contracts: [] }, selected.map((item) => ({
+                id: item.id,
+                type: 'statement' in item ? 'contract' : 'rule',
+                decision,
+            })), { source: 'mcp' });
         }
-        recordGuardProposalDecision(root, selected.map((item) => ({
-            id: item.id,
-            type: 'statement' in item ? 'contract' : 'rule',
-            decision,
-        })));
         return jsonToolResult({ status: 'ok', root, decision, ids });
     });
     server.registerTool('codapult_guard_verify', {
@@ -339,6 +447,9 @@ export function registerGuardTools(server) {
         },
     }, ({ root: requestedRoot, checks, changed_only, requirement, tools, strict, project_checks, iteration, }) => {
         const root = getGuardRoot(requestedRoot);
+        const agent = loadAgentSafely(root);
+        if ('error' in agent)
+            return agent.error;
         const result = runGuardVerification(root, {
             checks,
             changedOnly: changed_only,
@@ -347,7 +458,7 @@ export function registerGuardTools(server) {
             strict,
             projectChecks: project_checks,
         });
-        const completionGate = loadGuardAgentConfig(root).completionGate;
+        const completionGate = agent.config.completionGate;
         return jsonToolResult({
             ...result,
             completionGate: {
@@ -371,7 +482,7 @@ export function registerGuardTools(server) {
             return notConfiguredToolResult();
         }
         const report = scanGuard(root, config, { includeArchitectureInsights: true });
-        const contractIssues = validateGuardContracts(root, config.contracts ?? []);
+        const contractIssues = validateGuardPolicy(root, config);
         const errors = report.findings.filter((finding) => finding.severity === 'error').length;
         const warnings = report.findings.filter((finding) => finding.severity === 'warning').length;
         const status = errors > 0 || contractIssues.length > 0 ? 'fail' : warnings > 0 ? 'warning' : 'ok';
@@ -411,7 +522,12 @@ export function registerGuardTools(server) {
         if (!config) {
             return notConfiguredToolResult();
         }
-        const packet = buildGuardReviewPacket(root, config, changed_only ? loadBaseline(root) : new Set(), max_diff_chars, changed_only, requirement, base);
+        const loadedBaseline = changed_only
+            ? loadBaselineSafely(root)
+            : { baseline: new Set() };
+        if (loadedBaseline.error)
+            return loadedBaseline.error;
+        const packet = buildGuardReviewPacket(root, config, loadedBaseline.baseline ?? new Set(), max_diff_chars, changed_only, requirement, base);
         return jsonToolResult({ ...packet, status: packet.diffError ? 'fail' : 'needs-review' }, Boolean(packet.diffError));
     });
     server.registerTool('codapult_guard_check', {
@@ -427,12 +543,15 @@ export function registerGuardTools(server) {
         if (!config) {
             return notConfiguredToolResult();
         }
+        const loadedBaseline = loadBaselineSafely(root);
+        if (loadedBaseline.error)
+            return loadedBaseline.error;
         const report = scanGuard(root, config, {
             changedOnly: changed_only,
-            baseline: loadBaseline(root),
+            baseline: loadedBaseline.baseline,
             includeArchitectureInsights: true,
         });
-        const contractIssues = validateGuardContracts(root, config.contracts ?? []);
+        const contractIssues = validateGuardPolicy(root, config);
         const errors = report.findings.filter((finding) => finding.severity === 'error').length;
         return jsonToolResult({
             status: errors > 0 || contractIssues.length > 0 ? 'fail' : 'ok',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codapult/guard",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Local-first architecture guardrails for JavaScript and TypeScript projects, with first-class support for Next.js SaaS and AI-assisted development",
   "license": "MIT",
   "packageManager": "pnpm@12.4.2+sha512.08adc6613180275c7c9edada39dcf08c9c61ad4e7eaf330a4f3461f102b0f907423454d117f98e72d47fef0616070644d7bffc973a6a57f5090a6d7c368b07c9",
@@ -104,19 +104,19 @@
   },
   "devDependencies": {
     "@js-toolkit/config-utils": "^1.0.1",
-    "@js-toolkit/eslint-config": "^1.3.0",
+    "@js-toolkit/eslint-config": "^1.3.2",
     "@js-toolkit/prettier-config": "^1.0.1",
     "@js-toolkit/tsconfig": "^1.0.1",
     "@release-it/conventional-changelog": "^12.0.2",
-    "@types/node": "^26.6.1",
+    "@types/node": "^26.6.2",
     "@typescript/native": "npm:typescript@^7.0.2",
     "@vitest/coverage-v8": "^5.0.1",
-    "eslint": "^10.10.0",
+    "eslint": "^10.11.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.6",
-    "prettier": "^3.9.7",
-    "release-it": "^21.0.3",
-    "typescript-eslint": "^8.70.0",
+    "prettier": "^3.9.8",
+    "release-it": "^21.1.0",
+    "typescript-eslint": "^8.70.1",
     "vitest": "^5.0.1"
   }
 }