create-svc 0.1.9 → 0.1.11

package/templates/shared/README.md

@@ -1,52 +1,96 @@
 # {{SERVICE_NAME}}
 
-Generated by `create-svc`.
+Generated by `create-service`.
 
-This scaffold targets `{{RUNTIME}} + {{FRAMEWORK}}` on Cloud Run with:
+This `{{PROFILE}}` profile targets `{{RUNTIME}} + {{FRAMEWORK}}` on Cloud Run with:
 
 - one generated `service.yaml` manifest
-- a local `svc-cloudrun` CLI for bootstrap, deploy, and cleanup
-- GitHub Actions for CI, `main` deploys, PR previews, and personal environments
-- GCP project bootstrap with billing and quota-project-aware `gcloud` calls
-- Neon main, preview, and personal branch provisioning
+- a lightweight `{{EXAMPLE_LABEL}}` example surface
+- local Docker Compose Postgres for first-run development
+- a local `service` CLI for create, deploy, doctor, dashboards, and destroy
+- GCP project create with billing and quota-project-aware `gcloud` calls
+- Neon-backed remote database provisioning during create and deploy
+- Better Auth client-credentials resource-server registration through `authctl`
+- stage-aware waitlist data and trigger ingestion
+- typed HTTP webhook ingestion where the selected template supports it
+- a production API origin at `https://{{API_HOSTNAME}}`
+
+The default happy path is standalone. Terraform is optional: advanced users can
+precreate shared foundations and point this package at them, but a generated app
+does not need Terraform state, Terraform plans, a control plane, or a platform
+console to create and deploy.
 
 ## Commands
 
 ```bash
-make dev
-make gen
-make lint
-make test
-make bootstrap
-make deploy
-make deploy ARGS="--environment personal --name <slug>"
-make deploy ARGS="--destroy --environment personal --name <slug>"
-make cleanup
-make cleanup ARGS="--repo --project"
+{{COMMAND_DEV}}
+{{COMMAND_MIGRATE}}
+{{COMMAND_GEN}}
+{{COMMAND_LINT}}
+{{COMMAND_TEST}}
+{{COMMAND_BOOTSTRAP}}
+{{COMMAND_DEPLOY}}
+{{COMMAND_AUTH_RESOURCE}}
+{{COMMAND_AUTH_CLIENT}}
+{{COMMAND_DEPLOY_PERSONAL}}
+{{COMMAND_DEPLOY_DESTROY}}
+{{COMMAND_CLEANUP}}
+{{COMMAND_CLEANUP_PROJECT}}
+```
+
+## Local development
+
+The scaffold writes a ready-to-use `.env.local` and includes a local Postgres service in `docker-compose.yml`.
+
+First local run:
+
+```bash
+{{COMMAND_MIGRATE}}
+{{COMMAND_DEV}}
 ```
 
-## Configuration
+Local runtime uses:
+
+- `DATABASE_URL` from `.env.local`, pointed at Docker Compose Postgres
+- `{{COMMAND_MIGRATE}}` and `{{COMMAND_DEV}}`, which open Docker Desktop if needed, wait for Docker readiness, and start Docker Compose Postgres
+- `TEMPORAL_ENABLED=false` by default; set Temporal env vars locally only when you want to run against a real Temporal server
+
+No cloud credentials are required for local HTTP development after Docker and Postgres are running.
+
+## Remote provisioning
 
 The generated Cloud Run config lives in [scripts/cloudrun/config.ts](scripts/cloudrun/config.ts).
 
-Bootstrap, deploy, and cleanup use:
+Create, deploy, and destroy use:
 
+- known-good CLIs first, especially `gcloud`
 - `gcloud`
-- `gh`
 - `NEON_API_KEY`, or a working Vault login via `VAULT_ADDR` plus `VAULT_TOKEN`, `VAULT_TOKEN_FILE`, or `~/.vault-token`
-- the local repo CLI via `npx --no-install svc-cloudrun ...`
+- the package-local CLI via `npx --no-install service ...`
 
