@wervt/cli 0.2.0 → 0.2.2

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
-import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { styleText } from "node:util";
 import * as p from "@clack/prompts";
@@ -7,7 +8,6 @@ import { defineCommand, runMain } from "citty";
 import { detectPackageManager } from "nypm";
 import { x } from "tinyexec";
 import { packTar } from "modern-tar";
-import { homedir } from "node:os";
 //#region 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. */
@@ -71,6 +71,52 @@ async function saveConfig(config) {
 	return file;
 }
 //#endregion
+//#region src/source.ts
+async function git(dir, ...args) {
+	try {
+		const result = await x("git", args, {
+			nodeOptions: { cwd: dir },
+			throwOnError: false
+		});
+		return result.exitCode === 0 ? result.stdout.trim() || void 0 : void 0;
+	} catch {
+		return;
+	}
+}
+/** `git@github.com:owner/repo.git` and `https://…/repo.git` as `https://github.com/owner/repo`. */
+function webUrl(remote) {
+	if (!remote) return void 0;
+	const ssh = remote.match(/^(?:ssh:\/\/)?git@([^:/]+)[:/](.+?)(?:\.git)?$/);
+	if (ssh) return `https://${ssh[1]}/${ssh[2]}`;
+	const https = remote.match(/^https:\/\/(?:[^@/]+@)?(.+?)(?:\.git)?$/);
+	return https ? `https://${https[1]}` : void 0;
+}
+async function deploySource(dir) {
+	const env = process.env;
+	const message = await git(dir, "log", "-1", "--format=%s");
+	if (env.GITHUB_ACTIONS === "true") {
+		const repo = `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}`;
+		return {
+			commit: env.GITHUB_SHA,
+			branch: env.GITHUB_HEAD_REF || env.GITHUB_REF_NAME,
+			message,
+			repo,
+			actor: env.GITHUB_ACTOR,
+			run: `${repo}/actions/runs/${env.GITHUB_RUN_ID}`
+		};
+	}
+	const status = await git(dir, "status", "--porcelain", "--", ".");
+	const commit = await git(dir, "rev-parse", "HEAD");
+	return {
+		commit,
+		branch: await git(dir, "branch", "--show-current"),
+		message,
+		dirty: commit ? Boolean(status) : void 0,
+		repo: webUrl(await git(dir, "remote", "get-url", "origin")),
+		actor: await git(dir, "config", "user.name")
+	};
+}
+//#endregion
 //#region src/index.ts
 const connection = {
 	url: {
@@ -79,7 +125,7 @@ const connection = {
 	},
 	token: {
 		type: "string",
-		description: "Deploy or read token (or WERVT_TOKEN)"
+		description: "Admin, read or deploy token (or WERVT_TOKEN)"
 	}
 };
 async function api(path, flags, init = {}) {
@@ -158,9 +204,13 @@ const deploy = defineCommand({
 		const bundle = await createBundle(dir);
 		spinner.stop(`Packed ${bundle.files} files (${(bundle.data.byteLength / 1024).toFixed(0)} kB)`);
 		spinner.start("Uploading");
+		const source = await deploySource(dir);
 		const res = await api(`/v1/apps/${name}/deploys`, args, {
 			method: "POST",
-			headers: { "content-type": "application/gzip" },
+			headers: {
+				"content-type": "application/gzip",
+				"x-wervt-source": encodeURIComponent(JSON.stringify(source))
+			},
 			body: new Uint8Array(bundle.data)
 		});
 		const labels = {
@@ -184,6 +234,7 @@ const deploy = defineCommand({
 				if (event.done) {
 					spinner.stop(`Release ${event.release}`);
 					p.outro(`Deployed → ${event.url}`);
+					if (process.env.GITHUB_OUTPUT) await appendFile(process.env.GITHUB_OUTPUT, `url=${event.url}\nrelease=${event.release}\n`);
 					return;
 				}
 				spinner.message(labels[event.step] ?? event.step);
@@ -236,7 +287,18 @@ const releases = defineCommand({
 	},
 	async run({ args }) {
 		const info = await (await api(`/v1/apps/${args.app}`, args)).json();
-		for (const release of [...info.releases].reverse()) console.log(`${release}${release === info.release ? "  (active)" : ""}`);
+		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 details = [
+				source?.commit ? `${source.commit.slice(0, 7)}${source.dirty ? "+" : ""}` : void 0,
+				source?.branch,
+				source?.actor ?? deployedBy,
+				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 activate = defineCommand({
@@ -378,7 +440,53 @@ const env = defineCommand({
 			})
 		}) : await api(`/v1/apps/${args.app}/env`, args)).json();
 		console.log(keys.length ? keys.join("\n") : "No variables set.");
-		if (Object.keys(set).length || unset.length) console.log("Applies to newly started isolates (next deploy or after idle timeout).");
+		if (Object.keys(set).length || unset.length) console.log("Applies from the next request.");
+	}
+});
+const tokens = defineCommand({
+	meta: {
+		name: "tokens",
+		description: "List, create or revoke an app's deploy tokens (for CI)"
+	},
+	args: {
+		app: {
+			type: "positional",
+			required: true,
+			description: "App name"
+		},
+		create: {
+			type: "string",
+			description: "Create a token with this name, e.g. github"
+		},
+		revoke: {
+			type: "string",
+			description: "Revoke the token with this id"
+		},
+		...connection
+	},
+	async run({ args }) {
+		const path = `/v1/apps/${args.app}/tokens`;
+		if (args.create) {
+			const token = await (await api(path, args, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ name: args.create })
+			})).json();
+			console.error(`Deploy token "${token.name}" for ${args.app} (shown once):`);
+			console.log(token.token);
+			console.error(styleText("dim", "It can deploy this app and nothing else. Store it as the WERVT_TOKEN secret."));
+			return;
+		}
+		if (args.revoke) {
+			await api(`${path}/${args.revoke}`, args, { method: "DELETE" });
+			return console.log(`Revoked ${args.revoke}`);
+		}
+		const list = await (await api(path, args)).json();
+		if (!list.length) return console.log(`No deploy tokens for ${args.app}.`);
+		for (const token of list) {
+			const used = token.lastUsedAt ? `used ${token.lastUsedAt.slice(0, 10)}` : "never used";
+			console.log(`${token.id}  ${token.name.padEnd(20)} created ${token.createdAt.slice(0, 10)}  ${used}`);
+		}
 	}
 });
 const remove = defineCommand({
@@ -492,6 +600,55 @@ const logs = defineCommand({
 		for (const entry of entries.reverse()) printLog(entry, Boolean(args.json));
 	}
 });
+const whoami = defineCommand({
+	meta: {
+		name: "whoami",
+		description: "Show the control plane and what the token can do"
+	},
+	args: connection,
+	async run({ args }) {
+		const { url, token } = await resolveConfig(args);
+		const deployApp = token.match(/^wervtd_([a-z0-9-]+)_/)?.[1];
+		let role = deployApp ? `deploy token for ${deployApp}` : "unknown";
+		if (!deployApp) {
+			const res = await fetch(`${url}/v1/databases`, { headers: { authorization: `Bearer ${token}` } });
+			if (res.status === 401) throw new Error(`The token is not valid for ${url}`);
+			role = res.ok ? "admin" : res.status === 403 ? "read" : `unknown (${res.status})`;
+		}
+		console.log(`${url}\n${role}`);
+	}
+});
+const skill = defineCommand({
+	meta: {
+		name: "skill",
+		description: "Install the wervt agent skill"
+	},
+	subCommands: { install: defineCommand({
+		meta: {
+			name: "install",
+			description: "Write the wervt skill to ~/.claude/skills/wervt, so agents can build and ship apps"
+		},
+		args: {
+			dir: {
+				type: "string",
+				description: "Skills directory (default: ~/.claude/skills; .claude/skills for --project)"
+			},
+			project: {
+				type: "boolean",
+				description: "Install into this project instead"
+			}
+		},
+		async run({ args }) {
+			const base = args.dir ?? (args.project ? ".claude/skills" : join(homedir(), ".claude", "skills"));
+			const target = resolve(base, "wervt", "SKILL.md");
+			const content = await readFile(new URL("../skill/SKILL.md", import.meta.url), "utf8");
+			const previous = await readFile(target, "utf8").catch(() => void 0);
+			await mkdir(join(target, ".."), { recursive: true });
+			await writeFile(target, content);
+			console.log(`${previous === void 0 ? "Installed" : previous === content ? "Up to date" : "Updated"}: ${target}`);
+		}
+	}) }
+});
 const login = defineCommand({
 	meta: {
 		name: "login",
@@ -506,12 +663,12 @@ const login = defineCommand({
 		token: {
 			type: "string",
 			required: true,
-			description: "Deploy token, or the read token"
+			description: "Admin, read or deploy token"
 		}
 	},
 	async run({ args }) {
 		const res = await fetch(`${args.url.replace(/\/$/, "")}/v1/apps`, { headers: { authorization: `Bearer ${args.token}` } });
-		if (!res.ok) throw new Error(`Login failed: ${res.status} ${res.statusText}`);
+		if (!res.ok && res.status !== 403) throw new Error(`Login failed: ${res.status} ${res.statusText}`);
 		const file = await saveConfig({
 			url: args.url,
 			token: args.token
@@ -534,8 +691,11 @@ runMain(defineCommand({
 		reprovision,
 		access,
 		env,
+		tokens,
 		delete: remove,
-		login
+		login,
+		whoami,
+		skill
 	}
 }));
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wervt/cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Deploy and manage apps on wervt.",
   "keywords": [
     "agents",
@@ -23,6 +23,7 @@
   "files": [
     "bin",
     "dist",
+    "skill",
     "README.md"
   ],
   "type": "module",

package/skill/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: wervt
+description: Build a small web app and ship it on the user's wervt server, or deploy, configure and debug an existing wervt app. Use when the user says "build X and ship it", "put it on wervt", "deploy this to wervt", "make it public", "set an env var", or asks why a wervt app fails. Covers scaffolding with create-wervt, deploying with the wervt CLI, access, env vars, GitHub Actions deploys, releases and logs.
+---
+
+# wervt
+
+wervt hosts small Nuxt apps on the user's own server: every app gets `https://<app>.<domain>`,
+its own Postgres schema, live data (Electric), sign-in through wervt, and logs. You build the app
+and ship it with the `wervt` CLI. One request ("build a habit tracker and ship it") should end with
+a working URL.
+
+## 1. Check the connection
+
+```bash
+npx -y @wervt/cli whoami
+```
+
+It prints the control plane URL and what the saved token can do (`admin`, `read`, or a deploy
+token for one app). Shipping new apps needs `admin`. If it says "Not logged in", ask the user to
+run `wervt login --url <control plane URL> --token <admin token>` themselves (for example with
+`! npx -y @wervt/cli login --url … --token …`). Never look for tokens in files, env or
+keychains, and never print or ask to paste one into the chat.
+
+## 2. Scaffold
+
+```bash
+pnpm create wervt <name>     # a-z, 0-9 and dashes; becomes the subdomain
+cd <name>
+```
+
+The app comes with `AGENTS.md`, skills in `.claude/skills/` and a deploy workflow. **Read
+`AGENTS.md` before writing code** and follow it: server routes, valibot validation, Drizzle schema
+and migrations, live data with shapes, users, logging, and what the isolate runtime can't do
+(no filesystem, no child processes, no long-running work, no WebSockets, no cron).
+
+Before picking a name, run `wervt apps` so you don't overwrite an existing app. If the user named an
+existing app, work in its repository instead.
+
+## 3. Build
+
+- Keep the app small and complete: data in Postgres through `useDb()`, writes through API routes,
+  lists through `useShape` so every open tab stays live. Ask only when the request is genuinely
+  ambiguous; otherwise choose sensible defaults and say what you chose.
+- Users: wervt signs people in. Use `useWervtUser()`; never build login, passwords or OAuth.
+- After changing `server/db/schema.ts`: `pnpm db:generate`, and commit the migration.
+- `pnpm dev` runs against a local wervt stack, which the user may not have. When it isn't running,
+  don't set one up: `pnpm build` plus `pnpm exec vp check --fix` are the checks, and the
+  deployed app is the test.
+- Finish with `pnpm exec vp check --fix` passing.
+
+## 4. Ship
+
+```bash
+pnpm exec wervt deploy                            # build, upload, migrate, activate
+pnpm exec wervt access <name> --public            # new apps are private (signed-in admins only)
+pnpm exec wervt access <name> --add a@x.com,*@company.com   # or let specific people in
+pnpm exec wervt env <name> --set KEY=value        # server env vars, 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.
+- 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.
+- Then open the URL `wervt deploy` printed (curl it: expect 200, or a redirect to sign-in for
+  private apps) and check `pnpm exec wervt logs <name> 'level:error' --since 15m`. Fix and
+  redeploy until both are clean.
+
+## 5. Deploy on push (when the user wants a repository)
+
+Only when asked, or when the user wants a GitHub repo for the app:
+
+```bash
+git init -b main && git add -A && git commit -m "Initial app"
+gh repo create <name> --private --source . --remote origin
+pnpm exec wervt tokens <name> --create github | gh secret set WERVT_TOKEN -R <owner>/<name>
+gh variable set WERVT_URL -R <owner>/<name> --body <control plane URL from whoami>
+git push -u origin main
+```
+
+The pipe hands the deploy token straight to GitHub; it never appears in the output. A deploy token
+can only deploy that one app. Set the secret and variable **before** the first push, or the first
+workflow run fails. Then `gh run watch` and check `pnpm exec wervt releases <name>`: the new
+release lists the commit.
+
+## Existing apps
+
+```bash
+pnpm exec wervt apps                           # every app, active release, URL
+pnpm exec wervt releases <name>                # newest first, with commit and author
+pnpm exec wervt logs <name> 'status:>=500' --since 1d --json
+pnpm exec wervt rollback <name>                # the previous release (migrations stay)
+```
+
+For debugging, use the app's `wervt-logs` skill (logs live 14 days; queries are LogsQL).
+
+## Never without asking
+
+`wervt delete` (never with `--drop-database` unless the user says so explicitly), `rollback`,
+`activate`, revoking tokens, making a private app public, or deploying over an app you didn't
+create in this conversation. Outside an app directory, `pnpm exec wervt` isn't installed: use
+`npx -y @wervt/cli <command>`.