@owlmeans/viable-sdk 0.1.18-rc.1

package/build/project/setup.js

@@ -0,0 +1,190 @@
+import fs from 'fs-extra';
+import p from 'node:path';
+import { spawn } from 'node:child_process';
+import { hasWorker } from '../executor/layout.js';
+import { CONNECT_ENV_BEGIN, CONNECT_ENV_END } from '@owlmeans/viable-common';
+import { probeUrl, readEnv, ROOT_ENV_FILE } from './env.js';
+/** Everything a connection string says except who is connecting. */
+export const redactUrl = (url) => {
+    try {
+        const parsed = new URL(url);
+        if (parsed.username !== '' || parsed.password !== '') {
+            parsed.username = '***';
+            parsed.password = '';
+        }
+        return parsed.toString();
+    }
+    catch {
+        return url.replace(/\/\/[^@/]*@/, '//***@');
+    }
+};
+/** Whether a command can be run here. `--version` rather than `which`, which Windows lacks. */
+export const probeCommand = async (command) => await new Promise(resolve => {
+    const child = spawn(command, ['--version'], { stdio: 'ignore', shell: process.platform === 'win32' });
+    const settle = (ok) => { resolve(ok); };
+    child.once('error', () => { settle(false); });
+    child.once('exit', code => { settle(code === 0); });
+    setTimeout(() => { child.kill(); settle(false); }, 4_000).unref?.();
+});
+const stateOf = async (url) => {
+    const configured = url != null && url.trim() !== '' && !url.includes('postgres:postgres@localhost:5432');
+    return {
+        configured,
+        reachable: configured ? await probeUrl(url) : false,
+        ...(configured ? { redacted: redactUrl(url) } : {}),
+    };
+};
+/** Whether the project's own `.env` is kept out of its history — it holds credentials. */
+const envIsIgnored = async (dir) => {
+    const ignore = await fs.readFile(p.join(dir, '.gitignore'), 'utf-8').catch(() => '');
+    return /^\s*\.env\s*$/m.test(ignore) || /^\s*\*\.env\s*$/m.test(ignore) || /^\s*\.env\*/m.test(ignore);
+};
+export const readSetupReport = async (dir) => {
+    const { values } = await readEnv(dir);
+    const [database, queue, bun, git, docker, envIgnored] = await Promise.all([
+        stateOf(values.DATABASE_URL),
+        stateOf(values.VALKEY_URL),
+        probeCommand('bun'),
+        probeCommand('git'),
+        probeCommand('docker'),
+        envIsIgnored(dir),
+    ]);
+    return {
+        dir,
+        needsWorker: hasWorker(dir),
+        database,
+        queue,
+        tools: { bun, git, docker },
+        platform: process.platform,
+        envIgnored,
+    };
+};
+/** What is still missing before the application can start. */
+export const missingServices = (report) => [
+    ...(report.database.reachable ? [] : ['database']),
+    ...(report.needsWorker && !report.queue.reachable ? ['queue'] : []),
+];
+const dockerPostgres = (port) => `docker run -d --name viable-postgres -e POSTGRES_PASSWORD=viable -e POSTGRES_USER=viable`
+    + ` -e POSTGRES_DB=viable -p ${port}:5432 postgres:16-alpine`;
+const dockerValkey = (port) => `docker run -d --name viable-valkey -p ${port}:6379 valkey/valkey:8-alpine`;
+const nativeInstall = (platform) => platform === 'darwin'
+    ? ['  brew install postgresql@16 && brew services start postgresql@16',
+        '  brew install valkey && brew services start valkey']
+    : platform === 'win32'
+        ? ['  winget install PostgreSQL.PostgreSQL',
+            '  (a queue store is easiest through Docker Desktop on Windows)']
+        : ['  sudo apt install postgresql redis-server   # Debian/Ubuntu',
+            '  sudo systemctl enable --now postgresql redis-server'];
+/**
+ * The answer a parent agent reads when the project cannot run yet.
+ *
+ * It is written as a QUESTION with three answers, because which one is right is the user's to
+ * decide and nobody else's: they may already run Postgres, they may want one installed here, or
+ * they may prefer a hosted free tier and never install anything. Guessing means either a container
+ * on somebody's machine they did not ask for, or a connection string invented for a database that
+ * does not exist — and the second surfaces minutes later as a boot error nobody can place.
+ */
+export const renderSetupGuide = (report) => {
+    const missing = missingServices(report);
+    const lines = [`Project: ${report.dir}`, ''];
+    lines.push('What this machine provides:');
+    lines.push(`  bun      ${report.tools.bun ? 'yes' : 'NO — install it from https://bun.sh'}`);
+    lines.push(`  git      ${report.tools.git ? 'yes' : 'NO — the project keeps its own history'}`);
+    lines.push(`  database ${report.database.reachable
+        ? `yes — ${report.database.redacted ?? 'configured'}`
+        : report.database.configured
+            ? `configured but NOT answering — ${report.database.redacted ?? ''}`
+            : 'not configured'}`);
+    lines.push(`  queue    ${report.needsWorker
+        ? report.queue.reachable
+            ? `yes — ${report.queue.redacted ?? 'configured'}`
+            : report.queue.configured ? 'configured but NOT answering' : 'not configured'
+        : 'not needed — this project has no background worker'}`);
+    lines.push('');
+    if (missing.length < 1) {
+        lines.push('Everything the application needs is in place. Call run_local to build and start it.');
+        return lines.join('\n');
+    }
+    const what = missing.map(one => one === 'database' ? 'a Postgres database' : 'a queue store (Valkey or Redis)');
+    lines.push(`ASK THE USER — this project still needs ${what.join(' and ')}, and only they can say how to`, 'provide it. Put these three choices to them in your own words and wait for an answer:', '', '  1. "I already have one"  — running here, on another machine, or a service you already pay', '     for. Ask for the connection string and nothing else.', '  2. "Install one here"    — the commands are below; run them only if they choose this.', '  3. "Use a free hosted plan" — Supabase or Neon for Postgres, Upstash for Redis. They sign', '     up, create a project, and copy the connection string.', '', 'Then call set_local_service with what they gave you. Do not invent a connection string, and do', 'not install anything before they have chosen.', '');
+    if (missing.includes('database')) {
+        lines.push('--- 2. Install Postgres here ---');
+        lines.push(report.tools.docker
+            ? `  ${dockerPostgres(5432)}`
+            : '  Docker is not installed. Either install Docker, or use the native package:');
+        if (!report.tools.docker)
+            lines.push(nativeInstall(report.platform)[0]);
+        lines.push('  Then the connection string is:', '    postgres://viable:viable@localhost:5432/viable', '', '--- 3. Free hosted Postgres ---', '  Supabase: https://supabase.com → New project → Settings → Database → Connection string', '            (choose the "URI" form; it already carries the password)', '  Neon:     https://neon.tech → New project → Connection string', '  Either gives a `postgres://…` URL that goes straight into set_local_service.', '');
+    }
+    if (missing.includes('queue')) {
+        lines.push('--- A queue store, for this project\'s worker ---');
+        lines.push(report.tools.docker
+            ? `  ${dockerValkey(6379)}`
+            : nativeInstall(report.platform)[1]);
+        lines.push('  Then: redis://localhost:6379', '  Free hosted: https://upstash.com → Redis → Create database → copy the `redis://…` URL.', '');
+    }
+    lines.push('--- Where the value goes ---', `  Into ${p.join(report.dir, ROOT_ENV_FILE)}, OUTSIDE the block marked "viable:managed".`, '  set_local_service writes it there for you. The platform never overwrites a key you set,', '  and the credential never reaches the project marker, your agent\'s configuration, or the', '  platform.', report.envIgnored
+        ? '  That file is git-ignored, so the credential stays out of the project\'s history.'
+        : '  WARNING: .env is NOT git-ignored in this project. Say so before writing a credential.');
+    return lines.join('\n');
+};
+/**
+ * Write the user's own service lines into their half of the `.env`.
+ *
+ * Replaces the key where it already exists outside the managed block and appends it otherwise, so
+ * running this twice leaves one line rather than two — a `.env` takes the LAST assignment, and two
+ * copies of a credential is one of them being quietly ignored.
+ */
+export const setUserEnv = async (dir, values) => {
+    const file = p.join(dir, ROOT_ENV_FILE);
+    const existing = await fs.readFile(file, 'utf-8').catch(() => '');
+    const lines = existing === '' ? [] : existing.split('\n');
+    const written = [];
+    for (const [key, value] of Object.entries(values)) {
+        if (value.trim() === '')
+            continue;
+        written.push(key);
+        const line = `${key}=${value}`;
+        const pattern = new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=`);
+        // Walked with the block's boundaries in hand, because only a line the USER owns may be
+        // rewritten: one inside the managed block belongs to the platform, which composes its half
+        // whole on every push.
+        let inside = false;
+        let replaced = false;
+        for (let i = 0; i < lines.length; ++i) {
+            if (lines[i].trim() === CONNECT_ENV_BEGIN) {
+                inside = true;
+                continue;
+            }
+            if (lines[i].trim() === CONNECT_ENV_END) {
+                inside = false;
+                continue;
+            }
+            if (inside || !pattern.test(lines[i]))
+                continue;
+            lines[i] = line;
+            replaced = true;
+            break;
+        }
+        // Appended AFTER the block when it is new. A `.env` takes the last assignment, so a value the
+        // user set outranks the platform's placeholder wherever the block happens to sit.
+        if (!replaced) {
+            if (lines.length > 0 && lines[lines.length - 1] === '')
+                lines.pop();
+            lines.push(line);
+        }
+    }
+    // Nothing to say, nothing to write: rewriting the file for an empty call would rewrite its
+    // trailing whitespace and show up as a change nobody made.
+    if (written.length < 1)
+        return { written, file };
+    while (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    const next = lines.length > 0 ? `${lines.join('\n')}\n` : '';
+    if (next !== existing) {
+        await fs.ensureDir(p.dirname(file));
+        await fs.writeFile(file, next);
+    }
+    return { written, file };
+};
+//# sourceMappingURL=setup.js.map

package/build/project/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/project/setup.ts"],"names":[],"mappings":"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"}

package/build/run/index.d.ts

@@ -0,0 +1,75 @@
+import type { LocalRunRecord } from './state.js';
+export * from './state.js';
+export * from './serve.js';
+export interface RunLocalOptions {
+    /** Build before starting. On by default — starting a stale `dist/` is the confusing failure. */
+    build?: boolean;
+    log?: (line: string) => void;
+}
+export interface RunLocalResult {
+    record: LocalRunRecord | null;
+    /**
+     * The ports the run uses, so a caller can print an address without composing one.
+     *
+     * Stated even when a process did not come up: they are where the app WILL answer, and whether
+     * it does yet is what `error`, `buildError` and {@link localStatus} are for.
+     */
+    api: number;
+    web: number;
+    worker?: number;
+    /** The reason nothing was started, or the tree was refused. */
+    error?: string;
+    /** A build ran and failed. The web server still comes up so the state is visible. */
+    buildError?: string;
+}
+/** One supervised process, as a status read finds it. */
+export interface LocalProcessStatus {
+    pid: number;
+    port: number;
+    alive: boolean;
+}
+export interface LocalRunStatus {
+    running: boolean;
+    startedAt?: string;
+    /** Ports, flat, for a caller composing an address or a one-line report. */
+    api?: number;
+    worker?: number;
+    web?: number;
+    /** The target's own boot phase, when it got far enough to report one. */
+    phase?: string;
+    /** Whether the target says it is serving — never the same question as "the pid is alive". */
+    ready?: boolean;
+    /** Why it is not ready. Absent when it is. */
+    reason?: string;
+    processes: {
+        api?: LocalProcessStatus;
+        worker?: LocalProcessStatus;
+        web?: LocalProcessStatus;
+    };
+}
+/**
+ * Build the target, start its processes, serve its browser app.
+ *
+ * A previous run is stopped first: both halves bind fixed ports, and a replacement that races the
+ * process it is replacing loses the bind and exits — with nothing announcing it, since a failed
+ * `listen` says nothing on its own.
+ */
+export declare const runLocal: (dir: string, options?: RunLocalOptions) => Promise<RunLocalResult>;
+/**
+ * Stop whatever the run record names, and forget it.
+ *
+ * Safe to call when nothing is running: the record is the only authority, and a stale one names
+ * pids that are simply not alive. The children are detached, so they outlive the process that
+ * started them — which is exactly why the record is a file and this is the only way to end them.
+ */
+export declare const stopLocal: (dir: string) => Promise<void>;
+/**
+ * What is running, and whether the target is actually serving.
+ *
+ * Two independent facts, because either one alone lies. A live pid says nothing about a target
+ * that bound its port and then failed to reach its database — it answers `200` with `db.ok:false`
+ * and would otherwise read as healthy. A health answer says nothing about a process that died
+ * while something else holds the port.
+ */
+export declare const localStatus: (dir: string) => Promise<LocalRunStatus>;
+//# sourceMappingURL=index.d.ts.map

package/build/run/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/run/index.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAgB1B,MAAM,WAAW,eAAe;IAC9B,gGAAgG;IAChG,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,cAAc,GAAG,IAAI,CAAA;IAC7B;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,6FAA6F;IAC7F,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,EAAE;QACT,GAAG,CAAC,EAAE,kBAAkB,CAAA;QACxB,MAAM,CAAC,EAAE,kBAAkB,CAAA;QAC3B,GAAG,CAAC,EAAE,kBAAkB,CAAA;KACzB,CAAA;CACF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,QACd,MAAM,YAAW,eAAe,KACpC,OAAO,CAAC,cAAc,CA4DxB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,QAAe,MAAM,KAAG,OAAO,CAAC,IAAI,CAezD,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,QAAe,MAAM,KAAG,OAAO,CAAC,cAAc,CAyCrE,CAAA"}

package/build/run/index.js

@@ -0,0 +1,150 @@
+import fs from 'fs-extra';
+import p from 'node:path';
+import { SlotCommandType, SlotShellCommand, TARGET_API_PORT, TARGET_WEB_PORT, TARGET_WORKER_PORT } from '@owlmeans/viable-common';
+import { makeLocalSlotExecutor } from '../executor/index.js';
+import { readTargetHealth } from '../executor/health.js';
+import { integrityRefusal } from '../executor/integrity.js';
+import { apiPath, webPath } from '../executor/layout.js';
+import { isAlive } from '../executor/spawn.js';
+import { createLocalServer } from './serve.js';
+import { apiRunning, clearRun, readRun, startApi, startWorker, stopProcess, writeRun } from './state.js';
+export * from './state.js';
+export * from './serve.js';
+/**
+ * Run the generated application on the developer's own machine.
+ *
+ * The slot's equivalent is a pod: a publisher supervising two children and a static server, with
+ * Kubernetes underneath. None of that exists here, and the parts that were about the pod are
+ * deliberately not reproduced — there is no respawn ladder, no reconciler and no health route,
+ * because a developer watching their own terminal is the supervisor. What IS reproduced is the
+ * shape: the same ports, the same argv marker, the same environment, and the same "port ownership
+ * is the only proof" rule about restarts.
+ */
+/** Servers this process is holding, so a stop can close what a run opened. */
+const _servers = new Map();
+/**
+ * Build the target, start its processes, serve its browser app.
+ *
+ * A previous run is stopped first: both halves bind fixed ports, and a replacement that races the
+ * process it is replacing loses the bind and exits — with nothing announcing it, since a failed
+ * `listen` says nothing on its own.
+ */
+export const runLocal = async (dir, options = {}) => {
+    const root = p.resolve(dir);
+    const log = options.log ?? (() => undefined);
+    const ports = { api: TARGET_API_PORT, web: TARGET_WEB_PORT };
+    const refused = await integrityRefusal(root, 'Refused to run');
+    if (refused != null) {
+        return { record: null, ...ports, error: refused };
+    }
+    await stopLocal(root);
+    let buildError;
+    if (options.build !== false) {
+        log('Building the target project…');
+        const result = await makeLocalSlotExecutor(root, { log }).execute({
+            type: SlotCommandType.Shell, command: SlotShellCommand.Build,
+        });
+        if (result.result != null) {
+            buildError = result.result;
+        }
+    }
+    const record = { dir: root, startedAt: new Date().toISOString() };
+    // Only when the last build left something to spawn. Starting `bun dist/index.js` against a
+    // missing bundle fails with a message about a file rather than about the build that never
+    // produced it.
+    if (await fs.pathExists(p.resolve(apiPath(root), 'dist', 'index.js'))) {
+        record.api = await startApi(root);
+        log(`Target api started on port ${record.api.port}`);
+    }
+    else {
+        buildError ??= 'The target api has no build output — nothing was started.';
+    }
+    const worker = await startWorker(root);
+    if (worker != null) {
+        record.worker = worker;
+        log(`Target worker started on port ${worker.port}`);
+    }
+    const server = createLocalServer(() => p.resolve(webPath(root), 'dist'), { apiPort: TARGET_API_PORT });
+    await server.listen(TARGET_WEB_PORT);
+    _servers.set(root, server);
+    // The web server is this process, not a child: whoever called `runLocal` is holding it, and its
+    // pid is what a later `localStatus` from another process checks for liveness.
+    record.web = { pid: process.pid, port: TARGET_WEB_PORT };
+    log(`Target app served at http://localhost:${TARGET_WEB_PORT}`);
+    await writeRun(root, record);
+    return {
+        record,
+        ...ports,
+        ...(worker != null ? { worker: worker.port } : {}),
+        ...(buildError != null ? { buildError } : {}),
+    };
+};
+/**
+ * Stop whatever the run record names, and forget it.
+ *
+ * Safe to call when nothing is running: the record is the only authority, and a stale one names
+ * pids that are simply not alive. The children are detached, so they outlive the process that
+ * started them — which is exactly why the record is a file and this is the only way to end them.
+ */
+export const stopLocal = async (dir) => {
+    const root = p.resolve(dir);
+    const server = _servers.get(root);
+    if (server != null) {
+        _servers.delete(root);
+        await server.close();
+    }
+    const record = await readRun(root);
+    if (record == null)
+        return;
+    await stopProcess(record.worker);
+    await stopProcess(record.api);
+    await clearRun(root);
+};
+/**
+ * What is running, and whether the target is actually serving.
+ *
+ * Two independent facts, because either one alone lies. A live pid says nothing about a target
+ * that bound its port and then failed to reach its database — it answers `200` with `db.ok:false`
+ * and would otherwise read as healthy. A health answer says nothing about a process that died
+ * while something else holds the port.
+ */
+export const localStatus = async (dir) => {
+    const root = p.resolve(dir);
+    const record = await readRun(root);
+    if (record == null) {
+        return { running: false, processes: {} };
+    }
+    const status = {
+        running: apiRunning(record),
+        startedAt: record.startedAt,
+        processes: {},
+    };
+    if (record.api != null) {
+        const port = record.api.port ?? TARGET_API_PORT;
+        const health = await readTargetHealth(port, record.api.bootId ?? '', 2_000);
+        status.api = port;
+        status.ready = health.ready;
+        if (health.phase != null)
+            status.phase = health.phase;
+        if (!health.ready)
+            status.reason = health.reason;
+        status.processes.api = {
+            pid: record.api.pid, port, alive: isAlive(record.api.pid),
+        };
+    }
+    if (record.worker != null) {
+        const port = record.worker.port ?? TARGET_WORKER_PORT;
+        status.worker = port;
+        status.processes.worker = {
+            pid: record.worker.pid, port, alive: isAlive(record.worker.pid),
+        };
+    }
+    if (record.web != null) {
+        status.web = record.web.port;
+        status.processes.web = {
+            pid: record.web.pid, port: record.web.port, alive: isAlive(record.web.pid),
+        };
+    }
+    return status;
+};
+//# sourceMappingURL=index.js.map

package/build/run/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/run/index.ts"],"names":[],"mappings":"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"}

package/build/run/serve.d.ts

@@ -0,0 +1,18 @@
+export interface LocalServer {
+    listen: (port?: number, host?: string) => Promise<void>;
+    close: () => Promise<void>;
+    port: number;
+}
+export interface LocalServerOptions {
+    /** Where the target's api answers. The proxy target, not something the browser ever sees. */
+    apiPort?: number;
+}
+/**
+ * The static server, reading its directory per request.
+ *
+ * A getter and not a path, for the same reason every layout question here is a function: a
+ * re-initialization can move the web package under a running server, and a snapshot taken at
+ * construction would keep serving a directory that no longer exists.
+ */
+export declare const createLocalServer: (getWebDir: () => string, options?: LocalServerOptions) => LocalServer;
+//# sourceMappingURL=serve.d.ts.map

package/build/run/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/run/serve.ts"],"names":[],"mappings":"AAgDA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,kBAAkB;IACjC,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,cACjB,MAAM,MAAM,YAAW,kBAAkB,KACnD,WAiHF,CAAA"}

package/build/run/serve.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import http from 'node:http';
+import path from 'node:path';
+import { TARGET_API_BASE, TARGET_API_PORT, TARGET_WEB_PORT } from '@owlmeans/viable-common';
+/**
+ * Serve the target's built browser app, and put its `/api` behind the same origin.
+ *
+ * The slot does this with an HTTPRoute in front of two processes; a local run has no edge, so the
+ * proxy is what replaces it. It is not a convenience: the app and its API sharing one origin is
+ * what the generated app's own configuration assumes, and splitting them across two loopback ports
+ * would put the target's CORS setup in the path of a developer's first page load.
+ *
+ * Everything else the publisher's static server does — the crawler policy, the CSP, the preview
+ * error reporter, the build-state header — is about a PUBLIC hostname on a domain every customer
+ * shares. A loopback address has no reputation to spend and no crawler to answer, so none of it is
+ * reproduced here.
+ */
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.mjs': 'application/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+    '.webmanifest': 'application/manifest+json',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.txt': 'text/plain; charset=utf-8',
+};
+const PLACEHOLDER = '<!doctype html><html lang="en"><head><meta charset="UTF-8"/>'
+    + '<meta name="viewport" content="width=device-width, initial-scale=1.0"/>'
+    + '<title>Not built yet</title></head><body style="font-family:sans-serif">'
+    + '<p style="padding:2rem">This project has not been built yet. Run a build and reload.</p>'
+    + '</body></html>';
+/**
+ * The static server, reading its directory per request.
+ *
+ * A getter and not a path, for the same reason every layout question here is a function: a
+ * re-initialization can move the web package under a running server, and a snapshot taken at
+ * construction would keep serving a directory that no longer exists.
+ */
+export const createLocalServer = (getWebDir, options = {}) => {
+    const apiPort = options.apiPort ?? TARGET_API_PORT;
+    const apiPrefix = `/${TARGET_API_BASE}`;
+    let server = null;
+    let port = TARGET_WEB_PORT;
+    const proxy = (req, res) => {
+        const upstream = http.request({
+            host: '127.0.0.1',
+            port: apiPort,
+            method: req.method,
+            path: req.url,
+            headers: { ...req.headers, host: `127.0.0.1:${apiPort}` },
+        }, answer => {
+            res.writeHead(answer.statusCode ?? 502, answer.headers);
+            answer.pipe(res);
+        });
+        // The api is a supervised child, so it is legitimately absent between a stop and a start. Say
+        // which of the two processes failed — an unexplained 502 here reads as a bug in the app.
+        upstream.on('error', error => {
+            if (res.headersSent) {
+                return res.destroy();
+            }
+            res.writeHead(502, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(JSON.stringify({
+                error: `The target backend is not answering on port ${apiPort}: ${String(error)}`,
+            }));
+        });
+        req.pipe(upstream);
+    };
+    const serveFile = async (res, file, status = 200) => {
+        const body = await fsp.readFile(file).catch(() => null);
+        if (body == null)
+            return false;
+        res.writeHead(status, {
+            'Content-Type': MIME[path.extname(file).toLowerCase()] ?? 'application/octet-stream',
+            // A local build is rewritten constantly and served under stable, unhashed names
+            // (`/bundle.js`), so a cached copy is always the previous build wearing the current URL.
+            'Cache-Control': 'no-store',
+            'Content-Length': body.byteLength,
+        });
+        res.end(body);
+        return true;
+    };
+    const handle = async (req, res) => {
+        const url = req.url ?? '/';
+        if (url === apiPrefix || url.startsWith(`${apiPrefix}/`)) {
+            return proxy(req, res);
+        }
+        const dir = getWebDir();
+        const pathname = decodeURIComponent(url.split('?')[0]);
+        const resolved = path.resolve(dir, `.${path.posix.normalize(pathname)}`);
+        // Confinement, exactly as on the file side: a resolved path is the only one that can be
+        // compared to the root, and this server answers requests from a browser.
+        if (resolved !== dir && !resolved.startsWith(`${dir}${path.sep}`)) {
+            res.writeHead(403);
+            res.end();
+            return;
+        }
+        if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) {
+            if (await serveFile(res, resolved))
+                return;
+        }
+        // Client-side routing: any path the build did not emit a file for is a route inside the app.
+        const index = path.join(dir, 'index.html');
+        if (await serveFile(res, index))
+            return;
+        res.writeHead(200, { 'Content-Type': MIME['.html'], 'Cache-Control': 'no-store' });
+        res.end(PLACEHOLDER);
+    };
+    return {
+        listen: async (listenPort = TARGET_WEB_PORT, host = '127.0.0.1') => {
+            port = listenPort;
+            server = http.createServer((req, res) => {
+                void handle(req, res).catch(error => {
+                    if (res.headersSent) {
+                        res.destroy();
+                        return;
+                    }
+                    res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+                    res.end(String(error));
+                });
+            });
+            await new Promise((resolve, reject) => {
+                server?.once('error', reject);
+                server?.listen(listenPort, host, () => resolve());
+            });
+        },
+        close: async () => {
+            const current = server;
+            server = null;
+            if (current == null)
+                return;
+            await new Promise(resolve => current.close(() => resolve()));
+        },
+        get port() { return port; },
+    };
+};
+//# sourceMappingURL=serve.js.map

package/build/run/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../src/run/serve.ts"],"names":[],"mappings":"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"}