kibi-cli 0.19.0 → 2.0.0

package/dist/commands/init-helpers.js

@@ -19,8 +19,35 @@ import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFile
 import * as path from "node:path";
 import fg from "fast-glob";
 import { getBranchDiagnostic, resolveActiveBranch, } from "../utils/branch-resolver.js";
-import { DEFAULT_CONFIG } from "../utils/config.js";
+import { ensureBranchStoreManifest } from "../utils/branch-store-locator.js";
+import { defaultKbManifest, writeKbManifest } from "../utils/kb-manifest.js";
+import { ENTITY_LANES, KB_PATHS } from "../utils/kb-paths.js";
 import { SYMBOLS_MANIFEST_COMMENT_BLOCK } from "./sync/manifest.js";
+// Git executes hooks with the caller's PATH, which does not include
+// node_modules/.bin, so a locally installed kibi CLI would not resolve.
+// Each hook resolves the binary up front: PATH first (global installs),
+// then a walk up from the repository root (git runs hooks from the top of
+// the working tree) for local npm/bun dependencies.
+const KIBI_BIN_RESOLVER = `KIBI_BIN="$(command -v kibi 2>/dev/null || true)"
+if [ -z "$KIBI_BIN" ]; then
+  kibi_dir="$PWD"
+  while [ -n "$kibi_dir" ] && [ "$kibi_dir" != "/" ]; do
+    if [ -x "$kibi_dir/node_modules/.bin/kibi" ]; then
+      KIBI_BIN="$kibi_dir/node_modules/.bin/kibi"
+      break
+    fi
+    kibi_parent="\${kibi_dir%/*}"
+    if [ -z "$kibi_parent" ]; then
+      kibi_parent="/"
+    fi
+    kibi_dir="$kibi_parent"
+  done
+fi
+if [ -z "$KIBI_BIN" ]; then
+  echo "kibi: cannot locate the kibi CLI (checked PATH and node_modules/.bin)." >&2
+  echo "Install kibi globally or as a project dependency, then re-run 'kibi init'." >&2
+  exit 1
+fi`;
 const POST_CHECKOUT_HOOK = `#!/bin/sh
 # post-checkout hook for kibi
 # Parameters: old_ref new_ref branch_flag
@@ -34,16 +61,12 @@ old_ref=$1
 new_ref=$2
 branch_flag=$3
 
-if [ "$branch_flag" = "1" ]; then
-  # Try to resolve the branch we just left (strip decorations like ^ and ~)
-  old_branch=$(git name-rev --name-only "$old_ref" 2>/dev/null | sed 's/\\^.*//')
+${KIBI_BIN_RESOLVER}
 
-  # Basic validation: non-empty and does not contain ~ or ^
-  if [ -n "$old_branch" ] && echo "$old_branch" | grep -qv '[~^]'; then
-    kibi branch ensure --from "$old_branch" && kibi sync
-  else
-    kibi branch ensure && kibi sync
-  fi
+if [ "$branch_flag" = "1" ]; then
+  # Branch stores are derived from the checked-out tracked sources. Never copy
+  # the old branch's compiled store during checkout.
+  "$KIBI_BIN" sync
 fi
 `;
 const POST_MERGE_HOOK = `#!/bin/sh
@@ -53,7 +76,9 @@ const POST_MERGE_HOOK = `#!/bin/sh
 # Uses default non-coordinate-writing sync to avoid writing
 # committed symbol artifacts during automatic hook execution.
 
-kibi sync
+${KIBI_BIN_RESOLVER}
+
+"$KIBI_BIN" sync
 `;
 const POST_REWRITE_HOOK = `#!/bin/sh
 # post-rewrite hook for kibi
@@ -64,8 +89,10 @@ const POST_REWRITE_HOOK = `#!/bin/sh
 
 rewrite_type=$1
 
+${KIBI_BIN_RESOLVER}
+
 if [ "$rewrite_type" = "rebase" ]; then
-  kibi sync
+  "$KIBI_BIN" sync
 fi
 `;
 const PRE_COMMIT_HOOK = `#!/bin/sh
@@ -73,14 +100,16 @@ const PRE_COMMIT_HOOK = `#!/bin/sh
 # 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.
