kibi-cli 0.2.8 → 0.3.0

package/dist/cli.js

@@ -19,10 +19,15 @@ import { readFileSync } from "node:fs";
 import { Command } from "commander";
 import { branchEnsureCommand } from "./commands/branch.js";
 import { checkCommand } from "./commands/check.js";
+import { coverageCommand } from "./commands/coverage.js";
 import { doctorCommand } from "./commands/doctor.js";
+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 { queryCommand } from "./commands/query.js";
+import { searchCommand } from "./commands/search.js";
+import { statusCommand } from "./commands/status.js";
 import { syncCommand } from "./commands/sync.js";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const VERSION = packageJson.version ?? "0.1.0";
@@ -59,6 +64,63 @@ program
     .action(async (type, options) => {
     await queryCommand(type, options);
 });
+program
+    .command("search [query]")
+    .description("Search knowledge base metadata and markdown content")
+    .option("--type <type>", "Filter by entity type")
+    .option("--format <format>", "Output format: json|table", "table")
+    .option("--limit <n>", "Limit results", "20")
+    .option("--offset <n>", "Skip results", "0")
+    .action(async (query, options) => {
+    await searchCommand(query, options);
+});
+program
+    .command("status")
+    .description("Show KB snapshot and freshness metadata")
+    .option("--format <format>", "Output format: json|table", "table")
+    .action(async (options) => {
+    await statusCommand(options);
+});
+program
+    .command("gaps [type]")
+    .description("Find entities missing or present on selected relationships")
+    .option("--missing-rel <rels>", "Comma-separated missing relationship filters")
+    .option("--present-rel <rels>", "Comma-separated present relationship filters")
+    .option("--tag <tags>", "Comma-separated tag filter")
+    .option("--source <path>", "Source file substring filter")
+    .option("--limit <n>", "Limit results", "100")
+    .option("--offset <n>", "Skip results", "0")
+    .option("--format <format>", "Output format: json|table", "table")
+    .action(async (type, options) => {
+    await gapsCommand(type, options);
+});
+program
+    .command("coverage")
+    .description("Generate curated coverage reports")
+    .option("--by <group>", "Coverage mode: req|symbol|type", "req")
+    .option("--tag <tags>", "Comma-separated tag filter")
+    .option("--include-passing", "Include passing rows", false)
+    .option("--no-include-transitive", "Disable transitive symbol coverage")
+    .option("--limit <n>", "Limit results", "100")
+    .option("--offset <n>", "Skip results", "0")
+    .option("--format <format>", "Output format: json|table", "table")
+    .action(async (options) => {
+    await coverageCommand(options);
+});
+program
+    .command("graph")
+    .description("Traverse the KB graph from one or more seed IDs")
+    .option("--from <ids>", "Comma-separated seed IDs")
+    .option("--relationships <rels>", "Comma-separated relationship filter")
+    .option("--direction <direction>", "Direction: outgoing|incoming|both", "outgoing")
+    .option("--depth <n>", "Traversal depth", "1")
+    .option("--entity-types <types>", "Comma-separated entity type filter")
+    .option("--max-nodes <n>", "Maximum node count", "200")
+    .option("--max-edges <n>", "Maximum edge count", "500")
+    .option("--format <format>", "Output format: json|table", "table")
+    .action(async (options) => {
+    await graphCommand(options);
+});
 program
     .command("check")
     .description("Check KB consistency and integrity")

package/dist/commands/coverage.d.ts

@@ -0,0 +1,12 @@
+interface CoverageOptions {
+    by?: "req" | "symbol" | "type";
+    tag?: string;
+    includePassing?: boolean;
+    includeTransitive?: boolean;
+    limit?: string;
+    offset?: string;
+    format?: "json" | "table";
+}
+export declare function coverageCommand(options: CoverageOptions): Promise<void>;
+export {};
+//# sourceMappingURL=coverage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/commands/coverage.ts"],"names":[],"mappings":"AAQA,UAAU,eAAe;IACvB,EAAE,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC7E"}

package/dist/commands/coverage.js

