kennel 0.1.8 → 0.1.9

package/dist/site/renderers.d.ts

@@ -0,0 +1,61 @@
+import type { ChildCommand } from '../shared/process.js';
+export type PackageJson = {
+    name?: string;
+    scripts?: Record<string, string>;
+    dependencies?: Record<string, unknown>;
+    devDependencies?: Record<string, unknown>;
+    peerDependencies?: Record<string, unknown>;
+    optionalDependencies?: Record<string, unknown>;
+};
+export type SitePlatform = 'vitepress' | 'quartz' | 'script';
+export type RendererCapabilities = {
+    accessControl: boolean;
+    backlinks: boolean;
+    graph: boolean;
+    llms: boolean;
+    mcp: boolean;
+    search: boolean;
+    staticOutput: boolean;
+};
+export type RendererDeploymentDescriptor = {
+    capabilities: RendererCapabilities;
+    cleanUrls: boolean;
+    outputDirectory: string;
+    platform: SitePlatform;
+};
+export type RendererAdapter = {
+    buildCommand(root: string, pkg: PackageJson): ChildCommand;
+    capabilities: RendererCapabilities;
+    cleanUrls: boolean;
+    detect(root: string, pkg: PackageJson): boolean;
+    devCommand(root: string, options: {
+        script: string | null;
+    }, scriptArgs: string[], toolRoot?: string): ChildCommand;
+    outputDirectory(root: string): string;
+    platform: SitePlatform;
+};
+export declare function vitepressConfig(root: string): string | null;
+export declare function vitepressOutputDirectory(root: string): string;
+export declare function quartzConfig(root: string): string | null;
+export declare function quartzOutputDirectory(root: string): string;
+export declare function displayBasePath(config: {
+    base?: unknown;
+}): string;
+export declare function buildScriptDevCommand(root: string, pkg: PackageJson, options: {
+    script: string | null;
+}, scriptArgs: string[]): ChildCommand;
+export declare function buildVitePressDevCommand(root: string, _options: {
+    script: string | null;
+}, scriptArgs: string[], toolRoot?: string): ChildCommand;
+export declare function buildQuartzDevCommand(root: string, _options: {
+    script: string | null;
+}, scriptArgs: string[], toolRoot?: string): ChildCommand;
+export declare const rendererRegistry: RendererAdapter[];
+export declare function rendererFor(root: string, pkg: PackageJson): RendererAdapter;
+export declare function detectedPlatform(root: string, pkg: PackageJson): SitePlatform;
+export declare function rendererDeploymentDescriptor(root: string, pkg?: PackageJson): RendererDeploymentDescriptor;
+export declare function siteOutputDirectory(root: string, pkg?: PackageJson): string;
+export declare function rendererDevCommand(root: string, pkg: PackageJson, platform: SitePlatform, options: {
+    script: string | null;
+}, scriptArgs: string[], toolRoot?: string): ChildCommand;
+export declare function rendererBuildCommand(root: string, pkg: PackageJson): ChildCommand;

package/dist/site/renderers.js

