@oa-sdk/spec-bundler 0.1.0

package/dist/cli.js

@@ -0,0 +1,760 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { createBundle, loadManifest, unpackBundle, verifyBundle, inspectBundle, emitJsonSchema, explainReachability, resolveBundlePath, listManifestTopics, resolveTopicManifest, createTopicProfile, addTopicToManifest, } from "./index.js";
+import { checkFreshness, getLockfilePath } from "./freshness.js";
+function printUsage() {
+    console.log(`
+@spec-platform/meta-bundler CLI
+
+Usage:
+  spec-bundler pack [--config <file>] [--topic <name>] [--all-topics] [--tree-shake] [--force] [--dry-run] [--json] [--diff] [--explain <target>]
+    Builds the bundle, rewrites internal markdown links to bundle coordinates,
+    deduplicates entries, packages the ZIP archive, and synchronizes the lockfile.
+    Use --topic <name> to package a specific topic profile slice with boundary scoping.
+    Use --all-topics to package all declared topic profiles sequentially.
+    Use --tree-shake to enforce reachability pruning from entrypoints.
+    Use --dry-run to preview packaging without writing files to disk.
+    Use --json to output structured machine-readable JSON.
+    Use --diff to display detailed terminal diff reporting of planned rewrites.
+    Use --explain <target> to display the reachability provenance for a file.
+
+  spec-bundler topic create <name> [--phase <develop|fix|test|review>] [--entry <file>] [--author <name>]
+    Easily creates and registers a new topic profile in the manifest using lifecycle presets
+    (develop, fix, test, review) with tailored directions, category filters, and fidelity levels.
+
+  spec-bundler topics [--config <file>] [--json]
+    Lists all declared topic profiles configured in the manifest with their targets and outputs.
+
+  spec-bundler resolve <archive.zip> <path-or-reference> [--json]
+    Resolves a source file path, relative reference, or TypeSpec target (including #anchors)
+    to its exact coordinate inside the compressed bundle archive using the manifest BOM.
+
+  spec-bundler inspect [--config <file>] [--topic <name>]
+    Renders the visual hierarchical ASCII dependency reachability tree, size breakdown,
+    and entrypoint mapping.
+
+  spec-bundler check [--config <file>] [--topic <name>]
+    CI coverage & drift gate. Exits with code 0 if the bundle and lockfile are fresh,
+    or code 1 if upstream source files were modified without regenerating the bundle.
+
+  spec-bundler verify [--config <file>] [--topic <name>] [--check-anchors]
+    Validates link integrity (checks for dead links with fuzzy 'Did you mean?' suggestions),
+    anchor validity (#heading-slug), and collision warnings.
+
+  spec-bundler schema [--out <file>]
+    Emits the official JSON Schema (Draft 2020-12) for bundle manifest files.
+
+  spec-bundler unpack <archive.zip> [--dest <dir>]
+    Extracts a bundle archive cleanly into a target directory (default: current directory).
+`);
+}
+function findConfigFile(customConfig) {
+    if (customConfig) {
+        const abs = path.resolve(process.cwd(), customConfig);
+        if (!fs.existsSync(abs)) {
+            console.error(`❌ Specified config file not found: ${customConfig}`);
+            process.exit(1);
+        }
+        return abs;
+    }
+    const candidates = [
+        "evidence-bundle.manifest.json",
+        "bundle.manifest.json",
+        "bundle.config.json",
+    ];
+    for (const candidate of candidates) {
+        const full = path.join(process.cwd(), candidate);
+        if (fs.existsSync(full)) {
+            return full;
+        }
+    }
+    console.error(`❌ No manifest file found in current directory. Expected one of: ${candidates.join(", ")}`);
+    process.exit(1);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (!command || command === "--help" || command === "-h") {
+        printUsage();
+        process.exit(0);
+    }
+    let customConfig;
+    let force = false;
+    let dryRun = false;
+    let json = false;
+    let diff = false;
+    let explainTarget;
+    let destDir;
+    let outPath;
+    let checkAnchors = false;
+    let topic;
+    let allTopics = false;
+    let treeShake;
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if ((arg === "--config" || arg === "-c") && args[i + 1]) {
+            customConfig = args[++i];
+        }
+        else if (arg === "--topic" && args[i + 1]) {
+            topic = args[++i];
+        }
+        else if (arg === "--all-topics") {
+            allTopics = true;
+        }
+        else if (arg === "--tree-shake") {
+            treeShake = true;
+        }
+        else if (arg === "--no-tree-shake") {
+            treeShake = false;
+        }
+        else if (arg === "--force" || arg === "-f") {
+            force = true;
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--diff") {
+            diff = true;
+        }
+        else if (arg === "--check-anchors") {
+            checkAnchors = true;
+        }
+        else if (arg === "--explain" && args[i + 1]) {
+            explainTarget = args[++i];
+        }
+        else if ((arg === "--dest" || arg === "-d") && args[i + 1]) {
+            destDir = args[++i];
+        }
+        else if ((arg === "--out" || arg === "-o") && args[i + 1]) {
+            outPath = args[++i];
+        }
+    }
+    if (command === "create-topic" || (command === "topic" && args[1] === "create")) {
+        let topicName;
+        let phaseStr;
+        let author;
+        const entries = [];
+        let description;
+        let domain;
+        let issue;
+        let prompt;
+        let output;
+        let format;
+        let config;
+        const startIndex = command === "create-topic" ? 1 : 2;
+        for (let i = startIndex; i < args.length; i++) {
+            const arg = args[i];
+            if ((arg === "--phase" || arg === "-p") && args[i + 1]) {
+                phaseStr = args[++i];
+            }
+            else if ((arg === "--author" || arg === "-a") && args[i + 1]) {
+                author = args[++i];
+            }
+            else if ((arg === "--entry" || arg === "-e") && args[i + 1]) {
+                entries.push(args[++i]);
+            }
+            else if ((arg === "--desc" || arg === "--description") && args[i + 1]) {
+                description = args[++i];
+            }
+            else if (arg === "--domain" && args[i + 1]) {
+                domain = args[++i];
+            }
+            else if (arg === "--issue" && args[i + 1]) {
+                issue = args[++i];
+            }
+            else if (arg === "--prompt" && args[i + 1]) {
+                prompt = args[++i];
+            }
+            else if ((arg === "--output" || arg === "--out" || arg === "-o") && args[i + 1]) {
+                output = args[++i];
+            }
+            else if (arg === "--format" && args[i + 1]) {
+                const fmt = args[++i];
+                if (fmt === "zip" || fmt === "directory") {
+                    format = fmt;
+                }
+            }
+            else if ((arg === "--config" || arg === "-c") && args[i + 1]) {
+                config = args[++i];
+            }
+            else if (!arg.startsWith("-") && !topicName) {
+                topicName = arg;
+            }
+        }
+        if (!topicName) {
+            console.error(`\n❌ Topic name is required. Usage: spec-bundler topic create <name> [--phase <develop|fix|test|review>] [--entry <file>] [--author <name>]`);
+            process.exit(1);
+        }
+        if (phaseStr &&
+            phaseStr !== "develop" &&
+            phaseStr !== "fix" &&
+            phaseStr !== "test" &&
+            phaseStr !== "review") {
+            console.error(`\n❌ Invalid phase '${phaseStr}'. Expected one of: develop, fix, test, review`);
+            process.exit(1);
+        }
+        const configPath = findConfigFile(config ?? customConfig);
+        try {
+            const profile = createTopicProfile({
+                name: topicName,
+                phase: phaseStr,
+                author,
+                entrypoints: entries.length > 0 ? entries : undefined,
+                description,
+                domain,
+                issue,
+                prompt,
+                output,
+                format,
+            });
+            const res = addTopicToManifest(configPath, topicName, profile);
+            console.log(`\n✔ Successfully created topic '${topicName}' in ${path.relative(process.cwd(), configPath)}:`);
+            console.log(`   Work Phase: ${profile.phase ?? "develop"}`);
+            if (profile.author) {
+                console.log(`   Author:     ${profile.author}`);
+            }
+            if (profile.scope?.direction) {
+                console.log(`   Direction:  ${profile.scope.direction}`);
+            }
+            if (profile.scope?.includeCategories) {
+                console.log(`   Categories: ${profile.scope.includeCategories.join(", ")}`);
+            }
+            if (profile.scope?.entrypoints && profile.scope.entrypoints.length > 0) {
+                console.log(`   Entrypoint: ${profile.scope.entrypoints.join(", ")}`);
+            }
+            if (profile.context?.issue) {
+                console.log(`   Issue:      ${profile.context.issue}`);
+            }
+            console.log(`   Topics:     ${res.topicCount} declared topic profile(s) in manifest`);
+            console.log(`\n👉 Next steps:`);
+            console.log(`   spec-bundler inspect --topic ${topicName}`);
+            console.log(`   spec-bundler pack --topic ${topicName}`);
+            process.exit(0);
+        }
+        catch (err) {
+            console.error(`\n❌ Failed to create topic: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    if (command === "topics" || (command === "topic" && (args[1] === "list" || !args[1] || args[1].startsWith("-")))) {
+        const configPath = findConfigFile(customConfig);
+        try {
+            const manifest = loadManifest(configPath);
+            const summaries = listManifestTopics(manifest);
+            if (json) {
+                console.log(JSON.stringify(summaries, null, 2));
+                process.exit(0);
+            }
+            console.log(`\n📋 Declared Topic Profiles in ${path.relative(process.cwd(), configPath)}:`);
+            if (summaries.length === 0) {
+                console.log("  (No topic profiles declared under 'topics')");
+            }
+            else {
+                for (const s of summaries) {
+                    console.log(`  - ${s.name} (${s.format}, ${s.targetCount} target mapping${s.targetCount === 1 ? "" : "s"}):`);
+                    if (s.phase)
+                        console.log(`      Phase:       ${s.phase}`);
+                    if (s.author)
+                        console.log(`      Author:      ${s.author}`);
+                    if (s.description)
+                        console.log(`      Description: ${s.description}`);
+                    if (s.domain)
+                        console.log(`      Domain:      ${s.domain}`);
+                    if (s.issue)
+                        console.log(`      Issue:       ${s.issue}`);
+                    if (s.tags && s.tags.length > 0)
+                        console.log(`      Tags:        ${s.tags.join(", ")}`);
+                    if (s.contextDocsCount && s.contextDocsCount > 0) {
+                        console.log(`      Context:     ${s.contextDocsCount} ambient document(s)`);
+                    }
+                    if (s.hasScope) {
+                        console.log(`      Scope:       Configured (entrypoints, boundary filters)`);
+                    }
+                    if (s.direction) {
+                        console.log(`      Direction:   ${s.direction}`);
+                    }
+                    console.log(`      Output:      ${s.output}`);
+                }
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            console.error(`\n❌ Failed to read topics: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    if (command === "schema") {
+        const schemaContent = emitJsonSchema();
+        if (outPath) {
+            const absOut = path.resolve(process.cwd(), outPath);
+            fs.mkdirSync(path.dirname(absOut), { recursive: true });
+            fs.writeFileSync(absOut, schemaContent, "utf8");
+            console.log(`✔ Emitted JSON Schema to ${path.relative(process.cwd(), absOut)}`);
+        }
+        else {
+            console.log(schemaContent);
+        }
+        process.exit(0);
+    }
+    if (command === "inspect" || command === "tree") {
+        const configPath = findConfigFile(customConfig);
+        try {
+            const inspection = inspectBundle(configPath, { topic });
+            const topicSuffix = topic ? ` - Topic: ${topic}` : "";
+            console.log(`\n📦 Bundle Dependency Reachability Tree (${path.relative(process.cwd(), configPath)}${topicSuffix}):`);
+            if (inspection.manifest.phase) {
+                console.log(`   Phase:      ${inspection.manifest.phase}`);
+            }
+            if (inspection.manifest.author) {
+                console.log(`   Author:     ${inspection.manifest.author}`);
+            }
+            if (inspection.manifest.context) {
+                const ctx = inspection.manifest.context;
+                if (ctx.domain)
+                    console.log(`   Domain:     ${ctx.domain}`);
+                if (ctx.issue)
+                    console.log(`   Issue:      ${ctx.issue}`);
+                if (ctx.tags && ctx.tags.length > 0)
+                    console.log(`   Tags:       ${ctx.tags.join(", ")}`);
+                if (ctx.prompt)
+                    console.log(`   Prompt:     ${ctx.prompt.slice(0, 80)}${ctx.prompt.length > 80 ? "..." : ""}`);
+            }
+            const direction = inspection.manifest.treeShake?.direction ?? inspection.manifest.scope?.direction;
+            if (direction) {
+                console.log(`   Direction:  ${direction}`);
+            }
+            const cats = inspection.manifest.treeShake?.includeCategories ?? inspection.manifest.scope?.includeCategories;
+            if (cats && cats.length > 0) {
+                console.log(`   Categories: ${cats.join(", ")}`);
+            }
+            if (inspection.manifest.scope?.sections && inspection.manifest.scope.sections.length > 0) {
+                console.log(`   Sections:   ${inspection.manifest.scope.sections.join(", ")}`);
+            }
+            console.log("--------------------------------------------------------------------------------");
+            if (inspection.asciiTree) {
+                process.stdout.write(inspection.asciiTree);
+            }
+            else {
+                console.log("  (No entrypoints or reachable files found)");
+            }
+            console.log("--------------------------------------------------------------------------------");
+            console.log(`✔ Reachable:  ${inspection.reachableCount} files (${(inspection.totalSizeBytes / 1024).toFixed(1)} KB)`);
+            if (inspection.eliminatedCount > 0) {
+                console.log(`✂ Eliminated: ${inspection.eliminatedCount} unreferenced files`);
+            }
+            if (inspection.boundaryTerminals && inspection.boundaryTerminals.length > 0) {
+                console.log(`🛑 Boundary:   ${inspection.boundaryTerminals.length} terminal reference(s) halted traversal`);
+            }
+            if (inspection.warnings.length > 0) {
+                console.warn(`\n⚠️  Warnings (${inspection.warnings.length}):`);
+                for (const w of inspection.warnings)
+                    console.warn(`   - ${w}`);
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            console.error(`\n❌ Inspection failed: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    if (command === "pack") {
+        const configPath = findConfigFile(customConfig);
+        try {
+            if (allTopics) {
+                const manifest = loadManifest(configPath);
+                const summaries = listManifestTopics(manifest);
+                if (summaries.length === 0) {
+                    console.warn(`⚠️  No topics found under 'topics' in ${path.relative(process.cwd(), configPath)}.`);
+                    process.exit(0);
+                }
+                console.log(`📦 Packaging ${summaries.length} topic profile${summaries.length === 1 ? "" : "s"}...`);
+                let hadFailure = false;
+                for (const s of summaries) {
+                    console.log(`\n------------------------------------------------------------`);
+                    console.log(`🎯 Packaging Topic: ${s.name}${s.phase ? ` [Phase: ${s.phase}]` : ""}${s.author ? ` (Author: ${s.author})` : ""}`);
+                    console.log(`------------------------------------------------------------`);
+                    try {
+                        const result = createBundle(configPath, { force, dryRun, json: false, diff, topic: s.name, treeShake });
+                        console.log(`✔ Successfully generated topic bundle: ${path.relative(process.cwd(), result.outputPath)} (${result.filesCount} files)`);
+                    }
+                    catch (err) {
+                        console.error(`❌ Failed packaging topic '${s.name}': ${err.message}`);
+                        hadFailure = true;
+                    }
+                }
+                process.exit(hadFailure ? 1 : 0);
+            }
+            if (explainTarget) {
+                const inspection = inspectBundle(configPath, { topic });
+                const epList = inspection.manifest.treeShake?.entrypoints ?? [];
+                const hops = explainReachability(explainTarget, inspection.lineage, epList, inspection.boundaryEdges);
+                console.log(`\n🔍 Reachability Explanation for '${explainTarget}':`);
+                if (hops === null) {
+                    console.log(`  ❌ Target '${explainTarget}' was NOT reachable from any entrypoint (eliminated or unbundled).`);
+                }
+                else if (hops.length === 0) {
+                    console.log(`  ✔ Target '${explainTarget}' is a declared root entrypoint.`);
+                }
+                else {
+                    console.log(`  ✔ Reachable via ${hops.length} hop(s):`);
+                    hops.forEach((h, idx) => {
+                        console.log(`    ${idx + 1}. ${h.from} -> ${h.to} (ref: '${h.ref}')`);
+                    });
+                }
+                process.exit(0);
+            }
+            const result = createBundle(configPath, { force, dryRun, json, diff, topic, treeShake });
+            if (json) {
+                let manifestObj;
+                try {
+                    manifestObj = loadManifest(configPath);
+                }
+                catch {
+                    manifestObj = {};
+                }
+                const jsonReport = {
+                    manifest: path.relative(process.cwd(), configPath),
+                    topic: result.topic,
+                    phase: result.phase,
+                    author: result.author,
+                    bundleName: result.predictedLockfile?.bundleName ?? manifestObj.name ?? "bundle",
+                    bundleVersion: result.predictedLockfile?.manifestVersion ?? manifestObj.version ?? "1.0.0",
+                    outputPath: path.relative(process.cwd(), result.outputPath),
+                    format: manifestObj.format ?? "zip",
+                    dryRun: Boolean(result.dryRun),
+                    skipped: result.skipped,
+                    filesCount: result.filesCount,
+                    totalSizeBytes: result.totalSizeBytes,
+                    aggregateHash: result.aggregateHash,
+                    plannedEntries: result.plannedEntries ?? [],
+                    rewrites: result.rewrites ?? [],
+                    diagnostics: result.diagnostics,
+                    unbundledDiagnostics: result.unbundledDiagnostics ?? [],
+                    predictedLockfile: result.predictedLockfile,
+                    freshness: result.freshness,
+                    eliminatedFiles: result.eliminatedFiles ?? [],
+                    boundaryTerminals: result.boundaryTerminals ?? [],
+                    upstreamNodes: result.upstreamNodes ?? [],
+                    direction: result.direction,
+                    categoryBreakdown: result.categoryBreakdown,
+                };
+                console.log(JSON.stringify(jsonReport, null, 2));
+                const errors = result.diagnostics.filter((d) => d.severity === "error");
+                if (errors.length > 0) {
+                    process.exit(1);
+                }
+                process.exit(0);
+            }
+            if (result.skipped) {
+                console.log(`✔ Bundle is already up to date! (Aggregate Hash: ${result.aggregateHash.slice(0, 12)}...)`);
+                console.log(`  Use --force to rebuild unconditionally.`);
+                process.exit(0);
+            }
+            const topicHeader = result.topic ? ` [Topic: ${result.topic}]` : "";
+            if (dryRun || diff) {
+                const prefix = dryRun ? "🔍 [Dry Run Simulation]" : "📦";
+                console.log(`${prefix}${topicHeader} Packaging bundle using ${path.relative(process.cwd(), configPath)}...`);
+                if (result.plannedEntries && result.plannedEntries.length > 0) {
+                    console.log(`\n📋 Planned Destination Mappings (${result.plannedEntries.length} file${result.plannedEntries.length === 1 ? "" : "s"}):`);
+                    for (const entry of result.plannedEntries) {
+                        const sizeKb = (entry.size / 1024).toFixed(1);
+                        console.log(`  - ${entry.source} -> ${entry.dest} (${sizeKb} KB, sha256: ${entry.sha256.slice(0, 12)}...)`);
+                    }
+                }
+                if (result.rewrites && result.rewrites.length > 0) {
+                    console.log(`\n🔗 Recalculated Link Rewrites (${result.rewrites.length} link${result.rewrites.length === 1 ? "" : "s"}):`);
+                    for (const rw of result.rewrites) {
+                        console.log(`  - ${rw.file}:${rw.line}:${rw.column}: '${rw.originalHref}' -> '${rw.rewrittenHref}'`);
+                    }
+                }
+                else {
+                    console.log(`\n🔗 Recalculated Link Rewrites: 0 (No relative links required rewriting)`);
+                }
+                if (result.predictedLockfile) {
+                    console.log(`\n🔒 Predicted Lockfile State:`);
+                    console.log(`  - Aggregate Hash: ${result.predictedLockfile.aggregateHash.slice(0, 16)}...`);
+                    console.log(`  - Files Count:    ${result.predictedLockfile.filesCount}`);
+                    console.log(`  - Total Size:     ${result.predictedLockfile.totalSizeBytes} bytes`);
+                    if (result.freshness) {
+                        const freshStr = result.freshness.isFresh
+                            ? "✔ Synchronized"
+                            : `⚠️  Drift detected (+${result.freshness.added.length}, -${result.freshness.removed.length}, ~${result.freshness.modified.length})`;
+                        console.log(`  - Freshness:      ${freshStr}`);
+                    }
+                }
+                if (result.eliminatedFiles && result.eliminatedFiles.length > 0) {
+                    console.log(`  - Tree-shaken:   ${result.eliminatedFiles.length} unreferenced files eliminated`);
+                }
+                if (result.boundaryTerminals && result.boundaryTerminals.length > 0) {
+                    console.log(`  - Boundary Halt: ${result.boundaryTerminals.length} terminal reference(s) halted traversal`);
+                }
+                if (result.phase) {
+                    console.log(`  - Work Phase:    ${result.phase}`);
+                }
+                if (result.author) {
+                    console.log(`  - Initial Author:${result.author}`);
+                }
+                if (result.direction) {
+                    console.log(`  - Direction:     ${result.direction}`);
+                }
+                if (result.categoryBreakdown) {
+                    const catEntries = Object.entries(result.categoryBreakdown)
+                        .map(([cat, count]) => `${cat}: ${count}`)
+                        .join(", ");
+                    console.log(`  - Categories:    ${catEntries}`);
+                }
+                if (result.upstreamNodes && result.upstreamNodes.length > 0) {
+                    console.log(`  - Upstream Nodes:${result.upstreamNodes.length} caller document(s) included`);
+                }
+                if (result.unbundledDiagnostics && result.unbundledDiagnostics.length > 0) {
+                    console.log(`\n⚠️  Unbundled Reference Diagnostics (${result.unbundledDiagnostics.length} target${result.unbundledDiagnostics.length === 1 ? "" : "s"}):`);
+                    for (const u of result.unbundledDiagnostics) {
+                        const colStr = u.column ? `:${u.column}` : "";
+                        const icon = u.severity === "error" ? "❌" : u.severity === "warning" ? "⚠️" : "ℹ️";
+                        console.log(`   ${icon} ${u.file}:${u.line}${colStr}: ${u.message}`);
+                    }
+                }
+                const unbundledOriginalHrefs = new Set((result.unbundledDiagnostics ?? []).map((u) => `${u.file}:${u.line}:${u.column ?? 1}:${u.originalHref}`));
+                const otherWarnings = result.diagnostics.filter((d) => d.severity === "warning" &&
+                    !unbundledOriginalHrefs.has(`${d.file}:${d.line}:${d.column ?? 1}:${d.originalHref}`));
+                if (otherWarnings.length > 0) {
+                    console.log(`\n⚠️  [Link Warnings] (${otherWarnings.length} issues):`);
+                    for (const w of otherWarnings) {
+                        const colStr = w.column ? `:${w.column}` : "";
+                        console.log(`   - ${w.file}:${w.line}${colStr}: ${w.message}`);
+                    }
+                }
+                const allErrors = result.diagnostics.filter((d) => d.severity === "error");
+                if (allErrors.length > 0) {
+                    console.error(`\n❌ [Dead Link Errors] (${allErrors.length} issues):`);
+                    for (const e of allErrors) {
+                        const colStr = e.column ? `:${e.column}` : "";
+                        console.error(`   - ${e.file}:${e.line}${colStr}: ${e.message}`);
+                    }
+                    process.exit(1);
+                }
+                if (dryRun) {
+                    console.log(`\n✔ Dry run simulation complete. Zero disk modifications made.`);
+                }
+                else {
+                    console.log(`\n✔ Successfully generated bundle: ${path.relative(process.cwd(), result.outputPath)}`);
+                }
+                process.exit(0);
+            }
+            // Normal non-dryRun, non-diff output
+            console.log(`📦${topicHeader} Packaging bundle using ${path.relative(process.cwd(), configPath)}...`);
+            console.log(`\n✔ Successfully generated bundle: ${path.relative(process.cwd(), result.outputPath)}`);
+            console.log(`  - Files bundled: ${result.filesCount}`);
+            if (result.phase) {
+                console.log(`  - Work Phase:    ${result.phase}`);
+            }
+            if (result.author) {
+                console.log(`  - Initial Author:${result.author}`);
+            }
+            if (result.eliminatedFiles && result.eliminatedFiles.length > 0) {
+                console.log(`  - Tree-shaken:   ${result.eliminatedFiles.length} unreferenced files eliminated`);
+            }
+            if (result.boundaryTerminals && result.boundaryTerminals.length > 0) {
+                console.log(`  - Boundary Halt: ${result.boundaryTerminals.length} terminal reference(s) halted traversal`);
+            }
+            if (result.direction) {
+                console.log(`  - Direction:     ${result.direction}`);
+            }
+            if (result.categoryBreakdown) {
+                const catEntries = Object.entries(result.categoryBreakdown)
+                    .map(([cat, count]) => `${cat}: ${count}`)
+                    .join(", ");
+                console.log(`  - Categories:    ${catEntries}`);
+            }
+            if (result.upstreamNodes && result.upstreamNodes.length > 0) {
+                console.log(`  - Upstream Nodes:${result.upstreamNodes.length} caller document(s) included`);
+            }
+            console.log(`  - Total size:    ${result.totalSizeBytes} bytes`);
+            console.log(`  - SHA-256 BOM:   ${result.aggregateHash.slice(0, 16)}...`);
+            const warnings = result.diagnostics.filter((d) => d.severity === "warning");
+            const errors = result.diagnostics.filter((d) => d.severity === "error");
+            if (warnings.length > 0) {
+                console.warn(`\n⚠️  [Link Warnings] (${warnings.length} issues):`);
+                for (const w of warnings) {
+                    const colStr = w.column ? `:${w.column}` : "";
+                    console.warn(`   - ${w.file}:${w.line}${colStr}: ${w.message}`);
+                }
+            }
+            if (errors.length > 0) {
+                console.error(`\n❌ [Dead Link Errors] (${errors.length} issues):`);
+                for (const e of errors) {
+                    const colStr = e.column ? `:${e.column}` : "";
+                    console.error(`   - ${e.file}:${e.line}${colStr}: ${e.message}`);
+                }
+                process.exit(1);
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            console.error(`\n❌ Packaging failed: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    if (command === "check") {
+        const configPath = findConfigFile(customConfig);
+        let rawManifest;
+        try {
+            rawManifest = loadManifest(configPath);
+        }
+        catch (err) {
+            console.error(`\n❌ [CI Gate Failed] ${err.message}`);
+            process.exit(1);
+        }
+        const manifest = topic ? resolveTopicManifest(rawManifest, topic) : rawManifest;
+        const baseDir = path.dirname(configPath);
+        const effectiveLockfileMode = rawManifest.lockfileMode;
+        const lockfilePath = getLockfilePath(configPath, topic, effectiveLockfileMode);
+        const topicLabel = topic ? ` for topic '${topic}'` : "";
+        const freshness = checkFreshness(manifest, baseDir, lockfilePath, {
+            topic,
+            diff,
+            lockfileMode: effectiveLockfileMode,
+        });
+        if (json) {
+            console.log(JSON.stringify(freshness, null, 2));
+            process.exit(freshness.isFresh ? 0 : 1);
+        }
+        if (freshness.isFresh) {
+            console.log(`✔ [CI Gate Pass] Bundle and lockfile${topicLabel} are synchronized. (Hash: ${freshness.currentAggregateHash.slice(0, 12)}...)`);
+            process.exit(0);
+        }
+        console.error(`\n❌ [CI Gate Failed] Bundle drift detected${topicLabel}! Upstream sources have changed:`);
+        if (freshness.added.length > 0) {
+            console.error(`  - Added files (${freshness.added.length}): ${freshness.added.slice(0, 5).join(", ")}${freshness.added.length > 5 ? "..." : ""}`);
+        }
+        if (freshness.removed.length > 0) {
+            console.error(`  - Removed files (${freshness.removed.length}): ${freshness.removed.slice(0, 5).join(", ")}${freshness.removed.length > 5 ? "..." : ""}`);
+        }
+        if (freshness.modified.length > 0) {
+            console.error(`  - Modified files (${freshness.modified.length}): ${freshness.modified.slice(0, 5).join(", ")}${freshness.modified.length > 5 ? "..." : ""}`);
+        }
+        if (diff && freshness.semanticDiff) {
+            const sDiff = freshness.semanticDiff;
+            if (sDiff.modifiedFiles.length > 0) {
+                console.error(`\n🔍 Semantic Structural Drift Details:`);
+                for (const m of sDiff.modifiedFiles) {
+                    console.error(`  📄 ${m.file} [${m.type}]:`);
+                    if (m.addedAnchors && m.addedAnchors.length > 0) {
+                        console.error(`     + Added anchors (${m.addedAnchors.length}): ${m.addedAnchors.join(", ")}`);
+                    }
+                    if (m.removedAnchors && m.removedAnchors.length > 0) {
+                        console.error(`     - Removed anchors (${m.removedAnchors.length}): ${m.removedAnchors.join(", ")}`);
+                    }
+                    if (m.addedSymbols && m.addedSymbols.length > 0) {
+                        console.error(`     + Added symbols (${m.addedSymbols.length}): ${m.addedSymbols.join(", ")}`);
+                    }
+                    if (m.removedSymbols && m.removedSymbols.length > 0) {
+                        console.error(`     - Removed symbols (${m.removedSymbols.length}): ${m.removedSymbols.join(", ")}`);
+                    }
+                    if (m.lineDelta !== undefined && m.lineDelta !== 0) {
+                        const sign = m.lineDelta > 0 ? "+" : "";
+                        console.error(`     ~ Line delta: ${sign}${m.lineDelta} lines`);
+                    }
+                }
+            }
+        }
+        const topicArg = topic ? ` --topic ${topic}` : "";
+        console.error(`\n💡 To synchronize the bundle and lockfile, run:`);
+        console.error(`   spec-bundler pack --config ${path.relative(process.cwd(), configPath)}${topicArg}`);
+        if (process.env.GITHUB_ACTIONS) {
+            console.error(`::error file=${configPath}::Bundle drift detected. Run 'spec-bundler pack' to synchronize.`);
+        }
+        process.exit(1);
+    }
+    if (command === "verify") {
+        const configPath = findConfigFile(customConfig);
+        const { freshness, deadLinks, warnings } = verifyBundle(configPath, { checkAnchors, topic });
+        const topicSuffix = topic ? ` (Topic: ${topic})` : "";
+        console.log(`\n🔍 Verifying ${path.relative(process.cwd(), configPath)}${topicSuffix}:`);
+        console.log(`  - Freshness status: ${freshness.isFresh ? "✔ Synchronized" : "⚠️ Drift detected"}`);
+        if (warnings.length > 0) {
+            console.warn(`  - Collision / Resolver Warnings (${warnings.length}):`);
+            for (const w of warnings)
+                console.warn(`    * ${w}`);
+        }
+        const deadLinkErrors = deadLinks.filter((d) => d.severity === "error");
+        const deadLinkWarnings = deadLinks.filter((d) => d.severity === "warning");
+        if (deadLinkWarnings.length > 0) {
+            console.warn(`  ⚠️  Unbundled / Non-fatal Link Warnings (${deadLinkWarnings.length}):`);
+            for (const w of deadLinkWarnings) {
+                console.warn(`    * ${w.file}:${w.line}: ${w.message}`);
+            }
+        }
+        if (deadLinkErrors.length > 0) {
+            console.error(`  - Dead links inside bundle (${deadLinkErrors.length}):`);
+            for (const d of deadLinkErrors) {
+                console.error(`    * ${d.file}:${d.line}: ${d.message}`);
+            }
+            process.exit(1);
+        }
+        else {
+            console.log(`  - Dead links inside bundle: 0 (All internal references valid)`);
+        }
+        process.exit(0);
+    }
+    if (command === "unpack") {
+        const archivePath = args[1];
+        if (!archivePath || archivePath.startsWith("-")) {
+            console.error("Usage: spec-bundler unpack <archive.zip> [--dest <dir>]");
+            process.exit(1);
+        }
+        const targetDest = destDir ?? process.cwd();
+        console.log(`📂 Unpacking ${archivePath} into ${targetDest}...`);
+        const { extractedCount, files } = unpackBundle(archivePath, targetDest);
+        console.log(`✔ Extracted ${extractedCount} files successfully.`);
+        process.exit(0);
+    }
+    if (command === "resolve") {
+        const archiveArg = args[1];
+        const refArg = args[2];
+        if (!archiveArg || !refArg || archiveArg.startsWith("-")) {
+            console.error("Usage: spec-bundler resolve <archive.zip> <path-or-reference> [--json]");
+            process.exit(1);
+        }
+        const isJson = json || args.includes("--json");
+        try {
+            const resolution = resolveBundlePath(archiveArg, refArg);
+            if (isJson) {
+                console.log(JSON.stringify(resolution, null, 2));
+                process.exit(resolution.existsInBundle ? 0 : 1);
+            }
+            if (resolution.existsInBundle) {
+                console.log(`✔ Resolved '${refArg}' inside bundle archive:`);
+                console.log(`  - Bundle Path:    ${resolution.bundlePath}`);
+                console.log(`  - Full Reference: ${resolution.fullReference}`);
+                if (resolution.anchor) {
+                    console.log(`  - Target Anchor:  ${resolution.anchor}`);
+                }
+                process.exit(0);
+            }
+            else {
+                console.error(`❌ Reference '${refArg}' could not be resolved inside bundle archive.`);
+                if (resolution.suggestedTarget) {
+                    console.error(`  💡 Did you mean '${resolution.suggestedTarget}'?`);
+                }
+                process.exit(1);
+            }
+        }
+        catch (err) {
+            console.error(`❌ Resolution error: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map