@eyeauras/insight-cli 0.1.0 → 0.2.1

package/dist/src/debugger-supervisor.js

@@ -1,9 +1,13 @@
 /** Internal LLDB child owner. It has no public command or independent product IPC host. */
-import { spawn } from 'node:child_process';
+import { launchProcess, registerExistingProcess } from './tool-runtime/supervisor.js';
+import { createServer } from 'node:http';
 import { readFile, writeFile, mkdir, open, rename, realpath } from 'node:fs/promises';
 import { join, resolve, delimiter } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { HttpBridge } from './transport.js';
+import { callerMonitor } from './debugger-caller.js';
+import { debuggerLaunchArguments } from './debugger-launch.js';
+import { verifyManagedInstallation } from './tool-runtime/installer.js';
 async function main() {
     const root = await realpath(process.argv[2]), binding = JSON.parse(await readFile(join(root, 'process.json'), 'utf8'));
     if (root !== resolve(root) || binding.root !== root || binding.mode !== 'gui' || !Number.isSafeInteger(binding.pid))
@@ -38,6 +42,23 @@ async function main() {
     finally {
         await parent.close();
     } }
+    const appData = process.env.INSIGHT_TOOL_APPDATA, canonicalAppData = appData ? await realpath(appData) : undefined;
+    if (!appData || !canonicalAppData || !root.startsWith(join(canonicalAppData, 'workspace', 'ghidra-native') + '/'))
+        throw Error('Invalid tool profile');
+    if (binding.debuggerRuntime)
+        await verifyManagedInstallation(appData, 'ghidra-debugger', binding.debuggerRuntime);
+    const authority = createServer((req, res) => { if (req.url !== '/identity' || req.headers.authorization !== 'Bearer ' + token) {
+        res.writeHead(403).end();
+        return;
+    } res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify({ id, pid: process.pid, childPid: receipt.childPid, state: receipt.state })); });
+    await new Promise(ok => authority.listen(0, '127.0.0.1', ok));
+    authority.unref();
+    const address = authority.address();
+    if (!address || typeof address === 'string')
+        throw Error('No debugger identity port');
+    Object.assign(receipt, { identityPort: address.port });
+    const processSpec = { tool: 'ghidra', installation: binding.runtimeFingerprint, target: binding.target, session: binding.session, metadata: { debuggerReceipt: path, debuggerDiagnostics: join(directory, id + '.diagnostic.log'), contextRoot: root, ...(binding.debuggerRuntime ? { debuggerInstallation: binding.debuggerRuntime.id, debuggerFingerprint: binding.debuggerRuntime.fingerprint } : {}) } };
+    const helperProcess = await registerExistingProcess(appData, { ...processSpec, role: 'debugger-supervisor' }, process.execPath, process.pid, async () => true);
     await saved();
     const environment = { ...process.env };
     delete environment.GHIDRA_MCP_AUTH_TOKEN;