@@ -0,0 +1,24 @@
+import { escapeAtom } from "../prolog/codec.js";
+import { printDiscoveryResult, resolveCurrentKbPath, runJsonModuleQuery, withPrologProcess, } from "./discovery-shared.js";
+// implements REQ-002, REQ-003
+export async function coverageCommand(options) {
+    await withPrologProcess(async (prolog) => {
+        const kbPath = await resolveCurrentKbPath();
+        const by = options.by || "req";
+        const tags = options.tag
+            ? `[${options.tag
+                .split(",")
+                .map((item) => item.trim())
+                .filter(Boolean)
+                .map((item) => `'${escapeAtom(item)}'`)
+                .join(",")}]`
+            : "[]";
+        const includePassing = options.includePassing ?? false;
+        const includeTransitive = options.includeTransitive ?? true;
+        const limit = Number.parseInt(options.limit || "100", 10);
+        const offset = Number.parseInt(options.offset || "0", 10);
+        const result = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:coverage_report_json('${by}', ${tags}, ${includePassing}, ${includeTransitive}, ${limit}, ${offset}, JsonString)`, "coverage query failed", kbPath);
+        const summary = (result.summary ?? {});
+        printDiscoveryResult(options.format, result, `Coverage summary: ${summary.fullyCovered ?? 0} fully covered out of ${summary.total ?? 0}.`);
+    });
+}

package/dist/commands/discovery-shared.d.ts

@@ -0,0 +1,11 @@
+import { PrologProcess } from "../prolog.js";
+export interface DiscoveryCommandOptions {
+    format?: "json" | "table";
+}
+export declare function withAttachedBranchProlog<T>(callback: (prolog: PrologProcess) => Promise<T>): Promise<T>;
+export declare function withPrologProcess<T>(callback: (prolog: PrologProcess) => Promise<T>): Promise<T>;
+export declare function resolveCurrentKbPath(): Promise<string>;
+export declare function resolveCoreModulePath(fileName: string): string;
+export declare function runJsonModuleQuery<T>(prolog: PrologProcess, fileName: string, goal: string, errorLabel: string, kbPath?: string): Promise<T>;
+export declare function printDiscoveryResult(format: "json" | "table" | undefined, structured: unknown, fallbackText: string): void;
+//# sourceMappingURL=discovery-shared.d.ts.map

package/dist/commands/discovery-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery-shared.d.ts","sourceRoot":"","sources":["../../src/commands/discovery-shared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAmB,MAAM,cAAc,CAAC;AAI9D,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAsCZ;AAGD,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAcZ;AAGD,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAS5D;AAGD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9D;AAGD,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAQN"}

package/dist/commands/discovery-shared.js

@@ -0,0 +1,280 @@
+import path from "node:path";
+import Table from "cli-table3";
+import { PrologProcess, resolveKbPlPath } from "../prolog.js";
+import { escapeAtom } from "../prolog/codec.js";
+import { getCurrentBranch } from "./init-helpers.js";
+// implements REQ-003
+export async function withAttachedBranchProlog(callback) {
+    let prolog = null;
+    let attached = false;
+    try {
+        prolog = new PrologProcess({ timeout: 120000 });
+        await prolog.start();
+        await prolog.query("set_prolog_flag(answer_write_options, [max_depth(0), spacing(next_argument)])");
+        let branch;
+        try {
+            branch = process.env.KIBI_BRANCH || (await getCurrentBranch(process.cwd()));
+        }
+        catch {
+            branch = process.env.KIBI_BRANCH || "main";
+        }
+        const kbPath = path.join(process.cwd(), ".kb/branches", branch);
+        const attachResult = await prolog.query(`kb_attach('${escapeAtom(kbPath)}')`);
+        if (!attachResult.success) {
+            throw new Error(`Failed to attach KB: ${attachResult.error || "Unknown error"}`);
+        }
+        attached = true;
+        return await callback(prolog);
+    }
+    finally {
+        if (prolog) {
+            if (attached) {
+                try {
+                    await prolog.query("kb_detach");
+                }
+                catch { }
+            }
+            try {
+                await prolog.terminate();
+            }
+            catch { }
+        }
+    }
+}
+// implements REQ-003
+export async function withPrologProcess(callback) {
+    const prolog = new PrologProcess({ timeout: 120000 });
+    try {
+        await prolog.start();
+        ;
+        prolog.useOneShotMode = true;
+        await prolog.query("set_prolog_flag(answer_write_options, [max_depth(0), spacing(next_argument)])");
+        return await callback(prolog);
+    }
+    finally {
+        try {
+            await prolog.terminate();
+        }
+        catch { }
+    }
+}
+// implements REQ-003
+export async function resolveCurrentKbPath() {
+    let branch;
+    try {
+        branch = process.env.KIBI_BRANCH || (await getCurrentBranch(process.cwd()));
+    }
+    catch {
+        branch = process.env.KIBI_BRANCH || "main";
+    }
+    return path.join(process.cwd(), ".kb/branches", branch);
+}
+// implements REQ-003
+export function resolveCoreModulePath(fileName) {
+    return path.join(path.dirname(resolveKbPlPath()), fileName);
+}
+// implements REQ-003
+export async function runJsonModuleQuery(prolog, fileName, goal, errorLabel, kbPath) {
+    const modulePath = escapeAtom(resolveCoreModulePath(fileName).replace(/\\/g, "/"));
+    const wrappedGoal = kbPath
+        ? `(use_module('${modulePath}'), kb_attach('${escapeAtom(kbPath)}'), ${goal}, kb_detach)`
+        : `(use_module('${modulePath}'), ${goal})`;
+    const result = await prolog.query(wrappedGoal);
+    if (!result.success) {
+        throw new Error(`${errorLabel}: ${result.error || "Unknown error"}`);
+    }
+    const rawJson = result.bindings.JsonString;
+    if (!rawJson) {
+        throw new Error(`${errorLabel}: missing JsonString binding`);
+    }
+    let parsed = JSON.parse(rawJson);
+    if (typeof parsed === "string") {
+        parsed = JSON.parse(parsed);
+    }
+    return parsed;
+}
+// implements REQ-003
+export function printDiscoveryResult(format, structured, fallbackText) {
+    if (format === "json") {
+        console.log(JSON.stringify(structured, null, 2));
+        return;
+    }
+    const rendered = renderDiscoveryTable(structured);
+    console.log(rendered || fallbackText);
+}
+function renderDiscoveryTable(structured) {
+    if (!structured || typeof structured !== "object") {
+        return null;
+    }
+    const payload = structured;
+    if (Array.isArray(payload.results)) {
+        return renderSearchTable(payload);
+    }
+    if (typeof payload.branch === "string" && typeof payload.syncState === "string") {
+        return renderStatusTable(payload);
+    }
+    if (Array.isArray(payload.nodes) && Array.isArray(payload.edges)) {
+        return renderGraphTable(payload);
+    }
+    if (Array.isArray(payload.rows) && payload.summary && typeof payload.summary === "object") {
+        return renderCoverageTable(payload);
+    }
+    if (Array.isArray(payload.rows)) {
+        return renderGapsTable(payload);
+    }
+    return null;
+}
+function renderSearchTable(payload) {
+    const rows = Array.isArray(payload.results) ? payload.results : [];
+    const table = new Table({
+        head: ["ID", "Type", "Title", "Score", "Reasons", "Snippet"],
+        wordWrap: true,
+        colWidths: [20, 10, 32, 8, 28, 44],
+    });
+    for (const row of rows) {
+        const match = row;
+        const entity = (match.entity ?? {});
+        const reasons = Array.isArray(match.reasons) ? match.reasons.join(", ") : "";
+        table.push([
+            stringifyCell(entity.id),
+            stringifyCell(entity.type),
+            stringifyCell(entity.title),
+            stringifyCell(match.score),
+            reasons,
+            stringifyCell(match.snippet),
+        ]);
+    }
+    return [
+        `Search results: ${stringifyCell(payload.count)} total`,
+        table.toString(),
+    ].join("\n");
+}
+function renderStatusTable(payload) {
+    const table = new Table({
+        head: ["Field", "Value"],
+        colWidths: [18, 72],
+        wordWrap: true,
+    });
+    table.push(["Branch", stringifyCell(payload.branch)], ["Sync State", stringifyCell(payload.syncState)], ["Dirty", stringifyCell(payload.dirty)], ["Snapshot", stringifyCell(payload.snapshotId)], ["Synced At", stringifyCell(payload.syncedAt)], ["KB Path", stringifyCell(payload.kbPath)]);
+    return table.toString();
+}
+function renderGapsTable(payload) {
+    const rows = Array.isArray(payload.rows) ? payload.rows : [];
+    const table = new Table({
+        head: ["ID", "Type", "Status", "Missing", "Present", "Source"],
+        colWidths: [20, 10, 12, 24, 24, 40],
+        wordWrap: true,
+    });
+    for (const row of rows) {
+        const item = row;
+        table.push([
+            stringifyCell(item.id),
+            stringifyCell(item.type),
+            stringifyCell(item.status),
+            joinCells(item.missingRelationships),
+            joinCells(item.presentRelationships),
+            stringifyCell(item.source),
+        ]);
+    }
+    return [`Gap rows: ${stringifyCell(payload.count)}`, table.toString()].join("\n");
+}
+function renderCoverageTable(payload) {
+    const summary = (payload.summary ?? {});
+    const rows = Array.isArray(payload.rows) ? payload.rows : [];
+    const summaryTable = new Table({
+        head: ["Metric", "Value"],
+        colWidths: [24, 16],
+    });
+    for (const [key, value] of Object.entries(summary)) {
+        summaryTable.push([key, stringifyCell(value)]);
+    }
+    const firstRow = rows[0];
+    const isRequirementCoverage = firstRow && Object.hasOwn(firstRow, "scenarioCount");
+    const table = isRequirementCoverage
+        ? new Table({
+            head: ["ID", "Status", "Priority", "Coverage", "Scen", "Tests", "Symbols", "Gaps"],
+            colWidths: [20, 12, 12, 18, 8, 8, 10, 28],
+            wordWrap: true,
+        })
+        : new Table({
+            head: ["ID", "Type", "Coverage", "Details", "Gaps"],
+            colWidths: [20, 10, 18, 28, 28],
+            wordWrap: true,
+        });
+    for (const row of rows) {
+        const item = row;
+        if (isRequirementCoverage) {
+            table.push([
+                stringifyCell(item.id),
+                stringifyCell(item.status),
+                stringifyCell(item.priority),
+                stringifyCell(item.coverageStatus),
+                stringifyCell(item.scenarioCount),
+                stringifyCell(item.testCount),
+                stringifyCell(item.transitiveSymbolCount),
+                joinCells(item.gaps),
+            ]);
+        }
+        else {
+            table.push([
+                stringifyCell(item.id),
+                stringifyCell(item.type),
+                stringifyCell(item.coverageStatus),
+                `req=${stringifyCell(item.directRequirementCount)} test=${stringifyCell(item.testCount)} count=${stringifyCell(item.count)}`,
+                joinCells(item.gaps),
+            ]);
+        }
+    }
+    return [summaryTable.toString(), table.toString()].join("\n\n");
+}
+function renderGraphTable(payload) {
+    const nodes = Array.isArray(payload.nodes) ? payload.nodes : [];
+    const edges = Array.isArray(payload.edges) ? payload.edges : [];
+    const nodeTable = new Table({
+        head: ["Node ID", "Type", "Title", "Status"],
+        colWidths: [22, 10, 36, 12],
+        wordWrap: true,
+    });
+    for (const row of nodes) {
+        const item = row;
+        nodeTable.push([
+            stringifyCell(item.id),
+            stringifyCell(item.type),
+            stringifyCell(item.title),
+            stringifyCell(item.status),
+        ]);
+    }
+    const edgeTable = new Table({
+        head: ["Relationship", "From", "To"],
+        colWidths: [18, 22, 22],
+        wordWrap: true,
+    });
+    for (const row of edges) {
+        const item = row;
+        edgeTable.push([
+            stringifyCell(item.type),
+            stringifyCell(item.from),
+            stringifyCell(item.to),
+        ]);
+    }
+    return [
+        `Nodes: ${nodes.length}  Edges: ${edges.length}  Truncated: ${stringifyCell(payload.truncated)}`,
+        nodeTable.toString(),
+        edgeTable.toString(),
+    ].join("\n\n");
+}
+function stringifyCell(value) {
+    if (value === null || value === undefined || value === "") {
+        return "-";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    return String(value);
+}
+function joinCells(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        return "-";
+    }
+    return value.map((item) => stringifyCell(item)).join(", ");
+}

package/dist/commands/doctor.js

@@ -198,7 +198,7 @@ function checkGitHooks() {
     return {
         passed: false,
         message: "Partially installed",
-        remediation: "Run: kibi init --hooks",
+        remediation: "Run: kibi init",
     };
 }
 function checkPreCommitHook() {
@@ -218,7 +218,7 @@ function checkPreCommitHook() {
         return {
             passed: false,
             message: "Not installed",
-            remediation: "Run: kibi init --hooks",
+            remediation: "Run: kibi init",
         };
     }
     try {
@@ -233,7 +233,7 @@ function checkPreCommitHook() {
             return {
                 passed: false,
                 message: "pre-commit hook installed but does not invoke kibi",
-                remediation: "Run: kibi init --hooks to install recommended hooks",
+                remediation: "Run: kibi init to install recommended hooks",
             };
         }
         if (preCommitExecutable) {
@@ -247,7 +247,7 @@ function checkPreCommitHook() {
             return {
                 passed: true,
                 message: "Installed and executable (uses legacy 'kibi check' — consider running 'kibi init' to update hooks to use '--staged')",
-                remediation: "Run: kibi init --hooks to update git hooks to the latest template",
+                remediation: "Run: kibi init to update git hooks to the latest template",
             };
         }
         return {
@@ -260,7 +260,7 @@ function checkPreCommitHook() {
         return {
             passed: false,
             message: "Unable to check hook permissions or read content",
-            remediation: "Run: kibi init --hooks",
+            remediation: "Run: kibi init",
         };
     }
 }
@@ -281,7 +281,7 @@ function checkPostRewriteHook() {
         return {
             passed: false,
             message: "Not installed",
-            remediation: "Run: kibi init --hooks",
+            remediation: "Run: kibi init",
         };
     }
     try {
@@ -294,7 +294,7 @@ function checkPostRewriteHook() {
             return {
                 passed: false,
                 message: "post-rewrite hook installed but does not invoke kibi",
-                remediation: "Run: kibi init --hooks to install recommended hooks",
+                remediation: "Run: kibi init to install recommended hooks",
             };
         }
         if (postRewriteExecutable) {
@@ -313,7 +313,7 @@ function checkPostRewriteHook() {
         return {
             passed: false,
             message: "Unable to check hook permissions or read content",
-            remediation: "Run: kibi init --hooks",
+            remediation: "Run: kibi init",
         };
     }
 }

package/dist/commands/gaps.d.ts

@@ -0,0 +1,12 @@
+interface GapsOptions {
+    missingRel?: string;
+    presentRel?: string;
+    tag?: string;
+    source?: string;
+    limit?: string;
+    offset?: string;
+    format?: "json" | "table";
+}
+export declare function gapsCommand(type: string | undefined, options: GapsOptions): Promise<void>;
+export {};
+//# sourceMappingURL=gaps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gaps.d.ts","sourceRoot":"","sources":["../../src/commands/gaps.ts"],"names":[],"mappings":"AAQA,UAAU,WAAW;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAyBf"}

package/dist/commands/gaps.js

@@ -0,0 +1,28 @@
+import { escapeAtom } from "../prolog/codec.js";
+import { printDiscoveryResult, resolveCurrentKbPath, runJsonModuleQuery, withPrologProcess, } from "./discovery-shared.js";
+// implements REQ-002, REQ-003
+export async function gapsCommand(type, options) {
+    await withPrologProcess(async (prolog) => {
+        const kbPath = await resolveCurrentKbPath();
+        const missing = csvToPrologList(options.missingRel);
+        const present = csvToPrologList(options.presentRel);
+        const tags = csvToPrologList(options.tag);
+        const source = options.source ? `'${escapeAtom(options.source)}'` : "none";
+        const limit = Number.parseInt(options.limit || "100", 10);
+        const offset = Number.parseInt(options.offset || "0", 10);
+        const typeArg = type ? `'${escapeAtom(type)}'` : "none";
+        const result = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:find_gaps_json(${typeArg}, ${missing}, ${present}, ${tags}, ${source}, ${limit}, ${offset}, JsonString)`, "gaps query failed", kbPath);
+        printDiscoveryResult(options.format, result, `Found ${result.count ?? 0} gap rows.`);
+    });
+}
+function csvToPrologList(value) {
+    if (!value?.trim()) {
+        return "[]";
+    }
+    return `[${value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .map((item) => `'${escapeAtom(item)}'`)
+        .join(",")}]`;
+}

