@williamthorsen/kb 0.0.0 → 0.3.1

package/dist/esm/config/load-config.d.ts

@@ -0,0 +1,5 @@
+import type { KbRoot } from '../types.js';
+import { type KbConfig } from './config-schema.js';
+export declare function loadKbConfig(input: {
+    kbRoot: KbRoot;
+}): Promise<KbConfig>;

package/dist/esm/config/load-config.js

@@ -0,0 +1,36 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { CONFIG_FILE } from "../layout/index.js";
+import { isEnoent } from "../type-guards.js";
+import { configFileShape, defaultKbConfig } from "./config-schema.js";
+import { KbLoaderError } from "./kb-loader-error.js";
+export async function loadKbConfig(input) {
+    const path = join(input.kbRoot.path, CONFIG_FILE);
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isEnoent(error)) {
+            return defaultKbConfig;
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = parse(text);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new KbLoaderError(`${path}: malformed YAML — ${message}`);
+    }
+    const result = configFileShape.safeParse(parsed ?? {});
+    if (!result.success) {
+        throw new KbLoaderError(`${path}: invalid config.yaml — ${result.error.issues[0]?.message ?? 'unknown error'}`);
+    }
+    return {
+        targets: result.data.targets ?? defaultKbConfig.targets,
+        exclude: result.data.exclude ?? defaultKbConfig.exclude,
+    };
+}

package/dist/esm/config/note-scope.d.ts

@@ -0,0 +1,7 @@
+import type { KbConfig } from './config-schema.js';
+export interface NoteScopeMatcher {
+    isTarget(relativePath: string): boolean;
+    isExcluded(relativePath: string): boolean;
+    isNote(relativePath: string): boolean;
+}
+export declare function createNoteScopeMatcher(config: KbConfig): NoteScopeMatcher;

package/dist/esm/config/note-scope.js

@@ -0,0 +1,10 @@
+import picomatch from 'picomatch';
+export function createNoteScopeMatcher(config) {
+    const isTarget = picomatch([...config.targets], { dot: false });
+    const isExcluded = picomatch([...config.exclude], { dot: false });
+    return {
+        isTarget,
+        isExcluded,
+        isNote: (relativePath) => isTarget(relativePath) && !isExcluded(relativePath),
+    };
+}

package/dist/esm/create/create.d.ts

@@ -0,0 +1,26 @@
+export type DefaultKbOutcome = 'set' | 'unchanged' | 'needs-selection';
+export interface CreatedStore {
+    name: string;
+    storePath: string;
+    registered: boolean;
+    created: readonly string[];
+    defaultKb?: DefaultKbOutcome;
+}
+export type CreateInput = {
+    targetDir: string;
+    name?: string;
+} & ({
+    register: false;
+} | {
+    register: true;
+    registryPath: string;
+});
+export type CreateOutcome = {
+    ok: true;
+    created: CreatedStore;
+} | {
+    ok: false;
+    reason: 'kb-exists' | 'name-registered';
+    message: string;
+};
+export declare function create(input: CreateInput): Promise<CreateOutcome>;

package/dist/esm/create/create.js

