create-svc 0.1.77 → 0.1.80

package/README.md

@@ -17,6 +17,36 @@ Local provisioning intentionally prefers known-good CLIs over SDK-heavy orchestr
 
 npm: <https://www.npmjs.com/package/create-svc>
 
+## Install and update
+
+For an installed CLI, use npm as the canonical owner:
+
+```bash
+npm install -g create-svc@latest
+```
+
+That installs the `service`, `create-svc`, and `create-service` commands from the same package. Check the binary that is actually running:
+
+```bash
+service --version
+service doctor
+```
+
+`service doctor` reports the active binary path, package root, installed package version, npm latest version, and any other `service` binaries on `PATH`. If a stale Homebrew or manually copied binary is shadowing npm, remove that stale binary and reinstall npm latest:
+
+```bash
+which -a service
+rm "/opt/homebrew/bin/service"
+npm install -g create-svc@latest
+```
+
+If the stale binary came from a global npm install you no longer want, remove and reinstall it through npm instead:
+
+```bash
+npm uninstall -g create-svc
+npm install -g create-svc@latest
+```
+
 ## Usage
 
 ```bash

package/package.json

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

package/src/git-bootstrap.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
+import { protectMainBranch } from "./github-protection";
 
 export type GitBootstrapConfig = {
   enabled: boolean;
@@ -50,6 +51,7 @@ export async function bootstrapGitHubRepository(targetDir: string, config: GitBo
   run(["gh", "repo", "create", repository, "--private", "--source", ".", "--remote", "origin", "--push"], targetDir, undefined, {
     quiet: true,
   });
+  protectMainBranch({ repo: repository, cwd: targetDir });
 
   return {
     status: "created",

package/src/github-protection.ts

@@ -0,0 +1,196 @@
+type CommandOptions = {
+  cwd?: string;
+  input?: string;
+};
+
+type CommandResult = {
+  success: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+
+export type CommandRunner = (command: string, args: string[], options?: CommandOptions) => CommandResult;
+
+export type ProtectionOptions = {
+  repo?: string;
+  branch?: string;
+  requiredChecks?: string[];
+  cwd?: string;
+  runner?: CommandRunner;
+};
+
+export type BranchProtectionRequest = {
+  required_status_checks: {
+    strict: boolean;
+    contexts: string[];
+  };
+  enforce_admins: boolean;
+  required_pull_request_reviews: {
+    dismiss_stale_reviews: boolean;
+    required_approving_review_count: number;
+  };
+  restrictions: null;
+  required_linear_history: boolean;
+  allow_force_pushes: boolean;
+  allow_deletions: boolean;
+  block_creations: boolean;
+  required_conversation_resolution: boolean;
+  lock_branch: boolean;
+  allow_fork_syncing: boolean;
+};
+
+const DEFAULT_BRANCH = "main";
+const DEFAULT_REQUIRED_CHECKS = ["test", "deploy"];
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+
+export function parseProtectMainArgs(argv: string[]) {
+  const parsed: Pick<ProtectionOptions, "repo" | "branch"> = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token) {
+      continue;
+    }
+
+    const next = argv[index + 1];
+    const readValue = () => {
+      if (!next || next.startsWith("-")) {
+        throw new Error(`Missing value for ${token}`);
+      }
+      index += 1;
+      return next;
+    };
+
+    if (token === "--repo") {
+      parsed.repo = readValue();
+      continue;
+    }
+
+    if (token.startsWith("--repo=")) {
+      parsed.repo = token.slice("--repo=".length);
+      continue;
+    }
+
+    if (token === "--branch") {
+      parsed.branch = readValue();
+      continue;
+    }
+
+    if (token.startsWith("--branch=")) {
+      parsed.branch = token.slice("--branch=".length);
+      continue;
+    }
+
+    throw new Error(`Unknown argument for protect-main: ${token}`);
+  }
+
+  return parsed;
+}
+
+export function protectMainBranch(options: ProtectionOptions = {}) {
+  const runner = options.runner ?? run;
+  const repo = normalizeRepo(options.repo ?? process.env.GITHUB_REPOSITORY ?? discoverRepo(runner, options.cwd));
+  const branch = options.branch ?? DEFAULT_BRANCH;
+  const requiredChecks = options.requiredChecks ?? DEFAULT_REQUIRED_CHECKS;
+  const request = buildBranchProtectionRequest(requiredChecks);
+  const endpoint = `/repos/${repo}/branches/${branch}/protection`;
+  const result = runner("gh", ["api", "--method", "PUT", endpoint, "--input", "-"], {
+    cwd: options.cwd,
+    input: `${JSON.stringify(request)}\n`,
+  });
+
+  if (!result.success) {
+    throw new Error(formatProtectionFailure(repo, branch, result));
+  }
+
+  return {
+    repo,
+    branch,
+    requiredChecks,
+  };
+}
+
+export function buildBranchProtectionRequest(requiredChecks = DEFAULT_REQUIRED_CHECKS): BranchProtectionRequest {
+  return {
+    required_status_checks: {
+      strict: true,
+      contexts: requiredChecks,
+    },
+    enforce_admins: true,
+    required_pull_request_reviews: {
+      dismiss_stale_reviews: true,
+      required_approving_review_count: 1,
+    },
+    restrictions: null,
+    required_linear_history: false,
+    allow_force_pushes: false,
+    allow_deletions: false,
+    block_creations: false,
+    required_conversation_resolution: true,
+    lock_branch: false,
+    allow_fork_syncing: true,
+  };
+}
+
+export function formatProtectionFailure(repo: string, branch: string, result: CommandResult) {
+  const details = [result.stderr, result.stdout].filter(Boolean).join("\n");
+  const permissionHint = isPermissionFailure(details)
+    ? [
+        "",
+        "The authenticated GitHub token must have repository administration permission for this generated service repo.",
+        "Grant repo admin access or a fine-grained token with Administration: write, then rerun `service protect-main`.",
+      ].join("\n")
+    : "";
+
+  return [`Failed to reconcile ${branch} branch protection for ${repo}.`, details, permissionHint].filter(Boolean).join("\n");
+}
+
+function discoverRepo(runner: CommandRunner, cwd?: string) {
+  const result = runner("git", ["config", "--get", "remote.origin.url"], { cwd });
+  if (!result.success || !result.stdout) {
+    throw new Error("Unable to determine GitHub repo. Pass --repo owner/name or set GITHUB_REPOSITORY.");
+  }
+  return result.stdout;
+}
+
+function normalizeRepo(value: string) {
+  const trimmed = value.trim();
+  const sshMatch = trimmed.match(/^git@github\.com:([^/]+\/[^/]+?)(?:\.git)?$/);
+  if (sshMatch?.[1]) {
+    return sshMatch[1];
+  }
+
+  const urlMatch = trimmed.match(/^https:\/\/github\.com\/([^/]+\/[^/]+?)(?:\.git)?$/);
+  if (urlMatch?.[1]) {
+    return urlMatch[1];
+  }
+
+  if (/^[^/\s]+\/[^/\s]+$/.test(trimmed)) {
+    return trimmed.replace(/\.git$/, "");
+  }
+
+  throw new Error(`Invalid GitHub repo: ${value}. Expected owner/name.`);
+}
+
+function isPermissionFailure(details: string) {
+  return /403|404|admin|administration|resource not accessible|not found|forbidden/i.test(details);
+}
+
+function run(command: string, args: string[], options: CommandOptions = {}): CommandResult {
+  const result = Bun.spawnSync([command, ...args], {
+    cwd: options.cwd ?? process.cwd(),
+    env: process.env,
+    stdin: options.input === undefined ? undefined : encoder.encode(options.input),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  return {
+    success: result.success,
+    stdout: result.stdout ? decoder.decode(result.stdout).trim() : "",
+    stderr: result.stderr ? decoder.decode(result.stderr).trim() : "",
+    exitCode: result.exitCode,
+  };
+}

package/src/scaffold.test.ts

@@ -195,6 +195,7 @@ test("scaffolds all runtime/framework variants with shared cloudrun config", asy
       expect(packageJson).toContain('"migrate": "service migrate"');
       expect(packageJson).toContain('"create": "service create"');
       expect(packageJson).toContain('"deploy": "service deploy"');
+      expect(packageJson).toContain('"protect-main": "service protect-main"');
       expect(packageJson).toContain('"destroy": "service destroy"');
 
       const mainGo = await Bun.file(join(generatedRoot, "cmd", "server", "main.go")).text();
@@ -224,6 +225,8 @@ test("scaffolds all runtime/framework variants with shared cloudrun config", asy
       expect(makefile).toContain("bun run ./scripts/ensure-local-db.ts");
       expect(makefile).toContain("bun run ./scripts/wait-for-db.ts");
       expect(makefile).toContain("bun run ./scripts/dev.ts go run ./cmd/server --worker go run ./cmd/worker");
+      expect(makefile).toContain("protect-main:");
+      expect(makefile).toContain("$(SERVICE) protect-main");
       expect(await Bun.file(join(generatedRoot, "atlas.hcl")).exists()).toBeTrue();
       const atlasConfig = await Bun.file(join(generatedRoot, "atlas.hcl")).text();
       expect(atlasConfig).toContain('revisions_schema = "public"');
@@ -241,6 +244,7 @@ test("scaffolds all runtime/framework variants with shared cloudrun config", asy
       expect(packageJson).toContain('"migrate": "service migrate"');
       expect(packageJson).toContain('"create": "service create"');
       expect(packageJson).toContain('"deploy": "service deploy"');
+      expect(packageJson).toContain('"protect-main": "service protect-main"');
       expect(packageJson).toContain('"dashboards": "service dashboards"');
       expect(packageJson).toContain('"observability-bootstrap": "service observability-bootstrap"');
       expect(packageJson).toContain('"auth": "service auth"');
@@ -260,6 +264,7 @@ test("scaffolds all runtime/framework variants with shared cloudrun config", asy
       expect(makefile).toContain("SERVICE := service");
       expect(makefile).toContain("dashboards:");
       expect(makefile).toContain("observability-bootstrap:");
+      expect(makefile).toContain("protect-main:");
       expect(makefile).toContain("auth:");
       expect(makefile).toContain("bun run dev");
       const devScript = await Bun.file(join(generatedRoot, "scripts", "dev.ts")).text();
@@ -295,6 +300,9 @@ test("scaffolds all runtime/framework variants with shared cloudrun config", asy
       expect(readme).toContain("verifies JWT bearer tokens");
       expect(readme).toContain("prod/apps/auth/authctl/cloudflare-access");
       expect(readme).toContain("service auth resource-server");
+      expect(readme).toContain("GitHub main branch protection");
+      expect(readme).toContain("service create");
+      expect(readme).toContain("service protect-main");
     }
 
   }
@@ -329,6 +337,8 @@ test("scaffolds a backend package cleanly into a nested monorepo-style directory
   expect(readme).toContain("waitlist/launch service");
   expect(readme).not.toContain("Neon main, preview, and personal branch provisioning");
   expect(readme).toContain("GitHub Actions deployment");
+  expect(readme).toContain("GitHub main branch protection");
+  expect(readme).toContain("service protect-main");
   expect(readme).toContain(".github/workflows/preview.yml");
   expect(readme).toContain(".github/workflows/deploy.yml");
   expect(readme).toContain("/deploy preview");
@@ -367,6 +377,7 @@ test("scaffolds the workers target with wrangler lifecycle commands", async () =
   expect(packageJson).toContain('"@anmho/authctl": "0.1.1"');
   expect(packageJson).toContain('"dev": "bun run ./scripts/dev.ts wrangler dev --ip 127.0.0.1 --port 8787 --show-interactive-dev-session=false"');
   expect(packageJson).toContain('"service": "service"');
+  expect(packageJson).toContain('"protect-main": "service protect-main"');
   expect(packageJson).toContain('"auth": "service auth"');
   expect(packageJson).toContain('"wrangler"');
   expect(packageJson).toContain('"pg"');
@@ -413,6 +424,7 @@ test("scaffolds the workers target with wrangler lifecycle commands", async () =
   const makefile = await Bun.file(join(generatedRoot, "Makefile")).text();
   expect(makefile).toContain('no generated code for workers');
   expect(makefile).toContain("auth:");
+  expect(makefile).toContain("protect-main:");
   expect(makefile).not.toContain("scripts/codegen.ts");
 
   expect(await Bun.file(join(generatedRoot, "scripts", "authctl.ts")).exists()).toBeFalse();

package/src/scaffold.ts

@@ -247,6 +247,7 @@ function buildReplacements(config: ScaffoldConfig) {
     COMMAND_DEV_DOWN: "service dev down",
     COMMAND_BOOTSTRAP: "service create",
     COMMAND_DEPLOY: "service deploy",
+    COMMAND_PROTECT_MAIN: "service protect-main",
     COMMAND_OBSERVABILITY_BOOTSTRAP:
       config.runtime === "bun" ? "bun run observability-bootstrap" : "make observability-bootstrap",
     WORKFLOW_DEPLOY_MAIN_COMMAND: "service deploy --ci",

package/src/service-diagnostics.test.ts

@@ -0,0 +1,46 @@
+import { expect, test } from "bun:test";
+import { buildServiceDoctorReport, findServiceBinaries } from "./service-diagnostics";
+
+test("findServiceBinaries finds service commands on a provided PATH", () => {
+  const binaries = findServiceBinaries({
+    pathEnv: ["/old/bin", "/fresh/bin", "/missing/bin"].join(":"),
+    isExecutable: (path) => path === "/old/bin/service" || path === "/fresh/bin/service",
+  });
+
+  expect(binaries).toEqual(["/old/bin/service", "/fresh/bin/service"]);
+});
+
+test("buildServiceDoctorReport includes the active binary, package root, and version", () => {
+  const report = buildServiceDoctorReport({
+    activeBinaryPath: "/fresh/bin/service",
+    packageRoot: "/fresh/lib/node_modules/create-svc",
+    packageVersion: "0.1.77",
+    latestVersion: "0.1.77",
+    serviceBinaries: ["/fresh/bin/service"],
+    getBinaryVersion: () => "0.1.77",
+  });
+
+  expect(report.exitCode).toBe(0);
+  expect(report.text).toContain("active binary: /fresh/bin/service");
+  expect(report.text).toContain("package root: /fresh/lib/node_modules/create-svc");
+  expect(report.text).toContain("package version: 0.1.77");
+  expect(report.text).toContain("npm latest: 0.1.77");
+});
+
+test("buildServiceDoctorReport warns when stale service binaries are also on PATH", () => {
+  const report = buildServiceDoctorReport({
+    activeBinaryPath: "/fresh/bin/service",
+    packageRoot: "/fresh/lib/node_modules/create-svc",
+    packageVersion: "0.1.77",
+    latestVersion: "0.1.77",
+    serviceBinaries: ["/opt/homebrew/bin/service", "/fresh/bin/service"],
+    getBinaryVersion: (path) => (path === "/opt/homebrew/bin/service" ? "0.1.10" : "0.1.77"),
+  });
+
+  expect(report.exitCode).toBe(1);
+  expect(report.text).toContain("warning: multiple service binaries found on PATH");
+  expect(report.text).toContain("/opt/homebrew/bin/service");
+  expect(report.text).toContain("version: 0.1.10 (stale)");
+  expect(report.text).toContain('cleanup: rm "/opt/homebrew/bin/service"');
+  expect(report.text).toContain("update: npm install -g create-svc@latest");
+});

package/src/service-diagnostics.ts

@@ -0,0 +1,170 @@
+import { accessSync, constants, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+type FindServiceBinariesOptions = {
+  pathEnv?: string;
+  commandName?: string;
+  isExecutable?: (path: string) => boolean;
+};
+
+type BuildServiceDoctorReportOptions = {
+  activeBinaryPath: string;
+  packageRoot: string;
+  packageVersion: string;
+  latestVersion?: string;
+  latestVersionError?: string;
+  serviceBinaries: string[];
+  getBinaryVersion: (path: string) => string | undefined;
+};
+
+type DoctorReport = {
+  exitCode: number;
+  text: string;
+};
+
+const PACKAGE_NAME = "create-svc";
+const SERVICE_COMMAND = "service";
+
+export function packageRootFromModuleUrl(moduleUrl: string) {
+  return resolve(dirname(fileURLToPath(moduleUrl)), "..");
+}
+
+export function readPackageVersion(packageRoot: string) {
+  const packageJson = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")) as { version?: string };
+  return packageJson.version ?? "unknown";
+}
+
+export function findServiceBinaries(options: FindServiceBinariesOptions = {}) {
+  const commandName = options.commandName ?? SERVICE_COMMAND;
+  const isExecutable = options.isExecutable ?? defaultIsExecutable;
+  const seen = new Set<string>();
+  const results: string[] = [];
+
+  for (const entry of (options.pathEnv ?? process.env.PATH ?? "").split(":")) {
+    if (!entry) {
+      continue;
+    }
+
+    const candidate = join(entry, commandName);
+    if (seen.has(candidate)) {
+      continue;
+    }
+    seen.add(candidate);
+
+    if (isExecutable(candidate)) {
+      results.push(candidate);
+    }
+  }
+
+  return results;
+}
+
+export function buildServiceDoctorReport(options: BuildServiceDoctorReportOptions): DoctorReport {
+  const lines = [
+    "service doctor",
+    `active binary: ${options.activeBinaryPath}`,
+    `package root: ${options.packageRoot}`,
+    `package version: ${options.packageVersion}`,
+  ];
+
+  if (options.latestVersion) {
+    lines.push(`npm latest: ${options.latestVersion}`);
+  } else if (options.latestVersionError) {
+    lines.push(`npm latest: unavailable (${options.latestVersionError})`);
+  } else {
+    lines.push("npm latest: unavailable");
+  }
+
+  const binaries = uniquePaths(options.serviceBinaries);
+  const binaryDiagnostics = binaries.map((path) => {
+    const version = options.getBinaryVersion(path);
+    const stale = Boolean(version && options.latestVersion && compareVersions(version, options.latestVersion) < 0);
+    return { path, version, stale };
+  });
+
+  const staleBinaries = binaryDiagnostics.filter((binary) => binary.stale);
+  if (binaryDiagnostics.length > 1) {
+    lines.push("");
+    lines.push("warning: multiple service binaries found on PATH");
+    for (const binary of binaryDiagnostics) {
+      const version = binary.version ?? "unknown";
+      const state = binary.stale ? "stale" : binary.version && options.latestVersion ? "current" : "unknown";
+      lines.push(`- ${binary.path}`);
+      lines.push(`  version: ${version} (${state})`);
+      if (binary.stale) {
+        lines.push(`  cleanup: rm "${binary.path}"`);
+        lines.push(`  update: npm install -g ${PACKAGE_NAME}@latest`);
+      }
+    }
+  }
+
+  return {
+    exitCode: staleBinaries.length > 0 ? 1 : 0,
+    text: lines.join("\n"),
+  };
+}
+
+export function getInstalledServiceVersion(binaryPath: string) {
+  const result = safeSpawn([binaryPath, "--version"]);
+
+  if (!result || !result.success || !result.stdout) {
+    return undefined;
+  }
+
+  return new TextDecoder().decode(result.stdout).trim().match(/\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?/)?.[0];
+}
+
+export function getNpmLatestVersion() {
+  const result = safeSpawn(["npm", "view", `${PACKAGE_NAME}@latest`, "version"]);
+
+  if (!result || !result.success || !result.stdout) {
+    const stderr = result?.stderr ? new TextDecoder().decode(result.stderr).trim() : "npm view failed";
+    return { error: stderr || "npm view failed" };
+  }
+
+  return { version: new TextDecoder().decode(result.stdout).trim() };
+}
+
+function safeSpawn(command: string[]) {
+  try {
+    return Bun.spawnSync(command, {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+export function compareVersions(left: string, right: string) {
+  const leftParts = parseVersion(left);
+  const rightParts = parseVersion(right);
+
+  for (let i = 0; i < 3; i += 1) {
+    const diff = (leftParts[i] ?? 0) - (rightParts[i] ?? 0);
+    if (diff !== 0) {
+      return diff;
+    }
+  }
+
+  return 0;
+}
+
+function parseVersion(version: string): [number, number, number] {
+  const [major = "0", minor = "0", patch = "0"] = version.split(/[.-]/, 3);
+  return [Number(major) || 0, Number(minor) || 0, Number(patch) || 0];
+}
+
+function uniquePaths(paths: string[]) {
+  return [...new Set(paths)];
+}
+
+function defaultIsExecutable(path: string) {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -31,7 +31,7 @@ describe("local dev cleanup", () => {
   });
 
   test("stops service-owned listeners when the pid file is missing", async () => {
-    if (!Bun.which("lsof")) {
+    if (!Bun.which("lsof") && !(process.platform === "linux" && Bun.which("fuser"))) {
       return;
     }
 
@@ -126,6 +126,10 @@ async function isReachable(port: number) {
 }
 
 function listenerHasPid(port: number, pid: number) {
+  if (!Bun.which("lsof")) {
+    return false;
+  }
+
   const result = Bun.spawnSync(["lsof", "-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-Fp"], {
     stdout: "pipe",
     stderr: "pipe",

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

@@ -144,10 +144,6 @@ function waitForExit(pid: number, timeoutMs: number) {
 }
 
 function findServicePortProcesses(root: string, ports: number[], pidFromFile?: number): PortProcess[] {
-  if (!Bun.which("lsof")) {
-    return [];
-  }
-
   const resolvedRoot = realpath(root);
   const rootWithSlash = resolvedRoot.endsWith("/") ? resolvedRoot : `${resolvedRoot}/`;
   const seen = new Set<string>();
@@ -180,6 +176,21 @@ function realpath(path: string) {
 }
 
 function listeningPids(port: number) {
+  const pids = new Set<number>();
+  for (const pid of listeningPidsFromLsof(port)) {
+    pids.add(pid);
+  }
+  for (const pid of listeningPidsFromFuser(port)) {
+    pids.add(pid);
+  }
+  return [...pids];
+}
+
+function listeningPidsFromLsof(port: number) {
+  if (!Bun.which("lsof")) {
+    return [];
+  }
+
   const result = Bun.spawnSync(["lsof", "-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-Fp"], {
     stdout: "pipe",
     stderr: "pipe",
@@ -194,6 +205,26 @@ function listeningPids(port: number) {
     .filter((pid): pid is number => Boolean(pid && Number.isFinite(pid)));
 }
 
+function listeningPidsFromFuser(port: number) {
+  if (process.platform !== "linux" || !Bun.which("fuser")) {
+    return [];
+  }
+
+  const result = Bun.spawnSync(["fuser", "-n", "tcp", String(port)], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (!result.success) {
+    return [];
+  }
+  return decoder
+    .decode(result.stdout)
+    .trim()
+    .split(/\s+/)
+    .map((value) => Number.parseInt(value, 10))
+    .filter((pid): pid is number => Boolean(pid && Number.isFinite(pid)));
+}
+
 function processCwd(pid: number) {
   if (process.platform === "linux") {
     const procCwd = realpath(`/proc/${pid}/cwd`);

package/src/service.test.ts

@@ -30,6 +30,7 @@ test("createSvcVersion reports the package version", async () => {
 test("formatOutsideServiceCommandError rejects repo-local commands outside generated services", () => {
   expect(formatOutsideServiceCommandError("destroy")).toContain("service destroy must be run inside a generated service repo");
   expect(formatOutsideServiceCommandError("deploy")).toContain("No service.jsonc was found");
+  expect(formatOutsideServiceCommandError("protect-main")).toContain("service protect-main must be run inside a generated service repo");
 });
 
 test("formatOutsideServiceCommandError does not treat positional names as scaffold commands", () => {
@@ -66,3 +67,9 @@ test("generatedServiceCommandHelp intercepts deploy help before side effects", (
   expect(generatedServiceCommandHelp(["deploy"])).toBeUndefined();
   expect(generatedServiceCommandHelp(["destroy", "--help"])).toBeUndefined();
 });
+
+test("generatedServiceCommandHelp intercepts protect-main help before side effects", () => {
+  expect(generatedServiceCommandHelp(["protect-main", "--help"])).toContain("service protect-main");
+  expect(generatedServiceCommandHelp(["protect-main", "-h"])).toContain("--repo owner/name");
+  expect(generatedServiceCommandHelp(["protect-main"])).toBeUndefined();
+});

package/src/service.ts

@@ -1,7 +1,15 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { formatScaffoldHelp, run as runScaffoldCli } from "./cli";
+import { parseProtectMainArgs, protectMainBranch } from "./github-protection";
 import { parseJsonc } from "./jsonc";
+import {
+  buildServiceDoctorReport,
+  findServiceBinaries,
+  getInstalledServiceVersion,
+  getNpmLatestVersion,
+  packageRootFromModuleUrl,
+} from "./service-diagnostics";
 
 const SCAFFOLD_COMMANDS = new Set(["create", "new", "init"]);
 const GENERATED_SERVICE_COMMANDS = new Set([
@@ -14,6 +22,7 @@ const GENERATED_SERVICE_COMMANDS = new Set([
   "dns",
   "doctor",
   "migrate",
+  "protect-main",
   "sdk",
   "seed",
 ]);
@@ -41,6 +50,11 @@ export async function runServiceCommand(argv: string[], cwd = process.cwd()) {
     return;
   }
 
+  if (command === "doctor") {
+    runGlobalServiceDoctor();
+    return;
+  }
+
   console.error(formatOutsideServiceCommandError(command));
   process.exit(1);
 }
@@ -54,6 +68,23 @@ export function createSvcVersion() {
   return packageJson.version || "unknown";
 }
 
+function runGlobalServiceDoctor() {
+  const latest = getNpmLatestVersion();
+  const report = buildServiceDoctorReport({
+    activeBinaryPath: process.argv[1] || "service",
+    packageRoot: packageRootFromModuleUrl(import.meta.url),
+    packageVersion: createSvcVersion(),
+    latestVersion: latest.version,
+    latestVersionError: latest.error,
+    serviceBinaries: findServiceBinaries(),
+    getBinaryVersion: getInstalledServiceVersion,
+  });
+  console.log(report.text);
+  if (report.exitCode !== 0) {
+    process.exit(report.exitCode);
+  }
+}
+
 export function normalizeScaffoldArgs(argv: string[]) {
   const [command, ...rest] = argv;
   if (command && SCAFFOLD_COMMANDS.has(command)) {
@@ -109,7 +140,25 @@ async function delegateToGeneratedService(serviceRoot: string, argv: string[]) {
   process.chdir(serviceRoot);
   process.env.CREATE_SVC_SERVICE_ROOT = serviceRoot;
 
-  const serviceConfig = parseJsonc(await Bun.file(join(serviceRoot, "service.jsonc")).text()) as { target?: string };
+  const serviceConfig = parseJsonc(await Bun.file(join(serviceRoot, "service.jsonc")).text()) as {
+    service_id?: string;
+    target?: string;
+    git?: {
+      owner?: string;
+      repository?: string;
+    };
+  };
+  if (argv[0] === "protect-main") {
+    const protectionArgs = parseProtectMainArgs(argv.slice(1));
+    const result = protectMainBranch({
+      repo: protectionArgs.repo ?? repoFromServiceConfig(serviceConfig),
+      branch: protectionArgs.branch,
+      cwd: serviceRoot,
+    });
+    console.log(`Protected ${result.repo} ${result.branch} with required checks: ${result.requiredChecks.join(", ")}`);
+    return;
+  }
+
   if (serviceConfig.target === "workers") {
     const { main } = await import("./service-runtime/workers/cli");
     await main(argv);
@@ -120,6 +169,15 @@ async function delegateToGeneratedService(serviceRoot: string, argv: string[]) {
   await main(argv);
 }
 
+function repoFromServiceConfig(serviceConfig: { service_id?: string; git?: { owner?: string; repository?: string } }) {
+  const owner = serviceConfig.git?.owner || "anmho";
+  const repository = serviceConfig.git?.repository || serviceConfig.service_id;
+  if (!repository) {
+    throw new Error("service.jsonc is missing git.repository and service_id; pass --repo owner/name.");
+  }
+  return `${owner}/${repository}`;
+}
+
 export function generatedDependenciesInstalled(serviceRoot: string) {
   return !existsSync(join(serviceRoot, "package.json")) || existsSync(join(serviceRoot, "node_modules"));
 }
@@ -146,6 +204,15 @@ function ensureGeneratedDependencies(serviceRoot: string) {
 
 export function generatedServiceCommandHelp(argv: string[]) {
   const [command, ...rest] = argv;
+  if (command === "protect-main" && hasHelpFlag(rest)) {
+    return [
+      "Usage:",
+      "  service protect-main [--repo owner/name] [--branch main]",
+      "",
+      "Reconciles generated service branch protection with required test and deploy checks.",
+    ].join("\n");
+  }
+
   if (command !== "deploy" || !hasHelpFlag(rest)) {
     return undefined;
   }

package/templates/shared/README.md

@@ -31,6 +31,7 @@ console to create and deploy.
 {{COMMAND_TEST}}
 {{COMMAND_BOOTSTRAP}}
 {{COMMAND_DEPLOY}}
+{{COMMAND_PROTECT_MAIN}}
 {{COMMAND_DEV_DOWN}}
 {{COMMAND_AUTH_RESOURCE}}
 {{COMMAND_AUTH_CLIENT}}
@@ -145,6 +146,16 @@ gcloud auth application-default login
 
 The generated backend scripts still use `gcloud` as the primary control plane even when ADC is present.
 
+## GitHub main branch protection
+
+Generated repositories include GitHub Actions workflows for CI and production deploys. `service create` reconciles `main` branch protection after creating and pushing the GitHub repository. To rerun reconciliation for an existing generated repo:
+
+```bash
+{{COMMAND_PROTECT_MAIN}}
+```
+
+The protection requires the generated `test` and `deploy` status checks, pull requests, stale-review dismissal, conversation resolution, and admin enforcement. If GitHub permissions are missing, rerun the command with a token that has repo admin access or fine-grained `Administration: write`.
+
 Go variants use Atlas for migrations:
 
 ```bash

