@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/builder/typecheck.js

@@ -0,0 +1,102 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { generateAll } from './codegen/generate.js';
+import { RUNTIME_PACKAGE, isCompanyApiFile } from './company-imports.js';
+/**
+ * The TypeScript this runtime pins: the check never depends on whether, or which, `typescript` the repo
+ * lists. The types it reads (`@types/node`) are the repo's own devDependencies, which a release installs too.
+ */
+function pinnedTypescript() {
+    const require = createRequire(import.meta.url);
+    const pkgPath = require.resolve('typescript/package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin.tsc;
+    return { version: pkg.version, tsc: path.join(path.dirname(pkgPath), bin) };
+}
+function runTsc(tsc, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [tsc, ...args], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        let output = '';
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            output += chunk;
+        });
+        child.stderr.on('data', (chunk) => {
+            output += chunk;
+        });
+        child.once('error', reject);
+        child.once('close', (status) => resolve({ status, output }));
+    });
+}
+/** Whether a `paths` key (`@scope/*`, `*`, an exact name) can match an import of `@superpanel-sdk/…`. */
+function mapsSdkImports(key) {
+    const star = key.indexOf('*');
+    if (star === -1)
+        return key.startsWith('@superpanel-sdk/');
+    const prefix = key.slice(0, star);
+    return '@superpanel-sdk/'.startsWith(prefix) || prefix.startsWith('@superpanel-sdk/');
+}
+/**
+ * Why the repository's tsconfig would let its types see more than the company API (09-runtime-compat §6):
+ * `customConditions` resolve the platform's entries, and a `paths` entry can point a runtime import at
+ * any file. The one mapping it may have is `@superpanel-sdk/runtime` to a runtime's company API (the
+ * runtime's own fixtures map it to its source). Null when the config does neither.
+ */
+async function tsconfigImportIssue(tsc, root) {
+    // The effective config, `extends` applied. A config tsc cannot read fails the type check itself.
+    const { status, output } = await runTsc(tsc, ['-p', path.join(root, 'tsconfig.json'), '--showConfig'], root);
+    if (status !== 0)
+        return null;
+    let options;
+    try {
+        options = JSON.parse(output).compilerOptions ?? {};
+    }
+    catch {
+        return null;
+    }
+    if (options.customConditions && options.customConditions.length > 0) {
+        return `customConditions (${options.customConditions.join(', ')}) can change how ${RUNTIME_PACKAGE} resolves; company code gets it as it resolves by default`;
+    }
+    const base = options.baseUrl ? path.resolve(root, options.baseUrl) : root;
+    for (const [key, targets] of Object.entries(options.paths ?? {})) {
+        if (!mapsSdkImports(key))
+            continue;
+        if (key === RUNTIME_PACKAGE && targets.every((target) => isCompanyApiFile(path.resolve(base, target))))
+            continue;
+        return `paths maps '${key}': company code imports ${RUNTIME_PACKAGE} as the package resolves it`;
+    }
+    return null;
+}
+/**
+ * The repository's type check, as `npm run typecheck` runs it locally: `type:gen`, then `tsc --noEmit`
+ * with the repo's own `tsconfig.json`. With no sequence it writes only the root `__gen` (the local
+ * `type:gen` needs a sequence). The compile runs it itself, so a type error blocks a release in every
+ * environment; the platform never calls the repo's `typecheck` script.
+ */
+export async function typecheckRepo(repoRoot, onLog) {
+    const tsconfig = path.join(repoRoot, 'tsconfig.json');
+    if (!existsSync(tsconfig)) {
+        throw new Error('tsconfig.json is required: the compile type-checks the repository with it');
+    }
+    // type:gen first. A repository with no sequence still releases its company code (22 §11): only the
+    // root __gen is written then, which its root code's `ctx.api.db` is typed by.
+    await generateAll(repoRoot);
+    const { version, tsc } = pinnedTypescript();
+    onLog?.(`Type checking with TypeScript ${version}...`);
+    // tsc names files relative to its working directory, which is the real path (macOS's /var is a link):
+    // run it there, so the output names `sequences/…` as the repository has them.
+    const root = realpathSync(repoRoot);
+    const configIssue = await tsconfigImportIssue(tsc, root);
+    if (configIssue)
+        throw new Error(`Type check failed: tsconfig.json ${configIssue} (AGENTS.md, "Imports")`);
+    // Plain output whatever the terminal: the compile log is text.
+    const { status, output } = await runTsc(tsc, ['-p', path.join(root, 'tsconfig.json'), '--noEmit', '--pretty', 'false'], root);
+    if (status !== 0) {
+        throw new Error(`Type check failed (tsc --noEmit):\n${output.trim()}`);
+    }
+    onLog?.('Type check passed');
+}
+//# sourceMappingURL=typecheck.js.map

