@eyeauras/insight-cli 0.2.0 → 0.2.2

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 {};

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 {};