@userreason/cli 0.1.0 → 0.2.0

package/dist/first-survey.d.ts

@@ -0,0 +1,88 @@
+import { UserReasonClient } from './client.js';
+import { type LocalEvidence } from './first-survey-source.js';
+export interface FirstSurveyUI {
+    show(message: string): void;
+    confirm(message: string): Promise<boolean>;
+    choose(message: string, options: {
+        value: string;
+        label: string;
+    }[], initialValue?: string): Promise<string>;
+    answer(message: string): Promise<string>;
+    signal?: AbortSignal;
+    chooseMany?(message: string, options: {
+        value: string;
+        label: string;
+        hint?: string;
+    }[], initialValues: string[]): Promise<string[]>;
+    loading?<T>(message: string, work: () => Promise<T>): Promise<T>;
+}
+type Candidate = {
+    decision?: string;
+    objective?: string;
+    audience?: {
+        claim: string;
+    };
+    exclusions?: {
+        claim: string;
+    };
+    opportunity?: {
+        claim: string;
+    };
+    availability?: string;
+    frequency?: string;
+    readiness?: string;
+    warnings?: string[];
+    id: string;
+    question: string;
+    definition: Record<string, unknown>;
+    instrumentation: unknown[];
+    missing: string[];
+};
+type Plan = {
+    outcome: string;
+    candidates: Candidate[];
+    clarifications: {
+        id: string;
+        question: string;
+        reason: string;
+    }[];
+};
+/** Show all respondent copy and branching before the author approves a draft. */
+export declare function renderFirstSurveyQuestions(definition: Record<string, unknown>): string[];
+export declare function renderFirstSurveyCandidate(c: Candidate): string;
+type Session = {
+    version: 1;
+    root: string;
+    api: string;
+    workspace: string;
+    site: string;
+    id: string;
+    expires: number;
+    state: string;
+    sources: Pick<LocalEvidence, 'path' | 'file_hash'>[];
+    plan?: Plan;
+    digest?: string;
+    saves: Record<string, {
+        prompt: string;
+        request: string;
+        definition: Record<string, unknown>;
+        result?: unknown;
+    }>;
+};
+export declare function firstSurveyHandoff(root: string, api: string, workspace: string, site: string, id?: string): string;
+/** Separate from installation state. Owner-only, seven days, no source excerpts or credentials. */
+export declare function firstSurvey(client: UserReasonClient, root: string, workspace: string, site: string, ui: FirstSurveyUI, mode?: string): Promise<Session | {
+    state: string;
+    session_id?: undefined;
+    saves?: undefined;
+} | {
+    session_id: string;
+    state: string;
+    saves: Record<string, {
+        prompt: string;
+        request: string;
+        definition: Record<string, unknown>;
+        result?: unknown;
+    }>;
+}>;
+export {};

package/dist/first-survey.js

