@scenar/cli 0.1.20-rc.1 → 0.2.0

package/src/serve/request-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-path.d.ts","sourceRoot":"","sources":["../../../src/serve/request-path.ts"],"names":[],"mappings":"AAEA,2EAA2E;AAC3E,eAAO,MAAM,UAAU,eAAe,CAAC;AAEvC,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAE/D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAyBhE;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAG3D"}

package/src/serve/request-path.js

@@ -0,0 +1,52 @@
+import { CONTENT_TYPE_BY_EXTENSION, finalExtension } from "../pack/bundle-contract.js";
+/** File served for a directory request ("/" or any path ending in "/"). */
+export const INDEX_FILE = "index.html";
+/** Content type for an extension the bundle contract does not recognise. */
+export const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+/**
+ * Resolve an incoming request URL path to a clean, bundle-relative file path —
+ * or null if the request is malformed or attempts to escape the bundle root.
+ *
+ * Pure: no filesystem access. The caller maps the returned relative path onto
+ * disk (and 404s if the file is absent). This is the security-critical core of
+ * the local server, so it is isolated and exhaustively unit-tested:
+ *   - percent-decoding (rejecting malformed encodings),
+ *   - directory requests mapped to {@link INDEX_FILE},
+ *   - rejection of "", ".", ".." segments and backslash/NUL injection.
+ *
+ * A defence-in-depth absolute-path containment check still runs in the server
+ * after this resolves, but this function alone must never yield a traversing
+ * path.
+ */
+export function resolveStaticPath(urlPath) {
+    // Keep only the path; drop any query string or fragment defensively.
+    const pathOnly = urlPath.split(/[?#]/, 1)[0] ?? "";
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pathOnly);
+    }
+    catch {
+        return null; // malformed percent-encoding
+    }
+    // Requests are absolute-path form; reject separator/NUL injection outright.
+    if (!decoded.startsWith("/"))
+        return null;
+    if (decoded.includes("\0") || decoded.includes("\\"))
+        return null;
+    // A directory request ("/" or trailing slash) serves the index document.
+    const withIndex = decoded === "/" || decoded.endsWith("/") ? decoded + INDEX_FILE : decoded;
+    const segments = withIndex.replace(/^\/+/, "").split("/");
+    for (const segment of segments) {
+        // Empty (double-slash), current-dir, and parent-dir segments are all
+        // rejected: the charset is otherwise permissive and "." is a valid char.
+        if (segment === "" || segment === "." || segment === "..")
+            return null;
+    }
+    return segments.join("/");
+}
+/** Canonical content type for a bundle file path, keyed on its final extension. */
+export function contentTypeFor(relativePath) {
+    const ext = finalExtension(relativePath);
+    return CONTENT_TYPE_BY_EXTENSION[ext] ?? DEFAULT_CONTENT_TYPE;
+}
+//# sourceMappingURL=request-path.js.map

package/src/serve/request-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-path.js","sourceRoot":"","sources":["../../../src/serve/request-path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEvF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC;AAEvC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAE/D;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,qEAAqE;IACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAEnD,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,CAAC,6BAA6B;IAC5C,CAAC;IAED,4EAA4E;IAC5E,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAElE,yEAAyE;IACzE,MAAM,SAAS,GAAG,OAAO,KAAK,GAAG,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC;IAE5F,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1D,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,qEAAqE;QACrE,yEAAyE;QACzE,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;IACzE,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,YAAoB;IACjD,MAAM,GAAG,GAAG,cAAc,CAAC,YAAY,CAA2C,CAAC;IACnF,OAAO,yBAAyB,CAAC,GAAG,CAAC,IAAI,oBAAoB,CAAC;AAChE,CAAC"}

package/src/serve/request-path.ts

