@userreason/cli 0.1.1 → 0.2.0

package/dist/setup.js

@@ -0,0 +1,258 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { apiUrl } from './contracts.js';
+import { telemetryEnabled } from './telemetry.js';
+import { loadSetupSession, parseStoredSetup, saveSetupSession, setupProjectFingerprint, SetupError, } from './setup-store.js';
+import { parseSetupCapabilities, parseSetupDiscovery, parseSetupStartInput, parseSetupStartResult, parseSetupExchangeInput, parseSetupExchangeResult, parseSetupSession, parseSetupPollInput, parseSetupLocalPlanInput, parseSetupClaimInput, parseSetupClaimResult, parseSetupStartCommandInput, parseSetupCommandResultInput, parseSetupHeartbeatInput, parseSetupReconcileInput, parseSetupSampleReadInput, parseSetupSampleReadResult, parseSetupSourceInfoInput, parseSetupSourceInfo, parseSetupSourcePlanInput, parseSetupSourceUploadInput, } from './setup-wire.js';
+export class BrowserSetupUnavailable extends SetupError {
+    constructor() { super('browser_setup_unavailable', 'This API has not enabled browser setup v1. Continue with the existing terminal wizard.'); }
+}
+const terminal = new Set(['complete', 'cancelled', 'expired']);
+const retryable = new Set([429, 502, 503, 504]);
+function retryableNetwork(error) {
+    if (!(error instanceof Error))
+        return false;
+    const code = error.code ?? error.cause?.code;
+    if (code && !['ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN', 'ECONNREFUSED', 'ENETUNREACH', 'UND_ERR_CONNECT_TIMEOUT'].includes(code))
+        return false;
+    return error.name === 'TimeoutError' || error.name === 'AbortError' || error instanceof TypeError && error.message === 'fetch failed';
+}
+const failure = (status, data) => {
+    const code = typeof data === 'object' && data !== null ? data.error : null;
+    const nested = typeof code === 'object' && code !== null ? code.code : code;
+    const safe = typeof nested === 'string' && /^[a-z][a-z0-9_]{0,79}$/.test(nested) ? nested : 'setup_request_failed';
+    return new SetupError(safe, `Setup request failed (${status}, ${safe}). Resume this setup or review its status; no general CLI login was changed.`);
+};
+async function json(response) {
+    if (!response.headers.get('content-type')?.toLowerCase().startsWith('application/json') || !response.body)
+        throw new SetupError('invalid_setup_response', 'The setup service returned an invalid response.');
+    const reader = response.body.getReader(), chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const item = await reader.read();
+            if (item.done)
+                break;
+            size += item.value.byteLength;
+            if (size > 65_536) {
+                await reader.cancel();
+                throw new SetupError('setup_response_too_large', 'The setup response exceeded 64 KiB.');
+            }
+            chunks.push(item.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    try {
+        return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+    }
+    catch {
+        throw new SetupError('invalid_setup_response', 'The setup service returned invalid JSON.');
+    }
+}
+async function delay(ms, options) {
+    options.signal?.throwIfAborted();
+    if (options.sleep) {
+        await options.sleep(ms);
+        options.signal?.throwIfAborted();
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { options.signal?.removeEventListener('abort', aborted); resolve(); }, ms);
+        const aborted = () => { clearTimeout(timer); reject(options.signal?.reason ?? new Error('Setup cancelled')); };
+        options.signal?.addEventListener('abort', aborted, { once: true });
+    });
+}
+async function request(origin, operation, body, token, options, retries = 0) {
+    if (!['discovery', 'start', 'exchange', 'poll', 'plan', 'claim', 'start-command', 'report', 'heartbeat', 'reconcile', 'sample-read', 'source-info', 'source-plan', 'source-upload'].includes(operation))
+        throw new SetupError('invalid_setup_operation', 'Unsupported setup operation.');
+    const encoded = body === undefined ? undefined : JSON.stringify(body);
+    if (encoded && Buffer.byteLength(encoded) > 65_536)
+        throw new SetupError('setup_request_too_large', 'Setup request exceeds 64 KiB.');
+    const url = `${apiUrl(origin)}${operation === 'discovery' ? '/onboarding/v1/auth-config?setup=1' : `/onboarding/v1/setup/${operation}`}`;
+    // Preference reads are optional and bounded. Any read failure suppresses
+    // measurement, while the core setup request still proceeds normally.
+    const measurementDisabled = options.measurementDisabled === true || !await telemetryEnabled().catch(() => false);
+    for (let attempt = 0;; attempt++) {
+        options.signal?.throwIfAborted();
+        let response;
+        try {
+            response = await (options.fetcher ?? fetch)(url, {
+                method: encoded === undefined ? 'GET' : 'POST', redirect: 'error',
+                headers: { Accept: 'application/json', ...(encoded === undefined ? {} : { 'Content-Type': 'application/json' }), ...(token ? { Authorization: `Bearer ${token}` } : {}), ...(measurementDisabled ? { 'x-ur-measurement-disabled': '1' } : {}) },
+                ...(encoded === undefined ? {} : { body: encoded }),
+                signal: AbortSignal.any([AbortSignal.timeout(operation === 'source-upload' ? 50_000 : 10_000), ...(options.signal ? [options.signal] : [])]),
+            });
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            if (attempt < retries && retryableNetwork(error)) {
+                options.onProgress?.('retrying');
+                await delay(Math.min(15_000, 2_000 * 2 ** attempt), options);
+                continue;
+            }
+            throw new SetupError('setup_network_failed', 'Unable to reach the setup service. Retry this setup; local results and ordinary CLI credentials are unchanged.');
+        }
+        if (!response.ok && retryable.has(response.status) && attempt < retries) {
+            await response.body?.cancel();
+            options.onProgress?.('retrying');
+            await delay(Math.min(15_000, 2_000 * 2 ** attempt), options);
+            continue;
+        }
+        const data = await json(response);
+        if (!response.ok)
+            throw failure(response.status, data);
+        return data;
+    }
+}
+export async function discoverBrowserSetup(origin, options = {}) {
+    const data = await request(origin, 'discovery', undefined, undefined, options, 2);
+    // Released servers ignore ?setup=1 and return old auth-config. Only that exact
+    // legacy shape is unsupported; malformed claimed protocol data is an error.
+    if (data && typeof data === 'object' && !Array.isArray(data) && !('browser_setup' in data) && 'client_id' in data) {
+        const old = data;
+        let valid = false;
+        try {
+            valid = Object.keys(old).every(key => ['client_id', 'authkit_domain', 'environment'].includes(key)) &&
+                typeof old.client_id === 'string' && /^client_[A-Za-z0-9]{1,230}$/.test(old.client_id) &&
+                typeof old.authkit_domain === 'string' && apiUrl(old.authkit_domain) === old.authkit_domain && old.authkit_domain.startsWith('https://') &&
+                ['production', 'development', 'local'].includes(String(old.environment));
+        }
+        catch { /* Invalid old metadata is not a supported legacy response. */ }
+        if (valid)
+            throw new BrowserSetupUnavailable();
+    }
+    const discovery = parseSetupDiscovery(data);
+    if (!discovery.browser_setup.enabled)
+        throw new BrowserSetupUnavailable();
+    return discovery;
+}
+function browserOrigin(origin, configured) {
+    if (configured)
+        return apiUrl(configured, 'Setup browser origin');
+    if (origin === 'https://api.userreason.com')
+        return 'https://dash.userreason.com';
+    if (origin === 'https://api-dev.userreason.com')
+        return 'https://dash-dev.userreason.com';
+    throw new SetupError('setup_browser_origin_required', 'Configure a trusted dashboard origin for this nonstandard API before connecting browser setup.');
+}
+export function validateSetupBrowserUrl(value, expectedOrigin, challenge, now) {
+    let target;
+    try {
+        target = new URL(value.browser_url);
+    }
+    catch {
+        throw new SetupError('invalid_setup_response', 'Invalid setup browser URL.');
+    }
+    const query = [...target.searchParams], fragment = [...new URLSearchParams(target.hash.slice(1))];
+    const expiry = Date.parse(value.expires_at);
+    if (target.origin !== apiUrl(expectedOrigin) || target.username || target.password || target.pathname !== '/install' ||
+        query.length !== 1 || query[0]?.[0] !== 'setup' || query[0]?.[1] !== value.setup_id ||
+        fragment.length !== 1 || fragment[0]?.[0] !== 'request' || fragment[0]?.[1] !== value.ticket ||
+        expiry <= now || expiry > now + 901_000 || value.code !== challenge.slice(0, 8).toUpperCase())
+        throw new SetupError('invalid_setup_response', 'Invalid setup browser URL, verification code or expiry.');
+    return target.href;
+}
+/** The handshake never installs packages, edits source or grants management access. */
+export async function connectBrowserSetup(origin, input, onBrowser, options = {}) {
+    origin = apiUrl(origin);
+    const trustedBrowser = browserOrigin(origin, input.browserOrigin);
+    await discoverBrowserSetup(origin, options);
+    const verifier = randomBytes(32).toString('hex'), challenge = createHash('sha256').update(verifier).digest('hex');
+    const fingerprint = await setupProjectFingerprint(input.directory), now = options.now ?? Date.now;
+    const started = parseSetupStartResult(await request(origin, 'start', parseSetupStartInput({ schema_version: 1, challenge, project_fingerprint: fingerprint, capabilities: parseSetupCapabilities(input.capabilities) }), undefined, options));
+    const url = validateSetupBrowserUrl(started, trustedBrowser, challenge, now());
+    const pending = { schema_version: 1, state: 'pending', setup_id: started.setup_id, api_url: origin, project_fingerprint: fingerprint, created_at: new Date(now()).toISOString(), expires_at: started.expires_at, ticket: started.ticket, verifier };
+    await saveSetupSession(pending);
+    await onBrowser(url, started.code);
+    return finishBrowserSetup(pending, options);
+}
+async function finishBrowserSetup(pending, options) {
+    const now = options.now ?? Date.now, deadline = Math.min(Date.parse(pending.expires_at), now() + 600_000);
+    let attempts = 0;
+    while (now() < deadline && attempts++ < 301) {
+        const result = parseSetupExchangeResult(await request(pending.api_url, 'exchange', parseSetupExchangeInput({ schema_version: 1, setup_id: pending.setup_id, ticket: pending.ticket, verifier: pending.verifier }), undefined, options, 2));
+        if (result.status === 'rejected')
+            throw new SetupError('setup_rejected', 'Browser setup was declined. Existing installations, drafts and CLI credentials are unchanged.');
+        if (result.status === 'approved') {
+            if (result.session.setup_id !== pending.setup_id || result.session.project_fingerprint !== pending.project_fingerprint ||
+                Date.parse(result.expires_at) <= now() || Date.parse(result.expires_at) > now() + 7_201_000 ||
+                Date.parse(result.expires_at) > Date.parse(result.session.absolute_expires_at) || terminal.has(result.session.phase) || !/^ur-setup\.v1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(result.access_token))
+                throw new SetupError('invalid_setup_response', 'The approved setup response does not match this project or active session.');
+            const connected = { schema_version: 1, state: 'connected', setup_id: pending.setup_id, api_url: pending.api_url, project_fingerprint: pending.project_fingerprint, created_at: new Date(now()).toISOString(), expires_at: result.expires_at, access_token: result.access_token };
+            await saveSetupSession(connected);
+            return { client: new BrowserSetupClient(connected, options), session: result.session };
+        }
+        options.onProgress?.('waiting');
+        await delay(Math.max(0, Math.min(2_000, deadline - now())), options);
+    }
+    throw new SetupError('setup_expired', 'Browser setup approval timed out. Resume the same unexpired setup or start a new one.');
+}
+export async function resumeBrowserSetup(origin, setupId, directory, options = {}) {
+    const saved = await loadSetupSession(origin, setupId, directory, (options.now ?? Date.now)());
+    if (saved.state === 'pending')
+        return finishBrowserSetup(saved, options);
+    const client = new BrowserSetupClient(saved, options);
+    return { client, session: await client.poll() };
+}
+export class BrowserSetupClient {
+    #stored;
+    #options;
+    constructor(stored, options = {}) {
+        const valid = parseStoredSetup(stored);
+        if (valid.state !== 'connected')
+            throw new SetupError('invalid_setup_session', 'Expected a project-scoped setup capability, never a general CLI login.');
+        this.#stored = { ...valid };
+        this.#options = options;
+    }
+    /** Nonsecret identity for the local executor journal; never exposes the bearer. */
+    get identity() { const { setup_id, api_url, project_fingerprint, expires_at } = this.#stored; return { setup_id, api_url, project_fingerprint, expires_at }; }
+    async call(operation, body, retries = 0) {
+        if (Date.parse(this.#stored.expires_at) <= (this.#options.now ?? Date.now)())
+            throw new SetupError('setup_expired', 'Setup access expired. Start a new setup; it cannot be refreshed into ordinary CLI access.');
+        return request(this.#stored.api_url, operation, body, this.#stored.access_token, this.#options, retries);
+    }
+    scoped(input) {
+        const value = input;
+        if (value.setup_id !== this.#stored.setup_id || (value.project_fingerprint && value.project_fingerprint !== this.#stored.project_fingerprint) ||
+            (value.plan?.project_fingerprint && value.plan.project_fingerprint !== this.#stored.project_fingerprint))
+            throw new SetupError('setup_binding_mismatch', 'Setup operation targets another project or session.');
+    }
+    view(value) {
+        const session = parseSetupSession(value);
+        this.scoped(session);
+        return session;
+    }
+    async poll() { return this.view(await this.call('poll', parseSetupPollInput({ schema_version: 1, setup_id: this.#stored.setup_id }), 2)); }
+    async discovery() { return discoverBrowserSetup(this.#stored.api_url, this.#options); }
+    async sourceInfo() {
+        const result = parseSetupSourceInfo(await this.call('source-info', parseSetupSourceInfoInput({ schema_version: 1, setup_id: this.#stored.setup_id }), 2));
+        this.scoped(result.session);
+        return result;
+    }
+    async sourcePlan(input) { const body = parseSetupSourcePlanInput(input); this.scoped(body); return this.view(await this.call('source-plan', body)); }
+    async sourceUpload(input) { const body = parseSetupSourceUploadInput(input); this.scoped(body); return this.view(await this.call('source-upload', body)); }
+    async plan(input) { const body = parseSetupLocalPlanInput(input); this.scoped(body); return this.view(await this.call('plan', body)); }
+    async claim(input) {
+        const body = parseSetupClaimInput(input);
+        this.scoped(body);
+        const result = parseSetupClaimResult(await this.call('claim', body));
+        this.scoped(result.session);
+        if (result.command && result.command.executor_generation !== body.executor_generation)
+            throw new SetupError('invalid_setup_response', 'Claimed setup command has the wrong executor generation.');
+        return result;
+    }
+    async startCommand(input) { const body = parseSetupStartCommandInput(input); this.scoped(body); return this.view(await this.call('start-command', body)); }
+    async report(input) { const body = parseSetupCommandResultInput(input); this.scoped(body); return this.view(await this.call('report', body)); }
+    async heartbeat(input) { const body = parseSetupHeartbeatInput(input); this.scoped(body); return this.view(await this.call('heartbeat', body, 2)); }
+    async reconcile(input) { const body = parseSetupReconcileInput(input); this.scoped(body); return this.view(await this.call('reconcile', body)); }
+    async sample(requestId = randomUUID()) {
+        const active = await this.poll();
+        if (active.phase !== 'agent_test' || !['waiting', 'received'].includes(active.sample.status))
+            throw new SetupError('setup_sample_unavailable', 'This setup is not waiting for its optional sample read. Open that step in the browser first.');
+        const body = parseSetupSampleReadInput({ schema_version: 1, setup_id: this.#stored.setup_id, request_id: requestId });
+        const result = parseSetupSampleReadResult(await this.call('sample-read', body, 2));
+        this.scoped(result);
+        return result;
+    }
+}

package/dist/starter-survey.d.ts

@@ -0,0 +1,22 @@
+import { UserReasonClient } from './client.js';
+import { type FirstSurveyPreparation } from './first-survey-preparation.js';
+import { type FirstSurveyUI } from './first-survey.js';
+export type StarterGoal = 'improve' | 'friction' | 'satisfaction';
+type Definition = Record<string, unknown>;
+export declare function starterDefinition(goal: StarterGoal, product: string, focus?: string): Definition;
+/** Guided draft creation. Templates work without AI, source consent or provider availability. */
+export declare function starterSurvey(client: UserReasonClient, root: string, workspace: string, site: string, ui: FirstSurveyUI, options?: {
+    product?: string;
+    preparation?: FirstSurveyPreparation;
+}): Promise<{
+    state: string;
+    prompt_id: string;
+    result: unknown;
+} | {
+    state: string;
+    goal?: undefined;
+} | {
+    state: string;
+    goal: StarterGoal;
+}>;
+export {};