@wervt/cli 0.2.1 → 0.2.2

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 } 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. */
@@ -600,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",
@@ -644,7 +693,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.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>`.