package/templates/targets/workers/Makefile

@@ -1,4 +1,4 @@
-.PHONY: dev migrate gen lint test create deploy dashboards auth destroy
+.PHONY: dev migrate gen lint test create deploy protect-main dashboards auth destroy
 
 SERVICE := service
 
@@ -23,6 +23,9 @@ create:
 deploy:
 	$(SERVICE) deploy $(ARGS)
 
+protect-main:
+	$(SERVICE) protect-main $(ARGS)
+
 dashboards:
 	$(SERVICE) dashboards
 

package/templates/targets/workers/README.md

@@ -22,6 +22,7 @@ bun run trigger -- --help
 bun run trigger:dev
 service create
 service deploy
+{{COMMAND_PROTECT_MAIN}}
 bun run dashboards
 bun run doctor
 bun run destroy
@@ -70,6 +71,16 @@ Worker deploy and fail clearly if these values are missing.
 GitHub Actions deploys require matching repository secrets:
 `TRIGGER_PROJECT_REF`, `TRIGGER_ACCESS_TOKEN`, and `TRIGGER_SECRET_KEY`.
 
+## GitHub main branch protection
+
+Generated repositories include GitHub Actions workflows for CI and production deploys. `service create` reconciles `main` branch protection after creating and pushing the GitHub repository. To rerun reconciliation for an existing generated repo:
+
+```bash
+{{COMMAND_PROTECT_MAIN}}
+```
+
+The protection requires the generated `test` and `deploy` status checks, pull requests, stale-review dismissal, conversation resolution, and admin enforcement. If GitHub permissions are missing, rerun the command with a token that has repo admin access or fine-grained `Administration: write`.
+
 The Trigger.dev CLI is installed in this generated package as a dev dependency
 from the `trigger.dev` npm package.
 Use `bun run trigger -- <args>` for ad-hoc commands, `bun run trigger:dev` for

