@kibhq/cli 0.1.0

package/src/commands/lint.ts

@@ -0,0 +1,100 @@
+import { resolveVaultRoot, VaultNotFoundError } from "@kibhq/core";
+import * as log from "../ui/logger.js";
+import { createSpinner } from "../ui/spinner.js";
+
+interface LintOpts {
+	fix?: boolean;
+	check?: string;
+	json?: boolean;
+}
+
+export async function lint(opts: LintOpts) {
+	let root: string;
+	try {
+		root = resolveVaultRoot();
+	} catch (err) {
+		if (err instanceof VaultNotFoundError) {
+			log.error(err.message);
+			process.exit(1);
+		}
+		throw err;
+	}
+
+	const { lintVault } = await import("@kibhq/core");
+
+	log.header("linting wiki");
+
+	const spinner = createSpinner("Checking articles...");
+	spinner.start();
+
+	const result = await lintVault(root, {
+		ruleFilter: opts.check,
+		onProgress: (msg) => {
+			spinner.text = `  ${msg}`;
+		},
+	});
+
+	spinner.stop();
+
+	if (opts.json) {
+		console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+
+	const total = result.diagnostics.length;
+	if (total === 0) {
+		log.success("No issues found");
+		log.blank();
+		return;
+	}
+
+	console.log(`  ${total} issue${total === 1 ? "" : "s"} found:`);
+	log.blank();
+
+	const severityLabel = {
+		error: "\x1b[31mERROR\x1b[0m  ",
+		warning: "\x1b[33mWARN\x1b[0m   ",
+		info: "\x1b[36mINFO\x1b[0m   ",
+	};
+
+	const ruleLabel = {
+		orphan: "ORPHAN ",
+		"broken-link": "LINK   ",
+		stale: "STALE  ",
+		frontmatter: "FMATTER",
+		missing: "MISSING",
+	};
+
+	for (const d of result.diagnostics) {
+		const sev = severityLabel[d.severity];
+		const rule = ruleLabel[d.rule] ?? d.rule.padEnd(7);
+		const path = d.path ? `\x1b[2m${d.path}\x1b[0m` : "";
+
+		console.log(`  ${sev} ${rule}  ${d.message}`);
+		if (path) {
+			console.log(`                   ${path}`);
+		}
+		console.log();
+	}
+
+	// Summary
+	const parts: string[] = [];
+	if (result.errors > 0) parts.push(`${result.errors} error${result.errors === 1 ? "" : "s"}`);
+	if (result.warnings > 0)
+		parts.push(`${result.warnings} warning${result.warnings === 1 ? "" : "s"}`);
+	if (result.infos > 0) parts.push(`${result.infos} info${result.infos === 1 ? "" : "s"}`);
+	log.dim(parts.join(", "));
+
+	const fixable = result.diagnostics.filter((d) => d.fixable).length;
+	if (fixable > 0 && !opts.fix) {
+		log.blank();
+		log.dim(`${fixable} fixable issue${fixable === 1 ? "" : "s"} — run kib lint --fix`);
+	}
+
+	log.blank();
+
+	// Exit with error code if there are errors
+	if (result.errors > 0) {
+		process.exit(1);
+	}
+}

package/src/commands/query.ts

@@ -0,0 +1,78 @@
+import {
+	createProvider,
+	loadConfig,
+	NoProviderError,
+	resolveVaultRoot,
+	VaultNotFoundError,
+} from "@kibhq/core";
+import * as log from "../ui/logger.js";
+import { setupProvider } from "../ui/setup-provider.js";
+import { createSpinner } from "../ui/spinner.js";
+
+interface QueryOpts {
+	file?: boolean;
+	sources?: boolean;
+	json?: boolean;
+}
+
+export async function query(question: string, opts: QueryOpts) {
+	let root: string;
+	try {
+		root = resolveVaultRoot();
+	} catch (err) {
+		if (err instanceof VaultNotFoundError) {
+			log.error(err.message);
+			process.exit(1);
+		}
+		throw err;
+	}
+
+	const config = await loadConfig(root);
+
+	// Create provider
+	let provider;
+	try {
+		provider = await createProvider(config.provider.default, config.provider.model);
+	} catch (err) {
+		if (err instanceof NoProviderError) {
+			provider = await setupProvider(root);
+		} else {
+			log.error((err as Error).message);
+			process.exit(1);
+		}
+	}
+
+	const { queryVault } = await import("@kibhq/core");
+
+	log.header("querying knowledge base");
+
+	const spinner = createSpinner("Searching and generating answer...");
+	spinner.start();
+
+	try {
+		const result = await queryVault(root, question, provider);
+		spinner.stop();
+
+		// Print answer
+		console.log();
+		console.log(result.answer);
+		console.log();
+
+		// Print sources if requested
+		if (opts.sources && result.sourcePaths.length > 0) {
+			log.dim("Sources:");
+			for (const path of result.sourcePaths) {
+				log.dim(`  - ${path}`);
+			}
+			log.blank();
+		}
+
+		if (opts.json) {
+			console.log(JSON.stringify(result, null, 2));
+		}
+	} catch (err) {
+		spinner.fail("Query failed");
+		log.error((err as Error).message);
+		process.exit(1);
+	}
+}

package/src/commands/search.ts

@@ -0,0 +1,87 @@
+import { resolveVaultRoot, VaultNotFoundError } from "@kibhq/core";
+import * as log from "../ui/logger.js";
+import { createSpinner } from "../ui/spinner.js";
+
+interface SearchOpts {
+	wiki?: boolean;
+	raw?: boolean;
+	limit?: number;
+	json?: boolean;
+}
+
+export async function search(term: string, opts: SearchOpts) {
+	let root: string;
+	try {
+		root = resolveVaultRoot();
+	} catch (err) {
+		if (err instanceof VaultNotFoundError) {
+			log.error(err.message);
+			process.exit(1);
+		}
+		throw err;
+	}
+
+	const { SearchIndex } = await import("@kibhq/core");
+
+	const scope = opts.wiki ? "wiki" : opts.raw ? "raw" : "all";
+	const limit = opts.limit ?? 20;
+
+	const spinner = createSpinner("Searching...");
+	spinner.start();
+
+	const index = new SearchIndex();
+
+	// Try to load cached index first
+	const loaded = await index.load(root);
+	if (!loaded) {
+		spinner.text = "  Building search index...";
+		await index.build(root, scope);
+		await index.save(root);
+	}
+
+	const start = performance.now();
+	const results = index.search(term, { limit });
+	const elapsed = Math.round(performance.now() - start);
+
+	spinner.stop();
+
+	if (opts.json) {
+		console.log(JSON.stringify(results, null, 2));
+		return;
+	}
+
+	log.header("searching vault");
+
+	if (results.length === 0) {
+		log.dim(`No results for "${term}"`);
+		log.blank();
+		return;
+	}
+
+	console.log(`  ${results.length} result${results.length === 1 ? "" : "s"} (${elapsed}ms):`);
+	log.blank();
+
+	for (let i = 0; i < results.length; i++) {
+		const r = results[i]!;
+		const num = String(i + 1).padStart(2);
+		const title = r.title ?? r.path.split("/").pop()?.replace(/\.md$/, "") ?? r.path;
+		const score = r.score.toFixed(2).padStart(5);
+
+		console.log(`  ${num}. ${title}  ${score}`);
+		console.log(`      ${dimPath(r.path)}`);
+		if (r.snippet) {
+			console.log(`      ${truncate(r.snippet, 80)}`);
+		}
+		console.log();
+	}
+}
+
+function dimPath(path: string): string {
+	// Import chalk dynamically to keep lazy loading
+	return `\x1b[2m${path}\x1b[0m`;
+}
+
+function truncate(str: string, max: number): string {
+	if (str.length <= max) return str;
+	return `${str.slice(0, max - 3)}...`;
+}

package/src/commands/skill.ts

@@ -0,0 +1,97 @@
+import {
+	createProvider,
+	loadConfig,
+	NoProviderError,
+	resolveVaultRoot,
+	VaultNotFoundError,
+} from "@kibhq/core";
+import * as log from "../ui/logger.js";
+import { setupProvider } from "../ui/setup-provider.js";
+import { createSpinner } from "../ui/spinner.js";
+
+export async function skill(subcommand: string, name?: string, _opts?: unknown) {
+	let root: string;
+	try {
+		root = resolveVaultRoot();
+	} catch (err) {
+		if (err instanceof VaultNotFoundError) {
+			log.error(err.message);
+			process.exit(1);
+		}
+		throw err;
+	}
+
+	const { loadSkills, findSkill, runSkill } = await import("@kibhq/core");
+
+	switch (subcommand) {
+		case "list": {
+			log.header("available skills");
+
+			const skills = await loadSkills(root);
+
+			for (const s of skills) {
+				console.log(`  ${s.name.padEnd(20)} ${s.description}`);
+			}
+			log.blank();
+			log.dim(`Run a skill: kib skill run <name>`);
+			log.blank();
+			break;
+		}
+
+		case "run": {
+			if (!name) {
+				log.error("Skill name required. Usage: kib skill run <name>");
+				process.exit(1);
+			}
+
+			const s = await findSkill(root, name);
+			if (!s) {
+				log.error(`Skill "${name}" not found. Run kib skill list to see available skills.`);
+				process.exit(1);
+			}
+
+			log.header(`running skill: ${s.name}`);
+
+			let provider;
+			if (s.llm?.required) {
+				const config = await loadConfig(root);
+				const modelKey = s.llm.model === "fast" ? "fast_model" : "model";
+				const model = config.provider[modelKey];
+				try {
+					provider = await createProvider(config.provider.default, model);
+				} catch (err) {
+					if (err instanceof NoProviderError) {
+						provider = await setupProvider(root);
+					} else {
+						log.error((err as Error).message);
+						process.exit(1);
+					}
+				}
+			}
+
+			const spinner = createSpinner(`Running ${s.name}...`);
+			spinner.start();
+
+			try {
+				const result = await runSkill(root, s, { provider });
+				spinner.succeed(`${s.name} completed`);
+
+				if (result.content) {
+					log.blank();
+					console.log(result.content);
+					log.blank();
+				}
+			} catch (err) {
+				spinner.fail(`${s.name} failed`);
+				log.error((err as Error).message);
+				process.exit(1);
+			}
+			break;
+		}
+
+		default:
+			log.error(`Unknown subcommand: ${subcommand}`);
+			log.dim("Available: list, run");
+			process.exit(1);
+	}
+}

package/src/commands/status.ts

@@ -0,0 +1,70 @@
+import { loadConfig, loadManifest, resolveVaultRoot, VaultNotFoundError } from "@kibhq/core";
+import * as log from "../ui/logger.js";
+
+export async function status() {
+	let root: string;
+	try {
+		root = resolveVaultRoot();
+	} catch (err) {
+		if (err instanceof VaultNotFoundError) {
+			log.error(err.message);
+			process.exit(1);
+		}
+		throw err;
+	}
+
+	const manifest = await loadManifest(root);
+	const config = await loadConfig(root);
+
+	log.header("vault status");
+
+	log.keyValue("vault", manifest.vault.name);
+	log.keyValue("provider", `${config.provider.default} (${config.provider.model})`);
+	log.keyValue("path", root);
+	log.blank();
+
+	const sourceCount = Object.keys(manifest.sources).length;
+	const articleCount = Object.keys(manifest.articles).length;
+	const pendingCount = Object.values(manifest.sources).filter(
+		(s) => !s.lastCompiled || s.lastCompiled < s.ingestedAt,
+	).length;
+
+	log.keyValue(
+		"SOURCES",
+		`${sourceCount} total${pendingCount > 0 ? ` | ${pendingCount} pending compilation` : ""}`,
+	);
+	log.keyValue(
+		"ARTICLES",
+		`${articleCount} total | ${manifest.stats.totalWords.toLocaleString()} words`,
+	);
+
+	if (manifest.vault.lastCompiled) {
+		const ago = timeAgo(new Date(manifest.vault.lastCompiled));
+		log.keyValue("LAST COMPILED", ago);
+	} else {
+		log.keyValue("LAST COMPILED", "never");
+	}
+
+	if (manifest.stats.lastLintAt) {
+		const ago = timeAgo(new Date(manifest.stats.lastLintAt));
+		log.keyValue("LAST LINT", ago);
+	}
+
+	if (pendingCount > 0) {
+		log.blank();
+		log.warn(`${pendingCount} sources pending — run kib compile`);
+	}
+
+	log.blank();
+}
+
+function timeAgo(date: Date): string {
+	const seconds = Math.floor((Date.now() - date.getTime()) / 1000);
+	if (seconds < 60) return "just now";
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+	const days = Math.floor(hours / 24);
+	return `${days} day${days === 1 ? "" : "s"} ago`;
+}

package/src/commands/watch.ts

@@ -0,0 +1,141 @@
+import { watch as fsWatch } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { INBOX_DIR, loadConfig, resolveVaultRoot, VaultNotFoundError } from "@kibhq/core";
+import * as log from "../ui/logger.js";
+
+export async function watch() {
+	let root: string;
+	try {
+		root = resolveVaultRoot();
+	} catch (err) {
+		if (err instanceof VaultNotFoundError) {
+			log.error(err.message);
+			process.exit(1);
+		}
+		throw err;
+	}
+
+	const config = await loadConfig(root);
+	const inboxPath = resolve(root, config.watch.inbox_path);
+	const { ingestSource } = await import("@kibhq/core");
+
+	log.header(`watching ${config.watch.inbox_path}/`);
+	log.dim(`Drop files into ${inboxPath} to auto-ingest.`);
+	log.dim("Press Ctrl+C to stop.");
+	log.blank();
+
+	// Track already-seen files to avoid double-processing
+	const processed = new Set<string>();
+
+	// Seed with existing files
+	try {
+		const existing = await readdir(inboxPath);
+		for (const f of existing) processed.add(f);
+	} catch {
+		// inbox might not exist yet
+	}
+
+	// Start the HTTP server for browser extension
+	const server = startHttpServer(root, ingestSource);
+
+	// Watch for new files
+	const watcher = fsWatch(inboxPath, { recursive: false }, async (event, filename) => {
+		if (!filename || processed.has(filename)) return;
+		if (filename.startsWith(".")) return; // skip dotfiles
+
+		const filePath = join(inboxPath, filename);
+
+		// Wait briefly for file to finish writing
+		await new Promise((r) => setTimeout(r, 500));
+
+		try {
+			await stat(filePath);
+		} catch {
+			return; // file was deleted before we could process it
+		}
+
+		processed.add(filename);
+		const timestamp = new Date().toLocaleTimeString("en-US", { hour12: false });
+
+		try {
+			log.info(`${timestamp} Ingesting ${filename}...`);
+			const result = await ingestSource(root, filePath);
+
+			if (result.skipped) {
+				log.dim(`${timestamp} Skipped: ${result.skipReason}`);
+			} else {
+				log.success(`${timestamp} ${result.title} → ${result.path}`);
+
+				if (config.watch.auto_compile) {
+					log.dim(`${timestamp} Auto-compile: run kib compile to process`);
+				}
+			}
+		} catch (err) {
+			log.error(`${timestamp} Failed to ingest ${filename}: ${(err as Error).message}`);
+		}
+	});
+
+	// Handle graceful shutdown
+	process.on("SIGINT", () => {
+		watcher.close();
+		server?.stop();
+		log.blank();
+		log.dim("Watch stopped.");
+		process.exit(0);
+	});
+}
+
+function startHttpServer(root: string, ingestSource: typeof import("@kibhq/core").ingestSource) {
+	try {
+		const server = Bun.serve({
+			port: 4747,
+			async fetch(req) {
+				const url = new URL(req.url);
+
+				if (req.method === "POST" && url.pathname === "/ingest") {
+					try {
+						const body = (await req.json()) as { content: string; url?: string; title?: string };
+
+						// Write content to a temp file in inbox
+						const slug = (body.title ?? "untitled")
+							.toLowerCase()
+							.replace(/[^a-z0-9]+/g, "-")
+							.slice(0, 60);
+						const tmpPath = join(root, "inbox", `${slug}-${Date.now()}.md`);
+
+						const fullContent = body.title
+							? `# ${body.title}\n\n${body.url ? `Source: ${body.url}\n\n` : ""}${body.content}`
+							: body.content;
+
+						await Bun.write(tmpPath, fullContent);
+						await ingestSource(root, tmpPath, { title: body.title });
+
+						return new Response(JSON.stringify({ ok: true }), {
+							headers: { "Content-Type": "application/json" },
+						});
+					} catch (err) {
+						return new Response(JSON.stringify({ error: (err as Error).message }), {
+							status: 500,
+							headers: { "Content-Type": "application/json" },
+						});
+					}
+				}
+
+				if (req.method === "GET" && url.pathname === "/") {
+					return new Response("kib watch running", {
+						headers: { "Content-Type": "text/plain" },
+					});
+				}
+
+				return new Response("Not found", { status: 404 });
+			},
+		});
+
+		log.dim(`HTTP server listening on http://localhost:4747`);
+		return server;
+	} catch {
+		log.dim("HTTP server not started (port 4747 may be in use)");
+		return null;
+	}
+}

package/src/index.ts

@@ -0,0 +1,129 @@
+import { Command } from "commander";
+
+const program = new Command()
+	.name("kib")
+	.description("The Headless Knowledge Compiler")
+	.version("0.1.0");
+
+program
+	.command("init")
+	.description("Create a new vault in the current directory")
+	.option("--name <name>", "vault name (default: directory name)")
+	.option("--provider <provider>", "force LLM provider instead of auto-detect")
+	.action(async (opts) => {
+		const { init } = await import("./commands/init.js");
+		await init(opts);
+	});
+
+program
+	.command("config [key] [value]")
+	.description("Get or set configuration")
+	.option("--list", "list all configuration")
+	.action(async (key, value, opts) => {
+		const { config } = await import("./commands/config.js");
+		await config(key, value, opts);
+	});
+
+program
+	.command("status")
+	.description("Vault health dashboard")
+	.action(async () => {
+		const { status } = await import("./commands/status.js");
+		await status();
+	});
+
+program
+	.command("ingest <sources...>")
+	.description("Ingest sources into raw/")
+	.option("--category <cat>", "override raw/ subdirectory")
+	.option("--tags <tags>", "comma-separated tags")
+	.option("--batch", "read sources from stdin (one per line)")
+	.action(async (sources, opts) => {
+		const { ingest } = await import("./commands/ingest.js");
+		await ingest(sources, opts);
+	});
+
+program
+	.command("compile")
+	.description("Compile raw sources into wiki articles")
+	.option("--force", "recompile all sources")
+	.option("--dry-run", "show what would happen without doing it")
+	.option("--source <path>", "compile only a specific source")
+	.option("--max <n>", "limit sources per pass", Number.parseInt)
+	.action(async (opts) => {
+		const { compile } = await import("./commands/compile.js");
+		await compile(opts);
+	});
+
+program
+	.command("search <term>")
+	.description("Fast text search across the vault")
+	.option("--wiki", "search only wiki/")
+	.option("--raw", "search only raw/")
+	.option("--limit <n>", "max results", Number.parseInt)
+	.option("--json", "JSON output")
+	.action(async (term, opts) => {
+		const { search } = await import("./commands/search.js");
+		await search(term, opts);
+	});
+
+program
+	.command("query <question>")
+	.description("Ask a question against the knowledge base")
+	.option("--file", "auto-file to wiki/outputs/")
+	.option("--no-file", "never file")
+	.option("--sources", "show which articles were used")
+	.option("--json", "JSON output")
+	.action(async (question, opts) => {
+		const { query } = await import("./commands/query.js");
+		await query(question, opts);
+	});
+
+program
+	.command("chat")
+	.description("Interactive REPL with the knowledge base")
+	.action(async () => {
+		const { chat } = await import("./commands/chat.js");
+		await chat();
+	});
+
+program
+	.command("lint")
+	.description("Run health checks on the wiki")
+	.option("--fix", "auto-fix all issues")
+	.option("--check <type>", "run specific check")
+	.option("--json", "JSON output")
+	.action(async (opts) => {
+		const { lint } = await import("./commands/lint.js");
+		await lint(opts);
+	});
+
+program
+	.command("skill <subcommand> [name]")
+	.description("Manage skills (install, list, run, create)")
+	.action(async (subcommand, name, opts) => {
+		const { skill } = await import("./commands/skill.js");
+		await skill(subcommand, name, opts);
+	});
+
+program
+	.command("watch")
+	.description("Watch inbox/ and auto-ingest")
+	.action(async () => {
+		const { watch } = await import("./commands/watch.js");
+		await watch();
+	});
+
+program
+	.command("export")
+	.description("Export wiki to other formats")
+	.option("--format <type>", "output format: markdown, html, pdf", "markdown")
+	.option("--output <path>", "output directory")
+	.action(async (opts) => {
+		const { exportVault } = await import("./commands/export.js");
+		await exportVault(opts);
+	});
+
+export function main() {
+	program.parse();
+}