kibi-cli 0.14.0 → 0.17.0

package/dist/cli-validate.d.ts

@@ -0,0 +1,18 @@
+export type DiagnosticTelemetry = Readonly<Record<string, unknown>>;
+export type ValidationResult = {
+    readonly valid: true;
+} | {
+    readonly valid: false;
+    readonly errors: readonly string[];
+};
+export type PreparedInputResult = {
+    readonly valid: true;
+    readonly businessInput: Readonly<Record<string, unknown>>;
+    readonly telemetry?: DiagnosticTelemetry;
+} | {
+    readonly valid: false;
+    readonly errors: readonly string[];
+};
+export declare function prepareOperationInput(input: unknown, schema: object): PreparedInputResult;
+export declare function validateAgainstSchema(input: unknown, schema: object): ValidationResult;
+//# sourceMappingURL=cli-validate.d.ts.map

package/dist/cli-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-validate.d.ts","sourceRoot":"","sources":["../src/cli-validate.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAGpE,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAGlE,MAAM,MAAM,mBAAmB,GAC3B;IACE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;CAC1C,GACD;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAiBlE,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,GACb,mBAAmB,CAgCrB;AAGD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,GACb,gBAAgB,CAKlB"}

package/dist/cli-validate.js

@@ -0,0 +1,45 @@
+import Ajv from "ajv";
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function formatValidationErrors(errors) {
+    return errors.map((error) => {
+        const location = error.instancePath.length > 0 ? error.instancePath : "/";
+        const parameters = Object.values(error.params).join(", ");
+        return `${location} ${error.message ?? "is invalid"}${parameters.length > 0 ? `: ${parameters}` : ""}`;
+    });
+}
+// implements REQ-kibi-operation-interface-parity
+export function prepareOperationInput(input, schema) {
+    if (!isObject(input)) {
+        return { valid: false, errors: ["input must be an object"] };
+    }
+    const telemetryValue = input._diagnostic_telemetry;
+    if (telemetryValue !== undefined && !isObject(telemetryValue)) {
+        return {
+            valid: false,
+            errors: ["_diagnostic_telemetry must be an object when provided"],
+        };
+    }
+    const businessInput = Object.fromEntries(Object.entries(input).filter(([key]) => key !== "_diagnostic_telemetry"));
+    const schemaWithExactTopLevel = { ...schema, additionalProperties: false };
+    const validator = new Ajv({ allErrors: true, strict: false }).compile(schemaWithExactTopLevel);
+    if (!validator(businessInput)) {
+        return {
+            valid: false,
+            errors: validator.errors
+                ? formatValidationErrors(validator.errors)
+                : ["input is invalid"],
+        };
+    }
+    return telemetryValue === undefined
+        ? { valid: true, businessInput }
+        : { valid: true, businessInput, telemetry: telemetryValue };
+}
+// implements REQ-kibi-operation-interface-parity
+export function validateAgainstSchema(input, schema) {
+    const result = prepareOperationInput(input, schema);
+    return result.valid
+        ? { valid: true }
+        : { valid: false, errors: result.errors };
+}

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
-/** All command handlers return this instead of calling process.exit(). */
-export interface CommandResult {
-    exitCode?: number;
-}
+import { Command } from "commander";
+export type { CommandResult } from "./cli-command.js";
+export declare function buildProgram(): Command;
+export declare function main(): Promise<never>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA8CA,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAmBtD,wBAAgB,YAAY,IAAI,OAAO,CAYtC;AAGD,wBAAsB,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAgB3C"}

package/dist/cli.js

@@ -15,219 +15,56 @@
  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 { once } from "node:events";
 import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 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 { migrateCommand } from "./commands/migrate.js";
