kennel 0.2.31 → 0.2.33

package/dist/llm/clipboard.d.ts

@@ -0,0 +1 @@
+export declare function copyToClipboard(text: string): Promise<void>;

package/dist/llm/clipboard.js

@@ -0,0 +1,59 @@
+import { spawn } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+function onPath(command) {
+    return (process.env.PATH ?? '').split(delimiter).some((directory) => {
+        if (!directory)
+            return false;
+        try {
+            accessSync(join(directory, command), constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** The platform clipboard tool. No shell runs, so the text is never interpreted. */
+function clipboardTool() {
+    if (process.platform === 'darwin')
+        return { command: 'pbcopy', args: [], encoding: 'utf8' };
+    // clip.exe reads UTF-16LE text that starts with a byte order mark.
+    if (process.platform === 'win32')
+        return { command: 'clip', args: [], encoding: 'utf16le' };
+    if (process.env.WAYLAND_DISPLAY && onPath('wl-copy'))
+        return { command: 'wl-copy', args: [], encoding: 'utf8' };
+    if (process.env.DISPLAY && onPath('xclip'))
+        return { command: 'xclip', args: ['-selection', 'clipboard'], encoding: 'utf8' };
+    if (process.env.DISPLAY && onPath('xsel'))
+        return { command: 'xsel', args: ['--clipboard', '--input'], encoding: 'utf8' };
+    throw new Error('No clipboard tool is available. Install wl-copy (Wayland) or xclip or xsel (X11) in a desktop session, or run knl llm without --copy.');
+}
+export function copyToClipboard(text) {
+    const tool = clipboardTool();
+    const input = tool.encoding === 'utf16le' ? Buffer.from(`\ufeff${text}`, 'utf16le') : Buffer.from(text, 'utf8');
+    return new Promise((resolve, reject) => {
+        // stderr is inherited: wl-copy keeps serving the selection in a forked
+        // process, and a pipe it holds open would keep this command alive.
+        const child = spawn(tool.command, tool.args, { stdio: ['pipe', 'ignore', 'inherit'] });
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            reject(new Error(`${tool.command} did not finish within 10 seconds`));
+        }, 10_000);
+        child.once('error', (error) => {
+            clearTimeout(timer);
+            reject(new Error(`Cannot run ${tool.command}: ${error.message}`));
+        });
+        child.once('exit', (code, signal) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${tool.command} failed ${signal ? `with signal ${signal}` : `with exit code ${code}`}`));
+        });
+        child.stdin.on('error', () => {
+            // The exit status reports the failure.
+        });
+        child.stdin.end(input);
+    });
+}

package/dist/llm/command.d.ts

@@ -0,0 +1 @@
+export declare function llm(args: string[]): Promise<void>;

package/dist/llm/command.js

@@ -0,0 +1,226 @@
+import { fork } from 'node:child_process';
+import { realpathSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const TIMEOUT_MS = 60_000;
+const LLM_USAGE = `Usage:
+  knl llm [folder] [--profile <name>|--no-instructions] [--no-plugins] [--copy]
+  knl llm --folder <path> [options]
+  knl llm full [--folder <path>] [options]
+  knl llm [--folder <path>] --depth <count> [options]
+  knl llm --help
+
+Prints only applicable AGENTS.md, personal instructions, and the research
+write destination. The folder defaults to the current directory. Startup
+reads registered workspace configs without scanning notes or the project catalog.
+Folders inside the configured Raggle base repository (rgl base) omit the
+generated write destination and linked repository context. Elsewhere, the
+destination is an explicit Raggle notes link when one exists; otherwise,
+with repositoryNotes enabled in the Kennel user config, it is the repository
+notes folder (kennel notes path), looked up read-only: startup registers nothing.
+
+  full                 Add folder details and plugin sections; outside the base,
+                       also add all links and local subpaths.
+  --depth <count>      Add links and plugin sections, limited to a positive graph depth.
+  --profile <name>     Use this personal instruction profile.
+  --no-instructions    Omit personal profiles, all inlined instruction files, and the
+                       generated write destination. Expanded modes can still include
+                       graph paths and plugin context.
+  --no-plugins         Omit plugins in expanded modes. Startup never loads plugins.
+  --copy               Copy the message to the clipboard instead of printing it.
+
+Use --folder ./full for a folder named full. Use knl llm full for plugin
+context from the pinned build; refresh it with \`kennel plugin add <source>\`.
+`;
+function usageError(message) {
+    throw new Error(`${message}\nRun knl llm --help for usage.`);
+}
+/** Strict argument parser: unknown, repeated, or conflicting input fails. */
+function parseLlmArgs(args) {
+    const options = { help: false, includeInstructions: true, includePlugins: true, copy: false };
+    const seen = new Set();
+    const once = (name) => {
+        if (seen.has(name))
+            usageError(`Use ${name} once`);
+        seen.add(name);
+    };
+    const positionals = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const equals = arg.startsWith('--') ? arg.indexOf('=') : -1;
+        const name = equals === -1 ? arg : arg.slice(0, equals);
+        const inline = equals === -1 ? undefined : arg.slice(equals + 1);
+        const value = (label) => {
+            const next = inline ?? args[++index];
+            if (next === undefined || next === '' || (inline === undefined && next.startsWith('-'))) {
+                usageError(`${name} requires ${label}`);
+            }
+            return next;
+        };
+        const flag = () => {
+            if (inline !== undefined)
+                usageError(`${name} does not take a value`);
+            once(name);
+        };
+        if (name === '-h' || name === '--help') {
+            options.help = true;
+        }
+        else if (name === '--folder') {
+            once(name);
+            options.folder = value('a folder path');
+        }
+        else if (name === '--depth') {
+            once(name);
+            const count = value('a positive count');
+            if (!/^[1-9][0-9]{0,8}$/u.test(count))
+                usageError(`--depth must be a positive integer: ${count}`);
+            options.depth = Number(count);
+        }
+        else if (name === '--profile') {
+            once(name);
+            options.profile = value('a profile name');
+        }
+        else if (name === '--no-instructions') {
+            flag();
+            options.includeInstructions = false;
+        }
+        else if (name === '--no-plugins') {
+            flag();
+            options.includePlugins = false;
+        }
+        else if (name === '--copy') {
+            flag();
+            options.copy = true;
+        }
+        else if (arg.startsWith('-')) {
+            usageError(`Unknown option: ${arg}`);
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    if (options.help)
+        return options;
+    if (positionals[0] === 'full') {
+        positionals.shift();
+        if (options.depth !== undefined)
+            usageError('Use either full or --depth, not both');
+        options.depth = 'full';
+    }
+    if (positionals.length > 1)
+        usageError(`Unexpected argument: ${positionals[1]}`);
+    if (positionals.length === 1) {
+        if (options.folder !== undefined)
+            usageError('Give the folder once: as an argument or with --folder');
+        options.folder = positionals[0];
+    }
+    if (options.profile !== undefined && !options.includeInstructions) {
+        usageError('--profile cannot be combined with --no-instructions');
+    }
+    return options;
+}
+function resolveFolder(input) {
+    let folder;
+    try {
+        folder = realpathSync(resolve(input));
+    }
+    catch {
+        throw new Error(`Folder does not exist: ${input}`);
+    }
+    if (!statSync(folder).isDirectory())
+        throw new Error(`Not a folder: ${input}. knl llm needs a folder.`);
+    return folder;
+}
+class Interrupted extends Error {
+}
+/** Runs one bounded generation in a child process and returns its message. */
+function generate(request) {
+    return new Promise((resolvePromise, reject) => {
+        const child = fork(fileURLToPath(new URL('./worker.js', import.meta.url)), [JSON.stringify(request)], {
+            env: { ...process.env, NODE_OPTIONS: '' },
+            execArgv: [],
+            // Optional catalog/plugin logs are not startup output. Failures arrive over IPC.
+            stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+        });
+        let stage = 'context generation';
+        let settled = false;
+        const finish = (error, text) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            process.off('SIGINT', interrupt);
+            process.off('SIGTERM', interrupt);
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill('SIGKILL');
+            if (error)
+                reject(error);
+            else
+                resolvePromise(text);
+        };
+        const interrupt = () => finish(new Interrupted('Cancelled. No context was printed or copied.'));
+        const timer = setTimeout(() => {
+            finish(new Error(`Context generation timed out after ${TIMEOUT_MS / 1000} seconds during ${stage}. No context was printed or copied.`));
+        }, TIMEOUT_MS);
+        process.once('SIGINT', interrupt);
+        process.once('SIGTERM', interrupt);
+        child.on('message', (message) => {
+            if (message?.type === 'stage' && typeof message.stage === 'string') {
+                stage = message.stage;
+            }
+            else if (message?.type === 'result' && message.ok && typeof message.text === 'string') {
+                finish(undefined, message.text);
+            }
+            else if (message?.type === 'result' && !message.ok) {
+                finish(new Error(String(message.error)));
+            }
+            else {
+                finish(new Error('The context worker sent an invalid message'));
+            }
+        });
+        child.once('error', (error) => finish(new Error(`Cannot start the context worker: ${error.message}`)));
+        child.once('exit', (code, signal) => {
+            // A terminal Ctrl+C reaches the worker too, sometimes before this process.
+            if (signal === 'SIGINT' || signal === 'SIGTERM')
+                return interrupt();
+            finish(new Error(`The context worker stopped during ${stage} (${signal ? `signal ${signal}` : `exit code ${code}`}) without a result`));
+        });
+    });
+}
+export async function llm(args) {
+    const options = parseLlmArgs(args);
+    if (options.help) {
+        process.stdout.write(LLM_USAGE);
+        return;
+    }
+    const folder = resolveFolder(options.folder ?? '.');
+    let text;
+    try {
+        text = await generate({
+            folder,
+            ...(options.depth !== undefined ? { depth: options.depth } : {}),
+            ...(options.profile !== undefined ? { profile: options.profile } : {}),
+            includeInstructions: options.includeInstructions,
+            includePlugins: options.includePlugins,
+        });
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = error instanceof Interrupted ? 130 : 1;
+        return;
+    }
+    if (options.copy) {
+        const { copyToClipboard } = await import('./clipboard.js');
+        try {
+            await copyToClipboard(text);
+        }
+        catch (error) {
+            console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = 1;
+            return;
+        }
+        console.error(`Copied the LLM context for ${folder} to the clipboard (${Buffer.byteLength(text, 'utf8')} bytes).`);
+        return;
+    }
+    process.stdout.write(text);
+}

package/dist/llm/worker.d.ts

@@ -0,0 +1,19 @@
+export type WorkerRequest = {
+    folder: string;
+    depth?: number | 'full';
+    profile?: string;
+    includeInstructions: boolean;
+    includePlugins: boolean;
+};
+export type WorkerMessage = {
+    type: 'stage';
+    stage: string;
+} | {
+    type: 'result';
+    ok: true;
+    text: string;
+} | {
+    type: 'result';
+    ok: false;
+    error: string;
+};