@weft-js/start 0.0.0-stage → 0.1.0

package/src/list.ts

@@ -0,0 +1,224 @@
+// The list contract: one way to ask for a page or a cursor, whatever holds
+// the rows. `listInput` is a schema a `query` takes as its `input`, and a source is what the `@weft-js/db` subpaths build.
+//
+//   export const tasks = query({
+//     input: listInput({ sort: ['rank', 'title'], filter: ['status'], search: ['title'], pageSize: { default: 25, max: 100 } }),
+//     run: ({ input }) => Tasks.list(input),
+//   })
+//
+// Every name a client sends is checked against an allowlist twice, here and against the source's `columns`, so no
+// request reaches an identifier. A filter value is a scalar or a list of them: an object is refused, which
+// is what stops `{ $ne: null }` reaching a document store. Only `columns` are selected, returned or written.
+
+import { StartError, type StandardSchemaV1 } from './data'
+
+/** One value a filter can hold. */
+export type Scalar = string | number | boolean | null
+/** Which way a sort runs. */
+export type Dir = 'asc' | 'desc'
+/** One field and a direction. */
+export interface Sort { field: string; dir: Dir }
+
+/** A checked request, as a source takes it. */
+export interface ListParams {
+  mode: 'page' | 'cursor'
+  limit: number
+  /** Rows to skip, in `page` mode. */
+  offset: number
+  /** The position to continue after, in `cursor` mode: the last row's sort value and id. */
+  after: [value: unknown, id: unknown] | null
+  sort: Sort | null
+  search?: string
+  /** A list means any of them. `null` means the field is empty. */
+  filter: Record<string, Scalar | Scalar[]>
+}
+
+/** The envelope warp's `Table` reads. `next` and `prev` go back in as `cursor` or `page`; absent means no such page. */
+export interface ListPage<T> { items: T[]; total?: number; next?: string | number; prev?: string | number }
+
+/** What a list lets a client ask for. */
+export interface ListSpec {
+  /** Required, even empty: nothing is sortable, filterable or searchable by default. */
+  sort: readonly string[]
+  filter: readonly string[]
+  search?: readonly string[]
+  defaultSort?: Sort
+  pageSize?: { default?: number; max?: number }
+}
+
+/** What a client sends: every field is checked by `listInput`. */
+export interface ListRequest {
+  mode?: 'page' | 'cursor'
+  page?: number
+  pageSize?: number
+  cursor?: string | null
+  sort?: Sort | null
+  search?: string
+  filter?: Record<string, Scalar | Scalar[]>
+}
+
+const SEARCH_MAX = 200, IN_MAX = 100, CURSOR_MAX = 1024
+
+const scalar = (v: unknown): v is Scalar => v === null || typeof v === 'boolean' || typeof v === 'string' || (typeof v === 'number' && Number.isFinite(v))
+
+const pack = (v: unknown) => (v instanceof Date ? { $d: v.toISOString() } : v)
+const stamped = (v: unknown): v is { $d: string } => typeof (v as { $d?: unknown } | null)?.$d === 'string'
+const unpack = (v: unknown) => (stamped(v) ? new Date(v.$d) : v)
+
+/** Opaque to a client, and read with the same care as any other input. */
+export function encodeCursor(value: unknown, id: unknown): string {
+  const bytes = new TextEncoder().encode(JSON.stringify([pack(value), pack(id)]))
+  return btoa(String.fromCharCode(...bytes)).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '')
+}
+
+/** The other way from `encodeCursor`: null for anything that isn't a cursor of ours. */
+export function decodeCursor(text: string): [unknown, unknown] | null {
+  if (text.length > CURSOR_MAX) return null
+  try {
+    const bytes = Uint8Array.from(atob(text.replaceAll('-', '+').replaceAll('_', '/')), c => c.charCodeAt(0))
+    const list: unknown = JSON.parse(new TextDecoder().decode(bytes))
+    const fits = (v: unknown) => scalar(v) || (stamped(v) && !Number.isNaN(Date.parse(v.$d)))
+    return Array.isArray(list) && list.length === 2 && list.every(fits) ? [unpack(list[0]), unpack(list[1])] : null
+  } catch {
+    return null
+  }
+}
+
+/** A `query`'s `input`. Takes a `ListRequest` from the client, and hands `run` the `ListParams` a source takes. */
+export function listInput(spec: ListSpec): StandardSchemaV1<ListRequest | undefined, ListParams> {
+  const fallback = spec.pageSize?.default ?? 25, max = spec.pageSize?.max ?? 100
+  const sorts = new Set(spec.sort), filters = new Set(spec.filter)
+  const validate = (input: unknown) => {
+    const issues: { message: string; path?: string[] }[] = []
+    const no = (message: string, ...path: string[]) => void issues.push({ message, path })
+    const r = (input ?? {}) as ListRequest
+    if (typeof r !== 'object' || Array.isArray(r)) return { issues: [{ message: 'a list request is an object' }] }
+    const mode = r.mode ?? (r.cursor !== undefined ? 'cursor' : 'page')
+    if (mode !== 'page' && mode !== 'cursor') no('`mode` is `page` or `cursor`', 'mode')
+    const size = r.pageSize ?? fallback
+    if (!Number.isInteger(size) || size < 1 || size > max) no(`\`pageSize\` is a whole number up to ${max}`, 'pageSize')
+    const page = r.page ?? 1
+    if (!Number.isInteger(page) || page < 1 || page > 1e6) no('`page` is a whole number from 1', 'page')
+    let after: ListParams['after'] = null
+    if (r.cursor != null) {
+      after = typeof r.cursor === 'string' ? decodeCursor(r.cursor) : null
+      if (!after) no('that cursor is not one of ours', 'cursor')
+    }
+    const sort = r.sort ?? spec.defaultSort ?? null
+    if (sort && !(typeof sort === 'object' && sorts.has(sort.field) && (sort.dir === 'asc' || sort.dir === 'desc'))) no('that sort is not allowed', 'sort')
+    if (r.search !== undefined && (typeof r.search !== 'string' || r.search.length > SEARCH_MAX)) no(`\`search\` is text up to ${SEARCH_MAX} characters`, 'search')
+    if (r.search && !spec.search?.length) no('this list has no search', 'search')
+    const filter: ListParams['filter'] = Object.create(null)
+    if (r.filter !== undefined && (typeof r.filter !== 'object' || r.filter === null || Array.isArray(r.filter))) no('`filter` is an object', 'filter')
+    else for (const key of Object.keys(r.filter ?? {})) {
+      const v = r.filter![key]!
+      if (!filters.has(key)) no(`\`${key}\` can't be filtered on`, 'filter', key)
+      else if (Array.isArray(v) ? !(v.length && v.length <= IN_MAX && v.every(scalar)) : !scalar(v)) no(`\`${key}\` takes a value or a list of up to ${IN_MAX}, not an object`, 'filter', key)
+      else filter[key] = v
+    }
+    if (issues.length) return { issues }
+    const params: ListParams = { mode, limit: size, offset: mode === 'page' ? (page - 1) * size : 0, after, sort, filter, ...(r.search ? { search: r.search } : {}) }
+    return { value: params }
+  }
+  return { '~standard': { version: 1, vendor: 'weft', validate } }
+}
+
+// ---- sources --------------------------------------------------------------------------------------------------------
+
+/** The allowlist a source reads and writes through. */
+export interface SourceSpec {
+  /** Public name → stored name. Required: only these are selected, returned or written. */
+  columns: Record<string, string>
+  /** The public name of the row's id. Default `id`. */
+  id?: string
+  /** Public names `search` scans. */
+  search?: readonly string[]
+  /** Public names a write may set. Default every column but the id. */
+  write?: readonly string[]
+}
+
+/** One table or collection, read and written the same way whatever holds it. */
+export interface ListSource<Row = Record<string, unknown>> {
+  list(params: ListParams): Promise<ListPage<Row>>
+  get(id: unknown): Promise<Row | null>
+  create(data: Record<string, unknown>): Promise<Row>
+  /** Null when there's no such row. */
+  update(id: unknown, patch: Record<string, unknown>): Promise<Row | null>
+  remove(id: unknown): Promise<boolean>
+  /** What it can't do, so a page can leave the control out. */
+  readonly limits?: { page?: false; search?: 'prefix' | 'cased' | false; sort?: readonly string[] }
+}
+
+/** `db.adapter@1`: what a provider exports. `target` is the driver's handle: a collection, a table, a query function. */
+export interface DbAdapter<T = unknown> {
+  readonly name: string
+  source<Row = Record<string, unknown>>(target: T, spec: SourceSpec): ListSource<Row>
+}
+
+const refuse = (what: string) => new StartError('Q002', `the list source refused ${what}`, 'add it to the source\'s `columns`, and to `listInput`', { status: 400 })
+
+/** A request checked against the source and put in stored names. Throws on any name outside `columns`. */
+export interface Plan {
+  sort: { column: string; dir: Dir; field: string } | null
+  /** The last thing to order by, so rows that tie keep one order across pages. */
+  id: { column: string; field: string }
+  where: { column: string; values: Scalar[] }[]
+  search?: { columns: string[]; text: string }
+}
+
+/** Stored name of the row's id. A spec without one can't address a row, so a write can't go nowhere in silence. */
+export function storedId(spec: SourceSpec): string {
+  const id = spec.id ?? 'id'
+  if (!Object.hasOwn(spec.columns, id)) throw refuse(`\`${id}\` as the id`)
+  return spec.columns[id]!
+}
+
+/** Check a request against `spec`, for a source to run. */
+export function plan(spec: SourceSpec, p: ListParams): Plan {
+  const stored = (field: string) => (Object.hasOwn(spec.columns, field) ? spec.columns[field]! : (() => { throw refuse(`\`${field}\``) })())
+  const id = spec.id ?? 'id'
+  const where = Object.keys(p.filter).map(field => ({ column: stored(field), values: [p.filter[field]!].flat() }))
+  if (where.some(w => !w.values.every(scalar))) throw refuse('a filter value that is not a scalar')
+  const searching = p.search ? spec.search ?? [] : []
+  if (p.search && !searching.length) throw refuse('a search')
+  return {
+    sort: p.sort ? { column: stored(p.sort.field), dir: p.sort.dir, field: p.sort.field } : null,
+    id: { column: stored(id), field: id },
+    where,
+    ...(p.search ? { search: { columns: searching.map(stored), text: p.search } } : {}),
+  }
+}
+
+/** A stored row in public names, with only `columns` in it. */
+export const rowOf = <Row = Record<string, unknown>>(spec: SourceSpec) => {
+  const pairs = Object.entries(spec.columns)
+  return (row: object) => Object.fromEntries(pairs.filter(([, c]) => c in row).map(([f, c]) => [f, (row as Record<string, unknown>)[c]])) as Row
+}
+
+/** A write in stored names. Refuses anything outside `write`, so a client can't set `role` or move an id. */
+export function written(spec: SourceSpec, data: Record<string, unknown>, creating = false): Record<string, unknown> {
+  const id = spec.id ?? 'id'
+  const allowed = new Set(spec.write ?? Object.keys(spec.columns).filter(f => f !== id))
+  if (creating) allowed.add(id)
+  const out: Record<string, unknown> = {}
+  for (const field of Object.keys(data)) {
+    if (!allowed.has(field) || !Object.hasOwn(spec.columns, field)) throw refuse(`a write to \`${field}\``)
+    out[spec.columns[field]!] = data[field]
+  }
+  return out
+}
+
+/** `rows` are in public names, with one more than `limit` in cursor mode when there is a next page. */
+export function pageOf<R>(rows: R[], p: ListParams, field: { sort?: string | undefined; id: string }, total?: number): ListPage<R> {
+  if (p.mode === 'page') {
+    const page = p.offset / p.limit + 1
+    return { items: rows, ...(total === undefined ? {} : { total }), ...(total !== undefined && p.offset + p.limit < total ? { next: page + 1 } : {}), ...(page > 1 ? { prev: page - 1 } : {}) }
+  }
+  const more = rows.length > p.limit
+  const items = more ? rows.slice(0, p.limit) : rows
+  const last = items.at(-1) as R & Record<string, unknown>
+  return { items, ...(total === undefined ? {} : { total }), ...(more ? { next: encodeCursor(field.sort ? last[field.sort] : last[field.id], last[field.id]) } : {}) }
+}
+
+/** `LIKE` with `!` as the escape: the one character that means the same on SQLite, Postgres and MySQL. */
+export const likeOf = (text: string) => `%${text.replace(/[!%_]/g, '!$&')}%`.toLowerCase()

