@supatype/cli 0.1.1 → 0.1.3

package/src/commands/init.ts

@@ -1,36 +1,26 @@
 import type { Command } from "commander"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
-import { resolve, join, dirname, basename } from "node:path"
-import { fileURLToPath } from "node:url"
+import { resolve, join, basename } from "node:path"
 import { spawnSync } from "node:child_process"
-import * as p from "@clack/prompts"
-import { ensureNotCancelled, printLogo } from "../ui/prompts.js"
+import { p, runClackFlow } from "../ui/clack.js"
+import { ensureNotCancelled } from "../ui/prompts.js"
 import { generateAndWriteKeys } from "./keys.js"
 import { file, error, info, plain, warn } from "../ui/messages.js"
 import { nextSteps } from "../ui/next-steps.js"
 import { probeDockerDaemon, reportDockerUnavailable } from "../docker-runtime.js"
-
-export { scaffold }
-
-// ─── Markers used by `supatype app add / remove` (app.ts) ────────────────────
-export const APP_COMPOSE_MARKER = "  # ─── App service (run: supatype app add) ───"
-export const KONG_APP_MARKER = "  # ─── App fallback route (run: supatype app add) ───"
-
-const CLI_PACKAGE_JSON = join(
-  dirname(fileURLToPath(import.meta.url)),
-  "..",
-  "..",
-  "package.json",
-)
-
-function cliPackageVersion(): string {
-  try {
-    const pkg = JSON.parse(readFileSync(CLI_PACKAGE_JSON, "utf8")) as { version?: string }
-    return pkg.version ?? "0.1.0"
-  } catch {
-    return "0.1.0"
-  }
-}
+import { loadConfig } from "../config.js"
+import {
+  ensureComponentBinaries,
+  reportComponentBinaryFailures,
+} from "../ensure-component-binaries.js"
+import { mergeSupatypePackageJson } from "../init-package-json.js"
+import { cliPackageVersion } from "../cli-package-version.js"
+import {
+  initDependencyVersionsFallback,
+  resolveInitDependencyVersions,
+  type InitDependencyVersions,
+} from "../init-dependency-versions.js"
+import { detectProjectSetup, type DetectedProjectSetup } from "../init-project-detect.js"
 
 // ─── Options model ─────────────────────────────────────────────────────────--
 
