@frontera-sdk/cli 1.43.9 → 1.44.0

package/src/project-bootstrap.ts

@@ -0,0 +1,176 @@
+import { existsSync, readdirSync, rmSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { UsageError } from './errors'
+
+/**
+ * The steps between "files written" and "a project someone can work in".
+ *
+ * `frontera app init` used to stop at writing files, and everything after that
+ * was a list the author had to retype: install, init a repository, discover
+ * that the name they chose produced an invalid `package.json`, discover that
+ * they had just written a scaffold on top of an existing project. Every one of
+ * those is knowable at scaffold time, so the command does them.
+ *
+ * They live here rather than in the command because each one is a decision
+ * with an edge case — an occupied directory, a machine with no git identity, a
+ * sandbox with no network — and those are worth testing directly rather than
+ * through a command that also writes forty files.
+ */
+
+/**
+ * Names that survive being a directory, an npm package name and a slug.
+ *
+ * The scaffold writes `name` straight into `package.json`, so a capital letter
+ * or a space produced a project where `bun install` fails on the manifest —
+ * after the files were written, which is the least useful moment to find out.
+ */
+export function validateAppName(name: string): void {
+  if (name.length > 100) {
+    throw new UsageError('app name is too long', 'use 100 characters or fewer')
+  }
+  if (/^[a-z0-9][a-z0-9-]*$/.test(name) && !name.endsWith('-')) return
+
+  const suggestion = name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+  throw new UsageError(
+    `invalid app name: ${name}`,
+    suggestion.length > 0 && /^[a-z0-9]/.test(suggestion)
+      ? `use lowercase letters, digits and hyphens — try \`frontera app init ${suggestion}\``
+      : 'use lowercase letters, digits and hyphens, starting with a letter or digit',
+  )
+}
+
+/** Entries that do not make a directory "occupied". */
+const IGNORED_ENTRIES = new Set(['.git', '.DS_Store', '.idea', '.vscode', 'Thumbs.db'])
+
+/**
+ * Refuse to scaffold over someone's work.
+ *
+ * Writing into a non-empty directory is silent damage: the scaffold overwrites
+ * `package.json`, `tsconfig.json` and `src/app/page.tsx` without asking, and
+ * the author finds out when their project stops building.
+ */
+export function assertTargetAvailable(target: string): void {
+  if (!existsSync(target)) return
+
+  // Sorted so the message is the same on every machine — readdir order is not.
+  const occupied = readdirSync(target)
+    .filter((entry) => !IGNORED_ENTRIES.has(entry))
+    .sort()
+  if (occupied.length === 0) return
+
+  const shown = occupied.slice(0, 3).join(', ')
+  throw new UsageError(
+    `${target} already exists and is not empty (${shown}${occupied.length > 3 ? ', …' : ''})`,
+    'choose another name, or remove that directory first',
+  )
+}
+
+export interface InstallResult {
+  installed: boolean
+  /** The last line bun printed — its own package count and timing. */
+  summary: string
+}
+
+/**
+ * Install dependencies, best effort.
+ *
+ * `app init` is `offline: true` and must keep working in a sandbox with no
+ * network, so a failed install is reported and the project is still usable —
+ * the next-steps block grows a `bun install` line instead. Output is captured
+ * rather than inherited because stdout carries command data and nothing else;
+ * everything here is progress, which belongs on stderr.
+ */
+export async function installDependencies(target: string): Promise<InstallResult> {
+  try {
+    const child = Bun.spawn(['bun', 'install'], {
+      cwd: target,
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ])
+    const lines = `${stdout}\n${stderr}`
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+
+    if (exitCode !== 0) {
+      return { installed: false, summary: lines.at(-1) ?? `bun install exited with ${exitCode}` }
+    }
+    const installed = lines.filter((line) => /packages installed|Checked \d+ install/.test(line))
+    return { installed: true, summary: installed.at(-1) ?? lines.at(-1) ?? 'dependencies installed' }
+  } catch (error) {
+    return { installed: false, summary: error instanceof Error ? error.message : 'bun install failed' }
+  }
+}
+
+export interface GitResult {
+  initialized: boolean
+  reason?: 'already-in-repository' | 'unavailable'
+}
+
+/**
+ * Start the project on a commit.
+ *
+ * Skipped inside an existing repository: a nested repo the author did not ask
+ * for is worse than no repo, and a monorepo is a normal place to scaffold an
+ * App.
+ *
+ * The rollback below only ever removes a repository THIS call created, and the
+ * probe asks about `target` as well as its parent. Both are load-bearing, and
+ * the earlier version of this function had neither:
+ *
+ *   mkdir myapp && cd myapp && git init && git commit …
+ *   cd .. && frontera app init myapp
+ *
+ * `.git` is deliberately ignored when deciding whether a directory is occupied
+ * (`git clone --no-checkout` then scaffold is a real workflow), the parent-only
+ * probe never noticed that `myapp` was itself a worktree, and `git commit` then
+ * failed the way it does on a machine with no `user.email` — or with a
+ * `pre-commit` hook that exits non-zero, or `commit.gpgsign` and no key. The
+ * cleanup deleted history, branches, remotes and stashes that this command had
+ * not created. That was reproduced end to end before this was rewritten.
+ */
+export async function initGitRepository(target: string): Promise<GitResult> {
+  const run = async (args: string[], cwd: string): Promise<boolean> => {
+    try {
+      const child = Bun.spawn(args, { cwd, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
+      await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text()])
+      return (await child.exited) === 0
+    } catch {
+      return false
+    }
+  }
+
+  // `target` first: it is the directory whose repository we could destroy.
+  if (
+    existsSync(join(target, '.git')) ||
+    (await run(['git', 'rev-parse', '--is-inside-work-tree'], target)) ||
+    (await run(['git', 'rev-parse', '--is-inside-work-tree'], dirname(target)))
+  ) {
+    return { initialized: false, reason: 'already-in-repository' }
+  }
+
+  const steps =
+    (await run(['git', 'init', '-b', 'main'], target)) &&
+    (await run(['git', 'add', '-A'], target)) &&
+    (await run(['git', 'commit', '-m', 'Initial commit from frontera app init'], target))
+
+  if (!steps) {
+    // Safe because of the guard above: nothing here existed a moment ago. A
+    // repository with no first commit reports the whole scaffold as untracked
+    // while looking initialised, which is worse than no repository at all.
+    rmSync(join(target, '.git'), { recursive: true, force: true })
+    return { initialized: false, reason: 'unavailable' }
+  }
+  return { initialized: true }
+}

package/src/project.ts

@@ -16,6 +16,10 @@ export interface ProjectConfig {
   /** Origins the app may reach at runtime; become the served CSP. */
   connectDomains: string[]
   resourceDomains: string[]
+  /** Directory containing the already-built static artifact. */
+  outputDirectory: string
+  /** Hosting behavior, deliberately independent of the build framework. */
+  routing: 'spa' | 'filesystem'
 }
 
 const STATE_FILE = '.frontera/state.json'
@@ -23,11 +27,9 @@ const STATE_FILE = '.frontera/state.json'
 /**
  * Read app identity and runtime configuration.
  *
- * All of it lives in `package.json` under a `frontera` key — the same key that
- * marks a directory as an app project. A separate `frontera.config.ts` was
- * specified originally and is deliberately not used: it would force the CLI to
- * evaluate TypeScript to learn a slug, and it would put an app's identity in
- * two files that can disagree. JSON is also what an agent can patch safely.
+ * New projects keep deployment settings in `frontera.config.json`, leaving
+ * package.json to standard package metadata. The legacy `package.json#frontera`
+ * object remains readable so existing projects do not need a migration.
  */
 export function readProject(dir: string): ProjectConfig {
   const pkgPath = join(dir, 'package.json')
@@ -44,8 +46,27 @@ export function readProject(dir: string): ProjectConfig {
       description?: string
       connectDomains?: unknown
       resourceDomains?: unknown
+      outputDirectory?: string
+      routing?: unknown
     }
   }
+  const configPath = join(dir, 'frontera.config.json')
+  let config: {
+    displayName?: string
+    description?: string
+    connectDomains?: unknown
+    resourceDomains?: unknown
+    outputDirectory?: string
+    routing?: unknown
+  } = {}
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf8')) as typeof config
+    } catch (err) {
+      throw new Error(`frontera.config.json is not valid JSON: ${(err as Error).message}`)
+    }
+  }
+  const state = readState(dir)
 
   // Bootstrap only: the name to CREATE the app under, on the one deploy where
   // it does not exist yet. Never written back, because the platform owns the