@@ -0,0 +1,219 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { hasDependency, localBin, packageManagerFor, runArgsFor } from '../shared/package-manager.js';
+function rendererCapabilities(capabilities) {
+    return capabilities;
+}
+export function vitepressConfig(root) {
+    const configNames = [
+        '.vitepress/config.mts',
+        '.vitepress/config.ts',
+        '.vitepress/config.mjs',
+        '.vitepress/config.js',
+        'docs/.vitepress/config.mts',
+        'docs/.vitepress/config.ts',
+        'docs/.vitepress/config.mjs',
+        'docs/.vitepress/config.js',
+    ];
+    return configNames.find((configName) => existsSync(join(root, configName))) ?? null;
+}
+export function vitepressOutputDirectory(root) {
+    const configPath = vitepressConfig(root);
+    if (configPath?.startsWith('docs/'))
+        return 'docs/.vitepress/dist';
+    return '.vitepress/dist';
+}
+export function quartzConfig(root) {
+    const configNames = [
+        'quartz.config.ts',
+        'quartz.config.js',
+        'docs/quartz.config.ts',
+        'docs/quartz.config.js',
+    ];
+    return configNames.find((configName) => existsSync(join(root, configName))) ?? null;
+}
+export function quartzOutputDirectory(root) {
+    const configPath = quartzConfig(root);
+    if (configPath?.startsWith('docs/'))
+        return 'docs/public';
+    return 'public';
+}
+export function displayBasePath(config) {
+    if (typeof config.base !== 'string' || config.base.trim() === '')
+        return '/';
+    const base = config.base.trim();
+    const normalized = base.replace(/^\/+|\/+$/g, '');
+    if (!normalized)
+        return '/';
+    return `/${normalized}/`;
+}
+export function buildScriptDevCommand(root, pkg, options, scriptArgs) {
+    const scripts = pkg.scripts ?? {};
+    const script = options.script ?? (scripts['docs:dev'] ? 'docs:dev' : 'dev');
+    if (typeof scripts[script] !== 'string') {
+        throw new Error(`${join(root, 'package.json')} does not define script "${script}"`);
+    }
+    const packageManager = packageManagerFor(root);
+    return {
+        command: packageManager,
+        args: runArgsFor(packageManager, script, scriptArgs),
+    };
+}
+export function buildVitePressDevCommand(root, _options, scriptArgs, toolRoot = root) {
+    const siteRoot = toolRoot === root ? '.' : root;
+    const vitepress = localBin(toolRoot, 'vitepress');
+    if (vitepress) {
+        const args = ['dev', siteRoot];
+        args.push(...scriptArgs);
+        return { command: vitepress, args, cwd: toolRoot };
+    }
+    const packageManager = packageManagerFor(toolRoot);
+    if (packageManager === 'npm') {
+        const args = ['exec', '--', 'vitepress', 'dev', siteRoot];
+        args.push(...scriptArgs);
+        return { command: packageManager, args, cwd: toolRoot };
+    }
+    const args = ['x', 'vitepress', 'dev', siteRoot];
+    args.push(...scriptArgs);
+    return { command: packageManager, args, cwd: toolRoot };
+}
+export function buildQuartzDevCommand(root, _options, scriptArgs, toolRoot = root) {
+    const scriptsRoot = toolRoot === root ? '.' : root;
+    const quartz = localBin(toolRoot, 'quartz');
+    if (quartz) {
+        const args = ['build', '--serve', '--directory', scriptsRoot];
+        args.push(...scriptArgs);
+        return { command: quartz, args, cwd: toolRoot };
+    }
+    const packageManager = packageManagerFor(toolRoot);
+    if (packageManager === 'npm') {
+        const args = ['exec', '--', 'quartz', 'build', '--serve', '--directory', scriptsRoot];
+        args.push(...scriptArgs);
+        return { command: packageManager, args, cwd: toolRoot };
+    }
+    const args = ['x', 'quartz', 'build', '--serve', '--directory', scriptsRoot];
+    args.push(...scriptArgs);
+    return { command: packageManager, args, cwd: toolRoot };
+}
+function buildVitePressCommand(root, _pkg) {
+    const packageManager = packageManagerFor(root);
+    const vitepress = localBin(root, 'vitepress');
+    if (vitepress)
+        return { command: vitepress, args: ['build', '.'] };
+    if (packageManager === 'npm')
+        return { command: packageManager, args: ['exec', '--', 'vitepress', 'build', '.'] };
+    return { command: packageManager, args: ['x', 'vitepress', 'build', '.'] };
+}
+function buildQuartzCommand(root, _pkg) {
+    const packageManager = packageManagerFor(root);
+    const quartz = localBin(root, 'quartz');
+    const directory = quartzConfig(root)?.startsWith('docs/') ? 'docs' : '.';
+    if (quartz)
+        return { command: quartz, args: ['build', '--directory', directory] };
+    if (packageManager === 'npm')
+        return { command: packageManager, args: ['exec', '--', 'quartz', 'build', '--directory', directory] };
+    return { command: packageManager, args: ['x', 'quartz', 'build', '--directory', directory] };
+}
+function buildScriptCommand(root, pkg) {
+    const scripts = pkg.scripts ?? {};
+    const packageManager = packageManagerFor(root);
+    if (typeof scripts['docs:build'] === 'string') {
+        return { command: packageManager, args: runArgsFor(packageManager, 'docs:build', []) };
+    }
+    if (typeof scripts.build === 'string') {
+        return { command: packageManager, args: runArgsFor(packageManager, 'build', []) };
+    }
+    return buildVitePressCommand(root, pkg);
+}
+export const rendererRegistry = [
+    {
+        buildCommand: buildVitePressCommand,
+        capabilities: rendererCapabilities({
+            accessControl: true,
+            backlinks: false,
+            graph: false,
+            llms: true,
+            mcp: true,
+            search: true,
+            staticOutput: true,
+        }),
+        cleanUrls: true,
+        detect: (root, pkg) => Boolean(vitepressConfig(root)) || hasDependency(pkg, 'vitepress'),
+        devCommand: buildVitePressDevCommand,
+        outputDirectory: vitepressOutputDirectory,
+        platform: 'vitepress',
+    },
+    {
+        buildCommand: buildQuartzCommand,
+        capabilities: rendererCapabilities({
+            accessControl: true,
+            backlinks: true,
+            graph: true,
+            llms: false,
+            mcp: true,
+            search: true,
+            staticOutput: true,
+        }),
+        cleanUrls: false,
+        detect: (root, pkg) => Boolean(quartzConfig(root)) || hasDependency(pkg, '@jackyzha0/quartz'),
+        devCommand: buildQuartzDevCommand,
+        outputDirectory: quartzOutputDirectory,
+        platform: 'quartz',
+    },
+    {
+        buildCommand: buildScriptCommand,
+        capabilities: rendererCapabilities({
+            accessControl: true,
+            backlinks: false,
+            graph: false,
+            llms: false,
+            mcp: true,
+            search: false,
+            staticOutput: true,
+        }),
+        cleanUrls: false,
+        detect: () => true,
+        devCommand: () => {
+            throw new Error('script dev commands require package.json and must use buildScriptDevCommand');
+        },
+        outputDirectory: () => 'dist',
+        platform: 'script',
+    },
+];
+export function rendererFor(root, pkg) {
+    return rendererRegistry.find((renderer) => renderer.detect(root, pkg)) ?? rendererRegistry.at(-1);
+}
+export function detectedPlatform(root, pkg) {
+    return rendererFor(root, pkg).platform;
+}
+export function rendererDeploymentDescriptor(root, pkg) {
+    const renderer = pkg
+        ? rendererFor(root, pkg)
+        : rendererRegistry.find((entry) => entry.platform !== 'script' && entry.detect(root, {})) ?? rendererRegistry.at(-1);
+    return {
+        capabilities: renderer.capabilities,
+        cleanUrls: renderer.cleanUrls,
+        outputDirectory: renderer.outputDirectory(root),
+        platform: renderer.platform,
+    };
+}
+export function siteOutputDirectory(root, pkg) {
+    return rendererDeploymentDescriptor(root, pkg).outputDirectory;
+}
+export function rendererDevCommand(root, pkg, platform, options, scriptArgs, toolRoot = root) {
+    if (platform === 'script')
+        return buildScriptDevCommand(root, pkg, options, scriptArgs);
+    return rendererRegistry.find((renderer) => renderer.platform === platform)?.devCommand(root, options, scriptArgs, toolRoot)
+        ?? buildScriptDevCommand(root, pkg, options, scriptArgs);
+}
+export function rendererBuildCommand(root, pkg) {
+    const scripts = pkg.scripts ?? {};
+    const packageManager = packageManagerFor(root);
+    if (typeof scripts['docs:build'] === 'string') {
+        return { command: packageManager, args: runArgsFor(packageManager, 'docs:build', []) };
+    }
+    if (typeof scripts.build === 'string') {
+        return { command: packageManager, args: runArgsFor(packageManager, 'build', []) };
+    }
+    return rendererFor(root, pkg).buildCommand(root, pkg);
+}

