@userreason/cli 0.1.1 → 0.2.1

package/dist/setup-files.js

@@ -0,0 +1,96 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath } from 'node:fs/promises';
+import { join, relative, resolve, sep } from 'node:path';
+import { SetupError } from './setup-store.js';
+export const setupHash = (value) => createHash('sha256').update(value).digest('hex');
+export function setupCanonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(setupCanonical).join(',')}]`;
+    if (value && typeof value === 'object')
+        return `{${Object.entries(value).filter(([, v]) => v !== undefined).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${setupCanonical(v)}`).join(',')}}`;
+    return JSON.stringify(value);
+}
+export const setupDigest = (value) => setupHash(setupCanonical(value));
+/** All paths are project relative. Refuse links, hard links and escaping ancestors. */
+async function checkedPath(directory, name, createParents = false) {
+    const root = await realpath(directory);
+    if (!name || name.length > 240 || /[\\:\x00-\x1f\x7f]/.test(name) || name.split('/').some(p => !p || p === '.' || p === '..'))
+        throw new SetupError('setup_path_unsafe', 'The reviewed path must be inside the original real project directory.');
+    const target = resolve(root, name);
+    if (relative(root, target).startsWith(`..${sep}`))
+        throw new SetupError('setup_path_unsafe', 'The reviewed path escapes the project.');
+    let parent = root;
+    for (const part of name.split('/').slice(0, -1)) {
+        parent = join(parent, part);
+        let info = await lstat(parent).catch(error => { if (error.code === 'ENOENT')
+            return null; throw error; });
+        if (!info && createParents) {
+            await mkdir(parent);
+            info = await lstat(parent);
+        }
+        if (!info)
+            return target;
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new SetupError('setup_path_unsafe', 'A reviewed directory was replaced or is a link.');
+    }
+    return target;
+}
+export async function readSetupFile(directory, path) {
+    const target = await checkedPath(directory, path);
+    let before;
+    try {
+        before = await lstat(target);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size > 2_000_000)
+        throw new SetupError('setup_path_unsafe', 'A reviewed file is not a bounded ordinary file.');
+    const handle = await open(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const current = await handle.stat();
+        if (before.dev !== current.dev || before.ino !== current.ino || current.nlink !== 1 || current.size > 2_000_000)
+            throw new SetupError('setup_path_unsafe', 'A reviewed file changed while reading.');
+        const bytes = await handle.readFile();
+        if (bytes.length > 2_000_000)
+            throw new SetupError('setup_path_unsafe', 'A reviewed file exceeds the size limit.');
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function writeSetupFile(directory, file) {
+    // Verify drift before creating even a parent directory for a planned file.
+    if (await readSetupFile(directory, file.path) !== file.before)
+        throw new SetupError('setup_files_changed', 'The reviewed file changed. Review a new plan before applying it.');
+    const target = await checkedPath(directory, file.path, true);
+    if (await readSetupFile(directory, file.path) !== file.before)
+        throw new SetupError('setup_files_changed', 'The reviewed file changed. Review a new plan before applying it.');
+    if (file.before === file.after)
+        return;
+    const info = file.before === null ? null : await lstat(target);
+    const handle = await open(target, info ? constants.O_WRONLY | (constants.O_NOFOLLOW ?? 0) : constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o644);
+    try {
+        const now = await handle.stat();
+        if (!now.isFile() || now.nlink !== 1 || info && (now.dev !== info.dev || now.ino !== info.ino))
+            throw new SetupError('setup_files_changed', 'The reviewed file changed while opening.');
+        if (info && await readSetupFile(directory, file.path) !== file.before)
+            throw new SetupError('setup_files_changed', 'The reviewed file changed while opening.');
+        await handle.writeFile(file.after);
+        await handle.truncate(Buffer.byteLength(file.after));
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function verifySetupFiles(directory, files, state) {
+    for (const file of files)
+        if (await readSetupFile(directory, file.path) !== file[state])
+            return false;
+    return true;
+}

package/dist/setup-heartbeat.d.ts

@@ -0,0 +1,268 @@
+import type { BrowserSetupClient } from './setup.js';
+import type { SetupSessionView } from './setup-wire.js';
+/** Stop waiting when this run ends, including user-supplied preparations. */
+export declare function setupAbortable<T>(work: Promise<T>, signal?: AbortSignal): Promise<T>;
+/** One lease-aware heartbeat for the entire run, independent of its current stage. */
+export declare class SetupHeartbeat {
+    private client;
+    private options;
+    private session?;
+    private timer?;
+    private pending?;
+    private stopped;
+    private paused;
+    private failure?;
+    private lease?;
+    private readonly lifetime;
+    readonly signal: AbortSignal;
+    constructor(client: Pick<BrowserSetupClient, 'identity' | 'heartbeat'>, options?: {
+        signal?: AbortSignal;
+        heartbeatMs?: number;
+    });
+    observe(next: SetupSessionView): SetupSessionView;
+    get current(): ({
+        phase: "expired" | "cancelled" | "analyzing" | "configuring" | "awaiting_local_approval" | "applying" | "ready_for_recommendations" | "selecting_drafts" | "creating_drafts" | "agent_test" | "complete";
+        revision: string;
+        workspace_id: string | null;
+        site_id: string | null;
+        project_fingerprint: string;
+        choices: {
+            install_sdk: boolean;
+            install_skill: boolean;
+            footer_badge: boolean;
+        } & {};
+        capabilities: {
+            framework: string;
+            package_manager: string;
+            install_packages: boolean;
+            initialize_sdk: boolean;
+            install_skill: boolean;
+            insert_footer: boolean;
+            source_review: boolean;
+            sample_read: boolean;
+        } & {
+            onboarding_v2?: boolean | undefined;
+            project_name?: string | undefined;
+            launcher?: ({
+                wizard_version: string;
+                api_origin: string;
+            } & {
+                registry?: string | undefined;
+            }) | undefined;
+            terminal?: ({
+                platform: string;
+                app: string;
+            } & {}) | undefined;
+        };
+        local_plan: ({
+            project_fingerprint: string;
+            choices_digest: string;
+            effects: import("./setup-wire.js").SetupEffect[];
+        } & {
+            manual_steps?: ({
+                kind: "install_packages" | "initialize_sdk" | "install_skill" | "insert_footer";
+                code: string;
+            } & {})[] | undefined;
+        }) | null;
+        plan_digest: string | null;
+        commands: ({
+            operation_id: string;
+            sequence: number;
+            kind: "install_packages" | "initialize_sdk" | "install_skill" | "insert_footer";
+            expected_revision: string;
+            input: import("./setup-wire.js").SetupEffect;
+            input_digest: string;
+            approval_digest: string;
+            status: "approved" | "manual" | "cancelled" | "failed" | "outcome_unknown" | "prepared" | "leased" | "running" | "succeeded";
+            executor_generation: number | null;
+            lease_generation: number;
+            lease_expires_at: string | null;
+            result: ({
+                code: "cancelled" | "skipped" | "already_present" | "unsupported" | "operation_failed" | "verified" | "review_required" | "dependency_failed" | "outcome_unknown";
+            } & {
+                verified?: boolean | undefined;
+            }) | null;
+            result_digest: string | null;
+            created_at: string;
+            started_at: string | null;
+            finished_at: string | null;
+            updated_at: string;
+        } & {})[];
+        executor_generation: number;
+        connection: string;
+        heartbeat_at: string | null;
+        sample: {
+            status: string;
+            first_received_at: string | null;
+            latest_received_at: string | null;
+            latest_request_id: string | null;
+        } & {};
+        draft_outcomes: ({
+            candidate_id: string;
+            status: string;
+            prompt_id: string;
+            request_id: string;
+            revision: string | null;
+            code: "cancelled" | "skipped" | "already_present" | "unsupported" | "operation_failed" | "verified" | "review_required" | "dependency_failed" | "outcome_unknown" | null;
+        } & {})[];
+        bound_at: string;
+        last_activity_at: string;
+        idle_expires_at: string;
+        absolute_expires_at: string;
+        terminal_at: string | null;
+        schema_version: 1;
+        setup_id: string;
+    } & {
+        source?: ({
+            preparation_id: string;
+            status: string;
+            packet_digest: string;
+            provider_fingerprint: string;
+            authorized_at: string | null;
+            expires_at: string;
+            error_code: "operation_failed" | "planning_unavailable" | "planning_paused" | "planning_daily_budget" | "planning_allowance_exhausted" | "planning_provider_unavailable" | "planning_policy_changed" | "planning_consent_expired" | "planning_input_budget" | "planning_invalid_output" | "planning_timeout" | "source_changed" | "source_unavailable" | "recommendations_no_source" | null;
+        } & {
+            analysis_id?: string | undefined;
+            analysis_started_at?: string | undefined;
+            analysis_completed_at?: string | undefined;
+            deadline_at?: string | undefined;
+            timings?: ({} & {
+                extraction_ms?: number | undefined;
+                consolidation_ms?: number | undefined;
+                authoring_ms?: number | undefined;
+                total_ms?: number | undefined;
+            }) | undefined;
+        }) | null | undefined;
+        recommendation_digest?: string | null | undefined;
+        selected_candidates?: string[] | undefined;
+    }) | undefined;
+    setLease(lease: {
+        operation_id: string;
+        executor_generation: number;
+        lease_generation: number;
+    }): void;
+    latest(fallback: SetupSessionView): {
+        phase: "expired" | "cancelled" | "analyzing" | "configuring" | "awaiting_local_approval" | "applying" | "ready_for_recommendations" | "selecting_drafts" | "creating_drafts" | "agent_test" | "complete";
+        revision: string;
+        workspace_id: string | null;
+        site_id: string | null;
+        project_fingerprint: string;
+        choices: {
+            install_sdk: boolean;
+            install_skill: boolean;
+            footer_badge: boolean;
+        } & {};
+        capabilities: {
+            framework: string;
+            package_manager: string;
+            install_packages: boolean;
+            initialize_sdk: boolean;
+            install_skill: boolean;
+            insert_footer: boolean;
+            source_review: boolean;
+            sample_read: boolean;
+        } & {
+            onboarding_v2?: boolean | undefined;
+            project_name?: string | undefined;
+            launcher?: ({
+                wizard_version: string;
+                api_origin: string;
+            } & {
+                registry?: string | undefined;
+            }) | undefined;
+            terminal?: ({
+                platform: string;
+                app: string;
+            } & {}) | undefined;
+        };
+        local_plan: ({
+            project_fingerprint: string;
+            choices_digest: string;
+            effects: import("./setup-wire.js").SetupEffect[];
+        } & {
+            manual_steps?: ({
+                kind: "install_packages" | "initialize_sdk" | "install_skill" | "insert_footer";
+                code: string;
+            } & {})[] | undefined;
+        }) | null;
+        plan_digest: string | null;
+        commands: ({
+            operation_id: string;
+            sequence: number;
+            kind: "install_packages" | "initialize_sdk" | "install_skill" | "insert_footer";
+            expected_revision: string;
+            input: import("./setup-wire.js").SetupEffect;
+            input_digest: string;
+            approval_digest: string;
+            status: "approved" | "manual" | "cancelled" | "failed" | "outcome_unknown" | "prepared" | "leased" | "running" | "succeeded";
+            executor_generation: number | null;
+            lease_generation: number;
+            lease_expires_at: string | null;
+            result: ({
+                code: "cancelled" | "skipped" | "already_present" | "unsupported" | "operation_failed" | "verified" | "review_required" | "dependency_failed" | "outcome_unknown";
+            } & {
+                verified?: boolean | undefined;
+            }) | null;
+            result_digest: string | null;
+            created_at: string;
+            started_at: string | null;
+            finished_at: string | null;
+            updated_at: string;
+        } & {})[];
+        executor_generation: number;
+        connection: string;
+        heartbeat_at: string | null;
+        sample: {
+            status: string;
+            first_received_at: string | null;
+            latest_received_at: string | null;
+            latest_request_id: string | null;
+        } & {};
+        draft_outcomes: ({
+            candidate_id: string;
+            status: string;
+            prompt_id: string;
+            request_id: string;
+            revision: string | null;
+            code: "cancelled" | "skipped" | "already_present" | "unsupported" | "operation_failed" | "verified" | "review_required" | "dependency_failed" | "outcome_unknown" | null;
+        } & {})[];
+        bound_at: string;
+        last_activity_at: string;
+        idle_expires_at: string;
+        absolute_expires_at: string;
+        terminal_at: string | null;
+        schema_version: 1;
+        setup_id: string;
+    } & {
+        source?: ({
+            preparation_id: string;
+            status: string;
+            packet_digest: string;
+            provider_fingerprint: string;
+            authorized_at: string | null;
+            expires_at: string;
+            error_code: "operation_failed" | "planning_unavailable" | "planning_paused" | "planning_daily_budget" | "planning_allowance_exhausted" | "planning_provider_unavailable" | "planning_policy_changed" | "planning_consent_expired" | "planning_input_budget" | "planning_invalid_output" | "planning_timeout" | "source_changed" | "source_unavailable" | "recommendations_no_source" | null;
+        } & {
+            analysis_id?: string | undefined;
+            analysis_started_at?: string | undefined;
+            analysis_completed_at?: string | undefined;
+            deadline_at?: string | undefined;
+            timings?: ({} & {
+                extraction_ms?: number | undefined;
+                consolidation_ms?: number | undefined;
+                authoring_ms?: number | undefined;
+                total_ms?: number | undefined;
+            }) | undefined;
+        }) | null | undefined;
+        recommendation_digest?: string | null | undefined;
+        selected_candidates?: string[] | undefined;
+    };
+    check(): void;
+    private schedule;
+    pulse(): Promise<void>;
+    /** Finish the old lease's in-flight heartbeat before closing it in a report. */
+    duringReport<T>(operation: () => Promise<T>): Promise<T>;
+    stop(): Promise<void>;
+}
+/** Observe all responses; cancel outstanding reads/source work when the run ends. */
+export declare function observeSetupClient<T extends object>(client: T, heartbeat: SetupHeartbeat, signal?: AbortSignal): T;

package/dist/setup-heartbeat.js

@@ -0,0 +1,120 @@
+const terminal = new Set(['complete', 'cancelled', 'expired']);
+/** Stop waiting when this run ends, including user-supplied preparations. */
+export function setupAbortable(work, signal) {
+    if (!signal)
+        return work;
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener('abort', abort, { once: true });
+        work.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    });
+}
+/** One lease-aware heartbeat for the entire run, independent of its current stage. */
+export class SetupHeartbeat {
+    client;
+    options;
+    session;
+    timer;
+    pending;
+    stopped = false;
+    paused = 0;
+    failure;
+    lease;
+    lifetime = new AbortController();
+    signal;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.options = options;
+        this.signal = AbortSignal.any([this.lifetime.signal, ...(options.signal ? [options.signal] : [])]);
+    }
+    observe(next) {
+        const current = this.session;
+        if (!current || BigInt(next.revision) >= BigInt(current.revision)) {
+            const heartbeat = current?.heartbeat_at && (!next.heartbeat_at || Date.parse(current.heartbeat_at) > Date.parse(next.heartbeat_at)) ? current.heartbeat_at : next.heartbeat_at;
+            this.session = { ...next, heartbeat_at: heartbeat };
+        }
+        if (terminal.has(this.session.phase) && !this.signal.aborted)
+            this.lifetime.abort(new Error('Setup ended'));
+        if (!this.stopped && !this.timer && !this.pending && !this.paused && !terminal.has(this.session.phase))
+            this.schedule(0);
+        return this.session;
+    }
+    get current() { return this.session; }
+    setLease(lease) { this.lease = lease; }
+    latest(fallback) { return this.observe(fallback); }
+    check() { this.options.signal?.throwIfAborted(); if (this.failure)
+        throw this.failure; }
+    schedule(delay = this.options.heartbeatMs ?? 10000) {
+        if (this.stopped || this.paused || !this.session || terminal.has(this.session.phase) || this.signal.aborted)
+            return;
+        this.timer = setTimeout(() => { this.timer = undefined; void this.pulse(); }, delay);
+    }
+    async pulse() {
+        if (this.pending)
+            return this.pending;
+        if (this.stopped || this.paused || this.signal.aborted || !this.session || terminal.has(this.session.phase))
+            return;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        const session = this.session;
+        this.pending = setupAbortable(this.client.heartbeat({ schema_version: 1, setup_id: this.client.identity.setup_id, executor_generation: session.executor_generation,
+            operation_id: this.lease?.operation_id ?? null, lease_generation: this.lease?.lease_generation ?? null }), this.signal)
+            .then(value => { this.observe(value); })
+            .catch(error => { if (!this.stopped && !this.options.signal?.aborted) {
+            this.failure = error;
+            this.lifetime.abort(error);
+        } })
+            .finally(() => { this.pending = undefined; this.schedule(); });
+        return this.pending;
+    }
+    /** Finish the old lease's in-flight heartbeat before closing it in a report. */
+    async duringReport(operation) {
+        this.paused++;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        try {
+            await this.pending;
+            this.lease = undefined;
+            return await operation();
+        }
+        finally {
+            this.paused--;
+            this.schedule();
+        }
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.lifetime.abort(new Error('Setup run ended'));
+        await this.pending;
+    }
+}
+/** Observe all responses; cancel outstanding reads/source work when the run ends. */
+export function observeSetupClient(client, heartbeat, signal) {
+    return new Proxy(client, { get(target, key, receiver) {
+            const value = Reflect.get(target, key, target);
+            if (typeof value !== 'function')
+                return value;
+            if (key === 'withSignal')
+                return value.bind(target);
+            return async (...args) => {
+                // Reports settle already-recorded effects, including a cancelled operation.
+                if (key !== 'report')
+                    signal?.throwIfAborted();
+                // Acknowledged mutations remain acknowledged if cancellation races their
+                // response. Reads and the long source upload can stop waiting immediately.
+                const requestSignal = ['poll', 'discovery', 'sourceInfo', 'sourceUpload'].includes(String(key)) ? signal : undefined;
+                const result = await setupAbortable(Reflect.apply(value, target, args), requestSignal);
+                const view = result && typeof result === 'object' && 'session' in result ? result.session : result;
+                if (view && typeof view === 'object' && 'phase' in view && 'revision' in view && typeof view.phase === 'string' && typeof view.revision === 'string')
+                    heartbeat.observe(view);
+                return result;
+            };
+        } });
+}

package/dist/setup-runner.d.ts

@@ -0,0 +1,16 @@
+import { type BrowserSetupClient } from './setup.js';
+import { type SetupExecutorOptions, type SetupExecutorRuntime } from './setup-executor.js';
+import { type PreparedSetupSource } from './setup-source.js';
+import { type SetupSessionView } from './setup-wire.js';
+export interface BrowserSetupRunnerOptions extends SetupExecutorOptions {
+    automaticSetup?: boolean;
+    preparedSource?: Promise<PreparedSetupSource | null>;
+    onSourceIssue?: (code: string) => void;
+    /** Local display only. Never forward this callback's source content to telemetry. */
+    onSourcePrepared?: (packet: PreparedSetupSource) => void;
+    onSample?: (session: SetupSessionView) => void;
+}
+export type BrowserSetupRunnerClient = Pick<BrowserSetupClient, 'identity' | 'poll' | 'plan' | 'claim' | 'startCommand' | 'report' | 'heartbeat' | 'reconcile' | 'discovery' | 'sourceInfo' | 'sourcePlan' | 'sourceUpload'> & Partial<Pick<BrowserSetupClient, 'withSignal'>>;
+/** Browser controls consent and drafts. This runner holds only the setup capability,
+ * executes reviewed local effects, and uploads the separately approved source packet. */
+export declare function runBrowserSetup(client: BrowserSetupRunnerClient, directory: string, runtime: SetupExecutorRuntime, options?: BrowserSetupRunnerOptions): Promise<SetupSessionView>;