@kibhq/core 0.1.0

package/src/skills/skills.test.ts

@@ -0,0 +1,134 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CompletionParams, CompletionResult, LLMProvider, StreamChunk } from "../types.js";
+import { initVault, writeWiki } from "../vault.js";
+import { findSkill, loadSkills } from "./loader.js";
+import { runSkill } from "./runner.js";
+
+let tempDir: string;
+
+afterEach(async () => {
+	if (tempDir) await rm(tempDir, { recursive: true, force: true });
+});
+
+async function makeTempVault() {
+	tempDir = await mkdtemp(join(tmpdir(), "kib-skills-test-"));
+	await initVault(tempDir, { name: "test" });
+	return tempDir;
+}
+
+function mockProvider(response: string): LLMProvider {
+	return {
+		name: "mock",
+		async complete(): Promise<CompletionResult> {
+			return {
+				content: response,
+				usage: { inputTokens: 100, outputTokens: 50 },
+				stopReason: "end_turn",
+			};
+		},
+		async *stream(): AsyncIterable<StreamChunk> {
+			yield { type: "text", text: response };
+		},
+	};
+}
+
+function articleMd(title: string, slug: string, content: string): string {
+	return `---\ntitle: ${title}\nslug: ${slug}\ncategory: concept\ntags: []\nsummary: ""\n---\n\n# ${title}\n\n${content}`;
+}
+
+describe("skill loader", () => {
+	test("loads built-in skills", async () => {
+		const root = await makeTempVault();
+		const skills = await loadSkills(root);
+
+		expect(skills.length).toBeGreaterThanOrEqual(3);
+		expect(skills.some((s) => s.name === "summarize")).toBe(true);
+		expect(skills.some((s) => s.name === "flashcards")).toBe(true);
+		expect(skills.some((s) => s.name === "connections")).toBe(true);
+	});
+
+	test("finds skill by name", async () => {
+		const root = await makeTempVault();
+		const skill = await findSkill(root, "summarize");
+
+		expect(skill).not.toBeNull();
+		expect(skill!.name).toBe("summarize");
+		expect(skill!.description).toBeTruthy();
+	});
+
+	test("returns null for unknown skill", async () => {
+		const root = await makeTempVault();
+		const skill = await findSkill(root, "nonexistent");
+		expect(skill).toBeNull();
+	});
+});
+
+describe("skill runner", () => {
+	test("runs summarize skill", async () => {
+		const root = await makeTempVault();
+		await writeWiki(
+			root,
+			"concepts/test.md",
+			articleMd("Test Article", "test", "This is test content for summarization."),
+		);
+
+		const skill = await findSkill(root, "summarize");
+		expect(skill).not.toBeNull();
+
+		const provider = mockProvider("Summary: This is a test article about testing.");
+		const result = await runSkill(root, skill!, { provider });
+
+		expect(result.content).toContain("Summary");
+	});
+
+	test("runs flashcards skill", async () => {
+		const root = await makeTempVault();
+		await writeWiki(
+			root,
+			"concepts/ml.md",
+			articleMd("Machine Learning", "ml", "ML is a subset of AI that learns from data."),
+		);
+
+		const skill = await findSkill(root, "flashcards");
+		const provider = mockProvider("Q: What is ML?\nA: A subset of AI that learns from data.");
+		const result = await runSkill(root, skill!, { provider });
+
+		expect(result.content).toContain("Q:");
+		expect(result.content).toContain("A:");
+	});
+
+	test("throws when LLM required but not provided", async () => {
+		const root = await makeTempVault();
+		const skill = await findSkill(root, "summarize");
+
+		expect(runSkill(root, skill!)).rejects.toThrow("requires an LLM provider");
+	});
+
+	test("skill context has access to vault data", async () => {
+		const root = await makeTempVault();
+		await writeWiki(root, "concepts/a.md", articleMd("Article A", "article-a", "Content A."));
+		await writeWiki(root, "concepts/b.md", articleMd("Article B", "article-b", "Content B."));
+
+		// Custom skill that tests context access
+		const testSkill = {
+			name: "test-context",
+			version: "1.0.0",
+			description: "Test skill context",
+			input: "wiki" as const,
+			output: "report" as const,
+			async run(ctx: any) {
+				const articles = await ctx.vault.readWiki();
+				const index = await ctx.vault.readIndex();
+				return {
+					content: `Found ${articles.length} articles. Index length: ${index.length}`,
+				};
+			},
+		};
+
+		const result = await runSkill(root, testSkill as any);
+		expect(result.content).toContain("Found 2 articles");
+	});
+});

