@v1nvn/agentic-core 0.45.0 → 0.46.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@v1nvn/agentic-core",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "Shared source home for the @v1nvn agent tools — runtime helpers and the drawing kit every process-side surface imports.",
   "type": "module",
-  "main": "./src/index.ts",
+  "main": "./src/index.js",
   "exports": {
-    ".": "./src/index.ts",
-    "./draw": "./src/draw.ts",
-    "./vite": "./src/vite.ts"
+    ".": "./src/index.js",
+    "./draw": "./src/draw.js",
+    "./vite": "./src/vite.js"
   },
   "scripts": {
     "test": "vitest run",

package/src/cli.js

@@ -0,0 +1,194 @@
+import { Command, InvalidArgumentError, Option } from 'commander';
+import { describeError } from "./mcp.js";
+// A --help ask caught mid-parse: the parse doors return it instead of exiting,
+// and runCli answers it (the help payload) on stdout with 0.
+export class HelpRequested extends Error {
+    command;
+    constructor(command) {
+        super(`${command.name()} --help`);
+        this.command = command;
+    }
+}
+function addOption(cmd, option) {
+    const bare = option.env === undefined &&
+        option.choices === undefined &&
+        option.default === undefined &&
+        option.parse === undefined;
+    if (bare) {
+        cmd.option(option.flags, option.description);
+        return;
+    }
+    const built = new Option(option.flags, option.description);
+    if (option.env !== undefined) {
+        built.env(option.env);
+    }
+    if (option.choices !== undefined) {
+        built.choices(option.choices);
+    }
+    if (option.default !== undefined) {
+        built.default(option.default);
+    }
+    const { parse } = option;
+    if (parse !== undefined) {
+        // A plain Error from a parse fn skips commander's exitOverride, which is
+        // what records the subcommand for the usage print — wrap it so it rides.
+        built.argParser((value) => {
+            try {
+                return parse(value);
+            }
+            catch (err) {
+                if (err.code === 'commander.invalidArgument') {
+                    throw err;
+                }
+                throw new InvalidArgumentError(describeError(err));
+            }
+        });
+    }
+    cmd.addOption(built);
+}
+function wire(cmd, spec, program, isRoot, sink) {
+    if (spec.description !== undefined) {
+        cmd.description(spec.description);
+    }
+    if (spec.argument !== undefined) {
+        cmd.argument(spec.argument.flags, spec.argument.description);
+    }
+    for (const option of spec.options ?? []) {
+        addOption(cmd, option);
+    }
+    if (isRoot && spec.version !== undefined) {
+        cmd.option('-V, --version', 'print the version and exit');
+    }
+    cmd.action((...all) => {
+        const options = all.at(-2);
+        const command = all.at(-1);
+        sink?.({
+            command: isRoot ? undefined : spec.name,
+            options,
+            args: command.args,
+            root: program.opts(),
+        });
+    });
+    for (const sub of spec.commands ?? []) {
+        const child = new Command(sub.name);
+        wire(child, sub, program, false, sink);
+        cmd.addCommand(child);
+    }
+}
+function materialize(spec, sink) {
+    const program = new Command(spec.name);
+    wire(program, spec, program, true, sink);
+    return program;
+}
+export function buildCli(spec) {
+    return materialize(spec);
+}
+function quiet(command, onUsageError) {
+    command.configureOutput({
+        writeOut: () => undefined,
+        writeErr: () => undefined,
+    });
+    command.exitOverride(err => {
+        const code = err.code;
+        if (code === 'commander.help' || code === 'commander.helpDisplayed') {
+            throw new HelpRequested(command);
+        }
+        onUsageError(command);
+        throw err;
+    });
+    command.commands.forEach(c => {
+        quiet(c, onUsageError);
+    });
+}
+export function parseCli(spec, argv, onHelp, onUsageError) {
+    let invocation;
+    const program = materialize(spec, found => {
+        invocation = found;
+    });
+    let errored;
+    quiet(program, command => {
+        errored = command;
+    });
+    try {
+        program.parse([...argv], { from: 'user' });
+    }
+    catch (err) {
+        if (!(err instanceof HelpRequested)) {
+            if (errored !== undefined) {
+                const cause = err instanceof Error ? err : new Error(String(err));
+                onUsageError?.(errored, cause);
+            }
+            return undefined;
+        }
+        return onHelp !== undefined
+            ? onHelp(err.command.name(), err.command.helpInformation())
+            : err;
+    }
+    return invocation;
+}
+export function helpTextFor(spec, topic) {
+    const program = materialize(spec);
+    const command = topic === spec.name
+        ? program
+        : program.commands.find(c => c.name() === topic);
+    if (command === undefined) {
+        throw new Error(`no '${topic}' command to describe`);
+    }
+    return command.helpInformation();
+}
+function usageError(spec, topic, message) {
+    if (message !== undefined) {
+        // Commander 15 builds its messages with the 'error: ' prefix already in.
+        process.stderr.write(`${message}\n`);
+    }
+    process.stderr.write(`${helpTextFor(spec, topic === undefined ? spec.name : topic)}\n`);
+    return spec.usageExit ?? 1;
+}
+async function call(run, options, args) {
+    try {
+        return (await run(options, args)) ?? 0;
+    }
+    catch (err) {
+        console.error(err.message);
+        return 1;
+    }
+}
+export async function runCli(spec, argv, onHelp) {
+    let asked;
+    let usageTopic;
+    let usageMessage;
+    const parsed = parseCli(spec, argv, (topic, text) => {
+        asked = { topic, text };
+        return 0;
+    }, (command, err) => {
+        usageTopic = command.name();
+        usageMessage = err.message;
+    });
+    if (parsed === undefined) {
+        return usageError(spec, usageTopic, usageMessage);
+    }
+    if (asked !== undefined) {
+        if (onHelp !== undefined) {
+            return onHelp(asked.topic, asked.text) ?? 0;
+        }
+        process.stdout.write(`${asked.text}\n`);
+        return 0;
+    }
+    const invocation = parsed;
+    if (spec.version !== undefined && invocation.root.version === true) {
+        process.stdout.write(`${spec.version}\n`);
+        return 0;
+    }
+    if (invocation.command === undefined) {
+        if ((spec.commands?.length ?? 0) > 0) {
+            return usageError(spec);
+        }
+        return spec.run === undefined
+            ? 0
+            : await call(spec.run, invocation.options, invocation.args);
+    }
+    const sub = spec.commands?.find(c => c.name === invocation.command);
+    return sub?.run === undefined
+        ? 0
+        : await call(sub.run, invocation.options, invocation.args);
+}

package/src/dev.js

@@ -0,0 +1,25 @@
+const RELOAD_DEBOUNCE_MS = 150;
+const IGNORED_SEGMENTS = ['/node_modules/', '/dist/', '/.git/', '/coverage/'];
+function shouldReload(file) {
+    return IGNORED_SEGMENTS.every(seg => !file.includes(seg));
+}
+/**
+ * Debounced file-change reloads, serialized via a promise chain: concurrent
+ * saves never overlap, and a mid-reload save still produces a follow-up.
+ */
+export function watchWithReload(vite, reload) {
+    let chain = Promise.resolve();
+    let timer;
+    vite.watcher.on('change', file => {
+        if (!shouldReload(file)) {
+            return;
+        }
+        if (timer) {
+            clearTimeout(timer);
+        }
+        timer = setTimeout(() => {
+            timer = undefined;
+            chain = chain.then(reload);
+        }, RELOAD_DEBOUNCE_MS);
+    });
+}

package/src/draw.js

@@ -0,0 +1,244 @@
+/**
+ * The drawing kit — the one home of the repo's terminal drawing model: ink
+ * kinds are a closed union, color values are data, surfaces render
+ * documents, and `toSgr` is the one skin, resetting each inked segment
+ * unless it carries its ink into the next. Loaded only by processes — the
+ * engine's island loader imports its own files by relative path alone.
+ */
+export function rgb(r, g, b) {
+    return { rgb: [r, g, b] };
+}
+export function indexed(n) {
+    return { indexed: n };
+}
+export function bg(ink) {
+    return { bg: ink };
+}
+export function line(...segments) {
+    return segments;
+}
+export function doc(...rows) {
+    return rows;
+}
+export function plain(text) {
+    return { text };
+}
+export function dim(text) {
+    return { text, ink: 'dim' };
+}
+export function bold(text) {
+    return { text, ink: 'bold' };
+}
+export function green(text) {
+    return { text, ink: 'green' };
+}
+export function magenta(text) {
+    return { text, ink: 'magenta' };
+}
+export function red(text) {
+    return { text, ink: 'red' };
+}
+export function yellow(text) {
+    return { text, ink: 'yellow' };
+}
+function assertNever(kind) {
+    throw new Error(`unhandled Ink kind: ${String(kind)}`);
+}
+function paramsOf(ink) {
+    if (typeof ink !== 'string') {
+        if ('bg' in ink) {
+            return paramsOf(ink.bg)
+                .replace(/^3(\d)/, '4$1')
+                .replace(/^9(\d)/, '10$1');
+        }
+        return 'indexed' in ink
+            ? `38;5;${ink.indexed}`
+            : `38;2;${ink.rgb[0]};${ink.rgb[1]};${ink.rgb[2]}`;
+    }
+    switch (ink) {
+        case 'blue':
+            return '34';
+        case 'bold':
+            return '1';
+        case 'brightBlack':
+            return '90';
+        case 'cyan':
+            return '36';
+        case 'dim':
+            return '2';
+        case 'green':
+            return '32';
+        case 'magenta':
+            return '35';
+        case 'mark':
+            return '1;97';
+        case 'plain':
+            return '39';
+        case 'red':
+            return '31';
+        case 'white':
+            return '37';
+        case 'yellow':
+            return '33';
+        default:
+            return assertNever(ink);
+    }
+}
+function rowsOf(rows) {
+    return rows.every(r => Array.isArray(r))
+        ? rows
+        : [rows];
+}
+export function toSgr(rows) {
+    return rowsOf(rows)
+        .map(row => {
+        let out = '';
+        let inkOpen = false;
+        for (const seg of row) {
+            if (seg.ink === undefined) {
+                out += (inkOpen ? '\x1b[0m' : '') + seg.text;
+                inkOpen = false;
+                continue;
+            }
+            out += `\x1b[${paramsOf(seg.ink)}m${seg.text}`;
+            if (seg.carry === true) {
+                inkOpen = true;
+            }
+            else {
+                out += '\x1b[0m';
+                inkOpen = false;
+            }
+        }
+        return inkOpen ? `${out}\x1b[0m` : out;
+    })
+        .join('\n');
+}
+export function stripSgr(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\x1b\[[0-9;]*m/g, '');
+}
+export function textOf(rows) {
+    return rowsOf(rows)
+        .map(row => row.map(seg => seg.text).join(''))
+        .join('\n');
+}
+function stdioOf(result) {
+    return typeof result === 'object' && result !== null ? result : {};
+}
+export function stdoutOf(result) {
+    const { stdout } = stdioOf(result);
+    return typeof stdout === 'string' ? stdout : '';
+}
+/** The one line an exec shows: the refusal's reason, stdout, else stderr or `fallback`. */
+export function lineOf(call, fallback) {
+    if (call.deny !== undefined) {
+        return call.deny;
+    }
+    if (call.isError === true) {
+        return call.text ?? fallback;
+    }
+    const out = stdoutOf(call.result).trim();
+    if (out !== '') {
+        return out;
+    }
+    const { stderr } = stdioOf(call.result);
+    const err = typeof stderr === 'string' ? stderr.trim() : '';
+    return err !== '' ? err : fallback;
+}
+export const RULE_WIDTH = 68;
+export const BLOCK = '█';
+export const TRACK = '·';
+export const EIGHTHS = [
+    '',
+    '▏',
+    '▎',
+    '▍',
+    '▌',
+    '▋',
+    '▊',
+    '▉',
+];
+export function rule(width = RULE_WIDTH) {
+    return '─'.repeat(Math.max(0, width));
+}
+export function pad(text, width, side) {
+    if (text.length >= width) {
+        return text;
+    }
+    const gap = ' '.repeat(width - text.length);
+    return side === 'left' ? gap + text : text + gap;
+}
+export function meter(pct, width, filled = 'green') {
+    const safePct = typeof pct === 'number' && Number.isFinite(pct) ? pct : 0;
+    const n = Math.max(0, Math.min(width, Math.round((safePct / 100) * width)));
+    return line({ text: BLOCK.repeat(n), ink: filled }, { text: TRACK.repeat(width - n), ink: 'dim' });
+}
+/** Fixed-width bar field: full blocks, an eighth-fraction edge, spaces to width. */
+export function bar(value, max, width) {
+    if (!(value > 0) || !(max > 0)) {
+        return ' '.repeat(width);
+    }
+    const scaled = (value / max) * width;
+    let full = Math.floor(scaled);
+    let fi = Math.round((scaled - full) * 8);
+    if (fi === 8) {
+        full += 1;
+        fi = 0;
+    }
+    if (full === 0 && fi === 0) {
+        fi = 1;
+    }
+    let out = BLOCK.repeat(Math.min(full, width));
+    if (full < width && fi > 0) {
+        out += EIGHTHS[fi] ?? '';
+    }
+    return pad(out, width, 'right');
+}
+export function pad2(n) {
+    return String(n).padStart(2, '0');
+}
+export const MONTHS = [
+    'Jan',
+    'Feb',
+    'Mar',
+    'Apr',
+    'May',
+    'Jun',
+    'Jul',
+    'Aug',
+    'Sep',
+    'Oct',
+    'Nov',
+    'Dec',
+];
+/** Compact count: 1.2K / 3.4M / 5.6B; '—' for absent or NaN. */
+export function fmtTokens(n) {
+    if (n == null || Number.isNaN(n)) {
+        return '—';
+    }
+    if (n >= 1e9) {
+        return (n / 1e9).toFixed(1) + 'B';
+    }
+    if (n >= 1e6) {
+        return (n / 1e6).toFixed(1) + 'M';
+    }
+    if (n >= 1e3) {
+        return (n / 1e3).toFixed(1) + 'K';
+    }
+    return String(n);
+}
+/** Grouped integer, en-US separators; 0 for absent. */
+export function fmtNum(n) {
+    return (n || 0).toLocaleString('en-US');
+}
+/** Local date-time stamp: `YYYY-MM-DD`, plus `HH:mm` and optionally seconds. */
+export function localStamp(now, clock) {
+    const day = `${now.getFullYear()}-${pad2(now.getMonth() + 1)}-${pad2(now.getDate())}`;
+    if (clock === 'none') {
+        return day;
+    }
+    const hhmm = `${pad2(now.getHours())}:${pad2(now.getMinutes())}`;
+    return clock === 'second'
+        ? `${day} ${hhmm}:${pad2(now.getSeconds())}`
+        : `${day} ${hhmm}`;
+}

package/src/index.js

@@ -0,0 +1,8 @@
+export * from "./cli.js";
+export * from "./dev.js";
+export * from "./draw.js";
+export * from "./input.js";
+export * from "./last-reply.js";
+export * from "./logger.js";
+export * from "./mcp.js";
+export * from "./shutdown.js";

package/src/input.js

@@ -0,0 +1,25 @@
+import { readFileSync, statSync } from 'node:fs';
+function readAll(stream) {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        stream.setEncoding('utf8');
+        stream.on('data', (chunk) => {
+            data += chunk;
+        });
+        stream.on('end', () => {
+            resolve(data);
+        });
+        stream.on('error', reject);
+    });
+}
+export function readStdin(stream = process.stdin) {
+    return readAll(stream);
+}
+/** A markdown file's contents, with the CLI's no-such-file error. */
+export function readMarkdownFile(path) {
+    const stats = statSync(path, { throwIfNoEntry: false });
+    if (!stats?.isFile()) {
+        throw new Error(`no such file: ${path}`);
+    }
+    return readFileSync(path, 'utf8');
+}

