@wervt/cli 0.2.14 → 0.2.16

package/README.md

@@ -16,5 +16,5 @@ vp exec wervt logs my-app
 ```
 
 Without [Vite+](https://viteplus.dev), use `npx @wervt/cli` and `pnpm exec wervt`. `wervt --help`
-lists every command: `apps`, `releases`, `rollback`, `activate`, `env`, `tokens`, `members`,
+lists every command: `apps`, `releases`, `audit`, `rollback`, `activate`, `env`, `tokens`, `token`, `members`,
 `tasks`, `stats`, `delete`, `whoami`, … Docs: [wervt.app](https://wervt.app/getting-started/quickstart).

package/dist/index.mjs

@@ -8,7 +8,7 @@ import { defineCommand, runMain } from "citty";
 import { detectPackageManager } from "nypm";
 import { x } from "tinyexec";
 import { packTar } from "modern-tar";
-//#region src/bundle.ts
+// src/bundle.ts
 /** Files under `dir`. Follows symlinks: Nitro can leave traced dependencies in
 * server/node_modules as links into the local pnpm store, which won't exist on the server. */
 async function walk(dir) {
@@ -51,8 +51,7 @@ async function createBundle(appDir) {
 		files: files.length
 	};
 }
-//#endregion
-//#region src/config.ts
+// src/config.ts
 const file = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "wervt", "config.json");
 /** Flags > WERVT_URL / WERVT_TOKEN > ~/.config/wervt/config.json. */
 async function resolveConfig(flags) {
@@ -74,8 +73,62 @@ async function saveConfig(config) {
 	await writeFile(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 384 });
 	return file;
 }
-//#endregion
-//#region src/source.ts
+// src/format.ts
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = [
+		"KB",
+		"MB",
+		"GB"
+	];
+	let value = bytes / 1024;
+	let unit = 0;
+	while (value >= 1024 && unit < units.length - 1) {
+		value /= 1024;
+		unit++;
+	}
+	return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+}
+const list = (value) => Array.isArray(value) ? value.map(String).join(", ") : "";
+const text = (value) => typeof value === "string" ? value : "";
+/** What an audit entry changed, in a few words: `env.update` → `set API_URL, TOKEN`. */
+function auditSummary(entry) {
+	const d = entry.details ?? {};
+	switch (entry.action) {
+		case "deploy":
+		case "deploy.failed": {
+			const migrations = list(d.migrations);
+			return [
+				text(d.release),
+				migrations && `migrated ${migrations}`,
+				text(d.checkError) && `checks failed: ${text(d.checkError)}`,
+				entry.action === "deploy.failed" && text(d.error).split("\n")[0]
+			].filter(Boolean).join("  ");
+		}
+		case "rollback":
+		case "activate": return `${text(d.previous) || "none"} → ${text(d.release)}`;
+		case "env.update": return [list(d.set) && `set ${list(d.set)}`, list(d.unset) && `unset ${list(d.unset)}`].filter(Boolean).join("; ");
+		case "access.update": return [
+			text(d.visibility),
+			list(d.allow) && `allow ${list(d.allow)}`,
+			list(d.add) && `add ${list(d.add)}`,
+			list(d.remove) && `remove ${list(d.remove)}`
+		].filter(Boolean).join("; ");
+		case "owners.update": return [
+			text(d.owner) && `owner ${text(d.owner)}`,
+			list(d.added) && `added ${list(d.added)}`,
+			list(d.removed) && `removed ${list(d.removed)}`
+		].filter(Boolean).join("; ");
+		case "token.create":
+		case "token.revoke": return text(d.name) || text(d.id);
+		case "client.create":
+		case "client.link":
+		case "client.delete": return text(d.name) || text(d.clientId);
+		case "app.delete": return `database ${text(d.database)}`;
+		default: return entry.account ?? "";
+	}
+}
+// src/source.ts
 async function git(dir, ...args) {
 	try {
 		const result = await x("git", args, {
@@ -120,8 +173,7 @@ async function deploySource(dir) {
 		actor: await git(dir, "config", "user.name")
 	};
 }
-//#endregion
-//#region src/index.ts
+// src/index.ts
 const interactive = process.stdout.isTTY === true && !process.env.CI;
 function progress() {
 	if (interactive) return p.spinner();
@@ -294,6 +346,10 @@ const deploy = defineCommand({
 					process.exitCode = 1;
 					continue;
 				}
+				if (event.step === "quota-warning") {
+					p.log.warn(event.message);
+					continue;
+				}
 				if (event.step === "storage-failed") {
 					p.log.warn(`Storage isn't set up: ${event.message}. The app runs; files won't work yet.`);
 					continue;
@@ -333,6 +389,7 @@ const rollback = defineCommand({
 		console.log(`${args.app} is now on release ${result.release}`);
 	}
 });
+const firstLine = (text) => text.split("\n")[0];
 const releases = defineCommand({
 	meta: {
 		name: "releases",
@@ -349,16 +406,75 @@ const releases = defineCommand({
 	async run({ args }) {
 		const info = await (await api(`/v1/apps/${args.app}`, args)).json();
 		const history = new Map(info.history?.map((entry) => [entry.release, entry]));
-		for (const release of [...info.releases].reverse()) {
-			const { source, deployedBy } = history.get(release) ?? {};
+		const failed = new Map(info.failedDeploys?.map((entry) => [entry.release, entry]));
+		const ids = [...info.releases, ...failed.keys()].sort((a, b) => b.localeCompare(a));
+		for (const release of ids) {
+			const failure = failed.get(release);
+			const kept = history.get(release);
+			const source = failure?.source ?? kept?.source;
+			const commit = source?.commit ? `${source.commit.slice(0, 7)}${source.dirty ? "+" : ""}` : void 0;
+			const applied = kept?.migrations?.applied.length;
 			const details = [
-				source?.commit ? `${source.commit.slice(0, 7)}${source.dirty ? "+" : ""}` : void 0,
+				commit,
 				source?.branch,
-				source?.actor ?? deployedBy,
+				source?.actor ?? failure?.actor ?? kept?.deployedBy,
+				kept?.size && formatBytes(kept.size.bundle),
+				applied && `${applied} migration${applied === 1 ? "" : "s"}`,
 				source?.message && styleText("dim", source.message)
 			].filter(Boolean);
-			const active = release === info.release ? styleText("green", " (active)") : "";
-			console.log(`${release}${active}${details.length ? `  ${details.join("  ")}` : ""}`);
+			const status = release === info.release ? styleText("green", " (active)") : failure ? styleText("red", " (failed)") : kept?.bootError ? styleText("red", " (didn't start)") : "";
+			const checks = kept?.checkError ? styleText("yellow", " (checks failed)") : "";
+			console.log(`${release}${status}${checks}${details.length ? `  ${details.join("  ")}` : ""}`);
+			const error = failure?.error ?? kept?.bootError ?? kept?.checkError;
+			if (error) console.log(styleText("dim", `  ${firstLine(error)}`));
+		}
+	}
+});
+const audit = defineCommand({
+	meta: {
+		name: "audit",
+		description: "Show who deployed, rolled back, deleted or changed access, env and tokens"
+	},
+	args: {
+		app: {
+			type: "positional",
+			required: false,
+			description: "App name (default: all you see)"
+		},
+		action: {
+			type: "string",
+			description: "Only these actions, comma-separated; deploy* for all deploys"
+		},
+		limit: {
+			type: "string",
+			default: "50",
+			description: "Newest entries to show (max 1000)"
+		},
+		json: {
+			type: "boolean",
+			description: "One JSON object per line"
+		},
+		...connection
+	},
+	async run({ args }) {
+		const params = new URLSearchParams({ limit: args.limit });
+		if (args.action) params.set("action", args.action);
+		const entries = await (await api(`${args.app ? `/v1/apps/${args.app}/audit` : "/v1/audit"}?${params.toString()}`, args)).json();
+		if (!entries.length && !args.json) return console.error("No audit entries.");
+		for (const entry of entries.reverse()) {
+			if (args.json) {
+				console.log(JSON.stringify(entry));
+				continue;
+			}
+			const time = new Date(entry.at).toISOString().slice(0, 16).replace("T", " ");
+			const color = entry.action === "deploy.failed" ? "red" : "cyan";
+			console.log([
+				styleText("dim", time),
+				styleText(color, entry.action.padEnd(15)),
+				(entry.app ?? "-").padEnd(16),
+				entry.actor,
+				styleText("dim", auditSummary(entry))
+			].join(" "));
 		}
 	}
 });
@@ -441,6 +557,10 @@ const access = defineCommand({
 			type: "boolean",
 			description: "Make the app private, and let people with access invite others in the app"
 		},
+		"invite-by": {
+			type: "string",
+			description: "Who may invite on an invite-only app: anyone (with access, the default) or owners (owner, members and admins)"
+		},
 		add: {
 			type: "string",
 			description: "Allow emails or *@domain (comma separated)"
@@ -456,6 +576,7 @@ const access = defineCommand({
 		if (args.public) change.visibility = "public";
 		if (args.private) change.visibility = "private";
 		if (args.invite) change.visibility = "invite";
+		if (args["invite-by"]) change.inviteBy = args["invite-by"];
 		if (args.add) change.add = toList(args.add);
 		if (args.remove) change.remove = toList(args.remove);
 		const result = await (Object.keys(change).length ? await api(`/v1/apps/${args.app}/access`, args, {
@@ -468,6 +589,7 @@ const access = defineCommand({
 		if (result.visibility === "public") return;
 		console.log(result.allow.length ? `allowed: ${result.allow.join(", ")}` : "allowed: admins only");
 		if (result.visibility === "invite") {
+			console.log(result.inviteBy === "owners" ? "who invites: the owner, members and admins" : "who invites: everyone with access");
 			const invited = result.invited ?? [];
 			console.log(invited.length ? "invited:" : "invited: nobody yet");
 			for (const invite of invited) console.log(`  ${invite.email} (by ${invite.by}, ${invite.at.slice(0, 10)})`);
@@ -542,7 +664,7 @@ const env = defineCommand({
 			return [pair.slice(0, i), pair.slice(i + 1)];
 		}));
 		const unset = toList(args.unset);
-		const { keys } = await (Object.keys(set).length || unset.length ? await api(`/v1/apps/${args.app}/env`, args, {
+		const { keys, warnings = [] } = await (Object.keys(set).length || unset.length ? await api(`/v1/apps/${args.app}/env`, args, {
 			method: "PATCH",
 			headers: { "content-type": "application/json" },
 			body: JSON.stringify({
@@ -551,13 +673,38 @@ const env = defineCommand({
 			})
 		}) : await api(`/v1/apps/${args.app}/env`, args)).json();
 		console.log(keys.length ? keys.join("\n") : "No variables set.");
+		for (const warning of warnings) console.error(styleText("yellow", `Warning: ${warning}`));
 		if (Object.keys(set).length || unset.length) console.log("Applies from the next request.");
 	}
 });
+const SIZE_FLAGS = [
+	"database",
+	"storage",
+	"releases"
+];
+/** Bytes as people read them: `1.5 GB`, `200 MB`; `no limit` for null. */
+function size(bytes) {
+	if (bytes === null || bytes === void 0) return "no limit";
+	const units = [
+		"B",
+		"KB",
+		"MB",
+		"GB",
+		"TB"
+	];
+	let value = bytes;
+	let unit = 0;
+	while (value >= 1024 && unit < units.length - 1) {
+		value /= 1024;
+		unit++;
+	}
+	return `${Number(value.toFixed(value < 10 && unit ? 1 : 0))} ${units[unit]}`;
+}
+const describeLimits = (limits) => `${limits.apps ?? "no limit"} apps, database ${size(limits.database)} and files ${size(limits.storage)} per app, releases ${size(limits.releases)}`;
 const accounts = defineCommand({
 	meta: {
 		name: "accounts",
-		description: "Admins: list accounts and their app limits, or set one"
+		description: "Admins: list accounts and their limits, or change them"
 	},
 	args: {
 		email: {
@@ -569,21 +716,35 @@ const accounts = defineCommand({
 			type: "string",
 			description: "Apps the account may own: a number, \"none\" for no limit, \"default\""
 		},
+		database: {
+			type: "string",
+			description: "Database size per app, e.g. 2GB; past it deploys are refused. \"none\", \"default\""
+		},
+		storage: {
+			type: "string",
+			description: "Files per app (bucket quota), e.g. 10GB. \"none\", \"default\""
+		},
+		releases: {
+			type: "string",
+			description: "Space all releases of their apps may take, e.g. 2GB. \"none\", \"default\""
+		},
 		...connection
 	},
 	async run({ args }) {
 		if (args.email) {
-			if (!args.apps) throw new Error("Pass --apps <n|none|default> to change the limit");
-			const apps = args.apps === "none" ? null : args.apps === "default" ? "default" : Number(args.apps);
+			const change = {};
+			if (args.apps) change.apps = args.apps === "none" ? null : args.apps === "default" ? "default" : Number(args.apps);
+			for (const flag of SIZE_FLAGS) if (args[flag]) change[flag] = args[flag] === "none" ? null : args[flag];
+			if (!Object.keys(change).length) throw new Error("Pass --apps, --database, --storage or --releases (a value, none or default)");
 			const result = await (await api(`/v1/accounts/${encodeURIComponent(args.email)}`, args, {
 				method: "PATCH",
 				headers: { "content-type": "application/json" },
-				body: JSON.stringify({ apps })
+				body: JSON.stringify(change)
 			})).json();
-			return console.log(`${result.email}: ${result.limits.apps ?? "no limit"} apps`);
+			return console.log(`${result.email}: ${describeLimits(result.limits)}`);
 		}
 		const result = await (await api("/v1/accounts", args)).json();
-		console.log(`default: ${result.defaults.apps ?? "no limit"} apps per account`);
+		console.log(`default: ${describeLimits(result.defaults)}`);
 		for (const account of result.accounts) {
 			const list = account.apps.length ? `  ${account.apps.join(", ")}` : "";
 			if (account.admin) {
@@ -593,6 +754,7 @@ const accounts = defineCommand({
 			const limit = account.limits.apps ?? "no limit";
 			const own = "apps" in account.custom ? "" : " (default)";
 			console.log(`${account.email}  ${account.apps.length}/${limit}${own}${list}`);
+			if (SIZE_FLAGS.some((flag) => flag in account.custom)) console.log(styleText("dim", `  database ${size(account.limits.database)}, files ${size(account.limits.storage)} per app, releases ${size(account.limits.releases)}`));
 		}
 	}
 });
@@ -642,6 +804,236 @@ const tokens = defineCommand({
 		}
 	}
 });
+const appArg = {
+	type: "positional",
+	required: true,
+	description: "App name"
+};
+const clients = defineCommand({
+	meta: {
+		name: "clients",
+		description: "Manage the OAuth clients of an app's native apps (sign-in with wervt)"
+	},
+	subCommands: {
+		list: defineCommand({
+			meta: {
+				name: "list",
+				description: "List the app's native app clients"
+			},
+			args: {
+				app: appArg,
+				...connection
+			},
+			async run({ args }) {
+				const list = await (await api(`/v1/apps/${args.app}/clients`, args)).json();
+				if (!list.length) return console.log(`No native app clients for ${args.app}.`);
+				for (const client of list) {
+					const used = client.lastUsedAt ? `used ${client.lastUsedAt.slice(0, 10)}` : "never used";
+					console.log(`${client.clientId}  ${client.name}  created ${client.createdAt.slice(0, 10)}  ${used}`);
+					for (const uri of client.redirectUris) console.log(styleText("dim", `  ${uri}`));
+				}
+			}
+		}),
+		create: defineCommand({
+			meta: {
+				name: "create",
+				description: "Register a native app for sign-in, e.g. --redirect dev.example.app:/auth"
+			},
+			args: {
+				app: appArg,
+				name: {
+					type: "string",
+					required: true,
+					description: "Shown on the consent page"
+				},
+				redirect: {
+					type: "string",
+					required: true,
+					description: "Redirect URI; comma-separated for several"
+				},
+				...connection
+			},
+			async run({ args }) {
+				const client = await (await api(`/v1/apps/${args.app}/clients`, args, {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify({
+						name: args.name,
+						redirectUris: toList(args.redirect)
+					})
+				})).json();
+				console.error(`Client "${client.name}" for ${args.app}:`);
+				console.log(client.clientId);
+				console.error(styleText("dim", "A public client (PKCE, no secret): put the id in the app config."));
+			}
+		}),
+		delete: defineCommand({
+			meta: {
+				name: "delete",
+				description: "Delete a client; everyone signed in through it is signed out"
+			},
+			args: {
+				app: appArg,
+				clientId: {
+					type: "positional",
+					required: true,
+					description: "Client id"
+				},
+				yes: {
+					type: "boolean",
+					description: "Skip the confirmation"
+				},
+				...connection
+			},
+			async run({ args }) {
+				if (!args.yes) {
+					const ok = await p.confirm({
+						message: `Delete ${args.clientId}? Every install signed in through it is signed out.`,
+						initialValue: false
+					});
+					if (p.isCancel(ok) || !ok) return p.cancel("Cancelled");
+				}
+				await api(`/v1/apps/${args.app}/clients/${args.clientId}`, args, { method: "DELETE" });
+				console.log(`Deleted ${args.clientId}`);
+			}
+		}),
+		link: defineCommand({
+			meta: {
+				name: "link",
+				description: "Admins: assign a client that registered itself to the app"
+			},
+			args: {
+				app: appArg,
+				clientId: {
+					type: "positional",
+					required: true,
+					description: "Client id"
+				},
+				...connection
+			},
+			async run({ args }) {
+				await api(`/v1/apps/${args.app}/clients/${args.clientId}/link`, args, { method: "POST" });
+				console.log(`${args.clientId} belongs to ${args.app} now`);
+			}
+		})
+	}
+});
+const token = defineCommand({
+	meta: {
+		name: "token",
+		description: "Mint a short-lived access token for your account on an app, to test a private app (curl, Playwright)"
+	},
+	args: {
+		app: {
+			type: "positional",
+			required: true,
+			description: "App name"
+		},
+		ttl: {
+			type: "string",
+			default: "15m",
+			description: "Lifetime, 1m to 1h (default: 15m)"
+		},
+		cookie: {
+			type: "boolean",
+			default: false,
+			description: "Print a cookie for Playwright's context.addCookies() instead of the token"
+		},
+		json: {
+			type: "boolean",
+			default: false,
+			description: "Print token, cookie and expiry as JSON"
+		},
+		...connection
+	},
+	async run({ args }) {
+		const minted = await (await api(`/v1/apps/${args.app}/agent-tokens`, args, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ ttl: args.ttl })
+		})).json();
+		if (args.json) return console.log(JSON.stringify(minted, null, 2));
+		console.log(args.cookie ? JSON.stringify(minted.cookie) : minted.token);
+		console.error(styleText("dim", `${minted.app} as ${minted.user} until ${minted.expiresAt} (token ${minted.id}). ` + (args.cookie ? `Playwright: await context.addCookies([cookie]), then open ${minted.url}` : `curl -H "Authorization: Bearer $TOKEN" ${minted.url}/api/…`)));
+	}
+});
+function printIdentity(status) {
+	if (!status.configured) console.log("Workload identity is not configured on this server.");
+	console.log(status.enabled ? `${status.app} has a workload identity (since ${status.enabledAt?.slice(0, 10)}, by ${status.enabledBy})` : `${status.app} has no workload identity`);
+	console.log(`issuer:    ${status.issuer}`);
+	console.log(`subject:   ${status.subject ?? "(the app has no owner yet)"}`);
+	console.log(`audiences: ${status.audiences.join(", ")}`);
+}
+const identityApp = (enabled) => defineCommand({
+	meta: {
+		name: enabled === void 0 ? "status" : enabled ? "enable" : "disable",
+		description: enabled === void 0 ? "Show an app's workload identity and the values a provider rule needs" : enabled ? "Owners: let the app get identity tokens, for provider rules that trust it" : "Owners: stop signing identity tokens for the app"
+	},
+	args: {
+		app: {
+			type: "positional",
+			required: true,
+			description: "App name"
+		},
+		...connection
+	},
+	async run({ args }) {
+		printIdentity(await (enabled === void 0 ? await api(`/v1/apps/${args.app}/identity`, args) : await api(`/v1/apps/${args.app}/identity`, args, {
+			method: "PATCH",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ enabled })
+		})).json());
+	}
+});
+const identity = defineCommand({
+	meta: {
+		name: "identity",
+		description: "Workload identity: apps authenticate to AI providers without API keys"
+	},
+	subCommands: {
+		status: identityApp(),
+		enable: identityApp(true),
+		disable: identityApp(false),
+		jwks: defineCommand({
+			meta: {
+				name: "jwks",
+				description: "Print the issuer's public keys, for providers that can't fetch them"
+			},
+			args: connection,
+			async run({ args }) {
+				const res = await api("/.well-known/jwks.json", args);
+				console.log(JSON.stringify(await res.json(), null, 2));
+			}
+		}),
+		keygen: defineCommand({
+			meta: {
+				name: "keygen",
+				description: "Print a new private signing key for WERVT_IDENTITY_KEY (runs locally)"
+			},
+			args: { kid: {
+				type: "string",
+				description: "Key id (default: wervt-<date>)"
+			} },
+			async run({ args }) {
+				const pair = await crypto.subtle.generateKey({
+					name: "ECDSA",
+					namedCurve: "P-256"
+				}, true, ["sign", "verify"]);
+				const { kty, crv, x, y, d } = await crypto.subtle.exportKey("jwk", pair.privateKey);
+				const kid = args.kid ?? `wervt-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`;
+				console.log(JSON.stringify({
+					kty,
+					crv,
+					x,
+					y,
+					d,
+					kid
+				}));
+				console.error(styleText("dim", "Private: set it as WERVT_IDENTITY_KEY on control only, never in an app or a repo."));
+			}
+		})
+	}
+});
 const tasks = defineCommand({
 	meta: {
 		name: "tasks",
@@ -722,7 +1114,7 @@ const remove = defineCommand({
 		const dropDb = Boolean(args["drop-database"]);
 		if (!args.yes) {
 			const ok = await p.confirm({
-				message: `Delete ${args.app}${dropDb ? " and ALL its data" : " (database is kept)"}?`,
+				message: `Delete ${args.app}${dropDb ? " and ALL its data" : " (data is kept, the name stays yours)"}?`,
 				initialValue: false
 			});
 			if (p.isCancel(ok) || !ok) return p.cancel("Cancelled");
@@ -1030,6 +1422,7 @@ runMain(defineCommand({
 		deploy,
 		apps,
 		releases,
+		audit,
 		logs,
 		activate,
 		rollback,
@@ -1039,6 +1432,9 @@ runMain(defineCommand({
 		accounts,
 		env,
 		tokens,
+		token,
+		clients,
+		identity,
 		tasks,
 		stats,
 		delete: remove,
@@ -1047,5 +1443,4 @@ runMain(defineCommand({
 		skill
 	}
 }));
-//#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wervt/cli",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Deploy and manage apps on wervt.",
   "keywords": [
     "agents",
@@ -30,8 +30,8 @@
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "citty": "^0.2.2",
-    "modern-tar": "^0.8.5",
-    "nypm": "^0.6.10",
+    "modern-tar": "^0.8.6",
+    "nypm": "^0.6.12",
     "tinyexec": "^1.3.1"
   },
   "scripts": {

package/skill/SKILL.md

@@ -66,19 +66,37 @@ pnpm exec wervt deploy                            # build, upload, migrate, acti
 pnpm exec wervt access <name> --public            # new apps are private (owner, members, admins)
 pnpm exec wervt access <name> --add a@x.com,*@company.com   # or let specific people in
 pnpm exec wervt access <name> --invite            # private, and people with access invite others (useWervtAccess)
+pnpm exec wervt access <name> --invite-by owners  # only owner, members and admins may invite
 pnpm exec wervt members <name> --add a@x.com      # who may deploy and manage it (the first deploy owns it)
-pnpm exec wervt env <name> --set KEY=value        # server env vars, applied from the next request
+pnpm exec wervt env <name> --set NUXT_API_KEY=…   # runtimeConfig.apiKey, applied from the next request
 ```
 
 - Ask before making an app public if it shows personal or private data. "Ship it" alone doesn't
   decide that. Private, with the user's email allowed, is the safe default.
