@userreason/cli 0.1.1 → 0.2.0

package/dist/setup-source.js

@@ -0,0 +1,48 @@
+import { randomUUID } from 'node:crypto';
+import { collectFirstSurveySource, verifyFirstSurveySource } from './first-survey-source.js';
+import { setupDigest } from './setup-files.js';
+import { SetupError } from './setup-store.js';
+import { parseSetupSourceManifest, parseSetupSourceUploadInput } from './setup-wire.js';
+/** Reuse the bounded application collector without Git, provider calls or local packet persistence. */
+export async function prepareSetupSource(directory, preparationId = randomUUID(), signal) {
+    signal?.throwIfAborted();
+    const preview = await collectFirstSurveySource({ root: directory, snapshotId: preparationId, recommendations: true, signal });
+    await verifyFirstSurveySource(directory, preview.evidence);
+    const evidence = preview.evidence, packages = preview.packages;
+    const prepared = {
+        preparation_id: preparationId, evidence, packages,
+        manifest: {
+            packet_digest: setupDigest({ evidence, packages }), snapshot_id: preparationId,
+            files: evidence.map(item => ({ path: item.path, file_hash: item.file_hash, excerpt_hash: item.excerpt_hash,
+                bytes: Buffer.byteLength(item.excerpt), start_line: item.start_line, end_line: item.end_line })),
+            omitted_files: preview.omitted.length, truncated: preview.truncated, git_included: false,
+        },
+    };
+    // The shared public decoder enforces the actual UTF-8 wire budget, including
+    // JSON escaping; the collector's estimate is deliberately not authorization.
+    parseSetupSourceManifest(prepared.manifest);
+    parseSetupSourceUploadInput({ schema_version: 1, setup_id: preparationId, preparation_id: preparationId,
+        project_fingerprint: '0'.repeat(64), evidence });
+    return prepared;
+}
+/** An approved preparation is rebuilt with its original snapshot ID; no raw source needs a receipt. */
+export async function restoreSetupSource(directory, approved, signal) {
+    const prepared = await prepareSetupSource(directory, approved.preparation_id, signal);
+    if (setupDigest(prepared.manifest) !== setupDigest(approved.manifest) || setupDigest(prepared.packages) !== setupDigest(approved.packages))
+        throw new SetupError('setup_source_changed', 'Application source or installed package metadata changed. Review a new source packet in the browser before analysis.');
+    return prepared;
+}
+/** Revalidate immediately before upload; only the immutable reviewed memory packet may leave the process. */
+export async function verifySetupSource(directory, packet, signal) {
+    signal?.throwIfAborted();
+    if (packet.preparation_id !== packet.manifest.snapshot_id || setupDigest({ evidence: packet.evidence, packages: packet.packages }) !== packet.manifest.packet_digest)
+        throw new SetupError('setup_source_changed', 'The prepared source packet changed. Review a new packet before analysis.');
+    try {
+        await verifyFirstSurveySource(directory, packet.evidence);
+    }
+    catch {
+        throw new SetupError('setup_source_changed', 'Application files changed. Review a new source packet before analysis.');
+    }
+    await restoreSetupSource(directory, packet, signal);
+    signal?.throwIfAborted();
+}

package/dist/setup-store.d.ts

