@eyeauras/insight-cli 0.1.0 → 0.2.0

package/.cli-package-build.json

@@ -1 +1 @@
-{"version":1,"artifact":"c3714e4dd4db303fdccc352327ce7c7f5dff074726238298a6953be70aca1db3"}
+{"version":1,"artifact":"e6afb01edf053fe9b2087f5cc2ca38dd13cb0587a804ebbb1d39c4e5f433c6a3"}

package/README.md

@@ -17,14 +17,17 @@ The executable is `insight-cli`. Its global npm executable directory must be on
 No source checkout, TypeScript build or separate Factory installation is required.
 The pinned Factory IPC runtime is a normal npm dependency fetched from an immutable
 GitHub tarball URL; installation therefore needs npm registry and GitHub access.
-Ghidra 12.1.2 and Java 21 are external dependencies for Ghidra commands.
+Use `insight-cli ghidra install` to deliver the pinned Ghidra/JDK/native/server runtime.
+External Ghidra launchers and Java paths are also supported.
 Help, skill discovery and saving ordinary files do not need Ghidra or Java.
 
 ## Start
 
 ```sh
-insight-cli profile create local --java /path/to/java --ghidra-home /path/to/ghidra
+insight-cli profile create local
 insight-cli --profile local permissions grant Update
+insight-cli --profile local ghidra install
+insight-cli --profile local ghidra status
 insight-cli --profile local ghidra open ./client.exe --session new --json
 ```
 
