@userreason/cli 0.1.0 → 0.1.1

package/dist/bin.js

@@ -1,63 +1,424 @@
 #!/usr/bin/env node
+import { eventCollection } from './event-policy.js';
+import { CaptureError, capturePage, captureUrl } from './capture.js';
+import { randomUUID } from "node:crypto";
 import { parseArgs } from "node:util";
 import { spawn } from "node:child_process";
-import { createReadStream } from "node:fs";
+import { createReadStream, readFileSync } from "node:fs";
 import { UserReasonClient, ApiError } from "./client.js";
 import { resolveConfig, saveConfig } from "./config.js";
-import { keychainCredentials } from "./credentials.js";
+import { resolveCredentials, CredentialStoreError } from "./credentials.js";
 import { object, origin, scope, uuid } from "./contracts.js";
-import { login } from "./workos.js";
-const help = `UserReason CLI\n\nuserreason login [--open]\nuserreason logout\nuserreason whoami\nuserreason workspace list\nuserreason workspace create --name NAME\nuserreason site list --workspace UUID\nuserreason site create --workspace UUID --name NAME --origin URL [--origin URL]\nuserreason grant request --scope site:read [--scope site:create] [--workspace UUID] [--wait]\nuserreason grant status --id UUID [--wait]\nuserreason command --file COMMAND.json\nuserreason query --workspace UUID --resource surveys [--site UUID] [--limit 50] [--after UUID]\n\nGlobal options: --dev, --api-url ORIGIN, --client-id CLIENT_ID, --json\nCreation options: --request-id UUID, --workspace-id UUID / --site-id UUID\nSite environment: --environment development|production (default production)\nCredentials are stored in the OS credential store. WorkOS API keys are never required.\n`;
+import { DocsError, formatDocsSearch, getDocsPage, printable, searchDocs } from "./docs.js";
+import { authorizeCli } from "./authorize.js";
+import { detectProjectTarget } from "./project.js";
+import { cliHelp, commandCatalog, getCommandReference, searchCommands } from './catalog.js';
+import { AuthenticationError } from './workos.js';
+import { ConfigurationError, NetworkError } from './errors.js';
+import { docsOrigin, packageProfile } from "./profile.js";
+import { createSpinner, createUiKit, detectAgentHarness, detectColorLevel } from './ui.js';
+import { nounHelp, overviewHelp, overviewNouns, suggestCommand } from './help.js';
+import { grantSummary, promptsView, resultsOverviewView, sitesView, whoamiView, workspacesView } from './views.js';
+/** Terminal styling applies only to a person at a terminal: never when piped, with --json, or in an agent harness. */
+let errorStyle;
+const cliVersion = () => { try {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+}
+catch {
+    return undefined;
+} };
+const developmentApi = () => { try {
+    return packageProfile().apiEnvironment === 'development';
+}
+catch {
+    return false;
+} };
+class UnknownCommand extends Error {
+    word;
+    suggestion;
+    constructor(word, suggestion) {
+        super(`Unknown command "${word}".${suggestion ? ` Did you mean userreason ${suggestion}?` : ''} Run userreason --help to see all commands.`);
+        this.word = word;
+        this.suggestion = suggestion;
+    }
+}
+/** Split an error message into its headline and the sentences that tell the person what to do. */
+function splitMessage(message) {
+    const [first = message, ...rest] = message.split(/(?<=[.!?])\s+(?=[A-Z])/);
+    return { headline: first.replace(/\.$/, ''), hints: rest };
+}
+function humanError(kit, detail, error, retryInfo) {
+    const { c, S } = kit;
+    const lines = [];
+    let headline, hints;
+    if (error instanceof UnknownCommand) {
+        headline = `Unknown command ${c.code(error.word)}`;
+        hints = [...(error.suggestion ? [`${c.muted('Did you mean')} ${c.code(`userreason ${error.suggestion}`)}${c.muted('?')}`] : []), `${c.muted('Search:')} ${c.code(`userreason cli search "${error.word}"`)}`];
+    }
+    else if (error instanceof ApiError && error.code === 'authorization_required') {
+        headline = `Access required ${c.muted(`${S.dot} the current login lacks access to this target`)}`;
+        hints = [`${c.muted('Review workspace access:')} ${c.code('userreason access --open')}`, ...(detail.approval_url ? [`${c.muted('Approval link:')} ${c.code(detail.approval_url)}`] : [])];
+    }
+    else if (detail.error === 'invalid_grant') {
+        headline = `Not signed in ${c.muted(`${S.dot} your session expired or was revoked`)}`;
+        hints = [`${c.muted('Run')} ${c.code('userreason login --open')}`];
+    }
+    else {
+        const split = splitMessage(detail.message);
+        headline = split.headline;
+        hints = split.hints.map(hint => c.muted(hint));
+    }
+    if (retryInfo) {
+        const id = retryInfo.prompt_id ?? retryInfo.audience_id ?? retryInfo.event_definition_id;
+        hints.push(`${c.muted('Retry with the same input:')} ${c.code(`${id ? `--id ${id} ` : ''}--request-id ${retryInfo.request_id}`)}`, c.muted('Read the resource first if you change the request.'));
+    }
+    lines.push(`${kit.symbol.error}  ${headline}`, ...hints.map(hint => `${c.danger(S.bar)}    ${hint}`));
+    return lines;
+}
+let retry;
+async function readJsonFile(file) {
+    const chunks = [];
+    let size = 0;
+    for await (const part of createReadStream(file, { highWaterMark: 16_384 })) {
+        const chunk = Buffer.from(part);
+        size += chunk.byteLength;
+        if (size > 65_536)
+            throw new Error("JSON file exceeds 64 KB");
+        chunks.push(chunk);
+    }
+    let body;
+    try {
+        body = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)));
+    }
+    catch {
+        throw new Error("File must contain valid UTF-8 JSON");
+    }
+    return object(body, "JSON file");
+}
 async function main() {
     const parsed = parseArgs({ allowPositionals: true, strict: true, options: {
-            help: { type: "boolean", short: "h" }, json: { type: "boolean" }, dev: { type: "boolean" }, open: { type: "boolean" }, wait: { type: "boolean" },
-            "api-url": { type: "string" }, "client-id": { type: "string" }, name: { type: "string" }, workspace: { type: "string" }, id: { type: "string" },
+            all: { type: "boolean" }, human: { type: "boolean" }, "no-color": { type: "boolean" },
+            width: { type: 'string' }, height: { type: 'string' }, 'capture-bin': { type: 'string' }, 'browser-executable': { type: 'string' }, interactive: { type: 'boolean' },
+            preview: { type: "boolean" }, confirm: { type: "string" }, help: { type: "boolean", short: "h" }, json: { type: "boolean" }, dev: { type: "boolean" }, open: { type: "boolean" }, wait: { type: "boolean" }, "no-wait": { type: "boolean" },
+            offline: { type: "boolean" }, live: { type: "boolean" }, "credential-store": { type: "string" }, "api-url": { type: "string" }, "docs-url": { type: "string" }, "client-id": { type: "string" }, name: { type: "string" }, workspace: { type: "string" }, id: { type: "string" },
             origin: { type: "string", multiple: true }, scope: { type: "string", multiple: true }, site: { type: "string", multiple: true }, environment: { type: "string" },
             "request-id": { type: "string" }, "workspace-id": { type: "string" }, "site-id": { type: "string" },
-            file: { type: "string" }, resource: { type: "string" }, limit: { type: "string" }, after: { type: "string" },
+            file: { type: "string" }, "context-file": { type: "string" }, purpose: { type: "string" }, mode: { type: "string" }, "confirmation-token": { type: "string" }, resource: { type: "string" }, limit: { type: "string" }, after: { type: "string" }, revision: { type: "string" }, "prompt-id": { type: "string" },
+            days: { type: "string" }, "time-zone": { type: "string" }, country: { type: "string" }, segment: { type: "string" }, by: { type: "string" }, user: { type: "string" }, kind: { type: "string" }, search: { type: "string" }, cursor: { type: "string" },
+            run: { type: 'string' }, variant: { type: 'string' }, 'all-attempts': { type: 'boolean' }, 'reported-only': { type: 'boolean' },
         } });
-    const values = parsed.values, [command, action] = parsed.positionals;
+    const values = parsed.values, [command, action, positionalId] = parsed.positionals;
+    if (action === 'delete' && positionalId && command === 'workspace')
+        values.workspace = uuid(positionalId);
+    if (action === 'delete' && positionalId && command === 'site')
+        values.site = [uuid(positionalId)];
+    const harness = detectAgentHarness();
+    const humanOut = Boolean(process.stdout.isTTY) && !values.json && (!harness || Boolean(values.human));
+    const humanErr = Boolean(process.stderr.isTTY) && !values.json && (!harness || Boolean(values.human));
+    const kit = createUiKit({ level: detectColorLevel({ stream: process.stdout, off: values["no-color"] }) });
+    const errKit = createUiKit({ level: detectColorLevel({ stream: process.stderr, off: values["no-color"] }), stream: process.stderr });
+    errorStyle = { human: humanErr, kit: errKit };
     if (values.help || !command) {
-        process.stdout.write(help);
+        const noun = command && values.help ? nounHelp(kit, command) : undefined;
+        process.stdout.write(values.all ? cliHelp() : noun ?? overviewHelp(kit, { version: cliVersion(), development: values.dev ?? developmentApi(), trademark: humanOut }));
+        return;
+    }
+    if (!overviewNouns.includes(command)) {
+        const guess = suggestCommand(command);
+        throw new UnknownCommand(command, guess);
+    }
+    // A command name without an action is a usage error, as before: the actions go to stderr and the exit code is 1.
+    if (!action && nounHelp(errKit, command)) {
+        process.stderr.write(nounHelp(errKit, command));
+        process.exitCode = 1;
         return;
     }
     const required = (key) => { const value = values[key]; if (typeof value !== "string" || !value)
         throw new Error(`Missing --${key}`); return value; };
-    const config = await resolveConfig({ development: values.dev, apiUrl: values["api-url"], clientId: values["client-id"] });
-    const credentials = keychainCredentials(config), client = new UserReasonClient(config, credentials);
-    let result;
-    if (command === "login") {
-        const authenticated = await login(config, credentials, device => {
-            process.stderr.write(`Open ${device.verificationUriComplete}\nConfirm code: ${device.userCode}\n`);
-            if (values.open) {
-                const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer.exe" : "xdg-open";
-                const child = spawn(command, [device.verificationUriComplete], { stdio: "ignore", detached: true });
-                child.on("error", () => { });
-                child.unref();
+    if (command === "cli") {
+        const words = parsed.positionals.slice(2).join(' ');
+        const result = action === 'search' ? searchCommands(words, values.limit === undefined ? 5 : Number(values.limit)) : action === 'get' ? getCommandReference(words) : action === 'list' ? commandCatalog : undefined;
+        if (!result)
+            throw new Error('Use userreason cli search "QUESTION", cli get "COMMAND", or cli list');
+        process.stdout.write((humanOut ? kit.json(result) : JSON.stringify(result, null, values.json ? undefined : 2)) + '\n');
+        return;
+    }
+    if (values.offline && values.live)
+        throw new Error('Choose --offline or --live');
+    if (command === "docs") {
+        // Public documentation: no login, saved configuration or credential store is involved.
+        let projectDevelopment;
+        if (!values['docs-url'] && !process.env.UR_DOCS_URL && values.dev === undefined) {
+            try {
+                const target = await detectProjectTarget();
+                if (target && ['https://api.userreason.com', 'https://api-dev.userreason.com'].includes(target.apiUrl))
+                    projectDevelopment = target.apiUrl === 'https://api-dev.userreason.com';
             }
+            catch { /* Reading docs never requires a resolvable project. */ }
+        }
+        const docs = { offline: values.offline, live: values.live ?? false, origin: values["docs-url"] ?? (process.env.UR_DOCS_URL || docsOrigin(values.dev ?? projectDevelopment ?? packageProfile().apiEnvironment === "development")) }, words = parsed.positionals.slice(2);
+        if (action === "search") {
+            const found = await searchDocs({ ...docs, query: words.join(" "), limit: values.limit === undefined ? undefined : Number(values.limit) });
+            if (found.warning)
+                process.stderr.write(found.warning.message + '\nUsing the bundled CLI reference.\n');
+            process.stdout.write(values.json ? JSON.stringify(found) + "\n" : formatDocsSearch(found));
+        }
+        else if (action === "get") {
+            if (words.length > 1)
+                throw new Error("docs get reads one page");
+            const page = await getDocsPage({ ...docs, target: words[0] ?? "" });
+            process.stdout.write(values.json ? JSON.stringify(page) + "\n" : printable(page.markdown).trimEnd() + "\n");
+        }
+        else
+            throw new Error('Use userreason docs search "QUESTION" or userreason docs get URL_OR_PATH');
+        return;
+    }
+    let project;
+    try {
+        project = await detectProjectTarget();
+    }
+    catch (error) {
+        if (!values.workspace && !values.site)
+            throw error;
+    }
+    const explicitApi = values["api-url"] ?? process.env.UR_API_URL ?? (values.dev ? 'https://api-dev.userreason.com' : undefined);
+    if (project && !values.workspace && !values.site && explicitApi && new URL(explicitApi).origin !== project.apiUrl)
+        throw new Error('The selected API differs from the project SDK. Supply --site and --workspace explicitly to target another environment.');
+    const selectedApi = explicitApi ?? project?.apiUrl;
+    const development = values.dev ?? (selectedApi === 'https://api-dev.userreason.com' ? true : selectedApi === 'https://api.userreason.com' ? false : packageProfile().apiEnvironment === 'development');
+    const config = await resolveConfig({ development, apiUrl: selectedApi, clientId: values["client-id"], credentialStore: values["credential-store"] });
+    const credentials = resolveCredentials(config), client = new UserReasonClient(config, credentials);
+    const targeting = ['preview', 'prompt', 'audience', 'results', 'responses', 'user', 'event', 'member', 'query', 'site'].includes(command);
+    let targetName;
+    if (targeting && !values.workspace) {
+        const siteId = values.site?.length === 1 ? values.site[0] : project?.siteId;
+        if (siteId) {
+            const site = await client.siteById(uuid(siteId));
+            targetName = printable(site.name);
+            values.workspace = site.workspace_id;
+            if (!values.site && project && !(command === 'site' && ['list', 'create'].includes(action ?? '')))
+                values.site = [site.id];
+            if (!values.json)
+                process.stderr.write(humanErr
+                    ? `${errKit.symbol.info}  ${errKit.c.muted(`Using ${printable(site.name)} (${site.environment})`)}\n`
+                    : `Using ${printable(site.name)} (${site.id}) on ${config.apiUrl}\n`);
+        }
+    }
+    let result;
+    if (command === "login" || command === "access") {
+        const open = (url) => {
+            if (!values.open)
+                return;
+            const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer.exe" : "xdg-open";
+            const child = spawn(command, [url], { stdio: "ignore", detached: true });
+            child.on("error", () => { });
+            child.unref();
+        };
+        let spinner = undefined;
+        const say = (kind, text) => process.stderr.write(`${errKit.symbol[kind]}  ${text}\n`);
+        const link = (url) => process.stderr.write(`${errKit.c.faint(errKit.S.bar)}    ${errKit.c.code(url)}\n`);
+        const wait = (text) => { spinner = createSpinner(errKit, process.stderr); spinner.start(text); };
+        result = await authorizeCli(config, credentials, {
+            client, wait: !values["no-wait"],
+            onDevice: device => {
+                if (!humanErr) {
+                    process.stderr.write(`Open ${device.verificationUriComplete}\nConfirm code: ${device.userCode}\n`);
+                    open(device.verificationUriComplete);
+                    return;
+                }
+                say('info', `${values.open ? 'Opening the browser to sign in' : 'Open the link to sign in'} ${errKit.S.dot} ${errKit.c.muted('code')} ${errKit.c.code(device.userCode)}`);
+                if (!values.open)
+                    link(device.verificationUriComplete);
+                open(device.verificationUriComplete);
+                wait('Waiting for sign-in');
+            },
+            onApproval: request => {
+                if (humanErr && spinner) {
+                    spinner.stop();
+                    spinner = undefined;
+                    say('done', 'Signed in');
+                }
+                if (!request.approval_url)
+                    return;
+                if (!humanErr) {
+                    process.stderr.write(`Review workspace access and permissions: ${request.approval_url}\n`);
+                    open(request.approval_url);
+                    return;
+                }
+                say('info', `Review workspace access and permissions in the browser`);
+                if (!values.open)
+                    link(request.approval_url);
+                open(request.approval_url);
+                if (!values["no-wait"])
+                    wait('Waiting for approval');
+            },
         });
-        await saveConfig(config, values.dev);
-        result = { authenticated: true, email: authenticated.email, api_url: config.apiUrl };
+        spinner?.stop();
+        if (humanErr && !values["no-wait"]) {
+            const grant = result.grant;
+            const summary = grantSummary(grant);
+            say('done', `Access approved${summary ? ` ${errKit.c.muted(`(${summary})`)}` : ''}`);
+        }
+        await saveConfig(config, development);
     }
     else if (command === "logout") {
         await credentials.clear();
         result = { logged_out: true, message: "Local credentials removed. Revoke approved agent access in the dashboard if needed." };
     }
-    else if (command === "whoami")
-        result = await client.account();
+    else if (command === "whoami") {
+        const account = await client.account();
+        let target = null;
+        if (project) {
+            try {
+                target = { ...project, site: await client.siteById(project.siteId), access: 'approved' };
+            }
+            catch (error) {
+                if (!(error instanceof ApiError))
+                    throw error;
+                target = { ...project, access: error.code, next_step: 'userreason access --open' };
+            }
+        }
+        result = { ...account, api_url: config.apiUrl, project: target };
+    }
+    else if (command === 'preview' && action === 'capture') {
+        if (!positionalId || parsed.positionals.length !== 3)
+            throw new Error('Use userreason preview capture URL --dev');
+        const url = captureUrl(positionalId);
+        if (values.site?.length !== 1)
+            throw new Error('Capture requires one --site or a detected project site');
+        const workspaceId = uuid(required('workspace')), siteId = uuid(values.site[0]);
+        // Check the environment and existing read access before launching Chrome or downloading tools.
+        await client.previewCaptures(workspaceId, siteId, true);
+        if (!values.json)
+            process.stderr.write('Capturing locally with SingleFile. Only the HTML capture is uploaded.\n');
+        const start = performance.now();
+        const html = await capturePage(url.href, {
+            width: values.width === undefined ? undefined : Number(values.width), height: values.height === undefined ? undefined : Number(values.height),
+            engine: values['capture-bin'], browser: values['browser-executable'],
+            interactive: values.interactive,
+            onProgress: values.json ? undefined : message => process.stderr.write(message + '\n'),
+        });
+        const captureMs = performance.now() - start, uploadStart = performance.now();
+        if (!values.json)
+            process.stderr.write(`Captured ${(html.byteLength / 1024).toFixed(0)} KiB. Uploading to the development preview…\n`);
+        const saved = object(await client.uploadPreview(workspaceId, siteId, values.name ?? url.hostname, html), 'capture');
+        result = { ...saved, capture_ms: Math.round(captureMs), upload_ms: Math.round(performance.now() - uploadStart) };
+        if (values.open) {
+            const links = object(saved.links, 'capture links'), target = new URL(String(links.preview));
+            if (!['https:', 'http:'].includes(target.protocol) || target.username || target.password)
+                throw new Error('Invalid dashboard preview URL');
+            const child = spawn(process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer.exe' : 'xdg-open', [target.href], { stdio: 'ignore', detached: true });
+            child.on('error', () => { });
+            child.unref();
+        }
+    }
+    else if (command === 'deletion' && action === 'status')
+        result = await client.deletion('status', { workspace_id: uuid(required('workspace')), id: uuid(required('id')) });
+    else if (['workspace', 'site', 'prompt'].includes(command) && action === 'delete') {
+        const workspace_id = uuid(required('workspace'));
+        const resource_id = command === 'workspace' ? workspace_id : command === 'site' ? uuid(positionalId ?? values.site?.[0] ?? required('id')) : uuid(positionalId ?? required('id'));
+        if (command !== 'workspace' && values.site?.length !== 1)
+            throw new Error('Deletion requires exactly one --site');
+        const target = { workspace_id, resource_type: command, resource_id, ...(command !== 'workspace' ? { site_id: uuid(values.site[0]) } : {}) };
+        if (values.preview || !values.confirm)
+            result = await client.deletion('preview', target);
+        else {
+            const request_id = uuid(values['request-id'] ?? randomUUID());
+            retry = { request_id };
+            result = await client.deletion('request', { ...target, request_id, expected_revision: required('revision'), confirmation_token: required('confirmation-token'), confirm_name: values.confirm });
+        }
+    }
     else if (command === "workspace" && action === "list")
         result = (await client.account()).workspaces;
     else if (command === "workspace" && action === "create")
         result = await client.createWorkspace(required("name"), { requestId: values["request-id"], workspaceId: values["workspace-id"] });
     else if (command === "site" && action === "list")
         result = await client.sites(uuid(required("workspace")));
+    else if (["results", "responses", "user", "event", "member"].includes(command) || (command === "site" && (action === "activity" || action === "frequency" || action === "events")) || (command === "prompt" && action === "history")) {
+        // Reads the dashboard also shows, and the two site settings with commands of their own.
+        const workspaceId = uuid(required("workspace"));
+        if (command === "member") {
+            if (action !== "list")
+                throw new Error("Use userreason member list");
+            result = await client.read('members.list', { workspaceId });
+        }
+        else {
+            if (!values.site || values.site.length !== 1)
+                throw new Error("This command requires one --site");
+            const context = { workspaceId, siteId: uuid(values.site[0]) }, sub = parsed.positionals[2];
+            const number = (key) => values[key] === undefined ? undefined : Number(values[key]);
+            const segment = values.segment === undefined ? [] : values.segment.split("=");
+            if (values.segment !== undefined && (segment.length !== 2 || !segment[0]))
+                throw new Error("Use --segment key=value, such as --segment browser=Chrome");
+            const range = { days: number("days"), time_zone: values["time-zone"] };
+            const filters = { country: values.country, ...(segment.length ? { segment_key: segment[0], segment_value: segment[1] } : {}) };
+            const page = { cursor: values.cursor, limit: number("limit") };
+            const requestId = uuid(values["request-id"] ?? randomUUID());
+            const send = async (body, ids = {}) => {
+                retry = { request_id: requestId, ...ids };
+                const sent = { ...object(await client.command({ ...body, workspace_id: context.workspaceId, site_id: context.siteId, request_id: requestId }), 'result'), ...retry };
+                retry = undefined;
+                return sent;
+            };
+            if (command === "results" && action === "overview")
+                result = await client.read('insights.overview', { ...context, ...range, ...filters });
+            else if (command === "results" && action === "prompt")
+                result = await client.read('insights.prompt', { ...context, ...range, ...filters, prompt_id: uuid(positionalId ?? required("prompt-id")) });
+            else if (command === "results" && action === "experiments")
+                result = await client.read('insights.experiments', { ...context, prompt_id: uuid(positionalId ?? required('prompt-id')), run_id: values.run, all_attempts: values['all-attempts'] ?? false, reported_only: values['reported-only'] ?? false });
+            else if (command === "results" && action === "breakdown")
+                result = await client.read('insights.breakdown', { ...context, ...range, ...filters, by: required("by"), prompt_id: values["prompt-id"] });
+            else if (command === "responses" && action === "list")
+                result = await client.read('responses.list', { ...context, ...filters, ...page, days: number("days"), prompt_id: values["prompt-id"], user_id: values.user, search: values.search, run_id: values.run, variant_id: values.variant });
+            else if (command === "user" && action === "list")
+                result = await client.read('users.list', { ...context, ...page, days: number("days"), kind: values.kind, country: values.country, search: values.search });
+            else if (command === "user" && action === "get")
+                result = await client.read('users.get', { ...context, user_id: uuid(positionalId ?? required("user")) });
+            else if (command === "user" && action === "eligibility") {
+                // A file tries an audience that is not published yet on this person: an audience file, or the rule alone.
+                const file = values.file ? await readJsonFile(values.file) : undefined;
+                result = await client.read('users.eligibility', { ...context, user_id: uuid(positionalId ?? required("user")), draft: file ? { audience: 'rule' in file && !('type' in file) ? file.rule : file } : undefined });
+            }
+            else if (command === "prompt")
+                result = await client.read('prompts.history', context);
+            else if (command === "event" && action === "overview")
+                result = await client.read('events.overview', { ...context, ...range });
+            else if (command === "event" && action === "list")
+                result = await client.query({ ...context, resource: 'events', limit: number("limit"), after: values.after });
+            else if (command === "event" && (action === "create" || action === "update")) {
+                const eventId = uuid(positionalId ?? values.id ?? (action === 'create' ? randomUUID() : required("id")));
+                const file = await readJsonFile(required("file"));
+                result = await send({ action: `event.${action}`, event_definition_id: eventId, ...(action === 'create' ? { event_key: file.event_key } : { expected_revision: required("revision") }), properties: file.properties ?? {}, collection: eventCollection(file, values.purpose) }, { event_definition_id: eventId });
+            }
+            else if (command === "site" && action === "events") {
+                const mode = required("mode");
+                if (!['all', 'registered', 'explicit'].includes(mode))
+                    throw new Error('Mode must be all, registered or explicit');
+                const limits = values.file ? (await readJsonFile(values.file)) : undefined;
+                if (sub === 'preview')
+                    result = await client.query({ ...context, resource: 'event_capture', eventCaptureMode: mode, eventCollectionLimits: limits });
+                else if (sub === 'set')
+                    result = await send({ action: 'site.events.update', event_capture_mode: mode, event_collection_limits: limits, expected_revision: required('revision'), confirmation_token: values['confirmation-token'] });
+                else
+                    throw new Error('Use site events preview or site events set');
+            }
+            else if (command === "site" && action === "activity")
+                result = await client.read('site.activity', context);
+            else if (command === "site" && sub === "get") {
+                const record = await client.siteRecord(context);
+                result = { site_id: record.id, revision: record.revision, frequency_policy: record.frequency_policy ?? null };
+            }
+            else if (command === "site" && (sub === "set" || sub === "reset"))
+                result = await send({ action: 'site.frequency.update', expected_revision: required("revision"), frequency_policy: sub === "set" ? await readJsonFile(required("file")) : null });
+            else
+                throw new Error(`Unknown ${command} action. Run userreason --help`);
+        }
+    }
     else if (command === "site" && action === "create") {
         const environment = values.environment ?? (values.dev ? "development" : "production");
         if (environment !== "production" && environment !== "development")
             throw new Error("Invalid --environment");
-        if (!values.origin?.length)
-            throw new Error("Supply one or more --origin values");
-        result = await client.createSite({ workspaceId: uuid(required("workspace")), name: required("name"), environment, origins: [...new Set(values.origin.map(value => origin(value, environment)))], requestId: values["request-id"], siteId: values["site-id"] });
+        result = await client.createSite({ workspaceId: uuid(required("workspace")), name: required("name"), environment, origins: [...new Set((values.origin ?? []).map(value => origin(value, environment)))], requestId: values["request-id"], siteId: values["site-id"] });
     }
     else if (command === "grant" && action === "request") {
         const request = await client.requestGrant({ workspaceId: values.workspace, siteIds: values.site, scopes: (values.scope ?? []).flatMap(value => value.split(",")).map(scope), requestId: values["request-id"] });
@@ -68,36 +429,105 @@ async function main() {
     else if (command === "grant" && action === "status")
         result = values.wait ? await client.waitForGrant(required("id")) : await client.grantStatus(required("id"));
     else if (command === "command") {
-        const chunks = [];
-        let size = 0;
-        for await (const part of createReadStream(required("file"), { highWaterMark: 16_384 })) {
-            const chunk = Buffer.from(part);
-            size += chunk.byteLength;
-            if (size > 65_536)
-                throw new Error("Command JSON file exceeds 64 KB");
-            chunks.push(chunk);
-        }
-        let body;
-        try {
-            body = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)));
-        }
-        catch {
-            throw new Error("Command file must contain valid UTF-8 JSON");
-        }
-        result = await client.command(object(body, "command"));
+        result = await client.command(await readJsonFile(required("file")));
     }
     else if (command === "query") {
         if (values.site && values.site.length !== 1)
             throw new Error("A query accepts one --site");
-        result = await client.query({ workspaceId: required("workspace"), siteId: values.site?.[0], resource: required("resource"), limit: values.limit === undefined ? undefined : Number(values.limit), after: values.after });
+        result = await client.query({ workspaceId: required("workspace"), siteId: values.site?.[0], resource: required("resource"), limit: values.limit === undefined ? undefined : Number(values.limit), after: values.after, id: values.id, promptId: values["prompt-id"] });
+    }
+    else if (command === "prompt") {
+        if (!values.site || values.site.length !== 1)
+            throw new Error("Survey commands require one --site");
+        const context = { workspaceId: uuid(required("workspace")), siteId: uuid(values.site[0]) };
+        const page = { limit: values.limit === undefined ? undefined : Number(values.limit), after: values.after };
+        if (action === "validate")
+            result = await client.read('prompts.validate', { ...context, definition: await readJsonFile(required("file")), ...(values["context-file"] ? await readJsonFile(values["context-file"]) : {}) });
+        else if (action === "list")
+            result = await client.prompts({ ...context, ...page });
+        else {
+            if (positionalId && values.id && positionalId !== values.id)
+                throw new Error("Survey IDs disagree");
+            const promptId = uuid(positionalId ?? values.id ?? (action === 'create' ? randomUUID() : required("id")));
+            if (action === "get")
+                result = await client.prompt({ ...context, promptId });
+            else if (action === "responses")
+                result = await client.query({ ...context, ...page, resource: 'responses', promptId });
+            else {
+                if (!["create", "update", "publish", "pause", "resume", "archive"].includes(action ?? ''))
+                    throw new Error("Unknown survey action");
+                const definition = action === 'create' || action === 'update' ? await readJsonFile(required("file")) : undefined;
+                const requestId = uuid(values["request-id"] ?? randomUUID());
+                retry = { request_id: requestId, prompt_id: promptId };
+                result = { ...object(await client.promptCommand({ ...context, action: action, promptId, requestId, revision: values.revision, definition }), 'survey result'), ...retry };
+                retry = undefined;
+            }
+        }
+    }
+    else if (command === "audience") {
+        if (!values.site || values.site.length !== 1)
+            throw new Error("Audience commands require one --site");
+        const context = { workspaceId: uuid(required("workspace")), siteId: uuid(values.site[0]) };
+        if (action === "list")
+            result = await client.audiences({ ...context, limit: values.limit === undefined ? undefined : Number(values.limit), after: values.after });
+        else {
+            if (positionalId && values.id && positionalId !== values.id)
+                throw new Error("Audience IDs disagree");
+            const audienceId = uuid(positionalId ?? values.id ?? (action === 'create' ? randomUUID() : required("id")));
+            if (action === "get")
+                result = await client.audience({ ...context, audienceId });
+            else {
+                if (!["create", "update", "publish", "discard", "archive"].includes(action ?? ''))
+                    throw new Error("Unknown audience action");
+                const audience = action === 'create' || action === 'update' ? await readJsonFile(required("file")) : undefined;
+                const requestId = uuid(values["request-id"] ?? randomUUID());
+                retry = { request_id: requestId, audience_id: audienceId };
+                result = { ...object(await client.audienceCommand({ ...context, action: action, audienceId, requestId, revision: values.revision, audience }), 'audience result'), ...retry };
+                retry = undefined;
+            }
+        }
     }
     else
         throw new Error("Unknown command. Run userreason --help");
-    process.stdout.write(JSON.stringify(result, null, values.json ? undefined : 2) + "\n");
+    if (command === 'logout' && humanErr) {
+        process.stderr.write(`${errKit.symbol.done}  Signed out ${errKit.c.muted(`${errKit.S.dot} local credentials removed`)}\n${errKit.symbol.info}  ${errKit.c.muted('Revoke approved agent access in the dashboard if needed.')}\n`);
+        if (!humanOut)
+            process.stdout.write(JSON.stringify(result, null, values.json ? undefined : 2) + "\n");
+        return;
+    }
+    // A person at a terminal has just read the progress lines; the JSON result needs --json or a pipe.
+    if ((command === 'login' || command === 'access') && humanOut && !values["no-wait"])
+        return;
+    const view = humanOut ? humanView(kit, command, action, result) : undefined;
+    process.stdout.write((view ? view.join('\n') : humanOut ? kit.json(result) : JSON.stringify(result, null, values.json ? undefined : 2)) + "\n");
+    function humanView(ui, name, verb, data) {
+        try {
+            if (name === 'whoami')
+                return whoamiView(ui, data, { development });
+            if (name === 'site' && verb === 'list' && Array.isArray(data))
+                return sitesView(ui, data);
+            if (name === 'workspace' && verb === 'list' && Array.isArray(data))
+                return workspacesView(ui, data);
+            if (name === 'prompt' && verb === 'list' && data && typeof data === 'object')
+                return promptsView(ui, data, targetName);
+            if (name === 'results' && verb === 'overview' && data && typeof data === 'object')
+                return resultsOverviewView(ui, data, targetName);
+        }
+        catch { /* A response in an unexpected shape falls back to highlighted JSON. */ }
+        return undefined;
+    }
 }
 main().catch(error => {
     const json = process.argv.includes("--json");
-    const detail = { error: error instanceof ApiError ? error.code : "command_failed", message: error instanceof Error ? error.message : "Command failed", ...(error instanceof ApiError && error.approvalUrl ? { approval_url: error.approvalUrl } : {}) };
-    process.stderr.write((json ? JSON.stringify(detail) : detail.message) + "\n");
-    process.exitCode = 1;
+    const detail = { error: error instanceof ApiError || error instanceof DocsError || error instanceof CredentialStoreError || error instanceof NetworkError || error instanceof AuthenticationError || error instanceof ConfigurationError || error instanceof CaptureError ? error.code : "command_failed", message: error instanceof Error ? error.message : "Command failed", ...(error instanceof ApiError && error.approvalUrl ? { approval_url: error.approvalUrl } : {}), ...(retry ? { retry } : {}) };
+    const exitCode = error instanceof CaptureError && error.code === 'capture_cancelled' ? 130 : 1;
+    if (error instanceof ApiError && error.code === 'authorization_required')
+        detail.message += '. The current login lacks access to this target. Run userreason access --open to review workspace access and permissions.';
+    if (!json && errorStyle?.human) {
+        process.stderr.write(humanError(errorStyle.kit, detail, error, retry).join('\n') + '\n');
+        process.exitCode = exitCode;
+        return;
+    }
+    process.stderr.write((json ? JSON.stringify(detail) : detail.message + (retry ? `\nRetry with the same input, --id ${retry.prompt_id} --request-id ${retry.request_id}; read the survey first if changing the request.` : "")) + "\n");
+    process.exitCode = exitCode;
 });

package/dist/capture.d.ts

@@ -0,0 +1,18 @@
+/** External, pinned capture tool; no SingleFile source is bundled into the UserReason package. */
+export declare const CAPTURE_ENGINE = "single-file-cli@2.0.77";
+export type CaptureOptions = {
+    width?: number;
+    height?: number;
+    engine?: string;
+    browser?: string;
+    timeoutMs?: number;
+    interactive?: boolean;
+    onProgress?: (message: string) => void;
+};
+export declare class CaptureError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare function captureUrl(value: string): URL;
+export declare function captureArguments(url: string, output: string, options?: CaptureOptions): string[];
+export declare function capturePage(value: string, options?: CaptureOptions): Promise<Uint8Array>;