wawesome 0.3.0 → 0.5.0

package/README.md

@@ -231,10 +231,110 @@ 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.
+
+**An SVG is served with script denied.** The rule behind the refusal above is that nothing you deploy
+as a file runs script on your App's own origin, and an SVG opened directly in a browser would. It is
+served rather than refused because denying it costs the file nothing: an `<img src="logo.svg">` never
+ran that script, so your drawings render as they always did — every SVG and XML file carries
+`Content-Security-Policy: script-src 'none'`, and only navigating straight to one loses anything.
+
+### Schedules
+
+Add `"schedules"` to run a Function on a recurring timer, with no caller:
+
+```json
+{
+  "app": "my-app",
+  "function": "nightly-reconcile",
+  "entry": "src/index.ts",
+  "schedules": [{ "name": "overnight", "expression": "0 3 * * *" }]
+}
+```
+
+An expression is **five fields, read in UTC** — minute, hour, day of month, month, day of week. There
+is no seconds field, and no timezone: a local zone would make one night a year fire a job twice and
+another night not at all.
+
+The name is yours to choose and is what the platform keys the schedule by, so editing an expression
+is a change to the same schedule rather than the deletion of one and the creation of another — its
+history and its paused state stay attached to it.
+
+Your deploy applies them and prints each one with the time it will next run. It is refused, before
+anything is built or uploaded, if an expression cannot be read, if it would run more often than every
+five minutes, or if one Function declares more than five schedules.
+
+Two rules worth knowing before you edit the file:
+
+- **A schedule you delete from the file is disabled, not deleted.** Its history stays, and declaring
+  it again is what turns it back on — so a typo costs you a deploy rather than a job's record.
+- **A deploy never resumes a schedule a person paused.** When it runs is code; whether it is running
+  is not, and an unrelated commit the next morning must not restart what you stopped at 3am.
+
+Leaving `schedules` out of the file entirely says nothing about them and changes nothing. Writing
+`"schedules": []` says this Function declares none, which disables the ones it used to have.
+
+### Keeping a Function off the web
+
+A job on a timer should not also be sitting at a guessable URL where a stranger can fire it. Add
+`"visibility"` to make a Function unreachable from the internet:
+
+```json
+{
+  "app": "my-app",
+  "function": "nightly-reconcile",
+  "entry": "src/index.ts",
+  "visibility": "private"
+}
+```
+
+A private Function has **no address at all** — not a hidden one, not one behind a credential. A
+request for it is answered with the same 404 as a Function that was never deployed, on your App's
+own hostname and on the development path form alike. This is how you deploy a job with side effects
+without leaving it where a stranger who guesses the slug can fire it.
+
+Leave the line out and your Function is public, which is what every Function without it has always
+been.
+
+Today that is all a private Function is: there is no way *in* to one yet. Schedules do not fire yet,
+and the authenticated trigger that runs a Function by hand is not built — so make one private when
+you want it off the web, and expect to publish it again to call it until those land.
+
+Making a Function private takes nothing but the deploy. Making it public again does not: deleting
+the line is refused, and the deploy tells you so having written nothing.
+
+```bash
+npx wawesome deploy --publish
+```
+
+That is deliberate — the line that keeps a job off the internet is one line, and a deploy that
+quietly honoured its deletion would put the job back on the open internet with nothing said. Every
+deploy prints the visibility it landed, beside the URL or in place of it.
 
 ### Reserved headers
 
@@ -243,11 +343,12 @@ handler sees it, and off your response before the caller does — so **do not na
 on that prefix**: it is dropped silently rather than rejected, and you will not get an error telling
 you why it vanished.
 
-Three headers arrive or leave on it, and the stripping is what makes them worth trusting:
+Four headers arrive or leave on it, and the stripping is what makes them worth trusting:
 
 | Header | Direction | What it means |
 | --- | --- | --- |
 | `x-wawesome-forwarded-prefix` | inbound | The mount that was stripped from the path. Join it to the path you observe to rebuild the caller's URL. |