package/src/types.ts

@@ -0,0 +1,136 @@
+import type { z } from "zod";
+import type {
+	ArticleCategorySchema,
+	ArticleEntrySchema,
+	ArticleFrontmatterSchema,
+	CompileResultSchema,
+	CompletionParamsSchema,
+	CompletionResultSchema,
+	FileOperationSchema,
+	IngestResultSchema,
+	LintDiagnosticSchema,
+	LintRuleSchema,
+	LintSeveritySchema,
+	ManifestSchema,
+	MessageRoleSchema,
+	MessageSchema,
+	SearchResultSchema,
+	SourceEntrySchema,
+	SourceTypeSchema,
+	VaultConfigSchema,
+} from "./schemas.js";
+
+// ─── Core Data Types ─────────────────────────────────────────────
+
+export type SourceType = z.infer<typeof SourceTypeSchema>;
+export type ArticleCategory = z.infer<typeof ArticleCategorySchema>;
+export type SourceEntry = z.infer<typeof SourceEntrySchema>;
+export type ArticleEntry = z.infer<typeof ArticleEntrySchema>;
+export type Manifest = z.infer<typeof ManifestSchema>;
+export type VaultConfig = z.infer<typeof VaultConfigSchema>;
+export type ArticleFrontmatter = z.infer<typeof ArticleFrontmatterSchema>;
+
+// ─── LLM Types ───────────────────────────────────────────────────
+
+export type MessageRole = z.infer<typeof MessageRoleSchema>;
+export type Message = z.infer<typeof MessageSchema>;
+export type CompletionParams = z.infer<typeof CompletionParamsSchema>;
+export type CompletionResult = z.infer<typeof CompletionResultSchema>;
+
+// ─── Operation Types ─────────────────────────────────────────────
+
+export type FileOperation = z.infer<typeof FileOperationSchema>;
+export type SearchResult = z.infer<typeof SearchResultSchema>;
+export type IngestResult = z.infer<typeof IngestResultSchema>;
+export type CompileResult = z.infer<typeof CompileResultSchema>;
+
+// ─── Lint Types ──────────────────────────────────────────────────
+
+export type LintSeverity = z.infer<typeof LintSeveritySchema>;
+export type LintRule = z.infer<typeof LintRuleSchema>;
+export type LintDiagnostic = z.infer<typeof LintDiagnosticSchema>;
+
+// ─── Provider Interface ──────────────────────────────────────────
+
+export interface StreamChunk {
+	type: "text" | "usage";
+	text?: string;
+	usage?: { inputTokens: number; outputTokens: number };
+}
+
+export interface LLMProvider {
+	name: string;
+
+	complete(params: CompletionParams): Promise<CompletionResult>;
+
+	stream(params: CompletionParams): AsyncIterable<StreamChunk>;
+
+	/** Optional: for vision-based ingest */
+	vision?(params: { image: Buffer; prompt: string }): Promise<string>;
+}
+
+// ─── Skill Types ─────────────────────────────────────────────────
+
+export interface SkillContext {
+	vault: {
+		readIndex(): Promise<string>;
+		readGraph(): Promise<string>;
+		readWiki(): Promise<{ title: string; slug: string; content: string }[]>;
+		readRaw(): Promise<{ path: string; content: string }[]>;
+		readFile(path: string): Promise<string>;
+		writeFile(path: string, content: string): Promise<void>;
+		listFiles(glob: string): Promise<string[]>;
+		manifest: Manifest;
+		config: VaultConfig;
+	};
+
+	llm: {
+		complete(params: CompletionParams): Promise<CompletionResult>;
+		stream(params: CompletionParams): AsyncIterable<StreamChunk>;
+	};
+
+	search: {
+		query(term: string, opts?: { limit?: number }): Promise<SearchResult[]>;
+	};
+
+	logger: {
+		info(msg: string): void;
+		warn(msg: string): void;
+		error(msg: string): void;
+	};
+
+	args: Record<string, unknown>;
+}
+
+export interface SkillDefinition {
+	name: string;
+	version: string;
+	description: string;
+	author?: string;
+
+	input: "wiki" | "raw" | "vault" | "selection" | "index" | "none";
+	output: "articles" | "report" | "mutations" | "stdout" | "none";
+
+	llm?: {
+		required: boolean;
+		model: "default" | "fast";
+		systemPrompt: string;
+		maxTokens?: number;
+		temperature?: number;
+	};
+
+	run(ctx: SkillContext): Promise<{ content?: string }>;
+}
+
+// ─── Extract Types ───────────────────────────────────────────────
+
+export interface ExtractResult {
+	title: string;
+	content: string;
+	metadata: Record<string, unknown>;
+}
+
+export interface Extractor {
+	type: SourceType;
+	extract(input: string): Promise<ExtractResult>;
+}