@@ -0,0 +1,51 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { loadKbRegistry } from "../discovery/load-registry.js";
+import { registerStore } from "../discovery/register-store.js";
+import { setDefaultKb } from "../discovery/set-default-kb.js";
+import { pathExists } from "../filesystem/exists.js";
+import { ALIASES_FILE, CONFIG_FILE, CONTENT_DIR, EVENTS_DIR, KB_DIR, resolveEventsDir, resolveKbDir, } from "../layout/index.js";
+import { renderAliasesSeed, renderConfigSeed } from "./render-seeds.js";
+export async function create(input) {
+    const storePath = resolve(input.targetDir);
+    const name = input.name ?? basename(storePath);
+    if (await pathExists(resolveKbDir(storePath))) {
+        return { ok: false, reason: 'kb-exists', message: `a ${KB_DIR}/ store already exists at ${storePath}` };
+    }
+    if (!input.register) {
+        const created = await scaffold(storePath);
+        return { ok: true, created: { name, storePath, registered: false, created } };
+    }
+    const { registryPath } = input;
+    const before = await loadKbRegistry({ userConfigPath: registryPath });
+    if (before.entries.some((entry) => entry.name === name)) {
+        return { ok: false, reason: 'name-registered', message: nameRegisteredMessage(name, registryPath) };
+    }
+    const created = await scaffold(storePath);
+    const result = await registerStore({ registryPath, name, storePath });
+    if (result.status === 'already-present') {
+        return { ok: false, reason: 'name-registered', message: nameRegisteredMessage(name, registryPath) };
+    }
+    const defaultKb = await ensureDefaultKb({ registryPath, name, before });
+    return { ok: true, created: { name, storePath, registered: true, created, defaultKb } };
+}
+async function ensureDefaultKb(input) {
+    if (input.before.defaultKb !== undefined) {
+        return 'unchanged';
+    }
+    if (input.before.entries.length > 0) {
+        return 'needs-selection';
+    }
+    await setDefaultKb({ registryPath: input.registryPath, name: input.name });
+    return 'set';
+}
+function nameRegisteredMessage(name, registryPath) {
+    return `a store named "${name}" is already registered in ${registryPath}`;
+}
+async function scaffold(storePath) {
+    await mkdir(resolveKbDir(storePath), { recursive: true });
+    await writeFile(join(storePath, CONFIG_FILE), renderConfigSeed(), 'utf8');
+    await writeFile(join(storePath, ALIASES_FILE), renderAliasesSeed(), 'utf8');
+    await mkdir(resolveEventsDir(storePath), { recursive: true });
+    return [CONFIG_FILE, ALIASES_FILE, `${CONTENT_DIR}/`, `${EVENTS_DIR}/`];
+}

package/dist/esm/create/index.d.ts

@@ -0,0 +1,3 @@
+export type { CreatedStore, CreateInput, CreateOutcome } from './create.js';
+export { create } from './create.js';
+export { renderAliasesSeed, renderConfigSeed } from './render-seeds.js';

package/dist/esm/create/index.js

@@ -0,0 +1,2 @@
+export { create } from "./create.js";
+export { renderAliasesSeed, renderConfigSeed } from "./render-seeds.js";

package/dist/esm/create/render-seeds.d.ts

@@ -0,0 +1,2 @@
+export declare function renderAliasesSeed(): string;
+export declare function renderConfigSeed(): string;

package/dist/esm/create/render-seeds.js

@@ -0,0 +1,29 @@
+import { stringify } from 'yaml';
+import { defaultKbConfig } from "../config/config-schema.js";
+const ALIASES_HEADER = `# Tag aliases for this knowledge store.
+#
+# Map each canonical tag to the aliases that should resolve to it, for example:
+#   aliases:
+#     typescript: [ts, type-script]
+# The \`aliases:\` key is required even when empty.
+`;
+const CONFIG_HEADER = `# Check configuration for this knowledge store.
+#
+# Both keys are optional and fall back to the defaults shown below; an absent file uses these defaults too. Uncomment
+# and edit to override. \`targets\` selects which notes \`kb check\` enumerates and \`exclude\` removes matches;
+# patterns are slash-separated and relative to the store root.
+#
+`;
+export function renderAliasesSeed() {
+    return `${ALIASES_HEADER}aliases: {}\n`;
+}
+export function renderConfigSeed() {
+    return `${CONFIG_HEADER}${commentBlock(stringify(defaultKbConfig))}\n`;
+}
+function commentBlock(text) {
+    return text
+        .trimEnd()
+        .split('\n')
+        .map((line) => (line === '' ? '#' : `# ${line}`))
+        .join('\n');
+}