@@ -0,0 +1,227 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile, rename, open, unlink, lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { configDirectory } from './config.js';
+import { object } from './contracts.js';
+import { collectFirstSurveySource, collectFirstSurveyHistory, verifyFirstSurveySource, sourceHash } from './first-survey-source.js';
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+function describeCondition(value) {
+    const condition = record(value);
+    if (Array.isArray(condition.conditions))
+        return condition.conditions.map(describeCondition).join(condition.type === 'any' ? ' OR ' : ' AND ');
+    const comparison = record(condition.comparison);
+    const operand = Array.isArray(comparison.value) ? comparison.value.join(', ') : comparison.value ?? (comparison.min !== undefined ? `${comparison.min}–${comparison.max}` : '');
+    return `${String(condition.question_id ?? 'earlier answer')} ${String(comparison.operator ?? 'matches')} ${String(operand)}`.trim();
+}
+/** Show all respondent copy and branching before the author approves a draft. */
+export function renderFirstSurveyQuestions(definition) {
+    const content = record(definition.content), questions = content.questions;
+    if (!Array.isArray(questions))
+        return ['Full question definition unavailable; validation is required before saving.'];
+    return questions.flatMap((value, index) => {
+        const q = record(value), logic = record(q.logic);
+        const lines = [`${index + 1}. ${String(q.prompt ?? 'Missing question')} [${String(q.kind ?? 'unknown type')}; ${q.required === true ? 'required' : 'optional'}]`];
+        if (q.kind === 'rating') {
+            const labels = Array.isArray(q.labels) ? q.labels : [];
+            lines.push(labels.length ? `   Scale: ${labels.map((label, i) => `${Number(q.min ?? 0) + i}: ${String(label)}`).join(' · ')}` : `   Scale: ${String(q.min)} (${String(q.min_label ?? '')}) to ${String(q.max)} (${String(q.max_label ?? '')})`);
+        }
+        if (Array.isArray(q.options))
+            for (const value of q.options) {
+                const option = record(value);
+                lines.push(`   - ${String(option.label ?? 'Missing label')}${option.other ? ' (asks for their own words)' : ''}`);
+            }
+        if (q.kind === 'multiple_choice')
+            lines.push(`   Select ${String(q.min_selections)}–${String(q.max_selections)} choices.`);
+        if (q.answer_order)
+            lines.push(`   Answer order: ${typeof q.answer_order === 'string' ? q.answer_order : JSON.stringify(q.answer_order)}`);
+        if (logic.show_when)
+            lines.push(`   Show when: ${describeCondition(logic.show_when)}.`);
+        if (Array.isArray(logic.rules))
+            for (const value of logic.rules) {
+                const rule = record(value), to = record(rule.to);
+                lines.push(`   When ${describeCondition(rule.when)} → ${String(to.id ?? to.type)}.`);
+            }
+        if (logic.otherwise) {
+            const to = record(logic.otherwise);
+            lines.push(`   Otherwise → ${String(to.id ?? to.type)}.`);
+        }
+        return lines;
+    });
+}
+export function renderFirstSurveyCandidate(c) {
+    return [`Decision: ${c.decision ?? 'Review with the author'}`, `Learning objective: ${c.objective ?? 'Not supplied'}`, `Question: ${c.question}`, ...renderFirstSurveyQuestions(c.definition), `Audience: ${c.audience?.claim ?? 'Needs review'}`, `Exclude: ${c.exclusions?.claim ?? 'Needs review'}`, `Timing: ${c.opportunity?.claim ?? 'Needs review'}`, `Availability: ${c.availability ?? 'Unverified'}`, `Frequency: ${c.frequency ?? 'Inherited from site'}`, `Missing signals: ${c.missing.join('; ') || 'None reported (not proof of readiness)'}`, `Readiness: ${c.readiness ?? 'Review required'}; browser behavior unverified`, ...(c.warnings ?? []).map(w => 'Warning: ' + w)].join('\n');
+}
+export function firstSurveyHandoff(root, api, workspace, site, id) {
+    return `Use the installed UserReason skill to propose up to three first surveys. Application root: ${JSON.stringify(root)}. API: ${api}; workspace: ${workspace}; site: ${site}${id ? `; session: ${id}` : ''}. Confirm installed SDK and scope. The coding agent may send source to its own provider: obtain separate source-processing consent. Reuse application facts and semantic success events; clicks are not completion and missing history is unknown. Cite relative paths, full-file hashes and line ranges. Include decision, objective, one neutral question, observable audience/exclusions, safe opportunity, availability, inherited site frequency and missing signals. Do not infer deployment or visitor history from source. Preview instrumentation with before-file hashes; obtain explicit edit approval and verify behavior, cleanup, deduplication and overlapping availability owners. Unsupported edits require a manual diff. Obtain separate approval before prompt validate and prompt create; use stable prompt/request IDs and report authoritative IDs, revisions and links.edit. A local file is not a draft. Never publish without separate approval of the exact saved revision. Configuration reachability is not browser verification. Continue interactively with userreason first-survey start --workspace ${workspace} --site ${site}.`;
+}
+/** Separate from installation state. Owner-only, seven days, no source excerpts or credentials. */
+export async function firstSurvey(client, root, workspace, site, ui, mode = 'start') {
+    ui.signal?.throwIfAborted();
+    const check = () => ui.signal?.throwIfAborted();
+    const directory = join(configDirectory(), 'first-survey');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const key = sourceHash(JSON.stringify([root, client.config.apiUrl, workspace, site]));
+    const path = join(directory, key + '.json');
+    const lock = await open(path + '.lock', 'wx', 0o600).catch(() => { throw new Error('Another first-survey process owns this session. Retry after it exits; remove a stale .lock only after verifying the process stopped.'); });
+    let state = { version: 1, root, api: client.config.apiUrl, workspace, site, id: randomUUID(), expires: Date.now() + 7 * 86400000, state: 'source_review', sources: [], saves: {} };
+    const save = async () => { const temporary = path + '.' + randomUUID() + '.tmp'; await writeFile(temporary, JSON.stringify(state), { mode: 0o600, flag: 'wx' }); await rename(temporary, path); };
+    const lookup = () => ({ schema_version: 1, scope: { api: state.api, workspace_id: workspace, site_id: site }, session_id: state.id });
+    try {
+        try {
+            if ((await lstat(path)).isSymbolicLink())
+                throw new Error('Unsafe session');
+            const old = JSON.parse(await readFile(path, 'utf8'));
+            if (old.version !== 1 || old.root !== root || old.api !== state.api || old.workspace !== workspace || old.site !== site)
+                throw new Error('Session scope changed');
+            if (old.expires > Date.now())
+                state = old;
+            else
+                await unlink(path);
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        if (mode === 'delete') {
+            await client.request('/onboarding/v1/planning/delete', lookup());
+            await unlink(path).catch(() => { });
+            return { state: 'deleted' };
+        }
+        if (mode === 'cancel') {
+            state.state = 'cancelled';
+            await save();
+            await client.request('/onboarding/v1/planning/cancel', lookup()).catch(() => ui.show('Local cancellation saved. Remote cancellation could not be confirmed; retry cancel when connected.'));
+            return state;
+        }
+        if (mode === 'handoff') {
+            ui.show(firstSurveyHandoff(root, state.api, workspace, site, state.id));
+            return { state: 'handoff' };
+        }
+        if (['cancelled', 'failed'].includes(state.state)) {
+            state = { ...state, id: randomUUID(), state: 'source_review', plan: undefined, digest: undefined, saves: {} };
+        }
+        const metadata = object(await client.request('/onboarding/v1/planning/describe', lookup()), 'planning destination');
+        const limits = { input_tokens: 12000, output_tokens: 4000, deadline_ms: 35000 };
+        if (!state.plan) {
+            if (state.state === 'analyzing') {
+                const existing = object(await client.request('/onboarding/v1/planning/get', lookup()), 'plan');
+                if (existing.status === 'proposed') {
+                    state.plan = existing.result;
+                    state.digest = sourceHash(JSON.stringify(state.plan));
+                    state.state = 'proposed';
+                    await save();
+                }
+                else
+                    throw new Error('Analysis is pending or failed. Cancel this session before starting again.');
+            }
+            if (!state.plan) {
+                ui.show('Only the chosen application root is inspected. No sibling packages are included. Secret detection is best effort; review every excerpt.');
+                const selection = await ui.answer('Relative files/directories to include, comma separated (blank: bounded application root; no siblings)');
+                const preview = await collectFirstSurveySource({ root, signal: ui.signal, selected: selection.trim() ? selection.split(',').map(p => p.trim()) : undefined });
+                ui.show(JSON.stringify({ root, packages: preview.packages, installed_sdk: preview.packages.length ? 'metadata found, runtime unverified' : 'unknown: verify using installed skill', manifest: preview.evidence.map(({ excerpt, ...rest }) => rest), omitted: preview.omitted, truncated: preview.truncated, destination: metadata.destination, provider_model: metadata.model, provider_prices: metadata.prices, provider_policy: metadata.policy, configuration_fingerprint: metadata.configuration_fingerprint, retention: 'Receipt and private plan: seven days, deleted on next planning activity; submitted source packets are not stored by UserReason; generated plans can quote source. Provider policy must be reviewed separately.', budget: `${limits.input_tokens} input / ${limits.output_tokens} completion tokens (including reasoning); ${limits.deadline_ms / 1000} seconds`, capabilities: preview.capabilities, capability_status: preview.capability_status }));
+                ui.show(JSON.stringify(preview.evidence));
+                if (!await ui.confirm('Approve uploading exactly this source packet to the displayed provider?')) {
+                    ui.show('Manual path: use prompt validate with your own evidence-labelled definition, then explicitly approve prompt create. No source processing is required.');
+                    ui.show(firstSurveyHandoff(root, state.api, workspace, site, state.id));
+                    return { state: 'declined' };
+                }
+                const git = await ui.confirm('Separately include up to 20 local Git commit subjects within 90 days? (No authors, diffs or remote fetch)');
+                const history = await collectFirstSurveyHistory(root, git);
+                if (history.warning)
+                    ui.show(history.warning);
+                let evidence = [...preview.evidence, ...history.evidence];
+                if (history.evidence.length) {
+                    ui.show(JSON.stringify(history.evidence));
+                    if (!await ui.confirm('Approve this additional Git packet?'))
+                        evidence = preview.evidence;
+                }
+                await verifyFirstSurveySource(root, preview.evidence);
+                state.sources = preview.evidence.map(({ path, file_hash }) => ({ path, file_hash }));
+                for (let round = 0; round < 2; round++) {
+                    check();
+                    state.state = 'analyzing';
+                    await save();
+                    const response = object(await client.request('/onboarding/v1/planning/analyze', { schema_version: 1, session_id: state.id, request_id: randomUUID(), scope: lookup().scope, packages: preview.packages, capabilities: preview.capabilities, evidence, previous_plan_digest: state.digest ?? null, limits, consent: { packet_digest: sourceHash(JSON.stringify(evidence)), destination: metadata.destination, policy_version: 'first-survey-v1', configuration_fingerprint: metadata.configuration_fingerprint, authorized_at: new Date().toISOString(), git_authorized: git } }, ui.signal), 'analysis');
+                    check();
+                    state.plan = response.result;
+                    state.digest = sourceHash(JSON.stringify(state.plan));
+                    state.state = 'proposed';
+                    await save();
+                    if (state.plan.outcome !== 'needs_clarification' || round === 1)
+                        break;
+                    ui.show('Clarification needed before proposing a survey.');
+                    const answers = [];
+                    for (const q of state.plan.clarifications) {
+                        const answer = await ui.answer(q.question + ' — ' + q.reason);
+                        answers.push({ kind: 'clarification', id: 'answer_' + q.id, question_id: q.id, answer });
+                    }
+                    if (!await ui.confirm('Approve sending these clarification answers to the same provider?'))
+                        return { state: 'clarification_declined' };
+                    evidence = [...evidence, ...answers];
+                    state.id = randomUUID();
+                    state.plan = undefined;
+                    await verifyFirstSurveySource(root, state.sources);
+                }
+            }
+        }
+        const plan = state.plan;
+        ui.show(`Analysis: ${plan.outcome}. ${plan.candidates.length} candidates for review.`);
+        if (plan.outcome !== 'proposed') {
+            ui.show(firstSurveyHandoff(root, state.api, workspace, site, state.id));
+            return { state: plan.outcome };
+        }
+        if (sourceHash(JSON.stringify(plan)) !== state.digest)
+            throw new Error('Plan changed; new review required');
+        await verifyFirstSurveySource(root, state.sources);
+        for (;;) {
+            const id = await ui.choose('Select one candidate to review/save (or finish)', [...plan.candidates.map(c => ({ value: c.id, label: c.question })), { value: 'finish', label: 'Finish without more drafts' }]);
+            if (id === 'finish')
+                break;
+            check();
+            const c = plan.candidates.find(c => c.id === id);
+            if (!c)
+                throw new Error('Unknown candidate');
+            ui.show(renderFirstSurveyCandidate(c));
+            const diagnostics = await client.read('prompts.validate', { workspaceId: workspace, siteId: site, definition: c.definition });
+            const validation = object(diagnostics, 'validation');
+            ui.show(`Definition: ${validation.valid === false ? 'invalid' : 'validated'}; readiness: ${String(validation.status ?? 'unverified')}. Integration: ${c.instrumentation.length ? 'blocked pending manual preview, edit approval and verification' : 'not browser verified'}. Unpublished.`);
+            if (Array.isArray(validation.warnings))
+                for (const warning of validation.warnings)
+                    ui.show('Warning: ' + String(warning));
+            if (object(diagnostics, 'validation').valid === false) {
+                ui.show('Definition invalid; correct it using the coding-agent handoff before saving.');
+                continue;
+            }
+            if (!await ui.confirm(`Create this real unpublished draft${c.instrumentation.length ? ' with blocked integration readiness' : ''}? No edits or publication are authorized.`))
+                continue;
+            check();
+            await verifyFirstSurveySource(root, state.sources);
+            const receipt = state.saves[id] ?? { prompt: randomUUID(), request: randomUUID(), definition: c.definition };
+            state.saves[id] = receipt;
+            await save();
+            if (sourceHash(JSON.stringify(receipt.definition)) !== sourceHash(JSON.stringify(c.definition)))
+                throw new Error('Reviewed definition changed');
+            if (!receipt.result)
+                receipt.result = await client.promptCommand({ workspaceId: workspace, siteId: site, action: 'create', promptId: receipt.prompt, requestId: receipt.request, definition: receipt.definition });
+            state.state = 'saved';
+            await save();
+            const saved = object(receipt.result, 'draft');
+            const links = saved.links && typeof saved.links === 'object' ? saved.links : {};
+            ui.show(`Draft saved: ${String(saved.id ?? receipt.prompt)}; revision ${String(saved.revision ?? 'see editor')}. Edit: ${String(links.edit ?? 'Open the workspace survey editor')}. Unpublished; integration unverified.`);
+        }
+        return { session_id: state.id, state: state.state, saves: state.saves };
+    }
+    catch (e) {
+        if (ui.signal?.aborted) {
+            state.state = 'cancelled';
+            await save();
+            await client.request('/onboarding/v1/planning/cancel', lookup()).catch(() => { });
+        }
+        ui.show(firstSurveyHandoff(root, state.api, workspace, site, state.id));
+        throw e;
+    }
+    finally {
+        await lock.close();
+        await unlink(path + '.lock');
+    }
+}

package/dist/help.d.ts

@@ -0,0 +1,13 @@
+import type { UiKit } from './ui.js';
+export declare const overviewNouns: string[];
+export interface HelpOptions {
+    version?: string;
+    development?: boolean;
+    trademark?: boolean;
+}
+/** Four groups of nouns, one line each. Plain (piped) output is the same text without colour or rules. */
+export declare function overviewHelp(kit: UiKit, { version, development, trademark }?: HelpOptions): string;
+/** One noun's actions: exact usage from the catalog, without the options every command shares. */
+export declare function nounHelp(kit: UiKit, noun: string): string | undefined;
+/** The closest command name within two edits, for "Did you mean". */
+export declare function suggestCommand(word: string): string | undefined;

package/dist/help.js

@@ -0,0 +1,74 @@
+import { commandCatalog, commandSummary } from './catalog.js';
+/** The overview groups every command noun. A test keeps this list in step with the catalog. */
+const GROUPS = [
+    ['Get started', [['login', 'Sign in in the browser'], ['access', 'Review or renew what this CLI may do'], ['whoami', "Account, grants and this project's site"], ['logout', 'Remove local credentials'], ['setup', 'Read an active setup’s simulated sample answers']]],
+    ['Feedback', [['first-survey', 'Review evidence-backed first-survey suggestions'], ['prompt', 'Create, validate, publish and read surveys'], ['preview', 'Capture a site for the development preview lab'], ['audience', 'Choose who sees a survey'], ['results', 'Summaries and breakdowns'], ['responses', 'Read answers'], ['conversation', 'Read conversation transcripts'], ['user', 'People and their eligibility'], ['event', 'Product events and collection']]],
+    ['Workspaces and sites', [['workspace', 'list · create · ai · delete'], ['site', 'list · create · activity · events · frequency · delete'], ['member', 'list'], ['grant', 'Request and check access'], ['deletion', 'Check a deletion request']]],
+    ['Reference', [['docs', 'Search and read the documentation'], ['cli', "Search this CLI's commands"], ['query', 'Raw management API for agents'], ['command', 'Send a management command file'], ['telemetry', 'Enable, disable or inspect usage measurement']]],
+];
+export const overviewNouns = GROUPS.flatMap(([, items]) => items.map(([name]) => name));
+/** Commands with no action of their own: they never get a per-command help page. */
+const NO_ACTION = new Set(['login', 'access', 'logout', 'whoami', 'command', 'query']);
+const READ_SCOPES = new Set(['workspace:read', 'site:read']);
+/** Four groups of nouns, one line each. Plain (piped) output is the same text without colour or rules. */
+export function overviewHelp(kit, { version, development = false, trademark = false } = {}) {
+    const { c, S } = kit;
+    const lines = [];
+    const environment = development ? `(development API)` : '';
+    const meta = [version ? `v${version}` : '', environment].filter(Boolean).join(' ');
+    if (kit.level > 0)
+        lines.push(`${c.bold(c.accent(trademark ? 'UserReason™ CLI' : 'userreason'))}${meta ? `  ${c.muted(meta)}` : ''}`, c.faint(S.rule.repeat(54)));
+    else
+        lines.push(`userreason${meta ? ` ${meta}` : ''}`);
+    lines.push(`${c.muted('Usage')}  userreason <command> [options]`, '');
+    const first = Math.max(...overviewNouns.map(name => name.length));
+    for (const [group, items] of GROUPS) {
+        lines.push(c.bold(group), ...items.map(([name, text]) => `  ${c.code(name)}${' '.repeat(first - name.length + 2)}${c.muted(text)}`), '');
+    }
+    lines.push(`${c.muted('Options')}  --json  --workspace UUID  --site UUID  --dev  --no-color  --no-telemetry  -h`, `${c.muted('Target')}   this project's SDK site; override with --workspace and --site`, `${c.muted('More')}     ${c.code('userreason <command> --help')}   ${c.code('userreason --help --all')}   ${c.code('userreason cli search "<task>"')}`);
+    return lines.join('\n') + '\n';
+}
+/** One noun's actions: exact usage from the catalog, without the options every command shares. */
+export function nounHelp(kit, noun) {
+    if (NO_ACTION.has(noun))
+        return undefined;
+    const items = commandCatalog.filter(item => item.command === noun || item.command.startsWith(`${noun} `));
+    if (!items.length)
+        return undefined;
+    const { c, S } = kit;
+    const short = (usage) => usage.replace(/^userreason /, '').replace(/ --workspace UUID/g, '').replace(/ --site UUID/g, '').replace(`${noun} `, '');
+    const lines = [];
+    const summary = commandSummary(noun);
+    if (kit.level > 0)
+        lines.push(`${c.bold(c.accent(`userreason ${noun}`))}${summary ? `  ${c.muted(summary)}` : ''}`, c.faint(S.rule.repeat(54)));
+    else
+        lines.push(`userreason ${noun}${summary ? ` ${S.dot} ${summary}` : ''}`);
+    for (const [title, read] of [['Read', true], ['Write', false]]) {
+        const rows = items.filter(item => (item.command !== 'workspace ai set' && item.scopes.every(scope => READ_SCOPES.has(scope))) === read);
+        if (!rows.length)
+            continue;
+        lines.push(c.bold(title));
+        for (const item of rows) {
+            lines.push(`  ${c.code(short(item.usage))}`);
+            const specific = commandSummary(item.command);
+            if (specific && item.command !== noun)
+                lines.push(`    ${c.muted(specific)}`);
+        }
+    }
+    lines.push(`${c.muted('Options')}  --workspace UUID  --site UUID  ${c.muted("(default: this project's site)")}  --json`);
+    return lines.join('\n') + '\n';
+}
+/** The closest command name within two edits, for "Did you mean". */
+export function suggestCommand(word) {
+    const distance = (a, b) => {
+        const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+        for (let j = 1; j <= b.length; j++)
+            d[0][j] = j;
+        for (let i = 1; i <= a.length; i++)
+            for (let j = 1; j <= b.length; j++)
+                d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        return d[a.length][b.length];
+    };
+    const [best] = overviewNouns.map(name => [name, distance(word.toLowerCase(), name)]).sort((a, b) => a[1] - b[1]);
+    return best && best[1] <= 2 ? best[0] : undefined;
+}

package/dist/index.d.ts

@@ -2,4 +2,27 @@ export * from "./client.js";
 export * from "./config.js";
 export * from "./contracts.js";
 export * from "./credentials.js";
+export * from "./docs.js";
+export * from "./profile.js";
 export * from "./workos.js";
+export * from "./authorize.js";
+export * from "./project.js";
+export * from "./errors.js";
+export * from "./catalog.js";
+export * from "./ui.js";
+export * from "./help.js";
+export * from "./views.js";
+export * from "./telemetry.js";
+export * from "./first-survey-source.js";
+export * from "./first-survey.js";
+export * from "./first-survey-preparation.js";
+export * from "./starter-survey.js";
+export * from "./recommended-surveys.js";
+export * from "./setup.js";
+export * from "./setup-store.js";
+export * from "./setup-wire.js";
+export * from "./setup-executor.js";
+export * from "./setup-files.js";
+export * from "./setup-terminal.js";
+export * from "./setup-source.js";
+export * from "./setup-runner.js";

package/dist/index.js

@@ -2,4 +2,27 @@ export * from "./client.js";
 export * from "./config.js";
 export * from "./contracts.js";
 export * from "./credentials.js";
+export * from "./docs.js";
+export * from "./profile.js";
 export * from "./workos.js";
+export * from "./authorize.js";
+export * from "./project.js";
+export * from "./errors.js";
+export * from "./catalog.js";
+export * from "./ui.js";
+export * from "./help.js";
+export * from "./views.js";
+export * from "./telemetry.js";
+export * from "./first-survey-source.js";
+export * from "./first-survey.js";
+export * from "./first-survey-preparation.js";
+export * from "./starter-survey.js";
+export * from "./recommended-surveys.js";
+export * from "./setup.js";
+export * from "./setup-store.js";
+export * from "./setup-wire.js";
+export * from "./setup-executor.js";
+export * from "./setup-files.js";
+export * from "./setup-terminal.js";
+export * from "./setup-source.js";
+export * from "./setup-runner.js";

package/dist/lock.js

@@ -2,22 +2,36 @@ import { createHash, randomUUID } from "node:crypto";
 import { mkdir, open, readFile, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { configDirectory } from "./config.js";
+import { CredentialStoreError } from './credentials.js';
 // Serialize rotating refresh tokens across CLI/wizard processes. No credentials enter this file.
 export async function withSessionLock(config, operation) {
     const directory = join(configDirectory(), "locks");
-    await mkdir(directory, { recursive: true, mode: 0o700 });
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        throw new CredentialStoreError('lock_failed', `Refreshing the UserReason session requires local write access to ${directory}. Allow that access and retry; workspace grants are unrelated.`);
+    }
     const path = join(directory, createHash("sha256").update(`${config.apiUrl}\n${config.clientId}`).digest("hex") + ".lock");
     const id = randomUUID(), deadline = Date.now() + 35_000;
     while (true) {
         try {
             const file = await open(path, "wx", 0o600);
-            await file.writeFile(JSON.stringify({ id, createdAt: Date.now() }));
-            await file.close();
+            try {
+                await file.writeFile(JSON.stringify({ id, createdAt: Date.now() }));
+            }
+            catch (error) {
+                await unlink(path).catch(() => { });
+                throw error;
+            }
+            finally {
+                await file.close();
+            }
             break;
         }
         catch (error) {
             if (error.code !== "EEXIST")
-                throw new Error("Unable to lock the UserReason credential store");
+                throw new CredentialStoreError('lock_failed', `Unable to lock UserReason credentials for refresh at ${path}. Allow local write access and retry.`);
             try {
                 const old = JSON.parse(await readFile(path, "utf8"));
                 if (typeof old.createdAt === "number" && Date.now() - old.createdAt > 120_000) {
@@ -27,7 +41,7 @@ export async function withSessionLock(config, operation) {
             }
             catch { /* Another process may be writing or releasing its lock. */ }
             if (Date.now() >= deadline)
-                throw new Error("Another UserReason process is refreshing credentials; try again shortly");
+                throw new CredentialStoreError('lock_timeout', "Another UserReason process is refreshing credentials; try again shortly");
             await new Promise(resolve => setTimeout(resolve, 150));
         }
     }

package/dist/profile.d.ts

@@ -0,0 +1,20 @@
+export interface PackageProfile {
+    schemaVersion: 1;
+    kind: "production" | "local-development";
+    apiEnvironment: "production" | "development";
+    docsUrl: string;
+    sdkVersion: string;
+    cliVersion: string;
+    wizardVersion?: string;
+    buildId?: string;
+    registry?: string;
+}
+export declare const PRODUCTION_DOCS = "https://docs.userreason.com";
+export declare const DEVELOPMENT_DOCS = "https://docs-dev.userreason.com";
+export declare const productionProfile: PackageProfile;
+export declare function parsePackageProfile(value: unknown): PackageProfile;
+/** The same optional file travels beside the CLI modules and the wizard's bundled modules. */
+export declare function packageProfile(): PackageProfile;
+export declare function docsOrigin(development?: boolean): string;
+/** Ask the foreground builder for a complete current set, including changes still being compiled. */
+export declare function currentPackageProfile(profile?: PackageProfile, fetcher?: typeof fetch): Promise<PackageProfile>;

package/dist/profile.js

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+import { apiUrl, object } from "./contracts.js";
+export const PRODUCTION_DOCS = "https://docs.userreason.com";
+export const DEVELOPMENT_DOCS = "https://docs-dev.userreason.com";
+export const productionProfile = {
+    schemaVersion: 1, kind: "production", apiEnvironment: "production",
+    docsUrl: PRODUCTION_DOCS, sdkVersion: "0.5.0", cliVersion: "0.2.0",
+};
+export function parsePackageProfile(value) {
+    const data = object(value, "package profile");
+    if (data.schemaVersion !== 1 || data.kind !== "local-development" || data.apiEnvironment !== "development" ||
+        data.docsUrl !== DEVELOPMENT_DOCS || typeof data.buildId !== "string" || !/^[a-f0-9]{64}$/.test(data.buildId) ||
+        [data.sdkVersion, data.cliVersion, data.wizardVersion].some(version => typeof version !== "string" || !/^\d+\.\d+\.\d+-dev\.[0-9]+$/.test(version)) ||
+        typeof data.registry !== "string")
+        throw new Error("Invalid local UserReason package profile");
+    const registry = apiUrl(data.registry), url = new URL(registry);
+    if (url.protocol !== "http:" || url.hostname !== "127.0.0.1")
+        throw new Error("Local UserReason packages require a loopback registry");
+    return { schemaVersion: 1, kind: "local-development", apiEnvironment: "development", docsUrl: DEVELOPMENT_DOCS,
+        sdkVersion: data.sdkVersion, cliVersion: data.cliVersion, wizardVersion: data.wizardVersion,
+        buildId: data.buildId, registry };
+}
+/** The same optional file travels beside the CLI modules and the wizard's bundled modules. */
+export function packageProfile() {
+    try {
+        return parsePackageProfile(JSON.parse(readFileSync(new URL("./package-profile.json", import.meta.url), "utf8")));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { ...productionProfile };
+        throw error;
+    }
+}
+export function docsOrigin(development = packageProfile().apiEnvironment === "development") {
+    return development ? DEVELOPMENT_DOCS : PRODUCTION_DOCS;
+}
+/** Ask the foreground builder for a complete current set, including changes still being compiled. */
+export async function currentPackageProfile(profile = packageProfile(), fetcher = fetch) {
+    if (profile.kind !== "local-development")
+        return profile;
+    let response;
+    try {
+        response = await fetcher(`${profile.registry}/-/userreason/dev-profile`, { redirect: "error", signal: AbortSignal.timeout(120_000), headers: { Accept: "application/json" } });
+    }
+    catch {
+        throw new Error("Local UserReason builder is unavailable. Start npm run dev:packages in ur-platform and retry.");
+    }
+    if (!response.ok)
+        throw new Error("The current local UserReason build failed. Check the dev:packages terminal and retry after fixing it.");
+    const text = await response.text();
+    if (text.length > 8192)
+        throw new Error("Invalid local UserReason build response");
+    const current = parsePackageProfile(JSON.parse(text));
+    if (current.registry !== profile.registry)
+        throw new Error("Local UserReason build registry does not match this wizard");
+    return current;
+}

package/dist/project.d.ts

@@ -0,0 +1,9 @@
+export interface ProjectTarget {
+    directory: string;
+    file: string;
+    siteId: string;
+    apiUrl: string;
+    workspaceId?: string;
+}
+/** Parse static SDK initialization only. Never execute application code or select an arbitrary account site. */
+export declare function detectProjectTarget(directory?: string): Promise<ProjectTarget | undefined>;