create-svc 0.1.7 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-svc",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Bun-authored CLI to scaffold Go Cloud Run services with Chi, ConnectRPC, Vault, and Cloudflare examples.",
   "module": "index.ts",
   "type": "module",

package/src/cli.test.ts

@@ -1,5 +1,6 @@
 import { expect, test } from "bun:test";
-import { normalizeValidationResult } from "./cli";
+import { mkdir } from "node:fs/promises";
+import { assertDiscoveryReady, normalizeValidationResult, validateServiceNameInput } from "./cli";
 
 test("normalizeValidationResult converts success to undefined", () => {
   expect(normalizeValidationResult(true)).toBeUndefined();
@@ -8,3 +9,31 @@ test("normalizeValidationResult converts success to undefined", () => {
 test("normalizeValidationResult preserves validation errors", () => {
   expect(normalizeValidationResult("Service name is required")).toBe("Service name is required");
 });
+
+test("assertDiscoveryReady requires Neon discovery to succeed", () => {
+  expect(() =>
+    assertDiscoveryReady({
+      projects: [],
+      billingAccounts: [],
+      warnings: [],
+      neonError: "Vault secret resolution requires VAULT_ADDR, VAULT_TOKEN, and a secret path",
+    })
+  ).toThrow(
+    "Neon discovery is required before scaffolding. Set NEON_API_KEY, or use Vault by providing VAULT_ADDR and VAULT_TOKEN. Optional overrides: VAULT_SECRET_MOUNT, VAULT_NEON_API_KEY_PATH, VAULT_NEON_API_KEY_FIELD."
+  );
+});
+
+test("validateServiceNameInput rejects a taken target directory", async () => {
+  const cwd = process.cwd();
+  const root = "/tmp/create-svc-cli-validation";
+  await mkdir(root, { recursive: true });
+  await mkdir(`${root}/taken-app`, { recursive: true });
+  await Bun.write(`${root}/taken-app/keep.txt`, "x");
+
+  process.chdir(root);
+  try {
+    expect(validateServiceNameInput("taken-app")).toBe("Directory already exists and is not empty");
+  } finally {
+    process.chdir(cwd);
+  }
+});

package/src/cli.ts

@@ -5,13 +5,13 @@ import {
   intro,
   isCancel,
   log,
-  note,
   outro,
   select,
   spinner,
   text,
 } from "@clack/prompts";
 import pc from "picocolors";
+import { readdirSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runPostScaffoldFlow } from "./post-scaffold";
@@ -55,6 +55,7 @@ type DiscoveryState = {
   neonProjectId?: string;
   neonBaseBranchId?: string;
   neonBaseBranchName?: string;
+  neonError?: string;
   warnings: string[];
 };
 
@@ -255,18 +256,19 @@ function parseArgs(argv: string[]): ParsedArgs {
 
 export async function resolveConfig(args: ParsedArgs): Promise<ScaffoldConfig> {
   const inferredName = slugify(basename(args.directory ?? "my-service"));
-  const discoveryPromise = discoverCloudInputs();
   const serviceName = args.yes
     ? inferredName
-    : await promptText("Service name", inferredName, (value) => slugify(value).length > 0 || "Service name is required");
+    : await promptText("Service name", inferredName, (value) => validateServiceNameInput(value, args.directory));
   const directory = args.directory ?? serviceName;
   const targetDir = resolve(process.cwd(), directory);
   await assertTargetDirectoryIsEmpty(targetDir);
 
+  const discoveryPromise = discoverCloudInputs();
   const defaults = deriveDefaults(serviceName);
   const runtime = await resolveRuntime(args);
   const framework = await resolveFramework(args, runtime);
   const discovery = await discoveryPromise;
+  assertDiscoveryReady(discovery);
   const gcpSelection = await resolveGcpSelection(args, defaults, discovery);
   const githubRepo = args.githubRepo ?? defaults.githubRepo;
   const region = args.region ?? DEFAULT_REGION;
@@ -487,12 +489,20 @@ async function discoverCloudInputs(): Promise<DiscoveryState> {
     result.neonBaseBranchId = neonDefaults.baseBranchId;
     result.neonBaseBranchName = neonDefaults.baseBranchName;
   } catch (error) {
-    result.warnings.push(`Skipping Neon discovery: ${formatError(error)}`);
+    result.neonError = formatError(error);
   }
 
   return result;
 }
 
+export function assertDiscoveryReady(discovery: DiscoveryState) {
+  if (!discovery.neonError) {
+    return;
+  }
+
+  throw new Error(formatNeonDiscoveryRequirement(discovery.neonError));
+}
+
 function chooseBillingAccount(input: string | undefined, accounts: BillingAccount[]) {
   if (input) {
     return input;
@@ -536,11 +546,21 @@ function formatError(error: unknown) {
   return error instanceof Error ? error.message : String(error);
 }
 
+function formatNeonDiscoveryRequirement(reason: string) {
+  if (reason.includes("Vault secret resolution requires")) {
+    return [
+      "Neon discovery is required before scaffolding.",
+      "Set NEON_API_KEY, or use Vault by providing VAULT_ADDR and VAULT_TOKEN.",
+      "Optional overrides: VAULT_SECRET_MOUNT, VAULT_NEON_API_KEY_PATH, VAULT_NEON_API_KEY_FIELD.",
+    ].join(" ");
+  }
+
+  return `Neon discovery is required before scaffolding: ${reason}`;
+}
+
 function handleCliError(error: unknown) {
   if (error instanceof DirectoryConflictError) {
-    log.error(`The directory ${error.targetDir} contains files that could conflict.`);
-    note(formatConflictEntries(error.entries), "Conflicting files");
-    log.message("Either try using a new directory name, or remove the files listed above.");
+    log.error(`Target directory already exists and is not empty: ${error.targetDir}`);
     process.exit(1);
   }
 
@@ -548,15 +568,6 @@ function handleCliError(error: unknown) {
   process.exit(1);
 }
 
-function formatConflictEntries(entries: string[]) {
-  const visibleEntries = entries.slice(0, 12);
-  const lines = visibleEntries.map((entry) => `- ${entry}`);
-  if (entries.length > visibleEntries.length) {
-    lines.push(`- ...and ${entries.length - visibleEntries.length} more`);
-  }
-  return lines.join("\n");
-}
-
 async function promptForExistingProject(projects: GcpProject[]) {
   const value = await autocomplete({
     message: "Existing GCP project",
@@ -601,6 +612,29 @@ export function normalizeValidationResult(result: true | string): string | undef
   return result === true ? undefined : result;
 }
 
+export function validateServiceNameInput(rawValue: string, directoryOverride?: string) {
+  const serviceName = slugify(rawValue);
+  if (!serviceName) {
+    return "Service name is required";
+  }
+
+  const directory = directoryOverride ?? serviceName;
+  const targetDir = resolve(process.cwd(), directory);
+
+  try {
+    const entries = readdirSync(targetDir);
+    if (entries.length > 0) {
+      return "Directory already exists and is not empty";
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      return "Unable to check target directory";
+    }
+  }
+
+  return true;
+}
+
 function printHelp() {
   log.message(`
 Usage:

package/src/scaffold.test.ts

@@ -72,7 +72,10 @@ test("scaffolds all runtime/framework variants with shared cloudrun config", asy
       expect(mainGo).toContain("NewDNSService");
     } else {
       const packageJson = await Bun.file(join(generatedRoot, "package.json")).text();
-      expect(packageJson).toContain('"bootstrap": "bun run ./scripts/cloudrun/bootstrap.ts"');
+      expect(packageJson).toContain('"svc-cloudrun": "./scripts/cloudrun/cli.ts"');
+
+      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");

package/templates/shared/scripts/cloudrun/bootstrap.ts

@@ -14,6 +14,8 @@ import {
   gcloud,
   requireCommand,
   resolveDeploymentTarget,
+  runMain,
+  runStep,
   setGithubVariable,
   workloadIdentityPoolResource,
   workloadIdentityProviderResource,
@@ -23,54 +25,67 @@ export async function bootstrap() {
   requireCommand("gcloud");
   requireCommand("gh");
 
-  ensureProject();
-  attachBilling();
-  gcloud(["services", "enable", ...config.requiredApis, "--project", config.project.id]);
+  await runStep("Ensuring GCP project", () => ensureProject());
+  await runStep("Attaching billing", () => attachBilling());
+  await runStep("Enabling required GCP APIs", () => gcloud(["services", "enable", ...config.requiredApis, "--project", config.project.id]));
 
-  ensureServiceAccount(config.runtimeServiceAccount);
-  ensureServiceAccount(config.deployerServiceAccount);
-  ensureArtifactRepository();
+  await runStep("Ensuring runtime and deployer service accounts", () => {
+    ensureServiceAccount(config.runtimeServiceAccount);
+    ensureServiceAccount(config.deployerServiceAccount);
+  });
 
-  ensureProjectRole(`serviceAccount:${config.deployerServiceAccount}`, "roles/run.admin");
-  ensureProjectRole(`serviceAccount:${config.deployerServiceAccount}`, "roles/cloudbuild.builds.editor");
-  ensureProjectRole(`serviceAccount:${config.deployerServiceAccount}`, "roles/artifactregistry.writer");
-  ensureProjectRole(`serviceAccount:${config.deployerServiceAccount}`, "roles/serviceusage.serviceUsageConsumer");
-  ensureProjectRole(`serviceAccount:${config.runtimeServiceAccount}`, "roles/secretmanager.secretAccessor");
+  await runStep("Ensuring Artifact Registry repository", () => ensureArtifactRepository());
 
-  ensureServiceAccountRole(config.runtimeServiceAccount, `serviceAccount:${config.deployerServiceAccount}`, "roles/iam.serviceAccountUser");
+  await runStep("Granting project roles", () => {
+    ensureProjectRole(`serviceAccount:${config.deployerServiceAccount}`, "roles/run.admin");
+    ensureProjectRole(`serviceAccount:${config.deployerServiceAccount}`, "roles/cloudbuild.builds.editor");
+    ensureProjectRole(`serviceAccount:${config.deployerServiceAccount}`, "roles/artifactregistry.writer");
+    ensureProjectRole(`serviceAccount:${config.deployerServiceAccount}`, "roles/serviceusage.serviceUsageConsumer");
+    ensureProjectRole(`serviceAccount:${config.runtimeServiceAccount}`, "roles/secretmanager.secretAccessor");
+    ensureServiceAccountRole(config.runtimeServiceAccount, `serviceAccount:${config.deployerServiceAccount}`, "roles/iam.serviceAccountUser");
+  });
 
-  ensureWorkloadIdentityPool();
-  ensureWorkloadIdentityProvider();
-  ensureServiceAccountRole(
-    config.deployerServiceAccount,
-    `principalSet://iam.googleapis.com/${workloadIdentityPoolResource()}/attribute.repository/${config.github.repo}`,
-    "roles/iam.workloadIdentityUser"
-  );
+  await runStep("Ensuring Workload Identity setup", () => {
+    ensureWorkloadIdentityPool();
+    ensureWorkloadIdentityProvider();
+    ensureServiceAccountRole(
+      config.deployerServiceAccount,
+      `principalSet://iam.googleapis.com/${workloadIdentityPoolResource()}/attribute.repository/${config.github.repo}`,
+      "roles/iam.workloadIdentityUser"
+    );
+  });
 
   if (!config.neon.projectId || !config.neon.baseBranchId) {
     throw new Error("Neon project and base branch must be configured before bootstrap");
   }
 
   const target = resolveDeploymentTarget("main");
-  await ensureDatabase(config.neon.projectId, config.neon.baseBranchId, config.neon.databaseName);
-  const connectionUri = await getConnectionUri(
-    config.neon.projectId,
-    config.neon.baseBranchId,
-    config.neon.databaseName,
-    config.neon.roleName
-  );
-  addSecretVersion(target.databaseSecretName, connectionUri);
-  ensureSecretAccessor(target.databaseSecretName, `serviceAccount:${config.runtimeServiceAccount}`);
+  await runStep("Ensuring Neon database", () => ensureDatabase(config.neon.projectId, config.neon.baseBranchId, config.neon.databaseName));
 
-  for (const [name, value] of Object.entries(githubVariables)) {
-    setGithubVariable(name, value);
-  }
+  await runStep("Publishing database secret", async () => {
+    const connectionUri = await getConnectionUri(
+      config.neon.projectId,
+      config.neon.baseBranchId,
+      config.neon.databaseName,
+      config.neon.roleName
+    );
+    addSecretVersion(target.databaseSecretName, connectionUri);
+    ensureSecretAccessor(target.databaseSecretName, `serviceAccount:${config.runtimeServiceAccount}`);
+  });
+
+  await runStep("Configuring GitHub repository variables", () => {
+    for (const [name, value] of Object.entries(githubVariables)) {
+      setGithubVariable(name, value);
+    }
 
-  setGithubVariable("GCP_WIF_PROVIDER", workloadIdentityProviderResource());
-  setGithubVariable("GCP_DEPLOYER_SERVICE_ACCOUNT", config.deployerServiceAccount);
+    setGithubVariable("GCP_WIF_PROVIDER", workloadIdentityProviderResource());
+    setGithubVariable("GCP_DEPLOYER_SERVICE_ACCOUNT", config.deployerServiceAccount);
+  });
 }
 
 if (import.meta.main) {
-  await bootstrap();
+  await runMain("Bootstrap", async () => {
+    await bootstrap();
+    return `Bootstrap finished for ${config.serviceName}`;
+  });
 }
-

package/templates/shared/scripts/cloudrun/cleanup.ts

@@ -0,0 +1,100 @@
+import { log } from "@clack/prompts";
+import { config, githubVariables } from "./config";
+import { deleteBranch, deleteDatabase, listBranches } from "./neon";
+import {
+  deleteGithubRepository,
+  deleteGithubVariable,
+  deleteProject,
+  deleteSecret,
+  deleteService,
+  deleteServiceAccount,
+  deleteWorkloadIdentityProvider,
+  listCloudRunServices,
+  listSecrets,
+  parseCleanupArgs,
+  requireCommand,
+  runMain,
+  runStep,
+} from "./lib";
+
+function matchesServiceResource(name: string) {
+  return name === config.serviceName || name.startsWith(`${config.serviceName}-pr-`) || name.startsWith(`${config.serviceName}-dev-`);
+}
+
+function matchesSecretResource(name: string) {
+  return name === `${config.serviceName}-database-url` || name.startsWith(`${config.serviceName}-pr-`) || name.startsWith(`${config.serviceName}-dev-`);
+}
+
+export async function cleanup(args = Bun.argv.slice(2)) {
+  requireCommand("gcloud");
+
+  const options = parseCleanupArgs(args);
+
+  const services = await runStep("Finding Cloud Run services", () => listCloudRunServices());
+  const serviceNames = services.filter(matchesServiceResource);
+  await runStep("Deleting Cloud Run services", () => {
+    for (const serviceName of serviceNames) {
+      deleteService(serviceName);
+    }
+  });
+
+  const secrets = await runStep("Finding service secrets", () => listSecrets());
+  const secretNames = secrets.filter(matchesSecretResource);
+  await runStep("Deleting service secrets", () => {
+    for (const secretName of secretNames) {
+      deleteSecret(secretName);
+    }
+  });
+
+  if (config.neon.projectId && config.neon.baseBranchId) {
+    const branches = await runStep("Finding Neon branches", () => listBranches(config.neon.projectId));
+    const disposableBranches = branches.filter(
+      (branch) => branch.name.startsWith(`${config.neon.previewBranchPrefix}-`) || branch.name.startsWith(`${config.neon.personalBranchPrefix}-`)
+    );
+
+    await runStep("Deleting Neon preview and personal branches", async () => {
+      for (const branch of disposableBranches) {
+        await deleteBranch(config.neon.projectId, branch.id);
+      }
+    });
+
+    await runStep("Deleting Neon service database", () =>
+      deleteDatabase(config.neon.projectId, config.neon.baseBranchId, config.neon.databaseName)
+    );
+  } else {
+    log.step("Skipping Neon cleanup because Neon is not configured");
+  }
+
+  await runStep("Deleting service-specific identity resources", () => {
+    deleteWorkloadIdentityProvider();
+    deleteServiceAccount(config.runtimeServiceAccount);
+    deleteServiceAccount(config.deployerServiceAccount);
+  });
+
+  if (Bun.which("gh")) {
+    await runStep("Deleting GitHub repository variables", () => {
+      for (const name of [...Object.keys(githubVariables), "GCP_WIF_PROVIDER", "GCP_DEPLOYER_SERVICE_ACCOUNT"]) {
+        deleteGithubVariable(name);
+      }
+    });
+
+    if (options.destroyRepo) {
+      await runStep(`Deleting GitHub repository ${config.github.repo}`, () => deleteGithubRepository());
+    }
+  } else if (options.destroyRepo) {
+    throw new Error("gh is required to delete the GitHub repository");
+  } else {
+    log.step("Skipping GitHub cleanup because gh is not installed");
+  }
+
+  if (options.destroyProject) {
+    await runStep(`Deleting GCP project ${config.project.id}`, () => deleteProject());
+    return `Deleted project ${config.project.id}`;
+  }
+
+  return `Cleanup finished for ${config.serviceName}`;
+}
+
+if (import.meta.main) {
+  await runMain("Cleanup", () => cleanup(Bun.argv.slice(2)));
+}

package/templates/shared/scripts/cloudrun/cli.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env bun
+
+import { bootstrap } from "./bootstrap";
+import { cleanup } from "./cleanup";
+import { deploy } from "./deploy";
+import { runMain } from "./lib";
+
+async function main(argv = Bun.argv.slice(2)) {
+  const [command, ...rest] = argv;
+
+  if (command === "bootstrap") {
+    await runMain("Bootstrap", async () => {
+      await bootstrap();
+      return "Bootstrap finished";
+    });
+    return;
+  }
+
+  if (command === "deploy") {
+    await runMain("Deploy", () => deploy(rest));
+    return;
+  }
+
+  if (command === "cleanup") {
+    await runMain("Cleanup", () => cleanup(rest));
+    return;
+  }
+
+  throw new Error("Usage: svc-cloudrun <bootstrap|deploy|cleanup> [args]");
+}
+
+if (import.meta.main) {
+  await main();
+}

package/templates/shared/scripts/cloudrun/deploy.ts

@@ -1,5 +1,5 @@
-import { bootstrap } from "./bootstrap";
 import { config } from "./config";
+import { bootstrap } from "./bootstrap";
 import { deleteBranch, ensureBranch, ensureDatabase, getConnectionUri, listBranches } from "./neon";
 import {
   addSecretVersion,
@@ -11,6 +11,8 @@ import {
   parseDeployArgs,
   requireCommand,
   resolveDeploymentTarget,
+  runMain,
+  runStep,
   serviceUrl,
   writeRenderedManifest,
 } from "./lib";
@@ -31,52 +33,65 @@ export async function deploy(args = Bun.argv.slice(2)) {
       throw new Error("Refusing to destroy the main environment");
     }
 
-    deleteService(target.serviceName);
-
-    const branches = await listBranches(config.neon.projectId);
-    const branch = branches.find((candidate) => candidate.name === target.branchName);
-    if (branch) {
-      await deleteBranch(config.neon.projectId, branch.id);
-    }
-    return;
+    await runStep(`Deleting Cloud Run service ${target.serviceName}`, () => deleteService(target.serviceName));
+    await runStep(`Deleting Neon branch ${target.branchName}`, async () => {
+      const branches = await listBranches(config.neon.projectId);
+      const branch = branches.find((candidate) => candidate.name === target.branchName);
+      if (branch) {
+        await deleteBranch(config.neon.projectId, branch.id);
+      }
+    });
+    return `Destroyed ${target.serviceName}`;
   }
 
-  ensureArtifactRepository();
+  await runStep("Ensuring Artifact Registry repository", () => ensureArtifactRepository());
 
   let branchId = config.neon.baseBranchId;
   if (options.environment !== "main") {
-    const branch = await ensureBranch(config.neon.projectId, target.branchName, config.neon.baseBranchId);
+    const branch = await runStep(`Ensuring Neon branch ${target.branchName}`, () =>
+      ensureBranch(config.neon.projectId, target.branchName, config.neon.baseBranchId)
+    );
     branchId = branch.id;
   }
 
-  await ensureDatabase(config.neon.projectId, branchId, config.neon.databaseName);
-  const connectionUri = await getConnectionUri(config.neon.projectId, branchId, config.neon.databaseName, config.neon.roleName);
-  addSecretVersion(target.databaseSecretName, connectionUri);
-  ensureSecretAccessor(target.databaseSecretName, `serviceAccount:${config.runtimeServiceAccount}`);
+  await runStep("Publishing environment database secret", async () => {
+    await ensureDatabase(config.neon.projectId, branchId, config.neon.databaseName);
+    const connectionUri = await getConnectionUri(config.neon.projectId, branchId, config.neon.databaseName, config.neon.roleName);
+    addSecretVersion(target.databaseSecretName, connectionUri);
+    ensureSecretAccessor(target.databaseSecretName, `serviceAccount:${config.runtimeServiceAccount}`);
+  });
 
   const image = imageUrl();
-  gcloud(["builds", "submit", "--project", config.project.id, "--region", config.region, "--tag", image]);
+  await runStep("Building container image", () =>
+    gcloud(["builds", "submit", "--project", config.project.id, "--region", config.region, "--tag", image])
+  );
+
+  const renderedManifestPath = await runStep("Rendering Cloud Run manifest", () => writeRenderedManifest(image, target));
+
+  await runStep(`Deploying Cloud Run service ${target.serviceName}`, () =>
+    gcloud(["run", "services", "replace", renderedManifestPath.pathname, "--project", config.project.id, "--region", config.region])
+  );
 
-  const renderedManifestPath = await writeRenderedManifest(image, target);
-  gcloud(["run", "services", "replace", renderedManifestPath.pathname, "--project", config.project.id, "--region", config.region]);
-  gcloud([
-    "run",
-    "services",
-    "add-iam-policy-binding",
-    target.serviceName,
-    "--project",
-    config.project.id,
-    "--region",
-    config.region,
-    "--member",
-    "allUsers",
-    "--role",
-    "roles/run.invoker",
-  ]);
+  await runStep("Granting public invoker access", () =>
+    gcloud([
+      "run",
+      "services",
+      "add-iam-policy-binding",
+      target.serviceName,
+      "--project",
+      config.project.id,
+      "--region",
+      config.region,
+      "--member",
+      "allUsers",
+      "--role",
+      "roles/run.invoker",
+    ])
+  );
 
-  console.log(serviceUrl(target.serviceName));
+  return serviceUrl(target.serviceName);
 }
 
 if (import.meta.main) {
-  await deploy();
+  await runMain("Deploy", () => deploy(Bun.argv.slice(2)));
 }

package/templates/shared/scripts/cloudrun/lib.ts

@@ -1,8 +1,8 @@
+import { intro, log, outro, spinner } from "@clack/prompts";
 import { config } from "./config";
 
 type CommandOptions = {
   allowFailure?: boolean;
-  capture?: boolean;
   input?: string;
 };
 
@@ -13,6 +13,11 @@ type DeployArgs = {
   name?: string;
 };
 
+type CleanupArgs = {
+  destroyProject: boolean;
+  destroyRepo: boolean;
+};
+
 type DeploymentTarget = {
   environment: "main" | "preview" | "personal";
   serviceName: string;
@@ -20,36 +25,60 @@ type DeploymentTarget = {
   databaseSecretName: string;
 };
 
+type CommandResult = {
+  success: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+
 const decoder = new TextDecoder();
 
+export class CommandError extends Error {
+  command: string;
+  args: string[];
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+
+  constructor(command: string, args: string[], result: CommandResult) {
+    super(`command failed: ${command} ${args.join(" ")}`);
+    this.name = "CommandError";
+    this.command = command;
+    this.args = args;
+    this.stdout = result.stdout;
+    this.stderr = result.stderr;
+    this.exitCode = result.exitCode;
+  }
+}
+
 export function requireCommand(name: string) {
   if (!Bun.which(name)) {
     throw new Error(`missing required command: ${name}`);
   }
 }
 
-export function run(command: string, args: string[], options: CommandOptions = {}) {
+export function run(command: string, args: string[], options: CommandOptions = {}): CommandResult {
   const result = Bun.spawnSync([command, ...args], {
     cwd: process.cwd(),
     env: process.env,
     stdin: options.input,
-    stdout: options.capture || options.allowFailure ? "pipe" : "inherit",
-    stderr: options.capture || options.allowFailure ? "pipe" : "inherit",
+    stdout: "pipe",
+    stderr: "pipe",
   });
 
-  const stdout = result.stdout ? decoder.decode(result.stdout).trim() : "";
-  const stderr = result.stderr ? decoder.decode(result.stderr).trim() : "";
-
-  if (!result.success && !options.allowFailure) {
-    throw new Error([`command failed: ${command} ${args.join(" ")}`, stdout, stderr].filter(Boolean).join("\n"));
-  }
-
-  return {
+  const commandResult: CommandResult = {
     success: result.success,
-    stdout,
-    stderr,
+    stdout: result.stdout ? decoder.decode(result.stdout).trim() : "",
+    stderr: result.stderr ? decoder.decode(result.stderr).trim() : "",
     exitCode: result.exitCode,
   };
+
+  if (!commandResult.success && !options.allowFailure) {
+    throw new CommandError(command, args, commandResult);
+  }
+
+  return commandResult;
 }
 
 export function gcloud(args: string[], options: CommandOptions = {}) {
@@ -64,6 +93,40 @@ export function gh(args: string[], options: CommandOptions = {}) {
   return run("gh", args, options);
 }
 
+export async function runStep<T>(label: string, task: () => Promise<T> | T) {
+  const indicator = spinner();
+  indicator.start(label);
+
+  try {
+    const result = await task();
+    indicator.stop(label);
+    return result;
+  } catch (error) {
+    indicator.stop(`${label} failed`);
+    throw new Error(`${label} failed\n${formatError(error)}`);
+  }
+}
+
+export async function runMain(name: string, task: () => Promise<string | void>) {
+  intro(name);
+
+  try {
+    const message = await task();
+    outro(message || "Done");
+  } catch (error) {
+    log.error(formatError(error));
+    process.exit(1);
+  }
+}
+
+export function formatError(error: unknown) {
+  if (error instanceof CommandError) {
+    return [error.message, error.stderr || error.stdout].filter(Boolean).join("\n");
+  }
+
+  return error instanceof Error ? error.message : String(error);
+}
+
 export function ensureProject() {
   if (gcloud(["projects", "describe", config.project.id], { allowFailure: true }).success) {
     return;
@@ -89,6 +152,10 @@ export function ensureServiceAccount(email: string) {
   gcloud(["iam", "service-accounts", "create", accountId, "--project", config.project.id, "--display-name", accountId]);
 }
 
+export function deleteServiceAccount(email: string) {
+  gcloud(["iam", "service-accounts", "delete", email, "--project", config.project.id, "--quiet"], { allowFailure: true });
+}
+
 export function ensureProjectRole(member: string, role: string) {
   gcloud(["projects", "add-iam-policy-binding", config.project.id, "--member", member, "--role", role]);
 }
@@ -125,6 +192,18 @@ export function ensureSecretAccessor(secretName: string, member: string) {
   gcloud(["secrets", "add-iam-policy-binding", secretName, "--project", config.project.id, "--member", member, "--role", "roles/secretmanager.secretAccessor"]);
 }
 
+export function listSecrets() {
+  return gcloud(["secrets", "list", "--project", config.project.id, "--format=value(name)"]).stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((name) => name.split("/").pop() ?? name);
+}
+
+export function deleteSecret(secretName: string) {
+  gcloud(["secrets", "delete", secretName, "--project", config.project.id, "--quiet"], { allowFailure: true });
+}
+
 export function ensureArtifactRepository() {
   if (
     gcloud(
@@ -150,7 +229,7 @@ export function ensureArtifactRepository() {
 }
 
 export function projectNumber() {
-  return gcloud(["projects", "describe", config.project.id, "--format=value(projectNumber)"], { capture: true }).stdout;
+  return gcloud(["projects", "describe", config.project.id, "--format=value(projectNumber)"]).stdout;
 }
 
 export function workloadIdentityPoolResource() {
@@ -229,12 +308,40 @@ export function ensureWorkloadIdentityProvider() {
   ]);
 }
 
+export function deleteWorkloadIdentityProvider() {
+  gcloud(
+    [
+      "iam",
+      "workload-identity-pools",
+      "providers",
+      "delete",
+      config.workloadIdentityProviderId,
+      "--project",
+      config.project.id,
+      "--location",
+      "global",
+      "--workload-identity-pool",
+      config.workloadIdentityPoolId,
+      "--quiet",
+    ],
+    { allowFailure: true }
+  );
+}
+
 export function setGithubVariable(name: string, value: string) {
   gh(["variable", "set", name, "--repo", config.github.repo, "--body", value]);
 }
 
+export function deleteGithubVariable(name: string) {
+  gh(["variable", "delete", name, "--repo", config.github.repo], { allowFailure: true });
+}
+
+export function deleteGithubRepository() {
+  gh(["repo", "delete", config.github.repo, "--yes"]);
+}
+
 export function imageTag() {
-  const gitSha = run("git", ["rev-parse", "--short", "HEAD"], { allowFailure: true, capture: true }).stdout;
+  const gitSha = run("git", ["rev-parse", "--short", "HEAD"], { allowFailure: true }).stdout;
   return gitSha || `${Date.now()}`;
 }
 
@@ -298,6 +405,27 @@ export function parseDeployArgs(argv: string[]): DeployArgs {
   return parsed;
 }
 
+export function parseCleanupArgs(argv: string[]): CleanupArgs {
+  const parsed: CleanupArgs = {
+    destroyProject: false,
+    destroyRepo: false,
+  };
+
+  for (const token of argv) {
+    if (token === "--project") {
+      parsed.destroyProject = true;
+      continue;
+    }
+
+    if (token === "--repo") {
+      parsed.destroyRepo = true;
+      continue;
+    }
+  }
+
+  return parsed;
+}
+
 export function resolveDeploymentTarget(environment: DeployArgs["environment"], rawName?: string): DeploymentTarget {
   if (environment === "main") {
     return {
@@ -359,17 +487,27 @@ export async function writeRenderedManifest(image: string, target: DeploymentTar
 
 export function serviceUrl(serviceName: string) {
   return gcloud(
-    ["run", "services", "describe", serviceName, "--project", config.project.id, "--region", config.region, "--format=value(status.url)"],
-    { capture: true }
+    ["run", "services", "describe", serviceName, "--project", config.project.id, "--region", config.region, "--format=value(status.url)"]
   ).stdout;
 }
 
+export function listCloudRunServices() {
+  return gcloud(["run", "services", "list", "--project", config.project.id, "--region", config.region, "--format=value(metadata.name)"]).stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
 export function deleteService(serviceName: string) {
   gcloud(["run", "services", "delete", serviceName, "--project", config.project.id, "--region", config.region, "--quiet"], {
     allowFailure: true,
   });
 }
 
+export function deleteProject() {
+  gcloud(["projects", "delete", config.project.id, "--quiet"]);
+}
+
 function slugify(value: string) {
   return value
     .trim()
@@ -377,4 +515,3 @@ function slugify(value: string) {
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "");
 }
-

package/templates/shared/scripts/cloudrun/neon.ts

@@ -85,6 +85,18 @@ export async function ensureDatabase(projectId: string, branchId: string, databa
   });
 }
 
+export async function deleteDatabase(projectId: string, branchId: string, databaseName: string) {
+  try {
+    await (await neonClient()).deleteProjectBranchDatabase(projectId, branchId, databaseName);
+  } catch (error) {
+    const status = (error as { response?: { status?: number } })?.response?.status;
+    if (status === 404) {
+      return;
+    }
+    throw error;
+  }
+}
+
 export async function ensureBranch(projectId: string, branchName: string, parentId: string) {
   const existing = (await listBranches(projectId)).find((branch) => branch.name === branchName);
   if (existing) {

package/templates/variants/bun-connectrpc/Makefile

@@ -0,0 +1,24 @@
+.PHONY: dev gen lint test bootstrap deploy cleanup
+
+CLOUDRUN := npx --no-install svc-cloudrun
+
+dev:
+	bun run ./src/index.ts
+
+gen:
+	bun run ./scripts/codegen.ts
+
+lint:
+	bunx tsc --noEmit
+
+test:
+	bun test
+
+bootstrap:
+	$(CLOUDRUN) bootstrap
+
+deploy:
+	$(CLOUDRUN) deploy $(ARGS)
+
+cleanup:
+	$(CLOUDRUN) cleanup $(ARGS)

package/templates/variants/bun-connectrpc/package.json

@@ -2,15 +2,11 @@
   "name": "{{SERVICE_NAME}}",
   "private": true,
   "type": "module",
-  "scripts": {
-    "dev": "bun run ./src/index.ts",
-    "gen": "bun run ./scripts/codegen.ts",
-    "lint": "bunx tsc --noEmit",
-    "test": "bun test",
-    "bootstrap": "bun run ./scripts/cloudrun/bootstrap.ts",
-    "deploy": "bun run ./scripts/cloudrun/deploy.ts"
+  "bin": {
+    "svc-cloudrun": "./scripts/cloudrun/cli.ts"
   },
   "dependencies": {
+    "@clack/prompts": "^1.2.0",
     "@neondatabase/api-client": "^2.7.1"
   },
   "devDependencies": {

package/templates/variants/bun-hono/Makefile

@@ -0,0 +1,24 @@
+.PHONY: dev gen lint test bootstrap deploy cleanup
+
+CLOUDRUN := npx --no-install svc-cloudrun
+
+dev:
+	bun run ./src/index.ts
+
+gen:
+	bun run ./scripts/codegen.ts
+
+lint:
+	bunx tsc --noEmit
+
+test:
+	bun test
+
+bootstrap:
+	$(CLOUDRUN) bootstrap
+
+deploy:
+	$(CLOUDRUN) deploy $(ARGS)
+
+cleanup:
+	$(CLOUDRUN) cleanup $(ARGS)

package/templates/variants/bun-hono/package.json

@@ -2,15 +2,11 @@
   "name": "{{SERVICE_NAME}}",
   "private": true,
   "type": "module",
-  "scripts": {
-    "dev": "bun run ./src/index.ts",
-    "gen": "bun run ./scripts/codegen.ts",
-    "lint": "bunx tsc --noEmit",
-    "test": "bun test",
-    "bootstrap": "bun run ./scripts/cloudrun/bootstrap.ts",
-    "deploy": "bun run ./scripts/cloudrun/deploy.ts"
+  "bin": {
+    "svc-cloudrun": "./scripts/cloudrun/cli.ts"
   },
   "dependencies": {
+    "@clack/prompts": "^1.2.0",
     "@neondatabase/api-client": "^2.7.1",
     "hono": "^4.10.1"
   },

package/templates/variants/go-chi/Makefile

@@ -0,0 +1,25 @@
+.PHONY: dev gen lint test bootstrap deploy cleanup
+
+CLOUDRUN := npx --no-install svc-cloudrun
+
+dev:
+	go run ./cmd/server
+
+gen:
+	buf generate
+
+lint:
+	go vet ./...
+	buf lint
+
+test:
+	bun test ./test
+
+bootstrap:
+	$(CLOUDRUN) bootstrap
+
+deploy:
+	$(CLOUDRUN) deploy $(ARGS)
+
+cleanup:
+	$(CLOUDRUN) cleanup $(ARGS)

package/templates/variants/go-chi/package.json

@@ -2,15 +2,11 @@
   "name": "{{SERVICE_NAME}}",
   "private": true,
   "type": "module",
+  "bin": {
+    "svc-cloudrun": "./scripts/cloudrun/cli.ts"
+  },
   "dependencies": {
+    "@clack/prompts": "^1.2.0",
     "@neondatabase/api-client": "^2.7.1"
-  },
-  "scripts": {
-    "dev": "go run ./cmd/server",
-    "gen": "buf generate",
-    "lint": "go vet ./... && buf lint",
-    "test": "bun test ./test",
-    "bootstrap": "bun run ./scripts/cloudrun/bootstrap.ts",
-    "deploy": "bun run ./scripts/cloudrun/deploy.ts"
   }
 }

package/templates/variants/go-chi/test/go.test.ts

@@ -1,11 +1,6 @@
 import { expect, test } from "bun:test";
 
-const decoder = new TextDecoder();
-
-test(
-  "go test ./...",
-  { timeout: 60_000 },
-  () => {
+test("go test ./...", { timeout: 60_000 }, () => {
   const result = Bun.spawnSync(["go", "test", "./..."], {
     cwd: process.cwd(),
     stdout: "pipe",
@@ -13,7 +8,6 @@ test(
     env: process.env,
   });
 
-  const output = [decoder.decode(result.stdout), decoder.decode(result.stderr)].join("").trim();
+  const output = `${new TextDecoder().decode(result.stdout)}${new TextDecoder().decode(result.stderr)}`.trim();
   expect(result.exitCode, output || "go test ./... failed").toBe(0);
-  }
-);
+});

package/templates/variants/go-connectrpc/Makefile

@@ -0,0 +1,25 @@
+.PHONY: dev gen lint test bootstrap deploy cleanup
+
+CLOUDRUN := npx --no-install svc-cloudrun
+
+dev:
+	go run ./cmd/server
+
+gen:
+	buf generate
+
+lint:
+	go vet ./...
+	buf lint
+
+test:
+	bun test ./test
+
+bootstrap:
+	$(CLOUDRUN) bootstrap
+
+deploy:
+	$(CLOUDRUN) deploy $(ARGS)
+
+cleanup:
+	$(CLOUDRUN) cleanup $(ARGS)

package/templates/variants/go-connectrpc/package.json

@@ -2,15 +2,11 @@
   "name": "{{SERVICE_NAME}}",
   "private": true,
   "type": "module",
+  "bin": {
+    "svc-cloudrun": "./scripts/cloudrun/cli.ts"
+  },
   "dependencies": {
+    "@clack/prompts": "^1.2.0",
     "@neondatabase/api-client": "^2.7.1"
-  },
-  "scripts": {
-    "dev": "go run ./cmd/server",
-    "gen": "buf generate",
-    "lint": "go vet ./... && buf lint",
-    "test": "bun test ./test",
-    "bootstrap": "bun run ./scripts/cloudrun/bootstrap.ts",
-    "deploy": "bun run ./scripts/cloudrun/deploy.ts"
   }
 }

package/templates/variants/go-connectrpc/test/go.test.ts

@@ -1,11 +1,6 @@
 import { expect, test } from "bun:test";
 
-const decoder = new TextDecoder();
-
-test(
-  "go test ./...",
-  { timeout: 60_000 },
-  () => {
+test("go test ./...", { timeout: 60_000 }, () => {
   const result = Bun.spawnSync(["go", "test", "./..."], {
     cwd: process.cwd(),
     stdout: "pipe",
@@ -13,7 +8,6 @@ test(
     env: process.env,
   });
 
-  const output = [decoder.decode(result.stdout), decoder.decode(result.stderr)].join("").trim();
+  const output = `${new TextDecoder().decode(result.stdout)}${new TextDecoder().decode(result.stderr)}`.trim();
   expect(result.exitCode, output || "go test ./... failed").toBe(0);
-  }
-);
+});