@eyeauras/insight-cli 0.0.0-stage → 0.2.0

package/dist/src/arguments.d.ts

@@ -0,0 +1,14 @@
+import type { OptionDefinition } from '@eyeauras/cli-factory';
+export interface Parameter {
+    name: string;
+    type: string;
+    required: boolean;
+    default?: string;
+    semantic?: string;
+    allowEmpty?: boolean;
+}
+export declare const key: (name: string) => string;
+export declare const flag: (name: string) => string;
+export declare function parsed(p: Parameter, value: unknown): unknown;
+export declare const selectedOptions: OptionDefinition[];
+export declare function option(p: Parameter): OptionDefinition;

package/dist/src/arguments.js

@@ -0,0 +1,62 @@
+import { address } from './research.js';
+import { fail } from './model.js';
+import { parseDomainJson } from './json.js';
+export const key = (name) => name.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+export const flag = (name) => name.replaceAll('_', '-');
+export function parsed(p, value) {
+    if (p.type === 'boolean') {
+        if (value === true || value === 'true')
+            return true;
+        if (value === false || value === 'false')
+            return false;
+        fail('invalid', `${flag(p.name)} must be true or false.`);
+    }
+    if (p.type === 'integer' || p.type === 'number') {
+        if (typeof value !== 'string' && typeof value !== 'number' || typeof value === 'string' && !/^-?\d+(?:\.\d+)?$/.test(value))
+            fail('invalid', `${flag(p.name)} must be a finite ${p.type}.`);
+        const result = Number(value);
+        if (!Number.isFinite(result) || p.type === 'integer' && !Number.isSafeInteger(result))
+            fail('invalid', `${flag(p.name)} is outside numeric range.`);
+        if (p.name === 'offset' && p.default !== '-1' && result < 0 || p.name === 'limit' && (result < 1 || result > 1000) ||
+            p.name === 'length' && (result < (p.default === '0' ? 0 : 1) || result > 65536) || p.name === 'max_steps' && (result < 1 || result > 1000000) ||
+            /^(max_steps|max_functions|num_examples|context_instructions|call_context_limit|call_context_lines|depth)$/.test(p.name) && result < 0)
+            fail('invalid', `${flag(p.name)} is outside its supported query range.`);
+        if (p.name === 'timeout_seconds' && (result < 1 || result > 1800))
+            fail('invalid', 'timeout-seconds must be between 1 and 1800.');
+        if (p.name === 'max_scan' && (result < 1 || result > 200000) || p.name === 'max_bytes' && (result < 1 || result > 16777216))
+            fail('invalid', `${flag(p.name)} is outside its supported work budget.`);
+        return result;
+    }
+    if (['json', 'object', 'array', 'any'].includes(p.type)) {
+        let result = value;
+        if (typeof value === 'string') {
+            if (value.length > 65536)
+                fail('limit', 'JSON input exceeds 64 KiB.');
+            try {
+                result = parseDomainJson(value);
+            }
+            catch {
+                fail('invalid', `${flag(p.name)} requires valid JSON.`);
+            }
+        }
+        if (p.type === 'object' && (!result || Array.isArray(result) || typeof result !== 'object') || p.type === 'array' && !Array.isArray(result))
+            fail('invalid', `${flag(p.name)} has the wrong JSON shape.`);
+        if (JSON.stringify(result).length > 65536)
+            fail('limit', 'JSON input exceeds 64 KiB.');
+        return result;
+    }
+    if (typeof value !== 'string' || value.length > 16000 || value.includes('\0') || !value && p.required && !p.allowEmpty)
+        fail('invalid', `${flag(p.name)} needs bounded text.`);
+    return p.semantic === 'address' ? address(value) : value;
+}
+export const selectedOptions = [{ flags: '--session <id>', description: 'Select the durable research session', required: true },
+    { flags: '--target <id>', description: 'Select the immutable input target', required: true }];
+export function option(p) {
+    const value = p.default;
+    const defaultValue = value === undefined || value === '' && !p.allowEmpty ? undefined : parsed(p, value);
+    return { flags: `--${flag(p.name)} <${p.type === 'json' ? 'json' : p.type}>`,
+        description: p.semantic === 'function_ref' ? 'Function name or explicit address' : p.semantic === 'address' ? 'Explicit hexadecimal address' :
+            `${flag(p.name)} (${p.type}${p.name === 'limit' ? ', 1–1000' : p.name === 'length' ? ', 1–65536 bytes' : ''})`,
+        ...(p.required ? { required: true } : {}), ...(defaultValue === undefined ? {} : { defaultValue }),
+        ...(['json', 'object', 'array', 'any'].includes(p.type) ? {} : { parse: (value) => parsed(p, value) }) };
+}

package/dist/src/artifacts.d.ts

@@ -0,0 +1,17 @@
+export type ArtifactKind = 'input' | 'snapshot';
+export interface Artifact {
+    id: string;
+    kind: ArtifactKind;
+    sha256: string;
+    size: number;
+}
+/** Immutable, content-addressed copies of the bytes actually consumed by the facade. */
+export declare class Artifacts {
+    readonly directory: string;
+    constructor(directory: string);
+    path(value: Artifact): string;
+    private ownedDirectory;
+    private syncDirectory;
+    verify(value: Artifact): Promise<string>;
+    capture(source: string, kind: ArtifactKind): Promise<Artifact>;
+}