package/src/listen.ts

@@ -0,0 +1,28 @@
+// `weft db listen`: the change feed as a process of its own, for an app on functions, which can't hold a connection. It
+// publishes pokes to the app's bus, so it needs a bus every instance reads, and its heartbeat is how the app knows it's up.
+
+import type { Bus } from './bus'
+import { createFeed, type Source } from './changes'
+import { StartError } from './data'
+
+const BEAT = 10_000
+
+/** Listens until the returned `stop`. Run one: two listeners poke twice, which costs a refetch and loses nothing. */
+export async function listen({ changes, bus, say = console.info, beat = BEAT }: { changes: Source; bus: Bus; say?: (line: string) => void; beat?: number }) {
+  if (bus.name === 'memory') throw new StartError('R017', '`weft db listen` publishes to the bus, and the memory bus stops at this process', 'set `bus` in `src/realtime.server.ts`')
+  const how = await changes.probe()
+  say(`weft live: ${how.mode} (${how.via})${how.why ? `: ${how.why}` : ''}`)
+  if (how.mode !== 'feed') throw new StartError('R015', `this listener has no real feed${how.why ? `: ${how.why}` : ''}`, how.fix)
+  const feed = createFeed(changes, {
+    emit: p => void bus.publish('weft:poke', JSON.stringify(p)).catch(e => say(`weft live: publish failed: ${e?.message ?? e}`)),
+    status: down => say(down ? `weft live: down: ${down}` : 'weft live: back'),
+  })
+  await feed.start(how)
+  const beats = setInterval(() => void bus.publish('weft:poke', '{"v":1,"b":1}').catch(() => {}), beat)
+  await bus.publish('weft:poke', '{"v":1,"b":1}')
+  return async () => {
+    clearInterval(beats)
+    await feed.stop()
+    await bus.close?.()
+  }
+}

