feat(astro): bundle SSR with esbuild + drop /* catchall + colocate manifest

Three coordinated fixes that align @run402/astro/release-slice with the
gateway's actual contract (Kychon's adoption of v1.1.0 surfaced the gaps):

1) SSR bundling (gateway rejects multi-file specs).

   The helper previously emitted functions.replace.<name>.{files,entrypoint}
   pointing at the multi-file Astro server output. The gateway hard-rejects
   that shape with "multi-file function spec (files + entrypoint) is not
   yet supported by the gateway; bundle locally with esbuild and pass
   `source` instead". New src/ssr-bundler.ts wraps esbuild with the right
   defaults (target node22, ESM, externalize Node built-ins +
   @run402/functions) and returns a bundled ESM string. release-slice
   emits source: <bundled string> instead.

2) Drop /* catchall + drop static aliases (gateway auto-fallback).

   The gateway's v1.52 ssr-fallback (run402-private commit 22bf0059)
   routes every unmatched-path request to the project's single class:'ssr'
   function automatically. The helper no longer needs to declare a /*
   catchall (route validator rejected it as "prefix wildcard must include
   a path segment before /*") and no longer emits static aliases for
   prerendered routes (the implicit public-paths mode handles them via
   the static manifest, and dual declarations were conflicting at /).

3) _assets-manifest.json colocated with the resolved client dir.

   The integration's vite plugin wrote dist/_assets-manifest.json at
   top-level, but the adapter relocates build.client to
   dist/run402/client/. The release slice's site.replace dir then didn't
   carry the manifest, triggering
   site.public_paths.inherited./_assets-manifest.json missing-asset
   rejections from the gateway. Fix: astro:config:done hook reads the
   final build.client and writes the manifest inside it. Universally
   correct — without an adapter, build.client defaults to dist/.

Plus dep: esbuild as a direct dependency (regular dep, not peer, since
bundling is a hard requirement for the helper to produce gateway-valid
specs).

Plus tests: 11 unit tests rewritten for the v1.2 contract (source-only
function shape, empty routes, cacheClass=>explicit public_paths). 244
astro tests / 11 release-slice tests all pass. End-to-end smoke against
api.run402.com confirms the gateway accepts the new slice shape (gets
past validation to plan phase).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MajorTal

astro/package.json

@@ -87,6 +87,9 @@
       "optional": true
     }
   },
+  "dependencies": {
+    "esbuild": "^0.24.0"
+  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@types/react": "^19.2.14",

astro/src/index.ts

@@ -66,6 +66,16 @@ type AstroIntegration = {
       command: "dev" | "build" | "preview";
       logger?: { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void };
     }) => void | Promise<void>;
+    "astro:config:done"?: (params: {
+      config: {
+        root: URL | string;
+        // The build triple is fully resolved by config:done time. Both
+        // `client` and `server` are URLs in Astro 5+; the integration only
+        // reads `build.client` to colocate `_assets-manifest.json` with
+        // the deploy slice's client dir.
+        build: { client: URL | string; server: URL | string; serverEntry: string };
+      };
+    }) => void | Promise<void>;
     "astro:build:setup"?: (params: unknown) => void | Promise<void>;
     "astro:server:setup"?: (params: unknown) => void | Promise<void>;
   };
@@ -121,6 +131,13 @@ export function run402Image(options: Run402AstroOptions = {}): AstroIntegration
   const dryRun = options.dryRun ?? false;
   const prefix = options.assetPrefix ?? DEFAULT_PREFIX;
 
+  // Shared across hooks. `astro:config:setup` runs first and creates the
+  // state + registers the Vite plugin; `astro:config:done` runs after
+  // every adapter / integration has mutated config (notably build.client),
+  // so it's the right moment to finalize manifestPath against the actual
+  // client output dir.
+  let state: VitePluginState | null = null;
+
   return {
     name: "@run402/astro",
     hooks: {
@@ -131,7 +148,7 @@ export function run402Image(options: Run402AstroOptions = {}): AstroIntegration
 
         const projectRoot = configRootToPath(config.root);
 
-        const state: VitePluginState = {
+        state = {
           projectRoot,
           aliases: loadAliasConfig(projectRoot),
           client: null,
@@ -145,6 +162,12 @@ export function run402Image(options: Run402AstroOptions = {}): AstroIntegration
           // v0.2 data-driven path. Resolve assetsDir(s) to absolute paths
           // against the project root so the walker doesn't depend on cwd.
           assetsDirs: resolveAssetsDirs(projectRoot, options.assetsDir),
+          // Provisional manifest path — replaced in `astro:config:done`
+          // unless the user explicitly set `options.manifestPath`. The
+          // provisional value is what older releases shipped (defaulting
+          // to `<projectRoot>/dist/_assets-manifest.json`), so a build
+          // that for some reason never reaches `astro:config:done` still
+          // writes a manifest to a sane path.
           manifestPath: resolveManifestPath(projectRoot, options.manifestPath),
           assetExtensions: options.assetExtensions ?? DEFAULT_ASSET_EXTENSIONS,
           manifestKeyByAbsPath: new Map(),
@@ -164,6 +187,28 @@ export function run402Image(options: Run402AstroOptions = {}): AstroIntegration
           },
         });
       },
+
+      // Capability `astro-ssr-runtime` coordination (v1.1+). When the
+      // Run402 SSR adapter is also active, it relocates `build.client`
+      // from the default `dist/` to `dist/run402/client/`. Writing the
+      // manifest to `<projectRoot>/dist/_assets-manifest.json` would
+      // then leave the manifest OUTSIDE the deploy slice's client dir,
+      // and the gateway's release validator would reject the missing
+      // file ("site.public_paths.inherited./_assets-manifest.json").
+      //
+      // Fix: write the manifest INTO the resolved `build.client` dir.
+      // This is universally correct:
+      //   - With the Run402 SSR adapter:    dist/run402/client/_assets-manifest.json
+      //   - With no adapter (static-only):  dist/_assets-manifest.json
+      //   - With a different SSR adapter:   <their client dir>/_assets-manifest.json
+      //
+      // Users who explicitly set `options.manifestPath` keep their
+      // override (escape hatch for non-standard layouts).
+      "astro:config:done": ({ config }) => {
+        if (!state || options.manifestPath) return;
+        const clientDir = configRootToPath(config.build.client);
+        state.manifestPath = path.join(clientDir, "_assets-manifest.json");
+      },
     },
   };
 }

astro/src/release-slice.test.ts

@@ -21,7 +21,13 @@ function writeFixture(
   mkdirSync(serverDir, { recursive: true });
   mkdirSync(clientDir, { recursive: true });
   const entryAbs = join(serverDir, "entry.mjs");
-  writeFileSync(entryAbs, "export const handler = async () => new Response('ok');\n");
+  // esbuild bundles this; the source must be valid ESM. The Astro
+  // server entry in production exports `handler` + `default` — match
+  // that shape so the bundled output looks right.
+  writeFileSync(
+    entryAbs,
+    "export const handler = async () => new Response('ok');\nexport default handler;\n",
+  );
   writeFileSync(join(clientDir, "index.html"), "<!doctype html><title>home</title>");
 
   if (manifest !== null) {
@@ -122,7 +128,7 @@ describe("loadAstroAdapterManifest", () => {
   });
 });
 
-describe("buildAstroReleaseSlice — happy path + prerender truth", () => {
+describe("buildAstroReleaseSlice — happy path", () => {
   let root: string;
   beforeEach(() => {
     root = mkdtempSync(join(tmpdir(), "r402-release-slice-build-"));
@@ -131,7 +137,7 @@ describe("buildAstroReleaseSlice — happy path + prerender truth", () => {
     rmSync(root, { recursive: true, force: true });
   });
 
-  it("returns site/functions/routes from a hybrid build", async () => {
+  it("emits site (LocalDirRef), functions (bundled source), empty routes", async () => {
     const { distDir } = writeFixture(root, {
       output: "server",
       routes: [
@@ -142,107 +148,55 @@ describe("buildAstroReleaseSlice — happy path + prerender truth", () => {
 
     const slice = await buildAstroReleaseSlice(distDir);
 
-    // site
+    // site — LocalDirRef pointing at dist/run402/client/
     const siteReplace = (slice.site as { replace: unknown }).replace as {
       __source: string;
       path: string;
     };
     assert.equal(siteReplace.__source, "local-dir");
     assert.match(siteReplace.path, /dist[/\\]run402[/\\]client$/);
 
-    // functions
+    // functions — single ssr function with bundled source (string)
     assert.deepEqual(Object.keys(slice.functions.replace), ["ssr"]);
     const fn = slice.functions.replace.ssr;
     assert.equal(fn.runtime, "node22");
     assert.equal((fn as { class?: string }).class, "ssr");
-    assert.equal(fn.entrypoint, "entry.mjs");
-    assert.ok(
-      fn.files && typeof fn.files === "object",
-      "functions.replace.ssr.files must be a FileSet",
+    assert.equal(
+      typeof fn.source,
+      "string",
+      "functions.replace.ssr.source must be a string (bundled ESM)",
     );
     assert.ok(
-      Object.prototype.hasOwnProperty.call(fn.files, "entry.mjs"),
-      "FileSet must contain the entry.mjs key",
+      typeof fn.source === "string" && fn.source.includes("handler"),
+      "bundled source should reference the entrypoint's `handler` export",
+    );
+    assert.equal(
+      fn.files,
+      undefined,
+      "v1.2 slice must NOT emit files+entrypoint — the gateway rejects multi-file specs",
+    );
+    assert.equal(
+      fn.entrypoint,
+      undefined,
+      "v1.2 slice must NOT emit entrypoint — the bundle is self-contained",
     );
 
-    // routes — prerendered /about gets a static alias, /[slug] falls through
-    // to the catchall (no per-route entry), then catchall last. Static aliases
-    // are constrained to GET/HEAD per the SDK's static-route validator.
-    assert.deepEqual(slice.routes.replace, [
-      {
-        pattern: "/about",
-        methods: ["GET", "HEAD"],
-        target: { type: "static", file: "about/index.html" },
-      },
-      { pattern: "/*", target: { type: "function", name: "ssr" } },
-    ]);
-  });
-
-  it("maps / → index.html and routes ending in .html keep the extension", async () => {
-    const { distDir } = writeFixture(root, {
-      routes: [
-        { pattern: "/", pathname: "/", prerender: true, type: "page" },
-        { pattern: "/sitemap.xml", pathname: "/sitemap.xml", prerender: true, type: "endpoint" },
-        { pattern: "/legacy.html", pathname: "/legacy.html", prerender: true, type: "page" },
-      ],
-    });
-
-    const slice = await buildAstroReleaseSlice(distDir);
-    const aliases = slice.routes.replace.filter((r) => r.target.type === "static");
-    assert.deepEqual(aliases, [
-      { pattern: "/", methods: ["GET", "HEAD"], target: { type: "static", file: "index.html" } },
-      {
-        pattern: "/sitemap.xml",
-        methods: ["GET", "HEAD"],
-        target: { type: "static", file: "sitemap.xml/index.html" },
-      },
-      {
-        pattern: "/legacy.html",
-        methods: ["GET", "HEAD"],
-        target: { type: "static", file: "legacy.html" },
-      },
-    ]);
-  });
-
-  it("skips redirect and fallback route types", async () => {
-    const { distDir } = writeFixture(root, {
-      routes: [
-        { pattern: "/old", prerender: true, type: "redirect" },
-        { pattern: "/404", prerender: true, type: "fallback" },
-        { pattern: "/keep", pathname: "/keep", prerender: true, type: "page" },
-      ],
-    });
-    const slice = await buildAstroReleaseSlice(distDir);
-    const aliases = slice.routes.replace.filter((r) => r.target.type === "static");
-    assert.deepEqual(aliases, [
-      {
-        pattern: "/keep",
-        methods: ["GET", "HEAD"],
-        target: { type: "static", file: "keep/index.html" },
-      },
-    ]);
-  });
-});
-
-describe("buildAstroReleaseSlice — option surface", () => {
-  let root: string;
-  beforeEach(() => {
-    root = mkdtempSync(join(tmpdir(), "r402-release-slice-opts-"));
-  });
-  afterEach(() => {
-    rmSync(root, { recursive: true, force: true });
+    // routes — empty by default. The gateway's class:'ssr' auto-fallback
+    // routes unmatched paths to the ssr function automatically. Prerendered
+    // routes are reachable via the static manifest's implicit public-paths
+    // mode — no explicit aliases needed (and emitting them would conflict
+    // with the implicit declaration for the same path).
+    assert.deepEqual(slice.routes.replace, []);
   });
 
-  it("respects functionName override across functions + routes", async () => {
+  it("functionName option flows through to functions key", async () => {
     const { distDir } = writeFixture(root, { routes: [] });
     const slice = await buildAstroReleaseSlice(distDir, { functionName: "render" });
     assert.deepEqual(Object.keys(slice.functions.replace), ["render"]);
-    assert.deepEqual(slice.routes.replace, [
-      { pattern: "/*", target: { type: "function", name: "render" } },
-    ]);
+    assert.deepEqual(slice.routes.replace, []);
   });
 
-  it("passes requireAuth + requireRole through verbatim", async () => {
+  it("passes requireAuth + requireRole through verbatim onto the ssr function", async () => {
     const { distDir } = writeFixture(root, { routes: [] });
     const slice = await buildAstroReleaseSlice(distDir, {
       requireAuth: true,
@@ -264,6 +218,16 @@ describe("buildAstroReleaseSlice — option surface", () => {
       cacheTtl: 30,
     });
   });
+});
+
+describe("buildAstroReleaseSlice — explicit cacheClass option", () => {
+  let root: string;
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "r402-release-slice-cache-"));
+  });
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
 
   it("emits explicit public_paths for prerendered routes when cacheClass is set", async () => {
     const { distDir } = writeFixture(root, {
@@ -294,4 +258,18 @@ describe("buildAstroReleaseSlice — option surface", () => {
       "public_paths must remain implicit unless the caller asked for cacheClass overrides",
     );
   });
+
+  it("normalizes Astro's empty-string root pathname to / in explicit public_paths", async () => {
+    const { distDir } = writeFixture(root, {
+      routes: [{ pattern: "", pathname: "", prerender: true, type: "page" }],
+    });
+    const slice = await buildAstroReleaseSlice(distDir, { cacheClass: "html" });
+    const publicPaths = (slice.site as { public_paths?: unknown }).public_paths as {
+      mode: string;
+      replace: Record<string, { asset: string; cache_class?: string }>;
+    };
+    assert.deepEqual(publicPaths.replace, {
+      "/": { asset: "index.html", cache_class: "html" },
+    });
+  });
 });