@eyeauras/insight-cli 0.2.0 → 0.2.1

package/dist/src/tool-runtime/run.js

@@ -0,0 +1,159 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, isAbsolute, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { CliError } from '@eyeauras/cli-factory';
+import { atomicWrite, withToolUse, toolRoot, readJson } from './store.js';
+import { launchProcess } from './supervisor.js';
+import { digest } from '../model.js';
+import { deadlineLaunch } from './deadline.js';
+import { windowsJobLaunch, windowsJobResult } from './windows-job.js';
+export async function runTool(c, spec) {
+    c.signal.throwIfAborted();
+    const directory = c.appArguments.AppDataDirectory;
+    toolRoot(directory, spec.tool);
+    if (!isAbsolute(spec.executable))
+        throw new CliError('Tool executable must be an absolute path.', { code: 'tool.configuration' });
+    if ((spec.observedSubject || spec.nativeMutex || spec.nativeRegistry) && (!spec.nativeDeadline || process.platform !== 'win32'))
+        throw new CliError('Native subject/mutex/registry binding requires an owned Windows job.', { code: 'tool.configuration' });
+    if (spec.nativeChildDeadlines && !spec.nativeDeadline)
+        throw new CliError('Native child deadlines require the native collector deadline.', { code: 'tool.configuration' });
+    let launch = { executable: spec.executable, arguments: spec.arguments ?? [] };
+    const id = randomUUID(), root = join(directory, 'runtime/runs', id), path = join(directory, 'runtime/processes', id + '.json');
+    const started = performance.now(), limit = spec.maxOutputBytes ?? 4 * 1024 ** 2;
+    let child, outcome, truncated = false, bytes = 0;
+    const stdout = [], stderr = [], record = { schema: 1, id, tool: spec.tool, role: spec.role, installation: spec.installation ?? 'probe', state: 'starting', executable: spec.executable, createdAt: new Date().toISOString(), root, ownerPid: process.pid, profileBinding: digest(resolve(directory)), gated: process.platform !== 'win32' && typeof process.execve === 'function', phase: 'reserved', ...(spec.session ? { session: spec.session } : {}), ...(spec.target ? { target: spec.target } : {}) };
+    const lease = await withToolUse(directory, spec.tool, async () => { await mkdir(root, { recursive: true, mode: 0o700 }); }, c.signal);
+    const environment = { PATH: c.environment.PATH ?? process.env.PATH, HOME: root, TMPDIR: root, ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot, WINDIR: process.env.WINDIR, ComSpec: process.env.ComSpec, TEMP: root, TMP: root, USERPROFILE: root, LOCALAPPDATA: root, APPDATA: root } : {}), ...spec.environment };
+    const secrets = Object.entries(environment).filter(([key, value]) => /TOKEN|PASSWORD|SECRET|KEY/i.test(key) && value && value.length >= 4).map(([, v]) => v);
+    const redact = (value) => secrets.reduce((text, secret) => text.split(secret).join('[redacted]'), value);
+    let timer, force, drain, hard, settled = false, abandon;
+    const signal = (name) => {
+        if (!child?.pid || settled)
+            return;
+        try {
+            if (process.platform !== 'win32')
+                process.kill(-child.pid, name);
+            else if (child.exitCode === null && child.signalCode === null)
+                child.kill(name);
+        }
+        catch (e) {
+            if (e.code === 'ESRCH')
+                return;
+            record.terminationError = e.code ?? 'signal_failed';
+            if (child.exitCode === null && child.signalCode === null)
+                try {
+                    child.kill(name);
+                }
+                catch { }
+        }
+    };
+    const stop = (reason) => { if (settled)
+        return; outcome ??= reason; signal('SIGTERM'); force ??= setTimeout(() => { signal('SIGKILL'); hard = setTimeout(() => { if (settled)
+        return; outcome = 'termination_unverified'; record.state = 'unverified'; child?.stdin?.destroy(); child?.stdout?.destroy(); child?.stderr?.destroy(); child?.unref(); abandon?.(new Error('termination_unverified')); }, 1000); hard.unref(); }, 1000); force.unref(); };
+    const aborted = () => stop('cancelled');
+    try {
+        c.signal.throwIfAborted();
+        if (spec.nativeDeadline)
+            launch = process.platform === 'win32' ? await windowsJobLaunch(root, id, spec.executable, spec.arguments ?? [], spec.cwd ?? root, spec.timeoutMs ?? 120000, { observedSubject: spec.observedSubject, nativeMutex: spec.nativeMutex, nativeRegistry: spec.nativeRegistry }) : await deadlineLaunch(spec.executable, spec.arguments ?? [], spec.timeoutMs ?? 120000);
+        child = await launchProcess(directory, { tool: spec.tool, role: spec.role, installation: spec.installation ?? 'probe', session: spec.session, target: spec.target, ...(spec.metadata || spec.nativeDeadline ? { metadata: { ...spec.metadata, ...(spec.observedSubject ? { observedSubject: spec.observedSubject } : {}), ...(spec.nativeMutex ? { nativeMutex: spec.nativeMutex } : {}), ...(spec.nativeRegistry ? { nativeRegistry: spec.nativeRegistry } : {}), ...(spec.nativeDeadline ? { nativeDeadlineSeconds: Math.ceil((spec.timeoutMs ?? 120000) / 1000), nativeExecutable: spec.executable, ...(spec.nativeChildDeadlines ? { nativeChildDeadlines: true } : {}) } : {}) } } : {}) }, launch.executable, launch.arguments, { cwd: spec.cwd ?? root, env: environment, windowsHide: true, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'] }, { id, finalize: false, signal: c.signal, onSpawn: launched => {
+                child = launched;
+                child.once('close', () => { settled = true; });
+                child.once('exit', () => { drain = setTimeout(() => stop('background_output'), 300); drain.unref(); });
+                const capture = (chunks, b) => { const available = Math.max(0, limit - bytes); if (available)
+                    chunks.push(Buffer.from(b.subarray(0, available))); bytes += b.length; if (bytes > limit) {
+                    truncated = true;
+                    stop('output_limit');
+                } };
+                child.stdout.on('data', b => capture(stdout, b));
+                child.stderr.on('data', b => capture(stderr, b));
+                child.stdin.on('error', () => { });
+                child.stdin.end(spec.input);
+                c.signal.addEventListener('abort', aborted, { once: true });
+                if (c.signal.aborted)
+                    aborted();
+                timer = setTimeout(() => stop('timeout'), spec.timeoutMs ?? 120000);
+                timer.unref();
+            } });
+        await Promise.race([child.toolClosed, new Promise((_ok, bad) => { abandon = bad; })]);
+        settled = true;
+        Object.assign(record, await readJson(path));
+        if (record.launchError)
+            outcome = 'launch_failed';
+        let exitCode = child.exitCode;
+        if (spec.nativeDeadline && process.platform === 'win32' && !outcome) {
+            try {
+                const job = await windowsJobResult(root, id, child.pid, Boolean(spec.nativeRegistry));
+                exitCode = job.childExitCode;
+                Object.assign(record, { windowsJob: job });
+                if (job.phase !== 'completed')
+                    outcome = job.phase;
+            }
+            catch {
+                outcome = 'job_result_unverified';
+            }
+        }
+        if (!outcome && spec.nativeDeadline && child.signalCode === 'SIGALRM')
+            outcome = 'timeout';
+        if (!outcome && (exitCode === null || !(spec.acceptedCodes ?? [0]).includes(exitCode)))
+            outcome = 'exit_code';
+        const result = { process: id, stdout: redact(Buffer.concat(stdout).toString('utf8')), stderr: redact(Buffer.concat(stderr).toString('utf8')), exitCode, signal: child.signalCode, elapsedMs: Math.round(performance.now() - started), truncated, diagnostics: root };
+        if (spec.retainRawOutput) {
+            result.rawStdout = join(root, 'stdout.bin');
+            result.rawStderr = join(root, 'stderr.bin');
+            await writeFile(result.rawStdout, Buffer.concat(stdout), { mode: 0o600 });
+            await writeFile(result.rawStderr, Buffer.concat(stderr), { mode: 0o600 });
+        }
+        await writeFile(join(root, 'stdout.log'), result.stdout, { mode: 0o600 });
+        await writeFile(join(root, 'stderr.log'), result.stderr, { mode: 0o600 });
+        Object.assign(record, { state: outcome ? 'failed' : 'exited', outcome: outcome ?? 'completed', exitCode: result.exitCode, signal: result.signal, elapsedMs: result.elapsedMs, endedAt: new Date().toISOString() });
+        await atomicWrite(path, record);
+        if (outcome)
+            throw new CliError('Tool execution did not complete successfully: ' + outcome + '.', { code: 'tool.' + outcome.replaceAll('_', '.'), result });
+        if (spec.outputFile)
+            try {
+                await writeFile(spec.outputFile, Buffer.concat(stdout), { flag: 'wx', mode: 0o600 });
+            }
+            catch (error) {
+                throw new CliError('Tool completed, but its binary output could not be written to a new file.', { code: 'tool.output', cause: error, result: { process: id, diagnostics: root } });
+            }
+        return result;
+    }
+    catch (error) {
+        const failure = error;
+        await atomicWrite(join(root, 'error.json'), { name: failure.name, code: failure.code, message: redact(failure.message ?? String(error)), ...(failure.cause ? { cause: { name: failure.cause.name, message: redact(failure.cause.message) } } : {}) });
+        if (child && !settled && record.state !== 'unverified') {
+            stop('failed');
+            await new Promise(ok => { if (settled) {
+                ok();
+                return;
+            } child.once('close', () => ok()); setTimeout(() => { signal('SIGKILL'); ok(); }, 1500).unref(); });
+        }
+        Object.assign(record, await readJson(path));
+        if (c.signal.aborted && !outcome)
+            outcome = 'cancelled';
+        if (record.state === 'starting' || record.state === 'running' || record.state === 'failed') {
+            Object.assign(record, { state: 'failed', outcome: outcome ?? 'launch_failed', endedAt: new Date().toISOString(), elapsedMs: Math.round(performance.now() - started) });
+            await atomicWrite(path, record);
+        }
+        if (record.state === 'unverified')
+            await atomicWrite(path, record);
+        if (error instanceof CliError)
+            throw error;
+        if (record.state === 'unverified')
+            throw new CliError('Tool termination could not be verified; its process record blocks removal.', { code: 'tool.termination.unverified', result: { process: id, diagnostics: root } });
+        throw new CliError('Tool execution failed; inspect its retained process record.', { code: outcome ? 'tool.' + outcome.replaceAll('_', '.') : 'tool.launch', cause: error, result: { process: id, diagnostics: root } });
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (force)
+            clearTimeout(force);
+        if (drain)
+            clearTimeout(drain);
+        if (hard)
+            clearTimeout(hard);
+        c.signal.removeEventListener('abort', aborted);
+        lease.release();
+    }
+}

