@userreason/cli 0.1.0 → 0.2.0

package/dist/project.js

@@ -0,0 +1,87 @@
+import ts from 'typescript';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { apiUrl, uuid } from './contracts.js';
+const explicit = 'Supply --workspace and --site (and --api-url or --dev for that environment).';
+async function source(root, file) {
+    const path = resolve(root, file), rel = relative(root, path);
+    if (rel.startsWith('..') || !rel)
+        return;
+    let current = root;
+    for (const part of rel.split(sep)) {
+        current = join(current, part);
+        try {
+            if ((await lstat(current)).isSymbolicLink())
+                throw new Error(`Cannot inspect symlinked project file ${file}. ${explicit}`);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+    const info = await lstat(path);
+    if (!info.isFile() || info.size > 2_000_000)
+        throw new Error(`Cannot inspect project file ${file}. ${explicit}`);
+    return readFile(path, 'utf8');
+}
+/** Parse static SDK initialization only. Never execute application code or select an arbitrary account site. */
+export async function detectProjectTarget(directory = process.cwd()) {
+    let root = await realpath(directory);
+    while (!(await source(root, 'package.json'))) {
+        const parent = dirname(root);
+        if (parent === root)
+            return;
+        root = parent;
+    }
+    const candidates = new Set();
+    for (const folder of ['', 'src/'])
+        for (const name of ['main', 'index', 'instrumentation-client', 'userreason.client', 'userreason.generated'])
+            for (const extension of ['ts', 'tsx', 'js', 'jsx', 'mjs'])
+                candidates.add(`${folder}${name}.${extension}`);
+    const html = await source(root, 'index.html');
+    for (const match of html?.matchAll(/<script\b([^>]*)>/gi) ?? []) {
+        const src = /\bsrc\s*=\s*['"]([^'"]+)['"]/i.exec(match[1])?.[1];
+        if (src && /\btype\s*=\s*['"]module['"]/i.test(match[1]) && !/^(?:[a-z]+:|\/\/)|[?#]/i.test(src))
+            candidates.add(src.replace(/^\//, ''));
+    }
+    let found;
+    for (const file of candidates) {
+        const text = await source(root, file);
+        if (!text)
+            continue;
+        const ast = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, /x$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+        const bindings = new Set(ast.statements.filter(ts.isImportDeclaration)
+            .filter(node => ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === '@userreason/js')
+            .map(node => node.importClause?.name?.text).filter(Boolean));
+        const visit = (node) => {
+            if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'init' && bindings.has(node.expression.expression.getText(ast))) {
+                if (ast.parseDiagnostics?.length)
+                    throw new Error(`Invalid SDK initialization in ${file}. ${explicit}`);
+                const options = node.arguments[0];
+                if (!options || !ts.isObjectLiteralExpression(options))
+                    throw new Error(`Dynamic SDK initialization in ${file}. ${explicit}`);
+                const values = {};
+                for (const prop of options.properties) {
+                    if (ts.isSpreadAssignment(prop))
+                        throw new Error(`Spread SDK options in ${file}. ${explicit}`);
+                    const name = prop.name && (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) ? prop.name.text : '';
+                    if (!['siteId', 'workspaceId', 'apiBaseUrl'].includes(name))
+                        continue;
+                    if (!ts.isPropertyAssignment(prop) || !(ts.isStringLiteral(prop.initializer) || ts.isNoSubstitutionTemplateLiteral(prop.initializer)) || name in values)
+                        throw new Error(`Dynamic SDK option ${name} in ${file}. ${explicit}`);
+                    values[name] = prop.initializer.text;
+                }
+                if (values.siteId) {
+                    const target = { directory: root, file, siteId: uuid(values.siteId, 'SDK siteId'), apiUrl: apiUrl(values.apiBaseUrl ?? 'https://api.userreason.com'), ...(values.workspaceId ? { workspaceId: uuid(values.workspaceId) } : {}) };
+                    if (found && (found.siteId !== target.siteId || found.apiUrl !== target.apiUrl || found.workspaceId !== target.workspaceId))
+                        throw new Error(`Multiple SDK targets in this project. ${explicit}`);
+                    found = target;
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(ast);
+    }
+    return found;
+}

package/dist/recommended-surveys.d.ts

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

package/dist/recommended-surveys.js

@@ -0,0 +1,201 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { configDirectory } from "./config.js";
+import { sourceHash, verifyFirstSurveySource, } from "./first-survey-source.js";
+import { prepareFirstSurveyLocally, } from "./first-survey-preparation.js";
+const record = (v) => v && typeof v === "object" && !Array.isArray(v)
+    ? v
+    : {};
+/** One optional selection; all drafts stay unpublished and match no audience. */
+export async function recommendedSurveys(client, root, workspace, site, ui, options = {}) {
+    if (!options.sourceConsent)
+        return { state: "skipped" };
+    if (!ui.chooseMany)
+        throw Error("Survey selection requires a checkbox interface");
+    const scope = {
+        api: client.config.apiUrl,
+        workspace_id: workspace,
+        site_id: site,
+    };
+    const scopeKey = sourceHash(JSON.stringify([root, scope]));
+    const dir = join(configDirectory(), "recommended-surveys");
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, scopeKey + ".json");
+    const lock = await open(path + ".lock", "wx", 0o600);
+    const preparation = options.preparation ?? prepareFirstSurveyLocally(root);
+    let state = {
+        version: 1,
+        scope: scopeKey,
+        expires: Date.now() + 7 * 86400000,
+        candidates: [],
+        sources: [],
+        receipts: {},
+    };
+    const save = async () => {
+        const tmp = path + "." + randomUUID() + ".tmp";
+        await writeFile(tmp, JSON.stringify(state), { flag: "wx", mode: 0o600 });
+        await rename(tmp, path);
+    };
+    const check = () => ui.signal?.throwIfAborted();
+    try {
+        try {
+            const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                if ((await file.stat()).size > 128000)
+                    throw Error("Invalid recommendation cache");
+                const old = JSON.parse(await file.readFile("utf8"));
+                if (old.version !== 1 || old.scope !== scopeKey)
+                    throw Error("Recommendation scope changed");
+                if (old.expires > Date.now())
+                    state = old;
+            }
+            finally {
+                await file.close();
+            }
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+        check();
+        // A previous selected save can be retried without changing its definitions or IDs.
+        if (!state.selected) {
+            if (state.candidates.length) {
+                try {
+                    await verifyFirstSurveySource(root, state.sources);
+                }
+                catch {
+                    state.candidates = [];
+                    state.sources = [];
+                }
+            }
+            if (!state.candidates.length) {
+                const generate = async () => {
+                    const preview = await preparation.take(ui.signal);
+                    if (!preview.evidence.length)
+                        throw Error("No product source available");
+                    const metadata = record(await client.request("/onboarding/v1/planning/describe", { schema_version: 1, session_id: randomUUID(), scope }, ui.signal));
+                    if (!record(metadata.recommendations).version)
+                        throw Error("Development recommendation pipeline is unavailable");
+                    await verifyFirstSurveySource(root, preview.evidence);
+                    const response = record(await client.request("/onboarding/v1/planning/analyze", {
+                        schema_version: 1,
+                        session_id: randomUUID(),
+                        request_id: randomUUID(),
+                        scope,
+                        packages: preview.packages,
+                        capabilities: [
+                            ...preview.capabilities,
+                            "recommended_surveys:v1",
+                        ],
+                        evidence: preview.evidence,
+                        previous_plan_digest: null,
+                        limits: {
+                            input_tokens: 12000,
+                            output_tokens: 4000,
+                            deadline_ms: 40000,
+                        },
+                        consent: {
+                            packet_digest: sourceHash(JSON.stringify(preview.evidence)),
+                            destination: metadata.destination,
+                            configuration_fingerprint: metadata.configuration_fingerprint,
+                            policy_version: "first-survey-v1",
+                            authorized_at: new Date().toISOString(),
+                            git_authorized: false,
+                        },
+                    }, ui.signal));
+                    await verifyFirstSurveySource(root, preview.evidence);
+                    const candidates = record(response.result).candidates;
+                    if (!Array.isArray(candidates))
+                        throw Error("Invalid recommendations");
+                    state.candidates = candidates.slice(0, 3);
+                    state.sources = preview.evidence.map(({ path, file_hash }) => ({
+                        path,
+                        file_hash,
+                    }));
+                    await save();
+                };
+                try {
+                    if (ui.loading)
+                        await ui.loading("Finding recommended surveys", generate);
+                    else
+                        await generate();
+                }
+                catch (error) {
+                    check();
+                    ui.show("Recommendations are unavailable right now. Setup is complete; rerun the wizard to try again.");
+                    return {
+                        state: "unavailable",
+                        error: error instanceof Error ? error.message : "unavailable",
+                    };
+                }
+            }
+            if (!state.candidates.length) {
+                ui.show("No supported survey recommendations yet. Setup is complete.");
+                return { state: "empty" };
+            }
+            ui.show("Select surveys to get started. We’ll create drafts in your workspace. Nothing will be published.");
+            const selected = await ui.chooseMany("Recommended surveys", state.candidates.map((c) => ({
+                value: c.id,
+                label: `${String(c.definition.name)} — ${c.question}`,
+                hint: `${c.opportunity.claim} Delivery can be configured later.`,
+            })), []);
+            check();
+            if (!selected.length)
+                return { state: "skipped" };
+            if (new Set(selected).size !== selected.length ||
+                selected.some((id) => !state.candidates.some((c) => c.id === id)))
+                throw Error("Invalid survey selection");
+            await verifyFirstSurveySource(root, state.sources);
+            // Validate all selected drafts before writing any of them.
+            for (const id of selected) {
+                const c = state.candidates.find((c) => c.id === id);
+                const validation = record(await client.read("prompts.validate", {
+                    workspaceId: workspace,
+                    siteId: site,
+                    definition: c.definition,
+                }));
+                if (validation.valid !== true)
+                    throw Error("A recommended draft did not validate");
+            }
+            state.selected = selected;
+            for (const id of selected)
+                state.receipts[id] = {
+                    prompt: randomUUID(),
+                    request: randomUUID(),
+                    definition: state.candidates.find((c) => c.id === id).definition,
+                };
+            await save();
+        }
+        let count = 0;
+        for (const id of state.selected) {
+            check();
+            const receipt = state.receipts[id];
+            if (!receipt)
+                throw Error("Missing draft receipt");
+            if (!receipt.result) {
+                receipt.result = await client.promptCommand({
+                    workspaceId: workspace,
+                    siteId: site,
+                    action: "create",
+                    promptId: receipt.prompt,
+                    requestId: receipt.request,
+                    definition: receipt.definition,
+                });
+                await save();
+            }
+            const saved = record(receipt.result), link = record(saved.links).edit;
+            ui.show(`Draft saved: ${String(receipt.definition.name)}${typeof link === "string" ? `\n${link}` : ""}`);
+            count++;
+        }
+        ui.show(`${count} survey draft${count === 1 ? "" : "s"} saved. Nothing was published.`);
+        return { state: "saved", count, receipts: state.receipts };
+    }
+    finally {
+        preparation.cancel();
+        await lock.close();
+        await unlink(path + ".lock");
+    }
+}

package/dist/setup-executor.d.ts

@@ -0,0 +1,35 @@
+import { type BrowserSetupClient } from './setup.js';
+import { type SetupLocalPlan, type SetupEffect, type SetupSessionView } from './setup-wire.js';
+import { type SetupLocalFile } from './setup-files.js';
+export interface PreparedSetupOperation {
+    effect: SetupEffect;
+    files: SetupLocalFile[];
+    guards?: {
+        path: string;
+        before_hash: string | null;
+    }[];
+}
+export interface PreparedSetupPlan {
+    wire: SetupLocalPlan;
+    operations: PreparedSetupOperation[];
+}
+export interface SetupExecutorRuntime {
+    prepare(session: SetupSessionView): Promise<PreparedSetupPlan>;
+    /** Only a locally prepared allowlisted operation is passed here, never a server script. */
+    apply(operation: PreparedSetupOperation, signal: AbortSignal): Promise<'verified' | 'already_present'>;
+    /** Installed package versions require a runtime check in addition to file hashes. */
+    verify?(operation: PreparedSetupOperation): Promise<boolean>;
+}
+export interface SetupExecutorOptions {
+    signal?: AbortSignal;
+    pollMs?: number;
+    heartbeatMs?: number;
+    maxPolls?: number;
+    sleep?: (ms: number) => Promise<void>;
+    onSession?: (session: SetupSessionView) => 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>;