@@ -53,3 +56,6 @@ and `insight-cli skill insight-re` to locate packaged instructions and reference
 
 Full documentation and verification: [GitHub](https://github.com/iXab3r/insight-cli).
 License: MIT. The bundled GhidraMCP bridge has its own Apache-2.0 license and notice.
+
+Runtime management, local archives and external paths: [managed runtime](references/managed-runtime.md).
+The host debugger and OS permissions are checked separately by `ghidra doctor`.

package/SKILL.md

@@ -3,7 +3,10 @@ name: insight-cli
 description: Research several executable inputs through durable independent sessions and isolated Ghidra contexts using the matching insight-cli facade. Agents supply the investigation and interpret results.
 ---
 
-# insight-cli 0.1.0
+# insight-cli 0.2.0
+
+Use `ghidra status` to inspect runtime readiness; `ghidra install` delivers the pinned runtime.
+For archives, external launchers, server lifecycle or removal, read [managed runtime](references/managed-runtime.md).
 
 This skill and its executable helper are one npm package. Run `insight-cli skill` to locate
 these installed resources. Use generated `--help` for syntax; read the references as needed.

package/dist/src/administration-results.js

@@ -12,7 +12,7 @@ export function administrationResult(operation, p, raw) {
     const value = object(raw);
     if (JSON.stringify(value).length > 1048576)
         fail('limit', 'Administration result exceeds one MiB.');
-    if (['status', 'connect', 'disconnect'].includes(operation)) {
+    if (['status', 'connect', 'disconnect', 'stop'].includes(operation)) {
         if (typeof value.connected !== 'boolean' || !['local', 'external'].includes(String(value.mode)))
             fail('partial', 'Server status is incomplete.');
         if (value.connected && typeof value.repository !== 'string')

package/dist/src/administration.d.ts

@@ -11,4 +11,4 @@ export declare class Administration {
     read(operation: string, parameters: Record<string, unknown>): Promise<Record<string, unknown>>;
     change(operation: string, parameters: Record<string, unknown>, callerId?: string): Promise<unknown>;
 }
-export declare function administrationCommands(service: (context: CommandContext) => Administration): CommandDefinition[];
+export declare function administrationCommands(service: (context: CommandContext) => Administration, unconfiguredStatus?: (context: CommandContext) => Promise<Record<string, unknown> | undefined>): CommandDefinition[];

package/dist/src/administration.js

@@ -1,6 +1,7 @@
 import { command, Permission } from '@eyeauras/cli-factory';
 import { fail, id, text } from './model.js';
 import { option, parsed, key } from './arguments.js';
+import { runtimeProcesses } from './runtime-manager.js';
 import { administrationResult } from './administration-results.js';
 const repository = (value) => { const name = text(value, 128); if (name !== name.trim() || /[\\/\0]/.test(name) || name.startsWith('.'))
     fail('invalid', 'Repository name must be a single bounded name.'); return name; };
@@ -67,6 +68,8 @@ export class Administration {
 const repo = { name: 'repository', type: 'string', required: true }, path = { name: 'path', type: 'string', required: false, default: '/' };
 const leaves = [
     { names: ['status'], operation: 'status', gate: Permission.ReadOnly, params: [] },
+    { names: ['start'], operation: 'connect', gate: Permission.Update, params: [] },
+    { names: ['stop'], operation: 'stop', gate: Permission.Update, params: [] },
     { names: ['connect'], operation: 'connect', gate: Permission.Update, params: [] },
     { names: ['disconnect'], operation: 'disconnect', gate: Permission.Update, params: [] },
     { names: ['repositories', 'list'], operation: 'repositories', gate: Permission.ReadOnly, params: [] },
@@ -81,11 +84,22 @@ const leaves = [
     { names: ['admin', 'terminate-checkout'], operation: 'terminate_checkout', gate: 'Destructive', params: [repo, { ...path, required: true, default: undefined }, { name: 'checkout_id', type: 'string', required: false }] },
     { names: ['admin', 'terminate-all-checkouts'], operation: 'terminate_all_checkouts', gate: 'Destructive', params: [repo, path] },
 ];
-export function administrationCommands(service) {
+export function administrationCommands(service, unconfiguredStatus) {
     const children = [];
     for (const leaf of leaves) {
         const changing = leaf.gate !== Permission.ReadOnly;
-        const definition = command(leaf.names.at(-1), 'Operate on the configured server and explicit repository', ({ options: o }, c) => {
+        const definition = command(leaf.names.at(-1), 'Operate on the configured server and explicit repository', async ({ options: o }, c) => {
+            if (leaf.operation === 'stop') {
+                if (c.profile.values.server)
+                    fail('authorization', 'External server lifecycle is owned by its operator. Use server disconnect.');
+                if ((await runtimeProcesses(c.appArguments.AppDataDirectory)).some(p => p.kind !== 'server'))
+                    fail('busy', 'Close active Ghidra contexts before stopping their server.');
+            }
+            if (leaf.operation === 'status' && unconfiguredStatus) {
+                const passive = await unconfiguredStatus(c);
+                if (passive)
+                    return passive;
+            }
             const parameters = {};
             for (const p of leaf.params) {
                 const value = o[key(p.name)];

package/dist/src/cli.js

@@ -27,16 +27,46 @@ import { VersionTracking, trackingCommands } from './version-tracking.js';
 import { Extensions, extensionCommands, extensionState, extensionInventoryCommands, managedExtensions } from './extensions.js';
 import { Synchronization, synchronizationCommands } from './sync-policy.js';
 import { artifactsCommands } from './saved-materials.js';
+import { RuntimeManager, runtimeCommands, runtimeProcesses } from './runtime-manager.js';
+import { runtimeSelection } from './runtime-selection.js';
 const bindingFields = ['java', 'ghidraHome', 'mcpJar', 'mcpJarSha256', 'server', 'repository', 'readerUser', 'publisherUser', 'maxContexts', 'debuggerPython', 'windbgDir', 'archiveUrl'];
 class Owner {
     options;
     profiles = new Map();
+    runtimeChanging = new Set();
+    async runtime(c, action, quiescent = true) {
+        const directory = c.appArguments.AppDataDirectory;
+        if (this.runtimeChanging.has(directory))
+            fail('busy', 'Another runtime operation is in progress.');
+        const current = this.profiles.get(directory);
+        if (quiescent && current?.tasks.size)
+            fail('busy', 'Research operations are in progress; finish them before managing the runtime.');
+        this.runtimeChanging.add(directory);
+        try {
+            if (!quiescent)
+                return await action();
+            const processes = await runtimeProcesses(directory);
+            if (processes.length)
+                fail('busy', 'Close Ghidra contexts and stop the owned server before changing or checking the runtime.', { processes });
+            if (current) {
+                await (await current.backend)?.dispose();
+                current.workspace.close();
+                this.profiles.delete(directory);
+            }
+            return await action();
+        }
+        finally {
+            this.runtimeChanging.delete(directory);
+        }
+    }
     constructor(options) {
         this.options = options;
     }
     selected(c) {
         const directory = c.appArguments.AppDataDirectory;
-        const configuration = digest({ profile: Object.fromEntries(bindingFields.map(key => [key, c.profile.values[key]])), extensions: extensionState(join(directory, 'workspace')).modules.filter(m => m.enabled).map(m => [m.name, m.sha256]) });
+        if (this.runtimeChanging.has(directory))
+            fail('busy', 'Runtime preparation is in progress.');
+        const configuration = digest({ runtime: runtimeSelection(directory), profile: Object.fromEntries(bindingFields.map(key => [key, c.profile.values[key]])), extensions: extensionState(join(directory, 'workspace')).modules.filter(m => m.enabled).map(m => [m.name, m.sha256]) });
         let profile = this.profiles.get(directory);
         if (!profile) {
             profile = { workspace: new Workspace(join(directory, 'workspace'), c.profile.name), tasks: new Map(), configuration };
@@ -64,6 +94,8 @@ class Owner {
     }
     async invalidateProfile(app) {
         const directory = app.AppDataDirectory, profile = this.profiles.get(directory);
+        if (this.runtimeChanging.has(directory))
+            fail('busy', 'Runtime preparation is in progress; finish it before changing or deleting the profile.');
         const materials = await readdir(join(directory, 'materials')).catch(error => { if (error.code === 'ENOENT')
             return []; throw error; });
         if (existsSync(join(directory, 'workspace', 'workspace.sqlite')) || materials.length)
@@ -190,7 +222,7 @@ function scopedFailures(entry, owner, parents = []) {
 export function createDefinition(options = {}) {
     const owner = new Owner(options);
     const definition = {
-        name: 'insight-cli', applicationId: 'insight-cli', version: '0.1.0', description: 'Isolated research contexts and coordinated Ghidra analysis',
+        name: 'insight-cli', applicationId: 'insight-cli', version: '0.2.0', description: 'Isolated research contexts and coordinated Ghidra analysis',
         resources: [owner], permissions: { categories: [{ name: 'Destructive', description: 'Explicit deletion or replacement of retained research data', enabledByDefault: false }] }, ...(options.runtime ? { runtime: options.runtime } : {}),
         profile: { fields: fields.map(([name, flags, description]) => ({ name: name, flags: flags, description: description,
                 ...(name === 'maxContexts' ? { normalize: (value) => number(value, 16, 1) } : {}) })) },
@@ -249,7 +281,7 @@ export function createDefinition(options = {}) {
                 const name = args.name === undefined ? 'insight-cli' : text(args.name);
                 if (!['insight-cli', 'insight-re'].includes(name))
                     fail('notFound', 'Unknown skill; choose insight-cli or insight-re.');
-                return { version: '0.1.0', name, path: fileURLToPath(new URL(name === 'insight-re' ? '../../skills/insight-re/SKILL.md' : '../../SKILL.md', import.meta.url)),
+                return { version: '0.2.0', name, path: fileURLToPath(new URL(name === 'insight-re' ? '../../skills/insight-re/SKILL.md' : '../../SKILL.md', import.meta.url)),
                     skills: ['insight-cli', 'insight-re'] };
             })],
         commands: [
@@ -381,7 +413,7 @@ export function createDefinition(options = {}) {
         ],
     };
     return { ...definition, commands: definition.commands?.map(entry => entry.name === 'ghidra' ?
-            scopedFailures({ ...entry, children: extendQueries(extendQueries(extendQueries(entry.children ?? [], queryCommands(c => owner.selected(c).research)), mutationCommands(c => owner.selected(c).research)), [...sdkCommands(c => owner.selected(c).research), ...sdkFileCommands(c => owner.selected(c).sdkFiles), ...trackingCommands(c => owner.selected(c).tracking), ...crossCommands(c => owner.selected(c).research), ...administrationCommands(c => owner.selected(c).administration),
-                    ...extensionCommands(c => new Extensions(join(c.appArguments.AppDataDirectory, 'workspace'))), ...extensionInventoryCommands(c => owner.selected(c).backend), ...pluginCommands(c => owner.selected(c).ui), ...synchronizationCommands(c => owner.selected(c).synchronization), ...utilityCommands(), ...lifecycleCommands(c => owner.selected(c).lifecycle), ...projectCommands(c => owner.selected(c).projects), ...uiCommands(c => owner.selected(c).ui), ...debuggerCommands(c => owner.selected(c).debugger), ...archiveCommands(c => owner.selected(c).archive)]) }, owner) : entry) };
+            scopedFailures({ ...entry, children: extendQueries(extendQueries(extendQueries(entry.children ?? [], queryCommands(c => owner.selected(c).research)), mutationCommands(c => owner.selected(c).research)), [...sdkCommands(c => owner.selected(c).research), ...sdkFileCommands(c => owner.selected(c).sdkFiles), ...trackingCommands(c => owner.selected(c).tracking), ...crossCommands(c => owner.selected(c).research), ...administrationCommands(c => owner.selected(c).administration, options.backend ? undefined : async (c) => { const status = await new RuntimeManager(c).status(); return status.state === 'not_ready' ? { ...status.server, connected: false, state: 'runtime_not_ready', missing: status.missing } : undefined; }),
+                    ...extensionCommands(c => new Extensions(join(c.appArguments.AppDataDirectory, 'workspace'))), ...extensionInventoryCommands(c => owner.selected(c).backend), ...pluginCommands(c => owner.selected(c).ui), ...synchronizationCommands(c => owner.selected(c).synchronization), ...utilityCommands(), ...runtimeCommands((c, action, quiescent) => owner.runtime(c, action, quiescent)), ...lifecycleCommands(c => owner.selected(c).lifecycle, c => new RuntimeManager(c).status()), ...projectCommands(c => owner.selected(c).projects), ...uiCommands(c => owner.selected(c).ui), ...debuggerCommands(c => owner.selected(c).debugger), ...archiveCommands(c => owner.selected(c).archive)]) }, owner) : entry) };
 }
 export const createInsightCli = (options = {}) => createCli(createDefinition(options));

package/dist/src/contexts.js

@@ -1,8 +1,9 @@
+import { runtimeProcesses } from './runtime-manager.js';
 import { spawn } from 'node:child_process';
 import { randomUUID, randomBytes } from 'node:crypto';
 import { mkdir, open, readFile, readdir, rename, link, realpath, copyFile, chmod, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
-import { join, delimiter, sep, resolve } from 'node:path';
+import { join, delimiter, sep, resolve, dirname } from 'node:path';
 import { createServer } from 'node:net';
 import { setTimeout as delay } from 'node:timers/promises';
 import { nativeHelpers, nativeInputs, nativeJvmDirectories, nativeExtensionArguments } from './native-inputs.js';
@@ -73,7 +74,16 @@ export class GhidraContexts {
     fork(c) { return new GhidraContexts(this.workspace, this.inputs, c, this.running, this.modelTasks, this.ownedServer.fork(c), this.capacity); }
     directory() { return join(this.workspace.directory, 'ghidra-native'); }
     server() { return this.ownedServer; }
-    async administration(operation, parameters) { return this.server().administration(operation, parameters); }
+    async administration(operation, parameters) {
+        if (operation === 'stop') {
+            if (this.c.profile.values.server)
+                fail('authorization', 'External server lifecycle is owned by its operator. Use server disconnect.');
+            const processes = await runtimeProcesses(dirname(this.workspace.directory));
+            if (processes.some(p => p.kind !== 'server'))
+                fail('busy', 'Close active Ghidra contexts before stopping their server.');
+        }
+        return this.server().administration(operation, parameters);
+    }
     async sdkFile(operation, parameters) { return this.server().sdkFile(operation, parameters); }
     async prepareRoot(kind, target, context) {
         const root = join(this.directory(), kind, context ?? target, randomUUID());

package/dist/src/lifecycle.d.ts

@@ -46,4 +46,4 @@ export declare class Lifecycle {
     discard(selected: Scope, callerId?: string): Promise<unknown>;
     saveAll(session: string, callerId?: string): Promise<unknown>;
 }
-export declare function lifecycleCommands(service: (context: CommandContext) => Lifecycle): CommandDefinition[];
+export declare function lifecycleCommands(service: (context: CommandContext) => Lifecycle, runtimeStatus?: (context: CommandContext) => Promise<unknown>): CommandDefinition[];

package/dist/src/lifecycle.js

@@ -138,11 +138,17 @@ export class Lifecycle {
         return result;
     }
 }
-export function lifecycleCommands(service) {
+export function lifecycleCommands(service, runtimeStatus) {
     return [command('changes', 'Manage unpublished edits in the selected context', [
             command('discard', 'Save a retained copy, then restore the opening base without publication', ({ options: o }, c) => service(c).discard(scope(o), o.requestId === undefined ? undefined : id(o.requestId)), { permission: 'Destructive', options: [...selectedOptions, { flags: '--request-id <id>', description: 'Retrieve the same local discard result' }] })
         ]),
         command('save-all', 'Save every Ghidra context in the explicit session; outcomes are per context', ({ options: o }, c) => service(c).saveAll(id(o.session), o.requestId === undefined ? undefined : id(o.requestId)), { permission: Permission.Update, options: [{ flags: '--session <id>', description: 'Explicit session whose contexts are saved', required: true }, { flags: '--request-id <id>', description: 'Retrieve the recorded session save outcomes' }] }),
-        command('status', 'Verify tool health and inspect the selected private context', ({ options: o }, c) => service(c).health(scope(o)), { permission: Permission.ReadOnly, options: selectedOptions }),
+        command('status', 'Inspect the installed runtime, or verify a selected context', ({ options: o }, c) => {
+            if (o.session === undefined && o.target === undefined && runtimeStatus)
+                return runtimeStatus(c);
+            if (o.session === undefined || o.target === undefined)
+                fail('invalid', 'Context status requires both --session and --target.');
+            return service(c).health(scope(o));
+        }, { permission: Permission.ReadOnly, options: selectedOptions.map(option => ({ ...option, required: false })) }),
         ...['save', 'close'].map(name => command(name, name === 'save' ? 'Save private work without publication' : 'Save and release the owned context; reopen retains local work', ({ options: o }, c) => service(c).change(scope(o), name, o.requestId === undefined ? undefined : id(o.requestId)), { permission: Permission.Update, options: [...selectedOptions, { flags: '--request-id <id>', description: 'Retrieve the lifecycle outcome after a lost response' }] }))];
 }

package/dist/src/native-inputs.js

@@ -6,6 +6,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { fail, stable, text } from './model.js';
 import { managedExtensions, extensionJvmArguments } from './extensions.js';
+import { runtimeValues, runtimeSelection } from './runtime-selection.js';
 export const pinnedMcpJar = '7084e2fda16dc779dd05398e48821ff3f9ace4d32757ea143b257b39689e5fbd';
 export const packagedMcpJar = fileURLToPath(new URL('../../runtime/GhidraMCP-7.0.0.jar', import.meta.url));
 /** Ghidra has its own cache/settings overrides in addition to Java's home/tmp properties. */
@@ -78,6 +79,10 @@ export async function nativeRuntimeFingerprint(ghidraVersion, files) {
     return createHash('sha256').update(stable({ schema: 2, ghidraVersion, hashes })).digest('hex');
 }
 export async function nativeInputs(values, directory) {
+    if (directory)
+        values = runtimeValues(dirname(directory), values);
+    if (!values.java || !values.ghidraHome)
+        fail('configuration', 'Ghidra is not installed. Run insight-cli ghidra install, or supply external runtime paths.');
     const requested = [text(values.java, 4096), text(values.ghidraHome, 4096), text(values.mcpJar ?? packagedMcpJar, 4096)];
     if (!requested.every(isAbsolute))
         fail('configuration', 'Configure absolute Java, Ghidra home and GhidraMCP jar paths.');
@@ -110,12 +115,18 @@ export async function nativeInputs(values, directory) {
         join(debug, 'Debugger-agent-lldb/pypkg/dist/ghidralldb-12.1-py3-none-any.whl')
     ];
     const files = await nativeRuntimeFiles(ghidraHome, java);
+    const baseFingerprint = await nativeRuntimeFingerprint(ghidraVersion, [...files, { name: 'bridge/GhidraMCP-7.0.0.jar', path: mcpJar }]);
+    if (directory) {
+        const selected = runtimeSelection(dirname(directory));
+        if (selected && selected.fingerprint !== baseFingerprint)
+            fail('binding', 'Selected runtime inputs differ from their installation receipt; reinstall or restore the verified files.');
+    }
     for (const module of modules)
         for (const file of module.files)
             files.push({ name: 'extension/' + module.name + '/' + file.name, path: join(module.root, file.name) });
     // Logical names bind locations without embedding the author's installation path.
     files.push({ name: 'bridge/GhidraMCP-7.0.0.jar', path: mcpJar });
-    const fingerprint = await nativeRuntimeFingerprint(ghidraVersion, files);
+    const fingerprint = modules.length ? await nativeRuntimeFingerprint(ghidraVersion, files) : baseFingerprint;
     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. */

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

@@ -0,0 +1,5 @@
+import type { RuntimeArtifact } from './runtime-catalog.js';
+export declare function fileSha256(path: string): Promise<string>;
+export declare function archiveName(name: string): string;
+export declare function extractArchive(file: string, destination: string, format: 'tgz' | 'zip'): Promise<void>;
+export declare function cacheArtifact(artifact: RuntimeArtifact, cache: string, fetcher: typeof fetch, signal: AbortSignal, offline?: boolean): Promise<string>;

package/dist/src/runtime-archives.js

@@ -0,0 +1,127 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdir, open, rename, rm, stat } from 'node:fs/promises';
+import { dirname, join, posix } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import * as tar from 'tar';
+import * as zip from 'yauzl';
+import { fail } from './model.js';
+export async function fileSha256(path) { const hash = createHash('sha256'); for await (const chunk of createReadStream(path))
+    hash.update(chunk); return hash.digest('hex'); }
+export function archiveName(name) {
+    if (!name || name.includes('\\') || name.includes('\0') || name.startsWith('/') || /^[a-zA-Z]:/.test(name) || name.split('/').includes('..'))
+        fail('invalid', 'Runtime archive contains an unsafe path.');
+    return name.replace(/^(\.\/)+/, '');
+}
+export async function extractArchive(file, destination, format) {
+    await mkdir(destination, { recursive: true, mode: 0o700 });
+    let count = 0, bytes = 0;
+    const bound = (name, size) => { archiveName(name); if (++count > 100000 || !Number.isSafeInteger(size) || size < 0 || (bytes += size) > 8 * 1024 ** 3)
+        fail('limit', 'Runtime archive exceeds extraction bounds.'); };
+    if (format === 'tgz') {
+        let unsafe;
+        await tar.t({ file, strict: true, filter: (path, entry) => {
+                try {
+                    if (!('type' in entry))
+                        fail('invalid', 'Unsupported runtime archive metadata.');
+                    bound(path, entry.size);
+                    if (!['File', 'Directory', 'SymbolicLink', 'Link', 'OldFile', 'ContiguousFile'].includes(entry.type))
+                        fail('invalid', 'Unsupported runtime archive entry.');
+                    if (entry.type === 'SymbolicLink' || entry.type === 'Link') {
+                        const target = entry.linkpath;
+                        if (typeof target !== 'string')
+                            fail('invalid', 'Runtime archive link omitted its target.');
+                        if (target.startsWith('/') || target.includes('\\') || /^[a-zA-Z]:/.test(target))
+                            fail('invalid', 'Runtime archive link escapes extraction storage.');
+                        const joined = posix.normalize(entry.type === 'Link' ? target : posix.join(posix.dirname(path), target));
+                        archiveName(joined);
+                    }
+                    return true;
+                }
+                catch (error) {
+                    unsafe ??= error;
+                    return false;
+                }
+            } });
+        if (unsafe)
+            throw unsafe;
+        await tar.x({ file, cwd: destination, strict: true, preserveOwner: false, noChmod: false });
+        return;
+    }
+    const archive = await new Promise((ok, bad) => zip.open(file, { lazyEntries: true, strictFileNames: true }, (e, z) => e ? bad(e) : ok(z)));
+    await new Promise((ok, bad) => {
+        const failed = (e) => { archive.close(); bad(e); };
+        archive.on('error', failed);
+        archive.on('end', ok);
+        archive.on('entry', (entry) => {
+            void (async () => {
+                bound(entry.fileName, entry.uncompressedSize);
+                const mode = entry.externalFileAttributes >>> 16, type = mode & 0o170000;
+                if (type && type !== 0o100000 && type !== 0o040000)
+                    fail('invalid', 'Runtime zip may contain only files and directories.');
+                const path = join(destination, entry.fileName);
+                if (entry.fileName.endsWith('/'))
+                    await mkdir(path, { recursive: true, mode: 0o700 });
+                else {
+                    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+                    const stream = await new Promise((ok, bad) => archive.openReadStream(entry, (e, s) => e ? bad(e) : ok(s)));
+                    await pipeline(stream, createWriteStream(path, { flags: 'wx', mode: mode & 0o111 ? 0o755 : 0o644 }));
+                }
+                archive.readEntry();
+            })().catch(failed);
+        });
+        archive.readEntry();
+    });
+}
+export async function cacheArtifact(artifact, cache, fetcher, signal, offline = false) {
+    await mkdir(cache, { recursive: true, mode: 0o700 });
+    const path = join(cache, artifact.sha256 + '.' + artifact.format);
+    try {
+        if ((await stat(path)).isFile() && await fileSha256(path) === artifact.sha256)
+            return path;
+        fail('binding', 'Cached runtime archive failed its SHA256 check; remove the corrupt cache entry before retrying.');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (offline)
+        fail('configuration', 'Required runtime archive is not cached; run ghidra download before using --offline.', { artifact: artifact.name, sha256: artifact.sha256 });
+    const temporary = path + '.partial-' + randomUUID();
+    try {
+        let headers = {};
+        if (artifact.url.startsWith('https://ghcr.io/v2/homebrew/core/ghidra/')) {
+            const response = await fetcher('https://ghcr.io/token?service=ghcr.io&scope=repository:homebrew/core/ghidra:pull', { signal, redirect: 'error' });
+            if (!response.ok)
+                fail('download', 'Anonymous runtime registry authorization failed.');
+            const value = await response.json();
+            if (!value.token || value.token.length > 8192)
+                fail('download', 'Invalid anonymous runtime registry token.');
+            headers = { Authorization: 'Bearer ' + value.token };
+        }
+        const response = await fetcher(artifact.url, { signal, headers });
+        if (!response.ok || !response.body)
+            fail('download', 'Pinned runtime download failed.', { artifact: artifact.name, status: response.status });
+        let size = 0;
+        const hash = createHash('sha256'), handle = await open(temporary, 'wx', 0o600);
+        try {
+            for await (const chunk of response.body) {
+                if ((size += chunk.byteLength) > 2 * 1024 ** 3)
+                    fail('limit', 'Runtime download exceeds two GiB.');
+                hash.update(chunk);
+                await handle.writeFile(chunk);
+            }
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        if (hash.digest('hex') !== artifact.sha256)
+            fail('binding', 'Downloaded runtime archive failed its pinned SHA256 check.');
+        await rename(temporary, path);
+        return path;
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

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

@@ -0,0 +1,18 @@
+export interface RuntimeArtifact {
+    name: string;
+    url: string;
+    sha256: string;
+    format: 'zip' | 'tgz';
+    root: string;
+    license: string;
+}
+export declare const ghidraArchive: RuntimeArtifact;
+export declare function runtimeCatalog(platform?: string, arch?: string, kernel?: string): {
+    schema: number;
+    ghidraVersion: string;
+    javaVersion: string;
+    platform: string;
+    architecture: string;
+    ghidra: RuntimeArtifact;
+    java: RuntimeArtifact;
+};

package/dist/src/runtime-catalog.js

@@ -0,0 +1,27 @@
+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' };
+const bottles = { arm64_sonoma: '40f68357d6b62a08429c36228907c995e3449283b6d2e08ba5a4e30b53a09725', arm64_sequoia: '90aa942184fca2337ad0a123f818f37372ea642e8e69e969d45cc144a6f26fdf', arm64_tahoe: '079007d8a3a477c8d5901e6596947612d86c8641956424a2bcb71ecd798bedcc', sonoma: 'e30f8c84b64331f87f6ef1890cbdded6672bb7fcc8b674794ac93e4b3e62ad2b' };
+const jdks = {
+    'darwin-arm64': ['aarch64_mac', '6ebcf221c9b41507b14c098e93c6ead6440b8d9bd154f8ec666c4c73abbdb201'],
+    'darwin-x64': ['x64_mac', '34180eb03e6d207c388cce3da668f6cc7cd7508c185c24782fadac2c9c0e66f9'],
+    'linux-x64': ['x64_linux', '4b2220e232a97997b436ca6ab15cbf70171ecff52958a46159dfa5a8c44ca4de'],
+    'win32-x64': ['x64_windows', 'd3625e7cadf23787ea540229544b6e2ab494b3b54da1801879e583e1dfee0a64'],
+};
+export function runtimeCatalog(platform = process.platform, arch = process.arch, kernel = release()) {
+    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' };
+    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 };
+    }
+    return { schema: 1, ghidraVersion: '12.1.2', javaVersion: '21.0.11+10', platform, architecture: arch, ghidra, java };
+}

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

@@ -0,0 +1,101 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+export declare function runtimeWrite(path: string, value: unknown): Promise<void>;
+/** Passive, conservative inventory: a reused PID blocks deletion; it never grants kill authority. */
+export declare function runtimeProcesses(directory: string): Promise<Record<string, unknown>[]>;
+export declare function externalGhidra(path: string): Promise<string>;
+export declare class RuntimeManager {
+    private readonly c;
+    readonly directory: string;
+    readonly root: string;
+    constructor(c: CommandContext);
+    status(): Promise<{
+        missing: string[];
+        capabilities: {
+            headless: boolean;
+            decompiler: boolean;
+            gui: boolean;
+            debugger: {
+                backend: string;
+                requires: string;
+                checkedBy: string;
+            } | {
+                backend: string;
+                checkedBy: string;
+                requires?: undefined;
+            };
+        };
+        server: {
+            pid?: unknown;
+            mode: string;
+            state: string;
+        };
+        processes: Record<string, unknown>[];
+        installations: {
+            id: string;
+            selected: boolean;
+            ghidraVersion: unknown;
+            verifiedAt: unknown;
+        }[];
+        retainedStages: string[];
+        lastCheck: any;
+        storage: {
+            runtime: string;
+            research: string;
+            materials: string;
+        };
+        installation?: string | undefined;
+        fingerprint?: string | undefined;
+        state: string;
+        mode: string;
+        recommended: string;
+        ghidraVersion: string | undefined;
+        java: string | undefined;
+        ghidraHome: string | undefined;
+    }>;
+    download(offline?: boolean): Promise<{
+        state: string;
+        ghidraVersion: string;
+        javaVersion: string;
+        items: {
+            name: string;
+            path: string;
+            sha256: string;
+            license: string;
+        }[];
+    }>;
+    private archive;
+    private cleanupProbes;
+    install(o: Record<string, unknown>): Promise<{
+        checks: string[];
+        schema: 1;
+        mode: "managed" | "external";
+        id?: string;
+        ghidraHome: string;
+        java: string;
+        fingerprint: string;
+        selectedAt: string;
+        uninstalledAt?: string;
+        state: string;
+    }>;
+    uninstall(purgeCache?: boolean): Promise<{
+        state: string;
+        mode: "external" | "managed";
+        externalInstallationPreserved: boolean;
+        researchPreserved: boolean;
+        materialsPreserved: boolean;
+        cachePreserved: boolean;
+    }>;
+    private probe;
+    doctor(): Promise<{
+        state: string;
+        fingerprint: string;
+        ghidraVersion: string;
+        checkedAt: string;
+        headless: unknown;
+        decompiler: unknown;
+        server: boolean;
+        debugger: Record<string, unknown>;
+        diagnostics: string;
+    }>;
+}
+export declare function runtimeCommands(exclusive: <T>(c: CommandContext, action: () => Promise<T>, quiescent?: boolean) => Promise<T>): CommandDefinition[];