-## Environment setup
+Local provisioning intentionally prefers known-good CLIs over SDKs for Google Cloud operations.
 
-For project-specific Vault settings, prefer repo-local config over shell startup files:
+Authenticate `gcloud` on the machine before running provisioning commands:
 
 ```bash
-cp .env.example .env.local
+gcloud auth login
 ```
 
-Then edit `.env.local` with your Vault address and secret path overrides.
+If you also want local Application Default Credentials available for other tools, run:
 
-For the token itself, prefer a normal Vault login flow:
+```bash
+gcloud auth application-default login
+```
+
+The generated backend scripts still use `gcloud` as the primary control plane even when ADC is present.
+
+Go variants use Atlas for migrations:
+
+```bash
+atlas version
+```
+
+For the Neon admin credential, prefer a normal Vault login flow:
 
 ```bash
 vault login
@@ -60,10 +104,154 @@ The scaffold will use, in order:
 
 That keeps stable settings in the repo and keeps the token out of `~/.zshrc`.
 
-Optional Vault overrides for Neon admin key lookup:
+For production auth registration, `authctl` also needs the auth service's
+Cloudflare Access service token:
+
+```bash
+export AUTH_INTERNAL_BASE_URL="$(vault kv get -mount=secret -field=AUTH_INTERNAL_BASE_URL prod/apps/auth/authctl/cloudflare-access)"
+export CLOUDFLARE_ACCESS_SERVICE_TOKEN_CLIENT_ID="$(vault kv get -mount=secret -field=CLOUDFLARE_ACCESS_SERVICE_TOKEN_CLIENT_ID prod/apps/auth/authctl/cloudflare-access)"
+export CLOUDFLARE_ACCESS_SERVICE_TOKEN_CLIENT_SECRET="$(vault kv get -mount=secret -field=CLOUDFLARE_ACCESS_SERVICE_TOKEN_CLIENT_SECRET prod/apps/auth/authctl/cloudflare-access)"
+```
+
+Before first production create, verify the installed `authctl` exposes the
+resource-server control-plane command:
+
+```bash
+{{COMMAND_AUTH_RESOURCE}} --help
+```
+
+If this fails with `authctl is installed but does not expose resource-server
+commands`, make sure the generated package installed `@anmho/authctl@0.1.1` or
+newer before running `{{COMMAND_BOOTSTRAP}}`.
+
+Optional remote-only Vault overrides for Neon admin key lookup:
 
 - `VAULT_SECRET_MOUNT` default `secret`
-- `VAULT_NEON_API_KEY_PATH` default `provider/neon-api-key`
-- `VAULT_NEON_API_KEY_FIELD` default `value`
+- `VAULT_NEON_API_KEY_PATH` default `prod/providers/neon`
+- `VAULT_NEON_API_KEY_FIELD` default `api_key`
+
+The generator only stores application-facing connection material in Secret Manager. Neon admin credentials stay local to create and deploy.
+
+## Temporal
+
+Cloud Run variants include an in-process Temporal worker in the service process.
+Production Temporal is enabled when you set `TEMPORAL_ENABLED=true`, or when
+`TEMPORAL_ADDRESS`, `TEMPORAL_API_KEY`, or `TEMPORAL_API_KEY_SECRET` is present
+during deploy rendering.
+
+For Temporal Cloud, provide:
+
+```bash
+TEMPORAL_ENABLED=true
+TEMPORAL_ADDRESS=<namespace>.<account>.tmprl.cloud:7233
+TEMPORAL_NAMESPACE=<namespace>.<account>
+TEMPORAL_API_KEY=<one-time local value for service create>
+```
+
+`service create` writes `TEMPORAL_API_KEY` to Secret Manager as
+`{{SERVICE_ID}}-temporal-api-key` and grants the runtime service account access.
+Later deploys can set `TEMPORAL_API_KEY_SECRET={{SERVICE_ID}}-temporal-api-key`
+without exposing the key locally.
+
+## Service auth
+
+Generated services are resource servers for the Better Auth client-credentials
+server at `https://auth.anmho.com`.
+
+`service create` registers this service as an auth resource server through
+`authctl` before the first production deploy. The generated resource server is:
+
+- id: `{{SERVICE_ID}}`
+- audience: `api://{{SERVICE_ID}}`
+- default scopes: `{{SERVICE_ID}}:read`, `{{SERVICE_ID}}:write`
+
+Production runtime has `AUTH_ENABLED=true` and verifies JWT bearer tokens from
+the Better Auth JWKS endpoint on `/v1/*` and ConnectRPC service paths. Local
+development defaults to `AUTH_ENABLED=false` in `.env.local`.
+
+Use `service auth` for follow-up auth operations:
+
+```bash
+{{COMMAND_BOOTSTRAP}} # includes resource-server registration
+{{COMMAND_AUTH_RESOURCE}}
+{{COMMAND_AUTH_CLIENT}} --resource-server <target-service> --scope <scope>
+```
+
+`authctl clients create` prints a one-time client secret plus the recommended
+Vault command. By convention, generated services store outgoing service-client
+credentials under:
+
+```text
+prod/apps/{{SERVICE_ID}}/server/oauth-clients/<resource_server_id>
+```
+
+When requesting a client-credentials token for a generated service, include the
+target resource server as `resource=api://<resource_server_id>`. The generated
+runtime expects a JWT with that audience; omitting `resource` can return an
+opaque access token that the service will reject.
+
+Webhook signature hooks are provider-specific and optional in v1. Add provider
+secrets only when you add a provider adapter. A generic adapter can honor:
+
+- `WEBHOOK_<PROVIDER>_SECRET`
+
+## One-command production create
+
+The one-command production create path is designed for a fresh standalone service.
+
+When generated through `create-service`, the intended flow is:
+
+```bash
+bun create service {{SERVICE_NAME}} --yes
+```
+
+That command scaffolds this package, runs `service create`, deploys the production
+Cloud Run service through `service deploy`, and fails loudly with resumable
+instructions if a required cloud credential is missing. The generated package can also be run
+manually:
+
+```bash
+{{COMMAND_BOOTSTRAP}}
+{{COMMAND_DEPLOY}}
+```
+
+Create reads Neon credentials from environment variables or from Vault when
+`VAULT_ADDR` and a Vault token are available. Runtime database credentials are
+delivered to Cloud Run through app-project Secret Manager.
+
+## Production API
+
+The main environment is intended to be public at:
+
+```bash
+https://{{API_HOSTNAME}}
+```
+
+Preview and personal environments keep using deterministic Cloud Run hostnames in v1 so the generated backend stays easy to use inside standalone repos or monorepos.
+
+## Generated backend domain
+
+The generated microservice profile is a waitlist/launch service example. It is
+kept deliberately small so the integration plumbing is easy to remove or adapt:
+
+- public launch/waitlist submission
+- status lookup
+- trigger ingestion for scheduled, webhook, and manual follow-up work
+- provider webhook ingress where the selected template supports it
+
+The current Hono backend plumbing includes:
+
+- `waitlist_entries`
+- `waitlist_triggers`
+
+Hono variants expose:
+
+- `POST /v1/waitlist`
+- `GET /v1/waitlist?email=...`
+- `GET /v1/waitlist/{entryId}`
+- `POST /v1/triggers/waitlist`
+- `POST /webhooks/:provider`
 
