@eyeauras/insight-cli 0.0.0-stage → 0.1.0

package/.cli-package-build.json

@@ -0,0 +1 @@
+{"version":1,"artifact":"c3714e4dd4db303fdccc352327ce7c7f5dff074726238298a6953be70aca1db3"}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 insight-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# insight-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CLI/API for reverse engineering with durable sessions, isolated Ghidra contexts,
+explicit merge/refresh and ordinary saved files. Agents choose the investigation.
+
+## Install
+
+Use Node.js 24 or newer:
+
+```sh
+npm install --global @eyeauras/insight-cli
+insight-cli --help
+insight-cli skill insight-re
+```
+
+The executable is `insight-cli`. Its global npm executable directory must be on PATH.
+No source checkout, TypeScript build or separate Factory installation is required.
+The pinned Factory IPC runtime is a normal npm dependency fetched from an immutable
+GitHub tarball URL; installation therefore needs npm registry and GitHub access.
+Ghidra 12.1.2 and Java 21 are external dependencies for Ghidra commands.
+Help, skill discovery and saving ordinary files do not need Ghidra or Java.
+
+## Start
+
+```sh
+insight-cli profile create local --java /path/to/java --ghidra-home /path/to/ghidra
+insight-cli --profile local permissions grant Update
+insight-cli --profile local ghidra open ./client.exe --session new --json
+```
+
+Retain the returned `session` and `target` and supply both on research calls:
+
+```sh
+insight-cli --profile local ghidra strings search --session <session> --target <target> --contains config.json --json
+insight-cli --profile local ghidra functions decompile --session <session> --target <target> --address <entry> --json
+insight-cli --profile local ghidra merge --session <session> --target <target> --json
+```
+
+Another agent uses `--session new` for its own context on the same input. It receives
+published changes with `ghidra refresh`; local work and conflicts remain explicit.
+Managed local startup needs no separately configured Ghidra Server.
+
+Save a completed project file or folder when a retained checkpoint is useful:
+
+```sh
+insight-cli --profile local artifacts save ./analysis --json
+```
+
+The response returns an ordinary saved path and digest. Follow existing project RE
+rules, formats and evidence locations; the packaged RE skill fills unspecified gaps.
+Installation does not register skills or change agent settings. Use `insight-cli skill`
+and `insight-cli skill insight-re` to locate packaged instructions and references.
+
+Full documentation and verification: [GitHub](https://github.com/iXab3r/insight-cli).
+License: MIT. The bundled GhidraMCP bridge has its own Apache-2.0 license and notice.

package/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: insight-cli
+description: Research several executable inputs through durable independent sessions and isolated Ghidra contexts using the matching insight-cli facade. Agents supply the investigation and interpret results.
+---
+
+# insight-cli 0.1.0
+
+This skill and its executable helper are one npm package. Run `insight-cli skill` to locate
+these installed resources. Use generated `--help` for syntax; read the references as needed.
+Follow applicable project RE rules for tools, source of truth, evidence layout and format;
+this package's walkthroughs fill gaps rather than replacing those conventions.
+
+For coordinating a reverse-engineering investigation with ordinary files, external tools
+and multiple agents, read the packaged [Insight RE skill](skills/insight-re/SKILL.md),
+also located by `insight-cli skill insight-re`. When a retained checkpoint is useful, save
+a completed project file or folder with
+`insight-cli artifacts save <path>`; [save semantics](references/artifacts.md) describe the
+ordinary saved copy and its receipt. Neither operation requires a Ghidra installation.
+
+1. Select the configured runtime profile. Ordinary work uses a managed local server; an external
+   server is optional. See [setup](references/setup.md). Factory permissions authorize changes.
+2. Open the input with `ghidra open <input> --session new`. Retain the returned session and target.
+   Another agent chooses `new` independently; one session can open several inputs.
+3. Pass both `--session` and `--target` on research calls. Follow strings to xrefs and their
+   function addresses, then inspect/decompile. See [research](references/research.md).
+4. Rename functions or set/clear comments through ordinary commands. An `applied` result means
+   verified saved private work. Other sessions keep their own views; local edits remain unpublished in the default manual mode.
+5. By default, publish explicitly with `ghidra merge`; receive safe shared changes with `ghidra refresh`.
+   Resolve overlapping names/comments against an explicitly observed shared value. A conflict
+   prevents the whole selected merge and retains local work.
+6. Continue with `ghidra open --session <id> --target <id>`. For uncertain outcomes inspect
+   `sessions status <id> --target <id>` and [recovery](references/recovery.md). Supplying a stable
+   optional `--request-id` lets a repeated changing intent retrieve its outcome without rerunning.
+
+The facade exposes the pinned static research/editing catalog, merge/refresh, project/server/GUI
+controls, debugger, archive exchange and supported recovery. Preserve private work
+and journals while an outcome is unresolved. The CLI supplies the investigation tools; agents
+choose research goals and interpret findings.
+Installing this package does not register this skill in an agent's configuration.
+
+For project files, program export/import and configured-server administration, read
+[administration](references/administration.md). These operations preserve separate research views;
+their external effects do not participate in program merge.
+
+For owned GUI execution, CPU state, breakpoints and retained traces, read
+[debugger](references/debugger.md). Execution side effects remain separate from program publication.
+
+For explicit external documentation exchange and retained submission outcomes, read
+[archive](references/archive.md).
+
+For selected native SDK extensions (VT, DB differences, byte/assembly edits, formats, GDT,
+FID/BSim, namespaces and typed IR), read [native workflows](references/native-workflows.md).
+
+For managed SDK extension modules, actual language/analyzer/plugin discovery and opt-in
+automatic synchronization, read [extensions and sync](references/extensions-and-sync.md).

package/dist/src/administration-results.d.ts

@@ -0,0 +1 @@
+export declare function administrationResult(operation: string, p: Record<string, unknown>, raw: unknown): Record<string, unknown>;

package/dist/src/administration-results.js

@@ -0,0 +1,84 @@
+import { object, fail } from './model.js';
+const integer = (value, min = 0) => { if (!Number.isSafeInteger(value) || Number(value) < min)
+    fail('partial', 'Administration returned an invalid integer.'); };
+const names = (value) => { if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || !item))
+    fail('partial', 'Administration name inventory is absent.'); return value; };
+const array = (value) => { if (!Array.isArray(value))
+    fail('partial', 'Administration item inventory is absent.'); return value.map(object); };
+const file = (value) => { const row = object(value); for (const field of ['name', 'path', 'type'])
+    if (typeof row[field] !== 'string')
+        fail('partial', 'Repository file identity is incomplete.'); integer(row.version, 1); return row; };
+export function administrationResult(operation, p, raw) {
+    const value = object(raw);
+    if (JSON.stringify(value).length > 1048576)
+        fail('limit', 'Administration result exceeds one MiB.');
+    if (['status', 'connect', 'disconnect'].includes(operation)) {
+        if (typeof value.connected !== 'boolean' || !['local', 'external'].includes(String(value.mode)))
+            fail('partial', 'Server status is incomplete.');
+        if (value.connected && typeof value.repository !== 'string')
+            fail('partial', 'Connected server omitted its repository.');
+    }
+    else if (operation === 'repositories') {
+        const values = names(value.repositories);
+        integer(value.count);
+        if (value.count !== values.length)
+            fail('partial', 'Repository count is inconsistent.');
+    }
+    else if (operation === 'create_repository') {
+        if (value.state !== 'created' || value.repository !== p.repository)
+            fail('partial', 'Created repository identity changed.');
+    }
+    else if (operation === 'users') {
+        const users = array(value.users);
+        integer(value.count);
+        if (users.length !== value.count || users.some(user => typeof user.name !== 'string'))
+            fail('partial', 'Server user count is inconsistent.');
+    }
+    else {
+        if (value.repository !== p.repository)
+            fail('binding', 'Administration returned another repository.');
+        if (operation === 'files') {
+            names(value.folders);
+            array(value.files).forEach(file);
+            if (value.path !== p.path)
+                fail('binding', 'Repository folder changed.');
+        }
+        else if (operation === 'file') {
+            const row = file(value.file);
+            if (row.path !== p.path)
+                fail('binding', 'Repository file path changed.');
+        }
+        else if (operation === 'permissions') {
+            array(value.users).forEach(user => { if (typeof user.name !== 'string')
+                fail('partial', 'ACL username is absent.'); integer(user.access); if (Number(user.access) > 2)
+                fail('partial', 'Invalid ACL level.'); });
+            if (typeof value.anonymous !== 'boolean')
+                fail('partial', 'ACL anonymous flag is absent.');
+        }
+        else if (operation === 'set_permissions') {
+            const users = object(value.users);
+            if (value.state !== 'applied' || users[String(p.user)] !== p.access || typeof value.anonymous !== 'boolean')
+                fail('partial', 'Permission update lacks exact readback.');
+        }
+        else if (operation === 'history') {
+            if (value.path !== p.path)
+                fail('binding', 'History selected another file.');
+            array(value.versions).forEach(version => { integer(version.version, 1); if (typeof version.user !== 'string' || typeof version.comment !== 'string')
+                fail('partial', 'Version history is incomplete.'); });
+        }
+        else if (operation === 'checkouts') {
+            if (value.path !== p.path)
+                fail('binding', 'Checkout selection changed.');
+            array(value.checkouts).forEach(item => { if (typeof item.id !== 'string' || !/^\d+$/.test(item.id) || typeof item.path !== 'string' || typeof item.user !== 'string')
+                fail('partial', 'Checkout identity is incomplete.'); integer(item.version); });
+        }
+        else if (operation === 'terminate_checkout' || operation === 'terminate_all_checkouts') {
+            if (value.path !== p.path)
+                fail('binding', 'Termination selected another path.');
+            integer(value.terminated);
+        }
+        else
+            fail('schema', 'Administration operation lacks a result contract.');
+    }
+    return value;
+}

