@superpanel-sdk/runtime 0.2.2 → 0.5.0

package/dist/builder/schedules.js

@@ -0,0 +1,102 @@
+import { pathToFileURL } from 'node:url';
+import { CronExpressionParser } from 'cron-parser';
+import { SCHEDULE_FUNCTION_PREFIX, SCHEDULES_MODULE, scheduleFunctionName, } from '../core/functions/schedules.js';
+import { compileScheduleModuleCode } from './compile/function-code.js';
+import { companyImportGraphHref } from './company-import-graph.js';
+import { findTsModule } from './paths.js';
+/** A job name: an identifier, so `schedule.<name>` stays one plain function name. */
+const SCHEDULE_NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+function isPlainObject(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Whether `timezone` is an IANA name this runtime knows. */
+function knownTimezone(timezone) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Why one job's `cron` / `timezone` cannot run, or `null`. The cron is read by the same parser the
+ * worker's job scheduler uses (BullMQ's cron-parser); five fields only, so nothing runs every second.
+ */
+export function scheduleTimingIssue(cron, timezone) {
+    if (typeof timezone !== 'string' || !knownTimezone(timezone)) {
+        return `timezone ${JSON.stringify(timezone)} is not an IANA timezone (e.g. 'UTC', 'America/Phoenix')`;
+    }
+    if (typeof cron !== 'string' || cron.trim().split(/\s+/).length !== 5) {
+        return `cron ${JSON.stringify(cron)} must have five fields: minute hour day-of-month month day-of-week (e.g. '0 2 * * *')`;
+    }
+    try {
+        CronExpressionParser.parse(cron.trim(), { tz: timezone }).next();
+    }
+    catch (error) {
+        return `cron ${JSON.stringify(cron)} is not valid: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    return null;
+}
+/** Read a `schedules` export: every job named, timed and runnable, else one error listing what is wrong. */
+export function parseSchedules(value, where) {
+    if (!isPlainObject(value)) {
+        throw new Error(`${where}: export const schedules = defineSchedules({ name: { cron, timezone, run } })`);
+    }
+    const issues = [];
+    for (const [name, entry] of Object.entries(value)) {
+        if (!SCHEDULE_NAME.test(name)) {
+            issues.push(`'${name}': a job name is letters, digits and _ starting with a letter (at most 64)`);
+            continue;
+        }
+        if (!isPlainObject(entry)) {
+            issues.push(`'${name}': expected { cron, timezone, run }`);
+            continue;
+        }
+        if (typeof entry.run !== 'function')
+            issues.push(`'${name}': run must be an async function (ctx) => { … }`);
+        const timing = scheduleTimingIssue(entry.cron, entry.timezone);
+        if (timing)
+            issues.push(`'${name}': ${timing}`);
+    }
+    if (issues.length > 0)
+        throw new Error(`${where}: ${issues.join('; ')} (25 §6.4)`);
+    return value;
+}
+async function importSchedules(modulePath, where) {
+    const mod = (await import(companyImportGraphHref(pathToFileURL(modulePath).href)));
+    const fromDefault = isPlainObject(mod.default) && Object.hasOwn(mod.default, 'schedules') ? mod.default.schedules : mod.default;
+    return parseSchedules(mod.schedules ?? fromDefault, where);
+}
+/** Load and check `<dir>/schedules.ts`; `where` names it in errors (`schedules.ts`, `sequences/pi/schedules.ts`). */
+export async function loadSchedules(dir, where) {
+    const modulePath = findTsModule(dir, SCHEDULES_MODULE);
+    if (!modulePath)
+        return null;
+    const schedules = await importSchedules(modulePath, where);
+    const functions = {};
+    const manifest = {};
+    for (const [name, { cron, timezone, run }] of Object.entries(schedules)) {
+        functions[scheduleFunctionName(name)] = { kind: 'noCase', main: run };
+        manifest[name] = { cron: cron.trim(), timezone };
+    }
+    return { path: modulePath, functions, manifest };
+}
+/** The build's registry entries of the jobs: `schedule.<name>` (`code` left out on the serve overlay). */
+export async function scheduleRegistry(loaded, includeCode) {
+    const entries = await Promise.all(Object.keys(loaded.manifest).map(async (name) => [
+        scheduleFunctionName(name),
+        includeCode
+            ? { kind: 'noCase', code: await compileScheduleModuleCode(loaded.path, name) }
+            : { kind: 'noCase' },
+    ]));
+    return Object.fromEntries(entries);
+}
+/** Authored functions must leave `schedule.*` to `schedules.ts`. */
+export function assertNoScheduleNames(names, where) {
+    const taken = names.filter((name) => name.startsWith(SCHEDULE_FUNCTION_PREFIX));
+    if (taken.length > 0) {
+        throw new Error(`${where} must not define ${taken.map((n) => `'${n}'`).join(', ')}: ${SCHEDULE_FUNCTION_PREFIX}* names are the jobs of ${SCHEDULES_MODULE}.ts`);
+    }
+}
+//# sourceMappingURL=schedules.js.map

package/dist/builder/slot-schema-validation.d.ts

@@ -0,0 +1,4 @@
+import type { ValidationIssue } from '../core/slot/types.js';
+/** The issues that stop codegen and compile: all but {@link WARNING_SLOT_SCHEMA_CODES}. */
+export declare function fatalSlotSchemaIssues(issues: ValidationIssue[]): ValidationIssue[];
+//# sourceMappingURL=slot-schema-validation.d.ts.map

package/dist/builder/slot-schema-validation.js

@@ -0,0 +1,10 @@
+/**
+ * Slot schema issues that only warn. Every other issue fails codegen and compile: a new issue code
+ * blocks the build unless it is listed here on purpose. None warns today.
+ */
+const WARNING_SLOT_SCHEMA_CODES = new Set([]);
+/** The issues that stop codegen and compile: all but {@link WARNING_SLOT_SCHEMA_CODES}. */
+export function fatalSlotSchemaIssues(issues) {
+    return issues.filter((issue) => !WARNING_SLOT_SCHEMA_CODES.has(issue.code));
+}
+//# sourceMappingURL=slot-schema-validation.js.map

package/dist/builder/typecheck.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The repository's type check, as `pnpm 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 declare function typecheckRepo(repoRoot: string, onLog?: (text: string) => void): Promise<void>;
+//# sourceMappingURL=typecheck.d.ts.map

package/dist/builder/typecheck.js

@@ -0,0 +1,105 @@
+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, generateCompany, listSequenceIds } 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 `pnpm 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.
+    if (listSequenceIds(repoRoot).length > 0)
+        await generateAll(repoRoot);
+    else
+        await generateCompany(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,108 @@
-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 { 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 sequence's recurring jobs (`sequences/<id>/schedules.ts`, 25 §6.4), by name; each one's code is
+     * `functions['schedule.<name>']`. Absent: none.
+     */
+    schedules?: ScheduleManifest;
+};
+/**
+ * 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";
 //# sourceMappingURL=types.d.ts.map

package/dist/builder/types.js

@@ -1,2 +1,3 @@
-export {};
+/** Where company-level functions live, in place of a sequence's directory name. */
+export const COMPANY_SCOPE = '@company';
 //# 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