@weft-js/cli 0.1.0 → 0.1.2

package/src/db-layer.mjs

@@ -6,12 +6,15 @@ import { loadConfig } from './load-config.mjs'
 
 /** The app's data layer: the plugin that declares one, or Drizzle, which is built in. Null with no database. */
 export async function dbLayer(root, loaded) {
-  const { contributions = [] } = loaded ?? await loadConfig(root)
-  const plugin = contributions.find(c => c.manifest.db)?.manifest.db
+  const { contributions = [] } = loaded ?? (await loadConfig(root))
+  const plugin = contributions.find((c) => c.manifest.db)?.manifest.db
   if (plugin) return plugin
   // Drizzle has no plugin to say so: its config file, or a client from `@weft-js/start/db/*`, does.
   const entry = join(root, 'src/db/index.server.ts')
-  return existsSync(join(root, 'drizzle.config.ts')) || (existsSync(entry) && readFileSync(entry, 'utf8').includes('@weft-js/start/db/')) ? DRIZZLE : null
+  return existsSync(join(root, 'drizzle.config.ts')) ||
+    (existsSync(entry) && readFileSync(entry, 'utf8').includes('@weft-js/start/db/'))
+    ? DRIZZLE
+    : null
 }
 
 const DRIZZLE = {
@@ -24,10 +27,15 @@ const DRIZZLE = {
       const req = createRequire(join(root, 'package.json'))
       bin = join(dirname(req.resolve('drizzle-kit')), 'bin.cjs')
     } catch {
-      throw Object.assign(new Error('drizzle-kit is not installed in this project'), { code: 'E_USAGE' })
+      throw Object.assign(new Error('drizzle-kit is not installed in this project'), {
+        code: 'E_USAGE',
+      })
     }
     const r = spawnSync(process.execPath, [bin, 'generate'], { cwd: root, encoding: 'utf8' })
-    if (r.status !== 0) throw Object.assign(new Error(`drizzle-kit generate failed:\n${r.stdout}${r.stderr}`), { code: 'E_INTERNAL' })
+    if (r.status !== 0)
+      throw Object.assign(new Error(`drizzle-kit generate failed:\n${r.stdout}${r.stderr}`), {
+        code: 'E_INTERNAL',
+      })
     return r.stdout.trim()
   },
 }

package/src/deploy/cdn.mjs