package/dist/src/administration.d.ts

@@ -0,0 +1,14 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import type { ResearchBackend } from './research.js';
+import { Workspace } from './workspace.js';
+export declare function repositoryPath(value: unknown): string;
+export declare class Administration {
+    readonly workspace: Workspace;
+    private readonly backend;
+    private readonly tasks;
+    constructor(workspace: Workspace, backend: () => Promise<ResearchBackend>, tasks: Map<string, Promise<unknown>>);
+    private ordered;
+    read(operation: string, parameters: Record<string, unknown>): Promise<Record<string, unknown>>;
+    change(operation: string, parameters: Record<string, unknown>, callerId?: string): Promise<unknown>;
+}
+export declare function administrationCommands(service: (context: CommandContext) => Administration): CommandDefinition[];

package/dist/src/administration.js

@@ -0,0 +1,120 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { fail, id, text } from './model.js';
+import { option, parsed, key } from './arguments.js';
+import { administrationResult } from './administration-results.js';
+const repository = (value) => { const name = text(value, 128); if (name !== name.trim() || /[\\/\0]/.test(name) || name.startsWith('.'))
+    fail('invalid', 'Repository name must be a single bounded name.'); return name; };
+export function repositoryPath(value) {
+    const path = text(value, 4096);
+    if (!path.startsWith('/') || path.includes('\\') || path.split('/').some(part => part === '.' || part === '..') || path.includes('//'))
+        fail('invalid', 'Use an absolute repository path without traversal.');
+    return path.length > 1 ? path.replace(/\/$/, '') : path;
+}
+export class Administration {
+    workspace;
+    backend;
+    tasks;
+    constructor(workspace, backend, tasks) {
+        this.workspace = workspace;
+        this.backend = backend;
+        this.tasks = tasks;
+    }
+    async ordered(action) {
+        const key = 'administration', 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 read(operation, parameters) {
+        return this.ordered(async () => {
+            const backend = await this.backend();
+            if (!backend.administration)
+                fail('configuration', 'Selected backend has no repository administration adapter.');
+            const value = administrationResult(operation, parameters, await backend.administration(operation, parameters));
+            return operation === 'status' ? { ...value, unresolvedRequests: this.workspace.unresolvedServer().map(request => ({ operation: request.operation, state: request.state, ...(request.callerId ? { requestId: request.callerId } : {}) })) } : value;
+        });
+    }
+    async change(operation, parameters, callerId) {
+        const reserved = this.workspace.reserveAdministration('server.' + operation, parameters, 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;
+                fail('unknown', 'Administration outcome is retained and is not re-executed.', request.result);
+            }
+            const backend = await this.backend();
+            if (!backend.administration)
+                fail('configuration', 'Selected backend has no repository administration adapter.');
+            this.workspace.administrationState(request.id, 'running');
+            try {
+                const value = administrationResult(operation, parameters, await backend.administration(operation, parameters));
+                this.workspace.administrationState(request.id, 'applied', value);
+                return value;
+            }
+            catch (error) {
+                this.workspace.administrationState(request.id, 'unknown', { state: 'unknown', operation });
+                throw error;
+            }
+        });
+    }
+}
+const repo = { name: 'repository', type: 'string', required: true }, path = { name: 'path', type: 'string', required: false, default: '/' };
+const leaves = [
+    { names: ['status'], operation: 'status', gate: Permission.ReadOnly, params: [] },
+    { names: ['connect'], operation: 'connect', gate: Permission.Update, params: [] },
+    { names: ['disconnect'], operation: 'disconnect', gate: Permission.Update, params: [] },
+    { names: ['repositories', 'list'], operation: 'repositories', gate: Permission.ReadOnly, params: [] },
+    { names: ['repositories', 'create'], operation: 'create_repository', gate: Permission.Update, params: [repo] },
+    { names: ['repositories', 'files'], operation: 'files', gate: Permission.ReadOnly, params: [repo, path] },
+    { names: ['repositories', 'file'], operation: 'file', gate: Permission.ReadOnly, params: [repo, { ...path, required: true, default: undefined }] },
+    { names: ['history'], operation: 'history', gate: Permission.ReadOnly, params: [repo, { ...path, required: true, default: undefined }] },
+    { names: ['checkouts'], operation: 'checkouts', gate: Permission.ReadOnly, params: [repo, path] },
+    { names: ['admin', 'users'], operation: 'users', gate: Permission.ReadOnly, params: [] },
+    { names: ['admin', 'permissions'], operation: 'permissions', gate: Permission.ReadOnly, params: [repo] },
+    { names: ['admin', 'set-permissions'], operation: 'set_permissions', gate: 'Destructive', params: [repo, { name: 'user', type: 'string', required: true }, { name: 'access', type: 'string', required: true }] },
+    { names: ['admin', 'terminate-checkout'], operation: 'terminate_checkout', gate: 'Destructive', params: [repo, { ...path, required: true, default: undefined }, { name: 'checkout_id', type: 'string', required: false }] },
+    { names: ['admin', 'terminate-all-checkouts'], operation: 'terminate_all_checkouts', gate: 'Destructive', params: [repo, path] },
+];
+export function administrationCommands(service) {
+    const children = [];
+    for (const leaf of leaves) {
+        const changing = leaf.gate !== Permission.ReadOnly;
+        const definition = command(leaf.names.at(-1), 'Operate on the configured server and explicit repository', ({ options: o }, c) => {
+            const parameters = {};
+            for (const p of leaf.params) {
+                const value = o[key(p.name)];
+                if (value !== undefined)
+                    parameters[p.name] = parsed(p, value);
+            }
+            if (parameters.repository !== undefined)
+                parameters.repository = repository(parameters.repository);
+            if (parameters.path !== undefined)
+                parameters.path = repositoryPath(parameters.path);
+            if (parameters.checkout_id !== undefined && !/^\d+$/.test(String(parameters.checkout_id)))
+                fail('invalid', 'Checkout ID must be an exact decimal integer.');
+            if (parameters.access !== undefined) {
+                const level = String(parameters.access).toLowerCase().replaceAll('-', '_'), access = { read_only: 0, readonly: 0, read: 0, write: 1, admin: 2, '0': 0, '1': 1, '2': 2 }[level];
+                if (access === undefined)
+                    fail('invalid', 'Access must be read_only, write or admin.');
+                parameters.access = access;
+            }
+            return changing ? service(c).change(leaf.operation, parameters, o.requestId === undefined ? undefined : id(o.requestId)) : service(c).read(leaf.operation, parameters);
+        }, { permission: leaf.gate, options: [...leaf.params.map(option), ...(changing ? [{ flags: '--request-id <id>', description: 'Retrieve this administration outcome after a lost response' }] : [])] });
+        if (leaf.names.length === 1)
+            children.push(definition);
+        else {
+            const group = children.find(item => item.name === leaf.names[0]);
+            if (group)
+                group.children.push(definition);
+            else
+                children.push(command(leaf.names[0], `${leaf.names[0]} administration`, [definition]));
+        }
+    }
+    return [command('server', 'Configured server management', children)];
+}