package/dist/src/artifacts.js

@@ -0,0 +1,115 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open, mkdir, link, unlink, realpath, lstat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { fail } from './model.js';
+const maximumBytes = 4 * 1024 * 1024 * 1024;
+/** Immutable, content-addressed copies of the bytes actually consumed by the facade. */
+export class Artifacts {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    path(value) {
+        if (!['input', 'snapshot'].includes(value.kind) || !/^[a-f0-9]{64}$/.test(value.sha256) ||
+            value.id !== `${value.kind}:${value.sha256}` || !Number.isSafeInteger(value.size) ||
+            value.size < 1 || value.size > maximumBytes)
+            fail('artifact', 'Saved artifact reference is malformed.');
+        return join(this.directory, 'artifacts', `${value.sha256}.${value.kind === 'snapshot' ? 'gzf' : 'bin'}`);
+    }
+    async ownedDirectory() {
+        const directory = join(this.directory, 'artifacts');
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        if ((await lstat(directory)).isSymbolicLink() || await realpath(directory) !== resolve(directory))
+            fail('artifact', 'Artifact directory must remain inside its owned profile storage.');
+        return directory;
+    }
+    async syncDirectory(directory) {
+        // Directory fsync is unavailable on Windows. The file itself is synced on all platforms.
+        if (process.platform === 'win32')
+            return;
+        const handle = await open(directory, constants.O_RDONLY);
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async verify(value) {
+        await this.ownedDirectory();
+        const path = this.path(value);
+        if ((await lstat(path)).isSymbolicLink())
+            fail('artifact', 'Saved artifact cannot be replaced by a symbolic link.');
+        const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() || info.size !== value.size)
+                fail('artifact', 'Saved artifact size or type changed.');
+            const hash = createHash('sha256');
+            let size = 0;
+            for await (const chunk of handle.createReadStream({ autoClose: false })) {
+                size += chunk.length;
+                hash.update(chunk);
+                if (size > value.size)
+                    fail('artifact', 'Saved artifact grew during verification.');
+            }
+            if (size !== value.size || hash.digest('hex') !== value.sha256)
+                fail('artifact', 'Saved artifact contents changed; its original copy is required.');
+            return path;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async capture(source, kind) {
+        if (!['input', 'snapshot'].includes(kind))
+            fail('artifact', 'Unsupported artifact kind.');
+        const directory = await this.ownedDirectory();
+        const temporary = join(directory, 'pending-' + randomUUID());
+        const input = await open(source, constants.O_RDONLY);
+        let output;
+        try {
+            const info = await input.stat({ bigint: true });
+            if (!info.isFile() || info.size < 1n || info.size > BigInt(maximumBytes))
+                fail('limit', 'Input must be a nonempty regular file of at most 4 GiB.');
+            output = await open(temporary, 'wx', 0o600);
+            const hash = createHash('sha256');
+            let size = 0;
+            for await (const chunk of input.createReadStream({ autoClose: false })) {
+                size += chunk.length;
+                if (size > maximumBytes)
+                    fail('limit', 'Input exceeds 4 GiB.');
+                hash.update(chunk);
+                await output.writeFile(chunk);
+            }
+            const after = await input.stat({ bigint: true });
+            if (BigInt(size) !== info.size || after.size !== info.size || after.mtimeNs !== info.mtimeNs ||
+                after.ctimeNs !== info.ctimeNs)
+                fail('inputChanged', 'Input changed while being copied; retry against a stable file.');
+            const sha256 = hash.digest('hex');
+            const result = { id: `${kind}:${sha256}`, kind, sha256, size };
+            await output.chmod(0o400);
+            await output.sync();
+            await output.close();
+            output = undefined;
+            // Link publishes without replacing a previous artifact, including a concurrent capture.
+            try {
+                await link(temporary, this.path(result));
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+            await this.verify(result);
+            await this.syncDirectory(directory);
+            return result;
+        }
+        finally {
+            await input.close();
+            await output?.close();
+            await unlink(temporary).catch(error => { if (error.code !== 'ENOENT')
+                throw error; });
+        }
+    }
+}

package/dist/src/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runHosted } from '@eyeauras/cli-factory-ipc';
+import { createDefinition } from './cli.js';
+process.exitCode = await runHosted({ entryPoint: import.meta.url, createDefinition });

package/dist/src/cli.d.ts

@@ -0,0 +1,10 @@
+import { type CliDefinition, type CliRuntime, type CommandContext } from '@eyeauras/cli-factory';
+import { Workspace } from './workspace.js';
+import { type ResearchBackend } from './research.js';
+export interface Options {
+    runtime?: CliRuntime;
+    /** Offline fixture seam; production uses owned native Ghidra contexts. */
+    backend?: (workspace: Workspace, context: CommandContext) => ResearchBackend | Promise<ResearchBackend>;
+}
+export declare function createDefinition(options?: Options): CliDefinition;
+export declare const createInsightCli: (options?: Options) => import("@eyeauras/cli-factory").CliApplication;