@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/cli/serve/index.js

@@ -1,26 +1,29 @@
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cancel, isCancel, select } from '@clack/prompts';
 import chokidar from 'chokidar';
-import { compileAll } from '../../builder/compile/compile-sequence.js';
+import { compileAll, compileCompanyPart, runtimePackageSource, runtimePackageVersion, } from '../../builder/compile/compile-sequence.js';
 import { withCompanyImportGraph } from '../../builder/company-import-graph.js';
-import { findTsModule } from '../../builder/paths.js';
-import { listSequenceIds, loadSequenceCaseContextView, loadSequenceFunctions } from '../../builder/load.js';
+import { findTsModule, requireCompanyResolveModule, requireResolveModule } from '../../builder/paths.js';
+import { listSequenceIds, loadCompanyWebhook, loadSequenceCaseOrchestrator, WEBHOOK_MODULE, loadCompanyResolver, loadSequenceResolver, loadSequenceEvents, loadSequenceFunctions, } from '../../builder/load.js';
+import { loadSchedules } from '../../builder/schedules.js';
+import { loadOnError } from '../../builder/errors.js';
+import { ORCHESTRATOR_FUNCTION } from '../../core/case-orchestrator/types.js';
+import { WEBHOOK_RECEIVED_FUNCTION } from '../../core/functions/events.js';
+import { COMPANY_RESOLVE_FUNCTION, RESOLVE_FUNCTION } from '../../core/party/types.js';
+import { COMPANY_SCOPE, } from '../../builder/types.js';
+import { realPath } from '../../builder/company-imports.js';
 import { createSourceComputeHost } from '../../compute-host/source-compute-host.js';
 import { formatRuntimeVersion } from '../../fn-context/rpc/request-id.js';
 import { encodeOverlayMessage, OVERLAY_REPLACED_CLOSE_CODE, parseOverlayMessage, } from '../../dev-overlay/protocol.js';
-const DEFAULT_BACKEND_URL = 'http://127.0.0.1:8100';
-function env(name) {
-    const value = process.env[name];
-    return value && value.length > 0 ? value : undefined;
-}
+import { getLogger } from '../../logger.js';
+import { listServeEnvironments, loadCachedServeAuthorization, resolveBackendUrl, ServeAuthorizationRejectedError, } from '../auth/auth.js';
+import { forgetServeAuthorization, loginServe } from '../auth/serve-login.js';
+import { toHttpUrl, toWsUrl } from '../auth/backend-url.js';
+import { progressIndicator } from '../auth/progress.js';
+const logger = getLogger(['runtime', 'overlay']);
 export function overlayWebSocketUrl(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}`);
-    }
+    const url = toWsUrl(raw);
     const path = url.pathname.replace(/\/$/, '');
     if (path === '')
         url.pathname = '/overlay';
@@ -29,14 +32,7 @@ export function overlayWebSocketUrl(raw) {
     return url.toString();
 }
 function overlayRpcUrl(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}`);
-    }
+    const url = toHttpUrl(raw);
     url.pathname = `${url.pathname.replace(/\/$/, '')}/trpc`;
     url.search = '';
     url.hash = '';
@@ -48,9 +44,20 @@ function sequenceIdFromPath(repoRoot, file) {
     const match = /^sequences[/\\]([^/\\]+)(?:[/\\]|$)/.exec(rel);
     return match?.[1] ?? null;
 }
