kibi-cli 0.1.7 → 0.2.0

package/dist/utils/branch-resolver.js

@@ -0,0 +1,311 @@
+/*
+ * 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 { execSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync, } from "node:fs";
+import * as path from "node:path";
+// Files to exclude when copying branch snapshots (volatile artifacts)
+const VOLATILE_ARTIFACTS = new Set([
+    "sync-cache.json",
+    "journal.log",
+    "audit.log",
+    "lock",
+    "lockfile",
+    ".lock",
+]);
+// File extensions to exclude
+const VOLATILE_EXTENSIONS = new Set([".lock", ".tmp", ".temp", ".pid"]);
+/**
+ * Check if a file should be excluded from clean snapshot copy.
+ */
+function isVolatileArtifact(fileName) {
+    if (VOLATILE_ARTIFACTS.has(fileName))
+        return true;
+    const ext = path.extname(fileName).toLowerCase();
+    if (VOLATILE_EXTENSIONS.has(ext))
+        return true;
+    // Journal files with timestamps: journal-*.log
+    if (fileName.startsWith("journal-") && fileName.endsWith(".log"))
+        return true;
+    return false;
+}
+/**
+ * Resolve the active branch according to ADR-012 precedence:
+ * 1. KIBI_BRANCH env var (if set)
+ * 2. Git active branch (from git branch --show-current)
+ * 3. Diagnostic failure (no silent fallback)
+ *
+ * @param workspaceRoot - The workspace root directory
+ * @returns BranchResolutionResult with either the branch name or an error
+ */
+export function resolveActiveBranch(workspaceRoot = process.cwd()) {
+    // 1. Check KIBI_BRANCH env var first (highest precedence)
+    const envBranch = process.env.KIBI_BRANCH?.trim();
+    if (envBranch) {
+        // Validate the env branch name
+        if (!isValidBranchName(envBranch)) {
+            return {
+                error: `Invalid branch name from KIBI_BRANCH environment variable: '${envBranch}'`,
+                code: "ENV_OVERRIDE",
+            };
+        }
+        return { branch: envBranch };
+    }
+    // 2. Try to get the current git branch
+    try {
+        const branch = execSync("git branch --show-current", {
+            cwd: workspaceRoot,
+            encoding: "utf8",
+            timeout: 5000,
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        if (!branch) {
+            // Empty result means detached HEAD
+            return {
+                error: getBranchDiagnostic(undefined, "Git is in detached HEAD state"),
+                code: "DETACHED_HEAD",
+            };
+        }
+        // Validate the branch name
+        if (!isValidBranchName(branch)) {
+            return {
+                error: `Invalid branch name detected: '${branch}'`,
+                code: "UNKNOWN_ERROR",
+            };
+        }
+        // Normalize 'master' to 'main' for consistency
+        const normalizedBranch = branch === "master" ? "main" : branch;
+        return { branch: normalizedBranch };
+    }
+    catch (error) {
+        // Try alternative: git rev-parse --abbrev-ref HEAD
+        try {
+            const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+                cwd: workspaceRoot,
+                encoding: "utf8",
+                timeout: 5000,
+                stdio: ["pipe", "pipe", "pipe"],
+            }).trim();
+            if (branch === "HEAD") {
+                return {
+                    error: getBranchDiagnostic(undefined, "Git is in detached HEAD state"),
+                    code: "DETACHED_HEAD",
+                };
+            }
+            if (!branch || branch === "") {
+                return {
+                    error: getBranchDiagnostic(undefined, "Unable to determine git branch"),
+                    code: "UNBORN_BRANCH",
+                };
+            }
+            if (!isValidBranchName(branch)) {
+                return {
+                    error: `Invalid branch name detected: '${branch}'`,
+                    code: "UNKNOWN_ERROR",
+                };
+            }
+            // Normalize 'master' to 'main' for consistency
+            const normalizedBranch = branch === "master" ? "main" : branch;
+            return { branch: normalizedBranch };
+        }
+        catch (fallbackError) {
+            // Determine specific error type
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (errorMessage.includes("not a git repository")) {
+                return {
+                    error: getBranchDiagnostic(undefined, "Not a git repository"),
+                    code: "NOT_A_GIT_REPO",
+                };
+            }
+            if (errorMessage.includes("command not found") ||
+                errorMessage.includes("ENOENT")) {
+                return {
+                    error: getBranchDiagnostic(undefined, "Git is not installed or not available in PATH"),
+                    code: "GIT_NOT_AVAILABLE",
+                };
+            }
+            return {
+                error: getBranchDiagnostic(undefined, errorMessage),
+                code: "UNKNOWN_ERROR",
+            };
+        }
+    }
+}
+/**
+ * Check if the repository is in detached HEAD state.
+ *
+ * @param workspaceRoot - The workspace root directory
+ * @returns true if in detached HEAD, false otherwise
+ */
+export function isDetachedHead(workspaceRoot = process.cwd()) {
+    try {
+        const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+            cwd: workspaceRoot,
+            encoding: "utf8",
+            timeout: 5000,
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        return branch === "HEAD";
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Get a detailed diagnostic message for branch resolution failures.
+ *
+ * @param branch - The branch that was detected (if any)
+ * @param error - The error message or context
+ * @returns A formatted diagnostic message
+ */
+export function getBranchDiagnostic(branch, error) {
+    const lines = ["Branch Resolution Failed", "", `Reason: ${error}`];
+    if (branch) {
+        lines.push(`Detected branch: ${branch}`);
+    }
+    lines.push("", "Resolution options:", "1. Set KIBI_BRANCH environment variable to explicitly specify the branch:", "   export KIBI_BRANCH=main", "", "2. Ensure you are in a git repository with a valid checked-out branch", "", "3. If in detached HEAD state, create or checkout a branch:", "   git checkout -b my-branch", "", "4. For non-git workspaces, always use KIBI_BRANCH:", "   KIBI_BRANCH=feature-branch kibi sync");
+    return lines.join("\n");
+}
+/**
+ * Validate a branch name for safety and correctness.
+ *
+ * @param name - The branch name to validate
+ * @returns true if valid, false otherwise
+ */
+export function isValidBranchName(name) {
+    if (!name || name.length === 0 || name.length > 255)
+        return false;
+    // Reject path traversal attempts
+    if (name.includes("..") || path.isAbsolute(name) || name.startsWith("/")) {
+        return false;
+    }
+    // Only allow safe characters
+    if (!/^[a-zA-Z0-9._\-/+]+$/.test(name))
+        return false;
+    // Reject problematic patterns
+    if (name.includes("//") ||
+        name.endsWith("/") ||
+        name.endsWith(".") ||
+        name.includes("\\") ||
+        name.startsWith("-")) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Copy a clean snapshot from source branch to target branch, excluding
+ * volatile artifacts like sync-cache.json, lock files, and journal files.
+ *
+ * @param sourcePath - Path to the source branch KB directory
+ * @param targetPath - Path to the target branch KB directory
+ * @throws Error if the copy fails
+ */
+export function copyCleanSnapshot(sourcePath, targetPath) {
+    if (!existsSync(sourcePath)) {
+        throw new Error(`Source branch KB does not exist: ${sourcePath}`);
+    }
+    // Create target directory
+    mkdirSync(targetPath, { recursive: true });
+    // Recursively copy, excluding volatile artifacts
+    copyDirectoryClean(sourcePath, targetPath);
+}
+/**
+ * Recursively copy a directory, excluding volatile artifacts.
+ */
+function copyDirectoryClean(sourceDir, targetDir) {
+    const entries = readdirSync(sourceDir);
+    for (const entry of entries) {
+        // Skip volatile artifacts
+        if (isVolatileArtifact(entry)) {
+            continue;
+        }
+        const sourcePath = path.join(sourceDir, entry);
+        const targetPath = path.join(targetDir, entry);
+        const stat = statSync(sourcePath);
+        if (stat.isDirectory()) {
+            // Recursively copy subdirectory
+            mkdirSync(targetPath, { recursive: true });
+            copyDirectoryClean(sourcePath, targetPath);
+        }
+        else {
+            // Copy file
+            copyFileSync(sourcePath, targetPath);
+        }
+    }
+}
+/**
+ * Get the list of files that would be excluded from a clean snapshot copy.
+ * Useful for debugging and testing.
+ *
+ * @returns Array of volatile artifact patterns
+ */
+export function getVolatileArtifactPatterns() {
+    return [
+        ...Array.from(VOLATILE_ARTIFACTS),
+        ...Array.from(VOLATILE_EXTENSIONS).map((ext) => `*${ext}`),
+        "journal-*.log",
+    ];
+}
+/**
+ * Resolve the default branch using the following precedence:
+ * 1. Configured defaultBranch from config (if set and valid)
+ * 2. Git remote HEAD (refs/remotes/origin/HEAD)
+ * 3. Fallback to "main"
+ *
+ * Unlike resolveActiveBranch, this does NOT normalize branch names.
+ * Configured names are returned verbatim.
+ *
+ * @param cwd - The working directory to resolve the default branch
+ * @param config - Optional config with defaultBranch
+ * @returns BranchResolutionResult with either the branch name or an error
+ */
+export function resolveDefaultBranch(cwd = process.cwd(), config) {
+    // 1. Check config.defaultBranch first (highest precedence)
+    const configuredBranch = config?.defaultBranch?.trim();
+    if (configuredBranch) {
+        if (!isValidBranchName(configuredBranch)) {
+            return {
+                error: `Invalid defaultBranch configured in .kb/config.json: '${configuredBranch}'`,
+                code: "INVALID_CONFIG",
+            };
+        }
+        // Return configured branch verbatim (no normalization)
+        return { branch: configuredBranch };
+    }
+    // 2. Try to get the remote default branch from origin/HEAD
+    try {
+        const remoteHead = execSync("git symbolic-ref refs/remotes/origin/HEAD", {
+            cwd,
+            encoding: "utf8",
+            timeout: 5000,
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        // Parse refs/remotes/origin/BRANCH_NAME -> BRANCH_NAME
+        const match = remoteHead.match(/^refs\/remotes\/origin\/(.+)$/);
+        if (match) {
+            const branch = match[1];
+            if (isValidBranchName(branch)) {
+                return { branch };
+            }
+        }
+    }
+    catch {
+        // origin/HEAD doesn't exist or command failed, fall through to fallback
+    }
+    // 3. Final fallback to "main"
+    return { branch: "main" };
+}

package/dist/utils/config.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Configuration paths for entity documentation directories.
+ */
+export interface KbConfigPaths {
+    requirements?: string;
+    scenarios?: string;
+    tests?: string;
+    adr?: string;
+    flags?: string;
+    events?: string;
+    facts?: string;
+    symbols?: string;
+}
+/**
+ * Shared configuration for Kibi.
+ * Stored in .kb/config.json
+ */
+export interface KbConfig {
+    paths: KbConfigPaths;
+    defaultBranch?: string;
+}
+/**
+ * Default configuration values for new repositories.
+ */
+export declare const DEFAULT_CONFIG: KbConfig;
+/**
+ * Default paths used by sync command (backward compatible glob patterns).
+ */
+export declare const DEFAULT_SYNC_PATHS: KbConfigPaths;
+/**
+ * Load and parse the Kibi configuration from .kb/config.json.
+ * Falls back to DEFAULT_CONFIG if the file doesn't exist or is invalid.
+ *
+ * @param cwd - The working directory to look for .kb/config.json
+ * @returns The merged configuration (defaults + user config)
+ */
+export declare function loadConfig(cwd?: string): KbConfig;
+/**
+ * Load sync configuration with fallback to glob patterns.
+ * This is used by sync.ts to maintain backward compatibility with
+ * older config files that may use glob patterns.
+ *
+ * @param cwd - The working directory to look for .kb/config.json
+ * @returns The merged configuration with sync-compatible paths
+ */
+export declare function loadSyncConfig(cwd?: string): KbConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/utils/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAqBA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,aAAa,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,QAY5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAShC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAsB,GAAG,QAAQ,CAqBhE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAsB,GAAG,QAAQ,CAqBpE"}

package/dist/utils/config.js

@@ -0,0 +1,105 @@
+/*
+ * 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, readFileSync } from "node:fs";
+import * as path from "node:path";
+/**
+ * Default configuration values for new repositories.
+ */
+export const DEFAULT_CONFIG = {
+    paths: {
+        requirements: "documentation/requirements",
+        scenarios: "documentation/scenarios",
+        tests: "documentation/tests",
+        adr: "documentation/adr",
+        flags: "documentation/flags",
+        events: "documentation/events",
+        facts: "documentation/facts",
+        symbols: "documentation/symbols.yaml",
+    },
+    defaultBranch: undefined,
+};
+/**
+ * Default paths used by sync command (backward compatible glob patterns).
+ */
+export const DEFAULT_SYNC_PATHS = {
+    requirements: "requirements/**/*.md",
+    scenarios: "scenarios/**/*.md",
+    tests: "tests/**/*.md",
+    adr: "adr/**/*.md",
+    flags: "flags/**/*.md",
+    events: "events/**/*.md",
+    facts: "facts/**/*.md",
+    symbols: "symbols.yaml",
+};
+/**
+ * Load and parse the Kibi configuration from .kb/config.json.
+ * Falls back to DEFAULT_CONFIG if the file doesn't exist or is invalid.
+ *
+ * @param cwd - The working directory to look for .kb/config.json
+ * @returns The merged configuration (defaults + user config)
+ */
+export function loadConfig(cwd = process.cwd()) {
+    const configPath = path.join(cwd, ".kb/config.json");
+    let userConfig = {};
+    if (existsSync(configPath)) {
+        try {
+            const content = readFileSync(configPath, "utf8");
+            userConfig = JSON.parse(content);
+        }
+        catch {
+            // Invalid config, use defaults
+            userConfig = {};
+        }
+    }
+    return {
+        paths: {
+            ...DEFAULT_CONFIG.paths,
+            ...userConfig.paths,
+        },
+        defaultBranch: userConfig.defaultBranch,
+    };
+}
+/**
+ * Load sync configuration with fallback to glob patterns.
+ * This is used by sync.ts to maintain backward compatibility with
+ * older config files that may use glob patterns.
+ *
+ * @param cwd - The working directory to look for .kb/config.json
+ * @returns The merged configuration with sync-compatible paths
+ */
+export function loadSyncConfig(cwd = process.cwd()) {
+    const configPath = path.join(cwd, ".kb/config.json");
+    let userConfig = {};
+    if (existsSync(configPath)) {
+        try {
+            const content = readFileSync(configPath, "utf8");
+            userConfig = JSON.parse(content);
+        }
+        catch {
+            // Invalid config, use defaults
+            userConfig = {};
+        }
+    }
+    return {
+        paths: {
+            ...DEFAULT_SYNC_PATHS,
+            ...userConfig.paths,
+        },
+        defaultBranch: userConfig.defaultBranch,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -36,6 +36,18 @@
     "./schemas/relationship": {
       "types": "./dist/public/schemas/relationship.d.ts",
       "default": "./dist/public/schemas/relationship.js"
+    },
+    "./utils/branch-resolver": {
+      "types": "./dist/public/branch-resolver.d.ts",
+      "default": "./dist/public/branch-resolver.js"
+    },
+    "./public/branch-resolver": {
+      "types": "./dist/public/branch-resolver.d.ts",
+      "default": "./dist/public/branch-resolver.js"
+    },
+    "./diagnostics": {
+      "types": "./dist/diagnostics.d.ts",
+      "default": "./dist/diagnostics.js"
     }
   },
   "types": "./dist/cli.d.ts",

package/src/public/branch-resolver.ts

@@ -0,0 +1 @@
+export * from "../utils/branch-resolver.js";