@userreason/cli 0.1.1 → 0.2.0

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 + ' '),
+    };
+}

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 {};