package/dist/site/viewer.d.ts

@@ -0,0 +1,9 @@
+export type ViewerOptions = {
+    host: string;
+    lan: boolean;
+    root: string;
+    port: string;
+    tailscale: boolean;
+};
+export declare function splitViewerArgs(input: string[]): ViewerOptions;
+export declare function viewer(input: string[]): Promise<void>;

package/dist/site/viewer.js

@@ -0,0 +1,192 @@
+import { createServer } from 'node:http';
+import { execFile, execFileSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, extname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFolder } from '@raggle-ai/barkdown/node';
+const mime = {
+    '.css': 'text/css; charset=utf-8',
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+};
+export function splitViewerArgs(input) {
+    let hasHost = false;
+    let hasRoot = false;
+    const options = {
+        host: '127.0.0.1',
+        lan: false,
+        root: process.cwd(),
+        port: '5173',
+        tailscale: false,
+    };
+    for (let index = 0; index < input.length; index += 1) {
+        const arg = input[index];
+        if (arg === '--port') {
+            options.port = input[index + 1] ?? '';
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--port=')) {
+            options.port = arg.slice('--port='.length);
+            continue;
+        }
+        if (arg === '--host') {
+            options.host = input[index + 1] ?? '';
+            hasHost = true;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--host=')) {
+            options.host = arg.slice('--host='.length);
+            hasHost = true;
+            continue;
+        }
+        if (arg === '--lan') {
+            options.lan = true;
+            continue;
+        }
+        if (arg === '--tailscale') {
+            options.tailscale = true;
+            continue;
+        }
+        if (arg.startsWith('-'))
+            throw new Error(`Unknown viewer option: ${arg}`);
+        if (hasRoot)
+            throw new Error('kennel accepts one folder');
+        options.root = resolve(arg);
+        hasRoot = true;
+    }
+    if (!options.port || !/^\d+$/.test(options.port)) {
+        throw new Error('kennel requires a numeric port');
+    }
+    if (!options.host)
+        throw new Error('kennel requires a host');
+    if ((options.lan || options.tailscale) && hasHost) {
+        throw new Error('kennel does not accept --host with --lan or --tailscale');
+    }
+    if (options.lan && options.tailscale) {
+        throw new Error('kennel accepts one remote access mode');
+    }
+    if (options.lan)
+        options.host = lanHost();
+    if (!existsSync(options.root) || !statSync(options.root).isDirectory()) {
+        throw new Error(`Folder not found: ${options.root}`);
+    }
+    return options;
+}
+function lanHost() {
+    const route = execFileSync('/sbin/route', ['-n', 'get', 'default'], { encoding: 'utf8' });
+    const device = route.match(/interface:\s+(\S+)/)?.[1];
+    if (!device)
+        throw new Error('kennel could not find the local network interface');
+    const host = execFileSync('/usr/sbin/ipconfig', ['getifaddr', device], {
+        encoding: 'utf8',
+    }).trim();
+    if (!host)
+        throw new Error(`kennel could not find an address for ${device}`);
+    return host;
+}
+function tailscaleHost() {
+    const status = JSON.parse(execFileSync('tailscale', ['status', '--json'], { encoding: 'utf8' }));
+    const host = typeof status.Self?.DNSName === 'string' ? status.Self.DNSName.replace(/\.$/, '') : '';
+    if (host)
+        return host;
+    throw new Error('kennel could not find the Tailscale DNS name');
+}
+export async function viewer(input) {
+    const options = splitViewerArgs(input);
+    const web = resolve(dirname(fileURLToPath(import.meta.url)), '../../web');
+    if (!existsSync(resolve(web, 'index.html'))) {
+        throw new Error(`Kennel web app not found. Run the CLI build first.`);
+    }
+    const server = createServer(async (request, response) => {
+        try {
+            const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+            if (url.pathname === '/api/health') {
+                response.writeHead(200, {
+                    'Cache-Control': 'no-store',
+                    'Content-Type': 'application/json; charset=utf-8',
+                });
+                response.end(JSON.stringify({ root: options.root }));
+                return;
+            }
+            if (url.pathname === '/api/documents') {
+                const root = resolve(url.searchParams.get('path') ?? options.root);
+                const body = JSON.stringify(await readFolder(root));
+                response.writeHead(200, {
+                    'Cache-Control': 'no-store',
+                    'Content-Type': 'application/json; charset=utf-8',
+                });
+                response.end(body);
+                return;
+            }
+            if (url.pathname === '/api/open-folder' && request.method === 'POST') {
+                const root = resolve(url.searchParams.get('path') ?? options.root);
+                if (!existsSync(root) || !statSync(root).isDirectory()) {
+                    response.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+                    response.end(`Folder not found: ${root}`);
+                    return;
+                }
+                execFile('/usr/bin/open', [root], (error) => {
+                    if (error) {
+                        response.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+                        response.end('Could not open folder');
+                        return;
+                    }
+                    response.writeHead(204);
+                    response.end();
+                });
+                return;
+            }
+            const requested = url.pathname === '/' ? 'index.html' : decodeURIComponent(url.pathname.slice(1));
+            const path = resolve(web, requested);
+            const escaped = relative(web, path).startsWith('..');
+            if (escaped) {
+                response.writeHead(404);
+                response.end('Not found');
+                return;
+            }
+            const appRoute = !extname(path);
+            const file = appRoute ? resolve(web, 'index.html') : path;
+            const body = await readFile(file);
+            response.writeHead(200, {
+                'Cache-Control': appRoute || file.endsWith('index.html') ? 'no-store' : 'public, max-age=3600',
+                'Content-Type': mime[extname(file)] ?? 'application/octet-stream',
+            });
+            response.end(body);
+        }
+        catch (error) {
+            if (response.headersSent) {
+                response.destroy(error instanceof Error ? error : undefined);
+                return;
+            }
+            response.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+            response.end(error instanceof Error ? error.message : 'Not found');
+        }
+    });
+    await new Promise((done, fail) => {
+        server.once('error', fail);
+        server.listen(Number(options.port), options.host, done);
+    });
+    console.log(`Reading documents from ${options.root}`);
+    if (options.tailscale) {
+        execFileSync('tailscale', ['serve', '--bg', '--yes', options.port]);
+        console.log(`Kennel is running at https://${tailscaleHost()}`);
+    }
+    else {
+        console.log(`Kennel is running at http://${options.host}:${options.port}`);
+    }
+    console.log('Press Ctrl+C to stop.');
+    const close = () => server.close();
+    process.once('SIGINT', close);
+    process.once('SIGTERM', close);
+    await new Promise((done) => server.once('close', done));
+    if (options.tailscale) {
+        execFileSync('tailscale', ['serve', '--https=443', 'off']);
+    }
+}

