@eyeauras/insight-cli 0.2.0 → 0.2.1

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

@@ -0,0 +1,266 @@
+import { spawn } from 'node:child_process';
+import { access, mkdir, readdir } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join, isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { CliError } from '@eyeauras/cli-factory';
+import { atomicWrite, readJson, toolRoot, withToolLock } from './store.js';
+import { processIdentity } from './identity.js';
+import { digest } from '../model.js';
+const owned = new Map();
+const ownedKey = (directory, id) => resolve(directory) + '\0' + id;
+/** Receipts report pending lifetime only; they never authorize a signal to another PID. */
+async function nativeChildren(record) {
+    if (record.metadata?.nativeChildDeadlines !== true)
+        return [];
+    let names;
+    try {
+        names = await readdir(join(record.root, 'native-deadlines'));
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+    if (names.length > 100)
+        throw new CliError('Native helper receipt count exceeds its bound.', { code: 'tool.process.unverified' });
+    return Promise.all(names.map(async (name) => {
+        const value = await readJson(join(record.root, 'native-deadlines', name));
+        if (!/^\d+\.json$/.test(name) || !value || value.protocol !== 1 || !Number.isSafeInteger(value.pid) || value.pid < 1 || value.pid > 2147483647 || name !== value.pid + '.json' || !Number.isSafeInteger(value.parentPid) || value.parentPid < 1 || !Number.isSafeInteger(value.birthSeconds) || value.birthSeconds < 1 || !Number.isSafeInteger(value.birthMicroseconds) || value.birthMicroseconds < 0 || value.birthMicroseconds >= 1000000 || !Number.isSafeInteger(value.deadlineUnixSeconds) || value.deadlineUnixSeconds <= 0)
+            throw new CliError('Native helper receipt is invalid; no cleanup was assumed.', { code: 'tool.process.unverified' });
+        const receiptDigest = digest(value), acknowledgment = join(record.root, 'native-deadline-exits', name), previous = await readJson(acknowledgment);
+        if (previous?.receiptDigest === receiptDigest)
+            return { ...value, state: 'exited' };
+        const identity = await processIdentity(value.pid), seconds = identity && process.platform === 'darwin' ? Date.parse(identity.birth + ' GMT') / 1000 : NaN;
+        // A different observable birth proves reuse, without granting permission to signal that PID.
+        const exited = !identity || Number.isFinite(seconds) && seconds !== value.birthSeconds;
+        if (exited)
+            await atomicWrite(acknowledgment, { receiptDigest, observedAt: new Date().toISOString() });
+        return { ...value, state: exited ? 'exited' : 'pending' };
+    }));
+}
+export async function launchProcess(directory, spec, executable, args, options = {}, control = {}) {
+    return withToolLock(directory, spec.tool, async () => {
+        control.signal?.throwIfAborted();
+        toolRoot(directory, spec.tool);
+        if (!isAbsolute(executable))
+            throw new CliError('Tool executable must be absolute.', { code: 'tool.configuration' });
+        const id = control.id ?? randomUUID();
+        if (!/^[a-f0-9-]{36}$/.test(id))
+            throw Error('Invalid process identity');
+        const root = join(directory, 'runtime/runs', id), path = join(directory, 'runtime/processes', id + '.json');
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        const gated = process.platform !== 'win32' && typeof process.execve === 'function';
+        const record = { schema: 1, id, ...spec, state: 'starting', executable, root, ownerPid: process.pid, profileBinding: digest(resolve(directory)), gated, phase: 'reserved', createdAt: new Date().toISOString() };
+        await atomicWrite(path, record);
+        try {
+            control.signal?.throwIfAborted();
+            await access(executable, process.platform === 'win32' ? constants.F_OK : constants.X_OK);
+        }
+        catch (error) {
+            Object.assign(record, { state: 'failed', phase: 'preflight_failed' });
+            await atomicWrite(path, record);
+            throw error;
+        }
+        const environment = options.env ?? { PATH: process.env.PATH, HOME: root, TMPDIR: root };
+        const stdio = Array.isArray(options.stdio) ? [...options.stdio] : Array(3).fill(options.stdio ?? 'pipe'), fd = stdio.length, nonce = randomUUID();
+        if (gated)
+            stdio.push('pipe');
+        let child;
+        try {
+            child = spawn(gated ? process.execPath : executable, gated ? ['--no-warnings', fileURLToPath(new URL('./launch-worker.js', import.meta.url)), directory, id, String(fd)] : args, { cwd: root, ...options, stdio, windowsHide: true, env: gated ? { PATH: environment.PATH, HOME: root, TMPDIR: root } : environment });
+        }
+        catch (error) {
+            Object.assign(record, { state: 'failed', phase: 'spawn_failed' });
+            await atomicWrite(path, record);
+            throw error;
+        }
+        const closed = new Promise((ok, bad) => { child.on('error', error => { if (!child.pid)
+            bad(error); }); child.once('close', ok); });
+        void closed.catch(() => { });
+        const handle = { child, closed, record };
+        owned.set(ownedKey(directory, id), handle);
+        const finalized = control.finalize === false ? closed : closed.then(async () => {
+            const current = await readJson(path) ?? record;
+            if (current.state !== 'failed' && current.state !== 'unverified')
+                Object.assign(current, { state: 'exited', exitCode: child.exitCode, signal: child.signalCode, endedAt: new Date().toISOString(), outcome: current.requestedStop === 'kill' ? 'killed' : current.requestedStop === 'stop' ? 'stopped' : 'completed' });
+            await atomicWrite(path, current);
+        }, async () => { Object.assign(record, { state: 'failed', phase: 'spawn_failed' }); await atomicWrite(path, record); });
+        handle.closed = finalized.finally(() => { owned.delete(ownedKey(directory, id)); });
+        void handle.closed.catch(() => { });
+        Object.assign(child, { toolProcessId: id, toolClosed: handle.closed });
+        try {
+            await control.onSpawn?.(child);
+            if (!child.pid)
+                throw Error('Owned tool spawn did not obtain a PID');
+            if (gated) {
+                const channel = child.stdio[fd];
+                channel.on('error', () => { });
+                channel.end(JSON.stringify({ executable, arguments: args, environment: Object.fromEntries(Object.entries(environment).filter(([, v]) => v !== undefined)), nonce }));
+                let armed = false;
+                for (let i = 0; i < 400; i++) {
+                    control.signal?.throwIfAborted();
+                    const ready = await readJson(join(root, 'armed.json'));
+                    if (ready && ready.pid === child.pid && ready.nonce === nonce) {
+                        armed = true;
+                        break;
+                    }
+                    if (child.exitCode !== null || child.signalCode !== null)
+                        break;
+                    await delay(25);
+                }
+                if (!armed)
+                    throw Error('Owned launch did not become armed');
+                Object.assign(record, await readJson(path), { state: 'running', phase: 'exec_authorized' });
+                await atomicWrite(path, record);
+                await atomicWrite(join(root, 'go.json'), { nonce });
+            }
+            else {
+                if (!child.pid)
+                    throw Error('No child process');
+                const identity = await processIdentity(child.pid);
+                Object.assign(record, { pid: child.pid, identity: identity?.birth, strongIdentity: identity?.strong, processGroup: identity?.group, state: 'running', phase: 'direct_child_only' });
+                await atomicWrite(path, record);
+            }
+            return child;
+        }
+        catch (error) {
+            if (child.exitCode === null && child.signalCode === null)
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { }
+            await Promise.race([handle.closed.catch(() => { }), delay(2000)]);
+            Object.assign(record, { state: child.exitCode !== null || child.signalCode !== null ? 'failed' : 'unverified', phase: 'launch_failed' });
+            await atomicWrite(path, record);
+            throw error;
+        }
+    }, control.signal);
+}
+export async function processStatus(directory, id, verify) {
+    if (!/^[a-f0-9-]{36}$/.test(id))
+        throw new CliError('Invalid process identity.', { code: 'tool.process.invalid' });
+    const record = await readJson(join(directory, 'runtime/processes', id + '.json'));
+    if (!record || record.id !== id)
+        throw new CliError('Unknown tool process.', { code: 'tool.process.missing' });
+    if (record.root !== join(directory, 'runtime/runs', id) || record.profileBinding !== digest(resolve(directory)))
+        return { ...record, state: 'unverified', phase: 'profile_binding_changed' };
+    const finishing = owned.get(ownedKey(directory, id));
+    if (finishing && (finishing.child.exitCode !== null || finishing.child.signalCode !== null)) {
+        await finishing.closed;
+        return processStatus(directory, id, verify);
+    }
+    let children;
+    try {
+        children = await nativeChildren(record);
+    }
+    catch {
+        return { ...record, state: 'unverified', phase: 'native_children_unverified' };
+    }
+    const pending = children.some(c => c.state === 'pending');
+    const observed = { ...record, ...(children.length ? { nativeChildren: children } : {}) };
+    if (['exited', 'failed'].includes(record.state))
+        return pending ? { ...observed, state: 'unverified', phase: 'native_children_pending' } : observed;
+    if (!record.pid) {
+        try {
+            process.kill(record.ownerPid, 0);
+            return record;
+        }
+        catch {
+            return { ...record, state: record.gated ? 'failed' : 'unverified', phase: 'owner_lost_before_pid' };
+        }
+    }
+    const identity = await processIdentity(record.pid);
+    if (!identity)
+        return { ...observed, state: pending ? 'unverified' : 'exited', phase: pending ? 'native_children_pending' : 'observed_exit', outcome: 'unknown' };
+    if (identity.birth !== record.identity)
+        return { ...record, state: 'unverified', phase: 'pid_identity_changed' };
+    const current = owned.get(ownedKey(directory, id)), local = current?.child.pid === record.pid && current.record.identity === record.identity && current.child.exitCode === null && current.child.signalCode === null;
+    const proof = verify ? await verify(record) : undefined;
+    if (local || proof === true || proof === undefined && record.strongIdentity && identity.strong)
+        return { ...observed, state: 'running' };
+    return { ...observed, state: 'unverified', phase: 'tool_identity_required' };
+}
+export async function listProcesses(directory, filter = {}, verify) {
+    let names;
+    try {
+        names = await readdir(join(directory, 'runtime/processes'));
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+    const items = [];
+    for (const name of names) {
+        if (!/^[a-f0-9-]{36}\.json$/.test(name))
+            continue;
+        const record = await processStatus(directory, name.slice(0, -5), verify);
+        if (filter.tool && record.tool !== filter.tool || filter.session && record.session !== filter.session || filter.target && record.target !== filter.target)
+            continue;
+        items.push(record);
+    }
+    return items.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+export async function terminateProcess(directory, id, force, verify, graceful) {
+    const path = join(directory, 'runtime/processes', id + '.json'), record = await processStatus(directory, id, verify);
+    if (['exited', 'failed'].includes(record.state))
+        return { process: id, state: 'already_exited' };
+    if (record.state !== 'running' || !record.pid)
+        throw new CliError('Process ownership is unverified; no signal was sent.', { code: 'tool.process.unverified' });
+    if (!force && graceful)
+        await graceful(record);
+    let current = await processStatus(directory, id, verify);
+    if (!['exited', 'failed'].includes(current.state)) {
+        if (current.state !== 'running' || current.pid !== record.pid)
+            throw new CliError('Process identity changed during stop.', { code: 'tool.process.unverified' });
+        current.requestedStop = force ? 'kill' : 'stop';
+        await atomicWrite(path, current);
+        const identity = await processIdentity(record.pid);
+        if (!identity || identity.birth !== record.identity)
+            throw new CliError('Process identity changed before signalling.', { code: 'tool.process.unverified' });
+        try {
+            if (process.platform !== 'win32' && record.processGroup === record.pid && identity.group === record.pid)
+                process.kill(-record.pid, force ? 'SIGKILL' : 'SIGTERM');
+            else
+                process.kill(record.pid, force ? 'SIGKILL' : 'SIGTERM');
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                throw error;
+        }
+        for (let i = 0; i < 100; i++) {
+            if (!await processIdentity(record.pid))
+                break;
+            await delay(50);
+        }
+        if (await processIdentity(record.pid))
+            throw new CliError('Owned process did not stop; its record is retained.', { code: 'tool.process.busy' });
+    }
+    await owned.get(ownedKey(directory, id))?.closed;
+    current = { ...(await readJson(path) ?? record), state: 'exited', outcome: force ? 'killed' : 'stopped', endedAt: new Date().toISOString() };
+    await atomicWrite(path, current);
+    return { process: id, state: force ? 'killed' : 'stopped', interrupted: force, tool: record.tool, session: record.session, target: record.target };
+}
+/** Migration/reconnection only: an adapter must authenticate a known existing tool before registration. */
+export async function registerExistingProcess(directory, spec, executable, pid, verify) {
+    toolRoot(directory, spec.tool);
+    const identity = await processIdentity(pid);
+    if (!identity)
+        throw new CliError('Existing tool process has exited.', { code: 'tool.process.missing' });
+    const hex = digest({ profile: resolve(directory), ...spec, pid, identity: identity.birth }).slice(0, 32), id = [hex.slice(0, 8), hex.slice(8, 12), hex.slice(12, 16), hex.slice(16, 20), hex.slice(20)].join('-');
+    const root = join(directory, 'runtime/runs', id), path = join(directory, 'runtime/processes', id + '.json');
+    const record = { schema: 1, id, ...spec, root, ownerPid: process.pid, profileBinding: digest(resolve(directory)), gated: false, state: 'running', phase: 'adopted_verified', createdAt: new Date().toISOString(), executable, pid, identity: identity.birth, strongIdentity: identity.strong, processGroup: identity.group };
+    if (!await verify(record))
+        throw new CliError('Existing process did not authenticate as the owned tool.', { code: 'tool.process.unverified' });
+    if ((await processIdentity(pid))?.birth !== identity.birth)
+        throw new CliError('Existing process identity changed during registration.', { code: 'tool.process.unverified' });
+    const previous = await readJson(path);
+    if (previous)
+        return id;
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    await atomicWrite(path, record);
+    return id;
+}

package/dist/src/tool-runtime/windows-job.d.ts

@@ -0,0 +1,22 @@
+/** Stock Windows PowerShell loads the packaged first-party Job Object executor; no runtime compiler. */
+export declare function windowsJobLaunch(root: string, nonce: string, executable: string, args: string[], cwd: string, timeoutMs: number, options?: {
+    observedSubject?: {
+        pid: number;
+        birth: string;
+    };
+    nativeMutex?: 'procmon';
+    nativeRegistry?: 'procmon';
+}): Promise<{
+    executable: string;
+    arguments: string[];
+}>;
+export declare function windowsJobResult(root: string, nonce: string, launcherPid: number, registryExpected?: boolean): Promise<{
+    registryIsolated?: boolean | undefined;
+    schema: number;
+    nonce: string;
+    launcherPid: number;
+    phase: string;
+    childExitCode: number;
+    childPid: number;
+    childBirthTicks: string;
+}>;

package/dist/src/tool-runtime/windows-job.js

@@ -0,0 +1,43 @@
+import { fileURLToPath } from 'node:url';
+import { readFile } from 'node:fs/promises';
+import { join, isAbsolute } from 'node:path';
+import { CliError } from '@eyeauras/cli-factory';
+import { fileSha256 } from './archives.js';
+import { atomicWrite, readJson } from './store.js';
+import { processIdentity } from './identity.js';
+/** Stock Windows PowerShell loads the packaged first-party Job Object executor; no runtime compiler. */
+export async function windowsJobLaunch(root, nonce, executable, args, cwd, timeoutMs, options = {}) {
+    if (process.platform !== 'win32' || !Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000)
+        throw new CliError('Owned Windows job deadline must be 1–600 seconds.', { code: 'tool.configuration' });
+    const native = fileURLToPath(new URL('../../../runtime/native/windows-job/', import.meta.url));
+    const proof = await readJson(join(native, 'provenance.json'));
+    if (!proof || await fileSha256(join(native, 'Insight.WindowsJob.dll')) !== proof.sha256 || await fileSha256(join(native, 'windows-job.ps1')) !== proof.launcherSha256)
+        throw new CliError('Packaged Windows job differs from its reviewed build.', { code: 'tool.binding' });
+    const identity = await processIdentity(process.pid), system = process.env.SystemRoot ?? process.env.WINDIR;
+    if (!identity?.strong || !/^\d+$/.test(identity.birth) || !system || !isAbsolute(system))
+        throw new CliError('Windows owner birth identity or system directory is unavailable.', { code: 'tool.process.unverified' });
+    if (options.observedSubject && (!Number.isSafeInteger(options.observedSubject.pid) || options.observedSubject.pid < 1 || !/^\d+$/.test(options.observedSubject.birth)))
+        throw new CliError('Borrowed Windows subject identity is invalid.', { code: 'tool.process.unverified' });
+    let registry = {};
+    if (options.nativeRegistry) {
+        const registryShim = join(native, '../insight-registry-win-x64.dll'), proof = await readJson(join(native, '../windows-registry.provenance.json'));
+        if (!proof || await fileSha256(registryShim) !== proof.sha256)
+            throw new CliError('Private Windows registry helper is missing or differs from its reviewed build.', { code: 'tool.binding' });
+        registry = { registryShim, registryShimSha256: proof.sha256 };
+    }
+    const specification = join(root, 'job-specification.json');
+    await atomicWrite(specification, { schema: 1, nonce, executable, arguments: args, cwd, timeoutMs, ownerPid: process.pid, ownerBirthTicks: identity.birth, ...registry, ...(options.observedSubject ? { observedPid: options.observedSubject.pid, observedBirthTicks: options.observedSubject.birth } : {}), ...(options.nativeMutex ? { nativeMutex: 'Local\\insight-cli-procmon-capture' } : {}) });
+    return { executable: join(system, 'System32/WindowsPowerShell/v1.0/powershell.exe'), arguments: ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', join(native, 'windows-job.ps1'), '-Specification', specification] };
+}
+export async function windowsJobResult(root, nonce, launcherPid, registryExpected = false) {
+    const result = await readJson(join(root, 'job-result.json'));
+    const started = await readJson(join(root, 'job-started.json'));
+    if (!result || !started || result.schema !== 1 || started.schema !== 1 || result.nonce !== nonce || started.nonce !== nonce || result.launcherPid !== launcherPid || started.launcherPid !== launcherPid || !['completed', 'timeout', 'owner_lost'].includes(result.phase) || !Number.isSafeInteger(result.childExitCode) || result.childExitCode < 0 || result.childExitCode > 0xffffffff || !Number.isSafeInteger(result.childPid) || result.childPid < 1 || result.childPid !== started.childPid || !/^\d+$/.test(result.childBirthTicks) || result.childBirthTicks !== started.childBirthTicks || started.phase !== 'assigned_suspended')
+        throw new CliError('Owned Windows job result is missing or unverified; no successful outcome was assumed.', { code: 'tool.process.unverified' });
+    if (registryExpected) {
+        const proof = await readFile(join(root, 'registry-isolated.bin'));
+        if (proof.length !== 48 || proof.readUInt32LE(0) !== 0x49484b31 || proof.readUInt32LE(4) !== result.childPid || proof.readUInt32LE(8) !== 0 || proof.subarray(12).toString('ascii') !== nonce)
+            throw new CliError('Private Windows registry initialization is unverified.', { code: 'tool.process.unverified' });
+    }
+    return { ...result, ...(registryExpected ? { registryIsolated: true } : {}) };
+}

package/dist/src/toolbox.d.ts

@@ -0,0 +1,84 @@
+import { type CommandDefinition } from '@eyeauras/cli-factory';
+interface PackagedSkill {
+    name: string;
+    title: string;
+    path: string;
+    resources: Record<string, string>;
+}
+interface Capability {
+    id: string;
+    namespace: string;
+    kind: 'analytical' | 'supporting' | 'capability';
+    skill: string;
+    purpose: string;
+    evaluationCase: {
+        id: string;
+        inputFamily: string;
+        task: string;
+        modes: string[];
+        requiredObservations: string[];
+    };
+    inputs: string[];
+    tasks: string[];
+    platforms: string[];
+    dependencies: string[];
+    workflowCommands: string[];
+    limitations: string[];
+}
+export interface Toolbox {
+    schema: 1;
+    skills: PackagedSkill[];
+    tools: Capability[];
+}
+export declare const toolbox: Toolbox;
+export declare function locateSkill(name?: string): {
+    version: string;
+    name: string;
+    bundlePath: string;
+    path: string;
+    skills: string[];
+};
+export declare function describeTool(id: string): {
+    status: string;
+    version: string;
+    skill: {
+        version: string;
+        name: string;
+        bundlePath: string;
+        path: string;
+        skills: string[];
+    };
+    runtime: {
+        required: boolean;
+        providedByNamespace: string;
+        dependencies: string[];
+        readiness?: undefined;
+        statusCommand?: undefined;
+    } | {
+        required: boolean;
+        readiness: string;
+        statusCommand: string[];
+        providedByNamespace?: undefined;
+        dependencies?: undefined;
+    };
+    id: string;
+    namespace: string;
+    kind: "analytical" | "supporting" | "capability";
+    purpose: string;
+    evaluationCase: {
+        id: string;
+        inputFamily: string;
+        task: string;
+        modes: string[];
+        requiredObservations: string[];
+    };
+    inputs: string[];
+    tasks: string[];
+    platforms: string[];
+    dependencies: string[];
+    workflowCommands: string[];
+    limitations: string[];
+};
+export declare function skillCommand(): CommandDefinition;
+export declare function toolboxCommands(): CommandDefinition[];
+export {};

package/dist/src/toolbox.js

@@ -0,0 +1,35 @@
+import { localCommand, CliError, tableView, recordView } from '@eyeauras/cli-factory';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { packageVersion } from './package-version.js';
+const packageRoot = new URL('../../', import.meta.url);
+export const toolbox = JSON.parse(readFileSync(new URL('runtime/toolbox.json', packageRoot), 'utf8'));
+export function locateSkill(name = 'insight-cli') {
+    const skill = toolbox.skills.find(s => s.name === name);
+    if (!skill)
+        throw new CliError(`Unknown skill '${name}'.`, { code: 'toolbox.skillNotFound', next: [['tools', 'list']] });
+    return { version: packageVersion, name, bundlePath: fileURLToPath(new URL('skill-bundle', packageRoot)), path: fileURLToPath(new URL(skill.path, packageRoot)), skills: toolbox.skills.map(s => s.name) };
+}
+export function describeTool(id) {
+    const tool = toolbox.tools.find(t => t.id === id);
+    if (!tool)
+        throw new CliError(`Unknown tool '${id}'.`, { code: 'toolbox.notFound', next: [['tools', 'list']] });
+    return { ...tool, status: 'available', version: packageVersion, skill: locateSkill(tool.skill),
+        runtime: tool.kind !== 'analytical' ? { required: false, providedByNamespace: tool.namespace, dependencies: tool.dependencies } : { required: true, readiness: 'notChecked', statusCommand: ['insight-cli', tool.namespace, 'status', '--json'] } };
+}
+export function skillCommand() {
+    return localCommand('skill [name]', 'Locate packaged tool instructions', ({ args }) => locateSkill(args.name === undefined ? undefined : String(args.name)), {
+        view: recordView({ fields: [{ label: 'Skill', value: x => x.name }, { label: 'Version', value: x => x.version }, { label: 'Path', value: x => x.path }] })
+    });
+}
+export function toolboxCommands() {
+    return [
+        localCommand('list', 'List shipped research capabilities', () => ({ version: packageVersion, items: toolbox.tools.map(t => ({ id: t.id, namespace: t.namespace, kind: t.kind, purpose: t.purpose, inputs: t.inputs, tasks: t.tasks, platforms: t.platforms, skill: t.skill, status: 'available' })) }), {
+            view: tableView({ rows: x => x.items, columns: [{ header: 'Tool', value: x => x.id }, { header: 'Purpose', value: x => x.purpose }, { header: 'Skill', value: x => x.skill }] })
+        }),
+        localCommand('show <tool>', 'Describe tasks and tool preparation', ({ args }) => describeTool(String(args.tool)), {
+            view: recordView({ fields: [{ label: 'Tool', value: x => x.id }, { label: 'Purpose', value: x => x.purpose }, { label: 'Kind', value: x => x.kind }, { label: 'Platforms', value: x => x.platforms.join(', ') }, { label: 'Dependencies', value: x => x.dependencies.join(', ') || 'none' }, { label: 'Skill', value: x => x.skill.path }],
+                sections: [{ title: () => 'Tasks', lines: x => x.tasks }, { title: () => 'Limitations', lines: x => x.limitations }], next: x => [['skill', x.skill.name]] })
+        }),
+    ];
+}

package/dist/src/tshark.d.ts

@@ -0,0 +1,23 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import type { Workspace } from './workspace.js';
+export declare function tsharkInstaller(c: CommandContext): ToolInstaller;
+export type PacketFields = Record<string, string[]>;
+export declare function tsharkRows(value: string): PacketFields[];
+export declare function tsharkStreams(rows: PacketFields[]): {
+    frames: number[];
+    sources: string[];
+    destinations: string[];
+    transport: string;
+    stream: number;
+}[];
+export declare function tsharkFollow(output: string, transport: string, stream: number): {
+    nodes: string[];
+    chunks: {
+        node: number;
+        hex: string;
+        bytes: number;
+    }[];
+    totalBytes: number;
+};
+export declare function tsharkCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];