package/src/live-fake.ts

@@ -0,0 +1,42 @@
+// @weft-js/core/test's realtime transport (research 30 §7): the real hub, a memory bus, frames through JSON.
+
+import { fakeScope, FnError, net, runtime, type Fn } from './data'
+import type { Body } from './hub'
+
+const loadExec = async () => (runtime.exec ??= await import('./exec'))
+
+/** A change to a connection's subscriptions, as the route would take it. */
+export async function change(body: Body) {
+  const [{ hub }, exec] = await Promise.all([import('./hub'), loadExec()])
+  const c = hub().find(body.k!)
+  if (!c) throw new FnError({}, 404)
+  const request = new Request('http://localhost/_weft/rt', { method: 'POST' })
+  await hub().change(c, request, fakeScope(exec, net()!, request).options, body)
+}
+
+/** A connection to the real hub in this process. */
+export async function open(body: Body, frame: (event: string, data: unknown) => void, signal: AbortSignal, up: () => void, subs: Map<string, { fn: Fn; input: unknown }>, closing: (close: () => unknown) => void) {
+  const n = net()!
+  const [{ hub, resetHub }, exec] = await Promise.all([import('./hub'), loadExec()])
+  if (!n.online()) throw Object.assign(new Error('offline'), { name: 'OfflineError' })
+  closing(resetHub)
+  const h = hub()
+  runtime.poke ??= (tags, origin) => hub().poke(tags, origin)
+  const request = new Request('http://localhost/_weft/rt', { method: 'POST' })
+  return new Promise<void>((done, fail) => {
+    let conn: Parameters<typeof h.close>[0] | undefined
+    const sink = { write: (e: string, d: string) => frame(e, JSON.parse(d)), backlog: () => 0, close: () => done() }
+    n.rt = {
+      push: (id, msg) => h.push(id, msg),
+      poke: tags => h.poke(tags),
+      drop: () => conn && h.close(conn),
+      subscriptions: () => [...subs.values()].map(s => ({ kind: s.fn.kind, id: s.fn.$id, input: s.input })),
+    }
+    signal.addEventListener('abort', () => (conn ? h.close(conn) : done()))
+    h.connect(request, fakeScope(exec, n, request), body, sink).then(c => {
+      conn = c
+      if (signal.aborted) h.close(c)
+      up()
+    }, fail)
+  })
+}

