@eyeauras/insight-cli 0.1.0 → 0.2.1

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

@@ -0,0 +1,13 @@
+import type { ToolArtifact } from './tool-runtime/definition.js';
+export interface RuntimeArtifact extends ToolArtifact {
+}
+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: ToolArtifact;
+    java: ToolArtifact;
+};

package/dist/src/runtime-catalog.js

@@ -0,0 +1,26 @@
+import { release } from 'node:os';
+import { fail } from './model.js';
+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'],
+    '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 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 = catalogArtifact(hash);
+    }
+    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,125 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { atomicWrite } from './tool-runtime/store.js';
+export declare const runtimeWrite: typeof atomicWrite;
+/** 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;
+    constructor(c: CommandContext);
+    get root(): string;
+    status(): Promise<{
+        missing: string[];
+        capabilities: {
+            headless: boolean;
+            decompiler: boolean;
+            gui: boolean;
+            debugger: {
+                backend: string;
+                runtime: {
+                    retainedStages: string[];
+                    processes: import("./tool-runtime/supervisor.js").ProcessRecord[];
+                    tool: string;
+                    state: string;
+                    mode: string;
+                    installation: string | undefined;
+                    executable: string | undefined;
+                    components: Record<string, string>;
+                    lastProbe: Record<string, unknown> | undefined;
+                    recommended: string;
+                };
+                requires: string;
+                checkedBy: string;
+            } | {
+                backend: string;
+                requires: string;
+                checkedBy: string;
+                runtime?: undefined;
+            } | {
+                backend: string;
+                checkedBy: string;
+                runtime?: undefined;
+                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<{
+        debugger?: {
+            backend: string;
+            installation: string;
+            fingerprint: string;
+        } | undefined;
+        checks: unknown;
+        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[];

package/dist/src/runtime-manager.js

@@ -0,0 +1,385 @@
+import { runTool } from './tool-runtime/run.js';
+import { readFile, mkdir, rename, rm, realpath, readdir, stat, cp } from 'node:fs/promises';
+import { existsSync, realpathSync } from 'node:fs';
+import { join, dirname, resolve, delimiter, basename } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { runtimeRoot, runtimeSelection, runtimeValues } from './runtime-selection.js';
+import { runtimeCatalog } from './runtime-catalog.js';
+import { cacheArtifact, extractArchive, consumeArchive } from './tool-runtime/archives.js';
+import { nativeInputs, nativeHelpers, nativeJvmDirectories, pinnedMcpJar } from './native-inputs.js';
+import { GhidraServer, stopLocalServer } from './server.js';
+import { fail, text, digest, object } from './model.js';
+import { atomicWrite, installationStage, removeInstallation, withToolLock, assertUnused } from './tool-runtime/store.js';
+import { lifecycleCommands as sharedLifecycle } from './tool-runtime/definition.js';
+import { managedGhidraDebugger, ghidraDebuggerInstaller, prepareGhidraDebugger } from './ghidra-debugger-runtime.js';
+const suffix = process.platform === 'win32' ? '.exe' : '';
+export const runtimeWrite = atomicWrite;
+const live = (pid) => { if (!Number.isSafeInteger(pid) || Number(pid) < 1)
+    return false; try {
+    process.kill(Number(pid), 0);
+    return true;
+}
+catch (error) {
+    if (error.code === 'ESRCH')
+        return false;
+    throw error;
+} };
+/** Passive, conservative inventory: a reused PID blocks deletion; it never grants kill authority. */
+export async function runtimeProcesses(directory) {
+    const items = [];
+    async function walk(path, depth = 0) {
+        if (depth > 6)
+            return;
+        let entries;
+        try {
+            entries = await readdir(path, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        for (const entry of entries) {
+            const at = join(path, entry.name);
+            if (entry.isDirectory())
+                await walk(at, depth + 1);
+            else if (entry.name === 'process.json') {
+                const p = object(JSON.parse(await readFile(at, 'utf8')));
+                let stopped = false;
+                try {
+                    const s = object(JSON.parse(await readFile(join(path, 'stopped.json'), 'utf8')));
+                    stopped = s.pid === p.pid && s.tokenSecret === p.tokenSecret;
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+                if (!stopped && live(p.pid))
+                    items.push({ kind: p.kind, pid: p.pid, sessionContext: p.context, ...(typeof p.session === 'string' ? { session: p.session } : {}), target: p.target, mode: p.mode });
+            }
+        }
+    }
+    await walk(join(directory, 'workspace', 'ghidra-native'));
+    try {
+        const s = object(JSON.parse(await readFile(join(directory, 'workspace/server/local.json'), 'utf8')));
+        if (live(s.pid))
+            items.push({ kind: 'server', pid: s.pid });
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return items;
+}
+export async function externalGhidra(path) {
+    const resolved = await realpath(path), kind = await stat(resolved);
+    const parent = kind.isDirectory() ? resolved : dirname(dirname(resolved));
+    const candidates = kind.isDirectory() ? [resolved, join(resolved, 'libexec')] : [dirname(resolved), parent, join(parent, 'libexec')];
+    for (const home of candidates)
+        if (existsSync(join(home, 'Ghidra/application.properties'))) {
+            if (!kind.isDirectory() && !['ghidraRun', 'ghidraRun.bat', 'analyzeHeadless', 'analyzeHeadless.bat'].includes(basename(resolved)))
+                fail('configuration', 'Use the Ghidra launcher or installation directory, not a target EXE.');
+            return home;
+        }
+    fail('configuration', 'The external path does not identify a complete Ghidra installation. Use its ghidraRun launcher or installation directory.');
+}
+async function findRoot(root, marker, depth = 0) {
+    if (existsSync(join(root, marker)))
+        return root;
+    if (depth >= 4)
+        return;
+    for (const entry of await readdir(root, { withFileTypes: true }))
+        if (entry.isDirectory()) {
+            const found = await findRoot(join(root, entry.name), marker, depth + 1);
+            if (found)
+                return found;
+        }
+}
+export class RuntimeManager {
+    c;
+    directory;
+    constructor(c) {
+        this.c = c;
+        this.directory = c.appArguments.AppDataDirectory;
+    }
+    // Canonicalize storage once the profile exists, without creating it for passive status.
+    // Keep the Factory directory for shared process/lock identity and existing run receipts.
+    get root() { return runtimeRoot(existsSync(this.directory) ? realpathSync.native(this.directory) : this.directory); }
+    async status() {
+        const selected = runtimeSelection(this.directory), values = selected ? runtimeValuesForStatus(selected, this.c.profile.values) : this.c.profile.values;
+        const java = typeof values.java === 'string' ? values.java : undefined, home = typeof values.ghidraHome === 'string' ? values.ghidraHome : undefined;
+        const missing = [];
+        if (!java || !existsSync(java))
+            missing.push('jdk');
+        if (!home || !existsSync(join(home, 'Ghidra/application.properties')))
+            missing.push('ghidra');
+        if (selected?.uninstalledAt)
+            missing.push('uninstalled');
+        if (selected?.mode === 'managed' && !existsSync(join(this.root, 'installations', selected.id, 'ready.json')))
+            missing.push('installation_receipt');
+        let version;
+        if (home)
+            try {
+                version = /^application.version=(.+)$/m.exec(await readFile(join(home, 'Ghidra/application.properties'), 'utf8'))?.[1]?.trim();
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        const host = process.platform === 'darwin' ? (process.arch === 'arm64' ? 'mac_arm_64' : 'mac_x86_64') : process.platform === 'win32' ? 'win_x86_64' : 'linux_x86_64';
+        const native = home ? join(home, 'Ghidra/Features/Decompiler/os', host, 'decompile' + suffix) : undefined;
+        if (home && (!native || !existsSync(native)))
+            missing.push('decompiler');
+        if (version && version !== '12.1.2')
+            missing.push('compatible_ghidra');
+        let lastCheck;
+        try {
+            lastCheck = JSON.parse(await readFile(join(this.root, 'last-check.json'), 'utf8'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const installations = [];
+        let stages = [];
+        try {
+            for (const name of (await readdir(join(this.root, 'installations'))).slice(0, 100)) {
+                if (!/^[a-f0-9]{64}$/.test(name))
+                    continue;
+                const path = join(this.root, 'installations', name);
+                if (existsSync(join(path, 'ready.json'))) {
+                    const ready = object(JSON.parse(await readFile(join(path, 'ready.json'), 'utf8')));
+                    installations.push({ id: name, selected: name === selected?.id, ghidraVersion: ready.ghidraVersion, verifiedAt: ready.verifiedAt });
+                }
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        try {
+            stages = (await readdir(join(this.root, 'stages'))).slice(0, 100);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const processes = await runtimeProcesses(this.directory), server = processes.find(p => p.kind === 'server');
+        return { state: missing.length ? 'not_ready' : 'installed', mode: selected?.mode ?? (home || java ? 'external' : 'unconfigured'), recommended: 'managed', ghidraVersion: version, java, ghidraHome: home,
+            ...(selected ? { installation: selected.id, fingerprint: selected.fingerprint } : {}), missing, capabilities: { headless: !missing.length, decompiler: !missing.length, gui: !missing.length,
+                debugger: managedGhidraDebugger() ? { backend: 'managed-lldb', runtime: await ghidraDebuggerInstaller(this.c).status(), requires: 'OS debugger authorization', checkedBy: 'ghidra doctor' } : process.platform === 'darwin' ? { backend: 'system-lldb', requires: 'Apple developer tools and OS debugger authorization', checkedBy: 'ghidra doctor' } : { backend: 'host-debugger', checkedBy: 'ghidra doctor' } },
+            server: { mode: this.c.profile.values.server ? 'external' : 'local', state: this.c.profile.values.server ? 'configured' : server ? 'running' : 'stopped', ...(server ? { pid: server.pid } : {}) }, processes, installations, retainedStages: stages, lastCheck: lastCheck ? { ...lastCheck, appliesToSelection: lastCheck.fingerprint === selected?.fingerprint && !selected?.uninstalledAt } : undefined,
+            storage: { runtime: this.root, research: join(this.directory, 'workspace'), materials: join(this.directory, 'materials') } };
+    }
+    async download(offline = false) {
+        const catalog = runtimeCatalog(), cache = join(this.root, 'cache'), items = [];
+        for (const artifact of [catalog.ghidra, catalog.java]) {
+            const path = await cacheArtifact(artifact, cache, this.c.fetch, this.c.signal, offline);
+            items.push({ name: artifact.name, path, sha256: artifact.sha256, license: artifact.license });
+        }
+        if (managedGhidraDebugger())
+            for (const item of (await ghidraDebuggerInstaller(this.c).download(offline)).items)
+                items.push({ name: 'LLDB/Python', path: item.path, sha256: item.sha256, license: item.license });
+        return { state: 'downloaded', ghidraVersion: catalog.ghidraVersion, javaVersion: catalog.javaVersion, items };
+    }
+    async archive(artifact, provided, checksum, offline) {
+        if (provided === undefined)
+            return { path: await cacheArtifact(artifact, join(this.root, 'cache'), this.c.fetch, this.c.signal, offline), artifact };
+        return consumeArchive(resolve(this.c.cwd, text(provided, 4096)), join(this.root, 'cache'), artifact, checksum === undefined ? undefined : text(checksum, 64), this.c.signal);
+    }
+    async cleanupProbes() {
+        // A killed owner may leave a disposable validation server alive. Its authenticated
+        // receipt, not PID existence, authorizes recovery; no research repository is touched.
+        for (const parent of ['stages', 'checks']) {
+            let names;
+            try {
+                names = await readdir(join(this.root, parent));
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            for (const name of names) {
+                if (!/^[a-f0-9-]{36}$/.test(name))
+                    continue;
+                const root = join(this.root, parent, name, ...(parent === 'stages' ? ['validation'] : []));
+                if (existsSync(join(root, 'server/local.json'))) {
+                    if (await realpath(root) !== resolve(root))
+                        fail('binding', 'Retained runtime probe moved outside its owned storage.');
+                    await stopLocalServer(root, this.c);
+                }
+            }
+        }
+    }
+    async install(o) {
+        return withToolLock(this.directory, 'ghidra', async () => {
+            await assertUnused(this.directory, 'ghidra');
+            await this.cleanupProbes();
+            if (o.executable && o.archive)
+                fail('invalid', 'Choose --executable or --archive.');
+            if (o.archiveSha256 && !o.archive || o.javaArchiveSha256 && !o.javaArchive)
+                fail('invalid', 'Archive checksum requires its archive path.');
+            if (o.debuggerArchiveSha256 && !o.debuggerArchive)
+                fail('invalid', 'Debugger archive checksum requires its archive path.');
+            if ((o.debuggerArchive || o.debuggerArchiveSha256) && !managedGhidraDebugger())
+                fail('unsupported', 'A managed debugger archive requires macOS 15+ ARM64.');
+            const catalog = runtimeCatalog(), offline = Boolean(o.offline), external = o.executable ? await externalGhidra(resolve(this.c.cwd, text(o.executable, 4096))) : undefined;
+            const ghidra = external ? undefined : await this.archive(catalog.ghidra, o.archive, o.archiveSha256, offline);
+            const java = o.java ? await realpath(resolve(this.c.cwd, text(o.java, 4096))) : undefined;
+            if (java && o.javaArchive)
+                fail('invalid', 'Choose --java or --java-archive.');
+            const jdk = java ? undefined : await this.archive(catalog.java, o.javaArchive, o.javaArchiveSha256, offline);
+            const identity = digest({ schema: 1, platform: process.platform, architecture: process.arch, external, java, ghidra: ghidra?.artifact.sha256, jdk: jdk?.artifact.sha256, bridge: pinnedMcpJar });
+            const receipt = await installationStage(this.root, identity, async (temporary, installation) => {
+                let ghidraHome = external, nativeOverlay;
+                if (ghidra) {
+                    const extracted = join(temporary, 'ghidra-extract');
+                    await extractArchive(ghidra.path, extracted, ghidra.artifact.format, this.c.signal);
+                    const found = await findRoot(extracted, 'Ghidra/application.properties');
+                    if (!found)
+                        fail('configuration', 'Archive omitted a complete Ghidra installation.');
+                    await rename(found, join(temporary, 'ghidra'));
+                    await rm(extracted, { recursive: true, force: true });
+                    ghidraHome = join(temporary, 'ghidra');
+                    const host = process.arch === 'arm64' ? 'mac_arm_64' : 'mac_x86_64';
+                    if (process.platform === 'darwin' && !existsSync(join(ghidraHome, 'Ghidra/Features/Decompiler/os', host, 'decompile'))) {
+                        const bottle = await cacheArtifact(catalog.ghidra, join(this.root, 'cache'), this.c.fetch, this.c.signal, offline), nativeRoot = join(temporary, 'native-extract');
+                        nativeOverlay = catalog.ghidra;
+                        await extractArchive(bottle, nativeRoot, 'tgz', this.c.signal);
+                        const nativeHome = join(nativeRoot, catalog.ghidra.root);
+                        for (const module of ['Decompiler', 'FileFormats'])
+                            await cp(join(nativeHome, 'Ghidra/Features', module, 'os', host), join(ghidraHome, 'Ghidra/Features', module, 'os', host), { recursive: true, errorOnExist: true });
+                        await rm(nativeRoot, { recursive: true, force: true });
+                    }
+                }
+                let javaPath = java;
+                if (jdk) {
+                    const extracted = join(temporary, 'jdk-extract');
+                    await extractArchive(jdk.path, extracted, jdk.artifact.format, this.c.signal);
+                    const home = await findRoot(extracted, 'bin/java' + suffix);
+                    if (!home)
+                        fail('configuration', 'Java archive omitted a JDK.');
+                    await rename(home, join(temporary, 'jdk'));
+                    await rm(extracted, { recursive: true, force: true });
+                    javaPath = join(temporary, 'jdk/bin/java' + suffix);
+                }
+                const inputs = await nativeInputs({ ...this.c.profile.values, java: javaPath, ghidraHome }, undefined, this.c);
+                await this.probe(inputs, join(temporary, 'validation'));
+                await rm(join(temporary, 'validation'), { recursive: true, force: true });
+                const receipt = { schema: 1, id: identity, ghidraVersion: inputs.ghidraVersion, fingerprint: inputs.fingerprint, java: java ?? join(installation, 'jdk/bin/java' + suffix), ghidraHome: external ?? join(installation, 'ghidra'),
+                    archives: [...(nativeOverlay ? [{ sha256: nativeOverlay.sha256, source: nativeOverlay.url }] : []), ...(ghidra ? [{ sha256: ghidra.artifact.sha256, source: o.archive ? 'local' : catalog.ghidra.url }] : []), ...(jdk ? [{ sha256: jdk.artifact.sha256, source: o.javaArchive ? 'local' : catalog.java.url }] : [])], verifiedAt: new Date().toISOString(), checks: ['jdk', 'native-decompiler', 'local-server-reader-publisher-authority'] };
+                return receipt;
+            }, async (receipt) => {
+                const inputs = await nativeInputs({ ...this.c.profile.values, java: receipt.java, ghidraHome: receipt.ghidraHome }, undefined, this.c);
+                if (inputs.fingerprint !== receipt.fingerprint)
+                    fail('binding', 'Installed runtime differs from its verified installation receipt.');
+            }, this.c.signal);
+            const selected = { schema: 1, mode: external ? 'external' : 'managed', id: identity, ghidraHome: String(receipt.ghidraHome), java: String(receipt.java), fingerprint: String(receipt.fingerprint), selectedAt: new Date().toISOString() };
+            const debuggerRuntime = managedGhidraDebugger() ? await prepareGhidraDebugger(this.c, { archive: o.debuggerArchive, archiveSha256: o.debuggerArchiveSha256, offline: o.offline }) : undefined;
+            await runtimeWrite(join(this.root, 'selection.json'), selected);
+            return { state: 'installed', ...selected, checks: receipt.checks, ...(debuggerRuntime ? { debugger: { backend: 'managed-lldb', installation: debuggerRuntime.id, fingerprint: debuggerRuntime.fingerprint } } : {}) };
+        }, this.c.signal);
+    }
+    async uninstall(purgeCache = false) {
+        return withToolLock(this.directory, 'ghidra', async () => {
+            await assertUnused(this.directory, 'ghidra');
+            await this.cleanupProbes();
+            const selected = runtimeSelection(this.directory);
+            if (!selected)
+                fail('configuration', 'No managed selection exists; externally configured profile paths are never removed.');
+            if (purgeCache && selected.id) {
+                const receipt = object(JSON.parse(await readFile(join(this.root, 'installations', selected.id, 'ready.json'), 'utf8')));
+                for (const a of Array.isArray(receipt.archives) ? receipt.archives : []) {
+                    const sha = String(object(a).sha256);
+                    if (!/^[a-f0-9]{64}$/.test(sha))
+                        fail('binding', 'Invalid cached component identity.');
+                    for (const ext of ['zip', 'tgz'])
+                        await rm(join(this.root, 'cache', sha + '.' + ext), { force: true });
+                }
+            }
+            if (managedGhidraDebugger() && (await ghidraDebuggerInstaller(this.c).status()).state === 'installed')
+                await ghidraDebuggerInstaller(this.c).uninstall(purgeCache);
+            if (selected.id)
+                await removeInstallation(this.root, selected.id);
+            await runtimeWrite(join(this.root, 'selection.json'), { ...selected, uninstalledAt: new Date().toISOString() });
+            // Retain the selection: an explicit external profile must never become an implicit fallback.
+            return { state: 'uninstalled', mode: selected.mode, externalInstallationPreserved: selected.mode === 'external', researchPreserved: true, materialsPreserved: true, cachePreserved: !purgeCache };
+        }, this.c.signal);
+    }
+    async probe(inputs, root) {
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        const classes = await nativeHelpers(root, inputs, this.c), log = join(root, 'doctor.log');
+        let output;
+        try {
+            output = await runTool(this.c, { tool: 'ghidra', role: 'doctor', installation: inputs.fingerprint, executable: inputs.java, arguments: ['-Djava.awt.headless=true', '-Dghidra.home=' + inputs.ghidraHome, ...nativeJvmDirectories(root), '-cp', classes + delimiter + inputs.classpath, 'InsightRuntimeDoctor'],
+                cwd: root, environment: { PATH: dirname(inputs.java), HOME: root, TMPDIR: root }, timeoutMs: 90000, maxOutputBytes: 1024 * 1024 });
+        }
+        catch (error) {
+            await runtimeWrite(log, { failure: String(error.stderr ?? error) });
+            fail('configuration', 'Native decompiler probe failed; the diagnostic stage is retained.', { diagnostics: log });
+        }
+        const value = object(JSON.parse(output.stdout));
+        if (value.state !== 'ready' || value.decompiler !== true || value.expectedReturn !== 42)
+            fail('partial', 'Native decompiler probe did not verify its expected result.');
+        const probeContext = { ...this.c, profile: { ...this.c.profile, values: { ...this.c.profile.values, server: undefined } } };
+        const server = new GhidraServer(root, inputs, probeContext);
+        try {
+            const result = await server.administration('connect', {});
+            if (result.connected !== true || result.mode !== 'local')
+                fail('partial', 'Owned server probe did not connect.');
+            const checked = await server.administration('status', {});
+            if (checked.connected !== true)
+                fail('partial', 'Owned server identity/authority probe failed.');
+        }
+        finally {
+            await server.stop();
+        }
+        return value;
+    }
+    async doctor() {
+        await this.cleanupProbes();
+        const root = join(this.root, 'checks', randomUUID()), values = runtimeValues(this.directory, this.c.profile.values);
+        const inputs = await nativeInputs(values, undefined, this.c), native = await this.probe(inputs, root);
+        let debuggerCheck = { state: 'host_specific' };
+        if (managedGhidraDebugger())
+            try {
+                const selected = await ghidraDebuggerInstaller(this.c).selected();
+                debuggerCheck = { ...(await ghidraDebuggerInstaller(this.c).doctor()), backend: 'managed-lldb', installation: selected.id };
+            }
+            catch {
+                debuggerCheck = { state: 'missing', backend: 'managed-lldb', reason: 'Run insight-cli ghidra install to prepare or repair its LLDB/Python runtime' };
+            }
+        else if (process.platform === 'darwin')
+            try {
+                const checked = await runTool(this.c, { tool: 'ghidra', role: 'debugger-doctor', executable: '/usr/bin/lldb', arguments: ['--no-lldbinit', '--batch', '-o', 'script import lldb,sys; print("INSIGHT_LLDB_PYTHON_OK")'], environment: { PATH: '/usr/bin:/bin', HOME: root, TMPDIR: root }, timeoutMs: 30000, maxOutputBytes: 65536 });
+                debuggerCheck = { state: checked.stdout.includes('INSIGHT_LLDB_PYTHON_OK') ? 'ready' : 'missing', backend: 'system-lldb' };
+            }
+            catch {
+                debuggerCheck = { state: 'missing', backend: 'system-lldb', reason: 'Apple developer tools or debugger authorization is unavailable' };
+            }
+        const result = { state: 'verified', fingerprint: inputs.fingerprint, ghidraVersion: inputs.ghidraVersion, checkedAt: new Date().toISOString(), headless: native.headless, decompiler: native.decompiler, server: true, debugger: debuggerCheck, diagnostics: root };
+        await runtimeWrite(join(this.root, 'last-check.json'), result);
+        if (debuggerCheck.state === 'missing')
+            fail('partial', 'Static analysis and local server passed; the host debugger is unavailable.', { ...result, state: 'partial' });
+        return result;
+    }
+}
+function runtimeValuesForStatus(selection, values) { return { ...values, java: selection.java, ghidraHome: selection.ghidraHome }; }
+export function runtimeCommands(exclusive) {
+    const source = [{ flags: '--archive <path>', description: 'Local Ghidra zip/tar.gz; missing dependencies are downloaded' },
+        { flags: '--debugger-archive <path>', description: 'Local pinned LLDB/Python runtime archive (macOS 15+ ARM64)' },
+        { flags: '--debugger-archive-sha256 <sha256>', description: 'Expected SHA256 for the supplied debugger runtime archive' },
+        { flags: '--archive-sha256 <sha256>', description: 'Expected SHA256 for the supplied Ghidra archive' },
+        { flags: '--java-archive <path>', description: 'Local Java 21 JDK zip/tar.gz' },
+        { flags: '--java-archive-sha256 <sha256>', description: 'Expected SHA256 for the supplied JDK archive' },
+        { flags: '--java <path>', description: 'Use an external Java 21 JDK executable' },
+        { flags: '--executable <path>', description: 'Use an external Ghidra launcher or installation directory; never deleted' },
+        { flags: '--offline', description: 'Use local archives/cache only; never access the network' }];
+    return sharedLifecycle({ id: 'ghidra', description: 'Complete Ghidra runtime', components: [], installOptions: source, lifecycle: {
+            download: (o, c) => exclusive(c, () => new RuntimeManager(c).download(Boolean(o.offline)), false),
+            install: (o, c) => exclusive(c, () => new RuntimeManager(c).install(o)),
+            uninstall: (o, c) => exclusive(c, () => new RuntimeManager(c).uninstall(Boolean(o.purgeCache))),
+            doctor: (_o, c) => exclusive(c, () => new RuntimeManager(c).doctor(), false),
+        } });
+}

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

@@ -0,0 +1,13 @@
+export interface RuntimeSelection {
+    schema: 1;
+    mode: 'managed' | 'external';
+    id?: string;
+    ghidraHome: string;
+    java: string;
+    fingerprint: string;
+    selectedAt: string;
+    uninstalledAt?: string;
+}
+export declare const runtimeRoot: (directory: string) => string;
+export declare function runtimeSelection(directory: string): RuntimeSelection | undefined;
+export declare function runtimeValues(directory: string, values: Record<string, unknown>): Record<string, unknown>;

package/dist/src/runtime-selection.js

@@ -0,0 +1,42 @@
+import { readFileSync, existsSync, realpathSync } from 'node:fs';
+import { join, isAbsolute, resolve } from 'node:path';
+import { fail, object } from './model.js';
+export const runtimeRoot = (directory) => join(directory, 'runtime');
+export function runtimeSelection(directory) {
+    const path = join(runtimeRoot(directory), 'selection.json');
+    if (!existsSync(path))
+        return;
+    const value = object(JSON.parse(readFileSync(path, 'utf8')));
+    if (value.schema !== 1 || !['managed', 'external'].includes(String(value.mode)) || typeof value.java !== 'string' || !isAbsolute(value.java) || typeof value.ghidraHome !== 'string' || !isAbsolute(value.ghidraHome) || !/^[a-f0-9]{64}$/.test(String(value.fingerprint)))
+        fail('binding', 'Runtime selection receipt is invalid.');
+    if (value.mode === 'managed') {
+        const id = String(value.id), recordedProfile = resolve(value.ghidraHome, '../../../..');
+        if (!/^[a-f0-9]{64}$/.test(id) || value.ghidraHome !== join(runtimeRoot(recordedProfile), 'installations', id, 'ghidra'))
+            fail('binding', 'Managed runtime moved outside its owned installation.');
+        // Workspace resolves AppData physically; older install receipts can retain a profile
+        // alias such as /tmp -> /private/tmp. Accept that same profile, never an inner escape.
+        let profile, recorded, home;
+        try {
+            profile = realpathSync.native(directory);
+            recorded = realpathSync.native(recordedProfile);
+            if (existsSync(value.ghidraHome))
+                home = realpathSync.native(value.ghidraHome);
+        }
+        catch {
+            fail('binding', 'Managed runtime profile ownership could not be verified.');
+        }
+        if (recorded !== profile || home !== undefined && home !== join(runtimeRoot(profile), 'installations', id, 'ghidra'))
+            fail('binding', 'Managed runtime moved outside its owned installation.');
+    }
+    return value;
+}
+export function runtimeValues(directory, values) {
+    const selected = runtimeSelection(directory);
+    if (!selected)
+        return values;
+    if (selected.uninstalledAt)
+        fail('configuration', 'Selected Ghidra runtime was uninstalled. Run insight-cli ghidra install.');
+    if (selected.mode === 'managed' && !existsSync(join(runtimeRoot(directory), 'installations', selected.id, 'ready.json')))
+        fail('configuration', 'Selected managed Ghidra is not installed. Run insight-cli ghidra install.');
+    return { ...values, java: selected.java, ghidraHome: selected.ghidraHome };
+}