create-svc 0.1.9 → 0.1.11

package/templates/targets/workers/README.md

@@ -0,0 +1,75 @@
+# {{SERVICE_NAME}}
+
+Generated by `create-service`.
+
+This `{{PROFILE}}` profile targets `{{RUNTIME}} + {{FRAMEWORK}}` on Cloudflare Workers with:
+
+- one `wrangler.toml`
+- a lightweight waitlist/launch API
+- a local `service` CLI for create, deploy, doctor, dashboards, DNS, and destroy
+- Cron Trigger wiring for scheduled follow-up work
+- a Hyperdrive binding for Neon-backed Postgres persistence
+- a production API origin at `https://{{API_HOSTNAME}}`
+
+## Commands
+
+```bash
+wrangler dev
+bun run test
+bun run lint
+bun run migrate
+bun run create
+bun run deploy
+bun run dashboards
+bun run doctor
+bun run destroy
+```
+
+## Local Development
+
+```bash
+bun install
+bun run dev
+```
+
+The Workers target starts with an HTTP waitlist API. Local unit tests use an
+in-memory store. Deployed Workers use the `HYPERDRIVE` binding and create the
+small waitlist/trigger schema on first use.
+
+## API
+
+- `GET /healthz`
+- `GET /readyz`
+- `POST /v1/waitlist`
+- `GET /v1/waitlist?email=<email>`
+- `GET /v1/waitlist/:entryId`
+- `POST /v1/triggers/waitlist`
+- `POST /webhooks/:provider`
+- `GET /webhooks/:provider/health`
+
+## Production
+
+```bash
+bun run create
+```
+
+`service create` deploys the Worker through Wrangler. The custom domain is
+configured in `wrangler.toml`:
+
+```bash
+https://{{API_HOSTNAME}}
+```
+
+Use `bun run doctor` after create to verify Wrangler auth, route config, Cron,
+Hyperdrive, dashboard tooling, auth tooling, and deployed health.
+
+If the Hyperdrive binding id is empty, `service create` uses `DATABASE_URL`, or
+`NEON_API_KEY` to create/resolve the generated Neon database and connection URI,
+applies the waitlist schema, then runs `wrangler hyperdrive create` and writes
+the returned id back into `wrangler.toml` before deploy.
+
+You can also apply the schema manually:
+
+```bash
+DATABASE_URL=postgres://... bun run migrate
+```

package/templates/targets/workers/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "{{SERVICE_NAME}}",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "service": "./scripts/workers/cli.ts"
+  },
+  "scripts": {
+    "dev": "wrangler dev",
+    "service": "bun run ./scripts/workers/cli.ts",
+    "migrate": "bun run ./scripts/workers/cli.ts migrate",
+    "seed": "bun run ./scripts/workers/cli.ts seed",
+    "lint": "bunx tsc --noEmit",
+    "test": "bun test",
+    "create": "bun run ./scripts/workers/cli.ts create",
+    "deploy": "bun run ./scripts/workers/cli.ts deploy",
+    "dashboards": "bun run ./scripts/workers/cli.ts dashboards",
+    "auth": "bun run ./scripts/workers/cli.ts auth",
+    "destroy": "bun run ./scripts/workers/cli.ts destroy"
+  },
+  "dependencies": {
+    "@anmho/authctl": "0.1.1",
+    "@clack/prompts": "^1.2.0",
+    "@neondatabase/api-client": "^2.7.1",
+    "hono": "^4.10.1",
+    "pg": "^8.16.3"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "latest",
+    "@types/pg": "^8.16.0",
+    "@types/bun": "latest",
+    "typescript": "^5.9.3",
+    "wrangler": "^4.49.0"
+  }
+}

package/templates/targets/workers/scripts/workers/cli.ts