@@ -0,0 +1,55 @@
+import { CONTENT_TYPE_BY_EXTENSION, finalExtension } from "../pack/bundle-contract.js";
+
+/** File served for a directory request ("/" or any path ending in "/"). */
+export const INDEX_FILE = "index.html";
+
+/** Content type for an extension the bundle contract does not recognise. */
+export const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+
+/**
+ * Resolve an incoming request URL path to a clean, bundle-relative file path —
+ * or null if the request is malformed or attempts to escape the bundle root.
+ *
+ * Pure: no filesystem access. The caller maps the returned relative path onto
+ * disk (and 404s if the file is absent). This is the security-critical core of
+ * the local server, so it is isolated and exhaustively unit-tested:
+ *   - percent-decoding (rejecting malformed encodings),
+ *   - directory requests mapped to {@link INDEX_FILE},
+ *   - rejection of "", ".", ".." segments and backslash/NUL injection.
+ *
+ * A defence-in-depth absolute-path containment check still runs in the server
+ * after this resolves, but this function alone must never yield a traversing
+ * path.
+ */
+export function resolveStaticPath(urlPath: string): string | null {
+  // Keep only the path; drop any query string or fragment defensively.
+  const pathOnly = urlPath.split(/[?#]/, 1)[0] ?? "";
+
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathOnly);
+  } catch {
+    return null; // malformed percent-encoding
+  }
+
+  // Requests are absolute-path form; reject separator/NUL injection outright.
+  if (!decoded.startsWith("/")) return null;
+  if (decoded.includes("\0") || decoded.includes("\\")) return null;
+
+  // A directory request ("/" or trailing slash) serves the index document.
+  const withIndex = decoded === "/" || decoded.endsWith("/") ? decoded + INDEX_FILE : decoded;
+
+  const segments = withIndex.replace(/^\/+/, "").split("/");
+  for (const segment of segments) {
+    // Empty (double-slash), current-dir, and parent-dir segments are all
+    // rejected: the charset is otherwise permissive and "." is a valid char.
+    if (segment === "" || segment === "." || segment === "..") return null;
+  }
+  return segments.join("/");
+}
+
+/** Canonical content type for a bundle file path, keyed on its final extension. */
+export function contentTypeFor(relativePath: string): string {
+  const ext = finalExtension(relativePath) as keyof typeof CONTENT_TYPE_BY_EXTENSION;
+  return CONTENT_TYPE_BY_EXTENSION[ext] ?? DEFAULT_CONTENT_TYPE;
+}

package/src/serve/run-serve.d.ts

@@ -0,0 +1,31 @@
+import type { Viewport } from "../pack/viewport.js";
+import { type BundleServerHandle } from "./static-server.js";
+/** Options for {@link runServe}. */
+export interface RunServeOptions {
+    readonly bundleDir: string;
+    /** Port to bind; 0 lets the OS choose a free one. */
+    readonly port: number;
+    /** Host/interface to bind (default: localhost). */
+    readonly host?: string;
+}
+/** A running preview server plus the derived presentation details. */
+export interface ServeResult {
+    /** The running server (call .close() to stop). */
+    readonly handle: BundleServerHandle;
+    /** The browser-clickable URL (https→http downgraded for *.localhost). */
+    readonly url: string;
+    /** A ready-to-paste responsive <iframe> snippet for this URL. */
+    readonly snippet: string;
+    /** The viewport used for the snippet (recorded, or the default). */
+    readonly viewport: Viewport;
+    /** Whether the snippet's viewport came from the bundle (vs. the default). */
+    readonly recordedViewport: boolean;
+}
+/**
+ * Validate a packed bundle directory and start serving it — the orchestration
+ * behind `scenar serve`, with no process/exit coupling so both the CLI command
+ * and the MCP server can call it. The returned handle keeps running until the
+ * caller closes it. Throws on an invalid bundle or an unavailable port.
+ */
+export declare function runServe(options: RunServeOptions): Promise<ServeResult>;
+//# sourceMappingURL=run-serve.d.ts.map

package/src/serve/run-serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-serve.d.ts","sourceRoot":"","sources":["../../../src/serve/run-serve.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAKhF,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CA2B7E"}

