create-svc 0.1.9 → 0.1.10

package/src/neon.ts

@@ -21,25 +21,27 @@ export function createNeonApi(apiKey = process.env.NEON_API_KEY): NeonApi {
     async listProjects() {
       const client = createApiClient({ apiKey: (apiKey?.trim() || (await resolveNeonApiKey())) });
       const payload = await client.listProjects({ limit: 100 });
-      return (payload.projects ?? [])
-        .map((project) => ({
+      const projects = ((payload.data as { projects?: Array<{ id?: string; name?: string }> } | undefined)?.projects ?? []);
+      return projects
+        .map((project: { id?: string; name?: string }) => ({
           id: project.id ?? "",
           name: project.name ?? project.id ?? "",
         }))
-        .filter((project) => project.id)
-        .sort((left, right) => left.name.localeCompare(right.name));
+        .filter((project: NeonProject) => Boolean(project.id))
+        .sort((left: NeonProject, right: NeonProject) => left.name.localeCompare(right.name));
     },
 
     async listBranches(projectId: string) {
       const client = createApiClient({ apiKey: (apiKey?.trim() || (await resolveNeonApiKey())) });
       const payload = await client.listProjectBranches({ projectId });
-      return (payload.branches ?? [])
-        .map((branch) => ({
+      const branches = ((payload.data as { branches?: Array<{ id?: string; name?: string }> } | undefined)?.branches ?? []);
+      return branches
+        .map((branch: { id?: string; name?: string }) => ({
           id: branch.id ?? "",
           name: branch.name ?? branch.id ?? "",
         }))
-        .filter((branch) => branch.id)
-        .sort((left, right) => left.name.localeCompare(right.name));
+        .filter((branch: NeonBranch) => Boolean(branch.id))
+        .sort((left: NeonBranch, right: NeonBranch) => left.name.localeCompare(right.name));
     },
   };
 }

package/src/post-scaffold.ts

@@ -13,39 +13,18 @@ type CommandResult = {
 };
 
 const decoder = new TextDecoder();
+const encoder = new TextEncoder();
 
 export async function runPostScaffoldFlow(config: ScaffoldConfig, cwd: string) {
-  if (config.createGithubRepo) {
-    initializeRepository(cwd);
-    createGitHubRepo(config, cwd);
-  }
-
   if (config.autoDeploy) {
     installProjectDependencies(cwd);
-    run("bun", ["run", "bootstrap"], { cwd });
-    run("bun", ["run", "deploy"], { cwd });
-    return { message: "Repository initialized, pushed, and first deploy started" };
-  }
-
-  return { message: "Repository initialized" };
-}
-
-function initializeRepository(cwd: string) {
-  requireCommand("git");
-  run("git", ["init", "-b", "main"], { cwd, allowFailure: true });
-  run("git", ["add", "."], { cwd });
-  run("git", ["commit", "--allow-empty", "-m", "Initial commit"], { cwd, allowFailure: true });
-}
-
-function createGitHubRepo(config: ScaffoldConfig, cwd: string) {
-  requireCommand("gh");
-
-  const existing = run("gh", ["repo", "view", config.githubRepo], { cwd, allowFailure: true });
-  if (!existing.success) {
-    run("gh", ["repo", "create", config.githubRepo, `--${config.githubVisibility}`, "--source=.", "--remote=origin"], { cwd });
+    const command = config.runtime === "bun" ? "bun" : "make";
+    run(command, config.runtime === "bun" ? ["run", "bootstrap"] : ["bootstrap"], { cwd });
+    run(command, config.runtime === "bun" ? ["run", "deploy"] : ["deploy"], { cwd });
+    return { message: "Dependencies installed and first deploy started" };
   }
 
-  run("git", ["push", "-u", "origin", "main"], { cwd, allowFailure: true });
+  return { message: "Backend package generated" };
 }
 
 function installProjectDependencies(cwd: string) {
@@ -63,7 +42,7 @@ function run(command: string, args: string[], options: CommandOptions): CommandR
   const result = Bun.spawnSync([command, ...args], {
     cwd: options.cwd,
     env: process.env,
-    stdin: options.input,
+    stdin: options.input === undefined ? undefined : encoder.encode(options.input),
     stdout: options.allowFailure ? "pipe" : "inherit",
     stderr: options.allowFailure ? "pipe" : "inherit",
   });

package/src/profiles.ts

@@ -0,0 +1,28 @@
+export const PROFILES = ["microservice"] as const;
+
+export type Profile = (typeof PROFILES)[number];
+
+export function parseProfile(value: string): Profile {
+  if (PROFILES.includes(value as Profile)) {
+    return value as Profile;
+  }
+
+  if (value === "app") {
+    throw new Error(
+      [
+        "The app profile moved out of create-svc.",
+        "Use the private GitHub template repos anmho/create-app-consumer or anmho/create-app-saas instead.",
+      ].join(" ")
+    );
+  }
+
+  throw new Error(`Unknown profile: ${value}`);
+}
+
+export function exampleForProfile(profile: Profile) {
+  return {
+    kind: "microservice",
+    domain: "waitlist",
+    label: "waitlist/launch service",
+  };
+}

package/src/scaffold.test.ts

@@ -2,30 +2,28 @@ import { expect, test } from "bun:test";
 import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { deriveLocalPostgresPort } from "./naming";
 import { DirectoryConflictError, assertTargetDirectoryIsEmpty, scaffoldProject, type ScaffoldConfig } from "./scaffold";
 
 function baseConfig(overrides: Partial<ScaffoldConfig> = {}): ScaffoldConfig {
   return {
     directory: "svc",
     serviceName: "dns-api",
-    runtime: "go",
-    framework: "chi",
+    modulePath: "example.com/dns-api",
+    runtime: "bun",
+    framework: "hono",
     region: "us-west1",
     gcpProjectMode: "create_new",
     gcpProject: "anmho-dns-api",
     gcpProjectName: "dns-api",
     billingAccount: "billingAccounts/01BD2E-3A6949-8F4C84",
     quotaProjectId: "anmho-infra-prod",
-    githubRepo: "anmho/dns-api",
-    githubVisibility: "public",
-    createGithubRepo: true,
-    autoDeploy: false,
-    neonProjectId: "project-123",
-    neonBaseBranchId: "br-main",
-    neonBaseBranchName: "main",
+    profile: "microservice",
     neonDatabaseName: "dns_api",
+    apiHostname: "api.dns-api.anmho.com",
     generatorRoot: join(import.meta.dir, ".."),
     ...overrides,
+    autoDeploy: overrides.autoDeploy ?? false,
   };
 }
 
@@ -40,6 +38,7 @@ test("scaffolds all runtime/framework variants with shared cloudrun config", asy
   for (const variant of cases) {
     const root = await mkdtemp(join(tmpdir(), "create-svc-"));
     const generatedRoot = join(root, `${variant.runtime}-${variant.framework}`);
+    const localPort = deriveLocalPostgresPort("dns-api");
 
     await scaffoldProject(
       baseConfig({
@@ -50,37 +49,149 @@ test("scaffolds all runtime/framework variants with shared cloudrun config", asy
     );
 
     const configScript = await Bun.file(join(generatedRoot, "scripts", "cloudrun", "config.ts")).text();
+    expect(configScript).toContain('profile: "microservice"');
+    expect(configScript).toContain('domain: "waitlist"');
+    expect(configScript).toContain('kind: "microservice"');
     expect(configScript).toContain(`runtime: "${variant.runtime}"`);
     expect(configScript).toContain(`framework: "${variant.framework}"`);
     expect(configScript).toContain('mode: "create_new"');
     expect(configScript).toContain('quotaProjectId: "anmho-infra-prod"');
-    expect(configScript).toContain('projectId: "project-123"');
+    expect(configScript).toContain('projectId: ""');
+    expect(configScript).toContain('baseBranchId: ""');
+    expect(configScript).toContain('baseBranchName: "main"');
     expect(configScript).toContain('previewBranchPrefix: "dns-api-pr"');
+    expect(configScript).toContain('hostname: "api.dns-api.anmho.com"');
+    expect(configScript).toContain('attachmentBucket: "anmho-dns-api-dns-api-attachments"');
+    expect(configScript).toContain('attachmentPublicBaseUrl: "https://storage.googleapis.com/anmho-dns-api-dns-api-attachments"');
+    expect(configScript).not.toContain("github:");
 
     const deployScript = await Bun.file(join(generatedRoot, "scripts", "cloudrun", "lib.ts")).text();
     expect(deployScript).toContain('--billing-project", config.project.quotaProjectId');
+    expect(deployScript).toContain("serviceDomain");
+    expect(deployScript).toContain("ensureProductionDomainMapping");
+    expect(deployScript).toContain("ensureStorageBucket");
 
-    const workflow = await Bun.file(join(generatedRoot, ".github", "workflows", "personal.yml")).text();
-    expect(workflow).toContain("workflow_dispatch");
-    expect(workflow).toContain("--environment personal");
+    const bootstrapScript = await Bun.file(join(generatedRoot, "scripts", "cloudrun", "bootstrap.ts")).text();
+    expect(bootstrapScript).toContain("publishProviderRuntimeSecrets");
+
+    const manifest = await Bun.file(join(generatedRoot, "service.yaml")).text();
+    expect(manifest).toContain("CLERK_SECRET_KEY");
+    expect(manifest).toContain("STRIPE_SECRET_KEY");
+    expect(manifest).toContain("REVENUECAT_API_KEY");
+    expect(manifest).toContain("RESEND_API_KEY");
+    expect(manifest).toContain("POSTHOG_API_KEY");
+
+    const gitignore = await Bun.file(join(generatedRoot, ".gitignore")).text();
+    expect(gitignore).toContain("node_modules");
+    expect(await Bun.file(join(generatedRoot, "website", "package.json")).exists()).toBeFalse();
+
+    const dockerCompose = await Bun.file(join(generatedRoot, "docker-compose.yml")).text();
+    expect(dockerCompose).toContain('image: postgres:16-alpine');
+    expect(dockerCompose).toContain(`127.0.0.1:${localPort}:5432`);
+
+    const envExample = await Bun.file(join(generatedRoot, ".env.example")).text();
+    expect(envExample).toContain(`DATABASE_URL=postgres://postgres:postgres@127.0.0.1:${localPort}/dns_api`);
+    expect(envExample).toContain("ATTACHMENT_BUCKET=dns-api-local-attachments");
+    expect(envExample).toContain("CLERK_SECRET_KEY=");
+    expect(envExample).toContain("STRIPE_SECRET_KEY=");
+    expect(envExample).toContain("REVENUECAT_API_KEY=");
+    expect(envExample).toContain("RESEND_API_KEY=");
+    expect(envExample).toContain("POSTHOG_API_KEY=");
+
+    const localEnv = await Bun.file(join(generatedRoot, ".env.local")).text();
+    expect(localEnv).toContain(`DATABASE_URL=postgres://postgres:postgres@127.0.0.1:${localPort}/dns_api`);
+    expect(localEnv).toContain("ATTACHMENT_PUBLIC_BASE_URL=https://storage.local.invalid/dns-api-local-attachments");
+
+    expect(await Bun.file(join(generatedRoot, ".github", "workflows", "personal.yml")).exists()).toBeFalse();
 
     if (variant.runtime === "go") {
       const goMod = await Bun.file(join(generatedRoot, "go.mod")).text();
       expect(goMod).toContain("connectrpc.com/connect");
+      expect(goMod).toContain("module example.com/dns-api");
+      expect(goMod).not.toContain("module github.com/anmho/dns-api");
 
       const mainGo = await Bun.file(join(generatedRoot, "cmd", "server", "main.go")).text();
-      expect(mainGo).toContain("NewDNSService");
+      expect(mainGo).toContain("NewChatService");
+      expect(mainGo).toContain("example.com/dns-api");
     } else {
       const packageJson = await Bun.file(join(generatedRoot, "package.json")).text();
       expect(packageJson).toContain('"svc-cloudrun": "./scripts/cloudrun/cli.ts"');
+      expect(packageJson).toContain('"dev": "bun run ./src/index.ts"');
+      expect(packageJson).toContain('"gen": "bun run ./scripts/codegen.ts"');
+      expect(packageJson).toContain('"bootstrap": "bun run ./scripts/cloudrun/cli.ts bootstrap"');
+      expect(packageJson).toContain('"deploy": "bun run ./scripts/cloudrun/cli.ts deploy"');
+      expect(packageJson).toContain('"cleanup": "bun run ./scripts/cloudrun/cli.ts cleanup"');
 
       const makefile = await Bun.file(join(generatedRoot, "Makefile")).text();
       expect(makefile).toContain("npx --no-install svc-cloudrun");
 
       const entrypoint = await Bun.file(join(generatedRoot, "src", "index.ts")).text();
-      expect(entrypoint).toContain(variant.framework === "hono" ? "Hono" : "rpc.example.v1.Service/Ping");
+      const readme = await Bun.file(join(generatedRoot, "README.md")).text();
+      if (variant.framework === "connectrpc") {
+        expect(entrypoint).toContain("ChatService");
+        expect(gitignore).toContain("gen/");
+        expect(readme).toContain("Local introspection");
+      } else {
+        expect(entrypoint).toContain("/v1/conversations");
+        expect(gitignore).not.toContain("gen/");
+        expect(readme).not.toContain("Local introspection");
+      }
+      expect(entrypoint).toContain(variant.framework === "hono" ? "Hono" : "connectNodeAdapter");
+      expect(readme).toContain("ATTACHMENT_BUCKET");
+      expect(readme).toContain("/webhooks/:provider");
+      expect(readme).toContain("microservice profile");
+      expect(readme).toContain("waitlist/launch service");
+      expect(readme).toContain("Terraform is optional");
     }
   }
+}, 30000);
+
+test("scaffolds a backend package cleanly into a nested monorepo-style directory", async () => {
+  const root = await mkdtemp(join(tmpdir(), "create-svc-monorepo-"));
+  const generatedRoot = join(root, "apps", "dns-api");
+
+  await scaffoldProject(
+    baseConfig({
+      directory: generatedRoot,
+      runtime: "bun",
+      framework: "hono",
+    })
+  );
+
+  const readme = await Bun.file(join(generatedRoot, "README.md")).text();
+  expect(readme).toContain("`microservice` profile");
+  expect(readme).toContain("api.dns-api.anmho.com");
+  expect(readme).toContain("docker compose up -d");
+  expect(readme).toContain("local Postgres service in `docker-compose.yml`");
+  expect(readme).toContain("gcloud auth login");
+  expect(readme).toContain("known-good CLIs");
+  expect(readme).toContain("bun run bootstrap");
+  expect(readme).toContain("bun run deploy");
+  expect(readme).toContain("ATTACHMENT_BUCKET");
+  expect(readme).toContain("one-command production bootstrap");
+  expect(readme).toContain("waitlist/launch service");
+  expect(readme).toContain("Terraform is optional");
+  expect(readme).toContain("webhook_events");
+  expect(readme).not.toContain("Neon main, preview, and personal branch provisioning");
+  expect(readme).not.toContain("GitHub Actions");
+  expect(readme).not.toContain("repository");
+
+  const packageJson = await Bun.file(join(generatedRoot, "package.json")).text();
+  expect(packageJson).toContain('"hono"');
+
+  const entrypoint = await Bun.file(join(generatedRoot, "src", "index.ts")).text();
+  expect(entrypoint).toContain("/v1/attachments/uploads");
+
+  expect(await Bun.file(join(generatedRoot, ".github", "workflows", "ci.yml")).exists()).toBeFalse();
+}, 15000);
+
+test("microservice profile does not generate a website package", async () => {
+  const root = await mkdtemp(join(tmpdir(), "create-svc-microservice-profile-"));
+  const generatedRoot = join(root, "service");
+
+  await scaffoldProject(baseConfig({ directory: generatedRoot, profile: "microservice" }));
+
+  expect(await Bun.file(join(generatedRoot, "website", "package.json")).exists()).toBeFalse();
 });
 
 test("detects conflicting files before scaffold generation", async () => {

package/src/scaffold.ts

@@ -2,30 +2,30 @@ import { mkdir, readdir } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import {
   compactIdentifier,
+  compactDatabaseName,
+  deriveLocalPostgresPort,
   type Framework,
   type GcpProjectMode,
   type Runtime,
 } from "./naming";
+import { exampleForProfile, type Profile } from "./profiles";
 
 export type ScaffoldConfig = {
   directory: string;
   serviceName: string;
+  modulePath: string;
   runtime: Runtime;
   framework: Framework;
+  profile: Profile;
   region: string;
   gcpProjectMode: GcpProjectMode;
   gcpProject: string;
   gcpProjectName: string;
   billingAccount: string;
   quotaProjectId: string;
-  githubRepo: string;
-  githubVisibility: "public" | "private";
-  createGithubRepo: boolean;
   autoDeploy: boolean;
-  neonProjectId: string;
-  neonBaseBranchId: string;
-  neonBaseBranchName: string;
   neonDatabaseName: string;
+  apiHostname: string;
   generatorRoot: string;
 };
 
@@ -48,8 +48,9 @@ export async function scaffoldProject(config: ScaffoldConfig) {
   const replacements = buildReplacements(config);
   const sharedTemplateRoot = resolve(config.generatorRoot, "templates", "shared");
   const variantTemplateRoot = resolve(config.generatorRoot, "templates", "variants", `${config.runtime}-${config.framework}`);
+  const templateRoots = [sharedTemplateRoot, variantTemplateRoot];
 
-  for (const templateRoot of [sharedTemplateRoot, variantTemplateRoot]) {
+  for (const templateRoot of templateRoots) {
     const files = await collectTemplateFiles(templateRoot);
 
     for (const relativePath of files) {
@@ -62,6 +63,8 @@ export async function scaffoldProject(config: ScaffoldConfig) {
       await Bun.write(destinationPath, rendered);
     }
   }
+
+  await writeLocalEnvFile(targetDir, replacements);
 }
 
 async function ensureTargetDirectory(targetDir: string) {
@@ -91,9 +94,15 @@ async function collectTemplateFiles(root: string, relative = ""): Promise<string
   for (const entry of entries) {
     const nextRelative = relative ? join(relative, entry.name) : entry.name;
     if (entry.isDirectory()) {
+      if (nextRelative === ".github" || nextRelative.startsWith(".github/")) {
+        continue;
+      }
       files.push(...(await collectTemplateFiles(root, nextRelative)));
       continue;
     }
+    if (nextRelative === ".github" || nextRelative.startsWith(".github/")) {
+      continue;
+    }
     files.push(nextRelative);
   }
 
@@ -101,19 +110,21 @@ async function collectTemplateFiles(root: string, relative = ""): Promise<string
 }
 
 function buildReplacements(config: ScaffoldConfig) {
-  const [githubOwner = "anmho"] = config.githubRepo.split("/");
-  const modulePath = `github.com/${config.githubRepo}`;
+  const example = exampleForProfile(config.profile);
   const serviceAccountBase = compactIdentifier(config.serviceName, 21);
   const runtimeServiceAccount = `${serviceAccountBase}-runtime@${config.gcpProject}.iam.gserviceaccount.com`;
-  const deployerServiceAccount = `${serviceAccountBase}-deployer@${config.gcpProject}.iam.gserviceaccount.com`;
-  const wifPoolId = "github";
-  const wifProviderId = compactIdentifier(config.serviceName, 32);
   const previewBranchPrefix = `${config.serviceName}-pr`;
   const personalBranchPrefix = `${config.serviceName}-dev`;
+  const remoteAttachmentBucket = `${config.gcpProject}-${config.serviceName}-attachments`;
+  const remoteAttachmentPublicBaseUrl = `https://storage.googleapis.com/${remoteAttachmentBucket}`;
+  const localDatabaseName = compactDatabaseName(config.serviceName);
+  const localDatabasePort = deriveLocalPostgresPort(config.serviceName);
+  const localAttachmentBucket = `${config.serviceName}-local-attachments`;
+  const localAttachmentPublicBaseUrl = `https://storage.local.invalid/${localAttachmentBucket}`;
 
   return {
     SERVICE_NAME: config.serviceName,
-    MODULE_PATH: modulePath,
+    MODULE_PATH: config.modulePath,
     PROJECT_ID: config.gcpProject,
     PROJECT_NAME: config.gcpProjectName,
     REGION: config.region,
@@ -121,28 +132,88 @@ function buildReplacements(config: ScaffoldConfig) {
     PROJECT_CREATE_IF_MISSING: String(config.gcpProjectMode === "create_new"),
     BILLING_ACCOUNT: config.billingAccount,
     QUOTA_PROJECT_ID: config.quotaProjectId,
-    GITHUB_REPO: config.githubRepo,
-    GITHUB_OWNER: githubOwner,
-    GITHUB_VISIBILITY: config.githubVisibility,
-    GITHUB_CREATE_IF_MISSING: String(config.createGithubRepo),
     AUTO_DEPLOY: String(config.autoDeploy),
     RUNTIME: config.runtime,
     FRAMEWORK: config.framework,
+    PROFILE: config.profile,
+    EXAMPLE_KIND: example.kind,
+    EXAMPLE_DOMAIN: example.domain,
+    EXAMPLE_LABEL: example.label,
     CLOUD_RUN_SERVICE: config.serviceName,
-    NEON_PROJECT_ID: config.neonProjectId,
-    NEON_BASE_BRANCH_ID: config.neonBaseBranchId,
-    NEON_BASE_BRANCH_NAME: config.neonBaseBranchName,
+    NEON_PROJECT_ID: "",
+    NEON_BASE_BRANCH_ID: "",
+    NEON_BASE_BRANCH_NAME: "main",
     NEON_DATABASE_NAME: config.neonDatabaseName,
     NEON_ROLE_NAME: "neondb_owner",
     NEON_PREVIEW_BRANCH_PREFIX: previewBranchPrefix,
     NEON_PERSONAL_BRANCH_PREFIX: personalBranchPrefix,
     RUNTIME_SERVICE_ACCOUNT: runtimeServiceAccount,
-    DEPLOYER_SERVICE_ACCOUNT: deployerServiceAccount,
-    WIF_POOL_ID: wifPoolId,
-    WIF_PROVIDER_ID: wifProviderId,
+    API_HOSTNAME: config.apiHostname,
+    API_BASE_DOMAIN: "anmho.com",
+    ATTACHMENT_BUCKET: remoteAttachmentBucket,
+    ATTACHMENT_PUBLIC_BASE_URL: remoteAttachmentPublicBaseUrl,
+    LOCAL_DATABASE_NAME: localDatabaseName,
+    LOCAL_DATABASE_PORT: localDatabasePort,
+    LOCAL_DATABASE_USER: "postgres",
+    LOCAL_DATABASE_PASSWORD: "postgres",
+    LOCAL_ATTACHMENT_BUCKET: localAttachmentBucket,
+    LOCAL_ATTACHMENT_PUBLIC_BASE_URL: localAttachmentPublicBaseUrl,
+    COMMAND_DEV: config.runtime === "bun" ? "bun run dev" : "make dev",
+    COMMAND_MIGRATE: config.runtime === "bun" ? "bun run migrate" : "make migrate",
+    COMMAND_GEN: config.runtime === "bun" ? "bun run gen" : "make gen",
+    COMMAND_LINT: config.runtime === "bun" ? "bun run lint" : "make lint",
+    COMMAND_TEST: config.runtime === "bun" ? "bun run test" : "make test",
+    COMMAND_BOOTSTRAP: config.runtime === "bun" ? "bun run bootstrap" : "make bootstrap",
+    COMMAND_DEPLOY: config.runtime === "bun" ? "bun run deploy" : "make deploy",
+    COMMAND_DEPLOY_PERSONAL:
+      config.runtime === "bun"
+        ? 'bun run deploy -- --environment personal --name <slug>'
+        : 'make deploy ARGS="--environment personal --name <slug>"',
+    COMMAND_DEPLOY_DESTROY:
+      config.runtime === "bun"
+        ? 'bun run deploy -- --destroy --environment personal --name <slug>'
+        : 'make deploy ARGS="--destroy --environment personal --name <slug>"',
+    COMMAND_CLEANUP: config.runtime === "bun" ? "bun run cleanup" : "make cleanup",
+    COMMAND_CLEANUP_PROJECT: config.runtime === "bun" ? "bun run cleanup -- --project" : 'make cleanup ARGS="--project"',
+    GITIGNORE_EXTRA: config.framework === "connectrpc" ? "gen/" : "",
+    LOCAL_INTROSPECTION_NOTE:
+      config.framework === "connectrpc"
+        ? [
+            "",
+            "## Local introspection",
+            "",
+            "When running locally, ConnectRPC variants expose introspection by default.",
+            "",
+            "- `go + connectrpc`: standard gRPC reflection for tools like `grpcurl list localhost:<port>`",
+            "- `bun + connectrpc`: JSON introspection at `/debug/connectrpc`",
+            "- override with `ENABLE_RPC_INTROSPECTION=true|false`",
+          ].join("\n")
+        : "",
   };
 }
 
+async function writeLocalEnvFile(targetDir: string, replacements: Record<string, string>) {
+  const envPath = join(targetDir, ".env.local");
+  if (await Bun.file(envPath).exists()) {
+    return;
+  }
+
+  const rendered = renderTemplate(
+    [
+      "# Generated local development defaults for create-svc.",
+      "# This file is user-owned after scaffold and is gitignored.",
+      "",
+      "DATABASE_URL=postgres://{{LOCAL_DATABASE_USER}}:{{LOCAL_DATABASE_PASSWORD}}@127.0.0.1:{{LOCAL_DATABASE_PORT}}/{{LOCAL_DATABASE_NAME}}",
+      "ATTACHMENT_BUCKET={{LOCAL_ATTACHMENT_BUCKET}}",
+      "ATTACHMENT_PUBLIC_BASE_URL={{LOCAL_ATTACHMENT_PUBLIC_BASE_URL}}",
+      "",
+    ].join("\n"),
+    replacements
+  );
+
+  await Bun.write(envPath, rendered);
+}
+
 function renderTemplate(input: string, replacements: Record<string, string>) {
   return input.replace(/\{\{([A-Z0-9_]+)\}\}/g, (_, key: string) => {
     const replacement = replacements[key];

package/src/vault.test.ts

@@ -14,17 +14,41 @@ test("resolveNeonApiKey prefers NEON_API_KEY from env", async () => {
   await expect(resolveNeonApiKey()).resolves.toBe("direct-token");
 });
 
+test("resolveNeonApiKey reads the purpose-named Neon provider secret by default", async () => {
+  delete process.env.NEON_API_KEY;
+  process.env.VAULT_ADDR = "https://vault.example.com";
+  process.env.VAULT_TOKEN = "token-123";
+
+  const fetchMock = mock(async (input: string | URL | Request) => {
+    expect(String(input)).toBe("https://vault.example.com/v1/secret/data/prod/providers/neon");
+    return new Response(
+      JSON.stringify({
+        data: {
+          data: {
+            api_key: "vault-token",
+          },
+        },
+      }),
+      { status: 200 }
+    );
+  });
+
+  globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+  await expect(resolveNeonApiKey()).resolves.toBe("vault-token");
+});
+
 test("readVaultSecret reads KV v2 secret data using existing vault login env", async () => {
   process.env.VAULT_ADDR = "https://vault.example.com";
   process.env.VAULT_TOKEN = "token-123";
 
   const fetchMock = mock(async (input: string | URL | Request) => {
-    expect(String(input)).toBe("https://vault.example.com/v1/secret/data/provider/neon-api-key");
+    expect(String(input)).toBe("https://vault.example.com/v1/secret/data/prod/providers/neon");
     return new Response(
       JSON.stringify({
         data: {
           data: {
-            value: "vault-token",
+            api_key: "vault-token",
           },
         },
       }),
@@ -32,12 +56,12 @@ test("readVaultSecret reads KV v2 secret data using existing vault login env", a
     );
   });
 
-  globalThis.fetch = fetchMock as typeof fetch;
+  globalThis.fetch = fetchMock as unknown as typeof fetch;
 
   await expect(
     readVaultSecret({
-      path: "provider/neon-api-key",
-      field: "value",
+      path: "prod/providers/neon",
+      field: "api_key",
     })
   ).resolves.toBe("vault-token");
 });
@@ -56,7 +80,7 @@ test("readVaultSecret falls back to ~/.vault-token", async () => {
       JSON.stringify({
         data: {
           data: {
-            value: "vault-token",
+            api_key: "vault-token",
           },
         },
       }),
@@ -64,12 +88,12 @@ test("readVaultSecret falls back to ~/.vault-token", async () => {
     );
   });
 
-  globalThis.fetch = fetchMock as typeof fetch;
+  globalThis.fetch = fetchMock as unknown as typeof fetch;
 
   await expect(
     readVaultSecret({
-      path: "provider/neon-api-key",
-      field: "value",
+      path: "prod/providers/neon",
+      field: "api_key",
     })
   ).resolves.toBe("vault-token");
 });

package/src/vault.ts

@@ -2,8 +2,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 const DEFAULT_VAULT_SECRET_MOUNT = "secret";
-const DEFAULT_NEON_API_KEY_PATH = "provider/neon-api-key";
-const DEFAULT_NEON_API_KEY_FIELD = "value";
+const DEFAULT_NEON_API_KEY_PATH = "prod/providers/neon";
+const DEFAULT_NEON_API_KEY_FIELD = "api_key";
 
 type VaultSecretOptions = {
   addr?: string;
@@ -71,7 +71,8 @@ async function resolveVaultToken() {
     return direct;
   }
 
-  const tokenFile = process.env.VAULT_TOKEN_FILE?.trim() || join(homedir(), ".vault-token");
+  const home = process.env.HOME?.trim() || homedir();
+  const tokenFile = process.env.VAULT_TOKEN_FILE?.trim() || join(home, ".vault-token");
 
   try {
     const value = (await Bun.file(tokenFile).text()).trim();