wawesome 0.0.14 → 0.1.0

package/README.md

@@ -114,6 +114,26 @@ npx wawesome deploy
 
 ---
 
+## 🧭 Unsupported Globals
+
+Every build scans the bundle it just produced against the platform's declared guest surface, and says
+nothing unless it finds something.
+
+- **`Intl` is not provided.** Where the bundle reaches it as it loads — your own module scope, or a
+  dependency's — the build is refused before a deploy uploads anything: that bundle would not
+  evaluate on the platform. Where the reference sits inside a function that may never be called,
+  behind a `typeof` check, or inside a `try`, you get a warning and the deploy proceeds.
+- **`toLocaleString`, `toLocaleDateString`, `toLocaleTimeString`, `toLocaleLowerCase` and
+  `toLocaleUpperCase` ignore their locale argument.** They run and return an unlocalised answer, so
+  these warn.
+
+Each message names the global, the file and line in *your* source, and what to do about it. Declaring
+an `Intl` polyfill in your `package.json` — the same declaration [local parity
+reads](#testing-against-the-guests-javascript-surface) — silences the report, as does installing one
+on `globalThis` in the bundle itself. The scan reads static references only: a global reached through
+`globalThis['Intl']` is invisible to it, so it never refuses a deploy on a guess. `deploy
+--skip-build` scans the bundle it found on disk before uploading it.
+
 ## 📜 Invocation Logs
 
 Inspect past function runs or view raw `stdout` / `stderr` log outputs directly in your terminal.
@@ -200,6 +220,22 @@ Every project directory includes a `wawesome-function.json` file generated durin
 `app` is the App this Function is deployed into, and it is client-facing — every deploy from this
 directory is scoped to it.
 
+Add `"assets"` to deploy static files beside your code:
+
+```json
+{
+  "app": "my-app",
+  "function": "hello-world",
+  "entry": "src/index.ts",
+  "assets": "dist/client"
+}
+```
+
+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.
+
 ### Reserved headers
 
 `x-wawesome-*` belongs to the platform in both directions. It is stripped off the request before your
@@ -215,6 +251,33 @@ Three headers arrive or leave on it, and the stripping is what makes them worth
 | `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. |
 
+### Testing against the guest's JavaScript surface
+
+Your Function does not run on Node. The engine has no `Intl`, and its `toLocaleString` ignores the
+locale you pass — `(1234.5).toLocaleString('en-US')` comes back as `"1234.5"`, not `"1,234.50"`. On
+Node both work, which is how a green suite ships a Function that throws in production, or renders
+markup the browser then refuses to hydrate.
+
+Point your test suite at the guest's surface instead:
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: { setupFiles: ["wawesome/vitest-setup"] },
+});
+```
+
+Templates scaffolded with `wawesome init --template` ship this already. With it in place `Intl` is
+gone, `MessageChannel` is the platform's own implementation rather than Node's, and the
+locale-sensitive methods throw with a message naming the remedy — they throw rather than return the
+engine's unlocalised answer because the platform declares them unsupported, and a wrong string that
+fails nowhere is the thing this is here to stop you shipping.
+
+If you bundle an `Intl` polyfill, declare it in your `package.json` as you normally would — a
+dependency that provides `Intl` is left in place rather than stripped out from under you.
+
 ### Local Development / Gateway Overrides
 
 If you are running a local gateway or self-hosted instance, you can configure your CLI Gateway URL using any of the

package/dist/guest-parity-Df4rlLDW.mjs

@@ -0,0 +1,168 @@
+import { a as unsupportedGlobals, i as shimmedGlobals, n as methodRemedy, r as polyfilledGlobals, t as declaredMethods } from "./guest-surface-CXON0L5V.mjs";
+//#region ../../server/guest-surface/message-channel.js
+const ENTANGLED = Symbol("entangled");
+const QUEUE = Symbol("queue");
+const STARTED = Symbol("started");
+const CLOSED = Symbol("closed");
+const LISTENERS = Symbol("listeners");
+const ONMESSAGE = Symbol("onmessage");
+var MessagePort = class {
+	constructor() {
+		this[ENTANGLED] = null;
+		this[QUEUE] = [];
+		this[STARTED] = false;
+		this[CLOSED] = false;
+		this[LISTENERS] = [];
+		this[ONMESSAGE] = null;
+		this.onmessageerror = null;
+	}
+	get onmessage() {
+		return this[ONMESSAGE];
+	}
+	set onmessage(handler) {
+		this[ONMESSAGE] = handler;
+		if (handler) this.start();
+	}
+	start() {
+		if (this[STARTED]) return;
+		this[STARTED] = true;
+		drain(this);
+	}
+	close() {
+		this[CLOSED] = true;
+		const peer = this[ENTANGLED];
+		this[ENTANGLED] = null;
+		if (peer) peer[ENTANGLED] = null;
+	}
+	postMessage(data) {
+		const peer = this[ENTANGLED];
+		if (!peer || peer[CLOSED]) return;
+		peer[QUEUE].push(data);
+		if (peer[STARTED]) drain(peer);
+	}
+	addEventListener(type, listener) {
+		if (type !== "message" || !listener) return;
+		this[LISTENERS].push(listener);
+	}
+	removeEventListener(type, listener) {
+		if (type !== "message") return;
+		const at = this[LISTENERS].indexOf(listener);
+		if (at !== -1) this[LISTENERS].splice(at, 1);
+	}
+	dispatchEvent(event) {
+		deliver(this, event);
+		return true;
+	}
+};
+function drain(port) {
+	if (port[QUEUE].length === 0) return;
+	const data = port[QUEUE].shift();
+	setTimeout(() => {
+		if (port[CLOSED]) return;
+		deliver(port, {
+			type: "message",
+			data,
+			target: port,
+			ports: []
+		});
+		drain(port);
+	}, 0);
+}
+function deliver(port, event) {
+	if (typeof port.onmessage === "function") port.onmessage(event);
+	for (const listener of port[LISTENERS].slice()) if (typeof listener === "function") listener.call(port, event);
+	else if (listener && typeof listener.handleEvent === "function") listener.handleEvent(event);
+}
+var MessageChannel = class {
+	constructor() {
+		this.port1 = new MessagePort();
+		this.port2 = new MessagePort();
+		this.port1[ENTANGLED] = this.port2;
+		this.port2[ENTANGLED] = this.port1;
+	}
+};
+//#endregion
+//#region ../../server/guest-surface/locale-methods.js
+function installUnsupportedLocaleMethods(scope, methods, remedy) {
+	const replaced = [];
+	for (const { target, name } of methods) {
+		const owner = resolve(scope, target);
+		if (!owner || typeof owner[name] !== "function") continue;
+		const message = `wawesome: ${target}.${name} is not supported — ${remedy}.`;
+		const thrower = function() {
+			throw new TypeError(message);
+		};
+		Object.defineProperty(thrower, "name", {
+			value: name,
+			configurable: true
+		});
+		replaced.push({
+			target,
+			name,
+			owner,
+			previous: Object.getOwnPropertyDescriptor(owner, name)
+		});
+		Object.defineProperty(owner, name, {
+			value: thrower,
+			writable: true,
+			enumerable: false,
+			configurable: true
+		});
+	}
+	return replaced;
+}
+function resolve(scope, target) {
+	return target.split(".").reduce((current, part) => current == null ? current : current[part], scope);
+}
+//#endregion
+//#region src/guest-parity.ts
+const SHIMS = {
+	MessageChannel,
+	MessagePort
+};
+function applyGuestParity(options = {}) {
+	const scope = globalThis;
+	const polyfilled = polyfilledGlobals(options.projectDir ?? process.cwd());
+	const undo = [];
+	const removed = [];
+	const exempted = [];
+	for (const entry of unsupportedGlobals()) {
+		if (polyfilled.has(entry.name)) {
+			exempted.push(entry.name);
+			continue;
+		}
+		const descriptor = Object.getOwnPropertyDescriptor(scope, entry.name);
+		if (!descriptor) continue;
+		undo.push(() => Object.defineProperty(scope, entry.name, descriptor));
+		delete scope[entry.name];
+		removed.push(entry.name);
+	}
+	const shimmed = [];
+	for (const entry of shimmedGlobals()) {
+		const replacement = SHIMS[entry.name];
+		if (!replacement) throw new Error(`wawesome: the guest surface declares ${entry.name} as a platform shim, and no implementation is registered for it.`);
+		const descriptor = Object.getOwnPropertyDescriptor(scope, entry.name);
+		undo.push(() => {
+			if (descriptor) Object.defineProperty(scope, entry.name, descriptor);
+			else delete scope[entry.name];
+		});
+		scope[entry.name] = replacement;
+		shimmed.push(entry.name);
+	}
+	const replaced = installUnsupportedLocaleMethods(scope, declaredMethods(), methodRemedy());
+	undo.push(() => {
+		for (const { owner, name, previous } of replaced) if (previous) Object.defineProperty(owner, name, previous);
+	});
+	return {
+		removed,
+		shimmed,
+		replacedMethods: replaced.map(({ target, name }) => `${target}.${name}`),
+		exempted,
+		restore() {
+			for (const step of undo.reverse()) step();
+			undo.length = 0;
+		}
+	};
+}
+//#endregion
+export { applyGuestParity as t };

package/dist/guest-parity.d.mts

@@ -0,0 +1,16 @@
+//#region src/guest-parity.d.ts
+interface GuestParityOptions {
+  /** Where the polyfills are declared. Defaults to the working directory. */
+  projectDir?: string;
+}
+interface GuestParity {
+  removed: string[];
+  shimmed: string[];
+  replacedMethods: string[];
+  /** Left in place because the project bundles a polyfill for them. */
+  exempted: string[];
+  restore(): void;
+}
+declare function applyGuestParity(options?: GuestParityOptions): GuestParity;
+//#endregion
+export { GuestParity, GuestParityOptions, applyGuestParity };

package/dist/guest-parity.mjs

@@ -0,0 +1,2 @@
+import { t as applyGuestParity } from "./guest-parity-Df4rlLDW.mjs";
+export { applyGuestParity };

package/dist/guest-surface-CXON0L5V.mjs

@@ -0,0 +1,107 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region ../../server/guest-surface/surface.json
+var globals = [
+	{
+		"name": "MessageChannel",
+		"status": "shim",
+		"shim": "message-channel",
+		"why": "The engine has none. react-dom/server.browser constructs one at module scope, so a bundle that reaches for it does not evaluate at all."
+	},
+	{
+		"name": "MessagePort",
+		"status": "shim",
+		"shim": "message-channel",
+		"why": "The other half of the pair: a port handed to code that checks what it received has to be a real constructor."
+	},
+	{
+		"name": "Intl",
+		"status": "unsupported",
+		"remedy": "bundle an Intl polyfill, for example @formatjs/intl-numberformat",
+		"providedBy": [
+			"intl",
+			"full-icu",
+			"@formatjs/intl",
+			"@formatjs/intl-*",
+			"intl-pluralrules",
+			"intl-locales-supported",
+			"intl-segmenter-polyfill"
+		]
+	}
+];
+var methods = [
+	{
+		"target": "Number.prototype",
+		"name": "toLocaleString"
+	},
+	{
+		"target": "Date.prototype",
+		"name": "toLocaleString"
+	},
+	{
+		"target": "Date.prototype",
+		"name": "toLocaleDateString"
+	},
+	{
+		"target": "Date.prototype",
+		"name": "toLocaleTimeString"
+	},
+	{
+		"target": "String.prototype",
+		"name": "toLocaleLowerCase"
+	},
+	{
+		"target": "String.prototype",
+		"name": "toLocaleUpperCase"
+	}
+];
+var methodRemedy$1 = "the engine carries no ICU, so it ignores the locale and returns an unlocalised string; format the value yourself, or bundle a formatting library and call it directly";
+//#endregion
+//#region src/guest-surface.ts
+function declaredGlobals() {
+	return globals;
+}
+function declaredMethods() {
+	return methods;
+}
+function methodRemedy() {
+	return methodRemedy$1;
+}
+function unsupportedGlobals() {
+	return declaredGlobals().filter((entry) => entry.status === "unsupported");
+}
+function shimmedGlobals() {
+	return declaredGlobals().filter((entry) => entry.status === "shim");
+}
+/**
+* Globals a project already carries a polyfill for, read from the manifest the
+* polyfill is declared in so nothing here can drift from what is bundled.
+*/
+function polyfilledGlobals(projectDir) {
+	const declared = declaredPackages(projectDir);
+	return new Set(declaredGlobals().filter((entry) => (entry.providedBy ?? []).some((pattern) => declared.some((name) => matches(pattern, name)))).map((entry) => entry.name));
+}
+function matches(pattern, name) {
+	if (!pattern.endsWith("*")) return pattern === name;
+	return name.startsWith(pattern.slice(0, -1));
+}
+function declaredPackages(projectDir) {
+	const manifest = path.join(projectDir, "package.json");
+	if (!fs.existsSync(manifest)) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(fs.readFileSync(manifest, "utf-8"));
+	} catch {
+		return [];
+	}
+	return [
+		"dependencies",
+		"devDependencies",
+		"optionalDependencies"
+	].flatMap((field) => {
+		const deps = parsed[field];
+		return typeof deps === "object" && deps !== null ? Object.keys(deps) : [];
+	});
+}
+//#endregion
+export { unsupportedGlobals as a, shimmedGlobals as i, methodRemedy as n, polyfilledGlobals as r, declaredMethods as t };

