kibi-cli 0.1.0

package/dist/extractors/manifest.js

@@ -0,0 +1,122 @@
+/*
+ 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/>.
+*/
+/*
+ How to apply this header to source files (examples)
+
+ 1) Prepend header to a single file (POSIX shells):
+
+    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
+
+ 2) Apply to multiple files (example: the project's main entry files):
+
+    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
+      if [ -f "$f" ]; then
+        cp "$f" "$f".bak
+        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
+      fi
+    done
+
+ 3) Avoid duplicating the header: run a quick guard to only add if missing
+
+    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
+      if [ -f "$f" ]; then
+        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
+          cp "$f" "$f".bak
+          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
+        fi
+      fi
+    done
+*/
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { load as parseYAML } from "js-yaml";
+export class ManifestError extends Error {
+    filePath;
+    constructor(message, filePath) {
+        super(message);
+        this.filePath = filePath;
+        this.name = "ManifestError";
+    }
+}
+export function extractFromManifest(filePath) {
+    try {
+        const content = readFileSync(filePath, "utf8");
+        const manifest = parseYAML(content);
+        if (!manifest.symbols || !Array.isArray(manifest.symbols)) {
+            throw new ManifestError("No symbols array found in manifest", filePath);
+        }
+        return manifest.symbols.map((symbol) => {
+            if (!symbol.title) {
+                throw new ManifestError("Missing required field: title", filePath);
+            }
+            const id = symbol.id || generateId(filePath, symbol.title);
+            const relationships = extractRelationships(symbol.relationships || symbol.links || [], id);
+            return {
+                entity: {
+                    id,
+                    type: "symbol",
+                    title: symbol.title,
+                    status: symbol.status || "draft",
+                    created_at: symbol.created_at || new Date().toISOString(),
+                    updated_at: symbol.updated_at || new Date().toISOString(),
+                    source: filePath,
+                    tags: symbol.tags,
+                    owner: symbol.owner,
+                    priority: symbol.priority,
+                    severity: symbol.severity,
+                    links: symbol.links,
+                    text_ref: symbol.text_ref,
+                },
+                relationships,
+            };
+        });
+    }
+    catch (error) {
+        if (error instanceof ManifestError) {
+            throw error;
+        }
+        if (error instanceof Error) {
+            throw new ManifestError(`Failed to parse manifest: ${error.message}`, filePath);
+        }
+        throw error;
+    }
+}
+function generateId(filePath, title) {
+    const hash = createHash("sha256");
+    hash.update(`${filePath}:${title}`);
+    return hash.digest("hex").substring(0, 16);
+}
+function extractRelationships(links, fromId) {
+    if (!Array.isArray(links))
+        return [];
+    return links.map((link) => {
+        if (typeof link === "string") {
+            return {
+                type: "relates_to",
+                from: fromId,
+                to: link,
+            };
+        }
+        const linkObj = link;
+        return {
+            type: linkObj.type || "relates_to",
+            from: fromId,
+            to: linkObj.target || linkObj.id || linkObj.to || "",
+        };
+    });
+}

package/dist/extractors/markdown.d.ts

@@ -0,0 +1,39 @@
+export interface ExtractedEntity {
+    id: string;
+    type: string;
+    title: string;
+    status: string;
+    created_at: string;
+    updated_at: string;
+    source: string;
+    tags?: string[];
+    owner?: string;
+    priority?: string;
+    severity?: string;
+    links?: unknown[];
+    text_ref?: string;
+}
+export interface ExtractedRelationship {
+    type: string;
+    from: string;
+    to: string;
+}
+export interface ExtractionResult {
+    entity: ExtractedEntity;
+    relationships: ExtractedRelationship[];
+}
+export declare class FrontmatterError extends Error {
+    filePath: string;
+    classification: string;
+    hint: string;
+    originalError?: string;
+    constructor(message: string, filePath: string, options?: {
+        classification?: string;
+        hint?: string;
+        originalError?: string;
+    });
+    toString(): string;
+}
+export declare function extractFromMarkdown(filePath: string): ExtractionResult;
+export declare function inferTypeFromPath(filePath: string): string | null;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/extractors/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"AAiDA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAOhC,QAAQ,EAAE,MAAM;IANlB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IASM,QAAQ;CAUlB;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAqHtE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASjE"}

package/dist/extractors/markdown.js