@@ -0,0 +1,142 @@
+// What a half-set-up deploy looks like, without touching a provider (research 46 §8, §9): a credential written into a
+// file (E008), Cloudflare in front of nothing or in front of a CDN (E010, E011), and Cloudinary without what it needs
+// (E012–E014).
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { host } from './hosts.mjs'
+
+/** Credentials with a shape of their own, and a value assigned to a key that names one. */
+const SHAPED = [
+  [/\bnfp_[A-Za-z0-9]{20,}/, 'a Netlify token'],
+  [/\bFlyV1\s+fm\d_[A-Za-z0-9+/=_-]{20,}/, 'a Fly token'],
+  [
+    /api\.render\.com\/deploy\/srv-[\w-]+\?key=[\w-]+/,
+    'a Render deploy hook (its key deploys the service)',
+  ],
+  [/cloudinary:\/\/\d+:[^@\s'"]+@/, 'a Cloudinary URL with its secret'],
+]
+const KEYED =
+  /\b[\w-]*(token|secret|api[_-]?key|password)[\w-]*["']?\s*[:=]\s*["']([^"'\s$]{16,})["']/i
+
+const FILES = [
+  'weft.config.ts',
+  'weft.config.mts',
+  'weft.config.js',
+  'weft.config.mjs',
+  'weft.config.json',
+  'weft.config.yaml',
+  'weft.config.yml',
+  'netlify.toml',
+  'vercel.json',
+  'wrangler.toml',
+  'fly.toml',
+  'render.yaml',
+  'Dockerfile',
+]
+
+/** E008: a credential in a file that gets committed, comments included. An env var's name, or `${{ secrets.X }}`, is never one. */
+export function writtenSecrets(root) {
+  const out = []
+  const wf = join(root, '.github/workflows')
+  const files = [
+    ...FILES,
+    ...(existsSync(wf)
+      ? readdirSync(wf)
+          .filter((f) => /\.ya?ml$/.test(f))
+          .map((f) => `.github/workflows/${f}`)
+      : []),
+  ]
+  for (const file of files) {
+    let text
+    try {
+      text = readFileSync(join(root, file), 'utf8')
+    } catch {
+      continue
+    }
+    text.split('\n').forEach((line, i) => {
+      const shaped = SHAPED.find(([re]) => re.test(line))
+      const keyed = !shaped && KEYED.exec(line)
+      if (shaped || keyed)
+        out.push({
+          file,
+          line: i + 1,
+          what: shaped ? shaped[1] : `a value for \`${keyed[0].split(/["':=\s]/)[0]}\``,
+        })
+    })
+  }
+  return out
+}
+
+/** Hosts whose own domain says the proxy isn't in front. */
+const OWN = /\.(fly\.dev|onrender\.com|netlify\.app|vercel\.app|workers\.dev|pages\.dev)$/
+
+/** E010–E014 from the config, and the environment when `env` is given (a deploy or `weft doctor`). */
+export function cdnFindings(config = {}, { env } = {}) {
+  const out = []
+  const cdn = config.deploy?.cdn ?? {}
+  const target = config.deploy?.target && host(config.deploy.target)
+  const add = (code, severity, why, fix) =>
+    out.push({ code, severity, file: 'weft.config.ts', why, fix })
+  if (cdn.proxy === 'cloudflare') {
+    let url
+    try {
+      url = config.site?.url && new URL(config.site.url).hostname
+    } catch {}
+    if (url && OWN.test(url))
+      add(
+        'E010',
+        'warning',
+        `\`deploy.cdn.proxy\` is Cloudflare, and \`site.url\` is \`${url}\`, the host's own domain: nothing goes through the proxy, and canonical URLs point past it`,
+        'Set `site.url` to the domain Cloudflare proxies, with its DNS record proxied (orange cloud) to the host',
+      )
+    if (target && target.kind !== 'server')
+      add(
+        'E011',
+        'warning',
+        `\`deploy.cdn.proxy\` puts Cloudflare in front of ${target.name}, which is a CDN already: two caches, and a deploy purges only its own`,
+        'Drop `cdn.proxy`, or deploy to a server host (`fly`, `render`) behind it',
+      )
+  }
+  const images = cdn.images
+  if (images?.provider === 'cloudinary') {
+    const plugins = (config.plugins ?? []).map((p) => p?.name ?? p)
+    if (!plugins.some((n) => typeof n === 'string' && n.includes('plugin-media')))
+      add(
+        'E012',
+        'error',
+        '`deploy.cdn.images` is Cloudinary, and `@weft-js/plugin-media` is not in `plugins`: nothing would send it an image',
+        '`weft add media`, or drop `cdn.images`',
+      )
+    const given = env?.CLOUDINARY_URL
+    const cloud = given && /@([\w-]+)\/?$/.exec(given)?.[1]
+    if (!images.cloud && !given)
+      add(
+        'E013',
+        'error',
+        '`deploy.cdn.images` names no `cloud`, and `CLOUDINARY_URL` is unset: there is no account to send images to',
+        "Set `cdn.images.cloud` to the cloud's name, and `CLOUDINARY_URL` in the host's environment (never in a file)",
+      )
+    else if (cloud && images.cloud && cloud !== images.cloud)
+      add(
+        'E013',
+        'error',
+        `\`cdn.images.cloud\` is \`${images.cloud}\`, and \`CLOUDINARY_URL\` here names \`${cloud}\`: one of them is another account`,
+        'Make them name the same cloud',
+      )
+    else if (env && !given)
+      add(
+        'E013',
+        'warning',
+        "`CLOUDINARY_URL` is unset here: the server needs it in the host's environment",
+        "Set it in the host's environment settings, never in a file",
+      )
+    add(
+      'E014',
+      'info',
+      "`cdn.images` is checked, but this weft doesn't send uploads to Cloudinary yet: they still go to `media({ server: { dir } })`",
+      'Nothing yet: research 46 §9 is the plan. On a function host, uploads need a server host with a disk until then (E003)',
+    )
+  }
+  return out
+}

package/src/deploy/files.mjs

@@ -0,0 +1,266 @@
+// The files a host needs, written by `weft deploy init` and compared by `weft check` (research 46 §7). Each text file
+// starts with `# weft deploy init <target>, sha <hash>`, the hash of what follows: a matching hash that differs from what
+// init writes now is stale (E006), and a hash that doesn't match was edited by hand, so weft leaves it alone.
+
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { host, presetFor } from './hosts.mjs'
+
+/** The lockfile's manager: how the image and the workflow install. */
+const MANAGERS = [
+  [
+    'pnpm-lock.yaml',
+    {
+      name: 'pnpm',
+      install: 'corepack enable && pnpm install --frozen-lockfile',
+      x: 'pnpm exec',
+      cache: 'pnpm',
+    },
+  ],
+  [
+    'yarn.lock',
+    {
+      name: 'yarn',
+      install: 'corepack enable && yarn install --immutable',
+      x: 'yarn',
+      cache: 'yarn',
+    },
+  ],
+  ['bun.lock', { name: 'bun', install: 'bun install --frozen-lockfile', x: 'bunx', cache: '' }],
+  ['package-lock.json', { name: 'npm', install: 'npm ci', x: 'npx', cache: 'npm' }],
+]
+export const managerOf = (root) =>
+  (MANAGERS.find(([lock]) => existsSync(join(root, lock))) ?? [
+    null,
+    { name: 'npm', install: 'npm install', x: 'npx', cache: '' },
+  ])[1]
+
+/** Where a server host keeps what must last: SQLite's default `file:.data/app.db` lands on it unchanged. */
+export const DATA = '/app/.data'
+
+const sha = (body) => createHash('sha256').update(body).digest('hex').slice(0, 12)
+const stamp = (target, body) => `# weft deploy init ${target}, sha ${sha(body)}\n${body}`
+const STAMP = /^# weft deploy init (\w+), sha ([0-9a-f]{12})\n/
+
+const IMAGES = { node: 'node:26-slim', bun: 'oven/bun:1-slim', deno: 'denoland/deno:latest' }
+const RUN = {
+  node: '["node", ".output/server/index.mjs"]',
+  bun: '["bun", "run", ".output/server/index.mjs"]',
+  deno: '["deno", "run", "-A", ".output/server/index.mjs"]',
+}
+
+/** A two-stage image: build with the lockfile's manager, run the server. A sidecar needs cargo to build and `weft start` to run. */
+function dockerfile({ runtime, manager, needs }) {
+  const rust = needs.sidecar || needs.native
+  const lines = [
+    `FROM ${IMAGES.node} AS build`,
+    'WORKDIR /app',
+    ...(rust
+      ? [
+          'RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates build-essential && curl -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal',
+          'ENV PATH=/root/.cargo/bin:$PATH',
+        ]
+      : []),
+    'COPY . .',
+    `RUN ${manager.install}`,
+    `RUN ${manager.x} weft build --preset ${presetFor({}, runtime)}`,
+    '',
+    `FROM ${needs.sidecar ? IMAGES.node : (IMAGES[runtime] ?? IMAGES.node)}`,
+    'WORKDIR /app',
+    'ENV NODE_ENV=production HOST=0.0.0.0 PORT=8080',
+    // `weft start` runs each sidecar next to the server; without one the server is all there is
+    ...(needs.sidecar
+      ? [
+          'COPY --from=build /app ./',
+          'EXPOSE 8080',
+          `CMD ["${manager.x.split(' ')[0]}", ${manager.x.includes(' ') ? `"${manager.x.split(' ')[1]}", ` : ''}"weft", "start"]`,
+        ]
+      : [
+          'COPY --from=build /app/.output ./.output',
+          'EXPOSE 8080',
+          `CMD ${RUN[runtime] ?? RUN.node}`,
+        ]),
+  ]
+  return `${lines.join('\n')}\n`
+}
+
+const DOCKERIGNORE =
+  'node_modules\n.output\n.weft/*\n!.weft/plugins.lock.json\n.env\n.env.*\n.git\n.netlify\n.vercel\ntarget\n'
+
+function flyToml({ deploy, needs }) {
+  const fly = deploy.fly ?? {}
+  const held = needs.required || needs.feed || needs.sidecar
+  const lines = [
+    `app = ${JSON.stringify(fly.app ?? 'my-app')}`,
+    `primary_region = ${JSON.stringify(fly.region ?? 'iad')}`,
+    '',
+    '[env]',
+    '  PORT = "8080"',
+    ...(needs.uploads && fly.volume
+      ? [`  WEFT_MEDIA_DIR = "${fly.volume.path ?? DATA}/media"`]
+      : []),
+    '',
+    '[http_service]',
+    '  internal_port = 8080',
+    '  force_https = true',
+    '  auto_stop_machines = "stop"',
+    '  auto_start_machines = true',
+    // a change feed is a listener: a stopped machine hears nothing
+    `  min_machines_running = ${held ? 1 : 0}`,
+    ...(fly.volume
+      ? [
+          '',
+          '[[mounts]]',
+          `  source = ${JSON.stringify(fly.volume.name ?? 'data')}`,
+          `  destination = ${JSON.stringify(fly.volume.path ?? DATA)}`,
+          `  initial_size = "${fly.volume.sizeGb ?? 1}gb"`,
+        ]
+      : []),
+    '',
+    '[[vm]]',
+    `  memory = ${JSON.stringify(fly.memory ?? '512mb')}`,
+  ]
+  return `${lines.join('\n')}\n`
+}
+
+function renderYaml({ deploy, needs }) {
+  const r = deploy.render ?? {}
+  const lines = [
+    'services:',
+    '  - type: web',
+    `    name: ${r.service ?? 'my-app'}`,
+    '    runtime: docker',
+    `    plan: ${r.plan ?? (r.disk ? 'starter' : 'free')}`,
+    `    region: ${r.region ?? 'oregon'}`,
+    // the workflow deploys once `weft check` passes, through the deploy hook
+    '    autoDeploy: false',
+    '    healthCheckPath: /',
+    '    envVars:',
+    '      - key: NODE_ENV',
+    '        value: production',
+    ...(needs.uploads && r.disk
+      ? ['      - key: WEFT_MEDIA_DIR', `        value: ${r.disk.path ?? DATA}/media`]
+      : []),
+    ...(r.disk
+      ? [
+          '    disk:',
+          '      name: data',
+          `      mountPath: ${r.disk.path ?? DATA}`,
+          `      sizeGB: ${r.disk.sizeGb ?? 1}`,
+        ]
+      : []),
+  ]
+  return `${lines.join('\n')}\n`
+}
+
+const netlifyToml = ({ manager }) =>
+  `[build]\n  command = "${manager.x} weft build --preset netlify"\n  publish = "dist"\n\n[build.environment]\n  NODE_VERSION = "26"\n`
+
+const vercelJson = ({ manager }) =>
+  `${JSON.stringify({ $schema: 'https://openapi.vercel.sh/vercel.json', framework: null, installCommand: manager.install.replace(/^corepack enable && /, ''), buildCommand: `${manager.x} weft build --preset vercel` }, null, 2)}\n`
+
+const wranglerToml = ({ deploy }) =>
+  `name = ${JSON.stringify(deploy.cloudflare?.name ?? 'my-app')}\ncompatibility_flags = ["nodejs_compat"]\n`
+
+/** The workflow: on push to the branch, check and deploy to production; on a pull request, a preview where the host has one. */
+function workflow({ target, deploy, manager }) {
+  const h = host(target)
+  const previews = h.kind !== 'server'
+  const node =
+    manager.name === 'bun'
+      ? ['      - uses: oven-sh/setup-bun@v2']
+      : [
+          '      - uses: actions/setup-node@v4',
+          '        with:',
+          '          node-version: 26',
+          ...(manager.cache ? [`          cache: ${manager.cache}`] : []),
+        ]
+  const lines = [
+    'name: weft deploy',
+    'on:',
+    '  push:',
+    `    branches: [${deploy.branch ?? 'main'}]`,
+    ...(previews ? ['  pull_request:'] : []),
+    'permissions:',
+    '  contents: read',
+    'concurrency:',
+    // oxlint-disable-next-line no-template-curly-in-string -- a GitHub Actions expression, not a JS template
+    '  group: weft-deploy-${{ github.ref }}',
+    '  cancel-in-progress: true',
+    'jobs:',
+    '  deploy:',
+    '    runs-on: ubuntu-latest',
+    '    steps:',
+    '      - uses: actions/checkout@v4',
+    ...node,
+    ...(target === 'fly' ? ['      - uses: superfly/flyctl-actions/setup-flyctl@master'] : []),
+    `      - run: ${manager.install}`,
+    `      - run: ${manager.x} weft check`,
+    // oxlint-disable-next-line no-template-curly-in-string -- a GitHub Actions expression, not a JS template
+    `      - run: ${manager.x} weft deploy --yes${previews ? " ${{ github.event_name == 'push' && '--prod' || '' }}" : ' --prod'}`,
+    '        env:',
+    ...h.env.map((k) => `          ${k}: \${{ secrets.${k} }}`),
+  ]
+  return `${lines.join('\n')}\n`
+}
+
+const WORKFLOW = '.github/workflows/weft-deploy.yml'
+
+/**
+ * What `weft deploy init <target>` writes, as `{ path, text }`, every text one stamped.
+ * @param {{ target: string, deploy: any, needs: any, runtime: string, manager: any }} ctx
+ */
+export function filesFor(ctx) {
+  const { target } = ctx
+  const out = []
+  const text = (path, body) => out.push({ path, text: stamp(target, body) })
+  if (target === 'netlify') text('netlify.toml', netlifyToml(ctx))
+  if (target === 'vercel') out.push({ path: 'vercel.json', text: vercelJson(ctx), json: true })
+  if (target === 'cloudflare') text('wrangler.toml', wranglerToml(ctx))
+  if (target === 'fly') text('fly.toml', flyToml(ctx))
+  if (target === 'render') text('render.yaml', renderYaml(ctx))
+  if (target === 'fly' || target === 'render') {
+    text('Dockerfile', dockerfile(ctx))
+    out.push({ path: '.dockerignore', text: DOCKERIGNORE, plain: true })
+  }
+  if ((ctx.deploy.ci ?? 'github') === 'github') text(WORKFLOW, workflow(ctx))
+  return out
+}
+
+/**
+ * Each generated file's state: `missing`, `current`, `stale` (weft's, from an older config), `edited` (by hand: left
+ * alone), or `foreign` (no stamp: not weft's).
+ */
+export function fileStates(root, files) {
+  return files.map((f) => {
+    const abs = join(root, f.path)
+    if (!existsSync(abs)) return { ...f, state: 'missing' }
+    const now = readFileSync(abs, 'utf8')
+    if (now === f.text) return { ...f, state: 'current' }
+    if (f.json)
+      return {
+        ...f,
+        state: JSON.parse(now || '{}').buildCommand?.includes('weft build --preset vercel')
+          ? 'edited'
+          : 'stale',
+      }
+    if (f.plain) return { ...f, state: 'edited' }
+    const m = STAMP.exec(now)
+    if (!m) return { ...f, state: 'foreign' }
+    return { ...f, state: sha(now.slice(m[0].length)) === m[2] ? 'stale' : 'edited' }
+  })
+}
+
+/** Write what's missing or stale. Never a file weft didn't write, or one edited since. */
+export function writeFiles(root, states, { force = false } = {}) {
+  const written = []
+  for (const f of states) {
+    if (f.state === 'current' || (!force && (f.state === 'edited' || f.state === 'foreign')))
+      continue
+    mkdirSync(dirname(join(root, f.path)), { recursive: true })
+    writeFileSync(join(root, f.path), f.text)
+    written.push(f.path)
+  }
+  return written
+}

package/src/deploy/fit.mjs

@@ -0,0 +1,166 @@
+// Which hosts can run an app, and which one to suggest (research 46 §4). A finding is a need the host can't meet: an
+// error when nothing on that host fixes it, a warning when it runs degraded or needs a paid add-on.
+
+import { HOSTS } from './hosts.mjs'
+
+const SERVERS = "`deploy: { target: 'fly' }` or `'render'`: a server that stays up"
+const SPLIT =
+  'or keep the pages here and run realtime on a small server (the split, `weft docs deploy`)'
+
+/** What a disk need asks of a host, with the config that gives it one. */
+function disk(h, need, cfg = {}, assume) {
+  if (h.disk === 'none')
+    return {
+      severity: 'error',
+      fix:
+        need.what === 'a SQLite file'
+          ? `${SERVERS}, with a volume or disk, or a hosted database here (Postgres on Neon or Supabase, Turso for SQLite)`
+          : `${SERVERS}, with a volume or disk: this weft has no object store for uploads yet (research 46 §9)`,
+    }
+  const has = h.id === 'fly' ? cfg.fly?.volume : cfg.render?.disk
+  if (has) return
+  const add =
+    h.id === 'fly'
+      ? "`deploy.fly.volume: { name: 'data', sizeGb: 1 }` (billed)"
+      : '`deploy.render.disk: { sizeGb: 1 }` (a paid plan)'
+  return {
+    severity: assume ? 'warning' : 'error',
+    fix: `add ${add}: it mounts at \`/app/.data\`, where SQLite's default \`file:.data/app.db\` already is, and uploads go to \`.data/media\``,
+  }
+}
+
+/**
+ * @param {ReturnType<import('./needs.mjs').needsOf>} needs
+ * @param {import('./hosts.mjs').Host} h
+ * @param {{ deploy?: any, assume?: boolean, local?: boolean }} [options] `assume`: a paid add-on is a warning (the hosts list,
+ *   before a target is chosen). `local`: the build is deployed from this machine.
+ * @returns {{ host: string, fits: boolean, findings: { code: string, severity: string, file: string, why: string, fix: string }[] }}
+ */
+export function fit(needs, h, { deploy = {}, assume = false, local = false } = {}) {
+  const findings = []
+  const add = (code, severity, need, why, fix) =>
+    findings.push({ code, severity, file: need.file, why, fix })
+  if (needs.sockets && !h.sockets)
+    add(
+      'E001',
+      'error',
+      needs.sockets,
+      `${needs.sockets.what} holds a WebSocket, and ${h.name} ends each process with its request: the page would load and never connect (R024)`,
+      `${SERVERS}, or \`'cloudflare'\` (Durable Objects), ${SPLIT}`,
+    )
+  if (needs.required && !h.held)
+    add(
+      'E002',
+      'error',
+      needs.required,
+      `${needs.required.what} needs a change feed that stays connected, and ${h.name} keeps no process between requests (R013)`,
+      `${SERVERS}, run \`weft db listen\` on one with \`listener: 'external'\`, or drop \`required\``,
+    )
+  if (needs.sidecar && !h.sidecars)
+    add(
+      'E002',
+      'error',
+      needs.sidecar,
+      `${needs.sidecar.what} is a second process next to the server, and ${h.name} runs only the server`,
+      `${SERVERS} (the image runs both), or deploy the sidecar on its own and set \`rust.services.<name>.external: true\` with its \`WEFT_RUST_<NAME>_URL\``,
+    )
+  if (needs.native && h.kind === 'workers')
+    add(
+      'R104',
+      'error',
+      needs.native,
+      `${needs.native.what} loads an addon or a \`.wasm\` file, and ${h.name} has no file system`,
+      'use `remote()`, or a server host',
+    )
+  for (const key of ['sqlite', 'uploads']) {
+    const need = needs[key]
+    const d = need && disk(h, need, deploy, assume)
+    if (d)
+      add(
+        'E003',
+        d.severity,
+        need,
+        `${need.what} is kept on local disk, and ${h.disk === 'none' ? `${h.name}'s disk is gone after each request` : `${h.name} wipes it on each deploy without one`}`,
+        d.fix,
+      )
+  }
+  if (needs.feed && !h.held)
+    add(
+      'R014',
+      'warning',
+      needs.feed,
+      `${needs.feed.what} needs a process that stays up: on ${h.name}, writes from outside the app won't reach \`.live()\``,
+      `${SERVERS}, or \`weft db listen\` on one with \`listener: 'external'\``,
+    )
+  if (needs.memoryBus && h.many)
+    add(
+      'E009',
+      'warning',
+      needs.memoryBus,
+      `${needs.memoryBus.what} reaches the clients of one instance, and ${h.name} runs many`,
+      h.id === 'cloudflare'
+        ? '`durableObjectBus` in `src/realtime.server.ts`'
+        : '`weft add redis` or `weft add nats`, or `postgresBus({ url })` in `src/realtime.server.ts`',
+    )
+  if (needs.addons && local && h.prebuilt && process.platform !== 'linux')
+    add(
+      'E004',
+      'warning',
+      needs.addons,
+      `${needs.addons.what} has a compiled addon, built here for ${process.platform}, and ${h.name} runs Linux`,
+      "deploy from CI (`deploy.ci: 'github'` builds on Linux), or drop the addon",
+    )
+  return { host: h.id, fits: !findings.some((f) => f.severity === 'error'), findings }
+}
+
+/** Every host, fitted, and the one to suggest (research 46 §4), with why. */
+export function hostsReport(needs, { deploy = {} } = {}) {
+  const fits = HOSTS.map((h) => ({
+    ...fit(needs, h, { deploy, assume: true }),
+    name: h.name,
+    kind: h.kind,
+    cost: h.cost,
+    pricing: h.pricing,
+    deploys: h.deploys,
+  }))
+  return { fits, suggestion: suggest(needs, fits) }
+}
+
+/** @returns {{ host: string, why: string, alternative?: string }} */
+export function suggest(needs, fits = HOSTS.map((h) => fit(needs, h, { assume: true }))) {
+  const ok = (id) => fits.find((f) => f.host === id)?.fits
+  const clean = (id) => ok(id) && !fits.find((f) => f.host === id).findings.length
+  const held = needs.required || needs.sidecar || needs.feed
+  const kept = needs.sqlite || needs.uploads
+  if (!needs.sockets && !held && !kept) {
+    if (clean('netlify'))
+      return {
+        host: 'netlify',
+        why: 'nothing here needs a server that stays up: a CDN with functions behind it is the cheapest and fastest host',
+        alternative: 'vercel',
+      }
+    if (ok('netlify'))
+      return {
+        host: 'netlify',
+        why: 'nothing here needs a server that stays up, once the warnings are fixed',
+        alternative: 'vercel',
+      }
+  }
+  if (needs.sockets && !held && !kept && !needs.native && clean('cloudflare'))
+    return {
+      host: 'cloudflare',
+      why: 'channels need a socket, and a Durable Object holds one for each room without a server to run',
+      alternative: 'fly',
+    }
+  if (kept)
+    return {
+      host: 'fly',
+      why: `${kept.what} needs a disk that lasts: a Fly volume is per machine and cheap`,
+      alternative: 'render',
+    }
+  return {
+    host: 'fly',
+    why: `${(needs.sockets ?? held).what} needs a server that stays up, and Fly runs the app as it is. Render's free instance does too, but sleeps after 15 idle minutes`,
+    alternative: 'render',
+  }
+}