@eyeauras/insight-cli 0.2.0 → 0.2.1

package/dist/src/mitmproxy.js

@@ -0,0 +1,172 @@
+import { command, Permission, CliError } from '@eyeauras/cli-factory';
+import { dirname, join, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { release } from 'node:os';
+import { mkdir, readFile, stat, lstat, copyFile, cp, writeFile } from 'node:fs/promises';
+import { readFileSync, 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 { atomicWrite, treeFingerprint, readJson } 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 native = fileURLToPath(new URL('../../runtime/native/mitmproxy/', import.meta.url)), runtimeSha = '4bed6d0d2a0bcdc4afeb7408881c9b30e5f81b7c232c2ff9c987babcbed90125';
+let notices;
+function supported() { if (process.platform !== 'darwin' || process.arch !== 'arm64' || Number(release().split('.')[0]) < 24)
+    fail('unsupported', 'The pinned mitmproxy facade requires macOS 15+ ARM64. It uses only an owned loopback HTTP proxy and private profile CA; system proxy/trust settings are not installed.'); }
+function bundle(executable) { if (basename(executable) !== 'mitmdump' || basename(dirname(executable)) !== 'MacOS' || basename(resolve(dirname(executable), '../..')) !== 'mitmproxy.app')
+    fail('configuration', 'Select the pinned mitmproxy.app/Contents/MacOS/mitmdump and its complete adjacent runtime.'); return resolve(dirname(executable), '../..'); }
+export function mitmproxyInstaller(c) { return new ToolInstaller(c, { id: 'mitmproxy', primary: 'mitmproxy', preparationId: 'external-owned-copy-v1', prepareExternal: async (executable, stage) => { const source = bundle(executable), before = await treeFingerprint(source), owned = join(stage, 'execution/mitmproxy.app'); await cp(source, owned, { recursive: true, dereference: false, verbatimSymlinks: true, errorOnExist: true, force: false }); if (await treeFingerprint(source) !== before || await treeFingerprint(owned) !== before)
+        fail('binding', 'External mitmproxy runtime changed while making its owned execution copy.'); return { executable: join(owned, 'Contents/MacOS/mitmdump'), arguments: [], environment: {} }; }, components: () => { supported(); return { mitmproxy: catalogArtifact(runtimeSha) }; }, noticeFiles: notices ??= JSON.parse(readFileSync(join(native, 'notices.json'), 'utf8')), launch: roots => ({ executable: join(roots.mitmproxy, 'mitmproxy.app/Contents/MacOS/mitmdump'), arguments: [], environment: {} }), externalInputs: async (executable) => { supported(); return { runtimeFamily: await treeFingerprint(bundle(executable)) }; }, probe: async (launch, context) => { supported(); const result = await runTool(context, { tool: 'mitmproxy', role: 'version', executable: launch.executable, arguments: ['--version'], timeoutMs: 15000, maxOutputBytes: 65536, nativeDeadline: true }); if (!/^Mitmproxy: 12\.2\.3(?: binary)?\s*$/m.test(result.stdout))
+        fail('configuration', 'Select mitmproxy 12.2.3.'); return { version: '12.2.3', privatePython: '3.14.4', minimumSystem: 'macOS 15+ ARM64', typedHttpOnly: true, loopbackProxy: true, systemTrustInstalled: false, systemProxyInstalled: false }; } }); }
+export async function mitmproxyStatus(c) {
+    const status = await mitmproxyInstaller(c).status(), captures = [];
+    for (const process of status.processes) {
+        if (process.role !== 'record' || process.state !== 'running')
+            continue;
+        const metadata = process.metadata ?? {}, directory = metadata.query;
+        if (typeof directory !== 'string' || !/^[-a-f0-9]{36}$/.test(basename(directory)) || directory !== join(c.appArguments.AppDataDirectory, 'runtime/mitmproxy/queries', basename(directory)))
+            continue;
+        let ready = false;
+        try {
+            const receipt = await readJson(join(directory, 'ready.json'));
+            ready = receipt?.schema === 1 && receipt.nonce === metadata.nonce && receipt.host === '127.0.0.1' && receipt.port === metadata.listenPort;
+        }
+        catch { }
+        captures.push({ process: process.id, state: ready ? 'ready' : 'starting', ready, ...(ready ? { endpoint: 'http://127.0.0.1:' + metadata.listenPort, archive: join(directory, 'capture.mitm'), caCertificate: join(directory, 'conf/mitmproxy-ca-cert.pem') } : {}) });
+    }
+    return { ...status, captures };
+}
+export function compareHttp(left, right) {
+    const index = (rows) => { const counts = new Map(); return new Map(rows.map(row => { const request = row.request.method + ' ' + row.request.url, n = counts.get(request) ?? 0; counts.set(request, n + 1); return [request + ' #' + n, row]; })); }, a = index(left), b = index(right), items = [];
+    let unchanged = 0;
+    for (const key of [...new Set([...a.keys(), ...b.keys()])].sort()) {
+        const l = a.get(key), r = b.get(key);
+        if (!l || !r) {
+            items.push({ key, state: l ? 'left_only' : 'right_only', left: l?.id, right: r?.id });
+            continue;
+        }
+        const changed = [], unknown = [];
+        if (l.request.bodyAvailable && r.request.bodyAvailable) {
+            if (l.request.bodySha256 !== r.request.bodySha256)
+                changed.push('request.bodySha256');
+        }
+        else
+            unknown.push('request.body');
+        if (l.response && r.response) {
+            if (l.response.statusCode !== r.response.statusCode)
+                changed.push('response.statusCode');
+            if (l.response.bodyAvailable && r.response.bodyAvailable) {
+                if (l.response.bodySha256 !== r.response.bodySha256)
+                    changed.push('response.bodySha256');
+            }
+            else
+                unknown.push('response.body');
+        }
+        else
+            unknown.push('response');
+        if (l.error !== r.error)
+            changed.push('error');
+        if (l.pending || r.pending)
+            unknown.push('pending');
+        if (changed.length || unknown.length)
+            items.push({ key, state: changed.length ? 'changed' : 'unknown', left: l.id, right: r.id, changed, unknown });
+        else
+            unchanged++;
+    }
+    return { items, unchanged, scope: 'Literal method + URL, then occurrence order; selected body SHA256/status/error fields only. This alignment is a comparison aid, not proof of causal request correspondence. Volatile headers/timestamps are excluded; unavailable bodies remain unknown. Unmatched rows in a partial input do not prove absence.' };
+}
+async function bridge(c, selected, w, mode, o, input) {
+    const directory = join(c.appArguments.AppDataDirectory, 'runtime/mitmproxy/queries', randomUUID()), conf = join(directory, 'conf'), script = join(directory, 'bridge.py'), plan = join(directory, 'plan.json'), nonce = randomUUID(), bodyBytes = number(o.bodyBytes ?? 1024, 65536), maxFlows = number(o.maxFlows ?? 1000, 1000, 1), durationSeconds = mode === 'record' ? number(o.durationSeconds ?? 10, 300, 1) : undefined, port = mode === 'record' ? number(o.listenPort, 65535, 1) : undefined;
+    await mkdir(conf, { recursive: true, mode: 0o700 });
+    await copyFile(join(native, 'bridge.py'), script, constants.COPYFILE_EXCL);
+    const scriptSha = await fileSha256(script), capture = join(directory, 'capture.mitm'), caCertificate = join(conf, 'mitmproxy-ca-cert.pem');
+    const arguments_ = ['--set', 'confdir=' + conf, '--set', 'flow_detail=0', '--set', 'termlog_verbosity=error', '--set', 'body_size_limit=1m', '--set', 'websocket=false', '--set', 'rawtcp=false', '-s', script, ...(mode === 'record' ? ['--mode', 'regular', '--listen-host', '127.0.0.1', '--listen-port', String(port)] : ['--set', 'server=false'])];
+    let upstreamCaSha256;
+    if (o.upstreamCa) {
+        const path = resolve(c.cwd, text(o.upstreamCa, 4096)), artifact = await w.artifacts.capture(path, 'input');
+        if (artifact.size > 1024 ** 2)
+            fail('limit', 'Public upstream CA bundle exceeds 1 MiB.');
+        const body = await readFile(await w.artifacts.verify(artifact), 'utf8');
+        if (!body.includes('-----BEGIN CERTIFICATE-----') || body.includes('PRIVATE KEY'))
+            fail('invalid', 'Select a public PEM certificate bundle, without private keys.');
+        upstreamCaSha256 = artifact.sha256;
+        const captured = join(directory, 'upstream-ca.pem');
+        await copyFile(await w.artifacts.verify(artifact), captured, constants.COPYFILE_EXCL);
+        arguments_.push('--set', 'ssl_verify_upstream_trusted_ca=' + captured);
+    }
+    await atomicWrite(plan, { schema: 1, nonce, mode, bodyBytes, maxFlows, ...(mode === 'record' ? { durationSeconds, port } : { input: input.path }) });
+    let processResult;
+    try {
+        processResult = await runTool(c, { tool: 'mitmproxy', role: mode, installation: selected.id, executable: selected.executable, arguments: arguments_, environment: { HOME: join(directory, 'home'), INSIGHT_MITMPROXY_PLAN: plan }, nativeDeadline: true, timeoutMs: mode === 'record' ? durationSeconds * 1000 + 15000 : 60000, maxOutputBytes: 65536, target: input?.target, metadata: { mode, nonce, query: directory, bodyBytes, maxFlows, upstreamCaSha256, bridgeSha256: scriptSha, ...(mode === 'record' ? { listenHost: '127.0.0.1', listenPort: port, caCertificate, archive: capture, ready: join(directory, 'ready.json') } : { inputSha256: input.sha256 }) } });
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw new CliError(error.message, { code: error.code, cause: error, result: { ...error.result, diagnostics: directory, retainedArchive: mode === 'record' ? capture : input.path, coverage: 'Interrupted or failed operation. Retained observations may be incomplete; no automatic recollection or traffic replay.', next: mode === 'record' ? ['insight-cli', 'mitmproxy', 'inspect', capture, '--json'] : undefined } });
+        throw error;
+    }
+    if ((await stat(join(directory, 'result.json'))).size > 512 * 1024)
+        fail('limit', 'Native observation receipt exceeds 512 KiB.');
+    const receipt = await readJson(join(directory, 'result.json'));
+    if (receipt?.schema !== 1 || receipt.nonce !== nonce || receipt.mode !== mode || typeof receipt.complete !== 'boolean' || !Number.isSafeInteger(receipt.httpFlows) || receipt.httpFlows < 0 || receipt.httpFlows > maxFlows)
+        fail('partial', 'Native HTTP observation receipt could not be verified.', { diagnostics: directory, process: processResult.process });
+    const report = join(directory, 'flows.jsonl');
+    if ((await stat(report)).size > 8 * 1024 ** 2)
+        fail('limit', 'Native HTTP report exceeds 8 MiB.');
+    const lines = (await readFile(report, 'utf8')).trim().split('\n').map(line => JSON.parse(line)), header = lines.shift();
+    if (header?.kind !== 'header' || header.schema !== 1 || header.nonce !== nonce || header.mode !== mode || lines.length !== receipt.httpFlows || lines.some(row => row.kind !== 'http' || typeof row.id !== 'string' || typeof row.request?.method !== 'string' || typeof row.request?.url !== 'string'))
+        fail('partial', 'Native HTTP report does not match its completed receipt.', { diagnostics: directory });
+    if (input && await fileSha256(input.path) !== input.sha256)
+        fail('binding', 'Captured native flow input changed during inspection.');
+    return { state: receipt.complete ? 'completed' : 'partial', complete: receipt.complete, reason: receipt.reason, skippedFlows: receipt.skippedFlows, pendingRequests: receipt.pendingRequests, error: receipt.error, tlsFailures: receipt.tlsFailures, upstreamCaSha256, process: processResult.process, elapsedMs: processResult.elapsedMs, diagnostics: directory, bodyBytes, maxFlows, items: lines, coverage: mode === 'record' ? 'One explicit loopback proxy observation window; HTTP request/response only. No system proxy/trust change, WebSocket payload or global absence claim. Native bodies are limited to 1 MiB each; archive to 64 MiB, JSON to 8 MiB.' : 'HTTP observations from one immutable native archive/HAR, bounded by max-flows/output. Partial/unsupported records and unavailable bodies remain unknown. An empty archive can reflect TLS/interception failure; retain its original window summary before inferring anything about traffic.', archive: mode === 'record' ? capture : undefined, ...(mode === 'record' ? { caCertificate, listenHost: '127.0.0.1', listenPort: port } : { target: input.target, inputSha256: input.sha256 }) };
+}
+async function captureInput(c, w, path, targetId) { if (Boolean(path) === Boolean(targetId))
+    fail('invalid', 'Supply one native flow archive/HAR path or --target.'); if (path) {
+    const source = resolve(c.cwd, text(path, 4096)), info = await lstat(source);
+    if (info.isFile() && info.size === 0) {
+        const directory = join(c.appArguments.AppDataDirectory, 'runtime/mitmproxy/empty-inputs', randomUUID());
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const copy = join(directory, 'empty.mitm');
+        await copyFile(source, copy, constants.COPYFILE_EXCL);
+        if ((await stat(copy)).size !== 0 || (await stat(source)).size !== 0)
+            fail('binding', 'Empty archive changed while being captured.');
+        return { path: copy, sha256: await fileSha256(copy), target: undefined };
+    }
+} const target = path ? await w.importTarget(resolve(c.cwd, text(path, 4096))) : w.target(id(targetId)); if (target.input.size > 64 * 1024 ** 2)
+    fail('limit', 'Native flow input exceeds 64 MiB.'); return { path: await w.artifacts.verify(target.input), target: target.id, sha256: target.binarySha256 }; }
+async function ordinary(c, path, value) { const output = resolve(c.cwd, text(path, 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 { output, bytes: Buffer.byteLength(content) }; }
+export function mitmproxyCommands(workspace) {
+    const installer = (c) => mitmproxyInstaller(c), definition = defineTool({ id: 'mitmproxy', description: 'Record, inspect and compare bounded HTTP observations through an owned loopback proxy', components: [{ id: 'mitmproxy', version: '12.2.3', artifacts: [] }], lifecycle: { download: (o, c) => installer(c).download(Boolean(o.offline)), install: (o, c) => installer(c).install(o), status: (_o, c) => mitmproxyStatus(c), doctor: (_o, c) => installer(c).doctor(), uninstall: (o, c) => installer(c).uninstall(Boolean(o.purgeCache)) } }), bounds = [{ flags: '--body-bytes <bytes>', description: 'Returned prefix per body (0–65536); full bounded body SHA is retained', defaultValue: 1024 }, { flags: '--max-flows <count>', description: 'Maximum inspected/recorded flows (1–1000)', defaultValue: 1000 }], paging = [{ flags: '--limit <count>', description: 'Return up to 1000 rows', defaultValue: 50 }, { flags: '--offset <count>', description: 'Skip matching rows', defaultValue: 0 }];
+    return [command('mitmproxy', definition.description, [...lifecycleCommands(definition), command('record', 'Record an explicit HTTP proxy window; clients must independently opt into its loopback endpoint', async ({ options: o }, c) => { supported(); if (o.listenPort === undefined)
+                fail('invalid', 'Select an explicit --listen-port for your own client. No system proxy is changed.'); if (o.output)
+                try {
+                    await stat(resolve(c.cwd, text(o.output, 4096)));
+                    fail('invalid', 'Capture output already exists.');
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                } const w = workspace(c); return installer(c).use(async (selected) => { const result = await bridge(c, selected, w, 'record', o); if (result.reason === 'interrupted')
+                throw new CliError('HTTP observation window was interrupted; inspect the retained archive explicitly.', { code: 'tool.interrupted', result: { state: 'partial', complete: false, reason: result.reason, process: result.process, diagnostics: result.diagnostics, retainedArchive: result.archive, totalFlows: result.items.length } }); const archiveSize = (await stat(result.archive)).size, target = archiveSize ? await w.importTarget(result.archive) : undefined; let output; if (o.output) {
+                output = resolve(c.cwd, text(o.output, 4096));
+                await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+                await copyFile(result.archive, output, constants.COPYFILE_EXCL);
+            } const { items, ...base } = result; return { ...base, target: target?.id, inputSha256: target?.binarySha256 ?? await fileSha256(result.archive), archiveEmpty: archiveSize === 0, totalFlows: items.length, ...(output ? { output } : {}) }; }); }, { permission: Permission.Update, options: [...bounds, { flags: '--listen-port <port>', description: 'Required owned loopback HTTP proxy port' }, { flags: '--duration-seconds <seconds>', description: 'Observation window (1–300 seconds)', defaultValue: 10 }, { flags: '--upstream-ca <file>', description: 'Explicit public PEM CA for an owned HTTPS origin; never installed globally' }, { flags: '--output <file>', description: 'Copy completed native flow archive to a new ordinary file' }] }),
+            command('inspect [input]', 'Read retained native flow/HAR evidence without reconnecting or replaying traffic', async ({ args, options: o }, c) => { supported(); const view = text(o.view ?? 'overview', 16); if (!['overview', 'flows', 'flow'].includes(view) || (view === 'flow') !== Boolean(o.flowId))
+                fail('invalid', 'Use overview, flows or flow; only flow requires --flow-id.'); const limit = number(o.limit ?? 50, 1000, 1), offset = number(o.offset ?? 0, 1000000), w = workspace(c), input = await captureInput(c, w, args.input, o.target); return installer(c).use(async (selected) => { const result = await bridge(c, selected, w, 'inspect', o, input), { items: all, ...base } = result, items = all.filter(row => (!o.method || row.request.method === text(o.method, 32)) && (!o.urlContains || row.request.url.includes(text(o.urlContains, 4096))) && (!o.flowId || row.id === text(o.flowId, 128))); if (view === 'flow' && !items.length)
+                fail(result.complete ? 'notFound' : 'partial', 'Flow identity was not found in the inspected bounded input prefix.'); if (o.output)
+                return { ...base, ...await ordinary(c, o.output, { ...base, items, total: items.length }) }; if (view === 'overview') {
+                const methods = {}, statuses = {};
+                for (const row of items) {
+                    methods[row.request.method] = (methods[row.request.method] ?? 0) + 1;
+                    const status = String(row.response?.statusCode ?? 'unavailable');
+                    statuses[status] = (statuses[status] ?? 0) + 1;
+                }
+                return { ...base, totalFlows: all.length, matchingFlows: items.length, methods, statuses, errors: items.filter(r => r.error).length, bodyPrefixesTruncated: items.filter(r => r.request.bodyTruncated || r.response?.bodyTruncated).length };
+            } return { ...base, items: view === 'flow' ? items : items.slice(offset, offset + limit), total: items.length, limit, offset, truncated: view !== 'flow' && offset + limit < items.length }; }); }, { permission: Permission.Update, options: [...bounds, ...paging, { flags: '--target <id>', description: 'Reuse an immutable native flow/HAR target' }, { flags: '--view <kind>', description: 'overview, flows or flow', defaultValue: 'overview' }, { flags: '--flow-id <id>', description: 'Native flow UUID from this exact archive' }, { flags: '--method <name>', description: 'Literal HTTP method filter' }, { flags: '--url-contains <text>', description: 'Literal URL substring filter, applied before pagination' }, { flags: '--output <file>', description: 'Save the full bounded selected HTTP rows to a new JSON file' }] }),
+            command('compare <left> <right>', 'Compare two retained HTTP observations without sending or replaying requests', async ({ args, options: o }, c) => { supported(); const limit = number(o.limit ?? 50, 1000, 1), offset = number(o.offset ?? 0, 1000000), w = workspace(c), left = await captureInput(c, w, args.left, undefined), right = await captureInput(c, w, args.right, undefined); return installer(c).use(async (selected) => { const a = await bridge(c, selected, w, 'inspect', o, left), b = await bridge(c, selected, w, 'inspect', o, right), compared = compareHttp(a.items, b.items), unknown = compared.items.some(row => row.state === 'unknown' || Array.isArray(row.unknown) && row.unknown.length), complete = a.complete && b.complete && !unknown, base = { state: complete ? 'completed' : 'partial', complete, left: { target: left.target, inputSha256: left.sha256, process: a.process, diagnostics: a.diagnostics, complete: a.complete }, right: { target: right.target, inputSha256: right.sha256, process: b.process, diagnostics: b.diagnostics, complete: b.complete }, unchanged: compared.unchanged, total: compared.items.length, scope: compared.scope }; if (o.output)
+                return { ...base, ...await ordinary(c, o.output, { ...base, items: compared.items }) }; return { ...base, items: compared.items.slice(offset, offset + limit), limit, offset, truncated: offset + limit < compared.items.length }; }); }, { permission: Permission.Update, options: [...bounds, ...paging, { flags: '--output <file>', description: 'Save full bounded comparison to a new ordinary JSON file' }] })])];
+}

package/dist/src/native-inputs.d.ts

@@ -1,3 +1,4 @@
+import { type RunContext } from './tool-runtime/run.js';
 export interface NativeInputs {
     java: string;
     ghidraHome: string;
@@ -22,7 +23,7 @@ export interface NativeRuntimeFile {
 /** Installed native code/data, excluding documentation and isolated generated caches. */
 export declare function nativeRuntimeFiles(ghidraHome: string, java: string): Promise<NativeRuntimeFile[]>;
 export declare function nativeRuntimeFingerprint(ghidraVersion: string, files: NativeRuntimeFile[]): Promise<string>;
-export declare function nativeInputs(values: Record<string, unknown>, directory?: string): Promise<NativeInputs>;
+export declare function nativeInputs(values: Record<string, unknown>, directory?: string, c?: RunContext): Promise<NativeInputs>;
 /** Compile packaged helper sources against the selected installation, never an author checkout. */
-export declare function nativeHelpers(directory: string, inputs: NativeInputs): Promise<string>;
+export declare function nativeHelpers(directory: string, inputs: NativeInputs, c?: RunContext): Promise<string>;
 export declare const nativeExtensionArguments: (inputs: NativeInputs) => string[];

package/dist/src/native-inputs.js

@@ -1,3 +1,4 @@
+import { runTool } from './tool-runtime/run.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { readFile, writeFile, readdir, mkdir, open, rename, rm, realpath, stat } from 'node:fs/promises';
 import { basename, delimiter, dirname, isAbsolute, join, relative, sep } from 'node:path';
@@ -78,7 +79,7 @@ export async function nativeRuntimeFingerprint(ghidraVersion, files) {
         hashes.push({ name: file.name, sha256: await sha(file.path) });
     return createHash('sha256').update(stable({ schema: 2, ghidraVersion, hashes })).digest('hex');
 }
-export async function nativeInputs(values, directory) {
+export async function nativeInputs(values, directory, c) {
     if (directory)
         values = runtimeValues(dirname(directory), values);
     if (!values.java || !values.ghidraHome)
@@ -96,7 +97,7 @@ export async function nativeInputs(values, directory) {
         fail('configuration', 'This build requires the verified Ghidra 12.1.2 runtime.');
     let jdk;
     try {
-        jdk = await run(java, ['--version'], { timeout: 10000, maxBuffer: 16384 });
+        jdk = c ? await runTool(c, { tool: 'ghidra', role: 'java-version', executable: java, arguments: ['--version'], timeoutMs: 10000, maxOutputBytes: 16384 }) : await run(java, ['--version'], { timeout: 10000, maxBuffer: 16384 });
     }
     catch {
         fail('configuration', 'Configured Java executable could not be verified.');
@@ -130,7 +131,7 @@ export async function nativeInputs(values, directory) {
     return { java, ghidraHome, mcpJar, jars, classpath: jars.join(delimiter), ghidraVersion, fingerprint, debuggerWheels, extensionRoots: modules.map(m => m.root), serverClasspath: baseJars.join(delimiter) };
 }
 /** Compile packaged helper sources against the selected installation, never an author checkout. */
-export async function nativeHelpers(directory, inputs) {
+export async function nativeHelpers(directory, inputs, c) {
     const sources = fileURLToPath(new URL('../../references/native/', import.meta.url));
     const names = [...(await readdir(sources)).filter(name => name.endsWith('.java')), '../InsightRepositoryProbe.java'].sort();
     if (!names.length)
@@ -153,7 +154,11 @@ export async function nativeHelpers(directory, inputs) {
     const temporary = join(parent, 'compiling-' + randomUUID());
     await mkdir(temporary, { mode: 0o700 });
     try {
-        await run(join(dirname(inputs.java), 'javac' + (process.platform === 'win32' ? '.exe' : '')), ['-proc:none', '-cp', inputs.classpath, '-d', temporary, ...names.map(name => join(sources, name))], { timeout: 60000, maxBuffer: 262144 });
+        const executable = join(dirname(inputs.java), 'javac' + (process.platform === 'win32' ? '.exe' : '')), args = ['-proc:none', '-cp', inputs.classpath, '-d', temporary, ...names.map(name => join(sources, name))];
+        if (c)
+            await runTool(c, { tool: 'ghidra', role: 'compile-helpers', installation: inputs.fingerprint, executable, arguments: args, timeoutMs: 60000, maxOutputBytes: 262144 });
+        else
+            await run(executable, args, { timeout: 60000, maxBuffer: 262144 });
         const complete = await open(join(temporary, 'complete'), 'wx', 0o600);
         try {
             await complete.writeFile(key);

package/dist/src/package-version.d.ts

@@ -0,0 +1 @@
+export declare const packageVersion: string;

package/dist/src/package-version.js

@@ -0,0 +1,3 @@
+import { readFileSync } from 'node:fs';
+// The installed manifest is also covered by Factory's package build identity.
+export const packageVersion = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;

package/dist/src/procmon-config.d.ts

@@ -0,0 +1,2 @@
+/** Must be verified with the pinned ProcMon before an adapter admits active capture. */
+export declare function procmonConfiguration(pid: number, path?: string): Buffer<ArrayBuffer>;

package/dist/src/procmon-config.js

@@ -0,0 +1,15 @@
+// First-party serializer of the public PMC format research, not a Python runtime dependency.
+// https://github.com/eronnen/procmon-parser/blob/96080961e51745ddc6e83490c24e540553c44c71/docs/PMC%20Format.md
+import { fail } from './model.js';
+const u32 = (value) => { const bytes = Buffer.alloc(4); bytes.writeUInt32LE(value); return bytes; };
+const record = (name, data) => { const key = Buffer.from(name + '\0', 'utf16le'); return Buffer.concat([u32(16 + key.length + data.length), u32(16), u32(16 + key.length), u32(data.length), key, data]); };
+const rule = (column, value, numeric = 0) => { const bytes = Buffer.from(value + '\0', 'utf16le'); return Buffer.concat([u32(column), u32(0), Buffer.from([1]), u32(bytes.length), bytes, u32(numeric), u32(0)]); };
+/** Must be verified with the pinned ProcMon before an adapter admits active capture. */
+export function procmonConfiguration(pid, path) {
+    if (!Number.isSafeInteger(pid) || pid < 1 || pid > 0xffffffff)
+        fail('invalid', 'A positive owned Windows PID is required.');
+    if (path !== undefined && (!path || /[\x00-\x1f]/.test(path) || path.length > 4096))
+        fail('invalid', 'ProcMon path must be a bounded literal native path without control characters.');
+    const rules = [rule(40054, String(pid), pid), ...(path ? [rule(40071, path)] : [])];
+    return Buffer.concat([record('FilterRules', Buffer.concat([Buffer.from([1]), u32(rules.length), ...rules])), record('DestructiveFilter', u32(1)), record('Profiling', u32(0)), record('ResolveAddresses', u32(0)), record('Autoscroll', u32(0)), record('HistoryDepth', u32(1)), record('AdvancedMode', u32(0))]);
+}

package/dist/src/procmon-events.d.ts

@@ -0,0 +1,13 @@
+export interface ProcmonEvent {
+    time: string;
+    process: string;
+    pid: number;
+    operation: string;
+    path: string;
+    result: string;
+    detail: string;
+    duration?: string;
+}
+/** Parse complete, bounded native CSV rather than splitting quoted paths/details at commas. */
+export declare function procmonEvents(bytes: Buffer): ProcmonEvent[];
+export declare function procmonScope(events: ProcmonEvent[], pid: number, path?: string): ProcmonEvent[];

package/dist/src/procmon-events.js

@@ -0,0 +1,82 @@
+import { fail } from './model.js';
+/** Parse complete, bounded native CSV rather than splitting quoted paths/details at commas. */
+export function procmonEvents(bytes) {
+    if (bytes.length > 16 * 1024 ** 2)
+        fail('limit', 'Native ProcMon CSV exceeds 16 MiB; retained diagnostics are incomplete.');
+    let source;
+    try {
+        const marker = bytes.subarray(0, 2).toString('hex');
+        source = new TextDecoder(marker === 'fffe' ? 'utf-16le' : marker === 'feff' ? 'utf-16be' : 'utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        fail('partial', 'Native ProcMon CSV encoding is invalid; retained bytes were not replaced.');
+    }
+    if (source.includes('\0'))
+        fail('partial', 'Native ProcMon CSV contains invalid text.');
+    const rows = [];
+    let row = [], value = '', quoted = false, closed = false;
+    const cell = () => { if (row.length >= 64)
+        fail('limit', 'Native ProcMon CSV exceeds its column bound.'); row.push(value); value = ''; closed = false; };
+    const record = () => { cell(); if (row.some(x => x.length))
+        rows.push(row); row = []; if (rows.length > 100001)
+        fail('limit', 'Native ProcMon CSV exceeds 100000 event rows.'); };
+    for (let i = 0; i < source.length; i++) {
+        const c = source[i];
+        if (quoted) {
+            if (c === '"') {
+                if (source[i + 1] === '"') {
+                    value += '"';
+                    i++;
+                }
+                else {
+                    quoted = false;
+                    closed = true;
+                }
+            }
+            else
+                value += c;
+            continue;
+        }
+        if (c === '"') {
+            if (value || closed)
+                fail('partial', 'Native ProcMon CSV has an invalid quote.');
+            quoted = true;
+        }
+        else if (c === ',')
+            cell();
+        else if (c === '\n' || c === '\r') {
+            if (c === '\r' && source[i + 1] === '\n')
+                i++;
+            record();
+        }
+        else {
+            if (closed)
+                fail('partial', 'Native ProcMon CSV has text after a quoted cell.');
+            value += c;
+        }
+    }
+    if (quoted)
+        fail('partial', 'Native ProcMon CSV ends inside a quoted value.');
+    if (value || row.length || closed)
+        record();
+    const header = rows.shift();
+    if (!header)
+        fail('partial', 'Native ProcMon CSV has no header.');
+    const columns = ['Process Name', 'PID', 'Operation', 'Path', 'Result', 'Detail'], indices = Object.fromEntries(columns.map(name => [name, header.indexOf(name)]));
+    if (Object.values(indices).some(i => i < 0) || new Set(header).size !== header.length)
+        fail('partial', 'Native ProcMon CSV has an unsupported header.');
+    const time = header.indexOf('Time of Day') >= 0 ? header.indexOf('Time of Day') : header.indexOf('Date & Time'), duration = header.indexOf('Duration');
+    return rows.map(row => {
+        if (row.length !== header.length || !/^\d+$/.test(row[indices.PID]))
+            fail('partial', 'Native ProcMon CSV has a malformed event.');
+        const pid = Number(row[indices.PID]);
+        if (!Number.isSafeInteger(pid) || pid > 0xffffffff)
+            fail('partial', 'Native ProcMon CSV PID is invalid.');
+        return { time: time >= 0 ? row[time] : '', process: row[indices['Process Name']], pid, operation: row[indices.Operation], path: row[indices.Path], result: row[indices.Result], detail: row[indices.Detail], ...(duration >= 0 ? { duration: row[duration] } : {}) };
+    });
+}
+export function procmonScope(events, pid, path) {
+    if (events.some(e => e.pid !== pid || path !== undefined && e.path.toLowerCase() !== path.toLowerCase()))
+        fail('partial', 'Native ProcMon capture scope was not established; no foreign events were returned.');
+    return events;
+}

package/dist/src/procmon.d.ts

@@ -0,0 +1,4 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { ToolInstaller } from './tool-runtime/installer.js';
+export declare function procmonInstaller(c: CommandContext): ToolInstaller;
+export declare function procmonCommands(): CommandDefinition[];

package/dist/src/procmon.js

@@ -0,0 +1,107 @@
+import { command, Permission, CliError } from '@eyeauras/cli-factory';
+import { dirname, join, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdir, writeFile, readFile, stat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { atomicWrite, readJson } from './tool-runtime/store.js';
+import { fileSha256 } from './tool-runtime/archives.js';
+import { processStatus } from './tool-runtime/supervisor.js';
+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 { processIdentity } from './tool-runtime/identity.js';
+import { procmonConfiguration } from './procmon-config.js';
+import { procmonEvents, procmonScope } from './procmon-events.js';
+import { fail, text } from './model.js';
+import { number } from './research.js';
+function supported() { if (process.platform !== 'win32' || process.arch !== 'x64')
+    fail('unsupported', 'ProcMon capture requires Windows x64 and an elevated authorized owner.'); }
+const powershell = () => { const root = process.env.SystemRoot ?? process.env.WINDIR; if (!root)
+    fail('configuration', 'Windows system directory is unavailable.'); return join(root, 'System32/WindowsPowerShell/v1.0/powershell.exe'); };
+async function metadata(c, executable) { const r = await runTool(c, { tool: 'procmon', role: executable ? 'version' : 'privilege', executable: powershell(), arguments: ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', fileURLToPath(new URL('../../runtime/native/file-version.ps1', import.meta.url)), ...(executable ? ['-Executable', executable] : ['-Administrator'])], nativeDeadline: true, timeoutMs: 15000, maxOutputBytes: 65536 }); return r.stdout.trim(); }
+export function procmonInstaller(c) { return new ToolInstaller(c, { id: 'procmon', primary: 'procmon', components: () => { supported(); return { procmon: catalogArtifact('477754bf299c9e5b311c5666f7a4a48dfdb21265eaa8f0cca70ef9d9552e3a10') }; }, launch: roots => ({ executable: join(roots.procmon, 'Procmon64.exe'), arguments: [], environment: {} }), externalInputs: async (executable) => { supported(); if (basename(executable).toLowerCase() !== 'procmon64.exe')
+        fail('configuration', 'Select the ProcMon64.exe x64 executable.'); return {}; }, probe: async (launch, context) => { supported(); const version = await metadata(context, launch.executable); if (!/^4\.12(?:\.[0-9]+)*$/.test(version))
+        fail('configuration', 'Select Process Monitor 4.12.', { observedVersion: version }); return { version, codeMetadataVerified: true, captureRequiresAdministrator: true, elevatedOwner: await metadata(context) === 'true', captureScope: 'explicit existing PID and optional native path; original process lifetime preserved' }; } }); }
+async function captureEvents(c, record) {
+    const directory = c.appArguments.AppDataDirectory, meta = record.metadata ?? {}, root = String(meta.captureDirectory ?? ''), pid = Number(meta.subjectPid), nativePath = meta.nativePath === undefined ? undefined : String(meta.nativePath);
+    if (record.tool !== 'procmon' || record.role !== 'observe' || !['exited', 'failed'].includes(record.state) || !Number.isSafeInteger(pid) || pid < 1 || !/^[a-f0-9-]{36}$/.test(basename(root)) || root !== join(directory, 'runtime/procmon/captures', basename(root)))
+        fail('configuration', 'Select a terminal owned ProcMon observation; active or unverified captures are retained.');
+    const pml = join(root, 'events.pml');
+    if ((await stat(pml)).size > 64 * 1024 ** 2)
+        fail('limit', 'Retained native PML exceeds the 64 MiB query bound.', { diagnostics: root });
+    const pmlSha256 = await fileSha256(pml), receiptPath = join(root, 'export.json'), cached = await readJson(receiptPath);
+    let csv, exportProcess;
+    if (cached) {
+        if (cached.schema !== 1 || typeof cached.csv !== 'string' || typeof cached.csvSha256 !== 'string' || typeof cached.process !== 'string' || !/^[a-f0-9-]{36}$/.test(cached.process) || cached.pmlSha256 !== pmlSha256 || cached.csv !== join(root, basename(cached.csv)) || !/^export-[a-f0-9-]{36}\.csv$/.test(basename(cached.csv)) || await fileSha256(cached.csv) !== cached.csvSha256)
+            fail('binding', 'Retained ProcMon export differs from its verified bytes.');
+        csv = cached.csv;
+        exportProcess = cached.process;
+    }
+    else {
+        csv = join(root, 'export-' + randomUUID() + '.csv');
+        const exported = await procmonInstaller(c).use(selected => runTool(c, { tool: 'procmon', role: 'export', installation: selected.id, executable: selected.executable, arguments: ['/AcceptEula', '/Quiet', '/NoConnect', '/NoFilter', '/OpenLog', pml, '/SaveAs', csv], nativeDeadline: true, nativeRegistry: 'procmon', nativeMutex: 'procmon', timeoutMs: 30000 }));
+        exportProcess = exported.process;
+        if (await fileSha256(pml) !== pmlSha256)
+            fail('binding', 'Native PML changed during export; no complete query was assumed.');
+        if ((await stat(csv)).size > 16 * 1024 ** 2)
+            fail('limit', 'ProcMon CSV exceeds 16 MiB; raw capture is retained.', { diagnostics: root });
+        procmonScope(procmonEvents(await readFile(csv)), pid, nativePath);
+        await atomicWrite(receiptPath, { schema: 1, pmlSha256, csv, csvSha256: await fileSha256(csv), process: exportProcess });
+    }
+    if ((await stat(csv)).size > 16 * 1024 ** 2)
+        fail('limit', 'ProcMon CSV exceeds 16 MiB.');
+    return { events: procmonScope(procmonEvents(await readFile(csv)), pid, nativePath), exportProcess, diagnostics: root };
+}
+async function report(c, record, o) {
+    const limit = number(o.limit ?? 100, 1000, 1), offset = number(o.offset ?? 0, 1000000), { events, exportProcess, diagnostics } = await captureEvents(c, record), operations = {};
+    for (const e of events) {
+        const key = e.operation + ' / ' + e.result;
+        operations[key] = (operations[key] ?? 0) + 1;
+    }
+    const complete = record.outcome === 'completed', base = { state: complete ? 'completed' : 'partial', complete, subject: { pid: record.metadata.subjectPid, birth: record.metadata.subjectBirth }, durationSeconds: record.metadata.durationSeconds, ...(record.metadata.nativePath ? { nativePath: record.metadata.nativePath } : {}), process: record.id, exportProcess, elapsedMs: record.elapsedMs, diagnostics, operations, coverage: 'Only the explicit existing PID, optional native path and observed interval. Earlier and filtered behavior is unknown. An empty window does not establish absence. Interrupted/lost collector outcomes remain partial. Native PML/CSV stay private under profile diagnostics.' };
+    if (o.output) {
+        const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify({ ...base, events }, null, 2) + '\n';
+        await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+        await writeFile(output, content, { flag: 'wx', mode: 0o600 });
+        return { ...base, output, bytes: Buffer.byteLength(content), totalEvents: events.length };
+    }
+    return { ...base, events: events.slice(offset, offset + limit), offset, limit, totalEvents: events.length, truncated: offset + limit < events.length };
+}
+const outputOptions = [{ flags: '--output <file>', description: 'Save full bounded JSON to a new ordinary file' }, { flags: '--limit <count>', description: 'Maximum events to display (1–1000)', defaultValue: 100 }, { flags: '--offset <count>', description: 'Skip events', defaultValue: 0 }];
+export function procmonCommands() {
+    const definition = defineTool({ id: 'procmon', description: 'Observe scoped file, registry and process activity in an existing authorized Windows process', vendorDirect: true, components: [{ id: 'procmon', version: '4.12', artifacts: [] }], lifecycle: { download: (o, c) => procmonInstaller(c).download(Boolean(o.offline), Boolean(o.vendorDirect)), install: (o, c) => procmonInstaller(c).install(o), uninstall: (o, c) => procmonInstaller(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => procmonInstaller(c).doctor(), status: (_o, c) => procmonInstaller(c).status() } });
+    return [command('procmon', definition.description, [...lifecycleCommands(definition), command('observe', 'Record a bounded prefiltered interval without owning the original process lifetime', async ({ options: o }, c) => {
+                supported();
+                const pid = number(o.pid, 2147483647, 1), duration = number(o.durationSeconds ?? 5, 30, 1), path = o.path === undefined ? undefined : text(o.path, 4096), configuration = procmonConfiguration(pid, path);
+                const subject = await processIdentity(pid);
+                if (!subject?.strong || !/^\d+$/.test(subject.birth))
+                    fail('configuration', 'The explicit Windows subject PID is unavailable or its birth identity cannot be verified.');
+                if (await metadata(c) !== 'true')
+                    fail('configuration', 'ProcMon capture requires an elevated insight-cli owner. Stop the current owner and invoke from an authorized elevated terminal.');
+                const directory = join(c.appArguments.AppDataDirectory, 'runtime/procmon/captures', randomUUID()), pmc = join(directory, 'scope.pmc'), pml = join(directory, 'events.pml');
+                await mkdir(directory, { recursive: true, mode: 0o700 });
+                await writeFile(pmc, configuration, { flag: 'wx', mode: 0o600 });
+                return procmonInstaller(c).use(async (selected) => {
+                    if ((await processIdentity(pid))?.birth !== subject.birth)
+                        fail('binding', 'Original process identity changed before capture.');
+                    let capture;
+                    try {
+                        capture = await runTool(c, { tool: 'procmon', role: 'observe', installation: selected.id, executable: selected.executable, arguments: ['/AcceptEula', '/Quiet', '/Minimized', '/LoadConfig', pmc, '/BackingFile', pml, '/Runtime', String(duration)], nativeDeadline: true, nativeRegistry: 'procmon', nativeMutex: 'procmon', observedSubject: { pid, birth: subject.birth }, timeoutMs: (duration + 20) * 1000, acceptedCodes: [0, 1], metadata: { subjectPid: pid, subjectBirth: subject.birth, durationSeconds: duration, ...(path ? { nativePath: path } : {}), captureDirectory: directory } });
+                    }
+                    catch (error) {
+                        const retained = error instanceof CliError ? error.result?.process : undefined;
+                        if (error instanceof CliError && typeof retained === 'string')
+                            throw new CliError(error.message, { code: error.code, cause: error, result: { ...error.result, captureProcess: retained, nextCommand: 'insight-cli procmon inspect ' + retained } });
+                        throw error;
+                    }
+                    try {
+                        return await report(c, await processStatus(c.appArguments.AppDataDirectory, capture.process), o);
+                    }
+                    catch (error) {
+                        throw new CliError(error instanceof Error ? error.message : 'Retained capture could not be queried.', { code: error instanceof CliError ? error.code : 'coordinator.partial', cause: error, result: { captureProcess: capture.process, diagnostics: directory, nextCommand: 'insight-cli procmon inspect ' + capture.process } });
+                    }
+                });
+            }, { permission: Permission.Update, options: [{ flags: '--pid <number>', description: 'Required explicit authorized running Windows PID' }, { flags: '--duration-seconds <seconds>', description: 'Native observation interval (1–30)', defaultValue: 5 }, { flags: '--path <native-path>', description: 'Optional exact native path, such as a file path or HKCU registry path' }, ...outputOptions] }), command('inspect <process>', 'Read or export a retained terminal observation without collecting another interval', async ({ args, options: o }, c) => { supported(); const process = text(args.process, 36); if (!/^[a-f0-9-]{36}$/.test(process))
+                fail('invalid', 'Select an owned observation process ID.'); return report(c, await processStatus(c.appArguments.AppDataDirectory, process), o); }, { permission: Permission.Update, options: outputOptions })])];
+}

package/dist/src/research.d.ts

@@ -127,9 +127,18 @@ export declare class Research {
         session: string;
         target: string;
     }>;
-    function(selected: Scope, at: string, decompile?: boolean): Promise<{
-        code?: unknown;
+    function(selected: Scope, at: string, decompile?: boolean, page?: {
+        limit: number;
+        offset: number;
+    }): Promise<{
+        textSha256?: string | undefined;
+        totalCharacters?: number | undefined;
+        limit?: number | undefined;
+        offset?: number | undefined;
+        sourceTruncated?: boolean | undefined;
         truncated?: boolean | undefined;
+        coordinates?: string | undefined;
+        code?: string | undefined;
         address: string;
         name: unknown;
         signature: string;

package/dist/src/research.js

@@ -1,3 +1,4 @@
+import { textWindow } from './text-window.js';
 import { fail, id, object, text, digest } from './model.js';
 import { fieldKey, scalarMerge, scalarRefresh } from './merge.js';
 import { verifyMutation } from './mutation-effects.js';
@@ -256,7 +257,7 @@ export class Research {
         return { ...selected, items, offset, limit, total: page.total, truncated: object(value).truncated === true || offset + items.length < page.total,
             ...(object(value).scan ? { scan: object(value).scan, totalKnown: object(value).total_known !== false } : {}) };
     }
-    async function(selected, at, decompile = false) {
+    async function(selected, at, decompile = false, page) {
         return this.ordered(selected, async () => {
             const backend = await this.backend();
             await backend.open(selected);
@@ -267,8 +268,9 @@ export class Research {
             if (decompile && typeof result.decompiled_code !== 'string')
                 fail('partial', 'Function decompilation did not produce text.');
             const listing = object(await backend.call(selected, '/get_comment', { address: result.entry_point }));
-            return { ...selected, address: publicAddress(result.entry_point), name: result.name, signature: result.signature, comments: comments(listing),
-                ...(decompile ? { code: result.decompiled_code, truncated: Boolean(object(result.truncation ?? {}).decompiled_code) } : {}) };
+            const window = decompile ? textWindow(String(result.decompiled_code), page?.limit ?? 16000, page?.offset ?? 0, Boolean(object(result.truncation ?? {}).decompiled_code)) : undefined;
+            const { content, ...paging } = window ?? { content: undefined };
+            return { ...selected, address: publicAddress(result.entry_point), name: result.name, signature: result.signature, comments: comments(listing), ...(window ? { code: content, ...paging } : {}) };
         });
     }
     async xrefs(selected, at, limit, offset) {

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

@@ -1,18 +1,13 @@
-export interface RuntimeArtifact {
-    name: string;
-    url: string;
-    sha256: string;
-    format: 'zip' | 'tgz';
-    root: string;
-    license: string;
+import type { ToolArtifact } from './tool-runtime/definition.js';
+export interface RuntimeArtifact extends ToolArtifact {
 }
-export declare const ghidraArchive: RuntimeArtifact;
+export declare const ghidraArchive: ToolArtifact;
 export declare function runtimeCatalog(platform?: string, arch?: string, kernel?: string): {
     schema: number;
     ghidraVersion: string;
     javaVersion: string;
     platform: string;
     architecture: string;
-    ghidra: RuntimeArtifact;
-    java: RuntimeArtifact;
+    ghidra: ToolArtifact;
+    java: ToolArtifact;
 };

package/dist/src/runtime-catalog.js

@@ -1,7 +1,7 @@
 import { release } from 'node:os';
 import { fail } from './model.js';
-const github = 'https://github.com/';
-export const ghidraArchive = { name: 'ghidra-12.1.2', url: github + 'NationalSecurityAgency/ghidra/releases/download/Ghidra_12.1.2_build/ghidra_12.1.2_PUBLIC_20260605.zip', sha256: 'b62e81a0390618466c019c60d8c2f796ced2509c4c1aea4a37644a77272cf99d', format: 'zip', root: 'ghidra_12.1.2_PUBLIC', license: 'Apache-2.0 and included third-party licenses' };
+import { catalogArtifact } from './tool-runtime/catalog.js';
+export const ghidraArchive = catalogArtifact('b62e81a0390618466c019c60d8c2f796ced2509c4c1aea4a37644a77272cf99d');
 const bottles = { arm64_sonoma: '40f68357d6b62a08429c36228907c995e3449283b6d2e08ba5a4e30b53a09725', arm64_sequoia: '90aa942184fca2337ad0a123f818f37372ea642e8e69e969d45cc144a6f26fdf', arm64_tahoe: '079007d8a3a477c8d5901e6596947612d86c8641956424a2bcb71ecd798bedcc', sonoma: 'e30f8c84b64331f87f6ef1890cbdded6672bb7fcc8b674794ac93e4b3e62ad2b' };
 const jdks = {
     'darwin-arm64': ['aarch64_mac', '6ebcf221c9b41507b14c098e93c6ead6440b8d9bd154f8ec666c4c73abbdb201'],
@@ -13,15 +13,14 @@ export function runtimeCatalog(platform = process.platform, arch = process.arch,
     const jdk = jdks[platform + '-' + arch];
     if (!jdk)
         fail('configuration', 'No verified managed runtime for this OS/architecture; use an external compatible Ghidra installation.');
-    const windows = platform === 'win32', format = windows ? 'zip' : 'tgz', extension = windows ? 'zip' : 'tar.gz';
-    const java = { name: 'temurin-21.0.11+10-' + platform + '-' + arch, url: github + 'adoptium/temurin21-binaries/releases/download/jdk-21.0.11%2B10/OpenJDK21U-jdk_' + jdk[0] + '_hotspot_21.0.11_10.' + extension, sha256: jdk[1], format, root: 'jdk-21.0.11+10' + (platform === 'darwin' ? '.jdk/Contents/Home' : ''), license: 'GPL-2.0 WITH Classpath-exception-2.0; included legal notices' };
+    const java = catalogArtifact(jdk[1]);
     let ghidra = ghidraArchive;
     if (platform === 'darwin') {
         const major = Number(kernel.split('.')[0]);
         if (major < 23)
             fail('configuration', 'Managed macOS runtimes require macOS 14 or newer.');
         const tag = arch === 'x64' ? 'sonoma' : major >= 25 ? 'arm64_tahoe' : major >= 24 ? 'arm64_sequoia' : 'arm64_sonoma', hash = bottles[tag];
-        ghidra = { name: 'ghidra-12.1.2-' + tag, url: 'https://ghcr.io/v2/homebrew/core/ghidra/blobs/sha256:' + hash, sha256: hash, format: 'tgz', root: 'ghidra/12.1.2/libexec', license: ghidraArchive.license };
+        ghidra = catalogArtifact(hash);
     }
     return { schema: 1, ghidraVersion: '12.1.2', javaVersion: '21.0.11+10', platform, architecture: arch, ghidra, java };
 }