@eyeauras/insight-cli 0.0.0-stage → 0.2.0

package/dist/src/native-inputs.js

@@ -0,0 +1,182 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile, writeFile, readdir, mkdir, open, rename, rm, realpath, stat } from 'node:fs/promises';
+import { basename, delimiter, dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fail, stable, text } from './model.js';
+import { managedExtensions, extensionJvmArguments } from './extensions.js';
+import { runtimeValues, runtimeSelection } from './runtime-selection.js';
+export const pinnedMcpJar = '7084e2fda16dc779dd05398e48821ff3f9ace4d32757ea143b257b39689e5fbd';
+export const packagedMcpJar = fileURLToPath(new URL('../../runtime/GhidraMCP-7.0.0.jar', import.meta.url));
+/** Ghidra has its own cache/settings overrides in addition to Java's home/tmp properties. */
+export const nativeJvmDirectories = (root) => ['-Duser.home=' + root, '-Djava.io.tmpdir=' + root,
+    '-Dapplication.cachedir=' + join(root, 'cache'), '-Dapplication.settingsdir=' + join(root, 'settings'), '-Dapplication.tempdir=' + root];
+const run = promisify(execFile);
+export async function moduleJars(home) {
+    const jars = [];
+    async function collect(folder) {
+        for (const entry of (await readdir(folder, { withFileTypes: true })).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+            const path = join(folder, entry.name);
+            if (entry.isDirectory() && entry.name !== 'data')
+                await collect(path);
+            else if (entry.isFile() && entry.name.endsWith('.jar') && basename(folder) === 'lib')
+                jars.push(path);
+        }
+    }
+    await collect(join(home, 'Ghidra'));
+    return jars;
+}
+async function sha(path) {
+    const handle = await open(path, 'r');
+    try {
+        if (!(await handle.stat()).isFile())
+            fail('configuration', 'Native runtime input must be a regular file.');
+        const hash = createHash('sha256');
+        for await (const chunk of handle.createReadStream({ autoClose: false }))
+            hash.update(chunk);
+        return hash.digest('hex');
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Installed native code/data, excluding documentation and isolated generated caches. */
+export async function nativeRuntimeFiles(ghidraHome, java) {
+    const files = [], jdkHome = dirname(dirname(java)), suffix = process.platform === 'win32' ? '.exe' : '';
+    const named = (prefix, base, path) => ({ name: prefix + '/' + relative(base, path).split(sep).join('/'), path });
+    for (const path of [java, ...['javac', 'keytool'].map(name => join(dirname(java), name + suffix))])
+        if (!(await stat(path)).isFile())
+            fail('configuration', 'The configured JDK tool is not a regular file.');
+    async function walk(path, base, prefix, selected, ancestors = new Set()) {
+        const real = await realpath(path);
+        if (ancestors.has(real))
+            fail('configuration', 'Native runtime directories contain a cycle.');
+        const parents = new Set(ancestors);
+        parents.add(real);
+        for (const entry of (await readdir(path, { withFileTypes: true })).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+            if (['__pycache__', '.DS_Store'].includes(entry.name) || prefix === 'jdk' && entry.name === 'src.zip')
+                continue;
+            const item = join(path, entry.name), kind = entry.isSymbolicLink() ? await stat(item) : entry;
+            if (kind.isDirectory())
+                await walk(item, base, prefix, selected || ['data', 'os', 'pypkg', 'ghidra_scripts'].includes(entry.name), parents);
+            else if (kind.isFile() && (selected || entry.name === 'Module.manifest' || entry.name === 'application.properties' || entry.name.endsWith('.jar') && basename(path) === 'lib'))
+                files.push(named(prefix, base, item));
+        }
+    }
+    await walk(join(ghidraHome, 'Ghidra'), ghidraHome, 'ghidra', false);
+    for (const directory of ['bin', 'lib', 'conf'])
+        await walk(join(jdkHome, directory), jdkHome, 'jdk', true);
+    files.push(named('jdk', jdkHome, join(jdkHome, 'release')));
+    if (!(await stat(join(jdkHome, 'lib', 'modules'))).isFile())
+        fail('configuration', 'The configured JDK omitted its runtime modules.');
+    return files.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+}
+export async function nativeRuntimeFingerprint(ghidraVersion, files) {
+    const hashes = [];
+    for (const file of files)
+        hashes.push({ name: file.name, sha256: await sha(file.path) });
+    return createHash('sha256').update(stable({ schema: 2, ghidraVersion, hashes })).digest('hex');
+}
+export async function nativeInputs(values, directory) {
+    if (directory)
+        values = runtimeValues(dirname(directory), values);
+    if (!values.java || !values.ghidraHome)
+        fail('configuration', 'Ghidra is not installed. Run insight-cli ghidra install, or supply external runtime paths.');
+    const requested = [text(values.java, 4096), text(values.ghidraHome, 4096), text(values.mcpJar ?? packagedMcpJar, 4096)];
+    if (!requested.every(isAbsolute))
+        fail('configuration', 'Configure absolute Java, Ghidra home and GhidraMCP jar paths.');
+    const [java, ghidraHome, mcpJar] = await Promise.all(requested.map(path => realpath(path)));
+    const jarHash = await sha(mcpJar);
+    if (jarHash !== pinnedMcpJar || values.mcpJarSha256 !== undefined && String(values.mcpJarSha256).toLowerCase() !== jarHash)
+        fail('binding', 'GhidraMCP artifact differs from the pinned, verified runtime.');
+    const properties = await readFile(join(ghidraHome, 'Ghidra', 'application.properties'), 'utf8');
+    const ghidraVersion = /^application.version=(.+)$/m.exec(properties)?.[1]?.trim();
+    if (ghidraVersion !== '12.1.2')
+        fail('configuration', 'This build requires the verified Ghidra 12.1.2 runtime.');
+    let jdk;
+    try {
+        jdk = await run(java, ['--version'], { timeout: 10000, maxBuffer: 16384 });
+    }
+    catch {
+        fail('configuration', 'Configured Java executable could not be verified.');
+    }
+    if (!/^(?:openjdk|java) 21(?:[.\s-]|$)/m.test(jdk.stdout + '\n' + jdk.stderr))
+        fail('configuration', 'A Java 21 JDK is required.');
+    for (const program of ['javac', 'keytool'])
+        if (!(await stat(join(dirname(java), program + (process.platform === 'win32' ? '.exe' : '')))).isFile())
+            fail('configuration', 'Java must come from a JDK with javac and keytool.');
+    const modules = await managedExtensions(directory);
+    const extraJars = modules.flatMap(m => m.files.filter(f => /^lib\/[^/]+\.jar$/.test(f.name)).map(f => join(m.root, f.name)));
+    const baseJars = [mcpJar, ...await moduleJars(ghidraHome)], jars = [...baseJars, ...extraJars];
+    const debug = join(ghidraHome, 'Ghidra', 'Debug'), debuggerWheels = [
+        join(debug, 'Debugger-rmi-trace/pypkg/dist/protobuf-6.31.0-py3-none-any.whl'),
+        join(debug, 'Debugger-rmi-trace/pypkg/dist/ghidratrace-12.1-py3-none-any.whl'),
+        join(debug, 'Debugger-agent-lldb/pypkg/dist/ghidralldb-12.1-py3-none-any.whl')
+    ];
+    const files = await nativeRuntimeFiles(ghidraHome, java);
+    const baseFingerprint = await nativeRuntimeFingerprint(ghidraVersion, [...files, { name: 'bridge/GhidraMCP-7.0.0.jar', path: mcpJar }]);
+    if (directory) {
+        const selected = runtimeSelection(dirname(directory));
+        if (selected && selected.fingerprint !== baseFingerprint)
+            fail('binding', 'Selected runtime inputs differ from their installation receipt; reinstall or restore the verified files.');
+    }
+    for (const module of modules)
+        for (const file of module.files)
+            files.push({ name: 'extension/' + module.name + '/' + file.name, path: join(module.root, file.name) });
+    // Logical names bind locations without embedding the author's installation path.
+    files.push({ name: 'bridge/GhidraMCP-7.0.0.jar', path: mcpJar });
+    const fingerprint = modules.length ? await nativeRuntimeFingerprint(ghidraVersion, files) : baseFingerprint;
+    return { java, ghidraHome, mcpJar, jars, classpath: jars.join(delimiter), ghidraVersion, fingerprint, debuggerWheels, extensionRoots: modules.map(m => m.root), serverClasspath: baseJars.join(delimiter) };
+}
+/** Compile packaged helper sources against the selected installation, never an author checkout. */
+export async function nativeHelpers(directory, inputs) {
+    const sources = fileURLToPath(new URL('../../references/native/', import.meta.url));
+    const names = [...(await readdir(sources)).filter(name => name.endsWith('.java')), '../InsightRepositoryProbe.java'].sort();
+    if (!names.length)
+        fail('configuration', 'Installed package omitted its native helper sources.');
+    const hashes = [];
+    for (const name of names)
+        hashes.push(await sha(join(sources, name)));
+    const key = createHash('sha256').update(stable([inputs.fingerprint, names, hashes])).digest('hex');
+    const parent = join(directory, 'native-helpers');
+    await mkdir(parent, { recursive: true, mode: 0o700 });
+    const classes = join(parent, key);
+    try {
+        if (await readFile(join(classes, 'complete'), 'utf8') === key)
+            return classes;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const temporary = join(parent, 'compiling-' + randomUUID());
+    await mkdir(temporary, { mode: 0o700 });
+    try {
+        await run(join(dirname(inputs.java), 'javac' + (process.platform === 'win32' ? '.exe' : '')), ['-proc:none', '-cp', inputs.classpath, '-d', temporary, ...names.map(name => join(sources, name))], { timeout: 60000, maxBuffer: 262144 });
+        const complete = await open(join(temporary, 'complete'), 'wx', 0o600);
+        try {
+            await complete.writeFile(key);
+            await complete.sync();
+        }
+        finally {
+            await complete.close();
+        }
+        try {
+            await rename(temporary, classes);
+        }
+        catch (error) {
+            if (!['EEXIST', 'ENOTEMPTY'].includes(error.code ?? '') || await readFile(join(classes, 'complete'), 'utf8') !== key)
+                throw error;
+        }
+        return classes;
+    }
+    catch (error) {
+        await writeFile(join(parent, 'compilation-' + key + '.log'), String(error.stderr ?? 'Native compilation failed'), { mode: 0o600 });
+        fail('configuration', 'Native helper compilation failed against the configured runtime; diagnostics remain in owned profile storage.');
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+export const nativeExtensionArguments = (inputs) => extensionJvmArguments(inputs.extensionRoots ?? []);

package/dist/src/native-queries.d.ts

@@ -0,0 +1,2 @@
+import type { HttpBridge } from './transport.js';
+export declare function nativeQuery(http: HttpBridge, program: string, operation: string, parameters: Record<string, unknown>, write?: boolean): Promise<unknown>;

package/dist/src/native-queries.js

@@ -0,0 +1,29 @@
+import { readFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { object, fail } from './model.js';
+export async function nativeQuery(http, program, operation, parameters, write = false) {
+    const base = operation.startsWith('/sdk/') ? 'InsightSdkScript' : operation.startsWith('/emulate_') ? 'InsightEmulation' : 'InsightResearchQueries';
+    const name = base + '_' + randomUUID().replaceAll('-', '');
+    const source = await readFile(new URL('../../references/native/' + base + '.java', import.meta.url), 'utf8');
+    const response = object(await http.call('/run_script_inline', { program, code: source.replace('public class ' + base + ' ', 'public class ' + name + ' '),
+        args: Buffer.from(JSON.stringify({ operation, parameters, ...(write ? { write: true } : {}) }), 'utf8').toString('base64') }));
+    if (response.success !== true || typeof response.console_output !== 'string')
+        fail('partial', 'Native research helper did not complete.');
+    const matches = [...response.console_output.matchAll(/^INSIGHT_QUERY:(.+)$/gm)];
+    if (matches.length !== 1)
+        fail('partial', 'Native research helper omitted its unique result.');
+    let result;
+    try {
+        result = object(JSON.parse(matches[0][1]));
+    }
+    catch {
+        fail('partial', 'Native research helper returned malformed JSON.');
+    }
+    if (result.error) {
+        const error = object(result.error), code = String(error.code);
+        fail(['invalid', 'unsupported', 'limit', ...(operation.startsWith('/sdk/') ? ['rejected'] : [])].includes(code) ? code : 'partial', typeof error.message === 'string' ? error.message.slice(0, 500) : 'Native research failed.');
+    }
+    if (!Object.hasOwn(result, 'value'))
+        fail('partial', 'Native research helper omitted its value.');
+    return result.value;
+}

package/dist/src/projects.d.ts

@@ -0,0 +1,31 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { Workspace } from './workspace.js';
+import { Research, type ResearchBackend } from './research.js';
+export declare class Projects {
+    private readonly workspace;
+    private readonly backend;
+    private readonly research;
+    private readonly tasks;
+    constructor(workspace: Workspace, backend: () => Promise<ResearchBackend>, research: Research, tasks: Map<string, Promise<unknown>>);
+    private ordered;
+    private container;
+    private owned;
+    private result;
+    private native;
+    list(): Promise<{
+        items: {
+            project: string;
+        }[];
+        count: number;
+    }>;
+    read(op: string, name: string, p: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private recovered;
+    change(op: string, name: string, p: Record<string, unknown>, callerId?: string): Promise<unknown>;
+    private newOutput;
+    private exportArtifact;
+    export(selected: {
+        session: string;
+        target: string;
+    }, output: string, callerId?: string): Promise<unknown>;
+}
+export declare function projectCommands(service: (c: CommandContext) => Projects): CommandDefinition[];

package/dist/src/projects.js

@@ -0,0 +1,301 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { constants } from 'node:fs';
+import { mkdir, lstat, realpath, readFile, open, rename, readdir, copyFile, chmod } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { scope, number } from './research.js';
+import { id, text, object, fail, stable } from './model.js';
+import { repositoryPath } from './administration.js';
+import { selectedOptions } from './arguments.js';
+const projectName = (value) => { const name = id(value); if (name.startsWith('.') || name.length > 80)
+    fail('invalid', 'Project name requires 1–80 non-hidden ID characters.'); return name; };
+async function persist(path, value) {
+    const temporary = path + '.new-' + randomUUID(), h = await open(temporary, 'wx', 0o600);
+    try {
+        await h.writeFile(stable(value));
+        await h.sync();
+    }
+    finally {
+        await h.close();
+    }
+    await rename(temporary, path);
+    if (process.platform !== 'win32') {
+        const dir = await open(dirname(path), 'r');
+        try {
+            await dir.sync();
+        }
+        finally {
+            await dir.close();
+        }
+    }
+}
+export class Projects {
+    workspace;
+    backend;
+    research;
+    tasks;
+    constructor(workspace, backend, research, tasks) {
+        this.workspace = workspace;
+        this.backend = backend;
+        this.research = research;
+        this.tasks = tasks;
+    }
+    async ordered(action) {
+        const key = 'projects', previous = this.tasks.get(key), task = (previous ? previous.catch(() => { }) : Promise.resolve()).then(action);
+        this.tasks.set(key, task);
+        try {
+            return await task;
+        }
+        finally {
+            if (this.tasks.get(key) === task)
+                this.tasks.delete(key);
+        }
+    }
+    async container() {
+        const path = join(this.workspace.directory, 'ghidra-projects');
+        await mkdir(path, { recursive: true, mode: 0o700 });
+        if ((await lstat(path)).isSymbolicLink() || await realpath(path) !== resolve(path))
+            fail('binding', 'Project container moved outside the selected workspace.');
+        return path;
+    }
+    async owned(name, create = false) {
+        const root = join(await this.container(), projectName(name));
+        if (create) {
+            await mkdir(root, { mode: 0o700 });
+            await persist(join(root, 'owner.json'), { schema: 1, project: name, profile: this.workspace.profile });
+        }
+        if ((await lstat(root)).isSymbolicLink() || await realpath(root) !== resolve(root))
+            fail('binding', 'Project root moved outside owned storage.');
+        const owner = object(JSON.parse(await readFile(join(root, 'owner.json'), 'utf8')));
+        if (owner.schema !== 1 || owner.project !== name || owner.profile !== this.workspace.profile)
+            fail('binding', 'Project ownership receipt differs.');
+        return root;
+    }
+    result(op, name, p, raw) {
+        const value = object(raw);
+        if (value.project !== name)
+            fail('binding', 'Native operation returned another project.');
+        const states = { create: 'ready', restore: 'ready', open: 'ready', close: 'closed', info: 'ready', create_folder: 'created', move_file: 'moved', move_folder: 'moved', delete_file: 'deleted', delete: 'deleted', import: 'imported', archive: 'archived' };
+        if (op === 'files') {
+            if (value.path !== p.path || value.offset !== p.offset || value.limit !== p.limit || !Number.isSafeInteger(value.total) || Number(value.total) < 0 || !Array.isArray(value.items) || value.items.length > Number(p.limit))
+                fail('partial', 'Project listing omitted its selected page.');
+            for (const raw of value.items) {
+                const row = object(raw);
+                for (const field of ['name', 'path', 'type'])
+                    if (typeof row[field] !== 'string' || !row[field])
+                        fail('partial', 'Project file identity is incomplete.');
+                repositoryPath(row.path);
+            }
+            return { ...value, truncated: Number(p.offset) + value.items.length < Number(value.total) };
+        }
+        if (value.state !== states[op])
+            fail('partial', 'Project operation did not establish its expected state.');
+        if (['create_folder', 'delete_file'].includes(op) && value.path !== p.path)
+            fail('binding', 'Project operation selected another path.');
+        if (['move_file', 'move_folder'].includes(op)) {
+            const expected = (p.destination === '/' ? '' : p.destination) + '/' + String(p.path).split('/').at(-1);
+            if (value.path !== expected)
+                fail('binding', 'Moved item destination differs.');
+        }
+        if (op === 'import' && object(value.file).path !== p.path)
+            fail('binding', 'Imported file destination differs.');
+        if (op === 'archive' && (!Number.isSafeInteger(value.size) || Number(value.size) < 1))
+            fail('partial', 'Archive output is empty.');
+        return value;
+    }
+    async native(op, name, p, create = false) {
+        const root = await this.owned(name, create), backend = await this.backend();
+        if (!backend.project)
+            fail('configuration', 'Selected backend lacks project file operations.');
+        return this.result(op, name, p, await backend.project(op, { request_id: 'read_' + randomUUID(), ...p, root, project: name, profile: this.workspace.profile }));
+    }
+    async list() {
+        return this.ordered(async () => {
+            const items = [];
+            for (const name of (await readdir(await this.container())).sort()) {
+                const root = await this.owned(name);
+                try {
+                    if ((await lstat(join(root, 'project.gpr'))).isFile())
+                        items.push({ project: name });
+                }
+                catch (e) {
+                    if (e.code !== 'ENOENT')
+                        throw e;
+                }
+            }
+            return { items, count: items.length };
+        });
+    }
+    async read(op, name, p) {
+        return this.ordered(async () => {
+            const value = await this.native(op, name, p);
+            return op === 'info' ? { ...value, unresolvedRequests: this.workspace.unresolvedProject(name).map(request => ({ operation: request.operation, state: request.state, ...(request.callerId ? { requestId: request.callerId } : {}) })) } : value;
+        });
+    }
+    async recovered(request, op, name, p) {
+        const original = object(object(request.intent).parameters), expected = { ...original, request_id: request.id };
+        if (op === 'import' || op === 'restore')
+            expected.input = await this.workspace.artifacts.verify(original.input);
+        if (op === 'archive')
+            expected.output = join(this.workspace.directory, 'project-archives', request.id, 'project.gar');
+        const backend = await this.backend(), root = await this.owned(name), outcome = await backend.projectOutcome?.(request.id, { ...expected, project: name, root, profile: this.workspace.profile, operation: op });
+        if (!outcome)
+            return;
+        let value = this.result(op, name, p, outcome);
+        if (op === 'archive') {
+            const output = join(this.workspace.directory, 'project-archives', request.id, 'project.gar'), artifact = await this.workspace.artifacts.capture(output, 'input');
+            await this.exportArtifact(artifact, text(p.output, 4096), true);
+            value = { ...value, output: p.output, sha256: artifact.sha256 };
+        }
+        this.workspace.administrationState(request.id, 'applied', value);
+        return value;
+    }
+    async change(op, name, p, callerId) {
+        name = projectName(name);
+        let input;
+        if (op === 'import' || op === 'restore')
+            input = await this.workspace.artifacts.capture(text(p.input, 4096), 'input');
+        const intent = { project: name, ...p, ...(input ? { input } : {}) }, reserved = this.workspace.reserveAdministration('projects.' + op, intent, callerId);
+        return this.ordered(async () => {
+            const request = this.workspace.administration(reserved.request.id);
+            if (reserved.replay && request.state !== 'accepted') {
+                if (request.state === 'applied')
+                    return request.result;
+                const value = await this.recovered(request, op, name, p);
+                if (value)
+                    return value;
+                fail('unknown', 'Project outcome is retained; the operation is not repeated.', request.result);
+            }
+            for (const earlier of this.workspace.unresolvedProject(name))
+                if (earlier.id !== request.id && earlier.operation.startsWith('projects.')) {
+                    const params = object(object(earlier.intent).parameters);
+                    await this.recovered(earlier, earlier.operation.slice('projects.'.length), name, params);
+                }
+            if (this.workspace.unresolvedProject(name).some(item => item.id !== request.id))
+                fail('blocked', 'An earlier project operation is unresolved; preserve its project before continuing.');
+            const creating = op === 'create' || op === 'restore';
+            if (!creating)
+                await this.owned(name);
+            const nativeParameters = { ...p, request_id: request.id, ...(input ? { input: await this.workspace.artifacts.verify(input) } : {}) };
+            let output;
+            if (op === 'archive') {
+                await this.newOutput(text(p.output, 4096));
+                const stage = join(this.workspace.directory, 'project-archives', request.id);
+                await mkdir(stage, { recursive: true, mode: 0o700 });
+                output = join(stage, 'project.gar');
+                nativeParameters.output = output;
+            }
+            this.workspace.administrationState(request.id, 'running');
+            try {
+                const value = await this.native(op, name, nativeParameters, creating);
+                if (output) {
+                    const artifact = await this.workspace.artifacts.capture(output, 'input');
+                    await this.exportArtifact(artifact, text(p.output, 4096));
+                    const result = { ...value, output: p.output, sha256: artifact.sha256 };
+                    this.workspace.administrationState(request.id, 'applied', result);
+                    return result;
+                }
+                this.workspace.administrationState(request.id, 'applied', value);
+                return value;
+            }
+            catch (error) {
+                this.workspace.administrationState(request.id, 'unknown', { project: name, operation: op, state: 'unknown' });
+                throw error;
+            }
+        });
+    }
+    async newOutput(output) { try {
+        await lstat(output);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    } fail('exists', 'Output already exists; choose a new file.'); }
+    async exportArtifact(artifact, output, recover = false) {
+        const source = await this.workspace.artifacts.verify(artifact);
+        try {
+            await copyFile(source, output, constants.COPYFILE_EXCL);
+        }
+        catch (error) {
+            if (!recover || error.code !== 'EEXIST')
+                throw error;
+        }
+        const readback = await this.workspace.artifacts.capture(output, artifact.kind);
+        if (readback.id !== artifact.id)
+            fail('partial', 'Exported bytes differ from the retained snapshot.');
+        await chmod(output, 0o600);
+        const handle = await open(output, 'r+');
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async export(selected, output, callerId) {
+        const reserved = this.workspace.reserveRequest(selected, 'ghidra.program.export', { output }, callerId);
+        return this.research.ordered(selected, async () => {
+            const request = this.workspace.request(reserved.request.id);
+            if (reserved.replay && request.state !== 'accepted') {
+                if (request.state === 'applied')
+                    return request.result;
+                const execution = object(request.execution), snapshot = execution.snapshot;
+                await this.workspace.artifacts.verify(snapshot);
+                const observed = await this.workspace.artifacts.capture(output, 'snapshot'), current = this.workspace.context(selected);
+                if (observed.id !== snapshot.id || current.generation !== execution.generation)
+                    fail('unknown', 'Export output cannot establish the retained outcome.');
+                const result = { ...selected, state: 'exported', output, sha256: snapshot.sha256, size: snapshot.size };
+                this.workspace.completeSavedRequest(selected, request.id, current.generation, { workingSnapshot: snapshot }, result);
+                return result;
+            }
+            await this.newOutput(output);
+            const backend = await this.backend();
+            await backend.open(selected);
+            const snapshot = await backend.saved(selected), context = this.workspace.context(selected);
+            this.workspace.startRequest(request.id, { kind: 'export', generation: context.generation, snapshot, output });
+            try {
+                await this.exportArtifact(snapshot, output);
+                const result = { ...selected, state: 'exported', output, sha256: snapshot.sha256, size: snapshot.size };
+                this.workspace.completeSavedRequest(selected, request.id, context.generation, { workingSnapshot: snapshot }, result);
+                return result;
+            }
+            catch (error) {
+                this.workspace.recordRequest(request.id, 'unknown', { ...selected, state: 'unknown', savedSnapshot: snapshot });
+                throw error;
+            }
+        });
+    }
+}
+const projectOption = { flags: '--project <name>', description: 'Select a managed project in this profile', required: true }, requestOption = { flags: '--request-id <id>', description: 'Retrieve this outcome without repeating it' };
+export function projectCommands(service) {
+    const leaves = [command('list', 'List owned projects', (_, c) => service(c).list(), { permission: Permission.ReadOnly })];
+    for (const [name, op, permission] of [['create', 'create', Permission.Update], ['open', 'open', Permission.Update], ['close', 'close', Permission.Update], ['delete', 'delete', 'Destructive'], ['info', 'info', Permission.ReadOnly],
+        ['files', 'files', Permission.ReadOnly], ['create-folder', 'create_folder', Permission.Update], ['move-file', 'move_file', Permission.Update], ['move-folder', 'move_folder', Permission.Update], ['delete-file', 'delete_file', 'Destructive'], ['archive', 'archive', Permission.Update], ['restore', 'restore', Permission.Update]]) {
+        const path = ['files', 'create_folder', 'move_file', 'move_folder', 'delete_file'].includes(op), moving = op.startsWith('move_'), changing = permission !== Permission.ReadOnly;
+        const options = [projectOption, ...(path ? [{ flags: '--path <path>', description: 'Absolute path inside the project', ...(op === 'files' ? { defaultValue: '/' } : { required: true }) }] : []),
+            ...(moving ? [{ flags: '--destination <folder>', description: 'Existing destination folder', required: true }] : []),
+            ...(op === 'files' ? [{ flags: '--limit <count>', description: 'Page size 1–100', defaultValue: 50 }, { flags: '--offset <count>', description: 'Page offset', defaultValue: 0 }] : []),
+            ...(op === 'archive' ? [{ flags: '--output <file>', description: 'Create a new Ghidra project archive', required: true }] : []),
+            ...(op === 'restore' ? [{ flags: '--input <file>', description: 'Restore into a new owned project', required: true }] : []), ...(changing ? [requestOption] : [])];
+        leaves.push(command(name, 'Manage project files without changing research contexts', ({ options: o }, c) => {
+            const p = {};
+            if (path)
+                p.path = repositoryPath(o.path);
+            if (moving)
+                p.destination = repositoryPath(o.destination);
+            if (op === 'files') {
+                p.limit = number(o.limit, 100, 1);
+                p.offset = number(o.offset, 2147483647);
+            }
+            for (const key of ['input', 'output'])
+                if (o[key] !== undefined)
+                    p[key] = resolve(c.cwd, text(o[key], 4096));
+            return changing ? service(c).change(op, projectName(o.project), p, o.requestId === undefined ? undefined : id(o.requestId)) : service(c).read(op, projectName(o.project), p);
+        }, { permission, options }));
+    }
+    return [command('projects', 'Manage isolated Ghidra projects in the selected profile', leaves), command('program', 'Program files', [
+            command('export', 'Export the selected private program to a new GZF file', ({ options: o }, c) => service(c).export(scope(o), resolve(c.cwd, text(o.output, 4096)), o.requestId === undefined ? undefined : id(o.requestId)), { permission: Permission.Update, options: [...selectedOptions, { flags: '--output <file>', description: 'New output file; existing files are preserved', required: true }, requestOption] }),
+            command('import', 'Import a GZF into a managed project', ({ options: o }, c) => service(c).change('import', projectName(o.project), { input: resolve(c.cwd, text(o.input, 4096)), path: repositoryPath(o.path) }, o.requestId === undefined ? undefined : id(o.requestId)), { permission: Permission.Update, options: [projectOption, { flags: '--input <file>', description: 'Saved Ghidra program file', required: true }, { flags: '--path <path>', description: 'New file path inside the project', required: true }, requestOption] }),
+        ])];
+}

package/dist/src/prototype-cli.d.ts

@@ -0,0 +1,8 @@
+import { type CliDefinition, type CliRuntime, type CommandContext } from '@eyeauras/cli-factory';
+import { type Publisher } from './coordinator.js';
+export interface Options {
+    runtime?: CliRuntime;
+    publisher?: (context: CommandContext) => Publisher;
+}
+export declare function createDefinition(options?: Options): CliDefinition;
+export declare const createInsightCli: (options?: Options) => import("@eyeauras/cli-factory").CliApplication;