@eyeauras/insight-cli 0.0.0-stage → 0.1.0

package/dist/src/saved-materials.d.ts

@@ -0,0 +1,12 @@
+import { type CommandDefinition } from '@eyeauras/cli-factory';
+export interface SavedMaterials {
+    state: 'saved';
+    path: string;
+    kind: 'file' | 'directory';
+    files: number;
+    bytes: number;
+    sha256: string;
+}
+/** Copy user materials without initializing Ghidra, targets, sessions or Workspace. */
+export declare function saveMaterials(appDataDirectory: string, source: string, signal?: AbortSignal): Promise<SavedMaterials>;
+export declare function artifactsCommands(): CommandDefinition[];

package/dist/src/saved-materials.js

@@ -0,0 +1,196 @@
+import { command, CliError, Permission } from '@eyeauras/cli-factory';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, opendir, realpath, rename, rm } from 'node:fs/promises';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+const maximumEntries = 100_000, maximumDepth = 128;
+function fail(code, message) { throw new CliError(message, { code: 'artifacts.' + code }); }
+function check(signal) { if (signal?.aborted)
+    fail('cancelled', 'Saving materials was cancelled; no snapshot was published.'); }
+function inside(parent, child) {
+    const value = relative(parent, child);
+    return value === '' || (!isAbsolute(value) && value !== '..' && !value.startsWith('..' + sep));
+}
+function stamp(info) { return [info.dev, info.ino, info.mode, info.size, info.mtimeNs, info.ctimeNs].join(':'); }
+async function syncDirectory(path) {
+    if (process.platform === 'win32')
+        return;
+    const handle = await open(path, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function inventory(source, signal) {
+    const entries = [];
+    async function visit(path, name, depth) {
+        check(signal);
+        if (depth > maximumDepth || entries.length >= maximumEntries)
+            fail('limit', 'Materials exceed the traversal bound of 100000 entries or 128 directory levels; save a smaller selection.');
+        const info = await lstat(path, { bigint: true });
+        if (!info.isFile() && !info.isDirectory())
+            fail('unsupported', 'Materials must contain only ordinary files and directories; symbolic links and special files are unsupported.');
+        if (info.size > BigInt(Number.MAX_SAFE_INTEGER))
+            fail('limit', 'A materials entry exceeds the supported size counter.');
+        entries.push({ path: name, kind: info.isFile() ? 'file' : 'directory', stamp: stamp(info), size: Number(info.size) });
+        if (info.isDirectory()) {
+            // Sorting by code unit keeps manifest digests independent of locale and enumeration order.
+            const names = [];
+            for await (const child of await opendir(path)) {
+                check(signal);
+                if (names.length + entries.length >= maximumEntries)
+                    fail('limit', 'Materials exceed the traversal bound of 100000 entries; save a smaller selection.');
+                names.push(child.name);
+            }
+            names.sort();
+            for (const child of names)
+                await visit(join(path, child), name ? name + '/' + child : child, depth + 1);
+            if (stamp(await lstat(path, { bigint: true })) !== stamp(info))
+                fail('changed', 'Source changed while saving; save a stable file or directory.');
+        }
+    }
+    await visit(source, '', 0);
+    return entries;
+}
+async function verifyParents(source, entry, entries) {
+    let parent = entry.path ? entry.path.split('/').slice(0, -1).join('/') : undefined;
+    while (parent !== undefined) {
+        const expected = entries.get(parent);
+        if (stamp(await lstat(parent ? join(source, parent) : source, { bigint: true })) !== expected.stamp)
+            fail('changed', 'Source directory changed while saving; no snapshot was published.');
+        parent = parent ? parent.split('/').slice(0, -1).join('/') : undefined;
+    }
+}
+/** Copy user materials without initializing Ghidra, targets, sessions or Workspace. */
+export async function saveMaterials(appDataDirectory, source, signal) {
+    let stage, published;
+    try {
+        check(signal);
+        const sourcePath = resolve(source);
+        // Reject a symbolic source itself before resolving its parents (e.g. macOS /tmp).
+        const info = await lstat(sourcePath, { bigint: true });
+        if (!info.isFile() && !info.isDirectory())
+            fail('unsupported', 'Save an ordinary file or directory; symbolic links and special files are unsupported.');
+        const canonicalSource = await realpath(sourcePath);
+        await mkdir(appDataDirectory, { recursive: true, mode: 0o700 });
+        const appData = await realpath(appDataDirectory), storage = join(appData, 'materials');
+        if (info.isDirectory() && inside(canonicalSource, storage))
+            fail('recursive', 'Source contains the materials storage; choose a source outside its storage ancestry.');
+        await mkdir(storage, { recursive: true, mode: 0o700 });
+        if ((await lstat(storage)).isSymbolicLink() || await realpath(storage) !== storage)
+            fail('storage', 'Materials storage must be an ordinary profile-owned directory.');
+        const entries = await inventory(canonicalSource, signal), byPath = new Map(entries.map(entry => [entry.path, entry]));
+        if (entries[0].stamp !== stamp(info))
+            fail('changed', 'Source changed while preparing its snapshot; save a stable file or directory.');
+        const identity = randomUUID(), candidate = join(storage, '.pending-' + identity);
+        const final = join(storage, identity), content = join(candidate, 'content');
+        await mkdir(candidate, { mode: 0o700 });
+        stage = candidate;
+        await mkdir(content, { mode: 0o700 });
+        const name = basename(canonicalSource) || 'root', output = join(content, name);
+        const manifest = [], directories = [stage, content];
+        let files = 0, bytes = 0, fileDigest;
+        const buffer = Buffer.allocUnsafe(1024 * 1024);
+        for (const entry of entries) {
+            check(signal);
+            await verifyParents(canonicalSource, entry, byPath);
+            const inputPath = entry.path ? join(canonicalSource, entry.path) : canonicalSource;
+            const outputPath = entry.path ? join(output, entry.path) : output;
+            if (entry.kind === 'directory') {
+                await mkdir(outputPath, { mode: 0o700 });
+                directories.push(outputPath);
+                manifest.push({ path: entry.path, kind: 'directory' });
+                continue;
+            }
+            // NONBLOCK avoids a hang if a regular source is exchanged for a FIFO before open.
+            const input = await open(inputPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                const before = await input.stat({ bigint: true });
+                if (!before.isFile() || stamp(before) !== entry.stamp)
+                    fail('changed', 'Source file changed while saving; no snapshot was published.');
+                const destination = await open(outputPath, 'wx', 0o600), hash = createHash('sha256');
+                let copied = 0;
+                try {
+                    while (true) {
+                        check(signal);
+                        const { bytesRead } = await input.read(buffer, 0, buffer.length, copied);
+                        if (!bytesRead)
+                            break;
+                        copied += bytesRead;
+                        if (copied > entry.size)
+                            fail('changed', 'Source file grew while saving; no snapshot was published.');
+                        const chunk = buffer.subarray(0, bytesRead);
+                        hash.update(chunk);
+                        await destination.writeFile(chunk);
+                    }
+                    if (copied !== entry.size || stamp(await input.stat({ bigint: true })) !== entry.stamp ||
+                        stamp(await lstat(inputPath, { bigint: true })) !== entry.stamp)
+                        fail('changed', 'Source file changed while saving; no snapshot was published.');
+                    await destination.sync();
+                }
+                finally {
+                    await destination.close();
+                }
+                const sha256 = hash.digest('hex');
+                manifest.push({ path: entry.path, kind: 'file', bytes: copied, sha256 });
+                fileDigest = sha256;
+                files++;
+                bytes += copied;
+                if (!Number.isSafeInteger(bytes))
+                    fail('limit', 'Materials exceed the supported size counter.');
+            }
+            finally {
+                await input.close();
+            }
+        }
+        // Detect edits to earlier files and directory membership changes during the entire capture.
+        const after = await inventory(canonicalSource, signal);
+        if (JSON.stringify(after) !== JSON.stringify(entries) || await realpath(sourcePath) !== canonicalSource ||
+            stamp(await lstat(sourcePath, { bigint: true })) !== stamp(info))
+            fail('changed', 'Source changed while saving; no snapshot was published.');
+        const manifestBytes = JSON.stringify({ version: 1, entries: manifest }) + '\n';
+        const metadata = await open(join(stage, 'manifest.json'), 'wx', 0o600);
+        try {
+            await metadata.writeFile(manifestBytes);
+            await metadata.sync();
+        }
+        finally {
+            await metadata.close();
+        }
+        for (const directory of directories.reverse())
+            await syncDirectory(directory);
+        check(signal);
+        await rename(stage, final);
+        published = final;
+        stage = undefined;
+        await syncDirectory(storage);
+        return { state: 'saved', path: join(final, 'content', name), kind: entries[0].kind, files, bytes,
+            sha256: entries[0].kind === 'file' ? fileDigest : createHash('sha256').update(manifestBytes).digest('hex') };
+    }
+    catch (error) {
+        let cleanupFailed = false;
+        if (stage)
+            await rm(stage, { recursive: true, force: true }).catch(() => { cleanupFailed = true; });
+        // A directory-sync failure is not acknowledged as a durable save.
+        if (published)
+            await rm(published, { recursive: true, force: true }).catch(() => { cleanupFailed = true; });
+        if (error instanceof CliError) {
+            if (cleanupFailed)
+                throw new CliError(error.message + ' Some owned temporary files could not be removed; preserve the profile for cleanup.', { code: error.code });
+            throw error;
+        }
+        const code = error.code;
+        fail('save', `Could not save materials${code && /^[A-Z0-9_]+$/.test(code) ? ' (' + code + ')' : ''}; no complete snapshot was acknowledged.${cleanupFailed ? ' Some owned temporary files could not be removed; preserve the profile for cleanup.' : ''}`);
+    }
+}
+export function artifactsCommands() {
+    return [command('artifacts', 'Retain ordinary research files independently of analysis tools', [
+            command('save <path>', 'Save a complete independent copy of a file or directory in this profile', ({ args }, context) => {
+                if (typeof args.path !== 'string' || !args.path || args.path.includes('\0'))
+                    fail('invalid', 'Provide one file or directory path.');
+                return saveMaterials(context.appArguments.AppDataDirectory, resolve(context.cwd, args.path), context.signal);
+            }, { permission: Permission.Update }),
+        ])];
+}

package/dist/src/scripts.d.ts

@@ -0,0 +1,19 @@
+export interface ScriptItem {
+    script: string;
+    name: string;
+    language: 'Java' | 'Python';
+    origin: 'installation' | 'context' | 'extension';
+    category?: string;
+}
+export interface ScriptPage {
+    items: ScriptItem[];
+    count: number;
+    total: number;
+    offset: number;
+    limit: number;
+    truncated: boolean;
+}
+/** Resolve only an explicit inventory ID; native search paths never choose another script. */
+export declare function scriptPath(home: string, contextRoot: string, script: string, extensions?: string[]): Promise<string>;
+/** Enumerate configured installation and owned context scripts without exposing native paths. */
+export declare function scriptInventory(home: string, contextRoot: string, filter: string, limit: number, offset: number, extensions?: string[]): Promise<ScriptPage>;

package/dist/src/scripts.js

@@ -0,0 +1,79 @@
+import { readdir, open } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { constants } from 'node:fs';
+import { fail } from './model.js';
+/** Resolve only an explicit inventory ID; native search paths never choose another script. */
+export async function scriptPath(home, contextRoot, script, extensions = []) {
+    if (!/^(installation|context|extension):[^\0]+\.(java|py)$/.test(script) || script.includes('..') || script.includes('\\'))
+        fail('invalid', 'Choose an explicit script ID returned by ghidra scripts list.');
+    const page = await scriptInventory(home, contextRoot, script, 20000, 0, extensions), item = page.items.find(item => item.script === script);
+    if (!item)
+        fail('notFound', 'Script ID is absent from this context and installation.');
+    const part = script.slice(script.indexOf(':') + 1);
+    if (item.origin === 'extension') {
+        const [module, ...rest] = part.split('/'), root = extensions.find(p => p.split(/[\\/]/).pop() === module);
+        if (!root)
+            fail('binding', 'Script module is no longer enabled.');
+        return join(root, 'ghidra_scripts', ...rest);
+    }
+    if (item.origin === 'context')
+        return join(contextRoot, 'ghidra_scripts', part);
+    const segments = part.split('/'), filename = segments.pop();
+    return join(home, 'Ghidra', ...segments, 'ghidra_scripts', filename);
+}
+/** Enumerate configured installation and owned context scripts without exposing native paths. */
+export async function scriptInventory(home, contextRoot, filter, limit, offset, extensions = []) {
+    const items = [];
+    async function scripts(folder, origin, module) {
+        let entries;
+        try {
+            entries = await readdir(folder, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isFile() || !entry.name.endsWith('.java') && !entry.name.endsWith('.py'))
+                continue;
+            if (items.length >= 20000)
+                fail('limit', 'Script inventory exceeds 20000 entries.');
+            const name = entry.name, script = origin + ':' + (module ? module + '/' : '') + name;
+            const handle = await open(join(folder, name), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+            let category;
+            try {
+                const data = Buffer.alloc(4096), read = await handle.read(data, 0, data.length, 0);
+                if (!(await handle.stat()).isFile())
+                    fail('binding', 'Script inventory file changed during inspection.');
+                category = /^\s*(?:\/\/|#)\s*@category\s+([^\r\n]+)/m.exec(data.subarray(0, read.bytesRead).toString('utf8'))?.[1]?.trim().slice(0, 256);
+            }
+            finally {
+                await handle.close();
+            }
+            items.push({ script, name, language: name.endsWith('.java') ? 'Java' : 'Python', origin, ...(category ? { category } : {}) });
+        }
+    }
+    const installed = join(home, 'Ghidra');
+    async function modules(folder, depth) {
+        if (depth > 16)
+            fail('limit', 'Script module nesting exceeds 16 levels.');
+        for (const entry of (await readdir(folder, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory())
+                continue;
+            const path = join(folder, entry.name);
+            if (entry.name === 'ghidra_scripts')
+                await scripts(path, 'installation', relative(installed, folder).split(sep).join('/'));
+            else if (!['data', 'lib', 'os', 'src', 'docs'].includes(entry.name))
+                await modules(path, depth + 1);
+        }
+    }
+    await modules(installed, 0);
+    for (const root of extensions)
+        await scripts(join(root, 'ghidra_scripts'), 'extension', root.split(/[\\/]/).pop());
+    await scripts(join(contextRoot, 'ghidra_scripts'), 'context', '');
+    const matched = items.filter(item => !filter || [item.name, item.script, item.category ?? ''].some(value => value.toLowerCase().includes(filter.toLowerCase())))
+        .sort((a, b) => a.script.localeCompare(b.script));
+    const page = matched.slice(offset, offset + limit);
+    return { items: page, count: page.length, total: matched.length, offset, limit, truncated: offset + page.length < matched.length };
+}

package/dist/src/sdk-contracts.d.ts

@@ -0,0 +1,13 @@
+import type { Parameter } from './arguments.js';
+interface SdkOperation {
+    operation: string;
+    group: string;
+    name: string;
+    description: string;
+    write?: boolean;
+    pair?: boolean;
+    params: Parameter[];
+}
+export declare const sdkOperations: SdkOperation[];
+export declare const sdkWrites: Set<string>;
+export {};

package/dist/src/sdk-contracts.js

@@ -0,0 +1,37 @@
+const str = (name, required = true) => ({ name, type: 'string', required });
+const at = (name = 'address') => ({ ...str(name), semantic: 'address' });
+const json = (name, type = 'object', required = true) => ({ name, type, required });
+const count = (name, value) => ({ name, type: 'integer', required: false, default: value });
+const empty = (name) => ({ ...str(name, false), default: '', allowEmpty: true });
+const bool = (name) => ({ name, type: 'boolean', required: false, default: 'false' });
+const original = [str('name'), at('expect_start'), { ...count('expect_size', '1'), required: true }, str('expect_sha256')];
+export const sdkOperations = [
+    { operation: 'type-layout', group: 'types', name: 'layout', description: 'Read native packing, alignment, bitfields, settings and source archive identity', params: [str('path')] },
+    { operation: 'type-structure', group: 'types', name: 'define-layout', description: 'Create a native structure with packing/alignment/bitfields; replace only an explicitly selected empty placeholder', write: true, params: [str('path'), json('fields', 'array'), { name: 'packing', type: 'integer', required: false, default: '0' }, { name: 'alignment', type: 'integer', required: false, default: '0' }, bool('replace_placeholder')] },
+    { operation: 'type-settings', group: 'types', name: 'set-settings', description: 'Edit default settings by actual native definition names; null clears an explicit setting', write: true, params: [str('path'), json('settings')] },
+    { operation: 'type-archive-import', group: 'types', name: 'archive-import', description: 'Import explicit GDT type paths with archive identity and saved layout verification', write: true, params: [str('input'), json('types', 'array')] },
+    { operation: 'changes', group: 'changes', name: 'compare', description: 'Categorized native ProgramDiff of two saved private contexts; does not merge', pair: true, params: [{ ...json('categories', 'array', false), default: '["bytes","comments","symbols","functions"]' }, count('max_ranges', '100'), count('timeout_seconds', '30')] },
+    { operation: 'block-state', group: 'memory', name: 'block-state', description: 'Read exact block layout and bounded full-content digest', params: [str('name')] },
+    { operation: 'assembly-preview', group: 'assembly', name: 'preview', description: 'Assemble in this program language and processor context without writing', params: [at(), json('instructions', 'array')] },
+    { operation: 'patch-bytes', group: 'memory', name: 'patch-bytes', description: 'Replace equal-length bytes only when the expected bytes match; clears overlapping listing', write: true, params: [at(), str('expect_hex'), str('bytes_hex')] },
+    { operation: 'assemble', group: 'assembly', name: 'apply', description: 'Apply context-aware assembly with exact byte preconditions; clears overlapping listing', write: true, params: [at(), str('expect_hex'), json('instructions', 'array')] },
+    { operation: 'split-block', group: 'memory', name: 'split-block', description: 'Split one initialized block while verifying all original bytes and layout', write: true, params: [...original, at('split_address'), str('new_name')] },
+    { operation: 'move-block', group: 'memory', name: 'move-block', description: 'Move a block only when its original layout and bytes match', write: true, params: [...original, at()] },
+    { operation: 'join-blocks', group: 'memory', name: 'join-blocks', description: 'Join adjacent compatible blocks with independent content and size preconditions', write: true, params: [str('name'), str('second_name'), str('expect_sha256'), str('second_sha256'), { ...count('expect_size', '1'), required: true }, { ...count('second_size', '1'), required: true }] },
+    { operation: 'context-read', group: 'processor-context', name: 'read', description: 'Read bounded register-value ranges in the saved program context', params: [str('register'), at(), { ...at('end_address'), required: false }, count('limit', '100')] },
+    { operation: 'context-set', group: 'processor-context', name: 'set', description: 'Set a processor register value over at most 65536 bytes; requires unchanged-base publication', write: true, params: [str('register'), at(), at('end_address'), str('value')] },
+    { operation: 'context-clear', group: 'processor-context', name: 'clear', description: 'Remove an explicit processor register value over at most 65536 bytes', write: true, params: [str('register'), at(), at('end_address')] },
+    { operation: 'namespace-list', group: 'namespaces', name: 'list', description: 'List direct namespace/class children with explicit visited-symbol budget', params: [empty('parent'), count('limit', '100'), count('max_scan', '10000')] },
+    { operation: 'namespace-create', group: 'namespaces', name: 'create', description: 'Create an explicit namespace or class below an existing parent', write: true, params: [empty('parent'), str('name'), bool('class')] },
+    { operation: 'namespace-update', group: 'namespaces', name: 'update', description: 'Rename or reparent an ordinary namespace/class without recursive deletion', write: true, params: [str('path'), str('new_name'), empty('parent')] },
+    { operation: 'namespace-delete', group: 'namespaces', name: 'delete', description: 'Delete one empty ordinary namespace/class', write: true, params: [str('path')] },
+    { operation: 'external-list', group: 'externals', name: 'list', description: 'Read library identities or structured locations in one explicit library', params: [empty('library'), count('limit', '100')] },
+    { operation: 'library-create', group: 'externals', name: 'create-library', description: 'Create a named external library in the private program', write: true, params: [str('name')] },
+    { operation: 'library-update', group: 'externals', name: 'update-library', description: 'Rename an external library or change its logical project path', write: true, params: [str('name'), str('new_name', false), str('path', false)] },
+    { operation: 'library-delete', group: 'externals', name: 'delete-library', description: 'Delete an empty external library', write: true, params: [str('name')] },
+    { operation: 'external-create', group: 'externals', name: 'create-location', description: 'Create an external label/function with an optional memory address', write: true, params: [str('library'), str('label'), { ...at(), required: false }, bool('function')] },
+    { operation: 'external-update', group: 'externals', name: 'update-location', description: 'Rename/update one unambiguous external location', write: true, params: [str('library'), str('label'), str('new_label'), { ...at(), required: false }] },
+    { operation: 'external-delete', group: 'externals', name: 'delete-location', description: 'Delete one unambiguous external location, refusing retained dependencies', write: true, params: [str('library'), str('label')] },
+    { operation: 'decompiler-ir', group: 'decompiler', name: 'ir', description: 'Read bounded typed SSA P-code with explicit simplification/options and completion diagnostics', params: [at(), { ...str('simplification', false), default: 'decompile' }, count('max_ops', '1000'), count('timeout_seconds', '30'), bool('c_code'), { ...json('options', 'object', false), default: '{}' }] },
+];
+export const sdkWrites = new Set(sdkOperations.filter(v => v.write).map(v => '/sdk/' + v.operation));

package/dist/src/sdk-files.d.ts

@@ -0,0 +1,29 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { Workspace, type Scope } from './workspace.js';
+import { Research, type ResearchBackend } from './research.js';
+/** Native SDK file effects have retained input/output bytes and never repeat an uncertain call. */
+export declare class SdkFiles {
+    private readonly workspace;
+    private readonly research;
+    private readonly backend;
+    constructor(workspace: Workspace, research: Research, backend: () => Promise<ResearchBackend>);
+    loaders(input: string): Promise<{
+        inputSha256: string;
+    }>;
+    exporters(selected: Scope): Promise<{
+        value: Record<string, unknown>;
+        session: string;
+        target: string;
+    }>;
+    private copy;
+    private completedOutput;
+    databaseQuery(selected: Scope, operation: 'fid-query' | 'bsim-query', database: string, p: Record<string, unknown>): Promise<{
+        databaseSha256: string;
+        sourceSnapshotSha256: string;
+        value: Record<string, unknown>;
+        session: string;
+        target: string;
+    }>;
+    export(selected: Scope, operation: 'export' | 'archive-export' | 'fid-build' | 'bsim-build', parameters: Record<string, unknown>, directory: string, callerId?: string): Promise<unknown>;
+}
+export declare function sdkFileCommands(service: (c: CommandContext) => SdkFiles): CommandDefinition[];