-The generator only stores application-facing connection material in Secret Manager. Neon admin credentials stay local to bootstrap and deploy.
+ConnectRPC variants expose typed unary waitlist RPCs and will usually be the
+first place to adapt domain-specific contracts after scaffold.
+{{LOCAL_INTROSPECTION_NOTE}}

package/templates/shared/docker-compose.yml

@@ -0,0 +1,19 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: {{LOCAL_DATABASE_NAME}}
+      POSTGRES_USER: {{LOCAL_DATABASE_USER}}
+      POSTGRES_PASSWORD: {{LOCAL_DATABASE_PASSWORD}}
+    ports:
+      - "127.0.0.1:{{LOCAL_DATABASE_PORT}}:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U {{LOCAL_DATABASE_USER}} -d {{LOCAL_DATABASE_NAME}}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  postgres-data:

package/templates/shared/grafana/alerts.yaml

@@ -0,0 +1,54 @@
+apiVersion: 1
+groups:
+  - orgId: 1
+    name: "{{SERVICE_NAME}} baseline"
+    folder: "create-service"
+    interval: 1m
+    rules:
+      - uid: "{{SERVICE_ID}}-high-error-rate"
+        title: "{{SERVICE_NAME}} high error rate"
+        condition: C
+        data:
+          - refId: A
+            relativeTimeRange:
+              from: 600
+              to: 0
+            datasourceUid: "${datasource}"
+            model:
+              expr: "sum(rate(http_requests_total{service=\"{{SERVICE_NAME}}\",status=~\"5..\"}[5m]))"
+              intervalMs: 1000
+              maxDataPoints: 43200
+              refId: A
+          - refId: C
+            relativeTimeRange:
+              from: 600
+              to: 0
+            datasourceUid: __expr__
+            model:
+              conditions:
+                - evaluator:
+                    params: [0.05]
+                    type: gt
+                  operator:
+                    type: and
+                  query:
+                    params: [A]
+                  reducer:
+                    type: last
+                  type: query
+              datasource:
+                type: __expr__
+                uid: __expr__
+              expression: A
+              intervalMs: 1000
+              maxDataPoints: 43200
+              refId: C
+              type: threshold
+        noDataState: NoData
+        execErrState: Error
+        for: 5m
+        annotations:
+          summary: "{{SERVICE_NAME}} 5xx rate is elevated"
+        labels:
+          service_id: "{{SERVICE_ID}}"
+          target: "{{TARGET}}"