package/src/vault.test.ts

@@ -0,0 +1,141 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	initVault,
+	listWiki,
+	loadConfig,
+	loadManifest,
+	readRaw,
+	readWiki,
+	resolveVaultRoot,
+	writeRaw,
+	writeWiki,
+} from "./vault.js";
+
+let tempDir: string;
+
+afterEach(async () => {
+	if (tempDir) {
+		await rm(tempDir, { recursive: true, force: true });
+	}
+});
+
+async function makeTempDir() {
+	tempDir = await mkdtemp(join(tmpdir(), "kib-test-"));
+	return tempDir;
+}
+
+describe("initVault", () => {
+	test("creates vault directory structure", async () => {
+		const dir = await makeTempDir();
+		const { root, manifest, config } = await initVault(dir, { name: "test-vault" });
+
+		expect(root).toBe(dir);
+		expect(existsSync(join(dir, ".kb"))).toBe(true);
+		expect(existsSync(join(dir, ".kb", "manifest.json"))).toBe(true);
+		expect(existsSync(join(dir, ".kb", "config.toml"))).toBe(true);
+		expect(existsSync(join(dir, "raw"))).toBe(true);
+		expect(existsSync(join(dir, "wiki"))).toBe(true);
+		expect(existsSync(join(dir, "wiki", "concepts"))).toBe(true);
+		expect(existsSync(join(dir, "wiki", "topics"))).toBe(true);
+		expect(existsSync(join(dir, "wiki", "references"))).toBe(true);
+		expect(existsSync(join(dir, "wiki", "outputs"))).toBe(true);
+		expect(existsSync(join(dir, "inbox"))).toBe(true);
+
+		expect(manifest.vault.name).toBe("test-vault");
+		expect(manifest.version).toBe("1");
+		expect(config.provider.default).toBe("anthropic");
+	});
+
+	test("throws if vault already exists", async () => {
+		const dir = await makeTempDir();
+		await initVault(dir);
+		expect(initVault(dir)).rejects.toThrow("already exists");
+	});
+
+	test("allows reinit with force", async () => {
+		const dir = await makeTempDir();
+		await initVault(dir, { name: "first" });
+		const { manifest } = await initVault(dir, { name: "second", force: true });
+		expect(manifest.vault.name).toBe("second");
+	});
+});
+
+describe("resolveVaultRoot", () => {
+	test("finds vault root from subdirectory", async () => {
+		const dir = await makeTempDir();
+		await initVault(dir);
+		const subdir = join(dir, "wiki", "concepts");
+		expect(resolveVaultRoot(subdir)).toBe(dir);
+	});
+
+	test("throws if no vault found", async () => {
+		const dir = await makeTempDir();
+		expect(() => resolveVaultRoot(dir)).toThrow("No vault found");
+	});
+});
+
+describe("manifest operations", () => {
+	test("loadManifest round-trips through saveManifest", async () => {
+		const dir = await makeTempDir();
+		await initVault(dir, { name: "roundtrip-test" });
+		const manifest = await loadManifest(dir);
+		expect(manifest.vault.name).toBe("roundtrip-test");
+		expect(manifest.sources).toEqual({});
+		expect(manifest.articles).toEqual({});
+	});
+});
+
+describe("config operations", () => {
+	test("loadConfig returns valid config", async () => {
+		const dir = await makeTempDir();
+		await initVault(dir);
+		const config = await loadConfig(dir);
+		expect(config.provider.default).toBe("anthropic");
+		expect(config.compile.auto_index).toBe(true);
+		expect(config.cache.enabled).toBe(true);
+	});
+});
+
+describe("raw file operations", () => {
+	test("writeRaw and readRaw round-trip", async () => {
+		const dir = await makeTempDir();
+		await initVault(dir);
+		const content = "# Test Article\n\nSome content here.";
+		await writeRaw(dir, "articles/test.md", content);
+		const read = await readRaw(dir, "articles/test.md");
+		expect(read).toBe(content);
+	});
+
+	test("writeRaw creates subdirectories", async () => {
+		const dir = await makeTempDir();
+		await initVault(dir);
+		await writeRaw(dir, "papers/deep/nested/file.md", "content");
+		expect(existsSync(join(dir, "raw", "papers", "deep", "nested", "file.md"))).toBe(true);
+	});
+});
+
+describe("wiki file operations", () => {
+	test("writeWiki and readWiki round-trip", async () => {
+		const dir = await makeTempDir();
+		await initVault(dir);
+		const content = "---\ntitle: Test\n---\n\n# Test\n\nContent.";
+		await writeWiki(dir, "concepts/test.md", content);
+		const read = await readWiki(dir, "concepts/test.md");
+		expect(read).toBe(content);
+	});
+
+	test("listWiki returns markdown files", async () => {
+		const dir = await makeTempDir();
+		await initVault(dir);
+		await writeWiki(dir, "concepts/a.md", "# A");
+		await writeWiki(dir, "topics/b.md", "# B");
+		const files = await listWiki(dir);
+		expect(files.length).toBe(2);
+		expect(files.some((f) => f.endsWith("a.md"))).toBe(true);
+		expect(files.some((f) => f.endsWith("b.md"))).toBe(true);
+	});
+});