package/dist/src/tool-runtime/store.d.ts

@@ -0,0 +1,15 @@
+export declare function atomicWrite(path: string, value: unknown): Promise<void>;
+export declare function readJson<T>(path: string): Promise<T | undefined>;
+export declare function toolRoot(directory: string, tool: string): string;
+/** CLI clients already share Factory's elected owner. Do not create another IPC/lease protocol. */
+export declare function withToolLock<T>(directory: string, tool: string, action: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+export declare function toolProfileBusy(directory: string): boolean;
+export declare function toolUseCount(directory: string, tool: string): number;
+export declare function withToolUse<T>(directory: string, tool: string, acquire: () => Promise<T>, signal?: AbortSignal): Promise<{
+    value: T;
+    release: () => void;
+}>;
+export declare function assertUnused(directory: string, tool: string): Promise<void>;
+export declare function installationStage<T>(root: string, id: string, prepare: (stage: string, installed: string) => Promise<T>, verify: (receipt: T) => Promise<void>, signal?: AbortSignal): Promise<T>;
+export declare function removeInstallation(root: string, id: string): Promise<void>;
+export declare function treeFingerprint(root: string): Promise<string>;

package/dist/src/tool-runtime/store.js

@@ -0,0 +1,219 @@
+import { mkdir, open, rename, rm, readFile, readdir, lstat, realpath } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { dirname, join, resolve, relative, sep } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { CliError } from '@eyeauras/cli-factory';
+import { fail } from '../model.js';
+export async function atomicWrite(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = path + '.new-' + randomUUID(), file = await open(temporary, 'wx', 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value, null, 2) + '\n');
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    await rename(temporary, path);
+    if (process.platform !== 'win32') {
+        const parent = await open(dirname(path), 'r');
+        try {
+            await parent.sync();
+        }
+        finally {
+            await parent.close();
+        }
+    }
+}
+export async function readJson(path) { try {
+    return JSON.parse(await readFile(path, 'utf8'));
+}
+catch (e) {
+    if (e.code === 'ENOENT')
+        return;
+    throw e;
+} }
+export function toolRoot(directory, tool) { if (!/^[a-z][a-z0-9-]*$/.test(tool))
+    fail('invalid', 'Invalid tool identity.'); return tool === 'ghidra' ? join(directory, 'runtime') : join(directory, 'runtime', 'tools', tool); }
+const queues = new Map(), held = new AsyncLocalStorage(), uses = new Map();
+const key = (directory, tool) => resolve(directory) + '\0' + tool;
+/** CLI clients already share Factory's elected owner. Do not create another IPC/lease protocol. */
+export async function withToolLock(directory, tool, action, signal) {
+    signal?.throwIfAborted();
+    const k = key(directory, tool);
+    if (held.getStore()?.has(k))
+        return action();
+    const previous = queues.get(k) ?? Promise.resolve();
+    let started = false;
+    const execution = previous.then(() => { signal?.throwIfAborted(); started = true; return held.run(new Set([...(held.getStore() ?? []), k]), action); });
+    const tail = execution.then(() => { }, () => { });
+    queues.set(k, tail);
+    void tail.then(() => { if (queues.get(k) === tail)
+        queues.delete(k); });
+    if (!signal)
+        return execution;
+    return new Promise((ok, bad) => {
+        const aborted = () => { if (!started)
+            bad(signal.reason); };
+        signal.addEventListener('abort', aborted, { once: true });
+        if (signal.aborted)
+            aborted();
+        execution.then(ok, bad).finally(() => signal.removeEventListener('abort', aborted));
+    });
+}
+export function toolProfileBusy(directory) { const prefix = resolve(directory) + '\0'; return [...queues.keys(), ...uses.keys()].some(k => k.startsWith(prefix)); }
+export function toolUseCount(directory, tool) { return uses.get(key(directory, tool)) ?? 0; }
+export async function withToolUse(directory, tool, acquire, signal) {
+    return withToolLock(directory, tool, async () => {
+        const value = await acquire();
+        signal?.throwIfAborted();
+        const k = key(directory, tool);
+        uses.set(k, (uses.get(k) ?? 0) + 1);
+        let released = false;
+        return { value, release() { if (released)
+                return; released = true; const n = (uses.get(k) ?? 1) - 1; if (n)
+                uses.set(k, n);
+            else
+                uses.delete(k); } };
+    }, signal);
+}
+export async function assertUnused(directory, tool) {
+    if (toolUseCount(directory, tool))
+        fail('busy', 'Tool installation is reserved by an active operation.');
+    let names;
+    const root = join(directory, 'runtime/processes');
+    try {
+        names = await readdir(root);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return;
+        throw e;
+    }
+    for (const name of names) {
+        if (!/^[a-f0-9-]{36}\.json$/.test(name))
+            continue;
+        const retained = await readJson(join(root, name));
+        if (!retained || retained.tool !== tool)
+            continue;
+        const { processStatus } = await import('./supervisor.js'), record = await processStatus(directory, name.slice(0, -5));
+        if (['exited', 'failed'].includes(record.state))
+            continue;
+        if (record.phase === 'native_children_pending' || record.phase === 'native_children_unverified')
+            fail('busy', 'Tool has an active or unverified native helper; inspect its retained records before changing installations.');
+        if (!record.pid) {
+            if (record.gated && record.ownerPid)
+                try {
+                    process.kill(record.ownerPid, 0);
+                }
+                catch (e) {
+                    if (e.code === 'ESRCH')
+                        continue;
+                    throw e;
+                }
+            fail('busy', 'Tool has an unresolved process launch; inspect its process record.');
+        }
+        try {
+            process.kill(record.pid, 0);
+            fail('busy', 'Tool has an active or unverified process; stop it before changing installations.');
+        }
+        catch (e) {
+            if (e.code !== 'ESRCH')
+                throw e;
+        }
+    }
+}
+export async function installationStage(root, id, prepare, verify, signal) {
+    if (!/^[a-f0-9]{64}$/.test(id))
+        fail('invalid', 'Invalid installation identity.');
+    signal?.throwIfAborted();
+    const installed = join(root, 'installations', id), receipt = await readJson(join(installed, 'ready.json'));
+    if (receipt) {
+        await verify(receipt);
+        return receipt;
+    }
+    const stage = join(root, 'stages', randomUUID());
+    await mkdir(stage, { recursive: true, mode: 0o700 });
+    try {
+        const value = await prepare(stage, installed);
+        signal?.throwIfAborted();
+        await atomicWrite(join(stage, 'ready.json'), value);
+        await mkdir(dirname(installed), { recursive: true, mode: 0o700 });
+        try {
+            await lstat(installed);
+            fail('binding', 'Incomplete installation is retained; inspect it before removing it.');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        await rename(stage, installed);
+        if (process.platform !== 'win32') {
+            const p = await open(dirname(installed), 'r');
+            try {
+                await p.sync();
+            }
+            finally {
+                await p.close();
+            }
+        }
+        return value;
+    }
+    catch (error) {
+        const code = error instanceof CliError ? error.code : 'installation';
+        await atomicWrite(join(stage, 'failure.json'), { state: 'failed', code });
+        if (error instanceof CliError)
+            throw new CliError(error.message, { code: error.code, result: { ...(error.result && typeof error.result === 'object' ? error.result : {}), diagnostics: stage } });
+        throw new CliError('Tool installation failed; the prior selection and diagnostic stage are retained.', { code: 'tool.installation', cause: error, result: { diagnostics: stage } });
+    }
+}
+export async function removeInstallation(root, id) {
+    if (!/^[a-f0-9]{64}$/.test(id))
+        fail('binding', 'Invalid installation identity.');
+    const path = join(root, 'installations', id);
+    let actual;
+    try {
+        actual = await realpath(path);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return;
+        throw e;
+    }
+    if (actual !== join(await realpath(root), 'installations', id))
+        fail('binding', 'Owned installation path was replaced by an external link.');
+    await rm(path, { recursive: true, force: true });
+}
+export async function treeFingerprint(root) {
+    const hash = createHash('sha256'), canonicalRoot = await realpath(root);
+    let count = 0;
+    async function visit(path) {
+        for (const name of (await readdir(path)).sort()) {
+            if (path === root && name === 'ready.json')
+                continue;
+            const at = join(path, name), st = await lstat(at);
+            if (++count > 100000)
+                fail('limit', 'Tool installation exceeds its file bound.');
+            hash.update(relative(root, at).replaceAll('\\', '/') + '\0');
+            if (st.isDirectory())
+                await visit(at);
+            else if (st.isSymbolicLink()) {
+                const destination = await realpath(at);
+                if (!destination.startsWith(canonicalRoot + sep))
+                    fail('binding', 'Installed component link escapes its owned directory.');
+                hash.update('link:' + relative(canonicalRoot, destination));
+            }
+            else if (st.isFile()) {
+                const leaf = createHash('sha256');
+                for await (const b of createReadStream(at))
+                    leaf.update(b);
+                hash.update('file:' + st.size + ':' + leaf.digest('hex') + '\0');
+            }
+            else
+                fail('binding', 'Unsupported tool installation entry.');
+        }
+    }
+    await visit(root);
+    return hash.digest('hex');
+}

package/dist/src/tool-runtime/supervisor.d.ts

@@ -0,0 +1,57 @@
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+import type { ToolProcess } from './definition.js';
+export interface ProcessRecord extends ToolProcess {
+    root: string;
+    ownerPid: number;
+    profileBinding: string;
+    phase?: string;
+    strongIdentity?: boolean;
+    processGroup?: number;
+    gated: boolean;
+    metadata?: Record<string, unknown>;
+    outcome?: string;
+    requestedStop?: 'stop' | 'kill';
+    launchError?: string;
+}
+export interface ProcessSpec {
+    tool: string;
+    role: string;
+    installation: string;
+    session?: string;
+    target?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TrackedChild extends ChildProcess {
+    toolProcessId: string;
+    toolClosed: Promise<void>;
+}
+export type OwnershipVerifier = (record: ProcessRecord) => Promise<boolean | undefined>;
+export declare function launchProcess(directory: string, spec: ProcessSpec, executable: string, args: string[], options?: SpawnOptions, control?: {
+    id?: string;
+    finalize?: boolean;
+    onSpawn?: (child: TrackedChild) => void | Promise<void>;
+    signal?: AbortSignal;
+}): Promise<TrackedChild>;
+export declare function processStatus(directory: string, id: string, verify?: OwnershipVerifier): Promise<ProcessRecord>;
+export declare function listProcesses(directory: string, filter?: {
+    tool?: string;
+    session?: string;
+    target?: string;
+}, verify?: OwnershipVerifier): Promise<ProcessRecord[]>;
+export declare function terminateProcess(directory: string, id: string, force: boolean, verify?: OwnershipVerifier, graceful?: (record: ProcessRecord) => Promise<void>): Promise<{
+    process: string;
+    state: string;
+    interrupted?: undefined;
+    tool?: undefined;
+    session?: undefined;
+    target?: undefined;
+} | {
+    process: string;
+    state: string;
+    interrupted: boolean;
+    tool: string;
+    session: string | undefined;
+    target: string | undefined;
+}>;
+/** Migration/reconnection only: an adapter must authenticate a known existing tool before registration. */
+export declare function registerExistingProcess(directory: string, spec: ProcessSpec, executable: string, pid: number, verify: OwnershipVerifier): Promise<string>;