@userreason/cli 0.1.1 → 0.2.0

package/dist/starter-survey.js

@@ -0,0 +1,457 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { mkdir, open, rename, unlink, lstat, writeFile, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { configDirectory } from './config.js';
+import { sourceHash, verifyFirstSurveySource } from './first-survey-source.js';
+import { prepareFirstSurveyLocally } from './first-survey-preparation.js';
+const goals = [
+    { value: 'improve', label: 'Find opportunities to improve' },
+    { value: 'friction', label: 'Understand difficulties in a workflow' },
+    { value: 'satisfaction', label: 'Measure satisfaction' },
+];
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const blockedAudience = () => ({ type: 'not', rule: { type: 'always' } });
+const cleanText = (text, maximum) => text.trim().length > 0 && text.trim().length <= maximum && !/[\u0000-\u001f\u007f]/.test(text);
+const digest = (value) => sourceHash(JSON.stringify(value));
+export function starterDefinition(goal, product, focus = 'this workflow') {
+    const question = goal === 'satisfaction'
+        ? `How satisfied are you with ${product} overall?`
+        : goal === 'friction'
+            ? `What, if anything, made ${focus} difficult?`
+            : `What, if anything, would make ${product} more useful to you?`;
+    return {
+        schema_version: 1,
+        name: `${goals.find((g) => g.value === goal).label}: ${product}`.slice(0, 240),
+        priority: 0,
+        sampling_percent: 10,
+        enrollment_epoch: 'first-survey-v1',
+        content: {
+            schema_version: 1,
+            title: 'Help us improve',
+            description: null,
+            thank_you: null,
+            questions: [
+                goal === 'satisfaction'
+                    ? {
+                        id: 'first',
+                        kind: 'rating',
+                        prompt: question,
+                        required: false,
+                        min: 1,
+                        max: 5,
+                        min_label: 'Very dissatisfied',
+                        max_label: 'Very satisfied',
+                        labels: [
+                            'Very dissatisfied',
+                            'Dissatisfied',
+                            'Neither satisfied nor dissatisfied',
+                            'Satisfied',
+                            'Very satisfied',
+                        ],
+                    }
+                    : { id: 'first', kind: 'text', prompt: question, required: false, max_length: 2000 },
+            ],
+        },
+        // A saved starter cannot match anyone until the author configures targeting.
+        rules: {
+            schema_version: 1,
+            audience: blockedAudience(),
+            triggers: [{ type: 'page_load' }],
+            frequency: { mode: 'site_default' },
+        },
+    };
+}
+function suggestion(definition, reason, sources = []) {
+    const content = record(definition.content), questions = content.questions;
+    if (!Array.isArray(questions) || questions.length !== 1)
+        throw Error('A starter needs exactly one question');
+    const q = record(questions[0]);
+    if (typeof q.prompt !== 'string' ||
+        !cleanText(q.prompt, 300) ||
+        !['text', 'rating'].includes(String(q.kind)))
+        throw Error('Unsupported starter question');
+    const copy = structuredClone(definition);
+    // AI proposes wording, not verified runtime targeting. The author configures that separately.
+    copy.rules = {
+        schema_version: 1,
+        audience: blockedAudience(),
+        triggers: [{ type: 'page_load' }],
+        frequency: { mode: 'site_default' },
+    };
+    return { question: q.prompt, definition: copy, reason, sources };
+}
+function preview(s) {
+    const q = record(record(s.definition.content).questions[0]);
+    const response = q.kind === 'rating' && Array.isArray(q.labels)
+        ? `Optional rating: ${q.labels.join(' · ')}`
+        : 'Optional written answer';
+    return `${s.reason}\nQuestion: ${s.question}\n${response}`;
+}
+function abortable(work, signal) {
+    return new Promise((resolve, reject) => {
+        const aborted = () => reject(signal.reason ?? new Error('Cancelled'));
+        signal.addEventListener('abort', aborted, { once: true });
+        work.then((value) => {
+            signal.removeEventListener('abort', aborted);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', aborted);
+            reject(error);
+        });
+        if (signal.aborted)
+            aborted();
+    });
+}
+/** Guided draft creation. Templates work without AI, source consent or provider availability. */
+export async function starterSurvey(client, root, workspace, site, ui, options = {}) {
+    ui.signal?.throwIfAborted();
+    root = await realpath(root);
+    const preparation = options.preparation?.root === root ? options.preparation : prepareFirstSurveyLocally(root);
+    const directory = join(configDirectory(), 'starter-survey');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    if ((await lstat(directory)).isSymbolicLink())
+        throw Error('Unsafe starter session directory');
+    const path = join(directory, digest([root, client.config.apiUrl, workspace, site]) + '.json');
+    const lock = await open(path + '.lock', 'wx', 0o600).catch(() => {
+        preparation.cancel();
+        throw Error('Another first-survey process owns this session');
+    });
+    let state = {
+        version: 1,
+        root,
+        api: client.config.apiUrl,
+        workspace,
+        site,
+        expires: Date.now() + 7 * 86400000,
+        product: options.product && cleanText(options.product, 120) ? options.product.trim() : 'this product',
+        focus: 'this workflow',
+    };
+    const save = async () => {
+        const temp = path + '.' + randomUUID() + '.tmp';
+        await writeFile(temp, JSON.stringify(state), { flag: 'wx', mode: 0o600 });
+        await rename(temp, path);
+    };
+    let ai = {
+        status: 'idle',
+        suggestions: [],
+    };
+    let work, controller, analysisId;
+    const check = () => ui.signal?.throwIfAborted();
+    const scope = { api: client.config.apiUrl, workspace_id: workspace, site_id: site };
+    const stopAI = async () => {
+        controller?.abort();
+        if (analysisId && ai.status !== 'ready') {
+            await client
+                .request('/onboarding/v1/planning/cancel', { schema_version: 1, session_id: analysisId, scope }, AbortSignal.timeout(1500))
+                .catch(() => { });
+        }
+        await work;
+        analysisId = undefined;
+        ai = { status: 'idle', suggestions: [] };
+    };
+    const text = async (message, fallback, max = 300) => {
+        for (;;) {
+            check();
+            const answer = (await ui.answer(message)).trim() || fallback;
+            if (cleanText(answer, max))
+                return answer;
+            ui.show(`Use between 1 and ${max} characters on one line.`);
+        }
+    };
+    const showSaved = (result, id) => {
+        const value = record(result), links = record(value.links);
+        ui.show(`Draft saved. ${String(links.edit ?? id)}\nIt is unpublished. Review the audience and timing in the editor before launching.`);
+    };
+    const create = async () => {
+        check();
+        const receipt = state.receipt;
+        if (!receipt.result)
+            receipt.result = await client.promptCommand({
+                workspaceId: workspace,
+                siteId: site,
+                action: 'create',
+                promptId: receipt.prompt,
+                requestId: receipt.request,
+                definition: receipt.definition,
+            });
+        await save();
+        showSaved(receipt.result, receipt.prompt);
+        return { state: 'saved', prompt_id: receipt.prompt, result: receipt.result };
+    };
+    try {
+        try {
+            const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await file.stat();
+                if (stat.size > 128000)
+                    throw Error('Starter session too large');
+                const old = JSON.parse(await file.readFile('utf8'));
+                if (old.version !== 1 ||
+                    old.root !== root ||
+                    old.api !== state.api ||
+                    old.workspace !== workspace ||
+                    old.site !== site)
+                    throw Error('Starter session scope changed');
+                if (old.expires > Date.now())
+                    state = old;
+            }
+            finally {
+                await file.close();
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (state.receipt) {
+            if (state.receipt.result) {
+                showSaved(state.receipt.result, state.receipt.prompt);
+                return { state: 'saved', prompt_id: state.receipt.prompt, result: state.receipt.result };
+            }
+            ui.show('The previous save was not confirmed. Retrying uses the same draft and request IDs.');
+            if (!(await ui.confirm('Retry saving the already-reviewed draft?')))
+                return { state: 'save_pending' };
+            return await create();
+        }
+        if (!state.goal || !state.selected) {
+            const goal = await ui.choose('What would you like to learn?', [
+                ...goals,
+                { value: 'finish', label: 'Finish setup for now' },
+            ]);
+            if (goal === 'finish')
+                return { state: 'skipped' };
+            if (!goals.some((g) => g.value === goal))
+                throw Error('Unknown learning goal');
+            state.goal = goal;
+            if (state.goal === 'friction')
+                state.focus = await text('Which workflow? For example, creating a report (blank: using this product)', `using ${state.product}`, 120);
+            state.selected = suggestion(starterDefinition(state.goal, state.product, state.focus), 'A starter question. You can use or edit it now.');
+            await save();
+        }
+        for (;;) {
+            check();
+            const selected = state.selected;
+            ui.show(preview(selected));
+            const action = await ui.choose('Your first survey', [
+                { value: 'use', label: 'Use this question' },
+                { value: 'edit', label: 'Edit the question' },
+                ...(ai.status === 'abstained' ? [] : ai.status === 'ready'
+                    ? [{ value: 'review_ai', label: 'Review AI suggestions' }]
+                    : ai.status === 'pending'
+                        ? [{ value: 'check_ai', label: 'Check personalization — starter remains available' }]
+                        : [
+                            {
+                                value: 'personalize',
+                                label: ai.status === 'failed'
+                                    ? 'Retry AI personalization (optional)'
+                                    : 'Personalize with AI (optional)',
+                            },
+                        ]),
+                { value: 'more', label: 'Other goals or finish later' },
+            ]);
+            if (action === 'edit') {
+                const question = await text('Your question (blank: keep current wording)', selected.question);
+                const definition = structuredClone(selected.definition), content = record(definition.content);
+                content.questions[0].prompt = question;
+                state.selected = suggestion(definition, 'Your edited question.', selected.sources);
+                await save();
+            }
+            else if (action === 'personalize') {
+                try {
+                    const metadata = record(await client.request('/onboarding/v1/planning/describe', { schema_version: 1, session_id: randomUUID(), scope }, ui.signal));
+                    const preview = await preparation.take(ui.signal);
+                    if (!preview.evidence.length) {
+                        ui.show('No suitable source was found. Your starter question is ready to use.');
+                        continue;
+                    }
+                    const evidence = [
+                        ...preview.evidence,
+                        {
+                            kind: 'clarification',
+                            id: 'onboarding_goal',
+                            question_id: 'onboarding_goal',
+                            answer: state.goal,
+                        },
+                        {
+                            kind: 'clarification',
+                            id: 'onboarding_focus',
+                            question_id: 'onboarding_focus',
+                            answer: state.focus,
+                        },
+                        {
+                            kind: 'clarification',
+                            id: 'onboarding_product',
+                            question_id: 'onboarding_product',
+                            answer: state.product,
+                        },
+                    ];
+                    ui.show(`Optional personalization: ${String(metadata.destination)}\nModel: ${String(metadata.model ?? 'configured provider model')}\n${String(metadata.policy)}\nConfigured prices: ${JSON.stringify(metadata.prices ?? {})}. Limit: 12,000 source-input / 4,000 output tokens; 30 seconds.\nReview the following exact source packet and learning goal for private material before sending. Only this application root is included. No Git history is included.\n${JSON.stringify(evidence, null, 2)}`);
+                    if (!(await ui.confirm('Approve sending this exact packet for AI personalization?')))
+                        continue;
+                    await verifyFirstSurveySource(root, preview.evidence);
+                    check();
+                    await stopAI();
+                    controller = new AbortController();
+                    const signal = AbortSignal.any([
+                        controller.signal,
+                        AbortSignal.timeout(35000),
+                        ...(ui.signal ? [ui.signal] : []),
+                    ]);
+                    analysisId = randomUUID();
+                    ai = { status: 'pending', suggestions: [] };
+                    const current = ai;
+                    const request = {
+                        schema_version: 1,
+                        session_id: analysisId,
+                        request_id: randomUUID(),
+                        scope,
+                        packages: preview.packages,
+                        capabilities: [...preview.capabilities, 'guided_starter:v1'],
+                        evidence,
+                        previous_plan_digest: null,
+                        limits: { input_tokens: 12000, output_tokens: 4000, deadline_ms: 30000 },
+                        consent: {
+                            packet_digest: digest(evidence),
+                            destination: metadata.destination,
+                            policy_version: 'first-survey-v1',
+                            configuration_fingerprint: metadata.configuration_fingerprint,
+                            authorized_at: new Date().toISOString(),
+                            git_authorized: false,
+                        },
+                    };
+                    work = abortable(client.request('/onboarding/v1/planning/analyze', request, signal), signal)
+                        .then(async (response) => {
+                        signal.throwIfAborted();
+                        const candidates = record(record(response).result).candidates;
+                        if (!Array.isArray(candidates))
+                            throw Error('Invalid personalization result');
+                        await verifyFirstSurveySource(root, preview.evidence);
+                        signal.throwIfAborted();
+                        current.suggestions = candidates.slice(0, 3).flatMap((value) => {
+                            const c = record(value);
+                            try {
+                                const candidate = suggestion(record(c.definition), String(record(c.rationale).claim ?? 'A suggestion based on the reviewed source.'), preview.evidence.map(({ path, file_hash }) => ({ path, file_hash })));
+                                const q = record(record(candidate.definition.content).questions[0]);
+                                return q.kind === (state.goal === 'satisfaction' ? 'rating' : 'text') ? [candidate] : [];
+                            }
+                            catch {
+                                return [];
+                            }
+                        });
+                        current.status = current.suggestions.length ? 'ready' : 'abstained';
+                    })
+                        .catch(() => {
+                        current.status = 'failed';
+                    });
+                    ui.show('Personalization is running. You can use or edit the starter without waiting.');
+                }
+                catch {
+                    check();
+                    ai.status = 'failed';
+                    ui.show('Personalization is unavailable. Your starter question is still ready to use.');
+                }
+            }
+            else if (action === 'check_ai') {
+                ui.show(ai.status === 'pending'
+                    ? 'Still working. You can continue with the starter.'
+                    : ai.status === 'ready'
+                        ? 'Your AI suggestions are ready to review.'
+                        : 'No suitable personalization was returned. The starter remains available.');
+            }
+            else if (action === 'review_ai' && ai.status === 'ready') {
+                const pick = await ui.choose('Choose a suggestion or keep your current question', [
+                    ...ai.suggestions.map((s, i) => ({ value: String(i), label: s.question })),
+                    { value: 'keep', label: 'Keep my current question' },
+                ]);
+                if (pick !== 'keep') {
+                    const candidate = ai.suggestions[Number(pick)];
+                    if (!candidate)
+                        throw Error('Unknown suggestion');
+                    await verifyFirstSurveySource(root, candidate.sources);
+                    state.selected = candidate;
+                    await save();
+                }
+            }
+            else if (action === 'more') {
+                const next = await ui.choose('Continue when you are ready', [
+                    { value: 'back', label: 'Back to my question' },
+                    { value: 'goal', label: 'Choose another learning goal' },
+                    { value: 'finish', label: 'Finish later — keep this draft locally' },
+                ]);
+                if (next === 'finish') {
+                    ui.show('Your question is saved locally. Rerun the development wizard to resume it.');
+                    return { state: 'draft', goal: state.goal };
+                }
+                if (next === 'goal') {
+                    await stopAI();
+                    const goal = await ui.choose('What would you like to learn?', goals);
+                    if (!goals.some((g) => g.value === goal))
+                        throw Error('Unknown learning goal');
+                    state.goal = goal;
+                    if (state.goal === 'friction')
+                        state.focus = await text('Which workflow?', `using ${state.product}`, 120);
+                    state.selected = suggestion(starterDefinition(state.goal, state.product, state.focus), 'A starter question.');
+                    await save();
+                }
+            }
+            else if (action === 'use') {
+                await stopAI();
+                check();
+                if (selected.sources.length)
+                    await verifyFirstSurveySource(root, selected.sources);
+                const definition = structuredClone(selected.definition);
+                const when = await ui.choose('When should this survey be offered?', [
+                    { value: 'editor', label: 'Set audience and timing in the editor' },
+                    { value: 'event', label: 'After a verified workflow-completion event' },
+                ]);
+                if (when === 'event') {
+                    const event = await text('Existing completion event name', '', 80);
+                    if (!/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/.test(event)) {
+                        ui.show('Use a valid existing event name.');
+                        continue;
+                    }
+                    if (!(await ui.confirm('Have you verified this event fires only after the relevant experience, for people who can answer this question?')))
+                        continue;
+                    definition.rules = {
+                        schema_version: 1,
+                        audience: {
+                            type: 'local_event',
+                            version: 1,
+                            event_key: event,
+                            dimension_key: '',
+                            minimum: 1,
+                            delay_ms: 0,
+                        },
+                        triggers: [{ type: 'event', event_key: event }],
+                        frequency: { mode: 'site_default' },
+                    };
+                }
+                else if (when !== 'editor')
+                    throw Error('Unknown timing choice');
+                ui.show(when === 'editor'
+                    ? 'The saved draft will match nobody until you configure its audience and timing.'
+                    : 'The draft will use your confirmed completion event. Test it before launch.');
+                const validation = record(await client.read('prompts.validate', { workspaceId: workspace, siteId: site, definition }));
+                if (validation.valid !== true) {
+                    ui.show('This draft needs changes before it can be saved. Your question is kept locally.');
+                    continue;
+                }
+                if (!(await ui.confirm('Save this reviewed question as an unpublished draft?')))
+                    continue;
+                check();
+                if (selected.sources.length)
+                    await verifyFirstSurveySource(root, selected.sources);
+                state.receipt = { prompt: randomUUID(), request: randomUUID(), definition };
+                await save();
+                return await create();
+            }
+        }
+    }
+    finally {
+        await stopAI();
+        preparation.cancel();
+        await lock.close();
+        await unlink(path + '.lock');
+    }
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,67 @@
+import { type Credentials, type Session } from './contracts.js';
+export declare const WIZARD_FLOW_VERSION = "2026-10-26.1";
+export declare const WIZARD_CONTENT_VERSION = "2026-10-26.1";
+export declare const WIZARD_STEPS: readonly ["run", "authentication", "target_selection", "options", "sdk_install", "cli_install", "initialization", "configuration_check", "agent_note", "agent_skill", "cli_access", "global_cli"];
+export declare const WIZARD_PHASES: readonly ["eligible", "offered", "selected", "declined", "applied", "failed", "skipped", "already_present", "cancelled", "started", "completed"];
+export declare const TELEMETRY_REASONS: readonly ["not_requested", "installation_pending", "already_present", "up_to_date", "unsupported", "existing_content_preserved", "permission_denied", "validation_failed", "network_error", "operation_failed", "user_cancelled", "explicit_skip", "packages_current"];
+export type ExecutionMode = 'interactive' | 'agent' | 'ci' | 'noninteractive';
+type Step = typeof WIZARD_STEPS[number];
+type Phase = typeof WIZARD_PHASES[number];
+type Reason = typeof TELEMETRY_REASONS[number];
+type WizardDetails = {
+    duration_ms?: number;
+    reason?: Reason;
+    selection_source?: 'prompt' | 'flag' | 'default';
+    framework?: 'react' | 'next' | 'vue' | 'vanilla';
+    package_manager?: 'npm' | 'pnpm' | 'yarn';
+    resumed?: boolean;
+    guidance_file?: 'AGENTS.md' | 'CLAUDE.md';
+};
+type Context = {
+    workspace_id?: string;
+    site_id?: string;
+    source_site_environment?: 'development' | 'production';
+};
+export declare function telemetryEnabled(): Promise<boolean>;
+export declare function setTelemetryEnabled(enabled: boolean): Promise<void>;
+export declare function telemetryCommand(positionals: readonly string[], help?: boolean): string;
+/** A best-effort recorder. Credentials stay in memory and never enter the spool or payload. */
+export declare class ToolTelemetry {
+    private options;
+    readonly runId: `${string}-${string}-${string}-${string}-${string}`;
+    private pending;
+    private session;
+    private context;
+    private wizardContext;
+    private active;
+    private fetcher;
+    private origin;
+    constructor(options: {
+        surface: 'wizard' | 'cli';
+        releaseVersion: string;
+        executionMode: ExecutionMode;
+        apiUrl: string;
+        disabled?: boolean;
+        offline?: boolean;
+        fetcher?: typeof fetch;
+        minimumIntervalMs?: number;
+    });
+    configure(input: {
+        apiUrl?: string;
+        context?: Context;
+        wizard?: WizardDetails;
+    }): void;
+    setSession(session: Session | null): void;
+    observeCredentials(credentials: Credentials): Credentials;
+    private scope;
+    private common;
+    step(step_id: Step, phase: Phase, details?: WizardDetails): void;
+    command(command: string, success: boolean, durationMs: number): void;
+    /** Save a bounded checkpoint without introducing a network call into a wizard step. */
+    checkpoint(): Promise<void>;
+    flush(force?: boolean, storeOnly?: boolean): Promise<void>;
+    private aggregate;
+    private installationId;
+    private cleanup;
+}
+export {};