package/dist/builder/types.d.ts

@@ -1,36 +1,144 @@
-import type { CaseContextViewRegistryEntry, FunctionRegistry } from '../core/functions/types.js';
-import type { CompanySchema, EffectiveSchema } from '../core/slot/schema.js';
+import type { CaseOrchestratorManifest } from '../core/case-orchestrator/types.js';
+import type { ScheduleManifest } from '../core/functions/schedules.js';
+import type { FunctionRegistry } from '../core/functions/types.js';
+import type { OfficeHours } from '../core/office-hours/index.js';
+import type { ActionParameters } from '../core/page/define.js';
+import type { CompiledExperiments, CompiledVariables } from '../core/sequence/index.js';
 import type { CompiledSlotSchema } from '../core/slot/types.js';
-import type { CompiledAgenda } from '../core/stage/types.js';
 export type RuntimePackageSource = 'local-file' | 'npm';
 /**
- * Compiled sequence artifact (Manual §9 subset; grows over time).
- * Omitted for now: paramsDefaults, schedulers, caseManual.
+ * Deterministic compiled sequence artifact (22 §4.1; grows over time).
+ * Omitted for now: caseManual.
  *
  * Published builds include per-fn `code`. Local serve overlay uses the same
  * type but omits `code` — functions run on the laptop via WebSocket.
+ * Compilation time belongs to the database row's `createdAt`, never this artifact.
+ *
+ * Contract: the company repo's own runtime writes this, and the platform engine (always the
+ * newest runtime) reads it, for as long as that runtime version is supported.
+ *
+ * From launch on (docs/impl/09-runtime-compat.md), grow it only: never rename or remove a field,
+ * and give every new field a default the engine applies when an older build lacks it. A breaking
+ * change needs a new major runtime plus an announced end-of-support date for the old one. Before
+ * launch there are no older builds to read, so fields are added as required, with no defaults.
  */
 export type SequenceBuild = {
+    /** The directory name under `sequences/`: the sequence's identity (22 §10.2). */
     sequenceId: string;
-    sha: string;
+    /** What people see: `defineSequence({ meta: { label } })`, else the directory name. Synced on release. */
+    label: string;
+    /** Version of the runtime whose compiler produced this build (the company repo's runtime). */
     engineVersion: string;
     /** Installed @superpanel-sdk/runtime version resolved from the company repo. */
-    runtimeVersion?: string;
-    /** Dependency source declared by the company repo. Optional for legacy persisted builds. */
-    runtimeSource?: RuntimePackageSource;
-    compiledAt: string;
-    companySchemaSnapshot: CompanySchema;
-    /** SlotEngine runtime schema (tables + derivedOrder / reverseDeps). */
-    schema: CompiledSlotSchema;
-    effectiveSchema: EffectiveSchema;
+    runtimeVersion: string;
+    /** Dependency source declared by the company repo. */
+    runtimeSource: RuntimePackageSource;
+    /** The company table each run is about (`defineSequence({ subject })`, 14-sequence-instance §4.5). */
+    subject: string;
+    /** Run variables from `variables.ts` (14 §4.4); `{}` without the file. */
+    variables: CompiledVariables;
+    /** Experiments from `variables.ts`: how runs that do not set a variable are split. */
+    experiments: CompiledExperiments;
     /** Per-function registry. `code` omitted on local overlay. */
     functions: FunctionRegistry;
+    /** Platform event handlers keyed by event name; kind fixed by the event table. */
+    events: FunctionRegistry;
+    /**
+     * Sequence office hours from `sequences/<id>/office-hours.ts`. `null` when the sequence has no
+     * file (always open).
+     */
+    officeHours: OfficeHours | null;
+    /**
+     * The Case Orchestrator entry point (`orchestrator` in `functions`). `null` / absent when the
+     * sequence has no orchestrator.ts (older builds lack the field).
+     */
+    orchestrator?: CaseOrchestratorManifest | null;
+    /**
+     * The conversation's page script (`sequences/<id>/context.page.ts`, 15 §10.2), bundled: evaluates to
+     * the entry that renders the page or runs one of its actions. Always carries its code, the serve
+     * overlay included: the platform runs it next to the database. Every sequence has one. `channels`:
+     * the channels it has a page function for (17b §9.1).
+     */
+    contextPage: {
+        code: string;
+        channels: string[];
+        /** The functions' parameters, from their `args` types (38 §2.4): what a function button has filled. */
+        functions?: Record<string, {
+            parameters: ActionParameters;
+        }>;
+        /** The page's actions' parameters, from their `args` types (38 §2.9): what a page action button has filled. */
+        actions?: Record<string, {
+            parameters: ActionParameters;
+        }>;
+    };
+};
+/**
+ * The company build (22-sequence-as-business-unit §4.1): one release compiles the whole repository
+ * into it, and one Cloudflare Worker serves all of it. Same contract as {@link SequenceBuild}.
+ */
+export type CompanyBuild = {
+    /** The company's own code, outside any sequence (§5). */
+    company: CompanyPart;
+    /** Every sequence's build, keyed by its directory name under `sequences/`. */
+    sequences: Record<string, SequenceBuild>;
+};
+/**
+ * Company-level functions (`resolve.ts` and `webhook.ts` at the repository root): they run with no
+ * sequence. In the company Worker they are named `@company/<name>`; `@` keeps them apart from any
+ * sequence's directory.
+ */
+export type CompanyPart = {
+    /**
+     * `companyResolve`, `webhook.received` when the repository has `webhook.ts`, and `schedule.<name>`
+     * for each job of `schedules.ts`. `code` omitted on the local serve overlay.
+     */
+    functions: FunctionRegistry;
+    /** The company's recurring jobs (root `schedules.ts`, 25 §6.4), by name. Absent: none. */
+    schedules?: ScheduleManifest;
+    /**
+     * The company schema: what every function, page and the Orchestrator read and write, in every
+     * sequence (28 §2: a sequence has no schema of its own, only its `subject`).
+     */
+    schema: CompiledSlotSchema;
     /**
-     * Optional CaseContext projector. `null` when sequence has no view.ts
-     * (functions receive Slots / identity CaseContext).
+     * The runtime the repository installs, which the company Worker runs (every sequence compiles
+     * against the same one): known with no sequence at all (22 §11).
      */
-    caseContextView: CaseContextViewRegistryEntry | null;
-    /** Flattened agendas keyed by agenda id. Empty when the sequence has no agendas module. */
-    agendas: Record<string, CompiledAgenda>;
+    runtimeVersion: string;
+    runtimeSource: RuntimePackageSource;
 };