package/dist/commands/graph.d.ts

@@ -0,0 +1,13 @@
+interface GraphOptions {
+    from?: string;
+    relationships?: string;
+    direction?: "outgoing" | "incoming" | "both";
+    depth?: string;
+    entityTypes?: string;
+    maxNodes?: string;
+    maxEdges?: string;
+    format?: "json" | "table";
+}
+export declare function graphCommand(options: GraphOptions): Promise<void>;
+export {};
+//# sourceMappingURL=graph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/commands/graph.ts"],"names":[],"mappings":"AAQA,UAAU,YAAY;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCvE"}

package/dist/commands/graph.js

@@ -0,0 +1,35 @@
+import { escapeAtom } from "../prolog/codec.js";
+import { printDiscoveryResult, resolveCurrentKbPath, runJsonModuleQuery, withPrologProcess, } from "./discovery-shared.js";
+// implements REQ-002, REQ-003
+export async function graphCommand(options) {
+    if (!options.from?.trim()) {
+        console.error("Error: --from is required");
+        process.exitCode = 1;
+        return;
+    }
+    await withPrologProcess(async (prolog) => {
+        const kbPath = await resolveCurrentKbPath();
+        const seedIds = csvToPrologList(options.from);
+        const relationships = csvToPrologList(options.relationships);
+        const direction = options.direction || "outgoing";
+        const depth = Number.parseInt(options.depth || "1", 10);
+        const entityTypes = csvToPrologList(options.entityTypes);
+        const maxNodes = Number.parseInt(options.maxNodes || "200", 10);
+        const maxEdges = Number.parseInt(options.maxEdges || "500", 10);
+        const result = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:graph_expand_json(${seedIds}, ${relationships}, '${direction}', ${depth}, ${entityTypes}, ${maxNodes}, ${maxEdges}, JsonString)`, "graph query failed", kbPath);
+        const nodes = Array.isArray(result.nodes) ? result.nodes.length : 0;
+        const edges = Array.isArray(result.edges) ? result.edges.length : 0;
+        printDiscoveryResult(options.format, result, `Graph traversal returned ${nodes} nodes and ${edges} edges.`);
+    });
+}
+function csvToPrologList(value) {
+    if (!value?.trim()) {
+        return "[]";
+    }
+    return `[${value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .map((item) => `'${escapeAtom(item)}'`)
+        .join(",")}]`;
+}

package/dist/commands/search.d.ts

@@ -0,0 +1,9 @@
+interface SearchOptions {
+    type?: string;
+    format?: "json" | "table";
+    limit?: string;
+    offset?: string;
+}
+export declare function searchCommand(query: string | undefined, options: SearchOptions): Promise<void>;
+export {};
+//# sourceMappingURL=search.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/commands/search.ts"],"names":[],"mappings":"AAYA,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAGD,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/commands/search.js

@@ -0,0 +1,38 @@
+import { rankEntities } from "../search-ranking.js";
+import { VALID_ENTITY_TYPES, queryEntities, } from "../query/service.js";
+import { printDiscoveryResult, withAttachedBranchProlog, } from "./discovery-shared.js";
+// implements REQ-mcp-search-discovery, REQ-003
+export async function searchCommand(query, options) {
+    if (!query?.trim()) {
+        console.error("Error: search query is required");
+        process.exitCode = 1;
+        return;
+    }
+    if (options.type && !VALID_ENTITY_TYPES.includes(options.type)) {
+        console.error(`Error: invalid type '${options.type}'. Valid types: ${VALID_ENTITY_TYPES.join(", ")}`);
+        process.exitCode = 1;
+        return;
+    }
+    await withAttachedBranchProlog(async (prolog) => {
+        const limit = Number.parseInt(options.limit || "20", 10);
+        const offset = Number.parseInt(options.offset || "0", 10);
+        const result = await executeSearch(prolog, query, options.type, limit, offset);
+        printDiscoveryResult(options.format, result, buildSearchText(query, result));
+    });
+}
+async function executeSearch(prolog, query, type, limit, offset) {
+    const entitiesResult = await queryEntities(prolog, {
+        type,
+        limit: 100000,
+        offset: 0,
+    });
+    const matches = await rankEntities(entitiesResult.entities, query, process.cwd());
+    const paginated = matches.slice(offset, offset + limit);
+    return { results: paginated, count: matches.length };
+}
+function buildSearchText(query, result) {
+    if (result.count === 0) {
+        return `No search results for '${query}'.`;
+    }
+    return `Found ${result.count} search results for '${query}'. Showing ${result.results.length}: ${result.results.map((match) => match.entity.id).join(", ")}`;
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,6 @@
+interface StatusOptions {
+    format?: "json" | "table";
+}
+export declare function statusCommand(options: StatusOptions): Promise<void>;
+export {};
+//# sourceMappingURL=status.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAOA,UAAU,aAAa;IACrB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBzE"}

package/dist/commands/status.js

@@ -0,0 +1,9 @@
+import { printDiscoveryResult, resolveCurrentKbPath, runJsonModuleQuery, withPrologProcess, } from "./discovery-shared.js";
+// implements REQ-002, REQ-003
+export async function statusCommand(options) {
+    await withPrologProcess(async (prolog) => {
+        const kbPath = await resolveCurrentKbPath();
+        const result = await runJsonModuleQuery(prolog, "status.pl", "status:kb_status_json(JsonString)", "status query failed", kbPath);
+        printDiscoveryResult(options.format, result, `Branch ${result.branch} is ${result.syncState} (dirty=${result.dirty})`);
+    });
+}

package/dist/search-ranking.d.ts

@@ -0,0 +1,9 @@
+export interface SearchMatch {
+    entity: Record<string, unknown>;
+    score: number;
+    reasons: string[];
+    snippet?: string;
+}
+export declare function rankEntities(entities: Record<string, unknown>[], query: string, workspaceRoot: string): Promise<SearchMatch[]>;
+export declare function loadMarkdownBody(source: string, workspaceRoot: string): Promise<string | null>;
+//# sourceMappingURL=search-ranking.d.ts.map

package/dist/search-ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-ranking.d.ts","sourceRoot":"","sources":["../src/search-ranking.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAGD,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACnC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,EAAE,CAAC,CAuBxB;AA2FD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA2BxB"}

package/dist/search-ranking.js

@@ -0,0 +1,143 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import matter from "gray-matter";
+// implements REQ-mcp-search-discovery, REQ-002, REQ-003
+export async function rankEntities(entities, query, workspaceRoot) {
+    const matches = [];
+    for (const entity of entities) {
+        const match = await rankEntity(entity, query, workspaceRoot);
+        if (match) {
+            matches.push(match);
+        }
+    }
+    matches.sort((left, right) => {
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        const leftType = String(left.entity.type ?? "");
+        const rightType = String(right.entity.type ?? "");
+        if (leftType !== rightType) {
+            return leftType.localeCompare(rightType);
+        }
+        return String(left.entity.id ?? "").localeCompare(String(right.entity.id ?? ""));
+    });
+    return matches;
+}
+async function rankEntity(entity, query, workspaceRoot) {
+    const normalizedQuery = normalize(query);
+    const tokens = normalizedQuery.split(/\s+/).filter(Boolean);
+    const reasons = [];
+    let score = 0;
+    const id = String(entity.id ?? "");
+    const title = String(entity.title ?? "");
+    const type = String(entity.type ?? "");
+    const source = String(entity.source ?? "");
+    const owner = String(entity.owner ?? "");
+    const priority = String(entity.priority ?? "");
+    const severity = String(entity.severity ?? "");
+    const tags = Array.isArray(entity.tags)
+        ? entity.tags.map((tag) => String(tag))
+        : [];
+    const normalizedTitle = normalize(title);
+    const normalizedId = normalize(id);
+    if (normalizedTitle === normalizedQuery) {
+        score += 100;
+        reasons.push("exact title match");
+    }
+    else if (normalizedTitle.includes(normalizedQuery)) {
+        score += 60;
+        reasons.push("title phrase match");
+    }
+    if (normalizedId === normalizedQuery) {
+        score += 90;
+        reasons.push("exact ID match");
+    }
+    else if (normalizedId.includes(normalizedQuery)) {
+        score += 55;
+        reasons.push("ID match");
+    }
+    const metadataFields = [type, source, owner, priority, severity];
+    const metadataMatched = metadataFields.some((field) => normalize(field).includes(normalizedQuery));
+    if (metadataMatched) {
+        score += 20;
+        reasons.push("metadata match");
+    }
+    const matchingTags = tags.filter((tag) => normalize(tag).includes(normalizedQuery));
+    if (matchingTags.length > 0) {
+        score += 30;
+        reasons.push("tag match");
+    }
+    const titleTokenMatches = countTokenMatches(normalizedTitle, tokens);
+    if (titleTokenMatches > 0) {
+        score += titleTokenMatches * 8;
+        reasons.push("title token coverage");
+    }
+    const bodyText = await loadMarkdownBody(source, workspaceRoot);
+    let snippet;
+    if (bodyText) {
+        const normalizedBody = normalize(bodyText);
+        if (normalizedBody.includes(normalizedQuery)) {
+            score += 15;
+            reasons.push("markdown body match");
+            snippet = buildSnippet(bodyText, query);
+        }
+        else {
+            const bodyTokenMatches = countTokenMatches(normalizedBody, tokens);
+            if (bodyTokenMatches > 0) {
+                score += bodyTokenMatches * 3;
+                reasons.push("markdown body token coverage");
+                snippet = buildSnippet(bodyText, query);
+            }
+        }
+    }
+    if (score === 0) {
+        return null;
+    }
+    return {
+        entity,
+        score,
+        reasons: Array.from(new Set(reasons)),
+        snippet,
+    };
+}
+export async function loadMarkdownBody(source, workspaceRoot) {
+    if (!source) {
+        return null;
+    }
+    const normalizedSource = source.split("#", 1)[0]?.trim() ?? "";
+    if (!normalizedSource.endsWith(".md")) {
+        return null;
+    }
+    // Resolve to absolute path; relative paths are resolved against workspaceRoot.
+    const resolved = path.resolve(path.isAbsolute(normalizedSource) ? normalizedSource : path.join(workspaceRoot, normalizedSource));
+    // Reject paths that escape the workspace root to prevent path traversal.
+    const normalizedRoot = path.resolve(workspaceRoot);
+    if (!resolved.startsWith(normalizedRoot + path.sep)) {
+        return null;
+    }
+    try {
+        const fileContent = await fs.readFile(resolved, "utf8");
+        return matter(fileContent).content;
+    }
+    catch {
+        return null;
+    }
+}
+function normalize(value) {
+    return value.trim().toLowerCase();
+}
+function countTokenMatches(haystack, tokens) {
+    return tokens.filter((token) => haystack.includes(token)).length;
+}
+function buildSnippet(bodyText, query) {
+    const lines = bodyText
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const normalizedQuery = normalize(query);
+    const matchedLine = lines.find((line) => normalize(line).includes(normalizedQuery)) ?? lines[0];
+    if (!matchedLine) {
+        return undefined;
+    }
+    return matchedLine.length > 160 ? `${matchedLine.slice(0, 157)}...` : matchedLine;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -58,6 +58,10 @@
     "./diagnostics": {
       "types": "./dist/diagnostics.d.ts",
       "default": "./dist/diagnostics.js"
+    },
+    "./search-ranking": {
+      "types": "./dist/search-ranking.d.ts",
+      "default": "./dist/search-ranking.js"
     }
   },
   "types": "./dist/cli.d.ts",
@@ -68,7 +72,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.1.10",
+    "kibi-core": "^0.2.0",
     "ts-morph": "^23.0.0"
   },
   "devDependencies": {