package/src/last-reply.js

@@ -0,0 +1,75 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function textBlocks(entry) {
+    const content = entry.message?.content;
+    if (entry.type !== 'assistant' || !Array.isArray(content)) {
+        return undefined;
+    }
+    const blocks = content.filter((b) => typeof b === 'object' &&
+        b !== null &&
+        b.type === 'text');
+    return blocks.length > 0 ? blocks : undefined;
+}
+export function claudeProjectsDir() {
+    const claudeDir = process.env.CLAUDE_DIR ?? join(homedir(), '.claude');
+    return join(claudeDir, 'projects');
+}
+/**
+ * The last assistant text reply from a Claude Code session, reproducing Claude
+ * Code's `/copy` byte-for-byte: the last assistant entry that contains a
+ * `text` block, only its `text` block(s) (tool_use / thinking dropped), blocks
+ * joined with a blank line, and no trailing newline.
+ *
+ * @param arg a transcript file, a session UUID under the project dir, or
+ *   nothing to use the newest session for the current project.
+ */
+export function lastReply(arg) {
+    // Claude Code keys transcripts under the project root with "/" → "-".
+    // Prefer $CLAUDE_PROJECT_DIR (exported to hook processes) over $PWD.
+    const proj = (process.env.CLAUDE_PROJECT_DIR ?? process.cwd()).replaceAll('/', '-');
+    const projDir = join(claudeProjectsDir(), proj);
+    let file;
+    if (arg !== undefined) {
+        file = isFile(arg) ? arg : join(projDir, `${arg}.jsonl`);
+    }
+    else if (existsSync(projDir)) {
+        const newest = readdirSync(projDir)
+            .filter(f => f.endsWith('.jsonl'))
+            .map(f => ({ f, mtimeMs: statSync(join(projDir, f)).mtimeMs }))
+            .sort((a, b) => b.mtimeMs - a.mtimeMs)
+            .at(0);
+        if (newest) {
+            file = join(projDir, newest.f);
+        }
+    }
+    if (file === undefined || !isFile(file)) {
+        throw new Error(`no session transcript found in ${projDir}`);
+    }
+    let last;
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+        if (!line.includes('"assistant"')) {
+            continue;
+        }
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const blocks = textBlocks(entry);
+        if (blocks) {
+            last = blocks;
+        }
+    }
+    return (last ?? []).map(b => b.text ?? '').join('\n\n');
+}

