@userreason/cli 0.1.1 → 0.2.1

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.js

@@ -1,10 +1,10 @@
 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']]],
-    ['Feedback', [['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'], ['user', 'People and their eligibility'], ['event', 'Product events and collection']]],
-    ['Workspaces and sites', [['workspace', 'list · create · 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']]],
+    ['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. */
@@ -25,7 +25,7 @@ export function overviewHelp(kit, { version, development = false, trademark = fa
     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  -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>"')}`);
+    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. */
@@ -44,7 +44,7 @@ export function nounHelp(kit, noun) {
     else
         lines.push(`userreason ${noun}${summary ? ` ${S.dot} ${summary}` : ''}`);
     for (const [title, read] of [['Read', true], ['Write', false]]) {
-        const rows = items.filter(item => item.scopes.every(scope => READ_SCOPES.has(scope)) === read);
+        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));

package/dist/index.d.ts

@@ -12,3 +12,18 @@ 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-diagnostics.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

@@ -12,3 +12,18 @@ 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-diagnostics.js";
+export * from "./setup-files.js";
+export * from "./setup-terminal.js";
+export * from "./setup-source.js";
+export * from "./setup-runner.js";

package/dist/profile.js

@@ -4,7 +4,7 @@ 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.4.0", cliVersion: "^0.1.1",
+    docsUrl: PRODUCTION_DOCS, sdkVersion: "0.5.3", cliVersion: "0.2.1",
 };
 export function parsePackageProfile(value) {
     const data = object(value, "package profile");

package/dist/recommendation-source.d.ts

@@ -0,0 +1,13 @@
+type Source = {
+    path: string;
+    text: string;
+};
+type Window = Source & {
+    start: number;
+    end: number;
+};
+/** Same complete-file/whole-AST-unit policy as the benchmark. An oversized
+ * statement is omitted rather than cut in the middle to fill a byte quota. */
+export declare function recommendationSourceWindows(file: Source, requiredHandlers?: string[]): Window[];
+export declare function connectedRecommendationSource(candidates: Source[], maxPacketBytes?: number): Window[];
+export {};

package/dist/recommendation-source.js

@@ -0,0 +1,211 @@
+/** Benchmark structural source selection. The caller reads and screens files;
+ * this pure selector never executes code or expands the approved root. */
+import ts from 'typescript';
+import { posix } from 'node:path';
+const bytes = (text) => Buffer.byteLength(text);
+const limits = { roots: 64, total: 164000, file: 26000, span: 16000, workflow: 38000, support: 8000, shared: 5000, excerpts: 200 };
+function analyze(file) {
+    const ast = ts.createSourceFile(file.path, file.text, ts.ScriptTarget.Latest, true, /\.[cm]?jsx?$/.test(file.path) ? ts.ScriptKind.JSX : /\.tsx$/.test(file.path) ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const imports = [], tags = new Set(), handlers = new Set(), templates = [];
+    const walk = (node) => {
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+            const names = [], bindings = node.importClause?.namedBindings;
+            if (node.importClause?.name)
+                names.push(node.importClause.name.text);
+            if (bindings && ts.isNamedImports(bindings))
+                names.push(...bindings.elements.map(element => element.name.text));
+            imports.push({ specifier: node.moduleSpecifier.text, names });
+        }
+        if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier))
+            imports.push({ specifier: node.moduleSpecifier.text, names: [] });
+        if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node))
+            tags.add(node.tagName.getText(ast).split('.')[0]);
+        if (ts.isJsxAttribute(node) && /^on[A-Z]/.test(node.name.getText(ast))) {
+            const ids = (child) => { if (ts.isIdentifier(child))
+                handlers.add(child.text); ts.forEachChild(child, ids); };
+            ts.forEachChild(node, ids);
+        }
+        if (ts.isPropertyAssignment(node) && node.name.getText(ast) === 'templateUrl' && ts.isStringLiteral(node.initializer))
+            templates.push(node.initializer.text);
+        ts.forEachChild(node, walk);
+    };
+    walk(ast);
+    if (/\.(?:vue|svelte|html)$/.test(file.path))
+        for (const match of file.text.matchAll(/(?:\([\w.:-]+\)|@[\w.:-]+)\s*=\s*["']([^"']+)["']/g))
+            for (const call of match[1].matchAll(/([A-Za-z_$][\w$]*)\s*\(/g))
+                handlers.add(call[1]);
+    return { ast, imports, rendered: new Set(imports.filter(item => item.names.some(name => tags.has(name))).map(item => item.specifier)), handlers, templates };
+}
+/** Same complete-file/whole-AST-unit policy as the benchmark. An oversized
+ * statement is omitted rather than cut in the middle to fill a byte quota. */
+export function recommendationSourceWindows(file, requiredHandlers = []) {
+    const lines = file.text.split('\n');
+    const make = (start, end) => ({ path: file.path, start, end, text: lines.slice(start - 1, end).join('\n') });
+    if (bytes(file.text) <= limits.file)
+        return [make(1, lines.length)];
+    if (!/\.[cm]?[jt]sx?$/.test(file.path))
+        return [];
+    const a = analyze(file), units = [];
+    for (const handler of requiredHandlers)
+        a.handlers.add(handler);
+    const add = (node, priority) => units.push({ start: a.ast.getLineAndCharacterOfPosition(node.getStart(a.ast)).line + 1, end: a.ast.getLineAndCharacterOfPosition(node.end).line + 1, priority });
+    const inspect = (node) => {
+        if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+            add(node, 2);
+            return;
+        }
+        if ((ts.isFunctionDeclaration(node) || ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.body && ts.isBlock(node.body)) {
+            for (const statement of node.body.statements) {
+                const raw = statement.getText(a.ast);
+                const names = ts.isVariableStatement(statement) ? statement.declarationList.declarations.map(declaration => declaration.name.getText(a.ast)) : ts.isFunctionDeclaration(statement) && statement.name ? [statement.name.text] : [];
+                add(statement, /return\s*\(?\s*</.test(raw) || /useEffect|useState|useCallback|useMemo/.test(raw) || names.some(name => a.handlers.has(name)) ? 0 : 1);
+            }
+            return;
+        }
+        if (ts.isClassDeclaration(node)) {
+            for (const member of node.members)
+                add(member, member.name && a.handlers.has(member.name.getText(a.ast)) ? 0 : 1);
+            return;
+        }
+        if (ts.isVariableStatement(node)) {
+            let expanded = false;
+            for (const declaration of node.declarationList.declarations)
+                if (declaration.initializer && (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer))) {
+                    inspect(declaration.initializer);
+                    expanded = true;
+                }
+            if (!expanded)
+                add(node, 2);
+            return;
+        }
+        add(node, 2);
+    };
+    for (const node of a.ast.statements)
+        inspect(node);
+    const selected = [];
+    let retained = 0;
+    for (const unit of units.sort((a, b) => a.priority - b.priority || a.start - b.start)) {
+        if (selected.some(window => window.start <= unit.start && window.end >= unit.end))
+            continue;
+        const window = make(unit.start, unit.end), length = bytes(window.text);
+        if (length > limits.span || retained + length > limits.file)
+            continue;
+        selected.push(window);
+        retained += length;
+    }
+    return selected.sort((a, b) => a.start - b.start);
+}
+const shell = (path) => /^(?:app|main|router|routes|layout)\.[cm]?[jt]sx?$/i.test(posix.basename(path)) || /\/app\.component\.(?:ts|html)$/.test(path);
+const rank = (path) => /\/(?:routes|pages|screens|views)\//.test('/' + path) ? 0 : /\.component\.html$/.test(path) ? 1 : 2;
+const family = (path) => { const parts = path.split('/'), index = parts.findIndex(part => ['routes', 'pages', 'screens', 'views'].includes(part)); return index >= 0 ? parts.slice(0, index + 2).join('/') : posix.dirname(path); };
+export function connectedRecommendationSource(candidates, maxPacketBytes = 262144) {
+    const files = new Map(candidates.map(file => [file.path, file])), analyses = new Map();
+    const record = (path) => { if (!analyses.has(path))
+        analyses.set(path, analyze(files.get(path))); return analyses.get(path); };
+    const resolve = (from, specifier) => {
+        const base = specifier.startsWith('.') ? posix.normalize(posix.join(posix.dirname(from), specifier)) : specifier.startsWith('@/') ? `src/${specifier.slice(2)}` : '';
+        if (!base)
+            return undefined;
+        return [base, ...['.tsx', '.ts', '.jsx', '.js', '.vue', '.svelte', '.html', '/index.tsx', '/index.ts', '/index.jsx', '/index.js'].map(ext => base + ext)].find(path => files.has(path));
+    };
+    const references = (path) => {
+        const a = record(path);
+        return [
+            ...a.imports.flatMap(item => { const target = resolve(path, item.specifier); return target ? [{ target, rendered: a.rendered.has(item.specifier), template: false }] : []; }),
+            ...a.templates.flatMap(template => { const target = resolve(path, template); return target ? [{ target, rendered: true, template: true }] : []; }),
+            ...(/\.component\.html$/.test(path) && files.has(path.replace(/\.html$/, '.ts')) ? [{ target: path.replace(/\.html$/, '.ts'), rendered: true, template: true }] : []),
+        ].sort((a, b) => Number(b.rendered) - Number(a.rendered) || a.target.localeCompare(b.target));
+    };
+    const buckets = new Map();
+    for (const file of candidates.filter(file => rank(file.path) < 2 && !shell(file.path))) {
+        const key = family(file.path);
+        buckets.set(key, [...(buckets.get(key) ?? []), file]);
+    }
+    for (const bucket of buckets.values())
+        bucket.sort((a, b) => a.path.split('/').length - b.path.split('/').length || a.path.localeCompare(b.path));
+    const queues = [...buckets].sort((a, b) => a[0].localeCompare(b[0])), seeds = [];
+    for (let i = 0; seeds.length < Math.min(limits.roots, [...buckets.values()].reduce((n, values) => n + values.length, 0)); i++)
+        for (const [, bucket] of queues)
+            if (bucket[i] && seeds.length < limits.roots)
+                seeds.push(bucket[i].path);
+    if (!seeds.length)
+        seeds.push(...candidates.filter(file => shell(file.path)).map(file => file.path).slice(0, limits.roots));
+    if (!seeds.length)
+        seeds.push(...candidates.filter(file => /\.(?:[cm]?[jt]sx?|vue|svelte|html)$/.test(file.path)).map(file => file.path).slice(0, limits.roots));
+    const rootSet = new Set(seeds), owner = new Map(seeds.map(path => [path, path]));
+    const find = (path) => { const seen = new Set(); while (owner.get(path) !== path && !seen.has(path)) {
+        seen.add(path);
+        path = owner.get(path);
+    } return path; };
+    for (const seed of seeds)
+        for (const edge of references(seed))
+            if (edge.rendered && rootSet.has(edge.target) && find(seed) !== find(edge.target))
+                owner.set(find(edge.target), find(seed));
+    const groups = new Map();
+    for (const seed of seeds) {
+        const key = find(seed);
+        groups.set(key, [...(groups.get(key) ?? []), seed]);
+    }
+    const workflows = [];
+    for (const roots of groups.values()) {
+        const windows = [], seen = new Set(), queue = roots.map(path => ({ path, depth: 0 }));
+        let retained = 0, support = 0;
+        const append = (path, supporting, handlers = []) => {
+            for (const window of recommendationSourceWindows(files.get(path), handlers)) {
+                const key = `${path}:${window.start}:${window.end}`, length = bytes(window.text);
+                if (seen.has(key) || retained + length > limits.workflow || supporting && support + length > limits.support)
+                    continue;
+                seen.add(key);
+                windows.push(window);
+                retained += length;
+                if (supporting)
+                    support += length;
+            }
+        };
+        for (const root of roots)
+            append(root, false);
+        const visited = new Set();
+        while (queue.length) {
+            const item = queue.shift();
+            if (visited.has(item.path) || item.depth > 2)
+                continue;
+            visited.add(item.path);
+            for (const edge of references(item.path).slice(0, 12)) {
+                if (rootSet.has(edge.target) && !roots.includes(edge.target))
+                    continue;
+                append(edge.target, !roots.includes(edge.target), edge.template ? [...record(item.path).handlers] : []);
+                if (edge.rendered || edge.template)
+                    queue.push({ path: edge.target, depth: item.depth + 1 });
+            }
+        }
+        if (windows.length)
+            workflows.push(windows);
+    }
+    const selected = [], seen = new Set();
+    let retained = 0, wireBytes = 512;
+    const append = (window) => {
+        const key = `${window.path}:${window.start}:${window.end}`, length = bytes(window.text);
+        if (seen.has(key) || selected.length >= limits.excerpts || retained + length > limits.total)
+            return;
+        const encoded = bytes(JSON.stringify({ kind: 'local_source', id: `source_${selected.length + 1}`, path: window.path, file_hash: '0'.repeat(64), excerpt_hash: '0'.repeat(64), snapshot_id: '00000000-0000-4000-8000-000000000000', start_line: window.start, end_line: window.end, excerpt: window.text })) + 1;
+        if (wireBytes + encoded > maxPacketBytes)
+            return;
+        seen.add(key);
+        selected.push(window);
+        retained += length;
+        wireBytes += encoded;
+    };
+    let shared = 0;
+    for (const file of candidates.filter(file => shell(file.path)).slice(0, 8))
+        for (const window of recommendationSourceWindows(file))
+            if (shared + bytes(window.text) <= limits.shared) {
+                append(window);
+                shared += bytes(window.text);
+            }
+    // Fair interleaving keeps the first large view from consuming all evidence.
+    for (let i = 0; i < Math.max(0, ...workflows.map(windows => windows.length)); i++)
+        for (const windows of workflows)
+            if (windows[i])
+                append(windows[i]);
+    return selected;
+}

package/dist/recommended-surveys.d.ts

@@ -0,0 +1,30 @@
+import type { UserReasonClient } from "./client.js";
+import { type FirstSurveyPreparation } from "./first-survey-preparation.js";
+import type { FirstSurveyUI } from "./first-survey.js";
+type Receipt = {
+    prompt: string;
+    request: string;
+    definition: Record<string, unknown>;
+    result?: unknown;
+};
+/** One optional selection; all drafts stay unpublished and match no audience. */
+export declare function recommendedSurveys(client: UserReasonClient, root: string, workspace: string, site: string, ui: FirstSurveyUI, options?: {
+    preparation?: FirstSurveyPreparation;
+    sourceConsent?: boolean;
+}): Promise<{
+    state: string;
+    error?: undefined;
+    count?: undefined;
+    receipts?: undefined;
+} | {
+    state: string;
+    error: string;
+    count?: undefined;
+    receipts?: undefined;
+} | {
+    state: string;
+    count: number;
+    receipts: Record<string, Receipt>;
+    error?: undefined;
+}>;
+export {};