@eyeauras/insight-cli 0.1.0 → 0.2.1

package/dist/src/dotnet-diagnostics.js

@@ -0,0 +1,101 @@
+import { managedHeapCommand } from './managed-heap.js';
+import { command, Permission } from '@eyeauras/cli-factory';
+import { join, resolve, dirname } from 'node:path';
+import { mkdir, stat, copyFile, writeFile } from 'node:fs/promises';
+import { constants, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import { defineTool, lifecycleCommands } from './tool-runtime/definition.js';
+import { catalogArtifact } from './tool-runtime/catalog.js';
+import { dotnetArtifact, dotnetLaunch } from './tool-runtime/dotnet.js';
+import { runTool } from './tool-runtime/run.js';
+import { processIdentity } from './tool-runtime/identity.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+const packages = {
+    'dotnet-dump': 'ae70c9f37548e1e006467893e21ae41a005fefaf2270e29642b415df053324a7',
+    'dotnet-stack': 'cd35f399fe023f1793b528590a4d723a1f2f1d9b25696386d926a697bd24c0ca',
+    'dotnet-trace': 'ef17f25724a55f9685bfaf8506a778ea87c2b62783eca2ca73263226128b0d4e',
+};
+export function diagnosticsInstaller(tool, c) {
+    return new ToolInstaller(c, { id: tool, primary: 'tool', noticeFiles: { 'notices/LICENSE.TXT': readFileSync(new URL('../../runtime/notices/diagnostics-10.0.750501.txt', import.meta.url), 'utf8') }, components: () => {
+            if (process.platform !== 'darwin' || process.arch !== 'arm64')
+                fail('unsupported', 'Managed diagnostics are currently verified on macOS ARM64; use an external compatible executable on another supported native platform.');
+            return { tool: catalogArtifact(packages[tool]), dotnet: dotnetArtifact() };
+        }, launch: roots => dotnetLaunch(roots.dotnet, join(roots.tool, tool + '.dll')), probe: async (launch, context) => {
+            const result = await runTool(context, { tool, role: 'version', executable: launch.executable, arguments: [...launch.arguments, '--version'], environment: launch.environment, maxOutputBytes: 65536, timeoutMs: 30000 });
+            if (!/^10\.0\.750501\+ad724c4b85e7ae775e42f393c6e95a7557a57954\s*$/m.test(result.stdout))
+                fail('configuration', 'The selected diagnostics executable must provide version 10.0.750501 from the pinned source commit.');
+            return { version: '10.0.750501', runtime: 'private .NET 10.0.13 for managed installations' };
+        } });
+}
+export function sosReadCommand(value) {
+    const result = text(value, 2048).trim().replace(/^!/, ''), verb = result.split(/\s/)[0];
+    if (/[\r\n;&|`]/.test(result) || !['help', 'clrthreads', 'clrstack', 'dumpheap', 'dumpobj', 'dumpclass', 'dumpmt', 'dumpmodule', 'dumpassembly', 'dumpdomain', 'dumparray', 'dumpvc', 'dumpil', 'gcroot', 'eeheap', 'threadpool', 'dumpasync', 'dumpdelegate', 'name2ee', 'ip2md', 'setthread'].includes(verb))
+        fail('invalid', 'Choose one supported SOS inspection command; command chaining, scripts and arbitrary debugger commands are unsupported.');
+    return result;
+}
+async function subject(pidValue) { const pid = number(pidValue, 2147483647, 1), identity = await processIdentity(pid); if (!identity || ['unavailable', 'unverified'].includes(identity.birth))
+    fail('binding', 'The selected external process does not have an observable OS birth identity.'); return { pid, ...identity, ownership: 'external' }; }
+async function unchanged(before) { const after = await processIdentity(before.pid); if (!after || after.birth !== before.birth)
+    fail('binding', 'The external process exited or changed during capture. Retained collector output is not acknowledged as a verified capture.'); }
+export function diagnosticsCommands(workspace) {
+    const common = [{ flags: '--output <file>', description: 'Write complete bounded text to a new ordinary file' }, { flags: '--limit <lines>', description: 'Native text page length (1–400)', defaultValue: 100 }, { flags: '--offset <lines>', description: 'Native text lines to skip', defaultValue: 0 }, { flags: '--timeout-seconds <seconds>', description: 'Collector/analyzer deadline (1–600)', defaultValue: 120 }];
+    const live = [{ flags: '--pid <pid>', description: 'Explicit external managed process; its lifetime remains with its owner', required: true }, { flags: '--diagnostic-directory <directory>', description: 'Target process TMPDIR when it differs from the invoking environment' }];
+    const native = (tool, description, commands) => {
+        const installer = (c) => diagnosticsInstaller(tool, c), definition = defineTool({ id: tool, description, components: [{ id: 'tool', version: '10.0.750501', artifacts: [], dependencies: ['dotnet'] }, { id: 'dotnet', version: '10.0.13', artifacts: [] }], lifecycle: { download: (o, c) => installer(c).download(Boolean(o.offline)), install: (o, c) => installer(c).install(o), uninstall: (o, c) => installer(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => installer(c).doctor(), status: (_o, c) => installer(c).status() }, installOptions: [{ flags: '--archive <file>', description: 'Pinned diagnostics NuGet/zip archive' }, { flags: '--archive-sha256 <sha256>', description: 'Expected diagnostics archive hash' }, { flags: '--dotnet-archive <file>', description: 'Private runtime archive' }, { flags: '--dotnet-archive-sha256 <sha256>', description: 'Expected private runtime hash' }, { flags: '--executable <file>', description: 'External compatible diagnostics executable; never removed' }, { flags: '--offline', description: 'Use only supplied archives and verified cache' }] });
+        return command(tool, description, [...lifecycleCommands(definition), ...commands]);
+    };
+    const execute = async (tool, role, argv, o, c) => diagnosticsInstaller(tool, c).use(async (selected) => runTool(c, { tool, role, installation: selected.id, executable: selected.executable, arguments: [...selected.arguments, ...argv], environment: { ...selected.environment, TMPDIR: o.diagnosticDirectory ? resolve(c.cwd, text(o.diagnosticDirectory, 4096)) : c.environment.TMPDIR ?? tmpdir() }, timeoutMs: number(o.timeoutSeconds, 600, 1) * 1000 }));
+    const textResult = async (result, o, c, extra = {}) => {
+        const base = { state: 'completed', ...extra, process: result.process, elapsedMs: result.elapsedMs, diagnostics: result.diagnostics, ...(result.stderr.trim() ? { warnings: result.stderr.slice(0, 4096), warningsTruncated: result.stderr.length > 4096 } : {}) };
+        if (o.output) {
+            const output = resolve(c.cwd, text(o.output, 4096));
+            await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+            await writeFile(output, result.stdout, { flag: 'wx', mode: 0o600 });
+            return { ...base, output, bytes: Buffer.byteLength(result.stdout) };
+        }
+        const offset = number(o.offset, 10000000, 0), limit = number(o.limit, 400, 1), lines = result.stdout.trimEnd().split(/\r?\n/);
+        return { ...base, content: lines.slice(offset, offset + limit).join('\n'), offset, limit, totalLines: lines.length, truncated: offset + limit < lines.length };
+    };
+    const input = async (args, o, c) => { if (Boolean(args.input) === Boolean(o.target))
+        fail('invalid', 'Supply exactly one input file or --target.'); const w = workspace(c), target = args.input ? await w.importTarget(resolve(c.cwd, text(args.input, 4096))) : w.target(id(o.target)); return { w, target, path: await w.artifacts.verify(target.input) }; };
+    const staged = async (c) => { const directory = join(c.appArguments.AppDataDirectory, 'runtime/exports', randomUUID()); await mkdir(directory, { recursive: true, mode: 0o700 }); return directory; };
+    const publish = async (path, o, c) => { const info = await stat(path); if (!info.isFile() || info.size < 1 || info.size > 4 * 1024 ** 3)
+        fail('limit', 'Capture/export must be a nonempty regular file below four GiB.'); const w = workspace(c), target = await w.importTarget(path), output = resolve(c.cwd, text(o.output, 4096)); await mkdir(dirname(output), { recursive: true, mode: 0o700 }); await copyFile(path, output, constants.COPYFILE_EXCL); return { output, bytes: info.size, target: target.id, inputSha256: target.binarySha256 }; };
+    const readOptions = [...common, { flags: '--target <id>', description: 'Reuse immutable captured dump/trace bytes' }];
+    const collect = (tool) => command('collect', 'Collect a bounded artifact from an explicitly selected external managed process', async ({ options: o }, c) => {
+        if (!o.output)
+            fail('invalid', 'Collection requires --output FILE.');
+        const before = await subject(o.pid), directory = await staged(c), path = join(directory, tool === 'dotnet-dump' ? 'capture.dmp' : 'capture.nettrace');
+        const args = ['collect', '--process-id', String(before.pid), '--output', path];
+        if (tool === 'dotnet-dump') {
+            const kind = text(o.type, 16);
+            if (!['Mini', 'Heap', 'Full'].includes(kind))
+                fail('invalid', 'Dump type must be Mini, Heap or Full.');
+            args.push('--type', kind);
+        }
+        else {
+            const seconds = number(o.durationSeconds, 60, 1), profile = text(o.traceProfile, 64);
+            if (!['dotnet-sampled-thread-time', 'dotnet-common', 'gc-collect', 'gc-verbose'].includes(profile))
+                fail('invalid', 'Choose a supported .NET EventPipe profile; Linux kernel CPU profiles are not this collect API.');
+            args.push('--duration', '00:00:' + String(Math.floor(seconds / 60)).padStart(2, '0') + ':' + String(seconds % 60).padStart(2, '0'), '--profile', profile, '--buffersize', '16');
+        }
+        const result = await execute(tool, 'collect', args, o, c);
+        await unchanged(before);
+        return { state: 'captured', subject: before, ...await publish(path, o, c), process: result.process, diagnostics: result.diagnostics, elapsedMs: result.elapsedMs, ...(tool === 'dotnet-trace' ? { profile: o.traceProfile, durationSeconds: Number(o.durationSeconds), measurement: 'EventPipe events for the selected profile; not a kernel CPU measurement' } : { dumpType: o.type }) };
+    }, { permission: Permission.Update, options: [...common, ...live, ...(tool === 'dotnet-dump' ? [{ flags: '--type <kind>', description: 'Mini, Heap or Full', defaultValue: 'Heap' }] : [{ flags: '--duration-seconds <seconds>', description: 'Collection duration (1–60)', defaultValue: 5 }, { flags: '--trace-profile <profile>', description: 'EventPipe profile', defaultValue: 'dotnet-sampled-thread-time' }])] });
+    return [native('dotnet-dump', 'Capture compatible managed dumps and inspect them with SOS', [
+            managedHeapCommand(workspace, c => diagnosticsInstaller('dotnet-dump', c)), collect('dotnet-dump'), command('analyze [input]', 'Run one focused SOS inspection against immutable dump bytes', async ({ args, options: o }, c) => { const selected = await input(args, o, c), query = sosReadCommand(o.command), result = await execute('dotnet-dump', 'analyze', ['analyze', selected.path, '--command', query, '--command', 'exit'], o, c); return textResult(result, o, c, { target: selected.target.id, inputSha256: selected.target.binarySha256, query, interpretation: 'Inspect native SOS output; absence/errors are not proof that a requested object exists' }); }, { permission: Permission.Update, options: [...readOptions, { flags: '--command <query>', description: 'One supported SOS inspection, for example clrstack or dumpheap -type TYPE', required: true }] })
+        ]),
+        native('dotnet-stack', 'Read live managed thread stacks without taking ownership of the target', [
+            command('report', 'Read stacks from an explicitly selected external managed process', async ({ options: o }, c) => { const before = await subject(o.pid), result = await execute('dotnet-stack', 'report', ['report', '--process-id', String(before.pid)], o, c); await unchanged(before); return textResult(result, o, c, { subject: before }); }, { permission: Permission.Update, options: [...common, ...live] })
+        ]),
+        native('dotnet-trace', 'Collect bounded EventPipe traces and inspect sampled managed stacks', [
+            collect('dotnet-trace'), command('report [input]', 'Rank methods by sampled thread time in an immutable trace', async ({ args, options: o }, c) => { const selected = await input(args, o, c), argsNative = ['report', selected.path, 'topN', '--number', String(number(o.count, 100, 1)), ...(o.exclusive ? [] : ['--inclusive'])], result = await execute('dotnet-trace', 'report', argsNative, o, c); return textResult(result, o, c, { target: selected.target.id, inputSha256: selected.target.binarySha256, measurement: 'Sampled thread time; sleeping frames can dominate without consuming CPU' }); }, { permission: Permission.Update, options: [...readOptions, { flags: '--count <methods>', description: 'Maximum ranked methods (1–100)', defaultValue: 10 }, { flags: '--exclusive', description: 'Rank exclusive instead of inclusive samples' }] }),
+            command('convert [input]', 'Export an immutable trace to a new Speedscope or Chromium JSON file', async ({ args, options: o }, c) => { if (!o.output)
+                fail('invalid', 'Conversion requires --output FILE.'); const format = text(o.format, 32); if (!['Speedscope', 'Chromium'].includes(format))
+                fail('invalid', 'Format must be Speedscope or Chromium.'); const selected = await input(args, o, c), directory = await staged(c), prefix = join(directory, 'converted'), result = await execute('dotnet-trace', 'convert', ['convert', selected.path, '--format', format, '--output', prefix], o, c), path = prefix + (format === 'Speedscope' ? '.speedscope.json' : '.chromium.json'); return { state: 'converted', sourceTarget: selected.target.id, ...await publish(path, o, c), process: result.process, diagnostics: result.diagnostics }; }, { permission: Permission.Update, options: [...readOptions, { flags: '--format <format>', description: 'Speedscope or Chromium', defaultValue: 'Speedscope' }] })
+        ])];
+}

package/dist/src/frida-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/frida-worker.js

@@ -0,0 +1,125 @@
+// Internal bounded collector process, never a second public CLI or persistent service.
+import { pathToFileURL } from 'node:url';
+import { processIdentity } from './tool-runtime/identity.js';
+import { inheritedDeadlineEnvironment } from './tool-runtime/deadline.js';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+async function main() {
+    let input = '';
+    for await (const chunk of process.stdin) {
+        input += chunk;
+        if (Buffer.byteLength(input) > 2 * 1024 ** 2)
+            throw Error('Collector request exceeds two MiB');
+    }
+    const config = JSON.parse(input);
+    // Set this after Node starts: only SDK helper execs load the constructor, not the target.
+    const receipts = join(process.env.HOME, 'native-deadlines');
+    await mkdir(receipts, { mode: 0o700 });
+    Object.assign(process.env, await inheritedDeadlineEnvironment(config.deadlineUnixSeconds, receipts));
+    // This import is intentionally isolated in an owned child; native addon faults cannot crash the owner.
+    const frida = await import(pathToFileURL(config.module).href);
+    const emit = (value) => process.stdout.write(JSON.stringify(value) + '\n');
+    if (config.mode === 'probe') {
+        const version = await frida.getLocalDevice();
+        emit({ kind: 'probe', protocol: 1, version: '17.24.0', device: version.type });
+        return;
+    }
+    const cancellable = new frida.Cancellable();
+    let session, script, detached = false, finished = false, error = false, unloaded = false, sessionDetached = false, loaded = false, interrupted = false, count = 0;
+    const duration = config.durationMs ?? 1000, deadline = setTimeout(() => cancellable.cancel(), duration + 5000);
+    let resolveDone;
+    const done = new Promise(ok => resolveDone = ok);
+    let observation;
+    const stop = () => { interrupted = true; error = true; emit({ kind: 'interrupted', signal: 'SIGTERM' }); resolveDone(); if (!loaded)
+        cancellable.cancel(); };
+    process.once('SIGTERM', stop);
+    try {
+        if (!config.pid || (await processIdentity(config.pid))?.birth !== config.expectedBirth)
+            throw Error('Target birth identity changed before attach');
+        session = await frida.attach(config.pid, {}, cancellable);
+        session.detached.connect((reason, crash) => { detached = true; if (!finished) {
+            error = true;
+            emit({ kind: 'detached', reason, crash: Boolean(crash) });
+            resolveDone();
+        } });
+        let source = config.source;
+        if (config.mode === 'modules')
+            source = 'send({kind:"modules",items:Process.enumerateModules().map(m=>({name:m.name,path:m.path,base:m.base.toString(),size:m.size}))});';
+        if (config.mode === 'exports')
+            source = 'send({kind:"exports",module:' + JSON.stringify(config.moduleName) + ',items:Process.getModuleByName(' + JSON.stringify(config.moduleName) + ').enumerateExports()});';
+        // Keep user source untouched (strict directives and source line numbers matter).
+        const bootstrap = await session.createScript('send(Frida.version);', {}, cancellable);
+        let versionTimer;
+        const version = new Promise((ok, bad) => { bootstrap.message.connect((message) => message.type === 'send' ? ok(message.payload) : bad(new Error('Frida runtime version probe failed'))); versionTimer = setTimeout(() => bad(new Error('Frida runtime version probe timed out')), 5000); });
+        void version.catch(() => { });
+        try {
+            await bootstrap.load(cancellable);
+            const actual = await version;
+            emit({ kind: 'runtime', version: actual });
+            if (actual !== '17.24.0')
+                throw Error('Frida runtime version differs from 17.24.0');
+        }
+        finally {
+            if (versionTimer)
+                clearTimeout(versionTimer);
+            await bootstrap.unload(cancellable);
+        }
+        script = await session.createScript(source, {}, cancellable);
+        script.message.connect((message, data) => {
+            if (++count > 10000) {
+                error = true;
+                if (count === 10001)
+                    emit({ kind: 'limit', message: 'Collector exceeded 10000 messages' });
+                resolveDone();
+                return;
+            }
+            if (message.type === 'error') {
+                error = true;
+                resolveDone();
+            }
+            emit({ kind: 'message', message, ...(data ? { binaryBase64: data.toString('base64') } : {}) });
+            if (config.mode !== 'observe' && message.type === 'send' && message.payload?.kind === config.mode)
+                resolveDone();
+        });
+        await script.load(cancellable);
+        loaded = true;
+        emit({ kind: 'loaded' });
+        observation = setTimeout(resolveDone, duration);
+        await done;
+    }
+    finally {
+        if (observation)
+            clearTimeout(observation);
+        finished = true;
+        const cleanup = new frida.Cancellable(), cleanupDeadline = setTimeout(() => cleanup.cancel(), 2000);
+        try {
+            if (script && !detached) {
+                await script.unload(cleanup);
+                unloaded = true;
+            }
+        }
+        catch (e) {
+            error = true;
+            emit({ kind: 'cleanup-error', message: String(e) });
+        }
+        try {
+            if (session && !detached) {
+                await session.detach(cleanup);
+                sessionDetached = true;
+            }
+        }
+        catch (e) {
+            error = true;
+            emit({ kind: 'cleanup-error', message: String(e) });
+        }
+        clearTimeout(cleanupDeadline);
+        cleanup.cancel();
+        clearTimeout(deadline);
+        cancellable.cancel();
+        process.off('SIGTERM', stop);
+    }
+    emit({ kind: 'completed', complete: !error && unloaded && sessionDetached, detached, scriptUnloaded: unloaded, sessionDetached });
+    if (interrupted)
+        process.exitCode = 130;
+}
+main().catch(error => { process.stderr.write(String(error) + '\n'); process.exitCode = 1; });

package/dist/src/frida.d.ts

@@ -0,0 +1,16 @@
+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 fridaInstaller(c: CommandContext): ToolInstaller;
+export declare function fridaEvents(stdout: string): {
+    events: Record<string, any>[];
+    summary: {
+        totalEvents: number;
+        sendMessages: number;
+        scriptErrors: number;
+        logMessages: number;
+    };
+    complete: boolean;
+    cleanup: Record<string, any>;
+};
+export declare function fridaCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/frida.js

@@ -0,0 +1,125 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { dirname, join, resolve } from 'node:path';
+import { release } from 'node:os';
+import { readFile, mkdir, writeFile, stat } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import { defineTool, lifecycleCommands } from './tool-runtime/definition.js';
+import { catalogArtifact } from './tool-runtime/catalog.js';
+import { runTool } from './tool-runtime/run.js';
+import { treeFingerprint } from './tool-runtime/store.js';
+import { processIdentity } from './tool-runtime/identity.js';
+import { fail, text } from './model.js';
+import { number } from './research.js';
+const worker = fileURLToPath(new URL('./frida-worker.js', import.meta.url)), moduleRoot = (entry) => dirname(dirname(dirname(entry)));
+function supported() { if (process.platform !== 'darwin' || process.arch !== 'arm64' || Number(release().split('.')[0]) < 23)
+    fail('unsupported', 'This Frida facade requires macOS 14+ ARM64 and an explicitly selected authorized local process.'); }
+async function entryMetadata(entry) {
+    if (!entry.endsWith(join('build', 'src', 'frida.js')))
+        fail('configuration', 'External Frida selection requires its Node entry module at .../frida/build/src/frida.js; use managed install by default.');
+    let metadata;
+    try {
+        const path = join(moduleRoot(entry), 'package.json');
+        if ((await stat(path)).size > 128 * 1024)
+            fail('configuration', 'Invalid external Frida metadata.');
+        metadata = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        fail('configuration', 'External Frida Node package metadata is missing or invalid.');
+    }
+    if (metadata.name !== 'frida' || metadata.version !== '17.24.0')
+        fail('configuration', 'Select the Frida 17.24.0 Node entry module with its native NAPI-v8 binding and runtime dependencies.');
+    return metadata;
+}
+export function fridaInstaller(c) {
+    return new ToolInstaller(c, { id: 'frida', primary: 'frida', components: () => { supported(); return { frida: catalogArtifact('26e9e7b9a8d9c68c87cb3da879c328edd096d587720039095de6a522d2c8765e') }; }, launch: roots => ({ executable: join(roots.frida, 'node_modules/frida/build/src/frida.js'), arguments: [], environment: {} }), externalInputs: async (entry) => {
+            supported();
+            await entryMetadata(entry);
+            const values = { frida: await treeFingerprint(moduleRoot(entry)) };
+            for (const name of ['bindings', 'file-uri-to-path', 'minimatch', 'brace-expansion', 'balanced-match']) {
+                let found = false;
+                for (const base of createRequire(entry).resolve.paths(name) ?? []) {
+                    try {
+                        const root = join(base, name), metadata = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+                        if (metadata.name !== name)
+                            fail('binding', 'External Frida dependency identity differs.');
+                        values[name] = await treeFingerprint(root);
+                        found = true;
+                        break;
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw error;
+                    }
+                }
+                if (!found)
+                    fail('configuration', 'External Frida runtime dependency is missing: ' + name);
+            }
+            return values;
+        }, probe: async (launch, context) => {
+            supported();
+            const metadata = await entryMetadata(launch.executable);
+            const result = await runTool(context, { tool: 'frida', role: 'probe', executable: process.execPath, arguments: ['--no-warnings', worker], input: JSON.stringify({ mode: 'probe', module: launch.executable, deadlineUnixSeconds: Math.ceil(Date.now() / 1000) + 10 }), timeoutMs: 10000, nativeDeadline: true, nativeChildDeadlines: true, maxOutputBytes: 65536 });
+            const value = JSON.parse(result.stdout);
+            if (value.kind !== 'probe' || value.protocol !== 1 || value.device !== 'local')
+                fail('binding', 'Frida native binding did not provide a compatible local-device API.');
+            return { declaredVersion: metadata.version, node: process.version, entryKind: 'Node module', nativeApi: 'local device', pythonRequired: false };
+        } });
+}
+export function fridaEvents(stdout) {
+    const events = stdout.trim().split(/\r?\n/).filter(Boolean).map(line => { try {
+        return JSON.parse(line);
+    }
+    catch {
+        fail('binding', 'Frida collector returned malformed events; inspect retained native diagnostics.');
+    } });
+    const completed = events.at(-1);
+    if (completed?.kind !== 'completed' || typeof completed.complete !== 'boolean')
+        fail('partial', 'Frida did not acknowledge bounded capture and cleanup; inspect process diagnostics.');
+    const errors = events.some(e => ['detached', 'cleanup-error', 'limit'].includes(e.kind) || e.kind === 'message' && e.message?.type === 'error');
+    const summary = { totalEvents: events.length, sendMessages: events.filter(e => e.kind === 'message' && e.message?.type === 'send').length, scriptErrors: events.filter(e => e.kind === 'message' && e.message?.type === 'error').length, logMessages: events.filter(e => e.kind === 'message' && e.message?.type === 'log').length };
+    return { events, summary, complete: !errors && completed.complete === true && completed.scriptUnloaded === true && completed.sessionDetached === true && events.some(e => e.kind === 'runtime' && e.version === '17.24.0'), cleanup: completed };
+}
+export function fridaCommands(workspace) {
+    const definition = defineTool({ id: 'frida', description: 'Inspect modules/exports or collect bounded Frida script events from an explicit local PID', components: [{ id: 'frida', version: '17.24.0', artifacts: [] }], installOptions: [{ flags: '--archive <path>', description: 'Install a local Frida Node runtime archive' }, { flags: '--archive-sha256 <sha256>', description: 'Expected local archive hash' }, { flags: '--executable <path>', description: 'External Frida Node entry module: .../frida/build/src/frida.js' }, { flags: '--offline', description: 'Use verified local cache without network access' }], lifecycle: { download: (o, c) => fridaInstaller(c).download(Boolean(o.offline)), install: (o, c) => fridaInstaller(c).install(o), uninstall: (o, c) => fridaInstaller(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => fridaInstaller(c).doctor(), status: (_o, c) => fridaInstaller(c).status() } });
+    const options = [{ flags: '--pid <pid>', description: 'Explicit authorized local process; its lifetime remains external', required: true }, { flags: '--output <file>', description: 'Save all bounded collector events to a new JSON file' }, { flags: '--limit <count>', description: 'Maximum returned events (1–1000)', defaultValue: 100 }, { flags: '--offset <count>', description: 'Skip events', defaultValue: 0 }];
+    const collect = (mode) => command(mode, mode === 'observe' ? 'Load a captured Frida JavaScript file, observe for a bounded interval, unload and detach' : mode === 'modules' ? 'Inventory runtime modules in the selected local process' : 'Inventory exported addresses in one selected runtime module', async ({ options: o }, c) => {
+        supported();
+        const pid = number(o.pid, 2147483647, 1), before = await processIdentity(pid);
+        if (pid === process.pid || !before || ['unavailable', 'unverified'].includes(before.birth))
+            fail('binding', 'Select a different live process with an observable OS birth identity.');
+        const durationMs = mode === 'observe' ? number(o.durationSeconds ?? 2, 120, 1) * 1000 : 1000, limit = number(o.limit ?? 100, 1000, 1), offset = number(o.offset ?? 0, 1000000), moduleName = mode === 'exports' ? text(o.module, 4096) : undefined;
+        let source, scriptSha256;
+        if (mode === 'observe') {
+            const w = workspace(c), path = resolve(c.cwd, text(o.script, 4096)), metadata = await stat(path);
+            if (!metadata.isFile() || metadata.size > 256 * 1024)
+                fail('limit', 'Frida script must be a regular file of at most 256 KiB.');
+            const artifact = await w.artifacts.capture(path, 'input');
+            if (artifact.size > 256 * 1024)
+                fail('limit', 'Frida script exceeds 256 KiB.');
+            try {
+                source = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(await readFile(await w.artifacts.verify(artifact)));
+            }
+            catch {
+                fail('invalid', 'Frida JavaScript source must be valid UTF-8.');
+            }
+            scriptSha256 = artifact.sha256;
+        }
+        return fridaInstaller(c).use(async (selected) => {
+            const result = await runTool(c, { tool: 'frida', role: mode, installation: selected.id, metadata: { subjectPid: pid, subjectBirth: before.birth, durationMs, ...(scriptSha256 ? { scriptSha256 } : {}), ...(moduleName ? { moduleName } : {}) }, executable: process.execPath, arguments: ['--no-warnings', worker], input: JSON.stringify({ module: selected.executable, mode, pid, expectedBirth: before.birth, moduleName, source, durationMs, deadlineUnixSeconds: Math.ceil(Date.now() / 1000) + (durationMs + 10000) / 1000 }), timeoutMs: durationMs + 10000, nativeDeadline: true, nativeChildDeadlines: true }), capture = fridaEvents(result.stdout), after = await processIdentity(pid), sameProcess = after?.birth === before.birth, complete = capture.complete && sameProcess;
+            const records = mode === 'observe' ? undefined : capture.events.filter(e => e.kind === 'message' && e.message?.type === 'send' && e.message.payload?.kind === mode).flatMap(e => Array.isArray(e.message.payload.items) ? e.message.payload.items : []);
+            const base = { state: complete ? 'completed' : 'partial', complete, summary: capture.summary, subject: { pid, birth: before.birth, strongIdentity: before.strong, ownership: 'external', sameProcessAfterCapture: sameProcess }, ...(scriptSha256 ? { scriptSha256 } : {}), process: result.process, diagnostics: result.diagnostics, elapsedMs: result.elapsedMs, stderr: result.stderr, cleanup: capture.cleanup, coverage: 'Observed execution during this interval; static correspondence and unobserved paths require separate evidence. macOS birth identity is best effort. Collector stop/kill never signals the external target.' };
+            if (o.output) {
+                const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify({ ...base, events: capture.events }, null, 2) + '\n';
+                await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+                await writeFile(output, content, { flag: 'wx', mode: 0o600 });
+                return { ...base, output, bytes: Buffer.byteLength(content), totalEvents: capture.events.length };
+            }
+            if (records)
+                return { ...base, records: records.slice(offset, offset + limit), offset, limit, totalRecords: records.length, truncated: offset + limit < records.length, events: capture.events.filter(e => !(e.kind === 'message' && e.message?.payload?.kind === mode)) };
+            return { ...base, events: capture.events.slice(offset, offset + limit), offset, limit, totalEvents: capture.events.length, truncated: offset + limit < capture.events.length };
+        });
+    }, { permission: Permission.Update, options: [...options, ...(mode === 'exports' ? [{ flags: '--module <name>', description: 'Exact runtime module name or path', required: true }] : mode === 'observe' ? [{ flags: '--script <file>', description: 'Frida JavaScript source file; captured immutably before attach', required: true }, { flags: '--duration-seconds <seconds>', description: 'Observation window after script load (1–120)', defaultValue: 2 }] : [])] });
+    return [command('frida', definition.description, [...lifecycleCommands(definition), collect('modules'), collect('exports'), collect('observe')])];
+}

package/dist/src/ghidra-debugger-runtime.d.ts

@@ -0,0 +1,7 @@
+/** Private Python-capable LLDB dependency. The public application remains `ghidra`. */
+import type { CommandContext } from '@eyeauras/cli-factory';
+import { ToolInstaller, type ToolLaunch } from './tool-runtime/installer.js';
+export declare const managedGhidraDebugger: () => boolean;
+export declare function ghidraDebuggerLaunch(root: string): ToolLaunch;
+export declare function ghidraDebuggerInstaller(c: CommandContext): ToolInstaller;
+export declare function prepareGhidraDebugger(c: CommandContext, o?: Record<string, unknown>): Promise<import("./tool-runtime/installer.js").SelectedTool>;

package/dist/src/ghidra-debugger-runtime.js

@@ -0,0 +1,31 @@
+import { join } from 'node:path';
+import { release } from 'node:os';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import { catalogArtifact } from './tool-runtime/catalog.js';
+import { runTool } from './tool-runtime/run.js';
+import { fail } from './model.js';
+export const managedGhidraDebugger = () => process.platform === 'darwin' && process.arch === 'arm64' && Number(release().split('.')[0]) >= 24;
+export function ghidraDebuggerLaunch(root) {
+    const python = join(root, 'python@3.15/3.15.0/Frameworks/Python.framework/Versions/3.15');
+    return { executable: join(root, 'bin/lldb'), arguments: [], environment: { PYTHONHOME: python, PYTHONPATH: join(root, 'lldb/23.1.3_1/lib/python3.15/site-packages'), LLDB_PYTHON_LIBRARY: join(python, 'Python'), LLDB_DEBUGSERVER_PATH: join(root, 'bin/debugserver'), PYTHONNOUSERSITE: '1', PYTHONDONTWRITEBYTECODE: '1' } };
+}
+export function ghidraDebuggerInstaller(c) {
+    return new ToolInstaller(c, {
+        id: 'ghidra-debugger', primary: 'lldb', components: () => {
+            if (!managedGhidraDebugger())
+                fail('unsupported', 'The managed Ghidra LLDB/Python backend requires macOS 15+ ARM64.');
+            return { lldb: catalogArtifact('0f9e88490490fb2f487ad6f02d7aea774629a2839a10497fdcbaad9c6481c839') };
+        }, launch: roots => ghidraDebuggerLaunch(roots.lldb), probe: async (launch) => {
+            const result = await runTool(c, { tool: 'ghidra-debugger', role: 'doctor', executable: launch.executable, arguments: ['--no-lldbinit', '--batch', '-o', 'script import lldb,sys; print("INSIGHT_LLDB_PYTHON_OK",lldb.SBDebugger.GetVersionString(),sys.version_info[:2])'], environment: { ...launch.environment, PATH: '/usr/bin:/bin' }, timeoutMs: 30000, maxOutputBytes: 65536, nativeDeadline: true });
+            if (!result.stdout.includes('INSIGHT_LLDB_PYTHON_OK lldb version 23.1.3 (3, 15)'))
+                fail('configuration', 'The managed debugger must load LLDB 23.1.3 and its own Python 3.15.');
+            return { version: '23.1.3', python: '3.15', backend: 'managed-lldb', hostHomebrewRequired: false };
+        }
+    });
+}
+export async function prepareGhidraDebugger(c, o = {}) {
+    const installer = ghidraDebuggerInstaller(c);
+    if (o.archive || (await installer.status()).state !== 'installed')
+        await installer.install(o);
+    return installer.selected();
+}

package/dist/src/ghidra-processes.d.ts

@@ -0,0 +1,6 @@
+import type { CommandContext } from '@eyeauras/cli-factory';
+import { type ProcessRecord } from './tool-runtime/supervisor.js';
+import type { ToolProcessHooks } from './tool-runtime/commands.js';
+import type { Scope, Workspace } from './workspace.js';
+export declare function verifyGhidraProcess(r: ProcessRecord, c: CommandContext): Promise<boolean | undefined>;
+export declare function ghidraProcessHooks(workspace: (c: CommandContext) => Workspace, close: (scope: Scope, c: CommandContext) => Promise<unknown>): ToolProcessHooks;

package/dist/src/ghidra-processes.js

@@ -0,0 +1,121 @@
+import { runtimeSelection } from './runtime-selection.js';
+import { join, resolve, relative, sep } from 'node:path';
+import { readFile, readdir, realpath } from 'node:fs/promises';
+import { serverIdentity, stopLocalServer } from './server.js';
+import { HttpBridge } from './transport.js';
+import { registerExistingProcess } from './tool-runtime/supervisor.js';
+import { fail } from './model.js';
+async function ownedPath(c, path) {
+    if (typeof path !== 'string')
+        fail('binding', 'Tool resource moved outside this profile.');
+    const supplied = resolve(path), profile = resolve(c.appArguments.AppDataDirectory), canonical = await realpath(profile);
+    const base = supplied.startsWith(profile + sep) ? profile : supplied.startsWith(canonical + sep) ? canonical : undefined;
+    if (!base)
+        fail('binding', 'Tool resource moved outside this profile.');
+    // Keep Factory's raw AppData identity in process records, but compare native resources
+    // under its canonical profile. Accept the parent alias, never a replaced child link.
+    const expected = join(canonical, relative(base, supplied));
+    if (await realpath(supplied) !== expected)
+        fail('binding', 'Tool resource moved outside this profile.');
+    return expected;
+}
+export async function verifyGhidraProcess(r, c) {
+    try {
+        if (r.metadata?.serverDirectory) {
+            const directory = await ownedPath(c, r.metadata.serverDirectory), local = JSON.parse(await readFile(join(directory, 'server/local.json'), 'utf8'));
+            return Number((await serverIdentity(local, c)).pid) === r.pid;
+        }
+        if (r.metadata?.debuggerReceipt) {
+            const path = await ownedPath(c, r.metadata.debuggerReceipt), row = JSON.parse(await readFile(path, 'utf8')), root = await ownedPath(c, r.metadata.contextRoot), binding = JSON.parse(await readFile(join(root, 'process.json'), 'utf8'));
+            if (row.root !== root || row.ownerToken !== binding.tokenSecret || row.guiPid !== binding.pid || !Number.isSafeInteger(row.identityPort) || row.identityPort < 1 || row.identityPort > 65535)
+                return false;
+            const token = await c.secrets.require(binding.tokenSecret), response = await c.fetch('http://127.0.0.1:' + row.identityPort + '/identity', { redirect: 'error', signal: AbortSignal.timeout(1000), headers: { Authorization: 'Bearer ' + token } });
+            const body = await response.text();
+            if (!response.ok || body.length > 4096)
+                return false;
+            const info = JSON.parse(body);
+            return info.id === row.id && info.pid === row.supervisorPid && (r.role === 'debugger' ? info.childPid === r.pid : info.pid === r.pid);
+        }
+        if (r.metadata?.contextRoot) {
+            const root = await ownedPath(c, r.metadata.contextRoot), binding = JSON.parse(await readFile(join(root, 'process.json'), 'utf8'));
+            if (binding.root !== root || binding.pid !== r.pid || binding.runtimeFingerprint !== r.installation || binding.target !== r.target)
+                return false;
+            const token = await c.secrets.require(binding.tokenSecret), info = await new HttpBridge(binding.endpoint, c.fetch, undefined, token, 1500).instance();
+            return info.pid === r.pid && info.tcp_port === Number(new URL(binding.endpoint).port) && String(info.project_path ?? '').startsWith(root + sep);
+        }
+        return undefined;
+    }
+    catch {
+        return false;
+    }
+}
+export function ghidraProcessHooks(workspace, close) {
+    return {
+        verify: verifyGhidraProcess,
+        async discover(c) {
+            const directory = c.appArguments.AppDataDirectory, executable = runtimeSelection(directory)?.java ?? String(c.profile.values.java ?? 'unverified-legacy-executable');
+            async function walk(path, depth = 0) {
+                if (depth > 6)
+                    return;
+                let entries;
+                try {
+                    entries = await readdir(path, { withFileTypes: true });
+                }
+                catch (e) {
+                    if (e.code === 'ENOENT')
+                        return;
+                    throw e;
+                }
+                for (const entry of entries) {
+                    const at = join(path, entry.name);
+                    if (entry.isDirectory())
+                        await walk(at, depth + 1);
+                    else if (entry.name === 'process.json') {
+                        const b = JSON.parse(await readFile(at, 'utf8'));
+                        if (b.toolProcessId || !b.pid)
+                            continue;
+                        let session;
+                        if (b.context)
+                            session = workspace(c).contextById(b.context).session;
+                        try {
+                            await registerExistingProcess(directory, { tool: 'ghidra', role: b.mode === 'gui' ? 'gui' : b.kind, installation: b.runtimeFingerprint, target: b.target, session, metadata: { contextRoot: b.root } }, executable, b.pid, r => verifyGhidraProcess(r, c));
+                        }
+                        catch { }
+                    }
+                }
+            }
+            await walk(join(directory, 'workspace/ghidra-native'));
+            try {
+                const b = JSON.parse(await readFile(join(directory, 'workspace/server/local.json'), 'utf8'));
+                if (!b.toolProcessId && b.pid)
+                    await registerExistingProcess(directory, { tool: 'ghidra', role: 'server', installation: 'legacy', metadata: { serverDirectory: join(directory, 'workspace') } }, executable, b.pid, r => verifyGhidraProcess(r, c));
+            }
+            catch { }
+        },
+        async stop(r, c) {
+            if (r.metadata?.contextRoot) {
+                if (!r.session || !r.target)
+                    fail('busy', 'Internal Ghidra task is active; finish it before stopping its process.');
+                await close({ session: r.session, target: r.target }, c);
+            }
+            else if (r.role === 'server') {
+                const { runtimeProcesses } = await import('./runtime-manager.js');
+                if ((await runtimeProcesses(c.appArguments.AppDataDirectory)).some(p => p.kind !== 'server'))
+                    fail('busy', 'Close Ghidra contexts before stopping their server.');
+                await stopLocalServer(await ownedPath(c, r.metadata?.serverDirectory), c);
+            }
+        },
+        async beforeKill(r, c) {
+            // Save debugger traces and terminate the inferior through the existing authenticated GUI
+            // protocol. A generic signal to LLDB cannot establish that its debuggee has exited.
+            if (r.role === 'gui' && r.session && r.target) {
+                const scope = { session: r.session, target: r.target }, w = workspace(c), context = w.context(scope);
+                const debuggerActive = context.debugger?.connected || context.debugger?.traces.some(t => t.connected) || w.unresolved(scope).some(q => q.execution?.kind === 'debugger');
+                if (debuggerActive)
+                    await close(scope, c);
+            }
+            if (r.role.startsWith('debugger'))
+                fail('blocked', 'Close the owning GUI context to verify debugger and inferior cleanup.');
+        },
+    };
+}

package/dist/src/ghidra.js

@@ -1,6 +1,6 @@
-import { promisify } from 'node:util';
+import { runTool } from './tool-runtime/run.js';
+import { launchProcess } from './tool-runtime/supervisor.js';
 import { fileURLToPath } from 'node:url';
-import { spawn, execFile } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, open, readFile, readdir, cp, realpath, stat } from 'node:fs/promises';
 import { join, delimiter, resolve, isAbsolute, sep } from 'node:path';
@@ -89,7 +89,7 @@ export class GhidraRuntime {
         if (bridgeSecret && bridgeToken)
             await this.context.secrets.set(bridgeSecret, bridgeToken);
         const log = await open(join(root, 'process.log'), 'a', 0o600);
-        const child = spawn(java, ['-Xmx768m', '-Djava.awt.headless=true', '-Dghidra.home=' + home, '-Dapplication.name=GhidraMCP', '-Duser.home=' + root, '-Djava.io.tmpdir=' + root, '-cp', jars.join(delimiter), 'com.xebyte.headless.GhidraMCPHeadlessServer', '--bind', '127.0.0.1', '--port', String(port)], {
+        const child = await launchProcess(this.context.appArguments.AppDataDirectory, { tool: 'ghidra', role: 'prototype-' + role, installation: expected }, java, ['-Xmx768m', '-Djava.awt.headless=true', '-Dghidra.home=' + home, '-Dapplication.name=GhidraMCP', '-Duser.home=' + root, '-Djava.io.tmpdir=' + root, '-cp', jars.join(delimiter), 'com.xebyte.headless.GhidraMCPHeadlessServer', '--bind', '127.0.0.1', '--port', String(port)], {
             cwd: root, detached: true, stdio: ['ignore', log.fd, log.fd], windowsHide: true,
             env: { PATH: this.context.environment.PATH ?? process.env.PATH, HOME: root, TMPDIR: root, XDG_RUNTIME_DIR: this.directory,
                 GHIDRA_SERVER_HOST: url.hostname, GHIDRA_SERVER_PORT: url.port || '13100', GHIDRA_SERVER_USER: user, GHIDRA_SERVER_PASSWORD: password,
@@ -295,9 +295,9 @@ export class GhidraRuntime {
         const script = fileURLToPath(new URL('../../references/InsightRepositoryProbe.java', import.meta.url));
         let stdout;
         try {
-            ({ stdout } = await promisify(execFile)(java, ['-Djava.awt.headless=true', '-Dghidra.home=' + home, '-Duser.home=' + root, '-Djava.io.tmpdir=' + root, '-cp', jars.join(delimiter), '--source', '21', script, t.repository, t.programPath, role], {
-                cwd: root, timeout: 30000, maxBuffer: 262144, signal: this.context.signal,
-                env: { PATH: process.env.PATH, HOME: root, TMPDIR: root, GHIDRA_SERVER_HOST: url.hostname, GHIDRA_SERVER_PORT: url.port || '13100', GHIDRA_SERVER_USER: text(values[role === 'reader' ? 'readerUser' : 'publisherUser']), GHIDRA_SERVER_PASSWORD: password }
+            ({ stdout } = await runTool(this.context, { tool: 'ghidra', role: 'prototype-authority', executable: java, arguments: ['-Djava.awt.headless=true', '-Dghidra.home=' + home, '-Duser.home=' + root, '-Djava.io.tmpdir=' + root, '-cp', jars.join(delimiter), '--source', '21', script, t.repository, t.programPath, role],
+                cwd: root, timeoutMs: 30000, maxOutputBytes: 262144,
+                environment: { PATH: process.env.PATH, HOME: root, TMPDIR: root, GHIDRA_SERVER_HOST: url.hostname, GHIDRA_SERVER_PORT: url.port || '13100', GHIDRA_SERVER_USER: text(values[role === 'reader' ? 'readerUser' : 'publisherUser']), GHIDRA_SERVER_PASSWORD: password }
             }));
         }
         catch {

package/dist/src/ilspy.d.ts

@@ -0,0 +1,7 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { type ToolArtifact } from './tool-runtime/definition.js';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import type { Workspace } from './workspace.js';
+export declare function ilspyComponents(platform?: string, architecture?: NodeJS.Architecture): Record<string, ToolArtifact>;
+export declare function ilspyInstaller(c: CommandContext): ToolInstaller;
+export declare function ilspyCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];