package/src/logger.js

@@ -0,0 +1,50 @@
+const LEVEL_RANK = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    silent: Number.MAX_SAFE_INTEGER,
+};
+const LEVEL_LABEL = {
+    debug: 'DEBUG',
+    error: 'ERROR',
+    info: 'INFO',
+    warn: 'WARN',
+};
+const VALID_LEVELS = [
+    'debug',
+    'info',
+    'warn',
+    'error',
+    'silent',
+];
+export function loggerFromEnv(env, variable, fallback = 'info') {
+    const raw = env[variable];
+    return new Logger(VALID_LEVELS.find(level => level === raw) ?? fallback);
+}
+// stdout carries the MCP transport; everything here goes to stderr.
+export class Logger {
+    activeLevel;
+    stderr;
+    constructor(activeLevel, stderr = line => process.stderr.write(`${line}\n`)) {
+        this.activeLevel = activeLevel;
+        this.stderr = stderr;
+    }
+    debug(message) {
+        this.log('debug', message);
+    }
+    error(message) {
+        this.log('error', message);
+    }
+    info(message) {
+        this.log('info', message);
+    }
+    warn(message) {
+        this.log('warn', message);
+    }
+    log(level, message) {
+        if (LEVEL_RANK[level] >= LEVEL_RANK[this.activeLevel]) {
+            this.stderr(`${LEVEL_LABEL[level]} ${message}`);
+        }
+    }
+}

