@eyeauras/insight-cli 0.0.0-stage → 0.2.0

package/dist/src/lifecycle.js

@@ -0,0 +1,154 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { scope } from './research.js';
+import { id, fail, object, digest } from './model.js';
+import { selectedOptions } from './arguments.js';
+export class Lifecycle {
+    workspace;
+    research;
+    backend;
+    constructor(workspace, research, backend) {
+        this.workspace = workspace;
+        this.research = research;
+        this.backend = backend;
+    }
+    async health(selected) {
+        return this.research.ordered(selected, async () => {
+            const backend = await this.backend();
+            await backend.open(selected);
+            const connection = object(await backend.call(selected, '/check_connection')), health = object(await backend.call(selected, '/mcp/health'));
+            if (connection.status !== 'ok' || health.status !== 'ok' || health.connected !== true || !['headless', 'gui'].includes(String(health.server_kind)))
+                fail('partial', 'Tool health did not verify the selected context.');
+            return { ...this.research.status(selected), health: { connected: true, mode: health.server_kind, version: health.version, memory: health.memory_mb } };
+        });
+    }
+    async change(selected, operation, callerId) {
+        const reserved = this.workspace.reserveRequest(selected, 'ghidra.' + operation, {}, 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;
+                fail('unknown', 'This lifecycle outcome is retained; it is not re-executed.', request.result);
+            }
+            const backend = await this.backend(), unresolved = this.workspace.unresolved(selected);
+            const closingExternal = operation === 'close' && unresolved.length > 0 && unresolved.every(intent => ['debugger', 'ui'].includes(String(object(intent.execution ?? {}).kind)));
+            const alreadyEnded = closingExternal && backend.closed ? await backend.closed(selected) : false;
+            if (!closingExternal)
+                await backend.open(selected);
+            const before = this.workspace.context(selected);
+            this.workspace.startRequest(request.id, { kind: operation, generation: before.generation, workingSnapshot: before.workingSnapshot });
+            let savedSnapshot;
+            try {
+                if (operation === 'close' && !alreadyEnded)
+                    await backend.close(selected);
+                const current = this.workspace.context(selected), snapshot = operation === 'save' ? await backend.saved(selected) : current.workingSnapshot;
+                if (!snapshot)
+                    fail('partial', 'Lifecycle operation did not retain its private snapshot.');
+                savedSnapshot = snapshot;
+                if (closingExternal && backend.closed && await backend.closed(selected))
+                    for (const intent of unresolved) {
+                        const before = this.workspace.context(selected), execution = object(intent.execution ?? {}), outcome = object(intent.result ?? {}), retained = outcome.savedDebugger;
+                        if (execution.kind === 'debugger' && before.generation === execution.generation) {
+                            const program = outcome.metadataChanged === true ? outcome.savedSnapshot : undefined;
+                            if (program)
+                                await this.workspace.artifacts.verify(program);
+                            for (const trace of retained?.traces ?? [])
+                                await this.workspace.artifacts.verify(trace.snapshot);
+                            if (retained || program)
+                                this.workspace.saveContext(selected, before.generation, { ...(retained ? { debugger: { ...retained, connected: false, traces: retained.traces.map(trace => ({ ...trace, connected: false })) } } : {}),
+                                    ...(program ? { workingSnapshot: program, complexChanges: before.complexChanges.includes(intent.id) ? before.complexChanges : [...before.complexChanges, intent.id] } : {}) });
+                        }
+                        this.workspace.recordRequest(intent.id, 'failed', { ...selected, state: 'disconnected', outcome: 'unknown', operation: object(intent.execution ?? {}).operation });
+                    }
+                const retained = this.workspace.context(selected);
+                const result = { ...selected, state: operation === 'save' ? 'saved' : 'closed', pendingChanges: retained.scalars.length + retained.complexChanges.length };
+                this.workspace.completeSavedRequest(selected, request.id, retained.generation, { workingSnapshot: operation === 'close' ? retained.workingSnapshot ?? snapshot : snapshot, ...(operation === 'close' ? { state: 'stopped',
+                        ...(retained.debugger ? { debugger: { ...retained.debugger, connected: false, traces: retained.debugger.traces.map(trace => ({ ...trace, connected: false })) } } : {}) } : {}) }, result);
+                return result;
+            }
+            catch (error) {
+                this.workspace.recordRequest(request.id, 'unknown', { ...selected, state: 'unknown', ...(savedSnapshot ? { savedSnapshot } : {}) });
+                throw error;
+            }
+        });
+    }
+    async discard(selected, callerId) {
+        const reserved = this.workspace.reserveRequest(selected, 'ghidra.changes.discard', {}, 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;
+                fail('unknown', 'Local discard outcome is retained; continue the context before retrieving it.', request.result);
+            }
+            const backend = await this.backend();
+            await backend.open(selected);
+            if (this.workspace.context(selected).debugger?.connected)
+                fail('busy', 'Close the live debugger context before discarding static program edits.');
+            // Resource save/release precedes the local atomic switch, as with mode preparation.
+            await backend.close(selected);
+            const context = this.workspace.context(selected);
+            if (!context.baseSnapshot || !context.workingSnapshot)
+                fail('binding', 'Discard requires retained base and private snapshots.');
+            await this.workspace.artifacts.verify(context.baseSnapshot);
+            const result = { ...selected, state: 'discarded', discardedChanges: context.scalars.length + context.complexChanges.length, pendingChanges: 0,
+                baseRevision: 'R' + context.baseRevision, discardedSnapshot: context.workingSnapshot };
+            this.workspace.startRequest(request.id, { kind: 'discard', generation: context.generation, baseSnapshot: context.baseSnapshot, discardedSnapshot: context.workingSnapshot, result });
+            this.workspace.completeSavedRequest(selected, request.id, context.generation, { workingSnapshot: context.baseSnapshot, state: 'stopped', viewEpoch: (context.viewEpoch ?? 0) + 1, scalars: [], complexChanges: [] }, result);
+            return result;
+        });
+    }
+    async saveAll(session, callerId) {
+        this.workspace.session(session);
+        const reserved = this.workspace.reserveAdministration('session.ghidra.save', { session }, callerId), request = this.workspace.administration(reserved.request.id);
+        if (reserved.replay && request.state !== 'accepted') {
+            if (request.state === 'applied')
+                return request.result;
+            fail('unknown', 'Session save outcomes are retained and are not repeated.', request.result);
+        }
+        const contexts = [];
+        for (let offset = 0;; offset += 100) {
+            const page = this.workspace.contexts(session, 100, offset);
+            contexts.push(...page);
+            if (page.length < 100)
+                break;
+            if (contexts.length >= 1000)
+                fail('limit', 'Session-wide save supports fewer than 1000 contexts; save explicitly selected contexts.');
+        }
+        const result = { session, state: 'saving', saved: 0, errors: 0, items: [] };
+        this.workspace.administrationState(request.id, 'running', result);
+        for (const context of contexts) {
+            const selected = { session, target: context.target };
+            this.workspace.administrationState(request.id, 'unknown', { ...result, pending: selected });
+            try {
+                const value = object(await this.change(selected, 'save', 'save-' + digest([request.id, context.id])));
+                result.items.push(value);
+                result.saved++;
+            }
+            catch {
+                result.items.push({ ...selected, state: 'unknown' });
+                result.errors++;
+            }
+            this.workspace.administrationState(request.id, 'unknown', result);
+        }
+        result.state = result.errors ? 'partial' : 'saved';
+        this.workspace.administrationState(request.id, result.errors ? 'unknown' : 'applied', result);
+        if (result.errors)
+            fail('partial', 'Some selected context saves need recovery; completed saves remain retained.', result);
+        return result;
+    }
+}
+export function lifecycleCommands(service, runtimeStatus) {
+    return [command('changes', 'Manage unpublished edits in the selected context', [
+            command('discard', 'Save a retained copy, then restore the opening base without publication', ({ options: o }, c) => service(c).discard(scope(o), o.requestId === undefined ? undefined : id(o.requestId)), { permission: 'Destructive', options: [...selectedOptions, { flags: '--request-id <id>', description: 'Retrieve the same local discard result' }] })
+        ]),
+        command('save-all', 'Save every Ghidra context in the explicit session; outcomes are per context', ({ options: o }, c) => service(c).saveAll(id(o.session), o.requestId === undefined ? undefined : id(o.requestId)), { permission: Permission.Update, options: [{ flags: '--session <id>', description: 'Explicit session whose contexts are saved', required: true }, { flags: '--request-id <id>', description: 'Retrieve the recorded session save outcomes' }] }),
+        command('status', 'Inspect the installed runtime, or verify a selected context', ({ options: o }, c) => {
+            if (o.session === undefined && o.target === undefined && runtimeStatus)
+                return runtimeStatus(c);
+            if (o.session === undefined || o.target === undefined)
+                fail('invalid', 'Context status requires both --session and --target.');
+            return service(c).health(scope(o));
+        }, { permission: Permission.ReadOnly, options: selectedOptions.map(option => ({ ...option, required: false })) }),
+        ...['save', 'close'].map(name => command(name, name === 'save' ? 'Save private work without publication' : 'Save and release the owned context; reopen retains local work', ({ options: o }, c) => service(c).change(scope(o), name, o.requestId === undefined ? undefined : id(o.requestId)), { permission: Permission.Update, options: [...selectedOptions, { flags: '--request-id <id>', description: 'Retrieve the lifecycle outcome after a lost response' }] }))];
+}