@@ -56,45 +77,57 @@ export function readProject(dir: string): ProjectConfig {
   if (!slug) throw new Error('package.json needs a "name"')
 
   return {
-    // The real identifier. In package.json rather than `.frontera/state.json`
-    // because state is gitignored, so a colleague who clones the repo would
-    // otherwise have nothing durable — and would deploy to a new app.
-    appId: pkg.frontera?.appId ?? readState(dir).appId ?? null,
+    // The real identifier is local environment state. A source tree remains
+    // portable across Frontera organizations; first authenticated use binds a
+    // clone to the App in that environment and subsequent calls use the id.
+    appId: state.appId ?? pkg.frontera?.appId ?? null,
     slug,
-    displayName: pkg.frontera?.displayName ?? slug,
-    description: pkg.frontera?.description,
-    parentVersion: readState(dir).parentVersion ?? null,
-    connectDomains: stringList(pkg.frontera?.connectDomains),
-    resourceDomains: stringList(pkg.frontera?.resourceDomains),
+    displayName: config.displayName ?? pkg.frontera?.displayName ?? slug,
+    description: config.description ?? pkg.frontera?.description,
+    parentVersion: state.parentVersion ?? null,
+    connectDomains: stringList(config.connectDomains ?? pkg.frontera?.connectDomains, 'connectDomains'),
+    resourceDomains: stringList(config.resourceDomains ?? pkg.frontera?.resourceDomains, 'resourceDomains'),
+    outputDirectory: safeOutputDirectory(
+      config.outputDirectory ?? pkg.frontera?.outputDirectory ?? 'dist',
+    ),
+    routing: routing(config.routing ?? pkg.frontera?.routing),
   }
 }
 
