@williamthorsen/kb 0.5.0 → 0.6.1

package/README.md

@@ -4,17 +4,7 @@ Foundation library for knowledge-base tooling.
 Provides knowledge-base discovery, registry loading, frontmatter parsing and writing, tag canonicalization, and type-blind vault-integrity checks.
 It underpins the knowledge-base skills — among them `kb-retrieve` (assertion recall) and `kb-retrieve-events` (event recall), `kb-add`, `kb-curate`, `capture-event`, and `kb-update-events` — and the planned `@williamthorsen/kb-mcp` server.
 
-<!-- section:release-notes -->
-## Release notes — v0.5.0 (2026-08-08)
-
-### 🎉 Features
-
-- Register a new store with a description and keep the registry sorted (#1237)
-
-  Adds a `--description` flag to `kb create`, so that a new knowledge base can be given a description as it is created. Alphabetical ordering of keys in `kb.yaml` is now enforced on every write.
-
-  Also fixes an issue where creating a knowledge base under an empty name could leave a stray registry entry. Across the CLI, a flag given an empty value is now refused.
-<!-- /section:release-notes -->
+<!-- section:release-notes --><!-- /section:release-notes -->
 
 ## Exports
 
@@ -284,7 +274,7 @@ Without `--merge`, a store that already declares a taxonomy is left untouched an
 
 ## Error and exception model
 
-The checks **return** findings; they never throw. Loaders (`loadKbConfig`, `loadAliases`, `loadTaxonomy`) **throw** a typed `KbLoaderError` on structural defects or malformed YAML, with the offending file path named in the message. `KbLoaderError` (exported from `@williamthorsen/kb/config`) carries a `kind: 'KbLoaderError'` discriminant — and an `isKbLoaderError` type guard — so a caller can distinguish a recoverable config or alias defect from any other throw. `loadKbRegistry` throws a plain `Error` on its own structural defects. I/O errors other than a missing optional file propagate.
+The checks **return** findings; they never throw. Loaders (`loadKbConfig`, `loadAliases`, `loadTaxonomy`) **throw** a typed `KbLoaderError` on structural defects or malformed YAML, with the offending file path named in the message. `KbLoaderError` (exported from `@williamthorsen/kb/config`) carries a `kind: 'KbLoaderError'` discriminant — and an `isKbLoaderError` type guard — so a caller can distinguish a recoverable config or alias defect from any other throw. An underlying failure, such as a YAML parse error, is attached as the thrown error's `cause`. `loadKbRegistry` throws a plain `Error` on its own structural defects. I/O errors other than a missing optional file propagate.
 
 ## MCP wrappability
 

package/bin/kb.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
+// Imports only node builtins: a top-level import resolves before the gate below runs, so an
+// unresolvable dependency would replace this file's build-first message with ERR_MODULE_NOT_FOUND.
 import { existsSync } from 'node:fs';
 
 // Thin wrapper so pnpm can symlink the bin at install time, before `dist/` exists.

package/dist/esm/check/enumerate.js

@@ -1,6 +1,7 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 import process from 'node:process';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { createNoteScopeMatcher } from "../config/note-scope.js";
 import { readNoteContent } from "../note-io/read-note.js";
 import { isGlobSegment } from "./glob-segments.js";
@@ -26,8 +27,7 @@ export async function enumerateNotes(input) {
             });
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            process.stderr.write(`kb: warning: could not read note ${path}; skipping: ${message}\n`);
+            process.stderr.write(`kb: warning: could not read note ${path}; skipping: ${describeError(error)}\n`);
         }
     }
     return notes;
@@ -58,8 +58,7 @@ async function walk(input) {
         entries = await readdir(dir, { withFileTypes: true });
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        process.stderr.write(`kb: warning: could not read directory ${dir}; skipping: ${message}\n`);
+        process.stderr.write(`kb: warning: could not read directory ${dir}; skipping: ${describeError(error)}\n`);
         return;
     }
     const atRoot = dir === root;

package/dist/esm/cli/commands/check.js