+/** Where company-level functions live, in place of a sequence's directory name. */
+export declare const COMPANY_SCOPE = "@company";
+/** The page script's name among its sequence's functions (its `functionKey`): reserved, no function takes it. */
+export declare const CONTEXT_PAGE_FUNCTION = "contextPage";
+/**
+ * The name the platform knows a piece of compiled company code by, wherever it runs: its scope (the
+ * sequence's directory name, or {@link COMPANY_SCOPE}), then its name. A Worker function is invoked
+ * by it (the company Worker's registry is keyed by it); the page script, run in the page sandbox, is
+ * `<sequence>/contextPage`. Directory names never contain `/` or `@`, so names of different scopes
+ * cannot meet.
+ */
+export declare function functionKey(scope: string, name: string): string;
+/**
+ * The file a piece of code's stack frames name, by its {@link functionKey}: its `//# sourceURL` in the
+ * company Worker, the file name the page sandbox runs it as. Its source map is found by that key.
+ */
+export declare function functionScriptFile(key: string): string;
+/**
+ * The source map of one compiled function or page script (v3, no `sourcesContent`): where a position
+ * in its `code` was in the company's own files, by path from the repository root. Every other source
+ * (the compile's entry, the runtime, dependencies) is `null`, the platform's code. Kept out of the
+ * build, which is read on every run: a failure's stack is turned into the company's with it.
+ */
+export type FunctionSourceMap = {
+    version: 3;
+    sources: Array<string | null>;
+    names: string[];
+    mappings: string;
+};
+/**
+ * Source maps of compiled code by its {@link functionKey}: a sequence's functions, events and page
+ * script (`<sequence>/contextPage`), the company's functions (`@company/<name>`).
+ */
+export type SourceMaps = Record<string, FunctionSourceMap>;
 //# sourceMappingURL=types.d.ts.map

