@pilvia/astro 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# @pilvia/astro
+
+The [Astro](https://astro.build) adapter for [Pilvia App](https://pilvia.com) —
+EU-hosted, installable on your own iron. Prerendered pages and assets are
+served by the host; on-demand pages, endpoints and Astro Actions run in an
+isolate next to your data.
+
+```sh
+bun add @pilvia/astro
+```
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import pilvia from "@pilvia/astro";
+
+export default defineConfig({
+  adapter: pilvia(),
+});
+```
+
+```json
+// pilvia.app.json — beside astro.config.mjs
+{
+  "name": "my-site",
+  "auth": "public",
+  "build": "dist/pilvia.build.json",
+  "egress": { "allow": ["api.eu.mailgun.net"] }
+}
+```
+
+```sh
+astro build
+pilvia app deploy
+```
+
+That is the whole change. Switching back to another adapter is the same one
+line in the other direction.
+
+## What the adapter does
+
+- Builds the server half for a web-platform isolate: `webworker` target,
+  every dependency bundled (there is no `node_modules` at runtime), the
+  worker/browser exports of each package.
+- Emits the platform contract, `export default { fetch(request, env) }`,
+  from `astro/app`. Nothing platform-specific is in your build.
+- Writes **`dist/pilvia.build.json`** after the build: where the server entry
+  and the client assets are, and the routes Astro renders on demand —
+  derived from Astro's own route manifest. `pilvia app deploy` reads it via
+  `"build"`; nobody hand-writes a routes list.
+- Surfaces the platform's capability object as **`Astro.locals.env`**
+  (`context.locals.env` in endpoints, middleware and Actions): `env.user`,
+  `env.memory`, `env.entities`, `env.broker`, … — whatever the app's manifest
+  grants. `Astro.clientAddress` is the real client behind the platform's load
+  balancer.
+- Sets the image service to passthrough unless you configured one yourself:
+  sharp is native code and cannot run inside the isolate.
+
+## How requests are routed
+
+The host routes **asset → declared route → fallback**. A prerendered page is
+an asset the host serves (with strong ETags and a year of `immutable` on
+hashed files); an on-demand page, an endpoint or `/_actions/*` is a declared
+route the isolate answers; anything else gets your `404.html` without spinning
+an isolate up. A fully prerendered site with no Actions deploys as a plain
+static site — no isolate at all.
+
+## Outbound requests
+
+The isolate has no ambient network. Name what your server code reaches in
+`pilvia.app.json` → `"egress": { "allow": [...] }` (hosts, `*.example.com`
+wildcards, optional `:port`). The platform intersects it with the box's
+ceiling; a fetch to an unlisted host fails closed.
+
+## Limits, honestly
+
+- **Astro sessions** need a driver; the platform's KV binding is not wired to
+  `astro:session` yet.
+- **`astro:env` secrets** (`getSecret`) are not wired; read configuration from
+  `Astro.locals.env` or bake it in at build time.
+- **Images**: passthrough at runtime. Prerendered pages keep build-time
+  optimisation only if you configure an image service that does it at build
+  time.
+- **Node built-ins**: the isolate is a web-platform runtime, not Node. `Buffer`
+  is provided (the standard `buffer` polyfill) because sites reach for it
+  casually; other `node:*` modules are not.
+- **Server islands** do not work yet: the engine's WebCrypto has no AES-GCM,
+  which Astro uses to encrypt island props. The adapter keeps Astro's eager
+  key import from spamming the log; a page that actually renders a server
+  island fails at that point with the engine's message.
+- **Engine gaps** carried as guarded bundle-layer workarounds until the engine
+  catches up (`src/preamble.js`, `src/entrypoint.js`): no ICU (`Intl`,
+  `String.prototype.normalize`); `es-module-lexer` aliased to its pure-JS build
+  because the isolate has no `WebAssembly` global; the fetch-event Request is
+  rebuilt before Astro sees it (its immutable headers/body trip Actions'
+  `formData()`). None of these touch your code.
+
+## Development
+
+```sh
+bun install
+bun test          # unit tests + a real `astro build` of test/fixture
+```
+
+Part of [`pilvia/app`](https://github.com/pilvia/app) — see `docs/app-runtime.md`
+there, "Server side" → Layer 2, for why this is an adapter of our own rather
+than compatibility with another platform's build output.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@pilvia/astro",
+  "version": "0.1.0",
+  "description": "Astro adapter for Pilvia App — prerendered pages become host-served assets, on-demand routes and Actions run in the isolate, the routes list is derived from Astro's own manifest.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pilvia/app.git",
+    "directory": "packages/astro"
+  },
+  "homepage": "https://pilvia.com",
+  "keywords": ["astro", "astro-adapter", "withastro", "pilvia"],
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./entrypoint": "./src/entrypoint.js"
+  },
+  "files": ["src", "README.md"],
+  "scripts": {
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0"
+  },
+  "dependencies": {
+    "buffer": "^6.0.3"
+  },
+  "devDependencies": {
+    "astro": "^5.16.0"
+  }
+}

package/src/compat.js

@@ -0,0 +1,16 @@
+// Bundle-layer workaround for a gap in the ENGINE (StarlingMonkey as shipped
+// by componentize-js) — not for any hosting platform's affordances. Guarded,
+// so it is a no-op the day the engine grows the real thing. The load-order-
+// sensitive shims (Intl, `process`) live in `preamble.js` instead, because an
+// import cannot run before the chunks Astro's entry imports ahead of us.
+//
+// Node's Buffer. Site code reaches for it casually (`Buffer.from(s).toString(
+// "base64")` for a Basic-auth header is the classic); this is the same
+// polyfill every bundler ships for browsers, and it is only needed at request
+// time, so import order does not matter. The trailing slash makes the bundler
+// pick the npm package over a Node builtin of the same name.
+import { Buffer } from "buffer/";
+
+if (typeof globalThis.Buffer === "undefined") {
+  globalThis.Buffer = Buffer;
+}

package/src/entrypoint.js

@@ -0,0 +1,75 @@
+// The server entry Astro builds around: `astro/app` behind the platform
+// contract, `export default { fetch(request, env) }`.
+//
+// By the time a request lands here the host has served every asset and
+// prerendered page itself and gated the rest on the routes list this adapter
+// derived — so the isolate sees only what Astro renders on demand. No asset
+// binding, no cache API, no platform module.
+
+import "./compat.js";
+import { App } from "astro/app";
+
+/**
+ * @param {import('astro').SSRManifest} manifest
+ */
+export function createExports(manifest) {
+  // Astro imports its server-islands encryption key eagerly (`decodeKey` →
+  // `crypto.subtle.importKey(… "AES-GCM" …)`) and stores the PROMISE in
+  // `manifest.key`, awaiting it only when a server island renders. The
+  // engine's WebCrypto has no AES-GCM yet, so that promise rejects at module
+  // init and, left unhandled, StarlingMonkey reports it after EVERY request
+  // ("Unhandled promise rejections detected after handling incoming
+  // request"). Mark it handled here; the rejection itself stays put, so a
+  // site that does render a server island still fails loudly at that point
+  // with the engine's own message.
+  if (manifest?.key && typeof manifest.key.catch === "function") {
+    manifest.key.catch(() => {});
+  }
+  const app = new App(manifest);
+
+  /**
+   * @param {Request} request
+   * @param {unknown} env the platform's capability object (`env.memory`,
+   *   `env.entities`, `env.user`, …) — surfaced to pages, endpoints,
+   *   middleware and Actions as `Astro.locals.env` / `context.locals.env`.
+   */
+  async function fetch(request, env) {
+    const routeData = app.match(request);
+    // The host stamps the real client on `x-real-ip` (PROXY protocol behind
+    // the isle's load balancer; the TLS peer otherwise).
+    const clientAddress = request.headers.get("x-real-ip") ?? undefined;
+    const response = await app.render(workable(request), {
+      routeData,
+      locals: { env },
+      clientAddress,
+    });
+    for (const cookie of app.setCookieHeaders(response)) {
+      response.headers.append("set-cookie", cookie);
+    }
+    return response;
+  }
+
+  return { default: { fetch } };
+}
+
+/**
+ * Engine workaround, still needed on componentize-js 0.22 (verified
+ * 2026-08-27): the fetch-event Request in StarlingMonkey is not an ordinary
+ * Request — its Headers are immutable, and on ≤ 0.21 `Request.clone()` on it
+ * threw; on 0.22 clone works, but an Actions form POST handed the event
+ * request as-is still answers 415 UNSUPPORTED_MEDIA_TYPE where the same body
+ * on a rebuilt Request validates. Hand Astro an ordinary Request; it costs a
+ * header copy. Re-test on each engine upgrade and drop when it passes.
+ * @param {Request} request
+ */
+function workable(request) {
+  const hasBody = request.method !== "GET" && request.method !== "HEAD";
+  return new Request(request.url, {
+    method: request.method,
+    headers: new Headers(request.headers),
+    body: hasBody ? request.body : undefined,
+    // A streamed body needs this on runtimes that check (spec'd, harmless
+    // where it is not).
+    duplex: "half",
+  });
+}

package/src/index.d.ts

@@ -0,0 +1,44 @@
+import type { AstroIntegration } from "astro";
+
+/** No options yet — the adapter derives everything from the Astro build. */
+export interface PilviaAdapterOptions {}
+
+/**
+ * The platform's capability object, as handed to `fetch(request, env)` and
+ * surfaced by this adapter as `Astro.locals.env`. Only the capabilities the
+ * app's manifest grants are live; the rest throw when called (fail closed).
+ * The authoritative surface is `crates/tuike/src/guest/entry.js` in
+ * `pilvia/app`; this type is deliberately loose until it is generated from
+ * the WIT world.
+ */
+export interface PilviaEnv {
+  /** Validated session claims of the signed-in user, or null when anonymous. */
+  user: Readonly<Record<string, unknown>> | null;
+  memory: {
+    search(query: string, opts?: Record<string, unknown>): Promise<unknown>;
+    list(opts?: Record<string, unknown>): Promise<unknown>;
+    get(id: string): Promise<unknown>;
+    write(content: string, opts?: Record<string, unknown>): Promise<unknown>;
+  };
+  entities: {
+    types(): Promise<unknown>;
+    list(filter?: Record<string, unknown>): Promise<unknown>;
+    get(ref: string | Record<string, unknown>): Promise<unknown>;
+    upsert(entity: Record<string, unknown>): Promise<unknown>;
+    upsertBatch(items: unknown[], opts?: Record<string, unknown>): Promise<unknown>;
+    link(from: string, rel: string, to: string): Promise<unknown>;
+  };
+  broker: { call(req: Record<string, unknown>): Promise<unknown> };
+  [capability: string]: unknown;
+}
+
+declare global {
+  namespace App {
+    interface Locals {
+      /** The Pilvia App capability object for this request. */
+      env: PilviaEnv;
+    }
+  }
+}
+
+export default function pilvia(options?: PilviaAdapterOptions): AstroIntegration;

package/src/index.js

@@ -0,0 +1,157 @@
+// @pilvia/astro — the Astro adapter for Pilvia App.
+//
+// What it does, and deliberately no more:
+//   * tells Astro to build for a server (`astro/app` + our entrypoint) with
+//     the web-platform half of the dependency graph (`webworker` target,
+//     everything bundled — the isolate has no node_modules);
+//   * points the image service at passthrough (sharp cannot run inside the
+//     isolate; prerendered pages are optimised at build time only if you
+//     configure a service that does so yourself);
+//   * after the build, writes `dist/pilvia.build.json`: where the server
+//     entry and the client assets are, and the routes Astro renders on
+//     demand — derived from Astro's own route manifest. `pilvia app deploy`
+//     reads it via `"build"` in `pilvia.app.json`.
+//
+// The host is the front door: it serves prerendered pages and assets itself
+// and hands the isolate only the declared routes, so this adapter needs no
+// asset binding, no cache API and no platform module — the platform
+// contract is `export default { fetch(request, env) }` and nothing else
+// (charter: docs/app-runtime.md → "Server side" → Layer 2).
+
+import { writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { relative } from "node:path";
+import { passthroughImageService } from "astro/config";
+import { PREAMBLE } from "./preamble.js";
+import { hostRoutes } from "./routes.js";
+
+const { version: VERSION } = createRequire(import.meta.url)("../package.json");
+
+const SHARP = "astro/assets/services/sharp";
+
+/**
+ * @param {import('./index.js').PilviaAdapterOptions} [options]
+ * @returns {import('astro').AstroIntegration}
+ */
+export default function pilvia(options = {}) {
+  /** @type {import('astro').AstroConfig} */
+  let config;
+  /** @type {import('astro').IntegrationResolvedRoute[]} */
+  let routes = [];
+  let buildOutput = "server";
+
+  return {
+    name: "@pilvia/astro",
+    hooks: {
+      "astro:config:setup": ({ config: cfg, updateConfig, logger }) => {
+        const update = {};
+        // Astro's default image service is sharp — native code, which the
+        // isolate cannot load. Swap it for passthrough unless the site chose
+        // something else on purpose.
+        if (!cfg.image?.service?.entrypoint || cfg.image.service.entrypoint === SHARP) {
+          update.image = { service: passthroughImageService() };
+          logger.info("image service: passthrough (sharp cannot run in the isolate)");
+        }
+        updateConfig(update);
+      },
+
+      "astro:config:done": ({ setAdapter, config: cfg, buildOutput: out }) => {
+        config = cfg;
+        buildOutput = out;
+        setAdapter({
+          name: "@pilvia/astro",
+          serverEntrypoint: "@pilvia/astro/entrypoint",
+          exports: ["default"],
+          adapterFeatures: {
+            edgeMiddleware: false,
+            buildOutput: out,
+          },
+          supportedAstroFeatures: {
+            staticOutput: "stable",
+            hybridOutput: "stable",
+            serverOutput: "stable",
+            i18nDomains: "unsupported",
+            // `astro:env` secrets: the isolate has no process env; the
+            // platform's `env` is `Astro.locals.env`. Wire getSecret to it
+            // when a site needs it.
+            envGetSecret: "unsupported",
+            sharpImageService: {
+              support: "limited",
+              message:
+                "sharp cannot run inside the Pilvia isolate; @pilvia/astro serves images as built (passthrough).",
+              suppress: "default",
+            },
+          },
+        });
+      },
+
+      "astro:routes:resolved": ({ routes: resolved }) => {
+        routes = resolved;
+      },
+
+      "astro:build:setup": ({ vite, target }) => {
+        if (target !== "server") return;
+        // The server bundle runs in a web-platform isolate: resolve the
+        // worker/browser half of every package and bundle all of it — there
+        // is no node_modules at runtime.
+        vite.ssr ||= {};
+        vite.ssr.target = "webworker";
+        vite.ssr.noExternal = true;
+        vite.ssr.resolve ||= {};
+        vite.ssr.resolve.conditions = [
+          "worker",
+          "browser",
+          "module",
+          "development|production",
+          ...(vite.ssr.resolve.conditions ?? []),
+        ];
+        // es-module-lexer's default entry instantiates a WebAssembly module at
+        // load; the isolate has no nested WebAssembly. Its `/js` entry is the
+        // same lexer compiled to plain JS — Astro only needs it for imports.
+        vite.resolve ||= {};
+        vite.resolve.alias ||= {};
+        const alias = { find: "es-module-lexer", replacement: "es-module-lexer/js" };
+        if (Array.isArray(vite.resolve.alias)) {
+          vite.resolve.alias.push(alias);
+        } else {
+          vite.resolve.alias[alias.find] = alias.replacement;
+        }
+        vite.build ||= {};
+        vite.build.rollupOptions ||= {};
+        vite.build.rollupOptions.output ||= {};
+        // Engine-gap workarounds that must run before any module body — see
+        // preamble.js. Rollup prepends a banner to every chunk.
+        const banner = vite.build.rollupOptions.output.banner;
+        vite.build.rollupOptions.output.banner =
+          typeof banner === "function"
+            ? async (chunk) => `${PREAMBLE}\n${await banner(chunk)}`
+            : `${PREAMBLE}\n${banner ?? ""}`;
+        vite.define = { "process.env": "process.env", ...vite.define };
+      },
+
+      "astro:build:done": async ({ logger }) => {
+        const outDir = config.outDir;
+        const rel = (url) => relative(fileURLToPath(outDir), fileURLToPath(url)).split("\\").join("/");
+        const desc = {
+          adapter: "@pilvia/astro",
+          version: VERSION,
+          assets: rel(config.build.client) || ".",
+        };
+        if (buildOutput === "server") {
+          desc.entry = rel(new URL(config.build.serverEntry, config.build.server));
+          desc.routes = hostRoutes(routes);
+        } else {
+          desc.routes = [];
+        }
+        await writeFile(new URL("./pilvia.build.json", outDir), `${JSON.stringify(desc, null, 2)}\n`);
+        logger.info(
+          desc.entry
+            ? `pilvia.build.json: ${desc.routes.length} on-demand route(s) → the isolate; everything else is a host-served asset`
+            : "pilvia.build.json: fully static — the host serves everything, no isolate",
+        );
+        void options;
+      },
+    },
+  };
+}

package/src/preamble.js

@@ -0,0 +1,24 @@
+// Text prepended to EVERY server chunk (Rollup `output.banner`), so it runs
+// before any module body — an `import` of a compat module cannot promise
+// that, because ESM evaluates imported chunks before the importer's own code
+// and Astro's generated entry imports its renderers and manifest ahead of
+// the adapter entrypoint.
+//
+// These are workarounds for gaps in the ENGINE (StarlingMonkey as shipped by
+// componentize-js), not for any hosting platform's affordances. Each is
+// guarded, so it is a no-op wherever the real thing exists — under bun/node
+// in tests, and in the engine the day it grows ICU. Charter: "anything
+// shim-shaped is scaffolding to be replaced by the engine's own surface,
+// never grown."
+export const PREAMBLE = [
+  // Astro's own emitted `import.meta.env` guard reads `process.env` at load.
+  "globalThis.process ??= {}; globalThis.process.env ??= {};",
+  // No ICU in the engine build. Astro's logger builds an Intl.DateTimeFormat
+  // at module scope for log timestamps, and its router calls `normalize` on
+  // route params. Identity/ISO stand-ins cover exactly those two uses.
+  'if (typeof globalThis.Intl === "undefined") { globalThis.Intl = {',
+  "  DateTimeFormat: class { format(d = new Date()) { return new Date(d).toISOString().slice(11, 19); } resolvedOptions() { return {}; } },",
+  "  NumberFormat: class { format(n) { return String(n); } resolvedOptions() { return {}; } },",
+  "}; }",
+  'if (typeof String.prototype.normalize !== "function") { Object.defineProperty(String.prototype, "normalize", { value() { return String(this); }, writable: true, configurable: true }); }',
+].join("\n");

package/src/routes.js

@@ -0,0 +1,59 @@
+// Astro's route manifest → the host's `routes` list.
+//
+// The host routes asset → declared route → fallback (charter: "The hosting
+// product"). Astro's own prerender/on-demand split maps onto that one-to-one:
+// a prerendered page is an asset the host serves, an on-demand page, endpoint
+// or the `/_actions/*` RPC route is a declared route the isolate answers.
+// Deriving the list here means nobody hand-writes it and it cannot drift
+// from the build.
+
+/**
+ * One Astro route pattern (`/blog/[slug]`, `/_actions/[...path]`) to the
+ * host's grammar: `:param` takes exactly one segment, a trailing `*` takes
+ * the rest of the path (Astro's `[...rest]`, zero or more segments).
+ *
+ * A segment that mixes literal text and a param (`[lang]-[slug]`,
+ * `page-[n]`) still occupies exactly one path segment, so it becomes a
+ * single `:param` — the host matches by segment count, Astro then matches
+ * the real pattern inside the isolate. A rest segment anywhere but last is
+ * a bug in the calling site, not something to guess around.
+ * @param {string} pattern
+ * @returns {string}
+ */
+export function toHostPattern(pattern) {
+  const segs = pattern.split("/").filter(Boolean);
+  const out = segs.map((seg, i) => {
+    if (/^\[\.\.\.[^\]]+\]$/.test(seg)) {
+      if (i !== segs.length - 1) {
+        throw new Error(`@pilvia/astro: rest segment must be last in ${pattern}`);
+      }
+      return "*";
+    }
+    if (seg.includes("[")) {
+      const name = seg.replace(/[[\]]/g, "").replace(/\.\.\./g, "").replace(/[^A-Za-z0-9_-]/g, "_");
+      return `:${name || "param"}`;
+    }
+    return seg;
+  });
+  return `/${out.join("/")}`;
+}
+
+/**
+ * The declared routes for a build: every route Astro renders on demand,
+ * whatever its origin (a page, an endpoint, Astro's own `/_actions`,
+ * `/_image`, `/_server-islands`, a server-side redirect). Prerendered routes
+ * are assets and stay out. Literals first, then by parameter count, so the
+ * list reads the way the host resolves it.
+ * @param {ReadonlyArray<{ pattern: string, isPrerendered: boolean, type: string }>} routes
+ * @returns {string[]}
+ */
+export function hostRoutes(routes) {
+  const seen = new Set();
+  for (const r of routes) {
+    if (r.isPrerendered) continue;
+    if (r.type === "fallback") continue; // i18n fallback stubs: Astro serves them from the real route
+    seen.add(toHostPattern(r.pattern));
+  }
+  const params = (p) => p.split("/").filter((s) => s.startsWith(":") || s === "*").length;
+  return [...seen].sort((a, b) => params(a) - params(b) || (a < b ? -1 : a > b ? 1 : 0));
+}