@userreason/cli 0.1.0 → 0.2.0

package/dist/docs.js

@@ -0,0 +1,143 @@
+import { apiUrl, object } from "./contracts.js";
+import { DEVELOPMENT_DOCS } from "./profile.js";
+import { bundledCliMarkdown, searchCommands } from './catalog.js';
+import { NetworkError, networkError } from './errors.js';
+export const DOCS_URL = "https://docs.userreason.com";
+export class DocsError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+export const docsUrl = (value) => apiUrl(value, "Docs URL");
+const invalid = (status) => new DocsError("invalid_response", `Invalid UserReason docs response (${status})`, status);
+/** The docs are public: requests carry no credentials, never follow redirects and read a bounded body. */
+async function read(url, accept, limit, fetcher) {
+    try {
+        const response = await fetcher(url.href, { headers: { Accept: accept }, redirect: "error", signal: AbortSignal.timeout(20_000) });
+        const chunks = [];
+        let bytes = 0;
+        if (response.body)
+            for await (const chunk of response.body) {
+                bytes += chunk.byteLength;
+                if (bytes > limit)
+                    throw new DocsError("response_too_large", "UserReason docs response is too large", response.status);
+                chunks.push(chunk);
+            }
+        try {
+            return { response, text: new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)) };
+        }
+        catch {
+            throw invalid(response.status);
+        }
+    }
+    catch (error) {
+        if (error instanceof DocsError)
+            throw error;
+        const failure = networkError(error, url.href, 'UserReason documentation request');
+        throw failure.code === 'network_unreachable' ? new DocsError("docs_unreachable", `${failure.message} Use cli search or docs search --offline for the bundled CLI reference, or set --docs-url or UR_DOCS_URL.`) : failure;
+    }
+}
+function searchResult(value) {
+    const data = object(value, "docs search result");
+    if (["title", "url", "markdown_url", "passage"].some(key => typeof data[key] !== "string") || (data.heading !== null && typeof data.heading !== "string") || ["package", "version", "since"].some(key => data[key] !== undefined && typeof data[key] !== "string"))
+        throw new Error("Invalid docs search result");
+    return data;
+}
+export async function searchDocs(input) {
+    const query = input.query.trim();
+    if (!query || query.length > 500)
+        throw new Error("Docs search needs a question of 1–500 characters");
+    if (input.limit !== undefined && (!Number.isInteger(input.limit) || input.limit < 1 || input.limit > 20))
+        throw new Error("Docs search limit must be an integer from 1 to 20");
+    const offline = () => ({ query, source: 'bundled', results: searchCommands(query, input.limit).map(item => ({
+            title: 'CLI command reference', heading: item.command, url: docsUrl(input.origin ?? DOCS_URL) + '/cli/', markdown_url: docsUrl(input.origin ?? DOCS_URL) + '/cli/', passage: item.summary + '\n' + item.usage, package: '@userreason/cli',
+        })) });
+    if (input.offline)
+        return offline();
+    const url = new URL("/search", docsUrl(input.origin ?? DOCS_URL));
+    url.searchParams.set("q", query);
+    if (input.limit !== undefined)
+        url.searchParams.set("limit", String(input.limit));
+    let response, text;
+    try {
+        ({ response, text } = await read(url, "application/json", 262_144, input.fetcher ?? fetch));
+    }
+    catch (error) {
+        if (input.live === false && (error instanceof NetworkError || error instanceof DocsError && error.code === 'docs_unreachable'))
+            return { ...offline(), warning: { code: error.code, message: error.message } };
+        throw error;
+    }
+    if (!response.ok) {
+        let code = "request_failed";
+        try {
+            const detail = object(object(JSON.parse(text), "error").error, "error");
+            if (typeof detail.code === "string" && /^[a-z0-9_:-]{1,100}$/i.test(detail.code))
+                code = detail.code;
+        }
+        catch { /* Not a docs error body. */ }
+        throw new DocsError(code, `UserReason docs search failed (${response.status}, ${code})`, response.status);
+    }
+    try {
+        const data = object(JSON.parse(text), "docs search");
+        if (typeof data.query !== "string" || !Array.isArray(data.results))
+            throw new Error("Invalid docs search");
+        const selectedOrigin = docsUrl(input.origin ?? DOCS_URL);
+        const address = (value) => selectedOrigin === DEVELOPMENT_DOCS && value.startsWith(DOCS_URL + '/') ? DEVELOPMENT_DOCS + value.slice(DOCS_URL.length) : value;
+        return { ...data, query: data.query, results: data.results.map(value => {
+                const result = searchResult(value);
+                return { ...result, url: address(result.url), markdown_url: address(result.markdown_url) };
+            }) };
+    }
+    catch {
+        throw invalid(response.status);
+    }
+}
+/** Accepts a page address or path. Search results name the public site, so its addresses are read from the selected origin. */
+export function docsPageUrl(target, origin = DOCS_URL) {
+    const base = docsUrl(origin);
+    if (!target.trim())
+        throw new Error("Supply a docs page URL or path, such as /sdk/events/");
+    let url;
+    try {
+        url = new URL(target.trim(), base);
+    }
+    catch {
+        throw new Error("Invalid docs page URL or path");
+    }
+    if (url.username || url.password || (url.origin !== base && url.origin !== DOCS_URL && url.origin !== DEVELOPMENT_DOCS))
+        throw new Error(`docs get reads pages from ${base} only`);
+    const path = url.pathname;
+    return base + (path.endsWith("/") || path.slice(path.lastIndexOf("/") + 1).includes(".") ? path : `${path}/`);
+}
+export async function getDocsPage(input) {
+    const url = new URL(docsPageUrl(input.target, input.origin));
+    if (!input.live && ['/cli/', '/cli/index.md'].includes(url.pathname))
+        return { url: url.href, markdown: bundledCliMarkdown(), source: 'bundled' };
+    if (input.offline)
+        throw new DocsError('not_bundled', 'Only the CLI reference (/cli/) is bundled. SDK documentation needs network access; use --live to read it.');
+    const { response, text } = await read(url, "text/markdown", 2_097_152, input.fetcher ?? fetch);
+    if (response.status === 404)
+        throw new DocsError("not_found", `No docs page at ${url.href}. Find pages with userreason docs search, or read ${url.origin}/llms.txt.`, 404);
+    if (!response.ok)
+        throw new DocsError("request_failed", `UserReason docs request failed (${response.status})`, response.status);
+    const type = response.headers.get("content-type")?.toLowerCase() ?? "";
+    if (!type.startsWith("text/markdown") && !type.startsWith("text/plain"))
+        throw new DocsError("not_markdown", `${url.href} did not return Markdown`, response.status);
+    const tokens = Number(response.headers.get("x-markdown-tokens"));
+    return { url: url.href, markdown: text, ...(Number.isInteger(tokens) && tokens > 0 ? { tokens } : {}) };
+}
+/** Terminal output keeps line breaks and tabs and drops other control characters. */
+export const printable = (text) => text.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
+export function formatDocsSearch(found) {
+    const note = found.source === 'bundled' ? 'Bundled CLI reference only. SDK documentation requires network access.\n' : '';
+    if (!found.results.length)
+        return printable(`${note}No docs sections match "${found.query}".\n`);
+    return printable(note + found.results.map((result, index) => {
+        const notes = [[result.package, result.version].filter(Boolean).join(" "), result.since ? `added in ${result.since}` : ""].filter(Boolean).join(", ");
+        return `${index + 1}. ${result.title}${result.heading ? ` › ${result.heading}` : ""}${notes ? ` (${notes})` : ""}\n   ${result.url}\n   ${result.passage}\n`;
+    }).join("\n") + "\nRead a page as Markdown: userreason docs get URL\n");
+}

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+/** Local transport failures are different from an API denying workspace access. */
+export declare class NetworkError extends Error {
+    code: 'network_blocked' | 'network_timeout' | 'network_unreachable';
+    constructor(code: 'network_blocked' | 'network_timeout' | 'network_unreachable', message: string);
+}
+export declare class ConfigurationError extends Error {
+    code: 'config_read_failed' | 'config_write_failed' | 'invalid_config';
+    constructor(code: 'config_read_failed' | 'config_write_failed' | 'invalid_config', message: string);
+}
+export declare function networkError(error: unknown, url: string, operation: string): NetworkError;
+export declare function fetchWithErrors(fetcher: typeof fetch, url: string, init: RequestInit, operation: string): Promise<Response>;