@@ -47,14 +68,22 @@ async function main() {
     const python = await realpath(environment.INSIGHT_DEBUGGER_PYTHON ?? '');
     if (!python.startsWith(root + '/debug-python-') || python !== environment.INSIGHT_DEBUGGER_PYTHON)
         throw Error('Owned debugger Python identity changed');
+    let debuggerExecutable = '/usr/bin/lldb';
+    if (binding.debuggerRuntime) {
+        debuggerExecutable = binding.debuggerRuntime.executable;
+        Object.assign(environment, binding.debuggerRuntime.environment);
+        Object.assign(receipt, { debuggerInstallation: binding.debuggerRuntime.id, debuggerFingerprint: binding.debuggerRuntime.fingerprint });
+    }
     environment.PYTHONPATH = python + delimiter + (environment.PYTHONPATH ?? '');
     delete environment.INSIGHT_DEBUGGER_PYTHON;
-    let closing = false, finished = false;
+    let closing = false, finished = false, launchComplete = false;
     process.once('SIGHUP', close);
     process.once('SIGTERM', close);
     // A separate session keeps the GUI terminal's SIGHUP from bypassing our orderly kill.
-    const child = spawn('/usr/bin/lldb', ['--no-lldbinit', '-o', 'settings set auto-confirm true', ...process.argv.slice(3)], { env: environment, detached: true, stdio: ['pipe', 'pipe', 'pipe'] });
-    const exited = new Promise((ok, bad) => { child.once('error', bad); child.once('exit', () => { finished = true; ok(); }); });
+    const launchArguments = process.argv.slice(3), usesGhidra = launchArguments.includes('script import os, ghidralldb');
+    const child = await launchProcess(appData, { ...processSpec, role: 'debugger' }, debuggerExecutable, ['--no-lldbinit', '-o', 'settings set auto-confirm true', '-o', 'settings set target.detach-on-error false', ...debuggerLaunchArguments(launchArguments, launch.stopAtEntry === true, usesGhidra ? python : undefined)], { env: environment, detached: true, stdio: ['pipe', 'pipe', 'pipe'] });
+    launchComplete = true;
+    const exited = child.toolClosed.then(() => { finished = true; });
     void exited.catch(() => { });
     receipt.childPid = child.pid ?? 0;
     receipt.state = 'running';
@@ -87,6 +116,10 @@ async function main() {
     function close() {
         if (closing || finished)
             return;
+        if (!launchComplete) {
+            setTimeout(close, 10).unref();
+            return;
+        }
         closing = true;
         process.stdin.pause();
         child.stdout.unpipe(process.stdout);
@@ -104,13 +137,23 @@ async function main() {
         child.kill('SIGINT'); });
     process.stdin.once('end', close);
     process.stdin.once('error', close);
-    const monitor = setInterval(() => { try {
-        process.kill(binding.pid, 0);
-    }
-    catch (error) {
-        if (error.code === 'ESRCH')
-            close();
-    } }, 250);
+    const observeCaller = callerMonitor(python, command => { if (!closing && !finished)
+        child.stdin.write(command); });
+    let callerDiagnostic = false;
+    const monitor = setInterval(() => {
+        try {
+            process.kill(binding.pid, 0);
+        }
+        catch (error) {
+            if (error.code === 'ESRCH')
+                close();
+        }
+        if (!closing && !finished)
+            void observeCaller().catch(() => { if (!callerDiagnostic) {
+                callerDiagnostic = true;
+                process.stderr.write('Native caller observation failed; its request is retained.\n');
+            } });
+    }, 250);
     try {
         await saved();
         await exited;
@@ -122,13 +165,13 @@ async function main() {
         receipt.inferiorTerminated = result?.id === id && result.inferiorTerminated === true;
         receipt.state = receipt.inferiorTerminated ? 'closed' : 'failed';
         Object.assign(receipt, { exitCode: child.exitCode, signalCode: child.signalCode });
-        if (!receipt.inferiorTerminated)
-            await writeFile(join(directory, id + '.diagnostic.log'), diagnostics, { mode: 0o600 });
+        await writeFile(join(directory, id + '.diagnostic.log'), diagnostics, { mode: 0o600 });
         await saved();
     }
     finally {
         clearInterval(monitor);
         process.stdin.pause();
+        authority.close();
     }
     // Keep a failed child outcome observable; never claim that killing LLDB proves inferior exit.
     process.exitCode = receipt.inferiorTerminated ? 0 : 1;

package/dist/src/debugger.js

@@ -3,7 +3,7 @@ import { resolve } from 'node:path';
 import { scope, address, number } from './research.js';
 import { id, text, object, fail } from './model.js';
 import { selectedOptions } from './arguments.js';
-import { debuggerResult, debuggerProgramMetadata as metadata } from './debugger-results.js';
+import { debuggerResult, debuggerExecutionSettled, debuggerProgramMetadata as metadata } from './debugger-results.js';
 import { setTimeout as delay } from 'node:timers/promises';
 import { randomUUID } from 'node:crypto';
 const lists = ['launch_offers', 'modules', 'list_breakpoints', 'stack_trace'];
@@ -89,7 +89,7 @@ export class Debugger {
                 if (request.state === 'failed' && result.reason === 'disconnected')
                     fail('disconnected', 'Selected trace has no live target.', result);
                 if (request.state === 'failed' && result.reason === 'busy')
-                    fail('busy', 'This context already has a live debug target; use another session for another process.', result);
+                    fail('busy', 'This context still has a connected debugger; close/reopen it or use another session before a new launch.', result);
                 if (request.state === 'failed' && result.reason === 'native_precondition')
                     fail('rejected', 'The native live precondition failed; the target write was not started.', result);
                 fail('unknown', 'Debugger action is retained and is not repeated.', request.result);
@@ -98,7 +98,7 @@ export class Debugger {
             if (operation === 'launch' && (await backend.debuggerSaved(selected)).connected) {
                 const result = { ...selected, state: 'not_started', reason: 'busy' };
                 this.workspace.recordRequest(request.id, 'failed', result);
-                fail('busy', 'This context already has a live debug target; use another session for another process.', result);
+                fail('busy', 'This context still has a connected debugger; close/reopen it or use another session before a new launch.', result);
             }
             const before = debuggerResult('status', {}, await backend.debuggerCall(selected, 'status'));
             if (operation !== 'launch' && object(before).target_connected !== true) {
@@ -125,11 +125,10 @@ export class Debugger {
                 }
                 const value = debuggerResult(operation, p, raw);
                 if (['resume', 'interrupt', 'step'].includes(operation)) {
-                    const wanted = operation === 'resume' ? 'RUNNING' : 'STOPPED';
                     let observed = false;
                     for (let attempt = 0; attempt < 40; attempt++) {
                         const status = object(debuggerResult('status', {}, await backend.debuggerCall(selected, 'status')));
-                        if (status.execution_state === wanted || operation === 'resume' && status.execution_state === 'STOPPED' && BigInt(String(status.snap ?? 0)) > BigInt(String(object(before).snap ?? 0))) {
+                        if (debuggerExecutionSettled(operation, object(before), status)) {
                             observed = true;
                             break;
                         }
@@ -151,11 +150,16 @@ export class Debugger {
                     if (!observed)
                         fail('partial', 'Breakpoint inventory did not verify the action.');
                 }
+                if (operation === 'launch' && p.stop_at_entry === true) {
+                    const stopped = object(debuggerResult('status', {}, await backend.debuggerCall(selected, 'status')));
+                    if (stopped.target_connected !== true || stopped.execution_state !== 'STOPPED')
+                        fail('partial', 'Entry-stop launch did not verify a stopped live target.');
+                }
                 saved = await backend.debuggerSaved(selected);
                 savedSnapshot = await backend.saved(selected);
                 metadataChanged = beforeMetadata !== undefined && beforeMetadata !== await metadata(backend, savedSnapshot);
                 const complexChanges = metadataChanged ? [...context.complexChanges, request.id] : context.complexChanges;
-                const result = { ...selected, state: 'applied', ...(saved.active ? { trace: saved.active } : {}), pendingChanges: context.scalars.length + complexChanges.length, sharedState: context.scalars.length || complexChanges.length ? 'pending' : 'shared', value };
+                const result = { ...selected, state: 'applied', ...(operation === 'launch' && p.stop_at_entry === true ? { stoppedAtEntry: true } : {}), ...(saved.active ? { trace: saved.active } : {}), pendingChanges: context.scalars.length + complexChanges.length, sharedState: context.scalars.length || complexChanges.length ? 'pending' : 'shared', value };
                 this.workspace.completeSavedRequest(selected, request.id, context.generation, { debugger: saved, workingSnapshot: savedSnapshot, complexChanges }, result);
                 return result;
             }
@@ -195,7 +199,7 @@ export function debuggerCommands(service) {
             ...(operation === 'schedule' ? [{ flags: '--schedule <time>', description: 'Parse and validate a native time schedule without executing it', required: true }] : []),
             ...(paged ? [{ flags: '--limit <count>', description: 'Page size 1–100', defaultValue: 50 }, { flags: '--offset <count>', description: 'Page offset', defaultValue: 0 }] : []),
             ...(operation === 'step' ? [{ flags: '--kind <kind>', description: 'into, over or out', defaultValue: 'into' }] : []),
-            ...(operation === 'launch' ? [{ flags: '--args <text>', description: 'Target command-line arguments', defaultValue: '' }, { flags: '--cwd <directory>', description: 'Target working directory (default owned run folder)' },
+            ...(operation === 'launch' ? [{ flags: '--stop-at-entry', description: 'macOS local LLDB: launch stopped at entry for inspection before running' }, { flags: '--args <text>', description: 'Target command-line arguments', defaultValue: '' }, { flags: '--cwd <directory>', description: 'Target working directory (default owned run folder)' },
                 { flags: '--offer <name>', description: 'Launch offer title or configuration name', defaultValue: process.platform === 'win32' ? 'dbgeng' : process.platform === 'darwin' ? 'lldb' : 'gdb' }, { flags: '--timeout-seconds <count>', description: 'Launch wait 1–300 seconds', defaultValue: 60 }] : []), ...(changing ? [request] : [])];
         leaves.push(command(operation.replaceAll('_', '-'), 'Use the selected context debugger', ({ options: o }, c) => {
             const p = {};
@@ -248,6 +252,11 @@ export function debuggerCommands(service) {
                     fail('invalid', 'Step kind must be into, over or out.');
             }
             if (operation === 'launch') {
+                if (o.stopAtEntry === true) {
+                    if (process.platform !== 'darwin' || o.offer !== 'lldb')
+                        fail('unsupported', '--stop-at-entry requires the local macOS lldb offer.');
+                    p.stop_at_entry = true;
+                }
                 if (typeof o.args !== 'string' || o.args.length > 8192 || o.args.includes('\0'))
                     fail('invalid', 'Arguments must be bounded text.');
                 p.args = o.args;

package/dist/src/die.d.ts

@@ -0,0 +1,12 @@
+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 dieInstaller(c: CommandContext): ToolInstaller;
+/** Upstream may append signature errors after its JSON while exiting zero. Never discard them. */
+export declare function dieJson(stdout: string, stderr: string): {
+    data: Record<string, unknown>;
+    diagnostics: string[];
+    complete: boolean;
+};
+export declare function dieFindings(data: Record<string, unknown>): Record<string, string>[];
+export declare function dieCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/die.js

@@ -0,0 +1,127 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { dirname, join, resolve } from 'node:path';
+import { release } from 'node:os';
+import { mkdir, writeFile, stat } from 'node:fs/promises';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import { treeFingerprint } from './tool-runtime/store.js';
+import { defineTool, lifecycleCommands } from './tool-runtime/definition.js';
+import { catalogArtifact } from './tool-runtime/catalog.js';
+import { runTool } from './tool-runtime/run.js';
+import { fileSha256 } from './tool-runtime/archives.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+const frameworks = ['QtConcurrent', 'QtCore', 'QtCore5Compat', 'QtNetwork', 'QtQml'];
+const contents = (executable) => dirname(dirname(executable));
+export function dieInstaller(c) {
+    return new ToolInstaller(c, { id: 'die', primary: 'die', components: () => {
+            if (process.platform !== 'darwin' || process.arch !== 'arm64' || Number(release().split('.')[0]) < 22)
+                fail('unsupported', 'Managed DiE requires macOS 13+ ARM64.');
+            return { die: catalogArtifact('5fc9f1d870b4c791ae688a07ccbae0dcdf677eedeeb6ae732bbc83eac61148af') };
+        }, launch: roots => ({ executable: join(roots.die, 'MacOS/diec'), arguments: [], environment: {} }), externalInputs: async (executable) => {
+            const root = contents(executable), inputs = {};
+            // The database is executable signature code: fingerprint it as part of the external tool.
+            for (const name of ['db', 'db_custom'])
+                inputs['Resources/' + name] = await treeFingerprint(join(root, 'Resources', name));
+            inputs['Resources/qt.conf'] = await fileSha256(join(root, 'Resources/qt.conf'));
+            for (const path of ['MacOS/qt.conf', 'Info.plist', 'PlugIns'])
+                try {
+                    const at = join(root, path);
+                    inputs[path] = (await stat(at)).isDirectory() ? await treeFingerprint(at) : await fileSha256(at);
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+            if (process.platform === 'darwin')
+                for (const name of frameworks)
+                    inputs[name] = await treeFingerprint(join(root, 'Frameworks', name + '.framework'));
+            return inputs;
+        }, probe: async (launch, context) => {
+            const root = contents(launch.executable);
+            await stat(join(root, 'Resources/db/_init'));
+            const r = await runTool(context, { tool: 'die', role: 'version', executable: launch.executable, arguments: ['--version'], maxOutputBytes: 65536, timeoutMs: 30000 });
+            if (!/\b3\.21\b/.test(r.stdout))
+                fail('configuration', 'The selected Detect It Easy console must provide version 3.21 with its adjacent Resources/db database.');
+            return { version: '3.21', database: 'adjacent Resources/db', managedMinimumMacOS: '13.0', signaturesAreHeuristic: true };
+        } });
+}
+/** Upstream may append signature errors after its JSON while exiting zero. Never discard them. */
+export function dieJson(stdout, stderr) {
+    const start = stdout.search(/\S/);
+    if (start < 0 || stdout[start] !== '{')
+        fail('binding', 'DiE did not return a JSON object; inspect the retained native process diagnostics.');
+    let depth = 0, string = false, escaped = false, end = -1;
+    for (let i = start; i < stdout.length; i++) {
+        const ch = stdout[i];
+        if (string) {
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                string = false;
+        }
+        else if (ch === '"')
+            string = true;
+        else if (ch === '{')
+            depth++;
+        else if (ch === '}' && --depth === 0) {
+            end = i + 1;
+            break;
+        }
+    }
+    if (end < 0)
+        fail('binding', 'DiE returned incomplete JSON; inspect the retained native process diagnostics.');
+    let data;
+    try {
+        data = JSON.parse(stdout.slice(start, end));
+    }
+    catch {
+        fail('binding', 'DiE returned malformed JSON; inspect the retained native process diagnostics.');
+    }
+    const diagnostics = [stdout.slice(end).trim(), stderr.trim()].filter(Boolean);
+    return { data, diagnostics, complete: diagnostics.length === 0 };
+}
+export function dieFindings(data) {
+    if (!Array.isArray(data.detects))
+        fail('binding', 'DiE omitted its detection array; retained output is not a complete classification.');
+    const rows = [];
+    for (const group of data.detects) {
+        if (!group || typeof group !== 'object' || typeof group.filetype !== 'string' || !Array.isArray(group.values))
+            fail('binding', 'DiE returned an unsupported detection schema.');
+        for (const value of group.values) {
+            if (!value || typeof value !== 'object' || ['name', 'type', 'version', 'info', 'string'].some(k => typeof value[k] !== 'string'))
+                fail('binding', 'DiE returned an unsupported signature record.');
+            rows.push({ fileType: group.filetype, offset: String(group.offset ?? ''), region: String(group.parentfilepart ?? ''), ...Object.fromEntries(['name', 'type', 'version', 'info', 'string'].map(k => [k, value[k]])) });
+        }
+    }
+    return rows;
+}
+export function dieCommands(workspace) {
+    const definition = defineTool({ id: 'die', description: 'Classify binaries and retain compiler, runtime or packer signature evidence', components: [{ id: 'die', version: '3.21', artifacts: [] }], lifecycle: { download: (o, c) => dieInstaller(c).download(Boolean(o.offline)), install: (o, c) => dieInstaller(c).install(o), uninstall: (o, c) => dieInstaller(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => dieInstaller(c).doctor(), status: (_o, c) => dieInstaller(c).status() } });
+    return [command('die', definition.description, [...lifecycleCommands(definition), command('classify [input]', 'Read input format/architecture and signature evidence without running the input', async ({ args, options: o }, c) => {
+                if (Boolean(args.input) === Boolean(o.target))
+                    fail('invalid', 'Supply exactly one input path or --target.');
+                const limit = number(o.limit, 400, 1), offset = number(o.offset, 1000000, 0), timeoutMs = number(o.timeoutSeconds, 600, 1) * 1000;
+                const w = workspace(c), target = args.input ? await w.importTarget(resolve(c.cwd, text(args.input, 4096))) : w.target(id(o.target)), input = await w.artifacts.verify(target.input);
+                return dieInstaller(c).use(async (selected) => {
+                    const database = join(contents(selected.executable), 'Resources/db'), calls = [];
+                    for (const mode of ['info', 'scan']) {
+                        const result = await runTool(c, { tool: 'die', role: mode, installation: selected.id, executable: selected.executable, arguments: ['--json', '--database', database, ...(mode === 'info' ? ['--info'] : [...(o.deep ? ['--deepscan'] : []), ...(o.heuristic ? ['--heuristicscan'] : [])]), input], environment: selected.environment, target: target.id, timeoutMs });
+                        calls.push({ mode, result, parsed: dieJson(result.stdout, result.stderr) });
+                    }
+                    const info = calls[0].parsed.data.data;
+                    if (!info?.Info || typeof info.Info !== 'object' || Array.isArray(info.Info))
+                        fail('binding', 'DiE omitted its file information view.');
+                    const findings = dieFindings(calls[1].parsed.data), diagnostics = calls.flatMap(call => call.parsed.diagnostics.map(message => ({ view: call.mode, message }))), complete = diagnostics.length === 0;
+                    const base = { state: complete ? 'completed' : 'partial', complete, target: target.id, inputSha256: target.binarySha256, information: info.Info, diagnostics, coverage: 'Heuristic signatures are evidence; Unknown or no match does not prove absence of packing, obfuscation or a runtime.', processes: calls.map(call => ({ view: call.mode, process: call.result.process, diagnostics: call.result.diagnostics, elapsedMs: call.result.elapsedMs })) };
+                    if (o.output) {
+                        const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify({ ...base, findings }, 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), totalFindings: findings.length };
+                    }
+                    return { ...base, findings: findings.slice(offset, offset + limit), totalFindings: findings.length, offset, limit, truncated: offset + limit < findings.length };
+                });
+            }, { permission: Permission.Update, options: [{ flags: '--target <id>', description: 'Reuse an immutable research target' }, { flags: '--deep', description: 'Enable deeper signature scanning' }, { flags: '--heuristic', description: 'Enable optional heuristic scanning' }, { flags: '--output <file>', description: 'Save the full bounded classification and all warnings to a new JSON file' }, { flags: '--limit <count>', description: 'Maximum signature findings (1–400)', defaultValue: 100 }, { flags: '--offset <count>', description: 'Skip signature findings', defaultValue: 0 }, { flags: '--timeout-seconds <seconds>', description: 'Deadline per native view (1–600)', defaultValue: 120 }] })])];
+}

package/dist/src/dnspy-runtime.d.ts

@@ -0,0 +1,8 @@
+import type { CommandContext } from '@eyeauras/cli-factory';
+export declare const dnspyNative: string;
+export declare function prepareDnspy(root: string, c: CommandContext): Promise<void>;
+export declare function prepareExternalDnspy(executable: string, stage: string, c: CommandContext): Promise<{
+    executable: string;
+    arguments: never[];
+    environment: {};
+}>;

package/dist/src/dnspy-runtime.js

@@ -0,0 +1,46 @@
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdir, copyFile, rename, lstat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { atomicWrite, readJson } from './tool-runtime/store.js';
+import { fileSha256, archiveName } from './tool-runtime/archives.js';
+import { runTool } from './tool-runtime/run.js';
+import { fail } from './model.js';
+export const dnspyNative = fileURLToPath(new URL('../../runtime/native/dnspy-extension/', import.meta.url));
+const engine = 'dnSpy.Debugger.DotNet.CorDebug.x.dll', original = '13e0c4ea5396d071cdc7e31f0e5e9036c51da734a00b27d9d3dfeda9fa5b722f';
+export async function prepareDnspy(root, c) {
+    const input = join(root, 'bin', engine);
+    if (await fileSha256(input) !== original)
+        fail('binding', 'The pinned dnSpy Core engine differs before local Unicode preparation.');
+    const directory = join(c.appArguments.AppDataDirectory, 'runtime/dnspy/preparation', randomUUID()), extension = join(directory, 'extension');
+    await mkdir(extension, { recursive: true, mode: 0o700 });
+    await copyFile(join(dnspyNative, 'Insight.DnSpy.x.dll'), join(extension, 'Insight.DnSpy.x.dll'), constants.COPYFILE_EXCL);
+    const nonce = randomUUID(), plan = join(directory, 'plan.json'), result = join(directory, 'result.json'), output = join(directory, engine);
+    await atomicWrite(plan, { Schema: 1, Nonce: nonce, Mode: 'patch-engine', Input: input, Output: output, BuildKey: join(dnspyNative, 'upstream-public-build.snk'), Result: result });
+    await runTool(c, { tool: 'dnspy', role: 'prepare-unicode-loader', executable: join(root, 'dnSpy.exe'), arguments: ['--multiple', '--no-activate', '--settings-file', join(directory, 'settings.xml'), '--extension-directory', extension, '--insight-plan:' + plan], nativeDeadline: true, timeoutMs: 60000, maxOutputBytes: 65536 });
+    const receipt = await readJson(result);
+    if (receipt?.schema !== 1 || receipt.nonce !== nonce || receipt.data?.state !== 'completed' || receipt.data.mode !== 'patch-engine' || receipt.data.beforeSha256 !== original || !receipt.data.unicodeLoader || !receipt.data.strongNameIdentityPreserved || await fileSha256(output) !== receipt.data.afterSha256)
+        fail('binding', 'Owned dnSpy Unicode-loader preparation was not verified.', { diagnostics: directory });
+    // The one-shot process has exited and the native Job has closed before replacing any mapped engine.
+    await rename(output, input);
+    await atomicWrite(join(root, 'insight-unicode-loader.json'), receipt.data);
+}
+export async function prepareExternalDnspy(executable, stage, c) {
+    const manifest = await readJson(join(dnspyNative, 'vendor-files.json'));
+    if (manifest?.schema !== 1 || manifest.files.length !== 867)
+        fail('binding', 'Pinned dnSpy file inventory is missing.');
+    const originalRoot = dirname(executable), owned = join(stage, 'execution');
+    for (const entry of manifest.files) {
+        archiveName(entry.path);
+        const source = join(originalRoot, entry.path), destination = join(owned, entry.path), info = await lstat(source);
+        if (!info.isFile() || info.size !== entry.size || await fileSha256(source) !== entry.sha256)
+            fail('binding', 'External dnSpy component differs from the pinned vendor bundle.', { component: entry.path });
+        await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+        await copyFile(source, destination, constants.COPYFILE_EXCL);
+        if (await fileSha256(destination) !== entry.sha256)
+            fail('binding', 'Copied dnSpy component differs from the pinned vendor bundle.');
+    }
+    await prepareDnspy(owned, c);
+    return { executable: join(owned, 'dnSpy.exe'), arguments: [], environment: {} };
+}

package/dist/src/dnspy.d.ts

@@ -0,0 +1,22 @@
+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 dnspyInstaller(c: CommandContext): ToolInstaller;
+export declare function dnspyToken(value: unknown): number;
+export declare function dnspyPlan(o: Record<string, unknown>, mode: 'debug' | 'edit-constant'): {
+    ExpectedConstant: number;
+    ReplacementConstant: number;
+    Schema: number;
+    Mode: "debug" | "edit-constant";
+    Token: number;
+    Offset: number;
+} | {
+    Runtime: string;
+    Parameters: number[];
+    Arguments: string[];
+    Schema: number;
+    Mode: "debug" | "edit-constant";
+    Token: number;
+    Offset: number;
+};
+export declare function dnspyCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/dnspy.js

@@ -0,0 +1,160 @@
+import { command, Permission, CliError } from '@eyeauras/cli-factory';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { copyFile, mkdir, writeFile, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+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 } from './tool-runtime/dotnet.js';
+import { runTool } from './tool-runtime/run.js';
+import { fileSha256 } from './tool-runtime/archives.js';
+import { treeFingerprint, atomicWrite, readJson } from './tool-runtime/store.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+import { dnspyNative as native, prepareDnspy, prepareExternalDnspy } from './dnspy-runtime.js';
+function supported() { if (process.platform !== 'win32' || process.arch !== 'x64')
+    fail('unsupported', 'dnSpyEx requires Windows x64 with an interactive desktop; managed targets execute only in an owned debugger context.'); }
+async function bridgeIdentity() { const identity = await readJson(join(native, 'provenance.json')); if (!identity || await fileSha256(join(native, 'Insight.DnSpy.x.dll')) !== identity.sha256)
+    fail('binding', 'Packaged dnSpy extension differs from its reviewed build.'); return identity; }
+export function dnspyInstaller(c) {
+    return new ToolInstaller(c, { id: 'dnspy', primary: 'dnspy', preparationId: 'unicode-core-loader-v1', prepare: (roots, c) => prepareDnspy(roots.dnspy, c), prepareExternal: prepareExternalDnspy, components: () => { supported(); return { dnspy: catalogArtifact('8ed48f165dc355e869f3a0037ad4f9216147f995a5ae0258b296eeef1f73aab0'), dotnet: dotnetArtifact() }; }, launch: roots => ({ executable: join(roots.dnspy, 'dnSpy.exe'), arguments: [], environment: { DOTNET_ROOT: roots.dotnet, DOTNET_MULTILEVEL_LOOKUP: '0', DOTNET_CLI_TELEMETRY_OPTOUT: '1' } }), externalInputs: async (executable) => { supported(); if (basename(executable).toLowerCase() !== 'dnspy.exe')
+            fail('configuration', 'Select the dnSpyEx 6.6.0 root dnSpy.exe and its complete adjacent bin directory.'); return { runtimeFamily: await treeFingerprint(dirname(executable)) }; }, probe: async (launch, context) => {
+            supported();
+            const root = dirname(launch.executable), identity = await bridgeIdentity();
+            for (const [name, expected] of Object.entries(identity.contracts))
+                if (await fileSha256(join(root, 'bin', name)) !== expected)
+                    fail('binding', 'dnSpyEx runtime contracts differ from the pinned 6.6.0 build.', { component: name });
+            const system = process.env.SystemRoot ?? process.env.WINDIR;
+            if (!system)
+                fail('configuration', 'Windows system directory is unavailable.');
+            const result = await runTool(context, { tool: 'dnspy', role: 'version', executable: join(system, 'System32/WindowsPowerShell/v1.0/powershell.exe'), arguments: ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', fileURLToPath(new URL('../../runtime/native/file-version.ps1', import.meta.url)), '-Executable', launch.executable], nativeDeadline: true, timeoutMs: 15000, maxOutputBytes: 65536 });
+            if (!/^6\.6\.0(?:\.0)?$/.test(result.stdout.trim()))
+                fail('configuration', 'Select dnSpyEx 6.6.0.');
+            return { version: '6.6.0', selfContainedDebuggerRuntime: '10.0.9', privateTargetRuntime: launch.environment.DOTNET_ROOT ? '10.0.13' : 'External Core targets require --dotnet-host or a self-contained input', pinnedContractsVerified: true, ownedDebugger: true, interactiveDesktopRequired: true };
+        } });
+}
+function nativeFilename(name) { return name.length > 0 && name.length <= 255 && !/[<>:\x22/\\|?*\x00-\x1f]/.test(name) && !/[ .]$/.test(name) && name !== '.' && name !== '..'; }
+export function dnspyToken(value) { const token = text(value, 16); if (!/^0x06[0-9a-fA-F]{6}$/.test(token) || Number(token) === 0x06000000)
+    fail('invalid', 'Use a MethodDef metadata token such as 0x06000002, from the selected managed module.'); return Number(token); }
+export function dnspyPlan(o, mode) {
+    const Token = dnspyToken(o.method), Offset = number(o.ilOffset ?? 0, 0x1000000), base = { Schema: 1, Mode: mode, Token, Offset };
+    if (mode === 'edit-constant') {
+        const integer = (value) => { if (value === undefined || !/^[-+]?\d+$/.test(String(value)))
+            fail('invalid', 'Explicit signed Int32 expected/replacement constants are required.'); const n = Number(value); if (!Number.isSafeInteger(n) || n < -2147483648 || n > 2147483647)
+            fail('invalid', 'Constant is outside Int32.'); return n; };
+        return { ...base, ExpectedConstant: integer(o.expectInt32), ReplacementConstant: integer(o.setInt32) };
+    }
+    const Runtime = text(o.runtime ?? 'framework', 16);
+    if (!['framework', 'core'].includes(Runtime))
+        fail('invalid', 'Select framework or core runtime.');
+    if (Runtime === 'core' && !o.module)
+        fail('invalid', 'Core apphost debugging requires its paired --module managed DLL.');
+    if (Runtime !== 'core' && (o.module || o.dotnetHost))
+        fail('invalid', '--module and --dotnet-host apply to a Core apphost input.');
+    const Parameters = o.parameters === undefined ? [] : text(o.parameters, 256).split(',').map(v => { if (!/^\d+$/.test(v.trim()))
+        fail('invalid', 'Parameter indices must be decimal integers.'); return number(v.trim(), 65535); });
+    if (Parameters.length > 32 || new Set(Parameters).size !== Parameters.length)
+        fail('invalid', 'Select up to 32 distinct zero-based parameter indices.');
+    const Arguments = (Array.isArray(o.arg) ? o.arg : o.arg === undefined ? [] : [o.arg]).map(v => { if (typeof v !== 'string' || Buffer.byteLength(v) > 4096)
+        fail('invalid', 'Program argument must be a bounded literal string.'); return v; });
+    if (Arguments.length > 64 || Arguments.some(v => /[\0\r\n]/.test(v)))
+        fail('invalid', 'Program arguments exceed their literal bounds.');
+    return { ...base, Runtime, Parameters, Arguments };
+}
+export function dnspyCommands(workspace) {
+    const installer = (c) => dnspyInstaller(c), definition = defineTool({ id: 'dnspy', description: 'Observe managed breakpoint parameters and edit an explicit IL constant in a new assembly copy', vendorDirect: true, components: [{ id: 'dnspy', version: '6.6.0', artifacts: [], dependencies: ['dotnet'] }, { id: 'dotnet', version: '10.0.13', artifacts: [] }], installOptions: [{ flags: '--vendor-direct', description: 'Explicitly acquire the pinned unmodified upstream bundle' }, { flags: '--archive <path>', description: 'Matching local dnSpyEx archive' }, { flags: '--archive-sha256 <sha256>', description: 'Expected local tool archive SHA256' }, { flags: '--executable <file>', description: 'External root dnSpy.exe; complete adjacent runtime is fingerprinted' }, { flags: '--offline', description: 'Use only local archives and verified cache' }, { flags: '--dotnet-archive <path>', description: 'Matching private .NET 10.0.13 Windows x64 runtime archive for offline setup' }], lifecycle: { download: (o, c) => installer(c).download(Boolean(o.offline), Boolean(o.vendorDirect)), 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() } });
+    const common = [{ flags: '--target <id>', description: 'Reuse an immutable captured managed input' }, { flags: '--method <token>', description: 'Required MethodDef token (0x060000NN), scoped to the selected module' }, { flags: '--il-offset <bytes>', description: 'Exact decimal IL instruction offset', defaultValue: 0 }], execute = (mode) => command((mode === 'debug' ? 'inspect' : 'edit-constant') + ' [input]', mode === 'debug' ? 'Launch an owned managed debugger and read selected primitive parameters at an IL breakpoint' : 'Replace one expected Int32 IL constant and save a new ordinary assembly', async ({ args, options: o }, c) => {
+        supported();
+        if (Boolean(args.input) === Boolean(o.target))
+            fail('invalid', 'Supply exactly one input path or --target.');
+        if (mode === 'edit-constant' && !o.output)
+            fail('invalid', 'A new --output assembly path is required.');
+        const limit = number(o.limit ?? 32, 64, 1), offset = number(o.offset ?? 0, 64), plan = dnspyPlan(o, mode), w = workspace(c), target = args.input ? await w.importTarget(resolve(c.cwd, text(args.input, 4096))) : w.target(id(o.target)), source = await w.artifacts.verify(target.input), name = basename(args.input ? text(args.input, 4096) : target.name ?? 'input.exe');
+        if ((!nativeFilename(name) || !/\.(?:exe|dll)$/i.test(name)))
+            fail('invalid', 'Input must have an ordinary .exe or .dll filename.');
+        const directory = join(c.appArguments.AppDataDirectory, 'runtime/dnspy/queries', randomUUID()), inputDirectory = join(directory, 'input'), extension = join(directory, 'extension');
+        await mkdir(inputDirectory, { recursive: true, mode: 0o700 });
+        await mkdir(extension, { mode: 0o700 });
+        const input = join(inputDirectory, name);
+        await copyFile(source, input, constants.COPYFILE_EXCL);
+        const companions = {};
+        let companionBytes = 0;
+        const paths = [...(o.module ? [o.module] : []), ...(Array.isArray(o.companion) ? o.companion : o.companion === undefined ? [] : [o.companion])];
+        if (paths.length > 32)
+            fail('limit', 'At most 32 explicitly selected input companions are supported.');
+        for (const value of paths) {
+            const path = resolve(c.cwd, text(value, 4096)), name = basename(path);
+            if (!nativeFilename(name) || Object.keys(companions).some(x => x.toLowerCase() === name.toLowerCase()) || basename(input).toLowerCase() === name.toLowerCase())
+                fail('invalid', 'Companion filenames must be ordinary and unique.');
+            const artifact = await w.artifacts.capture(path, 'input');
+            if ((companionBytes += artifact.size) > 64 * 1024 ** 2)
+                fail('limit', 'Captured companions exceed 64 MiB.');
+            await copyFile(await w.artifacts.verify(artifact), join(inputDirectory, name), constants.COPYFILE_EXCL);
+            companions[name] = artifact.sha256;
+        }
+        if (mode === 'debug' && !/\.exe$/i.test(input))
+            fail('invalid', 'Debugging launches an EXE. For Core, supply the apphost EXE and its --module DLL plus declared sidecars.');
+        const nonce = randomUUID(), receipt = join(directory, 'result.json'), patched = join(directory, 'patched' + (name.toLowerCase().endsWith('.dll') ? '.dll' : '.exe')), identity = await bridgeIdentity();
+        await copyFile(join(native, 'Insight.DnSpy.x.dll'), join(extension, 'Insight.DnSpy.x.dll'), constants.COPYFILE_EXCL);
+        const planFile = join(directory, 'plan.json');
+        await atomicWrite(planFile, { ...plan, Nonce: nonce, Input: input, Module: o.module ? join(inputDirectory, basename(text(o.module, 4096))) : input, Result: receipt, ...(mode === 'edit-constant' ? { Output: patched } : {}) });
+        return installer(c).use(async (selected) => {
+            const environment = { ...selected.environment };
+            if (o.dotnetHost) {
+                const host = resolve(c.cwd, text(o.dotnetHost, 4096));
+                if (basename(host).toLowerCase() !== 'dotnet.exe')
+                    fail('invalid', 'Select an explicit compatible dotnet.exe for the external Core target runtime.');
+                await fileSha256(host);
+                environment.DOTNET_ROOT = dirname(host);
+                environment.DOTNET_MULTILEVEL_LOOKUP = '0';
+            }
+            if (mode === 'debug' && o.runtime === 'core' && !environment.DOTNET_ROOT)
+                fail('configuration', 'External Core apphost debugging requires --dotnet-host pointing to a compatible runtime. Managed setup provides a private runtime.');
+            let result;
+            try {
+                result = await runTool(c, { tool: 'dnspy', role: mode, installation: selected.id, executable: selected.executable, arguments: ['--multiple', '--no-activate', '--settings-file', join(directory, 'settings.xml'), '--extension-directory', extension, '--insight-plan:' + planFile], environment, nativeDeadline: true, timeoutMs: 60000, target: target.id, metadata: { inputSha256: target.binarySha256, companions, method: plan.Token, ilOffset: plan.Offset, extensionSha256: identity.sha256, mode } });
+            }
+            catch (error) {
+                let observation;
+                try {
+                    if ((await stat(receipt)).size <= 1024 ** 2) {
+                        const value = await readJson(receipt);
+                        if (value?.schema === 1 && value.nonce === nonce && value.data?.state === 'failed')
+                            observation = value.data;
+                    }
+                }
+                catch { }
+                if (error instanceof CliError && observation)
+                    throw new CliError(String(observation.error ?? error.message), { code: error.code, cause: error, result: { ...error.result, nativeDiagnostics: error.result?.diagnostics, diagnostics: directory, observation } });
+                throw error;
+            }
+            if ((await stat(receipt)).size > 1024 ** 2)
+                fail('limit', 'Typed debugger receipt exceeds 1 MiB.');
+            const value = await readJson(receipt);
+            if (!value || value.schema !== 1 || value.nonce !== nonce || value.data?.state !== 'completed' || value.data.mode !== mode || value.data.token !== plan.Token)
+                throw new CliError('Managed debugger/editor did not complete the selected typed operation.', { code: 'tool.partial', result: { process: result.process, diagnostics: directory, observation: value?.data } });
+            if (await fileSha256(input) !== target.binarySha256)
+                fail('binding', 'Captured input bytes changed during the operation.');
+            const base = { state: 'completed', complete: true, target: target.id, inputSha256: target.binarySha256, companions, process: result.process, elapsedMs: result.elapsedMs, diagnostics: directory, observation: value.data, coverage: mode === 'debug' ? 'One owned execution and selected IL breakpoint; primitive parameters only, no expression evaluation. Adjacent input dependencies must be selected explicitly.' : 'Static edit of one expected Int32 IL constant in a new copy. Output behavior, signatures and strong names need independent verification; original bytes are preserved.' };
+            if (mode === 'edit-constant') {
+                if (!o.output)
+                    fail('invalid', 'A new --output assembly path is required.');
+                const output = resolve(c.cwd, text(o.output, 4096));
+                await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+                await copyFile(patched, output, constants.COPYFILE_EXCL);
+                return { ...base, output, outputSha256: await fileSha256(output) };
+            }
+            const frames = Array.isArray(value.data.frames) ? value.data.frames : [];
+            if (o.output) {
+                const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify({ ...base, observation: { ...value.data, frames } }, 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) };
+            }
+            return { ...base, observation: { ...value.data, frames: frames.slice(offset, offset + limit) }, totalFrames: frames.length, stackBoundReached: frames.length === 64, limit, offset, truncated: offset + limit < frames.length };
+        });
+    }, { permission: Permission.Update, options: [...common, ...(mode === 'debug' ? [{ flags: '--runtime <kind>', description: 'framework or core apphost', defaultValue: 'framework' }, { flags: '--module <file>', description: 'Core apphost paired managed DLL containing the breakpoint token' }, { flags: '--companion <files...>', description: 'Explicit DLL/runtimeconfig/deps companions copied beside the owned input' }, { flags: '--dotnet-host <file>', description: 'Compatible external dotnet.exe for Core targets with an external debugger selection' }, { flags: '--parameters <indices>', description: 'Comma-separated zero-based primitive parameter indices (at most 32)' }, { flags: '--arg <literal...>', description: 'Literal input program arguments' }, { flags: '--limit <count>', description: 'Maximum stack frames to return (1–64)', defaultValue: 32 }, { flags: '--offset <count>', description: 'Skip stack frames', defaultValue: 0 }, { flags: '--output <file>', description: 'Save full bounded JSON to a new ordinary file' }] : [{ flags: '--expect-int32 <value>', description: 'Required current Int32 constant' }, { flags: '--set-int32 <value>', description: 'Required replacement Int32 constant' }, { flags: '--output <file>', description: 'Required new assembly path; never overwrites' }])] });
+    return [command('dnspy', definition.description, [...lifecycleCommands(definition), execute('debug'), execute('edit-constant')])];
+}

package/dist/src/dotnet-diagnostics.d.ts

@@ -0,0 +1,13 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import type { Workspace } from './workspace.js';
+declare const packages: {
+    readonly 'dotnet-dump': "ae70c9f37548e1e006467893e21ae41a005fefaf2270e29642b415df053324a7";
+    readonly 'dotnet-stack': "cd35f399fe023f1793b528590a4d723a1f2f1d9b25696386d926a697bd24c0ca";
+    readonly 'dotnet-trace': "ef17f25724a55f9685bfaf8506a778ea87c2b62783eca2ca73263226128b0d4e";
+};
+export type DiagnosticTool = keyof typeof packages;
+export declare function diagnosticsInstaller(tool: DiagnosticTool, c: CommandContext): ToolInstaller;
+export declare function sosReadCommand(value: unknown): string;
+export declare function diagnosticsCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];
+export {};