wawesome 0.0.5 → 0.0.7

package/dist/index.mjs

@@ -5,6 +5,7 @@ import { build } from "esbuild";
 import os from "node:os";
 import http from "node:http";
 import readline from "node:readline";
+import zlib from "node:zlib";
 import { select } from "@inquirer/prompts";
 //#region src/config.ts
 /**
@@ -124,6 +125,7 @@ async function buildJs(entryInput, options) {
 	try {
 		await build({
 			entryPoints: [entry],
+			absWorkingDir: process.cwd(),
 			bundle: true,
 			format: "esm",
 			outfile: outPath,
@@ -148,8 +150,183 @@ async function buildJs(entryInput, options) {
 	}
 }
 //#endregion
+//#region src/prompt.ts
+/**
+* Open a prompt session on stdin, queueing lines as they arrive.
+*
+* Reading one `rl.question` at a time drops piped input: it lands as a single
+* chunk, so every line after the first is emitted with no question pending.
+* End of input answers the remaining questions with their defaults.
+*/
+function openPromptSession() {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	const queued = [];
+	const waiting = [];
+	let ended = false;
+	rl.on("line", (line) => {
+		const next = waiting.shift();
+		if (next) next(line);
+		else queued.push(line);
+	});
+	rl.on("close", () => {
+		ended = true;
+		while (waiting.length > 0) waiting.shift()?.(null);
+	});
+	function nextLine() {
+		if (queued.length > 0) return Promise.resolve(queued.shift());
+		if (ended) return Promise.resolve(null);
+		return new Promise((resolve) => waiting.push(resolve));
+	}
+	return {
+		async ask(question, defaultVal) {
+			const offered = defaultVal ? ` (${defaultVal})` : "";
+			process.stdout.write(`${question}${offered}: `);
+			const line = await nextLine();
+			if (line === null) {
+				process.stdout.write("\n");
+				return defaultVal;
+			}
+			return line.trim() || defaultVal;
+		},
+		close() {
+			rl.close();
+		}
+	};
+}
+/**
+* Whether a question can actually be put to somebody. A piped or redirected
+* stdin still answers — with end-of-input — so this only tells a caller whether
+* a *default* is going to be what the user gets.
+*/
+function isInteractive() {
+	return Boolean(process.stdin.isTTY);
+}
+//#endregion
+//#region src/errors.ts
+/** A rejection carrying the gateway's own prose and, where given, its reason. */
+var GatewayError = class extends Error {
+	status;
+	reason;
+	/** The raw response, for `--verbose` to print when the prose is not enough. */
+	body;
+	constructor(message, status, reason, body = "") {
+		super(message);
+		this.name = "GatewayError";
+		this.status = status;
+		this.reason = reason;
+		this.body = body;
+	}
+};
+/**
+* Read a failed response into a `GatewayError`.
+*
+* `fallback` is used only when the response carries no prose of its own — a
+* proxy's HTML error page, or an empty body. A 401 is deliberately *not* special
+* cased here: what to say about an expired session depends on what the caller
+* was doing, so callers handle it before reaching this.
+*/
+async function asGatewayError(res, fallback) {
+	const body = await res.text().catch(() => "");
+	try {
+		const parsed = JSON.parse(body);
+		return new GatewayError(parsed.error || fallback, res.status, parsed.reason, body);
+	} catch {
+		return new GatewayError(fallback, res.status, void 0, body);
+	}
+}
+/** What went wrong, as text, whatever was thrown. */
+function errorText(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
+//#region src/tenant.ts
+async function fetchTenantDetails(creds) {
+	const res = await fetch(`${creds.gateway_url}/v1/tenant`, { headers: { Authorization: `Bearer ${creds.tenant_jwt}` } });
+	if (!res.ok) throw await asGatewayError(res, `Failed to read workspace (HTTP ${res.status}).`);
+	return await res.json();
+}
+/**
+* The workspace's name and slug, preferring what login already stored.
+*
+* Credentials written before the slug was stored have neither, so this fetches
+* and writes them back rather than making every later command ask again.
+*/
+async function resolveWorkspace(creds) {
+	if (creds.tenant_slug && creds.tenant_name) return {
+		name: creds.tenant_name,
+		slug: creds.tenant_slug
+	};
+	const tenant = await fetchTenantDetails(creds);
+	writeCredentials({
+		...creds,
+		tenant_slug: tenant.tenant_slug,
+		tenant_name: tenant.name
+	});
+	return {
+		name: tenant.name,
+		slug: tenant.tenant_slug
+	};
+}
+/**
+* Ask for the workspace's public address to become `slug`.
+*
+* The slug is sent exactly as typed. Sanitizing it the way an App slug is
+* sanitized would hand the user a public address they never chose, so an
+* unusable name comes back as a `malformed` rejection instead.
+*/
+async function renameTenantSlug(creds, slug) {
+	const res = await fetch(`${creds.gateway_url}/v1/tenant/slug`, {
+		method: "PUT",
+		headers: {
+			Authorization: `Bearer ${creds.tenant_jwt}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({ slug })
+	});
+	if (!res.ok) throw await asGatewayError(res, `Rename failed (HTTP ${res.status}).`);
+	const result = await res.json();
+	const stored = readCredentials();
+	if (stored) writeCredentials({
+		...stored,
+		tenant_slug: result.tenant_slug
+	});
+	return result;
+}
+/** The address a deployed Function answers on, for a workspace and app. */
+function publicInvokeUrl(gatewayUrl, tenantSlug, appSlug, functionName) {
+	return `${gatewayUrl}/v1/s/${encodeURIComponent(tenantSlug)}/apps/${encodeURIComponent(appSlug)}/functions/${encodeURIComponent(functionName)}/invoke`;
+}
+//#endregion
 //#region src/auth.ts
 /**
+* Ask what to call the workspace being created.
+*
+* There is no default worth offering: a name nobody typed is exactly what this
+* replaced. A non-interactive login has nobody to ask, so it says what flag to
+* pass rather than inventing one and minting a workspace under it.
+*/
+async function promptForWorkspaceName(options) {
+	const supplied = options.workspace?.trim();
+	if (supplied) return supplied;
+	if (!isInteractive()) throw new Error("No workspace found, and no name to create one with. Re-run with --workspace <name>.");
+	console.log("\n[wawesome] You don't have a workspace yet — let's create one.");
+	console.log("  (this is the name you'll see in the dashboard; its public address is set separately)");
+	const session = openPromptSession();
+	try {
+		for (let attempt = 0; attempt < 3; attempt++) {
+			const answer = await session.ask("  Workspace name?", "");
+			if (answer.trim()) return answer.trim();
+			console.log("[wawesome] A workspace needs a name.");
+		}
+	} finally {
+		session.close();
+	}
+	throw new Error("No workspace name given. Nothing was created.");
+}
+/**
 * OAuth login flow:
 * 1. Build Supabase OAuth URL
 * 2. Open browser
@@ -217,18 +394,24 @@ async function login(options) {
 					if (!tenantsRes.ok) throw new Error(`Failed to fetch tenants (HTTP ${tenantsRes.status}). Have you completed onboarding?`);
 					const tenants = await tenantsRes.json();
 					let primaryTenantId;
+					let workspaceName;
+					let workspaceSlug;
 					if (tenants.length === 0) {
-						console.log("[wawesome] No workspaces found. Initializing default workspace...");
+						const chosenName = await promptForWorkspaceName(options);
+						console.log(`[wawesome] Creating workspace "${chosenName}"...`);
 						const initRes = await fetch(`${gatewayUrl}/api/v1/onboarding/init`, {
 							method: "POST",
 							headers: {
 								Authorization: `Bearer ${accessToken}`,
 								"Content-Type": "application/json"
 							},
-							body: JSON.stringify({ tenant_name: "Personal Workspace" })
+							body: JSON.stringify({ tenant_name: chosenName })
 						});
 						if (!initRes.ok) throw new Error(`Failed to initialize workspace (HTTP ${initRes.status}).`);
-						primaryTenantId = (await initRes.json()).tenant_id;
+						const initData = await initRes.json();
+						primaryTenantId = initData.tenant_id;
+						workspaceSlug = initData.tenant_slug;
+						workspaceName = initData.tenant_name || chosenName;
 					} else primaryTenantId = tenants[0].tenant_id;
 					if (isVerbose) console.log(`[wawesome:verbose] Using tenant: ${primaryTenantId}`);
 					console.log("[wawesome] Exchanging for tenant-scoped credentials...");
@@ -242,6 +425,8 @@ async function login(options) {
 					});
 					if (!exchangeRes.ok) throw new Error(`Token exchange failed (HTTP ${exchangeRes.status}).`);
 					const exchangeData = await exchangeRes.json();
+					workspaceSlug = exchangeData.tenant_slug || workspaceSlug;
+					workspaceName = exchangeData.tenant_name || workspaceName;
 					let userEmail = exchangeData.email || "unknown";
 					try {
 						const payloadPart = exchangeData.tenant_jwt.split(".")[1];
@@ -252,14 +437,18 @@ async function login(options) {
 						gateway_url: gatewayUrl,
 						tenant_jwt: exchangeData.tenant_jwt,
 						tenant_id: primaryTenantId,
-						user_email: userEmail
+						user_email: userEmail,
+						tenant_slug: workspaceSlug,
+						tenant_name: workspaceName
 					});
 					console.log("\n======================================================");
 					console.log("🎉 \x1B[32mLOGIN SUCCESSFUL!\x1B[0m");
 					console.log("======================================================");
-					console.log(`\n  Tenant:  ${primaryTenantId}`);
-					console.log(`  Gateway: ${gatewayUrl}`);
-					console.log(`  Email:   ${userEmail}`);
+					if (workspaceName) console.log(`\n  Workspace: ${workspaceName}`);
+					if (workspaceSlug) console.log(`  Address:   ${workspaceSlug}`);
+					console.log(`  Tenant:    ${primaryTenantId}`);
+					console.log(`  Gateway:   ${gatewayUrl}`);
+					console.log(`  Email:     ${userEmail}`);
 					console.log("\n  Credentials saved to ~/.wawesome/credentials.json");
 					console.log("======================================================\n");
 					server.close();
@@ -297,16 +486,26 @@ function logout() {
 /**
 * Show current login status.
 */
-function whoami() {
+async function whoami() {
 	const creds = readCredentials();
 	if (!creds) {
 		console.log("[wawesome] Not logged in. Run 'wawesome login' to authenticate.");
 		return;
 	}
+	let workspace = null;
+	try {
+		workspace = await resolveWorkspace(creds);
+	} catch {
+		workspace = null;
+	}
 	console.log("\n[wawesome] Current session:");
-	console.log(`  Email:   ${creds.user_email}`);
-	console.log(`  Tenant:  ${creds.tenant_id}`);
-	console.log(`  Gateway: ${creds.gateway_url}\n`);
+	console.log(`  Email:     ${creds.user_email}`);
+	if (workspace) {
+		console.log(`  Workspace: ${workspace.name}`);
+		console.log(`  Address:   ${workspace.slug}`);
+	}
+	console.log(`  Tenant:    ${creds.tenant_id}`);
+	console.log(`  Gateway:   ${creds.gateway_url}\n`);
 }
 //#endregion
 //#region src/deploy.ts
@@ -403,40 +602,849 @@ async function deploy(entryInput, options) {
 			console.error(`[wawesome] Error: Deployment failed (HTTP ${deployRes.status}).`);
 			if (isVerbose) console.error(`[wawesome:verbose] Response: ${errorBody}`);
 		}
-		process.exit(1);
+		process.exit(1);
+	}
+	let invokeUrl = null;
+	try {
+		const { slug } = await resolveWorkspace(creds);
+		invokeUrl = publicInvokeUrl(creds.gateway_url, slug, app, funcName);
+	} catch (err) {
+		if (isVerbose) console.log(`[wawesome:verbose] Could not resolve the workspace address: ${err instanceof Error ? err.message : err}`);
+	}
+	console.log("\n======================================================");
+	console.log("🚀 \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 (invokeUrl) console.log(`\n  URL:      \x1b[36m${invokeUrl}\x1b[0m`);
+	console.log("======================================================\n");
+	return {
+		app,
+		functionName: funcName,
+		version,
+		invokeUrl
+	};
+}
+//#endregion
+//#region src/env.ts
+const STANDARD_SECRET_MESSAGES = [
+	"Encrypted at rest using AES-256",
+	"This value can't be viewed again after you save it — only updated or deleted",
+	"Only decrypted at the moment your function runs — never returned by the CLI, dashboard, or API after creation."
+];
+/**
+* Load credentials and validate project config.
+*/
+function loadClientContext() {
+	const creds = readCredentials();
+	if (!creds) {
+		console.error("[wawesome] Error: Not logged in. Run 'wawesome login' first.");
+		process.exit(1);
+	}
+	const config = readFunctionConfig();
+	if (!config || !config.app || !config.app.trim()) {
+		console.error("[wawesome] Error: No wawesome-function.json found in the current directory.");
+		console.error("[wawesome] Run 'wawesome init' to create one, or create it manually.");
+		process.exit(1);
+	}
+	return {
+		creds,
+		app: config.app.trim()
+	};
+}
+/**
+* Store one variable on an App, reporting failure by throwing.
+*
+* The endpoint half of `env set`, without the exiting: template scaffolding
+* stores a whole manifest's worth of variables and has already written files by
+* the time it does, so it needs to say what did land before it gives up.
+*/
+async function putEnvVar(creds, app, key, value, isSecret) {
+	const url = `${creds.gateway_url}/v1/apps/${encodeURIComponent(app)}/env`;
+	const res = await fetch(url, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${creds.tenant_jwt}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({
+			key,
+			value,
+			is_secret: isSecret
+		})
+	});
+	if (!res.ok) {
+		if (res.status === 401) throw new GatewayError("Authentication expired. Run 'wawesome login' again.", 401);
+		throw await asGatewayError(res, `Failed to set variable '${key}' (HTTP ${res.status}).`);
+	}
+	return await res.json();
+}
+/**
+* Set or overwrite an environment variable on the current app.
+*/
+async function setEnvVar(key, value, options) {
+	const isVerbose = Boolean(options.verbose);
+	if (!key || value === void 0) {
+		console.error("[wawesome] Error: Missing key or value. Usage: wawesome env set <KEY> <VALUE> [--secret]");
+		process.exit(1);
+	}
+	const { creds, app } = loadClientContext();
+	const isSecret = Boolean(options.secret);
+	if (isVerbose) {
+		console.log(`[wawesome:verbose] POST ${creds.gateway_url}/v1/apps/${encodeURIComponent(app)}/env`);
+		console.log(`[wawesome:verbose] Payload: key=${key}, is_secret=${isSecret}`);
+	}
+	let data;
+	try {
+		data = await putEnvVar(creds, app, key, value, isSecret);
+	} catch (err) {
+		console.error(`[wawesome] Error: ${errorText(err)}`);
+		if (isVerbose && err instanceof GatewayError) console.error(`[wawesome:verbose] Response: ${err.body}`);
+		process.exit(1);
+		return;
+	}
+	if (data.variable.is_secret || isSecret) {
+		console.log(`\n[wawesome] ✅ Set secret variable '${key}' on app '${app}'.`);
+		const messages = data.notice?.messages?.length ? data.notice.messages : STANDARD_SECRET_MESSAGES;
+		console.log("\n🔒 \x1B[1mSecret Notice:\x1B[0m");
+		for (const msg of messages) console.log(`  • ${msg}`);
+		console.log("");
+	} else console.log(`[wawesome] ✅ Set variable '${key}' on app '${app}'.`);
+}
+function truncate(str, maxLen) {
+	if (str.length <= maxLen) return str;
+	if (maxLen <= 3) return str.slice(0, maxLen);
+	return str.slice(0, maxLen - 1) + "…";
+}
+/**
+* List environment variables on the current app.
+*/
+async function listEnvVars(options) {
+	const isVerbose = Boolean(options.verbose);
+	const { creds, app } = loadClientContext();
+	const url = `${creds.gateway_url}/v1/apps/${encodeURIComponent(app)}/env`;
+	if (isVerbose) console.log(`[wawesome:verbose] GET ${url}`);
+	const res = await fetch(url, {
+		method: "GET",
+		headers: { Authorization: `Bearer ${creds.tenant_jwt}` }
+	});
+	if (!res.ok) {
+		const errorBody = await res.text();
+		if (res.status === 401) console.error("[wawesome] Error: Authentication expired. Run 'wawesome login' again.");
+		else {
+			console.error(`[wawesome] Error: Failed to list variables (HTTP ${res.status}).`);
+			if (isVerbose) console.error(`[wawesome:verbose] Response: ${errorBody}`);
+		}
+		process.exit(1);
+	}
+	const data = await res.json();
+	if (!data.variables || data.variables.length === 0) {
+		console.log(`[wawesome] No environment variables set for app '${app}'.`);
+		return;
+	}
+	const availableWidth = (process.stdout.columns && process.stdout.columns > 40 ? process.stdout.columns : 80) - 12;
+	let rawMaxKeyLen = 15;
+	let rawMaxValLen = 15;
+	for (const item of data.variables) {
+		if (item.key.length > rawMaxKeyLen) rawMaxKeyLen = item.key.length;
+		if (item.value.length > rawMaxValLen) rawMaxValLen = item.value.length;
+	}
+	const maxKeyLen = Math.min(rawMaxKeyLen, Math.max(15, Math.floor(availableWidth * .4)));
+	const maxValLen = Math.min(rawMaxValLen, Math.max(15, availableWidth - maxKeyLen));
+	console.log(`\n📋 \x1b[1mEnvironment variables for '${app}'\x1b[0m\n`);
+	const headerKey = "KEY".padEnd(maxKeyLen);
+	const headerVal = "VALUE".padEnd(maxValLen);
+	console.log(`${headerKey} | ${headerVal} | SECRET`);
+	console.log(`${"-".repeat(maxKeyLen)}-|- ${"-".repeat(maxValLen)} |-------`);
+	for (const item of data.variables) {
+		const truncatedKey = truncate(item.key, maxKeyLen);
+		const truncatedVal = truncate(item.value, maxValLen);
+		const keyStr = truncatedKey.padEnd(maxKeyLen);
+		const valStr = truncatedVal.padEnd(maxValLen);
+		const secretStr = item.is_secret ? "\x1B[33mtrue\x1B[0m" : "false";
+		console.log(`${keyStr} | ${valStr} | ${secretStr}`);
+	}
+	console.log("");
+}
+/**
+* Delete an environment variable on the current app.
+*/
+async function removeEnvVar(key, options) {
+	const isVerbose = Boolean(options.verbose);
+	if (!key) {
+		console.error("[wawesome] Error: Missing variable key. Usage: wawesome env rm <KEY>");
+		process.exit(1);
+	}
+	const { creds, app } = loadClientContext();
+	const url = `${creds.gateway_url}/v1/apps/${encodeURIComponent(app)}/env/${encodeURIComponent(key)}`;
+	if (isVerbose) console.log(`[wawesome:verbose] DELETE ${url}`);
+	const res = await fetch(url, {
+		method: "DELETE",
+		headers: { Authorization: `Bearer ${creds.tenant_jwt}` }
+	});
+	if (!res.ok) {
+		const errorBody = await res.text();
+		if (res.status === 401) console.error("[wawesome] Error: Authentication expired. Run 'wawesome login' again.");
+		else if (res.status === 404) console.error(`[wawesome] Error: Variable '${key}' not found on app '${app}'.`);
+		else {
+			console.error(`[wawesome] Error: Failed to delete variable '${key}' (HTTP ${res.status}).`);
+			if (isVerbose) console.error(`[wawesome:verbose] Response: ${errorBody}`);
+		}
+		process.exit(1);
+	}
+	console.log(`[wawesome] ✅ Deleted variable '${key}' from app '${app}'.`);
+}
+/**
+* Dispatcher function for `wawesome env` CLI command.
+*/
+async function envCommand(action, key, value, options) {
+	if (!action || action === "list" || action === "ls") return listEnvVars(options);
+	if (action === "set") return setEnvVar(key, value, options);
+	if (action === "rm" || action === "remove" || action === "delete" || action === "unset") return removeEnvVar(key, options);
+	console.error(`[wawesome] Error: Unknown env action '${action}'. Available actions: list, set, rm.`);
+	process.exit(1);
+}
+//#endregion
+//#region src/provision.ts
+/** The gateway's own words for a failure, or a plain HTTP status if it gave none. */
+async function rejected(res, fallback) {
+	if (res.status === 401) return new GatewayError("Authentication expired. Run 'wawesome login' again.", 401);
+	return asGatewayError(res, `${fallback} (HTTP ${res.status}).`);
+}
+function authHeaders(creds) {
+	return {
+		Authorization: `Bearer ${creds.tenant_jwt}`,
+		"Content-Type": "application/json"
+	};
+}
+/**
+* Make sure the App exists before anything is attached to it.
+*
+* Environment variables and subscriptions are both App-scoped, and neither
+* endpoint creates one — deploy would, but it runs last, and a Function that
+* goes live before its secrets do is a Function that fails its first request.
+*
+* Listing first rather than creating and reading the error keeps the common
+* case ("I already have this App") off the failure path; an App that appears in
+* between is still treated as the success it is.
+*/
+async function ensureApp(creds, appSlug) {
+	const listRes = await fetch(`${creds.gateway_url}/v1/apps`, { headers: { Authorization: `Bearer ${creds.tenant_jwt}` } });
+	if (!listRes.ok) throw await rejected(listRes, "Could not list the Tenant's apps");
+	if ((await listRes.json()).applications?.some((app) => app.slug === appSlug)) return;
+	const createRes = await fetch(`${creds.gateway_url}/v1/apps`, {
+		method: "POST",
+		headers: authHeaders(creds),
+		body: JSON.stringify({
+			name: appSlug,
+			slug: appSlug
+		})
+	});
+	if (createRes.ok) return;
+	const error = await rejected(createRes, `Could not create the app '${appSlug}'`);
+	if (/already exists/i.test(error.message)) return;
+	throw error;
+}
+/**
+* Enable one catalogue provider for the App.
+*
+* A template declares the providers it calls; without the subscription the
+* platform's egress policy denies those calls, so this is what stands between a
+* scaffolded template and an outbound request that silently fails at runtime.
+*/
+async function enableEgressProvider(creds, appSlug, providerKey) {
+	const url = `${creds.gateway_url}/v1/apps/${encodeURIComponent(appSlug)}/egress/subscriptions`;
+	const res = await fetch(url, {
+		method: "POST",
+		headers: authHeaders(creds),
+		body: JSON.stringify({ provider_key: providerKey })
+	});
+	if (!res.ok) throw await rejected(res, `Could not enable outbound provider '${providerKey}'`);
+}
+//#endregion
+//#region src/scaffold.ts
+const MANIFEST_FILE = "template.json";
+const PACKAGE_FILE = "package.json";
+const FUNCTION_CONFIG_FILE = "wawesome-function.json";
+/** Read the template's requirements declaration out of a scaffolded directory. */
+function readTemplateManifest(dir) {
+	const manifestPath = path.join(dir, MANIFEST_FILE);
+	if (!fs.existsSync(manifestPath)) throw new Error(`The template has no ${MANIFEST_FILE}, so there is nothing to set it up from.`);
+	let raw;
+	try {
+		raw = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+	} catch (err) {
+		throw new Error(`The template's ${MANIFEST_FILE} is not valid JSON: ${errorText(err)}`);
+	}
+	return {
+		env: Array.isArray(raw.env) ? raw.env : [],
+		providers: Array.isArray(raw.providers) ? raw.providers : [],
+		post_deploy: typeof raw.post_deploy === "string" ? raw.post_deploy : ""
+	};
+}
+/**
+* Patch the two configuration files, and nothing else.
+*
+* Every placeholder originally scoped for substitution turned out to be
+* something else: the Tenant slug never appears in template source, and a
+* template's environment-variable *names* are fixed by its own code. What is
+* left is identity — which App this is, and what the Function is called.
+*/
+function applyTemplateIdentity(dir, identity) {
+	patchJson(path.join(dir, PACKAGE_FILE), (pkg) => ({
+		...pkg,
+		name: identity.functionName
+	}));
+	patchJson(path.join(dir, FUNCTION_CONFIG_FILE), (config) => ({
+		...config,
+		app: identity.app,
+		function: identity.functionName
+	}));
+}
+function patchJson(file, patch) {
+	if (!fs.existsSync(file)) throw new Error(`The template is missing ${path.basename(file)}, which scaffolding must patch.`);
+	let current;
+	try {
+		current = JSON.parse(fs.readFileSync(file, "utf-8"));
+	} catch (err) {
+		throw new Error(`The template's ${path.basename(file)} is not valid JSON: ${errorText(err)}`);
+	}
+	fs.writeFileSync(file, JSON.stringify(patch(current), null, 2) + "\n", "utf-8");
+}
+/**
+* Which of the files a scaffold is about to write are already there.
+*
+* Checked before the first byte is written: half a template over half a project
+* is worse than refusing, and the user is the only one who knows which they
+* meant to keep.
+*/
+function collidingPaths(dir, relativePaths) {
+	return relativePaths.filter((relative) => fs.existsSync(path.join(dir, relative)));
+}
+/**
+* Fill the post-deploy message in. `{{url}}` is the only placeholder anywhere in
+* the template system, and it never touches a source file — if the address could
+* not be resolved the message still prints, with the placeholder left visible
+* rather than a confident "undefined".
+*/
+function renderPostDeploy(postDeploy, invokeUrl) {
+	if (!invokeUrl) return postDeploy;
+	return postDeploy.split("{{url}}").join(invokeUrl);
+}
+/**
+* Normalise arbitrary input into a legal DNS label, returning an empty string
+* when nothing legal survives — callers decide whether that is an error.
+*/
+function sanitizeSlug(raw) {
+	let label = "";
+	for (const c of raw.trim().toLowerCase()) if (c >= "a" && c <= "z") label += c;
+	else if (c >= "0" && c <= "9") label += c;
+	else if (label.length > 0 && !label.endsWith("-")) label += "-";
+	label = label.slice(0, 63);
+	while (label.endsWith("-")) label = label.slice(0, -1);
+	return label;
+}
+/**
+* Whether `candidate` is already a legal DNS label — i.e. whether
+* {@link sanitizeSlug} would leave it untouched.
+*/
+function isLegalSlug(candidate) {
+	return candidate.length > 0 && candidate.length <= 63 && !candidate.startsWith("-") && !candidate.endsWith("-") && !candidate.includes("--") && /^[a-z0-9-]+$/.test(candidate);
+}
+//#endregion
+//#region src/tarball.ts
+/**
+* Reading a repository archive, so scaffolding needs no git.
+*
+* Git being absent is the common case for the audience this platform is for, and
+* on Windows it is the *normal* case — so the template arrives as a `.tar.gz`
+* over plain HTTP and is unpacked here. Node ships gzip; the tar half is 512-byte
+* blocks, which is little enough code that carrying a dependency for it would
+* cost more than it saves.
+*
+* An archive is untrusted input even when it comes from a URL the platform
+* chose: extraction refuses anything whose path could land outside the
+* destination, and refuses links entirely, before writing a single file.
+*/
+const BLOCK_SIZE = 512;
+/** Where each field a header carries begins, and how long it is. */
+const NAME = {
+	at: 0,
+	len: 100
+};
+const MODE = {
+	at: 100,
+	len: 8
+};
+const SIZE = {
+	at: 124,
+	len: 12
+};
+const TYPE_FLAG = 156;
+const MAGIC = {
+	at: 257,
+	len: 6
+};
+const PREFIX = {
+	at: 345,
+	len: 155
+};
+/** Entry types extraction acts on. Everything else is metadata or refused. */
+const TYPE_FILE = "0";
+const TYPE_FILE_ALT = "\0";
+const TYPE_DIRECTORY = "5";
+const TYPE_SYMLINK = "2";
+const TYPE_HARDLINK = "1";
+const TYPE_PAX_NEXT = "x";
+const TYPE_PAX_GLOBAL = "g";
+const TYPE_GNU_LONGNAME = "L";
+/** A tar the CLI cannot make sense of, phrased for whoever is watching. */
+var ArchiveError = class extends Error {};
+function field(block, at, len) {
+	const raw = block.toString("utf-8", at, at + len);
+	const end = raw.indexOf("\0");
+	return end === -1 ? raw : raw.slice(0, end);
+}
+function octal(block, at, len) {
+	const text = field(block, at, len).trim();
+	if (!text) return 0;
+	const value = parseInt(text, 8);
+	return Number.isFinite(value) ? value : 0;
+}
+/**
+* The path an entry claims, honouring the two ways a long one is recorded:
+* split across the `ustar` prefix field, or carried by the pax header that
+* precedes it. Both come out of a real `git archive` — which one you get depends
+* only on where the path's slashes happen to fall.
+*/
+function entryPath(block, paxPath) {
+	if (paxPath) return paxPath;
+	const name = field(block, NAME.at, NAME.len);
+	const prefix = field(block, PREFIX.at, PREFIX.len);
+	return prefix ? `${prefix}/${name}` : name;
+}
+/** The `path=` record of a pax extended header, if it declares one. */
+function paxHeaderPath(body) {
+	let offset = 0;
+	while (offset < body.length) {
+		const space = body.indexOf(32, offset);
+		if (space === -1) break;
+		const length = parseInt(body.toString("ascii", offset, space), 10);
+		if (!Number.isFinite(length) || length <= 0) break;
+		const record = body.toString("utf-8", space + 1, offset + length).replace(/\n$/, "");
+		const eq = record.indexOf("=");
+		if (eq !== -1 && record.slice(0, eq) === "path") return record.slice(eq + 1);
+		offset += length;
+	}
+	return null;
+}
+/**
+* Every file in a tar, in archive order.
+*
+* Refuses links rather than skipping them: a symlink extracted into the
+* destination turns a later, innocent-looking entry into a write anywhere on
+* the filesystem, and no template has a reason to ship one.
+*/
+function readEntries(tar) {
+	const entries = [];
+	let paxPath = null;
+	let offset = 0;
+	let sawHeader = false;
+	while (offset + BLOCK_SIZE <= tar.length) {
+		const block = tar.subarray(offset, offset + BLOCK_SIZE);
+		offset += BLOCK_SIZE;
+		if (block.every((byte) => byte === 0)) break;
+		if (!field(block, MAGIC.at, MAGIC.len).startsWith("ustar")) throw new ArchiveError("The downloaded file is not a tar archive.");
+		sawHeader = true;
+		const size = octal(block, SIZE.at, SIZE.len);
+		const bodyEnd = offset + size;
+		if (bodyEnd > tar.length) throw new ArchiveError("The downloaded archive is truncated.");
+		const body = tar.subarray(offset, bodyEnd);
+		offset += Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE;
+		const type = String.fromCharCode(block[TYPE_FLAG]);
+		if (type === TYPE_PAX_NEXT || type === TYPE_GNU_LONGNAME) {
+			paxPath = type === TYPE_GNU_LONGNAME ? field(body, 0, body.length) : paxHeaderPath(body);
+			continue;
+		}
+		if (type === TYPE_PAX_GLOBAL) continue;
+		const recorded = entryPath(block, paxPath);
+		paxPath = null;
+		if (type === TYPE_SYMLINK || type === TYPE_HARDLINK) throw new ArchiveError(`The archive contains a link ('${recorded}'), which is not extracted.`);
+		if (type === TYPE_DIRECTORY) continue;
+		if (type !== TYPE_FILE && type !== TYPE_FILE_ALT) continue;
+		entries.push({
+			path: recorded,
+			mode: octal(block, MODE.at, MODE.len),
+			body
+		});
+	}
+	if (!sawHeader) throw new ArchiveError("The downloaded file is not a tar archive.");
+	return entries;
+}
+/** Drop the archive's single root directory, the way `--strip-components=1` does. */
+function withoutArchiveRoot(entryPath) {
+	const firstSlash = entryPath.indexOf("/");
+	if (firstSlash === -1) return null;
+	return entryPath.slice(firstSlash + 1);
+}
+/**
+* The path an entry takes inside the template directory, or `null` if it belongs
+* to a different one. `.` means the template owns the whole repository.
+*/
+function withinDirectory(entryPath, directory) {
+	if (directory === "." || directory === "") return entryPath;
+	const prefix = `${directory}/`;
+	return entryPath.startsWith(prefix) ? entryPath.slice(prefix.length) : null;
+}
+/**
+* Unpack one template directory out of a repository archive.
+*
+* Contents are written exactly as they were recorded — a template is a real
+* project, so nothing here rewrites, re-encodes or substitutes anything. The
+* whole archive is validated before the first write, so a refused entry leaves
+* the destination as it found it rather than half-scaffolded.
+*
+* Returns the paths written, relative to `destination`.
+*/
+function extractTemplateDirectory(archive, options) {
+	let tar;
+	try {
+		tar = zlib.gunzipSync(archive);
+	} catch {
+		throw new ArchiveError("The downloaded file is not a gzip archive.");
+	}
+	const { directory, destination } = options;
+	const root = path.resolve(destination);
+	const planned = [];
+	for (const entry of readEntries(tar)) {
+		if (path.posix.isAbsolute(entry.path) || /^[A-Za-z]:/.test(entry.path)) throw new ArchiveError(`The archive contains an absolute path ('${entry.path}').`);
+		const stripped = withoutArchiveRoot(entry.path);
+		if (stripped === null) continue;
+		const relative = withinDirectory(stripped, directory);
+		if (relative === null || relative === "") continue;
+		const absolute = path.resolve(root, relative);
+		if (absolute !== root && !absolute.startsWith(root + path.sep)) throw new ArchiveError(`The archive contains a path outside the project ('${entry.path}').`);
+		planned.push({
+			absolute,
+			relative,
+			entry
+		});
+	}
+	if (planned.length === 0) throw new ArchiveError(`The archive contains no directory named '${directory}'.`);
+	for (const { absolute, entry } of planned) {
+		fs.mkdirSync(path.dirname(absolute), { recursive: true });
+		fs.writeFileSync(absolute, entry.body, { mode: entry.mode & 511 || 420 });
+	}
+	return planned.map(({ relative }) => relative);
+}
+//#endregion
+//#region src/templates.ts
+/**
+* Read the template catalogue.
+*
+* Deliberately unauthenticated: discovery has to work for someone who has not
+* signed up yet, so no credential is read and none is sent — a stale token file
+* left over from a previous install cannot turn this into a rejection.
+*/
+async function fetchTemplateCatalog(gatewayUrl) {
+	let res;
+	try {
+		res = await fetch(`${gatewayUrl}/v1/templates`);
+	} catch (err) {
+		throw new Error(`Could not reach ${gatewayUrl} to list templates. ${err instanceof Error ? err.message : err}`);
+	}
+	if (!res.ok) throw new Error(`${gatewayUrl} could not list templates (HTTP ${res.status}).`);
+	let data;
+	try {
+		data = await res.json();
+	} catch {
+		throw new Error(`${gatewayUrl} answered with something that is not a template list.`);
+	}
+	if (!Array.isArray(data.templates)) throw new Error(`${gatewayUrl} answered with something that is not a template list.`);
+	return data.templates;
+}
+/**
+* Find one template by the name a user typed after `--template`.
+*
+* Resolved against the catalogue rather than a list compiled in here, so a
+* template added yesterday is scaffoldable by a CLI released last year. An
+* unknown name answers with the names that do exist: the mistake is almost
+* always a typo, and the fix is on screen.
+*/
+async function resolveTemplate(gatewayUrl, name) {
+	const templates = await fetchTemplateCatalog(gatewayUrl);
+	const match = templates.find((template) => template.name === name);
+	if (match) return match;
+	if (templates.length === 0) throw new Error(`No templates are available from ${gatewayUrl} yet.`);
+	const available = templates.map((template) => template.name).join(", ");
+	throw new Error(`No template called '${name}'. Available templates: ${available}.`);
+}
+/**
+* Download a template's archive.
+*
+* From the archive host the catalogue named, rather than the REST API's tarball
+* endpoint: that one is rate-limited per IP for unauthenticated callers, so
+* behind corporate NAT or on a shared runner the very first thing a new user
+* does would fail intermittently, for a reason they cannot diagnose.
+*/
+async function downloadTemplateArchive(archiveUrl) {
+	let res;
+	try {
+		res = await fetch(archiveUrl);
+	} catch (err) {
+		throw new Error(`Could not download the template from ${archiveUrl}. ${errorText(err)}`);
+	}
+	if (!res.ok) throw new Error(`Could not download the template from ${archiveUrl} (HTTP ${res.status}). The template's stable ref may not have been published yet.`);
+	return Buffer.from(await res.arrayBuffer());
+}
+/** List every template in the catalogue. */
+async function listTemplates(options) {
+	const gatewayUrl = getGatewayUrl(options.api);
+	if (options.verbose) console.log(`[wawesome:verbose] GET ${gatewayUrl}/v1/templates`);
+	let templates;
+	try {
+		templates = await fetchTemplateCatalog(gatewayUrl);
+	} catch (err) {
+		console.error(`[wawesome] Error: ${err instanceof Error ? err.message : err}`);
+		process.exit(1);
+		return;
+	}
+	if (templates.length === 0) {
+		console.log("[wawesome] No templates available yet.");
+		return;
+	}
+	console.log("\n📦 \x1B[1mTemplates\x1B[0m\n");
+	for (const template of templates) {
+		console.log(`  \x1b[36m${template.name}\x1b[0m — ${template.title}`);
+		console.log(`    ${template.description}`);
+		if (template.tags.length > 0) console.log(`    \x1b[90m${template.tags.join(", ")}\x1b[0m`);
+		console.log(`    \x1b[90m${template.source_url}\x1b[0m`);
+		if (options.verbose) console.log(`    \x1b[90mref ${template.ref} · ${template.archive_url}\x1b[0m`);
+		console.log("");
+	}
+}
+/** Dispatch for `wawesome templates [action]`. */
+async function templatesCommand(action, options) {
+	if (!action || action === "list" || action === "ls") return listTemplates(options);
+	console.error(`[wawesome] Error: Unknown templates action '${action}'. Available actions: list (alias: ls).`);
+	process.exit(1);
+}
+//#endregion
+//#region src/init.ts
+/** Bound on the re-prompt loop, so unusable input exits instead of looping. */
+const MAX_SLUG_ATTEMPTS = 5;
+/**
+* Ask for a name that becomes part of the public URL, until the answer is one.
+*
+* Both names this asks for — the App the Function belongs to, and the Function
+* itself — end up in the address a client reads, so neither may be taken as
+* typed. An illegal answer is re-offered as a suggestion rather than rewritten:
+* the user sees the name they will get before agreeing to it.
+*/
+async function promptForSlug(session, label, proposed) {
+	let suggestion = sanitizeSlug(proposed);
+	for (let attempt = 0; attempt < MAX_SLUG_ATTEMPTS; attempt++) {
+		const answer = await session.ask(`  ${label}?`, suggestion);
+		if (isLegalSlug(answer)) return answer;
+		const sanitized = sanitizeSlug(answer);
+		if (sanitized) {
+			console.log(`[wawesome] '${answer}' can't be used as ${anArticle(label)}. Suggested: '${sanitized}'.`);
+			suggestion = sanitized;
+		} else console.log(`[wawesome] ${anArticle(label, true)} needs lowercase letters or numbers, separated by single hyphens.`);
+	}
+	console.error(`[wawesome] Error: no usable ${label} after ${MAX_SLUG_ATTEMPTS} attempts. Nothing was written.`);
+	console.error(`[wawesome] Run 'wawesome init' again once you know what to call it.`);
+	process.exit(1);
+}
+/** "an App slug" / "A Function name" — so one prompt reads for both names. */
+function anArticle(label, capitalized = false) {
+	const article = /^[aeiou]/i.test(label) ? "an" : "a";
+	return `${capitalized ? article[0].toUpperCase() + article.slice(1) : article} ${label}`;
+}
+/** Report a failure the user can act on, and stop. */
+function fail(message, ...advice) {
+	console.error(`[wawesome] Error: ${message}`);
+	for (const line of advice) console.error(`[wawesome] ${line}`);
+	process.exit(1);
+	throw new Error(message);
+}
+/**
+* Ask for every variable the template declared.
+*
+* The pointer to where the value lives is shown with the question, because the
+* user is being asked for a value that exists in somebody else's dashboard and
+* hunting for it in third-party documentation is where a first deploy stalls.
+* A blank answer is allowed even for a required variable: for a webhook secret
+* the value does not exist yet — the endpoint has to be created first — so
+* refusing to continue would be refusing the only order that works.
+*/
+async function promptForDeclaredEnv(session, declared) {
+	if (declared.length === 0) return [];
+	console.log("\n[wawesome] This template needs a few values before it can run.\n");
+	const answers = [];
+	for (const variable of declared) {
+		const flags = [variable.required ? "required" : "optional"];
+		if (variable.secret) flags.push("stored write-only");
+		console.log(`  \x1b[1m${variable.key}\x1b[0m \x1b[90m(${flags.join(", ")})\x1b[0m`);
+		console.log(`    ${variable.description}`);
+		console.log(`    \x1b[90mWhere to find it: ${variable.where_to_find}\x1b[0m`);
+		const value = await session.ask(`  ${variable.key}?`, "");
+		console.log("");
+		answers.push({
+			declared: variable,
+			value
+		});
+	}
+	return answers;
+}
+/**
+* Satisfy the template's declarations against the platform.
+*
+* The manifest declares; nothing here is template-specific. Each declaration
+* goes through an endpoint the platform already ships, which is what keeps a new
+* template from needing a CLI release.
+*/
+async function wireUp(creds, appSlug, manifest, answers) {
+	const scaffolded = "Your project is scaffolded — fix this, then run 'wawesome deploy'.";
+	try {
+		await ensureApp(creds, appSlug);
+	} catch (err) {
+		fail(errorText(err), scaffolded);
+	}
+	for (const { declared, value } of answers) {
+		if (!value) {
+			const secretFlag = declared.secret ? " --secret" : "";
+			console.log(`[wawesome] ${declared.key} left blank. Set it with: wawesome env set ${declared.key} <value>${secretFlag}`);
+			continue;
+		}
+		try {
+			await putEnvVar(creds, appSlug, declared.key, value, declared.secret);
+		} catch (err) {
+			fail(errorText(err), scaffolded);
+		}
+		console.log(`[wawesome] ✅ Stored ${declared.key}${declared.secret ? " (secret)" : ""}.`);
+	}
+	for (const provider of manifest.providers) {
+		try {
+			await enableEgressProvider(creds, appSlug, provider);
+		} catch (err) {
+			fail(errorText(err), scaffolded);
+		}
+		console.log(`[wawesome] ✅ Enabled outbound calls to '${provider}'.`);
 	}
-	console.log("\n======================================================");
-	console.log("🚀 \x1B[32mDEPLOYED SUCCESSFULLY!\x1B[0m");
-	console.log("======================================================");
-	console.log(`\n  App:      ${app}`);
-	console.log(`  Function: ${funcName}`);
-	if (version !== void 0) console.log(`  Version:  ${version}`);
-	console.log("======================================================\n");
 }
-//#endregion
-//#region src/init.ts
-function prompt(question, defaultVal) {
-	const rl = readline.createInterface({
-		input: process.stdin,
-		output: process.stdout
+/**
+* Scaffold from a catalogue template, wire up what it declared, and deploy it.
+*
+* The template arrives as a repository archive over plain HTTP — no git, which
+* makes this work on a machine that has never had it installed, and on Windows.
+* It is unpacked into a staging directory first, so a template that turns out to
+* collide with what is already here leaves the directory exactly as it found it.
+*/
+async function initFromTemplate(templateName, options) {
+	const isVerbose = Boolean(options.verbose);
+	const gatewayUrl = getGatewayUrl(options.api);
+	const cwd = process.cwd();
+	const dirName = path.basename(cwd);
+	let template;
+	try {
+		template = await resolveTemplate(gatewayUrl, templateName);
+	} catch (err) {
+		fail(errorText(err));
+	}
+	console.log(`[wawesome] Fetching ${template.title} (${template.ref})...`);
+	if (isVerbose) console.log(`[wawesome:verbose] GET ${template.archive_url}`);
+	let archive;
+	try {
+		archive = await downloadTemplateArchive(template.archive_url);
+	} catch (err) {
+		fail(errorText(err));
+	}
+	const staging = fs.mkdtempSync(path.join(os.tmpdir(), "wawesome-template-"));
+	const sweepStaging = () => fs.rmSync(staging, {
+		recursive: true,
+		force: true
 	});
-	return new Promise((resolve) => {
-		rl.question(`${question} (${defaultVal}): `, (answer) => {
-			rl.close();
-			resolve(answer.trim() || defaultVal);
-		});
+	process.once("exit", sweepStaging);
+	const session = openPromptSession();
+	let functionName;
+	let appSlug;
+	let manifest;
+	try {
+		let files;
+		try {
+			files = extractTemplateDirectory(archive, {
+				directory: template.directory,
+				destination: staging
+			});
+			manifest = readTemplateManifest(staging);
+		} catch (err) {
+			fail(errorText(err));
+		}
+		const collisions = collidingPaths(cwd, files);
+		if (collisions.length > 0) fail(`${collisions.join(", ")} already exist${collisions.length === 1 ? "s" : ""} here.`, "Run this in an empty directory, or move those files aside first. Nothing was written.");
+		functionName = await promptForSlug(session, "Function name", readFunctionConfig(staging)?.function || dirName);
+		console.log("  (an App groups the Functions of one project — its slug is part of the public URL)");
+		appSlug = await promptForSlug(session, "App slug", dirName);
+		try {
+			fs.cpSync(staging, cwd, { recursive: true });
+			applyTemplateIdentity(cwd, {
+				app: appSlug,
+				functionName
+			});
+		} catch (err) {
+			fail(errorText(err), `Some of '${template.name}' may have been written to ${cwd}.`);
+		}
+		console.log(`\n[wawesome] ✅ Scaffolded ${files.length} files from '${template.name}'.`);
+	} finally {
+		sweepStaging();
+		process.off("exit", sweepStaging);
+	}
+	let answers = [];
+	let creds;
+	try {
+		creds = readCredentials();
+		if (creds) answers = await promptForDeclaredEnv(session, manifest.env);
+	} finally {
+		session.close();
+	}
+	if (!creds) {
+		console.log("\n[wawesome] 🎉 Project ready. Next steps:");
+		console.log("  1. npm install");
+		console.log("  2. wawesome login");
+		console.log("  3. wawesome deploy\n");
+		return;
+	}
+	await wireUp(creds, appSlug, manifest, answers);
+	const result = await deploy(void 0, {
+		out: "dist/index.js",
+		verbose: options.verbose
 	});
+	if (manifest.post_deploy) {
+		console.log(renderPostDeploy(manifest.post_deploy, result.invokeUrl));
+		console.log("");
+	}
 }
 /**
 * Scaffold a new wawesome function project in the current directory.
 */
 async function init(options) {
+	if (options.template) return initFromTemplate(options.template, options);
 	const isVerbose = Boolean(options.verbose);
 	const cwd = process.cwd();
 	const dirName = path.basename(cwd);
 	console.log("[wawesome] Initializing a new function project...\n");
-	const functionName = await prompt("  Function name?", dirName);
-	const appSlug = await prompt("  App slug?", "default-app");
+	const session = openPromptSession();
+	let functionName;
+	let appSlug;
+	try {
+		functionName = await promptForSlug(session, "Function name", dirName);
+		console.log("  (an App groups the Functions of one project — its slug is part of the public URL)");
+		appSlug = await promptForSlug(session, "App slug", dirName);
+	} finally {
+		session.close();
+	}
 	const entry = "src/index.ts";
 	if (isVerbose) console.log(`[wawesome:verbose] function=${functionName}, app=${appSlug}, entry=${entry}`);
 	const configContent = {
@@ -666,177 +1674,6 @@ async function switchVersion(targetInput, options) {
 	console.log(`======================================================\n`);
 }
 //#endregion
-//#region src/env.ts
-const STANDARD_SECRET_MESSAGES = [
-	"Encrypted at rest using AES-256",
-	"This value can't be viewed again after you save it — only updated or deleted",
-	"Only decrypted at the moment your function runs — never returned by the CLI, dashboard, or API after creation."
-];
-/**
-* Load credentials and validate project config.
-*/
-function loadClientContext() {
-	const creds = readCredentials();
-	if (!creds) {
-		console.error("[wawesome] Error: Not logged in. Run 'wawesome login' first.");
-		process.exit(1);
-	}
-	const config = readFunctionConfig();
-	if (!config || !config.app || !config.app.trim()) {
-		console.error("[wawesome] Error: No wawesome-function.json found in the current directory.");
-		console.error("[wawesome] Run 'wawesome init' to create one, or create it manually.");
-		process.exit(1);
-	}
-	return {
-		creds,
-		app: config.app.trim()
-	};
-}
-/**
-* Set or overwrite an environment variable on the current app.
-*/
-async function setEnvVar(key, value, options) {
-	const isVerbose = Boolean(options.verbose);
-	if (!key || value === void 0) {
-		console.error("[wawesome] Error: Missing key or value. Usage: wawesome env set <KEY> <VALUE> [--secret]");
-		process.exit(1);
-	}
-	const { creds, app } = loadClientContext();
-	const isSecret = Boolean(options.secret);
-	const url = `${creds.gateway_url}/v1/apps/${encodeURIComponent(app)}/env`;
-	if (isVerbose) {
-		console.log(`[wawesome:verbose] POST ${url}`);
-		console.log(`[wawesome:verbose] Payload: key=${key}, is_secret=${isSecret}`);
-	}
-	const res = await fetch(url, {
-		method: "POST",
-		headers: {
-			Authorization: `Bearer ${creds.tenant_jwt}`,
-			"Content-Type": "application/json"
-		},
-		body: JSON.stringify({
-			key,
-			value,
-			is_secret: isSecret
-		})
-	});
-	if (!res.ok) {
-		const errorBody = await res.text();
-		if (res.status === 401) console.error("[wawesome] Error: Authentication expired. Run 'wawesome login' again.");
-		else {
-			let msg = `HTTP ${res.status}`;
-			try {
-				const parsed = JSON.parse(errorBody);
-				if (parsed.error) msg = parsed.error;
-			} catch {}
-			console.error(`[wawesome] Error: Failed to set variable '${key}' (${msg}).`);
-			if (isVerbose) console.error(`[wawesome:verbose] Response: ${errorBody}`);
-		}
-		process.exit(1);
-	}
-	const data = await res.json();
-	if (data.variable.is_secret || isSecret) {
-		console.log(`\n[wawesome] ✅ Set secret variable '${key}' on app '${app}'.`);
-		const messages = data.notice?.messages?.length ? data.notice.messages : STANDARD_SECRET_MESSAGES;
-		console.log("\n🔒 \x1B[1mSecret Notice:\x1B[0m");
-		for (const msg of messages) console.log(`  • ${msg}`);
-		console.log("");
-	} else console.log(`[wawesome] ✅ Set variable '${key}' on app '${app}'.`);
-}
-function truncate(str, maxLen) {
-	if (str.length <= maxLen) return str;
-	if (maxLen <= 3) return str.slice(0, maxLen);
-	return str.slice(0, maxLen - 1) + "…";
-}
-/**
-* List environment variables on the current app.
-*/
-async function listEnvVars(options) {
-	const isVerbose = Boolean(options.verbose);
-	const { creds, app } = loadClientContext();
-	const url = `${creds.gateway_url}/v1/apps/${encodeURIComponent(app)}/env`;
-	if (isVerbose) console.log(`[wawesome:verbose] GET ${url}`);
-	const res = await fetch(url, {
-		method: "GET",
-		headers: { Authorization: `Bearer ${creds.tenant_jwt}` }
-	});
-	if (!res.ok) {
-		const errorBody = await res.text();
-		if (res.status === 401) console.error("[wawesome] Error: Authentication expired. Run 'wawesome login' again.");
-		else {
-			console.error(`[wawesome] Error: Failed to list variables (HTTP ${res.status}).`);
-			if (isVerbose) console.error(`[wawesome:verbose] Response: ${errorBody}`);
-		}
-		process.exit(1);
-	}
-	const data = await res.json();
-	if (!data.variables || data.variables.length === 0) {
-		console.log(`[wawesome] No environment variables set for app '${app}'.`);
-		return;
-	}
-	const availableWidth = (process.stdout.columns && process.stdout.columns > 40 ? process.stdout.columns : 80) - 12;
-	let rawMaxKeyLen = 15;
-	let rawMaxValLen = 15;
-	for (const item of data.variables) {
-		if (item.key.length > rawMaxKeyLen) rawMaxKeyLen = item.key.length;
-		if (item.value.length > rawMaxValLen) rawMaxValLen = item.value.length;
-	}
-	const maxKeyLen = Math.min(rawMaxKeyLen, Math.max(15, Math.floor(availableWidth * .4)));
-	const maxValLen = Math.min(rawMaxValLen, Math.max(15, availableWidth - maxKeyLen));
-	console.log(`\n📋 \x1b[1mEnvironment variables for '${app}'\x1b[0m\n`);
-	const headerKey = "KEY".padEnd(maxKeyLen);
-	const headerVal = "VALUE".padEnd(maxValLen);
-	console.log(`${headerKey} | ${headerVal} | SECRET`);
-	console.log(`${"-".repeat(maxKeyLen)}-|- ${"-".repeat(maxValLen)} |-------`);
-	for (const item of data.variables) {
-		const truncatedKey = truncate(item.key, maxKeyLen);
-		const truncatedVal = truncate(item.value, maxValLen);
-		const keyStr = truncatedKey.padEnd(maxKeyLen);
-		const valStr = truncatedVal.padEnd(maxValLen);
-		const secretStr = item.is_secret ? "\x1B[33mtrue\x1B[0m" : "false";
-		console.log(`${keyStr} | ${valStr} | ${secretStr}`);
-	}
-	console.log("");
-}
-/**
-* Delete an environment variable on the current app.
-*/
-async function removeEnvVar(key, options) {
-	const isVerbose = Boolean(options.verbose);
-	if (!key) {
-		console.error("[wawesome] Error: Missing variable key. Usage: wawesome env rm <KEY>");
-		process.exit(1);
-	}
-	const { creds, app } = loadClientContext();
-	const url = `${creds.gateway_url}/v1/apps/${encodeURIComponent(app)}/env/${encodeURIComponent(key)}`;
-	if (isVerbose) console.log(`[wawesome:verbose] DELETE ${url}`);
-	const res = await fetch(url, {
-		method: "DELETE",
-		headers: { Authorization: `Bearer ${creds.tenant_jwt}` }
-	});
-	if (!res.ok) {
-		const errorBody = await res.text();
-		if (res.status === 401) console.error("[wawesome] Error: Authentication expired. Run 'wawesome login' again.");
-		else if (res.status === 404) console.error(`[wawesome] Error: Variable '${key}' not found on app '${app}'.`);
-		else {
-			console.error(`[wawesome] Error: Failed to delete variable '${key}' (HTTP ${res.status}).`);
-			if (isVerbose) console.error(`[wawesome:verbose] Response: ${errorBody}`);
-		}
-		process.exit(1);
-	}
-	console.log(`[wawesome] ✅ Deleted variable '${key}' from app '${app}'.`);
-}
-/**
-* Dispatcher function for `wawesome env` CLI command.
-*/
-async function envCommand(action, key, value, options) {
-	if (!action || action === "list" || action === "ls") return listEnvVars(options);
-	if (action === "set") return setEnvVar(key, value, options);
-	if (action === "rm" || action === "remove" || action === "delete" || action === "unset") return removeEnvVar(key, options);
-	console.error(`[wawesome] Error: Unknown env action '${action}'. Available actions: list, set, rm.`);
-	process.exit(1);
-}
-//#endregion
 //#region src/logs.ts
 const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function isUuid(str) {
@@ -1323,6 +2160,105 @@ async function followFunctionLog(gatewayUrl, tenantJwt, funcNameInput, appOverri
 	}
 }
 //#endregion
+//#region src/workspace.ts
+function requireCredentials() {
+	const creds = readCredentials();
+	if (!creds) {
+		console.error("[wawesome] Error: Not logged in. Run 'wawesome login' first.");
+		process.exit(1);
+	}
+	return creds;
+}
+/**
+* Show the workspace's name, address, and whether that address is still free to
+* change — the rename is offered here rather than discovered by attempting it.
+*/
+async function showWorkspace(options) {
+	const creds = requireCredentials();
+	let tenant;
+	try {
+		tenant = await fetchTenantDetails(creds);
+	} catch (err) {
+		console.error(`[wawesome] Error: ${err instanceof Error ? err.message : err}`);
+		process.exit(1);
+	}
+	console.log("\n[wawesome] Workspace:");
+	console.log(`  Name:     ${tenant.name}`);
+	console.log(`  Address:  ${tenant.tenant_slug}`);
+	console.log(`  Tenant:   ${tenant.id}`);
+	if (options.verbose) console.log(`  Invoke:   ${creds.gateway_url}/v1/s/${tenant.tenant_slug}/apps/<app>/functions/<function>/invoke`);
+	if (tenant.slug_locked) console.log("\n  🔒 The address is fixed — a Function version has been promoted and live URLs carry it.");
+	else {
+		console.log("\n  The address can still be changed: \x1B[36mwawesome workspace rename <name>\x1B[0m");
+		console.log("  It locks for good the first time you deploy.");
+	}
+	console.log("");
+}
+/**
+* Change the workspace's public address.
+*
+* The lock is read from the gateway before asking, so a user who cannot rename
+* is told why instead of being walked into a rejection. The rejection is still
+* handled: a promotion landing between the two calls is the one case where the
+* gateway knows something this command could not.
+*/
+async function renameWorkspace(slug, options) {
+	const creds = requireCredentials();
+	if (!slug || !slug.trim()) {
+		console.error("[wawesome] Error: No name given. Usage: wawesome workspace rename <name>");
+		process.exit(1);
+		return;
+	}
+	try {
+		const tenant = await fetchTenantDetails(creds);
+		if (tenant.slug_locked) {
+			console.error("\n[wawesome] \x1B[31mThe workspace address can no longer be changed.\x1B[0m");
+			console.error(`[wawesome] '${tenant.tenant_slug}' is fixed: a Function version has been promoted, and live URLs already carry it.`);
+			process.exit(1);
+			return;
+		}
+		if (options.verbose) console.log(`[wawesome:verbose] Renaming '${tenant.tenant_slug}' → '${slug}'`);
+		const result = await renameTenantSlug(creds, slug.trim());
+		console.log("\n======================================================");
+		console.log("✅ \x1B[32mWORKSPACE RENAMED\x1B[0m");
+		console.log("======================================================");
+		console.log(`\n  Address:  ${result.tenant_slug}`);
+		console.log(`  Previous: ${result.previous_slug} (still resolves)`);
+		console.log("======================================================\n");
+	} catch (err) {
+		if (err instanceof GatewayError) {
+			console.error(`\n[wawesome] \x1b[31m${err.message}\x1b[0m`);
+			switch (err.reason) {
+				case "taken":
+					console.error("[wawesome] Pick a different name.");
+					break;
+				case "reserved":
+					console.error("[wawesome] Pick a different name.");
+					break;
+				case "malformed":
+					console.error("[wawesome] Use lowercase letters, numbers and single hyphens.");
+					break;
+				case "locked":
+					console.error("[wawesome] A deploy landed while this was running, which fixed the address for good.");
+					break;
+			}
+			console.error("");
+			process.exit(1);
+			return;
+		}
+		console.error(`[wawesome] Error: ${err instanceof Error ? err.message : err}`);
+		process.exit(1);
+	}
+}
+/** Dispatch for `wawesome workspace [action]`. */
+async function workspaceCommand(action, target, options) {
+	if (!action || action === "show" || action === "info") return showWorkspace(options);
+	if (action === "rename") return renameWorkspace(target, options);
+	console.error(`[wawesome] Error: Unknown workspace action '${action}'.`);
+	console.error("[wawesome] Usage: wawesome workspace [show|rename <name>]");
+	process.exit(1);
+}
+//#endregion
 //#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));
@@ -1338,10 +2274,12 @@ cli.command("env [action] [key] [value]", "Manage environment variables (set, li
 cli.command("env set <key> <value>", "Set or overwrite an environment variable on the current app").option("-s, --secret", "Flag variable as secret (write-only)").option("-v, --verbose", "Enable verbose debug output").action((key, value, options) => setEnvVar(key, value, options));
 cli.command("env list", "List environment variables for the current app").alias("env ls").option("-v, --verbose", "Enable verbose debug output").action((options) => listEnvVars(options));
 cli.command("env rm <key>", "Delete an environment variable from the current app").alias("env remove").alias("env delete").alias("env unset").option("-v, --verbose", "Enable verbose debug output").action((key, options) => removeEnvVar(key, options));
-cli.command("login", "Authenticate with the wawesome.io platform").option("--api <url>", "API URL (default: https://api.wawesome.io)").option("--gateway <url>", "Alias for --api <url>").option("--provider <name>", "OAuth provider (default: github)").option("-v, --verbose", "Enable verbose debug output").action((options) => login(options));
+cli.command("login", "Authenticate with the wawesome.io platform").option("--api <url>", "API URL (default: https://api.wawesome.io)").option("--gateway <url>", "Alias for --api <url>").option("--provider <name>", "OAuth provider (default: github)").option("--workspace <name>", "Name for the workspace, when signing up without a terminal to prompt").option("-v, --verbose", "Enable verbose debug output").action((options) => login(options));
 cli.command("logout", "Clear stored authentication credentials").action(() => logout());
 cli.command("whoami", "Show current login session info").action(() => whoami());
-cli.command("init", "Scaffold a new function project in the current directory").option("-v, --verbose", "Enable verbose debug output").action((options) => init(options));
+cli.command("workspace [action] [name]", "Show the workspace, or rename its public address").usage("workspace <action> [name]\n\nActions:\n  show                Show the workspace name, address, and whether it can still change\n  rename <name>       Change the public address, while nothing live depends on it").example("wawesome workspace").example("wawesome workspace rename northwind").option("-v, --verbose", "Enable verbose debug output").action((action, name, options) => workspaceCommand(action, name, options));
+cli.command("templates [action]", "Browse the template catalog").usage("templates [action]\n\nActions:\n  list (ls)           Show every available template (default)").example("wawesome templates").example("wawesome templates list").option("--api <url>", "API URL (default: https://api.wawesome.io)").option("-v, --verbose", "Enable verbose debug output").action((action, options) => templatesCommand(action, options));
+cli.command("init", "Scaffold a new function project in the current directory").usage("init [options]\n\nWith --template, the project is fetched from the template catalog, wired up\nfrom what the template declares it needs, and deployed. Run 'wawesome templates'\nto see what is available.").example("wawesome init").example("wawesome init --template stripe-webhook").option("-t, --template <name>", "Scaffold from a catalog template and deploy it").option("--api <url>", "API URL (default: https://api.wawesome.io)").option("-v, --verbose", "Enable verbose debug output").action((options) => init(options));
 cli.command("logs [function-name-or-invocation-id]", "View invocation history, fetch log output, or follow live").usage(`logs [target] [options]
 
   The target argument determines what the command does: