feat(sdk): reject Astro adapter build-tree shipped as site content (gh#411)

A deploy that roots its file source at the build root (`dist/`) instead of
`dist/run402/client/` ships the @run402/astro adapter tree
(`run402/adapter.json`, `run402/server/**`) as static assets and lands every
page under a `run402/client/` path prefix. The static manifest then has no
reachable pages, every URL falls through to the SSR catchall and 404s, and the
SSR bundle becomes publicly downloadable - an apply that "succeeds" but takes
the whole site down (#411).

validateSpec now rejects this locally with `ASTRO_ADAPTER_TREE_IN_SITE` before
any CAS upload or plan - both for literal FileSets (synchronously) and for
`dir()` LocalDirRefs (post-expansion). Not suppressible by RUN402_ALLOW_WARNINGS.

Also: CLI `deploy apply --dir` tolerates the slice omitting `routes`, and
llms-cli.txt documents the anti-pattern + the new guard.

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

Author: MajorTal

cli/lib/deploy-v2.mjs

@@ -603,14 +603,16 @@ async function mergeAstroReleaseSlice(spec, dirArg) {
     throw err;
   }
 
-  // Slice owns site/functions/routes. The caller's manifest can declare
-  // cross-cutting slices (database, secrets, i18n, subdomains) that the
-  // slice doesn't touch. On collision in `functions.replace`, the slice
-  // wins for its own function name; the caller's other functions are
-  // preserved. `site` and `routes` are whole-resource replacements — slice
-  // wins entirely on those.
+  // Slice owns site/functions. The caller's manifest can declare cross-cutting
+  // slices (database, secrets, i18n, subdomains, routes) that the slice doesn't
+  // touch. On collision in `functions.replace`, the slice wins for its own
+  // function name; the caller's other functions are preserved. `site` is a
+  // whole-resource replacement — slice wins entirely. The slice omits `routes`
+  // by default (the SSR catchall is implicit; base routes carry forward), so we
+  // only set `spec.routes` if the slice explicitly provides one; otherwise the
+  // caller's manifest `routes` (if any) is preserved.
   spec.site = slice.site;
-  spec.routes = slice.routes;
+  if (slice.routes !== undefined) spec.routes = slice.routes;
   const sliceFns = slice.functions?.replace ?? {};
   const existingFns =
     spec.functions && typeof spec.functions === "object" && spec.functions.replace

cli/llms-cli.txt

@@ -312,7 +312,7 @@ run402 deploy apply --dir ./dist --project prj_...
 run402 deploy apply --dir ./dist --manifest run402.config.json --project prj_...
 ```
 
-The CLI dynamically imports `@run402/astro/release-slice` (must be installed in the consuming project, **`@run402/astro >=1.2.1` + `@run402/sdk >=2.18.0`** — older SDKs reject `FunctionSpec.class: 'ssr'` locally in `validateKnownFields` before the spec ever reaches the gateway; the helper preflights this and emits `R402_ASTRO_SDK_VERSION_TOO_OLD` with a precise upgrade command). The helper bundles the SSR server output with esbuild into a single `source` (the gateway rejects multi-file function specs), emits no `/*` catchall route (the gateway routes every unmatched path to the project's `class: 'ssr'` function automatically), defaults `site.public_paths: { mode: "implicit" }` to opt out of inherited explicit-mode paths from the base release, and colocates the `_assets-manifest.json` inside the resolved `build.client` dir (so the slice's site replace dir carries it). On a missing/incompatible manifest the error envelope carries `code: "R402_ASTRO_ADAPTER_MANIFEST_MISSING"` or `R402_ASTRO_ADAPTER_MANIFEST_VERSION_UNSUPPORTED` with `hint` + `docs` fields pointing at run402.com/errors. Direct-SDK callers get the same primitive via `import { buildAstroReleaseSlice } from "@run402/astro/release-slice"`.
+The CLI dynamically imports `@run402/astro/release-slice` (must be installed in the consuming project, **`@run402/astro >=1.2.1` + `@run402/sdk >=2.18.0`** — older SDKs reject `FunctionSpec.class: 'ssr'` locally in `validateKnownFields` before the spec ever reaches the gateway; the helper preflights this and emits `R402_ASTRO_SDK_VERSION_TOO_OLD` with a precise upgrade command). The helper bundles the SSR server output with esbuild into a single `source` (the gateway rejects multi-file function specs), roots the site at the resolved `build.client` dir (`dist/run402/client/`, NOT `dist/`), **omits `routes` entirely from the returned slice** (the gateway routes every unmatched path to the project's `class: 'ssr'` function automatically, so no route table is needed; omitting `routes` — rather than sending an empty `replace` that would CLEAR the table — carries forward any base-release routes such as a separately-declared `/api/*` function and keeps the slice safe to submit from a CI OIDC session without route scopes), defaults `site.public_paths: { mode: "implicit" }` to opt out of inherited explicit-mode paths from the base release, and colocates the `_assets-manifest.json` inside the resolved `build.client` dir (so the slice's site replace dir carries it). On a missing/incompatible manifest the error envelope carries `code: "R402_ASTRO_ADAPTER_MANIFEST_MISSING"` or `R402_ASTRO_ADAPTER_MANIFEST_VERSION_UNSUPPORTED` with `hint` + `docs` fields pointing at run402.com/errors. Direct-SDK callers get the same primitive via `import { buildAstroReleaseSlice } from "@run402/astro/release-slice"`. Do NOT hand-roll `site` / `public_paths`: if a deploy ships the adapter build tree (`run402/adapter.json`, `run402/server/**`) as site content — the symptom of rooting a file source at `dist/` instead of `dist/run402/client/` — the SDK rejects it 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 (kychee-com/run402#411).
 
 Recovery from a stuck deploy: when an `apply` ends in `activation_pending` (rare; transient gateway failure between SQL commit and the pointer-swap activation), the gateway auto-resumes on the hourly tick. Static spec/config activation failures are classified promptly and thrown as structured deploy errors instead of polling until timeout. For genuinely resumable operations, call resume explicitly:
 

sdk/src/namespaces/deploy.test.ts

@@ -11,7 +11,7 @@
 import { describe, it, before, beforeEach } from "node:test";
 import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
-import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -5102,3 +5102,105 @@ describe("Deploy release observability", () => {
   });
 
 });
+
+describe("Deploy.apply (Astro adapter build-tree guard — gh#411)", () => {
+  it("rejects a site.replace FileSet that ships the adapter build tree", async () => {
+    const w = makeWiring();
+    const deploy = new Deploy(w.client);
+    await assert.rejects(
+      () =>
+        deploy.apply({
+          project: "prj_test",
+          site: {
+            replace: {
+              "run402/adapter.json": "{}",
+              "run402/server/entry.mjs": "export {}",
+              "run402/client/index.html": "<html></html>",
+            },
+          },
+        }),
+      (err: unknown) => {
+        assert(err instanceof Run402DeployError);
+        assert.equal(err.code, "ASTRO_ADAPTER_TREE_IN_SITE");
+        assert.equal(err.resource, "site.replace");
+        assert.match(err.message, /dist\/run402\/client/);
+        assert.match(err.message, /buildAstroReleaseSlice/);
+        assert.equal(err.fix?.expected_dir, "dist/run402/client");
+        return true;
+      },
+    );
+    assert.equal(w.requests.length, 0, "fails before any gateway request");
+    assert.equal(w.puts.length, 0, "fails before any S3 upload");
+  });
+
+  it("rejects a site.patch.put FileSet that ships the adapter build tree", async () => {
+    const w = makeWiring();
+    const deploy = new Deploy(w.client);
+    await assert.rejects(
+      () =>
+        deploy.apply({
+          project: "prj_test",
+          site: { patch: { put: { "run402/server/chunks/x.mjs": "export {}" } } },
+        }),
+      (err: unknown) => {
+        assert(err instanceof Run402DeployError);
+        assert.equal(err.code, "ASTRO_ADAPTER_TREE_IN_SITE");
+        assert.equal(err.resource, "site.patch.put");
+        return true;
+      },
+    );
+    assert.equal(w.requests.length, 0, "fails before any gateway request");
+  });
+
+  it("rejects a mis-rooted dir() (LocalDirRef) post-expansion", async () => {
+    const root = mkdtempSync(join(tmpdir(), "astro-misroot-"));
+    try {
+      mkdirSync(join(root, "run402", "server"), { recursive: true });
+      mkdirSync(join(root, "run402", "client"), { recursive: true });
+      writeFileSync(join(root, "run402", "adapter.json"), "{}");
+      writeFileSync(join(root, "run402", "server", "entry.mjs"), "export {}");
+      writeFileSync(join(root, "run402", "client", "index.html"), "<html></html>");
+
+      const w = makeWiring();
+      const deploy = new Deploy(w.client);
+      await assert.rejects(
+        () =>
+          deploy.apply({
+            project: "prj_test",
+            site: { replace: dir(root) },
+          }),
+        (err: unknown) => {
+          assert(err instanceof Run402DeployError);
+          assert.equal(err.code, "ASTRO_ADAPTER_TREE_IN_SITE");
+          assert.equal(err.resource, "site.replace");
+          return true;
+        },
+      );
+      assert.equal(w.requests.length, 0, "fails before any gateway request");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("does NOT flag a correctly client-rooted site (no run402/ prefix)", async () => {
+    const w = makeWiring();
+    w.setHandler((req) => {
+      if (req.path === "/apply/v1/plans") return noContentPlan("plan_ok", "op_ok");
+      if (req.path === "/apply/v1/plans/plan_ok/commit") return readyCommit("op_ok", "rel_ok");
+      throw new Error(`unexpected path ${req.path}`);
+    });
+    const deploy = new Deploy(w.client);
+    const result = await deploy.apply({
+      project: "prj_test",
+      site: {
+        replace: {
+          "index.html": "<html></html>",
+          "events.html": "<html></html>",
+          "_astro/app.css": "body{}",
+        },
+        public_paths: { mode: "implicit" },
+      },
+    });
+    assert.equal(result.release_id, "rel_ok");
+  });
+});

sdk/src/namespaces/deploy.ts

@@ -2237,6 +2237,79 @@ function validateFunctionMap(value: unknown, resource: string): void {
   }
 }
 
+/**
+ * Detect a site path key that belongs to the `@run402/astro` SSR adapter's
+ * build tree rather than to deployable static content. The adapter writes
+ * `dist/run402/{adapter.json, server/**, client/**}`; only `client/**` is
+ * servable. `adapter.json` and `server/**` are build internals — their
+ * presence in a site spec means the caller rooted their file source at the
+ * build root (`dist/`) instead of `dist/run402/client/`.
+ */
+function isAstroAdapterTreeSitePath(path: string): boolean {
+  return path === "run402/adapter.json" || path.startsWith("run402/server/");
+}
+
+/**
+ * Return the synchronously-knowable keys of a site file container. Plain
+ * path-keyed `FileSet`s expose their keys directly; a `LocalDirRef`
+ * (`dir(path)`) or any future source sentinel carries an `__source` marker
+ * and is only knowable after expansion — those return `[]` here and are
+ * re-checked post-normalization.
+ */
+function siteFileSetKeysForGuard(container: unknown): string[] {
+  if (
+    !container ||
+    typeof container !== "object" ||
+    Array.isArray(container) ||
+    (container as { __source?: unknown }).__source !== undefined
+  ) {
+    return [];
+  }
+  return Object.keys(container as Record<string, unknown>);
+}
+
+/**
+ * Reject a site slice that ships the `@run402/astro` adapter build tree as
+ * static content. This is the mis-rooting behind kychee-com/run402#411: a
+ * deploy pointed `fileSetFromDir`/`dir()` at `dist/` (not `dist/run402/client/`),
+ * so every page landed under a `run402/client/` path prefix while
+ * `run402/adapter.json` + `run402/server/**` leaked in as assets — producing a
+ * release that 404'd every URL and exposed the SSR bundle. Fail fast, locally,
+ * with the fix, before any CAS upload or plan.
+ */
+function assertNoAstroAdapterTreeInSite(
+  paths: Iterable<string>,
+  resource: string,
+): void {
+  const offenders: string[] = [];
+  for (const p of paths) {
+    if (isAstroAdapterTreeSitePath(p)) offenders.push(p);
+    if (offenders.length >= 3) break;
+  }
+  if (offenders.length === 0) return;
+  throw new Run402DeployError(
+    `${resource} ships the @run402/astro adapter build tree (e.g. ${offenders
+      .map((p) => `\`${p}\``)
+      .join(", ")}) as static content. Only \`dist/run402/client/\` is deployable; ` +
+      `\`run402/adapter.json\` and \`run402/server/**\` are build internals. You likely ` +
+      `rooted your file source at the build root (\`dist/\`) instead of \`dist/run402/client/\`. ` +
+      `Use \`buildAstroReleaseSlice("dist")\` from @run402/astro (it roots the site and bundles ` +
+      `the SSR function correctly), or point your dir at \`dist/run402/client\`.`,
+    {
+      code: "ASTRO_ADAPTER_TREE_IN_SITE",
+      phase: "validate",
+      resource,
+      retryable: false,
+      fix: {
+        action: "reroot_site_to_astro_client_dir",
+        path: resource,
+        expected_dir: "dist/run402/client",
+      },
+      context: "validating spec",
+    },
+  );
+}
+
 function validateSiteSpec(site: unknown): void {
   if (site === undefined) return;
   const obj = requireObject(site, "site");
@@ -2249,11 +2322,15 @@ function validateSiteSpec(site: unknown): void {
   }
   if (obj.replace !== undefined) {
     requireObject(obj.replace, "site.replace");
+    assertNoAstroAdapterTreeInSite(siteFileSetKeysForGuard(obj.replace), "site.replace");
   }
   if (obj.patch !== undefined) {
     const patch = requireObject(obj.patch, "site.patch");
     validateKnownFields(patch, "site.patch", SITE_PATCH_FIELDS);
-    if (patch.put !== undefined) requireObject(patch.put, "site.patch.put");
+    if (patch.put !== undefined) {
+      requireObject(patch.put, "site.patch.put");
+      assertNoAstroAdapterTreeInSite(siteFileSetKeysForGuard(patch.put), "site.patch.put");
+    }
     if (patch.delete !== undefined) validateStringArray(patch.delete, "site.patch.delete");
   }
   if (obj.public_paths !== undefined) {
@@ -3113,6 +3190,9 @@ async function normalizeReleaseSpec(
       "public_paths" in spec.site ? spec.site.public_paths : undefined;
     if ("replace" in spec.site && spec.site.replace) {
       const map = await normalizeFileSet(spec.site.replace, rememberRelease);
+      // Re-check post-expansion so `dir("dist")` (a LocalDirRef whose keys are
+      // unknown at validateSpec time) is caught too, not just literal FileSets.
+      assertNoAstroAdapterTreeInSite(Object.keys(map), "site.replace");
       normalized.site = {
         replace: map,
         ...(publicPaths ? { public_paths: publicPaths } : {}),
@@ -3121,6 +3201,7 @@ async function normalizeReleaseSpec(
       const patch: { put?: Record<string, ContentRef>; delete?: string[] } = {};
       if (spec.site.patch.put) {
         patch.put = await normalizeFileSet(spec.site.patch.put, rememberRelease);
+        assertNoAstroAdapterTreeInSite(Object.keys(patch.put), "site.patch.put");
       }
       if (spec.site.patch.delete) patch.delete = spec.site.patch.delete;
       normalized.site = {