package/templates/targets/workers/package.json

@@ -11,6 +11,7 @@
     "test": "bun test",
     "create": "service create",
     "deploy": "service deploy",
+    "protect-main": "service protect-main",
     "dashboards": "service dashboards",
     "auth": "service auth",
     "destroy": "service destroy",

package/templates/variants/bun-connectrpc/Makefile

@@ -1,4 +1,4 @@
-.PHONY: dev migrate gen lint test create deploy dashboards observability-bootstrap auth destroy
+.PHONY: dev migrate gen lint test create deploy protect-main dashboards observability-bootstrap auth destroy
 
 SERVICE := service
 
@@ -23,6 +23,9 @@ create:
 deploy:
 	$(SERVICE) deploy $(ARGS)
 
+protect-main:
+	$(SERVICE) protect-main $(ARGS)
+
 dashboards:
 	$(SERVICE) dashboards
 

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

@@ -11,6 +11,7 @@
     "test": "bun test",
     "create": "service create",
     "deploy": "service deploy",
+    "protect-main": "service protect-main",
     "dashboards": "service dashboards",
     "observability-bootstrap": "service observability-bootstrap",
     "auth": "service auth",

package/templates/variants/bun-hono/Makefile

@@ -1,4 +1,4 @@
-.PHONY: dev migrate gen lint test create deploy dashboards observability-bootstrap auth destroy
+.PHONY: dev migrate gen lint test create deploy protect-main dashboards observability-bootstrap auth destroy
 
 SERVICE := service
 
