@userreason/cli 0.2.0 → 0.2.1

package/README.md

@@ -324,7 +324,17 @@ until tested: reachable configuration is not browser verification. Instrumentati
 requires a reviewed, hash-guarded diff and separate edit approval using the agent
 skill; unsupported host transforms are never executed automatically.
 
-The 0.2.0 production installation profile selects `@userreason/js@0.5.0` and
-`@userreason/cli@0.2.0` exactly. Browser setup remains an explicit wizard entry
+The 0.2.1 production installation profile selects `@userreason/js@0.5.3` and
+`@userreason/cli@0.2.1` exactly. Browser setup remains an explicit wizard entry
 and requires an enabled compatible server; ordinary CLI authentication and
 management commands retain their existing authorization flow.
+
+Local setup execution failures retain bounded, redacted diagnostic text in the
+private execution receipt. `onOperationError` displays it on failure and resume.
+The detailed text never enters setup API requests or telemetry; the server still
+receives only the typed outcome code.
+
+A new run automatically recovers an existing project lock only after verifying
+that its recorded process no longer exists. It still acquires the lock exclusively,
+keeps all installation receipts for reconciliation, and refuses live, unreadable
+or malformed locks. A live-lock error identifies the process to finish or stop.

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

@@ -43,6 +43,7 @@ export declare function collectFirstSurveySource(input: {
     snapshotId?: string;
     signal?: AbortSignal;
     recommendations?: boolean;
+    benchmark?: 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>;

package/dist/first-survey-source.js

@@ -4,6 +4,7 @@ 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';
+import { connectedRecommendationSource } from './recommendation-source.js';
 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;
@@ -30,10 +31,10 @@ export async function collectFirstSurveySource(input) {
     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);
+    const maxFiles = safeLimits(input.maxFiles, input.benchmark ? 1200 : 200, input.benchmark ? 1200 : 200);
+    const maxBytes = safeLimits(input.maxBytes, input.benchmark ? 12 * 1024 * 1024 : input.recommendations ? 2 * 1024 * 1024 : 500 * 1024, input.benchmark ? 12 * 1024 * 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 maxPacketBytes = safeLimits(input.maxPacketBytes, input.benchmark ? 262144 : 10000, input.benchmark ? 262144 : 10000);
     const snapshot_id = input.snapshotId ?? randomUUID();
     const omitted = [], evidence = [];
     let inspected = 0, bytes = 0, packetBytes = 0, truncated = false, entries = 0;
@@ -59,7 +60,7 @@ export async function collectFirstSurveySource(input) {
     const check = () => input.signal?.throwIfAborted();
     async function walk(directory, inherited) {
         check();
-        if (entries >= 2000 || inspected >= maxFiles || bytes >= maxBytes) {
+        if (entries >= (input.benchmark ? 20000 : 2000) || inspected >= maxFiles || bytes >= maxBytes) {
             truncated = true;
             return;
         }
@@ -81,13 +82,15 @@ export async function collectFirstSurveySource(input) {
         });
         for (const name of names) {
             check();
-            if (++entries > 2000 || inspected >= maxFiles || bytes >= maxBytes) {
+            if (++entries > (input.benchmark ? 20000 : 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.benchmark && /(?:^|\/)(?:scripts|tools|test|tests|__tests__|e2e|docs|examples|storybook|\.storybook)(?:\/|$)/i.test(path))
+                continue;
             if (input.recommendations && /^(?:\.agents|\.cursor|\.codex)(?:\/|$)/.test(path))
                 continue;
             const stat = await lstat(absolute);
@@ -175,7 +178,13 @@ export async function collectFirstSurveySource(input) {
         }
     }
     await walk(root, [{ base: root, rules: rootIgnore }]);
-    if (input.recommendations) {
+    if (input.benchmark) {
+        for (const file of connectedRecommendationSource(candidates, maxPacketBytes)) {
+            evidence.push({ kind: 'local_source', id: `source_${evidence.length + 1}`, path: file.path, file_hash: sourceHash(candidates.find(c => c.path === file.path).text), excerpt_hash: sourceHash(file.text), snapshot_id, start_line: file.start, end_line: file.end, excerpt: file.text });
+        }
+        truncated = candidates.length > evidence.length || evidence.some(e => e.start_line !== 1 || e.excerpt !== candidates.find(c => c.path === e.path)?.text);
+    }
+    else 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;

package/dist/index.d.ts

@@ -22,6 +22,7 @@ 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";

package/dist/index.js

@@ -22,6 +22,7 @@ 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";

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.5.0", cliVersion: "0.2.0",
+    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/setup-diagnostics.d.ts

@@ -0,0 +1,2 @@
+/** Bounded, local-only diagnostics. Never include these in setup API requests. */
+export declare function sanitizeSetupDiagnostic(value: string, secrets?: string[]): string;

package/dist/setup-diagnostics.js

@@ -0,0 +1,26 @@
+/** Bounded, local-only diagnostics. Never include these in setup API requests. */
+export function sanitizeSetupDiagnostic(value, secrets = []) {
+    let text = value.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
+    const environmentSecrets = Object.entries(process.env)
+        .filter(([key, value]) => /token|secret|password|api[_-]?key|authorization/i.test(key) && value && value.length >= 4)
+        .map(([, value]) => value);
+    for (const secret of [...secrets, ...environmentSecrets].filter(value => value.length >= 4).sort((a, b) => b.length - a.length))
+        text = text.split(secret).join('[redacted]');
+    text = text.replace(/\b(Bearer|Basic)\s+[^\s]+/gi, '$1 [redacted]');
+    text = text.replace(/((?:_authToken|_password|password|access_token|refresh_token|api_key|authorization)\s*[:=]\s*)[^\s]+/gi, '$1[redacted]');
+    text = text.replace(/\b(?:gh[pousr]_[A-Za-z0-9_]+|github_pat_[A-Za-z0-9_]+|npm_[A-Za-z0-9]+|sk-[A-Za-z0-9_-]{16,})\b/g, '[redacted]');
+    text = text.replace(/https?:\/\/[^\s<>"']+/g, value => {
+        try {
+            const url = new URL(value);
+            url.username = '';
+            url.password = '';
+            url.search = '';
+            url.hash = '';
+            return url.toString();
+        }
+        catch {
+            return '[invalid URL]';
+        }
+    });
+    return text.trim().slice(0, 8000);
+}

package/dist/setup-executor.d.ts

@@ -1,5 +1,6 @@
 import { type BrowserSetupClient } from './setup.js';
 import { type SetupLocalPlan, type SetupEffect, type SetupSessionView } from './setup-wire.js';
+import { SetupHeartbeat } from './setup-heartbeat.js';
 import { type SetupLocalFile } from './setup-files.js';
 export interface PreparedSetupOperation {
     effect: SetupEffect;
@@ -27,9 +28,15 @@ export interface SetupExecutorOptions {
     maxPolls?: number;
     sleep?: (ms: number) => Promise<void>;
     onSession?: (session: SetupSessionView) => void;
+    /** Sanitized local detail, retained in the private journal, never sent to the API. */
+    onOperationError?: (failure: {
+        kind: SetupEffect['kind'];
+        message: string;
+        receiptPath: string;
+    }) => void;
 }
 export type SetupExecutorClient = Pick<BrowserSetupClient, 'identity' | 'poll' | 'plan' | 'claim' | 'startCommand' | 'report' | 'heartbeat' | 'reconcile'>;
 /** Bounded local cleanup never restores authority or follows an unknown file/link. */
 export declare function pruneSetupExecutionReceipts(now?: number): Promise<number>;
 /** Runs only after browser approval. Durable intents precede effects and durable outcomes precede reports. */
-export declare function runSetupExecutor(client: SetupExecutorClient, directory: string, runtime: SetupExecutorRuntime, options?: SetupExecutorOptions): Promise<SetupSessionView>;
+export declare function runSetupExecutor(client: SetupExecutorClient, directory: string, runtime: SetupExecutorRuntime, options?: SetupExecutorOptions, sharedHeartbeat?: SetupHeartbeat): Promise<SetupSessionView>;