package/dist/site/vitepress.d.ts

@@ -1,21 +1 @@
-import type { ChildCommand } from '../shared/process.js';
-export type PackageJson = {
-    name?: string;
-    scripts?: Record<string, string>;
-    dependencies?: Record<string, unknown>;
-    devDependencies?: Record<string, unknown>;
-    peerDependencies?: Record<string, unknown>;
-    optionalDependencies?: Record<string, unknown>;
-};
-export declare function vitepressConfig(root: string): string | null;
-export declare function vitepressOutputDirectory(root: string): string;
-export declare function detectedPlatform(root: string, pkg: PackageJson): 'vitepress' | 'script';
-export declare function displayBasePath(config: {
-    base?: unknown;
-}): string;
-export declare function buildScriptDevCommand(root: string, pkg: PackageJson, options: {
-    script: string | null;
-}, scriptArgs: string[]): ChildCommand;
-export declare function buildVitePressDevCommand(root: string, _options: {
-    script: string | null;
-}, scriptArgs: string[], toolRoot?: string): ChildCommand;
+export * from './renderers.js';

package/dist/site/vitepress.js

@@ -1,66 +1 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { hasDependency, localBin, packageManagerFor, runArgsFor } from '../shared/package-manager.js';
-export function vitepressConfig(root) {
-    const configNames = [
-        '.vitepress/config.mts',
-        '.vitepress/config.ts',
-        '.vitepress/config.mjs',
-        '.vitepress/config.js',
-        'docs/.vitepress/config.mts',
-        'docs/.vitepress/config.ts',
-        'docs/.vitepress/config.mjs',
-        'docs/.vitepress/config.js',
-    ];
-    return configNames.find((configName) => existsSync(join(root, configName))) ?? null;
-}
-export function vitepressOutputDirectory(root) {
-    const configPath = vitepressConfig(root);
-    if (configPath?.startsWith('docs/'))
-        return 'docs/.vitepress/dist';
-    return '.vitepress/dist';
-}
-export function detectedPlatform(root, pkg) {
-    if (vitepressConfig(root) || hasDependency(pkg, 'vitepress'))
-        return 'vitepress';
-    return 'script';
-}
-export function displayBasePath(config) {
-    if (typeof config.base !== 'string' || config.base.trim() === '')
-        return '/';
-    const base = config.base.trim();
-    const normalized = base.replace(/^\/+|\/+$/g, '');
-    if (!normalized)
-        return '/';
-    return `/${normalized}/`;
-}
-export function buildScriptDevCommand(root, pkg, options, scriptArgs) {
-    const scripts = pkg.scripts ?? {};
-    const script = options.script ?? (scripts['docs:dev'] ? 'docs:dev' : 'dev');
-    if (typeof scripts[script] !== 'string') {
-        throw new Error(`${join(root, 'package.json')} does not define script "${script}"`);
-    }
-    const packageManager = packageManagerFor(root);
-    return {
-        command: packageManager,
-        args: runArgsFor(packageManager, script, scriptArgs),
-    };
-}
-export function buildVitePressDevCommand(root, _options, scriptArgs, toolRoot = root) {
-    const siteRoot = toolRoot === root ? '.' : root;
-    const vitepress = localBin(toolRoot, 'vitepress');
-    if (vitepress) {
-        const args = ['dev', siteRoot];
-        args.push(...scriptArgs);
-        return { command: vitepress, args, cwd: toolRoot };
-    }
-    const packageManager = packageManagerFor(toolRoot);
-    if (packageManager === 'npm') {
-        const args = ['exec', '--', 'vitepress', 'dev', siteRoot];
-        args.push(...scriptArgs);
-        return { command: packageManager, args, cwd: toolRoot };
-    }
-    const args = ['x', 'vitepress', 'dev', siteRoot];
-    args.push(...scriptArgs);
-    return { command: packageManager, args, cwd: toolRoot };
-}
+export * from './renderers.js';