package/dist/errors.js

@@ -0,0 +1,38 @@
+/** Local transport failures are different from an API denying workspace access. */
+export class NetworkError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export class ConfigurationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function networkError(error, url, operation) {
+    const codes = [];
+    let current = error;
+    for (let depth = 0; depth < 5 && current && typeof current === 'object'; depth++) {
+        const item = current;
+        codes.push(String(item.code ?? ''), String(item.name ?? ''));
+        current = item.cause;
+    }
+    const host = new URL(url).origin;
+    if (codes.some(code => ['EACCES', 'EPERM', 'ERR_ACCESS_DENIED'].includes(code)))
+        return new NetworkError('network_blocked', `${operation}: local permissions blocked network access to ${host}. Allow this command to reach that origin; changing workspace grants will not resolve it.`);
+    if (codes.some(code => ['ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'TimeoutError', 'AbortError'].includes(code)))
+        return new NetworkError('network_timeout', `${operation}: the request to ${host} timed out. Check connectivity and retry; this is not a workspace permission denial.`);
+    return new NetworkError('network_unreachable', `${operation}: unable to reach ${host}. Check the connection and the agent's network permissions; this is not a workspace permission denial.`);
+}
+export async function fetchWithErrors(fetcher, url, init, operation) {
+    try {
+        return await fetcher(url, init);
+    }
+    catch (error) {
+        throw networkError(error, url, operation);
+    }
+}

package/dist/event-policy.d.ts

@@ -0,0 +1,2 @@
+/** Explicit file policies win; the one-step registration preset is a product choice, not name inference. */
+export declare function eventCollection(file: Record<string, unknown>, purpose?: string): unknown;

package/dist/event-policy.js

@@ -0,0 +1,9 @@
+/** Explicit file policies win; the one-step registration preset is a product choice, not name inference. */
+export function eventCollection(file, purpose) {
+    const selected = purpose ?? file.purpose ?? 'business';
+    if (selected !== 'business' && selected !== 'activity')
+        throw new Error('Purpose must be business or activity');
+    return file.collection ?? (selected === 'activity'
+        ? { memory: true, local: false, server: false, raw_retention_days: 0, history_retention_days: null, purpose: 'activity' }
+        : { memory: true, local: false, server: true, raw_retention_days: 30, history_retention_days: 90, purpose: 'business' });
+}

package/dist/first-survey-preparation.d.ts

@@ -0,0 +1,8 @@
+import { type SourcePreview } from './first-survey-source.js';
+export interface FirstSurveyPreparation {
+    readonly root: string;
+    take(signal?: AbortSignal): Promise<SourcePreview>;
+    cancel(): void;
+}
+/** Local, memory-only work. No provider, account lookup, Git history or upload. */
+export declare function prepareFirstSurveyLocally(root: string): FirstSurveyPreparation;

package/dist/first-survey-preparation.js

@@ -0,0 +1,29 @@
+import { collectFirstSurveySource, verifyFirstSurveySource, } from './first-survey-source.js';
+/** Local, memory-only work. No provider, account lookup, Git history or upload. */
+export function prepareFirstSurveyLocally(root) {
+    const controller = new AbortController();
+    // Observe failures immediately even if the user never opens the survey step.
+    const prepared = collectFirstSurveySource({ root, signal: controller.signal, recommendations: true }).then((preview) => ({ preview }), () => ({ preview: undefined }));
+    return {
+        root,
+        async take(signal) {
+            signal?.throwIfAborted();
+            const cached = await prepared;
+            signal?.throwIfAborted();
+            if (cached.preview) {
+                try {
+                    // SDK installation or an editor may have changed files since sign-in.
+                    await verifyFirstSurveySource(root, cached.preview.evidence);
+                    return cached.preview;
+                }
+                catch {
+                    signal?.throwIfAborted();
+                }
+            }
+            return collectFirstSurveySource({ root, signal, recommendations: true });
+        },
+        cancel() {
+            controller.abort();
+        },
+    };
+}

package/dist/first-survey-source.d.ts

@@ -0,0 +1,60 @@
+export declare const sourceHash: (value: string) => string;
+export interface LocalEvidence {
+    kind: 'local_source';
+    id: string;
+    path: string;
+    file_hash: string;
+    excerpt_hash: string;
+    snapshot_id: string;
+    start_line: number;
+    end_line: number;
+    excerpt: string;
+}
+export interface SourcePreview {
+    root: string;
+    snapshot_id: string;
+    evidence: LocalEvidence[];
+    omitted: {
+        path: string;
+        reason: string;
+    }[];
+    truncated: boolean;
+    inspected: number;
+    packet_digest: string;
+    packages: {
+        name: string;
+        version: string;
+    }[];
+    capabilities: string[];
+    capability_status: "declared" | "unknown";
+}
+/**
+ * An explicit canonical absolute root is required even when cwd is an application.
+ * Callers creating temporary directories must resolve platform parent aliases
+ * with realpath first (e.g. macOS /var -> /private/var). Within the approved root,
+ * symlinks are never followed; verification rejects subsequent symlink changes.
+ */
+export declare function collectFirstSurveySource(input: {
+    root: string;
+    selected?: string[];
+    maxFiles?: number;
+    maxBytes?: number;
+    maxPacketBytes?: number;
+    snapshotId?: string;
+    signal?: AbortSignal;
+    recommendations?: boolean;
+}): Promise<SourcePreview>;
+/** Recheck every approved full-file hash before upload, edits or draft mutations. */
+export declare function verifyFirstSurveySource(root: string, sources: Pick<LocalEvidence, 'path' | 'file_hash'>[]): Promise<void>;
+export interface LocalHistory {
+    kind: 'local_history';
+    id: string;
+    commit: string;
+    date: string;
+    summary: string;
+}
+/** Separate opt-in; no fetch, diff, author identity, or deployment inference. */
+export declare function collectFirstSurveyHistory(root: string, consent: boolean): Promise<{
+    evidence: LocalHistory[];
+    warning?: string;
+}>;

package/dist/first-survey-source.js

@@ -0,0 +1,289 @@
+/** Node-only, bounded source inspection. Never imported by the browser SDK. */
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, realpath, readdir, open, readFile } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { execFile } from 'node:child_process';
+import ignore from 'ignore';
+export const sourceHash = (value) => createHash('sha256').update(value).digest('hex');
+const forbidden = /(^|\/)(?:\.git|\.env(?:\..*)?|node_modules|vendor|dist|build|coverage|\.next|\.nuxt|\.cache|\.output|public|uploads?|datasets?|fixtures?|__fixtures__|backups?|credentials?|secrets?)(\/|$)|(?:\.min\.[cm]?js|\.map|\.lock|\.(?:pem|key|p12|pfx|sqlite|db|csv|parquet|log|snap))$|(^|\/)(?:package-lock\.json|yarn\.lock|pnpm-lock\.yaml|\.npmrc|\.netrc|id_rsa|id_ed25519)$/i;
+const sourceFile = /(?:\.(?:[cm]?[jt]sx?|vue|svelte|json|md))$/i;
+const secret = /-----BEGIN [^-]*(?:PRIVATE KEY|CERTIFICATE)-----|\b(?:sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9_]{16,}|AKIA[A-Z0-9]{16})\b|(?:api[_-]?key|secret|password|access[_-]?token|authorization)\s*[:=]\s*["'`][^"'`\n]{8,}["'`]/i;
+function inside(root, file) {
+    const path = relative(root, file);
+    return path !== '' && path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path);
+}
+function safeLimits(value, fallback, max) {
+    const n = value ?? fallback;
+    if (!Number.isSafeInteger(n) || n < 1 || n > max)
+        throw new Error('Invalid source budget');
+    return n;
+}
+/**
+ * An explicit canonical absolute root is required even when cwd is an application.
+ * Callers creating temporary directories must resolve platform parent aliases
+ * with realpath first (e.g. macOS /var -> /private/var). Within the approved root,
+ * symlinks are never followed; verification rejects subsequent symlink changes.
+ */
+export async function collectFirstSurveySource(input) {
+    if (!isAbsolute(input.root) || resolve(input.root) !== input.root)
+        throw new Error('Use an explicit canonical absolute application root');
+    const root = await realpath(input.root);
+    if (root !== input.root || !(await lstat(root)).isDirectory())
+        throw new Error('Application root must be a canonical directory, not a symlink');
+    const maxFiles = safeLimits(input.maxFiles, 200, 200);
+    const maxBytes = safeLimits(input.maxBytes, input.recommendations ? 2 * 1024 * 1024 : 500 * 1024, input.recommendations ? 2 * 1024 * 1024 : 500 * 1024);
+    // Conservative UTF-8 byte budget: at most 12,000 tokens even for non-English source.
+    const maxPacketBytes = safeLimits(input.maxPacketBytes, 10000, 10000);
+    const snapshot_id = input.snapshotId ?? randomUUID();
+    const omitted = [], evidence = [];
+    let inspected = 0, bytes = 0, packetBytes = 0, truncated = false, entries = 0;
+    const candidates = [];
+    const rootIgnore = ignore();
+    for (const name of ['.gitignore', '.ignore', '.userreasonignore']) {
+        try {
+            const file = resolve(root, name), stat = await lstat(file);
+            if (stat.isFile() && !stat.isSymbolicLink() && stat.size <= 16384)
+                rootIgnore.add(await readFile(file, 'utf8'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    const selected = input.selected?.map(path => {
+        const absolute = resolve(root, path);
+        if (!inside(root, absolute) || path.includes('\\') || path.split('/').some(p => p === '..' || p === '.'))
+            throw new Error('Selected source must stay inside the application root');
+        return relative(root, absolute).split(sep).join('/');
+    });
+    const check = () => input.signal?.throwIfAborted();
+    async function walk(directory, inherited) {
+        check();
+        if (entries >= 2000 || inspected >= maxFiles || bytes >= maxBytes) {
+            truncated = true;
+            return;
+        }
+        const local = [...inherited];
+        if (directory !== root) {
+            try {
+                const file = resolve(directory, '.gitignore'), stat = await lstat(file);
+                if (stat.isFile() && !stat.isSymbolicLink() && stat.size <= 16384)
+                    local.push({ base: directory, rules: ignore().add(await readFile(file, 'utf8')) });
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        const names = (await readdir(directory)).sort((a, b) => {
+            const rank = (s) => /^(package\.json|README\.md)$/.test(s) ? 0 : /init|route|page|screen|state|event|app|main/i.test(s) ? 1 : 2;
+            return rank(a) - rank(b) || a.localeCompare(b);
+        });
+        for (const name of names) {
+            check();
+            if (++entries > 2000 || inspected >= maxFiles || bytes >= maxBytes) {
+                truncated = true;
+                break;
+            }
+            const absolute = resolve(directory, name), path = relative(root, absolute).split(sep).join('/');
+            if (forbidden.test(path))
+                continue;
+            if (input.recommendations && /^(?:\.agents|\.cursor|\.codex)(?:\/|$)/.test(path))
+                continue;
+            const stat = await lstat(absolute);
+            if (stat.isSymbolicLink()) {
+                omitted.push({ path, reason: 'symlink' });
+                continue;
+            }
+            if (!stat.isFile() && !stat.isDirectory()) {
+                omitted.push({ path, reason: 'non-regular' });
+                continue;
+            }
+            if (local.some(({ base, rules }) => rules.ignores(relative(base, absolute).split(sep).join('/') + (stat.isDirectory() ? '/' : ''))))
+                continue;
+            if (selected && !selected.some(p => p === path || p.startsWith(path + '/') || path.startsWith(p + '/')))
+                continue;
+            if (stat.isDirectory()) {
+                await walk(absolute, local);
+                continue;
+            }
+            if (input.recommendations && (!/\.(?:[cm]?[jt]sx?|vue|svelte)$/.test(path) || /(?:\.d\.ts|[.-](?:test|spec)\.[^.]+)$/.test(path) || /(?:^|\/)(?:vite|eslint|next|tailwind|postcss)\.config\./.test(path)))
+                continue;
+            if (!sourceFile.test(path))
+                continue;
+            inspected++;
+            const fileBudget = input.recommendations ? 256000 : 32768;
+            if (stat.size > fileBudget || stat.size + bytes > maxBytes) {
+                omitted.push({ path, reason: 'size budget' });
+                truncated = true;
+                continue;
+            }
+            // Open without following a last-component symlink; verify inode and canonical ancestry again.
+            const { constants } = await import('node:fs');
+            const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+            let data;
+            try {
+                const opened = await handle.stat();
+                if (!opened.isFile() || opened.ino !== stat.ino || opened.dev !== stat.dev || !inside(root, await realpath(absolute)))
+                    throw new Error('Source changed during inspection');
+                data = Buffer.alloc(fileBudget + 1);
+                const read = await handle.read(data, 0, data.length, 0);
+                data = data.subarray(0, read.bytesRead);
+                if (data.length > fileBudget || data.length !== opened.size)
+                    throw new Error('Source changed during inspection');
+            }
+            finally {
+                await handle.close();
+            }
+            bytes += data.length;
+            let text;
+            try {
+                text = new TextDecoder('utf-8', { fatal: true }).decode(data);
+            }
+            catch {
+                omitted.push({ path, reason: 'binary' });
+                continue;
+            }
+            if (text.includes('\0')) {
+                omitted.push({ path, reason: 'binary' });
+                continue;
+            }
+            if (secret.test(text)) {
+                omitted.push({ path, reason: 'possible secret; entire file omitted' });
+                continue;
+            }
+            if (input.recommendations) {
+                candidates.push({ path, text });
+                continue;
+            }
+            const lines = text.split('\n');
+            const accepted = [];
+            for (const line of lines) {
+                if (Buffer.byteLength([...accepted, line].join('\n')) > Math.min(12000, maxPacketBytes - packetBytes - Buffer.byteLength(path) - 512)) {
+                    truncated = true;
+                    break;
+                }
+                accepted.push(line);
+            }
+            if (!accepted.length) {
+                truncated = true;
+                continue;
+            }
+            const excerpt = accepted.join('\n');
+            packetBytes += Buffer.byteLength(excerpt) + Buffer.byteLength(path) + 512;
+            evidence.push({ kind: 'local_source', id: `source_${evidence.length + 1}`, path, file_hash: sourceHash(text), excerpt_hash: sourceHash(excerpt), snapshot_id, start_line: 1, end_line: accepted.length, excerpt });
+        }
+    }
+    await walk(root, [{ base: root, rules: rootIgnore }]);
+    if (input.recommendations) {
+        // Fairly cover product areas before taking more detail. Generated guidance,
+        // manifests and boilerplate cannot spend the product-evidence budget.
+        const rank = (p) => /\/(?:pages|screens|views)\//i.test('/' + p) ? 0 : /\/(?:app|routes?)\.[^.]+$/i.test(p) ? 1 : /components\//.test(p) ? 2 : 3;
+        const interactions = (f) => (f.text.match(/onClick|onSubmit|onChange|const handle[A-Z]|function handle[A-Z]/g) ?? []).length;
+        candidates.sort((a, b) => rank(a.path) - rank(b.path) || a.path.split('/').length - b.path.split('/').length || interactions(b) - interactions(a) || a.path.localeCompare(b.path));
+        const areas = new Map();
+        for (const file of candidates) {
+            const key = file.path.split('/').slice(0, -1).join('/');
+            areas.set(key, [...(areas.get(key) ?? []), file]);
+        }
+        const ordered = [];
+        for (let i = 0; ordered.length < candidates.length; i++)
+            for (const files of areas.values())
+                if (files[i])
+                    ordered.push(files[i]);
+        for (const { path, text } of ordered.slice(0, 12)) {
+            const lines = text.split('\n');
+            // Start at the component/handler rather than spending the excerpt on imports.
+            const behaviors = lines.map((line, index) => ({ line, index })).filter(({ line }) => /(?:const|function)\s+(?:handle|send|upload|download|submit|complete|create|pay|save)\w*\s*(?:=|\()/i.test(line));
+            behaviors.sort((a, b) => (/send|upload|download|submit|create|pay|save/i.test(b.line) ? 1 : 0) - (/send|upload|download|submit|create|pay|save/i.test(a.line) ? 1 : 0));
+            const behavior = behaviors[0]?.index ?? -1;
+            const rendered = lines.findIndex(line => /^\s*return\s*\(?\s*$/.test(line));
+            const start = Math.max(0, behavior >= 0 ? behavior : rendered >= 0 ? rendered : lines.findIndex(line => /(?:export (?:default )?(?:function|const|class)|function [A-Z]|const [A-Z]\w*\s*=)/.test(line)));
+            const accepted = [];
+            const allowance = Math.min(850, maxPacketBytes - packetBytes - 512 - Buffer.byteLength(path));
+            for (const line of lines.slice(start)) {
+                if (Buffer.byteLength([...accepted, line].join('\n')) > allowance)
+                    break;
+                accepted.push(line);
+            }
+            if (!accepted.length)
+                continue;
+            const excerpt = accepted.join('\n');
+            packetBytes += Buffer.byteLength(excerpt) + Buffer.byteLength(path) + 512;
+            evidence.push({ kind: 'local_source', id: `source_${evidence.length + 1}`, path, file_hash: sourceHash(text), excerpt_hash: sourceHash(excerpt), snapshot_id, start_line: start + 1, end_line: start + accepted.length, excerpt });
+        }
+        truncated = ordered.length > evidence.length;
+    }
+    const packages = [];
+    const capabilities = [];
+    // Report only bounded installed SDK metadata inside this app; never follow workspace links.
+    const metadata = resolve(root, 'node_modules/@userreason/js/package.json');
+    try {
+        if (await realpath(metadata) === metadata) {
+            const stat = await lstat(metadata);
+            if (stat.isFile() && stat.size <= 16384) {
+                const manifest = JSON.parse(await readFile(metadata, 'utf8'));
+                if (manifest.name === '@userreason/js' && typeof manifest.version === 'string' && manifest.version.length <= 100) {
+                    packages.push({ name: manifest.name, version: manifest.version });
+                    // Only parse bounded declarations/metadata; never import the installed application or SDK.
+                    if (typeof manifest.types === 'string') {
+                        const declaration = resolve(metadata, '..', manifest.types);
+                        if (inside(resolve(metadata, '..'), declaration) && await realpath(declaration) === declaration) {
+                            const stat = await lstat(declaration);
+                            if (stat.isFile() && stat.size <= 262144) {
+                                const text = await readFile(declaration, 'utf8');
+                                for (const name of ['setContext', 'setAvailable', 'event'])
+                                    if (new RegExp('\\b' + name + '\\s*\\(').test(text))
+                                        capabilities.push('declared:' + name);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch { /* Missing/linked SDK is an explicit unknown, not a reason to expand scope. */ }
+    return { root, snapshot_id, evidence, omitted, truncated, inspected, packages, capabilities, capability_status: capabilities.length ? 'declared' : 'unknown', packet_digest: sourceHash(JSON.stringify(evidence)) };
+}
+/** Recheck every approved full-file hash before upload, edits or draft mutations. */
+export async function verifyFirstSurveySource(root, sources) {
+    if (await realpath(root) !== root)
+        throw new Error('Application root changed');
+    for (const source of sources) {
+        const absolute = resolve(root, source.path);
+        if (!inside(root, absolute) || source.path.includes('\\') || source.path.split('/').some(p => !p || p === '.' || p === '..') || forbidden.test(source.path))
+            throw new Error('Source boundary changed');
+        let cursor = root;
+        for (const part of source.path.split('/')) {
+            cursor = resolve(cursor, part);
+            if ((await lstat(cursor)).isSymbolicLink())
+                throw new Error('Source became a symlink');
+        }
+        const stat = await lstat(absolute);
+        if (!stat.isFile() || stat.size > 256000 || sourceHash(await readFile(absolute, 'utf8')) !== source.file_hash)
+            throw new Error('Source changed; review a new snapshot');
+    }
+}
+/** Separate opt-in; no fetch, diff, author identity, or deployment inference. */
+export async function collectFirstSurveyHistory(root, consent) {
+    if (!consent)
+        return { evidence: [] };
+    if (await realpath(root) !== root)
+        throw new Error('Canonical root required');
+    // Do not invoke repository-configured pagers, hooks or external diff tools.
+    const args = ['--no-pager', '-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null', 'log', '--no-show-signature', '-20', '--since=90 days ago', '--format=%H%x09%cI%x09%s', '--', '.'];
+    try {
+        const output = await new Promise((ok, fail) => execFile('git', args, { cwd: root, timeout: 2000, maxBuffer: 16384, env: { PATH: process.env.PATH, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_TERMINAL_PROMPT: '0' } }, (err, out) => err ? fail(err) : ok(out)));
+        const evidence = [];
+        for (const line of output.trim().split('\n').filter(Boolean)) {
+            const [commit, date, ...subject] = line.split('\t'), summary = subject.join(' ').slice(0, 1200);
+            if (!/^[a-f0-9]{40,64}$/.test(commit) || !Number.isFinite(Date.parse(date)) || !summary || secret.test(summary))
+                continue;
+            evidence.push({ kind: 'local_history', id: `history_${evidence.length + 1}`, commit: commit, date: new Date(date).toISOString(), summary });
+        }
+        return { evidence, ...(!evidence.length ? { warning: 'No bounded local history available; source is not deployment evidence.' } : {}) };
+    }
+    catch {
+        return { evidence: [], warning: 'Local history unavailable; continuing without it.' };
+    }
+}

package/dist/first-survey-terminal.d.ts

@@ -0,0 +1,5 @@
+import type { Interface } from 'node:readline/promises';
+import type { Writable } from 'node:stream';
+import type { FirstSurveyUI } from './first-survey.js';
+/** Sanitize only terminal presentation, never evidence, plans or answers. */
+export declare function firstSurveyTerminalUI(rl: Pick<Interface, 'question'>, output: Pick<Writable, 'write'>, signal?: AbortSignal): FirstSurveyUI;

package/dist/first-survey-terminal.js

@@ -0,0 +1,16 @@
+import { printable } from './docs.js';
+/** Sanitize only terminal presentation, never evidence, plans or answers. */
+export function firstSurveyTerminalUI(rl, output, signal) {
+    const show = (message) => { output.write(printable(message + '\n')); };
+    const ask = (message) => rl.question(printable(message), { signal });
+    return {
+        signal,
+        show,
+        confirm: async (message) => (await ask(message + ' [yes/no] ')) === 'yes',
+        choose: async (message, options) => {
+            show(message + '\n' + options.map(option => option.value + ': ' + option.label).join('\n'));
+            return ask('Selection: ');
+        },
+        answer: message => ask(message + ' '),
+    };
+}