@@ -0,0 +1,37 @@
+export declare class SetupError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export type StoredSetup = {
+    schema_version: 1;
+    setup_id: string;
+    api_url: string;
+    project_fingerprint: string;
+    created_at: string;
+    expires_at: string;
+} & ({
+    state: 'pending';
+    ticket: string;
+    verifier: string;
+} | {
+    state: 'connected';
+    access_token: string;
+});
+/** A root identity, not uploaded source or a pathname in the remote setup record. */
+export declare function setupProjectFingerprint(directory: string): Promise<string>;
+export declare function parseStoredSetup(value: unknown): StoredSetup;
+/** Lazy, bounded retention cleanup; unrelated files, links and locks are left alone. */
+export declare function pruneSetupSessions(now?: number): Promise<{
+    scanned: number;
+    removed: number;
+}>;
+/** Setup capabilities never enter the general CLI credential store or project source. */
+export declare function saveSetupSession(value: StoredSetup): Promise<void>;
+export declare function loadSetupSession(origin: string, setupId: string, directory: string, now?: number): Promise<StoredSetup>;
+export declare function clearSetupSession(origin: string, setupId: string): Promise<void>;
+/** Create one private level at a time; never traverse a replaced setup ancestor. */
+export declare function setupPrivateDirectory(...parts: string[]): Promise<string>;
+/** Explicit recovery only after a crashed process is proven gone; never steals a live lock. */
+export declare function recoverSetupProjectLock(directory: string): Promise<boolean>;
+/** Fail closed on an existing lock. A stale process requires reconciliation, not a timed takeover. */
+export declare function withSetupProjectLock<T>(directory: string, operation: () => Promise<T>): Promise<T>;

package/dist/setup-store.js