package/dist/src/memory-inputs.d.ts

@@ -0,0 +1,8 @@
+import type { ResearchBackend } from './research.js';
+import type { Artifact } from './artifacts.js';
+export declare function blockContent(p: Record<string, unknown>): {
+    size: number;
+    initialized: boolean;
+    sha256: string | null;
+};
+export declare function verifyMemoryCreation(backend: ResearchBackend, snapshot: Artifact, p: Record<string, unknown>): Promise<Record<string, unknown>>;

package/dist/src/memory-inputs.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { fail, object } from './model.js';
+import { address, number } from './research.js';
+export function blockContent(p) {
+    let bytes;
+    if (p.bytes_hex !== undefined && p.bytes_base64 !== undefined)
+        fail('invalid', 'Choose bytes-hex or bytes-base64, not both.');
+    if (p.bytes_hex !== undefined) {
+        const value = String(p.bytes_hex).replace(/\s/g, '');
+        if (!value || value.length > 33554432 || value.length % 2 || !/^[0-9a-f]+$/i.test(value))
+            fail('invalid', 'bytes-hex needs complete hex byte pairs, at most 16 MiB.');
+        bytes = Buffer.from(value, 'hex');
+    }
+    if (p.bytes_base64 !== undefined) {
+        const value = String(p.bytes_base64);
+        if (!value || value.length > 22369624 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value))
+            fail('invalid', 'bytes-base64 needs canonical padded base64, at most 16 MiB.');
+        bytes = Buffer.from(value, 'base64');
+        if (bytes.toString('base64') !== value)
+            fail('invalid', 'bytes-base64 is not canonical.');
+    }
+    const initialized = p.initialized !== false, fill = number(p.fill_byte ?? 0, 255), size = number(p.size ?? bytes?.length, 16777216, 1);
+    if (bytes && bytes.length > size)
+        fail('invalid', 'Initial content exceeds the requested block size.');
+    if (!initialized && (bytes || fill !== 0))
+        fail('invalid', 'Uninitialized blocks cannot have byte content or a nonzero fill byte.');
+    const content = initialized ? Buffer.alloc(size, fill) : undefined;
+    if (content && bytes)
+        bytes.copy(content);
+    return { size, initialized, sha256: content ? createHash('sha256').update(content).digest('hex') : null };
+}
+export async function verifyMemoryCreation(backend, snapshot, p) {
+    if (!backend.inspect)
+        fail('configuration', 'Memory creation needs immutable saved-state inspection.');
+    const expected = blockContent(p), value = object(await backend.inspect(snapshot, { kind: 'memory', name: p.name, digest_bytes: true }));
+    const equal = (actual, wanted, label) => { if (actual !== wanted)
+        fail('partial', `Saved memory ${label} differs from the requested effect.`); };
+    equal(value.exists, true, 'presence');
+    equal(value.name, p.name, 'name');
+    equal(value.size, expected.size, 'size');
+    equal(value.initialized, expected.initialized, 'initialization');
+    equal(value.overlay, p.overlay ?? false, 'overlay');
+    for (const flag of ['read', 'write', 'execute', 'volatile'])
+        equal(value[flag], p[flag] ?? ['read', 'write'].includes(flag), flag);
+    equal(value.comment ?? '', p.comment ?? '', 'comment');
+    equal(value.sha256, expected.sha256, 'content digest');
+    const at = address(p.address), actual = String(value.start);
+    if (p.overlay) {
+        equal(value.physicalStart !== undefined ? address(value.physicalStart) : undefined, at, 'physical start');
+        if (!actual.includes(':'))
+            fail('partial', 'Saved overlay lost its address-space identity.');
+    }
+    else
+        equal(address(actual), at, 'start');
+    return value;
+}