package/dist/builder/types.js

@@ -1,2 +1,22 @@
-export {};
+/** Where company-level functions live, in place of a sequence's directory name. */
+export const COMPANY_SCOPE = '@company';
+/** The page script's name among its sequence's functions (its `functionKey`): reserved, no function takes it. */
+export const CONTEXT_PAGE_FUNCTION = 'contextPage';
+/**
+ * The name the platform knows a piece of compiled company code by, wherever it runs: its scope (the
+ * sequence's directory name, or {@link COMPANY_SCOPE}), then its name. A Worker function is invoked
+ * by it (the company Worker's registry is keyed by it); the page script, run in the page sandbox, is
+ * `<sequence>/contextPage`. Directory names never contain `/` or `@`, so names of different scopes
+ * cannot meet.
+ */
+export function functionKey(scope, name) {
+    return `${scope}/${name}`;
+}
+/**
+ * The file a piece of code's stack frames name, by its {@link functionKey}: its `//# sourceURL` in the
+ * company Worker, the file name the page sandbox runs it as. Its source map is found by that key.
+ */
+export function functionScriptFile(key) {
+    return `fn/${key}.js`;
+}
 //# sourceMappingURL=types.js.map

package/dist/cli/auth/auth.d.ts

@@ -0,0 +1,37 @@
+export type ServeAuthorization = {
+    token: string;
+    user: {
+        id: string;
+        email: string;
+    };
+    companyId: string;
+    companyName: string | null;
+};
+export declare function resolveBackendUrl(repoRoot: string, optionUrl?: string): string;
+export declare function loadCachedServeAuthorization(backendUrl: string, file?: string): Promise<ServeAuthorization | null>;
+export declare function cacheServeAuthorization(backendUrl: string, authorization: ServeAuthorization, file?: string): Promise<void>;
+export declare function clearCachedServeAuthorization(backendUrl: string, token: string, file?: string): Promise<void>;
+export declare function removeCachedServeAuthorization(backendUrl: string, file?: string): Promise<boolean>;
+export type ServeAuthorizationStatus = {
+    loggedIn: false;
+} | {
+    loggedIn: true;
+    authorization: ServeAuthorization;
+    expiresAt: number;
+    expired: boolean;
+};
+export declare function readServeAuthorizationStatus(backendUrl: string, file?: string): Promise<ServeAuthorizationStatus>;
+export type ServeEnvironment = {
+    id: string;
+    name: string;
+};
+/** The backend rejected the serve token (revoked, re-keyed, or the user lost access): log in again. */
+export declare class ServeAuthorizationRejectedError extends Error {
+    constructor(message: string);
+}
+/** Non-prod environments the serve token's company can overlay. */
+export declare function listServeEnvironments(backendUrl: string, token: string): Promise<ServeEnvironment[]>;
+export declare function authorizeServe(backendUrl: string, options?: {
+    openBrowser?: boolean;
+}): Promise<ServeAuthorization>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/cli/auth/auth.js