package/dist/esm/discovery/find-kb-root.d.ts

@@ -0,0 +1,4 @@
+import type { KbRoot } from '../types.js';
+export declare function findKbRoot(input: {
+    startDir: string;
+}): Promise<KbRoot | null>;

package/dist/esm/discovery/find-kb-root.js

@@ -0,0 +1,22 @@
+import { dirname, resolve } from 'node:path';
+import { directoryExists } from "../filesystem/exists.js";
+import { resolveKbDir } from "../layout/index.js";
+export async function findKbRoot(input) {
+    for (const current of ancestorDirs(input.startDir)) {
+        const kbDir = resolveKbDir(current);
+        if (await directoryExists(kbDir, { treatErrorsAsAbsent: true })) {
+            return { path: current, kbDir };
+        }
+    }
+    return null;
+}
+function* ancestorDirs(startDir) {
+    let current = resolve(startDir);
+    yield current;
+    let parent = dirname(current);
+    while (parent !== current) {
+        current = parent;
+        yield current;
+        parent = dirname(current);
+    }
+}

package/dist/esm/discovery/index.d.ts

@@ -0,0 +1,9 @@
+export type { KbRegistry, KbRegistryEntry, KbRoot } from '../types.js';
+export { findKbRoot } from './find-kb-root.js';
+export type { KbRegistryFile, KbRegistryFileEntry } from './kb-registry-schema.js';
+export { kbRegistryFileEntrySchema, kbRegistryFileSchema } from './kb-registry-schema.js';
+export type { KbRegistryLoadResult } from './load-registry.js';
+export { loadKbRegistry, tryLoadKbRegistry } from './load-registry.js';
+export type { RegisterStoreResult } from './register-store.js';
+export { registerStore } from './register-store.js';
+export { clearDefaultKb, setDefaultKb } from './set-default-kb.js';

package/dist/esm/discovery/index.js

@@ -0,0 +1,5 @@
+export { findKbRoot } from "./find-kb-root.js";
+export { kbRegistryFileEntrySchema, kbRegistryFileSchema } from "./kb-registry-schema.js";
+export { loadKbRegistry, tryLoadKbRegistry } from "./load-registry.js";
+export { registerStore } from "./register-store.js";
+export { clearDefaultKb, setDefaultKb } from "./set-default-kb.js";

