@userreason/cli 0.1.0 → 0.1.1

package/dist/docs.js

@@ -0,0 +1,143 @@
+import { apiUrl, object } from "./contracts.js";
+import { DEVELOPMENT_DOCS } from "./profile.js";
+import { bundledCliMarkdown, searchCommands } from './catalog.js';
+import { NetworkError, networkError } from './errors.js';
+export const DOCS_URL = "https://docs.userreason.com";
+export class DocsError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+export const docsUrl = (value) => apiUrl(value, "Docs URL");
+const invalid = (status) => new DocsError("invalid_response", `Invalid UserReason docs response (${status})`, status);
+/** The docs are public: requests carry no credentials, never follow redirects and read a bounded body. */
+async function read(url, accept, limit, fetcher) {
+    try {
+        const response = await fetcher(url.href, { headers: { Accept: accept }, redirect: "error", signal: AbortSignal.timeout(20_000) });
+        const chunks = [];
+        let bytes = 0;
+        if (response.body)
+            for await (const chunk of response.body) {
+                bytes += chunk.byteLength;
+                if (bytes > limit)
+                    throw new DocsError("response_too_large", "UserReason docs response is too large", response.status);
+                chunks.push(chunk);
+            }
+        try {
+            return { response, text: new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)) };
+        }
+        catch {
+            throw invalid(response.status);
+        }
+    }
+    catch (error) {
+        if (error instanceof DocsError)
+            throw error;
+        const failure = networkError(error, url.href, 'UserReason documentation request');
+        throw failure.code === 'network_unreachable' ? new DocsError("docs_unreachable", `${failure.message} Use cli search or docs search --offline for the bundled CLI reference, or set --docs-url or UR_DOCS_URL.`) : failure;
+    }
+}
+function searchResult(value) {
+    const data = object(value, "docs search result");
+    if (["title", "url", "markdown_url", "passage"].some(key => typeof data[key] !== "string") || (data.heading !== null && typeof data.heading !== "string") || ["package", "version", "since"].some(key => data[key] !== undefined && typeof data[key] !== "string"))
+        throw new Error("Invalid docs search result");
+    return data;
+}
+export async function searchDocs(input) {
+    const query = input.query.trim();
+    if (!query || query.length > 500)
+        throw new Error("Docs search needs a question of 1–500 characters");
+    if (input.limit !== undefined && (!Number.isInteger(input.limit) || input.limit < 1 || input.limit > 20))
+        throw new Error("Docs search limit must be an integer from 1 to 20");
+    const offline = () => ({ query, source: 'bundled', results: searchCommands(query, input.limit).map(item => ({
+            title: 'CLI command reference', heading: item.command, url: docsUrl(input.origin ?? DOCS_URL) + '/cli/', markdown_url: docsUrl(input.origin ?? DOCS_URL) + '/cli/', passage: item.summary + '\n' + item.usage, package: '@userreason/cli',
+        })) });
+    if (input.offline)
+        return offline();
+    const url = new URL("/search", docsUrl(input.origin ?? DOCS_URL));
+    url.searchParams.set("q", query);
+    if (input.limit !== undefined)
+        url.searchParams.set("limit", String(input.limit));
+    let response, text;
+    try {
+        ({ response, text } = await read(url, "application/json", 262_144, input.fetcher ?? fetch));
+    }
+    catch (error) {
+        if (input.live === false && (error instanceof NetworkError || error instanceof DocsError && error.code === 'docs_unreachable'))
+            return { ...offline(), warning: { code: error.code, message: error.message } };
+        throw error;
+    }
+    if (!response.ok) {
+        let code = "request_failed";
+        try {
+            const detail = object(object(JSON.parse(text), "error").error, "error");
+            if (typeof detail.code === "string" && /^[a-z0-9_:-]{1,100}$/i.test(detail.code))
+                code = detail.code;
+        }
+        catch { /* Not a docs error body. */ }
+        throw new DocsError(code, `UserReason docs search failed (${response.status}, ${code})`, response.status);
+    }
+    try {
+        const data = object(JSON.parse(text), "docs search");
+        if (typeof data.query !== "string" || !Array.isArray(data.results))
+            throw new Error("Invalid docs search");
+        const selectedOrigin = docsUrl(input.origin ?? DOCS_URL);
+        const address = (value) => selectedOrigin === DEVELOPMENT_DOCS && value.startsWith(DOCS_URL + '/') ? DEVELOPMENT_DOCS + value.slice(DOCS_URL.length) : value;
+        return { ...data, query: data.query, results: data.results.map(value => {
+                const result = searchResult(value);
+                return { ...result, url: address(result.url), markdown_url: address(result.markdown_url) };
+            }) };
+    }
+    catch {
+        throw invalid(response.status);
+    }
+}
+/** Accepts a page address or path. Search results name the public site, so its addresses are read from the selected origin. */
+export function docsPageUrl(target, origin = DOCS_URL) {
+    const base = docsUrl(origin);
+    if (!target.trim())
+        throw new Error("Supply a docs page URL or path, such as /sdk/events/");
+    let url;
+    try {
+        url = new URL(target.trim(), base);
+    }
+    catch {
+        throw new Error("Invalid docs page URL or path");
+    }
+    if (url.username || url.password || (url.origin !== base && url.origin !== DOCS_URL && url.origin !== DEVELOPMENT_DOCS))
+        throw new Error(`docs get reads pages from ${base} only`);
+    const path = url.pathname;
+    return base + (path.endsWith("/") || path.slice(path.lastIndexOf("/") + 1).includes(".") ? path : `${path}/`);
+}
+export async function getDocsPage(input) {
+    const url = new URL(docsPageUrl(input.target, input.origin));
+    if (!input.live && ['/cli/', '/cli/index.md'].includes(url.pathname))
+        return { url: url.href, markdown: bundledCliMarkdown(), source: 'bundled' };
+    if (input.offline)
+        throw new DocsError('not_bundled', 'Only the CLI reference (/cli/) is bundled. SDK documentation needs network access; use --live to read it.');
+    const { response, text } = await read(url, "text/markdown", 2_097_152, input.fetcher ?? fetch);
+    if (response.status === 404)
+        throw new DocsError("not_found", `No docs page at ${url.href}. Find pages with userreason docs search, or read ${url.origin}/llms.txt.`, 404);
+    if (!response.ok)
+        throw new DocsError("request_failed", `UserReason docs request failed (${response.status})`, response.status);
+    const type = response.headers.get("content-type")?.toLowerCase() ?? "";
+    if (!type.startsWith("text/markdown") && !type.startsWith("text/plain"))
+        throw new DocsError("not_markdown", `${url.href} did not return Markdown`, response.status);
+    const tokens = Number(response.headers.get("x-markdown-tokens"));
+    return { url: url.href, markdown: text, ...(Number.isInteger(tokens) && tokens > 0 ? { tokens } : {}) };
+}
+/** Terminal output keeps line breaks and tabs and drops other control characters. */
+export const printable = (text) => text.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
+export function formatDocsSearch(found) {
+    const note = found.source === 'bundled' ? 'Bundled CLI reference only. SDK documentation requires network access.\n' : '';
+    if (!found.results.length)
+        return printable(`${note}No docs sections match "${found.query}".\n`);
+    return printable(note + found.results.map((result, index) => {
+        const notes = [[result.package, result.version].filter(Boolean).join(" "), result.since ? `added in ${result.since}` : ""].filter(Boolean).join(", ");
+        return `${index + 1}. ${result.title}${result.heading ? ` › ${result.heading}` : ""}${notes ? ` (${notes})` : ""}\n   ${result.url}\n   ${result.passage}\n`;
+    }).join("\n") + "\nRead a page as Markdown: userreason docs get URL\n");
+}

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+/** Local transport failures are different from an API denying workspace access. */
+export declare class NetworkError extends Error {
+    code: 'network_blocked' | 'network_timeout' | 'network_unreachable';
+    constructor(code: 'network_blocked' | 'network_timeout' | 'network_unreachable', message: string);
+}
+export declare class ConfigurationError extends Error {
+    code: 'config_read_failed' | 'config_write_failed' | 'invalid_config';
+    constructor(code: 'config_read_failed' | 'config_write_failed' | 'invalid_config', message: string);
+}
+export declare function networkError(error: unknown, url: string, operation: string): NetworkError;
+export declare function fetchWithErrors(fetcher: typeof fetch, url: string, init: RequestInit, operation: string): Promise<Response>;