+| `x-wawesome-trigger` | inbound | How this run started: `caller` when someone called your address. A caller cannot forge it, so you may skip your own authorization on anything else and open nothing. |
 | `x-wawesome-invocation-id` | outbound | The id of this run — the key to fetch its logs with `npx wawesome logs --invocation <id>`. |
 | `x-wawesome-error` | outbound | Present only when the platform failed, never when your Function did. Its *absence* means the status on the wire is yours — up to the moment your response is committed, and no further. |
 

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.5.0";
 //#endregion
 //#region src/prompt.ts
 /**
@@ -1116,6 +1155,42 @@ async function whoami() {
 	console.log(`  Gateway:   ${creds.gateway_url}\n`);
 }
 //#endregion
+//#region src/schedules.ts
+/**
+* When a schedule next runs, or why it does not run at all.
+*
+* The three ways of being off never render alike: someone who cannot tell a
+* pause from a schedule they deleted from their config file will press resume
+* and watch nothing happen.
+*/
+function whenItRuns(schedule) {
+	switch (schedule.state) {
+		case "active": return schedule.next_fire_at ? `next run ${asUtc(schedule.next_fire_at)}` : "next run unknown";
+		case "paused": return "paused — resume it to run again";
+		case "undeclared": return "not in this config file — disabled, kept";
+		case "suspended": return "suspended — the workspace owes payment";
+		default: return schedule.state;
+	}
+}
+/** `2026-08-23 03:00 UTC`, which is the zone every expression is read in. */
+function asUtc(iso) {
+	const at = new Date(iso);
+	if (Number.isNaN(at.getTime())) return iso;
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${at.getUTCFullYear()}-${pad(at.getUTCMonth() + 1)}-${pad(at.getUTCDate())} ${pad(at.getUTCHours())}:${pad(at.getUTCMinutes())} UTC`;
+}
+/**
+* The block a deploy prints for the schedules it just applied. Every schedule
+* appears, including the ones that are off, so putting recurring compute on the
+* bill — or taking it off — is never silent.
+*/
+function scheduleLines(schedules) {
+	if (schedules.length === 0) return [];
+	const nameWidth = Math.max(...schedules.map((s) => s.name.length));
+	const expressionWidth = Math.max(...schedules.map((s) => s.expression.length));
+	return ["  Schedules:", ...[...schedules].sort((a, b) => a.name.localeCompare(b.name)).map((schedule) => `    ${schedule.name.padEnd(nameWidth)}  ${schedule.expression.padEnd(expressionWidth)}  ${whenItRuns(schedule)}`)];
+}
+//#endregion
 //#region src/usage.ts
 const USAGE_TIMEOUT_MS = 2e3;
 /**
@@ -1192,11 +1267,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 +1283,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 +1350,27 @@ 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`;
+	}
+}
+/** Refusals whose remedy is on the billing page and nowhere else. */
+const PLAN_LIMITS = [
+	"app-slots-exhausted",
+	"storage-exhausted",
+	"paid-plan-required"
+];
+/** The rule itself is the gateway's prose, and is deliberately not restated here. */
+function planLimitAdvice(reason) {
+	if (!reason || !PLAN_LIMITS.includes(reason)) return "";
+	return `Where to resolve it: ${billingPageUrl()}`;
+}
+//#endregion
 //#region src/assets.ts
 /**
 * The files under `dir`, hashed.
@@ -1408,6 +1514,31 @@ function trimTrailingSlashes(origin) {
 }
 //#endregion
 //#region src/deploy.ts
+function declaredFields(declared) {
+	return {
+		...declared.visibility ? { visibility: declared.visibility } : {},
+		...declared.confirmPublish ? { confirm_publish: true } : {}
+	};
+}
+/**
+* The visibility this project declares, refused here rather than at the gateway
+* so a typo is a message at the keyboard.
+*/
+function declaredVisibility(value) {
+	if (value === void 0 || value === null) return void 0;
+	if (value === "public" || value === "private") return value;
+	console.error(`[wawesome] Error: 'visibility' in wawesome-function.json is '${String(value)}'.`);
+	console.error("[wawesome] It must be \"public\" or \"private\".");
+	process.exit(1);
+}
+function reportPublishRefusal(message) {
+	console.error(`\n[wawesome] \x1b[31mError: ${message}\x1b[0m`);
+	console.error("[wawesome] Nothing was deployed. This Function is private, so its address");
+	console.error("[wawesome] resolves for nobody — publishing it puts it back on the open");
+	console.error("[wawesome] internet.");
+	console.error("[wawesome] Re-run with \x1B[36mwawesome deploy --publish\x1B[0m to publish it, or put");
+	console.error("[wawesome] \x1B[36m\"visibility\": \"private\"\x1B[0m back in wawesome-function.json.\n");
+}
 /**
 * Deploy a function: build → upload JS to gateway → promote.
 */