@@ -0,0 +1,203 @@
+/*
+ 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/>.
+*/
+/*
+ How to apply this header to source files (examples)
+
+ 1) Prepend header to a single file (POSIX shells):
+
+    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
+
+ 2) Apply to multiple files (example: the project's main entry files):
+
+    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
+      if [ -f "$f" ]; then
+        cp "$f" "$f".bak
+        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
+      fi
+    done
+
+ 3) Avoid duplicating the header: run a quick guard to only add if missing
+
+    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
+      if [ -f "$f" ]; then
+        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
+          cp "$f" "$f".bak
+          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
+        fi
+      fi
+    done
+*/
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import matter from "gray-matter";
+export class FrontmatterError extends Error {
+    filePath;
+    classification;
+    hint;
+    originalError;
+    constructor(message, filePath, options) {
+        super(message);
+        this.filePath = filePath;
+        this.name = "FrontmatterError";
+        this.classification = options?.classification || "Generic Error";
+        this.hint = options?.hint || "Check the file for syntax errors.";
+        this.originalError = options?.originalError;
+    }
+    toString() {
+        let msg = `${this.filePath}: [${this.classification}] ${this.message}`;
+        if (this.hint) {
+            msg += `\nHow to fix:\n- ${this.hint}`;
+        }
+        if (this.originalError) {
+            msg += `\n\nOriginal error: ${this.originalError}`;
+        }
+        return msg;
+    }
+}
+export function extractFromMarkdown(filePath) {
+    let content;
+    try {
+        content = readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        throw new FrontmatterError(`Failed to read file: ${error instanceof Error ? error.message : String(error)}`, filePath, { classification: "File Read Error" });
+    }
+    try {
+        const { data, content: body } = matter(content);
+        if (content.trim().startsWith("---")) {
+            const parts = content.split("---");
+            if (parts.length < 3) {
+                throw new FrontmatterError("Missing closing --- delimiter", filePath, {
+                    classification: "Missing closing ---",
+                    hint: "Ensure the frontmatter is enclosed between two '---' delimiters.",
+                });
+            }
+        }
+        const type = data.type || inferTypeFromPath(filePath);
+        if (!type) {
+            throw new FrontmatterError("Could not determine entity type from path or frontmatter", filePath, {
+                classification: "Missing Type",
+                hint: "Add 'type: <type>' to frontmatter or place file in a typed directory (e.g., /requirements/).",
+            });
+        }
+        if (!data.title) {
+            throw new FrontmatterError("Missing required field: title", filePath, {
+                classification: "Missing Field",
+                hint: "Add a 'title: ...' field to the YAML frontmatter.",
+            });
+        }
+        const id = data.id || generateId(filePath, data.title);
+        const relationships = extractRelationships(data.links || [], id);
+        return {
+            entity: {
+                id,
+                type,
+                title: data.title,
+                status: data.status || "draft",
+                created_at: data.created_at || new Date().toISOString(),
+                updated_at: data.updated_at || new Date().toISOString(),
+                source: filePath,
+                tags: data.tags,
+                owner: data.owner,
+                priority: data.priority,
+                severity: data.severity,
+                links: data.links,
+                text_ref: data.text_ref,
+            },
+            relationships,
+        };
+    }
+    catch (error) {
+        if (error instanceof FrontmatterError) {
+            throw error;
+        }
+        if (error instanceof Error) {
+            const message = error.message;
+            let classification = "Frontmatter YAML syntax error";
+            let hint = "Check the YAML syntax in your frontmatter.";
+            if (message.includes("incomplete explicit mapping pair") &&
+                message.includes(":")) {
+                classification = "Unquoted colon likely in title";
+                hint =
+                    'Wrap values containing colons in quotes (e.g., title: "Foo: Bar").';
+            }
+            else if (!content.trim().startsWith("---") ||
+                content.split("---").length < 3) {
+                if (content.trim().startsWith("---") &&
+                    content.split("---").length < 3) {
+                    classification = "Missing closing ---";
+                    hint =
+                        "Ensure the frontmatter is enclosed between two '---' delimiters.";
+                }
+            }
+            else if (message.includes("unexpected end of the stream") ||
+                message.includes("flow collection") ||
+                message.includes("end of the stream")) {
+                classification = "Generic YAML mapping error";
+                hint = "Check for unclosed brackets, braces, or quotes in your YAML.";
+            }
+            throw new FrontmatterError(`Failed to parse frontmatter: ${message}`, filePath, {
+                classification,
+                hint,
+                originalError: message,
+            });
+        }
+        throw error;
+    }
+}
+export function inferTypeFromPath(filePath) {
+    if (filePath.includes("/requirements/"))
+        return "req";
+    if (filePath.includes("/scenarios/"))
+        return "scenario";
+    if (filePath.includes("/tests/"))
+        return "test";
+    if (filePath.includes("/adr/"))
+        return "adr";
+    if (filePath.includes("/flags/"))
+        return "flag";
+    if (filePath.includes("/events/"))
+        return "event";
+    if (filePath.includes("/facts/"))
+        return "fact";
+    return null;
+}
+function generateId(filePath, title) {
+    const hash = createHash("sha256");
+    hash.update(`${filePath}:${title}`);
+    return hash.digest("hex").substring(0, 16);
+}
+function extractRelationships(links, fromId) {
+    if (!Array.isArray(links))
+        return [];
+    return links.map((link) => {
+        if (typeof link === "string") {
+            return {
+                type: "relates_to",
+                from: fromId,
+                to: link,
+            };
+        }
+        const linkObj = link;
+        return {
+            type: linkObj.type || "relates_to",
+            from: fromId,
+            to: linkObj.target || linkObj.id || linkObj.to || "",
+        };
+    });
+}

