@eyeauras/insight-cli 0.2.0 → 0.2.2

package/dist/src/tool-runtime/definition.d.ts

@@ -0,0 +1,73 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import type { ToolProcessHooks } from './commands.js';
+export interface ToolArtifact {
+    name: string;
+    url: string;
+    sha256: string;
+    size?: number;
+    format: 'zip' | 'tgz';
+    root: string;
+    license: string;
+    delivery?: {
+        kind: 'vendor-direct';
+        publisher: string;
+        termsUrl: string;
+        reason: string;
+    };
+}
+export interface ToolComponent {
+    id: string;
+    version: string;
+    artifacts: ToolArtifact[];
+    dependencies?: string[];
+}
+export interface ToolInstallation {
+    schema: 1;
+    tool: string;
+    id: string;
+    mode: 'managed' | 'external';
+    root: string;
+    executable: string;
+    fingerprint: string;
+    selectedAt: string;
+    uninstalledAt?: string;
+    components: Record<string, string>;
+}
+export interface ToolProcess {
+    schema: 1;
+    id: string;
+    tool: string;
+    role: string;
+    installation: string;
+    state: 'starting' | 'running' | 'exited' | 'failed' | 'unverified';
+    executable: string;
+    pid?: number;
+    identity?: string;
+    session?: string;
+    target?: string;
+    createdAt: string;
+    endedAt?: string;
+    exitCode?: number | null;
+    signal?: string | null;
+    elapsedMs?: number;
+}
+export interface ToolLifecycle {
+    download(options: Record<string, unknown>, context: CommandContext): Promise<unknown>;
+    install(options: Record<string, unknown>, context: CommandContext): Promise<unknown>;
+    uninstall(options: Record<string, unknown>, context: CommandContext): Promise<unknown>;
+    doctor(options: Record<string, unknown>, context: CommandContext): Promise<unknown>;
+    status?(options: Record<string, unknown>, context: CommandContext): Promise<unknown>;
+}
+export interface ToolDefinition {
+    id: string;
+    description: string;
+    components: ToolComponent[];
+    lifecycle: ToolLifecycle;
+    vendorDirect?: boolean;
+    installOptions?: NonNullable<CommandDefinition['options']>;
+    commands?: CommandDefinition[];
+    processes?: ToolProcessHooks;
+}
+/** Definitions are data/hooks. Factory remains the only parser, permission and output owner. */
+export declare function defineTool(value: ToolDefinition): ToolDefinition;
+export declare function lifecycleCommands(tool: ToolDefinition): CommandDefinition[];

package/dist/src/tool-runtime/definition.js

@@ -0,0 +1,49 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { fail } from '../model.js';
+/** Definitions are data/hooks. Factory remains the only parser, permission and output owner. */
+export function defineTool(value) {
+    if (!/^[a-z][a-z0-9-]*$/.test(value.id))
+        fail('invalid', 'Invalid tool name.');
+    const components = new Map(value.components.map(item => [item.id, item]));
+    if (components.size !== value.components.length)
+        fail('invalid', 'Duplicate tool component.');
+    const done = new Set(), pending = new Set();
+    function visit(id) {
+        const component = components.get(id);
+        if (!component)
+            fail('invalid', 'Unknown tool dependency.');
+        if (pending.has(id))
+            fail('invalid', 'Cyclic tool dependency.');
+        if (done.has(id))
+            return;
+        pending.add(id);
+        for (const dependency of component.dependencies ?? [])
+            visit(dependency);
+        pending.delete(id);
+        done.add(id);
+        for (const artifact of component.artifacts) {
+            if (!/^[a-f0-9]{64}$/.test(artifact.sha256) || new URL(artifact.url).protocol !== 'https:')
+                fail('invalid', 'Tool artifact requires HTTPS and a pinned SHA256.');
+        }
+    }
+    for (const id of components.keys())
+        visit(id);
+    return value;
+}
+export function lifecycleCommands(tool) {
+    const offline = { flags: '--offline', description: 'Use verified local archives and cache without network access' };
+    const vendor = tool.vendorDirect ? [{ flags: '--vendor-direct', description: 'Explicitly acquire pinned non-redistributable bytes from the named vendor' }] : [];
+    const source = [...vendor, { flags: '--archive <path>', description: 'Install from a local tool archive' },
+        { flags: '--archive-sha256 <sha256>', description: 'Expected SHA256 of the local tool archive' },
+        { flags: '--executable <path>', description: 'Use an external executable; its files are never deleted' }, offline];
+    const leaf = (name, description, permission, options) => command(name, description, ({ options: o }, c) => tool.lifecycle[name](o, c), { permission, options });
+    return [
+        leaf('download', 'Download the pinned tool and required runtime components', Permission.Update, [offline, ...vendor]),
+        leaf('install', 'Prepare, verify and select the tool installation', Permission.Update, tool.installOptions ?? source),
+        leaf('uninstall', 'Remove owned software while preserving research and external files', 'Destructive', [
+            { flags: '--purge-cache', description: 'Also remove owned downloaded archives' }
+        ]),
+        leaf('doctor', 'Run bounded probes of the selected tool', Permission.Update, []),
+        ...(tool.lifecycle.status ? [leaf('status', 'Inspect installation and process state without launching the tool', Permission.ReadOnly, [])] : []),
+    ];
+}

