@stigmer/server 3.14.0-dev.20260910084630

package/src/transport/console/__tests__/nginx-equivalence.test.ts

@@ -0,0 +1,144 @@
+/**
+ * The one-contract gate: proves the console resolver serves every real
+ * route to the SAME document as the nginx model in
+ * scripts/verify-static-export-routes.mjs — the module that already holds
+ * nginx.conf and the App Router route tree together in CI. With this test
+ * in the server suite, the repo's two serving implementations (the cloud
+ * nginx config and this server's lane 4) cannot drift apart silently: a
+ * new route, a changed nginx rule, or a resolver edit that lands them on
+ * different documents fails here by name.
+ *
+ * Hermetic by construction: the export file set is SYNTHESIZED from the
+ * enumerated routes via the gate's own exportFileOf (each page's .html
+ * plus its .txt flight twin plus /404.html — the gate's out-less mode),
+ * so this test never needs a built client-apps/web/out.
+ *
+ * The RSC flight arms assert against the derived twins directly (the
+ * nginx model is NOT the oracle there: nginx never handled flight
+ * rewrites — the disclosed cloud-side gap this lane deliberately fixes).
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import {
+  buildServerModel,
+  enumerateRoutes,
+  exportFileOf,
+  parseNginxConfig,
+  representativeUrlOf,
+  resolveRequest,
+} from "../../../../../../../scripts/verify-static-export-routes.mjs";
+import { buildConsoleFileIndex, resolveConsoleRequest } from "../resolver.js";
+
+const repoRoot = new URL("../../../../../../../", import.meta.url);
+const webAppDir = fileURLToPath(new URL("client-apps/web/src/app", repoRoot));
+const nginxConfPath = fileURLToPath(
+  new URL("client-apps/web/nginx.conf", repoRoot),
+);
+
+const routes = enumerateRoutes(webAppDir);
+const model = buildServerModel(
+  parseNginxConfig(readFileSync(nginxConfPath, "utf8")),
+);
+
+// The gate's own synthesis (verifyRoutes): every page's .html, its .txt
+// flight twin, and the export's always-emitted 404 document.
+const files = new Set<string>();
+for (const route of routes) {
+  const html = exportFileOf(route);
+  files.add(html);
+  files.add(html.replace(/\.html$/, ".txt"));
+}
+if (model.errorPage) {
+  files.add(model.errorPage.uri);
+}
+const index = buildConsoleFileIndex(files);
+
+/**
+ * The document the TS resolver ultimately serves for a URL: redirects are
+ * followed (the browser re-requests), notFound maps to the error page —
+ * the same terminal-document view resolveRequest answers for nginx.
+ */
+function tsResolverDocumentOf(url: string): string | null {
+  let pathname = url;
+  for (let hop = 0; hop < 6; hop++) {
+    const resolution = resolveConsoleRequest(pathname, index);
+    switch (resolution.kind) {
+      case "file":
+        return resolution.file;
+      case "redirect":
+        pathname = resolution.location;
+        continue;
+      case "notFound":
+        return model.errorPage?.uri ?? null;
+      default: {
+        const exhaustive: never = resolution;
+        throw new Error(`unhandled resolution ${String(exhaustive)}`);
+      }
+    }
+  }
+  throw new Error(`redirect loop resolving "${url}"`);
+}
+
+describe("console resolver ≡ nginx model (the route-tree equivalence)", () => {
+  it("enumerated a non-trivial route tree", () => {
+    expect(routes.length).toBeGreaterThan(10);
+    expect(routes.some((route) => route.segments.some((s) => s.dynamic))).toBe(
+      true,
+    );
+  });
+
+  it("serves every route's representative URL to the same document as nginx", () => {
+    for (const route of routes) {
+      const url = representativeUrlOf(route);
+      const nginxDocument = resolveRequest(model, url, files);
+      expect(tsResolverDocumentOf(url), `route ${route.url} (${url})`).toBe(
+        nginxDocument,
+      );
+      // And both must be the route's own export — anything else is the
+      // blank-page class the gate exists to prevent.
+      expect(nginxDocument, `route ${route.url} (${url})`).toBe(
+        exportFileOf(route),
+      );
+    }
+  });
+
+  it("canonicalizes trailing slashes to the same document as nginx", () => {
+    for (const route of routes) {
+      if (route.segments.length === 0) continue; // "/" has no slashless twin
+      const url = `${representativeUrlOf(route)}/`;
+      expect(tsResolverDocumentOf(url), `route ${route.url} (${url})`).toBe(
+        resolveRequest(model, url, files),
+      );
+    }
+  });
+
+  it("lands unknown URLs on the error document, like nginx, never the app shell", () => {
+    for (const url of [
+      "/zz-no-such-route",
+      "/zz-no/zz-such",
+      "/zz-no/zz-such/zz-route",
+      "/zz-no/zz-such/zz-route/zz-deep",
+    ]) {
+      const nginxDocument = resolveRequest(model, url, files);
+      expect(nginxDocument, url).not.toBe("/index.html");
+      expect(tsResolverDocumentOf(url), url).toBe(nginxDocument);
+    }
+  });
+});
+
+describe("RSC flight payloads across the whole route tree", () => {
+  it("serves every route's flight request its export's .txt twin", () => {
+    for (const route of routes) {
+      if (route.segments.length === 0) continue; // the root's payloads are literal __next.* files
+      const url = `${representativeUrlOf(route)}.txt`;
+      const expected = exportFileOf(route).replace(/\.html$/, ".txt");
+      const resolution = resolveConsoleRequest(url, index);
+      expect(
+        resolution.kind === "file" ? resolution.file : resolution.kind,
+        `route ${route.url} (${url})`,
+      ).toBe(expected);
+    }
+  });
+});

