kibi-cli 0.8.0 → 0.10.1

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAsCA,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuCA,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/cli.js

@@ -25,6 +25,7 @@ import { gapsCommand } from "./commands/gaps.js";
 import { gcCommand } from "./commands/gc.js";
 import { graphCommand } from "./commands/graph.js";
 import { initCommand } from "./commands/init.js";
+import { migrateCommand } from "./commands/migrate.js";
 import { queryCommand } from "./commands/query.js";
 import { searchCommand } from "./commands/search.js";
 import { statusCommand } from "./commands/status.js";
@@ -53,14 +54,24 @@ program
     .action(withExitCode(async (options) => {
     return initCommand(options);
 }));
+program
+    .command("migrate")
+    .description("Migrate .kb/config.json to the latest schema version")
+    .option("--dry-run", "Preview migration changes without writing files")
+    .option("--yes", "Apply migration changes without prompting")
+    .action(withExitCode(async (options) => {
+    return migrateCommand(options);
+}));
 program
     .command("sync")
     .description("Sync entities from documents")
     .option("--validate-only", "Perform validation without mutations")
+    .option("--refresh-symbol-coordinates", "Refresh generated symbol coordinates")
     .option("--rebuild", "Rebuild branch snapshot from scratch (discards current KB)")
     .action(withExitCode(async (options) => {
     return syncCommand(options);
 }));
+program;
 program
     .command("query [type]")
     .description("Query knowledge base")

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

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAuDA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,SAAS,EAAE,CAAC;AAI1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA+GD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAkR/B"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AA8EA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,SAAS,EAAE,CAAC;AAI1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA+UD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAmU/B"}

package/dist/commands/check.js

@@ -22,8 +22,12 @@ import { extractFromManifest, extractFromManifestString, } from "../extractors/m
 import { extractFromMarkdownString, } from "../extractors/markdown.js";
 import { PrologProcess } from "../prolog.js";
 import { escapeAtom, parseTriples, parseViolationRows, } from "../prolog/codec.js";
-import { getStagedFiles } from "../traceability/git-staged.js";
+import { getStagedFiles, } from "../traceability/git-staged.js";
+import { KIBI_NO_IMPACT_DECLARATION, KIBI_SYMBOLS_MANIFEST_PATH, } from "../traceability/evidence-model.js";
 import { validateStagedMarkdown } from "../traceability/markdown-validate.js";
+import { collectStagedKibiDiagnostics, } from "../traceability/staged-diagnostics.js";
+import { classifyKibiImpactEvidence, isBehaviorSourceEdit, parseKibiImpactOverride, } from "../traceability/staged-impact-contract.js";
+import { assessStagedSymbolsManifest, collectStagedAuthoredSymbolsManifestEvidence, } from "../traceability/staged-symbols-manifest.js";
 import { createManifestLookupSentinelKey, extractSymbolsFromStagedFile, } from "../traceability/symbol-extract.js";
 import { cleanupTempKb, consultOverlay, createOverlayFacts, createTempKb, projectStagedEntities, } from "../traceability/temp-kb.js";
 import { formatViolations as formatStagedViolations, validateStagedSymbols, } from "../traceability/validate.js";
@@ -112,6 +116,173 @@ function buildManifestLookup(stagedFiles) {
     }
     return { manifestLookup, manifestResults };
 }
