@upend/cli 0.1.0

package/src/commands/init.ts

@@ -0,0 +1,323 @@
+import { log } from "../lib/log";
+import { exec, execOrDie, hasCommand } from "../lib/exec";
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
+import { join, resolve } from "path";
+
+export default async function init(args: string[]) {
+  const name = args[0];
+  if (!name) {
+    log.error("usage: upend init <name>");
+    log.dim("  e.g. upend init beta → deploys to beta.upend.site");
+    process.exit(1);
+  }
+
+  const projectDir = resolve(name);
+  const domain = `${name}.upend.site`;
+
+  if (existsSync(projectDir)) {
+    log.error(`directory '${name}' already exists`);
+    process.exit(1);
+  }
+
+  log.header(`creating ${name}`);
+  log.dim(`→ ${domain}`);
+  log.blank();
+
+  mkdirSync(projectDir, { recursive: true });
+
+  // ── 1. generate JWT keys first (needed for JWKS setup) ──
+
+  log.info("generating JWT signing keys...");
+  mkdirSync(join(projectDir, ".keys"), { recursive: true });
+  const { privateKey, publicKey } = await crypto.subtle.generateKey(
+    { name: "RSASSA-PKCS1-v1_5", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" },
+    true,
+    ["sign", "verify"]
+  );
+  const privPem = await exportKeyToPem(privateKey, "PRIVATE");
+  const pubPem = await exportKeyToPem(publicKey, "PUBLIC");
+  writeFileSync(join(projectDir, ".keys/private.pem"), privPem);
+  writeFileSync(join(projectDir, ".keys/public.pem"), pubPem);
+  log.success("keys generated");
+
+  // ── 2. neon database + data API ──
+
+  let databaseUrl = "";
+  let neonDataApi = "";
+  let neonProjectId = "";
+
+  if (await hasCommand("neonctl")) {
+    // check auth
+    const { exitCode } = await exec(["neonctl", "me"], { silent: true });
+    if (exitCode !== 0) {
+      log.info("authenticating with neon...");
+      await execOrDie(["neonctl", "auth"]);
+    }
+
+    // create neon project
+    log.info("creating neon database...");
+    const { stdout: projectJson } = await execOrDie(["neonctl", "projects", "create", "--name", name, "--output", "json"]);
+    const project = JSON.parse(projectJson);
+    neonProjectId = project.project?.id || project.id;
+    log.success(`neon project: ${neonProjectId}`);
+
+    // get connection string (direct, not pooler)
+    const { stdout: connStr } = await execOrDie(["neonctl", "connection-string", "--project-id", neonProjectId]);
+    databaseUrl = connStr.trim();
+    log.success("connection string ready");
+
+    // get branch ID for data API setup
+    const { stdout: branchJson } = await execOrDie(["neonctl", "branches", "list", "--project-id", neonProjectId, "--output", "json"]);
+    const branches = JSON.parse(branchJson);
+    const branchId = branches[0]?.id || branches.branches?.[0]?.id;
+
+    if (branchId) {
+      // get neon API token from neonctl credentials
+      const neonToken = getNeonToken();
+
+      if (neonToken) {
+        // wait for endpoint to be ready, then enable Data API
+        log.info("enabling data API (waiting for endpoint)...");
+        for (let attempt = 0; attempt < 10; attempt++) {
+          const dataApiRes = await fetch(
+            `https://console.neon.tech/api/v2/projects/${neonProjectId}/branches/${branchId}/data-api/neondb`,
+            {
+              method: "POST",
+              headers: {
+                "Authorization": `Bearer ${neonToken}`,
+                "Content-Type": "application/json",
+              },
+              body: JSON.stringify({
+                auth_provider: "external",
+                jwks_url: `https://${domain}/.well-known/jwks.json`,
+                provider_name: "upend",
+                add_default_grants: true,
+                skip_auth_schema: true,
+                settings: {
+                  db_schemas: ["public"],
+                  jwt_role_claim_key: ".role",
+                },
+              }),
+            }
+          );
+
+          if (dataApiRes.ok) {
+            const dataApi = await dataApiRes.json() as any;
+            neonDataApi = dataApi.url || "";
+            log.success(`data API: ${neonDataApi}`);
+            break;
+          }
+
+          const err = await dataApiRes.text();
+          if (err.includes("initializing") && attempt < 9) {
+            await new Promise(r => setTimeout(r, 3000));
+            continue;
+          }
+          log.warn(`data API setup failed: ${err}`);
+          log.dim("you can enable it manually in the Neon console");
+          break;
+        }
+
+        // JWKS registration requires the URL to be reachable — defer to post-deploy
+        log.dim(`JWKS will be registered after deploy (${domain} must be live)`);
+        log.dim("run: upend setup:jwks  (after first deploy)");
+      } else {
+        log.warn("couldn't read neon API token — data API needs manual setup");
+      }
+    }
+  } else {
+    log.warn("neonctl not found — install with: npm i -g neonctl");
+    log.dim("then re-run: upend init " + name);
+    log.dim("or set DATABASE_URL manually in .env");
+  }
+
+  // ── 3. scaffold project files ──
+
+  log.info("scaffolding project...");
+
+  // resolve @upend/cli dependency
+  const cliPkgPath = new URL("../../package.json", import.meta.url).pathname;
+  const cliPkg = JSON.parse(readFileSync(cliPkgPath, "utf-8"));
+  const cliRoot = join(cliPkgPath, "..");
+  const cliDep = cliPkg.version === "0.1.0" ? `file:${cliRoot}` : `^${cliPkg.version}`;
+
+  writeFile(projectDir, "upend.config.ts", `import { defineConfig } from "@upend/cli";
+
+export default defineConfig({
+  name: "${name}",
+  database: process.env.DATABASE_URL,
+  dataApi: process.env.NEON_DATA_API,
+  deploy: {
+    host: process.env.DEPLOY_HOST,
+    dir: "/opt/upend",
+  },
+});
+`);
+
+  writeFile(projectDir, "package.json", JSON.stringify({
+    name,
+    private: true,
+    type: "module",
+    scripts: {
+      dev: "upend dev",
+      deploy: "upend deploy",
+      migrate: "upend migrate",
+    },
+    dependencies: {
+      "@upend/cli": cliDep,
+    },
+  }, null, 2) + "\n");
+
+  writeFile(projectDir, ".env", `DATABASE_URL="${databaseUrl}"
+NEON_DATA_API="${neonDataApi}"
+NEON_PROJECT_ID="${neonProjectId}"
+ANTHROPIC_API_KEY=
+DEPLOY_HOST=
+API_PORT=3001
+CLAUDE_PORT=3002
+`);
+
+  writeFile(projectDir, ".env.example", `DATABASE_URL=postgresql://user:pass@host/db?sslmode=require
+NEON_DATA_API=https://xxx.data-api.neon.tech
+ANTHROPIC_API_KEY=sk-ant-...
+DEPLOY_HOST=ec2-user@x.x.x.x
+`);
+
+  writeFile(projectDir, ".gitignore", `node_modules/
+.env
+.env.keys
+.keys/
+.snapshots/
+sessions/
+*.log
+.DS_Store
+`);
+
+  // migrations
+  mkdirSync(join(projectDir, "migrations"), { recursive: true });
+  writeFile(projectDir, "migrations/001_init.sql", `-- your first migration
+CREATE TABLE IF NOT EXISTS example (
+  id BIGSERIAL PRIMARY KEY,
+  name TEXT NOT NULL,
+  data JSONB DEFAULT '{}',
+  created_at TIMESTAMPTZ DEFAULT now(),
+  updated_at TIMESTAMPTZ DEFAULT now()
+);
+`);
+
+  // apps + services
+  mkdirSync(join(projectDir, "apps"), { recursive: true });
+  writeFile(projectDir, "apps/.gitkeep", "");
+  mkdirSync(join(projectDir, "services"), { recursive: true });
+  writeFile(projectDir, "services/.gitkeep", "");
+
+  // CLAUDE.md
+  writeFile(projectDir, "CLAUDE.md", `# ${name}
+
+You have FULL control of this codebase. Edit anything. Run anything. Create migrations. You are the developer.
+
+Changes take effect immediately (Bun --watch). A snapshot was taken before you started — if something breaks, the user can rollback.
+
+## Stack
+- **Runtime**: Bun
+- **Framework**: Hono
+- **Database**: Neon Postgres (connection in node_modules/@upend/cli)
+- **Auth**: Custom JWT (RS256)
+- **Domain**: ${domain}
+
+## What you can do
+- Edit any file in the project
+- Create new files, migrations, apps
+- Run \`upend migrate\` to apply database migrations
+- Create apps in \`apps/\` that are instantly served at \`/apps/<name>/\`
+
+## Data API
+Apps talk to Neon Data API at \`/api/data/<table>\`:
+- GET \`/api/data/example?order=created_at.desc\` — list rows
+- POST \`/api/data/example\` — create (JSON body, \`Prefer: return=representation\`)
+- PATCH \`/api/data/example?id=eq.5\` — update
+- DELETE \`/api/data/example?id=eq.5\` — delete
+All requests need \`Authorization: Bearer <jwt>\` header.
+
+## Conventions
+- Migrations: plain SQL in \`migrations/\`, numbered \`001_name.sql\`
+- Apps: static HTML/JS/CSS in \`apps/<name>/\`
+- Custom services: \`services/<name>/index.ts\`
+`);
+
+  log.success("project scaffolded");
+
+  // ── 4. encrypt .env ──
+
+  if (databaseUrl) {
+    log.info("encrypting .env...");
+    await exec(["bunx", "@dotenvx/dotenvx", "encrypt"], { cwd: projectDir });
+    log.success(".env encrypted");
+  }
+
+  // ── 5. git init ──
+
+  log.info("initializing git...");
+  await execOrDie(["git", "init"], { cwd: projectDir });
+  await execOrDie(["git", "add", "-A"], { cwd: projectDir });
+  await execOrDie(["git", "commit", "-m", "initial commit"], { cwd: projectDir });
+  log.success("git initialized");
+
+  // ── 6. install deps ──
+
+  log.info("installing dependencies...");
+  await execOrDie(["bun", "install"], { cwd: projectDir });
+  log.success("dependencies installed");
+
+  // ── done ──
+
+  log.blank();
+  log.header(`${name} is ready`);
+  log.blank();
+  log.info(`cd ${name}`);
+  if (!databaseUrl) {
+    log.info("# add your DATABASE_URL to .env");
+  }
+  if (!process.env.ANTHROPIC_API_KEY) {
+    log.info("# add your ANTHROPIC_API_KEY to .env");
+  }
+  log.info("upend dev");
+  log.blank();
+  if (databaseUrl) {
+    log.dim(`database:  ${neonProjectId}`);
+    if (neonDataApi) log.dim(`data API:  ${neonDataApi}`);
+    log.dim(`JWKS:      https://${domain}/.well-known/jwks.json`);
+    log.dim(`deploy:    upend infra:aws && upend deploy`);
+  }
+  log.blank();
+}
+
+// ── helpers ──
+
+function getNeonToken(): string | null {
+  const paths = [
+    join(process.env.HOME || "", ".config/neonctl/credentials.json"),
+    join(process.env.HOME || "", "Library/Application Support/neonctl/credentials.json"),
+  ];
+  for (const p of paths) {
+    try {
+      const creds = JSON.parse(readFileSync(p, "utf-8"));
+      return creds.access_token || null;
+    } catch {}
+  }
+  return null;
+}
+
+function writeFile(dir: string, path: string, content: string) {
+  const fullPath = join(dir, path);
+  mkdirSync(join(fullPath, ".."), { recursive: true });
+  writeFileSync(fullPath, content);
+}
+
+async function exportKeyToPem(key: CryptoKey, type: "PRIVATE" | "PUBLIC") {
+  const format = type === "PRIVATE" ? "pkcs8" : "spki";
+  const exported = await crypto.subtle.exportKey(format, key);
+  const b64 = Buffer.from(exported).toString("base64");
+  const lines = b64.match(/.{1,64}/g)!.join("\n");
+  return `-----BEGIN ${type} KEY-----\n${lines}\n-----END ${type} KEY-----\n`;
+}

package/src/commands/migrate.ts

@@ -0,0 +1,64 @@
+import { log } from "../lib/log";
+import { readdirSync, readFileSync } from "fs";
+import { join, resolve } from "path";
+
+export default async function migrate(args: string[]) {
+  const projectDir = resolve(".");
+  const migrationsDir = join(projectDir, "migrations");
+
+  log.header("running migrations");
+
+  // dynamic import postgres from the project's node_modules
+  const postgres = (await import("postgres")).default;
+  const sql = postgres(process.env.DATABASE_URL!, {
+    max: 1,
+    onnotice: () => {},
+  });
+
+  try {
+    // ensure migrations table
+    await sql`
+      CREATE TABLE IF NOT EXISTS _migrations (
+        name TEXT PRIMARY KEY,
+        ran_at TIMESTAMPTZ DEFAULT now()
+      )
+    `;
+
+    const ran = new Set(
+      (await sql`SELECT name FROM _migrations`).map((r: any) => r.name)
+    );
+
+    let files: string[];
+    try {
+      files = readdirSync(migrationsDir)
+        .filter((f) => f.endsWith(".sql"))
+        .sort();
+    } catch {
+      log.warn("no migrations directory found");
+      process.exit(0);
+    }
+
+    let count = 0;
+    for (const file of files) {
+      if (ran.has(file)) continue;
+      log.info(`running: ${file}`);
+      const content = readFileSync(join(migrationsDir, file), "utf-8");
+      await sql.unsafe(content);
+      await sql`INSERT INTO _migrations (name) VALUES (${file})`;
+      log.success(file);
+      count++;
+    }
+
+    if (count === 0) {
+      log.info("no new migrations");
+    } else {
+      log.success(`${count} migration(s) applied`);
+    }
+
+    await sql.end();
+  } catch (err: any) {
+    log.error(`migration failed: ${err.message}`);
+    await sql.end();
+    process.exit(1);
+  }
+}

package/src/config.ts

@@ -0,0 +1,18 @@
+export interface UpendConfig {
+  name: string;
+  database?: string;
+  dataApi?: string;
+  auth?: {
+    audience?: string;
+    tokenExpiry?: string;
+  };
+  services?: Record<string, { entry: string; port: number }>;
+  deploy?: {
+    host?: string;
+    dir?: string;
+  };
+}
+
+export function defineConfig(config: UpendConfig): UpendConfig {
+  return config;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { defineConfig } from "./config";
+export type { UpendConfig } from "./config";

package/src/lib/auth.ts

@@ -0,0 +1,89 @@
+import { importPKCS8, importSPKI, exportJWK, SignJWT, jwtVerify } from "jose";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+
+// KEYS_DIR resolves from the user's project, not the package
+const PROJECT_ROOT = process.env.UPEND_PROJECT || process.cwd();
+const KEYS_DIR = join(PROJECT_ROOT, ".keys");
+const PRIVATE_KEY_PATH = join(KEYS_DIR, "private.pem");
+const PUBLIC_KEY_PATH = join(KEYS_DIR, "public.pem");
+const ALG = "RS256";
+const ISSUER = "upend";
+
+async function ensureKeys() {
+  if (existsSync(PRIVATE_KEY_PATH) && existsSync(PUBLIC_KEY_PATH)) return;
+
+  mkdirSync(KEYS_DIR, { recursive: true });
+  console.log("[auth] generating RSA key pair...");
+
+  const { privateKey, publicKey } = await crypto.subtle.generateKey(
+    { name: "RSASSA-PKCS1-v1_5", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" },
+    true,
+    ["sign", "verify"]
+  );
+
+  const privPem = await exportKeyToPem(privateKey, "PRIVATE");
+  const pubPem = await exportKeyToPem(publicKey, "PUBLIC");
+
+  writeFileSync(PRIVATE_KEY_PATH, privPem);
+  writeFileSync(PUBLIC_KEY_PATH, pubPem);
+  console.log("[auth] keys written to .keys/");
+}
+
+async function exportKeyToPem(key: CryptoKey, type: "PRIVATE" | "PUBLIC") {
+  const format = type === "PRIVATE" ? "pkcs8" : "spki";
+  const exported = await crypto.subtle.exportKey(format, key);
+  const b64 = Buffer.from(exported).toString("base64");
+  const lines = b64.match(/.{1,64}/g)!.join("\n");
+  return `-----BEGIN ${type} KEY-----\n${lines}\n-----END ${type} KEY-----\n`;
+}
+
+let _privateKey: Awaited<ReturnType<typeof importPKCS8>> | null = null;
+let _publicKey: Awaited<ReturnType<typeof importSPKI>> | null = null;
+
+async function getPrivateKey() {
+  if (!_privateKey) {
+    await ensureKeys();
+    _privateKey = await importPKCS8(readFileSync(PRIVATE_KEY_PATH, "utf-8"), ALG);
+  }
+  return _privateKey;
+}
+
+async function getPublicKey() {
+  if (!_publicKey) {
+    await ensureKeys();
+    _publicKey = await importSPKI(readFileSync(PUBLIC_KEY_PATH, "utf-8"), ALG);
+  }
+  return _publicKey;
+}
+
+export async function signToken(userId: string, email: string, appRole: string = "user") {
+  const key = await getPrivateKey();
+  return new SignJWT({ email, role: "authenticated", app_role: appRole })
+    .setProtectedHeader({ alg: ALG, kid: "upend-1" })
+    .setSubject(userId)
+    .setIssuer(ISSUER)
+    .setAudience("upend")
+    .setIssuedAt()
+    .setExpirationTime("24h")
+    .sign(key);
+}
+
+export async function verifyToken(token: string) {
+  const key = await getPublicKey();
+  const { payload } = await jwtVerify(token, key, {
+    issuer: ISSUER,
+    audience: "upend",
+  });
+  return payload;
+}
+
+export async function getJWKS() {
+  const key = await getPublicKey();
+  const jwk = await exportJWK(key);
+  return {
+    keys: [
+      { ...jwk, kid: "upend-1", alg: ALG, use: "sig" },
+    ],
+  };
+}

package/src/lib/db.ts

@@ -0,0 +1,14 @@
+import postgres from "postgres";
+
+export const sql = postgres(process.env.DATABASE_URL!, {
+  max: 20,
+  idle_timeout: 20,
+  connect_timeout: 10,
+  transform: postgres.camel,
+  onnotice: (notice) => console.log("pg:", notice.message),
+});
+
+// subscribe to pg NOTIFY for realtime log streaming
+export async function listen(channel: string, fn: (payload: string) => void) {
+  await sql.listen(channel, fn);
+}

package/src/lib/exec.ts

@@ -0,0 +1,38 @@
+import { log } from "./log";
+
+export async function exec(
+  cmd: string[],
+  opts: { cwd?: string; env?: Record<string, string>; silent?: boolean } = {}
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const proc = Bun.spawn(cmd, {
+    cwd: opts.cwd,
+    env: { ...process.env, ...opts.env },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0 && !opts.silent) {
+    log.error(`command failed: ${cmd.join(" ")}`);
+    if (stderr.trim()) log.dim(stderr.trim());
+  }
+
+  return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
+}
+
+export async function execOrDie(cmd: string[], opts: { cwd?: string } = {}): Promise<{ stdout: string; stderr: string }> {
+  const { stdout, exitCode, stderr } = await exec(cmd, opts);
+  if (exitCode !== 0) {
+    log.error(stderr || `${cmd.join(" ")} failed`);
+    process.exit(1);
+  }
+  return { stdout, stderr };
+}
+
+export async function hasCommand(name: string): Promise<boolean> {
+  const { exitCode } = await exec(["which", name], { silent: true });
+  return exitCode === 0;
+}

package/src/lib/log.ts

@@ -0,0 +1,16 @@
+const orange = "\x1b[38;5;208m";
+const green = "\x1b[32m";
+const red = "\x1b[31m";
+const dim = "\x1b[2m";
+const reset = "\x1b[0m";
+const bold = "\x1b[1m";
+
+export const log = {
+  info: (msg: string) => console.log(`${dim}→${reset} ${msg}`),
+  success: (msg: string) => console.log(`${green}✓${reset} ${msg}`),
+  error: (msg: string) => console.error(`${red}✗${reset} ${msg}`),
+  warn: (msg: string) => console.log(`${orange}!${reset} ${msg}`),
+  header: (msg: string) => console.log(`\n${bold}${orange}${msg}${reset}\n`),
+  dim: (msg: string) => console.log(`  ${dim}${msg}${reset}`),
+  blank: () => console.log(),
+};

package/src/lib/middleware.ts

@@ -0,0 +1,51 @@
+import { createMiddleware } from "hono/factory";
+import { verifyToken } from "./auth";
+
+type AuthPayload = {
+  sub: string;
+  email: string;
+  role: string;
+};
+
+// middleware that verifies JWT from Authorization header or ?token= query param
+export const requireAuth = createMiddleware<{
+  Variables: { user: AuthPayload };
+}>(async (c, next) => {
+  const header = c.req.header("Authorization");
+  const queryToken = c.req.query("token");
+  const token = header?.startsWith("Bearer ") ? header.slice(7) : queryToken;
+  const method = c.req.method;
+  const path = c.req.path;
+
+  if (!token) {
+    console.log(`[auth] 401 no token: ${method} ${path}`);
+    return c.json({ error: "missing or invalid Authorization" }, 401);
+  }
+
+  try {
+    const payload = await verifyToken(token);
+    const user = {
+      sub: payload.sub as string,
+      email: payload.email as string,
+      role: (payload.role as string) || "user",
+    };
+    console.log(`[auth] ${user.email} → ${method} ${path}`);
+    c.set("user", user);
+    await next();
+  } catch (err: any) {
+    console.log(`[auth] 401 invalid token: ${method} ${path} — ${err.message}`);
+    return c.json({ error: "invalid token", detail: err.message }, 401);
+  }
+});
+
+// middleware that requires a specific role
+export const requireRole = (...roles: string[]) =>
+  createMiddleware(async (c, next) => {
+    const user = c.get("user") as AuthPayload | undefined;
+    if (!user) return c.json({ error: "not authenticated" }, 401);
+    if (!roles.includes(user.role)) {
+      console.log(`[auth] 403 forbidden: ${user.email} needs ${roles.join("|")}, has ${user.role}`);
+      return c.json({ error: "forbidden" }, 403);
+    }
+    await next();
+  });