package/dist/errors.js

@@ -0,0 +1,38 @@
+/** Local transport failures are different from an API denying workspace access. */
+export class NetworkError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export class ConfigurationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function networkError(error, url, operation) {
+    const codes = [];
+    let current = error;
+    for (let depth = 0; depth < 5 && current && typeof current === 'object'; depth++) {
+        const item = current;
+        codes.push(String(item.code ?? ''), String(item.name ?? ''));
+        current = item.cause;
+    }
+    const host = new URL(url).origin;
+    if (codes.some(code => ['EACCES', 'EPERM', 'ERR_ACCESS_DENIED'].includes(code)))
+        return new NetworkError('network_blocked', `${operation}: local permissions blocked network access to ${host}. Allow this command to reach that origin; changing workspace grants will not resolve it.`);
+    if (codes.some(code => ['ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'TimeoutError', 'AbortError'].includes(code)))
+        return new NetworkError('network_timeout', `${operation}: the request to ${host} timed out. Check connectivity and retry; this is not a workspace permission denial.`);
+    return new NetworkError('network_unreachable', `${operation}: unable to reach ${host}. Check the connection and the agent's network permissions; this is not a workspace permission denial.`);
+}
+export async function fetchWithErrors(fetcher, url, init, operation) {
+    try {
+        return await fetcher(url, init);
+    }
+    catch (error) {
+        throw networkError(error, url, operation);
+    }
+}

package/dist/event-policy.d.ts

@@ -0,0 +1,2 @@
+/** Explicit file policies win; the one-step registration preset is a product choice, not name inference. */
+export declare function eventCollection(file: Record<string, unknown>, purpose?: string): unknown;

package/dist/event-policy.js

@@ -0,0 +1,9 @@
+/** Explicit file policies win; the one-step registration preset is a product choice, not name inference. */
+export function eventCollection(file, purpose) {
+    const selected = purpose ?? file.purpose ?? 'business';
+    if (selected !== 'business' && selected !== 'activity')
+        throw new Error('Purpose must be business or activity');
+    return file.collection ?? (selected === 'activity'
+        ? { memory: true, local: false, server: false, raw_retention_days: 0, history_retention_days: null, purpose: 'activity' }
+        : { memory: true, local: false, server: true, raw_retention_days: 30, history_retention_days: 90, purpose: 'business' });
+}

package/dist/help.d.ts

@@ -0,0 +1,13 @@
+import type { UiKit } from './ui.js';
+export declare const overviewNouns: string[];
+export interface HelpOptions {
+    version?: string;
+    development?: boolean;
+    trademark?: boolean;
+}
+/** Four groups of nouns, one line each. Plain (piped) output is the same text without colour or rules. */
+export declare function overviewHelp(kit: UiKit, { version, development, trademark }?: HelpOptions): string;
+/** One noun's actions: exact usage from the catalog, without the options every command shares. */
+export declare function nounHelp(kit: UiKit, noun: string): string | undefined;
+/** The closest command name within two edits, for "Did you mean". */
+export declare function suggestCommand(word: string): string | undefined;

package/dist/help.js

@@ -0,0 +1,74 @@
+import { commandCatalog, commandSummary } from './catalog.js';
+/** The overview groups every command noun. A test keeps this list in step with the catalog. */
+const GROUPS = [
+    ['Get started', [['login', 'Sign in in the browser'], ['access', 'Review or renew what this CLI may do'], ['whoami', "Account, grants and this project's site"], ['logout', 'Remove local credentials']]],
+    ['Feedback', [['prompt', 'Create, validate, publish and read surveys'], ['preview', 'Capture a site for the development preview lab'], ['audience', 'Choose who sees a survey'], ['results', 'Summaries and breakdowns'], ['responses', 'Read answers'], ['user', 'People and their eligibility'], ['event', 'Product events and collection']]],
+    ['Workspaces and sites', [['workspace', 'list · create · delete'], ['site', 'list · create · activity · events · frequency · delete'], ['member', 'list'], ['grant', 'Request and check access'], ['deletion', 'Check a deletion request']]],
+    ['Reference', [['docs', 'Search and read the documentation'], ['cli', "Search this CLI's commands"], ['query', 'Raw management API for agents'], ['command', 'Send a management command file']]],
+];
+export const overviewNouns = GROUPS.flatMap(([, items]) => items.map(([name]) => name));
+/** Commands with no action of their own: they never get a per-command help page. */
+const NO_ACTION = new Set(['login', 'access', 'logout', 'whoami', 'command', 'query']);
+const READ_SCOPES = new Set(['workspace:read', 'site:read']);
+/** Four groups of nouns, one line each. Plain (piped) output is the same text without colour or rules. */
+export function overviewHelp(kit, { version, development = false, trademark = false } = {}) {
+    const { c, S } = kit;
+    const lines = [];
+    const environment = development ? `(development API)` : '';
+    const meta = [version ? `v${version}` : '', environment].filter(Boolean).join(' ');
+    if (kit.level > 0)
+        lines.push(`${c.bold(c.accent(trademark ? 'UserReason™ CLI' : 'userreason'))}${meta ? `  ${c.muted(meta)}` : ''}`, c.faint(S.rule.repeat(54)));
+    else
+        lines.push(`userreason${meta ? ` ${meta}` : ''}`);
+    lines.push(`${c.muted('Usage')}  userreason <command> [options]`, '');
+    const first = Math.max(...overviewNouns.map(name => name.length));
+    for (const [group, items] of GROUPS) {
+        lines.push(c.bold(group), ...items.map(([name, text]) => `  ${c.code(name)}${' '.repeat(first - name.length + 2)}${c.muted(text)}`), '');
+    }
+    lines.push(`${c.muted('Options')}  --json  --workspace UUID  --site UUID  --dev  --no-color  -h`, `${c.muted('Target')}   this project's SDK site; override with --workspace and --site`, `${c.muted('More')}     ${c.code('userreason <command> --help')}   ${c.code('userreason --help --all')}   ${c.code('userreason cli search "<task>"')}`);
+    return lines.join('\n') + '\n';
+}
+/** One noun's actions: exact usage from the catalog, without the options every command shares. */
+export function nounHelp(kit, noun) {
+    if (NO_ACTION.has(noun))
+        return undefined;
+    const items = commandCatalog.filter(item => item.command === noun || item.command.startsWith(`${noun} `));
+    if (!items.length)
+        return undefined;
+    const { c, S } = kit;
+    const short = (usage) => usage.replace(/^userreason /, '').replace(/ --workspace UUID/g, '').replace(/ --site UUID/g, '').replace(`${noun} `, '');
+    const lines = [];
+    const summary = commandSummary(noun);
+    if (kit.level > 0)
+        lines.push(`${c.bold(c.accent(`userreason ${noun}`))}${summary ? `  ${c.muted(summary)}` : ''}`, c.faint(S.rule.repeat(54)));
+    else
+        lines.push(`userreason ${noun}${summary ? ` ${S.dot} ${summary}` : ''}`);
+    for (const [title, read] of [['Read', true], ['Write', false]]) {
+        const rows = items.filter(item => item.scopes.every(scope => READ_SCOPES.has(scope)) === read);
+        if (!rows.length)
+            continue;
+        lines.push(c.bold(title));
+        for (const item of rows) {
+            lines.push(`  ${c.code(short(item.usage))}`);
+            const specific = commandSummary(item.command);
+            if (specific && item.command !== noun)
+                lines.push(`    ${c.muted(specific)}`);
+        }
+    }
+    lines.push(`${c.muted('Options')}  --workspace UUID  --site UUID  ${c.muted("(default: this project's site)")}  --json`);
+    return lines.join('\n') + '\n';
+}
+/** The closest command name within two edits, for "Did you mean". */
+export function suggestCommand(word) {
+    const distance = (a, b) => {
+        const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+        for (let j = 1; j <= b.length; j++)
+            d[0][j] = j;
+        for (let i = 1; i <= a.length; i++)
+            for (let j = 1; j <= b.length; j++)
+                d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        return d[a.length][b.length];
+    };
+    const [best] = overviewNouns.map(name => [name, distance(word.toLowerCase(), name)]).sort((a, b) => a[1] - b[1]);
+    return best && best[1] <= 2 ? best[0] : undefined;
+}

package/dist/index.d.ts

@@ -2,4 +2,13 @@ export * from "./client.js";
 export * from "./config.js";
 export * from "./contracts.js";
 export * from "./credentials.js";
+export * from "./docs.js";
+export * from "./profile.js";
 export * from "./workos.js";
+export * from "./authorize.js";
+export * from "./project.js";
+export * from "./errors.js";
+export * from "./catalog.js";
+export * from "./ui.js";
+export * from "./help.js";
+export * from "./views.js";

package/dist/index.js

@@ -2,4 +2,13 @@ export * from "./client.js";
 export * from "./config.js";
 export * from "./contracts.js";
 export * from "./credentials.js";
+export * from "./docs.js";
+export * from "./profile.js";
 export * from "./workos.js";
+export * from "./authorize.js";
+export * from "./project.js";
+export * from "./errors.js";
+export * from "./catalog.js";
+export * from "./ui.js";
+export * from "./help.js";
+export * from "./views.js";

package/dist/lock.js

@@ -2,22 +2,36 @@ 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";
+import { CredentialStoreError } from './credentials.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 });
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        throw new CredentialStoreError('lock_failed', `Refreshing the UserReason session requires local write access to ${directory}. Allow that access and retry; workspace grants are unrelated.`);
+    }
     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();
+            try {
+                await file.writeFile(JSON.stringify({ id, createdAt: Date.now() }));
+            }
+            catch (error) {
+                await unlink(path).catch(() => { });
+                throw error;
+            }
+            finally {
+                await file.close();
+            }
             break;
         }
         catch (error) {
             if (error.code !== "EEXIST")
-                throw new Error("Unable to lock the UserReason credential store");
+                throw new CredentialStoreError('lock_failed', `Unable to lock UserReason credentials for refresh at ${path}. Allow local write access and retry.`);
             try {
                 const old = JSON.parse(await readFile(path, "utf8"));
                 if (typeof old.createdAt === "number" && Date.now() - old.createdAt > 120_000) {
@@ -27,7 +41,7 @@ export async function withSessionLock(config, operation) {
             }
             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");
+                throw new CredentialStoreError('lock_timeout', "Another UserReason process is refreshing credentials; try again shortly");
             await new Promise(resolve => setTimeout(resolve, 150));
         }
     }

package/dist/profile.d.ts

@@ -0,0 +1,20 @@
+export interface PackageProfile {
+    schemaVersion: 1;
+    kind: "production" | "local-development";
+    apiEnvironment: "production" | "development";
+    docsUrl: string;
+    sdkVersion: string;
+    cliVersion: string;
+    wizardVersion?: string;
+    buildId?: string;
+    registry?: string;
+}
+export declare const PRODUCTION_DOCS = "https://docs.userreason.com";
+export declare const DEVELOPMENT_DOCS = "https://docs-dev.userreason.com";
+export declare const productionProfile: PackageProfile;
+export declare function parsePackageProfile(value: unknown): PackageProfile;
+/** The same optional file travels beside the CLI modules and the wizard's bundled modules. */
+export declare function packageProfile(): PackageProfile;
+export declare function docsOrigin(development?: boolean): string;
+/** Ask the foreground builder for a complete current set, including changes still being compiled. */
+export declare function currentPackageProfile(profile?: PackageProfile, fetcher?: typeof fetch): Promise<PackageProfile>;

package/dist/profile.js

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+import { apiUrl, object } from "./contracts.js";
+export const PRODUCTION_DOCS = "https://docs.userreason.com";
+export const DEVELOPMENT_DOCS = "https://docs-dev.userreason.com";
+export const productionProfile = {
+    schemaVersion: 1, kind: "production", apiEnvironment: "production",
+    docsUrl: PRODUCTION_DOCS, sdkVersion: "^0.4.0", cliVersion: "^0.1.1",
+};
+export function parsePackageProfile(value) {
+    const data = object(value, "package profile");
+    if (data.schemaVersion !== 1 || data.kind !== "local-development" || data.apiEnvironment !== "development" ||
+        data.docsUrl !== DEVELOPMENT_DOCS || typeof data.buildId !== "string" || !/^[a-f0-9]{64}$/.test(data.buildId) ||
+        [data.sdkVersion, data.cliVersion, data.wizardVersion].some(version => typeof version !== "string" || !/^\d+\.\d+\.\d+-dev\.[0-9]+$/.test(version)) ||
+        typeof data.registry !== "string")
+        throw new Error("Invalid local UserReason package profile");
+    const registry = apiUrl(data.registry), url = new URL(registry);
+    if (url.protocol !== "http:" || url.hostname !== "127.0.0.1")
+        throw new Error("Local UserReason packages require a loopback registry");
+    return { schemaVersion: 1, kind: "local-development", apiEnvironment: "development", docsUrl: DEVELOPMENT_DOCS,
+        sdkVersion: data.sdkVersion, cliVersion: data.cliVersion, wizardVersion: data.wizardVersion,
+        buildId: data.buildId, registry };
+}
+/** The same optional file travels beside the CLI modules and the wizard's bundled modules. */
+export function packageProfile() {
+    try {
+        return parsePackageProfile(JSON.parse(readFileSync(new URL("./package-profile.json", import.meta.url), "utf8")));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { ...productionProfile };
+        throw error;
+    }
+}
+export function docsOrigin(development = packageProfile().apiEnvironment === "development") {
+    return development ? DEVELOPMENT_DOCS : PRODUCTION_DOCS;
+}
+/** Ask the foreground builder for a complete current set, including changes still being compiled. */
+export async function currentPackageProfile(profile = packageProfile(), fetcher = fetch) {
+    if (profile.kind !== "local-development")
+        return profile;
+    let response;
+    try {
+        response = await fetcher(`${profile.registry}/-/userreason/dev-profile`, { redirect: "error", signal: AbortSignal.timeout(120_000), headers: { Accept: "application/json" } });
+    }
+    catch {
+        throw new Error("Local UserReason builder is unavailable. Start npm run dev:packages in ur-platform and retry.");
+    }
+    if (!response.ok)
+        throw new Error("The current local UserReason build failed. Check the dev:packages terminal and retry after fixing it.");
+    const text = await response.text();
+    if (text.length > 8192)
+        throw new Error("Invalid local UserReason build response");
+    const current = parsePackageProfile(JSON.parse(text));
+    if (current.registry !== profile.registry)
+        throw new Error("Local UserReason build registry does not match this wizard");
+    return current;
+}

package/dist/project.d.ts

@@ -0,0 +1,9 @@
+export interface ProjectTarget {
+    directory: string;
+    file: string;
+    siteId: string;
+    apiUrl: string;
+    workspaceId?: string;
+}
+/** Parse static SDK initialization only. Never execute application code or select an arbitrary account site. */
+export declare function detectProjectTarget(directory?: string): Promise<ProjectTarget | undefined>;

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/ui.d.ts

@@ -0,0 +1,75 @@
+type Role = 'accent' | 'good' | 'warn' | 'danger' | 'muted' | 'code' | 'faint';
+export declare const stripAnsi: (value: string) => string;
+export declare const textWidth: (value: string) => number;
+/** 0 none, 1 sixteen colours, 2 256 colours, 3 truecolor. Honours NO_COLOR and FORCE_COLOR. */
+export type ColorLevel = 0 | 1 | 2 | 3;
+export declare function detectColorLevel({ stream, env, off }?: {
+    stream?: {
+        isTTY?: boolean;
+    };
+    env?: NodeJS.ProcessEnv;
+    off?: boolean;
+}): ColorLevel;
+export declare function detectAgentHarness(env?: NodeJS.ProcessEnv): string | null;
+export interface UiKit {
+    level: ColorLevel;
+    c: Record<Role | 'bold', (text: string) => string>;
+    S: {
+        info: string;
+        done: string;
+        ask: string;
+        warn: string;
+        error: string;
+        section: string;
+        bar: string;
+        rule: string;
+        arrow: string;
+        dot: string;
+        frames: string[];
+    };
+    symbol: {
+        info: string;
+        done: string;
+        ask: string;
+        warn: string;
+        error: string;
+    };
+    cols(rows: [string, string?][], options?: {
+        gap?: number;
+    }): string[];
+    table(head: string[], rows: string[][]): string[];
+    json(value: unknown, indent?: number): string;
+    header(options: {
+        mode: string;
+        version: string;
+        detail?: string | string[];
+        trademark?: boolean;
+    }): string[];
+}
+export declare function createUiKit({ level, light, ascii, stream }?: {
+    level?: ColorLevel;
+    light?: boolean;
+    ascii?: boolean;
+    stream?: {
+        isTTY?: boolean;
+    };
+}): UiKit;
+/** Stable word prefixes for piped, CI and agent output, so lines can be filtered with grep. */
+export type PlainKind = 'info' | 'done' | 'warn' | 'error' | 'skip' | 'next';
+export declare const plainLine: (kind: PlainKind, text: string) => string;
+/**
+ * A one-line spinner. Unlike clack's it leaves no guide line behind, so a finished task can be replaced
+ * by a single result line. Without a terminal it prints nothing while it runs.
+ */
+export interface Spinner {
+    start(message: string): void;
+    message(message: string): void;
+    stop(finalLine?: string): void;
+}
+export declare function createSpinner(kit: UiKit, stream?: {
+    isTTY?: boolean;
+    write(chunk: string): unknown;
+}, options?: {
+    onCancel?: () => void;
+}): Spinner;
+export {};