package/src/vault.ts

@@ -0,0 +1,251 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import TOML from "@iarna/toml";
+import {
+	CACHE_DIR,
+	CONFIG_FILE,
+	DEFAULT_CATEGORIES,
+	DEFAULTS,
+	GRAPH_FILE,
+	INBOX_DIR,
+	INDEX_FILE,
+	LOGS_DIR,
+	MANIFEST_FILE,
+	MANIFEST_VERSION,
+	RAW_CATEGORIES,
+	RAW_DIR,
+	SKILLS_DIR,
+	VAULT_DIR,
+	WIKI_DIR,
+} from "./constants.js";
+import { ManifestError, VaultExistsError, VaultNotFoundError } from "./errors.js";
+import { ManifestSchema, VaultConfigSchema } from "./schemas.js";
+import type { Manifest, VaultConfig } from "./types.js";
+
+/**
+ * Find the vault root by walking up from startDir looking for .kb/
+ */
+export function resolveVaultRoot(startDir?: string): string {
+	let dir = resolve(startDir ?? process.cwd());
+	while (true) {
+		if (existsSync(join(dir, VAULT_DIR))) {
+			return dir;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) {
+			throw new VaultNotFoundError(startDir);
+		}
+		dir = parent;
+	}
+}
+
+/**
+ * Initialize a new vault at the given path.
+ */
+export async function initVault(
+	rootDir: string,
+	opts: { name?: string; provider?: string; model?: string; force?: boolean } = {},
+): Promise<{ root: string; manifest: Manifest; config: VaultConfig }> {
+	const root = resolve(rootDir);
+	const kbDir = join(root, VAULT_DIR);
+
+	if (existsSync(kbDir) && !opts.force) {
+		throw new VaultExistsError(root);
+	}
+
+	// Create directory structure
+	const dirs = [
+		kbDir,
+		join(kbDir, CACHE_DIR),
+		join(kbDir, CACHE_DIR, "responses"),
+		join(kbDir, SKILLS_DIR),
+		join(kbDir, LOGS_DIR),
+		join(root, INBOX_DIR),
+		join(root, WIKI_DIR),
+		...DEFAULT_CATEGORIES.map((c) => join(root, WIKI_DIR, c)),
+		join(root, RAW_DIR),
+		...RAW_CATEGORIES.map((c) => join(root, RAW_DIR, c)),
+	];
+
+	await Promise.all(dirs.map((d) => mkdir(d, { recursive: true })));
+
+	const now = new Date().toISOString();
+	const provider = opts.provider ?? DEFAULTS.provider;
+	const model = opts.model ?? DEFAULTS.model;
+	const name = opts.name ?? basename(root);
+
+	const manifest: Manifest = {
+		version: MANIFEST_VERSION,
+		vault: {
+			name,
+			created: now,
+			lastCompiled: null,
+			provider,
+			model,
+		},
+		sources: {},
+		articles: {},
+		stats: {
+			totalSources: 0,
+			totalArticles: 0,
+			totalWords: 0,
+			lastLintAt: null,
+		},
+	};
+
+	const config: VaultConfig = VaultConfigSchema.parse({
+		provider: { default: provider, model, fast_model: DEFAULTS.fastModel },
+		compile: {},
+		ingest: {},
+		watch: {},
+		search: {},
+		query: {},
+		cache: {},
+	});
+
+	await saveManifest(root, manifest);
+	await saveConfig(root, config);
+
+	return { root, manifest, config };
+}
+
+// ─── Manifest Operations ─────────────────────────────────────────
+
+export async function loadManifest(root: string): Promise<Manifest> {
+	const path = join(root, VAULT_DIR, MANIFEST_FILE);
+	try {
+		const raw = await readFile(path, "utf-8");
+		const data = JSON.parse(raw);
+		return ManifestSchema.parse(data);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+			throw new VaultNotFoundError(root);
+		}
+		throw new ManifestError(`Failed to load manifest: ${err}`);
+	}
+}
+
+export async function saveManifest(root: string, manifest: Manifest): Promise<void> {
+	const path = join(root, VAULT_DIR, MANIFEST_FILE);
+	const tmp = `${path}.tmp`;
+	await writeFile(tmp, JSON.stringify(manifest, null, 2), "utf-8");
+	await rename(tmp, path);
+}
+
+// ─── Config Operations ───────────────────────────────────────────
+
+export async function loadConfig(root: string): Promise<VaultConfig> {
+	const path = join(root, VAULT_DIR, CONFIG_FILE);
+	try {
+		const raw = await readFile(path, "utf-8");
+		const data = TOML.parse(raw);
+		return VaultConfigSchema.parse(data);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+			throw new VaultNotFoundError(root);
+		}
+		throw new ManifestError(`Failed to load config: ${err}`);
+	}
+}
+
+export async function saveConfig(root: string, config: VaultConfig): Promise<void> {
+	const path = join(root, VAULT_DIR, CONFIG_FILE);
+	const tmp = `${path}.tmp`;
+	await writeFile(tmp, TOML.stringify(config as any), "utf-8");
+	await rename(tmp, path);
+}
+
+// ─── Raw File Operations ─────────────────────────────────────────
+
+export async function writeRaw(
+	root: string,
+	relativePath: string,
+	content: string,
+): Promise<string> {
+	const fullPath = join(root, RAW_DIR, relativePath);
+	await mkdir(dirname(fullPath), { recursive: true });
+	const tmp = `${fullPath}.tmp`;
+	await writeFile(tmp, content, "utf-8");
+	await rename(tmp, fullPath);
+	return fullPath;
+}
+
+export async function readRaw(root: string, relativePath: string): Promise<string> {
+	const fullPath = join(root, RAW_DIR, relativePath);
+	return readFile(fullPath, "utf-8");
+}
+
+export async function listRaw(root: string): Promise<string[]> {
+	return listFilesRecursive(join(root, RAW_DIR));
+}
+
+// ─── Wiki File Operations ────────────────────────────────────────
+
+export async function writeWiki(
+	root: string,
+	relativePath: string,
+	content: string,
+): Promise<string> {
+	const fullPath = join(root, WIKI_DIR, relativePath);
+	await mkdir(dirname(fullPath), { recursive: true });
+	const tmp = `${fullPath}.tmp`;
+	await writeFile(tmp, content, "utf-8");
+	await rename(tmp, fullPath);
+	return fullPath;
+}
+
+export async function readWiki(root: string, relativePath: string): Promise<string> {
+	const fullPath = join(root, WIKI_DIR, relativePath);
+	return readFile(fullPath, "utf-8");
+}
+
+export async function listWiki(root: string): Promise<string[]> {
+	return listFilesRecursive(join(root, WIKI_DIR));
+}
+
+export async function readIndex(root: string): Promise<string> {
+	try {
+		return await readFile(join(root, WIKI_DIR, INDEX_FILE), "utf-8");
+	} catch {
+		return "";
+	}
+}
+
+export async function readGraph(root: string): Promise<string> {
+	try {
+		return await readFile(join(root, WIKI_DIR, GRAPH_FILE), "utf-8");
+	} catch {
+		return "";
+	}
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────
+
+async function listFilesRecursive(dir: string): Promise<string[]> {
+	const results: string[] = [];
+	try {
+		const entries = await readdir(dir, { withFileTypes: true });
+		for (const entry of entries) {
+			const fullPath = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				results.push(...(await listFilesRecursive(fullPath)));
+			} else if (entry.name.endsWith(".md")) {
+				results.push(fullPath);
+			}
+		}
+	} catch {
+		// Directory doesn't exist yet — that's fine
+	}
+	return results;
+}
+
+export async function deleteFile(path: string): Promise<void> {
+	try {
+		await unlink(path);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+			throw err;
+		}
+	}
+}