wawesome 0.4.0 → 0.6.0

package/README.md

@@ -258,6 +258,92 @@ Two rules to know about:
 **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 public address at all** in production — not a hidden one, not one
+behind a credential. A request for it against your App's own hostname is answered with the same 404
+as a Function that was never deployed. 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.
+
+On your own machine, the local development surface serves Functions regardless of visibility, and
+honours an explicit `x-wawesome-trigger` header so you can exercise a scheduled run by hand:
+
+```bash
+# Exercise a private or scheduled function locally on the development path form:
+curl -X POST http://localhost:3000/x/my-tenant-slug/default-app/nightly-reconcile \
+  -H "x-wawesome-trigger: schedule"
+```
+
+Because production strips the reserved header namespace inbound, a request that works locally
+provably cannot work against the Public address.
+
+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
 
 `x-wawesome-*` belongs to the platform in both directions. It is stripped off the request before your
@@ -265,11 +351,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, `schedule` when fired by a Schedule. A caller cannot forge it in production (stripped inbound). On the local development surface, pass `x-wawesome-trigger: schedule` to exercise a background run by hand with the collapsed budget. |
 | `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

@@ -759,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.4.0";
+const CLI_VERSION = "0.6.0";
 //#endregion
 //#region src/prompt.ts
 /**
@@ -1155,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;
 /**
@@ -1323,9 +1359,15 @@ function billingPageUrl() {
 		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 !== "app-slots-exhausted" && reason !== "storage-exhausted") return "";
+	if (!reason || !PLAN_LIMITS.includes(reason)) return "";
 	return `Where to resolve it: ${billingPageUrl()}`;
 }
 //#endregion
@@ -1472,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.
 */
@@ -1489,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}`);
@@ -1520,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}`,
@@ -1533,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",
@@ -1545,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");
@@ -1557,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);
@@ -1597,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("");
@@ -1620,7 +1717,8 @@ async function deploy(entryInput, options) {
 		app,
 		functionName: funcName,
 		version,
-		address
+		address,
+		schedules
 	};
 }
 /**
@@ -1630,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",
@@ -1640,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 {
@@ -3595,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wawesome",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "CLI tool for building and deploying serverless functions on wawesome.io platform",
   "type": "module",
   "bin": {