@codapult/guard 0.4.0 → 0.5.0

package/README.md

@@ -327,6 +327,9 @@ and Guard rejects the same declared actor when a proposal was generated with `GU
 These variables provide declared provenance only; external branch protection or signed identity
 remains responsible for proving who approved the change.
 
+See [the extension map](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:

package/dist/adapters/command.d.ts

@@ -5,6 +5,7 @@ export interface CommandResult {
     exitCode: number;
     stdout: string;
     stderr: string;
+    durationMs: number;
     timedOut?: boolean | undefined;
     truncated?: boolean | undefined;
 }

package/dist/adapters/command.js

@@ -24,6 +24,7 @@ function parseCommand(command) {
     return { executable: windowsExecutable, args };
 }
 export function runProjectCommand(command, cwd, options = {}) {
+    const startedAt = Date.now();
     const parsed = parseCommand(command);
     if (!parsed) {
         return {
@@ -33,6 +34,7 @@ export function runProjectCommand(command, cwd, options = {}) {
             exitCode: 2,
             stdout: '',
             stderr: 'Unsafe or empty project command rejected.',
+            durationMs: 0,
         };
     }
     try {
@@ -51,6 +53,7 @@ export function runProjectCommand(command, cwd, options = {}) {
             exitCode: 0,
             stdout: captured.value,
             stderr: '',
+            durationMs: Math.max(0, Date.now() - startedAt),
             truncated: captured.truncated,
         };
     }
@@ -68,6 +71,7 @@ export function runProjectCommand(command, cwd, options = {}) {
             exitCode,
             stdout: stdout.value,
             stderr: timedOut ? `${stderr.value}\n[command timed out]` : stderr.value,
+            durationMs: Math.max(0, Date.now() - startedAt),
             timedOut,
             truncated: stdout.truncated || stderr.truncated,
         };

package/dist/adapters/project-checks.js

@@ -12,6 +12,7 @@ function notConfigured(check) {
         exitCode: 0,
         stdout: '',
         stderr: `${check} script is not configured`,
+        durationMs: 0,
     };
 }
 function readPackageMetadata(root) {
@@ -119,6 +120,9 @@ const adapterScriptPatterns = {
     'dependency-graph': /(?:dep(?:endency)?[-:]?(?:check|graph|cruise)|madge|architecture)/i,
     security: /(?:security|semgrep|gitleaks|snyk|trivy|audit)/i,
     'dependency-hygiene': /(?:knip|dep(?:endency)?[-:]?(?:unused|hygiene))/i,
+    sast: /(?:semgrep|codeql|bearer|sast)/i,
+    'secret-scanning': /(?:gitleaks|trufflehog|secret[-_ ]?scan)/i,
+    'dependency-audit': /(?:npm audit|pnpm audit|yarn audit|osv|snyk|trivy|dependency[-_ ]?audit)/i,
 };
 /** Runs only explicitly configured project scripts; Guard does not recreate these tools. */
 export function runProjectAdapters(root, options = {}) {
@@ -126,6 +130,7 @@ export function runProjectAdapters(root, options = {}) {
     const manager = packageManager(root, metadata.packageManager);
     const scripts = metadata.scripts ?? {};
     const results = {};
+    const executed = new Map();
     for (const [adapter, pattern] of Object.entries(adapterScriptPatterns)) {
         const configured = options.tooling?.[adapter];
         const script = configured?.enabled
@@ -141,9 +146,13 @@ export function runProjectAdapters(root, options = {}) {
             continue;
         }
         const command = manager === 'npm' ? `npm run ${script}` : `${manager} run ${script}`;
-        results[adapter] = runProjectCommand(command, root, {
-            timeout: options.timeout ?? 120_000,
-        });
+        const previous = executed.get(command);
+        const result = previous ??
+            runProjectCommand(command, root, {
+                timeout: options.timeout ?? 120_000,
+            });
+        executed.set(command, result);
+        results[adapter] = result;
     }
     return results;
 }

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

@@ -42,6 +42,7 @@ export declare function guardDoctorCommand(options?: GuardOutputOptions & {
     fixCache?: boolean | undefined;
 }): void;
 export declare function guardHistoryCommand(): void;
+export declare function guardRunsCommand(options?: GuardOutputOptions): void;
 export declare function guardImpactCommand(files: string[], options?: GuardOutputOptions): void;
 export declare function guardHistoryDiffCommand(from: string, to: string, options?: GuardOutputOptions): void;
 export declare function guardVerifyCommand(options?: GuardVerifyOptions): void;

package/dist/cli/commands/guard.js

@@ -9,6 +9,7 @@ import { guardAgentTargets, installGuardAgentInstructions, installGuardAgentTarg
 import { dim, fail, heading, info, success, warn } from '../ui.js';
 import { guardFindingsToSarif } from '../../core/output/sarif.js';
 import { analyzeProjectImpact } from '../../core/analysis/impact.js';
+import { listGuardRuns, summarizeGuardRuns } from '../../core/history/runs.js';
 function renderFindings(findings) {
     for (const finding of findings) {
         const printer = finding.severity === 'error' ? fail : finding.severity === 'warning' ? warn : info;
@@ -194,6 +195,19 @@ export function guardHistoryCommand() {
         info(`${snapshot.revision}: ${snapshot.files} files, ${snapshot.modules} modules, ${snapshot.cycles} cycles`);
     }
 }
+export function guardRunsCommand(options = {}) {
+    const root = getRoot();
+    const result = { summary: summarizeGuardRuns(root), runs: listGuardRuns(root) };
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    heading('Codapult Guard Runs');
+    info(`${result.summary.total} run(s); ${result.summary.failed} failed, ${result.summary.warnings} warning, average ${result.summary.averageDurationMs} ms`);
+    for (const run of result.runs) {
+        info(`${run.runId}: ${run.outcome}, gate=${run.gate}, ${run.durationMs} ms`);
+    }
+}
 export function guardImpactCommand(files, options = {}) {
     const root = getRoot();
     if (files.length === 0) {

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/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, guardPolicyExplainCommand, guardProposeCommand, guardReviewCommand, guardRulesApproveCommand, guardVerifyCommand, } from './commands/guard.js';
+import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardImpactCommand, guardInitCommand, guardInstallAgentCommand, guardPolicyExplainCommand, guardProposeCommand, guardReviewCommand, guardRunsCommand, guardRulesApproveCommand, guardVerifyCommand, } from './commands/guard.js';
 import { config } from '../core/config.js';
 import { GuardBaselineReasonError, GuardConfigError, GuardStateBusyError, GuardStateStaleError, } from '../core/guard.js';
 import { guardErrorPayload } from '../core/errors.js';
@@ -22,6 +22,7 @@ guard.command('propose').option('--json').action(guardProposeCommand);
 guard.command('install-agent [target]').option('--json').action(guardInstallAgentCommand);
 guard.command('doctor').option('--json').option('--fix-cache').action(guardDoctorCommand);
 guard.command('history').action(guardHistoryCommand);
+guard.command('runs').option('--json').action(guardRunsCommand);
 guard.command('history-diff <from> <to>').option('--json').action(guardHistoryDiffCommand);
 guard.command('impact <files...>').option('--json').action(guardImpactCommand);
 guard

package/dist/core/history/runs.d.ts

@@ -1,4 +1,5 @@
 export declare const GUARD_RUNS_DIR: string;
+export declare const GUARD_RUN_RETENTION = 200;
 export interface GuardRunStage {
     durationMs: number;
     status: 'ok' | 'fail' | 'skipped';
@@ -22,7 +23,21 @@ export interface GuardRunContext {
     startedAtMs: number;
     stages: Record<string, GuardRunStage>;
 }
+export interface GuardRunSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    warnings: number;
+    averageDurationMs: number;
+    last?: GuardRunManifest | undefined;
+}
+export declare class GuardRunManifestError extends Error {
+    constructor();
+}
 export declare function startGuardRun(): GuardRunContext;
 export declare function recordGuardRunStage(context: GuardRunContext, name: string, status: GuardRunStage['status'], startedAtMs: number, detail?: string): void;
 export declare function writeGuardRun(root: string, manifest: GuardRunManifest): void;
+/** Reads locally persisted run manifests without reaching a remote service. */
+export declare function listGuardRuns(root: string, limit?: number): GuardRunManifest[];
+export declare function summarizeGuardRuns(root: string, limit?: number): GuardRunSummary;
 export declare function finishGuardRun(root: string, context: GuardRunContext, outcome: GuardRunManifest['outcome'], gate: string, command?: string): GuardRunManifest;

package/dist/core/history/runs.js

@@ -1,9 +1,40 @@
 import { randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { resolve } from 'node:path';
 import { config } from '../config.js';
 export const GUARD_RUNS_DIR = `.${config.appName}/guard/history/runs`;
+export const GUARD_RUN_RETENTION = 200;
+export class GuardRunManifestError extends Error {
+    constructor() {
+        super('Guard run manifest is invalid or contains an unsafe run ID.');
+        this.name = 'GuardRunManifestError';
+    }
+}
+function isGuardRunManifest(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const manifest = value;
+    return (manifest.version === 1 &&
+        typeof manifest.runId === 'string' &&
+        /^guard-[A-Za-z0-9-]+$/.test(manifest.runId) &&
+        typeof manifest.command === 'string' &&
+        typeof manifest.startedAt === 'string' &&
+        Number.isFinite(Date.parse(manifest.startedAt)) &&
+        typeof manifest.completedAt === 'string' &&
+        Number.isFinite(Date.parse(manifest.completedAt)) &&
+        typeof manifest.durationMs === 'number' &&
+        Number.isFinite(manifest.durationMs) &&
+        manifest.durationMs >= 0 &&
+        (manifest.outcome === 'pass' ||
+            manifest.outcome === 'fail' ||
+            manifest.outcome === 'warning' ||
+            manifest.outcome === 'needs-review' ||
+            manifest.outcome === 'not-configured') &&
+        typeof manifest.gate === 'string' &&
+        manifest.stages !== null &&
+        typeof manifest.stages === 'object');
+}
 export function startGuardRun() {
     return {
         runId: `guard-${randomUUID()}`,
@@ -19,13 +50,77 @@ export function recordGuardRunStage(context, name, status, startedAtMs, detail)
         ...(detail ? { detail } : {}),
     };
 }
+function pruneGuardRuns(root) {
+    const directory = resolve(root, GUARD_RUNS_DIR);
+    try {
+        const files = readdirSync(directory)
+            .filter((file) => file.endsWith('.json'))
+            .map((file) => ({
+            file,
+            modifiedAt: statSync(resolve(directory, file)).mtimeMs,
+        }))
+            .sort((left, right) => right.modifiedAt - left.modifiedAt);
+        for (const entry of files.slice(GUARD_RUN_RETENTION)) {
+            try {
+                unlinkSync(resolve(directory, entry.file));
+            }
+            catch {
+                // Retention is best effort; a concurrent reader may own the file.
+            }
+        }
+    }
+    catch {
+        // Diagnostics must never fail because retention cannot be completed.
+    }
+}
 export function writeGuardRun(root, manifest) {
+    if (!isGuardRunManifest(manifest))
+        throw new GuardRunManifestError();
     const directory = resolve(root, GUARD_RUNS_DIR);
     mkdirSync(directory, { recursive: true });
     const path = resolve(directory, `${manifest.runId}.json`);
     const temporaryPath = `${path}.tmp-${process.pid}-${manifest.runId}`;
     writeFileSync(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
     renameSync(temporaryPath, path);
+    pruneGuardRuns(root);
+}
+/** Reads locally persisted run manifests without reaching a remote service. */
+export function listGuardRuns(root, limit = 20) {
+    if (!Number.isInteger(limit) || limit < 1)
+        return [];
+    const boundedLimit = Math.min(limit, 1_000);
+    const directory = resolve(root, GUARD_RUNS_DIR);
+    try {
+        return readdirSync(directory)
+            .filter((file) => file.endsWith('.json'))
+            .map((file) => {
+            try {
+                const value = JSON.parse(readFileSync(resolve(directory, file), 'utf8'));
+                return isGuardRunManifest(value) ? value : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        })
+            .filter((manifest) => manifest !== undefined)
+            .sort((left, right) => right.completedAt.localeCompare(left.completedAt))
+            .slice(0, boundedLimit);
+    }
+    catch {
+        return [];
+    }
+}
+export function summarizeGuardRuns(root, limit = 100) {
+    const runs = listGuardRuns(root, limit);
+    const total = runs.length;
+    return {
+        total,
+        passed: runs.filter((run) => run.outcome === 'pass').length,
+        failed: runs.filter((run) => run.outcome === 'fail').length,
+        warnings: runs.filter((run) => run.outcome === 'warning').length,
+        averageDurationMs: total === 0 ? 0 : Math.round(runs.reduce((sum, run) => sum + run.durationMs, 0) / total),
+        ...(total > 0 ? { last: runs[0] } : {}),
+    };
 }
 export function finishGuardRun(root, context, outcome, gate, command = 'verify') {
     let commit;

package/dist/core/model/types.d.ts

@@ -6,5 +6,5 @@ export type GuardContractKind = 'guidance' | 'import-boundary' | 'required-call'
 export type GuardBudgetMetric = 'lines' | 'bytes' | 'imports';
 export type GuardToolMode = 'auto' | 'on' | 'off';
 export type GuardApprovalMode = 'local' | 'protected';
-export type GuardAdapterName = 'dependency-graph' | 'security' | 'dependency-hygiene';
+export type GuardAdapterName = 'dependency-graph' | 'security' | 'dependency-hygiene' | 'sast' | 'secret-scanning' | 'dependency-audit';
 export type ProjectCheck = 'lint' | 'typecheck' | 'test' | 'build';

package/dist/mcp/resources.js

@@ -1,6 +1,7 @@
 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' }],
@@ -20,6 +21,19 @@ function resourceError(uri, error) {
     }));
 }
 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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codapult/guard",
-  "version": "0.4.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",