@@ -0,0 +1,397 @@
+#!/usr/bin/env bun
+
+import { confirm, intro, isCancel, log, outro } from "@clack/prompts";
+import { createApiClient } from "@neondatabase/api-client";
+import { Client } from "pg";
+import { ensureAuthResourceServer, runAuthCommand, runAuthDoctor } from "../authctl";
+
+const config = {
+  serviceName: "{{SERVICE_NAME}}",
+  hostname: "{{API_HOSTNAME}}",
+  neonDatabaseName: "{{NEON_DATABASE_NAME}}",
+  neonRoleName: "neondb_owner",
+};
+
+type DoctorStatus = "pass" | "warn" | "fail";
+
+async function main(argv = Bun.argv.slice(2)) {
+  const [command, ...rest] = argv;
+
+  if (command === "create") {
+    return runMain("Create", async () => {
+      ensureAuthResourceServer();
+      const databaseUrl = await resolveDatabaseUrl();
+      await applySchema(databaseUrl);
+      await ensureHyperdrive(databaseUrl);
+      run("wrangler", ["deploy"]);
+      return `Created https://${config.hostname}`;
+    });
+  }
+
+  if (command === "deploy") {
+    return runMain("Deploy", () => {
+      run("wrangler", ["deploy", ...rest]);
+      return `Deployed https://${config.hostname}`;
+    });
+  }
+
+  if (command === "migrate") {
+    return runMain("Migrate", async () => {
+      await applySchema(await resolveDatabaseUrl());
+      return "Workers database schema applied";
+    });
+  }
+
+  if (command === "seed") {
+    return runMain("Seed", () => "Seed data is not configured");
+  }
+
+  if (command === "dashboards") {
+    return runMain("Dashboards", () => {
+      run("gcx", ["dev", "lint", "run", "./grafana", "-o", "compact"]);
+      run("gcx", ["resources", "push", "--path", "./grafana"]);
+      return "Dashboards pushed";
+    });
+  }
+
+  if (command === "dns") {
+    return runMain("DNS", () => `Workers custom domain is configured in wrangler.toml for ${config.hostname}`);
+  }
+
+  if (command === "doctor") {
+    return runMain("Doctor", () => runDoctor());
+  }
+
+  if (command === "auth") {
+    return runMain("Auth", () => runAuthCommand(rest));
+  }
+
+  if (command === "destroy") {
+    return runMain("Destroy", async () => {
+      await requireDestroyConfirmation(rest.includes("--force"));
+      const wranglerArgs = rest.filter((arg) => arg !== "--force");
+      await deleteHyperdrive();
+      run("wrangler", ["delete", "--name", config.serviceName, "--force", ...wranglerArgs]);
+      await deleteNeonDatabase();
+      await deleteGrafanaResources();
+      return `Destroyed ${config.serviceName}`;
+    });
+  }
+
+  if (command === "sdk") {
+    throw new Error("SDK commands are only available for ConnectRPC services");
+  }
+
+  throw new Error("Usage: service <create|deploy|migrate|seed|dashboards|dns|doctor|destroy|auth|sdk> [args]");
+}
+
+function run(command: string, args: string[], options: { allowFailure?: boolean; capture?: boolean } = {}) {
+  if (!Bun.which(command)) {
+    throw new Error(`missing required command: ${command}`);
+  }
+  const result = Bun.spawnSync([command, ...args], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdin: "inherit",
+    stdout: options.capture ? "pipe" : "inherit",
+    stderr: options.capture ? "pipe" : "inherit",
+  });
+  if (!result.success && !options.allowFailure) {
+    throw new Error(`${command} ${args.join(" ")} failed with exit code ${result.exitCode}`);
+  }
+  return result;
+}
+
+async function ensureHyperdrive(databaseUrl?: string) {
+  const configPath = "./wrangler.toml";
+  const text = await Bun.file(configPath).text();
+  if (!text.includes('binding = "HYPERDRIVE"')) {
+    return;
+  }
+  if (!text.includes('id = ""')) {
+    return;
+  }
+
+  const resolvedDatabaseUrl = databaseUrl ?? (await resolveDatabaseUrl());
+
+  const result = run("wrangler", ["hyperdrive", "create", `${config.serviceName}-hyperdrive`, "--connection-string", resolvedDatabaseUrl], {
+    capture: true,
+  });
+  const output = `${result.stdout ? new TextDecoder().decode(result.stdout) : ""}\n${result.stderr ? new TextDecoder().decode(result.stderr) : ""}`;
+  const hyperdriveId = extractHyperdriveId(output);
+  if (!hyperdriveId) {
+    throw new Error(`Could not find Hyperdrive id in wrangler output:\n${output.trim()}`);
+  }
+
+  await Bun.write(configPath, text.replace('id = ""', `id = "${hyperdriveId}"`));
+}
+
+function extractHyperdriveId(output: string) {
+  const jsonMatch = output.match(/"id"\s*:\s*"([^"]+)"/);
+  if (jsonMatch?.[1]) {
+    return jsonMatch[1];
+  }
+  const tomlMatch = output.match(/id\s*=\s*"([^"]+)"/);
+  return tomlMatch?.[1];
+}
+
+async function deleteHyperdrive() {
+  const text = await Bun.file("./wrangler.toml").text();
+  const id = text.match(/binding\s*=\s*"HYPERDRIVE"[\s\S]*?id\s*=\s*"([^"]+)"/)?.[1];
+  if (!id) {
+    return;
+  }
+  run("wrangler", ["hyperdrive", "delete", id, "--force"], { allowFailure: true });
+}
+
+async function resolveDatabaseUrl() {
+  const direct = Bun.env.DATABASE_URL?.trim();
+  if (direct) {
+    return direct;
+  }
+
+  const apiKey = Bun.env.NEON_API_KEY?.trim();
+  if (!apiKey) {
+    throw new Error("DATABASE_URL or NEON_API_KEY is required to provision the Hyperdrive binding");
+  }
+
+  const { neon, projectId, branchId } = await resolveNeonTarget(apiKey);
+
+  try {
+    await neon.getProjectBranchDatabase(projectId, branchId, config.neonDatabaseName);
+  } catch (error) {
+    const status = (error as { response?: { status?: number } })?.response?.status;
+    if (status !== 404) {
+      throw error;
+    }
+    await neon.createProjectBranchDatabase(projectId, branchId, {
+      database: {
+        name: config.neonDatabaseName,
+        owner_name: config.neonRoleName,
+      },
+    });
+  }
+
+  const uriPayload = await neon.getConnectionUri({
+    projectId,
+    branch_id: branchId,
+    database_name: config.neonDatabaseName,
+    role_name: config.neonRoleName,
+  });
+  const uri = (uriPayload.data as { uri?: string } | undefined)?.uri;
+  if (!uri) {
+    throw new Error(`Neon did not return a connection URI for ${config.neonDatabaseName}`);
+  }
+  return uri;
+}
+
+async function resolveNeonTarget(apiKey: string) {
+  const neon = createApiClient({ apiKey });
+  const projectsPayload = await neon.listProjects({ limit: 100 });
+  const projects = ((projectsPayload.data as { projects?: Array<{ id?: string }> } | undefined)?.projects ?? []).filter((project) => project.id);
+  const project = projects[0];
+  if (!project?.id) {
+    throw new Error("No Neon projects are available for Workers provisioning");
+  }
+
+  const branchesPayload = await neon.listProjectBranches({ projectId: project.id });
+  const branches = ((branchesPayload.data as { branches?: Array<{ id?: string; name?: string }> } | undefined)?.branches ?? []).filter(
+    (branch) => branch.id
+  );
+  const branch = branches.find((candidate) => candidate.name === "main") ?? branches[0];
+  if (!branch?.id) {
+    throw new Error(`No Neon branches are available in project ${project.id}`);
+  }
+
+  return { neon, projectId: project.id, branchId: branch.id };
+}
+
+async function deleteNeonDatabase() {
+  const apiKey = Bun.env.NEON_API_KEY?.trim();
+  if (!apiKey) {
+    log.step("Skipping Neon database deletion because NEON_API_KEY is not set");
+    return;
+  }
+
+  const { neon, projectId, branchId } = await resolveNeonTarget(apiKey);
+  try {
+    await neon.getProjectBranchDatabase(projectId, branchId, config.neonDatabaseName);
+  } catch (error) {
+    const status = (error as { response?: { status?: number } })?.response?.status;
+    if (status === 404) {
+      return;
+    }
+    throw error;
+  }
+
+  const payload = await neon.getProjectBranchDatabase(projectId, branchId, config.neonDatabaseName);
+  const database = (payload.data as { database?: { name?: string; owner_name?: string } } | undefined)?.database;
+  if (database?.name !== config.neonDatabaseName || (database.owner_name && database.owner_name !== config.neonRoleName)) {
+    throw new Error(`Refusing to delete Neon database ${database?.name ?? config.neonDatabaseName}; ownership metadata does not match`);
+  }
+
+  await neon.deleteProjectBranchDatabase(projectId, branchId, config.neonDatabaseName);
+}
+
+async function deleteGrafanaResources() {
+  if (!(await Bun.file("./grafana").exists())) {
+    return;
+  }
+  if (!Bun.which("gcx")) {
+    log.step("Skipping Grafana deletion because gcx is not installed");
+    return;
+  }
+  run("gcx", ["resources", "delete", "--path", "./grafana", "--yes", "--on-error", "ignore"], { allowFailure: true });
+}
+
+async function applySchema(databaseUrl: string) {
+  const client = new Client({ connectionString: databaseUrl });
+  await client.connect();
+  try {
+    await client.query(`
+create table if not exists waitlist_entries (
+  id text primary key,
+  email text not null unique,
+  name text,
+  company text,
+  source text,
+  status text not null default 'joined',
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+create table if not exists waitlist_triggers (
+  id text primary key,
+  type text not null,
+  entry_id text references waitlist_entries(id) on delete set null,
+  status text not null default 'queued',
+  payload_json text not null default '{}',
+  created_at timestamptz not null default now(),
+  processed_at timestamptz
+);
+
+create index if not exists waitlist_triggers_status_created_idx
+  on waitlist_triggers (status, created_at);
+`);
+  } finally {
+    await client.end();
+  }
+}
+
+async function runDoctor() {
+  const results: Array<{ name: string; status: DoctorStatus; detail: string }> = [];
+
+  await record(results, "bun CLI", "fail", () => checkCommand("bun"));
+  await record(results, "wrangler CLI", "fail", () => checkCommand("wrangler"));
+  await record(results, "wrangler auth", "fail", () => {
+    run("wrangler", ["whoami"]);
+    return "authenticated";
+  });
+  await record(results, "wrangler.toml", "fail", async () => {
+    const text = await Bun.file("./wrangler.toml").text();
+    if (!text.includes(`name = "${config.serviceName}"`)) {
+      throw new Error(`wrangler.toml does not name ${config.serviceName}`);
+    }
+    if (!text.includes(`pattern = "${config.hostname}/*"`)) {
+      throw new Error(`wrangler.toml does not route ${config.hostname}`);
+    }
+    return "name and custom domain route configured";
+  });
+  await record(results, "Cron Trigger", "fail", async () => {
+    const text = await Bun.file("./wrangler.toml").text();
+    if (!text.includes("[triggers]") || !text.includes("crons")) {
+      throw new Error("wrangler.toml is missing a cron trigger");
+    }
+    return "cron trigger configured";
+  });
+  await record(results, "Hyperdrive binding", "warn", async () => {
+    const text = await Bun.file("./wrangler.toml").text();
+    if (!text.includes('binding = "HYPERDRIVE"')) {
+      throw new Error("HYPERDRIVE binding is missing");
+    }
+    if (text.includes('id = ""')) {
+      throw new Error("HYPERDRIVE id is not provisioned yet");
+    }
+    return "Hyperdrive binding has an id";
+  });
+  await record(results, "dashboard tooling", "warn", () => checkCommand("gcx"));
+  await record(results, "dashboard artifacts", "warn", async () => {
+    if (!(await Bun.file("./grafana").exists()) && !(await Bun.file("./dashboards").exists())) {
+      throw new Error("no grafana/ or dashboards/ directory found");
+    }
+    return "dashboard directory found";
+  });
+  await record(results, "authctl", "warn", () => runAuthDoctor().detail);
+  await record(results, "deployed health", "warn", async () => {
+    const response = await fetch(`https://${config.hostname}/healthz`, { signal: AbortSignal.timeout(5_000) });
+    if (!response.ok) {
+      throw new Error(`GET /healthz returned ${response.status}`);
+    }
+    return "GET /healthz ok";
+  });
+
+  const output = results.map(formatDoctorResult).join("\n");
+  const failures = results.filter((result) => result.status === "fail");
+  if (failures.length > 0) {
+    throw new Error(`Doctor found ${failures.length} failing check(s)\n${output}`);
+  }
+  return output;
+}
+
+async function record(
+  results: Array<{ name: string; status: DoctorStatus; detail: string }>,
+  name: string,
+  failureStatus: "warn" | "fail",
+  check: () => string | Promise<string>
+) {
+  try {
+    results.push({ name, status: "pass", detail: await check() });
+  } catch (error) {
+    results.push({ name, status: failureStatus, detail: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+function checkCommand(name: string) {
+  const path = Bun.which(name);
+  if (!path) {
+    throw new Error(`${name} is not installed`);
+  }
+  return path;
+}
+
+function formatDoctorResult(result: { name: string; status: DoctorStatus; detail: string }) {
+  const marker = result.status === "pass" ? "PASS" : result.status === "warn" ? "WARN" : "FAIL";
+  return `[${marker}] ${result.name}: ${result.detail}`;
+}
+
+async function requireDestroyConfirmation(force: boolean) {
+  if (force) {
+    return;
+  }
+
+  if (!process.stdin.isTTY) {
+    throw new Error("service destroy requires --force when running non-interactively");
+  }
+
+  const answer = await confirm({
+    message: `Destroy resources owned by ${config.serviceName}?`,
+    initialValue: false,
+  });
+  if (isCancel(answer) || !answer) {
+    throw new Error("Destroy cancelled");
+  }
+}
+
+async function runMain(name: string, task: () => string | Promise<string>) {
+  intro(name);
+  try {
+    outro(await task());
+  } catch (error) {
+    log.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+if (import.meta.main) {
+  await main();
+}

package/templates/targets/workers/src/auth.ts

@@ -0,0 +1,178 @@
+type AuthConfig = {
+  enabled: boolean;
+  issuer: string;
+  audience: string;
+  jwksUrl: string;
+};
+
+type AuthEnv = {
+  AUTH_ENABLED?: string;
+  AUTH_ISSUER?: string;
+  AUTH_AUDIENCE?: string;
+  AUTH_JWKS_URL?: string;
+};
+
+type JwtHeader = {
+  alg?: string;
+  kid?: string;
+};
+
+type JwtClaims = {
+  iss?: string;
+  aud?: string | string[];
+  exp?: number;
+  nbf?: number;
+};
+
+type Jwk = JsonWebKey & {
+  kid?: string;
+};
+
+type Jwks = {
+  keys: Jwk[];
+};
+
+const encoder = new TextEncoder();
+const jwksCache = new Map<string, { expiresAt: number; jwks: Jwks }>();
+
+export function authMiddleware() {
+  return async (context: any, next: () => Promise<void>) => {
+    const config = authConfigFromEnv(context.env ?? {});
+    if (!config.enabled) {
+      await next();
+      return;
+    }
+
+    const token = bearerToken(context.req.header("authorization") ?? "");
+    if (!token) {
+      return context.json({ error: "missing bearer token", code: "unauthorized" }, 401);
+    }
+
+    try {
+      await verifyAccessToken(token, config);
+      await next();
+    } catch {
+      return context.json({ error: "invalid bearer token", code: "unauthorized" }, 401);
+    }
+  };
+}
+
+function authConfigFromEnv(env: AuthEnv): AuthConfig {
+  return {
+    enabled: truthy(env.AUTH_ENABLED),
+    issuer: env.AUTH_ISSUER ?? "",
+    audience: env.AUTH_AUDIENCE ?? "",
+    jwksUrl: env.AUTH_JWKS_URL ?? "",
+  };
+}
+
+async function verifyAccessToken(token: string, config: AuthConfig): Promise<JwtClaims> {
+  const parts = token.split(".");
+  if (parts.length !== 3 || !config.issuer || !config.audience || !config.jwksUrl) {
+    throw new Error("invalid auth config or token");
+  }
+
+  const [encodedHeader, encodedPayload, encodedSignature] = parts;
+  const header = decodeJSON<JwtHeader>(encodedHeader);
+  const claims = decodeJSON<JwtClaims>(encodedPayload);
+  const jwks = await fetchJwks(config.jwksUrl);
+  const key = selectKey(jwks, header);
+  if (!key || !header.alg) {
+    throw new Error("matching jwk not found");
+  }
+
+  const algorithm = importAlgorithm(header.alg, key);
+  const cryptoKey = await crypto.subtle.importKey("jwk", key, algorithm.import, false, ["verify"]);
+  const verified = await crypto.subtle.verify(
+    algorithm.verify,
+    cryptoKey,
+    toArrayBuffer(decodeBase64Url(encodedSignature)),
+    encoder.encode(`${encodedHeader}.${encodedPayload}`)
+  );
+  if (!verified) {
+    throw new Error("bad signature");
+  }
+
+  validateClaims(claims, config);
+  return claims;
+}
+
+async function fetchJwks(jwksUrl: string): Promise<Jwks> {
+  const cached = jwksCache.get(jwksUrl);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.jwks;
+  }
+
+  const response = await fetch(jwksUrl);
+  if (!response.ok) {
+    throw new Error(`jwks fetch failed: ${response.status}`);
+  }
+  const jwks = (await response.json()) as Jwks;
+  jwksCache.set(jwksUrl, { jwks, expiresAt: Date.now() + 5 * 60 * 1000 });
+  return jwks;
+}
+
+function selectKey(jwks: Jwks, header: JwtHeader): Jwk | undefined {
+  if (header.kid) {
+    return jwks.keys.find((key) => key.kid === header.kid);
+  }
+  return jwks.keys.length === 1 ? jwks.keys[0] : undefined;
+}
+
+function importAlgorithm(alg: string, key: JsonWebKey) {
+  if (alg === "RS256") {
+    return {
+      import: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+      verify: { name: "RSASSA-PKCS1-v1_5" },
+    } as const;
+  }
+  if (alg === "ES256" && key.crv === "P-256") {
+    return {
+      import: { name: "ECDSA", namedCurve: "P-256" },
+      verify: { name: "ECDSA", hash: "SHA-256" },
+    } as const;
+  }
+  throw new Error(`unsupported jwt alg: ${alg}`);
+}
+
+function validateClaims(claims: JwtClaims, config: AuthConfig) {
+  const now = Math.floor(Date.now() / 1000);
+  if (claims.iss !== config.issuer) {
+    throw new Error("issuer mismatch");
+  }
+  if (!audienceMatches(claims.aud, config.audience)) {
+    throw new Error("audience mismatch");
+  }
+  if (typeof claims.exp !== "number" || claims.exp <= now - 30) {
+    throw new Error("token expired");
+  }
+  if (typeof claims.nbf === "number" && claims.nbf > now + 30) {
+    throw new Error("token not active");
+  }
+}
+
+function audienceMatches(audience: JwtClaims["aud"], expected: string) {
+  return Array.isArray(audience) ? audience.includes(expected) : audience === expected;
+}
+
+function decodeJSON<T>(value: string): T {
+  return JSON.parse(new TextDecoder().decode(decodeBase64Url(value))) as T;
+}
+
+function decodeBase64Url(value: string): Uint8Array {
+  const base64 = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+  return Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+}
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+}
+
+function bearerToken(value: string) {
+  const [scheme, token] = value.trim().split(/\s+/, 2);
+  return /^Bearer$/i.test(scheme) ? token : "";
+}
+
+function truthy(value: string | undefined) {
+  return ["1", "true", "yes", "on"].includes((value ?? "").trim().toLowerCase());
+}