wawesome 0.3.0 → 0.4.0

package/README.md

@@ -231,10 +231,32 @@ Add `"assets"` to deploy static files beside your code:
 }
 ```
 
-Everything under that directory is deployed with the version, addressed by its path from the
-directory root. The CLI hashes each file and asks the platform which of them it does not already
-hold, so a redeploy that changed one chunk uploads one chunk — and a deploy that changed nothing at
-all is refused before a byte moves. Assets are not served yet.
+Everything under that directory is deployed with the version and served at its path beneath your
+Function's URL — `dist/client/assets/index-a1.js` answers at `https://<app-host>/<function>/assets/index-a1.js`.
+The CLI hashes each file and asks the platform which of them it does not already hold, so a redeploy
+that changed one chunk uploads one chunk — and a deploy that changed nothing at all is refused
+before a byte moves.
+
+Files are served straight from object storage; your Function is never invoked for one, and no
+invocation is recorded. They answer on your App's own hostname and nowhere else — on the
+development path form (`/x/<tenant>/<app>/<function>/...`) the same address reaches your handler
+as it always has, because a file on an origin every workspace shares would be same-origin with
+all of them. Each carries `Cache-Control: public, max-age=31536000, immutable` and an
+`ETag`, so name your build output by content hash — a file's bytes must never change under a name a
+browser has already cached for a year. The content type comes from the extension against a fixed
+allowlist and is never sniffed; anything off it is served as a download.
+
+Two rules to know about:
+
+- **Everything beneath `assets/` is static**, whatever the deploy carries. A request there never
+  reaches your handler — an unknown path under it is a 404, not a route for you to answer.
+- **At most 100 files may sit outside `assets/`.** Those paths travel on the version record so a
+  request can be routed without a lookup per file. Put bulk output under `assets/`, where a file
+  costs nothing; `favicon.ico`, `robots.txt` and a `.well-known/` directory are what the rest is
+  for.
+
+**HTML is refused at deploy time.** Your Function renders its own markup, and a document served from
+your App's own origin is the sharpest same-origin vector a static file has.
 
 ### Reserved headers
 

package/dist/index.mjs

@@ -5,12 +5,12 @@ import path from "node:path";
 import { build } from "esbuild";
 import os from "node:os";
 import { parse } from "acorn";
+import { spawnSync } from "node:child_process";
 import http from "node:http";
 import readline from "node:readline";
 import { Readable } from "node:stream";
 import crypto from "node:crypto";
 import { confirm, select } from "@inquirer/prompts";