package/dist/src/merge.d.ts

@@ -0,0 +1,29 @@
+import type { ScalarChange } from './workspace.js';
+export declare const fieldKey: (change: Pick<ScalarChange, "address" | "field">) => string;
+export interface SharedScalar {
+    value: string | null;
+    compatible: boolean;
+}
+export interface FieldConflict {
+    address: string;
+    field: ScalarChange['field'];
+    original: string | null;
+    local: string | null;
+    shared: string | null;
+    reason: 'overlap' | 'dependency_changed';
+}
+export interface MergePlan {
+    state: 'publish' | 'conflict' | 'already_shared';
+    apply: ScalarChange[];
+    conflicts: FieldConflict[];
+    fullSnapshot: boolean;
+}
+/** Three-way decisions only; backend effects happen after the entire plan passes. */
+export declare function scalarMerge(changes: ScalarChange[], complex: boolean, baseRevision: number, sharedRevision: number, values: Record<string, SharedScalar>): MergePlan;
+export interface RefreshPlan {
+    receive: ScalarChange[];
+    preserve: ScalarChange[];
+    conflicts: FieldConflict[];
+}
+/** Incoming safe fields update a private view; conflicting local values remain explicit. */
+export declare function scalarRefresh(local: ScalarChange[], incoming: ScalarChange[], values: Record<string, SharedScalar>): RefreshPlan;