package/src/mcp.js

@@ -0,0 +1,29 @@
+export function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * The wrapper owns the error-drift class: a thrown or rejected error (zod
+ * parse included) logs and answers an `isError` result instead of escaping
+ * the tool call.
+ */
+export function toolHandler(log, toErrorResult) {
+    return tool;
+    function tool(name, run, schema) {
+        function fail(err) {
+            log.error(`${name} failed: ${describeError(err)}`);
+            return toErrorResult(err);
+        }
+        return raw => {
+            try {
+                const args = schema === undefined ? raw : schema.parse(raw);
+                const result = run(args);
+                return result instanceof Promise
+                    ? result.then(undefined, fail)
+                    : result;
+            }
+            catch (err) {
+                return fail(err);
+            }
+        };
+    }
+}

package/src/shutdown.js

@@ -0,0 +1,23 @@
+/** Close each closable in order (best-effort), then force-exit. */
+export function shutdownOnSignals(closables, signals = ['SIGINT', 'SIGTERM']) {
+    function shutdown() {
+        void closables
+            .reduce((acc, closable) => acc.then(async () => {
+            try {
+                await closable.close();
+            }
+            catch {
+                // best-effort; exiting regardless
+            }
+            return;
+        }), Promise.resolve())
+            .finally(() => {
+            // Force-exit on signal; the n/no-process-exit rule targets libraries.
+            // eslint-disable-next-line n/no-process-exit
+            process.exit(0);
+        });
+    }
+    for (const signal of signals) {
+        process.on(signal, shutdown);
+    }
+}