package/dist/esm/discovery/kb-registry-schema.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export declare const kbRegistryFileEntrySchema: z.ZodObject<{
+    path: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    readonly: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const kbRegistryFileSchema: z.ZodObject<{
+    default_kb: z.ZodOptional<z.ZodString>;
+    kbs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        readonly: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type KbRegistryFileEntry = z.infer<typeof kbRegistryFileEntrySchema>;
+export type KbRegistryFile = z.infer<typeof kbRegistryFileSchema>;

package/dist/esm/discovery/kb-registry-schema.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export const kbRegistryFileEntrySchema = z.object({
+    path: z.string().min(1),
+    description: z.string().optional(),
+    readonly: z.boolean().optional(),
+});
+export const kbRegistryFileSchema = z.object({
+    default_kb: z.string().min(1).optional(),
+    kbs: z.record(z.string(), kbRegistryFileEntrySchema).optional(),
+});

package/dist/esm/discovery/load-registry.d.ts

@@ -0,0 +1,15 @@
+import type { KbRegistry } from '../types.js';
+export declare function loadKbRegistry(input?: {
+    userConfigPath?: string;
+    projectDir?: string;
+    home?: string;
+}): Promise<KbRegistry>;
+export interface KbRegistryLoadResult {
+    config: KbRegistry;
+    error?: string;
+}
+export declare function tryLoadKbRegistry(input?: {
+    userConfigPath?: string;
+    projectDir?: string;
+    home?: string;
+}): Promise<KbRegistryLoadResult>;

package/dist/esm/discovery/load-registry.js

@@ -0,0 +1,114 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { parse } from 'yaml';
+import { isEnoent } from "../type-guards.js";
+import { kbRegistryFileSchema } from "./kb-registry-schema.js";
+const USER_CONFIG_RELATIVE = join('.agents', 'kb.yaml');
+const PROJECT_CONFIG_RELATIVE = join('.agents', 'kb.yaml');
+export async function loadKbRegistry(input = {}) {
+    const home = input.home ?? homedir();
+    const userConfigPath = input.userConfigPath ?? join(home, USER_CONFIG_RELATIVE);
+    const projectConfigPath = input.projectDir === undefined ? undefined : join(input.projectDir, PROJECT_CONFIG_RELATIVE);
+    const userFile = await loadRegistryFile(userConfigPath, 'user', home);
+    const projectFile = projectConfigPath === undefined ? undefined : await loadRegistryFile(projectConfigPath, 'project', home);
+    const merged = mergeEntries(userFile?.entries ?? [], projectFile?.entries ?? []);
+    let defaultKbName;
+    let defaultKbSource = userConfigPath;
+    if (projectFile?.defaultKb !== undefined) {
+        defaultKbName = projectFile.defaultKb;
+        defaultKbSource = projectConfigPath ?? userConfigPath;
+    }
+    else if (userFile?.defaultKb !== undefined) {
+        defaultKbName = userFile.defaultKb;
+    }
+    const defaultKb = resolveDefaultKb(merged, defaultKbName, defaultKbSource);
+    const sources = {};
+    if (userFile !== undefined)
+        sources.user = userConfigPath;
+    if (projectConfigPath !== undefined && projectFile !== undefined) {
+        sources.project = projectConfigPath;
+    }
+    return { entries: merged, ...(defaultKb !== undefined && { defaultKb }), sources };
+}
+export async function tryLoadKbRegistry(input = {}) {
+    try {
+        return { config: await loadKbRegistry(input) };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { config: { entries: [], sources: {} }, error: message };
+    }
+}
+function expandTilde(value, home) {
+    if (value !== '~' && !value.startsWith('~/')) {
+        return value;
+    }
+    if (home === '') {
+        throw new Error(`cannot expand "${value}": HOME is not set`);
+    }
+    return value === '~' ? home : join(home, value.slice(2));
+}
+async function loadRegistryFile(path, source, home) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isEnoent(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = parse(text);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${path}: malformed YAML — ${message}`);
+    }
+    if (parsed === null || parsed === undefined) {
+        return { entries: [] };
+    }
+    const result = kbRegistryFileSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`${path}: invalid kb.yaml — ${result.error.issues[0]?.message ?? 'unknown error'}`);
+    }
+    const configDir = dirname(path);
+    const entries = [];
+    for (const [name, fileEntry] of Object.entries(result.data.kbs ?? {})) {
+        entries.push({
+            name,
+            path: resolvePath(fileEntry.path, configDir, home),
+            source,
+            ...(fileEntry.description !== undefined && { description: fileEntry.description }),
+            ...(fileEntry.readonly !== undefined && { readonly: fileEntry.readonly }),
+        });
+    }
+    return { entries, ...(result.data.default_kb !== undefined && { defaultKb: result.data.default_kb }) };
+}
+function mergeEntries(userEntries, projectEntries) {
+    const byName = new Map();
+    for (const entry of userEntries) {
+        byName.set(entry.name, entry);
+    }
+    for (const entry of projectEntries) {
+        byName.set(entry.name, entry);
+    }
+    return [...byName.values()];
+}
+function resolveDefaultKb(entries, name, sourcePath) {
+    if (name === undefined) {
+        return undefined;
+    }
+    const match = entries.find((entry) => entry.name === name);
+    if (match === undefined) {
+        throw new Error(`${sourcePath}: default_kb "${name}" does not match any registered KB`);
+    }
+    return match;
+}
+function resolvePath(value, configDir, home) {
+    const expanded = expandTilde(value, home);
+    return isAbsolute(expanded) ? expanded : resolve(configDir, expanded);
+}

package/dist/esm/discovery/register-store.d.ts

@@ -0,0 +1,9 @@
+export interface RegisterStoreResult {
+    status: 'added' | 'already-present';
+}
+export declare function registerStore(input: {
+    registryPath: string;
+    name: string;
+    storePath: string;
+    description?: string;
+}): Promise<RegisterStoreResult>;

package/dist/esm/discovery/register-store.js

@@ -0,0 +1,26 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { kbRegistryFileSchema } from "./kb-registry-schema.js";
+import { loadRegistryDocument } from "./registry-document.js";
+export async function registerStore(input) {
+    const doc = await loadRegistryDocument(input.registryPath);
+    const existing = kbRegistryFileSchema.safeParse(doc.toJS() ?? {});
+    if (!existing.success) {
+        throw new Error(`${input.registryPath}: invalid kb.yaml — ${existing.error.issues[0]?.message ?? 'unknown error'}`);
+    }
+    if (doc.hasIn(['kbs', input.name])) {
+        return { status: 'already-present' };
+    }
+    const entry = { path: input.storePath };
+    if (input.description !== undefined) {
+        entry.description = input.description;
+    }
+    doc.setIn(['kbs', input.name], entry);
+    const result = kbRegistryFileSchema.safeParse(doc.toJS());
+    if (!result.success) {
+        throw new Error(`${input.registryPath}: cannot register "${input.name}" — ${result.error.issues[0]?.message ?? 'invalid entry'}`);
+    }
+    await mkdir(dirname(input.registryPath), { recursive: true });
+    await writeFile(input.registryPath, doc.toString(), 'utf8');
+    return { status: 'added' };
+}

package/dist/esm/discovery/registry-document.d.ts

@@ -0,0 +1,2 @@
+import { Document } from 'yaml';
+export declare function loadRegistryDocument(path: string): Promise<Document>;

package/dist/esm/discovery/registry-document.js

@@ -0,0 +1,17 @@
+import { readFile } from 'node:fs/promises';
+import { Document, parseDocument } from 'yaml';
+import { isEnoent } from "../type-guards.js";
+export async function loadRegistryDocument(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isEnoent(error)) {
+            return new Document({});
+        }
+        throw error;
+    }
+    const doc = parseDocument(text);
+    return doc.contents === null ? new Document({}) : doc;
+}

package/dist/esm/discovery/set-default-kb.d.ts

@@ -0,0 +1,7 @@
+export declare function clearDefaultKb(input: {
+    registryPath: string;
+}): Promise<void>;
+export declare function setDefaultKb(input: {
+    registryPath: string;
+    name: string;
+}): Promise<void>;

package/dist/esm/discovery/set-default-kb.js

@@ -0,0 +1,53 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { isMap, isScalar } from 'yaml';
+import { kbRegistryFileSchema } from "./kb-registry-schema.js";
+import { loadRegistryDocument } from "./registry-document.js";
+export async function clearDefaultKb(input) {
+    const doc = await loadRegistryDocument(input.registryPath);
+    const existing = kbRegistryFileSchema.safeParse(doc.toJS() ?? {});
+    if (!existing.success) {
+        throw new Error(`${input.registryPath}: invalid kb.yaml — ${existing.error.issues[0]?.message ?? 'unknown error'}`);
+    }
+    if (!doc.has('default_kb')) {
+        return;
+    }
+    deleteDefaultKb(doc);
+    await writeFile(input.registryPath, doc.toString(), 'utf8');
+}
+export async function setDefaultKb(input) {
+    const doc = await loadRegistryDocument(input.registryPath);
+    const existing = kbRegistryFileSchema.safeParse(doc.toJS() ?? {});
+    if (!existing.success) {
+        throw new Error(`${input.registryPath}: invalid kb.yaml — ${existing.error.issues[0]?.message ?? 'unknown error'}`);
+    }
+    if (!doc.hasIn(['kbs', input.name])) {
+        throw new Error(`${input.registryPath}: "${input.name}" is not a registered knowledge base`);
+    }
+    doc.set('default_kb', input.name);
+    const result = kbRegistryFileSchema.safeParse(doc.toJS());
+    if (!result.success) {
+        throw new Error(`${input.registryPath}: cannot set default_kb — ${result.error.issues[0]?.message ?? 'invalid registry'}`);
+    }
+    await mkdir(dirname(input.registryPath), { recursive: true });
+    await writeFile(input.registryPath, doc.toString(), 'utf8');
+}
+function deleteDefaultKb(doc) {
+    const map = doc.contents;
+    if (!isMap(map)) {
+        doc.delete('default_kb');
+        return;
+    }
+    const index = map.items.findIndex((pair) => isScalar(pair.key) && pair.key.value === 'default_kb');
+    const removed = index !== -1 ? map.items[index] : undefined;
+    const carried = removed !== undefined && isScalar(removed.key) ? removed.key.commentBefore : undefined;
+    doc.delete('default_kb');
+    if (carried === undefined) {
+        return;
+    }
+    const successor = map.items[index];
+    if (successor !== undefined && isScalar(successor.key)) {
+        successor.key.commentBefore =
+            successor.key.commentBefore !== undefined ? `${carried}\n${successor.key.commentBefore}` : carried;
+    }
+}

package/dist/esm/filesystem/exists.d.ts

@@ -0,0 +1,6 @@
+export interface ExistsOptions {
+    absentCodes?: readonly string[];
+    treatErrorsAsAbsent?: boolean;
+}
+export declare function directoryExists(path: string, options?: ExistsOptions): Promise<boolean>;
+export declare function pathExists(path: string, options?: ExistsOptions): Promise<boolean>;

package/dist/esm/filesystem/exists.js

@@ -0,0 +1,24 @@
+import { stat } from 'node:fs/promises';
+import { isErrorCode } from "../type-guards.js";
+export async function directoryExists(path, options = {}) {
+    return statExists(path, options, (stats) => stats.isDirectory());
+}
+export async function pathExists(path, options = {}) {
+    return statExists(path, options, () => true);
+}
+const DEFAULT_ABSENT_CODES = ['ENOENT'];
+async function statExists(path, options, onStats) {
+    try {
+        return onStats(await stat(path));
+    }
+    catch (error) {
+        if (options.treatErrorsAsAbsent) {
+            return false;
+        }
+        const absentCodes = options.absentCodes ?? DEFAULT_ABSENT_CODES;
+        if (absentCodes.some((code) => isErrorCode(error, code))) {
+            return false;
+        }
+        throw error;
+    }
+}

package/dist/esm/filesystem/index.d.ts

@@ -0,0 +1 @@
+export { directoryExists, type ExistsOptions, pathExists } from './exists.js';

package/dist/esm/filesystem/index.js

@@ -0,0 +1 @@
+export { directoryExists, pathExists } from "./exists.js";

package/dist/esm/frontmatter/index.d.ts

@@ -0,0 +1,2 @@
+export type { Frontmatter, FrontmatterRaw, ParsedNote } from '../types.js';
+export { parseNote, parseNoteContent } from './parse-note.js';

package/dist/esm/frontmatter/index.js

@@ -0,0 +1 @@
+export { parseNote, parseNoteContent } from "./parse-note.js";

package/dist/esm/frontmatter/parse-note.d.ts

@@ -0,0 +1,8 @@
+import type { ParsedNote } from '../types.js';
+export declare function parseNote(input: {
+    path: string;
+}): Promise<ParsedNote>;
+export declare function parseNoteContent(input: {
+    content: string;
+    path?: string;
+}): ParsedNote;