-import { queryCommand } from "./commands/query.js";
-import { searchCommand } from "./commands/search.js";
-import { skillsListCommand, skillsLoadCommand, skillsReadCommand, skillsValidateCommand, } from "./commands/skills.js";
-import { statusCommand } from "./commands/status.js";
-import { syncCommand } from "./commands/sync.js";
-import { usageMetricsCommand } from "./commands/usage-metrics.js";
+import { registerJsonOnlyCommands } from "./cli-json-command.js";
+import { registerFoundationCommands } from "./cli-register-foundation.js";
+import { registerMaintenanceCommands } from "./cli-register-maintenance.js";
+import { registerReportingCommands } from "./cli-register-reporting.js";
+import { registerSkillsCommands } from "./cli-register-skills.js";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-const VERSION = packageJson.version ?? "0.1.0";
-// implements REQ-003
-/** Wraps an async command handler to apply its returned exitCode to process.exitCode. */
-function withExitCode(fn) {
-    return async (...args) => {
-        const result = await fn(...args);
-        if (result && typeof result.exitCode === "number") {
-            process.exitCode = result.exitCode;
-        }
-    };
+function packageVersion(value) {
+    if (value !== null &&
+        typeof value === "object" &&
+        "version" in value &&
+        typeof value.version === "string") {
+        return value.version;
+    }
+    return "0.1.0";
+}
+// implements REQ-kibi-operation-interface-parity
+export function buildProgram() {
+    const program = new Command()
+        .name("kibi")
+        .description("Prolog-based project knowledge base")
+        .version(packageVersion(packageJson));
+    registerFoundationCommands(program);
+    registerReportingCommands(program);
+    registerMaintenanceCommands(program);
+    registerSkillsCommands(program);
+    registerJsonOnlyCommands(program);
+    return program;
 }
-const program = new Command();
-program
-    .name("kibi")
-    .description("Prolog-based project knowledge base")
-    .version(VERSION);
-program
-    .command("init")
-    .description("Initialize .kb/ directory")
-    .option("--no-hooks", "Do not install git hooks (hooks installed by default)")
-    .action(withExitCode(async (options) => {
-    return initCommand(options);
-}));
-program
-    .command("migrate")
-    .description("Migrate .kb/config.json to the latest schema version")
-    .option("--dry-run", "Preview migration changes without writing files")
-    .option("--yes", "Apply migration changes without prompting")
-    .action(withExitCode(async (options) => {
-    return migrateCommand(options);
-}));
-program
-    .command("sync")
-    .description("Sync entities from documents")
-    .option("--validate-only", "Perform validation without mutations")
-    .option("--refresh-symbol-coordinates", "Refresh generated symbol coordinates")
-    .option("--rebuild", "Rebuild branch snapshot from scratch (discards current KB)")
-    .action(withExitCode(async (options) => {
-    return syncCommand(options);
-}));
-program;
-program
-    .command("query [type]")
-    .description("Query knowledge base")
-    .option("--id <id>", "Query specific entity by ID")
-    .option("--tag <tag>", "Filter by tag")
-    .option("--source <path>", "Filter by source file path (substring match)")
-    .option("--relationships <id>", "Get relationships from entity")
-    .option("--format <format>", "Output format: json|table", "json")
-    .option("--limit <n>", "Limit results", "100")
-    .option("--offset <n>", "Skip results", "0")
-    .action(withExitCode(async (type, options) => {
-    return 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")
-    .option("--fix", "Suggest fixes for violations")
-    .option("--kb-path <dir>", "Path to KB directory (overrides branch resolution)")
-    .option("--rules <csv>", "Comma-separated allowlist of rule names to run")
-    .option("--staged", "Run check only against staged changes (experimental)")
-    .option("--min-links <n>", "Minimum number of links required for symbol coverage", "1")
-    .option("--dry-run", "Do not modify files; only print what would happen")
-    .option("--format <format>", "Output format: text|json", "text")
-    .action(withExitCode(async (options) => {
-    return checkCommand(options);
-}));
-program
-    .command("gc")
-    .description("Garbage collect stale branch KBs")
-    .option("--dry-run", "Preview without deleting (default)", true)
-    .option("--force", "Actually delete stale branches")
-    .action(async (options) => {
-    const dryRun = !options.force;
-    await gcCommand({ dryRun, force: options.force });
-});
-program
-    .command("doctor")
-    .description("Diagnose KB setup and configuration")
-    .action(withExitCode(async () => doctorCommand()));
-program
-    .command("usage-metrics")
-    .description("Report usage and quality metrics from .kb/usage.log")
-    .option("--format <format>", "Output format: json|table", "table")
-    .option("--limit <n>", "Limit top zero-result source files", "10")
-    .action(withExitCode(async (options) => {
-    return usageMetricsCommand(options);
-}));
-const skillsProgram = program
-    .command("skills")
-    .description("Manage bundled markdown skills");
-skillsProgram
-    .command("list")
-    .description("List bundled markdown skills")
-    .option("--format <format>", "Output format: json|table", "table")
-    .action(withExitCode(async (options) => {
-    return skillsListCommand(options);
-}));
-skillsProgram
-    .command("load")
-    .description("Load a bundled markdown skill")
-    .argument("<id>", "Bundled skill ID")
-    .option("--format <format>", "Output format: json|markdown", "markdown")
-    .action(withExitCode(async (id, options) => {
-    return skillsLoadCommand(id, options);
-}));
-skillsProgram
-    .command("read")
-    .description("Read a declared bundled skill resource")
-    .argument("<id>", "Bundled skill ID")
-    .argument("<resource>", "Declared resource path")
-    .option("--format <format>", "Output format: text|json", "text")
-    .action(withExitCode(async (id, resource, options) => {
-    return skillsReadCommand(id, resource, options);
-}));
-skillsProgram
-    .command("validate")
-    .description("Validate a bundled markdown skill path")
-    .argument("<path>", "Skill bundle directory or SKILL.md path")
-    .option("--format <format>", "Output format: json|table", "table")
-    .action(withExitCode(async (pathLike, options) => {
-    return skillsValidateCommand(pathLike, options);
-}));
-program
-    .command("branch")
-    .description("Manage branch KBs")
-    .argument("<action>", "Action: ensure")
-    .option("--from <branch>", "Source branch to copy KB from")
-    .action(async (action, options) => {
-    if (action === "ensure") {
-        await branchEnsureCommand(options);
+// implements REQ-kibi-operation-interface-parity
+export async function main() {
+    let exitCode = process.exitCode ?? 0;
+    try {
+        await buildProgram().parseAsync(process.argv);
+        exitCode = process.exitCode ?? 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        exitCode = 1;
     }
-});
-program
-    .parseAsync(process.argv)
-    .then(() => process.exit(process.exitCode ?? 0))
-    .catch((error) => {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(message);
-    process.exit(1);
-});
+    await Promise.all([process.stdout, process.stderr].map((stream) => stream.writableNeedDrain ? once(stream, "drain") : Promise.resolve()));
+    process.exit(exitCode);
+}
+const entryPath = process.argv[1];
+if (entryPath !== undefined &&
+    import.meta.url === pathToFileURL(resolve(entryPath)).href) {
+    void main();
+}

package/dist/commands/aggregated-checks.d.ts

@@ -8,5 +8,5 @@ import type { Violation } from "./check.js";
  * @param rulesAllowlist - Set of rule names to run (null = all)
  * @param requireAdr - Whether to require ADR constraints for symbol-traceability
  */
-export declare function runAggregatedChecks(prolog: PrologProcess, rulesAllowlist: Set<string> | null, requireAdr?: boolean): Promise<Violation[]>;
+export declare function runAggregatedChecks(prolog: Pick<PrologProcess, "query">, rulesAllowlist: Set<string> | null, requireAdr?: boolean): Promise<Violation[]>;
 //# sourceMappingURL=aggregated-checks.d.ts.map

package/dist/commands/aggregated-checks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregated-checks.d.ts","sourceRoot":"","sources":["../../src/commands/aggregated-checks.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,cAAc,CAAC;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAU5C;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EAClC,UAAU,UAAQ,GACjB,OAAO,CAAC,SAAS,EAAE,CAAC,CA4DtB"}
+{"version":3,"file":"aggregated-checks.d.ts","sourceRoot":"","sources":["../../src/commands/aggregated-checks.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,cAAc,CAAC;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAU5C;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,EACpC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EAClC,UAAU,UAAQ,GACjB,OAAO,CAAC,SAAS,EAAE,CAAC,CAuDtB"}

package/dist/commands/aggregated-checks.js

@@ -21,44 +21,38 @@ export async function runAggregatedChecks(prolog, rulesAllowlist, requireAdr = f
     ->  call(checks:check_all_json_with_options(JsonString, ${requireAdrStr}))
     ;   call(checks:check_all_json(JsonString))
     ))`;
+    const result = await prolog.query(query);
+    if (!result.success) {
+        throw new Error(`Aggregated checks query failed: ${result.error || "Unknown error"}`);
+    }
+    let violationsDict;
     try {
-        const result = await prolog.query(query);
-        if (!result.success) {
-            throw new Error(`Aggregated checks query failed: ${result.error || "Unknown error"}`);
-        }
-        let violationsDict;
-        try {
-            const jsonString = result.bindings.JsonString;
-            if (!jsonString) {
-                throw new Error("No JSON string in binding");
-            }
-            let parsed = JSON.parse(jsonString);
-            if (typeof parsed === "string") {
-                parsed = JSON.parse(parsed);
-            }
-            violationsDict = parsed;
+        const jsonString = result.bindings.JsonString;
+        if (!jsonString) {
+            throw new Error("No JSON string in binding");
         }
-        catch (parseError) {
-            throw new Error(`Failed to parse violations JSON: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+        let parsed = JSON.parse(jsonString);
+        if (typeof parsed === "string") {
+            parsed = JSON.parse(parsed);
         }
-        for (const ruleViolations of Object.values(violationsDict)) {
-            for (const v of ruleViolations) {
-                const isAllowed = !rulesAllowlist || rulesAllowlist.has(v.rule);
-                if (isAllowed) {
-                    violations.push({
-                        rule: v.rule,
-                        entityId: v.entityId,
-                        description: v.description,
-                        ...(v.suggestion ? { suggestion: v.suggestion } : {}),
-                        ...(v.source ? { source: v.source } : {}),
-                    });
-                }
+        violationsDict = parsed;
+    }
+    catch (parseError) {
+        throw new Error(`Failed to parse violations JSON: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+    }
+    for (const ruleViolations of Object.values(violationsDict)) {
+        for (const v of ruleViolations) {
+            const isAllowed = !rulesAllowlist || rulesAllowlist.has(v.rule);
+            if (isAllowed) {
+                violations.push({
+                    rule: v.rule,
+                    entityId: v.entityId,
+                    description: v.description,
+                    ...(v.suggestion ? { suggestion: v.suggestion } : {}),
+                    ...(v.source ? { source: v.source } : {}),
+                });
             }
         }
-        return violations;
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Error running aggregated checks: ${message}`);
     }
+    return violations;
 }

package/dist/commands/check.d.ts

@@ -1,4 +1,4 @@
-import { type Violation } from "../utils/rule-registry.js";
+import type { Violation } from "../utils/rule-registry.js";
 export type { Violation };
 export interface CheckOptions {
     fix?: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAoFA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,SAAS,EAAE,CAAC;AAgB1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAkZD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAya/B"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAkFA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,YAAY,EAAE,SAAS,EAAE,CAAC;AAG1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AA2bD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAqW/B"}