@@ -1,3 +1,4 @@
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { check } from "../../check/check.js";
 import { isKbLoaderError } from "../../config/kb-loader-error.js";
 import { formatHuman, formatJson, summarize } from "../format.js";
@@ -119,8 +120,7 @@ export function parseCheckArgs(argv) {
     return { kb, json, help, patterns, vs };
 }
 function buildUsageError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { exitCode: 2, stdout: '', stderr: `kb check: ${message}\n${CHECK_HELP}` };
+    return { exitCode: 2, stdout: '', stderr: `kb check: ${describeError(error)}\n${CHECK_HELP}` };
 }
 async function resolveSelection(input) {
     const { options, store, result } = input;

package/dist/esm/cli/commands/create.js

@@ -1,5 +1,6 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { create } from "../../create/create.js";
 import { takeInlineValue, takeValue } from "../parse-flag-value.js";
 import { runSetDefault } from "./set-default.js";
@@ -109,8 +110,7 @@ export function parseCreateArgs(argv) {
 }
 const UNSET_DEFAULT_HINT = 'Multiple knowledge bases are registered and no default is set. Run `kb set-default` to choose one.\n';
 function buildUsageError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { exitCode: 2, stdout: '', stderr: `kb create: ${message}\n${CREATE_HELP}` };
+    return { exitCode: 2, stdout: '', stderr: `kb create: ${describeError(error)}\n${CREATE_HELP}` };
 }
 function formatCreated(created, registryPath) {
     const lines = [`Created knowledge base "${created.name}" at ${created.storePath}`];

package/dist/esm/cli/commands/set-default.js

@@ -1,5 +1,6 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { tryLoadKbRegistry } from "../../discovery/load-registry.js";
 import { clearDefaultKb, setDefaultKb } from "../../discovery/set-default-kb.js";
 export const SET_DEFAULT_HELP = `Usage: kb set-default [name] [options]
@@ -38,11 +39,11 @@ export async function runSetDefault(input) {
     if (error !== undefined) {
         return { exitCode: 2, stdout: '', stderr: `kb set-default: ${error}\n` };
     }
-    const entries = config.entries;
     if (options.none) {
         await clearDefaultKb({ registryPath });
         return { exitCode: 0, stdout: 'The default knowledge base has been cleared.\n', stderr: '' };
     }
+    const entries = config.entries;
     if (options.name !== null) {
         if (entries.length === 0) {
             return { exitCode: 2, stdout: '', stderr: buildNoStoresMessage() };
@@ -118,6 +119,5 @@ function buildSetConfirmation(name) {
     return `Default knowledge base has been set to "${name}".\n`;
 }
 function buildUsageError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { exitCode: 2, stdout: '', stderr: `kb set-default: ${message}\n${SET_DEFAULT_HELP}` };
+    return { exitCode: 2, stdout: '', stderr: `kb set-default: ${describeError(error)}\n${SET_DEFAULT_HELP}` };
 }

package/dist/esm/cli/commands/taxonomy.js

@@ -1,3 +1,4 @@
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { enumerateNotes } from "../../check/enumerate.js";
 import { isKbLoaderError } from "../../config/kb-loader-error.js";
 import { loadKbConfig } from "../../config/load-config.js";
@@ -34,8 +35,7 @@ export async function runTaxonomy(input) {
         options = parseTaxonomyArgs(input.argv);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { exitCode: 2, stdout: '', stderr: `kb taxonomy: ${message}\n${TAXONOMY_HELP}` };
+        return { exitCode: 2, stdout: '', stderr: `kb taxonomy: ${describeError(error)}\n${TAXONOMY_HELP}` };
     }
     if (options.help) {
         return { exitCode: 0, stdout: TAXONOMY_HELP, stderr: '' };

package/dist/esm/cli/index.js

@@ -1,4 +1,5 @@
 import process from 'node:process';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { run } from "./run.js";
 import { readlineSelectKbPrompt } from "./select-kb-prompt.js";
 async function main() {
@@ -12,8 +13,7 @@ async function main() {
         });
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        process.stderr.write(`kb: unexpected error: ${message}\n`);
+        process.stderr.write(`kb: unexpected error: ${describeError(error)}\n`);
         process.exit(2);
     }
     if (output.stdout !== '')

package/dist/esm/cli/run.js

@@ -12,9 +12,10 @@ Commands:
 
 Run "kb <command> --help" for command options.
 `;
+const HELP_COMMANDS = new Set([undefined, '--help', '-h']);
 export async function run(input) {
     const [command, ...rest] = input.argv;
-    if (command === undefined || command === '--help' || command === '-h') {
+    if (HELP_COMMANDS.has(command)) {
         return { exitCode: 0, stdout: HELP, stderr: '' };
     }
     if (command === 'check') {

package/dist/esm/cli/select-kb-prompt.js

@@ -14,7 +14,7 @@ export function parseSelection(answer, kbCount) {
     if (answer === '')
         return { kind: 'cancel' };
     const choice = Number(answer);
-    if (!Number.isInteger(choice))
+    if (!Number.isSafeInteger(choice))
         return null;
     if (choice >= 1 && choice <= kbCount)
         return { kind: 'kb', index: choice - 1 };

package/dist/esm/cli/targeting/resolve-changed-paths.js

@@ -1,6 +1,7 @@
 import { execFileSync } from 'node:child_process';
 import { realpathSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { isRecord } from "../../type-guards.js";
 export function resolveChangedPaths(input) {
     const { storeRoot, ref } = input;
@@ -37,7 +38,7 @@ function extractGitErrorMessage(error) {
     if (isRecord(error) && typeof error.stderr === 'string' && error.stderr.trim() !== '') {
         return error.stderr.trim();
     }
-    return error instanceof Error ? error.message : String(error);
+    return describeError(error);
 }
 function tryGit(storeRoot, args) {
     try {

package/dist/esm/config/kb-loader-error.d.ts

@@ -1,5 +1,5 @@
 export declare class KbLoaderError extends Error {
     readonly kind: "KbLoaderError";
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
 export declare function isKbLoaderError(error: unknown): error is KbLoaderError;

package/dist/esm/config/kb-loader-error.js

@@ -1,7 +1,7 @@
 export class KbLoaderError extends Error {
     kind = 'KbLoaderError';
-    constructor(message) {
-        super(message);
+    constructor(message, options) {
+        super(message, options);
         this.name = 'KbLoaderError';
     }
 }

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

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { parse } from 'yaml';
 import { CONFIG_FILE } from "../layout/index.js";
 import { isEnoent } from "../type-guards.js";
@@ -22,8 +23,7 @@ export async function loadKbConfig(input) {
         parsed = parse(text);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new KbLoaderError(`${path}: malformed YAML — ${message}`);
+        throw new KbLoaderError(`${path}: malformed YAML: ${describeError(error)}`, { cause: error });
     }
     const result = configFileShape.safeParse(parsed ?? {});
     if (!result.success) {

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

@@ -1,6 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 import { parse } from 'yaml';
 import { isEnoent } from "../type-guards.js";
 import { kbRegistryFileSchema } from "./kb-registry-schema.js";
@@ -36,8 +38,7 @@ export async function tryLoadKbRegistry(input = {}) {
         return { config: await loadKbRegistry(input) };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { config: { entries: [], sources: {} }, error: message };
+        return { config: { entries: [], sources: {} }, error: describeError(error) };
     }
 }
 function expandTilde(value, home) {
@@ -65,8 +66,7 @@ async function loadRegistryFile(path, source, home) {
         parsed = parse(text);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`${path}: malformed YAML — ${message}`);
+        throw chainError(`${path}: malformed YAML`, error);
     }
     if (parsed === null || parsed === undefined) {
         return { entries: [] };
@@ -77,7 +77,8 @@ async function loadRegistryFile(path, source, home) {
     }
     const configDir = dirname(path);
     const entries = [];
-    for (const [name, fileEntry] of Object.entries(result.data.kbs ?? {})) {
+    const fileEntries = Object.entries(result.data.kbs ?? {});
+    for (const [name, fileEntry] of fileEntries) {
         entries.push({
             name,
             path: resolvePath(fileEntry.path, configDir, home),
@@ -96,7 +97,7 @@ function mergeEntries(userEntries, projectEntries) {
     for (const entry of projectEntries) {
         byName.set(entry.name, entry);
     }
-    return [...byName.values()];
+    return byName.values().toArray();
 }
 function resolveDefaultKb(entries, name, sourcePath) {
     if (name === undefined) {

package/dist/esm/filesystem/write-atomic.d.ts

@@ -0,0 +1 @@
+export declare function writeAtomic(path: string, content: string): Promise<void>;

package/dist/esm/filesystem/write-atomic.js

@@ -0,0 +1,17 @@
+import { randomBytes } from 'node:crypto';
+import { rename, unlink, writeFile } from 'node:fs/promises';
+export async function writeAtomic(path, content) {
+    const tempPath = `${path}.${randomBytes(8).toString('hex')}.tmp`;
+    try {
+        await writeFile(tempPath, content, 'utf8');
+        await rename(tempPath, path);
+    }
+    catch (error) {
+        try {
+            await unlink(tempPath);
+        }
+        catch {
+        }
+        throw error;
+    }
+}

package/dist/esm/frontmatter/parse-note.js

@@ -91,7 +91,7 @@ function toFrontmatter(doc) {
                 tags = stringList(item.value);
                 break;
             default:
-                extra[key] = key in plainRecord ? plainRecord[key] : null;
+                extra[key] = Object.hasOwn(plainRecord, key) ? plainRecord[key] : null;
         }
     }
     return { title, recordType, created, updated, tags, extra };

package/dist/esm/note-io/write-note.js

@@ -1,5 +1,4 @@
-import { randomBytes } from 'node:crypto';
-import { rename, unlink, writeFile } from 'node:fs/promises';
+import { writeAtomic } from "../filesystem/write-atomic.js";
 import { renderFrontmatterFields } from "./yaml-fields.js";
 const FENCE = '---';
 export function renderNote(fields, body) {
@@ -8,14 +7,5 @@ export function renderNote(fields, body) {
     return `${FENCE}\n${frontmatter}\n${FENCE}\n\n${normalizedBody}`;
 }
 export async function writeNote(path, fields, body) {
-    const content = renderNote(fields, body);
-    const tempPath = `${path}.${randomBytes(8).toString('hex')}.tmp`;
-    await writeFile(tempPath, content, 'utf8');
-    try {
-        await rename(tempPath, path);
-    }
-    catch (error) {
-        await unlink(tempPath).catch(() => { });
-        throw error;
-    }
+    await writeAtomic(path, renderNote(fields, body));
 }

package/dist/esm/records/event.js

@@ -1,6 +1,7 @@
 import { asStringList, isValidDate } from "../note-io/field-validators.js";
 export const EVENT_IMPACT_LEVELS = ['low', 'medium', 'high', 'critical'];
 const IMPACT_LEVEL_SET = new Set(EVENT_IMPACT_LEVELS);
+const NOT_SUPPLIED_VALUES = new Set([undefined, null, '']);
 export function isEventImpact(value) {
     return typeof value === 'string' && IMPACT_LEVEL_SET.has(value);
 }
@@ -110,7 +111,7 @@ function readListField(value, field, errors) {
     return list;
 }
 function readOptionalNonEmptyString(value, field, errors) {
-    if (value === undefined || value === null || value === '') {
+    if (NOT_SUPPLIED_VALUES.has(value)) {
         return undefined;
     }
     if (typeof value === 'string') {

package/dist/esm/tags/load-aliases.js

@@ -1,5 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 import { parse } from 'yaml';
 import { KbLoaderError } from "../config/kb-loader-error.js";
 import { ALIASES_FILE } from "../layout/index.js";
@@ -20,8 +22,7 @@ export async function loadAliases(input) {
         return parseAliases(text, path);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new KbLoaderError(message);
+        throw new KbLoaderError(describeError(error), { cause: error });
     }
 }
 export function parseAliases(text, contextLabel = 'tag-aliases') {
@@ -30,8 +31,7 @@ export function parseAliases(text, contextLabel = 'tag-aliases') {
         parsed = parse(text);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`${contextLabel}: malformed YAML — ${message}`);
+        throw chainError(`${contextLabel}: malformed YAML`, error);
     }
     if (!isRecord(parsed)) {
         throw new Error(`${contextLabel}: top-level must be a mapping`);

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

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { parse } from 'yaml';
 import { KbLoaderError } from "../config/kb-loader-error.js";
 import { TAXONOMY_FILE } from "../layout/index.js";
@@ -22,8 +23,7 @@ export async function loadTaxonomy(input) {
         parsed = parse(text);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new KbLoaderError(`${path}: malformed YAML — ${message}`);
+        throw new KbLoaderError(`${path}: malformed YAML: ${describeError(error)}`, { cause: error });
     }
     const result = taxonomyFileShape.safeParse(parsed ?? {});
     if (!result.success) {

package/dist/esm/taxonomy/write-taxonomy.js

@@ -1,8 +1,9 @@
-import { randomBytes } from 'node:crypto';
-import { readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { isMap, isPair, isScalar, parseDocument } from 'yaml';
 import { KbLoaderError } from "../config/kb-loader-error.js";
+import { writeAtomic } from "../filesystem/write-atomic.js";
 import { TAXONOMY_FILE } from "../layout/index.js";
 import { isEnoent, isRecord } from "../type-guards.js";
 import { describeKeyDefect } from "./taxonomy-schema.js";
@@ -98,7 +99,7 @@ async function readDocument(path) {
     const document = parseDocument(text);
     const firstError = document.errors[0];
     if (firstError !== undefined) {
-        throw new KbLoaderError(`${path}: malformed YAML — ${firstError.message}`);
+        throw new KbLoaderError(`${path}: malformed YAML: ${describeError(firstError)}`, { cause: firstError });
     }
     if (document.contents !== null && !isMap(document.contents)) {
         throw new KbLoaderError(`${path}: top-level must be a mapping`);
@@ -129,14 +130,3 @@ function sortByPath(declarations) {
         return a.path < b.path ? -1 : 1;
     });
 }
-async function writeAtomic(path, content) {
-    const tempPath = `${path}.${randomBytes(8).toString('hex')}.tmp`;
-    await writeFile(tempPath, content, 'utf8');
-    try {
-        await rename(tempPath, path);
-    }
-    catch (error) {
-        await unlink(tempPath).catch(() => { });
-        throw error;
-    }
-}

package/dist/esm/vault-integrity/check-vault-integrity.js

@@ -6,7 +6,7 @@ export function checkVaultIntegrity(notes) {
 }
 function basenameFindings(vaultIndex) {
     const findings = [];
-    for (const key of [...vaultIndex.keys()].toSorted()) {
+    for (const key of vaultIndex.keys().toArray().toSorted()) {
         const paths = vaultIndex.get(key);
         if (paths === undefined || paths.size < 2)
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/kb",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Knowledge-base foundation: discovery, config, frontmatter parsing, records, tags, and vault-integrity checks",
   "keywords": [
     "frontmatter",
@@ -19,6 +19,7 @@
   },
   "license": "ISC",
   "author": "William Thorsen <william@thorsen.dev> (https://github.com/williamthorsen)",
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -96,6 +97,7 @@
     "dist"
   ],
   "dependencies": {
+    "@williamthorsen/toolbelt.errors": "0.5.0",
     "picomatch": "4.0.5",
     "yaml": "2.9.0",
     "zod": "4.4.3"
@@ -109,7 +111,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "nmr compile"
-  }
+  "scripts": {}
 }

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

@@ -1,3 +0,0 @@
-export { pathsFindings, type PathsNote } from './paths.js';
-export { tagAliasFindings, type TagAliasNote } from './tag-alias.js';
-export { taxonomyFindings, type TaxonomyNote } from './taxonomy.js';

package/dist/esm/lints/index.js

@@ -1,3 +0,0 @@
-export { pathsFindings } from "./paths.js";
-export { tagAliasFindings } from "./tag-alias.js";
-export { taxonomyFindings } from "./taxonomy.js";