package/src/serve/run-serve.js

@@ -0,0 +1,35 @@
+import { resolve, join } from "node:path";
+import { stat } from "node:fs/promises";
+import { buildEmbedSnippet } from "../deploy/embed-snippet.js";
+import { localViewUrl } from "../deploy/deploy-flow.js";
+import { readBundleViewport } from "../bundle/read-viewport.js";
+import { startBundleServer } from "./static-server.js";
+/** The servable entry every packed bundle contains at its root. */
+const INDEX_FILE = "index.html";
+/**
+ * Validate a packed bundle directory and start serving it — the orchestration
+ * behind `scenar serve`, with no process/exit coupling so both the CLI command
+ * and the MCP server can call it. The returned handle keeps running until the
+ * caller closes it. Throws on an invalid bundle or an unavailable port.
+ */
+export async function runServe(options) {
+    const resolvedDir = resolve(options.bundleDir);
+    const info = await stat(resolvedDir).catch(() => null);
+    if (!info || !info.isDirectory()) {
+        throw new Error(`${options.bundleDir} is not a directory. Pass a bundle produced by \`scenar pack\`.`);
+    }
+    const indexInfo = await stat(join(resolvedDir, INDEX_FILE)).catch(() => null);
+    if (!indexInfo || !indexInfo.isFile()) {
+        throw new Error(`no ${INDEX_FILE} in ${options.bundleDir}. Run \`scenar pack\` to produce a servable bundle first.`);
+    }
+    const handle = await startBundleServer({
+        rootDir: resolvedDir,
+        port: options.port,
+        host: options.host,
+    });
+    const url = localViewUrl(handle.url);
+    const { viewport, recorded } = await readBundleViewport(resolvedDir);
+    const snippet = buildEmbedSnippet({ embedUrl: url, viewport });
+    return { handle, url, snippet, viewport, recordedViewport: recorded };
+}
+//# sourceMappingURL=run-serve.js.map

package/src/serve/run-serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-serve.js","sourceRoot":"","sources":["../../../src/serve/run-serve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAA2B,MAAM,oBAAoB,CAAC;AAEhF,mEAAmE;AACnE,MAAM,UAAU,GAAG,YAAY,CAAC;AAyBhC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAwB;IACrD,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAE/C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IACvD,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,GAAG,OAAO,CAAC,SAAS,iEAAiE,CACtF,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAC9E,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACb,MAAM,UAAU,OAAO,OAAO,CAAC,SAAS,2DAA2D,CACpG,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC;QACrC,OAAO,EAAE,WAAW;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;KACnB,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,MAAM,kBAAkB,CAAC,WAAW,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,iBAAiB,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IAE/D,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,CAAC;AACxE,CAAC"}

package/src/serve/run-serve.ts