package/dist/sources/commands.d.ts

@@ -0,0 +1 @@
+export declare function sourceCommand(input: string[]): void;

package/dist/sources/commands.js

@@ -0,0 +1,88 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { collectMcpData } from '@raggle-ai/kennel-mcp/data';
+import { mcpDataConfig } from '../mcp/config.js';
+import { readJson } from '../shared/json.js';
+import { projectConfigPath } from '../shared/project-config.js';
+export function sourceCommand(input) {
+    const [commandValue, ...args] = input;
+    if (!isSourceCommand(commandValue))
+        throw new Error(`Unknown source command: ${commandValue ?? ''}`);
+    const options = parseSourceArgs(commandValue, args);
+    const configPath = projectConfigPath(options.targetPath, options.configFile);
+    const root = dirname(configPath);
+    const config = readJson(configPath);
+    const data = collectMcpData(root, mcpDataConfig(config));
+    if (commandValue === 'list')
+        return print(data.sources, options.json);
+    if (commandValue === 'describe') {
+        const source = sourceById(data.sources, options.id);
+        return print({ source, records: data.records.filter((record) => record.sourceId === source.id) }, options.json);
+    }
+    if (commandValue === 'query') {
+        sourceById(data.sources, options.id);
+        return print(data.records.filter((record) => record.sourceId === options.id).slice(0, options.limit), options.json);
+    }
+    if (commandValue === 'doctor') {
+        const sources = data.sources.map((source) => {
+            const actualRecordCount = data.records.filter((record) => record.sourceId === source.id).length;
+            return {
+                ...source,
+                actualRecordCount,
+                ok: source.healthy && (source.recordCount === undefined || source.recordCount === actualRecordCount),
+            };
+        });
+        return print({ ok: sources.every((source) => source.ok), sources }, options.json);
+    }
+    const target = join(root, '.kennel', 'generated', 'source-snapshot.json');
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, `${JSON.stringify({ records: data.records, sources: data.sources }, null, 2)}\n`);
+    console.log(options.json ? JSON.stringify({ path: target }) : target);
+}
+function parseSourceArgs(command, input) {
+    const positional = [];
+    let configFile = 'raggle.json';
+    let json = false;
+    let limit = 50;
+    for (let index = 0; index < input.length; index += 1) {
+        const arg = input[index] ?? '';
+        if (arg === '--config') {
+            configFile = input[index + 1] ?? '';
+            index += 1;
+            continue;
+        }
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+        if (arg === '--limit') {
+            limit = Math.max(1, Number(input[index + 1] ?? 50));
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('-'))
+            throw new Error(`Unknown source option: ${arg}`);
+        positional.push(arg);
+    }
+    const needsId = command === 'describe' || command === 'query';
+    const id = needsId ? positional.shift() ?? '' : '';
+    if (needsId && !id)
+        throw new Error(`source ${command} requires a source ID`);
+    return { configFile, id, json, limit, targetPath: positional[0] ?? '.' };
+}
+function sourceById(sources, id) {
+    const source = sources.find((entry) => entry.id === id);
+    if (!source)
+        throw new Error(`Knowledge source not found: ${id}`);
+    return source;
+}
+function print(value, json) {
+    if (json) {
+        console.log(JSON.stringify(value));
+        return;
+    }
+    console.log(JSON.stringify(value, null, 2));
+}
+function isSourceCommand(value) {
+    return value === 'describe' || value === 'doctor' || value === 'list' || value === 'query' || value === 'snapshot';
+}