@weft-js/cli 0.0.0-stage → 0.1.1

package/src/deploy/files.mjs

@@ -0,0 +1,187 @@
+// 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:',
+    '  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`,
+    `      - 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,62 @@
+// 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' }
+}

package/src/deploy/hosts.mjs

@@ -0,0 +1,56 @@
+// The hosts `weft deploy` knows (research 46 §3): what each can run, its preset, what its CLI reads, and a cost hint.
+// The fit (fit.mjs) and the generated files (files.mjs) both read this table, so they can't disagree about a host.
+
+/**
+ * @typedef {{
+ *   id: string, name: string, kind: 'functions' | 'workers' | 'server',
+ *   preset?: string, sockets: boolean, held: boolean, disk: 'none' | 'volume' | 'paid-disk', sidecars: boolean,
+ *   many: boolean, prebuilt: boolean, env: string[], cost: string, pricing: string, docs: string, deploys: boolean,
+ * }} Host
+ * `preset`: the Nitro preset, or none for the runtime's server preset. `prebuilt`: what is built here is what ships, so a
+ * native addon from this machine goes too. `deploys`: `weft deploy` drives it (AWS is a fit only, research 46 §11).
+ */
+
+/** @type {Host[]} */
+export const HOSTS = [
+  {
+    id: 'netlify', name: 'Netlify', kind: 'functions', preset: 'netlify', sockets: false, held: false, disk: 'none', sidecars: false, many: true, prebuilt: true,
+    env: ['NETLIFY_AUTH_TOKEN', 'NETLIFY_SITE_ID'], deploys: true,
+    cost: 'free tier; usage past it is billed in credits', pricing: 'https://www.netlify.com/pricing/', docs: 'https://docs.netlify.com/cli/get-started/',
+  },
+  {
+    id: 'vercel', name: 'Vercel', kind: 'functions', preset: 'vercel', sockets: false, held: false, disk: 'none', sidecars: false, many: true, prebuilt: true,
+    env: ['VERCEL_TOKEN', 'VERCEL_ORG_ID', 'VERCEL_PROJECT_ID'], deploys: true,
+    cost: 'Hobby is free for non-commercial use; Pro is per seat', pricing: 'https://vercel.com/pricing', docs: 'https://vercel.com/docs/cli',
+  },
+  {
+    id: 'cloudflare', name: 'Cloudflare Workers', kind: 'workers', preset: 'cloudflare_durable', sockets: true, held: false, disk: 'none', sidecars: false, many: true, prebuilt: true,
+    env: ['CLOUDFLARE_API_TOKEN', 'CLOUDFLARE_ACCOUNT_ID'], deploys: true,
+    cost: 'free tier includes Workers and SQLite-backed Durable Objects', pricing: 'https://developers.cloudflare.com/workers/platform/pricing/', docs: 'https://developers.cloudflare.com/workers/wrangler/',
+  },
+  {
+    id: 'fly', name: 'Fly.io', kind: 'server', sockets: true, held: true, disk: 'volume', sidecars: true, many: false, prebuilt: false,
+    env: ['FLY_API_TOKEN'], deploys: true,
+    cost: 'pay as you go, no free tier for new organizations', pricing: 'https://fly.io/docs/about/pricing/', docs: 'https://fly.io/docs/flyctl/',
+  },
+  {
+    id: 'render', name: 'Render', kind: 'server', sockets: true, held: true, disk: 'paid-disk', sidecars: true, many: false, prebuilt: false,
+    env: ['RENDER_DEPLOY_HOOK_URL'], deploys: true,
+    cost: 'free instance sleeps after 15 idle minutes and has no disk; paid plans add a disk', pricing: 'https://render.com/pricing', docs: 'https://render.com/docs/blueprint-spec',
+  },
+  {
+    id: 'aws', name: 'AWS Lambda', kind: 'functions', preset: 'aws_lambda', sockets: false, held: false, disk: 'none', sidecars: false, many: true, prebuilt: true,
+    env: [], deploys: false,
+    cost: 'Lambda has a free tier; a server would go on App Runner, billed per running instance', pricing: 'https://aws.amazon.com/pricing/', docs: 'https://nitro.build/deploy/providers/aws',
+  },
+]
+
+export const TARGETS = HOSTS.filter(h => h.deploys).map(h => h.id)
+
+export const host = id => HOSTS.find(h => h.id === id)
+
+/** `runtime` in the config as the server preset a container runs. */
+const SERVER_PRESETS = { node: 'node', bun: 'bun', deno: 'deno_server' }
+
+/** The preset a build for this host uses. */
+export const presetFor = (h, runtime = 'node') => h.preset ?? SERVER_PRESETS[runtime] ?? 'node'

package/src/deploy/index.mjs

@@ -0,0 +1,273 @@
+// `weft deploy`, `weft deploy hosts`, `weft deploy init`, and what `weft check` and `weft doctor` say about the deploy
+// (research 46). Nothing here talks to a provider except `weft deploy --yes`, which runs the host's own CLI.
+
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import ts from 'typescript'
+import { diagnostic, locate } from '../diag.mjs'
+import { findConfig, isDataConfig } from '../load-config.mjs'
+import { cdnFindings, writtenSecrets } from './cdn.mjs'
+import { fileStates, filesFor, managerOf, writeFiles } from './files.mjs'
+import { fit, hostsReport } from './fit.mjs'
+import { HOSTS, TARGETS, host, presetFor } from './hosts.mjs'
+import { needsOf } from './needs.mjs'
+
+export { HOSTS, TARGETS, fit, hostsReport, needsOf }
+
+const usage = message => Object.assign(new Error(message), { code: 'E_USAGE' })
+const refused = message => Object.assign(new Error(message), { code: 'E_REFUSED' })
+
+/** A finding as a diagnostic, pointing at the file that shows the need. */
+function toDiagnostic(root, f) {
+  let text = ''
+  try { text = readFileSync(join(root, f.file), 'utf8') } catch {}
+  const at = f.line ? { span: [f.line, 1, f.line, 1] } : text && f.needle ? locate(text, f.needle) : {}
+  return diagnostic({ code: f.code, severity: f.severity, file: f.file, ...at, why: f.why, help: f.fix })
+}
+
+/** The target this run is about: `--target`, then `deploy.target`, then the host whose preset `--preset` names. */
+export function targetOf(config, { target, preset } = {}) {
+  const id = target ?? config.deploy?.target ?? (preset && HOSTS.find(h => h.preset === preset)?.id)
+  if (id && !host(id)) throw usage(`unknown deploy target \`${id}\`: use ${TARGETS.join(', ')}`)
+  return id
+}
+
+/** E001–E004, E006, E008–E014 for `weft check`: the configured target's fit, its files, written secrets, CDN setup. */
+export function deployChecks(root, config, { preset } = {}) {
+  const out = writtenSecrets(root).map(s => ({ code: 'E008', severity: 'error', file: s.file, line: s.line, why: `${s.file}:${s.line} has ${s.what} in it: it would be committed, and anyone with the repository could deploy or bill as you`, fix: 'Move it to the environment (the host\'s settings, or GitHub\'s secrets for the workflow), and rotate it: it has been seen' }))
+  let id
+  try { id = targetOf(config, { preset }) } catch { id = undefined }
+  const deploy = config.deploy ?? {}
+  if (id) {
+    out.push(...fit(needsOf(root, config), host(id), { deploy }).findings)
+    if (deploy.target === id && host(id).deploys) {
+      for (const f of fileStates(root, filesFor(initContext(root, config, id)))) {
+        if (f.state === 'missing' || f.state === 'stale') out.push({ code: 'E006', severity: 'warning', file: f.path, why: `\`${f.path}\` is ${f.state === 'missing' ? 'missing' : 'from an older config'}: ${host(id).name} would deploy ${f.state === 'missing' ? 'without it' : 'what it said then'}`, fix: '`weft deploy init` writes it (a file edited by hand is left alone)' })
+      }
+    }
+  }
+  out.push(...cdnFindings(config))
+  return out.map(f => toDiagnostic(root, f))
+}
+
+/** What the generators read. */
+export function initContext(root, config, target) {
+  return { target, deploy: config.deploy ?? {}, needs: needsOf(root, config), runtime: config.runtime ?? 'node', manager: managerOf(root) }
+}
+
+/** `weft deploy hosts`, and the `deploy` part of `weft doctor`: every host's fit and the suggestion (E005 when none is set). */
+export function hostsCommand(root, config) {
+  const needs = needsOf(root, config)
+  const report = hostsReport(needs, { deploy: config.deploy })
+  const used = Object.entries(needs).filter(([k, v]) => k !== 'runtime' && v).map(([k, v]) => ({ need: k, ...v }))
+  const diagnostics = config.deploy?.target ? [] : [diagnostic({ code: 'E005', severity: 'info', file: findConfig(root) ? relative(root, findConfig(root)) : 'weft.config.ts', why: `No \`deploy.target\`. ${report.fits.filter(f => f.fits && f.deploys).map(f => f.name).join(', ')} can run this app; weft suggests ${host(report.suggestion.host).name}: ${report.suggestion.why}.`, help: `\`weft deploy init ${report.suggestion.host}\`` })]
+  return { needs: used, ...report, target: config.deploy?.target ?? null, diagnostics }
+}
+
+export function formatHosts(r) {
+  const lines = [`needs: ${r.needs.length ? r.needs.map(n => `${n.what} (${n.file})`).join(', ') : 'nothing a CDN with functions can\'t give'}`, '']
+  for (const f of r.fits) {
+    const mark = f.fits ? (f.findings.length ? '~' : '✓') : '✗'
+    lines.push(`${mark} ${f.host.padEnd(11)} ${f.name}${f.deploys ? '' : ' (fit only: `weft deploy` doesn\'t drive it yet)'}`)
+    for (const x of f.findings) lines.push(`    ${x.code} ${x.why}. Fix: ${x.fix}`)
+    lines.push(`    cost: ${f.cost} (${f.pricing})`)
+  }
+  lines.push('', `suggested: ${r.suggestion.host}, because ${r.suggestion.why}${r.suggestion.alternative ? `. Next best: ${r.suggestion.alternative}` : ''}`)
+  return lines.join('\n')
+}
+
+/** The object literal `export default` gives, directly or through `defineConfig(…)`. */
+function configObject(sf) {
+  for (const st of sf.statements) {
+    if (!ts.isExportAssignment(st)) continue
+    const value = ts.isCallExpression(st.expression) ? st.expression.arguments[0] : st.expression
+    if (value && ts.isObjectLiteralExpression(value)) return value
+  }
+}
+
+/** The `deploy` block init writes when the config has none: the names a host needs, from package.json, and a disk when data needs one. */
+export function defaultDeploy(root, target, needs) {
+  let name = 'my-app'
+  try { name = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).name?.replace(/^@[^/]+\//, '').replace(/[^a-z0-9-]/gi, '-').toLowerCase() || name } catch {}
+  const kept = needs.sqlite || needs.uploads
+  const per = {
+    netlify: { site: name }, vercel: { project: name }, cloudflare: { name },
+    fly: { app: name, region: 'iad', ...(kept && { volume: { name: 'data', sizeGb: 1 } }) },
+    render: { service: name, ...(kept && { plan: 'starter', disk: { sizeGb: 1 } }) },
+  }
+  return { target, [target]: per[target], ci: 'github', branch: 'main' }
+}
+
+const literal = (v, pad = '  ') => {
+  if (v && typeof v === 'object') return `{ ${Object.entries(v).map(([k, x]) => `${k}: ${literal(x, pad)}`).join(', ')} }`
+  return typeof v === 'string' ? `'${v}'` : String(v)
+}
+
+/** The config with `deploy` added. Refuses to touch one that already has it, or that isn't a plain object. */
+export function withDeploy(file, text, deploy) {
+  if (isDataConfig(file)) {
+    if (file.endsWith('.json')) return `${JSON.stringify({ ...JSON.parse(text), deploy }, null, 2)}\n`
+    return `${text.replace(/\n*$/, '\n')}deploy:\n${Object.entries(deploy).map(([k, v]) => `  ${k}: ${JSON.stringify(v)}`).join('\n')}\n`
+  }
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true)
+  const object = configObject(sf)
+  if (!object) throw refused(`${file} doesn't export a plain object, so \`weft deploy init\` can't add \`deploy\` to it. Add \`deploy: ${literal(deploy)}\` by hand. Nothing was changed.`)
+  const block = `deploy: ${literal(deploy)},`
+  const last = object.properties.at(-1)
+  return last ? text.slice(0, object.properties.end) + `${object.properties.hasTrailingComma ? '' : ','}\n  ${block}` + text.slice(object.properties.end) : text.slice(0, object.getStart(sf) + 1) + `\n  ${block}\n` + text.slice(object.getStart(sf) + 1)
+}
+
+/**
+ * `weft deploy init [target]`: the host's files and workflow, and `deploy` in the config when it has none. Refuses a
+ * target the app doesn't fit unless `unsafe` lets the codes through.
+ */
+export function initCommand(root, config, { target, dryRun = false, force = false, unsafe } = {}) {
+  const needs = needsOf(root, config)
+  const id = targetOf(config, { target }) ?? hostsReport(needs).suggestion.host
+  const h = host(id)
+  if (!h.deploys) throw usage(`\`weft deploy\` doesn't drive ${h.name} yet (research 46 §11): ${TARGETS.join(', ')} it does`)
+  if (config.deploy?.target && target && config.deploy.target !== target) throw refused(`\`deploy.target\` is \`${config.deploy.target}\` in the config. Change it there to move to \`${target}\`, then run this again. Nothing was changed.`)
+  const deploy = config.deploy ?? defaultDeploy(root, id, needs)
+  const result = fit(needs, h, { deploy })
+  const blocking = result.findings.filter(f => f.severity === 'error' && !unsafe?.allows(f))
+  if (blocking.length) throw refused(`${h.name} can't run this app:\n${blocking.map(f => `  ${f.code} ${f.file}: ${f.why}.\n       Fix: ${f.fix}`).join('\n')}\n\`weft deploy hosts\` shows which hosts can. Nothing was changed.`)
+  const ctx = { ...initContext(root, { ...config, deploy }, id) }
+  const states = fileStates(root, filesFor(ctx))
+  const configFile = findConfig(root)
+  const actions = []
+  let written = []
+  if (!config.deploy) {
+    const file = configFile ?? join(root, 'weft.config.ts')
+    const text = configFile ? readFileSync(configFile, 'utf8') : "import { defineConfig } from '@weft-js/core/config'\n\nexport default defineConfig({})\n"
+    actions.push(`${relative(root, file)}: ${configFile ? '' : '(new) '}deploy: ${literal(deploy)}`)
+    if (!dryRun) writeFileSync(file, withDeploy(file, text, deploy))
+  }
+  for (const f of states) actions.push(`${f.path}: ${{ missing: 'write', stale: 'rewrite (from an older config)', current: 'current', edited: force ? 'overwrite (edited by hand; --force)' : 'edited by hand: left alone', foreign: force ? 'overwrite (--force)' : 'not written by weft: left alone' }[f.state]}`)
+  if (!dryRun) written = writeFiles(root, states, { force })
+  const next = [
+    ...{
+      netlify: [`netlify sites:create --name ${deploy.netlify?.site ?? '<name>'}   (once; or link an existing site with \`netlify link\`)`],
+      vercel: [`vercel link --project ${deploy.vercel?.project ?? '<name>'}   (once: writes .vercel/project.json with the org and project ids)`],
+      cloudflare: ['wrangler login   (once, locally; CI reads CLOUDFLARE_API_TOKEN)'],
+      fly: [`flyctl apps create ${deploy.fly?.app ?? '<name>'}   (once; billed per running machine)`, ...(deploy.fly?.volume ? [`flyctl volumes create ${deploy.fly.volume.name ?? 'data'} --size ${deploy.fly.volume.sizeGb ?? 1} --region ${deploy.fly.region ?? 'iad'} -a ${deploy.fly.app}   (once; billed)`] : [])],
+      render: ['Create the service from render.yaml: Render dashboard → New → Blueprint, on this repository (once)', 'Copy the service\'s deploy hook (Settings → Deploy Hook) into RENDER_DEPLOY_HOOK_URL'],
+    }[id],
+    ...((deploy.ci ?? 'github') === 'github' ? [`gh secret set ${h.env.join(' / ')}   (each one, from the host's dashboard: weft never writes them)`] : []),
+    `weft deploy   (a dry run: shows what --yes would run)`,
+  ]
+  return { ok: true, target: id, dryRun, actions, written, next, findings: result.findings.map(f => toDiagnostic(root, f)) }
+}
+
+/** The host's CLI: on PATH, else through npx for the ones on npm. */
+function cliFor(name, { which = cmd => spawnSync(process.platform === 'win32' ? 'where' : 'which', [cmd], { encoding: 'utf8' }).status === 0 } = {}) {
+  const npm = { netlify: 'netlify-cli', vercel: 'vercel', wrangler: 'wrangler' }
+  for (const cmd of name === 'flyctl' ? ['flyctl', 'fly'] : [name]) if (which(cmd)) return [cmd]
+  if (npm[name]) return ['npx', '--yes', npm[name]]
+  throw refused(`\`${name}\` isn't installed: ${name === 'flyctl' ? 'https://fly.io/docs/flyctl/install/' : `npm install -g ${npm[name] ?? name}`}`)
+}
+
+/**
+ * The steps `weft deploy` takes for a target, as data: a dry run prints them, `--yes` runs them. A step reads env vars
+ * by name; their values are filled in only as it runs.
+ */
+export function deploySteps(root, config, { target, prod = false, which } = {}) {
+  const h = host(target)
+  const deploy = config.deploy ?? {}
+  const runtime = config.runtime ?? 'node'
+  const needs = needsOf(root, config)
+  const steps = []
+  const build = { kind: 'build', what: `weft build --preset ${presetFor(h, runtime)}`, preset: presetFor(h, runtime) }
+  if (target === 'netlify') {
+    const site = process.env.NETLIFY_SITE_ID ? [] : deploy.netlify?.site ? ['--site', deploy.netlify.site] : []
+    steps.push(build, { kind: 'run', cli: 'netlify', args: ['deploy', '--dir', 'dist', '--functions', '.netlify/functions-internal', '--json', ...site, ...(prod ? ['--prod'] : [])], reads: ['NETLIFY_AUTH_TOKEN', 'NETLIFY_SITE_ID'], url: 'json' })
+  }
+  if (target === 'vercel') steps.push(build, { kind: 'run', cli: 'vercel', args: ['deploy', '--prebuilt', '--yes', ...(prod ? ['--prod'] : [])], token: 'VERCEL_TOKEN', reads: ['VERCEL_TOKEN', 'VERCEL_ORG_ID', 'VERCEL_PROJECT_ID'], url: 'last-line' })
+  if (target === 'cloudflare') steps.push(build, { kind: 'run', cli: 'wrangler', args: ['deploy'], cwd: '.output', reads: ['CLOUDFLARE_API_TOKEN', 'CLOUDFLARE_ACCOUNT_ID'], url: 'workers' })
+  if (target === 'fly') {
+    // one machine unless a bus reaches the others: a second machine would split the rooms, and a volume is per machine
+    const one = needs.memoryBus || deploy.fly?.volume
+    steps.push({ kind: 'run', cli: 'flyctl', args: ['deploy', '--remote-only', ...(deploy.fly?.app ? ['--app', deploy.fly.app] : []), ...(one ? ['--ha=false'] : [])], reads: ['FLY_API_TOKEN'], url: deploy.fly?.app ? `https://${deploy.fly.app}.fly.dev` : 'fly' })
+  }
+  if (target === 'render') steps.push({ kind: 'hook', what: 'POST $RENDER_DEPLOY_HOOK_URL (Render builds the pushed commit)', reads: ['RENDER_DEPLOY_HOOK_URL'], url: deploy.render?.service ? `https://${deploy.render.service}.onrender.com` : undefined })
+  for (const s of steps) if (s.cli) s.what = `${s.cli} ${s.args.join(' ')}${s.token ? ` --token $${s.token}` : ''}${s.cwd ? `   (in ${s.cwd}/)` : ''}`
+  return steps
+}
+
+/** A variable a step reads, and whether its absence stops the deploy (E007). */
+function missingEnv(root, target, config, env) {
+  const ci = !!env.CI
+  const linked = { netlify: existsSync(join(root, '.netlify/state.json')) || !!config.deploy?.netlify?.site, vercel: existsSync(join(root, '.vercel/project.json')) }
+  // a token: the CLI's own login stands in, except in CI. An id: needed unless the project is linked.
+  const token = (k, how) => [k, ci ? 'error' : 'warning', how, ': the CLI\'s own login is used']
+  const id = (k, known, how) => [k, known ? null : 'error', how, '']
+  const need = {
+    netlify: [token('NETLIFY_AUTH_TOKEN', '`netlify login` here, or a personal access token from User settings → Applications'), id('NETLIFY_SITE_ID', linked.netlify, '`netlify link`, `deploy.netlify.site`, or the site id from Site configuration')],
+    vercel: [token('VERCEL_TOKEN', '`vercel login` here, or a token from Account Settings → Tokens'), id('VERCEL_ORG_ID', linked.vercel, '`vercel link` writes it to .vercel/project.json'), id('VERCEL_PROJECT_ID', linked.vercel, '`vercel link` writes it to .vercel/project.json')],
+    cloudflare: [token('CLOUDFLARE_API_TOKEN', '`wrangler login` here, or a token with Workers Scripts: Edit'), id('CLOUDFLARE_ACCOUNT_ID', !ci, 'the account id on the Workers overview page')],
+    fly: [token('FLY_API_TOKEN', '`flyctl auth login` here, or `flyctl tokens create deploy`')],
+    render: [id('RENDER_DEPLOY_HOOK_URL', false, "the service's Settings → Deploy Hook")],
+  }[target]
+  return need.filter(([k, severity]) => severity && !env[k]).map(([k, severity, how, local]) => ({ code: 'E007', severity, file: 'weft.config.ts', why: `\`${k}\` is unset${severity === 'warning' ? local : ''}`, fix: `${how}. Set it in the environment (never a file)` }))
+}
+
+/** The URL a host's CLI printed. */
+export function urlFrom(step, stdout) {
+  if (step.url === 'json') {
+    try { const j = JSON.parse(stdout.slice(stdout.indexOf('{'))); return j.url ?? j.deploy_url } catch { return }
+  }
+  if (step.url === 'last-line') return stdout.trim().split('\n').reverse().find(l => /^https:\/\//.test(l.trim()))?.trim()
+  if (step.url === 'workers') return /https:\/\/[\w.-]+\.workers\.dev/.exec(stdout)?.[0]
+  if (step.url === 'fly') return /https:\/\/[\w.-]+\.fly\.dev/.exec(stdout)?.[0]
+  return step.url
+}
+
+/**
+ * `weft deploy`: fit, then the steps. Without `yes` nothing runs: the result says what would. `build` is `weft build`
+ * in-process (start.mjs's buildCommand), `exec` runs a host CLI; both are injectable for tests.
+ */
+export async function deployCommand(root, config, { target, prod = false, yes = false, unsafe, env = process.env, build, exec = defaultExec, which, post = (url) => fetch(url, { method: 'POST' }) } = {}) {
+  const id = targetOf(config, { target })
+  if (!id) {
+    const s = hostsReport(needsOf(root, config)).suggestion
+    throw refused(`no deploy target: set \`deploy.target\` (\`weft deploy init\` does, and writes the host's files), or pass --target. weft suggests \`${s.host}\`: ${s.why}`)
+  }
+  const h = host(id)
+  if (!h.deploys) throw usage(`\`weft deploy\` doesn't drive ${h.name} yet (research 46 §11)`)
+  if (h.kind === 'server' && !prod) throw usage(`${h.name} has no preview deploys: pass --prod to deploy production`)
+  const needs = needsOf(root, config)
+  const findings = fit(needs, h, { deploy: config.deploy ?? {}, local: !env.CI }).findings
+  const blocking = findings.filter(f => f.severity === 'error' && !unsafe?.allows(f))
+  if (blocking.length) throw refused(`${h.name} can't run this app:\n${blocking.map(f => `  ${f.code} ${f.file}: ${f.why}.\n       Fix: ${f.fix}`).join('\n')}\nTo deploy anyway: --unsafe-allow ${[...new Set(blocking.map(f => f.code))].join(',')}`)
+  const steps = deploySteps(root, config, { target: id, prod, which })
+  const envFindings = missingEnv(root, id, config, env)
+  const diagnostics = [...findings, ...envFindings, ...cdnFindings(config, { env })].map(f => toDiagnostic(root, f))
+  if (!yes) return { ok: true, dryRun: true, target: id, prod, steps: steps.map(s => ({ what: s.what, reads: s.reads ?? [] })), diagnostics }
+  const stop = envFindings.find(f => f.severity === 'error')
+  if (stop) throw refused(`E007: ${stop.why}. ${stop.fix}.`)
+  let url
+  for (const s of steps) {
+    if (s.kind === 'build') {
+      const built = await build(root, { preset: s.preset })
+      diagnostics.push(...built.diagnostics)
+      if (!built.ok) throw refused('weft build failed: nothing was deployed. Fix the errors above.')
+    } else if (s.kind === 'hook') {
+      const res = await post(env.RENDER_DEPLOY_HOOK_URL)
+      if (!res.ok) throw refused(`Render's deploy hook answered ${res.status}: nothing was deployed. Check RENDER_DEPLOY_HOOK_URL.`)
+      url = s.url
+    } else {
+      const [cmd, ...pre] = cliFor(s.cli, { which })
+      const args = [...pre, ...s.args, ...(s.token && env[s.token] ? ['--token', env[s.token]] : [])]
+      const r = await exec(cmd, args, { cwd: join(root, s.cwd ?? ''), env })
+      if (r.code !== 0) throw refused(`${s.cli} failed (exit ${r.code}): nothing more was run.\n${(r.stderr || r.stdout).trim().split('\n').slice(-15).join('\n')}`)
+      url = urlFrom(s, r.stdout) ?? url
+    }
+  }
+  return { ok: true, dryRun: false, target: id, prod, url: url ?? null, diagnostics }
+}
+
+/** A host CLI with its progress on stderr, as it goes, and stdout kept for the URL. */
+function defaultExec(cmd, args, { cwd, env }) {
+  const r = spawnSync(cmd, args, { cwd, env, encoding: 'utf8', stdio: ['inherit', 'pipe', 'inherit'], maxBuffer: 64 * 1024 * 1024 })
+  return { code: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.error?.message ?? '' }
+}