@@ -0,0 +1,68 @@
+import { resolve, join } from "node:path";
+import { stat } from "node:fs/promises";
+import { buildEmbedSnippet } from "../deploy/embed-snippet.js";
+import { localViewUrl } from "../deploy/deploy-flow.js";
+import { readBundleViewport } from "../bundle/read-viewport.js";
+import type { Viewport } from "../pack/viewport.js";
+import { startBundleServer, type BundleServerHandle } from "./static-server.js";
+
+/** The servable entry every packed bundle contains at its root. */
+const INDEX_FILE = "index.html";
+
+/** Options for {@link runServe}. */
+export interface RunServeOptions {
+  readonly bundleDir: string;
+  /** Port to bind; 0 lets the OS choose a free one. */
+  readonly port: number;
+  /** Host/interface to bind (default: localhost). */
+  readonly host?: string;
+}
+
+/** A running preview server plus the derived presentation details. */
+export interface ServeResult {
+  /** The running server (call .close() to stop). */
+  readonly handle: BundleServerHandle;
+  /** The browser-clickable URL (https→http downgraded for *.localhost). */
+  readonly url: string;
+  /** A ready-to-paste responsive <iframe> snippet for this URL. */
+  readonly snippet: string;
+  /** The viewport used for the snippet (recorded, or the default). */
+  readonly viewport: Viewport;
+  /** Whether the snippet's viewport came from the bundle (vs. the default). */
+  readonly recordedViewport: boolean;
+}
+
+/**
+ * Validate a packed bundle directory and start serving it — the orchestration
+ * behind `scenar serve`, with no process/exit coupling so both the CLI command
+ * and the MCP server can call it. The returned handle keeps running until the
+ * caller closes it. Throws on an invalid bundle or an unavailable port.
+ */
+export async function runServe(options: RunServeOptions): Promise<ServeResult> {
+  const resolvedDir = resolve(options.bundleDir);
+
+  const info = await stat(resolvedDir).catch(() => null);
+  if (!info || !info.isDirectory()) {
+    throw new Error(
+      `${options.bundleDir} is not a directory. Pass a bundle produced by \`scenar pack\`.`,
+    );
+  }
+  const indexInfo = await stat(join(resolvedDir, INDEX_FILE)).catch(() => null);
+  if (!indexInfo || !indexInfo.isFile()) {
+    throw new Error(
+      `no ${INDEX_FILE} in ${options.bundleDir}. Run \`scenar pack\` to produce a servable bundle first.`,
+    );
+  }
+
+  const handle = await startBundleServer({
+    rootDir: resolvedDir,
+    port: options.port,
+    host: options.host,
+  });
+
+  const url = localViewUrl(handle.url);
+  const { viewport, recorded } = await readBundleViewport(resolvedDir);
+  const snippet = buildEmbedSnippet({ embedUrl: url, viewport });
+
+  return { handle, url, snippet, viewport, recordedViewport: recorded };
+}

package/src/serve/static-server.d.ts

@@ -0,0 +1,38 @@
+import { type Server } from "node:http";
+/** A running bundle server: where it is reachable and how to stop it. */
+export interface BundleServerHandle {
+    /** The base URL the bundle is served at (e.g. http://localhost:4173/). */
+    readonly url: string;
+    /** The port the server actually bound (useful when port 0 was requested). */
+    readonly port: number;
+    /** Stop accepting connections and release the port. */
+    close(): Promise<void>;
+}
+/** Options for {@link startBundleServer}. */
+export interface StartBundleServerOptions {
+    /** Bundle directory to serve (a `scenar pack` output). */
+    readonly rootDir: string;
+    /** Port to bind; 0 lets the OS pick a free one (handy in tests). */
+    readonly port: number;
+    /** Host/interface to bind. Defaults to "localhost". */
+    readonly host?: string;
+}
+/**
+ * Create (but do not start) an HTTP server that serves a packed bundle as a
+ * static site. Only GET/HEAD are allowed; every response carries the bundle
+ * contract's canonical content type and `Cache-Control: no-cache` (a local
+ * preview should always reflect the latest pack, never a stale asset).
+ *
+ * No CSP or other security headers are emitted: that envelope is the serving
+ * edge's responsibility (and is enforced + tested in scenar-cloud). A local
+ * preview deliberately matches the headerless behaviour of a plain static host
+ * such as GitHub Pages — the other Phase 1 target — so what you see locally is
+ * what a `scenar publish` visitor sees.
+ */
+export declare function createBundleServer(rootDir: string): Server;
+/**
+ * Start an HTTP server for a packed bundle and resolve once it is listening.
+ * Rejects if the port is already in use (the caller surfaces a clear message).
+ */
+export declare function startBundleServer(options: StartBundleServerOptions): Promise<BundleServerHandle>;
+//# sourceMappingURL=static-server.d.ts.map

package/src/serve/static-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-server.d.ts","sourceRoot":"","sources":["../../../src/serve/static-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAMjG,yEAAyE;AACzE,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ1D;AA4CD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAuBhG"}

package/src/serve/static-server.js

