kibi-cli 0.2.3 → 0.2.6

package/dist/kb/target-resolver.js

@@ -0,0 +1,313 @@
+/*
+ * 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.
+ */
+import { execSync } from "node:child_process";
+import * as path from "node:path";
+const WORKSPACE_ENV_KEYS = [
+    "KIBI_WORKSPACE",
+    "KIBI_PROJECT_ROOT",
+    "KIBI_ROOT",
+];
+const KB_PATH_ENV_KEYS = ["KIBI_KB_PATH", "KB_PATH"];
+/**
+ * Resolve workspace root directory.
+ * Priority: env vars > .kb directory > .git directory > cwd
+ */
+export function resolveWorkspaceRoot(startDir = process.cwd()) {
+    const envRoot = readFirstEnv(WORKSPACE_ENV_KEYS);
+    if (envRoot) {
+        return path.resolve(envRoot);
+    }
+    const kbRoot = findUpwards(startDir, ".kb");
+    if (kbRoot) {
+        return kbRoot;
+    }
+    const gitRoot = findUpwards(startDir, ".git");
+    if (gitRoot) {
+        return gitRoot;
+    }
+    return path.resolve(startDir);
+}
+/**
+ * Resolve workspace root with reason for resolution.
+ */
+export function resolveWorkspaceRootInfo(startDir = process.cwd()) {
+    const envRoot = readFirstEnv(WORKSPACE_ENV_KEYS);
+    if (envRoot) {
+        return { root: path.resolve(envRoot), reason: "env" };
+    }
+    const kbRoot = findUpwards(startDir, ".kb");
+    if (kbRoot) {
+        return { root: kbRoot, reason: "kb" };
+    }
+    const gitRoot = findUpwards(startDir, ".git");
+    if (gitRoot) {
+        return { root: gitRoot, reason: "git" };
+    }
+    return { root: path.resolve(startDir), reason: "cwd" };
+}
+/**
+ * Resolve KB path for a given workspace and branch.
+ */
+export function resolveKbPath(workspaceRoot, branch) {
+    const envPath = readFirstEnv(KB_PATH_ENV_KEYS);
+    if (envPath) {
+        const resolved = path.resolve(envPath);
+        if (isBranchPath(resolved)) {
+            return resolved;
+        }
+        return path.join(resolved, "branches", branch);
+    }
+    return path.join(workspaceRoot, ".kb", "branches", branch);
+}
+/**
+ * Resolve the active branch according to precedence:
+ * 1. KIBI_BRANCH env var (if set)
+ * 2. Git active branch (from git branch --show-current)
+ * 3. Diagnostic failure (no silent fallback)
+ */
+export function resolveActiveBranch(workspaceRoot = process.cwd()) {
+    // 1. Check KIBI_BRANCH env var first (highest precedence)
+    const envBranch = process.env.KIBI_BRANCH?.trim();
+    if (envBranch) {
+        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) {
+            return {
+                error: getBranchDiagnostic(undefined, "Git is in detached HEAD state"),
+                code: "DETACHED_HEAD",
+            };
+        }
+        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",
+                };
+            }
+            const normalizedBranch = branch === "master" ? "main" : branch;
+            return { branch: normalizedBranch };
+        }
+        catch {
+            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",
+            };
+        }
+    }
+}
+/**
+ * @deprecated defaultBranch is deprecated. Branch lifecycle now follows git naturally.
+ * This function is kept for backward compatibility but should not be used for new code.
+ *
+ * Resolve the default branch using precedence:
+ * 1. Configured defaultBranch from config (if set and valid)
+ * 2. Git remote HEAD (refs/remotes/origin/HEAD)
+ * 3. Fallback to "main"
+ */
+export function resolveDefaultBranch(cwd = process.cwd(), config) {
+    // 1. Check config.defaultBranch first
+    const configuredBranch = config?.defaultBranch?.trim();
+    if (configuredBranch) {
+        if (!isValidBranchName(configuredBranch)) {
+            return {
+                error: `Invalid defaultBranch configured in .kb/config.json: '${configuredBranch}'`,
+                code: "INVALID_CONFIG",
+            };
+        }
+        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();
+        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
+    }
+    // 3. Final fallback to "main"
+    return { branch: "main" };
+}
+/**
+ * Resolve complete KB target with all components.
+ */
+export function resolveKbTarget(options) {
+    const workspaceRoot = options?.workspaceRoot ?? resolveWorkspaceRoot();
+    let branch;
+    let reason;
+    if (options?.branch) {
+        branch = options.branch;
+        reason = "env";
+    }
+    else {
+        const branchResult = resolveActiveBranch(workspaceRoot);
+        if ("error" in branchResult) {
+            throw new Error(`Failed to resolve active branch: ${branchResult.error}. ` +
+                `Ensure you are in a git repository with a valid branch checked out.`);
+        }
+        branch = branchResult.branch;
+        reason = "git";
+    }
+    const kbPath = resolveKbPath(workspaceRoot, branch);
+    return { workspaceRoot, branch, kbPath, reason };
+}
+/**
+ * Check if repository is in detached HEAD state.
+ */
+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;
+    }
+}
+/**
+ * Validate a branch name for safety.
+ */
+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;
+}
+/**
+ * Get a detailed diagnostic message for branch resolution failures.
+ */
+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");
+}
+function readFirstEnv(keys) {
+    for (const key of keys) {
+        const value = process.env[key]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return null;
+}
+function findUpwards(startDir, marker) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const candidate = path.join(current, marker);
+        try {
+            // Check if path exists (works for both files and directories)
+            // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+            import("node:fs").then((fs) => {
+                fs.accessSync(candidate);
+            });
+            return current;
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current) {
+                return null;
+            }
+            current = parent;
+        }
+    }
+}
+function isBranchPath(p) {
+    const parent = path.basename(path.dirname(p));
+    return parent === "branches";
+}