package/src/live-target.mjs

@@ -0,0 +1,144 @@
+// What a deploy target can do for live data, from its preset and config alone: `weft check`, `weft build` and `weft
+// doctor` read this. What only a running server can know (a pooler, a missing trigger) the server probes at startup.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const LISTENER = 'run `weft db listen` on any always-on host (a VPS, Fly, Railway), publishing into a shared bus, and set `dbChanges(db, tables, { listener: \'external\' })`'
+const SERVER = 'deploy to a server preset (`node_server`, `bun`, `deno_server`, or a container on Fly, Railway or Render)'
+const POLLED = 'or poll the query yourself by reloading: `.live()` still updates on mutations'
+
+/** Presets that give each request its own short-lived process. */
+const FUNCTIONS = [
+  [/^vercel/, 'Vercel Functions'], [/^netlify/, 'Netlify Functions'], [/^aws[-_]lambda/, 'AWS Lambda'], [/^azure/, 'Azure Functions'],
+  [/^firebase/, 'Firebase Functions'], [/^cloudflare/, 'Cloudflare Workers'], [/^deno[-_]deploy/, 'Deno Deploy'],
+]
+
+/**
+ * @param {string} [preset]
+ * @returns {{ preset: string, held: boolean, host: string }} `held`: one process outlives a request, so it can hold a connection and a timer
+ */
+export function liveTarget(preset = 'node') {
+  const hit = FUNCTIONS.find(([re]) => re.test(preset))
+  return hit ? { preset, held: false, host: hit[1] } : { preset, held: true, host: 'a long-running server' }
+}
+
+const SKIP = new Set(['node_modules', '.weft', '.output', 'dist'])
+
+/** `live: { required: true }` on a query, and `.live(input, { required: true })` in a component, with where. */
+export function scanRequired(root) {
+  const out = []
+  const walk = dir => {
+    for (const d of readdirSync(dir, { withFileTypes: true })) {
+      const f = join(dir, d.name)
+      if (d.isDirectory()) { if (!SKIP.has(d.name)) walk(f) } else if (/\.[cm]?[jt]sx?$/.test(d.name) && !/\.test\./.test(d.name)) read(f)
+    }
+  }
+  const read = file => {
+    const text = readFileSync(file, 'utf8')
+    if (!/required:\s*true/.test(text)) return
+    for (const m of text.matchAll(/\blive:\s*\{[^}]*required:\s*true/g)) {
+      const name = [...text.slice(0, m.index).matchAll(/\b(\w+)\s*=\s*query\s*[(<]/g)].at(-1)?.[1]
+      if (name) out.push({ name, file: file.slice(root.length + 1) })
+    }
+    for (const m of text.matchAll(/\b(\w+)\.live\(([^;\n]*?)\brequired:\s*true/g)) out.push({ name: m[1], file: file.slice(root.length + 1) })
+  }
+  const src = join(root, 'src')
+  if (existsSync(src)) walk(src)
+  return [...new Map(out.map(r => [r.name, r])).values()]
+}
+
+/**
+ * What this deploy gets, for `weft doctor`, and the diagnostics `weft check` and `weft build` report.
+ * @param {{ preset?: string, source?: { name: string, external?: boolean, tables: string[] }, required?: { name: string, file: string }[] }} input
+ */
+export function livePlan({ preset, source, required = [] }) {
+  const target = liveTarget(preset)
+  const names = required.map(r => `\`${r.name}\``).join(', ')
+  const diagnostics = []
+  const options = target.held ? [] : [LISTENER, SERVER]
+  let mode, says
+  if (!source) {
+    mode = 'app'
+    says = 'Mutations update `.live()` queries. Writes from outside the app do not: nothing listens to the database.'
+    if (required.length) diagnostics.push({ code: 'R013', severity: 'error', why: `${names} require${required.length > 1 ? '' : 's'} a live feed, and \`src/realtime.server.ts\` sets no \`changes\`. Add \`changes: dbChanges(db, [tables])\`, or drop \`required\`.` })
+  } else if (source.external) {
+    mode = 'external'
+    says = `A separate listener reports writes to ${source.tables.join(', ')} through the bus. It is yours to keep running; \`.live()\` shows \`reconnecting\` when it goes quiet.`
+  } else if (target.held) {
+    mode = 'feed'
+    says = `This server listens to ${source.name} for writes to ${source.tables.join(', ')}. At startup it probes what the database allows, and logs what it settled on.`
+  } else {
+    mode = 'off'
+    says = `${target.host} ends a process with its request, so nothing can hold a connection to ${source.name}: mutations update \`.live()\`, and writes from outside the app do not. \`.live()\` shows \`degraded\`.`
+    if (required.length) diagnostics.push({ code: 'R013', severity: 'error', why: `${names} require${required.length > 1 ? '' : 's'} a live feed, and \`${target.preset}\` can't hold one: ${target.host} ends a process with its request. Either ${LISTENER}, or ${SERVER}, or drop \`required\`.` })
+    else diagnostics.push({ code: 'R014', severity: 'warning', why: `\`changes\` needs a process that stays up, and on \`${target.preset}\` none does: writes from outside the app won't reach \`.live()\`. Either ${LISTENER}, or ${SERVER}, ${POLLED}.` })
+  }
+  return { preset: target.preset, held: target.held, host: target.host, mode, says, required: required.map(r => r.name), options, diagnostics }
+}
+
+// ---- `verify` ---------------------------------------------------------------------------------------------------------
+
+const PRODUCTION = /(^|[.\-_])(prod|production|live|www|main|master)([.\-_]|$)/i
+const NOT_PRODUCTION = /(^|[.\-_])(staging|stage|stg|dev|develop|development|test|testing|qa|sandbox|preview|uat|demo)([.\-_]|$)|^localhost$|^127\.|^\[?::1\]?$/i
+
+const hostOf = url => { try { return new URL(url).hostname } catch { return url } }
+const dbNameOf = url => { try { return new URL(url).pathname.slice(1) } catch { return '' } }
+
+const HOWTO = 'Set `WEFT_STAGING_URL` to a running staging app, `STAGING_DATABASE_URL` to its database, or both for the whole chain.'
+
+/**
+ * Where a `verify` points, from the query's declaration, `live.targets` in weft.config.ts and the environment.
+ * @returns {{ name: string, url?: string, db?: string, marked: boolean } | { missing: string }}
+ */
+export function resolveTarget(verify, { targets = {}, env = process.env } = {}) {
+  if (typeof verify === 'object' && verify.target !== undefined) return resolveTarget(verify.target, { targets, env })
+  if (verify === true) {
+    const url = env.WEFT_STAGING_URL, db = env.STAGING_DATABASE_URL
+    return url || db ? { name: 'staging', url, db, marked: false } : { missing: `\`verify: true\` found neither \`WEFT_STAGING_URL\` nor \`STAGING_DATABASE_URL\`. ${HOWTO}` }
+  }
+  if (typeof verify === 'string') {
+    const t = targets[verify]
+    if (!t) return { missing: `\`verify: '${verify}'\` names no target. Add it to weft.config.ts: \`live: { targets: { ${verify}: { url: 'https://…', db: 'STAGING_DATABASE_URL', production: false } } }\`` }
+    const db = t.db && (t.db.includes('://') ? t.db : env[t.db])
+    if (t.db && !db) return { missing: `target \`${verify}\` reads its database from \`${t.db}\`, which isn't set on this machine.` }
+    return { name: verify, url: t.url, db, marked: t.production === false }
+  }
+  if (!verify.url && !verify.db) return { missing: `\`verify\` got an empty target (is its env var set?). ${HOWTO}` }
+  return { name: 'inline', url: verify.url, db: verify.db, marked: false }
+}
+
+/** Why this target must not be touched: R022. Anything that says production is refused, whatever config says. */
+export function refusal(target, { targets = {} } = {}) {
+  const hosts = [target.url && hostOf(target.url), target.db && hostOf(target.db)].filter(Boolean)
+  const names = [target.name, ...hosts, ...(target.db ? [dbNameOf(target.db)] : [])]
+  const said = names.find(n => PRODUCTION.test(n))
+  if (said) return `\`${said}\` looks like production: \`verify\` writes rows, and won't go near it`
+  if (target.name !== 'inline' && target.name !== 'staging' && targets[target.name]?.production !== false) return `target \`${target.name}\` isn't marked: add \`production: false\` to it in weft.config.ts`
+  if (target.marked) return
+  const unsure = hosts.find(h => !NOT_PRODUCTION.test(h))
+  if (unsure) return `nothing says \`${unsure}\` isn't production. Name it in weft.config.ts: \`live: { targets: { staging: { db: 'STAGING_DATABASE_URL', production: false } } }\`, and use \`verify: 'staging'\``
+}
+
+const PASSWORD = /[a-z][a-z0-9+.-]*:\/\/[^\s'"`/:@]+:[^\s'"`/@]+@/i
+
+/** R020: a connection string with a password, written into source. An env var's value never reaches this. */
+export function literalSecrets(root) {
+  const out = []
+  const look = file => {
+    const text = readFileSync(file, 'utf8')
+    if (!/\b(verify|targets)\b/.test(text)) return
+    text.split('\n').forEach((line, i) => {
+      if (PASSWORD.test(line) && /\b(db|url|verify)\b/.test(line)) out.push({ file: file.slice(root.length + 1), line: i + 1 })
+    })
+  }
+  const walk = dir => {
+    for (const d of readdirSync(dir, { withFileTypes: true })) {
+      const f = join(dir, d.name)
+      if (d.isDirectory()) { if (!SKIP.has(d.name)) walk(f) } else if (/\.[cm]?[jt]sx?$/.test(d.name)) look(f)
+    }
+  }
+  if (existsSync(join(root, 'src'))) walk(join(root, 'src'))
+  for (const f of ['weft.config.ts', 'weft.config.js', 'weft.config.mjs']) if (existsSync(join(root, f))) look(join(root, f))
+  return out
+}