package/dist/extractors/symbols-coordinator.d.ts

@@ -0,0 +1,4 @@
+import { type ManifestSymbolEntry } from "./symbols-ts.js";
+export type { ManifestSymbolEntry };
+export declare function enrichSymbolCoordinates(entries: ManifestSymbolEntry[], workspaceRoot: string): Promise<ManifestSymbolEntry[]>;
+//# sourceMappingURL=symbols-coordinator.d.ts.map

package/dist/extractors/symbols-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbols-coordinator.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-coordinator.ts"],"names":[],"mappings":"AA+CA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,iBAAiB,CAAC;AAazB,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAmChC"}

package/dist/extractors/symbols-coordinator.js

@@ -0,0 +1,131 @@
+/*
+ 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/>.
+*/
+/*
+ How to apply this header to source files (examples)
+
+ 1) Prepend header to a single file (POSIX shells):
+
+    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
+
+ 2) Apply to multiple files (example: the project's main entry files):
+
+    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
+      if [ -f "$f" ]; then
+        cp "$f" "$f".bak
+        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
+      fi
+    done
+
+ 3) Avoid duplicating the header: run a quick guard to only add if missing
+
+    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
+      if [ -f "$f" ]; then
+        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
+          cp "$f" "$f".bak
+          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
+        fi
+      fi
+    done
+*/
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { enrichSymbolCoordinatesWithTsMorph, } from "./symbols-ts.js";
+const TS_JS_EXTENSIONS = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mts",
+    ".cts",
+    ".mjs",
+    ".cjs",
+]);
+export async function enrichSymbolCoordinates(entries, workspaceRoot) {
+    const output = entries.map((entry) => ({ ...entry }));
+    const tsIndices = [];
+    const tsEntries = [];
+    for (let index = 0; index < output.length; index++) {
+        const entry = output[index];
+        const resolved = resolveSourcePath(entry.sourceFile, workspaceRoot);
+        if (!resolved)
+            continue;
+        const ext = path.extname(resolved.absolutePath).toLowerCase();
+        if (TS_JS_EXTENSIONS.has(ext)) {
+            tsIndices.push(index);
+            tsEntries.push(entry);
+            continue;
+        }
+        output[index] = enrichWithRegexHeuristic(entry, resolved.absolutePath);
+    }
+    if (tsEntries.length > 0) {
+        const enrichedTs = await enrichSymbolCoordinatesWithTsMorph(tsEntries, workspaceRoot);
+        for (let i = 0; i < tsIndices.length; i++) {
+            const target = tsIndices[i];
+            const enriched = enrichedTs[i];
+            if (target === undefined || !enriched)
+                continue;
+            output[target] = enriched;
+        }
+    }
+    return output;
+}
+function enrichWithRegexHeuristic(entry, absolutePath) {
+    try {
+        const content = fs.readFileSync(absolutePath, "utf8");
+        const escaped = escapeRegex(entry.title);
+        const pattern = new RegExp(`\\b${escaped}\\b`);
+        const lines = content.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i] ?? "";
+            const match = pattern.exec(line);
+            if (!match)
+                continue;
+            const sourceLine = i + 1;
+            const sourceColumn = match.index;
+            const sourceEndLine = sourceLine;
+            const sourceEndColumn = sourceColumn + entry.title.length;
+            return {
+                ...entry,
+                sourceLine,
+                sourceColumn,
+                sourceEndLine,
+                sourceEndColumn,
+                coordinatesGeneratedAt: new Date().toISOString(),
+            };
+        }
+        return entry;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[kibi] Failed regex coordinate heuristic for ${entry.id}: ${message}`);
+        return entry;
+    }
+}
+function resolveSourcePath(sourceFile, workspaceRoot) {
+    if (!sourceFile)
+        return null;
+    const absolutePath = path.isAbsolute(sourceFile)
+        ? sourceFile
+        : path.resolve(workspaceRoot, sourceFile);
+    if (!fs.existsSync(absolutePath))
+        return null;
+    return { absolutePath };
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/extractors/symbols-ts.d.ts

@@ -0,0 +1,21 @@
+export interface SymbolCoordinates {
+    sourceLine: number;
+    sourceColumn: number;
+    sourceEndLine: number;
+    sourceEndColumn: number;
+    coordinatesGeneratedAt: string;
+}
+export interface ManifestSymbolEntry {
+    id: string;
+    title: string;
+    sourceFile?: string;
+    sourceLine?: number;
+    sourceColumn?: number;
+    sourceEndLine?: number;
+    sourceEndColumn?: number;
+    coordinatesGeneratedAt?: string;
+    links?: string[];
+    [key: string]: unknown;
+}
+export declare function enrichSymbolCoordinatesWithTsMorph(entries: ManifestSymbolEntry[], workspaceRoot: string): Promise<ManifestSymbolEntry[]>;
+//# sourceMappingURL=symbols-ts.d.ts.map

package/dist/extractors/symbols-ts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbols-ts.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-ts.ts"],"names":[],"mappings":"AAuDA,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAaD,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAwDhC"}