create-svc 0.1.13 → 0.1.15

package/src/cli.ts

@@ -1,22 +1,15 @@
-import {
-  autocomplete,
-  cancel,
-  confirm,
-  intro,
-  isCancel,
-  log,
-  note,
-  outro,
-  select,
-  spinner,
-  text,
-} from "@clack/prompts";
+import { autocomplete, cancel, intro, isCancel, log, note, outro, select, spinner, text } from "@clack/prompts";
 import pc from "picocolors";
 import { readdirSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { runPostScaffoldFlow } from "./post-scaffold";
-import { bootstrapGitHubRepository, buildGitBootstrapConfig, commitAndPushGeneratedArtifacts } from "./git-bootstrap";
+import { buildDeploymentVerificationCommands, runPostScaffoldFlow } from "./post-scaffold";
+import {
+  bootstrapGitHubRepository,
+  buildGitBootstrapConfig,
+  commitAndPushGeneratedArtifacts,
+  type GitBootstrapResult,
+} from "./git-bootstrap";
 import { listOpenBillingAccounts, listAccessibleProjects, type BillingAccount, type GcpProject } from "./gcp";
 import {
   BILLING_ACCOUNT_DEFAULT,
@@ -39,6 +32,7 @@ import {
 } from "./scaffold";
 
 type ParsedArgs = {
+  serviceName?: string;
   directory?: string;
   target?: DeployTarget;
   runtime?: Runtime;
@@ -50,8 +44,6 @@ type ParsedArgs = {
   billingAccount?: string;
   quotaProjectId?: string;
   autoDeploy?: boolean;
-  autoUpdate?: boolean;
-  noUpdateCheck?: boolean;
   noGit?: boolean;
   profile: Profile;
   yes: boolean;
@@ -64,7 +56,25 @@ type DiscoveryState = {
   warnings: string[];
 };
 
+type GcpSelection = {
+  mode: GcpProjectMode;
+  projectId: string;
+  projectName: string;
+};
+
+type InteractiveStep = "serviceName" | "target" | "runtime" | "framework" | "modulePath" | "gcp" | "confirm";
+
+type InteractiveState = {
+  serviceName?: string;
+  target?: DeployTarget;
+  runtime?: Runtime;
+  framework?: Framework;
+  modulePath?: string;
+  gcpSelection?: GcpSelection;
+};
+
 const DEFAULT_REGION = "us-west1";
+const BACK = "__back__" as const;
 
 export async function run(argv: string[]) {
   try {
@@ -74,8 +84,6 @@ export async function run(argv: string[]) {
       return;
     }
 
-    await maybeCheckForUpdate(args);
-
     intro(`${pc.bold("service")} ${pc.dim("microservice bootstrap")}`);
 
     const config = await resolveConfig(args);
@@ -130,27 +138,75 @@ export async function run(argv: string[]) {
       }
     }
 
-    const isBun = config.runtime === "bun";
-    outro(
-      [
-        `Next: ${pc.cyan(`cd ${config.directory}`)}`,
-        `Local DB: ${pc.cyan("started by local dev command")}`,
-        `Migrate: ${pc.cyan(isBun ? "bun run migrate" : "make migrate")}`,
-        `Local dev: ${pc.cyan(isBun ? "bun run dev" : "make dev")}`,
-        `Create: ${pc.cyan("service create")}`,
-        `Deploy: ${pc.cyan("service deploy")}`,
-        config.git.enabled ? `Repository: ${pc.cyan(`https://github.com/anmho/${config.git.repository}`)}` : undefined,
-        `Personal env: ${pc.cyan(
-          `service deploy --environment personal --name ${config.serviceName}`
-        )}`,
-        `Production API: ${pc.cyan(`https://${config.apiHostname}`)}`,
-      ].filter(Boolean).join("\n")
-    );
+    outro(config.autoDeploy ? "Created and deployed" : "Created");
+    console.log(formatCompletionSummary(config, targetDir, gitResult));
   } catch (error) {
     handleCliError(error);
   }
 }
 
+function formatCompletionSummary(config: ScaffoldConfig, targetDir: string, gitResult: GitBootstrapResult) {
+  const isBun = config.runtime === "bun";
+  const devCommand = isBun ? "bun run dev" : "make dev";
+  const migrateCommand = isBun ? "bun run migrate" : "make migrate";
+  const lifecycleCommands: Array<[string, string]> = config.autoDeploy
+    ? [
+        ["service deploy", "Deploys later changes."],
+        [`service deploy --environment personal --name ${config.serviceName}`, "Deploys your personal environment."],
+      ]
+    : [
+        ["service create", "Provisions auth, database, migrations, and the first deploy."],
+        ["service deploy", "Deploys later changes."],
+      ];
+  const repository =
+    gitResult.status === "created"
+      ? gitResult.url
+      : config.git.enabled
+        ? `https://github.com/${config.git.owner}/${config.git.repository}`
+        : undefined;
+
+  return [
+    "",
+    `Success! Created ${config.serviceName} at ${targetDir}`,
+    "",
+    "Inside that directory, you can run:",
+    formatCommand(devCommand, "Starts local development."),
+    formatCommand(migrateCommand, "Applies local database migrations."),
+    ...lifecycleCommands.map(([command, description]) => formatCommand(command, description)),
+    "",
+    "Control-plane defaults:",
+    `  Auth issuer: https://auth.anmho.com/api/auth`,
+    `  Auth resource: api://${config.serviceName}`,
+    `  Auth token URL: https://auth.anmho.com/api/auth/oauth2/token`,
+    `  Temporal: disabled by default`,
+    `  Temporal address: localhost:7233`,
+    `  Temporal task queue: ${config.serviceName}`,
+    `  Temporal API key secret: ${config.serviceName}-temporal-api-key`,
+    config.runtime === "go" ? `  Go module: ${config.modulePath}` : undefined,
+    "",
+    config.autoDeploy ? "Verified after deploy:" : "After deploy, verify with:",
+    ...buildDeploymentVerificationCommands(config).map(formatShellCommand),
+    "",
+    "We suggest that you begin by typing:",
+    "",
+    `  cd ${config.directory}`,
+    `  ${devCommand}`,
+    "",
+    repository ? `Repository: ${repository}` : undefined,
+    `Production API: https://${config.apiHostname}`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function formatCommand(command: string, description: string) {
+  return [`  ${command}`, `    ${description}`].join("\n");
+}
+
+function formatShellCommand(command: { command: string; args: string[] }) {
+  return `  ${[command.command, ...command.args].join(" ")}`;
+}
+
 export function parseArgs(argv: string[]): ParsedArgs {
   const parsed: ParsedArgs = {
     profile: "microservice",
@@ -164,8 +220,8 @@ export function parseArgs(argv: string[]): ParsedArgs {
       continue;
     }
 
-    if (!token.startsWith("-") && !parsed.directory) {
-      parsed.directory = token;
+    if (!token.startsWith("-") && !parsed.serviceName) {
+      parsed.serviceName = token;
       continue;
     }
 
@@ -188,23 +244,23 @@ export function parseArgs(argv: string[]): ParsedArgs {
       continue;
     }
 
-    if (token === "--auto-update") {
-      parsed.autoUpdate = true;
+    if (token === "--no-git") {
+      parsed.noGit = true;
       continue;
     }
 
-    if (token === "--no-update-check") {
-      parsed.noUpdateCheck = true;
+    if (token === "--runtime") {
+      parsed.runtime = readValue() as Runtime;
       continue;
     }
 
-    if (token === "--no-git") {
-      parsed.noGit = true;
+    if (token === "--dir") {
+      parsed.directory = readValue();
       continue;
     }
 
-    if (token === "--runtime") {
-      parsed.runtime = readValue() as Runtime;
+    if (token.startsWith("--dir=")) {
+      parsed.directory = token.slice("--dir=".length);
       continue;
     }
 
@@ -324,74 +380,13 @@ export function parseArgs(argv: string[]): ParsedArgs {
   return parsed;
 }
 
-const CURRENT_VERSION = "0.1.9";
-const PACKAGE_NAME = "create-svc";
-
-async function maybeCheckForUpdate(args: ParsedArgs) {
-  if (args.noUpdateCheck || shouldSkipUpdateCheck()) {
-    return;
-  }
-
-  const latest = await resolveLatestVersion().catch(() => "");
-  if (!latest || !isVersionGreater(latest, CURRENT_VERSION)) {
-    return;
-  }
-
-  const command = `bunx ${PACKAGE_NAME}@latest ${Bun.argv.slice(2).filter((arg) => arg !== "--auto-update").join(" ")}`.trim();
-  if (!args.autoUpdate) {
-    log.info(`A newer ${PACKAGE_NAME} is available: ${CURRENT_VERSION} -> ${latest}. Run ${command}`);
-    return;
-  }
-
-  const result = Bun.spawnSync(["bunx", `${PACKAGE_NAME}@latest`, ...Bun.argv.slice(2).filter((arg) => arg !== "--auto-update")], {
-    stdin: "inherit",
-    stdout: "inherit",
-    stderr: "inherit",
-    env: {
-      ...process.env,
-      CREATE_SERVICE_NO_UPDATE_CHECK: "1",
-    },
-  });
-  process.exit(result.exitCode);
-}
-
-function shouldSkipUpdateCheck() {
-  return Boolean(
-    process.env.CI ||
-      process.env.CODEX_CI ||
-      process.env.CREATE_SERVICE_NO_UPDATE_CHECK ||
-      process.env.BUN_TEST ||
-      process.env.npm_lifecycle_event
-  );
-}
-
-async function resolveLatestVersion() {
-  const response = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
-    signal: AbortSignal.timeout(1_500),
-  });
-  if (!response.ok) {
-    return "";
+export async function resolveConfig(args: ParsedArgs): Promise<ScaffoldConfig> {
+  const inferredName = slugify(args.serviceName ?? basename(args.directory ?? "my-service"));
+  if (!args.yes) {
+    return resolveInteractiveConfig(args, inferredName);
   }
-  const payload = (await response.json()) as { version?: string };
-  return payload.version?.trim() ?? "";
-}
-
-function isVersionGreater(left: string, right: string) {
-  const parse = (value: string) => value.split(".").map((part) => Number.parseInt(part, 10) || 0);
-  const [leftMajor = 0, leftMinor = 0, leftPatch = 0] = parse(left);
-  const [rightMajor = 0, rightMinor = 0, rightPatch = 0] = parse(right);
-  return (
-    leftMajor > rightMajor ||
-    (leftMajor === rightMajor && leftMinor > rightMinor) ||
-    (leftMajor === rightMajor && leftMinor === rightMinor && leftPatch > rightPatch)
-  );
-}
 
-export async function resolveConfig(args: ParsedArgs): Promise<ScaffoldConfig> {
-  const inferredName = slugify(basename(args.directory ?? "my-service"));
-  const serviceName = args.yes
-    ? inferredName
-    : await promptText("Service name", inferredName, (value) => validateServiceNameInput(value, args.directory));
+  const serviceName = inferredName;
   const directory = args.directory ?? serviceName;
   const targetDir = resolve(process.cwd(), directory);
   await assertTargetDirectoryIsEmpty(targetDir);
@@ -405,22 +400,14 @@ export async function resolveConfig(args: ParsedArgs): Promise<ScaffoldConfig> {
   const modulePath = await resolveModulePath(args, runtime, defaults.modulePath);
   const discovery = await waitForDiscovery(discoveryPromise);
   const gcpSelection = await resolveGcpSelection(args, defaults, discovery);
+  if (gcpSelection === BACK) {
+    throw new Error("Unexpected back navigation in non-interactive config");
+  }
   const region = args.region ?? DEFAULT_REGION;
   const billingAccount = chooseBillingAccount(args.billingAccount, discovery.billingAccounts);
   const autoDeploy = resolveAutoDeploy(args.autoDeploy);
   const git = buildGitBootstrapConfig(serviceName, args.noGit);
 
-  if (!args.yes) {
-    const okay = await confirm({
-      message: "Create the scaffold with these defaults?",
-      initialValue: true,
-    });
-    if (isCancel(okay) || !okay) {
-      cancel("Aborted");
-      process.exit(1);
-    }
-  }
-
   for (const warning of discovery.warnings) {
     log.warn(warning);
   }
@@ -447,6 +434,226 @@ export async function resolveConfig(args: ParsedArgs): Promise<ScaffoldConfig> {
   };
 }
 
+async function resolveInteractiveConfig(args: ParsedArgs, initialServiceName: string): Promise<ScaffoldConfig> {
+  const state: InteractiveState = {
+    serviceName: args.serviceName ? slugify(args.serviceName) : undefined,
+    target: args.target,
+    runtime: args.runtime,
+    framework: args.framework,
+    modulePath: args.modulePath,
+  };
+  let serviceNameDraft = state.serviceName ?? initialServiceName;
+  let discovery: DiscoveryState | undefined;
+  const discoveryPromise = discoverCloudInputs();
+  let step: InteractiveStep = state.serviceName ? "target" : "serviceName";
+
+  while (true) {
+    if (step === "serviceName") {
+      const value = await promptText("Service name", serviceNameDraft, (input) => validateServiceNameInput(input, args.directory));
+      serviceNameDraft = value;
+      state.serviceName = value;
+      step = "target";
+      continue;
+    }
+
+    if (!state.serviceName) {
+      step = "serviceName";
+      continue;
+    }
+
+    const defaults = deriveDefaults(state.serviceName);
+
+    if (step === "target") {
+      if (args.target) {
+        state.target = args.target;
+      } else {
+        const value = await promptSelectWithBack<DeployTarget>(
+          "Deploy target",
+          [
+            { value: "cloudrun", label: "Cloud Run", hint: "Default" },
+            { value: "workers", label: "Cloudflare Workers" },
+          ],
+          "cloudrun",
+          step,
+          args,
+          state
+        );
+        if (value === BACK) {
+          step = previousPromptStep(step, args, state) ?? step;
+          continue;
+        }
+        state.target = value;
+        state.runtime = undefined;
+        state.framework = undefined;
+      }
+      step = "runtime";
+      continue;
+    }
+
+    if (step === "runtime") {
+      if (!state.target) {
+        step = "target";
+        continue;
+      }
+      if (state.target === "workers") {
+        state.runtime = "bun";
+      } else if (args.runtime) {
+        state.runtime = args.runtime;
+      } else {
+        const value = await promptSelectWithBack<Runtime>(
+          "Runtime",
+          [
+            { value: "go", label: "Go", hint: "Default" },
+            { value: "bun", label: "Bun" },
+          ],
+          "go",
+          step,
+          args,
+          state
+        );
+        if (value === BACK) {
+          step = previousPromptStep(step, args, state) ?? step;
+          continue;
+        }
+        state.runtime = value;
+        state.framework = undefined;
+      }
+      step = "framework";
+      continue;
+    }
+
+    if (step === "framework") {
+      if (!state.target || !state.runtime) {
+        step = state.target ? "runtime" : "target";
+        continue;
+      }
+      const allowed = frameworksForTargetRuntime(state.target, state.runtime);
+      if (args.framework) {
+        if (!allowed.some((framework) => framework === args.framework)) {
+          throw new Error(`Framework ${args.framework} is not valid for target ${state.target} and runtime ${state.runtime}`);
+        }
+        state.framework = args.framework;
+      } else {
+        const value = await promptSelectWithBack<Framework>(
+          "Framework",
+          allowed.map((framework, index) => ({
+            value: framework,
+            label: framework,
+            hint: index === 0 ? "Default" : undefined,
+          })),
+          allowed[0],
+          step,
+          args,
+          state
+        );
+        if (value === BACK) {
+          step = previousPromptStep(step, args, state) ?? step;
+          continue;
+        }
+        state.framework = value;
+      }
+      step = "modulePath";
+      continue;
+    }
+
+    if (step === "modulePath") {
+      if (!state.runtime) {
+        step = "runtime";
+        continue;
+      }
+      if (state.runtime !== "go") {
+        state.modulePath = args.modulePath ?? defaults.modulePath;
+      } else if (args.modulePath) {
+        state.modulePath = args.modulePath.trim();
+      } else {
+        const value = await promptTextWithBack(
+          "Go module path",
+          state.modulePath ?? defaults.modulePath,
+          (input) => {
+            if (!input.trim()) {
+              return "Go module path is required";
+            }
+            return true;
+          },
+          step,
+          args,
+          state
+        );
+        if (value === BACK) {
+          step = previousPromptStep(step, args, state) ?? step;
+          continue;
+        }
+        state.modulePath = value;
+      }
+      step = "gcp";
+      continue;
+    }
+
+    if (step === "gcp") {
+      discovery ??= await waitForDiscovery(discoveryPromise);
+      const value = await resolveGcpSelection(args, defaults, discovery, {
+        allowBack: Boolean(previousPromptStep(step, args, state)),
+      });
+      if (value === BACK) {
+        step = previousPromptStep(step, args, state) ?? step;
+        continue;
+      }
+      state.gcpSelection = value;
+      step = "confirm";
+      continue;
+    }
+
+    if (step === "confirm") {
+      if (!state.target || !state.runtime || !state.framework || !state.modulePath || !state.gcpSelection) {
+        step = "serviceName";
+        continue;
+      }
+      const value = await promptSelectWithBack<"create">(
+        "Create the scaffold with these defaults?",
+        [{ value: "create", label: "Create scaffold", hint: "Default" }],
+        "create",
+        step,
+        args,
+        state
+      );
+      if (value === BACK) {
+        step = previousPromptStep(step, args, state) ?? step;
+        continue;
+      }
+
+      const directory = args.directory ?? state.serviceName;
+      const targetDir = resolve(process.cwd(), directory);
+      await assertTargetDirectoryIsEmpty(targetDir);
+      const billingAccount = chooseBillingAccount(args.billingAccount, discovery?.billingAccounts ?? []);
+
+      for (const warning of discovery?.warnings ?? []) {
+        log.warn(warning);
+      }
+
+      return {
+        directory,
+        serviceName: state.serviceName,
+        modulePath: state.modulePath,
+        target: state.target,
+        runtime: state.runtime,
+        framework: state.framework,
+        profile: args.profile,
+        region: args.region ?? DEFAULT_REGION,
+        gcpProjectMode: state.gcpSelection.mode,
+        gcpProject: state.gcpSelection.projectId,
+        gcpProjectName: state.gcpSelection.projectName,
+        billingAccount,
+        quotaProjectId: args.quotaProjectId ?? QUOTA_PROJECT_DEFAULT,
+        autoDeploy: resolveAutoDeploy(args.autoDeploy),
+        git: buildGitBootstrapConfig(state.serviceName, args.noGit),
+        neonDatabaseName: defaults.neonDatabaseName,
+        apiHostname: defaults.apiHostname,
+        generatorRoot: resolve(dirname(fileURLToPath(import.meta.url)), ".."),
+      };
+    }
+  }
+}
+
 async function waitForDiscovery(discoveryPromise: Promise<DiscoveryState>) {
   const indicator = spinner();
   indicator.start("Discovering GCP defaults");
@@ -574,8 +781,9 @@ async function resolveModulePath(args: ParsedArgs, runtime: Runtime, initialValu
 async function resolveGcpSelection(
   args: ParsedArgs,
   defaults: ReturnType<typeof deriveDefaults>,
-  discovery: DiscoveryState
-) {
+  discovery: DiscoveryState,
+  options: { allowBack?: boolean } = {}
+): Promise<GcpSelection | typeof BACK> {
   if (args.gcpProjectMode && args.gcpProject) {
     const existing = discovery.projects.find((project) => matchesProject(project, args.gcpProject ?? ""));
     return {
@@ -614,6 +822,15 @@ async function resolveGcpSelection(
     message: "GCP project",
     initialValue: "create_new",
     options: [
+      ...(options.allowBack
+        ? [
+            {
+              value: BACK,
+              label: "Back",
+              hint: "Return to previous step",
+            },
+          ]
+        : []),
       {
         value: "create_new",
         label: `Create new project: ${defaults.projectName} (${defaults.projectId})`,
@@ -633,6 +850,10 @@ async function resolveGcpSelection(
     process.exit(1);
   }
 
+  if (mode === BACK) {
+    return BACK;
+  }
+
   if (mode === "create_new") {
     return {
       mode: "create_new" as const,
@@ -645,7 +866,10 @@ async function resolveGcpSelection(
     throw new Error("No existing GCP projects were discovered");
   }
 
-  const selected = await promptForExistingProject(discovery.projects);
+  const selected = await promptForExistingProject(discovery.projects, options);
+  if (selected === BACK) {
+    return BACK;
+  }
   if (!selected) {
     return resolveGcpSelection(
       {
@@ -654,7 +878,8 @@ async function resolveGcpSelection(
         gcpProject: undefined,
       },
       defaults,
-      discovery
+      discovery,
+      options
     );
   }
 
@@ -704,11 +929,11 @@ function chooseBillingAccount(input: string | undefined, accounts: BillingAccoun
   return accounts[0]?.name ?? BILLING_ACCOUNT_DEFAULT;
 }
 
-function resolveAutoDeploy(value: boolean | undefined) {
+export function resolveAutoDeploy(value: boolean | undefined) {
   if (value !== undefined) {
     return value;
   }
-  return false;
+  return true;
 }
 
 async function promptText(
@@ -730,6 +955,108 @@ async function promptText(
   return value.trim();
 }
 
+async function promptTextWithBack(
+  message: string,
+  initialValue: string,
+  validate: (value: string) => true | string,
+  step: InteractiveStep,
+  args: ParsedArgs,
+  state: InteractiveState
+): Promise<string | typeof BACK> {
+  const allowBack = Boolean(previousPromptStep(step, args, state));
+  const value = await text({
+    message: allowBack ? `${message} (type "back" to return)` : message,
+    initialValue,
+    validate: (input) => {
+      const normalized = (input ?? "").trim().toLowerCase();
+      if (allowBack && (normalized === "back" || normalized === "<")) {
+        return undefined;
+      }
+      return normalizeValidationResult(validate((input ?? "").trim()));
+    },
+  });
+
+  if (isCancel(value)) {
+    cancel("Aborted");
+    process.exit(1);
+  }
+
+  const trimmed = value.trim();
+  if (allowBack && (trimmed.toLowerCase() === "back" || trimmed === "<")) {
+    return BACK;
+  }
+
+  return trimmed;
+}
+
+async function promptSelectWithBack<Value extends string>(
+  message: string,
+  options: Array<{ value: Value; label?: string; hint?: string; disabled?: boolean }>,
+  initialValue: Value | undefined,
+  step: InteractiveStep,
+  args: ParsedArgs,
+  state: InteractiveState
+): Promise<Value | typeof BACK> {
+  const allowBack = Boolean(previousPromptStep(step, args, state));
+  const value = await select<Value | typeof BACK>({
+    message,
+    initialValue,
+    options: [
+      ...(allowBack
+        ? [
+            {
+              value: BACK,
+              label: "Back",
+              hint: "Return to previous step",
+            },
+          ]
+        : []),
+      ...options,
+    ] as any,
+  });
+
+  if (isCancel(value)) {
+    cancel("Aborted");
+    process.exit(1);
+  }
+
+  return value;
+}
+
+function previousPromptStep(step: InteractiveStep, args: ParsedArgs, state: InteractiveState): InteractiveStep | undefined {
+  const steps: InteractiveStep[] = ["serviceName", "target", "runtime", "framework", "modulePath", "gcp", "confirm"];
+  const currentIndex = steps.indexOf(step);
+  for (let index = currentIndex - 1; index >= 0; index -= 1) {
+    const candidate = steps[index];
+    if (candidate && isPromptableStep(candidate, args, state)) {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+function isPromptableStep(step: InteractiveStep, args: ParsedArgs, state: InteractiveState) {
+  if (step === "serviceName") {
+    return !args.serviceName;
+  }
+  if (step === "target") {
+    return !args.target;
+  }
+  if (step === "runtime") {
+    return state.target !== "workers" && !args.runtime;
+  }
+  if (step === "framework") {
+    return !args.framework;
+  }
+  if (step === "modulePath") {
+    return state.runtime === "go" && !args.modulePath;
+  }
+  if (step === "gcp") {
+    return !args.gcpProjectMode;
+  }
+  return step === "confirm";
+}
+
 function formatError(error: unknown) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -744,17 +1071,21 @@ function handleCliError(error: unknown) {
   process.exit(1);
 }
 
-async function promptForExistingProject(projects: GcpProject[]) {
+async function promptForExistingProject(projects: GcpProject[], options: { allowBack?: boolean } = {}) {
   const value = await autocomplete({
     message: "Existing GCP project",
     placeholder: "Search by project name or id",
     maxItems: 10,
     options: [
-      {
-        value: "__back__",
-        label: "Back",
-        hint: "Return to project mode",
-      },
+      ...(options.allowBack
+        ? [
+            {
+              value: BACK,
+              label: "Back",
+              hint: "Return to project mode",
+            },
+          ]
+        : []),
       ...projects.map((project) => ({
         value: project.projectId,
         label: project.name,
@@ -768,8 +1099,8 @@ async function promptForExistingProject(projects: GcpProject[]) {
     process.exit(1);
   }
 
-  if (value === "__back__") {
-    return undefined;
+  if (value === BACK) {
+    return BACK;
   }
 
   const project = projects.find((candidate) => candidate.projectId === value);
@@ -823,29 +1154,37 @@ export function validateServiceNameInput(rawValue: string, directoryOverride?: s
 }
 
 function printHelp() {
-  log.message(`
-Usage:
-  service create [service_id] [options]
-
-Options:
-  --target <cloudrun|workers>     Deploy target for the generated service
-  --profile <microservice>        Compatibility no-op; app workspaces moved out
-  --runtime <go|bun>              Runtime scaffold to generate
-  --framework <name>              Framework for the selected runtime
-  --module-path <path>            Go module path for generated Go scaffolds
-  --project-mode <mode>           create_new or use_existing
-  --project-id <id>               GCP project id
-  --billing-account <name>        Billing account resource name
-  --quota-project <id>            Billing quota project for gcloud calls
-  --region <region>               Cloud Run region
-  --auto-deploy                   Run service create and service deploy after scaffold
-  --no-auto-deploy                Scaffold only
-  --no-git                        Skip git init, initial commit, GitHub repo creation, and push
-  --auto-update                   Re-run through create-svc@latest when a newer version exists
-  --no-update-check               Skip the best-effort npm update check
-  --yes, -y                       Accept defaults without prompts
-  --help, -h                      Show this message
-`);
+  console.log(formatScaffoldHelp());
+}
+
+export function formatScaffoldHelp() {
+  return [
+    "Usage:",
+    "  service create <service_id> [options]",
+    "",
+    "Examples:",
+    "  service create waitlist-api --target cloudrun --runtime bun --framework hono",
+    "  service create waitlist-api --auto-deploy",
+    "",
+    "Options:",
+    "  --dir <path>                    Output directory; defaults to ./<service_id>",
+    "  --target <cloudrun|workers>     Deploy target for the generated service",
+    "  --runtime <go|bun>              Runtime scaffold to generate",
+    "  --framework <name>              Framework for the selected runtime",
+    "  --module-path <path>            Go module path for generated Go scaffolds",
+    "  --project-mode <mode>           create_new or use_existing",
+    "  --project-id <id>               GCP project id",
+    "  --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)",
+    "  --no-auto-deploy                Scaffold only",
+    "  --no-git                        Skip default private GitHub repo: anmho/<service_id>",
+    "  --yes, -y                       Accept defaults without prompts",
+    "  --help, -h                      Show this message",
+    "",
+    "Inside a generated service repo, run service --help for create, deploy, doctor, auth, and sdk commands.",
+  ].join("\n");
 }
 
 function matchesProject(project: GcpProject, query: string) {