package/dist/index.mjs

@@ -1,10 +1,14 @@
+import { a as unsupportedGlobals, n as methodRemedy, r as polyfilledGlobals, t as declaredMethods } from "./guest-surface-CXON0L5V.mjs";
 import cac from "cac";
 import fs from "node:fs";
 import path from "node:path";
 import { build } from "esbuild";
 import os from "node:os";
+import { parse } from "acorn";
 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";
@@ -119,6 +123,522 @@ function readFunctionConfig(projectDir) {
 	}
 }
 //#endregion
+//#region src/sourcemap.ts
+const BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const NO_POSITION = () => null;
+function originalPositionLookup(mapJson) {
+	if (!mapJson) return NO_POSITION;
+	let map;
+	try {
+		map = JSON.parse(mapJson);
+	} catch {
+		return NO_POSITION;
+	}
+	const sources = Array.isArray(map.sources) ? map.sources.map(String) : [];
+	const root = typeof map.sourceRoot === "string" && map.sourceRoot !== "" ? `${map.sourceRoot.replace(/\/+$/, "")}/` : "";
+	if (typeof map.mappings !== "string" || sources.length === 0) return NO_POSITION;
+	const lines = decodeMappings(map.mappings);
+	return (line, column) => {
+		const segments = lines[line - 1];
+		if (!segments) return null;
+		let found;
+		for (const segment of segments) {
+			if (segment[0] > column) break;
+			found = segment;
+		}
+		if (!found) return null;
+		const source = sources[found[1]];
+		if (source === void 0) return null;
+		return {
+			source: `${root}${source}`,
+			line: found[2] + 1,
+			column: found[3]
+		};
+	};
+}
+function decodeMappings(mappings) {
+	const lines = [];
+	let source = 0;
+	let sourceLine = 0;
+	let sourceColumn = 0;
+	for (const encodedLine of mappings.split(";")) {
+		const segments = [];
+		let generatedColumn = 0;
+		for (const encoded of encodedLine.split(",")) {
+			if (encoded === "") continue;
+			const fields = decodeVlq(encoded);
+			if (fields === null) continue;
+			generatedColumn += fields[0] ?? 0;
+			if (fields.length < 4) continue;
+			source += fields[1];
+			sourceLine += fields[2];
+			sourceColumn += fields[3];
+			segments.push([
+				generatedColumn,
+				source,
+				sourceLine,
+				sourceColumn
+			]);
+		}
+		lines.push(segments);
+	}
+	return lines;
+}
+function decodeVlq(encoded) {
+	const values = [];
+	let value = 0;
+	let shift = 0;
+	for (const character of encoded) {
+		const digit = BASE64.indexOf(character);
+		if (digit === -1) return null;
+		value += (digit & 31) << shift;
+		if (digit & 32) {
+			shift += 5;
+			continue;
+		}
+		const negative = value & 1;
+		value >>>= 1;
+		values.push(negative ? -value : value);
+		value = 0;
+		shift = 0;
+	}
+	return values;
+}
+//#endregion
+//#region src/guest-surface-scan.ts
+const MAX_LOCATIONS = 3;
+const ABSENT_PROBLEM = "the guest does not define it — evaluating this reference throws a ReferenceError";
+const METHOD_PROBLEM = "the guest carries no ICU, so it ignores the locale argument";
+const GUARDED_PROBLEM = "the guest does not define it — this bundle guards the reference, so the path it takes when the global is missing is the one that runs";
+const DEFERRED_PROBLEM = "the guest does not define it — the code holding this reference throws a ReferenceError if it ever runs";
+const GLOBAL_OBJECTS = /* @__PURE__ */ new Set([
+	"globalThis",
+	"window",
+	"self",
+	"global"
+]);
+const FUNCTIONS = /* @__PURE__ */ new Set([
+	"FunctionDeclaration",
+	"FunctionExpression",
+	"ArrowFunctionExpression"
+]);
+/** Everything it is unsure of warns: a wrong refusal costs a deploy that works. */
+function scanBundle(code, options = {}) {
+	let program;
+	try {
+		program = parse(code, {
+			ecmaVersion: "latest",
+			sourceType: "module",
+			locations: true
+		});
+	} catch {
+		return [];
+	}
+	const bound = /* @__PURE__ */ new Set();
+	const boundNodes = /* @__PURE__ */ new Set();
+	const guarded = /* @__PURE__ */ new Set();
+	const replacedMethods = /* @__PURE__ */ new Set();
+	const references = [];
+	const methodUses = [];
+	const scopes = /* @__PURE__ */ new Map();
+	const functionValues = /* @__PURE__ */ new Map();
+	const pendingBodies = [];
+	const scopeOf = (owner) => {
+		const existing = scopes.get(owner);
+		if (existing) return existing;
+		const scope = {
+			calls: [],
+			bodies: /* @__PURE__ */ new Map(),
+			locals: /* @__PURE__ */ new Set(),
+			immediate: []
+		};
+		scopes.set(owner, scope);
+		return scope;
+	};
+	scopeOf(null);
+	try {
+		walk(program, (node, parent, key, owner, inTry) => {
+			collectBindings(node, bound, boundNodes, scopeOf(owner), functionValues, pendingBodies);
+			collectGuards(node, guarded);
+			collectReplacedMethods(node, replacedMethods);
+			if (node.type === "CallExpression") {
+				const callee = unwrap(node.callee);
+				if (callee.type === "Identifier") scopeOf(owner).calls.push(String(callee.name));
+				const invoked = invokedFunction(callee);
+				if (invoked) {
+					scopeOf(owner).immediate.push(invoked);
+					if (invoked === callee) bindArguments(invoked, node.arguments, scopeOf(invoked));
+				}
+			}
+			if (node.type === "MemberExpression" && node.computed === false) methodUses.push(node.property);
+			if (node.type === "Identifier") {
+				if (boundNodes.has(node)) scopeOf(owner).locals.add(String(node.name));
+				if (isReference(node, parent, key)) references.push({
+					node,
+					owner,
+					guarded: inTry
+				});
+			}
+		});
+	} catch {
+		return [];
+	}
+	const absent = absentGlobals(options.projectDir ?? process.cwd());
+	const divergent = new Set(declaredMethods().map((method) => method.name));
+	resolveWrappedBodies(functionValues, pendingBodies);
+	const evaluated = evaluatedOnLoad(scopes);
+	const position = locator(options);
+	const findings = /* @__PURE__ */ new Map();
+	const classified = references.flatMap((reference) => {
+		const name = String(reference.node.name);
+		if (boundNodes.has(reference.node) || bound.has(name)) return [];
+		const gap = absent.get(name);
+		if (!gap) return [];
+		if (reference.guarded || guarded.has(name)) return [{
+			node: reference.node,
+			gap: {
+				...gap,
+				problem: GUARDED_PROBLEM
+			},
+			severity: "warn"
+		}];
+		if (!evaluated.has(reference.owner)) return [{
+			node: reference.node,
+			gap: {
+				...gap,
+				problem: DEFERRED_PROBLEM
+			},
+			severity: "warn"
+		}];
+		return [{
+			node: reference.node,
+			gap,
+			severity: "refuse"
+		}];
+	});
+	const refused = new Set(classified.filter((entry) => entry.severity === "refuse").map((entry) => entry.gap.name));
+	for (const entry of classified) {
+		if (entry.severity === "warn" && refused.has(entry.gap.name)) continue;
+		record(findings, entry.gap, entry.severity, position(entry.node));
+	}
+	for (const use of methodUses) {
+		const name = String(use.name);
+		if (replacedMethods.has(name) || !divergent.has(name)) continue;
+		record(findings, {
+			name,
+			problem: METHOD_PROBLEM,
+			remedy: methodRemedy()
+		}, "warn", position(use));
+	}
+	return [...findings.values()].sort((a, b) => a.severity === b.severity ? a.name.localeCompare(b.name) : a.severity === "refuse" ? -1 : 1);
+}
+/** The declared surface, less anything this project's own manifest says it bundles. */
+function absentGlobals(projectDir) {
+	const polyfilled = polyfilledGlobals(projectDir);
+	return new Map(unsupportedGlobals().filter((entry) => !polyfilled.has(entry.name)).map((entry) => [entry.name, {
+		name: entry.name,
+		problem: ABSENT_PROBLEM,
+		remedy: entry.remedy ?? ""
+	}]));
+}
+function refusesDeploy(findings) {
+	return findings.some((finding) => finding.severity === "refuse");
+}
+function surfaceReportLines(findings) {
+	const lines = [];
+	for (const finding of findings) {
+		const headline = finding.severity === "refuse" ? "Refusing to deploy" : "Warning";
+		lines.push(`[wawesome] ${headline}: \`${finding.name}\` — ${finding.problem}.`);
+		for (const location of finding.locations) lines.push(`[wawesome]   at ${location.file}:${location.line}:${location.column}`);
+		if (finding.undisplayedLocations > 0) lines.push(`[wawesome]   and ${finding.undisplayedLocations} more reference${finding.undisplayedLocations === 1 ? "" : "s"}`);
+		lines.push(`[wawesome]   Remedy: ${finding.remedy}`);
+	}
+	if (refusesDeploy(findings)) lines.push("[wawesome] The guest cannot evaluate this bundle, so nothing has been uploaded.");
+	return lines;
+}
+/**
+* A bundled CommonJS dependency is a function esbuild calls as the bundle
+* evaluates, so "runs on load" is not the same question as "sits outside every
+* function".
+*/
+function evaluatedOnLoad(scopes) {
+	const program = scopes.get(null);
+	const evaluated = /* @__PURE__ */ new Set([null]);
+	const pending = [null];
+	const run = (body) => {
+		if (evaluated.has(body)) return;
+		evaluated.add(body);
+		pending.push(body);
+	};
+	while (pending.length > 0) {
+		const owner = pending.shift();
+		const scope = scopes.get(owner);
+		if (!scope) continue;
+		for (const body of scope.immediate) run(body);
+		for (const call of scope.calls) {
+			const bodies = scope.bodies.get(call) ?? (scope.locals.has(call) ? [] : program.bodies.get(call) ?? []);
+			for (const body of bodies) run(body);
+		}
+	}
+	return evaluated;
+}
+function record(findings, gap, severity, location) {
+	const existing = findings.get(gap.name);
+	if (!existing) {
+		findings.set(gap.name, {
+			...gap,
+			severity,
+			locations: [location],
+			undisplayedLocations: 0
+		});
+		return;
+	}
+	if (existing.locations.some((known) => known.file === location.file && known.line === location.line && known.column === location.column)) return;
+	if (existing.locations.length < MAX_LOCATIONS) existing.locations.push(location);
+	else existing.undisplayedLocations += 1;
+}
+function locator(options) {
+	const bundleFile = options.bundlePath ? displayPath(options.bundlePath) : "the bundle";
+	const lookup = originalPositionLookup(options.map);
+	const baseDir = options.mapBaseDir ?? path.dirname(options.bundlePath ?? ".");
+	return (node) => {
+		const loc = node.loc;
+		const original = lookup(loc.start.line, loc.start.column);
+		if (original) return {
+			file: displayPath(path.resolve(baseDir, original.source)),
+			line: original.line,
+			column: original.column + 1
+		};
+		return {
+			file: bundleFile,
+			line: loc.start.line,
+			column: loc.start.column + 1
+		};
+	};
+}
+function displayPath(target) {
+	const relative = path.relative(process.cwd(), path.resolve(target));
+	return relative === "" || relative.startsWith("..") ? target : relative;
+}
+function isReference(node, parent, key) {
+	if (!parent) return true;
+	switch (parent.type) {
+		case "MemberExpression": return key !== "property" || parent.computed === true;
+		case "Property":
+		case "PropertyDefinition":
+		case "MethodDefinition": return key !== "key" || parent.computed === true;
+		case "UnaryExpression": return parent.operator !== "typeof";
+		case "ImportSpecifier":
+		case "ExportSpecifier":
+		case "ImportDefaultSpecifier":
+		case "ImportNamespaceSpecifier": return false;
+		case "LabeledStatement":
+		case "BreakStatement":
+		case "ContinueStatement": return key !== "label";
+		default: return true;
+	}
+}
+/** `typeof Intl`, `globalThis.Intl` — a bundle that asks has an answer for "no". */
+function collectGuards(node, guarded) {
+	if (node.type === "UnaryExpression" && node.operator === "typeof") {
+		const argument = node.argument;
+		if (argument.type === "Identifier") guarded.add(String(argument.name));
+		return;
+	}
+	if (node.type !== "MemberExpression") return;
+	const name = globalObjectProperty(node);
+	if (name !== null) guarded.add(name);
+}
+function collectReplacedMethods(node, replaced) {
+	if (node.type === "AssignmentExpression") {
+		const target = node.left;
+		if (target.type === "MemberExpression" && target.computed === false && onPrototype(target)) replaced.add(String(target.property.name));
+		return;
+	}
+	if (node.type !== "CallExpression") return;
+	const callee = node.callee;
+	const owner = node.arguments[0];
+	const property = node.arguments[1];
+	if (callee.type === "MemberExpression" && callee.computed === false && String(callee.property.name) === "defineProperty" && owner && isPrototype(owner) && property?.type === "Literal" && typeof property.value === "string") replaced.add(property.value);
+}
+function onPrototype(member) {
+	return isPrototype(member.object);
+}
+function isPrototype(node) {
+	return node.type === "MemberExpression" && node.computed === false && String(node.property.name) === "prototype";
+}
+function globalObjectProperty(member) {
+	const object = member.object;
+	if (object.type !== "Identifier" || !GLOBAL_OBJECTS.has(String(object.name))) return null;
+	const property = member.property;
+	if (member.computed === false && property.type === "Identifier") return String(property.name);
+	if (member.computed === true && property.type === "Literal" && typeof property.value === "string") return property.value;
+	return null;
+}
+function collectBindings(node, bound, boundNodes, scope, functionValues, pending) {
+	switch (node.type) {
+		case "VariableDeclarator":
+			bindPattern(node.id, bound, boundNodes);
+			bindBody(node.id, node.init, scope, functionValues, pending);
+			break;
+		case "FunctionDeclaration":
+		case "FunctionExpression":
+		case "ArrowFunctionExpression":
+			if (node.id) bindPattern(node.id, bound, boundNodes);
+			if (node.type === "FunctionDeclaration" && node.id) scope.bodies.set(String(node.id.name), [node]);
+			for (const param of node.params) bindPattern(param, bound, boundNodes);
+			break;
+		case "ClassDeclaration":
+		case "ClassExpression":
+			if (node.id) bindPattern(node.id, bound, boundNodes);
+			break;
+		case "CatchClause":
+			if (node.param) bindPattern(node.param, bound, boundNodes);
+			break;
+		case "ImportSpecifier":
+		case "ImportDefaultSpecifier":
+		case "ImportNamespaceSpecifier":
+			bindPattern(node.local, bound, boundNodes);
+			break;
+		case "AssignmentExpression":
+			bindAssignmentTarget(node.left, bound);
+			bindBody(node.left, node.right, scope, functionValues, pending);
+			break;
+		default: break;
+	}
+}
+function bindBody(target, value, scope, functionValues, pending) {
+	if (!value || target.type !== "Identifier") return;
+	const name = String(target.name);
+	if (FUNCTIONS.has(value.type)) {
+		scope.bodies.set(name, [value]);
+		functionValues.set(name, value);
+		return;
+	}
+	if (value.type !== "CallExpression") return;
+	const callee = unwrap(value.callee);
+	if (callee.type !== "Identifier") return;
+	const bodies = [];
+	for (const argument of value.arguments) {
+		if (FUNCTIONS.has(argument.type)) bodies.push(argument);
+		if (argument.type === "ObjectExpression") for (const property of argument.properties) {
+			const propertyValue = property.value;
+			if (propertyValue && FUNCTIONS.has(propertyValue.type)) bodies.push(propertyValue);
+		}
+	}
+	if (bodies.length > 0) pending.push({
+		scope,
+		name,
+		callee: String(callee.name),
+		bodies
+	});
+}
+/**
+* A bundled dependency arrives as a function handed to one of esbuild's wrapper
+* helpers, whose name minification has already rewritten. The helper is
+* recognised by what it does — hand back a function that invokes what it was
+* given — so an ordinary call handed an ordinary callback is left alone.
+*/
+function resolveWrappedBodies(functionValues, pending) {
+	const wrappers = new Set([...functionValues].filter(([, value]) => wrapsItsArgument(value)).map(([name]) => name));
+	for (const entry of pending) if (wrappers.has(entry.callee)) entry.scope.bodies.set(entry.name, entry.bodies);
+}
+function wrapsItsArgument(fn) {
+	const first = fn.params[0];
+	if (first?.type !== "Identifier") return false;
+	const returned = returnedFunction(fn);
+	if (!returned) return false;
+	let invokes = false;
+	walk(returned, (node) => {
+		if (node.type !== "CallExpression") return;
+		if (rootObject(unwrap(node.callee)) === String(first.name)) invokes = true;
+	});
+	return invokes;
+}
+function returnedFunction(fn) {
+	const body = fn.body;
+	if (FUNCTIONS.has(body.type)) return body;
+	if (body.type !== "BlockStatement") return null;
+	for (const statement of body.body) if (statement.type === "ReturnStatement" && statement.argument) {
+		const returned = statement.argument;
+		if (FUNCTIONS.has(returned.type)) return returned;
+	}
+	return null;
+}
+function rootObject(node) {
+	let current = node;
+	while (current.type === "MemberExpression") current = unwrap(current.object);
+	return current.type === "Identifier" ? String(current.name) : null;
+}
+/** `(0, fn)(...)` and `(fn)(...)` reach the same place as `fn(...)`. */
+function unwrap(node) {
+	if (node.type !== "SequenceExpression") return node;
+	const expressions = node.expressions;
+	return unwrap(expressions[expressions.length - 1]);
+}
+/** The one call site of an IIFE says exactly what its parameters hold. */
+function bindArguments(fn, args, scope) {
+	fn.params.forEach((param, index) => {
+		const argument = args[index];
+		if (param.type === "Identifier" && argument && FUNCTIONS.has(argument.type)) scope.bodies.set(String(param.name), [argument]);
+	});
+}
+function invokedFunction(callee) {
+	if (FUNCTIONS.has(callee.type)) return callee;
+	if (callee.type === "MemberExpression" && callee.computed === false) {
+		const property = String(callee.property.name);
+		const object = unwrap(callee.object);
+		if ((property === "call" || property === "apply") && FUNCTIONS.has(object.type)) return object;
+	}
+	return null;
+}
+function bindPattern(node, bound, boundNodes) {
+	if (!node) return;
+	switch (node.type) {
+		case "Identifier":
+			bound.add(String(node.name));
+			boundNodes.add(node);
+			break;
+		case "ObjectPattern":
+			for (const property of node.properties) bindPattern(property.value ?? property.argument, bound, boundNodes);
+			break;
+		case "ArrayPattern":
+			for (const element of node.elements) bindPattern(element, bound, boundNodes);
+			break;
+		case "RestElement":
+			bindPattern(node.argument, bound, boundNodes);
+			break;
+		case "AssignmentPattern":
+			bindPattern(node.left, bound, boundNodes);
+			break;
+		default: break;
+	}
+}
+function bindAssignmentTarget(target, bound) {
+	if (target.type === "Identifier") {
+		bound.add(String(target.name));
+		return;
+	}
+	if (target.type !== "MemberExpression") return;
+	const name = globalObjectProperty(target);
+	if (name !== null) bound.add(name);
+}
+function walk(node, visit, parent = null, key = "", owner = null, inTry = false) {
+	visit(node, parent, key, owner, inTry);
+	for (const childKey of Object.keys(node)) {
+		if (childKey === "loc") continue;
+		const value = node[childKey];
+		const childOwner = FUNCTIONS.has(node.type) || node.type === "PropertyDefinition" && node.static !== true ? node : owner;
+		const childInTry = inTry || node.type === "TryStatement" && childKey === "block";
+		if (Array.isArray(value)) {
+			for (const child of value) if (isNode(child)) walk(child, visit, node, childKey, childOwner, childInTry);
+		} else if (isNode(value)) walk(value, visit, node, childKey, childOwner, childInTry);
+	}
+}
+function isNode(value) {
+	return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+//#endregion
 //#region src/build.ts
 /**
 * Bundles user TS/JS entry point into a single optimized ESM JavaScript file using esbuild.
@@ -138,8 +658,9 @@ async function buildJs(entryInput, options) {
 		console.log(`[wawesome:verbose] Entry point resolved: ${path.resolve(entry)}`);
 		console.log(`[wawesome:verbose] Target output path: ${outPath}`);
 	}
+	let result;
 	try {
-		await build({
+		result = await build({
 			entryPoints: [entry],
 			absWorkingDir: process.cwd(),
 			bundle: true,
@@ -156,12 +677,10 @@ async function buildJs(entryInput, options) {
 			minify: true,
 			keepNames: true,
 			legalComments: "none",
-			logLevel: isVerbose ? "info" : "silent"
+			logLevel: isVerbose ? "info" : "silent",
+			sourcemap: "external",
+			write: false
 		});
-		const sizeKb = (fs.statSync(outPath).size / 1024).toFixed(2);
-		const elapsed = Date.now() - startTime;
-		console.log(`[wawesome] Successfully built ${options.out} (${sizeKb} KB) in ${elapsed}ms!`);
-		return outPath;
 	} catch (err) {
 		console.error("[wawesome] Build failed!");
 		if (isVerbose && err instanceof Error) console.error(err.stack || err.message);
@@ -169,6 +688,26 @@ async function buildJs(entryInput, options) {
 		else console.error(err);
 		process.exit(1);
 	}
+	const bundle = result.outputFiles.find((file) => file.path === outPath);
+	if (!bundle) {
+		console.error(`[wawesome] Build failed! esbuild produced no output at ${outPath}.`);
+		process.exit(1);
+	}
+	const map = result.outputFiles.find((file) => file.path === `${outPath}.map`);
+	fs.mkdirSync(path.dirname(outPath), { recursive: true });
+	fs.writeFileSync(outPath, bundle.contents);
+	const findings = scanBundle(bundle.text, {
+		bundlePath: outPath,
+		map: map?.text ?? null,
+		mapBaseDir: path.dirname(outPath)
+	});
+	const refused = refusesDeploy(findings);
+	for (const line of surfaceReportLines(findings)) (refused ? console.error : console.warn)(line);
+	if (refused) process.exit(1);
+	const sizeKb = (bundle.contents.byteLength / 1024).toFixed(2);
+	const elapsed = Date.now() - startTime;
+	console.log(`[wawesome] Successfully built ${options.out} (${sizeKb} KB) in ${elapsed}ms!`);
+	return outPath;
 }
 //#endregion
 //#region src/cli-version.ts
@@ -181,7 +720,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.0.14";
+const CLI_VERSION = "0.1.0";
 //#endregion
 //#region src/prompt.ts
 /**
@@ -726,6 +1265,65 @@ function widest(values) {
 	return values.reduce((longest, value) => Math.max(longest, value.length), 0);
 }
 //#endregion
+//#region src/assets.ts
+/**
+* The files under `dir`, hashed.
+*
+* Hashes are read off disk in a stream rather than by reading each file whole:
+* a client build's largest chunk is not something to hold in memory just to
+* find out the platform already has it.
+*/
+function collectAssets(dir) {
+	if (!fs.existsSync(dir)) return [];
+	const assets = [];
+	const walk = (current, prefix) => {
+		for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+			const absolute = path.join(current, entry.name);
+			const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+			if (entry.isDirectory()) walk(absolute, relative);
+			else if (entry.isFile()) assets.push({
+				path: relative,
+				content_hash: hashFile(absolute),
+				size_bytes: fs.statSync(absolute).size,
+				source: absolute
+			});
+		}
+	};
+	walk(dir, "");
+	return assets;
+}
+function hashFile(file) {
+	return sha256(fs.readFileSync(file));
+}
+function sha256(bytes) {
+	return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+/**
+* What this deploy *is*: the server bundle together with the sorted set of
+* asset path and content-hash pairs.
+*
+* Computed here, before anything is uploaded, so a deploy that changed nothing
+* is refused before a byte moves. Mirrors `deploy_digest` in
+* `server/crates/core/src/features/assets/identity.rs` — the gateway recomputes
+* it from what actually arrives, so the two have to agree exactly.
+*/
+const DEPLOY_DIGEST_DOMAIN = "wawesome-deploy-v1";
+function deployDigest(bundle, assets) {
+	const digest = crypto.createHash("sha256");
+	digest.update(`${DEPLOY_DIGEST_DOMAIN}\n`);
+	digest.update(`${sha256(bundle)}\n`);
+	for (const asset of [...assets].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) digest.update(`${asset.path}\0${asset.content_hash}\n`);
+	return digest.digest("hex");
+}
+/** The manifest as the gateway reads it — the bytes on disk are the CLI's business. */
+function manifestOf(assets) {
+	return assets.map(({ path, content_hash, size_bytes }) => ({
+		path,
+		content_hash,
+		size_bytes
+	}));
+}
+//#endregion
 //#region ../shared/public-address.ts
 const INVOCATION_PREFIX = "/x";
 const SUBTREE_NOTE = "Every path beneath this address reaches the Function.";
@@ -785,10 +1383,28 @@ async function deploy(entryInput, options) {
 		process.exit(1);
 	}
 	if (isVerbose) console.log(`[wawesome:verbose] Bundle size: ${(Buffer.byteLength(jsCode) / 1024).toFixed(2)} KB`);
+	if (options.skipBuild) {
+		const findings = scanBundle(jsCode, { bundlePath });
+		const refused = refusesDeploy(findings);
+		for (const line of surfaceReportLines(findings)) (refused ? console.error : console.warn)(line);
+		if (refused) process.exit(1);
+	}
+	const assets = config.assets ? collectAssets(path.resolve(config.assets)) : [];
+	if (assets.length > 0) await uploadAssets(creds, app, funcName, jsCode, assets, isVerbose);
 	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 = await fetch(uploadUrl, {
+	const uploadRes = assets.length > 0 ? await fetch(uploadUrl, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${creds.tenant_jwt}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({
+			code: jsCode,
+			assets: manifestOf(assets)
+		})
+	}) : await fetch(uploadUrl, {
 		method: "POST",
 		headers: {
 			Authorization: `Bearer ${creds.tenant_jwt}`,
@@ -853,6 +1469,7 @@ async function deploy(entryInput, options) {
 	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}`);
@@ -869,6 +1486,69 @@ async function deploy(entryInput, options) {
 		address
 	};
 }
+/**
+* Ask the gateway which of this deploy's files it does not hold, and send only
+* those.
+*
+* 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) {
+	const manifestUrl = `${creds.gateway_url}/v1/apps/${encodeURIComponent(app)}/functions/${encodeURIComponent(funcName)}/assets/manifest`;
+	const manifestRes = await fetch(manifestUrl, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${creds.tenant_jwt}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({
+			deploy_digest: deployDigest(Buffer.from(bundle, "utf-8"), assets),
+			assets: manifestOf(assets)
+		})
+	});
+	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) {
+			const refusal = rejectionOf(errorBody, manifestRes.status, "This deploy is already deployed.");
+			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 {
+			const refusal = rejectionOf(errorBody, manifestRes.status, `Asset manifest failed (HTTP ${manifestRes.status}).`);
+			console.error(`[wawesome] Error: ${refusal.message}`);
+			if (isVerbose) console.error(`[wawesome:verbose] Response: ${errorBody}`);
+		}
+		process.exit(1);
+	}
+	const { missing = [] } = await manifestRes.json();
+	const toUpload = assets.filter((asset) => missing.includes(asset.content_hash));
+	if (toUpload.length === 0) {
+		console.log(`[wawesome] ✅ ${assets.length} asset(s) already on the platform, nothing to upload.`);
+		return;
+	}
+	console.log(`[wawesome] Uploading ${toUpload.length} of ${assets.length} asset(s)...`);
+	for (const asset of toUpload) {
+		if (isVerbose) console.log(`[wawesome:verbose] PUT ${asset.path} (${asset.size_bytes} bytes)`);
+		const res = await fetch(`${creds.gateway_url}/v1/assets/${asset.content_hash}`, {
+			method: "PUT",
+			headers: {
+				Authorization: `Bearer ${creds.tenant_jwt}`,
+				"Content-Type": "application/octet-stream",
+				"Content-Length": String(asset.size_bytes)
+			},
+			body: Readable.toWeb(fs.createReadStream(asset.source)),
+			duplex: "half"
+		});
+		if (!res.ok) {
+			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}`);
+			if (isVerbose) console.error(`[wawesome:verbose] Response: ${errorBody}`);
+			process.exit(1);
+		}
+	}
+	console.log(`[wawesome] ✅ ${toUpload.length} asset(s) uploaded.`);
+}
 //#endregion
 //#region src/billing.ts
 function billingPageUrl() {

package/dist/vitest-setup.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/vitest-setup.mjs

@@ -0,0 +1,5 @@
+import { t as applyGuestParity } from "./guest-parity-Df4rlLDW.mjs";
+//#region src/vitest-setup.ts
+applyGuestParity();
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wawesome",
-  "version": "0.0.14",
+  "version": "0.1.0",
   "description": "CLI tool for building and deploying serverless functions on wawesome.io platform",
   "type": "module",
   "bin": {
@@ -8,6 +8,21 @@
   },
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./guest-parity": {
+      "types": "./dist/guest-parity.d.mts",
+      "default": "./dist/guest-parity.mjs"
+    },
+    "./vitest-setup": {
+      "types": "./dist/vitest-setup.d.mts",
+      "default": "./dist/vitest-setup.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "bin",
     "dist"
@@ -22,6 +37,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.5.2",
+    "acorn": "^8.18.0",
     "cac": "^6.7.14",
     "esbuild": "^0.28.0",
     "open": "^10.0.0"