@toolbaux/guardian 0.1.0

package/dist/commands/diff.js

@@ -0,0 +1,146 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+export async function runDiff(options) {
+    const { baselinePath, currentPath, output } = options;
+    let baselineRaw;
+    let currentRaw;
+    try {
+        baselineRaw = await fs.readFile(baselinePath, "utf8");
+    }
+    catch (err) {
+        console.error(`Failed to read baseline snapshot at ${baselinePath}`);
+        return;
+    }
+    try {
+        currentRaw = await fs.readFile(currentPath, "utf8");
+    }
+    catch (err) {
+        console.error(`Failed to read current snapshot at ${currentPath}`);
+        return;
+    }
+    const baseline = yaml.load(baselineRaw);
+    const current = yaml.load(currentRaw);
+    const diffResult = computeDiff(baseline, current);
+    const markdownRaw = generateDiffMarkdown(diffResult);
+    await fs.mkdir(path.dirname(output), { recursive: true });
+    await fs.writeFile(output, markdownRaw, "utf8");
+    console.log(`Wrote diff markdown to ${output}`);
+}
+function computeDiff(baseline, current) {
+    const baselineEndpoints = new Map(baseline.endpoints.map(e => [e.id, e]));
+    const currentEndpoints = new Map(current.endpoints.map(e => [e.id, e]));
+    const endpointAdded = [];
+    const endpointRemoved = [];
+    const endpointChanged = [];
+    for (const [id, e] of currentEndpoints.entries()) {
+        if (!baselineEndpoints.has(id)) {
+            endpointAdded.push(id);
+        }
+        else {
+            const bE = baselineEndpoints.get(id);
+            if (bE.path !== e.path || bE.method !== e.method || bE.handler !== e.handler) {
+                endpointChanged.push(id);
+            }
+        }
+    }
+    for (const id of baselineEndpoints.keys()) {
+        if (!currentEndpoints.has(id)) {
+            endpointRemoved.push(id);
+        }
+    }
+    const baselineModels = new Map(baseline.data_models?.map(m => [m.name, m]) ?? []);
+    const currentModels = new Map(current.data_models?.map(m => [m.name, m]) ?? []);
+    const modelsAdded = [];
+    const modelsRemoved = [];
+    const modelsChanged = [];
+    for (const [name, m] of currentModels.entries()) {
+        if (!baselineModels.has(name)) {
+            modelsAdded.push(name);
+        }
+        else {
+            const bM = baselineModels.get(name);
+            if (bM.fields.length !== m.fields.length || bM.relationships.length !== m.relationships.length) {
+                modelsChanged.push(name);
+            }
+        }
+    }
+    for (const name of baselineModels.keys()) {
+        if (!currentModels.has(name)) {
+            modelsRemoved.push(name);
+        }
+    }
+    // To handle components we need to look at UxSnapshot mostly, but let's see if we can use frontend_files/pages
+    const baselinePages = new Set((baseline.frontend?.pages ?? []).map(p => p.path));
+    const currentPages = new Set((current.frontend?.pages ?? []).map(p => p.path));
+    const componentsAdded = [];
+    const componentsRemoved = [];
+    for (const p of currentPages) {
+        if (!baselinePages.has(p))
+            componentsAdded.push(p);
+    }
+    for (const p of baselinePages) {
+        if (!currentPages.has(p))
+            componentsRemoved.push(p);
+    }
+    return {
+        endpoints: { added: endpointAdded, removed: endpointRemoved, changed: endpointChanged },
+        models: { added: modelsAdded, removed: modelsRemoved, changed: modelsChanged },
+        components: { added: componentsAdded, removed: componentsRemoved }
+    };
+}
+function generateDiffMarkdown(diff) {
+    const lines = [];
+    lines.push("# Architecture Snapshot Changelog");
+    lines.push("");
+    lines.push(`**${diff.endpoints.added.length}** endpoints added, **${diff.models.changed.length}** models changed, **${diff.components.removed.length}** components/pages removed.`);
+    lines.push("");
+    lines.push("## Endpoints");
+    if (diff.endpoints.added.length > 0) {
+        lines.push("### Added");
+        diff.endpoints.added.forEach(e => lines.push(`- ${e}`));
+    }
+    if (diff.endpoints.removed.length > 0) {
+        lines.push("### Removed");
+        diff.endpoints.removed.forEach(e => lines.push(`- ${e}`));
+    }
+    if (diff.endpoints.changed.length > 0) {
+        lines.push("### Changed");
+        diff.endpoints.changed.forEach(e => lines.push(`- ${e}`));
+    }
+    if (diff.endpoints.added.length === 0 && diff.endpoints.removed.length === 0 && diff.endpoints.changed.length === 0) {
+        lines.push("*No changes*");
+    }
+    lines.push("");
+    lines.push("## Data Models");
+    if (diff.models.added.length > 0) {
+        lines.push("### Added");
+        diff.models.added.forEach(e => lines.push(`- ${e}`));
+    }
+    if (diff.models.removed.length > 0) {
+        lines.push("### Removed");
+        diff.models.removed.forEach(e => lines.push(`- ${e}`));
+    }
+    if (diff.models.changed.length > 0) {
+        lines.push("### Changed");
+        diff.models.changed.forEach(e => lines.push(`- ${e}`));
+    }
+    if (diff.models.added.length === 0 && diff.models.removed.length === 0 && diff.models.changed.length === 0) {
+        lines.push("*No changes*");
+    }
+    lines.push("");
+    lines.push("## Frontend Pages (Components)");
+    if (diff.components.added.length > 0) {
+        lines.push("### Added");
+        diff.components.added.forEach(e => lines.push(`- ${e}`));
+    }
+    if (diff.components.removed.length > 0) {
+        lines.push("### Removed");
+        diff.components.removed.forEach(e => lines.push(`- ${e}`));
+    }
+    if (diff.components.added.length === 0 && diff.components.removed.length === 0) {
+        lines.push("*No changes*");
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/commands/discrepancy.js

@@ -0,0 +1,71 @@
+/**
+ * `specguard discrepancy` — diff current codebase intelligence against a baseline.
+ *
+ * Reads:
+ *   - specs-out/machine/codebase-intelligence.json
+ *   - specs-out/machine/product-document.baseline.json (optional)
+ *   - feature-specs/*.yaml (optional)
+ *
+ * Writes:
+ *   - specs-out/machine/discrepancies.json  (--format json, default)
+ *   - specs-out/human/discrepancies.md      (--format md)
+ *   Both if format is omitted.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { buildDiscrepancyReport, renderDiscrepancyMarkdown, } from "../extract/discrepancies.js";
+import { loadCodebaseIntelligence } from "../extract/codebase-intel.js";
+import { getOutputLayout } from "../output-layout.js";
+export async function runDiscrepancy(options) {
+    const specsDir = path.resolve(options.specs);
+    const layout = getOutputLayout(specsDir);
+    // Load codebase intelligence
+    const intelPath = path.join(layout.machineDir, "codebase-intelligence.json");
+    const intel = await loadCodebaseIntelligence(intelPath).catch(() => {
+        throw new Error(`Could not load codebase-intelligence.json from ${intelPath}. Run \`specguard intel --specs ${options.specs}\` first.`);
+    });
+    const baselinePath = path.join(layout.machineDir, "product-document.baseline.json");
+    const featureSpecsDir = options.featureSpecs ? path.resolve(options.featureSpecs) : null;
+    const report = await buildDiscrepancyReport({
+        intel,
+        baselinePath,
+        featureSpecsDir,
+    });
+    const format = options.format ?? "json";
+    const writeJson = format === "json" || format === "both";
+    const writeMd = format === "md" || format === "both";
+    if (writeJson) {
+        const jsonPath = options.output
+            ? path.resolve(options.output)
+            : path.join(layout.machineDir, "discrepancies.json");
+        await fs.mkdir(path.dirname(jsonPath), { recursive: true });
+        await fs.writeFile(jsonPath, JSON.stringify(report, null, 2), "utf8");
+        console.log(`Wrote ${jsonPath}`);
+    }
+    if (writeMd) {
+        const mdPath = options.output && format === "md"
+            ? path.resolve(options.output)
+            : path.join(layout.humanDir, "discrepancies.md");
+        const md = renderDiscrepancyMarkdown(report);
+        await fs.mkdir(path.dirname(mdPath), { recursive: true });
+        await fs.writeFile(mdPath, md, "utf8");
+        console.log(`Wrote ${mdPath}`);
+    }
+    // Exit summary
+    const { total_issues, has_critical } = report.summary;
+    if (total_issues === 0) {
+        console.log("✓ No discrepancies found.");
+    }
+    else {
+        console.log(`${has_critical ? "⚠ " : ""}${total_issues} discrepancy(s): ` +
+            [
+                report.new_endpoints.length > 0 && `${report.new_endpoints.length} new endpoint(s)`,
+                report.removed_endpoints.length > 0 && `${report.removed_endpoints.length} removed endpoint(s)`,
+                report.drifted_models.length > 0 && `${report.drifted_models.length} drifted model(s)`,
+                report.orphan_specs.length > 0 && `${report.orphan_specs.length} orphan spec(s)`,
+                report.untracked_endpoints.length > 0 && `${report.untracked_endpoints.length} untracked endpoint(s)`,
+            ]
+                .filter(Boolean)
+                .join(", "));
+    }
+}

package/dist/commands/doc-generate.js

@@ -0,0 +1,163 @@
+/**
+ * `specguard doc-generate` — generate a human-readable, self-updating product document.
+ *
+ * Reads:
+ *   - specs-out/machine/codebase-intelligence.json
+ *   - feature-specs/*.yaml (optional)
+ *   - specs-out/machine/feature-arcs.json (optional, if exists)
+ *   - specs-out/machine/product-document.baseline.json (optional, for discrepancy section)
+ *
+ * Writes:
+ *   - specs-out/human/product-document.md
+ *   - specs-out/machine/product-document.baseline.json (if --update-baseline)
+ *
+ * LLM env vars (optional — all deterministic sections write regardless):
+ *   SPECGUARD_LLM_ENDPOINT, SPECGUARD_LLM_API_KEY, SPECGUARD_LLM_MODEL
+ *   SPECGUARD_OLLAMA_HOST, SPECGUARD_OLLAMA_MODEL
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadCodebaseIntelligence } from "../extract/codebase-intel.js";
+import { buildFeatureArcs } from "../extract/feature-arcs.js";
+import { buildDiscrepancyReport, buildBaseline, } from "../extract/discrepancies.js";
+import { renderProductDocument } from "../extract/product-doc.js";
+import { loadExistingDocs } from "../extract/docs-loader.js";
+import { loadLlmConfig } from "../extract/llm-client.js";
+import { getOutputLayout } from "../output-layout.js";
+export async function runDocGenerate(options) {
+    const specsDir = path.resolve(options.specs);
+    const layout = getOutputLayout(specsDir);
+    // ── Step 1: LLM config resolution ─────────────────────────────────────────
+    process.stdout.write("Resolving LLM config... ");
+    const llmConfig = await loadLlmConfig();
+    if (!llmConfig) {
+        console.log("none (deterministic only)");
+        console.log("  Tip: set SPECGUARD_LLM_ENDPOINT + SPECGUARD_LLM_API_KEY, or run Ollama locally, to add narrative summaries.");
+    }
+    else if (llmConfig.provider === "ollama") {
+        console.log(`Ollama (${llmConfig.model} at ${llmConfig.endpoint.replace("/api/chat", "")})`);
+    }
+    else {
+        console.log(`${llmConfig.provider} (${llmConfig.model})`);
+        console.log("  ⚠ Cloud LLM enabled — this will consume API tokens (one call per section: overview, API domains, each model). Use Ollama to avoid costs.");
+    }
+    // ── Step 2: Load codebase intelligence ────────────────────────────────────
+    const intelPath = path.join(layout.machineDir, "codebase-intelligence.json");
+    process.stdout.write("Loading codebase intelligence... ");
+    const intel = await loadCodebaseIntelligence(intelPath).catch(() => {
+        console.log("failed");
+        throw new Error(`Could not load ${intelPath}. Run \`specguard intel --specs ${options.specs}\` first.`);
+    });
+    console.log(`${intel.meta.counts.endpoints} endpoints, ${intel.meta.counts.models} models, ` +
+        `${intel.meta.counts.enums} enums, ${intel.meta.counts.tasks} tasks`);
+    // ── Step 3: Feature arcs (optional) ───────────────────────────────────────
+    const arcsPath = path.join(layout.machineDir, "feature-arcs.json");
+    let featureArcs = null;
+    if (options.featureSpecs) {
+        const featureSpecsDir = path.resolve(options.featureSpecs);
+        process.stdout.write(`Building feature arcs from ${options.featureSpecs}... `);
+        featureArcs = await buildFeatureArcs(featureSpecsDir);
+        const arcCount = Object.keys(featureArcs.arcs).length;
+        console.log(`${arcCount} arc(s)`);
+        await fs.writeFile(arcsPath, JSON.stringify(featureArcs, null, 2), "utf8");
+        console.log(`  Wrote ${arcsPath}`);
+    }
+    else {
+        try {
+            const raw = await fs.readFile(arcsPath, "utf8");
+            featureArcs = JSON.parse(raw);
+            const arcCount = Object.keys(featureArcs.arcs).length;
+            console.log(`Feature arcs: loaded from cache (${arcCount} arc(s))`);
+        }
+        catch {
+            // No arcs — skip feature timeline section silently
+        }
+    }
+    // ── Step 4: Discrepancy report ─────────────────────────────────────────────
+    const baselinePath = path.join(layout.machineDir, "product-document.baseline.json");
+    process.stdout.write("Computing discrepancies... ");
+    const discrepancies = await buildDiscrepancyReport({
+        intel,
+        baselinePath,
+        featureSpecsDir: options.featureSpecs ? path.resolve(options.featureSpecs) : null,
+    });
+    if (discrepancies.summary.total_issues === 0) {
+        console.log("none (in sync)");
+    }
+    else {
+        const critical = discrepancies.summary.has_critical ? " ⚠ critical" : "";
+        console.log(`${discrepancies.summary.total_issues} issue(s)${critical}`);
+    }
+    // ── Step 5: Load existing docs (hld.md, summary.md, integration.md, etc.) ─
+    process.stdout.write("Loading existing docs... ");
+    const existingDocs = await loadExistingDocs(layout.machineDocsDir);
+    const loadedKeys = Object.entries(existingDocs).filter(([, v]) => v != null).map(([k]) => k);
+    console.log(loadedKeys.length > 0 ? loadedKeys.join(", ") : "none");
+    // ── Step 5b: Load product context (from config description or README) ─────
+    let productContext = null;
+    {
+        // Try config.project.description first
+        // Then try README.md auto-detection
+        const readmeCandidates = [
+            path.join(path.dirname(specsDir), "README.md"),
+            path.join(path.dirname(specsDir), "readme.md"),
+            path.join(path.dirname(specsDir), "Readme.md"),
+        ];
+        for (const candidate of readmeCandidates) {
+            try {
+                const raw = await fs.readFile(candidate, "utf8");
+                // Extract first meaningful content (up to first ## or 800 chars)
+                const lines = raw.split("\n");
+                const contextLines = [];
+                let inHeader = false;
+                let sectionCount = 0;
+                for (const line of lines) {
+                    if (line.startsWith("## ") && sectionCount > 0)
+                        break; // stop at second H2
+                    if (line.startsWith("## "))
+                        sectionCount++;
+                    if (line.startsWith("# ")) {
+                        inHeader = true;
+                        continue;
+                    } // skip H1
+                    if (inHeader && line.trim() === "") {
+                        inHeader = false;
+                        continue;
+                    }
+                    contextLines.push(line);
+                    if (contextLines.join("\n").length > 800)
+                        break;
+                }
+                productContext = contextLines.join("\n").trim();
+                if (productContext.length > 0) {
+                    console.log(`Product context: loaded from README.md (${productContext.length} chars)`);
+                }
+                break;
+            }
+            catch {
+                // Not found, try next
+            }
+        }
+    }
+    // ── Step 6: Render product document ───────────────────────────────────────
+    console.log("Rendering product document...");
+    const content = await renderProductDocument({ intel, featureArcs, discrepancies, llmConfig, existingDocs, productContext });
+    // ── Step 7: Write output ───────────────────────────────────────────────────
+    const outputPath = options.output
+        ? path.resolve(options.output)
+        : path.join(layout.humanDir, "product-document.md");
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, content, "utf8");
+    console.log(`Wrote ${outputPath}`);
+    // ── Step 7: Update baseline (optional) ────────────────────────────────────
+    if (options.updateBaseline) {
+        const baseline = buildBaseline(intel);
+        await fs.writeFile(baselinePath, JSON.stringify(baseline, null, 2), "utf8");
+        console.log(`Wrote baseline ${baselinePath}`);
+    }
+    // ── Done ──────────────────────────────────────────────────────────────────
+    if (discrepancies.summary.total_issues > 0) {
+        const critical = discrepancies.summary.has_critical ? " (critical changes detected)" : "";
+        console.log(`  ⚠ ${discrepancies.summary.total_issues} discrepancy(s) found${critical}. Run \`specguard discrepancy\` for details.`);
+    }
+}

package/dist/commands/doc-html.js

@@ -0,0 +1,120 @@
+/**
+ * `specguard doc-html` — generate a self-contained Javadoc-style HTML viewer.
+ *
+ * Same data pipeline as `doc-generate` but outputs a single index.html with:
+ *   - Fixed sidebar navigation (collapsible, searchable)
+ *   - Mermaid diagrams rendered in-browser
+ *   - Tables, collapsible sections, scroll-spy active states
+ *   - No server or build step required — open directly in browser
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { loadCodebaseIntelligence } from "../extract/codebase-intel.js";
+import { buildDiscrepancyReport } from "../extract/discrepancies.js";
+import { loadExistingDocs } from "../extract/docs-loader.js";
+import { renderHtmlDoc } from "../extract/html-doc.js";
+import { getOutputLayout } from "../output-layout.js";
+export async function runDocHtml(options) {
+    const specsDir = path.resolve(options.specs);
+    const layout = getOutputLayout(specsDir);
+    // ── Load codebase intelligence ────────────────────────────────────────────
+    const intelPath = path.join(layout.machineDir, "codebase-intelligence.json");
+    process.stdout.write("Loading codebase intelligence... ");
+    const intel = await loadCodebaseIntelligence(intelPath).catch(() => {
+        console.log("failed");
+        throw new Error(`Could not load ${intelPath}. Run \`specguard intel --specs ${options.specs}\` first.`);
+    });
+    console.log(`${intel.meta.counts.endpoints} endpoints, ${intel.meta.counts.models} models`);
+    // ── Feature arcs (optional) ───────────────────────────────────────────────
+    const arcsPath = path.join(layout.machineDir, "feature-arcs.json");
+    let featureArcs = null;
+    try {
+        const raw = await fs.readFile(arcsPath, "utf8");
+        featureArcs = JSON.parse(raw);
+        const arcCount = Object.keys(featureArcs.arcs).length;
+        console.log(`Feature arcs: ${arcCount} arc(s)`);
+    }
+    catch {
+        // optional
+    }
+    // ── Discrepancy report ────────────────────────────────────────────────────
+    const baselinePath = path.join(layout.machineDir, "product-document.baseline.json");
+    process.stdout.write("Computing discrepancies... ");
+    const discrepancies = await buildDiscrepancyReport({
+        intel,
+        baselinePath,
+        featureSpecsDir: null,
+    });
+    console.log(discrepancies.summary.total_issues === 0
+        ? "none"
+        : `${discrepancies.summary.total_issues} issue(s)`);
+    // ── Load existing docs ────────────────────────────────────────────────────
+    process.stdout.write("Loading existing docs... ");
+    const existingDocs = await loadExistingDocs(layout.machineDocsDir);
+    const loadedKeys = Object.entries(existingDocs).filter(([, v]) => v != null).map(([k]) => k);
+    console.log(loadedKeys.length > 0 ? loadedKeys.join(", ") : "none");
+    // ── Load UX snapshot (for component graph) ───────────────────────────────
+    process.stdout.write("Loading UX snapshot... ");
+    let uxSnapshot = null;
+    try {
+        const uxPath = path.join(layout.machineDir, "ux.snapshot.yaml");
+        const raw = await fs.readFile(uxPath, "utf8");
+        uxSnapshot = yaml.load(raw);
+        console.log(`${uxSnapshot.components?.length ?? 0} components, ${uxSnapshot.component_graph?.length ?? 0} edges`);
+    }
+    catch {
+        console.log("not found");
+    }
+    // ── Load product context from README ──────────────────────────────────────
+    let productContext = null;
+    const readmeCandidates = [
+        path.join(path.dirname(specsDir), "README.md"),
+        path.join(path.dirname(specsDir), "readme.md"),
+    ];
+    for (const candidate of readmeCandidates) {
+        try {
+            const raw = await fs.readFile(candidate, "utf8");
+            const lines = raw.split("\n");
+            const contextLines = [];
+            let sectionCount = 0;
+            for (const line of lines) {
+                if (line.startsWith("## ") && sectionCount > 0)
+                    break;
+                if (line.startsWith("## "))
+                    sectionCount++;
+                if (line.startsWith("# "))
+                    continue;
+                contextLines.push(line);
+                if (contextLines.join("\n").length > 1200)
+                    break;
+            }
+            productContext = contextLines.join("\n").trim();
+            break;
+        }
+        catch {
+            // Not found
+        }
+    }
+    // ── Render HTML (multi-page) ──────────────────────────────────────────────
+    console.log("Rendering HTML viewer...");
+    const files = renderHtmlDoc({ intel, featureArcs, discrepancies, existingDocs, uxSnapshot, productContext });
+    // ── Write output files ────────────────────────────────────────────────────
+    const outputDir = options.output
+        ? path.resolve(options.output)
+        : path.join(layout.humanDir, "docs");
+    await fs.mkdir(outputDir, { recursive: true });
+    let totalBytes = 0;
+    for (const [filename, html] of Object.entries(files)) {
+        const filePath = path.join(outputDir, filename);
+        await fs.writeFile(filePath, html, "utf8");
+        totalBytes += Buffer.byteLength(html, "utf8");
+    }
+    const totalKb = Math.round(totalBytes / 1024);
+    const fileCount = Object.keys(files).length;
+    console.log(`Wrote ${fileCount} files to ${outputDir}/ (${totalKb} KB total)`);
+    console.log(`  Open in browser: open "${path.join(outputDir, "index.html")}"`);
+    for (const filename of Object.keys(files)) {
+        console.log(`    ${filename}`);
+    }
+}

package/dist/commands/drift.js

@@ -0,0 +1,88 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { computeProjectDrift } from "../extract/drift.js";
+import { logResolvedProjectPaths, resolveProjectPaths } from "../project-discovery.js";
+export async function runDrift(options) {
+    const resolved = await resolveProjectPaths({
+        projectRoot: options.projectRoot,
+        backendRoot: options.backendRoot,
+        frontendRoot: options.frontendRoot,
+        configPath: options.configPath
+    });
+    logResolvedProjectPaths(resolved);
+    const drift = await computeProjectDrift({
+        backendRoot: resolved.backendRoot,
+        frontendRoot: resolved.frontendRoot,
+        configPath: options.configPath
+    });
+    const outputPath = path.resolve(options.output ?? "specs-out/drift.report.json");
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, JSON.stringify(drift, null, 2));
+    if (options.baseline) {
+        const config = resolved.config;
+        const projectRoot = resolved.workspaceRoot;
+        const baselinePath = typeof options.baseline === "string"
+            ? options.baseline
+            : config.drift?.baselinePath || "specs-out/baseline.json";
+        const resolvedBaseline = path.isAbsolute(baselinePath)
+            ? baselinePath
+            : path.resolve(projectRoot, baselinePath);
+        const baselinePayload = {
+            created_at: new Date().toISOString(),
+            K_t: drift.K_t,
+            drift
+        };
+        await fs.mkdir(path.dirname(resolvedBaseline), { recursive: true });
+        await fs.writeFile(resolvedBaseline, JSON.stringify(baselinePayload, null, 2));
+        console.log(`Wrote baseline ${resolvedBaseline}`);
+    }
+    if (options.history) {
+        const config = resolved.config;
+        const projectRoot = resolved.workspaceRoot;
+        const historyPath = typeof options.history === "string"
+            ? options.history
+            : config.drift?.historyPath || "specs-out/drift.history.jsonl";
+        const resolvedHistory = path.isAbsolute(historyPath)
+            ? historyPath
+            : path.resolve(projectRoot, historyPath);
+        const entry = {
+            timestamp: new Date().toISOString(),
+            graph_level: drift.graph_level,
+            D_t: drift.D_t,
+            K_t: drift.K_t,
+            delta: drift.delta,
+            status: drift.status,
+            metrics: drift.metrics,
+            details: drift.details,
+            capacity: drift.capacity,
+            growth: drift.growth,
+            scales: drift.scales
+        };
+        await fs.mkdir(path.dirname(resolvedHistory), { recursive: true });
+        await fs.appendFile(resolvedHistory, `${JSON.stringify(entry)}\n`);
+        console.log(`Appended history ${resolvedHistory}`);
+    }
+    console.log("SpecGuard Drift Report");
+    console.log(`Status: ${drift.status}`);
+    console.log(`D_t: ${drift.D_t.toFixed(4)}`);
+    console.log(`K_t: ${drift.K_t.toFixed(4)}`);
+    console.log(`Delta: ${drift.delta.toFixed(4)}`);
+    console.log(`Entropy: ${drift.metrics.entropy.toFixed(4)} | Cross-Layer: ${drift.metrics.cross_layer_ratio.toFixed(4)} | Cycle Density: ${drift.metrics.cycle_density.toFixed(4)} | Modularity Gap: ${drift.metrics.modularity_gap.toFixed(4)}`);
+    if (drift.scales.length > 1) {
+        console.log("Scale Summary:");
+        for (const scale of drift.scales) {
+            console.log(`- ${scale.level}: ${scale.status} | Delta ${scale.delta.toFixed(4)} | Edges ${scale.details.edges}`);
+        }
+    }
+    const totalCapacity = drift.capacity.total;
+    if (totalCapacity) {
+        const ratio = totalCapacity.ratio !== undefined ? totalCapacity.ratio.toFixed(2) : "n/a";
+        const budget = totalCapacity.budget ?? 0;
+        console.log(`Capacity: ${drift.capacity.status} | Used ${totalCapacity.used} / ${budget || "n/a"} | Ratio ${ratio}`);
+    }
+    else {
+        console.log(`Capacity: ${drift.capacity.status}`);
+    }
+    console.log(`Growth: ${drift.growth.status} | ${drift.growth.edges_per_day.toFixed(2)} edges/day (${drift.growth.trend})`);
+    console.log(`Wrote ${outputPath}`);
+}

package/dist/commands/extract.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+import { extractProject } from "../extract/index.js";
+import { runIntel } from "./intel.js";
+export async function runExtract(options) {
+    const { architecturePath, uxPath } = await extractProject(options);
+    console.log(`Wrote ${architecturePath}`);
+    console.log(`Wrote ${uxPath}`);
+    // Auto-build codebase intelligence after every extract
+    const specsDir = path.resolve(options.output);
+    try {
+        await runIntel({ specs: specsDir });
+    }
+    catch {
+        // Non-fatal — intel build failure should not break extract
+    }
+}