package/templates/shared/grafana/waitlist-dashboard.json

@@ -0,0 +1,63 @@
+{
+  "uid": "{{SERVICE_ID}}-waitlist",
+  "title": "{{SERVICE_NAME}} Waitlist Service",
+  "tags": ["create-service", "{{TARGET}}", "{{RUNTIME}}", "{{FRAMEWORK}}"],
+  "timezone": "browser",
+  "schemaVersion": 39,
+  "version": 1,
+  "refresh": "30s",
+  "panels": [
+    {
+      "id": 1,
+      "type": "timeseries",
+      "title": "Request rate",
+      "datasource": { "type": "prometheus", "uid": "${datasource}" },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum(rate(http_requests_total{service=\"{{SERVICE_NAME}}\"}[5m]))"
+        }
+      ],
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 }
+    },
+    {
+      "id": 2,
+      "type": "timeseries",
+      "title": "Error rate",
+      "datasource": { "type": "prometheus", "uid": "${datasource}" },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum(rate(http_requests_total{service=\"{{SERVICE_NAME}}\",status=~\"5..\"}[5m]))"
+        }
+      ],
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 }
+    },
+    {
+      "id": 3,
+      "type": "timeseries",
+      "title": "p95 latency",
+      "datasource": { "type": "prometheus", "uid": "${datasource}" },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket{service=\"{{SERVICE_NAME}}\"}[5m])) by (le))"
+        }
+      ],
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 8 }
+    },
+    {
+      "id": 4,
+      "type": "stat",
+      "title": "Queued triggers",
+      "datasource": { "type": "prometheus", "uid": "${datasource}" },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum(waitlist_triggers_queued{service=\"{{SERVICE_NAME}}\"})"
+        }
+      ],
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 8 }
+    }
+  ]
+}

package/templates/shared/scripts/authctl.ts