+- App configuration and secrets go through Nuxt's `runtimeConfig`, never `process.env` in app
+  code: declare the key with a default in `nuxt.config.ts` (`runtimeConfig: { apiKey: '' }`), read
+  it with `useRuntimeConfig()` and set it as `NUXT_` + the key in SCREAMING_SNAKE_CASE
+  (`apiKey` → `NUXT_API_KEY`, `public.mapStyle` → `NUXT_PUBLIC_MAP_STYLE`). Keys missing from
+  `runtimeConfig` are ignored.
 - Secrets for `wervt env` (API keys) come from the user. Ask them to run the command themselves
-  (`! pnpm exec wervt env <name> --set API_KEY=…`) instead of pasting the value to you.
+  (`! pnpm exec wervt env <name> --set NUXT_API_KEY=…`) instead of pasting the value to you.
 - `wervt deploy` requests `/` once the release started and fails (exit 1, with the first logged
   error) on a 5xx. Add the pages you changed: `--check /,/todos,/api/todos`. The checks are
   anonymous, so pages behind a sign-in only show they don't crash without a user.
 - Then open the URL `wervt deploy` printed and check
   `pnpm exec wervt logs <name> 'level:error' --since 15m`. Fix and redeploy until both are clean.
+- Check what's behind the login yourself, don't ask the user to. `wervt token` mints a token for
+  your CLI account on this app (15 minutes, `--ttl 1h` at most), and the app sees that account:
+
+  ```bash
+  TOKEN=$(pnpm exec wervt token <name>)
+  curl -sH "Authorization: Bearer $TOKEN" <url>/api/…            # protected API routes
+  pnpm exec wervt token <name> --cookie > /tmp/wervt-cookie.json  # for a headless browser
+  ```
+
+  In Playwright, `await context.addCookies([JSON.parse(cookieJson)])`, then open the URL to check
+  pages, icons and uploads. Works for owners, members and admins signed in with `wervt login`
+  (not with a deploy or read token). Never paste the token into files or commits.
 
 ## 5. Deploy on push (when the user wants a repository)
 
@@ -101,7 +119,8 @@ release lists the commit.
 
 ```bash
 pnpm exec wervt apps                           # every app, active release, URL
-pnpm exec wervt releases <name>                # newest first, with commit and author
+pnpm exec wervt releases <name>                # newest first, with commit, author, failed deploys
+pnpm exec wervt audit <name>                   # who deployed, rolled back, changed env or access
 pnpm exec wervt logs <name> 'status:>=500' --since 1d --json
 pnpm exec wervt tasks <name>                   # tasks, schedules, next runs
 pnpm exec wervt tasks <name> --run <task>      # run one now