package/dist/src/tool-runtime/dotnet.d.ts

@@ -0,0 +1,4 @@
+import type { ToolLaunch } from './installer.js';
+/** Shared private runtime dependency; it is not an independent analytical tool. */
+export declare function dotnetArtifact(platform?: string, architecture?: NodeJS.Architecture): import("./definition.js").ToolArtifact;
+export declare function dotnetLaunch(root: string, entryPoint: string): ToolLaunch;

package/dist/src/tool-runtime/dotnet.js

@@ -0,0 +1,22 @@
+import { join } from 'node:path';
+import { catalogArtifact } from './catalog.js';
+import { fail } from '../model.js';
+const runtimeHashes = {
+    'darwin-arm64': 'fdf7ef21688338ad5d1d99d7eca7f3cf2e159c86e552d3f5acd0553b11c80ca6',
+    'darwin-x64': '50fd6ea005731494a6144fd4617746f4155fdc0f3682d0ba7292eac9e9bf46e3',
+    'linux-x64': '958c952691d2c3f8ce21f717f4e911c02b5da0e21ead21bd576368c454b79c77',
+    'win32-x64': '8db74a746baa450925d01325a2108ccf6ac39af4018047475292ae155c013d89',
+};
+/** Shared private runtime dependency; it is not an independent analytical tool. */
+export function dotnetArtifact(platform = process.platform, architecture = process.arch) {
+    const hash = runtimeHashes[platform + '-' + architecture];
+    if (!hash)
+        fail('configuration', 'No pinned private .NET runtime for this platform; select an external compatible tool executable.');
+    return catalogArtifact(hash);
+}
+export function dotnetLaunch(root, entryPoint) {
+    return {
+        executable: join(root, 'dotnet' + (process.platform === 'win32' ? '.exe' : '')), arguments: [entryPoint],
+        environment: { DOTNET_ROOT: root, DOTNET_MULTILEVEL_LOOKUP: '0', DOTNET_CLI_TELEMETRY_OPTOUT: '1', DOTNET_NOLOGO: '1' },
+    };
+}

package/dist/src/tool-runtime/identity.d.ts

@@ -0,0 +1,6 @@
+export interface ProcessIdentity {
+    birth: string;
+    strong: boolean;
+    group?: number;
+}
+export declare function processIdentity(pid: number): Promise<ProcessIdentity | undefined>;

package/dist/src/tool-runtime/identity.js