+const KIBI_ENTITY_TYPES = new Set([
+    "req",
+    "scenario",
+    "test",
+    "adr",
+    "flag",
+    "event",
+    "symbol",
+    "fact",
+]);
+function isKibiEntityType(value) {
+    return KIBI_ENTITY_TYPES.has(value);
+}
+function isStagedManifestPath(filePath) {
+    if (filePath.endsWith("/symbols.yaml") ||
+        filePath.endsWith("/symbols.yml") ||
+        filePath.endsWith("/symbol-coordinates.yaml") ||
+        filePath === "symbols.yaml" ||
+        filePath === "symbols.yml" ||
+        filePath === "symbol-coordinates.yaml") {
+        return true;
+    }
+    try {
+        const config = loadConfig(process.cwd());
+        if (config.paths.symbols) {
+            const relSymbols = config.paths.symbols;
+            const configuredBase = relSymbols.split(/[\\/]/).pop();
+            if (filePath === relSymbols ||
+                (configuredBase && filePath.endsWith(`/${configuredBase}`))) {
+                return true;
+            }
+        }
+    }
+    catch {
+        // ignore config read errors
+    }
+    return false;
+}
+function isTestOnlySourcePath(filePath) {
+    return (filePath.startsWith("tests/") ||
+        filePath.includes("/tests/") ||
+        filePath.endsWith(".test.ts") ||
+        filePath.endsWith(".test.tsx") ||
+        filePath.endsWith(".test.js") ||
+        filePath.endsWith(".test.jsx") ||
+        filePath.endsWith(".spec.ts") ||
+        filePath.endsWith(".spec.tsx") ||
+        filePath.endsWith(".spec.js") ||
+        filePath.endsWith(".spec.jsx"));
+}
+function getStagedDiffText(stagedFile) {
+    return stagedFile.diffText ?? "";
+}
+function formatStagedKibiDiagnostics(diagnostics) {
+    return diagnostics
+        .map((diagnostic) => {
+        const lines = [`[${diagnostic.id}] ${diagnostic.message}`];
+        if (diagnostic.files.length > 0) {
+            lines.push(`  Files: ${diagnostic.files.join(", ")}`);
+        }
+        if (diagnostic.docs.length > 0) {
+            lines.push(`  Docs: ${diagnostic.docs.join(", ")}`);
+        }
+        lines.push(`  Suggestion: ${diagnostic.suggestion}`);
+        return lines.join("\n");
+    })
+        .join("\n\n");
+}
+function uniqueSorted(values) {
+    return Array.from(new Set(values)).sort();
+}
+function buildStagedKibiImpactEvidence(options) {
+    const { stagedFiles, sourceFiles, markdownFiles, markdownResults, symbolsByFile, symbolsManifestPath, } = options;
+    const sourceChanges = sourceFiles.map((file) => {
+        const symbolsForFile = symbolsByFile.get(file.path) ?? [];
+        const behaviorCandidate = !isTestOnlySourcePath(file.path) &&
+            isBehaviorSourceEdit({
+                path: file.path,
+                diffText: getStagedDiffText(file),
+                intersectsBehaviorBearingSymbol: symbolsForFile.length > 0,
+                knownUserFacingSurface: false,
+            });
+        return {
+            path: file.path,
+            kind: behaviorCandidate
+                ? "behavior_source_edit"
+                : "non_behavior_source_edit",
+        };
+    });
+    const behaviorSourcePaths = sourceChanges
+        .filter((change) => change.kind === "behavior_source_edit")
+        .map((change) => change.path);
+    const allSourcePaths = sourceChanges.map((change) => change.path);
+    const behaviorSourceFiles = sourceFiles.filter((file) => behaviorSourcePaths.includes(file.path));
+    const stagedSymbolsManifest = assessStagedSymbolsManifest({
+        symbolsManifestPath,
+        stagedFiles,
+        sourceFiles: behaviorSourceFiles,
+    });
+    const stagedAuthoredSymbolsEvidence = collectStagedAuthoredSymbolsManifestEvidence({
+        stagedFiles,
+        sourceFiles: behaviorSourceFiles,
+    });
+    const markdownResultsByPath = new Map();
+    for (const [index, file] of markdownFiles.entries()) {
+        const result = markdownResults[index];
+        if (result) {
+            markdownResultsByPath.set(file.path, result);
+        }
+    }
+    const resolvedKbArtifacts = [];
+    let override = null;
+    for (const file of markdownFiles) {
+        const parsedOverride = parseKibiImpactOverride(file.content ?? "");
+        const evidenceKind = classifyKibiImpactEvidence({
+            filePath: file.path,
+            extractionOutputChanged: false,
+            overrideDeclared: parsedOverride.declared,
+            overrideRationale: parsedOverride.rationale,
+        });
+        if (evidenceKind === "entity_markdown") {
+            const result = markdownResultsByPath.get(file.path);
+            if (result && isKibiEntityType(result.entity.type)) {
+                resolvedKbArtifacts.push({
+                    kind: "entity_markdown",
+                    path: file.path,
+                    entityTypes: [result.entity.type],
+                    entityIds: [result.entity.id],
+                    sourcePaths: [...behaviorSourcePaths],
+                });
+            }
+            continue;
+        }
+        if (!parsedOverride.declared || override !== null) {
+            continue;
+        }
+        override = {
+            declaration: KIBI_NO_IMPACT_DECLARATION,
+            path: file.path,
+            sourcePaths: [...allSourcePaths],
+            reason: "non_behavioral_source_edit",
+            rationale: parsedOverride.rationale ?? "",
+        };
+    }
+    if (stagedAuthoredSymbolsEvidence.entries.length > 0) {
+        resolvedKbArtifacts.push({
+            kind: "symbols_manifest",
+            path: stagedAuthoredSymbolsEvidence.path,
+            entityTypes: ["symbol"],
+            entityIds: uniqueSorted(stagedAuthoredSymbolsEvidence.entries.flatMap((entry) => entry.entityIds)),
+            sourcePaths: uniqueSorted(stagedAuthoredSymbolsEvidence.entries.map((entry) => entry.sourcePath)),
+        });
+    }
+    return {
+        sourceChanges,
+        symbolsManifest: {
+            path: stagedSymbolsManifest.path,
+            state: stagedSymbolsManifest.state,
+            sourcePaths: stagedSymbolsManifest.sourcePaths,
+        },
+        mode: resolvedKbArtifacts.length > 0
+            ? { kind: "kb_changes", kbArtifacts: resolvedKbArtifacts }
+            : override
+                ? { kind: "no_impact_override", override }
+                : { kind: "missing" },
+    };
+}
 // implements REQ-006
 export async function checkCommand(options) {
     let prolog = null;
@@ -147,7 +318,8 @@ export async function checkCommand(options) {
                     return { exitCode: 0 };
                 }
                 const { manifestLookup, manifestResults } = buildManifestLookup(stagedFiles);
-                const codeFiles = stagedFiles.filter((f) => !f.path.endsWith(".md"));
+                const symbolsManifestPath = loadConfig(process.cwd()).paths.symbols ?? KIBI_SYMBOLS_MANIFEST_PATH;
+                const sourceFiles = stagedFiles.filter((file) => !file.path.endsWith(".md") && !isStagedManifestPath(file.path));
                 const markdownFiles = stagedFiles.filter((f) => f.path.endsWith(".md"));
                 const markdownErrors = [];
                 for (const f of markdownFiles) {
@@ -168,9 +340,11 @@ export async function checkCommand(options) {
                     return { exitCode: 1 };
                 }
                 const allSymbols = [];
-                for (const f of codeFiles) {
+                const symbolsByFile = new Map();
+                for (const f of sourceFiles) {
                     try {
                         const symbols = extractSymbolsFromStagedFile(f, manifestLookup);
+                        symbolsByFile.set(f.path, symbols);
                         if (symbols?.length) {
                             allSymbols.push(...symbols);
                         }
@@ -184,11 +358,27 @@ export async function checkCommand(options) {
                     ...manifestResults,
                     ...markdownResults,
                 ];
+                const stagedKibiEvidence = buildStagedKibiImpactEvidence({
+                    stagedFiles,
+                    sourceFiles,
+                    markdownFiles,
+                    markdownResults,
+                    symbolsByFile,
+                    symbolsManifestPath,
+                });
+                const stagedKibiDiagnostics = collectStagedKibiDiagnostics(stagedKibiEvidence);
                 if (allSymbols.length === 0 && stagedEntityResults.length === 0) {
                     console.log("No exported symbols or staged entities found in staged files.");
                     return { exitCode: 0 };
                 }
                 if (allSymbols.length === 0) {
+                    if (stagedKibiDiagnostics.length > 0) {
+                        console.log(formatStagedKibiDiagnostics(stagedKibiDiagnostics));
+                        if (options.dryRun) {
+                            return { exitCode: 0 };
+                        }
+                        return { exitCode: 1 };
+                    }
                     console.log("✓ No violations found in staged files.");
                     return { exitCode: 0 };
                 }
@@ -207,6 +397,10 @@ export async function checkCommand(options) {
                     prolog: tempCtx.prolog,
                 });
                 const violationsFormatted = formatStagedViolations(violationsRaw);
+                if (stagedKibiDiagnostics.length > 0) {
+                    console.log(formatStagedKibiDiagnostics(stagedKibiDiagnostics));
+                    console.log();
+                }
                 if (violationsRaw && violationsRaw.length > 0) {
                     console.log(violationsFormatted);
                     await cleanupTempKb(tempCtx.tempDir);
@@ -215,6 +409,13 @@ export async function checkCommand(options) {
                     }
                     return { exitCode: 1 };
                 }
+                if (stagedKibiDiagnostics.length > 0) {
+                    await cleanupTempKb(tempCtx.tempDir);
+                    if (options.dryRun) {
+                        return { exitCode: 0 };
+                    }
+                    return { exitCode: 1 };
+                }
                 console.log("✓ No violations found in staged symbols.");
                 await cleanupTempKb(tempCtx.tempDir);
                 return { exitCode: 0 };
@@ -278,6 +479,7 @@ export async function checkCommand(options) {
             "domain-contradictions",
             "strict-fact-shape",
             "strict-req-fact-pairing",
+            "strict-readiness",
         ];
         const canUseAggregated = Array.from(effectiveRules).every((r) => supportedRules.includes(r));
         if (canUseAggregated) {
@@ -302,6 +504,7 @@ export async function checkCommand(options) {
             await runCheck("domain-contradictions", checkDomainContradictions);
             await runCheck("strict-fact-shape", checkStrictFactShape);
             await runCheck("strict-req-fact-pairing", checkStrictReqFactPairing);
+            await runCheck("strict-readiness", checkStrictReadiness);
         }
         if (violations.length === 0) {
             console.log("✓ No violations found. KB is valid.");
@@ -312,6 +515,12 @@ export async function checkCommand(options) {
         for (const v of violations) {
             const filename = v.source ? path.basename(v.source, ".md") : v.entityId;
             console.log(`[${v.rule}] ${filename}`);
+            if (filename !== v.entityId) {
+                console.log(`  Entity: ${v.entityId}`);
+            }
+            if (v.source) {
+                console.log(`  Source: ${v.source}`);
+            }
             console.log(`  ${v.description}`);
             if (options.fix && v.suggestion) {
                 console.log(`  Suggestion: ${v.suggestion}`);
@@ -620,7 +829,7 @@ async function checkDomainContradictions(prolog) {
         violations.push({
             rule: "domain-contradictions",
             entityId: `${reqA}/${reqB}`,
-            description: reason,
+            description: `${reason} [strict-readiness: contradiction-ready]`,
             suggestion: "Supersede one requirement or align both to the same required property",
         });
     }
@@ -658,6 +867,22 @@ async function checkStrictReqFactPairing(prolog) {
     }
     return violations;
 }
+async function checkStrictReadiness(prolog) {
+    const violations = [];
+    const result = await prolog.query(`findall(violation(Rule, EntityId, Desc, Sugg, Src),
+      checks:strict_readiness_violation(violation(Rule, EntityId, Desc, Sugg, Src)),
+      Violations)`);
+    if (!result.success || !result.bindings.Violations) {
+        return violations;
+    }
+    const violationsStr = result.bindings.Violations;
+    if (violationsStr && violationsStr !== "[]") {
+        for (const v of parseViolationRows(violationsStr)) {
+            violations.push(v);
+        }
+    }
+    return violations;
+}
 async function checkSymbolCoverage(prolog) {
     const violations = [];
     const uncoveredResult = await prolog.query("setof(Symbol, symbol_no_req_coverage(Symbol, _), Symbols)");

package/dist/commands/init-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AAuGA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAQN;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMpD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAsBjD;AAGD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU3D;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AASD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkCnE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBpD"}
+{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AAoGA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAQN;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMpD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAsBjD;AAGD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU3D;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AASD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkCnE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBpD"}

package/dist/commands/init-helpers.js

@@ -27,6 +27,8 @@ const POST_CHECKOUT_HOOK = `#!/bin/sh
 # branch_flag is 1 for branch checkout, 0 for file checkout
 # Refresh branch/worktree assumptions after checkout so advisory plugin state
 # starts from synced KB data instead of stale in-memory cache assumptions.
+# Uses default non-coordinate-writing sync to avoid writing
+# committed symbol artifacts during automatic hook execution.
 
 old_ref=$1
 new_ref=$2
@@ -48,6 +50,8 @@ const POST_MERGE_HOOK = `#!/bin/sh
 # post-merge hook for kibi
 # Parameter: squash_flag (not used)
 # Refresh KB state after merge so branch-level assumptions remain current.
+# Uses default non-coordinate-writing sync to avoid writing
+# committed symbol artifacts during automatic hook execution.
 
 kibi sync
 `;
@@ -55,6 +59,8 @@ const POST_REWRITE_HOOK = `#!/bin/sh
 # post-rewrite hook for kibi
 # Triggered after git rebase, git commit --amend, etc.
 # Parameter: rewrite_type (rebase or amend)
+# Uses default non-coordinate-writing sync to avoid writing
+# committed symbol artifacts during automatic hook execution.
 
 rewrite_type=$1
 
@@ -66,23 +72,14 @@ const PRE_COMMIT_HOOK = `#!/bin/sh
 # pre-commit hook for kibi
 # Hard enforcement boundary: commits are blocked only here via kibi check.
 # The OpenCode plugin remains advisory and must not replace this gate.
+# Behavior-changing source edits require staged Kibi impact evidence
+# (KB entity docs, authored symbols metadata, or refreshed symbol
+# coordinates). Test-only and docs-only edits are exempt.
+# Refresh with:
+#   kibi sync --refresh-symbol-coordinates && git add documentation/symbol-coordinates.yaml documentation/symbols.yaml
 
 set -e
 
-symbols_manifest="documentation/symbols.yaml"
-
-if [ ! -f "$symbols_manifest" ]; then
-  echo "Kibi symbols manifest is missing: $symbols_manifest" >&2
-  echo "Run 'kibi init' to create it, then stage and commit it." >&2
-  exit 1
-fi
-
-if ! git diff --quiet -- "$symbols_manifest"; then
-  echo "Kibi symbols manifest has unstaged changes: $symbols_manifest" >&2
-  echo "Stage and commit documentation/symbols.yaml with the code changes that refreshed it." >&2
-  exit 1
-fi
-
 kibi check --staged
 `;
 export async function getCurrentBranch(cwd = process.cwd()) {

package/dist/commands/migrate.d.ts

@@ -0,0 +1,9 @@
+interface MigrateOptions {
+    dryRun?: boolean;
+    yes?: boolean;
+}
+export declare function migrateCommand(options?: MigrateOptions): Promise<{
+    exitCode: number;
+}>;
+export {};
+//# sourceMappingURL=migrate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAkCA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AA6ID,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAwG/B"}

package/dist/commands/migrate.js

@@ -0,0 +1,183 @@
+/*
+ * Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ * Copyright (C) 2026 Piotr Franczyk
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import * as path from "node:path";
+import { resolveActiveBranch } from "../utils/branch-resolver.js";
+import { LATEST_KB_SCHEMA_VERSION, getSchemaVersionStatus, normalizeSchemaVersion, } from "../utils/schema-version.js";
+const MIGRATION_AUDIT_VERSION = 1;
+function printWarning(message) {
+    console.log(`Warning: ${message}`);
+}
+function toRelativePath(cwd, filePath) {
+    const relativePath = path.relative(cwd, filePath);
+    return relativePath.length > 0 ? relativePath : path.basename(filePath);
+}
+function resolveMigrationBranch(cwd) {
+    const result = resolveActiveBranch(cwd);
+    if ("error" in result) {
+        const isNonGitContext = result.code === "NOT_A_GIT_REPO" || result.code === "GIT_NOT_AVAILABLE";
+        if (isNonGitContext) {
+            return {
+                branch: "main",
+                warnings: [
+                    "Not in a git repository; using 'main' for migration audit metadata.",
+                ],
+            };
+        }
+        return {
+            error: `Failed to resolve active branch: ${result.error}`,
+        };
+    }
+    return {
+        branch: result.branch,
+        warnings: [],
+    };
+}
+function loadRawConfigDocument(cwd) {
+    const kbDir = path.join(cwd, ".kb");
+    const configPath = path.join(kbDir, "config.json");
+    if (!existsSync(kbDir)) {
+        return {
+            error: "Missing .kb/ directory. Run 'kibi init' before 'kibi migrate'.",
+        };
+    }
+    if (!existsSync(configPath)) {
+        return {
+            error: "Missing .kb/config.json. Run 'kibi init' to create a baseline config before migrating.",
+        };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+        if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object") {
+            return {
+                error: ".kb/config.json must contain a JSON object. Fix the file and retry 'kibi migrate'.",
+            };
+        }
+        return {
+            config: parsed,
+            configPath,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            error: `Invalid .kb/config.json: ${message}. Fix the JSON or re-run 'kibi init'.`,
+        };
+    }
+}
+function writeJsonAtomically(filePath, value) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    renameSync(tempPath, filePath);
+}
+function formatSchemaVersion(rawSchemaVersion, normalized) {
+    if (normalized === null) {
+        if (rawSchemaVersion === undefined) {
+            return "missing";
+        }
+        return `invalid (${JSON.stringify(rawSchemaVersion)})`;
+    }
+    return String(normalized);
+}
+function buildMigrationAuditRecord(args) {
+    return {
+        auditVersion: MIGRATION_AUDIT_VERSION,
+        branch: args.branch,
+        configPath: args.configPath,
+        fromVersion: args.fromVersion,
+        migratedAt: args.migratedAt,
+        status: "applied",
+        toVersion: LATEST_KB_SCHEMA_VERSION,
+        warning: args.warning,
+    };
+}
+// implements REQ-003
+export async function migrateCommand(options = {}) {
+    const cwd = process.cwd();
+    const branchResult = resolveMigrationBranch(cwd);
+    if ("error" in branchResult) {
+        console.error(branchResult.error);
+        return { exitCode: 1 };
+    }
+    const configResult = loadRawConfigDocument(cwd);
+    if ("error" in configResult) {
+        console.error(configResult.error);
+        return { exitCode: 1 };
+    }
+    const { branch, warnings: branchWarnings } = branchResult;
+    const { config, configPath } = configResult;
+    const configStatus = getSchemaVersionStatus(config);
+    const normalizedVersion = normalizeSchemaVersion(config.schemaVersion);
+    const rawSchemaVersion = config.schemaVersion;
+    const needsCanonicalSchemaWrite = normalizedVersion === LATEST_KB_SCHEMA_VERSION &&
+        rawSchemaVersion !== undefined &&
+        rawSchemaVersion !== LATEST_KB_SCHEMA_VERSION;
+    const migrationWarning = needsCanonicalSchemaWrite
+        ? "KB config schemaVersion should be normalized to the latest numeric version."
+        : configStatus.warning;
+    const warnings = [...branchWarnings, ...(migrationWarning ? [migrationWarning] : [])];
+    const auditPath = path.join(cwd, ".kb", "migrations", `${branch}.json`);
+    const configPathRelative = toRelativePath(cwd, configPath);
+    const auditPathRelative = toRelativePath(cwd, auditPath);
+    for (const warning of warnings) {
+        printWarning(warning);
+    }
+    if (configStatus.currentVersion !== null &&
+        configStatus.currentVersion > configStatus.latestVersion) {
+        console.error(`Unsupported schemaVersion ${configStatus.currentVersion}. Upgrade kibi-cli before migrating this KB.`);
+        return { exitCode: 1 };
+    }
+    if (!configStatus.needsMigration && !needsCanonicalSchemaWrite) {
+        console.log(`No migration needed: ${configPathRelative} is already at schemaVersion ${LATEST_KB_SCHEMA_VERSION}.`);
+        if (existsSync(auditPath)) {
+            console.log(`Existing migration audit metadata: ${auditPathRelative}`);
+        }
+        return { exitCode: 0 };
+    }
+    const fromVersionLabel = formatSchemaVersion(rawSchemaVersion, normalizedVersion);
+    if (options.dryRun) {
+        console.log(`dry run: would migrate ${configPathRelative} schemaVersion from ${fromVersionLabel} to ${LATEST_KB_SCHEMA_VERSION}.`);
+        console.log(`dry run: would write migration audit metadata to ${auditPathRelative}.`);
+        console.log("Re-run with --yes to apply these changes.");
+        return { exitCode: 0 };
+    }
+    if (!options.yes) {
+        printWarning(`Migration required for ${configPathRelative}.`);
+        console.log("No changes applied.");
+        console.log("Use --dry-run to preview or --yes to apply the migration.");
+        return { exitCode: 0 };
+    }
+    const nextConfig = {
+        ...config,
+        schemaVersion: LATEST_KB_SCHEMA_VERSION,
+    };
+    const migratedAt = new Date().toISOString();
+    writeJsonAtomically(configPath, nextConfig);
+    writeJsonAtomically(auditPath, buildMigrationAuditRecord({
+        branch,
+        configPath: configPathRelative,
+        fromVersion: configStatus.currentVersion,
+        migratedAt,
+        warning: migrationWarning,
+    }));
+    console.log(`Migrated ${configPathRelative} schemaVersion from ${fromVersionLabel} to ${LATEST_KB_SCHEMA_VERSION}.`);
+    console.log(`Wrote migration audit metadata to ${auditPathRelative}.`);
+    console.log("Migration complete. Future 'kibi migrate' runs will be a no-op.");
+    return { exitCode: 0 };
+}

package/dist/commands/sync/manifest.d.ts

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";
 import { type ManifestSymbolEntry, enrichSymbolCoordinates } from "../../extractors/symbols-coordinator.js";
+import { writeCoordinateArtifact } from "../../extractors/symbol-coordinates.js";
+import { resolveSymbolsManifestPaths } from "../../utils/manifest-paths.js";
 interface ManifestDeps {
     dumpYAML: typeof dumpYAML;
     enrichSymbolCoordinates: typeof enrichSymbolCoordinates;
@@ -8,9 +10,13 @@ interface ManifestDeps {
     parseYAML: typeof parseYAML;
     readFileSync: typeof readFileSync;
     writeFileSync: typeof writeFileSync;
+    writeCoordinateArtifact: typeof writeCoordinateArtifact;
+    resolveSymbolsManifestPaths: typeof resolveSymbolsManifestPaths;
 }
-export declare const SYMBOLS_MANIFEST_COMMENT_BLOCK = "# symbols.yaml\n# AUTHORED fields (edit freely):\n#   id, title, sourceFile, links, status, tags, owner, priority\n# GENERATED fields (never edit manually \u2014 overwritten by kibi sync and kb.symbols.refresh):\n#   sourceLine, sourceColumn, sourceEndLine, sourceEndColumn, coordinatesGeneratedAt\n# Run `kibi sync` or call the `kb.symbols.refresh` MCP tool to refresh coordinates.\n";
-export declare function refreshManifestCoordinates(manifestPath: string, workspaceRoot: string, deps?: Partial<ManifestDeps>): Promise<void>;
+export declare const SYMBOLS_MANIFEST_COMMENT_BLOCK = "# symbols.yaml\n# AUTHORED fields (edit freely):\n#   id, title, sourceFile, links, status, tags, owner, priority\n# GENERATED fields (never edit manually \u2014 overwritten by kibi sync and kb.symbols.refresh):\n#   sourceLine, sourceColumn, sourceEndLine, sourceEndColumn\n# Run `kibi sync` or call the `kb.symbols.refresh` MCP tool to refresh coordinates.\n";
+export declare function refreshManifestCoordinates(manifestPath: string, workspaceRoot: string, deps?: Partial<ManifestDeps> & {
+    refreshSymbolCoordinates?: boolean;
+}): Promise<void>;
 export declare function hasAllGeneratedCoordinates(entry: ManifestSymbolEntry): boolean;
 export declare function isEligibleForCoordinateRefresh(sourceFile: string | undefined, workspaceRoot: string, deps?: Partial<ManifestDeps>): boolean;
 export {};

package/dist/commands/sync/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAElE,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AAEjD,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AAcD,eAAO,MAAM,8BAA8B,qYAM1C,CAAC;AAqBF,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CA8Ef;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAST;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAElE,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACjF,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;CACjE;AAgBD,eAAO,MAAM,8BAA8B,6WAM1C,CAAC;AAoBF,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG;IAAE,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAE,GACpE,OAAO,CAAC,IAAI,CAAC,CAmIf;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAOT;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}