@@ -0,0 +1,211 @@
+import { spawn } from 'node:child_process';
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { readCompanyRepoConfig } from '../config.js';
+import { toHttpUrl } from './backend-url.js';
+import { copyToClipboard } from './clipboard.js';
+import { apiUrl, getJson, postJson } from './http.js';
+import { progressIndicator } from './progress.js';
+function env(name) {
+    const value = process.env[name];
+    return value && value.length > 0 ? value : undefined;
+}
+export function resolveBackendUrl(repoRoot, optionUrl) {
+    const resolved = optionUrl?.trim() || env('SUPERPANEL_SDK_BACKEND_URL') || readCompanyRepoConfig(repoRoot)?.backendUrl || undefined;
+    if (!resolved) {
+        throw new Error('No backend URL configured. Pass --url <backend-url>, set SUPERPANEL_SDK_BACKEND_URL, or configure .superpanel/config.json.');
+    }
+    return resolved;
+}
+function backendCacheKey(backendUrl) {
+    const url = toHttpUrl(backendUrl);
+    url.pathname = url.pathname.replace(/\/$/, '');
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
+function authorizationCachePath() {
+    return path.join(homedir(), '.superpanel', 'credentials.json');
+}
+function tokenExpiresAt(token) {
+    const body = token.split('.')[1];
+    if (!body)
+        return null;
+    try {
+        const claims = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+        return claims.purpose === 'serve' && typeof claims.exp === 'number' ? claims.exp * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isServeAuthorization(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    const user = record.user;
+    return (typeof record.token === 'string' &&
+        typeof record.companyId === 'string' &&
+        (record.companyName === null || typeof record.companyName === 'string') &&
+        Boolean(user) &&
+        typeof user === 'object' &&
+        typeof user.id === 'string' &&
+        typeof user.email === 'string');
+}
+async function readAuthorizationCache(file = authorizationCachePath()) {
+    try {
+        const raw = JSON.parse(await readFile(file, 'utf8'));
+        if (raw.version !== 1 || !raw.credentials || typeof raw.credentials !== 'object') {
+            return { version: 1, credentials: {} };
+        }
+        const credentials = {};
+        for (const [key, value] of Object.entries(raw.credentials)) {
+            if (isServeAuthorization(value))
+                credentials[key] = value;
+        }
+        return { version: 1, credentials };
+    }
+    catch (error) {
+        const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined;
+        if (code === 'ENOENT' || error instanceof SyntaxError)
+            return { version: 1, credentials: {} };
+        throw error;
+    }
+}
+async function writeAuthorizationCache(cache, file = authorizationCachePath()) {
+    const directory = path.dirname(file);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(cache, null, 2)}\n`, { mode: 0o600 });
+    await rename(temporary, file);
+    await chmod(file, 0o600);
+}
+export async function loadCachedServeAuthorization(backendUrl, file = authorizationCachePath()) {
+    const authorization = (await readAuthorizationCache(file)).credentials[backendCacheKey(backendUrl)];
+    if (!authorization)
+        return null;
+    const expiresAt = tokenExpiresAt(authorization.token);
+    return expiresAt !== null && expiresAt > Date.now() + 30_000 ? authorization : null;
+}
+export async function cacheServeAuthorization(backendUrl, authorization, file = authorizationCachePath()) {
+    const cache = await readAuthorizationCache(file);
+    cache.credentials[backendCacheKey(backendUrl)] = authorization;
+    await writeAuthorizationCache(cache, file);
+}
+export async function clearCachedServeAuthorization(backendUrl, token, file = authorizationCachePath()) {
+    const cache = await readAuthorizationCache(file);
+    const key = backendCacheKey(backendUrl);
+    if (cache.credentials[key]?.token !== token)
+        return;
+    delete cache.credentials[key];
+    await writeAuthorizationCache(cache, file);
+}
+export async function removeCachedServeAuthorization(backendUrl, file = authorizationCachePath()) {
+    const cache = await readAuthorizationCache(file);
+    const key = backendCacheKey(backendUrl);
+    if (!(key in cache.credentials))
+        return false;
+    delete cache.credentials[key];
+    await writeAuthorizationCache(cache, file);
+    return true;
+}
+export async function readServeAuthorizationStatus(backendUrl, file = authorizationCachePath()) {
+    const authorization = (await readAuthorizationCache(file)).credentials[backendCacheKey(backendUrl)];
+    if (!authorization)
+        return { loggedIn: false };
+    const expiresAt = tokenExpiresAt(authorization.token);
+    if (expiresAt === null)
+        return { loggedIn: false };
+    return { loggedIn: true, authorization, expiresAt, expired: expiresAt <= Date.now() };
+}
+/** The backend rejected the serve token (revoked, re-keyed, or the user lost access): log in again. */
+export class ServeAuthorizationRejectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ServeAuthorizationRejectedError';
+    }
+}
+/** Non-prod environments the serve token's company can overlay. */
+export async function listServeEnvironments(backendUrl, token) {
+    const { response, payload } = await getJson(apiUrl(backendUrl, 'cli-auth/environments'), token);
+    if (response.status === 401) {
+        throw new ServeAuthorizationRejectedError(payload.error ?? 'serve authorization rejected');
+    }
+    if (!response.ok) {
+        throw new Error(payload.error ?? `could not list environments (${response.status})`);
+    }
+    if (!Array.isArray(payload.environments)) {
+        throw new Error('malformed response from the backend (missing environments list)');
+    }
+    return payload.environments;
+}
+function openBrowser(url) {
+    const command = process.platform === 'darwin'
+        ? { file: 'open', args: [url] }
+        : process.platform === 'win32'
+            ? { file: 'rundll32', args: ['url.dll,FileProtocolHandler', url] }
+            : { file: 'xdg-open', args: [url] };
+    const child = spawn(command.file, command.args, { detached: true, stdio: 'ignore' });
+    child.once('error', () => undefined);
+    child.unref();
+}
+function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function authorizeServe(backendUrl, options = {}) {
+    const starting = progressIndicator();
+    starting.start('Starting browser authorization…');
+    let created;
+    try {
+        created = await postJson(apiUrl(backendUrl, 'cli-auth/device'), {});
+        if (!created.response.ok) {
+            throw new Error(created.payload.error ?? `could not start browser authorization (${created.response.status})`);
+        }
+    }
+    catch (error) {
+        starting.error('Could not start browser authorization.');
+        throw error;
+    }
+    starting.stop('Browser authorization started.');
+    const device = created.payload;
+    const progress = progressIndicator();
+    if (options.openBrowser === false) {
+        try {
+            copyToClipboard(device.verificationUrl);
+            progress.start(`Authorization URL copied to your clipboard. Paste it into a browser to continue:\n  ${device.verificationUrl}`);
+        }
+        catch (error) {
+            progress.start(`Could not copy the authorization URL (${error instanceof Error ? error.message : String(error)}). Open it manually:\n  ${device.verificationUrl}`);
+        }
+    }
+    else {
+        openBrowser(device.verificationUrl);
+        progress.start(`Opening your browser to continue — if it doesn't open within a few seconds, open this URL yourself:\n  ${device.verificationUrl}`);
+    }
+    try {
+        const expiresAt = Date.now() + device.expiresIn * 1000;
+        let delaySeconds = Math.max(1, device.interval);
+        while (Date.now() < expiresAt) {
+            await wait(delaySeconds * 1000);
+            const polled = await postJson(apiUrl(backendUrl, 'cli-auth/token'), { deviceCode: device.deviceCode });
+            if (polled.response.ok && 'token' in polled.payload) {
+                progress.stop('Authorized. You can close the browser tab now.');
+                return polled.payload;
+            }
+            if (polled.response.status === 202 || polled.response.status === 429) {
+                delaySeconds = Math.max(1, 'retryAfter' in polled.payload ? (polled.payload.retryAfter ?? delaySeconds) : delaySeconds);
+                continue;
+            }
+            if (polled.response.status === 410)
+                throw new Error('browser authorization expired');
+            throw new Error(polled.payload.error ?? `browser authorization failed (${polled.response.status})`);
+        }
+        throw new Error('browser authorization expired');
+    }
+    catch (error) {
+        progress.error('Browser authorization failed.');
+        throw error;
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/cli/auth/backend-url.d.ts

@@ -0,0 +1,5 @@
+/** Parses `raw` and rewrites its protocol to the ws/wss equivalent (http→ws, https→wss). */
+export declare function toWsUrl(raw: string): URL;
+/** Parses `raw` and rewrites its protocol to the http/https equivalent (ws→http, wss→https). */
+export declare function toHttpUrl(raw: string): URL;
+//# sourceMappingURL=backend-url.d.ts.map

package/dist/cli/auth/backend-url.js

@@ -0,0 +1,25 @@
+/** Parses `raw` and rewrites its protocol to the ws/wss equivalent (http→ws, https→wss). */
+export function toWsUrl(raw) {
+    const url = new URL(raw);
+    if (url.protocol === 'http:')
+        url.protocol = 'ws:';
+    else if (url.protocol === 'https:')
+        url.protocol = 'wss:';
+    else if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+        throw new Error(`unsupported backend url: ${raw}`);
+    }
+    return url;
+}
+/** Parses `raw` and rewrites its protocol to the http/https equivalent (ws→http, wss→https). */
+export function toHttpUrl(raw) {
+    const url = new URL(raw);
+    if (url.protocol === 'ws:')
+        url.protocol = 'http:';
+    else if (url.protocol === 'wss:')
+        url.protocol = 'https:';
+    else if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`unsupported backend url: ${raw}`);
+    }
+    return url;
+}
+//# sourceMappingURL=backend-url.js.map