+# (KB entity docs under .kb/, 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
+#   kibi sync --refresh-symbol-coordinates && git add .kb/symbol-coordinates.yaml .kb/symbols.yaml
 
 set -e
 
-kibi check --staged
+${KIBI_BIN_RESOLVER}
+
+"$KIBI_BIN" check --staged
 `;
 export async function getCurrentBranch(cwd = process.cwd()) {
     const result = resolveActiveBranch(cwd);
@@ -93,37 +122,89 @@ export async function getCurrentBranch(cwd = process.cwd()) {
 export function createKbDirectoryStructure(kbDir, currentBranch) {
     mkdirSync(kbDir, { recursive: true });
     mkdirSync(path.join(kbDir, "schema"), { recursive: true });
-    mkdirSync(path.join(kbDir, "branches", currentBranch), {
-        recursive: true,
-    });
+    // Canonical tracked knowledge lanes under .kb/.
+    for (const lane of ENTITY_LANES) {
+        mkdirSync(path.join(kbDir, lane), { recursive: true });
+    }
+    ensureBranchStoreManifest(path.dirname(kbDir), currentBranch);
     console.log("✓ Created .kb/ directory structure");
-    console.log(`✓ Created branches/${currentBranch}/ directory`);
+    console.log(`✓ Created hashed branch store for ${currentBranch}`);
 }
-export function createConfigFile(kbDir) {
-    writeFileSync(path.join(kbDir, "config.json"), JSON.stringify(DEFAULT_CONFIG, null, 2));
-    console.log("✓ Created config.json with default paths");
+export function createManifestFile(kbDir) {
+    writeKbManifest(path.dirname(kbDir), defaultKbManifest());
+    console.log("✓ Created Kibi lifecycle manifest at .kb/manifest.json");
 }
 export function updateGitIgnore(cwd) {
-    // implements REQ-001
+    // implements REQ-cli-init-canonical
     const gitignorePath = path.join(cwd, ".gitignore");
     const gitignoreContent = existsSync(gitignorePath)
         ? readFileSync(gitignorePath, "utf8")
         : "";
     const ensureEntry = (current, entry) => {
-        if (current.includes(entry)) {
+        const lines = current.split(/\r?\n/).map((line) => line.trim());
+        if (lines.includes(entry)) {
             return current;
         }
         return current ? `${current.trimEnd()}\n${entry}\n` : `${entry}\n`;
     };
-    const updatedContent = ensureEntry(gitignoreContent, ".kb/");
+    // Derived runtime state stays ignored. Authored knowledge lanes, the
+    // symbols manifest, relationship shards, schema, and the lifecycle
+    // manifest stay committable. `.kb/migrations/` is derived runtime
+    // audit state, not tracked project knowledge.
+    let updatedContent = stripLegacyKibiGitIgnoreStanza(gitignoreContent);
+    for (const entry of CANONICAL_DERIVED_GITIGNORE_ENTRIES) {
+        updatedContent = ensureEntry(updatedContent, entry);
+    }
     if (updatedContent !== gitignoreContent) {
         writeFileSync(gitignorePath, updatedContent);
-        console.log("✓ Added .kb/ to .gitignore");
+        console.log("✓ Configured .gitignore for the canonical .kb/ layout");
+    }
+}
+/** Exact derived-runtime entries owned by current Kibi init/migrate. */
+const CANONICAL_DERIVED_GITIGNORE_ENTRIES = [
+    ".kb/branches/",
+    ".kb/recovery/",
+    ".kb/proof/runs/",
+    ".kb/briefs/",
+    ".kb/migrations/",
+    ".kb/usage.log",
+];
+/**
+ * Pre-canonical Kibi init wrote a blanket `.kb/` fence and then
+ * re-included only config/schema/relationship artifacts. After the
+ * knowledge cutover that fence would keep `.kb/requirements/*` ignored.
+ */
+const LEGACY_KIBI_GITIGNORE_FENCE = ".kb/";
+const LEGACY_KIBI_GITIGNORE_REINCLUDES = [
+    "!.kb/",
+    "!.kb/config.json",
+    "!.kb/schema/",
+    "!.kb/relationships/",
+    "!.kb/relationships/*.yaml",
+];
+function stripLegacyKibiGitIgnoreStanza(content) {
+    if (content.length === 0)
+        return content;
+    const lines = content.split(/\r?\n/);
+    const trimmed = lines.map((line) => line.trim());
+    const hasFence = trimmed.includes(LEGACY_KIBI_GITIGNORE_FENCE);
+    const hasReinclude = LEGACY_KIBI_GITIGNORE_REINCLUDES.some((entry) => trimmed.includes(entry));
+    if (!hasFence || !hasReinclude) {
+        return content;
+    }
+    const drop = new Set([
+        LEGACY_KIBI_GITIGNORE_FENCE,
+        ...LEGACY_KIBI_GITIGNORE_REINCLUDES,
+    ]);
+    const kept = lines.filter((line) => !drop.has(line.trim()));
+    while (kept.length > 0 && kept[kept.length - 1] === "") {
+        kept.pop();
     }
+    return kept.length === 0 ? "" : `${kept.join("\n")}\n`;
 }
 // implements REQ-003
 export function ensureSymbolsManifestFile(cwd) {
-    const symbolsRelPath = DEFAULT_CONFIG.paths.symbols ?? "documentation/symbols.yaml";
+    const symbolsRelPath = KB_PATHS.symbolsManifest;
     const symbolsPath = path.join(cwd, symbolsRelPath);
     if (existsSync(symbolsPath)) {
         return;

package/dist/commands/init.d.ts

@@ -1,5 +1,7 @@
 interface InitOptions {
     hooks?: boolean;
+    github?: boolean;
+    badgeOnly?: boolean;
 }
 export declare function initCommand(options: InitOptions): Promise<{
     exitCode: number;

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

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAkCA,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAGD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA+D/B"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAqCA,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAoDD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA2F/B"}

package/dist/commands/init.js

@@ -18,45 +18,91 @@
 import { existsSync } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { resolveActiveBranch } from "../utils/branch-resolver.js";
-import { copySchemaFiles, createConfigFile, createKbDirectoryStructure, ensureSymbolsManifestFile, installGitHooks, updateGitIgnore, } from "./init-helpers.js";
+import { classifyActivation } from "../operations/bootstrap/activation.js";
+import { nodeFilesystem } from "../public/operations/node-ports.js";
+import { resolveBranchAttachment } from "../utils/branch-resolver.js";
+import { scaffoldGitHubIntegration } from "./github-init.js";
+import { copySchemaFiles, createKbDirectoryStructure, createManifestFile, ensureSymbolsManifestFile, installGitHooks, updateGitIgnore, } from "./init-helpers.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-// implements REQ-003
+async function initNextAction() {
+    const sourceFiles = await nodeFilesystem.glob([
+        ".kb/requirements/**/*.md",
+        ".kb/scenarios/**/*.md",
+        ".kb/tests/**/*.md",
+        ".kb/adrs/**/*.md",
+        ".kb/adr/**/*.md",
+        ".kb/flags/**/*.md",
+        ".kb/events/**/*.md",
+        ".kb/facts/**/*.md",
+    ], { cwd: process.cwd() });
+    const activation = await classifyActivation({
+        workspaceRoot: process.cwd(),
+        signal: new AbortController().signal,
+        clock: () => new Date(),
+        fs: nodeFilesystem,
+    }, sourceFiles);
+    switch (activation.activationState) {
+        case "root_active_seeded":
+            return {
+                operation: "continue-kibi-workflow",
+                message: "  Next: your repository already has seeded Kibi knowledge; continue working with your coding agent.",
+            };
+        case "root_partial":
+            return {
+                operation: "kibi doctor",
+                message: "  Next: run 'kibi doctor' to repair degraded Kibi infrastructure before bootstrapping.",
+            };
+        default:
+            return {
+                operation: "kb_plan_bootstrap",
+                message: "  Next: ask your coding agent “Bootstrap Kibi for this repository.”",
+            };
+    }
+}
+// implements REQ-cli-init
+// implements REQ-kibi-github-report-integration
 export async function initCommand(options) {
+    if (options.badgeOnly === true && options.github !== true) {
+        console.error("Error: --badge-only requires --github. The recommended integration is `kibi init --github` (badge + full report).");
+        return { exitCode: 1 };
+    }
     const kbDir = path.join(process.cwd(), ".kb");
     const kbExists = existsSync(kbDir);
-    // Resolve branch: allow non-git repos to use default "main" for init
+    // Resolve the exact active Git branch. Standalone use must be explicit via
+    // KIBI_BRANCH; there is no implicit default branch.
     let currentBranch;
-    const result = resolveActiveBranch();
+    const result = resolveBranchAttachment();
     if ("error" in result) {
         const isNonGitError = result.code === "NOT_A_GIT_REPO" || result.code === "GIT_NOT_AVAILABLE";
-        if (isNonGitError) {
-            // For init command, use "main" as default branch when not in a git repo.
-            // This allows initialization before git init, which is useful for first-time setup.
-            console.warn("Warning: Not in a git repository");
-            console.warn("Using 'main' as default branch. Run 'kibi sync' in a git repo for proper branch-aware behavior.");
-            currentBranch = "main";
-        }
-        else {
-            console.error("Error: Failed to resolve the active git branch.");
-            console.error(result.error);
-            return { exitCode: 1 };
-        }
+        console.error("Error: Failed to resolve the active git branch.");
+        console.error(isNonGitError
+            ? `${result.error} Set KIBI_BRANCH explicitly for a standalone workspace.`
+            : result.error);
+        return { exitCode: 1 };
     }
-    else {
-        currentBranch = result.branch;
+    if (result.migrationRequired) {
+        console.error(`Error: KB is attached through legacy branch storage for '${result.gitBranch}'. Run 'kibi branch migrate --from ${result.kbBranch} --to ${result.gitBranch} --apply' first.`);
+        return { exitCode: 1 };
     }
+    currentBranch = result.kbBranch;
     try {
         if (!kbExists) {
             createKbDirectoryStructure(kbDir, currentBranch);
-            createConfigFile(kbDir);
+            createManifestFile(kbDir);
             updateGitIgnore(process.cwd());
             const schemaSourceDir = path.resolve(__dirname, "..", "..", "schema");
             await copySchemaFiles(kbDir, schemaSourceDir);
         }
         else {
             console.log("✓ .kb/ directory already exists, skipping creation");
+            // An orphan branch can legitimately remove tracked `.kb/manifest.json`
+            // while the ignored branch stores remain on disk. Recreate the
+            // lifecycle manifest so status/doctor stay coherent; entity paths are
+            // canonical and require no per-repository configuration.
+            if (!existsSync(path.join(kbDir, "manifest.json"))) {
+                createManifestFile(kbDir);
+            }
         }
         ensureSymbolsManifestFile(process.cwd());
         if (options.hooks) {
@@ -68,10 +114,19 @@ export async function initCommand(options) {
                 installGitHooks(gitDir);
             }
         }
-        console.log("\nKibi initialized successfully!");
-        console.log("Next steps:");
-        console.log("  1. Run 'kibi doctor' to verify setup");
-        console.log("  2. Run 'kibi sync' to extract entities from documents");
+        console.log("\n✓ Kibi initialized. Kibi infrastructure is ready for this repository.");
+        console.log("  No product knowledge was inferred or changed by kibi init.");
+        if (kbExists) {
+            console.log("  Existing Kibi source knowledge was preserved.");
+        }
+        console.log((await initNextAction()).message);
+        console.log("  Optional diagnostic: run 'kibi doctor' if setup appears degraded.");
+        if (options.github === true) {
+            scaffoldGitHubIntegration({
+                cwd: process.cwd(),
+                badgeOnly: options.badgeOnly === true,
+            });
+        }
         return { exitCode: 0 };
     }
     catch (error) {

package/dist/commands/legacy-storage-migration.d.ts

@@ -0,0 +1,54 @@
+import { type SemanticAdvisorBackfill } from "../utils/kb-manifest.js";
+import { type EntityLane } from "../utils/kb-paths.js";
+/**
+ * One-way migration from the legacy configurable layout (entity documents
+ * under `documentation/` or custom configured paths, `.kb/config.json`)
+ * to the canonical `.kb/` knowledge namespace.
+ *
+ * The migration is deterministic and idempotent:
+ * - legacy `.kb/config.json` is read (never trusted blindly);
+ * - configured or default legacy paths are discovered on disk;
+ * - files move into `.kb/<lane>/` without content changes;
+ * - destination conflicts abort before any file moves;
+ * - partial migrations resume safely (already-moved files are no-ops);
+ * - on success the legacy config is retired.
+ */
+export interface StorageMigrationPlan {
+    /** Files that would move from a legacy location into `.kb/`. */
+    moves: StorageMigrationMove[];
+    /** Legacy `.kb/config.json` disposition. */
+    legacyConfig: "absent" | "present" | "malformed";
+    legacyConfigError?: string;
+    /** Lifecycle state preserved into the canonical manifest. */
+    schemaVersion: number | null;
+    semanticAdvisorBackfill: SemanticAdvisorBackfill | null;
+    /** Why the migration cannot proceed automatically, if blocked. */
+    blockers: string[];
+}
+export interface StorageMigrationMove {
+    from: string;
+    to: string;
+    lane: EntityLane | "symbols";
+}
+/** Discover the concrete migration moves for a workspace. */
+export declare function planLegacyStorageMigration(cwd: string): StorageMigrationPlan;
+export interface StorageMigrationResult {
+    movedFiles: string[];
+    retiredLegacyConfig: boolean;
+    manifestPath: string;
+    schemaVersion: number;
+    semanticAdvisorBackfill: SemanticAdvisorBackfill;
+}
+/**
+ * Apply the legacy storage migration. Moves every planned file, writes the
+ * canonical lifecycle manifest, retires the legacy config, and prunes empty
+ * legacy directories. Fails closed on any blocker.
+ */
+export declare function applyLegacyStorageMigration(cwd: string, plan: StorageMigrationPlan): StorageMigrationResult;
+/** Rewrite recovery pending-source receipts after a storage cutover. */
+export declare function rewritePendingSourceReceiptPaths(cwd: string, moves: readonly StorageMigrationMove[]): number;
+/** True when the workspace still needs the legacy storage migration. */
+export declare function needsLegacyStorageMigration(cwd: string): boolean;
+/** Entity lanes that must exist for the canonical layout to be complete. */
+export declare function missingCanonicalLanes(cwd: string): EntityLane[];
+//# sourceMappingURL=legacy-storage-migration.d.ts.map

package/dist/commands/legacy-storage-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-storage-migration.d.ts","sourceRoot":"","sources":["../../src/commands/legacy-storage-migration.ts"],"names":[],"mappings":"AAoCA,OAAO,EACL,KAAK,uBAAuB,EAI7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAGL,KAAK,UAAU,EAEhB,MAAM,sBAAsB,CAAC;AAI9B;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,4CAA4C;IAC5C,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uBAAuB,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACxD,kEAAkE;IAClE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;CAC9B;AA2BD,6DAA6D;AAC7D,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAqH5E;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,uBAAuB,EAAE,uBAAuB,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,oBAAoB,GACzB,sBAAsB,CAqDxB;AA+BD,wEAAwE;AACxE,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,oBAAoB,EAAE,GACrC,MAAM,CAwCR;AAED,wEAAwE;AACxE,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOhE;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CAI/D"}