@@ -23,6 +23,9 @@ create:
 deploy:
 	$(SERVICE) deploy $(ARGS)
 
+protect-main:
+	$(SERVICE) protect-main $(ARGS)
+
 dashboards:
 	$(SERVICE) dashboards
 

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

@@ -11,6 +11,7 @@
     "test": "bun test",
     "create": "service create",
     "deploy": "service deploy",
+    "protect-main": "service protect-main",
     "dashboards": "service dashboards",
     "observability-bootstrap": "service observability-bootstrap",
     "auth": "service auth",

package/templates/variants/go-chi/Makefile

@@ -1,4 +1,4 @@
-.PHONY: dev migrate migrate-lint gen lint test create deploy dashboards observability-bootstrap auth destroy
+.PHONY: dev migrate migrate-lint gen lint test create deploy protect-main dashboards observability-bootstrap auth destroy
 
 SERVICE := service
 WITH_ENV := set -a; [ ! -f .env.local ] || . ./.env.local; set +a;
@@ -33,6 +33,9 @@ create:
 deploy:
 	$(SERVICE) deploy $(ARGS)
 
+protect-main:
+	$(SERVICE) protect-main $(ARGS)
+
 dashboards:
 	$(SERVICE) dashboards
 

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

@@ -11,6 +11,7 @@
     "test": "make test",
     "create": "service create",
     "deploy": "service deploy",
+    "protect-main": "service protect-main",
     "auth": "service auth",
     "dashboards": "service dashboards",
     "destroy": "service destroy"

package/templates/variants/go-connectrpc/Makefile

@@ -1,4 +1,4 @@
-.PHONY: dev migrate migrate-lint gen lint test create deploy dashboards observability-bootstrap auth destroy
+.PHONY: dev migrate migrate-lint gen lint test create deploy protect-main dashboards observability-bootstrap auth destroy
 
 SERVICE := service
 WITH_ENV := set -a; [ ! -f .env.local ] || . ./.env.local; set +a;
@@ -34,6 +34,9 @@ create:
 deploy:
 	$(SERVICE) deploy $(ARGS)
 
+protect-main:
+	$(SERVICE) protect-main $(ARGS)
+
 dashboards:
 	$(SERVICE) dashboards
 

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

@@ -11,6 +11,7 @@
     "test": "make test",
     "create": "service create",
     "deploy": "service deploy",
+    "protect-main": "service protect-main",
     "auth": "service auth",
     "dashboards": "service dashboards",
     "destroy": "service destroy"