-import { spawnSync } from "node:child_process";
 import zlib from "node:zlib";
 //#region src/config.ts
 /**
@@ -503,8 +503,6 @@ function collectBindings(node, bound, boundNodes, scope, functionValues, pending
 		case "AssignmentExpression":
 			bindAssignmentTarget(node.left, bound);
 			bindBody(node.left, node.right, scope, functionValues, pending);
-			break;
-		default: break;
 	}
 }
 function bindBody(target, value, scope, functionValues, pending) {
@@ -608,10 +606,7 @@ function bindPattern(node, bound, boundNodes) {
 		case "RestElement":
 			bindPattern(node.argument, bound, boundNodes);
 			break;
-		case "AssignmentPattern":
-			bindPattern(node.left, bound, boundNodes);
-			break;
-		default: break;
+		case "AssignmentPattern": bindPattern(node.left, bound, boundNodes);
 	}
 }
 function bindAssignmentTarget(target, bound) {
@@ -639,6 +634,49 @@ function isNode(value) {
 	return typeof value === "object" && value !== null && typeof value.type === "string";
 }
 //#endregion
+//#region src/project-build.ts
+/**
+* Run the command a project declares as the thing that produces its entry point.
+*
+* See **Produced entry point** in `CONTEXT.md` for why the PATH and `NODE_ENV`
+* are what they are.
+*/
+function runProjectBuild(command, projectDir, verbose = false) {
+	console.log(`[wawesome] Running the project's build (${command})...`);
+	const result = spawnSync(command, {
+		cwd: projectDir,
+		shell: true,
+		stdio: verbose ? "inherit" : [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		env: {
+			...process.env,
+			NODE_ENV: "production",
+			PATH: withBinDirectories(projectDir, process.env.PATH ?? "")
+		}
+	});
+	if (result.status === 0) return;
+	console.error(`[wawesome] Error: the project's build failed (${command}).`);
+	for (const stream of [result.stdout, result.stderr]) {
+		const text = stream?.toString().trim();
+		if (text) console.error(text);
+	}
+	process.exit(1);
+}
+function withBinDirectories(projectDir, existing) {
+	const dirs = [];
+	let current = path.resolve(projectDir);
+	for (;;) {
+		dirs.push(path.join(current, "node_modules", ".bin"));
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	return [...dirs, existing].join(path.delimiter);
+}
+//#endregion
 //#region src/build.ts
 /**
 * Bundles user TS/JS entry point into a single optimized ESM JavaScript file using esbuild.
@@ -649,6 +687,7 @@ async function buildJs(entryInput, options) {
 	const entry = entryInput || config?.entry || "src/index.ts";
 	const outPath = path.resolve(options.out);
 	const isVerbose = Boolean(options.verbose);
+	if (config?.build) runProjectBuild(config.build, process.cwd(), isVerbose);
 	if (!fs.existsSync(entry)) {
 		console.error(`[wawesome] Error: Entry file '${entry}' not found.`);
 		process.exit(1);
@@ -720,7 +759,7 @@ async function buildJs(entryInput, options) {
 * that has to name this version — `--version`, the dependency a scaffolded
 * project pins — reads it here, so a release bumps one file.
 */
-const CLI_VERSION = "0.3.0";
+const CLI_VERSION = "0.4.0";
 //#endregion
 //#region src/prompt.ts
 /**
@@ -1192,11 +1231,10 @@ const MONTHS = [
 ];
 /** Indented to sit inside the receipt the deploy already prints. */
 function headroomLines(usage) {
-	const lines = [
-		`  Plan:     ${usage.plan.name} — this deploy does not change your bill.`,
-		`  Apps:     ${usage.occupied_app_slots} / ${usage.plan.limits.app_slots} slots`,
-		`  Usage:    ${periodLabel(usage.period.start, usage.period.end)}`
-	];
+	const lines = [`  Plan:     ${usage.plan.name} — this deploy does not change your bill.`, `  Apps:     ${usage.occupied_app_slots} / ${usage.plan.limits.app_slots} slots`];
+	const stored = storedLine(usage);
+	if (stored !== null) lines.push(stored);
+	lines.push(`  Usage:    ${periodLabel(usage.period.start, usage.period.end)}`);
 	const entries = Object.entries(usage.allowances);
 	const labelWidth = widest(entries.map(([key]) => allowanceLabel(key)));
 	const amountWidth = widest(entries.map(([key, allowance]) => amount(key, allowance.used, allowance.limit)));
@@ -1209,6 +1247,17 @@ function headroomLines(usage) {
 	if (refused !== null) lines.push(`  Refused:  ${formatCount(refused)} request${refused === 1 ? "" : "s"} at your share`);
 	return lines;
 }
+/**
+* What the workspace holds against what its plan grants. Beside the App slots
+* rather than among the allowances below, because neither is spent over the
+* period those are read against.
+*/
+function storedLine(usage) {
+	const occupied = usage.occupied_stored_bytes;
+	const granted = usage.plan.limits.stored_bytes;
+	if (typeof occupied !== "number" || typeof granted !== "number") return null;
+	return `  Storage:  ${formatBytes(occupied)} / ${formatBytes(granted)}`;
+}
 function refusedAtShare(usage) {
 	const refused = usage.refusals?.at_granted_share;
 	if (typeof refused !== "number" || !Number.isFinite(refused) || refused <= 0) return null;
@@ -1265,6 +1314,21 @@ function widest(values) {
 	return values.reduce((longest, value) => Math.max(longest, value.length), 0);
 }
 //#endregion
+//#region src/billing.ts
+function billingPageUrl() {
+	const base = getDashboardUrl().replace(/\/+$/, "");
+	try {
+		return new URL("billing", `${base}/`).toString();
+	} catch {
+		return `${base}/billing`;
+	}
+}
+/** The rule itself is the gateway's prose, and is deliberately not restated here. */
+function planLimitAdvice(reason) {
+	if (reason !== "app-slots-exhausted" && reason !== "storage-exhausted") return "";
+	return `Where to resolve it: ${billingPageUrl()}`;
+}
+//#endregion
 //#region src/assets.ts
 /**
 * The files under `dir`, hashed.
@@ -1616,6 +1680,8 @@ async function uploadAssets(creds, app, funcName, bundle, assets, isVerbose) {
 			const errorBody = await res.text();
 			const refusal = rejectionOf(errorBody, res.status, `Upload of '${asset.path}' failed (HTTP ${res.status}).`);
 			console.error(`[wawesome] Error: ${refusal.message}`);
+			const advice = planLimitAdvice(refusal.reason);
+			if (advice) console.error(`[wawesome] ${advice}`);
 			if (isVerbose) console.error(`[wawesome:verbose] Response: ${errorBody}`);
 			process.exit(1);
 		}
@@ -1623,20 +1689,6 @@ async function uploadAssets(creds, app, funcName, bundle, assets, isVerbose) {
 	console.log(`[wawesome] ✅ ${toUpload.length} asset(s) uploaded.`);
 }
 //#endregion
-//#region src/billing.ts
-function billingPageUrl() {
-	const base = getDashboardUrl().replace(/\/+$/, "");
-	try {
-		return new URL("billing", `${base}/`).toString();
-	} catch {
-		return `${base}/billing`;
-	}
-}
-function appSlotAdvice(reason) {
-	if (reason !== "app-slots-exhausted") return "";
-	return `Where to resolve it: ${billingPageUrl()}`;
-}
-//#endregion
 //#region src/env.ts
 const STANDARD_SECRET_MESSAGES = [
 	"Encrypted at rest using AES-256",
@@ -2559,7 +2611,7 @@ async function wireUp(creds, appSlug, manifest, answers) {
 	try {
 		await ensureApp(creds, appSlug);
 	} catch (err) {
-		fail(errorText(err), ...[appSlotAdvice(reasonOf(err)), scaffolded].filter(Boolean));
+		fail(errorText(err), ...[planLimitAdvice(reasonOf(err)), scaffolded].filter(Boolean));
 	}
 	for (const { declared, value } of answers) {
 		if (!value) {

package/dist/vite.d.mts

@@ -0,0 +1,23 @@
+import { Plugin } from "vite";
+//#region src/vite.d.ts
+interface WawesomeReactOptions {
+  /** The module the browser hydrates from. */
+  client?: string;
+  /** The module exporting the `fetch` handler the platform invokes. */
+  server?: string;
+  /** The HTML document the shell is cut from. */
+  html?: string;
+}
+/**
+ * Builds a React application into the two halves the platform deploys: a client
+ * bundle uploaded as **Static assets**, and a server bundle that renders the
+ * document and streams it.
+ *
+ * The document's own HTML is inlined into the server bundle rather than uploaded
+ * with the rest: served statically at the mount root it would shadow the SSR
+ * route and answer with an empty shell that fails to hydrate. Every URL it
+ * carries is a **Request-time base** away from the mount.
+ */
+declare function wawesomeReact(options?: WawesomeReactOptions): Plugin;
+//#endregion
+export { WawesomeReactOptions, wawesomeReact as default, wawesomeReact };

package/dist/vite.mjs

@@ -0,0 +1,247 @@
+import { a as unsupportedGlobals, n as methodRemedy, r as polyfilledGlobals, t as declaredMethods } from "./guest-surface-CXON0L5V.mjs";
+import fs from "node:fs";
+import path from "node:path";
+//#region src/vite.ts
+const DOCUMENT_MODULE_ID = "virtual:wawesome/document";
+const BASE_MODULE_ID = "virtual:wawesome/base";
+const RESOLVED_DOCUMENT = `\0${DOCUMENT_MODULE_ID}`;
+const RESOLVED_BASE = `\0${BASE_MODULE_ID}`;
+/** Where the rendered application is spliced into the document. */
+const APP_MARKER = "<!--app-html-->";
+const BASE_GLOBAL = "__WAWESOME_BASE__";
+/**
+* Stands where the **Request-time base** goes. The document is escaped whole
+* and split on this afterwards, so no part of the markup can be read as the
+* interpolation.
+*/
+const BASE_SLOT = "\0wawesome-base\0";
+/**
+* Builds a React application into the two halves the platform deploys: a client
+* bundle uploaded as **Static assets**, and a server bundle that renders the
+* document and streams it.
+*
+* The document's own HTML is inlined into the server bundle rather than uploaded
+* with the rest: served statically at the mount root it would shadow the SSR
+* route and answer with an empty shell that fails to hydrate. Every URL it
+* carries is a **Request-time base** away from the mount.
+*/
+function wawesomeReact(options = {}) {
+	const clientEntry = normalize(options.client ?? "src/entry.client.tsx");
+	const serverEntry = normalize(options.server ?? "src/entry.server.tsx");
+	const htmlFile = normalize(options.html ?? "index.html");
+	let root = process.cwd();
+	let dev = null;
+	let clientBuild = null;
+	return {
+		name: "wawesome:react-ssr",
+		config(_userConfig, env) {
+			const building = env.command === "build";
+			return {
+				appType: "custom",
+				base: "./",
+				environments: {
+					client: { build: {
+						outDir: "dist/client",
+						rollupOptions: { input: { index: clientEntry } }
+					} },
+					ssr: {
+						define: building ? { "process.env.NODE_ENV": "\"production\"" } : absentGlobalDefines(root),
+						resolve: building ? {
+							noExternal: true,
+							external: [],
+							conditions: [
+								"workerd",
+								"worker",
+								"browser"
+							]
+						} : {},
+						build: {
+							outDir: "dist/server",
+							ssr: true,
+							sourcemap: true,
+							copyPublicDir: false,
+							rollupOptions: {
+								input: { index: serverEntry },
+								output: { codeSplitting: false }
+							}
+						}
+					}
+				},
+				builder: {
+					sharedConfigBuild: true,
+					async buildApp(builder) {
+						await builder.build(builder.environments.client);
+						await builder.build(builder.environments.ssr);
+					}
+				}
+			};
+		},
+		configResolved(config) {
+			root = config.root;
+		},
+		configureServer(server) {
+			dev = server;
+			reportUnenforceableGaps(server, root);
+			return () => {
+				server.middlewares.use((req, res, next) => {
+					render(server, serverEntry, req, res).catch(next);
+				});
+			};
+		},
+		hotUpdate({ file }) {
+			if (file !== path.join(root, htmlFile)) return;
+			const module = this.environment.moduleGraph.getModuleById(RESOLVED_DOCUMENT);
+			if (module) this.environment.moduleGraph.invalidateModule(module);
+			dev?.environments.client.hot.send({ type: "full-reload" });
+		},
+		generateBundle(_output, bundle) {
+			if (this.environment.name !== "client") return;
+			const entry = Object.values(bundle).find((chunk) => chunk.type === "chunk" && chunk.isEntry);
+			if (!entry || entry.type !== "chunk") {
+				this.error(`The client build produced no entry chunk for '${clientEntry}'.`);
+				return;
+			}
+			clientBuild = {
+				entry: entry.fileName,
+				stylesheets: [...entry.viteMetadata?.importedCss ?? []]
+			};
+		},
+		resolveId(id) {
+			if (id === DOCUMENT_MODULE_ID) return RESOLVED_DOCUMENT;
+			if (id === BASE_MODULE_ID) return RESOLVED_BASE;
+		},
+		async load(id) {
+			if (id === RESOLVED_BASE) return baseModule();
+			if (id !== RESOLVED_DOCUMENT) return;
+			const html = fs.readFileSync(path.join(root, htmlFile), "utf-8");
+			if (dev) return documentModule(await dev.transformIndexHtml("/", html), clientEntry, {
+				entry: clientEntry,
+				stylesheets: []
+			});
+			if (!clientBuild) {
+				this.error("The client bundle has not been built, so the document has no script to name. Build both environments together with `vite build`.");
+				return;
+			}
+			return documentModule(html, clientEntry, clientBuild);
+		}
+	};
+}
+/**
+* The globals the guest does not have, taken away from the application's own
+* modules while it is served locally.
+*
+* Rewritten in the application's source rather than deleted off the global
+* scope, because the dev server is Node and Vite's own logger formats its
+* timestamps with `Intl`. A reference becomes a name nothing defines, which is
+* the ReferenceError the guest gives, and `typeof` still answers "undefined".
+*/
+function absentGlobalDefines(projectDir) {
+	return Object.fromEntries(absentGlobals(projectDir).map((name) => [name, `__wawesome_absent_${name}`]));
+}
+/**
+* Read off the declaration rather than listed here, and skipped for a global the
+* project's manifest says it polyfills — the two rules the build's surface scan
+* applies, so local development cannot disagree with the deploy about what is
+* there.
+*/
+function absentGlobals(projectDir) {
+	const polyfilled = polyfilledGlobals(projectDir);
+	return unsupportedGlobals().map((entry) => entry.name).filter((name) => !polyfilled.has(name));
+}
+/**
+* The declared gaps this dev server cannot reproduce, said once at startup.
+*
+* The locale-sensitive methods are the quiet half of the **Declared guest
+* surface**: the engine has them and answers wrongly, so an application
+* formatting a price renders different markup here and in production. They
+* cannot be replaced on the prototypes, which are Node's own and shared with
+* Vite — its shortcut handler lowercases with one. So they are named instead,
+* and the two places that do hold an application to them are named with them:
+* `wawesome build` reports every use with the file and line, and a suite run
+* under `wawesome/vitest-setup` refuses them outright.
+*/
+function reportUnenforceableGaps(server, projectDir) {
+	const gone = absentGlobals(projectDir).join(", ");
+	const methods = declaredMethods().map((method) => `${method.target}.${method.name}`).join(", ");
+	if (gone) server.config.logger.info(`  wawesome  ${gone} is not defined here, as on the guest`);
+	server.config.logger.warn(`  wawesome  ${methods} still answer here and will not on the guest`);
+	server.config.logger.warn(`            ${methodRemedy()}`);
+	server.config.logger.warn("            `wawesome build` reports each use; `npm test` refuses them.");
+}
+/**
+* Drive the same handler the platform invokes, over the dev server's own module
+* graph, and write what it answers out as it arrives.
+*
+* No forwarded prefix is set, because locally there is no **Mount** to strip.
+*/
+async function render(server, serverEntry, req, res) {
+	const { runner } = server.environments.ssr;
+	const handler = await runner.import(`/${serverEntry}`);
+	const url = new URL(req.url ?? "/", "http://localhost");
+	const response = await handler.default.fetch(new Request(url, { method: req.method ?? "GET" }));
+	res.statusCode = response.status;
+	response.headers.forEach((value, name) => res.setHeader(name, value));
+	if (response.body) for await (const chunk of response.body) res.write(chunk);
+	res.end();
+}
+function baseModule() {
+	return [
+		`const held = typeof window === "undefined" ? undefined : window[${JSON.stringify(BASE_GLOBAL)}];`,
+		"export const base = typeof held === \"string\" ? held : \"\";",
+		""
+	].join("\n");
+}
+function documentModule(html, clientEntry, built) {
+	if (html.includes("\0")) throw new Error("The HTML document carries a NUL byte, which is where the request-time base goes.");
+	if (!html.includes(APP_MARKER)) throw new Error(`The HTML document has no ${APP_MARKER} for the application to render into.`);
+	const document = withStylesheets(withoutEntryScript(html, clientEntry), built.stylesheets);
+	const at = document.indexOf(APP_MARKER);
+	return [
+		`export const clientEntry = ${JSON.stringify(built.entry)};`,
+		"",
+		"export function documentShell(base) {",
+		`  return {`,
+		`    before: ${interpolated(document.slice(0, at))},`,
+		`    after: ${interpolated(document.slice(at + 15))},`,
+		`  };`,
+		"}",
+		"",
+		"export function baseScript(base) {",
+		"  // A `<` inside a script body ends the element carrying it, whatever the",
+		"  // JSON around it says.",
+		`  return "window[" + ${JSON.stringify(JSON.stringify(BASE_GLOBAL))} + "]=" +`,
+		"    JSON.stringify(base).replace(/</g, \"\\\\u003c\");",
+		"}",
+		""
+	].join("\n");
+}
+/**
+* The entry script is dropped from the document because React emits it itself,
+* as a bootstrap module whose URL carries the base — the same string the rest
+* of the document is built from.
+*/
+function withoutEntryScript(html, clientEntry) {
+	return html.replace(/[ \t]*<script\b[^>]*><\/script>\n?/g, (tag) => {
+		const src = /\bsrc=["']([^"']+)["']/.exec(tag);
+		return src && normalize(src[1]) === clientEntry ? "" : tag;
+	});
+}
+/**
+* Stylesheets go in as links rather than through React, so they are in the
+* bytes the shell is committed with — a stylesheet React discovers while
+* rendering arrives after the markup it styles.
+*/
+function withStylesheets(html, stylesheets) {
+	if (stylesheets.length === 0) return html;
+	const links = stylesheets.map((href) => `<link rel="stylesheet" href="${BASE_SLOT}/${href}">`).join("");
+	return html.includes("</head>") ? html.replace("</head>", `${links}</head>`) : links + html;
+}
+/** A JS expression for `html`, with the base slot as the one live piece. */
+function interpolated(html) {
+	return html.split(BASE_SLOT).map((part) => JSON.stringify(part)).join(" + base + ");
+}
+function normalize(file) {
+	return file.replace(/\\/g, "/").replace(/^\.?\//, "");
+}
+//#endregion
+export { wawesomeReact as default, wawesomeReact };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wawesome",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI tool for building and deploying serverless functions on wawesome.io platform",
   "type": "module",
   "bin": {
@@ -17,6 +17,13 @@
       "types": "./dist/guest-parity.d.mts",
       "default": "./dist/guest-parity.mjs"
     },
+    "./vite": {
+      "types": "./dist/vite.d.mts",
+      "default": "./dist/vite.mjs"
+    },
+    "./vite-env": {
+      "types": "./vite-env.d.ts"
+    },
     "./vitest-setup": {
       "types": "./dist/vitest-setup.d.mts",
       "default": "./dist/vitest-setup.mjs"
@@ -25,7 +32,8 @@
   },
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "vite-env.d.ts"
   ],
   "scripts": {
     "build": "tsdown",
@@ -45,9 +53,23 @@
   "devDependencies": {
     "@changesets/cli": "^2.31.1",
     "@types/node": "^26.1.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.4",
+    "@vitejs/plugin-react": "^6.1.0",
     "publint": "^0.3.22",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "tsdown": "^0.22.5",
     "typescript": "^7.0.2",
+    "vite": "^8.2.2",
     "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "vite": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
   }
 }

package/vite-env.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The modules `wawesome/vite` generates, as TypeScript sees them.
+ *
+ * Hand-written because they exist only during a build, so nothing can emit
+ * declarations for them. What they actually contain is `documentModule` and
+ * `baseModule` in `src/vite.ts`; the CLI's deploy-seam suite builds a real
+ * project and runs its bundle, which is what holds the two together.
+ *
+ * Reached through `"types": ["wawesome/vite-env"]` in a project's tsconfig.
+ */
+
+declare module "virtual:wawesome/document" {
+  /**
+   * The document with the rendered application cut out of it, resolved against
+   * `base` — the **Mount** the platform stripped off this request.
+   */
+  export function documentShell(base: string): { before: string; after: string };
+
+  /**
+   * The client bundle's path, relative to the mount. Joined to a base to become
+   * the module the browser hydrates from.
+   */
+  export const clientEntry: string;
+
+  /**
+   * A script body that hands `base` to the browser, for
+   * `renderToReadableStream`'s `bootstrapScriptContent`. It is what
+   * `virtual:wawesome/base` reads, so the hydrating client resolves its URLs
+   * against exactly what the server rendered against.
+   */
+  export function baseScript(base: string): string;
+}
+
+declare module "virtual:wawesome/base" {
+  /** The base the server rendered this document against. Empty at the root. */
+  export const base: string;
+}