@@ -0,0 +1,50 @@
+import { readFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+function unavailable(pid) { try {
+    process.kill(pid, 0);
+}
+catch (e) {
+    if (e.code === 'ESRCH')
+        return;
+} return { birth: 'unavailable', strong: false }; }
+export async function processIdentity(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return;
+    try {
+        if (process.platform === 'linux') {
+            const raw = await readFile('/proc/' + pid + '/stat', 'utf8'), parts = raw.slice(raw.lastIndexOf(')') + 2).split(' ');
+            if (parts[0] === 'Z')
+                return;
+            return { birth: (await readFile('/proc/sys/kernel/random/boot_id', 'utf8')).trim() + ':' + parts[19], strong: true, group: Number(parts[2]) };
+        }
+        if (process.platform === 'darwin') {
+            const r = await exec('/bin/ps', ['-p', String(pid), '-o', 'stat=', '-o', 'pgid=', '-o', 'lstart='], { env: { PATH: '/usr/bin:/bin', LC_ALL: 'C', TZ: 'UTC' }, timeout: 3000, maxBuffer: 4096 });
+            const match = r.stdout.trim().match(/^(\S+)\s+(\d+)\s+(.+)$/);
+            if (!match)
+                return unavailable(pid);
+            if (match[1].startsWith('Z'))
+                return;
+            // ps birth time is second-resolution; recovered macOS processes additionally need a tool identity hook.
+            return { birth: match[3], strong: false, group: Number(match[2]) };
+        }
+        if (process.platform === 'win32') {
+            const script = 'try{$p=[Diagnostics.Process]::GetProcessById(' + pid + ');try{$p.StartTime.ToUniversalTime().Ticks.ToString()}finally{$p.Dispose()}}catch [ArgumentException]{}';
+            const r = await exec('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { windowsHide: true, timeout: 15000, maxBuffer: 4096 });
+            return r.stdout.trim() ? { birth: r.stdout.trim(), strong: true } : unavailable(pid);
+        }
+        try {
+            process.kill(pid, 0);
+            return { birth: 'unverified', strong: false };
+        }
+        catch {
+            return;
+        }
+    }
+    catch (error) {
+        if (['ENOENT', 'ESRCH', 'EACCES', 'EPERM'].includes(error.code ?? '') || error.code === 1)
+            return unavailable(pid);
+        throw error;
+    }
+}

package/dist/src/tool-runtime/installer.d.ts

@@ -0,0 +1,101 @@
+import type { CommandContext } from '@eyeauras/cli-factory';
+import type { ToolArtifact, ToolInstallation } from './definition.js';
+export interface ToolLaunch {
+    executable: string;
+    arguments: string[];
+    environment: Record<string, string>;
+}
+export interface SelectedTool extends ToolInstallation, ToolLaunch {
+    roots: Record<string, string>;
+    lastProbe: Record<string, unknown>;
+    externalInputs?: Record<string, string>;
+    noticeDigest?: string;
+    execution?: ToolLaunch;
+    executionFingerprint?: string;
+}
+/** Read-only verification used by an owned child after the command owner has staged a runtime. */
+export declare function verifyManagedInstallation(directory: string, tool: string, selected: SelectedTool): Promise<void>;
+export interface InstallDescriptor {
+    id: string;
+    primary: string;
+    components: () => Record<string, ToolArtifact>;
+    launch: (roots: Record<string, string>) => ToolLaunch;
+    probe: (launch: ToolLaunch, c: CommandContext) => Promise<Record<string, unknown>>;
+    /** Reviewed nested packaging preparation inside owned staging, before probe/fingerprint. */
+    prepare?: (roots: Record<string, string>, c: CommandContext) => Promise<void>;
+    /** Exceptional upstream adaptation: prepare an owned execution copy, never rewrite external software. */
+    prepareExternal?: (executable: string, stage: string, c: CommandContext) => Promise<ToolLaunch>;
+    preparationId?: string;
+    /** Known sibling executables/data files needed by an external tool family. */
+    externalInputs?: (executable: string, c: CommandContext) => Promise<Record<string, string>>;
+    /** Full retained notices copied into owned installation storage, including external selections. */
+    noticeFiles?: Record<string, string>;
+}
+/** Standard archive-based tools supply layout and a real probe; exceptional tools reuse the stage primitives. */
+export declare class ToolInstaller {
+    readonly c: CommandContext;
+    readonly descriptor: InstallDescriptor;
+    readonly directory: string;
+    readonly root: string;
+    readonly cache: string;
+    constructor(c: CommandContext, descriptor: InstallDescriptor);
+    private receipt;
+    status(): Promise<{
+        retainedStages: string[];
+        processes: import("./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;
+    }>;
+    download(offline?: boolean, vendorDirect?: boolean): Promise<{
+        tool: string;
+        state: string;
+        items: {
+            component: string;
+            path: string;
+            sha256: string;
+            license: string;
+            url: string;
+            delivery: {
+                kind: "vendor-direct";
+                publisher: string;
+                termsUrl: string;
+                reason: string;
+            } | {
+                kind: "owned-release";
+            };
+        }[];
+    }>;
+    install(o: Record<string, unknown>): Promise<{
+        tool: string;
+        state: string;
+        mode: "external" | "managed";
+        installation: string;
+        executable: string;
+        components: {
+            [k: string]: string;
+        };
+        checks: Record<string, unknown>;
+    }>;
+    private verify;
+    use<T>(action: (selection: SelectedTool) => Promise<T>): Promise<T>;
+    selected(): Promise<SelectedTool>;
+    doctor(): Promise<{
+        tool: string;
+        state: string;
+        installation: string;
+        checks: Record<string, unknown>;
+    }>;
+    uninstall(purgeCache?: boolean): Promise<{
+        tool: string;
+        state: string;
+        externalInstallationPreserved: boolean;
+        researchPreserved: boolean;
+        materialsPreserved: boolean;
+    }>;
+}

package/dist/src/tool-runtime/installer.js

@@ -0,0 +1,180 @@
+import { mkdir, stat, rm, readdir, writeFile, readFile } from 'node:fs/promises';
+import { join, resolve, sep, dirname } from 'node:path';
+import { cacheArtifact, consumeArchive, extractArchive, fileSha256, archiveName } from './archives.js';
+import { atomicWrite, readJson, toolRoot, withToolLock, installationStage, removeInstallation, treeFingerprint, assertUnused, withToolUse } from './store.js';
+import { listProcesses } from './supervisor.js';
+import { digest, fail, text } from '../model.js';
+/** Read-only verification used by an owned child after the command owner has staged a runtime. */
+export async function verifyManagedInstallation(directory, tool, selected) {
+    const root = join(toolRoot(directory, tool), 'installations', selected.id);
+    if (selected.schema !== 1 || selected.tool !== tool || selected.mode !== 'managed' || selected.uninstalledAt || !/^[a-f0-9]{64}$/.test(selected.id) || selected.root !== root || !resolve(selected.executable).startsWith(resolve(root) + sep))
+        fail('binding', 'Invalid managed tool installation receipt.');
+    const ready = await readJson(join(root, 'ready.json'));
+    const binding = (v) => { const { selectedAt, uninstalledAt, ...rest } = v; return rest; };
+    if (!ready || digest(binding(ready)) !== digest(binding(selected)))
+        fail('binding', 'Managed tool receipt differs from its verified installation.');
+    if (await treeFingerprint(root) !== selected.fingerprint)
+        fail('binding', 'Managed tool code differs from its verified installation.');
+}
+/** Standard archive-based tools supply layout and a real probe; exceptional tools reuse the stage primitives. */
+export class ToolInstaller {
+    c;
+    descriptor;
+    directory;
+    root;
+    cache;
+    constructor(c, descriptor) {
+        this.c = c;
+        this.descriptor = descriptor;
+        this.directory = c.appArguments.AppDataDirectory;
+        this.root = toolRoot(this.directory, descriptor.id);
+        this.cache = join(this.directory, 'runtime/cache');
+    }
+    async receipt() { return readJson(join(this.root, 'selection.json')); }
+    async status() {
+        const selected = await this.receipt();
+        let present = false;
+        if (selected && !selected.uninstalledAt)
+            try {
+                present = (await stat(selected.executable)).isFile() && (selected.mode === 'external' || Boolean(await readJson(join(this.root, 'installations', selected.id, 'ready.json'))));
+            }
+            catch (e) {
+                if (e.code !== 'ENOENT')
+                    throw e;
+            }
+        const stages = await readdir(join(this.root, 'stages')).catch(e => { if (e.code === 'ENOENT')
+            return []; throw e; });
+        const processes = (await listProcesses(this.directory, { tool: this.descriptor.id })).filter(r => !['exited', 'failed'].includes(r.state));
+        return { retainedStages: stages.slice(0, 100), processes, tool: this.descriptor.id, state: present ? 'installed' : 'not_ready', mode: selected?.mode ?? 'unconfigured', installation: selected?.id, executable: selected?.executable, components: selected?.components ?? {}, lastProbe: selected?.lastProbe, recommended: 'managed' };
+    }
+    async download(offline = false, vendorDirect = false) {
+        const items = [];
+        for (const [component, a] of Object.entries(this.descriptor.components()))
+            items.push({ component, path: await cacheArtifact(a, this.cache, this.c.fetch, this.c.signal, offline, vendorDirect), sha256: a.sha256, license: a.license, url: a.url, delivery: a.delivery ?? { kind: 'owned-release' } });
+        return { tool: this.descriptor.id, state: 'downloaded', items };
+    }
+    async install(o) {
+        return withToolLock(this.directory, this.descriptor.id, async () => {
+            await assertUnused(this.directory, this.descriptor.id);
+            if (o.executable && o.archive)
+                fail('invalid', 'Choose --executable or --archive.');
+            const external = o.executable ? resolve(this.c.cwd, text(o.executable, 4096)) : undefined, parts = external ? {} : this.descriptor.components(), consumed = {};
+            for (const [id, artifact] of Object.entries(parts)) {
+                const key = id === this.descriptor.primary ? 'archive' : id + 'Archive', checksum = id === this.descriptor.primary ? 'archiveSha256' : id + 'ArchiveSha256';
+                if (o[checksum] && !o[key])
+                    fail('invalid', 'Archive checksum requires its archive path.');
+                consumed[id] = o[key] ? await consumeArchive(resolve(this.c.cwd, text(o[key], 4096)), this.cache, artifact, o[checksum] === undefined ? undefined : text(o[checksum], 64), this.c.signal) : { path: await cacheArtifact(artifact, this.cache, this.c.fetch, this.c.signal, Boolean(o.offline), Boolean(o.vendorDirect)), artifact };
+            }
+            const components = Object.fromEntries(Object.entries(consumed).map(([id, v]) => [id, v.artifact.sha256]));
+            const externalDigest = external ? await fileSha256(external, this.c.signal) : undefined;
+            const externalInputs = external && this.descriptor.externalInputs ? await this.descriptor.externalInputs(external, this.c) : undefined;
+            const noticeDigest = this.descriptor.noticeFiles ? digest(this.descriptor.noticeFiles) : undefined;
+            const id = digest({ tool: this.descriptor.id, schema: 1, platform: process.platform, architecture: process.arch, external, externalDigest, components, ...(externalInputs ? { externalInputs } : {}), ...(noticeDigest ? { noticeDigest } : {}), ...(this.descriptor.preparationId ? { preparationId: this.descriptor.preparationId } : {}) });
+            const rootsAt = (directory) => Object.fromEntries(Object.entries(consumed).map(([part, v]) => { archiveName(v.artifact.root); return [part, join(directory, part, v.artifact.root)]; }));
+            const selected = await installationStage(this.root, id, async (stage, installed) => {
+                for (const [part, v] of Object.entries(consumed))
+                    await extractArchive(v.path, join(stage, part), v.artifact.format, this.c.signal);
+                if (!external)
+                    await this.descriptor.prepare?.(rootsAt(stage), this.c);
+                const execution = external ? await this.descriptor.prepareExternal?.(external, stage, this.c) : undefined;
+                if (execution && !resolve(execution.executable).startsWith(resolve(stage) + sep))
+                    fail('binding', 'Prepared external execution must use owned staging.');
+                for (const [name, body] of Object.entries(this.descriptor.noticeFiles ?? {})) {
+                    archiveName(name);
+                    if (!name || Buffer.byteLength(body) > 1024 ** 2)
+                        fail('configuration', 'Invalid bundled license notice.');
+                    const destination = join(stage, name);
+                    await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+                    await writeFile(destination, body, { flag: 'wx', mode: 0o600 });
+                }
+                const stageLaunch = external ? { executable: external, arguments: [], environment: {} } : this.descriptor.launch(rootsAt(stage));
+                const lastProbe = await this.descriptor.probe(execution ?? stageLaunch, this.c), launch = external ? stageLaunch : this.descriptor.launch(rootsAt(installed));
+                const fingerprint = external ? await fileSha256(external, this.c.signal) : await treeFingerprint(stage);
+                if (external && fingerprint !== externalDigest)
+                    fail('binding', 'External tool changed during installation.');
+                if (externalInputs && digest(await this.descriptor.externalInputs(external, this.c)) !== digest(externalInputs))
+                    fail('binding', 'External tool family changed during installation.');
+                const installedExecution = execution ? { ...execution, executable: join(installed, execution.executable.slice(stage.length + 1)) } : undefined;
+                return { schema: 1, tool: this.descriptor.id, id, mode: external ? 'external' : 'managed', root: installed, ...launch, roots: rootsAt(installed), components, fingerprint, lastProbe, ...(externalInputs ? { externalInputs } : {}), ...(noticeDigest ? { noticeDigest } : {}), ...(installedExecution ? { execution: installedExecution, executionFingerprint: await treeFingerprint(stage) } : {}), selectedAt: new Date().toISOString() };
+            }, value => this.verify(value), this.c.signal);
+            await atomicWrite(join(this.root, 'selection.json'), { ...selected, selectedAt: new Date().toISOString() });
+            return { tool: this.descriptor.id, state: 'installed', mode: selected.mode, installation: id, executable: selected.executable, components, checks: selected.lastProbe };
+        }, this.c.signal);
+    }
+    async verify(selected) {
+        if (selected.schema !== 1 || selected.tool !== this.descriptor.id || !/^[a-f0-9]{64}$/.test(selected.id))
+            fail('binding', 'Invalid tool installation receipt.');
+        const root = join(this.root, 'installations', selected.id);
+        if (selected.root !== root || selected.mode === 'managed' && !resolve(selected.executable).startsWith(resolve(root) + sep))
+            fail('binding', 'Selected tool points outside its owned installation.');
+        const ready = await readJson(join(root, 'ready.json'));
+        const binding = (v) => { const { selectedAt, uninstalledAt, ...rest } = v; return rest; };
+        if (!ready || digest(binding(ready)) !== digest(binding(selected)))
+            fail('binding', 'Selected tool receipt differs from its verified installation.');
+        if (this.descriptor.noticeFiles) {
+            if (selected.noticeDigest !== digest(this.descriptor.noticeFiles))
+                fail('binding', 'Bundled license notices changed; reinstall the selected tool.');
+            for (const [name, body] of Object.entries(this.descriptor.noticeFiles)) {
+                archiveName(name);
+                try {
+                    if (await readFile(join(root, name), 'utf8') !== body)
+                        fail('binding', 'Installed license notice differs from its retained text.');
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        fail('binding', 'Installed license notice is missing.');
+                    throw error;
+                }
+            }
+        }
+        if (selected.mode === 'managed')
+            await verifyManagedInstallation(this.directory, this.descriptor.id, selected);
+        else if (await fileSha256(selected.executable, this.c.signal) !== selected.fingerprint)
+            fail('binding', 'Selected tool code differs from its verified installation.');
+        if (selected.execution && (!resolve(selected.execution.executable).startsWith(resolve(root) + sep) || await treeFingerprint(root) !== selected.executionFingerprint))
+            fail('binding', 'Owned external-tool execution copy differs from its verified installation.');
+        if (selected.mode === 'external' && this.descriptor.externalInputs && (!selected.externalInputs || digest(await this.descriptor.externalInputs(selected.executable, this.c)) !== digest(selected.externalInputs)))
+            fail('binding', 'External tool family differs from its verified installation.');
+    }
+    async use(action) {
+        const lease = await withToolUse(this.directory, this.descriptor.id, () => this.selected(), this.c.signal);
+        try {
+            return await action({ ...lease.value, ...lease.value.execution });
+        }
+        finally {
+            lease.release();
+        }
+    }
+    async selected() {
+        const selected = await this.receipt();
+        if (!selected || selected.uninstalledAt)
+            fail('configuration', 'Tool is not installed; run insight-cli ' + this.descriptor.id + ' install.');
+        await this.verify(selected);
+        return selected;
+    }
+    async doctor() {
+        return withToolLock(this.directory, this.descriptor.id, async () => {
+            const selected = await this.selected(), checks = await this.descriptor.probe(selected.execution ?? selected, this.c);
+            await atomicWrite(join(this.root, 'last-check.json'), { fingerprint: selected.fingerprint, checkedAt: new Date().toISOString(), checks });
+            return { tool: this.descriptor.id, state: 'verified', installation: selected.id, checks };
+        }, this.c.signal);
+    }
+    async uninstall(purgeCache = false) {
+        return withToolLock(this.directory, this.descriptor.id, async () => {
+            await assertUnused(this.directory, this.descriptor.id);
+            const selected = await this.receipt();
+            if (!selected)
+                fail('configuration', 'No selected tool installation exists.');
+            await removeInstallation(this.root, selected.id);
+            if (purgeCache)
+                for (const sha of Object.values(selected.components)) {
+                    if (!/^[a-f0-9]{64}$/.test(sha))
+                        fail('binding', 'Invalid component digest.');
+                    for (const extension of ['zip', 'tgz'])
+                        await rm(join(this.cache, sha + '.' + extension), { force: true });
+                }
+            await atomicWrite(join(this.root, 'selection.json'), { ...selected, uninstalledAt: new Date().toISOString() });
+            return { tool: this.descriptor.id, state: 'uninstalled', externalInstallationPreserved: selected.mode === 'external', researchPreserved: true, materialsPreserved: true };
+        }, this.c.signal);
+    }
+}

package/dist/src/tool-runtime/java-arguments.d.ts

@@ -0,0 +1,6 @@
+/** The Windows java launcher uses ACP, while Java 21 javac reads UTF-8 @files. */
+export declare function encodeJavaLauncherFile(value: string): Promise<Buffer>;
+/** Java's quoted argument-file grammar (not JSON: it has no \u escapes). */
+export declare function quoteJavaArgument(value: string): string;
+/** Keep all other argv entries in place, including JVM flags and application arguments. */
+export declare function javaClasspathArguments(root: string, tool: string, executable: string, args: string[], platform?: string): Promise<string[]>;

package/dist/src/tool-runtime/java-arguments.js

@@ -0,0 +1,44 @@
+import { writeFile } from 'node:fs/promises';
+import { join, win32 } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+/** The Windows java launcher uses ACP, while Java 21 javac reads UTF-8 @files. */
+export async function encodeJavaLauncherFile(value) {
+    if (!/[^\x00-\x7f]/.test(value))
+        return Buffer.from(value, 'ascii');
+    // Fixed script; text travels over stdin, never through PowerShell's command parser.
+    // Match the native launcher without silently replacing unmappable path characters.
+    const script = '[Console]::InputEncoding=[Text.UTF8Encoding]::new($false,$true);$s=[Console]::In.ReadToEnd();$e=[Text.Encoding]::GetEncoding([Text.Encoding]::Default.CodePage,[Text.EncoderExceptionFallback]::new(),[Text.DecoderExceptionFallback]::new());[Console]::Out.Write([Convert]::ToBase64String($e.GetBytes($s)))';
+    const pending = exec(join(process.env.SystemRoot ?? 'C:\\Windows', 'System32/WindowsPowerShell/v1.0/powershell.exe'), ['-NoProfile', '-NonInteractive', '-Command', script], { windowsHide: true, timeout: 15000, maxBuffer: Math.max(4096, Buffer.byteLength(value) * 4) });
+    pending.child.stdin?.on('error', () => { });
+    pending.child.stdin?.end(value, 'utf8');
+    try {
+        return Buffer.from((await pending).stdout.trim(), 'base64');
+    }
+    catch {
+        throw new Error('Java classpath cannot be encoded for the Windows launcher; no process was started. Inspect the retained run and the JDK system-code-page path restrictions.');
+    }
+}
+/** Java's quoted argument-file grammar (not JSON: it has no \u escapes). */
+export function quoteJavaArgument(value) {
+    if (value.includes('\0'))
+        throw new Error('Java argument contains NUL');
+    return '"' + value.replace(/[\\"\n\r\t\f]/g, c => ({ '\\': '\\\\', '"': '\\"', '\n': '\\n', '\r': '\\r', '\t': '\\t', '\f': '\\f' }[c])) + '"';
+}
+/** Keep all other argv entries in place, including JVM flags and application arguments. */
+export async function javaClasspathArguments(root, tool, executable, args, platform = process.platform) {
+    if (platform !== 'win32' || tool !== 'ghidra' || !/^(java|javac)\.exe$/i.test(win32.basename(executable)))
+        return args;
+    // Conservative upper bound for Windows quoting, with room below CreateProcess's 32767 limit.
+    if (executable.length * 2 + args.reduce((n, arg) => n + arg.length * 2 + 3, 3) <= 28000)
+        return args;
+    const index = args.findIndex(arg => arg === '-cp' || arg === '-classpath' || arg === '--class-path');
+    if (index < 0 || args[index + 1] === undefined)
+        return args;
+    const path = join(root, 'java-classpath.args');
+    const content = '-classpath\n' + quoteJavaArgument(args[index + 1]) + '\n';
+    const bytes = /^java\.exe$/i.test(win32.basename(executable)) && process.platform === 'win32' ? await encodeJavaLauncherFile(content) : Buffer.from(content, 'utf8');
+    await writeFile(path, bytes, { flag: 'wx', mode: 0o600 });
+    return [...args.slice(0, index), '@' + path, ...args.slice(index + 2)];
+}

package/dist/src/tool-runtime/launch-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tool-runtime/launch-worker.js

@@ -0,0 +1,58 @@
+/** Internal POSIX exec gate, not a daemon. The record exists before the requested executable runs. */
+import { createReadStream } from 'node:fs';
+import { realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { atomicWrite, readJson } from './store.js';
+import { processIdentity } from './identity.js';
+async function main() {
+    const [directory, id, fd] = process.argv.slice(2);
+    if (!directory || !id || !/^[a-f0-9-]{36}$/.test(id))
+        throw Error('Invalid launch identity');
+    const root = await realpath(directory), path = join(root, 'runtime/processes', id + '.json');
+    const record = await readJson(path);
+    if (!record || record.id !== id || record.pid || record.ownerPid !== process.ppid)
+        throw Error('Launch owner changed');
+    let input = '';
+    for await (const b of createReadStream('', { fd: Number(fd), autoClose: true })) {
+        input += b.toString();
+        if (input.length > 4 * 1024 ** 2)
+            throw Error('Launch input exceeds its bound');
+    }
+    if (await realpath(String(record.root)) !== join(root, 'runtime/runs', id))
+        throw Error('Launch storage changed');
+    const plan = JSON.parse(input);
+    if (plan.executable !== record.executable)
+        throw Error('Launch executable changed');
+    const identity = await processIdentity(process.pid);
+    if (!identity)
+        throw Error('Launch process identity unavailable');
+    Object.assign(record, { pid: process.pid, identity: identity.birth, strongIdentity: identity.strong, processGroup: identity.group, phase: 'armed' });
+    await atomicWrite(path, record);
+    await atomicWrite(join(String(record.root), 'armed.json'), { pid: process.pid, nonce: plan.nonce });
+    for (let i = 0; i < 400; i++) {
+        const grant = await readJson(join(String(record.root), 'go.json'));
+        if (grant?.nonce === plan.nonce) {
+            try {
+                process.execve(plan.executable, [plan.executable, ...plan.arguments], plan.environment);
+            }
+            catch (error) {
+                Object.assign(record, { state: 'failed', phase: 'exec_failed', launchError: error.code ?? 'exec', endedAt: new Date().toISOString() });
+                await atomicWrite(path, record);
+                throw Error('Owned executable could not start');
+            }
+        }
+        try {
+            process.kill(Number(record.ownerPid), 0);
+        }
+        catch {
+            Object.assign(record, { state: 'failed', phase: 'owner_lost_before_exec' });
+            await atomicWrite(path, record);
+            return;
+        }
+        await delay(25);
+    }
+    Object.assign(record, { state: 'failed', phase: 'launch_grant_timeout' });
+    await atomicWrite(path, record);
+}
+await main().catch(() => { process.stderr.write('Owned tool launch gate failed.\n'); process.exitCode = 1; });