@eyeauras/insight-cli 0.0.0-stage → 0.1.0

package/dist/src/version-tracking.js

@@ -0,0 +1,200 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { mkdir, readFile, open, rename, realpath, lstat, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { scope, address, number } from './research.js';
+import { id, text, object, fail, stable } from './model.js';
+import { selectedOptions } from './arguments.js';
+import { randomUUID } from 'node:crypto';
+async function persist(path, value) { const temp = path + '.new-' + randomUUID(), file = await open(temp, 'wx', 0o600); try {
+    await file.writeFile(stable(value));
+    await file.sync();
+}
+finally {
+    await file.close();
+} await rename(temp, path); }
+/** A native VT object belongs to an existing research session; it is not another agent session. */
+export class VersionTracking {
+    workspace;
+    research;
+    backend;
+    tasks;
+    constructor(workspace, research, backend, tasks) {
+        this.workspace = workspace;
+        this.research = research;
+        this.backend = backend;
+        this.tasks = tasks;
+    }
+    async ordered(tracking, action) { const key = 'vt:' + tracking, 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 root(tracking) {
+        id(tracking);
+        if (!/^vt_a_[a-zA-Z0-9-]+$/.test(tracking))
+            fail('invalid', 'Invalid Version Tracking object ID.');
+        const root = join(this.workspace.directory, 'version-tracking', tracking);
+        if (await realpath(root) !== resolve(root) || (await lstat(root)).isSymbolicLink())
+            fail('binding', 'VT object left its owned storage.');
+        return root;
+    }
+    async owner(selected, tracking) {
+        const root = await this.root(tracking), owner = object(JSON.parse(await readFile(join(root, 'owner.json'), 'utf8')));
+        if (owner.schema !== 1 || owner.tracking !== tracking || owner.profile !== this.workspace.profile || owner.destination.session !== selected.session || owner.destination.target !== selected.target)
+            fail('binding', 'VT object belongs to another research scope.');
+        await this.workspace.artifacts.verify(owner.sourceSnapshot);
+        await this.workspace.artifacts.verify(owner.destinationSnapshot);
+        return { root, owner };
+    }
+    response(owner, value) {
+        return { ...owner.destination, tracking: owner.tracking, source: { ...owner.source, snapshotSha256: owner.sourceSnapshot.sha256 }, destination: { ...owner.destination, snapshotSha256: owner.destinationSnapshot.sha256 },
+            sourceContextChanged: this.workspace.context(owner.source).generation !== owner.sourceGeneration, destinationContextChanged: this.workspace.context(owner.destination).generation !== owner.destinationGeneration, value };
+    }
+    async native(operation, root, p) { const backend = await this.backend(); if (!backend.sdkFile)
+        fail('configuration', 'Native VT is unavailable.'); return backend.sdkFile('vt.' + operation, { ...p, root }); }
+    async list(selected, offset, limit) {
+        this.workspace.context(selected);
+        const parent = join(this.workspace.directory, 'version-tracking');
+        let entries;
+        try {
+            entries = await readdir(parent, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return { ...selected, items: [], complete: true };
+            throw error;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        const items = [];
+        let index = offset, visited = 0;
+        for (; index < entries.length && items.length < limit && visited < 1000; index++, visited++) {
+            const entry = entries[index];
+            if (!entry.isDirectory() || !/^vt_a_[a-zA-Z0-9-]+$/.test(entry.name))
+                fail('binding', 'VT inventory contains an unexpected storage entry.');
+            const root = await this.root(entry.name);
+            let owner;
+            try {
+                owner = JSON.parse(await readFile(join(root, 'owner.json'), 'utf8'));
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                fail('binding', 'VT owner record is malformed; retained storage requires inspection.');
+            }
+            if (owner.profile !== this.workspace.profile || owner.destination.session !== selected.session || owner.destination.target !== selected.target)
+                continue;
+            items.push({ tracking: entry.name, source: owner.source, destination: owner.destination, sourceSnapshotSha256: owner.sourceSnapshot.sha256, destinationSnapshotSha256: owner.destinationSnapshot.sha256 });
+        }
+        return { ...selected, items, visited, complete: index === entries.length, ...(index < entries.length ? { nextOffset: index } : {}) };
+    }
+    decisionResult(request, owner, value) {
+        const result = this.response(owner, value);
+        if (object(value).state === 'rejected') {
+            this.workspace.administrationState(request, 'failed', result);
+            fail('rejected', 'Native association constraints rejected this decision; its transaction was rolled back.', result);
+        }
+        this.workspace.administrationState(request, 'applied', result);
+        return result;
+    }
+    async create(selected, source, callerId) {
+        const reserved = this.workspace.reserveAdministration('sdk.vt.create', { ...selected, source }, callerId), tracking = 'vt_' + reserved.request.id;
+        return this.research.paired(selected, source, () => this.ordered(tracking, async () => {
+            const request = this.workspace.administration(reserved.request.id);
+            if (reserved.replay && request.state !== 'accepted') {
+                if (request.state === 'applied')
+                    return request.result;
+                const { root, owner } = await this.owner(selected, tracking);
+                let receipt;
+                try {
+                    receipt = object(JSON.parse(await readFile(join(root, 'created.json'), 'utf8')));
+                }
+                catch {
+                    fail('unknown', 'VT creation is retained without a completed receipt; it is not repeated.');
+                }
+                if (receipt.request !== request.id || receipt.operation !== 'create')
+                    fail('binding', 'VT creation receipt differs.');
+                const result = this.response(owner, receipt.value);
+                this.workspace.administrationState(request.id, 'applied', result);
+                return result;
+            }
+            const backend = await this.backend();
+            await backend.open(selected);
+            await backend.open(source);
+            const sourceSnapshot = await backend.saved(source), destinationSnapshot = await backend.saved(selected), root = join(this.workspace.directory, 'version-tracking', tracking);
+            await mkdir(root, { recursive: true, mode: 0o700 });
+            if (await realpath(root) !== resolve(root))
+                fail('binding', 'VT storage moved.');
+            const owner = { schema: 1, tracking, profile: this.workspace.profile, source, destination: selected, sourceSnapshot, destinationSnapshot,
+                sourceGeneration: this.workspace.context(source).generation, destinationGeneration: this.workspace.context(selected).generation };
+            await persist(join(root, 'owner.json'), owner);
+            this.workspace.administrationState(request.id, 'running', { tracking });
+            try {
+                const value = await this.native('create', root, { request_id: request.id, source_snapshot: await this.workspace.artifacts.verify(sourceSnapshot), destination_snapshot: await this.workspace.artifacts.verify(destinationSnapshot), receipt: join(root, 'created.json') });
+                const result = this.response(owner, value);
+                this.workspace.administrationState(request.id, 'applied', result);
+                return result;
+            }
+            catch (error) {
+                this.workspace.administrationState(request.id, 'unknown', { ...selected, tracking, state: 'unknown' });
+                throw error;
+            }
+        }));
+    }
+    async read(selected, tracking, operation, p) { return this.ordered(tracking, async () => { const { root, owner } = await this.owner(selected, tracking); return this.response(owner, await this.native(operation, root, p)); }); }
+    async decide(selected, tracking, p, callerId) {
+        const reserved = this.workspace.reserveAdministration('sdk.vt.decide', { ...selected, tracking, ...p }, callerId);
+        return this.ordered(tracking, async () => {
+            const request = this.workspace.administration(reserved.request.id), { root, owner } = await this.owner(selected, tracking), receipts = join(root, 'decisions');
+            await mkdir(receipts, { recursive: true, mode: 0o700 });
+            const receiptPath = join(receipts, request.id + '.json');
+            if (reserved.replay && request.state !== 'accepted') {
+                if (request.state === 'applied')
+                    return request.result;
+                if (request.state === 'failed')
+                    fail('rejected', 'The native association decision was rejected and is not repeated.', request.result);
+                let receipt;
+                try {
+                    receipt = object(JSON.parse(await readFile(receiptPath, 'utf8')));
+                }
+                catch {
+                    fail('unknown', 'VT decision is uncertain and is not repeated.');
+                }
+                if (receipt.request !== request.id || receipt.operation !== 'decide')
+                    fail('binding', 'VT decision receipt differs.');
+                return this.decisionResult(request.id, owner, receipt.value);
+            }
+            if (this.workspace.unresolvedSessionAdministration(selected.session, selected.target).some(earlier => earlier.id !== request.id && object(object(earlier.intent).parameters).tracking === tracking))
+                fail('blocked', 'An earlier decision on this VT object is unresolved.');
+            this.workspace.administrationState(request.id, 'running', { ...selected, tracking });
+            try {
+                const value = await this.native('decide', root, { ...p, request_id: request.id, receipt: receiptPath });
+                return this.decisionResult(request.id, owner, value);
+            }
+            catch (error) {
+                if (this.workspace.administration(request.id).state !== 'failed')
+                    this.workspace.administrationState(request.id, 'unknown', { ...selected, tracking, state: 'unknown' });
+                throw error;
+            }
+        });
+    }
+}
+export function trackingCommands(service) {
+    const tracking = { flags: '--tracking <id>', description: 'Native VT object returned by create', required: true }, request = { flags: '--request-id <id>', description: 'Retrieve a retained native decision without repeating it' }, association = [{ flags: '--source-address <address>', description: 'Source address in this VT snapshot', required: true }, { flags: '--destination-address <address>', description: 'Destination address in this VT snapshot', required: true }];
+    return [command('version-tracking', 'Native source/destination match sets, association decisions and markup inventory', [
+            command('list', 'List VT objects owned by this destination research scope, including retained creation stages', ({ options: o }, c) => service(c).list(scope(o), number(o.offset, 1000000), number(o.limit, 1000, 1)), { permission: Permission.ReadOnly, options: [...selectedOptions, { flags: '--limit <count>', description: 'Maximum returned owned VT objects', defaultValue: 100 }, { flags: '--offset <count>', description: 'Inventory offset; use nextOffset after a partial scan', defaultValue: 0 }] }),
+            command('create', 'Correlate immutable source/destination snapshots in a persistent owned native VT project', ({ options: o }, c) => {
+                const selected = scope(o), source = { session: o.sourceSession === undefined ? selected.session : id(o.sourceSession), target: id(o.sourceTarget) };
+                return service(c).create(selected, source, o.requestId === undefined ? undefined : id(o.requestId));
+            }, { permission: Permission.Update, options: [...selectedOptions, { flags: '--source-target <id>', description: 'Source immutable target', required: true }, { flags: '--source-session <id>', description: 'Source research session (default destination session)' }, request] }),
+            command('matches', 'Read native match sets and correlator-specific scores from the saved VT object', ({ options: o }, c) => service(c).read(scope(o), id(o.tracking), 'matches', { limit: number(o.limit, 1000, 1), offset: number(o.offset, 100000) }), { permission: Permission.ReadOnly, options: [...selectedOptions, tracking, { flags: '--limit <count>', description: 'Match page size 1–1000', defaultValue: 100 }, { flags: '--offset <count>', description: 'Page offset', defaultValue: 0 }] }),
+            command('markup', 'Inspect native markup values for one association before agent-directed edits', ({ options: o }, c) => service(c).read(scope(o), id(o.tracking), 'markup', { source_address: address(o.sourceAddress), destination_address: address(o.destinationAddress) }), { permission: Permission.ReadOnly, options: [...selectedOptions, tracking, ...association] }),
+            command('decide', 'Explicitly accept/reject/reset one native association; native one-to-one constraints apply', ({ options: o }, c) => {
+                const decision = text(o.decision);
+                if (!['accepted', 'rejected', 'available'].includes(decision))
+                    fail('invalid', 'Decision must be accepted, rejected or available.');
+                return service(c).decide(scope(o), id(o.tracking), { source_address: address(o.sourceAddress), destination_address: address(o.destinationAddress), decision }, o.requestId === undefined ? undefined : id(o.requestId));
+            }, { permission: Permission.Update, options: [...selectedOptions, tracking, ...association, { flags: '--decision <state>', description: 'accepted, rejected or available', required: true }, request] }),
+        ])];
+}

package/dist/src/workspace.d.ts

@@ -0,0 +1,199 @@
+import { Artifacts, type Artifact } from './artifacts.js';
+export interface ResearchTarget {
+    id: string;
+    name: string;
+    binarySha256: string;
+    size: number;
+    input: Artifact;
+    createdAt: string;
+}
+export interface ResearchSession {
+    id: string;
+    createdAt: string;
+}
+export interface GhidraLoadSettings {
+    autoAnalyze: boolean;
+    language?: string;
+    compilerSpec?: string;
+    imageBase?: string;
+    loader?: string;
+    loaderOptions?: Record<string, string | number | boolean>;
+}
+export interface GhidraModel {
+    target: string;
+    settings: GhidraLoadSettings;
+    state: 'opening' | 'ready' | 'unknown';
+    sharedRevision?: number;
+    sharedSnapshot?: Artifact;
+}
+export interface Scope {
+    session: string;
+    target: string;
+}
+export interface ScalarChange {
+    address: string;
+    field: 'function.name' | 'comment.eol' | 'comment.pre' | 'comment.post' | 'comment.plate' | 'comment.repeatable';
+    original: string | null;
+    local: string | null;
+    /** The field ceased to exist in a retained complex program result. Never a scalar setter. */
+    removed?: true;
+    dependency?: string;
+    conflict?: {
+        shared: string | null;
+    };
+}
+export interface SyncPolicy {
+    publish: 'manual' | 'after-edit' | 'after-save';
+    refresh: 'manual' | 'before-edit';
+}
+export interface GhidraContext extends Scope {
+    /** Internal storage key, never a caller's backend selector. */
+    id: string;
+    tool: 'ghidra';
+    state: 'opening' | 'ready' | 'stopped' | 'needs_recovery';
+    generation: number;
+    baseRevision?: number;
+    baseSnapshot?: Artifact;
+    workingSnapshot?: Artifact;
+    viewEpoch?: number;
+    scalars: ScalarChange[];
+    complexChanges: string[];
+    debugger?: DebuggerState;
+    syncPolicy?: SyncPolicy;
+}
+export interface SavedTrace {
+    id: string;
+    name: string;
+    snapshot: Artifact;
+    snap: string;
+    modules: number;
+    threads: number;
+    connected: boolean;
+    thread?: string;
+}
+export interface DebuggerState {
+    traces: SavedTrace[];
+    active?: string;
+    connected: boolean;
+}
+export type RequestState = 'accepted' | 'running' | 'applied' | 'failed' | 'unknown';
+export interface AdministrationRequest {
+    id: string;
+    operation: string;
+    intent: unknown;
+    state: RequestState;
+    callerId?: string;
+    result?: unknown;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ResearchRequest {
+    id: string;
+    callerId?: string;
+    operation: string;
+    intent: unknown;
+    context: string;
+    state: RequestState;
+    result?: unknown;
+    execution?: unknown;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Publication extends Scope {
+    id: string;
+    request: string;
+    state: 'preparing' | 'commit_intent' | 'unknown' | 'verified' | 'conflict';
+    expectedRevision: number;
+    snapshot: Artifact;
+    generation: number;
+    scalars: ScalarChange[];
+    complex: boolean;
+    complexChanges?: string[];
+    publishedRevision?: number;
+    detail?: unknown;
+}
+export interface OpenReservation {
+    context: GhidraContext;
+    request: ResearchRequest;
+    replay: boolean;
+}
+type ContextPatch = Partial<Pick<GhidraContext, 'state' | 'baseRevision' | 'baseSnapshot' | 'workingSnapshot' | 'viewEpoch' | 'scalars' | 'complexChanges' | 'debugger' | 'syncPolicy'>>;
+/** Profile root state, deliberately separate from the earlier coordinator.sqlite journals. */
+export declare class Workspace {
+    readonly profile: string;
+    readonly directory: string;
+    readonly artifacts: Artifacts;
+    private readonly db;
+    private namespace;
+    constructor(directory: string, profile: string);
+    close(): void;
+    private transaction;
+    private rememberArtifact;
+    private knownSnapshot;
+    captureSnapshot(path: string): Promise<Artifact>;
+    importTarget(path: string): Promise<ResearchTarget>;
+    target(target: string): ResearchTarget;
+    targets(limit?: number, offset?: number): ResearchTarget[];
+    session(session: string): ResearchSession;
+    sessions(limit?: number, offset?: number): ResearchSession[];
+    model(target: string): GhidraModel;
+    context(scope: Scope): GhidraContext;
+    contexts(session: string, limit?: number, offset?: number): GhidraContext[];
+    private existingRequest;
+    private insertRequest;
+    reserveOpen(target: string, session: string | 'new', settings: GhidraLoadSettings, callerId?: string, mode?: 'headless' | 'gui'): OpenReservation;
+    reserveRequest(scope: Scope, operation: string, parameters: unknown, callerId?: string): {
+        request: ResearchRequest;
+        replay: boolean;
+    };
+    request(request: string): ResearchRequest;
+    reserveAdministration(operation: string, parameters: unknown, callerId?: string): {
+        request: AdministrationRequest;
+        replay: boolean;
+    };
+    administrationByCaller(callerId: string): AdministrationRequest | undefined;
+    requestByCaller(callerId: string): ResearchRequest | undefined;
+    administration(request: string): AdministrationRequest;
+    unresolvedAdministration(): AdministrationRequest[];
+    unresolvedSessionAdministration(session: string, target?: string): AdministrationRequest[];
+    unresolvedServer(): AdministrationRequest[];
+    unresolvedProject(project: string): AdministrationRequest[];
+    administrationState(request: string, state: Exclude<RequestState, 'accepted'>, result?: unknown): AdministrationRequest;
+    unresolved(scope: Scope): ResearchRequest[];
+    startRequest(request: string, execution?: unknown): ResearchRequest;
+    recordRequest(request: string, state: 'applied' | 'failed' | 'unknown', result: unknown): ResearchRequest;
+    private writeRequest;
+    establishModel(target: string, revision: number, snapshot: Artifact): GhidraModel;
+    beginModelInitialization(target: string): GhidraModel;
+    observeShared(target: string, revision: number, snapshot: Artifact): GhidraModel;
+    publication(publication: string): Publication;
+    activePublication(target: string): Publication | undefined;
+    beginPublication(scope: Scope, request: string, expectedRevision: number, snapshot: Artifact): Publication;
+    publicationIntent(publication: string): Publication;
+    unknownPublication(publication: string, detail: unknown): {
+        state: "unknown";
+        detail: unknown;
+        id: string;
+        request: string;
+        expectedRevision: number;
+        snapshot: Artifact;
+        generation: number;
+        scalars: ScalarChange[];
+        complex: boolean;
+        complexChanges?: string[];
+        publishedRevision?: number;
+        session: string;
+        target: string;
+    };
+    finishPublication(publication: string, publishedRevision: number, result: unknown): Publication;
+    rejectPublication(publication: string, result: unknown): Publication;
+    publishedSince(target: string, revision: number): Publication[];
+    saveContext(scope: Scope, expectedGeneration: number, patch: ContextPatch): GhidraContext;
+    /** Snapshot and successful request acknowledgment enter the same durable transaction. */
+    completeSavedRequest(scope: Scope, request: string, expectedGeneration: number, patch: ContextPatch, result: unknown): {
+        context: GhidraContext;
+        request: ResearchRequest;
+    };
+    private writeContext;
+}
+export {};