kibi-cli 0.18.1 → 1.0.1

package/dist/commands/discovery-shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery-shared.d.ts","sourceRoot":"","sources":["../../src/commands/discovery-shared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEpB,MAAM,+BAA+B,CAAC;AAMvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC3D,WAAW,EAAE,OAAO,eAAe,CAAC;CACrC;AAGD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EACxD,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,cAAmB,6EAG7B;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/C,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAmCZ;AAID,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAS5D;AAGD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAGR;AAGD,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAQN"}
+{"version":3,"file":"discovery-shared.d.ts","sourceRoot":"","sources":["../../src/commands/discovery-shared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAMnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC3D,WAAW,EAAE,OAAO,eAAe,CAAC;CACrC;AAGD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EACxD,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,cAAmB,6EAG7B;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/C,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CA+CZ;AAID,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAI5D;AAGD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAGR;AAGD,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAQN"}

package/dist/commands/discovery-shared.js

@@ -1,12 +1,12 @@
 import path from "node:path";
-import { getBranchOverride } from "../env.js";
+import { EngineClient } from "../engine.js";
 import { PrologProcess, resolveKbPlPath } from "../prolog.js";
 import { escapeAtom } from "../prolog/codec.js";
-import { executeOperation, } from "../public/operations/index.js";
+import { executeOperation, } from "../public/operations/runtime-types.js";
 import { createCliRuntime } from "../runtime/cli-runtime.js";
+import { resolveBranchAttachment } from "../utils/branch-resolver.js";
 import { safeCleanupProlog } from "../utils/prolog-cleanup.js";
 import { renderDiscoveryTable } from "./discovery-table.js";
-import { getCurrentBranch } from "./init-helpers.js";
 export { renderCoverageTable } from "./discovery-table.js";
 // implements REQ-kibi-operation-interface-parity
 export async function executeReportingSpec(spec, input, options = {}) {
@@ -14,43 +14,56 @@ export async function executeReportingSpec(spec, input, options = {}) {
 }
 // implements REQ-003
 export async function withAttachedBranchProlog(callback, deps) {
+    const usesEngine = deps?.createProlog === undefined;
     const createProlog = deps?.createProlog ?? ((opts) => new PrologProcess(opts));
     let prolog = null;
+    let engine = null;
     let attached = false;
+    let branchName;
     try {
-        prolog = createProlog({ timeout: 120000 });
-        await prolog.start();
-        await prolog.query("set_prolog_flag(answer_write_options, [max_depth(0), spacing(next_argument)])");
-        let branch;
-        try {
-            branch = getBranchOverride() || (await getCurrentBranch(process.cwd()));
+        const attachment = resolveBranchAttachment(process.cwd());
+        if ("error" in attachment)
+            throw new Error(attachment.error);
+        branchName = attachment.kbBranch;
+        if (usesEngine) {
+            engine = new EngineClient({
+                workspaceRoot: process.cwd(),
+                branch: branchName,
+                timeout: 120_000,
+            });
+            await engine.start();
+            prolog = engine;
         }
-        catch {
-            branch = getBranchOverride() || "main";
+        else {
+            prolog = createProlog({ timeout: 120000 });
+            await prolog.start();
         }
-        const kbPath = path.join(process.cwd(), ".kb/branches", branch);
-        const attachResult = await prolog.query(`kb_attach('${escapeAtom(kbPath)}')`);
-        if (!attachResult.success) {
-            throw new Error(`Failed to attach KB: ${attachResult.error || "Unknown error"}`);
+        if (!usesEngine) {
+            const kbPath = attachment.storePath;
+            const attachResult = await prolog.query(`kb_attach('${escapeAtom(kbPath)}')`);
+            if (!attachResult.success) {
+                throw new Error(`Failed to attach KB: ${attachResult.error || "Unknown error"}`);
+            }
+            attached = true;
         }
-        attached = true;
         return await callback(prolog);
     }
     finally {
-        await safeCleanupProlog(prolog);
+        if (usesEngine) {
+            await engine?.terminate();
+        }
+        else {
+            await safeCleanupProlog(prolog);
+        }
     }
 }
 // implements REQ-003
 // implements REQ-003
 export async function resolveCurrentKbPath() {
-    let branch;
-    try {
-        branch = getBranchOverride() || (await getCurrentBranch(process.cwd()));
-    }
-    catch {
-        branch = getBranchOverride() || "main";
-    }
-    return path.join(process.cwd(), ".kb/branches", branch);
+    const attachment = resolveBranchAttachment(process.cwd());
+    if ("error" in attachment)
+        throw new Error(attachment.error);
+    return attachment.storePath;
 }
 // implements REQ-003
 export function resolveCoreModulePath(fileName, deps) {

package/dist/commands/doctor.d.ts

@@ -1,4 +1,7 @@
-export declare function doctorCommand(): Promise<{
+export interface DoctorOptions {
+    format?: "json" | "table";
+}
+export declare function doctorCommand(options?: DoctorOptions): Promise<{
     exitCode: number;
 }>;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AA4BA,wBAAsB,aAAa,IAAI,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAyDnE"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,aAAa,CACjC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAiF/B"}

package/dist/commands/doctor.js

@@ -17,9 +17,14 @@
 */
 import { execSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildMigrationPlan, migrationAction, } from "../public/operations/migration-plan.js";
+import { readKbManifestStatus } from "../utils/kb-manifest.js";
+import { planLegacyStorageMigration } from "./legacy-storage-migration.js";
 // implements REQ-003
-export async function doctorCommand() {
+export async function doctorCommand(options = {}) {
     const checks = [
         {
             name: "SWI-Prolog",
@@ -30,8 +35,12 @@ export async function doctorCommand() {
             check: checkKbDirectory,
         },
         {
-            name: "config.json",
-            check: checkConfigJson,
+            name: ".kb/ manifest",
+            check: checkKbManifest,
+        },
+        {
+            name: "Canonical storage",
+            check: checkLegacyStorage,
         },
         {
             name: "Git repository",
@@ -50,18 +59,35 @@ export async function doctorCommand() {
             check: checkPostRewriteHook,
         },
     ];
+    const results = checks.map(({ name, check }) => ({ name, ...check() }));
+    const allPassed = results.every((result) => result.passed);
+    const runtime = await runtimeProvenance();
+    const packageActions = await packageMigrationActions(runtime);
+    const migrationPlan = buildMigrationPlan({
+        expected: {
+            branch: null,
+            kbBranch: null,
+            configHash: null,
+        },
+        evaluatedDomains: ["package"],
+        actions: packageActions,
+    });
+    if (options.format === "json") {
+        console.log(JSON.stringify({
+            version: "kibi.doctor.v1",
+            passed: allPassed,
+            runtime,
+            checks: results,
+            migrationPlan,
+        }, null, 2));
+        return { exitCode: allPassed ? 0 : 1 };
+    }
     console.log("Kibi Environment Diagnostics\n");
-    let allPassed = true;
-    for (const { name, check } of checks) {
-        const result = check();
+    for (const result of results) {
         const status = result.passed ? "✓" : "✗";
-        console.log(`${status} ${name}: ${result.message}`);
-        if (!result.passed) {
-            allPassed = false;
-            if (result.remediation) {
-                console.log(`  → ${result.remediation}`);
-            }
-        }
+        console.log(`${status} ${result.name}: ${result.message}`);
+        if (!result.passed && result.remediation)
+            console.log(`  → ${result.remediation}`);
     }
     console.log();
     if (allPassed) {
@@ -71,6 +97,195 @@ export async function doctorCommand() {
     console.log("Some checks failed. Please address the issues above.");
     return { exitCode: 1 };
 }
+async function packageMigrationActions(runtime) {
+    const actions = [];
+    const versions = ["cliVersion", "coreVersion", "mcpVersion"].filter((key) => runtime[key] === "unresolved" || runtime[key] === "unknown");
+    if (versions.length > 0) {
+        actions.push(migrationAction({
+            id: "package-provenance-unresolved",
+            code: "package_provenance_unresolved",
+            category: "package",
+            safety: "operator",
+            invocation: {
+                kind: "review",
+                instruction: "Install one coordinated Kibi artifact set and rerun kibi doctor; Kibi never selects a package manager or rewrites dependency configuration.",
+            },
+            evidence: { unresolvedVersions: versions },
+            dispositionRequired: true,
+        }));
+    }
+    const cliVersion = typeof runtime.cliVersion === "string" ? runtime.cliVersion : "unknown";
+    const mcpCliRange = typeof runtime.mcpCliRange === "string" ? runtime.mcpCliRange : "unknown";
+    if (cliVersion !== "unknown" &&
+        mcpCliRange !== "unknown" &&
+        !satisfiesCaretRange(cliVersion, mcpCliRange)) {
+        actions.push(migrationAction({
+            id: "package-mcp-cli-range-mismatch",
+            code: "package_dependency_range_mismatch",
+            category: "package",
+            safety: "operator",
+            invocation: {
+                kind: "review",
+                instruction: "Install a newly versioned coordinated Kibi package set whose MCP CLI dependency range includes the installed CLI; project-local overrides are temporary and Kibi never edits dependency configuration.",
+            },
+            evidence: { cliVersion, mcpCliRange },
+            dispositionRequired: true,
+        }));
+    }
+    if (runtime.executeApplyPlanExported === false) {
+        actions.push(migrationAction({
+            id: "package-cli-export-surface-drift",
+            code: "package_export_surface_drift",
+            category: "package",
+            safety: "operator",
+            invocation: {
+                kind: "review",
+                instruction: "Treat same-version artifacts with different exports as a release defect: obtain a newly versioned CLI/MCP pair and do not downgrade receipts or hand-edit package metadata.",
+            },
+            evidence: { executeApplyPlanExported: false },
+            dispositionRequired: true,
+        }));
+    }
+    return actions;
+}
+function satisfiesCaretRange(version, range) {
+    const match = range.trim().match(/^\^(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return true;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    const patch = Number(match[3]);
+    const actual = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!actual)
+        return false;
+    const aMajor = Number(actual[1]);
+    const aMinor = Number(actual[2]);
+    const aPatch = Number(actual[3]);
+    return (aMajor === major &&
+        (aMinor > minor || (aMinor === minor && aPatch >= patch)));
+}
+async function runtimeProvenance() {
+    const packagePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+    let cli = {};
+    try {
+        cli = JSON.parse(readFileSync(packagePath, "utf8"));
+    }
+    catch {
+        // Keep doctor JSON useful even from an unusual packed entrypoint.
+    }
+    const core = resolveInstalledPackageInfo("kibi-core");
+    const mcp = resolveInstalledPackageInfo("kibi-mcp");
+    let executeApplyPlanExported;
+    try {
+        const operations = await import("../public/operations/index.js");
+        executeApplyPlanExported =
+            typeof operations.executeApplyPlan === "function";
+    }
+    catch {
+        executeApplyPlanExported = false;
+    }
+    return {
+        cliVersion: typeof cli.version === "string" ? cli.version : "unknown",
+        coreVersion: core.version,
+        mcpVersion: mcp.version,
+        coreRange: cli.dependencies && typeof cli.dependencies === "object"
+            ? (cli.dependencies["kibi-core"] ??
+                "unknown")
+            : "unknown",
+        mcpCliRange: mcp.dependencies?.["kibi-cli"] ?? "unknown",
+        executeApplyPlanExported,
+        entrypoint: process.argv[1] ?? "unknown",
+        packageVersions: process.env.KIBI_PACKAGE_VERSIONS ?? "unknown",
+        locations: {
+            cli: packagePath,
+            cliEntrypoint: process.argv[1] ?? "unknown",
+            core: core.path,
+            coreEntrypoint: core.entrypoint,
+            mcp: mcp.path,
+            mcpEntrypoint: mcp.entrypoint,
+        },
+    };
+}
+function packageInfoFromManifest(manifestPath) {
+    let metadata;
+    try {
+        metadata = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch {
+        // Missing or unreadable manifest is not usable provenance.
+        return undefined;
+    }
+    return {
+        version: typeof metadata.version === "string" ? metadata.version : "unknown",
+        path: manifestPath,
+        entrypoint: typeof metadata.main === "string"
+            ? path.resolve(path.dirname(manifestPath), metadata.main)
+            : "unknown",
+        dependencies: metadata.dependencies && typeof metadata.dependencies === "object"
+            ? metadata.dependencies
+            : undefined,
+    };
+}
+function nearestNamedPackageManifest(startDir, name) {
+    let current = startDir;
+    while (true) {
+        const candidate = path.join(current, "package.json");
+        try {
+            const metadata = JSON.parse(readFileSync(candidate, "utf8"));
+            if (metadata.name === name)
+                return candidate;
+        }
+        catch {
+            // Keep walking; an unrelated or absent manifest is not a match.
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+function resolveInstalledPackageInfo(name) {
+    const require = createRequire(import.meta.url);
+    // Preferred: direct manifest subpath. Works when the package exports
+    // "./package.json" or has no restrictive exports map at all.
+    try {
+        const info = packageInfoFromManifest(require.resolve(`${name}/package.json`));
+        if (info)
+            return info;
+    }
+    catch {
+        // Fall through to entrypoint-based resolution below.
+    }
+    // Fallback: a tight exports map may hide ./package.json while the package
+    // itself is installed and runnable. Resolve the entrypoint, then walk up to
+    // the nearest manifest that actually names the target package so doctor
+    // never reports a coordinated install as unresolved.
+    try {
+        const entrypoint = require.resolve(name);
+        const manifestPath = nearestNamedPackageManifest(path.dirname(entrypoint), name);
+        const info = manifestPath
+            ? packageInfoFromManifest(manifestPath)
+            : undefined;
+        if (info)
+            return info;
+    }
+    catch {
+        // The package is genuinely absent from this install graph.
+    }
+    // Last resort: sibling workspace package inside the Kibi monorepo.
+    const local = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", name.replace(/^kibi-/, ""), "package.json");
+    if (existsSync(local)) {
+        const info = packageInfoFromManifest(local);
+        if (info)
+            return info;
+    }
+    return {
+        version: "unresolved",
+        path: "unresolved",
+        entrypoint: "unresolved",
+        dependencies: undefined,
+    };
+}
 function checkSWIProlog() {
     try {
         const output = execSync("swipl --version", { encoding: "utf-8" });
@@ -125,30 +340,50 @@ function checkKbDirectory() {
         message: "Found",
     };
 }
-function checkConfigJson() {
-    const configPath = path.join(process.cwd(), ".kb/config.json");
-    if (!existsSync(configPath)) {
+function checkKbManifest() {
+    const status = readKbManifestStatus(process.cwd());
+    if (status.state === "missing") {
         return {
             passed: false,
             message: "Not found",
             remediation: "Run: kibi init",
         };
     }
-    try {
-        const content = readFileSync(configPath, "utf-8");
-        JSON.parse(content);
+    if (status.state !== "ok") {
         return {
-            passed: true,
-            message: "Valid JSON",
+            passed: false,
+            message: status.state === "invalid" ? "Invalid manifest" : "Future version",
+            remediation: `Repair .kb/manifest.json: ${status.warning}`,
         };
     }
-    catch (error) {
+    return {
+        passed: true,
+        message: `schemaVersion ${status.manifest.schemaVersion}`,
+    };
+}
+function checkLegacyStorage() {
+    const plan = planLegacyStorageMigration(process.cwd());
+    if (plan.legacyConfig === "malformed") {
         return {
             passed: false,
-            message: "Invalid JSON",
-            remediation: "Fix .kb/config.json syntax or run: kibi init",
+            message: "Legacy .kb/config.json is malformed",
+            remediation: plan.legacyConfigError ??
+                "Repair or remove the legacy .kb/config.json, then run: kibi migrate --yes",
         };
     }
+    if (plan.legacyConfig === "present" || plan.moves.length > 0) {
+        return {
+            passed: false,
+            message: plan.moves.length > 0
+                ? `${plan.moves.length} legacy knowledge file(s) still outside .kb/`
+                : "Legacy .kb/config.json still present",
+            remediation: "Run: kibi migrate --yes",
+        };
+    }
+    return {
+        passed: true,
+        message: "Canonical .kb/ layout",
+    };
 }
 function checkGitRepository() {
     try {

package/dist/commands/engine.d.ts

@@ -0,0 +1,8 @@
+export declare function engineStatusCommand(): Promise<void>;
+export declare function engineStopCommand(): Promise<void>;
+export declare function storageStatusCommand(): Promise<void>;
+export declare function storageCompactCommand(): Promise<void>;
+export declare function storageExportCommand(options: {
+    output: string;
+}): Promise<void>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/commands/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/commands/engine.ts"],"names":[],"mappings":"AAkCA,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4BzD;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAWvD;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB3D;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhB"}

package/dist/commands/engine.js

@@ -0,0 +1,103 @@
+import path from "node:path";
+import { EngineClient } from "../engine.js";
+import { resolveBranchAttachment } from "../utils/branch-resolver.js";
+function currentBranch(root) {
+    const resolved = resolveBranchAttachment(root);
+    if ("error" in resolved) {
+        throw new Error(resolved.error);
+    }
+    return resolved.kbBranch;
+}
+function client() {
+    const workspaceRoot = path.resolve(process.env.KIBI_WORKSPACE ??
+        process.env.KIBI_PROJECT_ROOT ??
+        process.env.KIBI_ROOT ??
+        process.cwd());
+    return new EngineClient({
+        workspaceRoot,
+        branch: currentBranch(workspaceRoot),
+    });
+}
+function workspaceRoot() {
+    return path.resolve(process.env.KIBI_WORKSPACE ??
+        process.env.KIBI_PROJECT_ROOT ??
+        process.env.KIBI_ROOT ??
+        process.cwd());
+}
+export async function engineStatusCommand() {
+    const engine = client();
+    try {
+        const result = await engine.storageStatus();
+        if (!result.success)
+            throw new Error(result.error ?? "Engine status failed");
+        let status = result.bindings.Status ?? null;
+        const encoded = result.bindings.Json;
+        if (encoded !== undefined) {
+            try {
+                const decoded = JSON.parse(encoded);
+                status = typeof decoded === "string" ? JSON.parse(decoded) : decoded;
+            }
+            catch {
+                // Preserve the raw Prolog dict text for diagnostics when a mismatched
+                // engine version cannot provide the negotiated JSON binding.
+            }
+        }
+        console.log(JSON.stringify({
+            pid: engine.getPid(),
+            running: engine.isRunning(),
+            branch: currentBranch(workspaceRoot()),
+            status,
+        }));
+    }
+    finally {
+        await engine.terminate();
+    }
+}
+export async function engineStopCommand() {
+    const engine = client();
+    try {
+        // Stopping an absent daemon must remain a no-op. Starting SWI merely to
+        // shut it down defeats the maintenance command and can unexpectedly
+        // migrate a legacy branch during an operator status check.
+        await engine.stop(false);
+        console.log("Kibi engine stopped");
+    }
+    finally {
+        await engine.terminate();
+    }
+}
+export async function storageStatusCommand() {
+    await engineStatusCommand();
+}
+export async function storageCompactCommand() {
+    const root = workspaceRoot();
+    const attachment = resolveBranchAttachment(root);
+    if ("error" in attachment)
+        throw new Error(attachment.error);
+    if (attachment.migrationRequired) {
+        throw new Error(`Storage compaction blocked by legacy attachment (${attachment.gitBranch} -> ${attachment.kbBranch}); migrate the branch KB first.`);
+    }
+    const engine = client();
+    try {
+        const result = await engine.compact();
+        if (!result.success)
+            throw new Error(result.error ?? "Storage compaction failed");
+        console.log("Kibi storage compacted");
+    }
+    finally {
+        await engine.terminate();
+    }
+}
+export async function storageExportCommand(options) {
+    const output = path.resolve(options.output);
+    const engine = client();
+    try {
+        const result = await engine.exportStorage(output);
+        if (!result.success)
+            throw new Error(result.error ?? "Storage export failed");
+        console.log(`Exported Kibi storage to ${output}`);
+    }
+    finally {
+        await engine.terminate();
+    }
+}

package/dist/commands/gaps.js

@@ -1,4 +1,4 @@
-import { findGapsSpec } from "../public/operations/index.js";
+import { findGapsSpec } from "../public/operations/specs/reporting.js";
 import { executeReportingSpec, printDiscoveryResult, } from "./discovery-shared.js";
 // implements REQ-002, REQ-003
 export async function gapsCommand(type, options) {

package/dist/commands/gc.d.ts

@@ -1,6 +1,9 @@
-export declare function gcCommand(options: {
+type GcOptions = {
     dryRun?: boolean;
     force?: boolean;
-}): Promise<void>;
+    purge?: boolean;
+    retentionDays?: number;
+};
+export declare function gcCommand(options?: GcOptions): Promise<void>;
 export default gcCommand;
 //# sourceMappingURL=gc.d.ts.map

package/dist/commands/gc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gc.d.ts","sourceRoot":"","sources":["../../src/commands/gc.ts"],"names":[],"mappings":"AAsBA,wBAAsB,SAAS,CAAC,OAAO,EAAE;IACvC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,iBAiFA;AAED,eAAe,SAAS,CAAC"}
+{"version":3,"file":"gc.d.ts","sourceRoot":"","sources":["../../src/commands/gc.ts"],"names":[],"mappings":"AAWA,KAAK,SAAS,GAAG;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AA0GF,wBAAsB,SAAS,CAAC,OAAO,GAAE,SAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAgFtE;AAED,eAAe,SAAS,CAAC"}