package/src/transport/console/__tests__/resolver.test.ts

@@ -0,0 +1,181 @@
+/**
+ * Pins the console resolver's two contracts against a realistic export
+ * shape (the file inventory mirrors client-apps/web/out):
+ *
+ *   - the PAGE contract: nginx.conf's try_files chain — literal, .html
+ *     sibling, directory index, placeholder candidates most-literal-first,
+ *     trailing-slash canonicalization, 404 posture (the full route-tree
+ *     equivalence against the parsed nginx model lives in
+ *     nginx-equivalence.test.ts; these arms pin the semantics readably);
+ *   - the RSC FLIGHT contract: the retired Go handler's `.txt` rewrites
+ *     (page-level twins and nested `__next.*.txt` payloads), including the
+ *     two-dynamic-segment routes the Go handler's single-substitution
+ *     loop could not resolve.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  buildConsoleFileIndex,
+  resolveConsoleRequest,
+  type ConsoleResolution,
+} from "../resolver.js";
+
+// The realistic export inventory: static pages, one- and two-dynamic-
+// segment routes, a literal-beats-dynamic sibling pair under /workflows,
+// root-level RSC payloads, and build assets.
+const index = buildConsoleFileIndex([
+  "/index.html",
+  "/index.txt",
+  "/404.html",
+  "/embed.js",
+  "/Icon-bw.svg",
+  "/__next._tree.txt",
+  "/conversations.html",
+  "/conversations.txt",
+  "/auth/github/callback.html",
+  "/sessions/__placeholder__.html",
+  "/sessions/__placeholder__.txt",
+  "/sessions/__placeholder__/__next.sessions.txt",
+  "/workflows/executions/__placeholder__.html",
+  "/workflows/executions/__placeholder__.txt",
+  "/workflows/__placeholder__/__placeholder__.html",
+  "/workflows/__placeholder__/__placeholder__.txt",
+  "/workflows/__placeholder__/__placeholder__/__next.workflows.txt",
+  "/_next/static/chunks/app-1a2b3c.js",
+]);
+
+function resolve(pathname: string): ConsoleResolution {
+  return resolveConsoleRequest(pathname, index);
+}
+
+function servedFile(pathname: string): string | null {
+  const resolution = resolve(pathname);
+  return resolution.kind === "file" ? resolution.file : null;
+}
+
+describe("page contract (the nginx chain)", () => {
+  it("serves the root route through the directory index", () => {
+    expect(servedFile("/")).toBe("/index.html");
+  });
+
+  it("serves literal files directly", () => {
+    expect(servedFile("/embed.js")).toBe("/embed.js");
+    expect(servedFile("/Icon-bw.svg")).toBe("/Icon-bw.svg");
+    expect(servedFile("/404.html")).toBe("/404.html");
+  });
+
+  it("serves static routes via the .html sibling", () => {
+    expect(servedFile("/conversations")).toBe("/conversations.html");
+    expect(servedFile("/auth/github/callback")).toBe(
+      "/auth/github/callback.html",
+    );
+  });
+
+  it("resolves one trailing dynamic segment to its placeholder document", () => {
+    expect(servedFile("/sessions/ses_abc123")).toBe(
+      "/sessions/__placeholder__.html",
+    );
+  });
+
+  it("prefers the more-literal candidate: a literal segment beats a dynamic one", () => {
+    // /workflows/executions/[id] and /workflows/[org]/[slug] are both
+    // three segments — the filesystem, not the segment count, decides
+    // (the F-12 lesson nginx.conf documents).
+    expect(servedFile("/workflows/executions/wfe_123")).toBe(
+      "/workflows/executions/__placeholder__.html",
+    );
+    expect(servedFile("/workflows/acme/my-flow")).toBe(
+      "/workflows/__placeholder__/__placeholder__.html",
+    );
+  });
+
+  it("serves a literal placeholder request through the .html sibling", () => {
+    expect(servedFile("/sessions/__placeholder__")).toBe(
+      "/sessions/__placeholder__.html",
+    );
+  });
+
+  it("301s trailing slashes to the canonical URL, one strip per hop", () => {
+    expect(resolve("/conversations/")).toEqual({
+      kind: "redirect",
+      location: "/conversations",
+    });
+    // nginx's ^(.+)/$ strips exactly one slash; the client walks the rest.
+    expect(resolve("/conversations//")).toEqual({
+      kind: "redirect",
+      location: "/conversations/",
+    });
+    // "/" has no slashless twin and never redirects.
+    expect(resolve("/").kind).toBe("file");
+  });
+
+  it("answers notFound for unknown URLs at every depth", () => {
+    expect(resolve("/zz-no-such-route").kind).toBe("notFound");
+    expect(resolve("/zz-no/zz-such/zz-route/zz-deep").kind).toBe("notFound");
+    // Two placeholder candidates are exhaustive: three trailing dynamic
+    // segments cannot resolve (MAX_DYNAMIC_SEGMENTS in the routing gate).
+    expect(resolve("/workflows/a/b/c").kind).toBe("notFound");
+  });
+
+  it("never resolves top-level paths through placeholders", () => {
+    // The nginx regexes require a non-empty static prefix.
+    expect(resolve("/ses_abc123").kind).toBe("notFound");
+  });
+
+  it("serves /_next/ assets literally and nothing else", () => {
+    expect(servedFile("/_next/static/chunks/app-1a2b3c.js")).toBe(
+      "/_next/static/chunks/app-1a2b3c.js",
+    );
+    expect(resolve("/_next/static/chunks/missing.js").kind).toBe("notFound");
+  });
+
+  it("cannot be traversed out of the index", () => {
+    expect(resolve("/../etc/passwd").kind).toBe("notFound");
+    expect(resolve("/sessions/../../secret").kind).toBe("notFound");
+  });
+});
+
+describe("RSC flight contract (the Go handler's rewrites)", () => {
+  it("serves static-route flight payloads directly", () => {
+    expect(servedFile("/conversations.txt")).toBe("/conversations.txt");
+    expect(servedFile("/__next._tree.txt")).toBe("/__next._tree.txt");
+  });
+
+  it("rewrites a dynamic route's flight payload to the placeholder twin", () => {
+    expect(servedFile("/sessions/ses_abc123.txt")).toBe(
+      "/sessions/__placeholder__.txt",
+    );
+  });
+
+  it("rewrites two-dynamic-segment flight payloads (beyond the Go handler)", () => {
+    expect(servedFile("/workflows/acme/my-flow.txt")).toBe(
+      "/workflows/__placeholder__/__placeholder__.txt",
+    );
+    expect(servedFile("/workflows/executions/wfe_123.txt")).toBe(
+      "/workflows/executions/__placeholder__.txt",
+    );
+  });
+
+  it("rewrites nested __next.*.txt payloads into the placeholder directory", () => {
+    expect(servedFile("/sessions/ses_abc123/__next.sessions.txt")).toBe(
+      "/sessions/__placeholder__/__next.sessions.txt",
+    );
+    expect(servedFile("/workflows/acme/my-flow/__next.workflows.txt")).toBe(
+      "/workflows/__placeholder__/__placeholder__/__next.workflows.txt",
+    );
+  });
+
+  it("answers notFound for flight requests on unknown routes", () => {
+    expect(resolve("/zz-nope/zz-nope.txt").kind).toBe("notFound");
+    expect(resolve("/zz-nope/zz-nope/__next.x.txt").kind).toBe("notFound");
+    // A known parent whose payload file is absent must not fall back to
+    // some other document.
+    expect(resolve("/sessions/ses_abc/__next.missing.txt").kind).toBe(
+      "notFound",
+    );
+  });
+
+  it("keeps /_next/ .txt requests literal-only", () => {
+    expect(resolve("/_next/static/zz.txt").kind).toBe("notFound");
+  });
+});

package/src/transport/console/assets.ts

@@ -0,0 +1,80 @@
+/**
+ * Console asset discovery — locates the web console's static export and
+ * indexes it for the console lane. The discovery rule is the workflow
+ * bundles' sibling idiom (src/temporal/workflow-source.ts): the slim
+ * packaging emits `console/` next to main.js, where the bundled
+ * import.meta.url shim resolves it; in the tsc dist the sibling never
+ * exists, so dev/test servers boot without the lane unless
+ * STIGMER_CONSOLE_DIR points somewhere explicitly (the conformance and
+ * unit-test posture — the lane is wire-invisible when assets are absent).
+ *
+ * The export is indexed ONCE at composition: it is immutable for the
+ * server's lifetime (it shipped inside the same artifact — DD-012's
+ * no-skew property), so a boot-time scan buys O(1) resolution, an exact
+ * availability answer, and a pure resolver.
+ */
+import { readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { Logger } from "../../boot/logger.js";
+import { buildConsoleFileIndex, type ConsoleFileIndex } from "./resolver.js";
+
+export interface ConsoleAssets {
+  /** Absolute filesystem root of the static export. */
+  readonly root: string;
+  /** "/"-rooted, "/"-separated file index the resolver consumes. */
+  readonly index: ConsoleFileIndex;
+  readonly fileCount: number;
+}
+
+/**
+ * Resolve and index the console export. Returns undefined — the modeled
+ * "not bundled" state, not an error — when neither the override nor the
+ * sibling exists.
+ */
+export function resolveConsoleAssets(
+  overrideDir: string,
+  logger: Logger,
+): ConsoleAssets | undefined {
+  const sibling = fileURLToPath(new URL("./console/", import.meta.url));
+  const root = overrideDir !== "" ? path.resolve(overrideDir) : sibling;
+
+  let rootStat;
+  try {
+    rootStat = statSync(root);
+  } catch {
+    return undefined;
+  }
+  if (!rootStat.isDirectory()) {
+    return undefined;
+  }
+
+  const files: string[] = [];
+  scan(root, "", files);
+  if (files.length === 0) {
+    // An empty directory serves nothing but would report "available" —
+    // treat it as absent and say why.
+    logger.warn("console asset directory is empty; console lane disabled", {
+      dir: root,
+    });
+    return undefined;
+  }
+  return {
+    root,
+    index: buildConsoleFileIndex(files),
+    fileCount: files.length,
+  };
+}
+
+/** Depth-first scan into "/"-separated index paths (never path.sep). */
+function scan(absoluteDir: string, indexPrefix: string, out: string[]): void {
+  for (const entry of readdirSync(absoluteDir, { withFileTypes: true })) {
+    const indexPath = `${indexPrefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      scan(path.join(absoluteDir, entry.name), indexPath, out);
+    } else if (entry.isFile()) {
+      out.push(indexPath);
+    }
+  }
+}