@prestack/thread 0.0.1 → 0.0.2

package/dist/core/asking.ts

@@ -0,0 +1,1342 @@
+import { createHash, randomBytes } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, relative } from 'node:path'
+import { argv, env, exit, stderr, stdin, stdout } from 'node:process'
+import { createInterface } from 'node:readline'
+import { pathToFileURL } from 'node:url'
+import { CONSTRAINTS } from '../integrity/constraint.ts'
+import type { Row } from './descend.ts'
+import { LISTS, descend, listFields, listShape, shapeFields, shapesNamed, type Field } from './descend.ts'
+import { quoted } from './rows.ts'
+import type { Tree } from './tree.ts'
+
+const RECEIPTS = join(tmpdir(), 'thread-create')
+
+export const RECEIPT = '--receipt'
+
+export const ENDS = '.'
+
+export const FROM = '--from'
+
+export const CHAINED = '--chained'
+
+export const BODY = 'body'
+
+export const WRITES = 'writes'
+
+export const asFlag = (key: string): string => `--${key}`
+
+export function refuse(because: string): never {
+  stderr.write(`create: ${because}\n`)
+  exit(1)
+}
+
+export function slug(one: string): string {
+  return one
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+}
+
+export function within(root: string, path: string): string {
+  return relative(root, path).split('\\').join('/')
+}
+
+const NAMED = /^([a-z][A-Za-z0-9_.-]*):[ \t]?(.*)$/
+
+export function parsed(text: string): readonly { readonly at: number; readonly key: string; readonly value: string }[] {
+  const lines = text.split('\n')
+  const found: { at: number; key: string; value: string }[] = []
+  for (let at = 0; at < lines.length; at += 1) {
+    const line = lines[at] ?? ''
+    if (line.trim() === '' || line.trimStart().startsWith('#')) continue
+    const held = NAMED.exec(line)
+    if (held === null) {
+      refuse(
+        `line ${String(at + 1)} is neither blank nor an answer: ${JSON.stringify(line.slice(0, 60))}. ` +
+          'Every answer is written `name: value`, and a body is written under `body:` and ended by a line ' +
+          `holding only ${ENDS}.`,
+      )
+    }
+    const key = held[1] ?? ''
+    if (key !== 'body') {
+      found.push({ at: at + 1, key, value: (held[2] ?? '').trim() })
+      continue
+    }
+
+    const body: string[] = []
+    const beside = held[2] ?? ''
+    if (beside.trim() !== '') body.push(beside)
+    let shut = false
+    for (at += 1; at < lines.length; at += 1) {
+      if ((lines[at] ?? '').trim() === ENDS) {
+        shut = true
+        break
+      }
+      body.push(lines[at] ?? '')
+    }
+    if (!shut) {
+      refuse(
+        `the \`body:\` opened on line ${String(found.length === 0 ? 1 : at)} is never closed — a body ends at a ` +
+          `line holding only ${ENDS}, and this one runs to the end of the input.`,
+      )
+    }
+    found.push({ at: at + 1, key, value: body.join('\n').trim() })
+  }
+  return found
+}
+
+export function scoped(
+  given: readonly { readonly at: number; readonly key: string; readonly value: string }[],
+  opens: string,
+): {
+  readonly own: readonly { readonly at: number; readonly key: string; readonly value: string }[]
+  readonly each: readonly (readonly { readonly at: number; readonly key: string; readonly value: string }[])[]
+} {
+  const own: { at: number; key: string; value: string }[] = []
+  const each: { at: number; key: string; value: string }[][] = []
+  const lists = new Set<string>(LISTS)
+  let mine = false
+  for (const one of given) {
+    if (one.key === opens) {
+      each.push([one])
+      mine = true
+      continue
+    }
+    if (lists.has(one.key)) {
+      mine = false
+      continue
+    }
+    if (mine) (each[each.length - 1] ?? []).push(one)
+    else if (each.length === 0) own.push(one)
+  }
+  return { own, each }
+}
+
+const locate = (one: { readonly at: number; readonly key: string }): string =>
+  one.at > 0 ? `line ${String(one.at)}` : `\`--${one.key}\``
+
+export interface Asked {
+  readonly at: string
+  readonly guide: string
+  readonly asks?: string
+  readonly optional?: boolean
+  readonly list?: boolean
+  readonly map?: boolean
+  readonly boolean?: boolean
+  readonly worded?: boolean
+}
+
+export interface Said {
+  readonly guide: string
+  readonly asks?: string
+  readonly optional?: boolean
+}
+
+let meanings: ReadonlyMap<string, string> | undefined
+
+function coined(word: string): string | undefined {
+  if (meanings === undefined) {
+    const found = new Map<string, string>()
+    try {
+      for (const [id, held] of descend().coined) {
+        const first = held.said[0]
+        if (first !== undefined && first !== '') found.set(id, first)
+      }
+    } catch {
+      found.clear()
+    }
+    meanings = found
+  }
+  return meanings.get(word)
+}
+
+export function asksOf(
+  noun: string,
+  shape: string | readonly Field[],
+  said: Readonly<Record<string, Said>>,
+  computed: readonly string[],
+): readonly Asked[] {
+  const fields: readonly Field[] = typeof shape === 'string' ? shapeFields(shape).map((one) => ({ ...one, boolean: false })) : shape
+  if (fields.length === 0) {
+    refuse(
+      `nothing installed here states what a ${noun} is made of, so \`thread create ${noun}\` has no questions to ` +
+        `ask. It reads that from the shape a ${noun} is declared with rather than from a list kept beside it. ` +
+        'Run `npx thread attach` to see whether the package that states it is taken on.',
+    )
+  }
+
+  const spoken: Record<string, Said> = { ...said }
+  for (const one of fields) {
+    if (spoken[one.name] !== undefined || computed.includes(one.name)) continue
+    const meaning = coined(one.name) ?? (one.guide === '' ? undefined : one.guide)
+    if (meaning === undefined) continue
+    spoken[one.name] = { guide: meaning }
+  }
+
+  const mute = fields
+    .filter((one) => one.required && !computed.includes(one.name) && spoken[one.name] === undefined)
+    .map((one) => one.name)
+  if (mute.length > 0) {
+    const one = mute.length === 1
+    refuse(
+      `every ${noun} states ${mute.join(', ')}, and \`thread create ${noun}\` never asks for ${one ? 'it' : 'them'}. ` +
+        `It would write a ${noun} with no ${mute.join(' and no ')}, and tell you it worked. ` +
+        `Give ${one ? 'it' : 'each'} a sentence where this command lists what it asks, or name ${one ? 'it' : 'them'} ` +
+        'as something the command fills in.',
+    )
+  }
+
+  return Object.keys(spoken).map((one) => {
+    const told = spoken[one] as Said
+    const known = fields.find((each) => each.name === one)
+    const spare = told.optional ?? (known !== undefined && !known.required)
+    return {
+      at: one,
+      guide: known?.boolean === true ? `${told.guide} — yes or no` : told.guide,
+      ...(told.asks === undefined ? {} : { asks: told.asks }),
+      ...(spare ? { optional: true } : {}),
+      ...(known?.list === true ? { list: true } : {}),
+      ...(known?.map === true ? { map: true } : {}),
+      ...(known?.boolean === true ? { boolean: true } : {}),
+      ...(known?.worded === true ? { worded: true } : {}),
+    }
+  })
+}
+
+export const named = (all: readonly Asked[]): readonly string[] => all.map((one) => one.at)
+
+export const prompted = (one: Asked): string =>
+  one.asks ?? `${one.at} — ${one.guide}${one.optional === true ? ', or blank' : ''}: `
+
+export type Given = { readonly at: number; readonly key: string; readonly value: string }
+
+export interface Child {
+  readonly id: string
+  readonly at: string
+  readonly describes: string
+  readonly by?: string
+  readonly runs?: string
+  readonly body?: string
+  readonly writes?: string
+}
+
+export interface Stated {
+  readonly field: string
+  readonly said: string
+  readonly list: boolean
+  readonly map?: boolean
+  readonly boolean?: boolean
+  readonly worded?: boolean
+}
+
+export const mapped = (one: { readonly map?: boolean; readonly worded?: boolean }, said: string): boolean =>
+  one.map === true && !(one.worded === true && !said.includes('='))
+
+export const CARRIES: readonly string[] = ['cites', 'requires', 'takes', 'by', 'runs']
+
+export function ownAnswers(all: readonly Given[]): readonly Given[] {
+  const opens = new Set<string>(LISTS)
+  const at = all.findIndex((one) => opens.has(one.key))
+  return at === -1 ? all : all.slice(0, at)
+}
+
+export async function stating(
+  asks: readonly Asked[],
+  all: readonly Given[],
+  piped: boolean,
+  ask: (name: string, asks: string) => Promise<string>,
+  line: () => Promise<string | undefined>,
+  settled: readonly string[],
+): Promise<{ readonly stated: readonly Stated[]; readonly kids: ReadonlyMap<string, readonly Child[]> }> {
+  const own = ownAnswers(all)
+  const skip = new Set<string>([...settled, ...LISTS])
+  const stated: Stated[] = []
+  for (const one of asks) {
+    if (skip.has(one.at)) continue
+    const given = (piped ? (answer(own, one.at) ?? '') : await ask(one.at, prompted(one))).trim()
+    if (given === '') continue
+    stated.push({ field: one.at, said: given, list: one.list === true, map: one.map === true, boolean: one.boolean === true, worded: one.worded === true })
+  }
+
+  if (piped) return { stated, kids: childrenIn(all) }
+
+  const kids = new Map<string, readonly Child[]>()
+  for (const list of LISTS) {
+    if (!asks.some((one) => one.at === list)) continue
+    const found = await children(list, all, ask, line)
+    if (found.length > 0) kids.set(list, found)
+  }
+  return { stated, kids }
+}
+
+export function arrayValue(pad: string, key: string, said: string, found: readonly Child[] | undefined): string {
+  if (found === undefined || found.length === 0) return asList(said)
+  const lines = rowLines(pad, [], new Map([[key, found]]))
+  return ['[', ...lines.slice(1, -1), `${pad}]`].join('\n')
+}
+
+const BARE = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+const NUMBER = /^-?\d+(?:\.\d+)?$/
+
+const nested = (held: Readonly<Record<string, unknown>>): string => {
+  const pairs = Object.entries(held).map(([key, value]) => {
+    const name = BARE.test(key) ? key : quoted(key)
+    if (typeof value === 'object' && value !== null) return `${name}: ${nested(value as Readonly<Record<string, unknown>>)}`
+    const said = String(value)
+    return `${name}: ${NUMBER.test(said) ? said : quoted(said)}`
+  })
+  return pairs.length === 0 ? '{}' : `{ ${pairs.join(', ')} }`
+}
+
+export const asMap = (said: string): string => {
+  const held: Record<string, unknown> = {}
+  for (const one of said.split(',').map((each) => each.trim()).filter((each) => each !== '')) {
+    const at = one.indexOf('=')
+    if (at < 1) {
+      refuse(
+        `\`${one}\` is one entry of a name-and-value field, and it states no value. Write each one as ` +
+          '`name=value`, separated by commas — `core=*` says that package at any version, and a dot in the name ' +
+          'nests it: `dark.background=colour-surface`. Nothing was written.',
+      )
+    }
+    const path = one.slice(0, at).trim().split('.')
+    const last = path[path.length - 1] ?? ''
+    let into = held
+    for (const step of path.slice(0, -1)) {
+      const next = into[step]
+      if (next !== undefined && (typeof next !== 'object' || next === null)) {
+        refuse(`\`${one}\` nests under \`${step}\`, and \`${step}\` is already given a value of its own. One or the other. Nothing was written.`)
+      }
+      if (next === undefined) into[step] = {}
+      into = into[step] as Record<string, unknown>
+    }
+    if (typeof into[last] === 'object' && into[last] !== null) {
+      refuse(`\`${one}\` gives \`${last}\` a value, and entries already nest under it. One or the other. Nothing was written.`)
+    }
+    into[last] = one.slice(at + 1).trim()
+  }
+  return nested(held)
+}
+
+export function gathered(all: readonly Given[], fields: readonly Field[]): readonly Given[] {
+  const maps = new Set(fields.filter((one) => one.map).map((one) => one.name))
+  const entries = new Map<string, { readonly at: number; readonly parts: string[] }>()
+  for (const one of all) {
+    const dot = one.key.indexOf('.')
+    if (dot === -1 || !maps.has(one.key.slice(0, dot))) continue
+    const head = one.key.slice(0, dot)
+    const held = entries.get(head) ?? { at: one.at, parts: [] }
+    held.parts.push(`${one.key.slice(dot + 1)}=${one.value}`)
+    entries.set(head, held)
+  }
+  const written = new Set<string>()
+  const out: Given[] = []
+  for (const one of all) {
+    const dot = one.key.indexOf('.')
+    const head = dot === -1 ? one.key : one.key.slice(0, dot)
+    if (dot === -1 || !entries.has(head)) {
+      out.push(one)
+      continue
+    }
+    if (written.has(head)) continue
+    written.add(head)
+    const held = entries.get(head)
+    out.push({ at: held?.at ?? one.at, key: head, value: (held?.parts ?? []).join(', ') })
+  }
+  return out
+}
+
+const asList = (said: string): string =>
+  `[${said
+    .split(',')
+    .map((one) => one.trim())
+    .filter((one) => one !== '')
+    .map(quoted)
+    .join(', ')}]`
+
+export const asBoolean = (said: string): string => {
+  const word = said.trim().toLowerCase()
+  if (word === 'yes' || word === 'y' || word === 'true') return 'true'
+  if (word === 'no' || word === 'n' || word === 'false') return 'false'
+  refuse(`\`${said}\` is not an answer to a yes-or-no field. Say yes or no. Nothing was written.`)
+}
+
+export function rowLines(
+  pad: string,
+  stated: readonly Stated[],
+  kids: ReadonlyMap<string, readonly Child[]>,
+): readonly string[] {
+  const kid = (one: Child): readonly string[] => [
+    `${pad}  {`,
+    `${pad}    id: ${quoted(one.id)},`,
+    `${pad}    at: ${quoted(one.at)},`,
+    `${pad}    describes: ${quoted(one.describes)},`,
+    ...(one.by === undefined || one.by === '' ? [] : [`${pad}    by: ${quoted(one.by)},`]),
+    ...(one.runs === undefined || one.runs === '' ? [] : [`${pad}    runs: ${quoted(one.runs)},`]),
+    `${pad}    version: 1,`,
+    `${pad}  },`,
+  ]
+  return [
+    ...stated.map(
+      (one) =>
+        `${pad}${one.field}: ${
+          mapped(one, one.said) ? asMap(one.said) : one.list ? asList(one.said) : one.boolean === true ? asBoolean(one.said) : quoted(one.said)
+        },`,
+    ),
+    ...[...kids].flatMap(([list, found]) => [`${pad}${list}: [`, ...found.flatMap(kid), `${pad}],`]),
+  ]
+}
+
+export function withChildren(row: string, lines: readonly string[]): string {
+  if (lines.length === 0) return row
+  const all = row.split('\n')
+  let at = all.length - 1
+  while (at >= 0 && (all[at] ?? '').trim() !== '},' && (all[at] ?? '').trim() !== '}') at -= 1
+  if (at < 0) {
+    refuse(
+      'the row just written has no closing brace on a line of its own, so what it declares has nowhere to go. ' +
+        'Nothing more was written, because adding the row and dropping its children quietly is the one outcome ' +
+        'nobody could see.',
+    )
+  }
+  return [...all.slice(0, at), ...lines, ...all.slice(at)].join('\n')
+}
+
+export function childrenIn(all: readonly Given[]): ReadonlyMap<string, readonly Child[]> {
+  const found = new Map<string, readonly Child[]>()
+  for (const list of LISTS) {
+    const each: Child[] = []
+    for (const group of scoped(all, list).each) {
+      const id = (answer(group, list) ?? '').trim()
+      if (id === '') continue
+      const at = (answer(group, 'at') ?? '').trim()
+      const describes = (answer(group, 'describes') ?? '').trim()
+      if (at === '' || describes === '') {
+        refuse(
+          `\`${list} ${id}\` names no ${at === '' ? 'file' : 'meaning'}. Every row says which file it is about and ` +
+            'what that file is, and one missing either is a row the next person cannot act on. Nothing more was written.',
+        )
+      }
+      const body = (answer(group, BODY) ?? '').trim()
+      const writes = (answer(group, WRITES) ?? '').trim()
+      each.push({
+        id,
+        at,
+        describes,
+        ...(writes === '' ? {} : { writes }),
+        ...(list === 'declares'
+          ? {}
+          : { by: (answer(group, 'by') ?? '').trim(), runs: (answer(group, 'runs') ?? '').trim() }),
+        ...(body === '' ? {} : { body }),
+      })
+    }
+    if (each.length > 0) found.set(list, each)
+  }
+  return found
+}
+
+export const BODIED: readonly string[] = ['declares', 'seeds']
+
+export const WRITTEN: readonly string[] = ['derives', 'seeds']
+
+export function seeding(kids: ReadonlyMap<string, readonly Child[]>, root: string): readonly string[] {
+  const said: string[] = []
+  for (const list of BODIED) {
+    for (const one of kids.get(list) ?? []) {
+      const into = join(root, one.at)
+      const there = existsSync(into)
+
+      if (one.body === undefined || one.body === '') {
+        said.push(
+          there
+            ? `${one.at} was already on disk, and the row now names it.`
+            : `${one.at} is declared and nothing is in it yet — write it with ` +
+              `\`${TYPED} edit ${one.at} --from <path>\`.`,
+        )
+        continue
+      }
+
+      if (there) {
+        said.push(
+          `${one.at} was already on disk, so the body you wrote was NOT put over it. Nothing was lost — ` +
+            `\`${TYPED} read ${one.at}\` prints what is there.`,
+        )
+        continue
+      }
+
+      mkdirSync(dirname(into), { recursive: true })
+      writeFileSync(into, one.body.endsWith('\n') ? one.body : `${one.body}\n`, 'utf8')
+      said.push(`wrote ${one.at} with the body you gave it.`)
+    }
+  }
+  return said
+}
+
+const ASKED: Readonly<Record<string, string>> = {
+  declares: 'name each file a person writes that this one owns',
+  derives: 'name each file a command writes from this one, and the command that writes it',
+  seeds: 'name each file a command shapes here',
+}
+
+export async function children(
+  list: string,
+  all: readonly Given[],
+  ask: (name: string, asks: string) => Promise<string>,
+  line: () => Promise<string | undefined>,
+): Promise<readonly Child[]> {
+  const written = WRITTEN.includes(list)
+  const out: Child[] = []
+
+  const owed = (id: string, at: string, describes: string): void => {
+    if (at !== '' && describes !== '') return
+    refuse(
+      `\`${list} ${id}\` names no ${at === '' ? 'file' : 'meaning'}. Every row says which file it is about and what ` +
+        'that file is, and one missing either is a row the next person cannot act on. Nothing more was written.',
+    )
+  }
+
+  const bodies = [
+    ...(written ? [`${asFlag(WRITES)} is the generator's own body — the code that writes the template`] : []),
+    ...(BODIED.includes(list) ? [`${asFlag(BODY)} is the body of the file itself`] : []),
+  ]
+  stdout.write(
+    `\n  ${list} — ${ASKED[list] ?? ''}. ` +
+      (bodies.length === 0
+        ? ''
+        : `Each one takes ${bodies.length === 1 ? 'one body' : `${String(bodies.length)} bodies, and they are never the same text`}: ` +
+          `${bodies.join('; ')}. `) +
+      'A blank id ends the list.\n',
+  )
+  for (;;) {
+    const id = (await ask(list, `  ${list} — id, or blank to stop: `)).trim()
+    if (id === '') break
+    const at = (await ask('at', '    at — the file this names: ')).trim()
+    const describes = (await ask('describes', '    describes — what that file is, to somebody who has not opened it: ')).trim()
+    owed(id, at, describes)
+    const by = written ? (await ask('by', '    by — the command that writes it: ')).trim() : undefined
+    const runs = written ? (await ask('runs', '    runs — the command that catches it drifting: ')).trim() : undefined
+    const writes = written
+      ? await bodied(`the generator behind \`${by ?? 'that command'}\` — this is ${asFlag(WRITES)}`, '', false, all, line)
+      : undefined
+    const body = BODIED.includes(list)
+      ? await bodied(`${at} itself — this is ${asFlag(BODY)}`, '', false, all, line)
+      : undefined
+    out.push({
+      id,
+      at,
+      describes,
+      ...(written ? { by, runs } : {}),
+      ...(writes === undefined ? {} : { writes }),
+      ...(body === undefined ? {} : { body }),
+    })
+  }
+  return out
+}
+
+export async function bodied(
+  what: string,
+  shows: string,
+  piped: boolean,
+  all: readonly Given[],
+  line: () => Promise<string | undefined>,
+): Promise<string | undefined> {
+  const from = argv[argv.indexOf(FROM) + 1]
+  if (argv.includes(FROM) && from !== undefined && !from.startsWith('-')) {
+    try {
+      return refuse(`${FROM} seeds the body out of a file, and a file is not a receipt: nothing here checked it and no descent reached it. Give the body with ${asFlag(BODY)} on the command. Nothing was written.`)
+    } catch {
+      refuse(
+        `\`${FROM} ${from}\` names a file nothing could read, so there is no body to seed and nothing was ` +
+          `written. Write it first, then run this again — or drop ${FROM} and type the body when it is asked for.`,
+      )
+    }
+  }
+  if (piped) {
+    const said = answer(all, BODY)
+    return said === undefined || said.trim() === '' ? undefined : said
+  }
+  if (shows.trim() === '') stdout.write(`  body — write what goes in ${what}.\n`)
+  else {
+    stdout.write(`  body — what a ${what} is handed looks like this:\n`)
+    for (const one of shows.split('\n')) stdout.write(`    ${one}\n`)
+  }
+  stdout.write(
+    `  write yours, then a line holding only ${ENDS}. A first line of ${ENDS} leaves it unwritten, and\n` +
+      `  \`${TYPED} trials\` reports it unproven until somebody writes it.\n` +
+      `  Or give ${FROM} <path> instead and the file at that path is what gets seeded, which is the one\n` +
+      '  form that needs no terminal.\n',
+  )
+  const held: string[] = []
+  for (;;) {
+    const next = await line()
+    if (next === undefined || next.trim() === ENDS) break
+    held.push(next)
+  }
+  const written = held.join('\n').trim()
+  return written === '' ? undefined : written
+}
+
+export function guidance(all: readonly Asked[]): readonly string[] {
+  const width = Math.max(...all.map((one) => one.at.length)) + 3
+  const under = ' '.repeat(width + 2)
+  return all.flatMap((one) => {
+    const lines = wrapped(one.optional === true ? `${one.guide.replace(/\.$/, '')}. Leave it blank and it is not stated` : one.guide, '')
+    return [`  ${`${one.at}:`.padEnd(width)}${lines[0] ?? ''}`, ...lines.slice(1).map((each) => `${under}${each}`)]
+  })
+}
+
+export function only(
+  given: readonly { readonly at: number; readonly key: string; readonly value: string }[],
+  allowed: readonly string[],
+  where: string,
+): void {
+  for (const one of ownAnswers(given)) {
+    if (CARRIES.includes(one.key) || one.key === WRITES) continue
+    if (allowed.includes(one.key)) continue
+    refuse(
+      `${locate(one)} answers \`${one.key}\`, and ${where} takes ${allowed.map((each) => `\`${each}\``).join(', ')}. ` +
+        'Nothing was written.',
+    )
+  }
+}
+
+export function answer(
+  given: readonly { readonly at: number; readonly key: string; readonly value: string }[],
+  key: string,
+): string | undefined {
+  const found = given.filter((one) => one.key === key)
+  if (found.length > 1) {
+    refuse(
+      `\`${key}\` is answered ${String(found.length)} times: ${found.map((one) => locate(one)).join(', ')}. ` +
+        'Nothing was written.',
+    )
+  }
+  const held = found[0]?.value
+  return held === undefined ? undefined : guarded(key, held)
+}
+
+export function accepted(
+  given: readonly { readonly at: number; readonly key: string; readonly value: string }[],
+): string {
+  if (given.length === 0) return 'nothing was accepted before it'
+  return `accepted so far: ${given.map((one) => `${one.key} (${locate(one)})`).join(', ')}`
+}
+
+export function needed(
+  given: readonly { readonly at: number; readonly key: string; readonly value: string }[],
+  key: string,
+  where: string,
+): string {
+  const held = answer(given, key)
+  if (held === undefined || held === '') {
+    refuse(`${where} states no \`${key}\`, and it is not optional. ${accepted(given)}. Nothing was written.`)
+  }
+  return held
+}
+
+export function wrapped(text: string, pad: string): readonly string[] {
+  const lines: string[] = []
+  let held = ''
+  for (const word of text.split(/\s+/).filter((one) => one !== '')) {
+    if (held !== '' && `${held} ${word}`.length > 92) {
+      lines.push(`${pad}${held}`)
+      held = word
+    } else held = held === '' ? word : `${held} ${word}`
+  }
+  if (held !== '') lines.push(`${pad}${held}`)
+  return lines
+}
+
+export function marked(parts: readonly string[]): string {
+  return createHash('sha256').update(parts.join('\n')).digest('hex').slice(0, 6)
+}
+
+export interface Told {
+  readonly on: string
+  readonly said: string
+}
+
+export interface Declared {
+  readonly at: string
+  readonly list: string
+  readonly shape: string | undefined
+  readonly fields: readonly Field[]
+  readonly describes: string
+  readonly holds: number
+  readonly cites: readonly Told[]
+  readonly top: { readonly id: string; readonly describes: string } | undefined
+  readonly files?: string
+}
+
+const citesOf = (held: unknown): readonly Told[] =>
+  Array.isArray(held)
+    ? held.filter(
+        (one): one is Told =>
+          one !== null && typeof one === 'object' && typeof (one as Told).on === 'string' && typeof (one as Told).said === 'string',
+      )
+    : []
+
+const HELD = ['holds', 'declares'] as const
+
+const NAMED_SHAPE = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+const rowLike = (one: unknown): one is Row =>
+  one !== null && typeof one === 'object' && typeof (one as Row).id === 'string' && typeof (one as Row).describes === 'string'
+
+const kinded = (shape: string): string =>
+  shape
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+
+const oneOf = (list: string): string => {
+  const word = list.toLowerCase().split('_').join('-')
+  return word.endsWith('s') ? word.slice(0, -1) : word
+}
+
+export async function declared(tree: Tree): Promise<ReadonlyMap<string, Declared>> {
+  const found = new Map<string, Declared>()
+  const walked = new Set<string>()
+
+  const says = new Map<string, string>()
+
+  const parents = new Map<string, Row & { readonly cites?: unknown }>()
+
+  const sheetsBy = new Map<string, Set<string>>()
+
+  const meant = (shape: string | undefined, sheetAt: string): string => {
+    if (shape === undefined) return ''
+    try {
+      const named = shapesNamed()
+      for (const at of named.get(shape) ?? []) {
+        if (at === sheetAt) continue
+        let others = 0
+        for (const [, files] of named) if (files.includes(at)) others += 1
+        if (others !== 1) continue
+        const told = says.get(at)
+        if (told !== undefined && told !== '') return told
+      }
+    } catch {
+      return ''
+    }
+    return ''
+  }
+
+  const sheet = (one: unknown): string | undefined => {
+    const at = (one as Row | undefined)?.at
+    return typeof at === 'string' && at.startsWith(`${tree.name}/`) && at.endsWith('.ts') ? at : undefined
+  }
+
+  const walk = async (at: string, top: Declared['top']): Promise<void> => {
+    if (walked.has(at)) return
+    walked.add(at)
+
+    let read: Record<string, unknown>
+    try {
+      read = (await import(pathToFileURL(join(tree.at, at)).href)) as Record<string, unknown>
+    } catch {
+      return
+    }
+
+    for (const [name, value] of Object.entries(read)) {
+      const node = value as
+        | { readonly id?: unknown; readonly describes?: unknown; readonly cites?: unknown; readonly declares?: unknown; readonly holds?: unknown; readonly files?: unknown }
+        | undefined
+      const lists: readonly { readonly list: string; readonly rows: readonly unknown[] }[] = Array.isArray(value)
+        ? [{ list: name, rows: value }]
+        : HELD.flatMap((list) => {
+            const rows = node?.[list]
+            return Array.isArray(rows) ? [{ list, rows }] : []
+          })
+      const rowed = lists.filter((one) => one.rows.every(rowLike))
+      const first = rowed[0]
+      if (first === undefined) continue
+
+      if (Array.isArray(value)) {
+        const noun = oneOf(name)
+        sheetsBy.set(name, new Set([...(sheetsBy.get(name) ?? []), at]))
+        if (!found.has(noun)) {
+          found.set(noun, {
+            at,
+            list: name,
+            shape: listShape(at, name),
+            fields: listFields(at, name),
+            describes: '',
+            holds: first.rows.length,
+            cites: [],
+            top,
+          })
+        }
+      } else if (at !== within(tree.at, tree.root)) {
+        const files = typeof node?.files === 'string' && node.files !== '' ? node.files : undefined
+        const held = files === undefined ? first : (rowed.find((one) => one.list === 'declares') ?? first)
+        const kind = listShape(at, held.list)
+        const noun =
+          kind === undefined || (kind === 'Threaded' && files === undefined)
+            ? undefined
+            : kind !== 'Threaded' && NAMED_SHAPE.test(kind)
+              ? kinded(kind)
+              : typeof node?.id === 'string' && node.id !== ''
+                ? node.id
+                : undefined
+        if (typeof noun === 'string' && noun !== '' && !found.has(noun)) {
+          found.set(noun, {
+            at,
+            list: held.list,
+            shape: kind,
+            fields: listFields(at, held.list),
+            describes: typeof node?.describes === 'string' ? node.describes : '',
+            holds: held.rows.length,
+            cites: citesOf(node?.cites),
+            top,
+            ...(files === undefined ? {} : { files }),
+          })
+        }
+      }
+      for (const one of rowed.flatMap((each) => each.rows)) {
+        const where = (one as Row).at
+        const told = (one as Row).describes
+        if (typeof where === 'string' && typeof told === 'string' && !says.has(where)) says.set(where, told)
+        const next = sheet(one)
+        if (next === undefined) continue
+        const row = one as Row & { readonly cites?: unknown }
+        if (!parents.has(next)) parents.set(next, row)
+        await walk(next, top ?? { id: typeof row.id === 'string' ? row.id : '', describes: typeof row.describes === 'string' ? row.describes : '' })
+      }
+    }
+  }
+
+  await walk(within(tree.at, tree.root), undefined)
+
+  const out = new Map<string, Declared>()
+  for (const [noun, one] of found) {
+    const parent = parents.get(one.at)
+    const said = typeof parent?.describes === 'string' ? parent.describes : ''
+    const owned = (sheetsBy.get(one.list)?.size ?? 0) <= 1
+    out.set(noun, {
+      ...one,
+      describes: one.describes !== '' ? one.describes : owned && said !== '' ? said : meant(one.shape, one.at),
+      cites: one.cites.length > 0 ? one.cites : citesOf(parent?.cites),
+    })
+  }
+  return out
+}
+
+export function nouns(all: readonly Row[], verb = 'create'): ReadonlyMap<string, string> {
+  const found = new Map<string, string>()
+  const opens = `thread ${verb} `
+  for (const one of all) {
+    const by = one.by
+    if (typeof by !== 'string' || !by.startsWith(opens)) continue
+    const word = by.slice(opens.length).trim()
+    if (word === '' || typeof one.at !== 'string') continue
+    const already = found.get(word)
+    if (already !== undefined && already !== one.at) {
+      refuse(
+        `two rows both state \`by: 'thread ${verb} ${word}'\` — ${already} and ${one.at} — so which one answers a ` +
+          `${word} is whichever was written first. One noun, one file.`,
+      )
+    }
+    found.set(word, one.at)
+  }
+  return found
+}
+
+const spends = (root: string, nonce: string): string =>
+  join(RECEIPTS, `${createHash('sha256').update(root).digest('hex').slice(0, 16)}-${nonce}.txt`)
+
+const stamp = (listing: string): string => createHash('sha256').update(listing).digest('hex').slice(0, 12)
+
+function beingMade(): string {
+  const words = argv.slice(2).filter((one) => !one.startsWith('-'))
+  if (words[0] === 'create' && typeof words[1] === 'string' && words[1] !== '') return words[1]
+  const file = (argv[1] ?? '').split('\\').join('/').split('/').at(-1) ?? ''
+  return file.replace(/\.[^.]+$/, '')
+}
+
+export const SKILLS_AT = 'thread/knowledge'
+
+export function skillOf(noun: string): string {
+  return `${SKILLS_AT}/${noun}.md`
+}
+
+function readTheSkill(): readonly string[] {
+  const noun = env.THREAD_NOUN ?? beingMade()
+  if (noun === '') return []
+  return [
+    '',
+    `READ ${skillOf(noun)} BEFORE YOU WRITE ANYTHING. It is this command's own output, kept as a`,
+    'file, and it lists everything that already exists. Building a second copy of something the tree',
+    'already has is the most expensive mistake available here and it has already been made: thirteen',
+    'elements were declared in one app that every one of them already shipped.',
+    '',
+    'If that file is not there, run `npx thread skills` and it will be.',
+  ]
+}
+
+export function issue(root: string, listing: string): string {
+  const nonce = randomBytes(6).toString('hex')
+  mkdirSync(RECEIPTS, { recursive: true })
+  writeFileSync(spends(root, nonce), `${stamp(listing)}\n`, 'utf8')
+  const said = readTheSkill()
+  if (said.length > 0) stdout.write(`${said.join('\n')}\n`)
+  return nonce
+}
+
+export function spend(root: string, listing: string, offered: string | undefined, sheet: string): void {
+  if (offered === undefined || offered.startsWith('-')) {
+    refuse(
+      `\`${RECEIPT}\` was handed nothing to check. Run \`thread create\` with no arguments — it lists what is ` +
+        'here and issues a receipt to hand back.',
+    )
+  }
+  const path = spends(root, offered)
+  if (!existsSync(path)) {
+    refuse(
+      `\`${offered}\` is not a receipt this tree issued, or it has been spent already — one run per receipt. ` +
+        'Run `thread create` again and use the one it prints.',
+    )
+  }
+  let when = ''
+  try {
+    when = readFileSync(path, 'utf8').trim()
+  } catch {
+    when = ''
+  }
+
+  process.on('exit', (code) => {
+    if (code === 0) rmSync(path, { force: true })
+  })
+
+  if (when !== stamp(listing)) {
+    refuse(
+      `${sheet} has changed since that receipt was issued, so what you read is not what is here. ` +
+        'Run `thread create` again.',
+    )
+  }
+}
+
+export function asking(
+  held: readonly { readonly at: number; readonly key: string; readonly value: string }[],
+): {
+  readonly piped: boolean
+  readonly ask: (
+    key: string,
+    question: string,
+    from?: readonly { readonly at: number; readonly key: string; readonly value: string }[],
+  ) => Promise<string>
+
+  readonly line: () => Promise<string | undefined>
+  readonly shut: () => void
+} {
+  const piped = answered()
+  const rl = piped ? undefined : createInterface({ input: stdin, output: stdout })
+  const lines = rl?.[Symbol.asyncIterator]()
+  return {
+    piped,
+    ask: async (key, question, from = held) => {
+      const already = answer(from, key)
+      if (already !== undefined) return guarded(key, already)
+      if (piped) return ''
+      stdout.write(question)
+      const next = await lines?.next()
+      return next === undefined || next.done === true ? '' : guarded(key, next.value.trim())
+    },
+    line: async () => {
+      const next = await lines?.next()
+      return next === undefined || next.done === true ? undefined : next.value
+    },
+    shut: () => rl?.close(),
+  }
+}
+
+const ANSWERS = '--answers'
+
+function fromFile(): string | undefined {
+  const at = argv.indexOf(ANSWERS)
+  if (at === -1) return undefined
+  const path = argv[at + 1]
+  if (path === undefined || path.startsWith('-')) {
+    refuse(`${ANSWERS} needs the path of a file holding the answers, one \`name: value\` to a line.`)
+  }
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    refuse(`${ANSWERS} names ${path}, and there is no file there to read the answers from.`)
+  }
+}
+
+const OWN = '--own'
+const CHECK = '--check'
+
+function flagged(): readonly { readonly at: number; readonly key: string; readonly value: string }[] {
+  const found: { at: number; key: string; value: string }[] = []
+  for (let at = 2; at < argv.length; at += 1) {
+    const one = argv[at] ?? ''
+    if (
+      !one.startsWith('--') ||
+      one === RECEIPT ||
+      one === ANSWERS ||
+      one === OWN ||
+      one === CHECK ||
+      one === FROM ||
+      one === CHAINED
+    )
+      continue
+    const value = argv[at + 1]
+    if (value === undefined || value.startsWith('-')) {
+      refuse(`\`${one}\` was given no value — an answer given as a flag is \`${one} value\`, with the value right after it.`)
+    }
+    found.push({ at: 0, key: one.slice(2), value })
+    at += 1
+  }
+  return found
+}
+
+export function answered(): boolean {
+  return argv.includes(ANSWERS) || stdin.isTTY !== true
+}
+
+export function given(): readonly { readonly at: number; readonly key: string; readonly value: string }[] {
+  const flags = flagged()
+  const fromFlag = new Set(flags.map((one) => one.key))
+
+  const held = fromFile()
+  if (held !== undefined) return read([...flags, ...parsed(held).filter((one) => !fromFlag.has(one.key))])
+
+  const text = handed()
+  if (text === undefined) return read(flags)
+
+  return read([...flags, ...parsed(text).filter((one) => !fromFlag.has(one.key))])
+}
+
+const FROM_END = '-from'
+
+function read(
+  all: readonly { readonly at: number; readonly key: string; readonly value: string }[],
+): readonly { readonly at: number; readonly key: string; readonly value: string }[] {
+  return all.map((one) => {
+    if (!one.key.endsWith(FROM_END)) return one
+    const key = one.key.slice(0, -FROM_END.length)
+    if (key === '') return one
+    if (all.some((each) => each.key === key)) {
+      refuse(
+        `\`${asFlag(key)}\` and \`${asFlag(one.key)}\` both answer ${key}, and they do not have to agree. ` +
+          'Give one of them. Nothing was written.',
+      )
+    }
+    try {
+      return refuse(`${asFlag(key)}${FROM_END} takes what this writes out of a file, and a file is not a receipt: nothing here checked it and no descent reached it. Give the text on the command with ${asFlag(key)}. Nothing was written.`)
+    } catch {
+      refuse(
+        `\`${asFlag(one.key)} ${one.value}\` names a file nothing could read, so there is no ${key} to write and ` +
+          `nothing was written. Write that file first, or give the text itself with ${asFlag(key)}.`,
+      )
+    }
+  })
+}
+
+let stood: string | undefined
+let taken = false
+
+export function handed(): string | undefined {
+  if (taken) return stood
+  taken = true
+  if (stdin.isTTY === true) return undefined
+  try {
+    stood = readFileSync(0, 'utf8')
+  } catch {
+    stood = undefined
+  }
+  return stood
+}
+
+export const TYPED = 'npx thread'
+
+const folded = (said: string, pad: string, room = 92): readonly string[] => {
+  const out: string[] = []
+  let line = ''
+  for (const word of said.split(/\s+/)) {
+    if (line === '') line = word
+    else if (`${line} ${word}`.length <= room) line = `${line} ${word}`
+    else {
+      out.push(line)
+      line = word
+    }
+  }
+  if (line !== '') out.push(line)
+  return out.map((one) => `${pad}${one}`)
+}
+
+const parented = ((): readonly string[] => {
+  const one = CONSTRAINTS.find((each) => each.id === 'twice-parented')
+  if (one === undefined) {
+    return [
+      '',
+      'THIS PAGE CANNOT STATE THE RULE. It reads what may declare a file out of the `twice-parented`',
+      'rule, and no rule by that name ships any more. Whatever governs this now, it is not said here —',
+      `\`${TYPED} create rule\` lists every rule that does exist.`,
+    ]
+  }
+  return [
+    '',
+    'which one you pick is a rule rather than a preference, and a check refuses the tree over it:',
+    '',
+    `  ${one.id}`,
+    ...folded(`bans ${one.bans}.`, '    '),
+    ...folded(one.instead.replace(/^./, (each) => each.toUpperCase()), '    '),
+  ]
+})()
+
+const NEXT: Readonly<Record<string, string>> = {
+  declares: 'It writes the file from that, and nothing else runs. A file already on disk is left alone and the row simply names it.',
+  derives: `It writes NO file at \`at:\`, because the command in \`by:\` writes that one — which is why there is no ${asFlag(BODY)} here to give. If this tree has no command answering \`by:\`, that generator is declared first and ${asFlag(WRITES)} is what goes in it.`,
+  seeds: `TWO files come out of this and a different hand writes each, which is the whole reason there are two bodies. If this tree has no command answering \`by:\`, that generator is declared here too, so one run leaves the row, the generator and the file.`,
+}
+
+export const VERBS: readonly string[] = [
+  'nothing is in this tree until a row names it, and which of three lists the row sits in says who',
+  'wrote the file. Pick the one that is true and the rest of this framework follows from it:',
+  '',
+  '  declares   a person wrote it. Exactly one row may ever declare an address, and a second is',
+  '             refused: a file with two owners has two answers for where it came from and the tree',
+  '             can give neither.',
+  '  derives    a command wrote it. Delete the file, run the command again, and the same bytes come',
+  '             back. Many rows may derive one address, because a derivation owns nothing — it states',
+  '             `by:`, the command that writes it, and `runs:`, what catches it drifting.',
+  '  seeds      a command wrote the shape and a person fills in the part no machine can supply. Many',
+  '             rows may seed one address as well, and it is proved by shape rather than by bytes,',
+  '             because half of what is on disk is your own writing.',
+  '',
+  `a file in none of them is not in this app at all — \`${TYPED} descent\` names every one it reached`,
+  'and every one it did not, and nothing undeclared is compiled in or shipped.',
+  '',
+  'and the list decides what this command does next, not just what the row says. What it does next is',
+  'ASK FOR BODIES, and there are two of them, which are never the same text and never the same file:',
+  '',
+  `  ${asFlag(BODY).padEnd(10)} the body of the file the row names. A person wrote it.`,
+  `  ${asFlag(WRITES).padEnd(10)} the body of the GENERATOR — the code that writes a template into that file.`,
+  '',
+  'give each as text on the command. Neither may be taken out of a file, because a file is not a',
+  'receipt: nothing here checked it and no descent reached it. Single-quote a body that holds quotes.',
+  '',
+  'so each list takes a different set of them, and giving one where the other belongs is the mistake',
+  'this section exists to stop:',
+  '',
+  ...LISTS.flatMap((list) => {
+    const takes = [
+      ...(WRITTEN.includes(list) ? [asFlag(WRITES)] : []),
+      ...(BODIED.includes(list) ? [asFlag(BODY)] : []),
+    ]
+    const said = folded(
+      `takes ${takes.length === 0 ? 'no body at all' : takes.join(' and ')}. ${NEXT[list] ?? ''}`,
+      '             ',
+    )
+    return said.map((line, at) => (at === 0 ? `  ${list.padEnd(11)}${line.trim()}` : line))
+  }),
+  ...parented,
+]
+
+export const grows = (sheetAt: string, noun: string): readonly string[] => {
+  const shaped = noun.split('-').map((one) => `${one.slice(0, 1).toUpperCase()}${one.slice(1)}`).join('')
+  return [
+    `this is also how the CLI grows. A list of rows in ${sheetAt} becomes a command: declare`,
+    `\`export const THINGS: readonly Thing[] = []\` beside what is already there and \`${TYPED} create thing\``,
+    'answers from that moment, asking for whatever a `Thing` states and writing the row into that list.',
+    '',
+    `The same is true of what you have now: \`${TYPED} create ${noun}\` exists because ${sheetAt} declares`,
+    `\`${shaped}\`. Nothing was added to a list of commands anywhere — the CLI reads what your tree says.`,
+  ]
+}
+
+export const VALUED = 'THREAD_VALUED'
+
+export function answering(noun: string): readonly string[] {
+  return [
+    ...(env[VALUED] === '1' ? [] : [...VERBS, '']),
+    'what `new` asks. Give each answer as a flag on one command and close with the receipt:',
+    '',
+    `  ${TYPED} create ${noun} new --<answer> <value> ... ${RECEIPT} <receipt>`,
+    '',
+    'Flags need no terminal, no pipe and no file, so that form works everywhere. The two others',
+    'each need something you may not have: one answer to a line on stdin needs a shell that can',
+    'redirect, and `--answers <path>` needs a way to write the file first. Use them when you have',
+    'them; the line above is the one that never depends on it.',
+    '',
+    'Where a question repeats — a list of things, each with answers of its own — there are no',
+    'separate flag names for the inner ones. Give the group\'s own flag again to begin the next,',
+    'then its answers after it, reusing the same words. They are read in the order you write them,',
+    'and everything before the first group flag belongs to the thing itself.',
+    '',
+    'the answers, in order:',
+  ]
+}
+
+export const CARRIED: readonly { readonly verb: string; readonly typed: string; readonly does: string }[] = [
+  { verb: 'read', typed: `${TYPED} read <row>`, does: 'prints every field a row states' },
+  { verb: 'edit', typed: `${TYPED} edit <row> --<field> <value>`, does: 'changes any field it was declared with' },
+  { verb: 'remove', typed: `${TYPED} edit <row> --remove`, does: 'takes the row out of the tree' },
+]
+
+const elsewhere = CARRIED.map((one) => `\`${one.typed}\` ${one.does}`)
+
+export const ELSEWHERE: readonly string[] = [
+  'reading a row, changing one of its answers and taking it out are done in one place, whatever',
+  'declared it \u2014 name the row by its id or by the mark printed beside it above:',
+  '',
+  ...CARRIED.map((one) => `  ${one.typed.padEnd(40)}${one.does}`),
+]
+
+const opening = (said: string): string => said.split(/(?<=\.)\s/)[0] ?? said
+
+const article = (word: string): string => (/^[aeiou]/.test(word) ? 'an' : 'a')
+
+export function taught(noun: string, told: ReadonlyMap<string, Declared>, commands: ReadonlySet<string>): readonly string[] {
+  const one = told.get(noun)
+  const opens: readonly (readonly [string, string])[] = [
+    [`${TYPED} read <id>`, 'the row, and the file it names'],
+    [`${TYPED} create ${noun}`, 'this list again, with a fresh receipt'],
+    ...(commands.has('thread inspect')
+      ? [[`${TYPED} inspect <word>`, 'every row whose name or sentence carries the word'] as const]
+      : []),
+  ]
+  const top = one?.top
+  const siblings =
+    top === undefined
+      ? []
+      : [...told]
+          .filter(([, each]) => each.top?.id === top.id && each.describes !== '')
+          .sort(([left], [right]) => (left < right ? -1 : 1))
+  const pad = Math.max(0, ...siblings.map(([word]) => word.length)) + 3
+  return [
+    'DO NOT CREATE WHAT ALREADY EXISTS. Everything listed below is declared and yours to use. A thing',
+    'you cannot find is usually one of these under a word you have not met \u2014 read the sentences, not',
+    'the names.',
+    '',
+    'IF NOTHING FITS, SAY SO AND STOP. Do not coin a name: a name is a meaning, and a meaning is',
+    'declared rather than invented. Being told the list is short a thing is a useful answer.',
+    '',
+    'NOW GO AND OPEN ONE. A sentence is a summary, and every expensive mistake here was made from a',
+    'summary. These print the real thing, and none of them writes anything:',
+    '',
+    ...opens.map(([said, does]) => `  ${said.padEnd(30)}${does}`),
+    '',
+    ...(one === undefined || one.describes === ''
+      ? []
+      : [
+          `what ${article(noun)} ${noun} is:`,
+          '',
+          ...wrapped(one.describes, '  '),
+          ...one.cites.flatMap((said) => ['', ...wrapped(`said on ${said.on}: "${said.said}"`, '  ')]),
+          '',
+        ]),
+    ...(top === undefined || siblings.length < 2
+      ? []
+      : [
+          `${top.id} \u2014 ${opening(top.describes)}`,
+          'what it makes, and what each one is. Pick the one that is true before declaring anything:',
+          '',
+          ...siblings.flatMap(([word, each]) => {
+            const lines = wrapped(opening(each.describes), '')
+            return [`  ${word.padEnd(pad)}${lines[0] ?? ''}`, ...lines.slice(1).map((line) => `${' '.repeat(pad + 2)}${line}`)]
+          }),
+          '',
+        ]),
+  ]
+}
+
+export function reminded(noun: string | undefined): string {
+  const lists =
+    noun === undefined || noun === 'meta'
+      ? `\`${TYPED} create\` lists what this tree makes, and any noun run bare lists what exists, each with its sentence`
+      : `\`${TYPED} create ${noun}\` lists what exists, each with its sentence`
+  return `thread: before the next thing, ${lists}. Do not create what already exists, and if nothing fits, say so and stop.`
+}
+
+export function wordsIn(offered: readonly string[]): readonly string[] {
+  const values = new Set([argv[argv.indexOf(RECEIPT) + 1], argv[argv.indexOf(ANSWERS) + 1], ...flagged().map((one) => one.value)])
+  const words = argv.slice(2).filter((one) => !one.startsWith('-') && !values.has(one))
+  const first = words[0]
+  if (offered.length === 0 || first === undefined || offered.includes(first)) return words
+  const carried = CARRIED.find((one) => one.verb === first)
+  if (carried !== undefined) {
+    refuse(
+      `\`${first}\` is not a word this command answers, because every row in this tree has it and it is ` +
+        `answered in one place rather than once per thing. \`${carried.typed}\` ${carried.does}, whatever ` +
+        'declared it, and it finds the row by its id or by the mark printed beside it. Nothing was written, ' +
+        'and nothing was read.',
+    )
+  }
+  refuse(
+    `\`${first}\` is not one of the things this command does. It does: ${offered.join(', ')}. ` +
+      `Reading, changing and removing a row are done elsewhere, because they reach every row rather than ` +
+      `only this one's: ${elsewhere.join('; ')}. ` +
+      'Run it with none of those to see what already exists and exactly what each of them asks for. ' +
+      'Nothing was written, and nothing was read.',
+  )
+}
+
+const ANNOUNCED: readonly { readonly what: string; readonly pattern: RegExp }[] = [
+  { what: 'a Stripe secret key', pattern: /\bsk_(?:live|test)_[A-Za-z0-9]{16,}/ },
+  { what: 'a Stripe restricted key', pattern: /\brk_(?:live|test)_[A-Za-z0-9]{16,}/ },
+  { what: 'a GitHub token', pattern: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{30,}/ },
+  { what: 'a GitHub personal access token', pattern: /\bgithub_pat_[A-Za-z0-9_]{30,}/ },
+  { what: 'an AWS access key id', pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/ },
+  { what: 'a Slack token', pattern: /\bxox[abposr]-[A-Za-z0-9-]{10,}/ },
+  { what: 'an OpenAI key', pattern: /\bsk-[A-Za-z0-9_-]{32,}/ },
+  { what: 'an Anthropic key', pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}/ },
+  { what: 'a Google API key', pattern: /\bAIza[A-Za-z0-9_-]{35}\b/ },
+  { what: 'a JSON web token', pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/ },
+  { what: 'a private key', pattern: /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/ },
+  { what: 'a password inside a connection string', pattern: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s:/@]{6,}@/ },
+]
+
+const ASSIGNED = /\b(?:secret|password|passwd|api_?key|apikey|access_?token|auth_?token|private_?key|client_?secret|credential)s?\b\s*[:=]\s*(['"`])([^'"`\n]{16,})\1/gi
+
+const MIXED = /^(?=.*[a-z])(?=.*[A-Z0-9])[A-Za-z0-9_+/=.-]{16,}$/
+
+const NOT = [
+  /^(?:sec|pub)_[a-z0-9_]+$/,
+  /^\$\{/,
+  /^(?:x{3,}|X{3,}|\.{3,}|<[^>]+>|change[-_]?me|your[-_]|example|placeholder|redacted|todo|test|dummy|sample|fake|dGhpcyBpcyBub3QgYSBzZWNyZXQ)/i,
+]
+
+function guarded(key: string, value: string): string {
+  const carried = credentialIn(value)
+  if (carried !== undefined) {
+    refuse(
+      `\`${key}\` holds ${carried}. A credential is never typed into a declaration — not in a describes, not ` +
+        'anywhere but a secret. Declare it with `thread create secret`, name it where the thing that needs it ' +
+        'states what it requires, and it is resolved through the vault at the moment it is used and never ' +
+        'written down. Nothing was written.',
+    )
+  }
+  const address = ADDRESS.exec(value)
+  if (address !== null) {
+    refuse(
+      `\`${key}\` holds the address \`${address[0]}\`. An address is a secret here, not a sentence — the same ` +
+        'thing behind another host is another environment, and one written into a declaration is one nothing ' +
+        'can point elsewhere. Declare it with `thread create secret` and name it where the thing that needs it ' +
+        'states what it requires. Nothing was written.',
+    )
+  }
+  return value
+}
+
+const ADDRESS = /\b[a-z][a-z0-9+.-]*:\/\/[^\s'"`)]+/i
+
+export function credentialIn(text: string): string | undefined {
+  for (const one of ANNOUNCED) {
+    if (one.pattern.test(text)) return one.what
+  }
+  for (const found of text.matchAll(ASSIGNED)) {
+    const value = found[2] ?? ''
+    if (NOT.some((each) => each.test(value))) continue
+    if (!MIXED.test(value)) continue
+    return `a ${(found[0].split(/[:=]/)[0] ?? '').trim()} written down as a literal ${String(value.length)} characters long`
+  }
+  return undefined
+}