-function isSchemaPath(repoRoot, file) {
-    const rel = path.relative(repoRoot, file);
-    return rel === 'schema.ts' || rel.startsWith(`schema${path.sep}`) || rel.startsWith('schema/');
+/** Not the repository's code: dependencies, git, and what compiling writes. */
+export function isIgnoredServePath(repoRoot, file) {
+    const parts = path.relative(repoRoot, file).split(/[/\\]/);
+    return parts.some((part) => part === 'node_modules' || part === '__gen' || part === 'build' || part === 'dist' || part.startsWith('.'));
+}
+/**
+ * What a changed file recompiles (22-sequence-as-business-unit §6): a file of one sequence, that
+ * sequence; anything else (`schema/`, `resolve.ts`, shared code) can reach every sequence, so all.
+ */
+export function reloadScopeForPath(repoRoot, file) {
+    if (isIgnoredServePath(repoRoot, file))
+        return null;
+    const sequenceId = sequenceIdFromPath(repoRoot, file);
+    return sequenceId ? { sequenceId } : 'all';
 }
 async function loadOne(repoRoot, sequenceId, generation) {
     return withCompanyImportGraph(repoRoot, async () => {
@@ -63,30 +70,102 @@ async function loadOne(repoRoot, sequenceId, generation) {
             throw new Error(`Failed to compile sequence ${sequenceId}`);
         }
         const sequenceDir = path.join(repoRoot, 'sequences', sequenceId);
+        // A sequence without `functions/` has none (76 §5.5), as the compile above takes it.
         const functionsPath = findTsModule(sequenceDir, 'functions');
-        if (!functionsPath) {
-            throw new Error(`No functions module for sequence ${sequenceId}`);
-        }
-        const functions = await loadSequenceFunctions(functionsPath);
-        const viewPath = findTsModule(sequenceDir, 'view');
-        const view = viewPath ? await loadSequenceCaseContextView(viewPath) : undefined;
-        return { build: compiled.build, functions, view, generation };
+        const caseOrchestratorPath = findTsModule(sequenceDir, 'orchestrator');
+        const authored = functionsPath ? await loadSequenceFunctions(functionsPath) : {};
+        const functions = {
+            ...authored,
+            [RESOLVE_FUNCTION]: (await loadSequenceResolver(requireResolveModule(sequenceDir, sequenceId))),
+            ...(caseOrchestratorPath ? { [ORCHESTRATOR_FUNCTION]: await loadSequenceCaseOrchestrator(caseOrchestratorPath) } : {}),
+        };
+        const eventsPath = findTsModule(sequenceDir, 'events');
+        const events = eventsPath ? await loadSequenceEvents(eventsPath) : {};
+        return { build: compiled.build, sourceMaps: compiled.sourceMaps, functions, events, generation };
     });
 }
+export async function loadCompany(repoRoot) {
+    return withCompanyImportGraph(repoRoot, async () => {
+        const webhookPath = findTsModule(repoRoot, WEBHOOK_MODULE);
+        return {
+            part: await compileCompanyPart(repoRoot, { includeCode: false }),
+            functions: {
+                [COMPANY_RESOLVE_FUNCTION]: (await loadCompanyResolver(requireCompanyResolveModule(repoRoot))),
+                ...(webhookPath ? { [WEBHOOK_RECEIVED_FUNCTION]: (await loadCompanyWebhook(webhookPath)) } : {}),
+                ...(await loadSchedules(repoRoot))?.functions,
+                ...(await loadOnError(repoRoot))?.functions,
+            },
+        };
+    });
+}
+/** The repository's sequences, compiled; a listed sequence missing from the repository is left out. */
 async function loadSequences(repoRoot, sequenceIds, generation) {
     return withCompanyImportGraph(repoRoot, async () => {
+        const present = new Set(listSequenceIds(repoRoot));
         const out = new Map();
         for (const sequenceId of sequenceIds) {
-            out.set(sequenceId, await loadOne(repoRoot, sequenceId, generation));
+            if (present.has(sequenceId))
+                out.set(sequenceId, await loadOne(repoRoot, sequenceId, generation));
         }
         return out;
     });
 }
+/**
+ * The changes waiting to be reloaded. A reload that fails keeps its scope (`fail`) for the next one,
+ * which a new file change starts (no retry on its own: the failure is in the code until it is
+ * edited); it is cleared only once a reload of it loads.
+ */
+export class ReloadQueue {
+    pending = { all: false, ids: new Set() };
+    failed = { all: false, ids: new Set() };
+    add(scope) {
+        if (scope === 'all')
+            this.pending.all = true;
+        else
+            this.pending.ids.add(scope.sequenceId);
+    }
+    /** Something changed since the last reload. */
+    hasChanges() {
+        return this.pending.all || this.pending.ids.size > 0;
+    }
+    /** The next reload: the new changes plus what failed before. */
+    take() {
+        const all = this.pending.all || this.failed.all;
+        const job = { all, ids: all ? new Set() : new Set([...this.failed.ids, ...this.pending.ids]) };
+        this.pending = { all: false, ids: new Set() };
+        this.failed = { all: false, ids: new Set() };
+        return job;
+    }
+    fail(job) {
+        this.failed = { all: this.failed.all || job.all, ids: new Set([...this.failed.ids, ...job.ids]) };
+    }
+}
+/**
+ * The state after a reload (`all`: the whole repository; else the sequences `ids` names), built
+ * aside: if any part fails to load it throws and the current state stays whole, never new company
+ * code with old sequences.
+ */
+export async function reloadServeState(repoRoot, current, job, generation) {
+    // Recompiling everything also picks up sequence directories added or removed since.
+    const ids = job.all ? listSequenceIds(repoRoot) : [...job.ids];
+    // The company's code is outside `sequences/`, so only a recompile of everything reaches it.
+    const company = job.all ? await loadCompany(repoRoot) : current.company;
+    const loaded = await loadSequences(repoRoot, ids, generation);
+    const sequences = job.all ? new Map() : new Map(current.sequences);
+    for (const id of ids) {
+        const next = loaded.get(id);
+        if (next)
+            sequences.set(id, next);
+        else
+            sequences.delete(id);
+    }
+    return { company, sequences };
+}
 function send(ws, message) {
     ws.send(encodeOverlayMessage(message));
 }
 function logField(label, value) {
-    console.log(`  ${label.padEnd(10)} ${value}`);
+    logger.info(label, value);
 }
 async function handleExecute(loaded, message, rpcUrl) {
     const data = message.data
@@ -97,30 +176,78 @@ async function handleExecute(loaded, message, rpcUrl) {
         : undefined;
     const host = createSourceComputeHost({
         functions: loaded.functions,
-        caseContextView: loaded.view,
+        events: loaded.events,
         data: data,
         runToken: message.runToken,
-        runtimeVersion: loaded.build.engineVersion,
-        runtimeSource: loaded.build.runtimeSource ?? 'npm',
+        runtimeVersion: loaded.runtimeVersion,
+        runtimeSource: loaded.runtimeSource,
         getRequestId: () => message.logRequestId,
         getTags: () => message.logTags,
     });
     try {
-        return await host.execute(message.name, message.args);
+        return await host.execute(message.name, message.invocation);
     }
     finally {
         host.dispose();
     }
 }
-function pushOverlays(ws, sequences) {
-    for (const [sequenceId, loaded] of sequences) {
-        send(ws, {
-            type: 'overlay',
-            sequenceId,
-            generation: loaded.generation,
-            build: loaded.build,
-        });
+/**
+ * Push the local company build: the company's functions and every loaded sequence, as one overlay.
+ * With no sequence left it is still pushed, so the environment drops the ones it had (22 §11).
+ */
+export function pushOverlay(ws, company, sequences, generation) {
+    const build = {
+        company: company.part,
+        sequences: Object.fromEntries([...sequences].map(([sequenceId, sequence]) => [sequenceId, sequence.build])),
+    };
+    const sourceMaps = Object.assign({}, ...[...sequences.values()].map((sequence) => sequence.sourceMaps));
+    send(ws, { type: 'overlay', generation, build, sourceMaps });
+}
+/** A stack frame as V8 prints it: `at name (file:line:col)` or `at file:line:col`. */
+const STACK_FRAME = /^\s*at (?:(.*?) \()?(.+?):(\d+):(\d+)\)?$/;
+/**
+ * What the company is shown of a failed function's stack (the backend's company logs): the error's first
+ * line and the frames of the repository's own files, by their path from its root. tsx runs the original
+ * files, so their lines are already the company's. Undefined when no frame is the repository's.
+ */
+export function repositoryStack(error, repoRoot) {
+    if (!(error instanceof Error) || !error.stack)
+        return undefined;
+    const lines = error.stack.split('\n');
+    const firstFrame = lines.findIndex((line) => /^\s*at /.test(line));
+    if (firstFrame === -1)
+        return undefined;
+    const roots = [...new Set([path.resolve(repoRoot), realPath(repoRoot)])];
+    const frames = lines.slice(firstFrame).flatMap((line) => {
+        const frame = STACK_FRAME.exec(line);
+        const file = frame ? repositoryFile(frame[2], roots) : null;
+        if (!frame || !file)
+            return [];
+        return [`    at ${frame[1] ? `${frame[1]} (` : ''}${file}:${frame[3]}:${frame[4]}${frame[1] ? ')' : ''}`];
+    });
+    return frames.length > 0 ? [...lines.slice(0, firstFrame), ...frames].join('\n') : undefined;
+}
+/** A frame's file as a path from the repository root; null outside its own files (node_modules included). */
+function repositoryFile(location, roots) {
+    let file = location;
+    if (file.startsWith('file://')) {
+        try {
+            // The import graph stamps the URLs it loads (`?spgen=…`).
+            file = fileURLToPath(file.replace(/[?#].*$/, ''));
+        }
+        catch {
+            return null;
+        }
     }
+    if (!path.isAbsolute(file))
+        return null;
+    for (const root of roots) {
+        const relative = path.relative(root, file);
+        if (relative && !relative.startsWith('..') && !path.isAbsolute(relative) && !relative.split(path.sep).includes('node_modules')) {
+            return relative.split(path.sep).join('/');
+        }
+    }
+    return null;
 }
 function closeDetail(event) {
     return event.reason ? `${event.code} ${event.reason}` : String(event.code);
@@ -160,6 +287,36 @@ class OverlayReplacedError extends Error {
         this.name = 'OverlayReplacedError';
     }
 }
+/** Transient: an infra hiccup, or a lease that was just replaced. Retry with backoff. */
+class OverlayUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OverlayUnavailableError';
+    }
+}
+/** Permanent: the request itself is invalid (missing or unknown environment, prod). Fatal. */
+class OverlayRequestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OverlayRequestError';
+    }
+}
+export function toOverlayError(message) {
+    switch (message.code) {
+        case 'authorization':
+            return new ServeAuthorizationRejectedError(message.error);
+        case 'request':
+            return new OverlayRequestError(message.error);
+        case 'unavailable':
+            return new OverlayUnavailableError(message.error);
+        default: {
+            // The wire format is not type-checked: a code this CLI doesn't know is a protocol bug, so
+            // stop and say so instead of reconnecting forever on an `undefined` error.
+            const unknown = message.code;
+            return new OverlayRequestError(`unknown auth.error code ${JSON.stringify(unknown)}: ${message.error}`);
+        }
+    }
+}
 function waitAuthOk(ws) {
     return new Promise((resolve, reject) => {
         const onMessage = (event) => {
@@ -177,7 +334,7 @@ function waitAuthOk(ws) {
                 }
                 if (message.type === 'auth.error') {
                     cleanup();
-                    reject(new Error(message.error));
+                    reject(toOverlayError(message));
                 }
             }
             catch (error) {
@@ -199,7 +356,12 @@ function waitAuthOk(ws) {
         ws.addEventListener('close', onClose);
     });
 }
-function attachExecuteHandler(ws, sequences, rpcUrl) {
+/**
+ * Runs each `execute` the backend sends, unless its deadline has passed: the backend has then reported
+ * it as failed (a paused process, a laptop that slept), and running it would repeat its effects when
+ * the call is retried. One already started is not interrupted.
+ */
+export function attachExecuteHandler(ws, find, rpcUrl, repoRoot) {
     ws.addEventListener('message', (event) => {
         void (async () => {
             let message;
@@ -207,46 +369,92 @@ function attachExecuteHandler(ws, sequences, rpcUrl) {
                 message = parseOverlayMessage(String(event.data));
             }
             catch (error) {
-                console.error('bad server message:', error instanceof Error ? error.message : error);
+                logger.error('bad server message', error);
                 return;
             }
             if (message.type !== 'execute')
                 return;
-            const call = `${message.sequenceId} ${message.name}`;
-            const loaded = sequences.get(message.sequenceId);
+            const lateMs = Date.now() - message.deadline;
+            if (lateMs > 0) {
+                send(ws, {
+                    type: 'execute.result',
+                    requestId: message.requestId,
+                    ok: false,
+                    error: `expired: the backend stopped waiting ${lateMs} ms ago, so it was not run`,
+                    notStarted: true,
+                });
+                logger.warn('execute skipped: it arrived after the backend stopped waiting', {
+                    sequenceId: message.sequenceId,
+                    name: message.name,
+                    lateMs,
+                });
+                return;
+            }
+            const loaded = find(message.sequenceId);
             if (!loaded) {
                 const error = `unknown sequence ${message.sequenceId}`;
-                console.error(`execute ${call} failed: ${error}`);
                 send(ws, {
                     type: 'execute.result',
                     requestId: message.requestId,
                     ok: false,
                     error,
+                    notStarted: true,
                 });
+                logger.error('execute failed', { sequenceId: message.sequenceId, name: message.name, error });
                 return;
             }
             const started = Date.now();
-            console.log(`execute ${call}`);
+            let result;
             try {
-                const result = await handleExecute(loaded, message, rpcUrl);
-                console.log(`execute ${call} ok ${Date.now() - started}ms`);
-                send(ws, { type: 'execute.result', requestId: message.requestId, ok: true, result });
+                result = await handleExecute(loaded, message, rpcUrl);
             }
             catch (error) {
                 const text = error instanceof Error ? error.message : String(error);
-                console.error(`execute ${call} failed: ${text}`);
+                const stack = repositoryStack(error, repoRoot);
                 send(ws, {
                     type: 'execute.result',
                     requestId: message.requestId,
                     ok: false,
                     error: text,
+                    ...(stack ? { stack } : {}),
+                    ...(error instanceof Error && error.name === 'PlatformUnavailableError' ? { platform: true } : {}),
                 });
+                logger.error('execute failed', {
+                    sequenceId: message.sequenceId,
+                    name: message.name,
+                    durationMs: Date.now() - started,
+                    error: text,
+                }, ...(stack ? [`\n${stack}`] : []));
+                return;
             }
+            send(ws, { type: 'execute.result', requestId: message.requestId, ok: true, result });
+            logger.info('execute ok', {
+                sequenceId: message.sequenceId,
+                name: message.name,
+                durationMs: Date.now() - started,
+            });
         })();
     });
 }
+function attachNoticeHandler(ws) {
+    ws.addEventListener('message', (event) => {
+        let message;
+        try {
+            message = parseOverlayMessage(String(event.data));
+        }
+        catch {
+            return;
+        }
+        if (message.type !== 'notice')
+            return;
+        if (message.details.length > 0)
+            logger.warn(message.message, message.details);
+        else
+            logger.warn(message.message);
+    });
+}
 function waitSessionEnd(ws) {
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
         if (ws.readyState === WebSocket.CLOSED) {
             resolve({ closed: 'already closed' });
             return;
@@ -255,9 +463,14 @@ function waitSessionEnd(ws) {
             try {
                 const message = parseOverlayMessage(String(event.data));
                 if (message.type === 'replaced') {
+                    logger.warn('another serve took the environment');
                     cleanup();
                     resolve('replaced');
                 }
+                else if (message.type === 'auth.error') {
+                    cleanup();
+                    reject(toOverlayError(message));
+                }
             }
             catch {
                 return;
@@ -275,35 +488,128 @@ function waitSessionEnd(ws) {
         ws.addEventListener('close', onClose);
     });
 }
+function exitOnCancel() {
+    cancel('Cancelled.');
+    process.exit(1);
+}
+/**
+ * Only prompt when there's an actual person at a terminal to answer — a CI runner, a piped/
+ * redirected stdin, or any other non-interactive invocation must keep failing fast on a missing
+ * flag instead of hanging on a readline prompt with undefined behavior off a real TTY.
+ */
+function requireInteractiveOrThrow(flag) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error(`${flag} is required (not running in an interactive terminal to prompt for it)`);
+    }
+}
+/** The token's non-prod environments. A rejected token surfaces as `ServeAuthorizationRejectedError`. */
+async function fetchEnvironments(backendUrl, authorization) {
+    const progress = progressIndicator();
+    const company = authorization.companyName ? ` in ${authorization.companyName}` : '';
+    progress.start(`Fetching environments${company}…`);
+    let environments;
+    try {
+        environments = await listServeEnvironments(backendUrl, authorization.token);
+    }
+    catch (error) {
+        if (error instanceof ServeAuthorizationRejectedError) {
+            progress.error('Login was rejected by the backend.');
+            throw error;
+        }
+        progress.error('Could not fetch environments.');
+        throw new Error(`Could not list environments: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    progress.stop(`Found ${environments.length} environment${environments.length === 1 ? '' : 's'}${company}.`);
+    return environments;
+}
+/**
+ * Login plus the company's environments. Listing them doubles as checking the cached token against
+ * the backend: it can be unexpired locally yet rejected (revoked, re-keyed, access removed), and
+ * then it is dropped for a fresh browser login. Rejections after startup stop serve instead.
+ */
+async function authorizeWithEnvironments(backendUrl, openBrowser) {
+    const cached = await loadCachedServeAuthorization(backendUrl);
+    if (cached) {
+        logger.info('using cached serve authorization');
+        try {
+            return { authorization: cached, environments: await fetchEnvironments(backendUrl, cached) };
+        }
+        catch (error) {
+            if (!(error instanceof ServeAuthorizationRejectedError))
+                throw error;
+            logger.warn('cached serve authorization is no longer valid; authorizing again', { error: error.message });
+            await forgetServeAuthorization(backendUrl, cached);
+        }
+    }
+    const authorization = await loginServe(backendUrl, { openBrowser });
+    return { authorization, environments: await fetchEnvironments(backendUrl, authorization) };
+}
+/** Prompts for one non-prod environment when `--environment` was not given. Shows id and name. */
+async function promptForEnvironment(environments) {
+    if (environments.length === 0) {
+        throw new Error('No non-prod environments available for this company.');
+    }
+    const picked = await select({
+        message: 'Which environment should Local Serve overlay?',
+        options: environments.map((environment) => ({
+            value: environment.id,
+            label: environment.name,
+            hint: environment.id,
+        })),
+    });
+    if (isCancel(picked))
+        exitOnCancel();
+    return picked;
+}
 export async function runServe(repoRoot, options = {}) {
-    const companyId = options.companyId ?? env('SUPERPANEL_SDK_COMPANY_ID');
-    const apiKey = options.apiKey ?? env('SUPERPANEL_SDK_API_KEY');
-    if (!companyId)
-        throw new Error('SUPERPANEL_SDK_COMPANY_ID or --company is required');
-    if (!apiKey)
-        throw new Error('SUPERPANEL_SDK_API_KEY or --api-key is required');
-    const backendUrl = options.url ?? env('SUPERPANEL_SDK_BACKEND_URL') ?? DEFAULT_BACKEND_URL;
-    const url = overlayWebSocketUrl(backendUrl);
-    const rpcUrl = overlayRpcUrl(backendUrl);
-    const sequenceIds = options.sequenceIds ?? listSequenceIds(repoRoot);
-    if (sequenceIds.length === 0) {
-        throw new Error(`No sequences with slots found under ${path.join(repoRoot, 'sequences')}`);
+    const backendUrl = resolveBackendUrl(repoRoot, options.url);
+    // A non-interactive caller cannot answer the prompt. Check this before authorization so a CI job
+    // with a missing flag fails instead of waiting on a browser-based device-auth flow.
+    let environment = options.environment?.trim();
+    if (!environment)
+        requireInteractiveOrThrow('--environment <id>');
+    if (listSequenceIds(repoRoot).length === 0) {
+        throw new Error(`No sequences found under ${path.join(repoRoot, 'sequences')}`);
     }
+    // Login is the first interactive step: the environment prompt needs the company-scoped token.
+    const { authorization, environments } = await authorizeWithEnvironments(backendUrl, options.openBrowser !== false);
+    if (!environment)
+        environment = await promptForEnvironment(environments);
+    // The whole repository serves the environment (22 §6): every sequence, and only these.
     let generation = 1;
-    const sequences = await loadSequences(repoRoot, sequenceIds, generation);
+    let company = await loadCompany(repoRoot);
+    let sequences = await loadSequences(repoRoot, listSequenceIds(repoRoot), generation);
+    const runtimeSource = runtimePackageSource(repoRoot);
+    const find = (scope) => {
+        if (scope === COMPANY_SCOPE) {
+            return { functions: company.functions, events: {}, runtimeVersion: runtimePackageVersion(), runtimeSource };
+        }
+        const loaded = sequences.get(scope);
+        return loaded
+            ? {
+                functions: loaded.functions,
+                events: loaded.events,
+                runtimeVersion: loaded.build.engineVersion,
+                runtimeSource: loaded.build.runtimeSource,
+            }
+            : undefined;
+    };
+    const url = overlayWebSocketUrl(backendUrl);
+    const rpcUrl = overlayRpcUrl(backendUrl);
     let socket = null;
-    const names = [...sequences.keys()];
     const firstBuild = sequences.values().next().value?.build;
-    console.log('Local overlay');
-    logField('company', companyId);
-    logField('sequences', names.join(', '));
+    logger.info('Local overlay');
+    logField('user', authorization.user.email);
+    logField('company', authorization.companyId);
+    logField('environment', environment);
+    logField('sequences', [...sequences.keys()].join(', '));
     if (firstBuild) {
-        logField('runtime', formatRuntimeVersion(firstBuild.engineVersion, firstBuild.runtimeSource ?? 'npm'));
+        logField('runtime', formatRuntimeVersion(firstBuild.engineVersion, firstBuild.runtimeSource));
     }
     logField('backend', backendUrl);
     logField('websocket', url);
     let timer;
-    let pending = { all: false, ids: new Set() };
+    const queue = new ReloadQueue();
     let flushing = false;
     const flush = () => {
         if (flushing)
@@ -311,54 +617,51 @@ export async function runServe(repoRoot, options = {}) {
         flushing = true;
         void (async () => {
             try {
-                while (pending.all || pending.ids.size > 0) {
-                    const job = pending;
-                    pending = { all: false, ids: new Set() };
+                while (queue.hasChanges()) {
+                    const job = queue.take();
                     generation += 1;
-                    const ids = job.all ? sequenceIds : [...job.ids];
-                    const next = await loadSequences(repoRoot, ids, generation);
-                    if (job.all)
-                        sequences.clear();
-                    for (const [id, loaded] of next)
-                        sequences.set(id, loaded);
+                    // Swapped in only whole: a failed reload leaves the code that runs (and is pushed) as it was.
+                    let next;
+                    try {
+                        next = await reloadServeState(repoRoot, { company, sequences }, job, generation);
+                    }
+                    catch (error) {
+                        // Kept for the next change: fixing one sequence then also reloads what this one covered.
+                        queue.fail(job);
+                        logger.error('reload failed', error);
+                        continue;
+                    }
+                    company = next.company;
+                    sequences = next.sequences;
                     if (socket && socket.readyState === WebSocket.OPEN) {
-                        pushOverlays(socket, sequences);
-                        console.log(`reloaded sequences ${ids.join(', ')}`);
+                        pushOverlay(socket, company, sequences, generation);
+                        logger.info('reloaded sequences', job.all ? 'all' : [...job.ids]);
                     }
                 }
             }
             catch (error) {
-                console.error('reload failed:', error instanceof Error ? error.message : error);
+                logger.error('reload failed', error);
             }
             finally {
                 flushing = false;
-                if (pending.all || pending.ids.size > 0)
+                if (queue.hasChanges())
                     flush();
             }
         })();
     };
     chokidar
-        .watch([path.join(repoRoot, 'schema'), path.join(repoRoot, 'schema.ts'), path.join(repoRoot, 'sequences')], {
+        .watch(repoRoot, {
         ignoreInitial: true,
-        ignored: (p) => p.includes(`${path.sep}__gen${path.sep}`) || p.includes(`${path.sep}build${path.sep}`),
+        ignored: (p) => isIgnoredServePath(repoRoot, p),
     })
         .on('all', (event, file) => {
         if (!file)
             return;
-        if (file.includes(`${path.sep}__gen${path.sep}`))
-            return;
-        if (file.includes(`${path.sep}build${path.sep}`))
-            return;
-        const rel = path.relative(repoRoot, file);
-        const schemaHit = isSchemaPath(repoRoot, file);
-        const sequenceId = sequenceIdFromPath(repoRoot, file);
-        if (!schemaHit && !sequenceId)
+        const scope = reloadScopeForPath(repoRoot, file);
+        if (!scope)
             return;
-        console.log(`changed ${rel}`);
-        if (schemaHit)
-            pending.all = true;
-        else if (sequenceId)
-            pending.ids.add(sequenceId);
+        logger.info('changed', path.relative(repoRoot, file));
+        queue.add(scope);
         clearTimeout(timer);
         timer = setTimeout(flush, 100);
     });
@@ -369,26 +672,35 @@ export async function runServe(repoRoot, options = {}) {
         try {
             await waitOpen(ws);
             const authOk = waitAuthOk(ws);
-            send(ws, {
-                type: 'auth',
-                apiKey,
-                companyId,
-                names: [...sequences.keys()],
-            });
+            send(ws, { type: 'auth', token: authorization.token, environment });
             await authOk;
-            attachExecuteHandler(ws, sequences, rpcUrl);
-            pushOverlays(ws, sequences);
+            attachExecuteHandler(ws, find, rpcUrl, repoRoot);
+            attachNoticeHandler(ws);
+            pushOverlay(ws, company, sequences, generation);
             delayMs = 500;
-            console.log(`connected  overlay ${url}`);
+            logger.info('connected', { url });
             const end = await waitSessionEnd(ws);
             if (end === 'replaced')
                 throw new OverlayReplacedError();
-            console.log(`disconnected  retrying  ${end.closed}`);
+            logger.warn('disconnected; retrying', { detail: end.closed });
         }
         catch (error) {
             if (error instanceof OverlayReplacedError)
                 throw error;
-            console.error('connection failed:', error instanceof Error ? error.message : error);
+            if (error instanceof OverlayRequestError)
+                throw error;
+            if (error instanceof ServeAuthorizationRejectedError) {
+                // Mid-session the identity is fixed: stop rather than log in again, and drop the cached
+                // token so the user's next `serve` starts with a fresh login.
+                await forgetServeAuthorization(backendUrl, authorization);
+                throw new Error(`Serve authorization was rejected (${error.message}). Run serve again to log in.`);
+            }
+            if (error instanceof OverlayUnavailableError) {
+                logger.warn('serve is temporarily unavailable; retrying', { error: error.message });
+            }
+            else {
+                logger.error('connection failed', error);
+            }
             if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
                 ws.close();
             }
@@ -398,4 +710,80 @@ export async function runServe(repoRoot, options = {}) {
         delayMs = Math.min(delayMs * 2, 5_000);
     }
 }
+/**
+ * The repository served on `environmentId` as `serve` serves it, once (no file watch, no reconnect): its
+ * code loaded through the company import graph (an import the compile refuses fails here), pushed, and
+ * every function the environment runs meanwhile run here. Resolves once the environment took it.
+ */
+export async function openOverlay(repoRoot, options) {
+    if (listSequenceIds(repoRoot).length === 0)
+        throw new Error(`No sequences found under ${path.join(repoRoot, 'sequences')}`);
+    const company = await loadCompany(repoRoot);
+    const sequences = await loadSequences(repoRoot, listSequenceIds(repoRoot), 1);
+    const runtimeSource = runtimePackageSource(repoRoot);
+    const find = (scope) => {
+        if (scope === COMPANY_SCOPE)
+            return { functions: company.functions, events: {}, runtimeVersion: runtimePackageVersion(), runtimeSource };
+        const loaded = sequences.get(scope);
+        return loaded
+            ? { functions: loaded.functions, events: loaded.events, runtimeVersion: loaded.build.engineVersion, runtimeSource: loaded.build.runtimeSource }
+            : undefined;
+    };
+    const ws = new WebSocket(overlayWebSocketUrl(options.backendUrl));
+    try {
+        await waitOpen(ws);
+        const authOk = waitAuthOk(ws);
+        send(ws, { type: 'auth', token: options.token, environment: options.environmentId });
+        await authOk;
+    }
+    catch (error) {
+        ws.close();
+        throw error;
+    }
+    attachExecuteHandler(ws, find, overlayRpcUrl(options.backendUrl), repoRoot);
+    attachNoticeHandler(ws);
+    // Served once the backend says so (`overlay.ok`): a call made before could still run the release.
+    const served = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('the environment did not take the code within 60 s')), 60_000);
+        ws.addEventListener('message', (event) => {
+            try {
+                const message = parseOverlayMessage(String(event.data));
+                if (message.type === 'overlay.ok' && message.generation === 1) {
+                    clearTimeout(timer);
+                    resolve();
+                }
+                else if (message.type === 'auth.error') {
+                    clearTimeout(timer);
+                    reject(new Error(`serve: ${message.error}`));
+                }
+            }
+            catch {
+                // not a message of ours
+            }
+        });
+        ws.addEventListener('close', () => {
+            clearTimeout(timer);
+            reject(new Error('the environment closed the connection before it took the code'));
+        });
+    });
+    pushOverlay(ws, company, sequences, 1);
+    try {
+        await served;
+    }
+    catch (error) {
+        ws.close();
+        throw error;
+    }
+    return {
+        sequences: [...sequences.keys()],
+        close: async () => {
+            if (ws.readyState === WebSocket.CLOSED)
+                return;
+            await new Promise((resolve) => {
+                ws.addEventListener('close', () => resolve(), { once: true });
+                ws.close();
+            });
+        },
+    };
+}
 //# sourceMappingURL=index.js.map