@@ -0,0 +1,231 @@
+import serviceConfig from "../service.config";
+import { existsSync } from "node:fs";
+
+type CommandResult = {
+  success: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+
+const decoder = new TextDecoder();
+
+export type AuthDoctorResult = {
+  hasAuthctl: boolean;
+  hasResourceServerCommands: boolean;
+  detail: string;
+  resourceServerCommand?: ResourceServerCommand;
+};
+
+type ResourceServerCommand = {
+  subject: string;
+  mutationAction?: "upsert" | "create";
+  actions: string[];
+};
+
+type ResourceServerMutationCommand = ResourceServerCommand & {
+  mutationAction: "upsert" | "create";
+};
+
+export function defaultAuthResourceServerArgs() {
+  const auth = serviceConfig.auth;
+  return [
+    "--resource-server",
+    auth.resource_server.id,
+    "--audience",
+    auth.resource_server.audience,
+    "--stage",
+    serviceConfig.stage_default,
+    ...auth.resource_server.default_scopes.flatMap((scope) => ["--scope", scope]),
+  ];
+}
+
+export function runAuthCommand(args: string[]) {
+  const [subject, action, ...rest] = args;
+
+  if (!subject || subject === "doctor") {
+    const result = runAuthDoctor();
+    if (!result.hasAuthctl) {
+      throw new Error(result.detail);
+    }
+    return result.detail;
+  }
+
+  if (subject === "resource-server" || subject === "resource-servers") {
+    const command = resolveResourceServerCommand();
+    if (!command) {
+      throw new Error(
+        "authctl is installed but does not expose resource-server commands; install @anmho/authctl@0.1.1 or newer before managing auth resource servers"
+      );
+    }
+    if (action === "get" || action === "list") {
+      if (!command.actions.includes(action)) {
+        throw new Error(`authctl ${command.subject} does not expose ${action}`);
+      }
+      authctl([command.subject, action, ...rest]);
+      return `Auth resource server ${action} finished`;
+    }
+    const mutation = ensureResourceServerCommandAvailable();
+    const subcommand = action ?? mutation.mutationAction;
+    if (!mutation.mutationAction || (subcommand !== mutation.mutationAction && !(subcommand === "upsert" && mutation.mutationAction === "create"))) {
+      throw new Error(`Usage: service auth resource-server [${mutation.mutationAction}] [authctl args]`);
+    }
+    authctl([mutation.subject, mutation.mutationAction, ...defaultAuthResourceServerArgs(), "--json", ...rest]);
+    return `Auth resource server ready: ${serviceConfig.auth.resource_server.id}`;
+  }
+
+  if (subject === "client" || subject === "clients") {
+    return runClientCommand(action, rest);
+  }
+
+  throw new Error("Usage: service auth <doctor|resource-server|client> [args]");
+}
+
+export function ensureAuthResourceServer() {
+  const command = ensureResourceServerCommandAvailable();
+  authctl([command.subject, command.mutationAction, ...defaultAuthResourceServerArgs(), "--json"]);
+  return `Auth resource server ready: ${serviceConfig.auth.resource_server.audience}`;
+}
+
+export function runAuthDoctor(): AuthDoctorResult {
+  if (!authctlPath()) {
+    return {
+      hasAuthctl: false,
+      hasResourceServerCommands: false,
+      detail: "authctl is not installed; run bun install in this generated service or link @anmho/authctl before service create",
+    };
+  }
+
+  const doctor = authctl(["doctor", "--json"], { allowFailure: true, quiet: true });
+  const resourceServerCommand = resolveResourceServerCommand();
+  const hasResourceServerCommands = Boolean(resourceServerCommand?.mutationAction);
+
+  if (!doctor.success) {
+    return {
+      hasAuthctl: true,
+      hasResourceServerCommands,
+      resourceServerCommand,
+      detail: `authctl doctor failed: ${doctor.stderr || doctor.stdout}`,
+    };
+  }
+
+  if (!hasResourceServerCommands) {
+    return {
+      hasAuthctl: true,
+      hasResourceServerCommands: false,
+      resourceServerCommand,
+      detail:
+        "authctl is installed but does not expose resource-server upsert/create; install @anmho/authctl@0.1.1 or newer before service create",
+    };
+  }
+
+  return {
+    hasAuthctl: true,
+    hasResourceServerCommands: true,
+    resourceServerCommand,
+    detail: `authctl ready for ${serviceConfig.auth.resource_server.id}`,
+  };
+}
+
+function runClientCommand(action = "", rest: string[]) {
+  if (action === "create") {
+    authctl([
+      "clients",
+      "create",
+      "--client-app",
+      serviceConfig.auth.client.app_id,
+      "--client-identity",
+      serviceConfig.auth.client.identity,
+      ...defaultClientTargetArgs(rest),
+      "--stage",
+      serviceConfig.stage_default,
+      "--yes",
+      "--json",
+      ...rest,
+    ]);
+    return "Auth client created";
+  }
+
+  if (["list", "get", "rotate", "revoke"].includes(action)) {
+    authctl(["clients", action, ...rest]);
+    return `Auth client ${action} finished`;
+  }
+
+  throw new Error("Usage: service auth client <create|list|get|rotate|revoke> [args]");
+}
+
+function defaultClientTargetArgs(rest: string[]) {
+  const hasResourceServer = hasFlag(rest, "--resource-server");
+  const hasScope = hasFlag(rest, "--scope");
+  return [
+    ...(hasResourceServer ? [] : ["--resource-server", serviceConfig.auth.resource_server.id]),
+    ...(hasScope ? [] : serviceConfig.auth.resource_server.default_scopes.flatMap((scope) => ["--scope", scope])),
+  ];
+}
+
+function hasFlag(args: string[], name: string) {
+  return args.some((arg) => arg === name || arg.startsWith(`${name}=`));
+}
+
+function ensureResourceServerCommandAvailable(): ResourceServerMutationCommand {
+  const doctor = runAuthDoctor();
+  if (!doctor.hasAuthctl || !doctor.hasResourceServerCommands) {
+    throw new Error(doctor.detail);
+  }
+  if (!doctor.resourceServerCommand?.mutationAction) {
+    throw new Error("authctl resource-server command discovery failed");
+  }
+  return doctor.resourceServerCommand as ResourceServerMutationCommand;
+}
+
+function resolveResourceServerCommand(): ResourceServerCommand | undefined {
+  for (const subject of ["resource-servers", "resource-server", "resources"]) {
+    const help = authctl([subject, "--help"], { allowFailure: true, quiet: true });
+    const output = `${help.stdout}\n${help.stderr}`;
+    if (!help.success || !output.includes(subject)) {
+      continue;
+    }
+    const actions = ["upsert", "create", "get", "list"].filter((candidate) => output.includes(candidate));
+    const mutationAction = actions.includes("upsert") ? "upsert" : actions.includes("create") ? "create" : undefined;
+    if (actions.length > 0) {
+      return { subject, mutationAction, actions };
+    }
+  }
+  return undefined;
+}
+
+function authctl(args: string[], options: { allowFailure?: boolean; quiet?: boolean } = {}): CommandResult {
+  const command = authctlPath();
+  if (!command) {
+    throw new Error("authctl is not installed; run bun install in this generated service or link @anmho/authctl");
+  }
+
+  const result = Bun.spawnSync([command, ...args], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdin: "inherit",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const output = {
+    success: result.success,
+    stdout: result.stdout ? decoder.decode(result.stdout).trim() : "",
+    stderr: result.stderr ? decoder.decode(result.stderr).trim() : "",
+    exitCode: result.exitCode,
+  };
+
+  if (!output.success && !options.allowFailure) {
+    throw new Error(`authctl ${args.join(" ")} failed with exit code ${output.exitCode}\n${output.stderr || output.stdout}`);
+  }
+
+  if (output.stdout && !options.quiet) {
+    console.log(output.stdout);
+  }
+
+  return output;
+}
+
+function authctlPath() {
+  return existsSync("./node_modules/.bin/authctl") ? "./node_modules/.bin/authctl" : Bun.which("authctl");
+}