package/dist/src/merge.js

@@ -0,0 +1,66 @@
+import { fail } from './model.js';
+export const fieldKey = (change) => change.address + '@' + change.field;
+/** Three-way decisions only; backend effects happen after the entire plan passes. */
+export function scalarMerge(changes, complex, baseRevision, sharedRevision, values) {
+    if (sharedRevision < baseRevision)
+        fail('binding', 'Shared history regressed below the private baseline.');
+    // A verified complete private result can include fields changed by structural edits.
+    // Retained refresh conflicts still require their original/local/shared comparison.
+    if (complex && baseRevision === sharedRevision && !changes.some(change => change.conflict))
+        return { state: 'publish', apply: [...changes], conflicts: [], fullSnapshot: true };
+    const apply = [], conflicts = [];
+    for (const change of changes) {
+        const observed = values[fieldKey(change)];
+        if (!observed)
+            fail('partial', 'Shared comparison omitted a local field.');
+        if (!observed.compatible)
+            conflicts.push({ ...change, shared: observed.value, reason: 'dependency_changed' });
+        else if (observed.value === change.local)
+            continue;
+        else if (observed.value === change.original)
+            apply.push(change);
+        else
+            conflicts.push({ ...change, shared: observed.value, reason: 'overlap' });
+    }
+    if (complex && baseRevision !== sharedRevision)
+        return { state: 'conflict', apply: [], conflicts, fullSnapshot: true };
+    if (conflicts.length)
+        return { state: 'conflict', apply: [], conflicts, fullSnapshot: false };
+    return { state: apply.length || complex ? 'publish' : 'already_shared', apply, conflicts: [], fullSnapshot: baseRevision === sharedRevision };
+}
+/** Incoming safe fields update a private view; conflicting local values remain explicit. */
+export function scalarRefresh(local, incoming, values) {
+    const locals = new Map(local.map(change => [fieldKey(change), change]));
+    const preserve = local.map(change => ({ ...change })), receive = [], conflicts = [];
+    for (const change of incoming) {
+        const key = fieldKey(change), pending = locals.get(key), observed = values[key];
+        if (!observed)
+            fail('partial', 'Incoming comparison omitted a field.');
+        if (!observed.compatible) {
+            if (pending)
+                conflicts.push({ ...pending, shared: observed.value, reason: 'dependency_changed' });
+            continue;
+        }
+        if (!pending) {
+            receive.push({ ...change, local: observed.value });
+            continue;
+        }
+        if (observed.value === pending.local) {
+            const index = preserve.findIndex(item => fieldKey(item) === key);
+            preserve.splice(index, 1);
+        }
+        else if (observed.value !== pending.original)
+            conflicts.push({ ...pending, shared: observed.value, reason: 'overlap' });
+        else {
+            const preserved = preserve.find(item => fieldKey(item) === key);
+            if (preserved)
+                delete preserved.conflict;
+        }
+    }
+    for (const conflict of conflicts) {
+        const preserved = preserve.find(change => fieldKey(change) === fieldKey(conflict));
+        if (preserved)
+            preserved.conflict = { shared: conflict.shared };
+    }
+    return { receive, preserve, conflicts };
+}