package/dist/src/archive-contract.d.ts

@@ -0,0 +1,6 @@
+export declare function archiveOrigin(value: unknown): string;
+export declare function archivePayload(raw: unknown, binary: string, version: string, run: string): Record<string, unknown>;
+export declare function archivePost(fetch: typeof globalThis.fetch, origin: string, payload: Record<string, unknown>, token?: string, signal?: AbortSignal): Promise<{
+    created: boolean;
+    conflicts_enqueued: number;
+}>;

package/dist/src/archive-contract.js

@@ -0,0 +1,108 @@
+import { object, text, fail } from './model.js';
+import { address } from './research.js';
+import { parseDomainJson } from './json.js';
+export function archiveOrigin(value) {
+    let url;
+    try {
+        url = new URL(text(value, 2048));
+    }
+    catch {
+        fail('configuration', 'Configure an explicit archive URL.');
+    }
+    if (url.username || url.password || url.search || url.hash || url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)))
+        fail('configuration', 'Archive URL must use HTTPS or local HTTP, without credentials, query or fragment.');
+    return url.href.replace(/\/$/, '');
+}
+const integer = (value) => { if (!Number.isSafeInteger(value) || Number(value) < 0)
+    fail('partial', 'Archive count is invalid.'); return Number(value); };
+export function archivePayload(raw, binary, version, run) {
+    const p = object(raw);
+    if (p.binary_name !== binary || p.version !== version || p.source_run_id !== run || p.source_tool !== 'ghidra_mcp_ingest')
+        fail('binding', 'Archive payload selected another input or request.');
+    address(p.address);
+    text(p.name);
+    text(p.prototype, 65536);
+    if (typeof p.no_return !== 'boolean' || typeof p.is_thunk !== 'boolean')
+        fail('partial', 'Archive function metadata is incomplete.');
+    for (const key of ['function_size_bytes', 'instruction_count', 'basic_block_count'])
+        if (p[key] !== undefined)
+            integer(p[key]);
+    if (p.opcode_hash !== undefined && (typeof p.opcode_hash !== 'string' || !/^[a-f0-9]{64}$/.test(p.opcode_hash)))
+        fail('partial', 'Archive opcode hash is malformed.');
+    for (const key of ['plate_comment', 'calling_convention'])
+        if (p[key] !== undefined)
+            text(p[key], 65536);
+    if (p.function_tags !== undefined) {
+        if (!Array.isArray(p.function_tags) || p.function_tags.length > 10000)
+            fail('partial', 'Archive tags are malformed.');
+        for (const tag of p.function_tags)
+            text(tag);
+    }
+    for (const key of ['locals', 'instruction_comments'])
+        if (p[key] !== undefined) {
+            if (!Array.isArray(p[key]) || p[key].length > 10000)
+                fail('partial', 'Archive documentation is malformed.');
+            for (const rawRow of p[key]) {
+                const row = object(rawRow);
+                if (key === 'locals') {
+                    text(row.name);
+                    text(row.data_type);
+                    text(row.storage);
+                    text(row.source_type);
+                }
+                else {
+                    if (!Number.isSafeInteger(row.address_offset) || !['EOL', 'PRE', 'POST', 'REPEATABLE'].includes(String(row.type)))
+                        fail('partial', 'Archive instruction comment is malformed.');
+                    text(row.text, 65536);
+                }
+            }
+        }
+    if (Buffer.byteLength(JSON.stringify(p)) > 262144)
+        fail('limit', 'Archive function payload exceeds 256 KiB.');
+    return p;
+}
+export async function archivePost(fetch, origin, payload, token, signal) {
+    let response;
+    try {
+        response = await fetch(archiveOrigin(origin) + '/v1/doc_archive/upsert', { method: 'POST', redirect: 'error', signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30000)]) : AbortSignal.timeout(30000),
+            headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: 'Bearer ' + token } : {}) }, body: JSON.stringify(payload) });
+    }
+    catch {
+        fail('unknown', 'Archive response was lost; the request is retained and is not repeated.');
+    }
+    if (!response.ok) {
+        await response.body?.cancel();
+        fail('unknown', 'Archive rejected the request; its external outcome is retained.');
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        fail('partial', 'Archive response is empty.');
+    const parts = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 65536)
+                fail('limit', 'Archive response exceeds 64 KiB.');
+            parts.push(value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    let raw;
+    try {
+        raw = parseDomainJson(Buffer.concat(parts).toString('utf8'));
+    }
+    catch {
+        fail('partial', 'Archive response is not JSON.');
+    }
+    const result = object(raw);
+    if (typeof result.created !== 'boolean')
+        fail('partial', 'Archive response omits its created flag.');
+    const conflicts = integer(result.conflicts_enqueued);
+    return { created: result.created, conflicts_enqueued: conflicts };
+}

