feat(astro)!: omit routes from buildAstroReleaseSlice (gh#411)

buildAstroReleaseSlice used to return `routes: { replace: [] }`. An empty
replace CLEARS the release route table, which (a) clobbers caller-declared base
routes like a separately-mounted `/api/*` function and (b) trips CI route-scope
enforcement (a CI OIDC session without route scopes is rejected for setting
`routes` at all) - part of why consumers hand-rolled their own CI deploy specs
and drifted into the #411 footgun.

The slice now OMITS `routes` entirely (the field is optional on
AstroReleaseSlice). An Astro hybrid release needs no explicit route table:
prerendered pages resolve through the static manifest and every other path
falls through to the implicit `class: "ssr"` fallback. Omitting `routes`
carries base routes forward and keeps the slice CI-safe.

BREAKING CHANGE: AstroReleaseSlice.routes is now optional and is undefined by
default. Consumers reading `slice.routes.replace` must use
`slice.routes?.replace ?? []`.

Also fixes the stale doc comment (it described a `/*` catchall + per-page static
aliases the helper has not emitted since v1.2) and adds a "Deploying with the
SDK directly (and from CI)" README section with the do/don't.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: MajorTal

astro/README.md

@@ -430,6 +430,32 @@ run402 logs --request-id req_xyz123 --json          # debug a failed render
 
 `run402 init astro` creates a working project with `package.json` (dev/deploy scripts), `astro.config.mjs` (one-line preset), sample `[slug].astro` with the full DB-fetch + cache pattern, an admin save endpoint demonstrating cache invalidation, and `.env.example`. See `run402 init astro --help`.
 
+### Deploying with the SDK directly (and from CI)
+
+Most projects deploy with `run402 deploy` (above) or `run402 deploy apply --dir dist`. If you write your own deploy script with `@run402/sdk` — e.g. a CI job that assembles a custom `ReleaseSpec` — turn the build into a deploy slice with the one canonical helper. **Do not hand-roll `site` / `public_paths`.**
+
+```ts
+import { run402 } from "@run402/sdk";
+import { buildAstroReleaseSlice } from "@run402/astro/release-slice";
+
+const slice = await buildAstroReleaseSlice("dist");   // point at the BUILD ROOT, not dist/run402/client
+await run402().project(projectId).apply({
+  database: { migrations },     // your own cross-cutting slices
+  ...slice,                     // site + functions (routes intentionally omitted)
+});
+```
+
+`buildAstroReleaseSlice` is the only supported way to map an Astro build to a `ReleaseSpec`. It:
+
+- roots the site at `dist/run402/client/` (the served output) — **not** `dist/`;
+- sets `site.public_paths: { mode: "implicit" }` so prerendered pages are reachable by filename;
+- bundles the SSR entry into a single `class: "ssr"` function;
+- **omits `routes`** (it is not in the returned object) so base-release routes — e.g. a separately-declared `/api/*` function — carry forward instead of being cleared, and the slice stays safe to submit from a CI OIDC session that has no route scopes.
+
+**Anti-pattern (the cause of [kychee-com/run402#411](https://github.com/kychee-com/run402/issues/411)):** do not point `fileSetFromDir`/`dir()` at `dist/` and build `public_paths` by hand. That ships the adapter build tree (`run402/adapter.json`, `run402/server/**`) as static assets and lands every page under a `run402/client/` path prefix — so the static manifest has no reachable pages, every URL falls through to the SSR catchall and 404s, and the SSR bundle becomes publicly downloadable. The SDK now rejects this locally with `ASTRO_ADAPTER_TREE_IN_SITE` before any upload, and the gateway warns (`SITE_NO_REACHABLE_HTML`) when a release ships HTML that isn't reachable at any public path.
+
+**Full vs CI/patch deploys use the same slice.** CI sessions are content-only (no subdomains/routes/i18n) — the slice already omits `routes`, so just don't add `routes`/`subdomains`/`i18n` to the spec in CI. The CAS substrate dedupes unchanged bytes, so a `site.replace` from the slice uploads only what actually changed; you don't need a hand-rolled `site.patch` diff to get incremental uploads.
+
 ## R402_* error codes
 
 Build / deploy / runtime / cache failures all return a structured envelope:

astro/src/release-slice.test.ts

@@ -137,7 +137,7 @@ describe("buildAstroReleaseSlice — happy path", () => {
     rmSync(root, { recursive: true, force: true });
   });
 
-  it("emits site (LocalDirRef), functions (bundled source), empty routes", async () => {
+  it("emits site (LocalDirRef), functions (bundled source), and omits routes", async () => {
     const { distDir } = writeFixture(root, {
       output: "server",
       routes: [
@@ -181,19 +181,23 @@ describe("buildAstroReleaseSlice — happy path", () => {
       "v1.2 slice must NOT emit entrypoint — the bundle is self-contained",
     );
 
-    // 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, []);
+    // routes — OMITTED (not `{ replace: [] }`). The gateway's class:'ssr'
+    // auto-fallback routes unmatched paths to the ssr function automatically,
+    // and prerendered pages resolve via the static manifest's implicit
+    // public-paths mode. Omitting `routes` carries forward any base-release
+    // routes instead of clearing them, and keeps the slice CI-safe.
+    assert.equal(
+      slice.routes,
+      undefined,
+      "slice must omit routes so base routes carry forward and CI sessions aren't rejected",
+    );
   });
 
   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, []);
+    assert.equal(slice.routes, undefined);
   });
 
   it("passes requireAuth + requireRole through verbatim onto the ssr function", async () => {

astro/src/release-slice.ts

@@ -211,7 +211,17 @@ export interface BuildAstroReleaseSliceOptions {
 export interface AstroReleaseSlice {
   site: SiteSpec;
   functions: { replace: Record<string, FunctionSpec> };
-  routes: { replace: RouteSpec[] };
+  /**
+   * Intentionally **omitted** by {@link buildAstroReleaseSlice} (the field is
+   * optional, not `{ replace: [] }`). An Astro hybrid release needs no explicit
+   * route table: prerendered pages resolve through the static manifest and
+   * every other path falls through to the gateway's implicit `class: "ssr"`
+   * fallback. Omitting `routes` carries forward any base-release routes (e.g. a
+   * separately-declared `/api/*` function) instead of clearing them, and keeps
+   * the slice safe to submit from a CI OIDC session that lacks route scopes.
+   * Callers who need explicit routes declare them on top of the slice.
+   */
+  routes?: { replace: RouteSpec[] };
 }
 
 /**
@@ -320,9 +330,14 @@ export async function loadAstroAdapterManifest(
  * - `functions.replace[functionName]` describes the SSR Lambda entry from
  *   `manifest.serverEntrypoint` and carries `class: "ssr"` (gateway v1.52+)
  *   so the gateway enables SnapStart + ISR-cache routing.
- * - `routes.replace` emits one `{ type: "static", file }` alias per
- *   prerendered route, followed by a final wildcard `/* → function:ssr`
- *   catchall. Order matters at the gateway: explicit > prefix > catchall.
+ * - `routes` is intentionally **omitted** from the returned slice (not
+ *   `{ replace: [] }`). An Astro hybrid release needs no explicit route table:
+ *   prerendered pages resolve through the static manifest (implicit
+ *   `public_paths`), and every unmatched path falls through to the gateway's
+ *   implicit `class: "ssr"` fallback (v1.52+). Omitting `routes` carries
+ *   forward any base-release routes (e.g. a separately-declared `/api/*`
+ *   function) instead of clearing them, and keeps the slice CI-safe — a CI
+ *   OIDC session without route scopes is rejected if the spec sets `routes`.
  */
 export async function buildAstroReleaseSlice(
   distDir: string,
@@ -396,21 +411,15 @@ export async function buildAstroReleaseSlice(
     replace: { [functionName]: functionSpec },
   };
 
-  // No explicit routes are emitted by default. The gateway (v1.52+,
-  // capability `astro-ssr-runtime`) routes every unmatched-path request
-  // to the project's single class:'ssr' function automatically — so
-  // the helper does not need to declare a /* catchall (which the route
-  // validator rejects anyway: "prefix wildcard must include a path
-  // segment before /*"). Prerendered routes are reachable via the
-  // gateway's implicit public-paths mode against the static manifest;
-  // we do not emit static-route aliases, which previously conflicted
-  // with the implicit-mode declaration for the same path.
-  //
-  // Callers who want explicit prefix routes (e.g. `/api/*` → a dedicated
-  // function) can still declare them on top of the slice; the slice's
-  // own `routes.replace: []` is intentionally empty so it doesn't
-  // clobber that pattern.
-  const routes: RouteSpec[] = [];
+  // `routes` is intentionally OMITTED from the returned slice (see the doc
+  // comment above) — not emitted as `{ replace: [] }`. The gateway (v1.52+,
+  // capability `astro-ssr-runtime`) routes every unmatched-path request to the
+  // project's single `class: "ssr"` function automatically, and prerendered
+  // pages resolve through `site.public_paths`. Omitting `routes` (rather than
+  // sending an empty replace, which CLEARS the route table) carries forward any
+  // caller-declared base routes (e.g. `/api/*` → a dedicated function) and
+  // keeps the slice safe to submit from a CI OIDC session without route scopes.
+  // Callers who need explicit routes declare them on top of the slice.
 
   // `cacheClass` is plumbed into `site.public_paths` for prerendered routes
   // when a caller cares about overriding the default html cache class. The
@@ -436,7 +445,7 @@ export async function buildAstroReleaseSlice(
     };
   }
 
-  return { site, functions, routes: { replace: routes } };
+  return { site, functions };
 }
 
 /**