@@ -1425,6 +1556,10 @@ async function deploy(entryInput, options) {
 		process.exit(1);
 	}
 	const { app, function: funcName } = config;
+	const declared = {
+		visibility: declaredVisibility(config.visibility),
+		confirmPublish: Boolean(options.publish)
+	};
 	if (isVerbose) {
 		console.log(`[wawesome:verbose] Deploying to app=${app}, function=${funcName}`);
 		console.log(`[wawesome:verbose] Gateway: ${creds.gateway_url}`);
@@ -1456,12 +1591,14 @@ async function deploy(entryInput, options) {
 		for (const line of surfaceReportLines(findings)) (refused ? console.error : console.warn)(line);
 		if (refused) process.exit(1);
 	}
+	const declaresSchedules = config.schedules !== void 0;
 	const assets = config.assets ? collectAssets(path.resolve(config.assets)) : [];
-	if (assets.length > 0) await uploadAssets(creds, app, funcName, jsCode, assets, isVerbose);
+	if (assets.length > 0) await uploadAssets(creds, app, funcName, jsCode, assets, declared, isVerbose, declaresSchedules);
 	console.log(`[wawesome] Uploading code for ${app}/${funcName}...`);
 	const uploadUrl = `${creds.gateway_url}/v1/apps/${encodeURIComponent(app)}/functions/${encodeURIComponent(funcName)}/code`;
 	if (isVerbose) console.log(`[wawesome:verbose] POST ${uploadUrl}`);
-	const uploadRes = assets.length > 0 ? await fetch(uploadUrl, {
+	const declaredOnTheWire = declaredFields(declared);
+	const uploadRes = assets.length > 0 || declaresSchedules || Object.keys(declaredOnTheWire).length > 0 ? await fetch(uploadUrl, {
 		method: "POST",
 		headers: {
 			Authorization: `Bearer ${creds.tenant_jwt}`,
@@ -1469,7 +1606,9 @@ async function deploy(entryInput, options) {
 		},
 		body: JSON.stringify({
 			code: jsCode,
-			assets: manifestOf(assets)
+			...assets.length > 0 ? { assets: manifestOf(assets) } : {},
+			...declaresSchedules ? { schedules: config.schedules } : {},
+			...declaredOnTheWire
 		})
 	}) : await fetch(uploadUrl, {
 		method: "POST",
@@ -1481,9 +1620,16 @@ async function deploy(entryInput, options) {
 	});
 	if (!uploadRes.ok) {
 		const errorBody = await uploadRes.text();
+		const refusal = rejectionOf(errorBody, uploadRes.status, "Version with this code bundle already exists.");
 		if (uploadRes.status === 401) console.error("[wawesome] Error: Authentication expired. Run 'wawesome login' again.");
-		else if (uploadRes.status === 409) {
-			const refusal = rejectionOf(errorBody, uploadRes.status, "Version with this code bundle already exists.");
+		else if (refusal.reason === "paid-plan-required") {
+			console.error(`\n[wawesome] \x1b[31mError: ${refusal.message}\x1b[0m`);
+			console.error(`[wawesome] ${planLimitAdvice(refusal.reason)}\n`);
+		} else if (uploadRes.status === 409) {
+			if (refusal.reason === "publish-needs-confirmation") {
+				reportPublishRefusal(refusal.message);
+				process.exit(1);
+			}
 			console.error(`\n[wawesome] \x1b[31mError: ${refusal.message}\x1b[0m`);
 			console.error("[wawesome] Code versions are immutable and cannot be overwritten.");
 			console.error("[wawesome] To switch active version, run: \x1B[36mwawesome version switch\x1B[0m\n");
@@ -1493,33 +1639,40 @@ async function deploy(entryInput, options) {
 		}
 		process.exit(1);
 	}
-	const version = (await uploadRes.json()).version_number;
-	console.log(`[wawesome] ✅ Code uploaded (version ${version ?? "unknown"}).`);
-	console.log(`[wawesome] Promoting to production...`);
-	const deployUrl = `${creds.gateway_url}/v1/apps/${encodeURIComponent(app)}/functions/${encodeURIComponent(funcName)}/deploy`;
-	if (isVerbose) console.log(`[wawesome:verbose] POST ${deployUrl}`);
-	const deployBody = {};
-	if (version !== void 0) deployBody.version_number = version;
-	const deployRes = await fetch(deployUrl, {
-		method: "POST",
-		headers: {
-			Authorization: `Bearer ${creds.tenant_jwt}`,
-			"Content-Type": "application/json"
-		},
-		body: JSON.stringify(deployBody)
-	});
-	if (!deployRes.ok) {
-		const errorBody = await deployRes.text();
-		if (deployRes.status === 401) console.error("[wawesome] Error: Authentication expired. Run 'wawesome login' again.");
-		else {
-			console.error(`[wawesome] Error: Deployment failed (HTTP ${deployRes.status}).`);
-			if (isVerbose) console.error(`[wawesome:verbose] Response: ${errorBody}`);
+	const uploadData = await uploadRes.json();
+	const version = uploadData.version_number;
+	const schedules = uploadData.schedules ?? [];
+	const visibility = uploadData.visibility ?? declared.visibility ?? "public";
+	const nothingBuilt = uploadData.status === "declarations-updated";
+	if (nothingBuilt) console.log(`[wawesome] ✅ Code and files unchanged (version ${version ?? "unknown"}); what the config file declares applied.`);
+	else console.log(`[wawesome] ✅ Code uploaded (version ${version ?? "unknown"}).`);
+	if (!nothingBuilt) {
+		console.log(`[wawesome] Promoting to production...`);
+		const deployUrl = `${creds.gateway_url}/v1/apps/${encodeURIComponent(app)}/functions/${encodeURIComponent(funcName)}/deploy`;
+		if (isVerbose) console.log(`[wawesome:verbose] POST ${deployUrl}`);
+		const deployBody = {};
+		if (version !== void 0) deployBody.version_number = version;
+		const deployRes = await fetch(deployUrl, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${creds.tenant_jwt}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify(deployBody)
+		});
+		if (!deployRes.ok) {
+			const errorBody = await deployRes.text();
+			if (deployRes.status === 401) console.error("[wawesome] Error: Authentication expired. Run 'wawesome login' again.");
+			else {
+				console.error(`[wawesome] Error: Deployment failed (HTTP ${deployRes.status}).`);
+				if (isVerbose) console.error(`[wawesome:verbose] Response: ${errorBody}`);
+			}
+			process.exit(1);
 		}
-		process.exit(1);
 	}
 	let address = null;
 	let surface = null;
-	try {
+	if (visibility === "public") try {
 		const { slug } = await resolveWorkspace(creds);
 		surface = await fetchInvocationSurface(creds.gateway_url);
 		address = publicAddress(surface, slug, app, funcName);
@@ -1533,19 +1686,27 @@ async function deploy(entryInput, options) {
 		if (isVerbose) console.log(`[wawesome:verbose] Could not read the plan's usage: ${errorText(err)}`);
 	}
 	console.log("\n======================================================");
-	console.log("🚀 \x1B[32mDEPLOYED SUCCESSFULLY!\x1B[0m");
+	console.log(nothingBuilt ? "🕒 \x1B[32mCONFIGURATION APPLIED\x1B[0m" : "🚀 \x1B[32mDEPLOYED SUCCESSFULLY!\x1B[0m");
 	console.log("======================================================");
-	console.log(`\n  App:      ${app}`);
-	console.log(`  Function: ${funcName}`);
-	if (version !== void 0) console.log(`  Version:  ${version}`);
-	if (assets.length > 0) console.log(`  Assets:   ${assets.length}`);
-	if (address) {
-		console.log(`\n  URL:      \x1b[36m${address}\x1b[0m`);
-		console.log(`            ${SUBTREE_NOTE}`);
+	console.log(`\n  App:        ${app}`);
+	console.log(`  Function:   ${funcName}`);
+	if (version !== void 0) console.log(`  Version:    ${version}${nothingBuilt ? " (already live, nothing promoted)" : ""}`);
+	if (assets.length > 0) console.log(`  Assets:     ${assets.length}`);
+	console.log(`  Visibility: ${visibility}`);
+	if (schedules.length > 0) {
+		console.log("");
+		for (const line of scheduleLines(schedules)) console.log(line);
+	}
+	if (visibility === "private") {
+		console.log("\n  URL:        none — this Function is private, so it is not reachable");
+		console.log("              from the web at all.");
+	} else if (address) {
+		console.log(`\n  URL:        \x1b[36m${address}\x1b[0m`);
+		console.log(`              ${SUBTREE_NOTE}`);
 	} else if (surface) {
-		console.log("\n  URL:      none — this gateway serves no public address form.");
-		console.log("            Set CONTENT_ORIGIN on it, or ALLOW_PATH_INVOCATION_FORM");
-		console.log("            for local development.");
+		console.log("\n  URL:        none — this gateway serves no public address form.");
+		console.log("              Set CONTENT_ORIGIN on it, or ALLOW_PATH_INVOCATION_FORM");
+		console.log("              for local development.");
 	}
 	if (headroom) {
 		console.log("");
@@ -1556,7 +1717,8 @@ async function deploy(entryInput, options) {
 		app,
 		functionName: funcName,
 		version,
-		address
+		address,
+		schedules
 	};
 }
 /**
@@ -1566,7 +1728,7 @@ async function deploy(entryInput, options) {
 * The identity of the whole deploy goes with the question, so a redeploy that
 * changed nothing at all is refused here — before a byte of it has moved.
 */
-async function uploadAssets(creds, app, funcName, bundle, assets, isVerbose) {
+async function uploadAssets(creds, app, funcName, bundle, assets, declared, isVerbose, continueWhenUnchanged) {
 	const manifestUrl = `${creds.gateway_url}/v1/apps/${encodeURIComponent(app)}/functions/${encodeURIComponent(funcName)}/assets/manifest`;
 	const manifestRes = await fetch(manifestUrl, {
 		method: "POST",
@@ -1576,14 +1738,23 @@ async function uploadAssets(creds, app, funcName, bundle, assets, isVerbose) {
 		},
 		body: JSON.stringify({
 			deploy_digest: deployDigest(Buffer.from(bundle, "utf-8"), assets),
-			assets: manifestOf(assets)
+			assets: manifestOf(assets),
+			...declaredFields(declared)
 		})
 	});
 	if (!manifestRes.ok) {
 		const errorBody = await manifestRes.text();
 		if (manifestRes.status === 401) console.error("[wawesome] Error: Authentication expired. Run 'wawesome login' again.");
 		else if (manifestRes.status === 409) {
+			if (continueWhenUnchanged) {
+				console.log("[wawesome] Code and files unchanged since the last deploy; applying schedules.");
+				return;
+			}
 			const refusal = rejectionOf(errorBody, manifestRes.status, "This deploy is already deployed.");
+			if (refusal.reason === "publish-needs-confirmation") {
+				reportPublishRefusal(refusal.message);
+				process.exit(1);
+			}
 			console.error(`\n[wawesome] \x1b[31mError: ${refusal.message}\x1b[0m`);
 			console.error("[wawesome] Nothing changed since the last deploy, so nothing was uploaded.\n");
 		} else {
@@ -1616,6 +1787,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 +1796,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 +2718,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) {
@@ -3543,7 +3702,7 @@ async function workspaceCommand(action, target, options) {
 //#region src/index.ts
 const cli = cac("wawesome");
 cli.command("build [entry]", "Bundle a serverless function to an optimized JS file").option("-o, --out <path>", "Output JS bundle path", { default: "dist/index.js" }).option("-v, --verbose", "Enable verbose debug output").action((entry, options) => buildJs(entry, options));
-cli.command("deploy [entry]", "Build, upload, and promote a serverless function").option("-o, --out <path>", "Output JS bundle path", { default: "dist/index.js" }).option("-v, --verbose", "Enable verbose debug output").option("--skip-build", "Skip the build step, deploy an already-built bundle").action((entry, options) => deploy(entry, options));
+cli.command("deploy [entry]", "Build, upload, and promote a serverless function").option("-o, --out <path>", "Output JS bundle path", { default: "dist/index.js" }).option("-v, --verbose", "Enable verbose debug output").option("--skip-build", "Skip the build step, deploy an already-built bundle").option("--publish", "Confirm putting a private function back on its public address").action((entry, options) => deploy(entry, options));
 cli.command("version [action] [target]", "Manage versions (e.g. 'version list', 'version switch [version]')").option("-e, --env <environment>", "Target environment (default: production)").option("-v, --verbose", "Enable verbose debug output").action((action, target, options) => {
 	if (!action || action === "list" || action === "ls") return listVersions(options);
 	if (action === "switch" || action === "use" || action === "select") return switchVersion(target, options);

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.5.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;
+}