package/dist/cli/auth/clipboard.d.ts

@@ -0,0 +1,9 @@
+export type ClipboardCommand = {
+    file: string;
+    args: string[];
+};
+/** Native clipboard commands, in preference order for the current platform. */
+export declare function clipboardCommands(platform: NodeJS.Platform): ClipboardCommand[];
+/** Copy text without invoking a shell, so an authorization URL is always treated as plain input. */
+export declare function copyToClipboard(text: string, platform?: NodeJS.Platform): void;
+//# sourceMappingURL=clipboard.d.ts.map

package/dist/cli/auth/clipboard.js

@@ -0,0 +1,38 @@
+import { spawnSync } from 'node:child_process';
+/** Native clipboard commands, in preference order for the current platform. */
+export function clipboardCommands(platform) {
+    switch (platform) {
+        case 'darwin':
+            return [{ file: 'pbcopy', args: [] }];
+        case 'win32':
+            return [{ file: 'clip.exe', args: [] }];
+        case 'linux':
+            return [
+                { file: 'wl-copy', args: [] },
+                { file: 'xclip', args: ['-selection', 'clipboard'] },
+                { file: 'xsel', args: ['--clipboard', '--input'] },
+            ];
+        default:
+            return [];
+    }
+}
+/** Copy text without invoking a shell, so an authorization URL is always treated as plain input. */
+export function copyToClipboard(text, platform = process.platform) {
+    const commands = clipboardCommands(platform);
+    if (commands.length === 0)
+        throw new Error(`clipboard copy is not supported on ${platform}`);
+    const failures = [];
+    for (const command of commands) {
+        const result = spawnSync(command.file, command.args, {
+            input: text,
+            encoding: 'utf8',
+            stdio: ['pipe', 'ignore', 'pipe'],
+        });
+        if (!result.error && result.status === 0)
+            return;
+        const detail = result.error?.message ?? (result.stderr.trim() || `exit ${result.status}`);
+        failures.push(`${command.file}: ${detail}`);
+    }
+    throw new Error(failures.join('; '));
+}
+//# sourceMappingURL=clipboard.js.map

package/dist/cli/auth/http.d.ts

@@ -0,0 +1,20 @@
+export declare function apiUrl(backendUrl: string, path: string): string;
+export declare function requestJson<T>(url: string, init: RequestInit): Promise<{
+    response: Response;
+    payload: T & {
+        error?: string;
+    };
+}>;
+export declare function postJson<T>(url: string, body: unknown): Promise<{
+    response: Response;
+    payload: T & {
+        error?: string;
+    };
+}>;
+export declare function getJson<T>(url: string, token: string): Promise<{
+    response: Response;
+    payload: T & {
+        error?: string;
+    };
+}>;
+//# sourceMappingURL=http.d.ts.map