create-svc 0.1.33 → 0.1.35

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.33",
+  "version": "0.1.35",
   "description": "Local microservice bootstrap CLI for Cloud Run and Workers services with Neon-backed data.",
   "module": "index.ts",
   "type": "module",

package/src/cli.ts

@@ -1191,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/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.ts

@@ -224,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,9 +1,11 @@
 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 {
   assertOwnedResource,
+  deleteArtifactImage,
   deleteProject,
   deleteProductionDomainMapping,
   deleteSecret,
@@ -14,6 +16,7 @@ import {
   describeSecret,
   formatError,
   listCloudRunServices,
+  listArtifactImages,
   listSecrets,
   parseCleanupArgs,
   requireCommand,
@@ -49,6 +52,7 @@ type DestroyPlan = {
   hasProductionDomainMapping: boolean;
   serviceNames: string[];
   secretNames: string[];
+  artifactImages: string[];
   neon?: {
     projectId: string;
     baseBranchId: string;
@@ -70,6 +74,8 @@ 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!));
   }
@@ -88,6 +94,13 @@ export async function cleanup(args = Bun.argv.slice(2)) {
     }
   });
 
+  const artifactImages = plan.artifactImages;
+  await runStep("Deleting Artifact Registry images", () => {
+    for (const image of artifactImages) {
+      deleteArtifactImage(image);
+    }
+  });
+
   const secretNames = plan.secretNames;
   await runStep("Deleting service secrets", () => {
     for (const secretName of secretNames) {
@@ -134,11 +147,14 @@ async function buildDestroyPlan(destroyProject: boolean): Promise<DestroyPlan> {
     hasProductionDomainMapping: false,
     serviceNames: [],
     secretNames: [],
+    artifactImages: [],
   };
 
   planGitHubRepository(plan);
+  await planLocalDev(plan);
   planProductionDomainMapping(plan);
   planCloudRunServices(plan);
+  planArtifactImages(plan);
   planSecrets(plan);
   await planNeon(plan);
   await planGrafana(plan);
@@ -150,6 +166,16 @@ 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) {
@@ -222,6 +248,21 @@ function planCloudRunServices(plan: DestroyPlan) {
   }
 }
 
+function planArtifactImages(plan: DestroyPlan) {
+  try {
+    plan.artifactImages = listArtifactImages();
+    if (plan.artifactImages.length === 0) {
+      plan.skipped.push({ label: `Artifact Registry images for ${config.serviceName}`, detail: "none matched" });
+      return;
+    }
+    for (const image of plan.artifactImages) {
+      plan.resources.push({ label: `Artifact Registry image ${image}`, detail: `${config.project.id}/${config.region}` });
+    }
+  } catch (error) {
+    plan.blockers.push(`Artifact Registry images for ${config.serviceName}: ${formatError(error)}`);
+  }
+}
+
 function planSecrets(plan: DestroyPlan) {
   try {
     plan.secretNames = listSecrets().filter(matchesSecretResource);

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/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",
@@ -302,6 +415,32 @@ export function ensureArtifactRepository() {
   ]);
 }
 
+export function artifactImageBase() {
+  return `${config.region}-docker.pkg.dev/${config.project.id}/${config.artifactRepository}/${config.serviceName}`;
+}
+
+export function listArtifactImages() {
+  const result = gcloud(
+    ["artifacts", "docker", "images", "list", artifactImageBase(), "--include-tags", "--project", config.project.id, "--format=json"],
+    { allowFailure: true }
+  );
+  if (!result.success || !result.stdout) {
+    return [];
+  }
+
+  try {
+    return (JSON.parse(result.stdout) as Array<{ package?: string; version?: string }>)
+      .map((image) => (image.package && image.version ? `${image.package}@${image.version}` : ""))
+      .filter(Boolean);
+  } catch {
+    throw new Error(`Unable to parse Artifact Registry images for ${artifactImageBase()}`);
+  }
+}
+
+export function deleteArtifactImage(image: string) {
+  gcloud(["artifacts", "docker", "images", "delete", image, "--delete-tags", "--project", config.project.id, "--quiet"], { allowFailure: true });
+}
+
 export function projectNumber() {
   return gcloud(["projects", "describe", config.project.id, "--format=value(projectNumber)"]).stdout;
 }
@@ -312,7 +451,7 @@ export function imageTag() {
 }
 
 export function imageUrl(tag = imageTag()) {
-  return `${config.region}-docker.pkg.dev/${config.project.id}/${config.artifactRepository}/${config.serviceName}:${tag}`;
+  return `${artifactImageBase()}:${tag}`;
 }
 
 export function parseDeployArgs(argv: string[]): DeployArgs {

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 = {
@@ -71,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());
   }
@@ -87,6 +95,7 @@ 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]);
@@ -116,6 +125,7 @@ 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",

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: