@eyeauras/insight-cli 0.2.0 → 0.2.1

package/dist/src/lldb.js

@@ -0,0 +1,99 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { dirname, join, resolve } from 'node:path';
+import { release } from 'node:os';
+import { mkdir, writeFile, open, copyFile, chmod } 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 { 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 rootOf = (executable) => dirname(dirname(executable));
+function supported() { if (process.platform !== 'darwin' || process.arch !== 'arm64' || Number(release().split('.')[0]) < 23)
+    fail('unsupported', 'This LLDB facade requires macOS 14+ ARM64. Imported PE/ELF files cannot be executed on this host.'); }
+export function lldbInstaller(c) { return new ToolInstaller(c, { id: 'lldb', primary: 'lldb', components: () => { supported(); return { lldb: catalogArtifact('3df8fefb9f15fd80d250dc78517a659f4ec67159f73fdc5df71b7100709213d5') }; }, launch: roots => ({ executable: join(roots.lldb, 'bin/lldb'), arguments: [], environment: {} }), externalInputs: async (executable) => { supported(); const root = rootOf(executable); return { debugserver: await fileSha256(join(root, 'bin/debugserver')), liblldb: await fileSha256(join(root, 'lib/liblldb.23.1.dylib')) }; }, probe: async (launch, context) => { supported(); const r = await runTool(context, { tool: 'lldb', role: 'version', executable: launch.executable, arguments: ['--no-lldbinit', '--version'], maxOutputBytes: 65536, timeoutMs: 10000, nativeDeadline: true }); if (!/lldb version 23\.1\.3\b/.test(r.stdout))
+        fail('configuration', 'Select LLDB 23.1.3 with adjacent bin/debugserver and lib/liblldb.23.1.dylib.'); await fileSha256(join(rootOf(launch.executable), 'bin/debugserver')); await fileSha256(join(rootOf(launch.executable), 'lib/liblldb.23.1.dylib')); return { version: '23.1.3', ownedLaunchOnly: true, detachOnError: false, kernelDeadline: true }; } }); }
+const quote = (value) => { if (/[\x00-\x1f\x7f`]/.test(value))
+    fail('invalid', 'Debugger arguments must not contain control characters or LLDB expression delimiters (backticks).'); return '"' + value.replaceAll('\\', '\\\\').replaceAll('"', '\\"') + '"'; };
+export function lldbPlan(o) {
+    const breakpoint = text(o.breakpoint, 512), address = /^0x[0-9a-fA-F]{1,16}$/.test(breakpoint);
+    if (breakpoint.startsWith('0x') && !address)
+        fail('invalid', 'A breakpoint address must be a hexadecimal unsigned 64-bit file address.');
+    const hit = number(o.hit ?? 1, 10000, 1), registers = text(o.registers ?? 'pc,sp,x0', 512).split(',');
+    if (registers.length > 64 || registers.some(r => !(/^[a-zA-Z][a-zA-Z0-9_]{0,31}$/).test(r)))
+        fail('invalid', 'Registers must be comma-separated native register names.');
+    const args = o.arg === undefined ? [] : Array.isArray(o.arg) ? o.arg : [o.arg];
+    if (args.length > 64)
+        fail('limit', 'At most 64 literal program arguments are supported.');
+    const commands = ['settings set auto-confirm true', 'settings set target.detach-on-error false', 'settings set target.disable-stdio true', 'breakpoint set --one-shot true --ignore-count ' + (hit - 1) + ' ' + (address ? '--address ' : '--name ') + quote(breakpoint), 'process launch --shell-expand-args false -- ' + args.map(v => quote(text(v, 4096))).join(' '), ...(o.variables || o.symbols ? ['frame variable --depth 2'] : []), 'register read ' + registers.join(' '), 'thread backtrace --count 32'];
+    if (o.memoryAddress !== undefined) {
+        const at = text(o.memoryAddress, 64);
+        if (!/^0x[0-9a-fA-F]{1,16}$/.test(at) && !/^\$[a-zA-Z][a-zA-Z0-9_]{0,31}$/.test(at))
+            fail('invalid', 'Memory address must be a hexadecimal runtime address or $register.');
+        commands.push('memory read --format x --size 1 --count ' + number(o.memoryBytes ?? 64, 4096, 1) + ' ' + at);
+    }
+    else if (o.memoryBytes !== undefined)
+        fail('invalid', '--memory-bytes requires --memory-address.');
+    if (o.stepOut)
+        commands.push('thread step-out', 'register read ' + registers.join(' '));
+    commands.push('process kill', 'quit');
+    return commands;
+}
+export function lldbSnapshot(stdout) {
+    const inferior = Number(stdout.match(/Process (\d+) launched:/)?.[1]);
+    if (!inferior || !(/stop reason = (?:one-shot )?breakpoint/).test(stdout) || !new RegExp('Process ' + inferior + ' exited with status').test(stdout))
+        fail('partial', 'LLDB did not complete the requested breakpoint snapshot and inferior cleanup; inspect native diagnostics.');
+    return { inferiorPid: inferior, lines: stdout.trimEnd().split(/\r?\n/) };
+}
+export function lldbCommands(workspace) {
+    const definition = defineTool({ id: 'lldb', description: 'Observe an owned native launch at a breakpoint, inspect state and terminate it', components: [{ id: 'lldb', version: '23.1.3', artifacts: [] }], lifecycle: { download: (o, c) => lldbInstaller(c).download(Boolean(o.offline)), install: (o, c) => lldbInstaller(c).install(o), uninstall: (o, c) => lldbInstaller(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => lldbInstaller(c).doctor(), status: (_o, c) => lldbInstaller(c).status() } });
+    return [command('lldb', definition.description, [...lifecycleCommands(definition), command('inspect [input]', 'Launch an owned copy, capture a breakpoint snapshot, optionally step out, then kill the inferior', async ({ args, options: o }, c) => {
+                supported();
+                if (Boolean(args.input) === Boolean(o.target))
+                    fail('invalid', 'Supply exactly one input path or --target.');
+                const commands = lldbPlan(o), limit = number(o.limit ?? 200, 1000, 1), offset = number(o.offset ?? 0, 1000000), timeoutMs = number(o.timeoutSeconds ?? 30, 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), header = Buffer.alloc(32), handle = await open(input, 'r');
+                try {
+                    await handle.read(header, 0, 32, 0);
+                }
+                finally {
+                    await handle.close();
+                }
+                // A captured Mach-O is executable only in its own platform. Never execute an imported PE/ELF.
+                const magic = header.subarray(0, 4).toString('hex');
+                if (!['cffaedfe', 'feedfacf'].includes(magic) || (magic === 'cffaedfe' ? header.readUInt32LE(4) : header.readUInt32BE(4)) !== 0x0100000c)
+                    fail('unsupported', 'LLDB owned launch requires a thin ARM64 Mach-O input on this host.');
+                const directory = join(c.appArguments.AppDataDirectory, 'runtime/lldb/subjects', randomUUID()), subject = join(directory, 'subject');
+                await mkdir(directory, { recursive: true, mode: 0o700 });
+                await copyFile(input, subject, constants.COPYFILE_EXCL);
+                await chmod(subject, 0o700);
+                if (await fileSha256(subject) !== target.binarySha256)
+                    fail('binding', 'Owned launch bytes differ from the immutable target.');
+                const symbols = o.symbols ? await w.artifacts.capture(resolve(c.cwd, text(o.symbols, 4096)), 'input') : undefined;
+                if (symbols)
+                    commands.unshift('target symbols add ' + quote(await w.artifacts.verify(symbols)));
+                return lldbInstaller(c).use(async (selected) => {
+                    const result = await runTool(c, { tool: 'lldb', role: 'inspect', installation: selected.id, executable: selected.executable, arguments: ['--no-lldbinit', '--batch', ...commands.flatMap(command => ['-o', command]), '--', subject], environment: { ...selected.environment, LLDB_DEBUGSERVER_PATH: join(rootOf(selected.executable), 'bin/debugserver') }, cwd: directory, target: target.id, timeoutMs, nativeDeadline: true }), snapshot = lldbSnapshot(result.stdout);
+                    // Observation only: never signal a PID parsed from native text. LLDB owns inferior termination.
+                    try {
+                        process.kill(snapshot.inferiorPid, 0);
+                        fail('partial', 'LLDB reported cleanup but its inferior PID remains present; inspect diagnostics.');
+                    }
+                    catch (error) {
+                        if (error.code !== 'ESRCH')
+                            throw error;
+                    }
+                    const base = { state: 'completed', target: target.id, inputSha256: target.binarySha256, ...(symbols ? { symbolsSha256: symbols.sha256 } : {}), process: result.process, inferiorPid: snapshot.inferiorPid, inferiorTerminated: true, elapsedMs: result.elapsedMs, diagnostics: result.diagnostics, stderr: result.stderr, coverage: 'One owned launch and selected breakpoint observation; executing the input can have application side effects. Static addresses require image correspondence; runtime addresses vary with ASLR.' };
+                    if (o.output) {
+                        const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify({ ...base, lines: snapshot.lines }, 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), totalLines: snapshot.lines.length };
+                    }
+                    return { ...base, lines: snapshot.lines.slice(offset, offset + limit), offset, limit, totalLines: snapshot.lines.length, truncated: offset + limit < snapshot.lines.length };
+                });
+            }, { permission: Permission.Update, options: [{ flags: '--target <id>', description: 'Reuse an immutable captured Mach-O target' }, { flags: '--breakpoint <function-or-address>', description: 'Required function name or 0x file address' }, { flags: '--hit <number>', description: 'Observe the selected hit (1–10000)', defaultValue: 1 }, { flags: '--arg <literal...>', description: 'Literal program arguments; no shell expansion' }, { flags: '--symbols <file>', description: 'Capture and load a matching DWARF companion file (inside .dSYM/Contents/Resources/DWARF)' }, { flags: '--variables', description: 'Also request local variables; requires usable debug information' }, { flags: '--registers <names>', description: 'Comma-separated registers', defaultValue: 'pc,sp,x0' }, { flags: '--memory-address <address>', description: 'Optional runtime 0x address or $register' }, { flags: '--memory-bytes <bytes>', description: 'Bytes to read (1–4096)', defaultValue: undefined }, { flags: '--step-out', description: 'Return from the stopped function and capture registers again' }, { flags: '--output <file>', description: 'Save the full bounded snapshot to a new JSON file' }, { flags: '--limit <count>', description: 'Maximum native output lines (1–1000)', defaultValue: 200 }, { flags: '--offset <count>', description: 'Skip native output lines', defaultValue: 0 }, { flags: '--timeout-seconds <seconds>', description: 'Owned launch deadline (1–600), retained after owner loss', defaultValue: 30 }] })])];
+}

package/dist/src/llvm.d.ts

@@ -0,0 +1,6 @@
+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 llvmInstaller(c: CommandContext): ToolInstaller;
+export declare function llvmAddress(value: unknown): bigint;
+export declare function llvmCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/llvm.js

@@ -0,0 +1,133 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { join, resolve, dirname } from 'node:path';
+import { release } from 'node:os';
+import { open, mkdir, writeFile } from 'node:fs/promises';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import { defineTool, lifecycleCommands } from './tool-runtime/definition.js';
+import { catalogArtifact } from './tool-runtime/catalog.js';
+import { fileSha256 } from './tool-runtime/archives.js';
+import { runTool } from './tool-runtime/run.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+const utilities = ['llvm-readobj', 'llvm-objdump', 'llvm-nm', 'llvm-pdbutil'];
+const executable = (primary, name) => name === 'llvm-readobj' ? primary : join(dirname(primary), name + (process.platform === 'win32' ? '.exe' : ''));
+export function llvmInstaller(c) {
+    return new ToolInstaller(c, { id: 'llvm', primary: 'llvm', components: () => {
+            if (process.platform !== 'darwin' || process.arch !== 'arm64' || Number(release().split('.')[0]) < 23)
+                fail('unsupported', 'Managed LLVM utilities require macOS 14+ ARM64; select an external compatible llvm-readobj with its three sibling utilities.');
+            return { llvm: catalogArtifact('2599cb40282085a61a3d8b50003d75d556010d764c05a9bf30e45a7c7b5b7861') };
+        }, launch: roots => ({ executable: join(roots.llvm, 'bin/llvm-readobj'), arguments: [], environment: {} }),
+        externalInputs: async (primary) => { const hashes = {}; for (const name of utilities)
+            try {
+                hashes[name] = await fileSha256(executable(primary, name), c.signal);
+            }
+            catch {
+                c.signal.throwIfAborted();
+                fail('configuration', 'External LLVM requires all four pinned sibling utilities in the executable directory.', { missing: name });
+            } return hashes; },
+        probe: async (launch, context) => {
+            const versions = {};
+            for (const name of utilities) {
+                const r = await runTool(context, { tool: 'llvm', role: 'version', executable: executable(launch.executable, name), arguments: ['--version'], maxOutputBytes: 65536, timeoutMs: 30000 });
+                if (!/\bLLVM version 23\.1\.3\b/.test(r.stdout))
+                    fail('configuration', 'The selected LLVM family must provide version 23.1.3.', { utility: name });
+                versions[name] = '23.1.3';
+            }
+            return { versions, managedMinimumMacOS: '14.0' };
+        } });
+}
+export function llvmAddress(value) { const v = text(value, 18); if (!/^0x[0-9a-fA-F]{1,16}$/.test(v))
+    fail('invalid', 'Address must be an explicit 0x-prefixed unsigned virtual address.'); return BigInt(v); }
+async function format(path) {
+    const file = await open(path, 'r'), magic = Buffer.alloc(4);
+    try {
+        await file.read(magic, 0, 4, 0);
+    }
+    finally {
+        await file.close();
+    }
+    if (magic.subarray(0, 2).toString() === 'MZ')
+        return 'pe';
+    if (magic.toString('hex') === '7f454c46')
+        return 'elf';
+    if (['feedface', 'cefaedfe', 'feedfacf', 'cffaedfe', 'cafebabe', 'bebafeca', 'cafebabf', 'bfbafeca'].includes(magic.toString('hex')))
+        return 'macho';
+    return 'other';
+}
+export function llvmCommands(workspace) {
+    const definition = defineTool({ id: 'llvm', description: 'Inspect native binary structure, symbols, instructions and PDBs', components: [{ id: 'llvm', version: '23.1.3', artifacts: [] }], lifecycle: { download: (o, c) => llvmInstaller(c).download(Boolean(o.offline)), install: (o, c) => llvmInstaller(c).install(o), uninstall: (o, c) => llvmInstaller(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => llvmInstaller(c).doctor(), status: (_o, c) => llvmInstaller(c).status() } });
+    const common = [{ flags: '--target <id>', description: 'Reuse an immutable research target' }, { flags: '--output <file>', description: 'Write full bounded native text to a new ordinary file' },
+        { flags: '--limit <count>', description: 'Maximum native text lines returned (1–400)', defaultValue: 100 }, { flags: '--offset <count>', description: 'Skip native text lines', defaultValue: 0 },
+        { flags: '--filter <text>', description: 'Select matching native lines; surrounding context may be outside the selection' }, { flags: '--timeout-seconds <seconds>', description: 'Deadline per native process (1–600)', defaultValue: 120 }];
+    const operation = (name, options = []) => command(name + ' [input]', 'Native ' + name + ' through pinned LLVM utilities', async ({ args, options: o }, c) => {
+        if (Boolean(args.input) === Boolean(o.target))
+            fail('invalid', 'Supply exactly one input path or --target.');
+        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);
+        const kind = await format(input), timeoutMs = number(o.timeoutSeconds, 600, 1) * 1000, limit = number(o.limit, 400, 1), offset = number(o.offset, 10000000, 0);
+        const calls = [];
+        if (name === 'headers' || name === 'sections')
+            calls.push({ utility: 'llvm-readobj', arguments: [name === 'headers' ? '--file-header' : '--sections', input] });
+        if (name === 'section-data') {
+            const section = text(o.section, 256);
+            if (!/^[a-zA-Z0-9_.+,$-]+$/.test(section))
+                fail('invalid', 'Section name must be an exact native section name.');
+            calls.push({ utility: 'llvm-readobj', arguments: ['--hex-dump=' + section, input] });
+        }
+        if (name === 'imports') {
+            if (kind === 'pe')
+                calls.push({ utility: 'llvm-readobj', arguments: ['--coff-imports', input] });
+            else if (kind === 'elf')
+                calls.push({ utility: 'llvm-readobj', arguments: ['--needed-libs', input] }, { utility: 'llvm-nm', arguments: ['--dynamic', '--undefined-only', '--format=posix', input] });
+            else if (kind === 'macho')
+                calls.push({ utility: 'llvm-objdump', arguments: ['--macho', '--dylibs-used', input] }, { utility: 'llvm-nm', arguments: ['--undefined-only', '--format=posix', input] });
+            else
+                fail('unsupported', 'Import linkage view requires a PE, ELF or Mach-O image.');
+        }
+        if (name === 'exports') {
+            if (kind === 'pe')
+                calls.push({ utility: 'llvm-readobj', arguments: ['--coff-exports', input] });
+            else if (kind === 'elf' || kind === 'macho')
+                calls.push({ utility: 'llvm-nm', arguments: [...(kind === 'elf' ? ['--dynamic'] : []), '--defined-only', '--extern-only', '--format=posix', input] });
+            else
+                fail('unsupported', 'Export linkage view requires a PE, ELF or Mach-O image.');
+        }
+        if (name === 'symbols')
+            calls.push({ utility: 'llvm-nm', arguments: ['--format=posix', ...(o.undefinedOnly ? ['--undefined-only'] : []), input] });
+        if (name === 'disassemble') {
+            const start = llvmAddress(o.address), length = number(o.bytes, 4096, 1), end = start + BigInt(length);
+            if (end > 0xffffffffffffffffn)
+                fail('invalid', 'Disassembly interval overflows a 64-bit address.');
+            calls.push({ utility: 'llvm-objdump', arguments: ['--disassemble', '--demangle', '--start-address=0x' + start.toString(16), '--stop-address=0x' + end.toString(16), input] });
+        }
+        if (name === 'pdb') {
+            const view = text(o.view, 16);
+            if (!['summary', 'modules', 'globals', 'publics', 'symbols', 'types'].includes(view))
+                fail('invalid', 'PDB view must be summary, modules, globals, publics, symbols or types.');
+            if (o.typeIndex && view !== 'types' || o.symbol && view !== 'globals')
+                fail('invalid', 'type-index is for types; symbol is for globals.');
+            if (o.typeIndex && llvmAddress(o.typeIndex) > 0xffffffffn)
+                fail('invalid', 'PDB type index exceeds 32 bits.');
+            const flags = view === 'types' ? (o.typeIndex ? ['--types', '--type-index=0x' + llvmAddress(o.typeIndex).toString(16)] : ['--type-stats']) : ['--' + view];
+            if (o.module !== undefined)
+                flags.push('--modi=' + number(o.module, 1000000, 0));
+            if (o.symbol)
+                flags.push('--global-name=' + text(o.symbol, 1024));
+            calls.push({ utility: 'llvm-pdbutil', arguments: ['dump', ...flags, input] });
+        }
+        return llvmInstaller(c).use(async (selected) => {
+            const results = [];
+            for (const call of calls)
+                results.push({ ...call, result: await runTool(c, { tool: 'llvm', role: name, installation: selected.id, executable: executable(selected.executable, call.utility), arguments: call.arguments, environment: selected.environment, target: target.id, timeoutMs }) });
+            const content = results.map(r => r.utility + '\n' + r.result.stdout).join('\n'), base = { state: 'completed', target: target.id, inputSha256: target.binarySha256, fileFormat: kind, format: 'native-text', processes: results.map(r => ({ utility: r.utility, process: r.result.process, diagnostics: r.result.diagnostics, elapsedMs: r.result.elapsedMs })) };
+            if (o.output) {
+                const output = resolve(c.cwd, text(o.output, 4096));
+                await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+                await writeFile(output, content, { flag: 'wx', mode: 0o600 });
+                return { ...base, output, bytes: Buffer.byteLength(content) };
+            }
+            const all = content.trimEnd().split(/\r?\n/), lines = o.filter ? all.filter(l => l.includes(text(o.filter, 1024))) : all;
+            return { ...base, content: lines.slice(offset, offset + limit).join('\n'), totalLines: lines.length, offset, limit, truncated: offset + limit < lines.length };
+        });
+    }, { permission: Permission.Update, options: [...common, ...options] });
+    return [command('llvm', definition.description, [...lifecycleCommands(definition), ...['headers', 'sections', 'imports', 'exports'].map(n => operation(n)), operation('section-data', [{ flags: '--section <name>', description: 'Exact section name; bounded hexadecimal contents, not virtual memory', required: true }]), operation('symbols', [{ flags: '--undefined-only', description: 'Only undefined symbols' }]), operation('disassemble', [{ flags: '--address <virtual-address>', description: 'Start virtual address, not a file offset', required: true }, { flags: '--bytes <count>', description: 'Byte interval (1–4096)', defaultValue: 128 }]), operation('pdb', [{ flags: '--view <name>', description: 'summary, modules, globals, publics, symbols or types', defaultValue: 'summary' }, { flags: '--module <index>', description: 'Focus a compiland by its numeric module index' }, { flags: '--symbol <name>', description: 'Exact global symbol name' }, { flags: '--type-index <0x-index>', description: 'Inspect one hexadecimal type record instead of type statistics' }])])];
+}

package/dist/src/managed-heap.d.ts

@@ -0,0 +1,4 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import type { ToolInstaller } from './tool-runtime/installer.js';
+import type { Workspace } from './workspace.js';
+export declare function managedHeapCommand(workspace: (c: CommandContext) => Workspace, installer: (c: CommandContext) => ToolInstaller): CommandDefinition;

package/dist/src/managed-heap.js

@@ -0,0 +1,73 @@
+import { command, Permission, CliError } from '@eyeauras/cli-factory';
+import { join, resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { dotnetLaunch } from './tool-runtime/dotnet.js';
+import { runTool } from './tool-runtime/run.js';
+import { atomicWrite } from './tool-runtime/store.js';
+import { fileSha256 } from './tool-runtime/archives.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+const helper = fileURLToPath(new URL('../../runtime/managed/insight-heap/Insight.Heap.dll', import.meta.url));
+export function managedHeapCommand(workspace, installer) {
+    return command('query [input]', 'Read bounded managed heap objects, fields and stacks from one immutable dump', async ({ args, options: o }, c) => {
+        if (process.platform !== 'darwin' || process.arch !== 'arm64')
+            fail('unsupported', 'The structured ClrMD facade is verified for matching macOS ARM64 CoreCLR dumps. Other native DAC profiles remain unverified.');
+        if (Boolean(args.input) === Boolean(o.target))
+            fail('invalid', 'Supply one dump input or --target.');
+        const view = text(o.view ?? 'overview', 16);
+        if (!['overview', 'objects', 'object', 'stacks'].includes(view))
+            fail('invalid', 'Use overview, objects, object or stacks.');
+        const address = o.address === undefined ? undefined : text(o.address, 18);
+        if ((view === 'object') !== Boolean(address) || address && !/^0x[0-9a-fA-F]{1,16}$/.test(address))
+            fail('invalid', 'Only object view requires a dump-scoped hexadecimal --address.');
+        if (o.thread !== undefined && view !== 'stacks')
+            fail('invalid', '--thread selects an OS thread in stacks view.');
+        const limit = number(o.limit ?? 50, 500, 1), offset = number(o.offset ?? 0, 1000000), maxObjects = number(o.maxObjects ?? 1000000, 1000000, 1), runtime = number(o.runtimeIndex ?? 0, 15);
+        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);
+        if (target.input.size > 4 * 1024 ** 3)
+            fail('limit', 'Dump input exceeds four GiB.');
+        return installer(c).use(async (selected) => {
+            let launch;
+            if (selected.roots.dotnet)
+                launch = dotnetLaunch(selected.roots.dotnet, helper);
+            else {
+                if (!o.dotnetHost)
+                    fail('configuration', 'An external diagnostics selection requires an explicit compatible --dotnet-host and --dac-file.');
+                const host = resolve(c.cwd, text(o.dotnetHost, 4096));
+                if (!['dotnet', 'dotnet.exe'].includes(basename(host).toLowerCase()))
+                    fail('invalid', 'Select a compatible .NET 10 host.');
+                await fileSha256(host);
+                launch = { executable: host, arguments: [helper], environment: { DOTNET_ROOT: dirname(host), DOTNET_MULTILEVEL_LOOKUP: '0', DOTNET_CLI_TELEMETRY_OPTOUT: '1' } };
+            }
+            const dac = o.dacFile ? resolve(c.cwd, text(o.dacFile, 4096)) : selected.roots.dotnet ? join(selected.roots.dotnet, 'shared/Microsoft.NETCore.App/10.0.13/libmscordaccore.dylib') : undefined;
+            if (!dac)
+                fail('configuration', 'Select an explicit matching native --dac-file.');
+            if (basename(dac) !== 'libmscordaccore.dylib')
+                fail('invalid', 'Select the matching CoreCLR macOS DAC library, not a target assembly.');
+            const dacSha256 = await fileSha256(dac), directory = join(c.appArguments.AppDataDirectory, 'runtime/managed-heap/queries', randomUUID()), plan = join(directory, 'plan.json');
+            await atomicWrite(plan, { schema: 1, input, dac, view, address, type: o.type === undefined ? undefined : text(o.type, 4096), thread: o.thread === undefined ? undefined : number(o.thread, 4294967295, 1), runtime, limit, offset, maxObjects });
+            const result = await runTool(c, { tool: 'dotnet-dump', role: 'structured-query', installation: selected.id, executable: launch.executable, arguments: [...launch.arguments, plan], environment: { ...launch.environment, DOTNET_EnableDiagnostics: '0' }, nativeDeadline: true, timeoutMs: 60000, maxOutputBytes: 8 * 1024 ** 2, target: target.id, metadata: { view, helperSha256: await fileSha256(helper), dacSha256 } });
+            let observation;
+            try {
+                observation = JSON.parse(result.stdout);
+            }
+            catch {
+                throw new CliError('Dump query did not return complete bounded JSON.', { code: 'tool.partial', result: { process: result.process, diagnostics: result.diagnostics } });
+            }
+            if (!['completed', 'partial'].includes(observation?.state) || typeof observation.complete !== 'boolean')
+                fail('partial', 'Dump query receipt was not verified.', { process: result.process, diagnostics: result.diagnostics });
+            if (await fileSha256(input) !== target.binarySha256 || await fileSha256(dac) !== dacSha256)
+                fail('binding', 'Dump or explicit DAC changed during the query.');
+            const value = { ...observation, target: target.id, inputSha256: target.binarySha256, dacSha256, dacSelection: o.dacFile ? 'explicit-local' : 'managed-10.0.13', process: result.process, elapsedMs: result.elapsedMs, diagnostics: result.diagnostics };
+            if (o.output) {
+                const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify(value, null, 2) + '\n';
+                await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+                await writeFile(output, content, { flag: 'wx', mode: 0o600 });
+                return { state: value.state, complete: value.complete, reason: value.reason, target: target.id, output, bytes: Buffer.byteLength(content), process: result.process, diagnostics: result.diagnostics };
+            }
+            return value;
+        });
+    }, { permission: Permission.Update, options: [{ flags: '--target <id>', description: 'Reuse captured immutable dump bytes' }, { flags: '--view <kind>', description: 'overview, objects, object or stacks', defaultValue: 'overview' }, { flags: '--type <name>', description: 'Exact heap type fullname; object view verifies the expected type' }, { flags: '--address <hex>', description: 'Object address from this exact dump' }, { flags: '--thread <id>', description: 'Dump-scoped OS thread ID for stacks' }, { flags: '--runtime-index <index>', description: 'CLR runtime index from overview', defaultValue: 0 }, { flags: '--dac-file <file>', description: 'Explicit matching trusted native CoreCLR DAC; managed default is 10.0.13' }, { flags: '--dotnet-host <file>', description: 'Compatible .NET 10 host for external diagnostics selection' }, { flags: '--max-objects <count>', description: 'Scan at most 1–1000000 objects; reaching this bound is partial', defaultValue: 1000000 }, { flags: '--limit <count>', description: 'Return 1–500 objects, fields or threads', defaultValue: 50 }, { flags: '--offset <count>', description: 'Skip matching rows', defaultValue: 0 }, { flags: '--output <file>', description: 'Save this bounded query to a new ordinary JSON file' }] });
+}

package/dist/src/managed-metadata.d.ts

@@ -0,0 +1,11 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import type { ToolInstaller, SelectedTool } from './tool-runtime/installer.js';
+import type { Workspace } from './workspace.js';
+export declare function metadataToken(value: unknown): number;
+export declare function runManagedMetadata(c: CommandContext, selected: SelectedTool, plan: Record<string, unknown>, externalHost?: unknown): Promise<{
+    data: any;
+    process: string;
+    elapsedMs: number;
+    diagnostics: string;
+}>;
+export declare function managedMetadataCommands(workspace: (c: CommandContext) => Workspace, installer: (c: CommandContext) => ToolInstaller): CommandDefinition[];

package/dist/src/managed-metadata.js

@@ -0,0 +1,66 @@
+import { command, Permission, CliError } from '@eyeauras/cli-factory';
+import { join, resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { dotnetLaunch } from './tool-runtime/dotnet.js';
+import { runTool } from './tool-runtime/run.js';
+import { atomicWrite } from './tool-runtime/store.js';
+import { fileSha256 } from './tool-runtime/archives.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+const helper = fileURLToPath(new URL('../../runtime/managed/insight-managed/Insight.Managed.dll', import.meta.url));
+export function metadataToken(value) { const token = text(value, 16); if (!/^0x06[0-9a-fA-F]{6}$/.test(token) || Number(token) === 0x06000000)
+    fail('invalid', 'Select a nonzero MethodDef token (0x060000NN) from this exact managed target.'); return Number(token); }
+async function input(c, w, path, target) { if (Boolean(path) === Boolean(target))
+    fail('invalid', 'Supply one managed input path or --target.'); const value = path ? await w.importTarget(resolve(c.cwd, text(path, 4096))) : w.target(id(target)); if (value.input.size > 64 * 1024 ** 2)
+    fail('limit', 'Static managed input exceeds 64 MiB.'); return { path: await w.artifacts.verify(value.input), target: value.id, sha256: value.binarySha256 }; }
+export async function runManagedMetadata(c, selected, plan, externalHost) {
+    let launch;
+    if (selected.roots.dotnet)
+        launch = dotnetLaunch(selected.roots.dotnet, helper);
+    else {
+        if (!externalHost)
+            fail('configuration', 'Static metadata requires the managed ILSpy private runtime, or an explicit --dotnet-host for an external ILSpy selection.');
+        const host = resolve(c.cwd, text(externalHost, 4096));
+        if (!['dotnet', 'dotnet.exe'].includes(basename(host).toLowerCase()))
+            fail('invalid', 'Select a compatible dotnet host, not a shell or compiler.');
+        await fileSha256(host);
+        launch = { executable: host, arguments: [helper], environment: { DOTNET_ROOT: dirname(host), DOTNET_MULTILEVEL_LOOKUP: '0', DOTNET_CLI_TELEMETRY_OPTOUT: '1' } };
+    }
+    const directory = join(c.appArguments.AppDataDirectory, 'runtime/managed-metadata/queries', randomUUID()), file = join(directory, 'plan.json');
+    await atomicWrite(file, { schema: 1, ...plan });
+    const result = await runTool(c, { tool: 'ilspy', role: plan.mode === 'compare' ? 'assembly-comparison' : 'metadata-query', installation: selected.id, executable: launch.executable, arguments: [...launch.arguments, file], environment: { ...launch.environment, DOTNET_EnableDiagnostics: '0' }, nativeDeadline: true, timeoutMs: 60000, maxOutputBytes: 8 * 1024 ** 2, metadata: { helperSha256: await fileSha256(helper), operation: plan.mode, view: plan.view }, target: typeof plan.target === 'string' ? plan.target : undefined });
+    let data;
+    try {
+        data = JSON.parse(result.stdout);
+    }
+    catch {
+        throw new CliError('Managed helper did not return complete bounded JSON.', { code: 'tool.partial', result: { process: result.process, diagnostics: result.diagnostics } });
+    }
+    if (data?.state !== 'completed' || data.complete !== true)
+        fail('partial', 'Static managed metadata was not fully verified.', { process: result.process, diagnostics: result.diagnostics, observation: data });
+    return { data, process: result.process, elapsedMs: result.elapsedMs, diagnostics: result.diagnostics };
+}
+export function managedMetadataCommands(workspace, installer) {
+    const common = [{ flags: '--type <name>', description: 'Exact dnlib type fullname from a prior query' }, { flags: '--filter <text>', description: 'Literal case-sensitive full signature/name substring' }, { flags: '--name-filter <text>', description: 'Case-insensitive managed method name only; methods, imports, method or compare' }, { flags: '--limit <count>', description: 'Rows/instructions to return (1–1000)', defaultValue: 50 }, { flags: '--offset <count>', description: 'Skip matching rows/instructions', defaultValue: 0 }, { flags: '--dotnet-host <file>', description: 'Compatible .NET 10 host for an external ILSpy selection' }, { flags: '--output <file>', description: 'Save this bounded result/page to a new ordinary JSON file' }];
+    const run = (mode) => command(mode === 'query' ? 'query [input]' : 'compare <left> <right>', mode === 'query' ? 'Read structured managed metadata, P/Invoke and normalized IL without executing the target' : 'Compare managed signatures, normalized IL and P/Invoke across two immutable assemblies', async ({ args, options: o }, c) => {
+        const limit = number(o.limit ?? 50, 1000, 1), offset = number(o.offset ?? 0, 1000000), view = mode === 'query' ? text(o.view ?? 'overview', 16) : undefined;
+        if (view && !['overview', 'types', 'methods', 'method', 'imports'].includes(view))
+            fail('invalid', 'Use overview, types, methods, method or imports.');
+        if (o.nameFilter !== undefined && mode === 'query' && !['methods', 'imports', 'method'].includes(view))
+            fail('invalid', '--name-filter selects method names; use methods, imports or method view.');
+        const token = o.method === undefined ? undefined : metadataToken(o.method);
+        if (view === 'method' && token === undefined)
+            fail('invalid', 'Method view requires --method from this exact module.');
+        const w = workspace(c), a = await input(c, w, mode === 'query' ? args.input : args.left, mode === 'query' ? o.target : undefined), b = mode === 'compare' ? await input(c, w, args.right, undefined) : undefined;
+        return installer(c).use(async (selected) => { const result = await runManagedMetadata(c, selected, { mode, input: a.path, other: b?.path, view, type: o.type === undefined ? undefined : text(o.type, 4096), filter: o.filter === undefined ? undefined : text(o.filter, 4096), nameFilter: o.nameFilter === undefined ? undefined : text(o.nameFilter, 4096), token, limit, offset, target: a.target }, o.dotnetHost); if (await fileSha256(a.path) !== a.sha256 || b && await fileSha256(b.path) !== b.sha256)
+            fail('binding', 'Immutable metadata input changed during the query.'); const { data: observation, ...execution } = result; const output = { ...observation, state: 'completed', complete: true, ...(b ? { left: { target: a.target, inputSha256: a.sha256 }, right: { target: b.target, inputSha256: b.sha256 } } : { target: a.target, inputSha256: a.sha256 }), ...execution }; if (o.output) {
+            const file = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify(output, null, 2) + '\n';
+            await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+            await writeFile(file, content, { flag: 'wx', mode: 0o600 });
+            return { state: 'completed', complete: true, target: a.target, output: file, bytes: Buffer.byteLength(content), process: result.process, diagnostics: result.diagnostics };
+        } return output; });
+    }, { permission: Permission.Update, options: [...common, ...(mode === 'query' ? [{ flags: '--target <id>', description: 'Reuse an immutable managed target' }, { flags: '--view <kind>', description: 'overview, types, methods, method or imports', defaultValue: 'overview' }, { flags: '--method <token>', description: 'MethodDef token (0x060000NN), required for method view' }] : [])] });
+    return [run('query'), run('compare')];
+}

package/dist/src/mitmproxy.d.ts

@@ -0,0 +1,55 @@
+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 mitmproxyInstaller(c: CommandContext): ToolInstaller;
+export declare function mitmproxyStatus(c: CommandContext): Promise<{
+    captures: {
+        endpoint?: string | undefined;
+        archive?: string | undefined;
+        caCertificate?: string | undefined;
+        process: string;
+        state: string;
+        ready: boolean;
+    }[];
+    retainedStages: string[];
+    processes: import("./tool-runtime/supervisor.js").ProcessRecord[];
+    tool: string;
+    state: string;
+    mode: string;
+    installation: string | undefined;
+    executable: string | undefined;
+    components: Record<string, string>;
+    lastProbe: Record<string, unknown> | undefined;
+    recommended: string;
+}>;
+interface Message {
+    bodyAvailable: boolean;
+    bodySha256: string | null;
+    bodyBase64: string | null;
+    bodyTruncated: boolean | null;
+    bodyBytes: number | null;
+    headers: [string, string][];
+    headersTruncated: boolean;
+}
+export interface HttpObservation {
+    kind: 'http';
+    id: string;
+    request: Message & {
+        method: string;
+        url: string;
+        host: string;
+        path: string;
+    };
+    response: (Message & {
+        statusCode: number;
+    }) | null;
+    error: string | null;
+    pending: boolean;
+}
+export declare function compareHttp(left: HttpObservation[], right: HttpObservation[]): {
+    items: Record<string, unknown>[];
+    unchanged: number;
+    scope: string;
+};
+export declare function mitmproxyCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];
+export {};