create-svc 0.1.32 → 0.1.34

package/README.md

@@ -41,7 +41,7 @@ service deploy
 To install from npm:
 
 ```bash
-bun install -g create-svc
+npm install -g create-svc@latest
 ```
 
 For the strict one-command production path:
@@ -51,8 +51,8 @@ service create my-service --yes
 ```
 
 By default, that scaffolds the repo, installs dependencies, runs the generated
-repo's `service create`, and then runs `service deploy`. Pass
-`--no-auto-deploy` for scaffold-only generation.
+repo's `service create`, deploys once, verifies production, starts local dev,
+and verifies local. Pass `--no-auto-deploy` for scaffold-only generation.
 
 `--profile microservice` is accepted as a compatibility no-op. App workspaces live outside this package in private app template repositories.
 
@@ -111,6 +111,7 @@ bun run lint
 bun run test
 service create
 service deploy
+service dev down
 service destroy
 ```
 
@@ -124,10 +125,12 @@ make lint
 make test
 service create
 service deploy
+service dev down
 service destroy
 ```
 
 Language-specific tasks such as local running, linting, formatting, testing, and building stay in package scripts or Make targets. Service lifecycle operations are exposed through the generated `service` CLI.
+`service destroy --force` also stops local dev and runs Docker Compose cleanup for generated Cloud Run services.
 
 After `service create` has provisioned auth, the generated repo can mint a
 client-credentials bearer token for smoke checks:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-svc",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "Local microservice bootstrap CLI for Cloud Run and Workers services with Neon-backed data.",
   "module": "index.ts",
   "type": "module",

package/src/cli.ts

@@ -8,6 +8,7 @@ import {
   bootstrapGitHubRepository,
   buildGitBootstrapConfig,
   commitAndPushGeneratedArtifacts,
+  markGitHubRepositoryDeleteOnDestroy,
   type GitBootstrapResult,
 } from "./git-bootstrap";
 import { listOpenBillingAccounts, listAccessibleProjects, type BillingAccount, type GcpProject } from "./gcp";
@@ -111,6 +112,7 @@ export async function run(argv: string[]) {
     gitSpinner.start("Preparing git repository");
     const gitResult = await bootstrapGitHubRepository(targetDir, config.git);
     if (gitResult.status === "created") {
+      await markGitHubRepositoryDeleteOnDestroy(targetDir);
       gitSpinner.stop(`GitHub repository created: ${gitResult.url}`);
     } else if (gitResult.status === "skipped-existing-worktree") {
       gitSpinner.stop(`Existing git worktree detected: ${gitResult.root}`);
@@ -136,6 +138,11 @@ export async function run(argv: string[]) {
         const result = commitAndPushGeneratedArtifacts(targetDir, "Record generated deployment artifacts");
         publishSpinner.stop(result.committed ? "Generated artifacts committed and pushed" : "Generated artifacts already committed");
       }
+    } else if (gitResult.status === "created") {
+      const publishSpinner = spinner();
+      publishSpinner.start("Publishing generated git ownership");
+      const result = commitAndPushGeneratedArtifacts(targetDir, "Record generated GitHub ownership");
+      publishSpinner.stop(result.committed ? "GitHub ownership committed and pushed" : "GitHub ownership already committed");
     }
 
     outro(config.autoDeploy ? "Created and deployed" : "Created");
@@ -1184,7 +1191,7 @@ export function formatScaffoldHelp() {
     "  --billing-account <name>        Billing account resource name",
     "  --quota-project <id>            Billing quota project for gcloud calls",
     "  --region <region>               Cloud Run region",
-    "  --auto-deploy                   Scaffold, run service create, then service deploy (default)",
+    "  --auto-deploy                   Scaffold, run service create, verify prod/local, and start local dev (default)",
     "  --no-auto-deploy                Scaffold only",
     "  --no-git                        Skip default private GitHub repo: anmho/<service_id>",
     "  --yes, -y                       Accept defaults without prompts",

package/src/git-bootstrap.test.ts

@@ -1,8 +1,8 @@
 import { expect, test } from "bun:test";
-import { mkdir, mkdtemp, realpath } from "node:fs/promises";
+import { mkdir, mkdtemp, realpath, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { buildGitBootstrapConfig, findExistingGitWorktree } from "./git-bootstrap";
+import { buildGitBootstrapConfig, findExistingGitWorktree, markGitHubRepositoryDeleteOnDestroy } from "./git-bootstrap";
 
 test("buildGitBootstrapConfig defaults to anmho private repo creation", () => {
   expect(buildGitBootstrapConfig("launch-api", undefined)).toEqual({
@@ -28,6 +28,15 @@ test("findExistingGitWorktree detects parent repositories", async () => {
   expect(findExistingGitWorktree(join(root, "apps", "launch-api"))).toBe(await realpath(root));
 });
 
+test("markGitHubRepositoryDeleteOnDestroy records generated repo ownership", async () => {
+  const root = await mkdtemp(join(tmpdir(), "create-svc-git-"));
+  await writeFile(join(root, "service.jsonc"), '{\n  "git": { "delete_on_destroy": false }\n}\n');
+
+  await markGitHubRepositoryDeleteOnDestroy(root);
+
+  expect(await Bun.file(join(root, "service.jsonc")).text()).toContain('"delete_on_destroy": true');
+});
+
 function run(command: string[], cwd: string) {
   const result = Bun.spawnSync(command, {
     cwd,

package/src/git-bootstrap.ts

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 
 export type GitBootstrapConfig = {
@@ -62,6 +63,16 @@ export function commitAndPushGeneratedArtifacts(targetDir: string, message: stri
   return { committed: true };
 }
 
+export async function markGitHubRepositoryDeleteOnDestroy(targetDir: string) {
+  const path = `${targetDir}/service.jsonc`;
+  const text = await readFile(path, "utf8");
+  const updated = text.replace('"delete_on_destroy": false', '"delete_on_destroy": true');
+  if (updated === text) {
+    throw new Error("service.jsonc does not contain a delete_on_destroy marker");
+  }
+  await writeFile(path, updated);
+}
+
 export function findExistingGitWorktree(targetDir: string) {
   const cwd = existingPath(targetDir);
   const result = Bun.spawnSync(["git", "-C", cwd, "rev-parse", "--show-toplevel"], {

package/src/post-scaffold.test.ts

@@ -2,25 +2,22 @@ import { describe, expect, test } from "bun:test";
 import { buildDeploymentVerificationCommands, buildLocalVerificationCommands, buildPostScaffoldCommands } from "./post-scaffold";
 
 describe("buildPostScaffoldCommands", () => {
-  test("runs create and deploy for HTTP services", () => {
+  test("runs create for HTTP services", () => {
     expect(buildPostScaffoldCommands({ framework: "hono" })).toEqual([
       { command: "service", args: ["create"] },
-      { command: "service", args: ["deploy"] },
     ]);
   });
 
-  test("builds SDK artifacts before create and deploy for ConnectRPC services", () => {
+  test("builds SDK artifacts before create for ConnectRPC services", () => {
     expect(buildPostScaffoldCommands({ framework: "connectrpc" })).toEqual([
       { command: "service", args: ["sdk", "build"] },
       { command: "service", args: ["create"] },
-      { command: "service", args: ["deploy"] },
     ]);
   });
 
   test("uses the workers service CLI for workers services", () => {
     expect(buildPostScaffoldCommands({ target: "workers", framework: "hono" })).toEqual([
       { command: "service", args: ["create"] },
-      { command: "service", args: ["deploy"] },
     ]);
   });
 });

package/src/post-scaffold.ts

@@ -38,7 +38,7 @@ export async function runPostScaffoldFlow(config: ScaffoldConfig, cwd: string) {
     for (const command of buildLocalVerificationCommands(config)) {
       runWithRetries(command, { cwd, quiet: true }, 18, 5_000);
     }
-    return { message: "Dependencies installed, service created, service deployed, production verified, and local dev started" };
+    return { message: "Dependencies installed, service created, production verified, and local dev started" };
   }
 
   return { message: "Backend package generated" };
@@ -225,7 +225,6 @@ export function buildPostScaffoldCommands(
   return [
     ...(config.target !== "workers" && config.framework === "connectrpc" ? [{ command: "service", args: ["sdk", "build"] }] : []),
     { command: "service", args: ["create"] },
-    { command: "service", args: ["deploy"] },
   ];
 }
 

package/src/scaffold.test.ts

@@ -71,6 +71,9 @@ test("scaffolds all runtime/framework variants with shared cloudrun config", asy
     expect(serviceConfig).toContain('"project_mode": "create_new"');
     expect(serviceConfig).toContain('"quota_project_id": "anmho-infra-prod"');
     expect(serviceConfig).toContain('"jwks_url": "https://auth.anmho.com/api/auth/jwks"');
+    expect(serviceConfig).toContain('"git": {');
+    expect(serviceConfig).toContain('"repository": "dns-api"');
+    expect(serviceConfig).toContain('"delete_on_destroy": false');
     expect(serviceConfig).toContain('"project_id": ""');
     expect(serviceConfig).toContain('"base_branch_id": ""');
     expect(serviceConfig).toContain('"base_branch_name": "main"');

package/src/scaffold.ts

@@ -209,6 +209,9 @@ function buildReplacements(config: ScaffoldConfig) {
     RUNTIME_SERVICE_ACCOUNT: runtimeServiceAccount,
     API_HOSTNAME: config.apiHostname,
     API_BASE_DOMAIN: "anmho.com",
+    GIT_ENABLED: String(config.git.enabled),
+    GIT_OWNER: config.git.owner,
+    GIT_REPOSITORY: config.git.repository,
     AUTH_ISSUER: authIssuer,
     AUTH_AUDIENCE: authAudience,
     AUTH_JWKS_URL: authJwksUrl,
@@ -221,6 +224,7 @@ function buildReplacements(config: ScaffoldConfig) {
     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_DEV_DOWN: "service dev down",
     COMMAND_BOOTSTRAP: "service create",
     COMMAND_DEPLOY: "service deploy",
     COMMAND_AUTH_RESOURCE: "service auth resource-server",

package/src/service-runtime/cloudrun/bootstrap.ts

@@ -1,22 +1,30 @@
 import { config } from "./config";
-import { ensureDatabase, getConnectionUri, resolveNeonConfig } from "./neon";
+import { ensureDatabase, getConnectionUri, resolveNeonConfig, type ResolvedNeonConfig } from "./neon";
 import {
   addSecretVersion,
   attachBilling,
   ensureArtifactRepository,
   ensureProject,
   ensureProjectRole,
+  ensureRequiredApis,
   ensureSecretAccessor,
   ensureServiceAccount,
-  gcloud,
   requireCommand,
   requireGcloudAuth,
   resolveDeploymentTarget,
   resolveTemporalRuntimeConfig,
   runMain,
   runStep,
+  type DeploymentTarget,
 } from "./lib";
 
+export type BootstrapResult = {
+  target: DeploymentTarget;
+  neon: ResolvedNeonConfig;
+  databaseUrl: string;
+  artifactRepositoryReady: boolean;
+};
+
 export async function bootstrap(options: { skipProjectSetup?: boolean } = {}) {
   requireCommand("gcloud");
   requireGcloudAuth();
@@ -39,7 +47,7 @@ export async function bootstrap(options: { skipProjectSetup?: boolean } = {}) {
   const target = resolveDeploymentTarget("main");
   await runStep("Ensuring Neon database", () => ensureDatabase(neon.projectId, neon.baseBranchId, neon.databaseName));
 
-  await runStep("Publishing database secret", async () => {
+  const databaseUrl = await runStep("Publishing database secret", async () => {
     const connectionUri = await getConnectionUri(
       neon.projectId,
       neon.baseBranchId,
@@ -48,15 +56,25 @@ export async function bootstrap(options: { skipProjectSetup?: boolean } = {}) {
     );
     addSecretVersion(target.databaseSecretName, connectionUri);
     ensureSecretAccessor(target.databaseSecretName, `serviceAccount:${config.runtimeServiceAccount}`);
+    return connectionUri;
   });
 
-  await runStep("Publishing Temporal secrets", () => publishTemporalSecrets());
+  if (shouldPublishTemporalSecrets()) {
+    await runStep("Publishing Temporal secrets", () => publishTemporalSecrets());
+  }
+
+  return {
+    target,
+    neon,
+    databaseUrl,
+    artifactRepositoryReady: true,
+  } satisfies BootstrapResult;
 }
 
 export async function prepareGcpProject() {
   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]));
+  await runStep("Enabling required GCP APIs", () => ensureRequiredApis());
 }
 
 function publishTemporalSecrets() {
@@ -71,6 +89,11 @@ function publishTemporalSecrets() {
   return temporal.apiKeySecretName;
 }
 
+function shouldPublishTemporalSecrets() {
+  const temporal = resolveTemporalRuntimeConfig();
+  return Boolean(process.env.TEMPORAL_API_KEY?.trim() && temporal.apiKeySecretName);
+}
+
 if (import.meta.main) {
   await runMain("Bootstrap", async () => {
     await bootstrap();

package/src/service-runtime/cloudrun/cleanup.ts

@@ -1,5 +1,6 @@
 import { confirm, isCancel, log } from "@clack/prompts";
 import { deleteAuthResourceServer } from "../authctl";
+import { buildLocalDevCleanupPlan, stopLocalDev } from "../local-dev";
 import { config } from "./config";
 import { deleteBranch, deleteDatabase, listBranches, resolveNeonConfig } from "./neon";
 import {
@@ -45,6 +46,7 @@ type DestroyPlan = {
   resources: PlannedResource[];
   skipped: PlannedResource[];
   blockers: string[];
+  githubRepository?: string;
   hasProductionDomainMapping: boolean;
   serviceNames: string[];
   secretNames: string[];
@@ -69,6 +71,12 @@ export async function cleanup(args = Bun.argv.slice(2)) {
 
   await requireDestroyConfirmation(options.force);
 
+  await runStep("Stopping local dev resources", () => stopLocalDev({ dockerCompose: true, removeVolumes: true }));
+
+  if (plan.githubRepository) {
+    await runStep(`Deleting GitHub repository ${plan.githubRepository}`, () => deleteGitHubRepository(plan.githubRepository!));
+  }
+
   await runStep(`Deleting auth resource server ${config.serviceName}`, () => deleteAuthResourceServer());
 
   if (plan.hasProductionDomainMapping) {
@@ -125,11 +133,14 @@ async function buildDestroyPlan(destroyProject: boolean): Promise<DestroyPlan> {
     ],
     skipped: [],
     blockers: [],
+    githubRepository: undefined,
     hasProductionDomainMapping: false,
     serviceNames: [],
     secretNames: [],
   };
 
+  planGitHubRepository(plan);
+  await planLocalDev(plan);
   planProductionDomainMapping(plan);
   planCloudRunServices(plan);
   planSecrets(plan);
@@ -143,6 +154,51 @@ async function buildDestroyPlan(destroyProject: boolean): Promise<DestroyPlan> {
   return plan;
 }
 
+async function planLocalDev(plan: DestroyPlan) {
+  const localDev = await buildLocalDevCleanupPlan({ dockerCompose: true });
+  for (const resource of localDev.resources) {
+    plan.resources.push({ label: resource, detail: "local" });
+  }
+  for (const skipped of localDev.skipped) {
+    plan.skipped.push({ label: skipped, detail: "local" });
+  }
+}
+
+function planGitHubRepository(plan: DestroyPlan) {
+  const repository = `${config.git.owner}/${config.git.repository}`;
+  if (!config.git.deleteOnDestroy) {
+    plan.skipped.push({
+      label: `GitHub repository ${repository}`,
+      detail: config.git.enabled ? "not created by this service CLI run" : "git disabled",
+    });
+    return;
+  }
+
+  if (!Bun.which("gh")) {
+    plan.blockers.push(`GitHub repository ${repository}: missing required command gh`);
+    return;
+  }
+
+  const auth = run("gh", ["auth", "status"], { allowFailure: true });
+  if (!auth.success) {
+    plan.blockers.push(`GitHub repository ${repository}: authenticate GitHub CLI with gh auth login`);
+    return;
+  }
+
+  const view = run("gh", ["repo", "view", repository, "--json", "name"], { allowFailure: true });
+  if (!view.success) {
+    plan.skipped.push({ label: `GitHub repository ${repository}`, detail: "not found" });
+    return;
+  }
+
+  plan.githubRepository = repository;
+  plan.resources.push({ label: `GitHub repository ${repository}`, detail: "private generated repo" });
+}
+
+function deleteGitHubRepository(repository: string) {
+  run("gh", ["repo", "delete", repository, "--yes"], { allowFailure: true });
+}
+
 function planProductionDomainMapping(plan: DestroyPlan) {
   try {
     const mapping = describeProductionDomainMapping();

package/src/service-runtime/cloudrun/cli.ts

@@ -2,6 +2,7 @@
 
 import { mkdir } from "node:fs/promises";
 import { ensureAuthClient, ensureAuthResourceServer, runAuthCommand, runAuthDoctor } from "../authctl";
+import { stopLocalDev } from "../local-dev";
 import { bootstrap, prepareGcpProject } from "./bootstrap";
 import { cleanup } from "./cleanup";
 import { deploy } from "./deploy";
@@ -38,11 +39,10 @@ export async function main(argv = Bun.argv.slice(2)) {
       await prepareGcpProject();
       await runStep("Registering auth resource server", () => ensureAuthResourceServer());
       await runStep("Provisioning auth client", () => ensureAuthClient());
-      await bootstrap({ skipProjectSetup: true });
-      const target = resolveDeploymentTarget("main");
-      const databaseUrl = await runStep("Reading production database URL", () => accessSecretVersion(target.databaseSecretName));
+      const bootstrapResult = await bootstrap({ skipProjectSetup: true });
+      const databaseUrl = bootstrapResult.databaseUrl;
       await runStep("Applying production migrations", () => runLanguageTask("migrate", { DATABASE_URL: databaseUrl }));
-      const origin = await deploy(["--ci"]);
+      const origin = await deploy(["--ci"], { bootstrapResult });
       await runOptionalBunScript("seed", { DATABASE_URL: databaseUrl });
       return `Created ${origin}`;
     });
@@ -69,6 +69,14 @@ export async function main(argv = Bun.argv.slice(2)) {
     return;
   }
 
+  if (command === "dev") {
+    if (rest[0] !== "down") {
+      throw new Error(`Unknown dev command: ${rest[0] || ""}\n\n${formatHelp()}`);
+    }
+    await runMain("Dev", () => stopLocalDev({ dockerCompose: true, removeVolumes: false }));
+    return;
+  }
+
   if (command === "dns") {
     await runMain("DNS", () => repairDns());
     return;
@@ -116,6 +124,7 @@ function formatHelp() {
     "  auth token  Mint a bearer token for protected API checks",
     "  sdk         Build or publish generated SDK artifacts",
     "  dns         Repair or inspect DNS mappings",
+    "  dev down    Stop local dev and Docker Compose containers",
     "  dashboards  Publish Grafana resources",
     "  destroy     Remove service-managed cloud resources",
   ].join("\n");

package/src/service-runtime/cloudrun/config.ts

@@ -49,6 +49,12 @@ export const config = {
     previewBranchPrefix: neon.preview_branch_prefix,
     personalBranchPrefix: neon.personal_branch_prefix,
   },
+  git: {
+    enabled: Boolean(serviceConfig.git?.enabled),
+    owner: serviceConfig.git?.owner || "anmho",
+    repository: serviceConfig.git?.repository || serviceConfig.service_id,
+    deleteOnDestroy: Boolean(serviceConfig.git?.delete_on_destroy),
+  },
   requiredApis: cloudrun.required_apis,
 } as const;
 

package/src/service-runtime/cloudrun/deploy.ts

@@ -1,5 +1,5 @@
 import { config } from "./config";
-import { bootstrap } from "./bootstrap";
+import { bootstrap, type BootstrapResult } from "./bootstrap";
 import { deleteBranch, ensureBranch, ensureDatabase, getConnectionUri, listBranches, resolveNeonConfig } from "./neon";
 import {
   addSecretVersion,
@@ -8,6 +8,7 @@ import {
   ensureProductionDomainMapping,
   ensureSecretAccessor,
   gcloud,
+  gcloudStreaming,
   gcloudWithRetry,
   imageUrl,
   parseDeployArgs,
@@ -19,17 +20,22 @@ import {
   writeRenderedManifest,
 } from "./lib";
 
-export async function deploy(args = Bun.argv.slice(2)) {
+type DeployOptions = {
+  bootstrapResult?: BootstrapResult;
+};
+
+export async function deploy(args = Bun.argv.slice(2), deployOptions: DeployOptions = {}) {
   requireCommand("gcloud");
   requireCommand("bun");
 
   const options = parseDeployArgs(args);
-  if (!options.ci) {
-    await bootstrap();
-  }
+  const bootstrapResult = deployOptions.bootstrapResult ?? (!options.ci ? await bootstrap() : undefined);
 
-  const target = resolveDeploymentTarget(options.environment, options.name);
-  const neon = await runStep("Resolving Neon defaults", () => resolveNeonConfig());
+  const target =
+    bootstrapResult && options.environment === "main" && !options.name
+      ? bootstrapResult.target
+      : resolveDeploymentTarget(options.environment, options.name);
+  const neon = bootstrapResult?.neon ?? (await runStep("Resolving Neon defaults", () => resolveNeonConfig()));
 
   if (options.destroy) {
     if (options.environment === "main") {
@@ -47,7 +53,9 @@ export async function deploy(args = Bun.argv.slice(2)) {
     return `Destroyed ${target.serviceName}`;
   }
 
-  await runStep("Ensuring Artifact Registry repository", () => ensureArtifactRepository());
+  if (!bootstrapResult?.artifactRepositoryReady) {
+    await runStep("Ensuring Artifact Registry repository", () => ensureArtifactRepository());
+  }
 
   let branchId: string = neon.baseBranchId;
   if (options.environment !== "main") {
@@ -57,15 +65,17 @@ export async function deploy(args = Bun.argv.slice(2)) {
     branchId = branch.id;
   }
 
-  await runStep("Publishing environment database secret", async () => {
-    await ensureDatabase(neon.projectId, branchId, neon.databaseName);
-    const connectionUri = await getConnectionUri(neon.projectId, branchId, neon.databaseName, neon.roleName);
-    addSecretVersion(target.databaseSecretName, connectionUri);
-    ensureSecretAccessor(target.databaseSecretName, `serviceAccount:${config.runtimeServiceAccount}`);
-  });
+  if (!bootstrapResult || target.environment !== "main") {
+    await runStep("Publishing environment database secret", async () => {
+      await ensureDatabase(neon.projectId, branchId, neon.databaseName);
+      const connectionUri = await getConnectionUri(neon.projectId, branchId, neon.databaseName, neon.roleName);
+      addSecretVersion(target.databaseSecretName, connectionUri);
+      ensureSecretAccessor(target.databaseSecretName, `serviceAccount:${config.runtimeServiceAccount}`);
+    });
+  }
   const image = imageUrl();
-  await runStep("Building container image", () =>
-    gcloud(["builds", "submit", "--project", config.project.id, "--region", config.region, "--tag", image])
+  await runStep("Building container image in Cloud Build", () =>
+    gcloudStreaming(["builds", "submit", "--project", config.project.id, "--region", config.region, "--tag", image])
   );
 
   const renderedManifestPath = await runStep("Rendering Cloud Run manifest", () => writeRenderedManifest(image, target));

package/src/service-runtime/cloudrun/lib.ts

@@ -117,6 +117,85 @@ export function gcloud(args: string[], options: CommandOptions = {}) {
   return run("gcloud", normalized, options);
 }
 
+export async function gcloudStreaming(args: string[], options: CommandOptions = {}) {
+  const normalized = [...args];
+  if (config.project.quotaProjectId && !normalized.includes("--billing-project")) {
+    normalized.push("--billing-project", config.project.quotaProjectId);
+  }
+  return runStreaming("gcloud", normalized, options);
+}
+
+export async function runStreaming(command: string, args: string[], options: CommandOptions = {}): Promise<CommandResult> {
+  const child = Bun.spawn([command, ...args], {
+    cwd: process.cwd(),
+    env: { ...process.env, ...options.env },
+    stdin: options.input === undefined ? undefined : encoder.encode(options.input),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const output = {
+    stdout: "",
+    stderr: "",
+    buildUrlPrinted: false,
+  };
+  await Promise.all([
+    captureStream(child.stdout, (chunk) => {
+      output.stdout += chunk;
+      printCloudBuildUrl(chunk, output);
+    }),
+    captureStream(child.stderr, (chunk) => {
+      output.stderr += chunk;
+      printCloudBuildUrl(chunk, output);
+    }),
+  ]);
+  const exitCode = await child.exited;
+  const result: CommandResult = {
+    success: exitCode === 0,
+    stdout: output.stdout.trim(),
+    stderr: output.stderr.trim(),
+    exitCode,
+  };
+
+  if (!result.success && !options.allowFailure) {
+    throw new CommandError(command, args, result);
+  }
+
+  return result;
+}
+
+async function captureStream(stream: ReadableStream<Uint8Array> | null, onChunk: (chunk: string) => void) {
+  if (!stream) {
+    return;
+  }
+  const reader = stream.getReader();
+  const streamDecoder = new TextDecoder();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    onChunk(streamDecoder.decode(value, { stream: true }));
+  }
+  const remaining = streamDecoder.decode();
+  if (remaining) {
+    onChunk(remaining);
+  }
+}
+
+function printCloudBuildUrl(chunk: string, output: { stdout: string; stderr: string; buildUrlPrinted: boolean }) {
+  if (output.buildUrlPrinted) {
+    return;
+  }
+  const combined = `${output.stdout}\n${output.stderr}\n${chunk}`;
+  const match = combined.match(/https:\/\/console\.cloud\.google\.com\/cloud-build\/[^\s)]+/);
+  if (!match?.[0]) {
+    return;
+  }
+  output.buildUrlPrinted = true;
+  log.step(`Cloud Build logs: ${match[0]}`);
+}
+
 export function gcloudWithRetry(args: string[], options: CommandOptions = {}) {
   let lastError: unknown;
   for (let attempt = 1; attempt <= 12; attempt += 1) {
@@ -187,6 +266,21 @@ export function attachBilling() {
   gcloud(["beta", "billing", "projects", "link", config.project.id, "--billing-account", config.project.billingAccount]);
 }
 
+export function ensureRequiredApis() {
+  const enabled = new Set(
+    gcloud(["services", "list", "--enabled", "--project", config.project.id, "--format=value(config.name)"]).stdout
+      .split("\n")
+      .map((name) => name.trim())
+      .filter(Boolean)
+  );
+  const missing = config.requiredApis.filter((api: string) => !enabled.has(api));
+  if (missing.length === 0) {
+    return "Required GCP APIs are already enabled";
+  }
+  gcloud(["services", "enable", ...missing, "--project", config.project.id]);
+  return `Enabled ${missing.join(", ")}`;
+}
+
 export function ensureServiceAccount(email: string) {
   if (gcloud(["iam", "service-accounts", "describe", email, "--project", config.project.id], { allowFailure: true }).success) {
     return;
@@ -202,9 +296,28 @@ export function deleteServiceAccount(email: string) {
 }
 
 export function ensureProjectRole(member: string, role: string) {
+  if (projectHasRole(member, role)) {
+    return;
+  }
   gcloudWithRetry(["projects", "add-iam-policy-binding", config.project.id, "--member", member, "--role", role]);
 }
 
+function projectHasRole(member: string, role: string) {
+  return gcloud(
+    [
+      "projects",
+      "get-iam-policy",
+      config.project.id,
+      "--flatten=bindings[].members",
+      `--filter=bindings.role=${role} AND bindings.members=${member}`,
+      "--format=value(bindings.role)",
+    ],
+    { allowFailure: true }
+  )
+    .stdout.split("\n")
+    .some((line) => line.trim() === role);
+}
+
 export function ensureServiceAccountRole(serviceAccount: string, member: string, role: string) {
   gcloudWithRetry([
     "iam",

package/src/service-runtime/cloudrun/neon.ts

@@ -18,7 +18,7 @@ type NeonDatabase = {
   ownerName: string;
 };
 
-type ResolvedNeonConfig = {
+export type ResolvedNeonConfig = {
   projectId: string;
   baseBranchId: string;
   baseBranchName: string;

package/src/service-runtime/local-dev.test.ts

@@ -0,0 +1,47 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { buildLocalDevCleanupPlan, stopLocalDev } from "./local-dev";
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("local dev cleanup", () => {
+  test("is idempotent with a missing pid and missing compose file", async () => {
+    const root = await tempRoot();
+    const result = await stopLocalDev({ root, dockerCompose: true, removeVolumes: true });
+
+    expect(result).toContain("No local dev pid file found");
+    expect(await Bun.file(join(root, ".service", "local-dev.pid")).exists()).toBe(false);
+  });
+
+  test("removes a stale pid file", async () => {
+    const root = await tempRoot();
+    await mkdir(join(root, ".service"), { recursive: true });
+    await Bun.write(join(root, ".service", "local-dev.pid"), "999999\n");
+
+    const result = await stopLocalDev({ root, dockerCompose: false });
+
+    expect(result).toContain("Removed stale local dev pid file for 999999");
+    expect(await Bun.file(join(root, ".service", "local-dev.pid")).exists()).toBe(false);
+  });
+
+  test("plans Docker Compose cleanup when compose exists", async () => {
+    const root = await tempRoot();
+    await Bun.write(join(root, "docker-compose.yml"), "services: {}\n");
+
+    const plan = await buildLocalDevCleanupPlan({ root, dockerCompose: true });
+
+    expect(plan.resources).toContain("Docker Compose containers, networks, and volumes");
+  });
+});
+
+async function tempRoot() {
+  const root = await mkdtemp(join(tmpdir(), "create-svc-local-dev-"));
+  roots.push(root);
+  return root;
+}

package/src/service-runtime/local-dev.ts

@@ -0,0 +1,138 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+
+type LocalDevOptions = {
+  root?: string;
+  dockerCompose?: boolean;
+  removeVolumes?: boolean;
+};
+
+export type LocalDevCleanupPlan = {
+  pidFile: string;
+  hasPidFile: boolean;
+  pid?: number;
+  hasDockerCompose: boolean;
+  resources: string[];
+  skipped: string[];
+};
+
+const decoder = new TextDecoder();
+
+export async function buildLocalDevCleanupPlan(options: LocalDevOptions = {}): Promise<LocalDevCleanupPlan> {
+  const root = options.root ?? defaultServiceRoot();
+  const pidFile = join(root, ".service", "local-dev.pid");
+  const hasPidFile = await Bun.file(pidFile).exists();
+  const pid = hasPidFile ? parsePid(await Bun.file(pidFile).text()) : undefined;
+  const hasDockerCompose = Boolean(options.dockerCompose) && (await Bun.file(join(root, "docker-compose.yml")).exists());
+  const resources: string[] = [];
+  const skipped: string[] = [];
+
+  if (hasPidFile) {
+    resources.push(`Local dev process from ${pidFile}`);
+  } else {
+    skipped.push("Local dev process: no .service/local-dev.pid");
+  }
+
+  if (hasDockerCompose) {
+    resources.push("Docker Compose containers, networks, and volumes");
+  } else if (options.dockerCompose) {
+    skipped.push("Docker Compose: no docker-compose.yml");
+  }
+
+  return {
+    pidFile,
+    hasPidFile,
+    pid,
+    hasDockerCompose,
+    resources,
+    skipped,
+  };
+}
+
+export async function stopLocalDev(options: LocalDevOptions = {}) {
+  const root = options.root ?? defaultServiceRoot();
+  const plan = await buildLocalDevCleanupPlan({ ...options, root });
+  const messages: string[] = [];
+
+  if (plan.hasPidFile) {
+    if (plan.pid) {
+      messages.push(stopPid(plan.pid) ? `Stopped local dev process ${plan.pid}` : `Removed stale local dev pid file for ${plan.pid}`);
+    } else {
+      messages.push(`Removed invalid local dev pid file ${plan.pidFile}`);
+    }
+    await rm(plan.pidFile, { force: true });
+  } else {
+    messages.push("No local dev pid file found");
+  }
+
+  if (plan.hasDockerCompose) {
+    const result = runDockerComposeDown(root, Boolean(options.removeVolumes));
+    messages.push(result);
+  }
+
+  return messages.join("\n");
+}
+
+function defaultServiceRoot() {
+  return process.env.CREATE_SVC_SERVICE_ROOT?.trim() || process.cwd();
+}
+
+function parsePid(raw: string) {
+  const pid = Number.parseInt(raw.trim(), 10);
+  return Number.isFinite(pid) && pid > 0 ? pid : undefined;
+}
+
+function stopPid(pid: number) {
+  const wasRunning = isRunning(pid);
+  tryKill(-pid, "SIGTERM") || tryKill(pid, "SIGTERM");
+  Bun.sleepSync(1_000);
+  if (isRunning(pid)) {
+    tryKill(-pid, "SIGKILL") || tryKill(pid, "SIGKILL");
+  }
+  return wasRunning;
+}
+
+function isRunning(pid: number) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function tryKill(pid: number, signal: NodeJS.Signals) {
+  try {
+    process.kill(pid, signal);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runDockerComposeDown(root: string, removeVolumes: boolean) {
+  if (!Bun.which("docker")) {
+    return "Docker is not installed; Docker Compose cleanup skipped";
+  }
+
+  const args = ["compose", "down", "--remove-orphans"];
+  if (removeVolumes) {
+    args.push("-v");
+  }
+  const result = Bun.spawnSync(["docker", ...args], {
+    cwd: root,
+    env: process.env,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (!result.success) {
+    const output = [
+      result.stderr ? decoder.decode(result.stderr).trim() : "",
+      result.stdout ? decoder.decode(result.stdout).trim() : "",
+    ]
+      .filter(Boolean)
+      .join("\n");
+    return `Docker Compose cleanup failed: ${output || `exit ${result.exitCode}`}`;
+  }
+  return removeVolumes ? "Docker Compose containers and volumes removed" : "Docker Compose containers stopped";
+}

package/src/service-runtime/workers/cli.ts

@@ -4,6 +4,7 @@ import { confirm, intro, isCancel, log, outro } from "@clack/prompts";
 import { createApiClient } from "@neondatabase/api-client";
 import { Client } from "pg";
 import { ensureAuthClient, ensureAuthResourceServer, runAuthCommand, runAuthDoctor } from "../authctl";
+import { stopLocalDev } from "../local-dev";
 import { serviceConfig } from "../runtime";
 
 const config = {
@@ -11,6 +12,12 @@ const config = {
   hostname: serviceConfig.dns.hostname,
   neonDatabaseName: serviceConfig.neon.database_name,
   neonRoleName: serviceConfig.neon.role_name,
+  git: {
+    enabled: Boolean(serviceConfig.git?.enabled),
+    owner: serviceConfig.git?.owner || "anmho",
+    repository: serviceConfig.git?.repository || serviceConfig.service_id,
+    deleteOnDestroy: Boolean(serviceConfig.git?.delete_on_destroy),
+  },
 };
 
 type DoctorStatus = "pass" | "warn" | "fail";
@@ -65,6 +72,13 @@ export async function main(argv = Bun.argv.slice(2)) {
     return runMain("DNS", () => `Workers custom domain is configured in wrangler.toml for ${config.hostname}`);
   }
 
+  if (command === "dev") {
+    if (rest[0] !== "down") {
+      throw new Error(`Unknown dev command: ${rest[0] || ""}\n\n${formatHelp()}`);
+    }
+    return runMain("Dev", () => stopLocalDev({ dockerCompose: false }));
+  }
+
   if (command === "doctor") {
     return runMain("Doctor", () => runDoctor());
   }
@@ -81,6 +95,8 @@ export async function main(argv = Bun.argv.slice(2)) {
     return runMain("Destroy", async () => {
       await requireDestroyConfirmation(rest.includes("--force"));
       const wranglerArgs = rest.filter((arg) => arg !== "--force");
+      await stopLocalDev({ dockerCompose: false });
+      deleteGitHubRepositoryIfOwned();
       await deleteHyperdrive();
       run("wrangler", ["delete", "--name", config.serviceName, "--force", ...wranglerArgs]);
       await deleteNeonDatabase();
@@ -109,12 +125,28 @@ function formatHelp() {
     "  doctor      Check local tools and cloud access",
     "  auth        Manage auth resource server and clients",
     "  auth token  Mint a bearer token for protected API checks",
+    "  dev down    Stop local dev",
     "  dns         Show Workers custom-domain configuration",
     "  dashboards  Publish Grafana resources",
     "  destroy     Remove service-managed Worker resources",
   ].join("\n");
 }
 
+function deleteGitHubRepositoryIfOwned() {
+  const repository = `${config.git.owner}/${config.git.repository}`;
+  if (!config.git.deleteOnDestroy) {
+    log.step(`Skipping GitHub repository ${repository}: ${config.git.enabled ? "not created by this service CLI run" : "git disabled"}`);
+    return;
+  }
+  run("gh", ["auth", "status"], { capture: true });
+  const view = run("gh", ["repo", "view", repository, "--json", "name"], { allowFailure: true, capture: true });
+  if (!view.success) {
+    log.step(`Skipping GitHub repository ${repository}: not found`);
+    return;
+  }
+  run("gh", ["repo", "delete", repository, "--yes"]);
+}
+
 function run(command: string, args: string[], options: { allowFailure?: boolean; capture?: boolean } = {}) {
   if (!Bun.which(command)) {
     throw new Error(`missing required command: ${command}`);

package/templates/shared/README.md

@@ -30,6 +30,7 @@ console to create and deploy.
 {{COMMAND_TEST}}
 {{COMMAND_BOOTSTRAP}}
 {{COMMAND_DEPLOY}}
+{{COMMAND_DEV_DOWN}}
 {{COMMAND_AUTH_RESOURCE}}
 {{COMMAND_AUTH_CLIENT}}
 {{COMMAND_DEPLOY_PERSONAL}}
@@ -215,7 +216,8 @@ service create {{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
+Cloud Run service once, verifies production and local endpoints, starts local dev,
+and fails loudly with resumable
 instructions if a required cloud credential is missing. The generated package can also be run
 manually:
 

package/templates/shared/service.jsonc

@@ -27,6 +27,15 @@
     "service_id": "{{SERVICE_ID}}"
   },
 
+  "git": {
+    "enabled": {{GIT_ENABLED}},
+    "owner": "{{GIT_OWNER}}",
+    "repository": "{{GIT_REPOSITORY}}",
+    // This flips to true only after `service create` actually creates the
+    // GitHub repository. Existing worktrees and --no-git stay false.
+    "delete_on_destroy": false
+  },
+
   "auth": {
     "issuer": "{{AUTH_ISSUER}}",
     "token_endpoint": "https://auth.anmho.com/api/auth/oauth2/token",