@@ -166,8 +156,14 @@ export function registerInit(program: Command): void {
 
       let result: WizardResult
       if (interactive) {
-        printLogo()
-        result = await runWizard(defaultName, modeTarget)
+        await runInteractiveInit({
+          name,
+          dir,
+          defaultName,
+          modeTarget,
+          opts,
+        })
+        return
       } else {
         result = {
           ...defaultScaffoldOptions(defaultName, modeTarget),
@@ -200,220 +196,346 @@ export function registerInit(program: Command): void {
 
       if (name) mkdirSync(dir, { recursive: true })
 
-      scaffold(dir, result)
+      const deps = await resolveInitDependencyVersions()
+      const runningCli = cliPackageVersion()
+      if (deps.cli !== runningCli || deps.types !== runningCli) {
+        info(
+          `Using published npm versions: @supatype/cli ^${deps.cli}, @supatype/types ^${deps.types}`,
+        )
+      }
+
+      scaffold(dir, result, deps)
 
-      if (doInstall) runInstall(dir, result.packageManager)
+      const installOk = doInstall ? runInstall(dir, result.packageManager) : false
       const keysGenerated = doKeys ? writeKeys(dir) : false
+      const binariesReady =
+        doInstall && installOk ? await ensureInitBinaries(dir) : false
+
+      if (doInstall && !installOk) {
+        error(
+          `Dependency install failed. Run "${result.packageManager} install" in the project directory, then "supatype update".`,
+        )
+        process.exit(1)
+      }
+      if (doKeys && !keysGenerated) {
+        error("Could not generate API keys. Check .env has JWT_SECRET, then run `supatype keys`.")
+        process.exit(1)
+      }
+      if (doInstall && installOk && !binariesReady) {
+        error("Component binaries could not be downloaded. Run `supatype update` in the project directory.")
+        process.exit(1)
+      }
 
       warnDockerUnavailableForProvider(result.provider)
 
       printNextSteps({
         name,
         result,
-        installed: doInstall,
+        installed: doInstall && installOk,
         keysGenerated,
+        binariesReady,
       })
     })
 }
 
-// ─── Wizard ──────────────────────────────────────────────────────────────────
+interface InteractiveInitArgs {
+  name: string | undefined
+  dir: string
+  defaultName: string
+  modeTarget: ProductionTarget
+  opts: InitCliOptions
+}
 
-async function runWizard(
-  defaultName: string,
-  defaultTarget: ProductionTarget,
-): Promise<WizardResult> {
-  p.intro("Create a new Supatype project")
+/** Interactive init — one Ink session for wizard + scaffold + install + finish. */
+async function runInteractiveInit(args: InteractiveInitArgs): Promise<void> {
+  const { name, dir, defaultName, modeTarget, opts } = args
+
+  await runClackFlow(async () => {
+    p.intro("Create a new Supatype project")
+    const detected = detectProjectSetup(dir)
+    if (detected.hasExistingFiles && detected.summaryLines.length > 0) {
+      p.note(
+        ["Existing project detected:", ...detected.summaryLines.map((line) => `  • ${line}`)].join(
+          "\n",
+        ),
+      )
+    }
+    let result = await collectWizardAnswers(defaultName, modeTarget, dir, detected)
+
+    if (opts.admin === false) {
+      delete result.adminEmail
+      delete result.adminPassword
+    } else if (opts.adminEmail && opts.adminPassword) {
+      result.adminEmail = opts.adminEmail
+      result.adminPassword = opts.adminPassword
+    }
 
-  const projectName = ensureNotCancelled(
-    await p.text({
-      message: "Project name",
-      defaultValue: defaultName,
-      placeholder: defaultName,
-    }),
-  ).trim() || defaultName
+    const doInstall = opts.install !== false && result.install
+    const doKeys = opts.keys !== false && result.generateKeys
 
-  const packageManager = ensureNotCancelled(
-    await p.select<PackageManager>({
-      message: "Package manager",
-      initialValue: detectInvokingPackageManager(),
-      options: [
-        { value: "npm", label: "npm" },
-        { value: "pnpm", label: "pnpm" },
-        { value: "yarn", label: "yarn" },
-        { value: "bun", label: "bun" },
-      ],
-    }),
-  )
+    if (name) mkdirSync(dir, { recursive: true })
 
-  const productionTarget = ensureNotCancelled(
-    await p.select<ProductionTarget>({
-      message: "Where will this run in production?",
-      initialValue: defaultTarget,
-      options: [
-        { value: "cloud", label: "Supatype Cloud", hint: "managed; deploy via supatype link" },
-        { value: "self-host", label: "Self-host", hint: "your own server with TLS" },
-        { value: "later", label: "Decide later", hint: "local development only for now" },
-      ],
-    }),
-  )
+    const deps = await resolveInitDependencyVersions()
+    const runningCli = cliPackageVersion()
+    if (deps.cli !== runningCli || deps.types !== runningCli) {
+      info(
+        `Using published npm versions: @supatype/cli ^${deps.cli}, @supatype/types ^${deps.types}`,
+      )
+    }
 
-  let domain: string | undefined
-  let tlsEmail: string | undefined
-  if (productionTarget === "self-host") {
-    domain = ensureNotCancelled(
-      await p.text({
-        message: "Production domain for ACME TLS (optional, can set later)",
-        placeholder: "api.example.com",
-        defaultValue: "",
-      }),
-    ).trim()
-    if (domain) {
-      tlsEmail =
-        ensureNotCancelled(
-          await p.text({
-            message: "Email for Let's Encrypt (HTTPS) certificates",
-            placeholder: "you@example.com",
-            defaultValue: "",
-          }),
-        ).trim() || undefined
+    const setupSpinner = p.spinner()
+    setupSpinner.start("Setting up your project...")
+
+    scaffold(dir, result, deps)
+
+    let installOk = !doInstall
+    if (doInstall) {
+      setupSpinner.start(`Installing dependencies with ${result.packageManager}...`)
+      installOk = runInstall(dir, result.packageManager)
+      setupSpinner.stop(installOk ? "Dependencies installed." : "Dependency install failed.")
     }
-  }
 
-  const provider = ensureNotCancelled(
-    await p.select<ScaffoldOptions["provider"]>({
-      message: "How should Postgres and the server run for local development?",
-      initialValue: "docker",
-      options: [
-        { value: "docker", label: "Docker", hint: "Docker Compose stack (recommended)" },
-        { value: "native", label: "Native", hint: "host Postgres + server binaries, no Docker" },
-      ],
-    }),
-  )
+    let keysGenerated = !doKeys
+    if (doKeys) {
+      setupSpinner.start("Generating API keys...")
+      keysGenerated = writeKeys(dir)
+      setupSpinner.stop(keysGenerated ? "API keys generated." : "Could not generate API keys.")
+    }
 
-  let kongPort: number | undefined
-  if (provider === "docker") {
-    const { promptKongPortChoice } = await import("../dev-ports.js")
-    kongPort = await promptKongPortChoice()
-  }
+    let binariesReady = false
+    if (doInstall && installOk) {
+      setupSpinner.start("Preparing component binaries...")
+      binariesReady = await ensureInitBinaries(dir)
+      setupSpinner.stop(binariesReady ? "Component binaries ready." : "Some binaries are missing.")
+    }
 
-  const schemaPath = ensureNotCancelled(
-    await p.text({
-      message: "Where should your schema live?",
-      defaultValue: "schema/index.ts",
-      placeholder: "schema/index.ts",
-    }),
-  ).trim() || "schema/index.ts"
+    if (doInstall && !installOk) {
+      error(
+        `Dependency install failed. Run "${result.packageManager} install" in the project directory, then "supatype update".`,
+      )
+      process.exit(1)
+    }
+    if (doKeys && !keysGenerated) {
+      error("Could not generate API keys. Check .env has JWT_SECRET, then run `supatype keys`.")
+      process.exit(1)
+    }
+    if (doInstall && installOk && !binariesReady) {
+      error("Component binaries could not be downloaded. Run `supatype update` in the project directory.")
+      process.exit(1)
+    }
 
-  const app = await promptApp()
+    warnDockerUnavailableForProvider(result.provider)
 
-  const email = ensureNotCancelled(
-    await p.select<ScaffoldOptions["email"]>({
-      message: "Email provider",
-      initialValue: "console",
-      options: [
-        { value: "console", label: "console", hint: "log emails to the terminal (dev)" },
-        { value: "smtp", label: "SMTP" },
-        { value: "resend", label: "Resend" },
-        { value: "ses", label: "Amazon SES" },
-      ],
-    }),
-  )
+    p.outro(`Supatype project ready${name ? ` in ${name}/` : ""}.`)
+    printNextSteps({
+      name,
+      result,
+      installed: doInstall && installOk,
+      keysGenerated,
+      binariesReady,
+    })
+  })
 
-  const storageLocal = ensureNotCancelled(
-    await p.select<StorageProvider>({
-      message: "Local storage (for development)?",
-      initialValue: "local",
-      options: STORAGE_PROVIDER_OPTIONS,
-    }),
-  )
+  process.exit(0)
+}
 
-  const storageProduction = ensureNotCancelled(
-    await p.select<StorageProvider>({
-      message: "Production storage?",
-      initialValue: "local",
-      options: STORAGE_PROVIDER_OPTIONS,
-    }),
-  )
+// ─── Wizard ──────────────────────────────────────────────────────────────────
 
-  const helloFunction = ensureNotCancelled(
-    await p.confirm({
-      message: "Create a hello-world edge function?",
-      initialValue: false,
-    }),
-  )
+async function collectWizardAnswers(
+  defaultName: string,
+  defaultTarget: ProductionTarget,
+  dir: string,
+  detected: DetectedProjectSetup,
+): Promise<WizardResult> {
+    const projectName = ensureNotCancelled(
+      await p.text({
+        message: "Project name",
+        defaultValue: defaultName,
+        placeholder: defaultName,
+      }),
+    ).trim() || defaultName
+
+    const admin = await promptAdminUser()
+
+    const packageManager = ensureNotCancelled(
+      await p.select<PackageManager>({
+        message: "Package manager",
+        initialValue: detectInvokingPackageManager(),
+        options: [
+          { value: "npm", label: "npm" },
+          { value: "pnpm", label: "pnpm" },
+          { value: "yarn", label: "yarn" },
+          { value: "bun", label: "bun" },
+        ],
+      }),
+    )
 
-  const install = ensureNotCancelled(
-    await p.confirm({
-      message: `Install dependencies with ${packageManager} now?`,
-      initialValue: true,
-    }),
-  )
+    const productionTarget = ensureNotCancelled(
+      await p.select<ProductionTarget>({
+        message: "Where will this run in production?",
+        initialValue: defaultTarget,
+        options: [
+          { value: "cloud", label: "Supatype Cloud", hint: "managed; deploy via supatype link" },
+          { value: "self-host", label: "Self-host", hint: "your own server with TLS" },
+          { value: "later", label: "Decide later", hint: "local development only for now" },
+        ],
+      }),
+    )
 
-  const generateKeys = ensureNotCancelled(
-    await p.confirm({
-      message: "Generate ANON_KEY and SERVICE_ROLE_KEY now?",
-      initialValue: true,
-    }),
-  )
+    let domain: string | undefined
+    let tlsEmail: string | undefined
+    if (productionTarget === "self-host") {
+      domain = ensureNotCancelled(
+        await p.text({
+          message: "Production domain for ACME TLS (optional, can set later)",
+          placeholder: "api.example.com",
+          defaultValue: "",
+        }),
+      ).trim()
+      if (domain) {
+        tlsEmail =
+          ensureNotCancelled(
+            await p.text({
+              message: "Email for Let's Encrypt (HTTPS) certificates",
+              placeholder: "you@example.com",
+              defaultValue: "",
+            }),
+          ).trim() || undefined
+      }
+    }
+
+    const provider = ensureNotCancelled(
+      await p.select<ScaffoldOptions["provider"]>({
+        message: "How should Postgres and the server run for local development?",
+        initialValue: "docker",
+        options: [
+          { value: "docker", label: "Docker", hint: "Docker Compose stack (recommended)" },
+          { value: "native", label: "Native", hint: "host Postgres + server binaries, no Docker" },
+        ],
+      }),
+    )
+
+    let kongPort: number | undefined
+    if (provider === "docker") {
+      const { promptKongPortChoice } = await import("../dev-ports.js")
+      kongPort = await promptKongPortChoice()
+    }
+
+    const defaultSchemaPath = existsSync(join(dir, "schema/index.ts"))
+      ? "schema/index.ts"
+      : "schema/index.ts"
+    const schemaPath = ensureNotCancelled(
+      await p.text({
+        message: "Where should your schema live?",
+        defaultValue: defaultSchemaPath,
+        placeholder: "schema/index.ts",
+      }),
+    ).trim() || defaultSchemaPath
+
+    const app = await promptApp(detected, productionTarget)
+
+    const email = ensureNotCancelled(
+      await p.select<ScaffoldOptions["email"]>({
+        message: "Email provider",
+        initialValue: "console",
+        options: [
+          { value: "console", label: "console", hint: "log emails to the terminal (dev)" },
+          { value: "smtp", label: "SMTP" },
+          { value: "resend", label: "Resend" },
+          { value: "ses", label: "Amazon SES" },
+        ],
+      }),
+    )
+
+    const storageLocal = ensureNotCancelled(
+      await p.select<StorageProvider>({
+        message: "Local storage (for development)?",
+        initialValue: "local",
+        options: STORAGE_PROVIDER_OPTIONS,
+      }),
+    )
+
+    const storageProduction = ensureNotCancelled(
+      await p.select<StorageProvider>({
+        message: "Production storage?",
+        initialValue: "local",
+        options: STORAGE_PROVIDER_OPTIONS,
+      }),
+    )
 
-  let adminEmail: string | undefined
-  let adminPassword: string | undefined
+    const helloFunction = ensureNotCancelled(
+      await p.confirm({
+        message: "Create a hello-world edge function?",
+        initialValue: false,
+      }),
+    )
+
+    return {
+      projectName,
+      provider,
+      ...(kongPort !== undefined ? { kongPort } : {}),
+      productionTarget,
+      ...(domain !== undefined ? { domain } : {}),
+      ...(tlsEmail !== undefined ? { tlsEmail } : {}),
+      schemaPath,
+      app,
+      email,
+      storageLocal,
+      storageProduction,
+      helloFunction,
+      packageManager,
+      install: true,
+      generateKeys: true,
+      ...admin,
+    }
+}
+
+async function promptAdminUser(): Promise<{ adminEmail?: string; adminPassword?: string }> {
   const createAdmin = ensureNotCancelled(
     await p.confirm({
       message: "Create an admin user for /admin?",
       initialValue: true,
     }),
   )
-  if (createAdmin) {
-    adminEmail =
-      ensureNotCancelled(
-        await p.text({
-          message: "Admin email",
-          placeholder: "you@example.com",
-          defaultValue: "",
-        }),
-      ).trim() || undefined
-    if (adminEmail) {
-      adminPassword =
-        ensureNotCancelled(
-          await p.text({
-            message: "Admin password (min 8 chars)",
-            defaultValue: "",
-          }),
-        ).trim() || undefined
-      if (adminPassword && adminPassword.length < 8) {
-        adminPassword = undefined
-      }
-    }
-  }
+  if (!createAdmin) return {}
 
-  p.outro("Setting up your project...")
+  p.note("First sign-in at /admin — created automatically on supatype dev or push.")
 
-  return {
-    projectName,
-    provider,
-    ...(kongPort !== undefined ? { kongPort } : {}),
-    productionTarget,
-    ...(domain !== undefined ? { domain } : {}),
-    ...(tlsEmail !== undefined ? { tlsEmail } : {}),
-    schemaPath,
-    app,
-    email,
-    storageLocal,
-    storageProduction,
-    helloFunction,
-    packageManager,
-    install,
-    generateKeys,
-    ...(adminEmail && adminPassword ? { adminEmail, adminPassword } : {}),
+  const adminEmail = ensureNotCancelled(
+    await p.text({
+      message: "Admin email",
+      placeholder: "you@example.com",
+      validate: (value) => (value.trim() ? undefined : "Email is required"),
+    }),
+  ).trim()
+
+  let adminPassword = ""
+  while (true) {
+    adminPassword = ensureNotCancelled(
+      await p.password({ message: "Admin password (min 8 characters)" }),
+    ).trim()
+    if (adminPassword.length >= 8) break
+    p.log.warn("Password must be at least 8 characters.")
   }
+
+  return { adminEmail, adminPassword }
 }
 
-async function promptApp(): Promise<ScaffoldAppOptions> {
+async function promptApp(
+  detected: DetectedProjectSetup,
+  productionTarget: ProductionTarget,
+): Promise<ScaffoldAppOptions> {
+  const initialMode: ScaffoldAppOptions["mode"] =
+    detected.hasVite && productionTarget !== "later"
+      ? "static"
+      : detected.hasVite
+        ? "proxy"
+        : "none"
+
   const mode = ensureNotCancelled(
     await p.select<ScaffoldAppOptions["mode"]>({
       message: "Host a frontend app at /?",
-      initialValue: "none",
+      initialValue: initialMode,
       options: [
         { value: "none", label: "No app", hint: "API only" },
         { value: "static", label: "Static site", hint: "serve a built directory" },
@@ -426,11 +548,11 @@ async function promptApp(): Promise<ScaffoldAppOptions> {
     const staticDir = ensureNotCancelled(
       await p.text({
         message: "Directory to serve",
-        defaultValue: "./public",
-        placeholder: "./public",
+        defaultValue: detected.staticDir,
+        placeholder: detected.staticDir,
       }),
-    ).trim() || "./public"
-    const viteDevUrl = await promptViteDevUrl()
+    ).trim() || detected.staticDir
+    const viteDevUrl = await promptViteDevUrl(detected, productionTarget)
     return { mode, staticDir, ...(viteDevUrl ? { viteDevUrl } : {}) }
   }
 
@@ -438,40 +560,49 @@ async function promptApp(): Promise<ScaffoldAppOptions> {
     const upstream = ensureNotCancelled(
       await p.text({
         message: "URL of your running dev server",
-        defaultValue: "http://localhost:3000",
-        placeholder: "http://localhost:3000",
+        defaultValue: detected.hasVite ? detected.viteDevUrl : "http://localhost:3000",
+        placeholder: detected.hasVite ? detected.viteDevUrl : "http://localhost:3000",
       }),
-    ).trim() || "http://localhost:3000"
+    ).trim() || (detected.hasVite ? detected.viteDevUrl : "http://localhost:3000")
     const start = ensureNotCancelled(
       await p.text({
         message: "package.json script that starts your dev server",
-        defaultValue: "dev",
-        placeholder: "dev",
+        defaultValue: detected.hasVite ? "vite" : "dev",
+        placeholder: detected.hasVite ? "vite" : "dev",
       }),
-    ).trim() || "dev"
-    const viteDevUrl = await promptViteDevUrl()
+    ).trim() || (detected.hasVite ? "vite" : "dev")
+    const viteDevUrl = await promptViteDevUrl(detected, productionTarget)
     return { mode, upstream, start, ...(viteDevUrl ? { viteDevUrl } : {}) }
   }
 
   return { mode: "none" }
 }
 
-async function promptViteDevUrl(): Promise<string | undefined> {
+async function promptViteDevUrl(
+  detected: DetectedProjectSetup,
+  productionTarget: ProductionTarget,
+): Promise<string | undefined> {
+  const defaultYes = detected.hasVite || productionTarget !== "later"
   const useVite = ensureNotCancelled(
     await p.confirm({
-      message: "Enable live reload from a separate Vite dev server?",
-      initialValue: false,
+      message: detected.hasVite
+        ? "Use Vite for local development?"
+        : "Develop locally with Vite (live reload)?",
+      initialValue: defaultYes,
     }),
   )
   if (!useVite) return undefined
+
+  p.note(`Press Enter for ${detected.viteDevUrl}, or type a custom URL.`)
+
   return (
     ensureNotCancelled(
       await p.text({
         message: "Vite dev server URL",
-        defaultValue: "http://127.0.0.1:5173",
-        placeholder: "http://127.0.0.1:5173",
+        defaultValue: detected.viteDevUrl,
+        placeholder: detected.viteDevUrl,
       }),
-    ).trim() || "http://127.0.0.1:5173"
+    ).trim() || detected.viteDevUrl
   )
 }
 
@@ -485,15 +616,36 @@ function detectInvokingPackageManager(): PackageManager {
   return "npm"
 }
 
-function runInstall(dir: string, pm: PackageManager): void {
-  info(`Installing dependencies with ${pm}...`)
+function runInstall(dir: string, pm: PackageManager): boolean {
   const res = spawnSync(pm, ["install"], {
     cwd: dir,
     stdio: "inherit",
     shell: process.platform === "win32",
   })
   if (res.status !== 0 || res.error) {
-    warn(`Dependency install did not complete (run "${pm} install" manually).`)
+    return false
+  }
+  return true
+}
+
+async function ensureInitBinaries(dir: string): Promise<boolean> {
+  const previousCwd = process.cwd()
+  try {
+    process.chdir(dir)
+    const config = loadConfig(dir)
+    const result = await ensureComponentBinaries(config, dir)
+    if (!result.ok) {
+      reportComponentBinaryFailures(result.failures)
+      return false
+    }
+    return true
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    warn(`Could not verify component binaries: ${message}`)
+    warn("Run manually from your project directory: supatype update")
+    return false
+  } finally {
+    process.chdir(previousCwd)
   }
 }
 
@@ -508,7 +660,11 @@ function writeKeys(dir: string): boolean {
 
 // ─── Scaffold ──────────────────────────────────────────────────────────────--
 
-function scaffold(dir: string, optsOrName: ScaffoldOptions | string): void {
+export function scaffold(
+  dir: string,
+  optsOrName: ScaffoldOptions | string,
+  deps: InitDependencyVersions = initDependencyVersionsFallback(),
+): void {
   const opts =
     typeof optsOrName === "string" ? defaultScaffoldOptions(optsOrName) : optsOrName
   const write = (rel: string, content: string) => {
@@ -520,9 +676,17 @@ function scaffold(dir: string, optsOrName: ScaffoldOptions | string): void {
 
   const pkgPath = join(dir, "package.json")
   if (!existsSync(pkgPath)) {
-    write("package.json", packageJsonTemplate(opts, cliPackageVersion()))
+    write("package.json", packageJsonTemplate(opts, deps))
   } else {
-    file("skipped", "package.json (already exists)")
+    try {
+      const existing = JSON.parse(readFileSync(pkgPath, "utf8")) as Record<string, unknown>
+      const merged = mergeSupatypePackageJson(existing, opts, deps)
+      writeFileSync(pkgPath, `${JSON.stringify(merged, null, 2)}\n`, "utf8")
+      file("updated", "package.json (added Supatype dependencies)")
+    } catch {
+      warn("Could not merge into package.json — add @supatype/cli and @supatype/types manually.")
+      file("skipped", "package.json (invalid JSON)")
+    }
   }
 
   write("supatype.config.ts", tsConfigTemplate(opts))
@@ -533,7 +697,7 @@ function scaffold(dir: string, optsOrName: ScaffoldOptions | string): void {
   write(".env", envTemplate(opts))
   write("seed.ts", seedTemplate(opts.projectName))
   write("seeds/.gitkeep", "")
-  scaffoldAppAssets(opts, write)
+  scaffoldAppAssets(dir, opts, write)
 
   if (opts.helloFunction) scaffoldHelloFunction(dir, write)
 
@@ -557,40 +721,63 @@ function staticDirRelative(staticDir?: string): string {
 }
 
 function scaffoldAppAssets(
+  dir: string,
   opts: ScaffoldOptions,
   write: (rel: string, content: string) => void,
 ): void {
+  const writeUnlessExists = (rel: string, content: string) => {
+    const full = join(dir, rel)
+    if (existsSync(full)) {
+      file("skipped", `${rel} (already exists)`)
+      return
+    }
+    write(rel, content)
+  }
+
   const holding = holdingPageTemplate(opts.projectName)
   const hasVite = Boolean(opts.app.viteDevUrl)
 
   if (opts.app.mode === "static") {
     const staticRel = staticDirRelative(opts.app.staticDir)
-    write(`${staticRel}/index.html`, holding)
-    if (hasVite) scaffoldVite(opts, write, holding)
+    if (opts.app.viteDevUrl && opts.productionTarget !== "later") {
+      writeUnlessExists("dist/index.html", holding)
+      scaffoldVite(dir, opts, writeUnlessExists, holding)
+      return
+    }
+    writeUnlessExists(`${staticRel}/index.html`, holding)
+    if (opts.app.viteDevUrl) scaffoldVite(dir, opts, writeUnlessExists, holding)
     return
   }
 
   if (opts.app.mode === "proxy" && opts.productionTarget !== "later") {
-    write("dist/index.html", holding)
-    if (hasVite) scaffoldVite(opts, write, holding)
+    writeUnlessExists("dist/index.html", holding)
+    if (hasVite) scaffoldVite(dir, opts, writeUnlessExists, holding)
     return
   }
 
   if (opts.app.mode === "proxy" && hasVite) {
-    scaffoldVite(opts, write, holding)
+    scaffoldVite(dir, opts, writeUnlessExists, holding)
     return
   }
 
-  write("public/.gitkeep", "")
+  writeUnlessExists("public/.gitkeep", "")
 }
 
 function scaffoldVite(
+  dir: string,
   opts: ScaffoldOptions,
   write: (rel: string, content: string) => void,
   holding: string,
 ): void {
   if (!opts.app.viteDevUrl) return
   write("index.html", holding)
+  const viteConfigRel = ["vite.config.ts", "vite.config.js", "vite.config.mjs", "vite.config.cjs"].find(
+    (name) => existsSync(join(dir, name)),
+  )
+  if (viteConfigRel) {
+    file("skipped", `${viteConfigRel} (already exists)`)
+    return
+  }
   write("vite.config.ts", viteConfigTemplate(opts.app.viteDevUrl))
 }
 
@@ -609,7 +796,7 @@ function scaffoldHelloFunction(
 
 // ─── Templates ───────────────────────────────────────────────────────────────
 
-function packageJsonTemplate(opts: ScaffoldOptions, cliVersion: string): string {
+function packageJsonTemplate(opts: ScaffoldOptions, deps: InitDependencyVersions): string {
   const scripts: string[] = [
     `    "dev": "supatype dev"`,
     `    "push": "supatype push"`,
@@ -633,8 +820,8 @@ function packageJsonTemplate(opts: ScaffoldOptions, cliVersion: string): string
 ${scripts.join(",\n")}
   },
   "dependencies": {
-    "@supatype/cli": "^${cliVersion}",
-    "@supatype/types": "^${cliVersion}"
+    "@supatype/cli": "^${deps.cli}",
+    "@supatype/types": "^${deps.types}"
   },
   "devDependencies": {
 ${devDeps.join(",\n")}
@@ -701,20 +888,49 @@ function localConfigTemplate(app: ScaffoldAppOptions): string {
     `const localConfig: Partial<SupatypeConfig> = {`,
     `  server: { mode: "dev" },`,
   ]
-  if (app.mode === "proxy") {
-    lines.push(`  app: {`)
-    lines.push(`    mode: "proxy",`)
-    lines.push(`    upstream: "${app.upstream ?? "http://localhost:3000"}",`)
-    lines.push(`    start: "${app.start ?? "dev"}",`)
-    if (app.viteDevUrl) lines.push(`    vite_dev_url: "${app.viteDevUrl}",`)
-    lines.push(`  },`)
+  const localApp = localDevAppConfigLines(app)
+  if (localApp.length > 0) {
+    lines.push(...localApp)
   }
   lines.push(`}`, ``, `export default localConfig`, ``)
   return lines.join("\n")
 }
 
+/** App block for supatype.local.config.ts (proxy + Vite during local dev). */
+function localDevAppConfigLines(app: ScaffoldAppOptions): string[] {
+  if (app.mode === "proxy") {
+    return [
+      `  app: {`,
+      `    mode: "proxy",`,
+      `    upstream: "${app.upstream ?? "http://localhost:3000"}",`,
+      `    start: "${app.start ?? "dev"}",`,
+      ...(app.viteDevUrl ? [`    vite_dev_url: "${app.viteDevUrl}",`] : []),
+      `  },`,
+    ]
+  }
+  if (app.viteDevUrl) {
+    return [
+      `  app: {`,
+      `    mode: "proxy",`,
+      `    upstream: "${app.viteDevUrl}",`,
+      `    start: "vite",`,
+      `    vite_dev_url: "${app.viteDevUrl}",`,
+      `  },`,
+    ]
+  }
+  return []
+}
+
 function appConfigLines(app: ScaffoldAppOptions, productionTarget: ProductionTarget): string[] {
   if (app.mode === "static") {
+    if (productionTarget !== "later" && app.viteDevUrl) {
+      return [
+        `  app: {`,
+        `    mode: "static",`,
+        `    static_dir: "./dist",  // production build output`,
+        `  },`,
+      ]
+    }
     const out = [
       `  app: {`,
       `    mode: "static",`,
@@ -774,7 +990,7 @@ function holdingPageTemplate(projectName: string): string {
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>${name} — Supatype</title>
-    <meta name="description" content="A Supatype project. Define your types — we generate your backend." />
+    <meta name="description" content="A Supatype project. Define your types — we generate your platform." />
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
@@ -909,6 +1125,8 @@ export default defineConfig({
     host: "127.0.0.1",
     port: ${port},
     strictPort: true,
+    // Docker Compose app proxy reaches the host as host.docker.internal.
+    allowedHosts: ["127.0.0.1", "localhost", "host.docker.internal"],
   },
 })
 `
@@ -1185,27 +1403,35 @@ function printNextSteps(args: {
   result: WizardResult
   installed: boolean
   keysGenerated: boolean
+  binariesReady: boolean
 }): void {
-  const { name, result, installed, keysGenerated } = args
+  const { name, result, installed, keysGenerated, binariesReady } = args
+  const setupComplete = installed && keysGenerated && binariesReady
   const steps: string[] = []
   if (name) steps.push(`cd ${name}`)
-  if (!installed) steps.push(`${result.packageManager} install`)
-  if (!keysGenerated) steps.push("supatype keys")
   const kongHint =
     result.provider === "docker" && result.kongPort !== undefined
       ? `supatype dev          # Docker Compose stack (Kong :${result.kongPort})`
       : "supatype dev          # Docker Compose stack (Kong :18473)"
-  steps.push(kongHint)
-  steps.push("supatype push         # apply schema + generate types")
-  if (result.adminEmail) {
-    steps.push("                      # first admin user is created on dev or push")
+  if (setupComplete) {
+    steps.push(kongHint)
+    steps.push("supatype push         # apply schema + generate types")
+    if (result.adminEmail) {
+      steps.push("                      # first admin user is created on dev or push")
+    }
+  } else {
+    if (!installed) steps.push(`${result.packageManager} install`)
+    if (!binariesReady) steps.push("supatype update        # download component binaries")
+    if (!keysGenerated) steps.push("supatype keys")
+    steps.push(kongHint)
+    steps.push("supatype push         # apply schema + generate types")
   }
   if (result.helloFunction) {
     steps.push("supatype functions serve   # run edge functions locally")
   }
 
   info(`Supatype project ready${name ? ` in ${name}/` : ""}.`)
-  nextSteps("Next steps:", steps)
+  nextSteps(setupComplete ? "Next steps:" : "Finish setup:", steps)
 
   if (result.app.mode === "none") {
     nextSteps("Static frontend (self-host):", [