@@ -0,0 +1,91 @@
+import { createServer } from "node:http";
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+import { contentTypeFor, resolveStaticPath } from "./request-path.js";
+/**
+ * Create (but do not start) an HTTP server that serves a packed bundle as a
+ * static site. Only GET/HEAD are allowed; every response carries the bundle
+ * contract's canonical content type and `Cache-Control: no-cache` (a local
+ * preview should always reflect the latest pack, never a stale asset).
+ *
+ * No CSP or other security headers are emitted: that envelope is the serving
+ * edge's responsibility (and is enforced + tested in scenar-cloud). A local
+ * preview deliberately matches the headerless behaviour of a plain static host
+ * such as GitHub Pages — the other Phase 1 target — so what you see locally is
+ * what a `scenar publish` visitor sees.
+ */
+export function createBundleServer(rootDir) {
+    const root = resolve(rootDir);
+    return createServer((req, res) => {
+        void serveRequest(root, req, res).catch(() => {
+            if (!res.headersSent)
+                res.writeHead(500, { "content-type": "text/plain" });
+            res.end("Internal Server Error");
+        });
+    });
+}
+async function serveRequest(root, req, res) {
+    if (req.method !== "GET" && req.method !== "HEAD") {
+        res.writeHead(405, { allow: "GET, HEAD", "content-type": "text/plain" });
+        res.end("Method Not Allowed");
+        return;
+    }
+    const relativePath = resolveStaticPath(req.url ?? "/");
+    if (relativePath === null) {
+        res.writeHead(400, { "content-type": "text/plain" });
+        res.end("Bad Request");
+        return;
+    }
+    const absolutePath = resolve(root, relativePath);
+    // Defence in depth: the resolved path must stay within the bundle root even
+    // if resolveStaticPath ever let something through.
+    if (absolutePath !== root && !absolutePath.startsWith(root + sep)) {
+        res.writeHead(403, { "content-type": "text/plain" });
+        res.end("Forbidden");
+        return;
+    }
+    const info = await stat(absolutePath).catch(() => null);
+    if (!info || !info.isFile()) {
+        res.writeHead(404, { "content-type": "text/plain" });
+        res.end("Not Found");
+        return;
+    }
+    res.writeHead(200, {
+        "content-type": contentTypeFor(relativePath),
+        "content-length": info.size,
+        "cache-control": "no-cache",
+    });
+    if (req.method === "HEAD") {
+        res.end();
+        return;
+    }
+    createReadStream(absolutePath).pipe(res);
+}
+/**
+ * Start an HTTP server for a packed bundle and resolve once it is listening.
+ * Rejects if the port is already in use (the caller surfaces a clear message).
+ */
+export function startBundleServer(options) {
+    const host = options.host ?? "localhost";
+    const server = createBundleServer(options.rootDir);
+    return new Promise((resolvePromise, reject) => {
+        const onError = (error) => reject(error);
+        server.once("error", onError);
+        server.listen(options.port, host, () => {
+            server.removeListener("error", onError);
+            const address = server.address();
+            const port = typeof address === "object" && address ? address.port : options.port;
+            // Wildcard binds are not dialable hostnames; advertise localhost instead.
+            const displayHost = host === "0.0.0.0" || host === "::" ? "localhost" : host;
+            resolvePromise({
+                url: `http://${displayHost}:${port}/`,
+                port,
+                close: () => new Promise((done, fail) => {
+                    server.close((err) => (err ? fail(err) : done()));
+                }),
+            });
+        });
+    });
+}
+//# sourceMappingURL=static-server.js.map

package/src/serve/static-server.js.map

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

package/src/serve/static-server.ts