@@ -0,0 +1,256 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, opendir, readFile, realpath, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { configDirectory } from './config.js';
+import { apiUrl, object, uuid } from './contracts.js';
+export class SetupError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** A root identity, not uploaded source or a pathname in the remote setup record. */
+export async function setupProjectFingerprint(directory) {
+    return createHash('sha256').update(await realpath(directory)).digest('hex');
+}
+export function parseStoredSetup(value) {
+    const data = object(value, 'stored setup');
+    const common = ['schema_version', 'setup_id', 'api_url', 'project_fingerprint', 'created_at', 'expires_at', 'state'];
+    const fields = data.state === 'pending' ? ['ticket', 'verifier'] : data.state === 'connected' ? ['access_token'] : [];
+    if (!fields.length || Object.keys(data).some(key => ![...common, ...fields].includes(key)) ||
+        [...common, ...fields].some(key => !(key in data)) || data.schema_version !== 1 ||
+        typeof data.api_url !== 'string' || apiUrl(data.api_url) !== data.api_url ||
+        typeof data.setup_id !== 'string' || uuid(data.setup_id) !== data.setup_id ||
+        typeof data.project_fingerprint !== 'string' || !/^[a-f0-9]{64}$/.test(data.project_fingerprint) ||
+        typeof data.created_at !== 'string' || typeof data.expires_at !== 'string' ||
+        !Number.isFinite(Date.parse(data.created_at)) || !Number.isFinite(Date.parse(data.expires_at)) ||
+        Date.parse(data.expires_at) <= Date.parse(data.created_at) ||
+        Date.parse(data.expires_at) - Date.parse(data.created_at) > (data.state === 'pending' ? 901_000 : 7_201_000) ||
+        fields.some(key => typeof data[key] !== 'string' || !data[key].length || data[key].length > 16_384) ||
+        (data.state === 'pending' && !/^[a-f0-9]{64}$/.test(data.verifier)) ||
+        (data.state === 'connected' && !/^ur-setup\.v1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(data.access_token))) {
+        throw new SetupError('invalid_setup_session', 'Invalid local setup session. Start a new setup; ordinary CLI credentials are unchanged.');
+    }
+    return data;
+}
+function storePath(origin, setupId) {
+    const key = createHash('sha256').update(`${apiUrl(origin)}\n${uuid(setupId)}`).digest('hex');
+    return join(configDirectory(), 'setup-v1', `${key}.json`);
+}
+const retentionMs = 7 * 24 * 60 * 60 * 1000;
+const pruneBatch = 128;
+/** Read through one bounded file handle, never through a symbolic link. */
+async function readSetupRecord(path) {
+    const before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > 65_536)
+        throw new Error('invalid setup file');
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const info = await file.stat();
+        if (!info.isFile() || info.ino !== before.ino || info.dev !== before.dev || info.size > 65_536)
+            throw new Error('changed setup file');
+        const buffer = Buffer.alloc(65_537);
+        let size = 0;
+        while (size < buffer.length) {
+            const part = await file.read(buffer, size, buffer.length - size, size);
+            if (!part.bytesRead)
+                break;
+            size += part.bytesRead;
+        }
+        if (size > 65_536)
+            throw new Error('oversized setup file');
+        return { data: parseStoredSetup(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, size)))), info };
+    }
+    finally {
+        await file.close();
+    }
+}
+async function removeSameRecord(path, info) {
+    try {
+        const current = await lstat(path);
+        if (!current.isFile() || current.isSymbolicLink() || current.ino !== info.ino || current.dev !== info.dev)
+            return false;
+        await rm(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Lazy, bounded retention cleanup; unrelated files, links and locks are left alone. */
+export async function pruneSetupSessions(now = Date.now()) {
+    if (!Number.isFinite(now))
+        return { scanned: 0, removed: 0 };
+    let directory;
+    try {
+        const path = join(configDirectory(), 'setup-v1'), info = await lstat(path);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            return { scanned: 0, removed: 0 };
+        directory = await opendir(path);
+    }
+    catch {
+        return { scanned: 0, removed: 0 };
+    }
+    let scanned = 0, removed = 0;
+    try {
+        for await (const entry of directory) {
+            if (++scanned > pruneBatch) {
+                scanned = pruneBatch;
+                break;
+            }
+            if (!entry.isFile() || !/^[a-f0-9]{64}\.json$/.test(entry.name))
+                continue;
+            const path = join(configDirectory(), 'setup-v1', entry.name);
+            try {
+                const { data, info } = await readSetupRecord(path);
+                if (storePath(data.api_url, data.setup_id) !== path || Date.parse(data.created_at) > now - retentionMs)
+                    continue;
+                if (await removeSameRecord(path, info))
+                    removed++;
+            }
+            catch { /* Unknown/corrupt files are not ours to erase. */ }
+        }
+    }
+    catch { /* Cleanup is best effort and never prevents a new setup. */ }
+    return { scanned, removed };
+}
+/** Setup capabilities never enter the general CLI credential store or project source. */
+export async function saveSetupSession(value) {
+    const data = parseStoredSetup(value), path = storePath(data.api_url, data.setup_id);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        const directory = join(configDirectory(), 'setup-v1');
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new SetupError('setup_store_failed', 'The setup store must be a regular private directory, not a symbolic link.');
+        await pruneSetupSessions();
+        const file = await open(temporary, 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(data) + '\n');
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, path);
+    }
+    catch (error) {
+        if (error instanceof SetupError)
+            throw error;
+        throw new SetupError('setup_store_failed', 'Unable to save the private setup session outside the project. Check local configuration-directory access.');
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => { });
+    }
+}
+export async function loadSetupSession(origin, setupId, directory, now = Date.now()) {
+    let data;
+    let info;
+    const path = storePath(origin, setupId);
+    try {
+        const parent = await lstat(join(configDirectory(), 'setup-v1'));
+        if (!parent.isDirectory() || parent.isSymbolicLink())
+            throw new Error('invalid setup directory');
+        ({ data, info } = await readSetupRecord(path));
+    }
+    catch (error) {
+        if (error instanceof SetupError)
+            throw error;
+        throw new SetupError('setup_session_unavailable', 'No valid local setup session for this API and ID. Resume from the original project or start a new setup.');
+    }
+    if (data.api_url !== apiUrl(origin) || data.setup_id !== setupId || data.project_fingerprint !== await setupProjectFingerprint(directory))
+        throw new SetupError('setup_binding_mismatch', 'The setup session belongs to another API or project. Use the original project and API.');
+    if (Date.parse(data.expires_at) <= now) {
+        await removeSameRecord(path, info);
+        throw new SetupError('setup_expired', 'This setup session expired. Start a new setup; saved drafts and completed local work are retained.');
+    }
+    return data;
+}
+export async function clearSetupSession(origin, setupId) {
+    await rm(storePath(origin, setupId), { force: true });
+}
+/** Create one private level at a time; never traverse a replaced setup ancestor. */
+export async function setupPrivateDirectory(...parts) {
+    let path = configDirectory();
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    for (const part of ['', 'setup-v1', ...parts]) {
+        if (part) {
+            path = join(path, part);
+            await mkdir(path, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+                throw error; });
+        }
+        const info = await lstat(path);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new SetupError('setup_store_failed', 'A private setup directory was replaced by a link.');
+    }
+    return path;
+}
+/** Explicit recovery only after a crashed process is proven gone; never steals a live lock. */
+export async function recoverSetupProjectLock(directory) {
+    const locks = await setupPrivateDirectory('project-locks');
+    const path = join(locks, `${await setupProjectFingerprint(directory)}.lock`);
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.size > 1024)
+        throw new SetupError('setup_lock_failed', 'The project lock needs manual review.');
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const now = await file.stat();
+        if (now.ino !== info.ino || now.dev !== info.dev)
+            throw new Error('changed lock');
+        const value = JSON.parse(await file.readFile('utf8'));
+        if (!Number.isInteger(value.pid) || value.pid < 1 || typeof value.owner !== 'string')
+            throw new Error('invalid lock');
+        try {
+            process.kill(value.pid, 0);
+            throw new SetupError('setup_project_locked', 'The project lock owner is still running.');
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                throw error;
+        }
+        return removeSameRecord(path, info);
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Fail closed on an existing lock. A stale process requires reconciliation, not a timed takeover. */
+export async function withSetupProjectLock(directory, operation) {
+    const fingerprint = await setupProjectFingerprint(directory);
+    const locks = await setupPrivateDirectory('project-locks');
+    const path = join(locks, `${fingerprint}.lock`), owner = randomUUID();
+    let file;
+    try {
+        file = await open(path, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new SetupError('setup_project_locked', 'Another setup owns this project. Reconcile its local results before retrying; an expired server lease does not release this lock.');
+        throw new SetupError('setup_lock_failed', 'Unable to lock this project for setup. Check local configuration-directory access.');
+    }
+    const lockInfo = await file.stat();
+    try {
+        await file.writeFile(JSON.stringify({ owner, pid: process.pid, created_at: new Date().toISOString() }));
+        await file.sync();
+        return await operation();
+    }
+    finally {
+        await file.close();
+        try {
+            if (JSON.parse(await readFile(path, 'utf8')).owner === owner)
+                await removeSameRecord(path, lockInfo);
+        }
+        catch { /* Never delete a replacement lock or mask the operation's result. */ }
+    }
+}

package/dist/setup-terminal.d.ts

@@ -0,0 +1,3 @@
+import type { SetupCapabilities } from './setup-wire.js';
+/** Fixed labels only. No process names, environment values, paths or shell are uploaded. */
+export declare function detectSetupTerminal(platform?: NodeJS.Platform, environment?: NodeJS.ProcessEnv): NonNullable<SetupCapabilities['terminal']>;

package/dist/setup-terminal.js

@@ -0,0 +1,6 @@
+/** Fixed labels only. No process names, environment values, paths or shell are uploaded. */
+export function detectSetupTerminal(platform = process.platform, environment = process.env) {
+    const detectedPlatform = platform === 'darwin' ? 'macos' : platform === 'win32' ? 'windows' : platform === 'linux' ? 'linux' : 'other';
+    const known = { Apple_Terminal: 'apple_terminal', iTerm: 'iterm2', 'iTerm.app': 'iterm2', vscode: 'vscode', cursor: 'cursor', WarpTerminal: 'warp', ghostty: 'ghostty', WezTerm: 'wezterm', Alacritty: 'alacritty', kitty: 'kitty' };
+    return { platform: detectedPlatform, app: known[environment.TERM_PROGRAM ?? ''] ?? (platform === 'win32' && environment.WT_SESSION ? 'windows_terminal' : 'generic') };
+}