package/dist/src/archive.d.ts

@@ -0,0 +1,12 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { Workspace, type Scope } from './workspace.js';
+import { Research, type ResearchBackend } from './research.js';
+export declare class Archive {
+    private readonly workspace;
+    private readonly research;
+    private readonly backend;
+    private readonly c;
+    constructor(workspace: Workspace, research: Research, backend: () => Promise<ResearchBackend>, c: CommandContext);
+    ingest(selected: Scope, operation: 'function' | 'program', p: Record<string, unknown>, callerId?: string): Promise<unknown>;
+}
+export declare function archiveCommands(service: (c: CommandContext) => Archive): CommandDefinition[];

package/dist/src/archive.js

@@ -0,0 +1,116 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { scope, address, number } from './research.js';
+import { id, text, object, fail, digest } from './model.js';
+import { selectedOptions } from './arguments.js';
+import { archiveOrigin, archivePayload, archivePost } from './archive-contract.js';
+export class Archive {
+    workspace;
+    research;
+    backend;
+    c;
+    constructor(workspace, research, backend, c) {
+        this.workspace = workspace;
+        this.research = research;
+        this.backend = backend;
+        this.c = c;
+    }
+    async ingest(selected, operation, p, callerId) {
+        const origin = p.dry_run ? undefined : archiveOrigin(this.c.profile.values.archiveUrl);
+        const reserved = this.workspace.reserveAdministration('ghidra.archive.' + operation, { ...selected, ...p, ...(origin ? { origin } : {}) }, callerId);
+        return this.research.ordered(selected, async () => {
+            const request = this.workspace.administration(reserved.request.id);
+            if (reserved.replay && request.state !== 'accepted') {
+                if (request.state === 'applied')
+                    return request.result;
+                fail('unknown', 'Archive outcome is retained and no external requests are repeated.', request.result);
+            }
+            const backend = await this.backend();
+            await backend.open(selected);
+            if (!backend.archivePayloads)
+                fail('configuration', 'Selected backend lacks archive payload support.');
+            const snapshot = await backend.saved(selected), binary = this.workspace.target(selected.target).name, run = 'insight-cli-' + request.id;
+            const token = origin ? await this.c.secrets.get('archiveToken') : undefined;
+            const result = { ...selected, state: 'running', binary_name: binary, version: String(p.version), source_run_id: run, dry_run: Boolean(p.dry_run),
+                total_functions: 0, created: 0, updated: 0, conflicts_enqueued: 0, skipped_default_named: 0, errors: 0, truncated: false, first_errors: [] };
+            this.workspace.administrationState(request.id, 'running', { ...result, sourceSnapshot: snapshot });
+            let offset = 0, more = true;
+            const seen = new Set();
+            try {
+                const maximum = operation === 'function' ? 1 : Number(p.limit) || 100000;
+                while (more && offset < maximum) {
+                    const page = object(await backend.archivePayloads(selected, { ...(operation === 'function' ? { function: p.function } : {}), binary_name: binary, version: p.version, run_id: run,
+                        skip_default_named: operation === 'program' && p.skip_default_named === true, offset, limit: Math.min(10, maximum - offset) }));
+                    if (!Array.isArray(page.payloads) || !Number.isSafeInteger(page.visited) || Number(page.visited) < 0 || Number(page.visited) > Math.min(10, maximum - offset) || !Number.isSafeInteger(page.skipped) || Number(page.skipped) < 0 || page.payloads.length + Number(page.skipped) !== page.visited || typeof page.more !== 'boolean' || page.more && page.visited === 0)
+                        fail('partial', 'Archive payload inventory has inconsistent counts.');
+                    const payloads = page.payloads.map(raw => archivePayload(raw, binary, String(p.version), run));
+                    for (const payload of payloads) {
+                        const at = address(payload.address);
+                        if (seen.has(at))
+                            fail('partial', 'Archive inventory repeated a function.');
+                        seen.add(at);
+                    }
+                    if (operation === 'function' && (payloads.length !== 1 || address(payloads[0].address) !== address(p.function)))
+                        fail('binding', 'Archive selected another function.');
+                    result.skipped_default_named += Number(page.skipped);
+                    result.total_functions += Number(page.skipped);
+                    for (const payload of payloads) {
+                        result.total_functions++;
+                        if (p.dry_run) {
+                            result.created++;
+                            continue;
+                        }
+                        // Commit the exact outbound identity before a request can leave the process.
+                        this.workspace.administrationState(request.id, 'unknown', { ...result, sourceSnapshot: snapshot, pending: { address: payload.address, payloadSha256: digest(payload) } });
+                        try {
+                            const received = await archivePost(this.c.fetch, origin, payload, token, this.c.signal);
+                            if (received.created)
+                                result.created++;
+                            else
+                                result.updated++;
+                            result.conflicts_enqueued += received.conflicts_enqueued;
+                        }
+                        catch {
+                            result.errors++;
+                            if (result.first_errors.length < 10)
+                                result.first_errors.push({ address: String(payload.address), state: 'unknown' });
+                        }
+                        this.workspace.administrationState(request.id, 'unknown', { ...result, sourceSnapshot: snapshot });
+                        if (this.c.signal.aborted)
+                            fail('unknown', 'Archive submission was cancelled; completed and uncertain outcomes are retained.');
+                    }
+                    offset += Number(page.visited);
+                    more = page.more;
+                }
+                if (more && Number(p.limit) === 0)
+                    fail('limit', 'Archive selection exceeds 100000 functions; use an explicit bounded selection.');
+                result.truncated = more;
+                result.state = result.errors ? 'partial' : p.dry_run ? 'preview' : 'applied';
+                this.workspace.administrationState(request.id, result.errors ? 'unknown' : 'applied', result);
+                if (result.errors)
+                    fail('partial', 'Some archive outcomes are unknown; retained counts are not retried.', result);
+                return result;
+            }
+            catch (error) {
+                const current = this.workspace.administration(request.id);
+                if (current.state !== 'applied')
+                    this.workspace.administrationState(request.id, 'unknown', { ...result, state: 'unknown', sourceSnapshot: snapshot });
+                throw error;
+            }
+        });
+    }
+}
+export function archiveCommands(service) {
+    return [command('archive', 'Send selected private documentation to the configured archive', ['function', 'program'].map(operation => command('ingest-' + operation, 'Prepare documentation and retain every external request outcome', ({ options: o }, c) => {
+            const p = { version: text(o.versionLabel, 512), dry_run: Boolean(o.dryRun) };
+            if (operation === 'function')
+                p.function = address(o.address);
+            else {
+                p.limit = number(o.limit, 100000);
+                p.skip_default_named = !o.includeDefaultNamed;
+            }
+            return service(c).ingest(scope(o), operation, p, o.requestId === undefined ? undefined : id(o.requestId));
+        }, { permission: Permission.Update, options: [...selectedOptions,
+                ...(operation === 'function' ? [{ flags: '--address <address>', description: 'Selected function entry point', required: true }] : [{ flags: '--limit <count>', description: 'Maximum visited functions (0 means all, at most 100000)', defaultValue: 0 }, { flags: '--include-default-named', description: 'Include auto-named functions' }]),
+                { flags: '--version-label <name>', description: 'Archive version label', defaultValue: 'unknown' }, { flags: '--dry-run', description: 'Validate payloads without sending documentation' },
+                { flags: '--request-id <id>', description: 'Retrieve retained counts without repeating archive requests' }] })))];
+}

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;