package/src/vite.js

@@ -0,0 +1,63 @@
+import { dirname, resolve } from 'node:path';
+import { createServerModuleRunner, createServer as createViteServer, } from 'vite';
+import { configDefaults } from 'vitest/config';
+import { watchWithReload } from "./dev.js";
+import { describeError } from "./mcp.js";
+import { shutdownOnSignals } from "./shutdown.js";
+export function serverVite({ testTimeout } = {}) {
+    return {
+        // Vite 8 spins the HMR websocket from `server.ws`, not `server.hmr`
+        // (`hmr: false` stops messaging, not the socket): without this a second
+        // dev boot dies fighting over the default ws port 24678.
+        server: { ws: false },
+        test: {
+            globals: true,
+            environment: 'node',
+            ...(testTimeout === undefined ? {} : { testTimeout }),
+            exclude: [...configDefaults.exclude, 'dist/**'],
+        },
+    };
+}
+/**
+ * The hot-reload harness every MCP-server dev entry runs. The transport and
+ * McpServer are single-use under the SDK (`StdioServerTransport.start()`
+ * throws on a second call), so `start` creates and connects them once and
+ * only the registrations swap on each file change. `start` must register
+ * before connecting — the SDK's `registerCapabilities` throws post-connect.
+ * `entry` is the module that exports the registration families, at
+ * `<package root>/src/<name>.ts`.
+ */
+export async function runDevServer(options) {
+    const vite = await createViteServer({
+        appType: 'custom',
+        configFile: false,
+        // Vite logs `info` (e.g. "(ssr) page reload") via console.log to stdout,
+        // which corrupts the MCP stream; `warn` keeps errors on stderr.
+        logLevel: 'warn',
+        root: resolve(dirname(options.entry), '..'),
+        server: { middlewareMode: true, ws: false },
+    });
+    // hmr: false in a hot-reload harness looks wrong but is right: the
+    // watcher re-imports the whole entry rather than patching modules.
+    const runner = createServerModuleRunner(vite.environments.ssr, {
+        hmr: false,
+    });
+    const first = await runner.import(options.entry);
+    const session = await options.start(first);
+    async function runOneReload() {
+        try {
+            runner.evaluatedModules.clear();
+            // Import the next module before reload removes the live
+            // registrations: a failed import leaves what is serving intact.
+            const next = await runner.import(options.entry);
+            session.reload(next);
+            options.log.info('[reload] success');
+        }
+        catch (err) {
+            options.log.error(`[reload] failed: ${describeError(err)}`);
+        }
+    }
+    watchWithReload(vite, runOneReload);
+    options.log.info('[reload] ready');
+    shutdownOnSignals([...session.closers, vite]);
+}