@@ -0,0 +1,118 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+import { contentTypeFor, resolveStaticPath } from "./request-path.js";
+
+/** A running bundle server: where it is reachable and how to stop it. */
+export interface BundleServerHandle {
+  /** The base URL the bundle is served at (e.g. http://localhost:4173/). */
+  readonly url: string;
+  /** The port the server actually bound (useful when port 0 was requested). */
+  readonly port: number;
+  /** Stop accepting connections and release the port. */
+  close(): Promise<void>;
+}
+
+/** Options for {@link startBundleServer}. */
+export interface StartBundleServerOptions {
+  /** Bundle directory to serve (a `scenar pack` output). */
+  readonly rootDir: string;
+  /** Port to bind; 0 lets the OS pick a free one (handy in tests). */
+  readonly port: number;
+  /** Host/interface to bind. Defaults to "localhost". */
+  readonly host?: string;
+}
+
+/**
+ * Create (but do not start) an HTTP server that serves a packed bundle as a
+ * static site. Only GET/HEAD are allowed; every response carries the bundle
+ * contract's canonical content type and `Cache-Control: no-cache` (a local
+ * preview should always reflect the latest pack, never a stale asset).
+ *
+ * No CSP or other security headers are emitted: that envelope is the serving
+ * edge's responsibility (and is enforced + tested in scenar-cloud). A local
+ * preview deliberately matches the headerless behaviour of a plain static host
+ * such as GitHub Pages — the other Phase 1 target — so what you see locally is
+ * what a `scenar publish` visitor sees.
+ */
+export function createBundleServer(rootDir: string): Server {
+  const root = resolve(rootDir);
+  return createServer((req, res) => {
+    void serveRequest(root, req, res).catch(() => {
+      if (!res.headersSent) res.writeHead(500, { "content-type": "text/plain" });
+      res.end("Internal Server Error");
+    });
+  });
+}
+
+async function serveRequest(root: string, req: IncomingMessage, res: ServerResponse): Promise<void> {
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    res.writeHead(405, { allow: "GET, HEAD", "content-type": "text/plain" });
+    res.end("Method Not Allowed");
+    return;
+  }
+
+  const relativePath = resolveStaticPath(req.url ?? "/");
+  if (relativePath === null) {
+    res.writeHead(400, { "content-type": "text/plain" });
+    res.end("Bad Request");
+    return;
+  }
+
+  const absolutePath = resolve(root, relativePath);
+  // Defence in depth: the resolved path must stay within the bundle root even
+  // if resolveStaticPath ever let something through.
+  if (absolutePath !== root && !absolutePath.startsWith(root + sep)) {
+    res.writeHead(403, { "content-type": "text/plain" });
+    res.end("Forbidden");
+    return;
+  }
+
+  const info = await stat(absolutePath).catch(() => null);
+  if (!info || !info.isFile()) {
+    res.writeHead(404, { "content-type": "text/plain" });
+    res.end("Not Found");
+    return;
+  }
+
+  res.writeHead(200, {
+    "content-type": contentTypeFor(relativePath),
+    "content-length": info.size,
+    "cache-control": "no-cache",
+  });
+  if (req.method === "HEAD") {
+    res.end();
+    return;
+  }
+  createReadStream(absolutePath).pipe(res);
+}
+
+/**
+ * Start an HTTP server for a packed bundle and resolve once it is listening.
+ * Rejects if the port is already in use (the caller surfaces a clear message).
+ */
+export function startBundleServer(options: StartBundleServerOptions): Promise<BundleServerHandle> {
+  const host = options.host ?? "localhost";
+  const server = createBundleServer(options.rootDir);
+
+  return new Promise<BundleServerHandle>((resolvePromise, reject) => {
+    const onError = (error: Error) => reject(error);
+    server.once("error", onError);
+    server.listen(options.port, host, () => {
+      server.removeListener("error", onError);
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : options.port;
+      // Wildcard binds are not dialable hostnames; advertise localhost instead.
+      const displayHost = host === "0.0.0.0" || host === "::" ? "localhost" : host;
+      resolvePromise({
+        url: `http://${displayHost}:${port}/`,
+        port,
+        close: () =>
+          new Promise<void>((done, fail) => {
+            server.close((err) => (err ? fail(err) : done()));
+          }),
+      });
+    });
+  });
+}