@wervt/cli 0.2.1 → 0.2.3

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
 import { appendFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { homedir, hostname } 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. */
@@ -59,12 +59,16 @@ async function resolveConfig(flags) {
 	const saved = JSON.parse(await readFile(file, "utf8").catch(() => "{}"));
 	const url = flags.url ?? process.env.WERVT_URL ?? saved.url;
 	const token = flags.token ?? process.env.WERVT_TOKEN ?? saved.token;
-	if (!url || !token) throw new Error("Not logged in. Run `wervt login --url <control url> --token <token>`.");
+	if (!url || !token) throw new Error("Not logged in. Run `wervt login --url <control url>`.");
 	return {
 		url: url.replace(/\/$/, ""),
 		token
 	};
 }
+/** The saved control plane URL, if any. */
+async function savedUrl() {
+	return JSON.parse(await readFile(file, "utf8").catch(() => "{}")).url;
+}
 async function saveConfig(config) {
 	await mkdir(dirname(file), { recursive: true });
 	await writeFile(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 384 });
@@ -600,31 +604,146 @@ 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}`);
+		}
+	}) }
+});
+/** Opens a URL in the default browser; quietly does nothing where that isn't possible. */
+async function openBrowser(url) {
+	const [command, ...args] = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? [
+		"cmd",
+		"/c",
+		"start",
+		"",
+		url
+	] : ["xdg-open", url];
+	try {
+		await x(command, args, {
+			throwOnError: false,
+			nodeOptions: { stdio: "ignore" }
+		});
+	} catch {}
+}
+/** Browser login: an admin approves this machine in the dashboard, the CLI gets its own token. */
+async function browserLogin(url) {
+	const start = await fetch(`${url}/v1/login`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({ name: hostname() })
+	});
+	if (!start.ok) throw new Error(`Could not start the login: ${start.status} ${await start.text()}`);
+	const login = await start.json();
+	p.note(`${styleText("bold", login.userCode)}\n\nEnter it at ${login.verifyUrl}`, "Your one-time code");
+	const go = await p.confirm({
+		message: "Open the browser?",
+		initialValue: true
+	});
+	if (p.isCancel(go)) throw new Error("Cancelled");
+	if (go) await openBrowser(login.verifyUrl);
+	const spinner = p.spinner();
+	spinner.start("Waiting for approval in the dashboard");
+	const deadline = new Date(login.expiresAt).getTime();
+	while (Date.now() < deadline) {
+		await new Promise((done) => setTimeout(done, login.interval * 1e3));
+		const res = await fetch(`${url}/v1/login/poll`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ deviceCode: login.deviceCode })
+		}).catch(() => void 0);
+		if (!res?.ok) continue;
+		const result = await res.json();
+		if (result.status === "pending") continue;
+		if (result.status === "approved" && result.token) {
+			spinner.stop("Approved");
+			return result.token;
+		}
+		spinner.error(result.status === "denied" ? "Denied in the dashboard" : "The login expired");
+		process.exit(1);
+	}
+	spinner.error("The login expired");
+	process.exit(1);
+}
 const login = defineCommand({
 	meta: {
 		name: "login",
-		description: "Save the control plane URL and token"
+		description: "Sign in: approve this machine in the dashboard (or pass a token)"
 	},
 	args: {
 		url: {
 			type: "string",
-			required: true,
-			description: "Control plane URL"
+			description: "Control plane URL, e.g. https://api.example.com"
 		},
 		token: {
 			type: "string",
-			required: true,
-			description: "Admin, read or deploy token"
+			description: "Save this token instead (admin, read or a deploy token, e.g. for CI)"
 		}
 	},
 	async run({ args }) {
-		const res = await fetch(`${args.url.replace(/\/$/, "")}/v1/apps`, { headers: { authorization: `Bearer ${args.token}` } });
+		p.intro("wervt login");
+		let url = args.url ?? process.env.WERVT_URL ?? await savedUrl();
+		if (!url) {
+			const answer = await p.text({
+				message: "Control plane URL",
+				placeholder: "https://api.example.com",
+				validate: (value) => /^https?:\/\/\S+$/.test(value ?? "") ? void 0 : "An http(s) URL"
+			});
+			if (p.isCancel(answer)) return p.cancel("Cancelled");
+			url = answer;
+		}
+		url = url.replace(/\/$/, "");
+		const token = args.token ?? await browserLogin(url);
+		const res = await fetch(`${url}/v1/apps`, { headers: { authorization: `Bearer ${token}` } });
 		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
+			url,
+			token
 		});
-		console.log(`Saved to ${file}`);
+		p.outro(`Signed in to ${url} (saved to ${file})`);
 	}
 });
 runMain(defineCommand({
@@ -644,7 +763,9 @@ runMain(defineCommand({
 		env,
 		tokens,
 		delete: remove,
-		login
+		login,
+		whoami,
+		skill
 	}
 }));
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wervt/cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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,103 @@
+---
+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 `! npx -y @wervt/cli login --url <control plane URL>` themselves: it shows a code, they
+approve it in the dashboard (CLI page) and the machine gets its own admin session. Never run the
+login for them, 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>`.