@eyeauras/insight-cli 0.1.0 → 0.2.1

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

@@ -0,0 +1,194 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream, constants } from 'node:fs';
+import { mkdir, open, rename, rm, lstat } 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, signal) { const hash = createHash('sha256'); for await (const chunk of createReadStream(path, { signal }))
+    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, signal) {
+    signal?.throwIfAborted();
+    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 readTar(file, tar.t({ 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;
+                }
+            } }), 'end', signal);
+        if (unsafe)
+            throw unsafe;
+        await readTar(file, tar.x({ cwd: destination, strict: true, preserveOwner: false, noChmod: false }), 'close', signal);
+        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 () => {
+                signal?.throwIfAborted();
+                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 }), { signal });
+                }
+                archive.readEntry();
+            })().catch(failed);
+        });
+        archive.readEntry();
+    });
+}
+export async function cacheArtifact(artifact, cache, fetcher, signal, offline = false, vendorDirect = false) {
+    signal.throwIfAborted();
+    await mkdir(cache, { recursive: true, mode: 0o700 });
+    const path = join(cache, artifact.sha256 + '.' + artifact.format);
+    try {
+        const cached = await lstat(path);
+        if (cached.isFile() && (artifact.size === undefined || cached.size === artifact.size) && await fileSha256(path, signal) === 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 the tool download command before using --offline.', { artifact: artifact.name, sha256: artifact.sha256 });
+    if (artifact.delivery?.kind === 'vendor-direct' && !vendorDirect)
+        fail('configuration', 'This non-redistributable runtime requires explicit vendor download; use --vendor-direct or supply a local archive.', { artifact: artifact.name, publisher: artifact.delivery.publisher, termsUrl: artifact.delivery.termsUrl });
+    const temporary = path + '.partial-' + randomUUID();
+    try {
+        const response = await fetcher(artifact.url, { signal, cache: 'no-store' });
+        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) {
+                signal.throwIfAborted();
+                if ((size += chunk.byteLength) > (artifact.size ?? 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 (artifact.size !== undefined && size !== artifact.size)
+            fail('binding', 'Downloaded runtime archive has an unexpected size.');
+        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 });
+    }
+}
+/** tar streams expose their own abort instead of Node's AbortSignal option. */
+async function readTar(file, parser, event, signal) {
+    signal?.throwIfAborted();
+    const input = createReadStream(file, { signal });
+    await new Promise((ok, bad) => {
+        let settled = false;
+        const failed = (error) => { if (settled)
+            return; settled = true; input.unpipe(); input.destroy(); parser.abort(error); bad(error); };
+        parser.on('error', failed);
+        input.on('error', failed);
+        parser.once(event, () => { if (!settled) {
+            settled = true;
+            ok();
+        } });
+        input.pipe(parser);
+    });
+}
+/** Consume local input once; extraction never races later edits to the caller's archive. */
+export async function consumeArchive(path, cache, artifact, checksum, signal) {
+    const { realpath, stat } = await import('node:fs/promises');
+    const source = await realpath(path), input = await open(source, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)), temporary = join(cache, 'local.partial-' + randomUUID());
+    try {
+        const metadata = await input.stat();
+        if (!metadata.isFile() || metadata.size > 2 * 1024 ** 3)
+            fail('invalid', 'Local runtime archive must be a regular file below two GiB.');
+        await mkdir(cache, { recursive: true, mode: 0o700 });
+        let size = 0;
+        const file = await open(temporary, 'wx', 0o600), hash = createHash('sha256');
+        try {
+            for await (const b of input.createReadStream({ signal, autoClose: false })) {
+                size += b.length;
+                if (size > 2 * 1024 ** 3)
+                    fail('limit', 'Local archive grew beyond two GiB.');
+                hash.update(b);
+                await file.writeFile(b);
+            }
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        const sha256 = hash.digest('hex');
+        if (checksum !== undefined && checksum.toLowerCase() !== sha256)
+            fail('binding', 'Local runtime archive differs from its expected SHA256.');
+        const handle = await open(temporary, 'r'), magic = Buffer.alloc(2);
+        try {
+            await handle.read(magic, 0, 2, 0);
+        }
+        finally {
+            await handle.close();
+        }
+        const format = magic.toString('hex') === '504b' ? 'zip' : 'tgz', owned = join(cache, sha256 + '.' + format);
+        try {
+            if (await fileSha256(owned) !== sha256)
+                fail('binding', 'Existing local-archive cache is corrupt.');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+            await rename(temporary, owned);
+        }
+        return { path: owned, artifact: { ...artifact, sha256, size, format } };
+    }
+    finally {
+        await input.close();
+        await rm(temporary, { force: true });
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { ToolArtifact } from './definition.js';
+/** Expected bytes come from the installed package, never a replaceable remote manifest. */
+export declare function catalogArtifact(sha256: string): ToolArtifact;

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

@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs';
+import { fail } from '../model.js';
+const catalog = JSON.parse(readFileSync(new URL('../../../runtime/tool-catalog.json', import.meta.url), 'utf8'));
+/** Expected bytes come from the installed package, never a replaceable remote manifest. */
+export function catalogArtifact(sha256) {
+    const a = catalog[sha256];
+    const dnspy = a?.url === 'https://github.com/dnSpyEx/dnSpy/releases/download/v6.6.0/dnSpy-net-win64.zip' && a.sha256 === '8ed48f165dc355e869f3a0037ad4f9216147f995a5ae0258b296eeef1f73aab0' && a.delivery?.publisher === 'dnSpyEx' && a.delivery.termsUrl === 'https://visualstudio.microsoft.com/license-terms/mlt552233/';
+    const microsoft = a?.delivery?.publisher === 'Microsoft' && new URL(a.delivery.termsUrl).hostname === 'learn.microsoft.com' && new URL(a.delivery.termsUrl).protocol === 'https:' && new URL(a.url).protocol === 'https:' && ['download.sysinternals.com', 'windbg.download.prss.microsoft.com'].includes(new URL(a.url).hostname);
+    const vendor = a?.delivery?.kind === 'vendor-direct' && Boolean(a.delivery.reason) && (dnspy || microsoft);
+    if (!a || a.sha256 !== sha256 || !(a.url.startsWith('https://github.com/iXab3r/insight-cli/releases/download/tool-') || vendor) || !Number.isSafeInteger(a.size) || a.size < 1)
+        fail('binding', 'Pinned tool distribution is absent or invalid in the retained catalog.');
+    return { ...a };
+}

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

@@ -0,0 +1,9 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { type ProcessRecord } from './supervisor.js';
+export interface ToolProcessHooks {
+    discover?: (c: CommandContext) => Promise<void>;
+    verify?: (record: ProcessRecord, c: CommandContext) => Promise<boolean | undefined>;
+    stop?: (record: ProcessRecord, c: CommandContext) => Promise<void>;
+    beforeKill?: (record: ProcessRecord, c: CommandContext) => Promise<void>;
+}
+export declare function toolProcessCommands(hooks?: Record<string, ToolProcessHooks>, metadata?: readonly CommandDefinition[]): CommandDefinition[];

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

@@ -0,0 +1,39 @@
+import { command, Permission, CliError } from '@eyeauras/cli-factory';
+import { listProcesses, processStatus, terminateProcess } from './supervisor.js';
+import { text } from '../model.js';
+const number = (value, max, min = 0) => { const n = Number(value); if (!Number.isSafeInteger(n) || n < min || n > max)
+    throw new CliError('Invalid process page bound.', { code: 'tool.input' }); return n; };
+export function toolProcessCommands(hooks = {}, metadata = []) {
+    const verifier = (c) => (record) => hooks[record.tool]?.verify?.(record, c) ?? Promise.resolve(undefined);
+    const discover = async (c) => { for (const h of Object.values(hooks))
+        await h.discover?.(c); };
+    const processes = {
+        name: 'processes', description: 'List owned tool processes; inspect or stop one recorded execution', permission: Permission.ReadOnly,
+        options: [{ flags: '--tool <name>', description: 'Filter by tool' }, { flags: '--session <id>', description: 'Filter by research session' }, { flags: '--target <id>', description: 'Filter by input target' },
+            { flags: '--all', description: 'Include completed and failed executions' }, { flags: '--limit <count>', description: 'Maximum records in this page', defaultValue: 50, parse: v => number(v, 1000, 1) },
+            { flags: '--offset <count>', description: 'Skip records before this page', defaultValue: 0, parse: v => number(v, 2147483647) }],
+        async run({ options: o }, c) {
+            await discover(c);
+            let items = await listProcesses(c.appArguments.AppDataDirectory, { tool: o.tool === undefined ? undefined : text(o.tool, 64), session: o.session === undefined ? undefined : text(o.session, 128), target: o.target === undefined ? undefined : text(o.target, 128) }, verifier(c));
+            if (!o.all)
+                items = items.filter(r => !['exited', 'failed'].includes(r.state));
+            const limit = number(o.limit, 1000, 1), offset = number(o.offset, 2147483647);
+            return { items: items.slice(offset, offset + limit), total: items.length, limit, offset, truncated: items.length > offset + limit };
+        },
+        children: [
+            command('show <process>', 'Inspect a recorded execution and its diagnostic paths', async ({ args }, c) => { await discover(c); return processStatus(c.appArguments.AppDataDirectory, text(args.process, 64), verifier(c)); }, { permission: Permission.ReadOnly }),
+            command('stop <process>', 'Request tool-aware graceful shutdown of an owned process', async ({ args }, c) => {
+                await discover(c);
+                return terminateProcess(c.appArguments.AppDataDirectory, text(args.process, 64), false, verifier(c), r => hooks[r.tool]?.stop?.(r, c) ?? Promise.resolve());
+            }, { permission: Permission.Update }),
+            command('kill <process>', 'Force termination of a verified owned process; preserve uncertain work', async ({ args }, c) => {
+                await discover(c);
+                const id = text(args.process, 64), r = await processStatus(c.appArguments.AppDataDirectory, id, verifier(c));
+                if (r.state === 'running')
+                    await hooks[r.tool]?.beforeKill?.(r, c);
+                return terminateProcess(c.appArguments.AppDataDirectory, id, true, verifier(c));
+            }, { permission: 'Destructive' }),
+        ],
+    };
+    return [command('tools', 'Inspect research tools and executions', [...metadata, processes])];
+}

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

@@ -0,0 +1,11 @@
+/** For reviewed native helper execs started inside an adapter worker, never an external target. */
+export declare function inheritedDeadlineEnvironment(deadlineUnixSeconds: number, receipts: string): Promise<{
+    DYLD_INSERT_LIBRARIES: string;
+    INSIGHT_NATIVE_DEADLINE_UNIX_SECONDS: string;
+    INSIGHT_NATIVE_DEADLINE_RECEIPTS: string;
+}>;
+/** Internal, first-party exec helper. No service or timer in the owner is needed after exec. */
+export declare function deadlineLaunch(executable: string, args: string[], timeoutMs: number): Promise<{
+    executable: string;
+    arguments: string[];
+}>;

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

@@ -0,0 +1,32 @@
+import { fileURLToPath } from 'node:url';
+import { CliError } from '@eyeauras/cli-factory';
+import { fileSha256 } from './archives.js';
+import { isAbsolute } from 'node:path';
+/** For reviewed native helper execs started inside an adapter worker, never an external target. */
+export async function inheritedDeadlineEnvironment(deadlineUnixSeconds, receipts) {
+    if (process.platform !== 'darwin' || process.arch !== 'arm64' || !Number.isInteger(deadlineUnixSeconds) || deadlineUnixSeconds <= Date.now() / 1000 || deadlineUnixSeconds > Date.now() / 1000 + 600 || !isAbsolute(receipts))
+        throw new CliError('Invalid inherited native deadline.', { code: 'tool.configuration' });
+    const library = fileURLToPath(new URL('../../../runtime/native/deadline-alarm-darwin-universal.dylib', import.meta.url));
+    if (library.includes(':') || await fileSha256(library) !== 'cd5ebd65aa419b79cb327f2ae872f98f3fd222b93049c909e409776eab65b8ef')
+        throw new CliError('Inherited deadline library differs from its reviewed build or has an unsupported loader path.', { code: 'tool.binding' });
+    return { DYLD_INSERT_LIBRARIES: library, INSIGHT_NATIVE_DEADLINE_UNIX_SECONDS: String(deadlineUnixSeconds), INSIGHT_NATIVE_DEADLINE_RECEIPTS: receipts };
+}
+/** Internal, first-party exec helper. No service or timer in the owner is needed after exec. */
+export async function deadlineLaunch(executable, args, timeoutMs) {
+    if (process.platform === 'linux' && process.arch === 'x64') {
+        if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000)
+            throw new CliError('Native deadline must be 1–600 seconds.', { code: 'tool.configuration' });
+        const helper = fileURLToPath(new URL('../../../runtime/native/child-deadline-linux-x64', import.meta.url));
+        if (await fileSha256(helper) !== 'e070e2de9a21aea78f224062877cdc0264be11229af314d3b88ff3b6bd77e26f')
+            throw new CliError('Packaged Linux launcher differs from its reviewed build.', { code: 'tool.binding' });
+        return { executable: helper, arguments: [String(Math.ceil(timeoutMs / 1000)), String(process.pid), executable, ...args] };
+    }
+    if (process.platform !== 'darwin' || process.arch !== 'arm64')
+        throw new CliError('A packaged native deadline is unavailable on this host.', { code: 'tool.unsupported' });
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000)
+        throw new CliError('Native deadline must be between one and 600 seconds.', { code: 'tool.configuration' });
+    const helper = fileURLToPath(new URL('../../../runtime/native/deadline-exec-darwin-arm64', import.meta.url));
+    if (await fileSha256(helper) !== '32c146075d1c83422b068eeedd4a244d5e30cb768b279b185756c5d3b8008d88')
+        throw new CliError('Packaged native deadline differs from its reviewed build.', { code: 'tool.binding' });
+    return { executable: helper, arguments: [String(Math.ceil(timeoutMs / 1000)), '--', executable, ...args] };
+}

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