@userreason/cli 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @userreason/cli
+
+The public CLI uses the same authenticated onboarding API as the dashboard and MCP. This source package is prepared for publication; the npm package is not published by building it.
+
+```sh
+npm ci
+npm test
+node dist/bin.js --help
+```
+
+After publication:
+
+```sh
+npx -y @userreason/cli@latest login --open
+npx -y @userreason/cli@latest whoami --json
+```
+
+The CLI discovers the public WorkOS client ID from `/onboarding/v1/auth-config` when no override, environment value or saved configuration exists. Discovery is bounded, timed out, environment checked and never follows redirects or receives authentication secrets. The public client ID is configuration, not a secret; `--client-id` or `UR_WORKOS_CLIENT_ID` can override it. `--dev` selects `https://api-dev.userreason.com` and uses `UR_WORKOS_DEV_CLIENT_ID` when provided. Production defaults to `https://api.userreason.com`. `--api-url` accepts HTTPS origins or loopback HTTP for local development. Successful login saves nonsecret client/API configuration separately for each environment.
+
+Login uses [WorkOS CLI Auth](https://workos.com/docs/authkit/cli-auth): a public device client confirms a code in the browser, polls at the prescribed interval and receives access/refresh tokens. No WorkOS API key, client secret or UserReason signing key is required. Device codes and tokens are never printed.
+
+Credentials live in macOS Keychain, Windows Credential Manager or Linux Secret Service through `@napi-rs/keyring`. There is no plaintext fallback. If the store is unavailable, enable it before logging in. Rotating refresh-token exchanges are serialized across CLI/wizard processes. Credentials are separated by API origin and WorkOS client ID. On provider outages, stored credentials are retained; a revoked/expired refresh grant requires a new login.
+
+Authentication does not grant workspace or site access to an agent. A human approves a local UserReason grant through the dashboard:
+
+```sh
+userreason grant request \
+  --scope workspace:create \
+  --scope workspace:read \
+  --scope site:create \
+  --scope site:read \
+  --scope site:update \
+  --wait
+
+userreason workspace create --name "Acme" --json
+userreason site create \
+  --workspace WORKSPACE_UUID \
+  --name "Acme application" \
+  --origin https://app.example.com \
+  --environment production \
+  --json
+```
+
+An account-level workspace-creation grant permits one creation. The backend binds its remaining permissions to the new workspace and removes `workspace:create`. Creating another workspace requires another approval. For an existing workspace, include `--workspace WORKSPACE_UUID` when requesting a grant. Use `--site SITE_UUID` to request site restrictions. Survey editing and campaign publishing have separate scopes and are not requested by installation.
+
+Use `--request-id UUID` and `--workspace-id UUID` or `--site-id UUID` to make externally orchestrated creation retries deterministic. Reuse the exact payload and IDs on retry. Default IDs are generated once per command and preserved across an access-token refresh; separate command invocations generate new IDs.
+
+`--json` emits a single JSON result on stdout. Browser links, login instructions and errors use stderr. A nonzero exit code means the command failed. An authorization-required error may contain an `approval_url`; request and approve the required scope before retrying. The `x-ur-client` header is a transport hint: the Worker derives identity and grant binding from the verified token.
+
+```sh
+userreason workspace list --json
+userreason site list --workspace WORKSPACE_UUID --json
+userreason grant status --id REQUEST_UUID --wait --json
+userreason logout
+```
+
+Approved agents can also use the delegated management endpoints:
+
+```sh
+userreason query --workspace WORKSPACE_UUID --site SITE_UUID --resource surveys --limit 50 --json
+userreason command --file survey-command.json --json
+```
+
+The command file is a versioned management command with `action`, `workspace_id`, `request_id`, site/resource IDs and its action-specific fields. Edits/publishing/deletion also require the current `expected_revision` where defined by the API. The CLI streams at most 64 KB from the local JSON file, and the server validates the complete command and enforces the exact action's scope. Reuse the unchanged file/UUIDs for a retry. Commands named `*.delete` archive or disable records; responses and published versions remain immutable. Workspace/site creation uses the dedicated onboarding commands instead.
+
+Queries support `sites`, `surveys`, `campaigns`, `events`, `responses` and `audits`, with a limit of 1–100 and an optional `--after` UUID from the server's `next` field. Site restrictions and current workspace membership are enforced server-side.
+
+Logout removes local credentials. Revoke the relevant grant in the dashboard to remove server-side agent access. The packaged [UserReason skill](skills/userreason/SKILL.md) describes agent use of these commands.
+
+The CLI uses `/onboarding/v1/...`; those endpoints require the new migrations, configured WorkOS environment and deployed Worker. Live provider authentication is not exercised by the local fixture tests.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { spawn } from "node:child_process";
+import { createReadStream } from "node:fs";
+import { UserReasonClient, ApiError } from "./client.js";
+import { resolveConfig, saveConfig } from "./config.js";
+import { keychainCredentials } 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`;
+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" },
+            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" },
+        } });
+    const values = parsed.values, [command, action] = parsed.positionals;
+    if (values.help || !command) {
+        process.stdout.write(help);
+        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();
+            }
+        });
+        await saveConfig(config, values.dev);
+        result = { authenticated: true, email: authenticated.email, api_url: config.apiUrl };
+    }
+    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 === "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 (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"] });
+    }
+    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"] });
+        if (request.approval_url)
+            process.stderr.write(`Approve access: ${request.approval_url}\n`);
+        result = values.wait ? await client.waitForGrant(request.id) : request;
+    }
+    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"));
+    }
+    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 });
+    }
+    else
+        throw new Error("Unknown command. Run userreason --help");
+    process.stdout.write(JSON.stringify(result, null, values.json ? undefined : 2) + "\n");
+}
+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;
+});

package/dist/client.d.ts

@@ -0,0 +1,56 @@
+import { type Account, type Credentials, type GrantRequest, type Scope, type Site, type Workspace } from "./contracts.js";
+import type { ClientConfig } from "./config.js";
+import { type Fetch } from "./workos.js";
+export declare class ApiError extends Error {
+    status: number;
+    code: string;
+    approvalUrl?: string | undefined;
+    constructor(status: number, code: string, approvalUrl?: string | undefined);
+}
+export declare class UserReasonClient {
+    readonly config: ClientConfig;
+    private credentials;
+    private options;
+    private fetcher;
+    constructor(config: ClientConfig, credentials: Credentials, options?: {
+        fetcher?: Fetch;
+        lock?: <T>(operation: () => Promise<T>) => Promise<T>;
+    });
+    private token;
+    request(path: string, body?: unknown): Promise<unknown>;
+    account(): Promise<Account>;
+    createWorkspace(name: string, options?: {
+        requestId?: string;
+        workspaceId?: string;
+    }): Promise<Workspace>;
+    sites(workspaceId: string): Promise<Site[]>;
+    createSite(input: {
+        workspaceId: string;
+        name: string;
+        environment: Site["environment"];
+        origins: string[];
+        requestId?: string;
+        siteId?: string;
+    }): Promise<Site>;
+    requestGrant(input: {
+        workspaceId?: string;
+        siteIds?: string[];
+        scopes: Scope[];
+        requestId?: string;
+    }): Promise<GrantRequest>;
+    grantStatus(id: string): Promise<GrantRequest>;
+    /** The server parses the complete versioned command and derives authorization from the verified caller. */
+    command(input: Record<string, unknown>): Promise<unknown>;
+    query(input: {
+        workspaceId: string;
+        siteId?: string;
+        resource: string;
+        limit?: number;
+        after?: string;
+    }): Promise<unknown>;
+    waitForGrant(id: string, options?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+        onStatus?: (request: GrantRequest) => void;
+    }): Promise<GrantRequest>;
+}

package/dist/client.js

@@ -0,0 +1,140 @@
+import { randomUUID } from "node:crypto";
+import { object, string, uuid, workspace, site, grantRequest } from "./contracts.js";
+import { refresh } from "./workos.js";
+import { withSessionLock } from "./lock.js";
+export class ApiError extends Error {
+    status;
+    code;
+    approvalUrl;
+    constructor(status, code, approvalUrl) {
+        super(`UserReason request failed (${status}, ${code})${approvalUrl ? `. Approve access at ${approvalUrl}` : ""}`);
+        this.status = status;
+        this.code = code;
+        this.approvalUrl = approvalUrl;
+    }
+}
+export class UserReasonClient {
+    config;
+    credentials;
+    options;
+    fetcher;
+    constructor(config, credentials, options = {}) {
+        this.config = config;
+        this.credentials = credentials;
+        this.options = options;
+        this.fetcher = options.fetcher ?? fetch;
+    }
+    async token(forceRefresh = false, previous) {
+        const lock = this.options.lock ?? ((operation) => withSessionLock(this.config, operation));
+        return lock(async () => {
+            const current = await this.credentials.load();
+            if (!current)
+                throw new Error("Run userreason login first");
+            if (current.apiUrl !== this.config.apiUrl || current.clientId !== this.config.clientId)
+                throw new Error("Stored login belongs to a different environment or WorkOS client");
+            if (current.expiresAt > Date.now() + 60_000 && (!forceRefresh || current.accessToken !== previous))
+                return current;
+            return refresh(this.config, this.credentials, current, this.fetcher);
+        });
+    }
+    async request(path, body) {
+        if (!path.startsWith("/onboarding/v1/") || path.includes("//") || path.includes("\\"))
+            throw new Error("Invalid UserReason API path");
+        let session = await this.token();
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const response = await this.fetcher(this.config.apiUrl + path, { method: body === undefined ? "GET" : "POST", redirect: "error", headers: { Authorization: `Bearer ${session.accessToken}`, "x-ur-client": "cli", "Content-Type": "application/json" }, ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(20_000) });
+            if (response.status === 401 && attempt === 0) {
+                session = await this.token(true, session.accessToken);
+                continue;
+            }
+            let result;
+            try {
+                result = await response.json();
+            }
+            catch {
+                throw new ApiError(response.status, "invalid_response");
+            }
+            if (!response.ok) {
+                const data = object(result, "error"), detail = typeof data.error === "object" && data.error ? object(data.error, "error") : data;
+                const code = typeof detail.code === "string" && /^[a-z0-9_:-]{1,100}$/i.test(detail.code) ? detail.code : typeof data.error === "string" && /^[a-z0-9_:-]{1,100}$/i.test(data.error) ? data.error : "request_failed";
+                const candidate = detail.approval_url ?? data.approval_url;
+                let approvalUrl;
+                if (typeof candidate === "string") {
+                    try {
+                        const url = new URL(candidate);
+                        if (url.protocol === "https:" && !url.username && !url.password)
+                            approvalUrl = url.toString();
+                    }
+                    catch { /* Reject malformed URLs. */ }
+                }
+                throw new ApiError(response.status, code, approvalUrl);
+            }
+            return result;
+        }
+        throw new ApiError(401, "authentication_required");
+    }
+    async account() {
+        const data = object(await this.request("/onboarding/v1/account"), "account"), user = object(data.user, "user");
+        uuid(string(user.id, "user ID"));
+        if (!Array.isArray(data.workspaces) || !Array.isArray(data.grants))
+            throw new Error("Invalid account memberships");
+        return { ...data, user, workspaces: data.workspaces.map(workspace) };
+    }
+    async createWorkspace(name, options = {}) {
+        if (!name.trim() || name.length > 240)
+            throw new Error("Workspace name must contain 1–240 characters");
+        const value = object(await this.request("/onboarding/v1/workspaces", { request_id: uuid(options.requestId ?? randomUUID()), workspace_id: uuid(options.workspaceId ?? randomUUID()), name: name.trim() }), "workspace creation");
+        return workspace(value.workspace ?? value);
+    }
+    async sites(workspaceId) {
+        const data = object(await this.request(`/onboarding/v1/workspaces/${uuid(workspaceId)}/sites`), "sites"), items = data.items ?? data.sites;
+        if (!Array.isArray(items))
+            throw new Error("Invalid site list");
+        return items.map(site);
+    }
+    async createSite(input) {
+        if (!input.name.trim() || input.name.length > 240)
+            throw new Error("Site name must contain 1–240 characters");
+        const value = object(await this.request("/onboarding/v1/sites", { request_id: uuid(input.requestId ?? randomUUID()), workspace_id: uuid(input.workspaceId), site_id: uuid(input.siteId ?? randomUUID()), name: input.name.trim(), environment: input.environment, allowed_origins: input.origins }), "site creation");
+        return site(value.site ?? value);
+    }
+    async requestGrant(input) {
+        if (!input.scopes.length || input.scopes.length > 7)
+            throw new Error("Request at least one supported permission");
+        return grantRequest(await this.request("/onboarding/v1/grants/request", { request_id: uuid(input.requestId ?? randomUUID()), workspace_id: input.workspaceId ? uuid(input.workspaceId) : null, site_ids: input.siteIds?.map(id => uuid(id)) ?? null, scopes: [...new Set(input.scopes)] }));
+    }
+    async grantStatus(id) { return grantRequest(await this.request(`/onboarding/v1/grants/requests/${uuid(id)}`)); }
+    /** The server parses the complete versioned command and derives authorization from the verified caller. */
+    async command(input) {
+        uuid(string(input.workspace_id, "workspace ID"));
+        uuid(string(input.request_id, "request ID"));
+        if (typeof input.action !== "string" || !/^[a-z]+\.[a-z]+$/.test(input.action))
+            throw new Error("Command requires a supported resource.action");
+        if (input.action === "workspace.create" || input.action === "site.create")
+            throw new Error("Use workspace create or site create for authenticated onboarding");
+        return this.request("/onboarding/v1/command", input);
+    }
+    async query(input) {
+        if (!["sites", "surveys", "campaigns", "events", "responses", "audits"].includes(input.resource))
+            throw new Error("Unsupported query resource");
+        const limit = input.limit ?? 50;
+        if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+            throw new Error("Query limit must be an integer from 1 to 100");
+        return this.request("/onboarding/v1/query", { workspace_id: uuid(input.workspaceId), ...(input.siteId ? { site_id: uuid(input.siteId) } : {}), resource: input.resource, limit, ...(input.after ? { after: uuid(input.after) } : {}) });
+    }
+    async waitForGrant(id, options = {}) {
+        const deadline = Date.now() + (options.timeoutMs ?? 300_000);
+        do {
+            const request = await this.grantStatus(id);
+            options.onStatus?.(request);
+            if (request.status === "approved")
+                return request;
+            if (request.status !== "pending")
+                throw new Error(`Access request ${request.status}; request access again if needed`);
+            if (request.expires_at && Date.parse(request.expires_at) <= Date.now())
+                throw new Error("Access request expired; request access again");
+            await new Promise(resolve => setTimeout(resolve, options.intervalMs ?? 2000));
+        } while (Date.now() < deadline);
+        throw new Error("Access approval timed out; check userreason grant status --id " + id);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+export interface ClientConfig {
+    apiUrl: string;
+    clientId: string;
+}
+export declare const configDirectory: () => string;
+export declare function discoverAuthConfig(url: string, development?: boolean, fetcher?: typeof fetch): Promise<string>;
+export declare function resolveConfig(options?: {
+    development?: boolean;
+    apiUrl?: string;
+    clientId?: string;
+}): Promise<ClientConfig>;
+export declare function saveConfig(config: ClientConfig, development?: boolean): Promise<void>;

package/dist/config.js

@@ -0,0 +1,88 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { apiUrl, object } from "./contracts.js";
+export const configDirectory = () => join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "userreason");
+export async function discoverAuthConfig(url, development = false, fetcher = fetch) {
+    let response;
+    try {
+        response = await fetcher(`${apiUrl(url)}/onboarding/v1/auth-config`, { headers: { Accept: "application/json" }, redirect: "error", signal: AbortSignal.timeout(10_000) });
+    }
+    catch {
+        throw new Error("Unable to discover UserReason authentication configuration. Check the API deployment or supply its public --client-id.");
+    }
+    if (!response.ok)
+        throw new Error(`UserReason authentication configuration is unavailable (${response.status}). Configure WorkOS in the Worker before running the wizard.`);
+    if (!response.headers.get("content-type")?.toLowerCase().startsWith("application/json") || !response.body)
+        throw new Error("Invalid UserReason authentication configuration response");
+    const reader = response.body.getReader(), chunks = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            bytes += part.value.byteLength;
+            if (bytes > 4096) {
+                await reader.cancel();
+                throw new Error("UserReason authentication configuration response is too large");
+            }
+            chunks.push(part.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const buffer = new Uint8Array(bytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        buffer.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    let config;
+    try {
+        config = object(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(buffer)), "authentication configuration");
+    }
+    catch {
+        throw new Error("Invalid UserReason authentication configuration response");
+    }
+    if (Object.keys(config).some(key => !["client_id", "authkit_domain", "environment"].includes(key)) || typeof config.client_id !== "string" || !/^client_[A-Za-z0-9]{1,230}$/.test(config.client_id) || typeof config.authkit_domain !== "string" || config.authkit_domain.length > 2048)
+        throw new Error("Invalid UserReason authentication configuration response");
+    const domain = apiUrl(config.authkit_domain);
+    if (!domain.startsWith("https://") || domain !== config.authkit_domain)
+        throw new Error("Invalid WorkOS AuthKit domain in authentication configuration");
+    if (config.environment !== "local" && config.environment !== (development ? "development" : "production"))
+        throw new Error("API authentication environment does not match the selected CLI environment; use --dev for development");
+    return config.client_id;
+}
+export async function resolveConfig(options = {}) {
+    const environment = options.development ? "development" : "production";
+    let saved = {};
+    try {
+        const root = object(JSON.parse(await readFile(join(configDirectory(), "config.json"), "utf8")), "configuration");
+        saved = object(root[environment] ?? {}, "environment configuration");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw new Error("Unable to read UserReason configuration");
+    }
+    const url = apiUrl(options.apiUrl ?? process.env.UR_API_URL ?? (typeof saved.apiUrl === "string" ? saved.apiUrl : options.development ? "https://api-dev.userreason.com" : "https://api.userreason.com"));
+    const configured = options.clientId ?? (options.development ? process.env.UR_WORKOS_DEV_CLIENT_ID : undefined) ?? process.env.UR_WORKOS_CLIENT_ID ?? (typeof saved.clientId === "string" ? saved.clientId : undefined);
+    const clientId = configured ?? await discoverAuthConfig(url, options.development);
+    if (!/^client_[A-Za-z0-9]+$/.test(clientId))
+        throw new Error("Set UR_WORKOS_CLIENT_ID or pass --client-id with the public WorkOS client ID. Never supply a WorkOS API key.");
+    return { apiUrl: url, clientId };
+}
+export async function saveConfig(config, development = false) {
+    await mkdir(configDirectory(), { recursive: true, mode: 0o700 });
+    let existing = {};
+    try {
+        existing = object(JSON.parse(await readFile(join(configDirectory(), "config.json"), "utf8")), "configuration");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw new Error("Unable to read UserReason configuration");
+    }
+    existing[development ? "development" : "production"] = config;
+    await writeFile(join(configDirectory(), "config.json"), JSON.stringify(existing, null, 2) + "\n", { mode: 0o600 });
+}

package/dist/contracts.d.ts

@@ -0,0 +1,55 @@
+export declare const SCOPES: readonly ["workspace:create", "workspace:read", "site:create", "site:read", "site:update", "survey:write", "campaign:publish"];
+export type Scope = typeof SCOPES[number];
+export interface Workspace {
+    id: string;
+    name: string;
+    role?: string;
+    revision?: string;
+}
+export interface Site {
+    id: string;
+    name: string;
+    workspace_id: string;
+    environment: "development" | "production";
+    allowed_origins: string[];
+    revision?: string;
+}
+export interface Account {
+    user: {
+        id: string;
+        email?: string | null;
+        name?: string | null;
+    };
+    workspaces: Workspace[];
+    grants: unknown[];
+}
+export interface GrantRequest {
+    id: string;
+    status: "pending" | "approved" | "rejected" | "denied" | "expired";
+    approval_url?: string;
+    expires_at?: string;
+    grant_id?: string | null;
+}
+export interface Session {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    userId: string;
+    email: string;
+    clientId: string;
+    apiUrl: string;
+}
+export interface Credentials {
+    load(): Promise<Session | null>;
+    save(session: Session): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare function object(value: unknown, label: string): Record<string, unknown>;
+export declare function string(value: unknown, label: string): string;
+export declare function uuid(value: string, label?: string): string;
+export declare function scope(value: string): Scope;
+export declare function apiUrl(value: string): string;
+export declare function origin(value: string, environment: Site["environment"]): string;
+export declare function workspace(value: unknown): Workspace;
+export declare function site(value: unknown): Site;
+export declare function grantRequest(value: unknown): GrantRequest;

package/dist/contracts.js

@@ -0,0 +1,58 @@
+export const SCOPES = ["workspace:create", "workspace:read", "site:create", "site:read", "site:update", "survey:write", "campaign:publish"];
+export function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`Invalid ${label} response`);
+    return value;
+}
+export function string(value, label) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`Invalid ${label}`);
+    return value;
+}
+export function uuid(value, label = "ID") {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value))
+        throw new Error(`${label} must be a UUID`);
+    return value;
+}
+export function scope(value) {
+    if (!SCOPES.includes(value))
+        throw new Error(`Unknown scope: ${value}`);
+    return value;
+}
+export function apiUrl(value) {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash || url.pathname !== "/")
+        throw new Error("API URL must be an origin without credentials, query or path");
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+        throw new Error("API URL must use HTTPS; loopback HTTP is allowed for local development");
+    return url.origin;
+}
+export function origin(value, environment) {
+    const normalized = apiUrl(value);
+    if (environment === "production" && !normalized.startsWith("https://"))
+        throw new Error("Production sites require HTTPS origins");
+    return normalized;
+}
+export function workspace(value) {
+    const data = object(value, "workspace");
+    return { ...data, id: uuid(string(data.id, "workspace ID")), name: string(data.name, "workspace name") };
+}
+export function site(value) {
+    const data = object(value, "site");
+    if (data.environment !== "development" && data.environment !== "production")
+        throw new Error("Invalid site environment");
+    if (!Array.isArray(data.allowed_origins) || !data.allowed_origins.every(item => typeof item === "string"))
+        throw new Error("Invalid site origins");
+    return { ...data, id: uuid(string(data.id ?? data.site_id, "site ID")), workspace_id: uuid(string(data.workspace_id, "workspace ID")), name: string(data.name, "site name") };
+}
+export function grantRequest(value) {
+    const data = object(value, "grant request");
+    if (!["pending", "approved", "rejected", "denied", "expired"].includes(String(data.status)))
+        throw new Error("Invalid grant request status");
+    if (data.approval_url !== undefined) {
+        const url = new URL(string(data.approval_url, "approval URL"));
+        if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+            throw new Error("Invalid grant approval URL");
+    }
+    return { ...data, id: uuid(string(data.id, "grant request ID")) };
+}

package/dist/credentials.d.ts

@@ -0,0 +1,3 @@
+import type { Credentials } from "./contracts.js";
+import type { ClientConfig } from "./config.js";
+export declare function keychainCredentials(config: ClientConfig): Credentials;

package/dist/credentials.js

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+export function keychainCredentials(config) {
+    const account = createHash("sha256").update(`${config.apiUrl}\n${config.clientId}`).digest("hex");
+    async function entry() {
+        try {
+            const { Entry } = await import("@napi-rs/keyring");
+            return new Entry("com.userreason.cli", account, { linux: { store: "secret-service" } });
+        }
+        catch {
+            throw new Error("UserReason cannot access the OS credential store. Enable macOS Keychain, Windows Credential Manager or Linux Secret Service; credentials will not be written to a plaintext file.");
+        }
+    }
+    return {
+        async load() {
+            let serialized;
+            try {
+                serialized = (await entry()).getPassword();
+            }
+            catch (error) {
+                if (/No entry|NoEntry|not found|not exist/i.test(String(error.message)))
+                    return null;
+                throw new Error("Unable to read the UserReason OS credential-store entry");
+            }
+            if (!serialized)
+                return null;
+            try {
+                const session = JSON.parse(serialized);
+                if (session.apiUrl !== config.apiUrl || session.clientId !== config.clientId || typeof session.accessToken !== "string" || typeof session.refreshToken !== "string" || typeof session.expiresAt !== "number")
+                    throw new Error();
+                return session;
+            }
+            catch {
+                throw new Error("Invalid stored UserReason session; run userreason logout, then login again");
+            }
+        },
+        async save(session) { try {
+            (await entry()).setPassword(JSON.stringify(session));
+        }
+        catch {
+            throw new Error("Unable to save the UserReason session in the OS credential store");
+        } },
+        async clear() { try {
+            (await entry()).deletePassword();
+        }
+        catch (error) {
+            if (!/No entry|NoEntry|not found|not exist/i.test(String(error.message)))
+                throw new Error("Unable to remove the UserReason OS credential-store entry");
+        } },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./client.js";
+export * from "./config.js";
+export * from "./contracts.js";
+export * from "./credentials.js";
+export * from "./workos.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./client.js";
+export * from "./config.js";
+export * from "./contracts.js";
+export * from "./credentials.js";
+export * from "./workos.js";

package/dist/lock.d.ts

@@ -0,0 +1,2 @@
+import { type ClientConfig } from "./config.js";
+export declare function withSessionLock<T>(config: ClientConfig, operation: () => Promise<T>): Promise<T>;

package/dist/lock.js

@@ -0,0 +1,45 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { configDirectory } from "./config.js";
+// Serialize rotating refresh tokens across CLI/wizard processes. No credentials enter this file.
+export async function withSessionLock(config, operation) {
+    const directory = join(configDirectory(), "locks");
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const path = join(directory, createHash("sha256").update(`${config.apiUrl}\n${config.clientId}`).digest("hex") + ".lock");
+    const id = randomUUID(), deadline = Date.now() + 35_000;
+    while (true) {
+        try {
+            const file = await open(path, "wx", 0o600);
+            await file.writeFile(JSON.stringify({ id, createdAt: Date.now() }));
+            await file.close();
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw new Error("Unable to lock the UserReason credential store");
+            try {
+                const old = JSON.parse(await readFile(path, "utf8"));
+                if (typeof old.createdAt === "number" && Date.now() - old.createdAt > 120_000) {
+                    await unlink(path);
+                    continue;
+                }
+            }
+            catch { /* Another process may be writing or releasing its lock. */ }
+            if (Date.now() >= deadline)
+                throw new Error("Another UserReason process is refreshing credentials; try again shortly");
+            await new Promise(resolve => setTimeout(resolve, 150));
+        }
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        try {
+            const own = JSON.parse(await readFile(path, "utf8"));
+            if (own.id === id)
+                await unlink(path);
+        }
+        catch { /* Cleanup does not replace the operation's result. */ }
+    }
+}

package/dist/workos.d.ts

@@ -0,0 +1,21 @@
+import type { Credentials, Session } from "./contracts.js";
+import type { ClientConfig } from "./config.js";
+export type Fetch = typeof fetch;
+export interface DeviceAuthorization {
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresIn: number;
+}
+export declare class AuthenticationError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+declare const sleep: (milliseconds: number) => Promise<void>;
+export declare function login(config: ClientConfig, credentials: Credentials, onDevice: (device: DeviceAuthorization) => void | Promise<void>, options?: {
+    fetcher?: Fetch;
+    sleep?: typeof sleep;
+    now?: () => number;
+}): Promise<Session>;
+export declare function refresh(config: ClientConfig, credentials: Credentials, current: Session, fetcher?: Fetch): Promise<Session>;
+export {};

package/dist/workos.js

@@ -0,0 +1,97 @@
+import { object, string } from "./contracts.js";
+export class AuthenticationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const sleep = (milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds));
+const endpoint = "https://api.workos.com/user_management";
+function session(data, config) {
+    const user = object(data.user, "authenticated user");
+    if (user.email_verified !== true)
+        throw new AuthenticationError("email_unverified", "Complete email verification before continuing");
+    const accessToken = string(data.access_token, "access token");
+    let expiresAt = Date.now() + 120_000;
+    try {
+        const payload = object(JSON.parse(Buffer.from(accessToken.split(".")[1], "base64url").toString()), "token payload");
+        if (typeof payload.exp === "number" && Number.isFinite(payload.exp))
+            expiresAt = payload.exp * 1000;
+    }
+    catch { /* Server verifies the token; decoding here only schedules refresh. */ }
+    return { accessToken, refreshToken: string(data.refresh_token, "refresh token"), expiresAt, userId: string(user.id, "user ID"), email: string(user.email, "email"), ...config };
+}
+async function post(path, body, fetcher, signal = AbortSignal.timeout(20_000)) {
+    const response = await fetcher(`${endpoint}/${path}`, { method: "POST", redirect: "error", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(body), signal });
+    const data = object(await response.json(), "authentication");
+    return { response, data };
+}
+export async function login(config, credentials, onDevice, options = {}) {
+    const fetcher = options.fetcher ?? fetch, wait = options.sleep ?? sleep, now = options.now ?? Date.now;
+    const authorization = await post("authorize/device", { client_id: config.clientId }, fetcher);
+    if (!authorization.response.ok)
+        throw new AuthenticationError("device_authorization_failed", `Unable to start WorkOS login (${authorization.response.status})`);
+    const data = authorization.data;
+    const expiresIn = Number(data.expires_in), initialInterval = Number(data.interval);
+    if (!Number.isFinite(expiresIn) || expiresIn <= 0 || expiresIn > 1800 || !Number.isFinite(initialInterval) || initialInterval < 1 || initialInterval > 60)
+        throw new Error("Invalid device authorization timing");
+    const deviceCode = string(data.device_code, "device authorization code");
+    const verificationUri = string(data.verification_uri, "verification URL"), verificationUriComplete = string(data.verification_uri_complete, "complete verification URL");
+    for (const uri of [verificationUri, verificationUriComplete]) {
+        const url = new URL(uri);
+        if (url.protocol !== "https:" || url.username || url.password)
+            throw new Error("WorkOS returned an invalid verification URL");
+    }
+    await onDevice({ userCode: string(data.user_code, "user authorization code"), verificationUri, verificationUriComplete, expiresIn });
+    let interval = initialInterval;
+    const deadline = now() + expiresIn * 1000;
+    while (now() < deadline) {
+        await wait(interval * 1000);
+        if (now() >= deadline)
+            break;
+        let result;
+        try {
+            result = await post("authenticate", { grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: deviceCode, client_id: config.clientId }, fetcher, AbortSignal.timeout(Math.min(20_000, deadline - now())));
+        }
+        catch {
+            interval = Math.min(interval * 2, 30);
+            continue;
+        }
+        if (result.response.ok) {
+            const authenticated = session(result.data, config);
+            await credentials.save(authenticated);
+            return authenticated;
+        }
+        const code = result.data.error ?? result.data.code;
+        if (code === "authorization_pending")
+            continue;
+        if (code === "slow_down") {
+            interval += 5;
+            continue;
+        }
+        if (result.response.status >= 500 || result.response.status === 429) {
+            interval = Math.min(interval * 2, 30);
+            continue;
+        }
+        if (code === "access_denied")
+            throw new AuthenticationError("access_denied", "Login was declined");
+        if (code === "expired_token")
+            break;
+        throw new AuthenticationError("authorization_failed", `WorkOS authorization failed (${result.response.status})`);
+    }
+    throw new AuthenticationError("expired_token", "The login code expired; run login again");
+}
+export async function refresh(config, credentials, current, fetcher = fetch) {
+    const result = await post("authenticate", { grant_type: "refresh_token", refresh_token: current.refreshToken, client_id: config.clientId }, fetcher);
+    if (!result.response.ok) {
+        if (result.data.error === "invalid_grant" || result.data.code === "invalid_grant") {
+            await credentials.clear();
+            throw new AuthenticationError("invalid_grant", "Your session expired or was revoked; run userreason login again");
+        }
+        throw new AuthenticationError("refresh_failed", `Unable to refresh your session (${result.response.status}); the stored session was retained`);
+    }
+    const updated = session(result.data, config);
+    await credentials.save(updated);
+    return updated;
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@userreason/cli",
+  "version": "0.1.0",
+  "description": "Authenticated UserReason onboarding and management CLI",
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": { "node": ">=22.12.0" },
+  "bin": { "userreason": "dist/bin.js" },
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "README.md", "skills"],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": { "@napi-rs/keyring": "2.1.0" },
+  "devDependencies": { "@types/node": "^24.0.0", "typescript": "^5.9.0" }
+}

package/skills/userreason/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: userreason
+description: Set up UserReason workspaces, sites and SDK installations through the authenticated UserReason CLI, or inspect existing setup. Use for UserReason onboarding and agent access; use other tooling for unrelated analytics products.
+---
+
+Use the installed `userreason` CLI or `npx -y @userreason/cli@latest`. Check `--help` for the available commands. Use `--json` for machine-readable results; stdout contains the result and stderr contains login/approval instructions.
+
+Run `whoami` to discover the authenticated account and its approved workspaces. `--dev` selects the development environment. The CLI discovers the public WorkOS client ID from the API, with optional saved configuration, `UR_WORKOS_CLIENT_ID` or `--client-id` overrides; no API key or signing secret is needed. If login is required, run `login` and show the browser URL and confirmation code to the human. The human completes authentication. Credentials stay in the OS credential store.
+
+Authentication and resource authorization are separate. An authorization-required response means the human must approve a grant through the provided dashboard URL. Request only the permissions needed for the task, then use `grant status --id REQUEST_UUID --wait`. A new-workspace installation needs `workspace:create`, `workspace:read`, `site:create`, `site:read` and optionally `site:update`; scope an existing-workspace request using `--workspace UUID`. Installation does not require `campaign:publish`.
+
+List existing resources before creating duplicates. For intended workspace/site creation, generate request and resource UUIDs once, pass `--request-id` plus `--workspace-id`/`--site-id`, and reuse the same IDs and payload on retries. A workspace-creation grant is consumed once and its remaining permissions become bound to that workspace.
+
+For approved management work, use `query --workspace UUID --site UUID --resource surveys|campaigns|events|responses|audits` and follow the server's `next` cursor with `--after`. Read the current resource revision before editing. Write the versioned management command to a local JSON file and run `command --file PATH --json`; reuse its `request_id` and payload on uncertain outcomes. Publishing needs `campaign:publish`; ordinary draft work needs `survey:write`. Delete commands archive/disable rather than erase immutable records. The backend validates the full command and derives the actor from authentication.
+
+For an authorized SDK installation, run `npx -y @userreason/wizard@latest` in the intended project. It needs a remote-compatible `@userreason/js >=0.2.0`. Use explicit workspace/site UUIDs or creation names, origins and `--yes` for unattended operation after approval. Review the generated integration and mount it at the application root with lifecycle cleanup. Only public SDK identifiers and API configuration belong in host code.
+
+The wizard verifies configuration availability. It does not claim that the customer's browser has connected. Exercise the application in its real allowed origin and check config/session requests before reporting installation as connected. Revoked access requires a new approval; do not substitute bootstrap/system credentials or another person's identity.