package/dist/prolog/codec.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Prolog codec utilities for escaping atoms, parsing responses, and handling
+ * Prolog list/property structures.
+ */
+/**
+ * Escape a string for use as a Prolog atom.
+ * Doubles single-quote characters per ISO Prolog standard.
+ */
+export declare function escapeAtom(value: string): string;
+/**
+ * Convert a string to a Prolog atom, quoting if necessary.
+ * Simple atoms (lowercase start, alphanumeric + underscore) pass through.
+ */
+export declare function toPrologAtom(value: string): string;
+/**
+ * Escape a string for embedding inside a single-quoted Prolog atom.
+ * Alias for escapeAtom for semantic clarity.
+ */
+export declare function escapeAtomContent(value: string): string;
+/**
+ * Split a string by delimiter at the top level (not inside brackets or quotes).
+ * This is the general-purpose version that splits at depth 0.
+ */
+export declare function splitTopLevel(str: string, delimiter: string): string[];
+/**
+ * Parse a Prolog list of lists into a JavaScript array.
+ * Input: "[[a,b,c],[d,e,f]]"
+ * Output: [["a", "b", "c"], ["d", "e", "f"]]
+ */
+export declare function parseListOfLists(listStr: string): string[][];
+/**
+ * Parse a single entity from Prolog binding format.
+ * Input: "[abc123, req, [id=abc123, title=\"Test\", ...]]"
+ */
+export declare function parseEntityFromBinding(bindingStr: string): Record<string, unknown>;
+/**
+ * Parse entity from array returned by parseListOfLists.
+ * Input: ["abc123", "req", "[id=abc123, title=\"Test\", ...]"]
+ */
+export declare function parseEntityFromList(data: string[]): Record<string, unknown>;
+/**
+ * Parse Prolog property list into JavaScript object.
+ * Input: "[id=abc123, title=\"Test\"]"
+ */
+export declare function parsePropertyList(propsStr: string): Record<string, unknown>;
+/**
+ * Parse a single Prolog value, handling typed literals and URIs.
+ */
+export declare function parsePrologValue(valueInput: string): unknown;
+/**
+ * Parse an atom list from Prolog response.
+ * Input: "[a, b, c]" or atom string
+ */
+export declare function parseAtomList(raw: string): string[];
+/**
+ * Parse a list of pairs from Prolog response.
+ */
+export declare function parsePairList(raw: string): Array<[string, string]>;
+/**
+ * Parse a list of triples from Prolog response.
+ */
+export declare function parseTriples(raw: string): Array<[string, string, string]>;
+//# sourceMappingURL=codec.d.ts.map

package/dist/prolog/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/prolog/codec.ts"],"names":[],"mappings":"AAUA;;;GAGG;AAEH;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAwDtE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CA6C5D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAW3E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA6B3E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CA2E5D;AAmED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAcnD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAclE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAczE"}