package/dist/src/model.d.ts

@@ -0,0 +1,74 @@
+export type State = 'queued' | 'applying' | 'staged' | 'checking_in' | 'publication_unknown' | 'published_verified' | 'conflict_pending' | 'failed';
+export interface Identity {
+    profile: string;
+    server: string;
+    repository: string;
+    programPath: string;
+    binarySha256: string;
+    language: string;
+    compilerSpec: string;
+    imageBase: string;
+}
+export interface Target extends Identity {
+    id: string;
+    lane: string;
+}
+export type CommentKind = 'eol' | 'pre' | 'post' | 'plate' | 'repeatable';
+export interface Finding {
+    requestId: string;
+    findingId: string;
+    targetId: string;
+    identity: Identity;
+    workerId: string;
+    baselineVersion: number;
+    address: string;
+    kind: CommentKind;
+    before: string | null;
+    after: string;
+    evidence: string;
+    resolves?: string;
+}
+export interface FindingRecord extends Finding {
+    state: State;
+    batchId?: string;
+    conflict?: unknown;
+}
+export interface Binding {
+    pid: number;
+    endpoint: string;
+    projectDirectory: string;
+    identity: Identity;
+    version: number;
+    role: 'reader' | 'publisher';
+    bridgeSecret?: string;
+    bridgePid?: number;
+    readEpoch?: string;
+    openingVersion?: number;
+}
+export interface Batch {
+    id: string;
+    targetId: string;
+    state: State;
+    ownerPid: number;
+    binding?: Binding;
+    baselineVersion?: number;
+    publishedVersion?: number;
+    findings: FindingRecord[];
+    detail?: unknown;
+}
+export interface Snapshot {
+    identity: Identity;
+    version: number;
+    values: Record<string, string | null>;
+}
+export declare const key: (f: Pick<Finding, "address" | "kind">) => string;
+export declare const stable: (value: unknown) => string;
+export declare const digest: (value: unknown) => string;
+export declare function fail(code: string, message: string, result?: unknown): never;
+export declare function object(value: unknown): Record<string, unknown>;
+export declare function text(value: unknown, max?: number): string;
+export declare function id(value: unknown): string;
+export declare function version(value: unknown): number;
+export declare function identity(value: unknown): Identity;
+export declare function assertIdentity(actual: Identity, expected: Identity): void;
+export declare function finding(value: unknown): Finding;