-/** Tolerate a missing or malformed list rather than failing a whole read. */
-function stringList(value: unknown): string[] {
-  return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : []
+function safeOutputDirectory(value: string): string {
+  if (
+    !value ||
+    value === '.' ||
+    value.startsWith('/') ||
+    /^[a-z]:[\\/]/i.test(value) ||
+    value.split(/[\\/]/).includes('..')
+  ) {
+    throw new Error('outputDirectory must be a project-relative directory without `..`')
+  }
+  return value
+}
+
+function routing(value: unknown): 'spa' | 'filesystem' {
+  if (value === undefined) return 'spa'
+  if (value === 'spa' || value === 'filesystem') return value
+  throw new Error('routing must be either "spa" or "filesystem"')
+}
+
+function stringList(value: unknown, field: string): string[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw new Error(`${field} must be an array of strings`)
+  }
+  return value as string[]
 }
 
 /**
- * Record the app's id in package.json, so it is committed alongside the code.
- *
- * Also DROPS any `frontera.slug`. Once the id is known the slug is dead weight
- * — the platform owns it and can rename it, so a committed copy only survives
- * to go stale and mislead the next person who reads the file.
- *
- * Idempotent: when nothing would change, the file is left untouched rather
- * than rewritten, so this never shows up as a spurious diff.
+ * Record the environment-specific app binding locally. Source remains portable
+ * across organizations and package.json remains ordinary package metadata.
  */
 export function writeAppId(dir: string, appId: string): void {
-  const pkgPath = join(dir, 'package.json')
-  const raw = readFileSync(pkgPath, 'utf8')
-  const pkg = JSON.parse(raw) as { frontera?: Record<string, unknown> }
-  const frontera = pkg.frontera ?? {}
-  if (frontera.appId === appId && frontera.slug === undefined) return
-
-  const { slug: _dropped, ...rest } = frontera
-  pkg.frontera = { appId, ...rest }
-  const indent = /^\{\n(\s+)"/.exec(raw)?.[1]?.length ?? 2
-  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`)
+  if (readState(dir).appId === appId) return
+  writeState(dir, { appId })
 }
 
 export function readPackageVersion(dir: string): string {

package/src/provenance.ts

@@ -0,0 +1,89 @@
+import { createHash } from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface AppBuildProvenance {
+  schemaVersion: 1
+  cliVersion: string
+  framework: 'next' | 'vite' | 'unknown'
+  frameworkVersion?: string
+  sourceCommit?: string
+  sourceDirty?: boolean
+  lockfilePath?: string
+  lockfileDigest?: string
+  packagedAt: string
+}
+
+const LOCKFILES = ['bun.lock', 'bun.lockb', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'] as const
+
+export function detectAppFramework(root: string): AppBuildProvenance['framework'] {
+  const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as {
+    dependencies?: Record<string, string>
+    devDependencies?: Record<string, string>
+  }
+  const dependencies = { ...pkg.devDependencies, ...pkg.dependencies }
+  return dependencies.next ? 'next' : dependencies.vite ? 'vite' : 'unknown'
+}
+
+function installedFrameworkVersion(root: string, framework: AppBuildProvenance['framework']): string | undefined {
+  const packageName = framework === 'next' ? 'next' : framework === 'vite' ? 'vite' : null
+  if (!packageName) return undefined
+  try {
+    const installed = JSON.parse(
+      readFileSync(join(root, 'node_modules', packageName, 'package.json'), 'utf8'),
+    ) as { version?: string }
+    return installed.version
+  } catch {
+    return undefined
+  }
+}
+
+function ownVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(join(import.meta.dir, '../package.json'), 'utf8')) as {
+      version?: string
+    }
+    return pkg.version ?? 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+export function collectBuildProvenance(root: string): AppBuildProvenance {
+  const framework = detectAppFramework(root)
+  const frameworkVersion = installedFrameworkVersion(root, framework)
+  const provenance: AppBuildProvenance = {
+    schemaVersion: 1,
+    cliVersion: ownVersion(),
+    framework,
+    ...(frameworkVersion ? { frameworkVersion } : {}),
+    packagedAt: new Date().toISOString(),
+  }
+
+  const lockfilePath = LOCKFILES.find((name) => existsSync(join(root, name)))
+  if (lockfilePath) {
+    provenance.lockfilePath = lockfilePath
+    provenance.lockfileDigest = `sha256:${createHash('sha256')
+      .update(readFileSync(join(root, lockfilePath)))
+      .digest('hex')}`
+  }
+
+  try {
+    provenance.sourceCommit = execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+    provenance.sourceDirty =
+      execFileSync('git', ['status', '--porcelain'], {
+        cwd: root,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim().length > 0
+  } catch {
+    // Source provenance is optional for projects outside Git.
+  }
+
+  return provenance
+}

package/src/render-evidence.ts

@@ -39,6 +39,12 @@ import { isExcluded } from './packaging'
 /** Written by `render_app`; see RENDER_EVIDENCE_RELATIVE_PATH in the service. */
 export const RENDER_EVIDENCE_PATH = '.frontera/last-render.json'
 
+/** The screenshot from that same render; RENDER_THUMBNAIL_RELATIVE_PATH. */
+export const RENDER_THUMBNAIL_PATH = '.frontera/last-render.png'
+
+/** Bigger than any viewport screenshot; a file over this is not one of ours. */
+const MAX_THUMBNAIL_BYTES = 4 * 1024 * 1024
+
 export interface RenderEvidence {
   /** True only when a render happened AFTER the newest source change. */
   rendered: boolean
@@ -130,6 +136,28 @@ export function readRenderEvidence(root: string): RenderEvidence {
   }
 }
 
+/**
+ * The screenshot from the last render, when this tree has one.
+ *
+ * Read whatever `readRenderEvidence` concluded: a `stale` picture is still a
+ * picture of THIS app, and the version row records that the source moved on
+ * afterwards, so a reviewer is never misled by it. Refusing to upload one
+ * would leave the gallery blank for exactly the apps people iterate on most.
+ *
+ * Never throws. This is the decorative half of the deploy payload, and a
+ * deploy that dies on an unreadable PNG would be a bad trade.
+ */
+export function readRenderThumbnail(root: string): Uint8Array | null {
+  const path = join(root, RENDER_THUMBNAIL_PATH)
+  try {
+    if (!existsSync(path)) return null
+    if (statSync(path).size > MAX_THUMBNAIL_BYTES) return null
+    return new Uint8Array(readFileSync(path))
+  } catch {
+    return null
+  }
+}
+
 /**
  * The line deploy prints, and the one the agent reads.
  *

package/src/sdk-sync.ts

@@ -0,0 +1,41 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import vendored from './vendor/sdk-sources.json'
+import { APP_SDK_PACKAGES, sdkPackageFiles } from './template'
+
+const VERSION_FILE = 'src/frontera/.frontera-sdk.json'
+
+export type SdkSyncResult =
+  | { kind: 'published' }
+  | { kind: 'vendored'; before: string; after: string; fileCount: number }
+
+export function syncVendoredAppSdk(root: string): SdkSyncResult {
+  const generatedRoot = join(root, 'src/frontera')
+  if (!existsSync(generatedRoot)) return { kind: 'published' }
+
+  let before = 'unknown'
+  try {
+    before = (JSON.parse(readFileSync(join(root, VERSION_FILE), 'utf8')) as { version?: string })
+      .version ?? 'unknown'
+  } catch {
+    // Trees scaffolded before version metadata are still syncable.
+  }
+
+  let fileCount = 0
+  for (const [pkg, spec] of Object.entries(APP_SDK_PACKAGES)) {
+    const target = join(root, spec.dir)
+    rmSync(target, { recursive: true, force: true })
+    for (const [rel, content] of Object.entries(sdkPackageFiles(pkg as keyof typeof APP_SDK_PACKAGES))) {
+      const full = join(target, rel)
+      mkdirSync(dirname(full), { recursive: true })
+      writeFileSync(full, content)
+      fileCount++
+    }
+  }
+  const after = vendored.sdkVersion
+  const versionPath = join(root, VERSION_FILE)
+  mkdirSync(dirname(versionPath), { recursive: true })
+  writeFileSync(versionPath, `${JSON.stringify({ version: after }, null, 2)}\n`)
+  return { kind: 'vendored', before, after, fileCount }
+}

package/src/shadcn-components.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared primitives come from the shadcn registry, not from us.
+ *
+ * The alternative was a curated Frontera component library, and the cost of
+ * that is continuous: every upstream fix has to be re-applied by hand, and an
+ * FDE waiting on a component they could have had in ten seconds writes their
+ * own instead. So the scaffold configures the ecosystem's registry and gets
+ * out of the way.
+ *
+ * What the scaffold DOES own is the wiring that makes upstream components work
+ * unmodified:
+ *
+ *  - `components.json` — paths, aliases, Tailwind v4 CSS entry, icon library.
+ *  - The npm packages. Every item in the shadcn registry declares NO
+ *    dependencies of its own, so `shadcn add button` writes a file importing
+ *    `class-variance-authority` and installs nothing. Verified against the
+ *    live registry: 63 items, zero declared dependencies. The scaffold
+ *    declares them up front so an added component compiles immediately.
+ *  - The token contract. `src/app/globals.css` already defines every variable
+ *    upstream components reference, which is why `add` leaves it untouched.
+ *
+ * `shadcn init` would rewrite that stylesheet with the vanilla palette and
+ * flatten the platform surfaces. Nothing here ever runs it, and the UI skill
+ * lists it as a red flag.
+ */
+
+/**
+ * The components the scaffold's own reference feature imports.
+ *
+ * This is the contract between three places: `app init` adds exactly these,
+ * the reference feature may import exactly these, and the scaffold test
+ * asserts the second never exceeds the first. A feature that reaches for a
+ * seventh component would otherwise produce a project whose first build fails
+ * on a file nobody added.
+ */
+export const BASELINE_COMPONENTS = ['button', 'input', 'table', 'skeleton', 'card', 'alert'] as const
+
+/** Paths those components occupy, for tests and for import resolution. */
+export const BASELINE_COMPONENT_PATHS = BASELINE_COMPONENTS.map(
+  (name) => `src/components/ui/${name}.tsx`,
+)
+
+/**
+ * The command that adds these by hand.
+ *
+ * Shared with the caller so a project that did not get them — offline, or
+ * `--no-components` — is told exactly what completes it. The reference feature
+ * imports these files, so "figure it out" here means a first build that fails
+ * on a missing module.
+ */
+export function shadcnAddCommand(names: readonly string[] = BASELINE_COMPONENTS): string {
+  return `bunx --bun shadcn@latest add ${names.join(' ')}`
+}
+
+export interface AddComponentsResult {
+  added: boolean
+  /** What to show the caller: a file count, or why nothing was written. */
+  summary: string
+  /** The command to run by hand when this did not work. */
+  command: string
+}
+
+/**
+ * Fetch the baseline into a freshly scaffolded project.
+ *
+ * Best effort, and reported rather than thrown: this needs the network, and so
+ * does the `bun install` that precedes it, so a machine without one already
+ * ends up with a project it must finish by hand. The failure has to name the
+ * command that finishes it, or the caller is left with a tree that type-checks
+ * against files that were never written.
+ */
+export async function addShadcnComponents(
+  target: string,
+  names: readonly string[] = BASELINE_COMPONENTS,
+): Promise<AddComponentsResult> {
+  const command = shadcnAddCommand(names)
+  try {
+    const child = Bun.spawn(['bunx', '--bun', 'shadcn@latest', 'add', ...names, '--yes'], {
+      cwd: target,
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ])
+
+    if (exitCode !== 0) {
+      const reason = `${stdout}\n${stderr}`
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .at(-1)
+      return { added: false, summary: reason ?? `shadcn exited with ${exitCode}`, command }
+    }
+    return { added: true, summary: `${names.length} components in src/components/ui/`, command }
+  } catch (error) {
+    return {
+      added: false,
+      summary: error instanceof Error ? error.message : 'shadcn add failed',
+      command,
+    }
+  }
+}

package/src/static-app-validation.ts

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+import { CliError } from './errors'
+
+function sourceFiles(root: string): string[] {
+  const files: string[] = []
+  const walk = (dir: string) => {
+    if (!existsSync(dir)) return
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry)
+      const stat = statSync(full)
+      if (stat.isDirectory()) walk(full)
+      else if (/\.(?:ts|tsx|js|jsx)$/.test(entry)) files.push(full)
+    }
+  }
+  walk(join(root, 'app'))
+  walk(join(root, 'src', 'app'))
+  return files
+}
+
+/** Actionable preflight; Next build remains the final compatibility authority. */
+export function validateStaticAppProject(
+  root: string,
+  routing: 'spa' | 'filesystem',
+): void {
+  if (routing !== 'filesystem') return
+  const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as {
+    dependencies?: Record<string, string>
+    devDependencies?: Record<string, string>
+  }
+  if (!pkg.dependencies?.next && !pkg.devDependencies?.next) return
+
+  const configName = ['next.config.ts', 'next.config.mjs', 'next.config.js'].find((name) =>
+    existsSync(join(root, name)),
+  )
+  const issues: string[] = []
+  if (!configName) {
+    issues.push('next.config is missing')
+  } else {
+    const config = readFileSync(join(root, configName), 'utf8')
+    if (!/output\s*:\s*['"]export['"]/.test(config)) issues.push('next.config needs output: "export"')
+  }
+
+  for (const name of ['middleware.ts', 'middleware.js', 'proxy.ts', 'proxy.js']) {
+    if (existsSync(join(root, name)) || existsSync(join(root, 'src', name))) {
+      issues.push(`${name} requires a request-time runtime`)
+    }
+  }
+  for (const file of sourceFiles(root)) {
+    const rel = relative(root, file).split('\\').join('/')
+    if (rel.split('/').some((segment) => segment.startsWith('[') && segment.endsWith(']'))) {
+      issues.push(`${rel} is a dynamic route; use search parameters or client state`)
+    }
+    if (/\/route\.(?:ts|js)$/.test(rel)) issues.push(`${rel} is a runtime Route Handler`)
+    if (/['"]use server['"]/.test(readFileSync(file, 'utf8'))) {
+      issues.push(`${rel} contains a Server Action`)
+    }
+  }
+
+  if (issues.length > 0) {
+    throw new CliError(`App is not compatible with static hosting:\n- ${issues.join('\n- ')}`, {
+      code: 'VALIDATION_ERROR',
+      hint: 'remove request-time features, then run `bun run build` again',
+    })
+  }
+}