package/dist/src/model.js

@@ -0,0 +1,67 @@
+import { createHash } from 'node:crypto';
+import { CliError } from '@eyeauras/cli-factory';
+export const key = (f) => `${f.address}:${f.kind}`;
+export const stable = (value) => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+    ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b))) : item);
+export const digest = (value) => createHash('sha256').update(stable(value)).digest('hex');
+export function fail(code, message, result) {
+    throw new CliError(message, { code: `coordinator.${code}`, ...(result === undefined ? {} : { result }) });
+}
+export function object(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail('invalid', 'Expected a JSON object.');
+    return value;
+}
+export function text(value, max = 512) {
+    if (typeof value !== 'string' || !value.length || value.length > max || /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(value))
+        fail('invalid', 'Expected a bounded non-empty string.');
+    return value;
+}
+export function id(value) {
+    const result = text(value, 128);
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(result))
+        fail('invalid', 'ID must use letters, digits, dot, underscore or hyphen.');
+    return result;
+}
+export function version(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1)
+        fail('invalid', 'Version must be a positive integer.');
+    return value;
+}
+export function identity(value) {
+    const o = object(value);
+    const result = {
+        profile: text(o.profile), server: text(o.server), repository: text(o.repository),
+        programPath: text(o.programPath), binarySha256: text(o.binarySha256).toLowerCase(),
+        language: text(o.language), compilerSpec: text(o.compilerSpec), imageBase: text(o.imageBase).toLowerCase(),
+    };
+    if (!/^ghidra:\/\/[^/]+$/.test(result.server) || /[@?#]/.test(result.server))
+        fail('invalid', 'Server must be a ghidra://host:port origin without credentials.');
+    if (/[\\/]/.test(result.repository) || result.repository.startsWith('.'))
+        fail('invalid', 'Repository name must be a single non-hidden component.');
+    if (!result.programPath.startsWith('/') || result.programPath.split('/').slice(1).some(p => !p || p.startsWith('.')))
+        fail('invalid', 'Program path must be absolute with non-hidden components.');
+    if (!/^[a-f0-9]{64}$/.test(result.binarySha256) || !/^[a-f0-9]+$/.test(result.imageBase))
+        fail('invalid', 'SHA256 or image base is malformed.');
+    return result;
+}
+export function assertIdentity(actual, expected) {
+    if (stable(identity(actual)) !== stable(identity(expected)))
+        fail('binding', 'Program, binary or connection identity does not match.');
+}
+export function finding(value) {
+    const o = object(value);
+    const kind = text(o.kind);
+    if (!['eol', 'pre', 'post', 'plate', 'repeatable'].includes(kind))
+        fail('invalid', 'Only scoped comment operations are supported.');
+    const address = text(o.address).toLowerCase();
+    if (!/^(?:[a-z0-9_]+:)?[a-f0-9]+$/.test(address))
+        fail('invalid', 'An explicit hexadecimal address is required.');
+    const comment = (v) => v === null ? null : typeof v === 'string' && v.length <= 16000 && !v.includes('\0') ? v : fail('invalid', 'Comment must be a string or null.');
+    return {
+        requestId: id(o.requestId), findingId: id(o.findingId), targetId: id(o.targetId),
+        identity: identity(o.identity), workerId: id(o.workerId), baselineVersion: version(o.baselineVersion),
+        address, kind, before: comment(o.before), after: text(o.after, 16000), evidence: text(o.evidence, 4000),
+        ...(o.resolves === undefined ? {} : { resolves: id(o.resolves) }),
+    };
+}

package/dist/src/mutation-effects.d.ts

@@ -0,0 +1,4 @@
+import type { ResearchBackend } from './research.js';
+import type { Artifact } from './artifacts.js';
+/** Effect assertions run against an immutable saved program, not the response's success flag. */
+export declare function verifyMutation(backend: ResearchBackend, snapshot: Artifact, path: string, p: Record<string, unknown>, response: Record<string, unknown>): Promise<Record<string, unknown>>;