@prestack/thread 0.0.1 → 0.0.2

package/dist/core/generators/meta.ts

@@ -0,0 +1,1006 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { argv, env, stdout } from 'node:process'
+import { pathToFileURL } from 'node:url'
+
+import { exit } from '../invoked.ts'
+import { BODY, RECEIPT, TYPED, answer, arrayValue, asBoolean, asFlag, asMap, asking, bodied, childrenIn, asksOf, declared, gathered, given as pipedIn, grows, guidance, issue, mapped, marked, named as answerNames, needed, nouns, only, ownAnswers, refuse, rowLines, seeding, spend, stating, VERBS, within, wordsIn, type Asked } from '../asking.ts'
+import { generators } from '../chain.ts'
+import { listFields, shapeFields, type Field } from '../descend.ts'
+import {
+  STATED,
+  fieldIn,
+  holdsRow,
+  listBounds,
+  quoted,
+  reconciled,
+  rowsIn,
+  withField,
+  withRow,
+  withoutRow,
+} from '../rows.ts'
+import type { Threaded } from '../thread.ts'
+import { findTree } from '../tree.ts'
+
+const TREE = findTree()
+
+const NOUN = env.THREAD_NOUN ?? 'meta'
+
+const MINE = NOUN === 'meta' ? undefined : (await declared(TREE)).get(NOUN)
+
+const FILES = MINE?.files
+
+const LIST = MINE?.list ?? 'declares'
+
+const SHAPE = MINE?.shape ?? 'Threaded'
+
+const FIELDS: readonly Field[] = MINE?.fields ?? shapeFields(SHAPE).map((one) => ({ ...one, boolean: false }))
+
+const ADDRESSED = FIELDS.some((one) => one.name === 'at')
+
+export const ASKS: readonly Asked[] = asksOf(
+  NOUN,
+  FIELDS,
+  {
+    name: {
+      guide:
+        NOUN === 'meta'
+          ? 'kebab-case, e.g. billing — this becomes its id, and its own sheet is scaffolded empty beside it, ready for whatever this app declares under it next'
+          : `kebab-case, e.g. billing — this becomes its id, and no other ${NOUN} in this tree may carry it`,
+      asks: 'name: ',
+    },
+    ...(NOUN === 'meta' || !ADDRESSED || FILES !== undefined
+      ? {}
+      : {
+          at: {
+            guide: 'the path of a file that already exists, relative to this tree',
+            asks: 'at — the file this names: ',
+          },
+        }),
+    describes: {
+      guide:
+        NOUN === 'meta'
+          ? 'one sentence a reader who has not seen the code could act on — what this governs'
+          : `one sentence a reader who has not seen the code could act on — what this ${NOUN} is`,
+      asks: 'describes — one sentence saying what this governs: ',
+    },
+  },
+  NOUN === 'meta' || FILES !== undefined ? ['id', 'at', 'version'] : ['id', 'version'],
+)
+
+const said = (one: string): string => ASKS.find((each) => each.at === one)?.asks ?? `${one}: `
+
+const WIDTH = Math.max(...ASKS.map((one) => one.at.length)) + 3
+
+type Held = Omit<Threaded, 'at'> & { readonly at?: string }
+
+const kebab = (one: string): string => one.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+
+const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/
+
+const at = MINE?.at ?? within(TREE.at, TREE.root)
+
+let sheet: Record<string, unknown> = {}
+try {
+  sheet = (await import(pathToFileURL(join(TREE.at, at)).href)) as Record<string, unknown>
+} catch {
+  sheet = {}
+}
+
+const shows = sheet['catalogue']
+
+const shown: readonly string[] = typeof shows === 'function' ? await (shows as () => Promise<readonly string[]>)() : []
+
+const teaches: readonly string[] = Array.isArray(sheet['TEACHES']) ? (sheet['TEACHES'] as readonly string[]) : []
+
+const inSheet = ((): readonly Held[] | undefined => {
+  const only = sheet[LIST]
+  if (Array.isArray(only)) return only as readonly Held[]
+  for (const value of Object.values(sheet)) {
+    const rows = (value as Readonly<Record<string, unknown>> | undefined)?.[LIST]
+    if (Array.isArray(rows)) return rows as readonly Held[]
+  }
+  return undefined
+})()
+if (inSheet === undefined) {
+  refuse(`${at} states no \`${LIST}\` list, so there is nowhere in it for a ${NOUN} to go. \`npx thread read ${at}\` prints what it does state.`)
+}
+const existing: readonly Held[] = inSheet
+
+const mark = (one: Held): string => marked([one.id, one.at ?? '', one.describes, String(one.version ?? '')])
+
+const listing = [
+  existing.length === 0
+    ? `${at} declares nothing yet.`
+    : `${String(existing.length)} thing(s) ${at} already declares:`,
+  ...existing.map((one) => `  [${mark(one)}] ${one.id} — ${one.describes}`),
+].join('\n')
+
+const words = wordsIn(['new', 'read', 'remove', 'add', 'edit'])
+
+const mustSay = (fields: readonly Field[] = FIELDS): readonly string[] =>
+  fields.filter((one) => one.required).map((one) => one.name)
+
+const kept = (): readonly string[] => [...mustSay(), 'version']
+
+const SAYS = new Map<string, string>([
+  ['id', 'the word this row coins — kebab-case, and not already in that sheet'],
+  ['at', 'the path of a file that already exists, relative to this tree'],
+  ['describes', 'one sentence a reader who has not seen the file could act on'],
+])
+
+function asks(fields: readonly Field[]): readonly string[] {
+  const named = mustSay(fields).filter((one) => one !== 'version')
+  const mute = named.filter((one) => !SAYS.has(one))
+  if (mute.length > 0) {
+    refuse(
+      `every ${NOUN} states ${mute.join(', ')}, and \`add\` has no sentence to ask for ` +
+        `${mute.length === 1 ? 'it' : 'them'} with. The sentence goes beside the others in \`SAYS\`.`,
+    )
+  }
+  const pad = Math.max(...named.map((one) => one.length)) + 3
+  return named.map((one) => `  ${`${one}:`.padEnd(pad)}${SAYS.get(one) ?? ''}`)
+}
+
+function unrestorable(row: Readonly<Record<string, unknown>>): readonly string[] {
+  const keeps = kept()
+  const worn = Object.keys(row).filter((one) => !keeps.includes(one) && row[one] !== undefined)
+  if (worn.length === 0) return []
+  return [
+    '',
+    `  \`add\` writes ${keeps.join(', ')} and nothing else, so ${worn.length === 1 ? 'this field goes' : 'these fields go'}`,
+    '  and no command here puts it back. Copy it now if this is a repoint rather than a deletion:',
+    '',
+    ...worn.map((one) => `      ${one}: ${JSON.stringify(row[one])}`),
+  ]
+}
+
+const rowLike = (one: unknown): one is Held =>
+  one !== null && typeof one === 'object' && typeof (one as Held).id === 'string'
+
+interface Below {
+  readonly row: Held
+  readonly list: string
+  readonly sheet: string
+}
+
+const HELD = ['declares', 'holds'] as const
+
+const under = async (row: Held, from: string, seen: Set<string>): Promise<readonly Below[]> => {
+  const sheet = row.at
+  if (typeof sheet !== 'string' || sheet === '' || sheet === from || seen.has(sheet)) return []
+  if (!sheet.startsWith(`${TREE.name}/`)) return []
+  seen.add(sheet)
+  let read: Record<string, unknown>
+  try {
+    read = (await import(pathToFileURL(join(TREE.at, sheet)).href)) as Record<string, unknown>
+  } catch {
+    return []
+  }
+  const found: Below[] = []
+  for (const [name, value] of Object.entries(read)) {
+    if (Array.isArray(value)) {
+      for (const each of value) if (rowLike(each)) found.push({ row: each, list: name, sheet })
+      continue
+    }
+    for (const list of HELD) {
+      const held = (value as Readonly<Record<string, unknown>> | undefined)?.[list]
+      if (Array.isArray(held)) for (const each of held) if (rowLike(each)) found.push({ row: each, list, sheet })
+    }
+  }
+  for (const each of [...found]) found.push(...(await under(each.row, sheet, seen)))
+  return found
+}
+
+interface Under {
+  readonly meta: Held
+  readonly row: Held
+  readonly list: string
+  readonly sheet: string
+}
+
+async function pointedAt(
+  which: string | undefined,
+  inNode: string | undefined,
+): Promise<{
+  readonly looking: readonly Held[]
+  readonly metas: readonly Held[]
+  readonly kids: readonly Under[]
+}> {
+  const byNode =
+    inNode === undefined ? existing : existing.filter((each) => mark(each) === inNode || each.id === inNode)
+
+  const sheeted = inNode !== undefined && byNode.length === 0 && inNode.endsWith('.ts')
+
+  const looking = sheeted ? existing : byNode
+  const metas = inNode === undefined ? existing.filter((each) => mark(each) === which || each.id === which) : []
+  const kids: Under[] = []
+  const seen = new Set<string>()
+  for (const meta of looking) {
+    for (const held of await under(meta, at, seen)) {
+      if (mark(held.row) !== which && held.row.id !== which) continue
+      if (sheeted && held.sheet !== inNode) continue
+      kids.push({ meta, row: held.row, list: held.list, sheet: held.sheet })
+    }
+  }
+  return { looking, metas, kids }
+}
+
+if (words[0] === 'read') {
+  const which = words[2] ?? words[1]
+  const inNode = words[2] === undefined ? undefined : words[1]
+  const pointed = await pointedAt(which, inNode)
+  const kid = pointed.kids[0]
+  const one = pointed.metas[0] ?? kid?.row
+  if (one === undefined) {
+    refuse(
+      `\`${which ?? '(nothing)'}\` is not a row this tree declares. Give its id, or the mark printed in brackets ` +
+        `beside it — \`${TYPED} create ${NOUN}\` with nothing after it lists every one.`,
+    )
+  }
+  const sheet = kid === undefined ? at : kid.sheet
+  const said = Object.entries(one as unknown as Record<string, unknown>).filter(
+    ([name, value]) => name !== 'id' && name !== 'describes' && value !== undefined,
+  )
+  const pad = Math.max(0, ...said.map(([name]) => name.length)) + 3
+  stdout.write(`${one.id} — ${one.describes}\n`)
+  stdout.write(`  it is a row in ${sheet}\n\n`)
+  for (const [name, value] of said) {
+    stdout.write(`  ${`${name}:`.padEnd(pad)}${typeof value === 'string' ? value : JSON.stringify(value)}\n`)
+  }
+  if (one.at === undefined) {
+    stdout.write(`\n${one.id} is a value ${sheet} holds rather than a file of its own.\n`)
+    exit(0)
+  }
+  if (one.at === sheet) {
+    stdout.write(`\n${one.at} is the sheet this row sits in rather than a file of its own.\n`)
+    exit(0)
+  }
+  stdout.write(`\n${one.at}:\n`)
+  try {
+    stdout.write(readFileSync(join(TREE.at, one.at), 'utf8'))
+  } catch {
+    stdout.write('(nothing is there)\n')
+  }
+  exit(0)
+}
+
+if (words[0] === 'remove') {
+
+  const which = words[2] ?? words[1]
+  const inNode = words[2] === undefined ? undefined : words[1]
+
+  const { looking, metas, kids } = await pointedAt(which, inNode)
+  if (inNode !== undefined && looking.length === 0) {
+    refuse(`\`${inNode}\` is not a governing node ${at} declares, so there is nothing under it to take out.`)
+  }
+
+  if (metas.length + kids.length === 0) {
+    refuse(
+      `\`${which ?? '(nothing)'}\` is not a row this tree declares. Every governing node in ${at} was ` +
+        'searched, and every list under each of them. Give the id, or the mark printed in brackets beside it above.',
+    )
+  }
+
+  if (metas.length + kids.length > 1) {
+    const named = [
+      ...metas.map((each) => `\`${each.id ?? '(unnamed)'}\` — the governing node in ${at}`),
+      ...kids.map((each) => `\`${each.row.id ?? '(unnamed)'}\` — under \`${each.meta.id ?? '(unnamed)'}\`, in ${each.sheet}`),
+    ]
+    refuse(
+      `\`${which}\` names ${String(named.length)} rows: ${named.join('; ')}. Say which node or which sheet to look in — ` +
+        `\`thread create ${NOUN} remove <node|sheet> ${String(which)}\` — because two rows carrying the same values carry the ` +
+        'same mark AND the same id, so naming the row again cannot separate them. Nothing was written.',
+    )
+  }
+
+  const kid = kids[0]
+  if (kid !== undefined) {
+    const sheet = join(TREE.at, kid.sheet)
+    const wrote = kid.list === 'derives' && kid.row.at !== undefined && kid.row.at !== kid.sheet
+    const flaggedKid = argv.indexOf(RECEIPT)
+    if (flaggedKid === -1) {
+      const nonce = issue(TREE.at, listing)
+      stdout.write(
+        [
+          '',
+          `\`${kid.row.id ?? '(unnamed)'}\` — ${kid.row.describes ?? ''}`,
+          kid.row.at === undefined
+            ? `  it is a value held under \`${kid.meta.id ?? '(unnamed)'}\` in ${kid.sheet}.`
+            : `  it names ${kid.row.at}, under \`${kid.meta.id ?? '(unnamed)'}\` in ${kid.sheet}.`,
+          '',
+
+          `  thread create ${NOUN} remove ${String(kid.meta.id)} ${String(kid.row.id)} ${RECEIPT} ${nonce}`,
+          '',
+          ...(wrote
+            ? [
+                `  this takes the row out of ${kid.sheet} and deletes ${kid.row.at}, because that row derives`,
+                '  it: a command wrote every byte of it, and with the row gone nothing writes it again. Any',
+                `  command the row names stops existing at the same moment, because \`${TYPED} create\` reads`,
+                '  the rows to know what commands there are.',
+              ]
+            : kid.row.at === undefined
+              ? [`  this takes the row out of ${kid.sheet} and deletes no file, because a held value names none.`]
+              : [
+                  `  this takes the row out of ${kid.sheet} and LEAVES ${kid.row.at} exactly where it is.`,
+                  '  Nothing here wrote that file, so nothing here deletes it — it goes back to being declared',
+                  '  by nobody, which the descent will say.',
+                ]),
+          ...unrestorable(kid.row as unknown as Readonly<Record<string, unknown>>),
+          '',
+        ].join('\n'),
+      )
+      stdout.write(`create: receipt ${nonce} — spent on use, and stale the moment ${at} changes.\n`)
+      exit(0)
+    }
+    spend(TREE.at, listing, argv[flaggedKid + 1], at)
+
+    const text = readFileSync(sheet, 'utf8')
+    const where = listBounds(text, kid.list)
+    if (where === undefined) {
+      refuse(`${kid.sheet} states no \`${kid.list}\` list, so there is nothing to take a row out of.`)
+    }
+    writeFileSync(sheet, withoutRow(text, where, String(kid.row.id)), 'utf8')
+    stdout.write(`create: took ${String(kid.row.id)} out of ${kid.sheet}.\n`)
+    if (!wrote) {
+      if (kid.row.at !== undefined) stdout.write(`create: ${kid.row.at} is still there, and now declared by nobody.\n`)
+      exit(0)
+    }
+    try {
+      rmSync(join(TREE.at, String(kid.row.at)))
+      stdout.write(`create: deleted ${kid.row.at} — the row derived it, so nothing writes it any more.\n`)
+    } catch {
+      stdout.write(`create: ${kid.row.at} was not there to delete, so only the row came out.\n`)
+    }
+    exit(0)
+  }
+
+  const one = metas[0]
+  if (one === undefined) refuse(`\`${which ?? '(nothing)'}\` names nothing this tree declares.`)
+
+  const owns = typeof one.at === 'string' && one.at !== at
+  const inside = await under(one, at, new Set())
+  if (inside.length > 0) {
+    refuse(
+      `\`${one.id}\` governs ${String(inside.length)} thing(s) — ${inside.map((each) => each.row.id).join(', ')}. Removing it would ` +
+        'leave every one of them answering to nothing, and this will not cascade on your behalf. Take those out first, ' +
+        'and this becomes an empty node you can remove. Nothing was written.',
+    )
+  }
+
+  const flaggedAt = argv.indexOf(RECEIPT)
+  if (flaggedAt === -1) {
+    const nonce = issue(TREE.at, listing)
+    stdout.write(
+      [
+        '',
+        `\`${one.id}\` — ${one.describes}`,
+        owns
+          ? `  it governs nothing, and its sheet ${one.at ?? ''} declares an empty list.`
+          : one.at === undefined
+            ? `  it is a value ${at} holds, and names no file.`
+            : `  it governs nothing, and ${one.at} is the sheet this row sits in rather than a file of its own.`,
+        '',
+        `  thread create ${NOUN} remove ${which ?? one.id} ${RECEIPT} ${nonce}`,
+        '',
+        owns
+          ? `  this takes the row out of ${at} and deletes ${one.at ?? ''}. It is the one command here that`
+          : `  this takes the row out of ${at} and deletes no file.`,
+        owns
+          ? '  running again will not undo.'
+          : one.at === undefined
+            ? `  ${at} holds every other value in that list and is left exactly as it is.`
+            : `  ${one.at} holds every other row in that list and is left exactly as it is.`,
+        ...unrestorable(one as unknown as Readonly<Record<string, unknown>>),
+        '',
+      ].join('\n'),
+    )
+    exit(0)
+  }
+  spend(TREE.at, listing, argv[flaggedAt + 1], at)
+
+  const text = readFileSync(join(TREE.at, at), 'utf8')
+  const where = listBounds(text, LIST)
+  if (where === undefined) refuse(`${at} states no \`${LIST}\` list, so there is nothing to take a row out of.`)
+  writeFileSync(join(TREE.at, at), withoutRow(text, where, one.id), 'utf8')
+  stdout.write(`create: took ${one.id} out of ${at}.\n`)
+  if (owns) {
+    try {
+      rmSync(join(TREE.at, one.at ?? ''))
+      stdout.write(`create: deleted ${one.at ?? ''}.\n`)
+    } catch {
+      stdout.write(`create: ${one.at ?? ''} was not there to delete.\n`)
+    }
+  }
+  exit(0)
+}
+
+const FIELD_KEY = 'field'
+
+const FIELD = asFlag(FIELD_KEY)
+
+const FIELD_ASKS: readonly Asked[] = [
+  { at: 'describes', guide: 'the sentence the CLI asks with. One a person who has not seen the code could answer' },
+  { at: 'options', guide: 'the values it may take, separated by |, e.g. framework|optional. Leave it off to take any text' },
+  {
+    at: 'optional',
+    guide:
+      'answer y and a row may leave the field unstated. Anything else and every row must state it, and each row ' +
+      'that does not is named below with the command that fills it in',
+  },
+]
+
+const FIELD_TAKES: readonly string[] = [FIELD_KEY, ...answerNames(FIELD_ASKS)]
+
+if (words[0] === 'edit' && argv.includes(FIELD)) {
+  const name = (argv[argv.indexOf(FIELD) + 1] ?? '').trim()
+  if (!/^[a-z][A-Za-z0-9]*$/.test(name)) {
+    refuse('`' + name + '` cannot be a field. A field is one camelCase word, e.g. folder. Nothing was written.')
+  }
+  const answers = pipedIn()
+  only(answers, FIELD_TAKES, '`edit ' + FIELD + '`')
+  const sentence = (answer(answers, 'describes') ?? '').trim()
+  const options = (answer(answers, 'options') ?? '').split('|').map((one) => one.trim()).filter((one) => one !== '')
+  const optional = (answer(answers, 'optional') ?? '').trim().toLowerCase().startsWith('y')
+
+  const flaggedField = argv.indexOf(RECEIPT)
+  if (flaggedField === -1) {
+    const nonce = issue(TREE.at, listing)
+    stdout.write(
+      [
+        '',
+        '`edit ' + FIELD + '` gives every ' + NOUN + ' a new field, written into the shape at the top of ' + at + '. From then on',
+        '`thread create ' + NOUN + '` asks for it with the sentence you give here, and `thread edit` can set it on any row.',
+        '',
+        ...guidance(FIELD_ASKS),
+        '',
+        '  thread create ' + NOUN + ' edit ' + FIELD + ' <name> --describes <sentence> ' + RECEIPT + ' ' + nonce,
+        '',
+      ].join('\n'),
+    )
+    stdout.write('create: receipt ' + nonce + ' — spent on use, and stale the moment ' + at + ' changes.\n')
+    exit(0)
+  }
+  spend(TREE.at, listing, argv[flaggedField + 1], at)
+
+  if (sentence === '') {
+    refuse('`' + name + '` was given no sentence, and the sentence is what `thread create ' + NOUN + '` asks with. Give --describes. Nothing was written.')
+  }
+  const file = join(TREE.at, at)
+  const text = readFileSync(file, 'utf8')
+  const opens = 'export interface ' + SHAPE + ' extends Threaded {'
+  const from = text.indexOf(opens)
+  if (from === -1) {
+    refuse(at + ' has no shape at its top for this to write into. Every sheet `thread create meta new` writes has one. Run `thread read ' + at + '` to see what is there. Nothing was written.')
+  }
+  const close = text.indexOf('\n}', from)
+  if (close === -1) {
+    refuse('the shape at the top of ' + at + ' never closes, so nothing can be added to it. Run `thread read ' + at + '` to see where it stops. Nothing was written.')
+  }
+  const block = text.slice(from, close)
+  if (block.includes('readonly ' + name + ':') || block.includes('readonly ' + name + '?:')) {
+    refuse('the shape at the top of ' + at + ' already states `' + name + '`. One field, one statement. Nothing was written.')
+  }
+  const type = options.length === 0 ? 'string' : options.map((one) => quoted(one)).join(' | ')
+  const line = '\n  /** ' + sentence + ' */\n  readonly ' + name + (optional ? '?' : '') + ': ' + type
+  writeFileSync(file, text.slice(0, close) + line + text.slice(close), 'utf8')
+  stdout.write('create: every ' + NOUN + ' now states `' + name + '`, and `thread create ' + NOUN + '` asks for it with the sentence you gave.\n')
+
+  if (!optional) {
+    const lacking = existing.filter((one) => (one as unknown as Record<string, unknown>)[name] === undefined)
+    if (lacking.length > 0) {
+      stdout.write('create: ' + String(lacking.length) + ' ' + NOUN + '(s) already here state no `' + name + '`, and the shape now requires it. Fill each in:\n')
+      for (const one of lacking) stdout.write('  thread edit ' + mark(one) + ' --' + name + ' <value>\n')
+    }
+  }
+  exit(0)
+}
+
+if (words[0] === 'edit') {
+  const which = words[2] ?? words[1]
+  const inNode = words[2] === undefined ? undefined : words[1]
+  const { looking, metas, kids } = await pointedAt(which, inNode)
+
+  if (inNode !== undefined && looking.length === 0) {
+    refuse(`\`${inNode}\` is not a governing node ${at} declares, so there is nothing under it to change.`)
+  }
+  if (metas.length + kids.length === 0) {
+    refuse(
+      `\`${which ?? '(nothing)'}\` is not a row this tree declares. Every governing node in ${at} was ` +
+        'searched, and every list under each of them. Give the id, or the mark printed in brackets beside it above.',
+    )
+  }
+  if (metas.length + kids.length > 1) {
+    const named = [
+      ...metas.map((each) => `\`${each.id ?? '(unnamed)'}\` — the governing node in ${at}`),
+      ...kids.map(
+        (each) => `\`${each.row.id ?? '(unnamed)'}\` — under \`${each.meta.id ?? '(unnamed)'}\`, in ${each.sheet}`,
+      ),
+    ]
+    refuse(
+      `\`${String(which)}\` names ${String(named.length)} rows: ${named.join('; ')}. Say which node to look ` +
+        `under — \`thread create ${NOUN} edit <node> ${String(which)}\` — because two rows carrying the same ` +
+        'values carry the same mark AND the same id, so naming the row again cannot separate them. Nothing was ' +
+        'written.',
+    )
+  }
+
+  const kid = kids[0]
+  const held = kid === undefined ? metas[0] : kid.row
+  if (held?.id === undefined) {
+    refuse(`\`${String(which)}\` names a row with no id, and a row is reached by its id. Nothing was written.`)
+  }
+  const file = kid === undefined ? join(TREE.at, at) : join(TREE.at, kid.sheet)
+  const shown = kid === undefined ? at : kid.sheet
+  const inList = kid === undefined ? LIST : kid.list
+
+  const shaped = listFields(file, inList).filter((one) => one.name !== 'id')
+  if (shaped.length === 0) {
+    refuse(
+      `${shown} states a \`${inList}\` this cannot read the shape of, so which fields a row there may carry is ` +
+        'unknown. Editing one blind is how a row stops being the shape its own list declares.',
+    )
+  }
+
+  const editable = shaped.map((one) => one.name)
+
+  const listed = new Set(shaped.filter((one) => one.list).map((one) => one.name))
+
+
+  const flagged = new Set(shaped.filter((one) => one.boolean).map((one) => one.name))
+
+  const text = readFileSync(file, 'utf8')
+  const where = listBounds(text, inList)
+  if (where === undefined) refuse(`${shown} states no \`${inList}\` list, so there is no row in it to change.`)
+
+  const standing = editable.map((one) => ({ field: one, value: fieldIn(text, where, String(held.id), one) }))
+
+  const flaggedEdit = argv.indexOf(RECEIPT)
+  if (flaggedEdit === -1) {
+    const nonce = issue(TREE.at, listing)
+    stdout.write(
+      [
+        '',
+        `\`${String(held.id)}\` — ${String(held.describes ?? '')}`,
+        `  it is a row in ${shown}, and \`edit\` changes what one of its fields says. One command, so a refusal`,
+        '  leaves the row exactly as it stands — which is the thing `remove` then `add` cannot promise.',
+        '',
+        'what it says now:',
+        '',
+        ...standing.map(
+          (one) => `  ${`${one.field}:`.padEnd(12)}${one.value === undefined ? '(not stated)' : one.value}`,
+        ),
+        '',
+        'answer only the field you are changing, one per line, in any order:',
+        '',
+        `  thread edit ${String(which)} --<field> <value> ${RECEIPT} ${nonce}`,
+        '',
+        '  a field it is not handed is left alone, and `id` is not among them: changing one retires a word',
+        '  and coins another, which is a decision rather than a replacement.',
+        '',
+      ].join('\n'),
+    )
+    stdout.write(`create: receipt ${nonce} — spent on use, and stale the moment ${at} changes.\n`)
+    exit(0)
+  }
+  spend(TREE.at, listing, argv[flaggedEdit + 1], at)
+
+  const answers = gathered(pipedIn(), shaped)
+  const own = ownAnswers(answers)
+  const groups = childrenIn(answers)
+  only(answers, editable, '`edit`')
+  if (answers.length === 0) {
+    refuse('`edit` was handed no field to change. Answer one of the fields it listed. Nothing was written.')
+  }
+
+  const wasAt = typeof held.at === 'string' ? held.at : ''
+  const moving = own.find((one) => one.key === 'at')
+  const goesTo = moving === undefined || moving.value === wasAt ? '' : moving.value
+  if (goesTo !== '' && existsSync(join(TREE.at, goesTo))) {
+    refuse(
+      `${goesTo} is already there, and one address holds one thing. Moving \`${String(held.id)}\` onto it would ` +
+        'leave two rows pointing at one file and no way to say which owns it. Nothing was written.',
+    )
+  }
+
+  let next = text
+  for (const one of own) {
+    const bounds = listBounds(next, inList)
+    if (bounds === undefined) refuse(`${shown} states no \`${LIST}\` list.`)
+    const now = fieldIn(next, bounds, String(held.id), one.key)
+    if (flagged.has(one.key)) {
+      const set = withField(next, bounds, String(held.id), one.key, asBoolean(one.value))
+      if (set !== undefined) {
+        next = set
+        continue
+      }
+    }
+    const field = shaped.find((each) => each.name === one.key)
+    if (field !== undefined && mapped(field, one.value)) {
+      const set = withField(next, bounds, String(held.id), one.key, asMap(one.value))
+      if (set !== undefined) {
+        next = set
+        continue
+      }
+    }
+    if (listed.has(one.key)) {
+      const put = withField(next, bounds, String(held.id), one.key, arrayValue('    ', one.key, one.value, groups.get(one.key)))
+      if (put !== undefined) {
+        next = put
+        continue
+      }
+    }
+    if (now === undefined && listed.has(one.key)) {
+      refuse(
+        `\`${String(held.id)}\` states no \`${one.key}\`, and that field holds rows rather than a sentence. ` +
+          `Write what goes in it with \`${TYPED} create meta add\`, which writes the whole row. Nothing was written.`,
+      )
+    }
+    if (now !== undefined && !now.startsWith("'")) {
+      refuse(
+        `\`${one.key}\` on \`${String(held.id)}\` is ${now}, which is not a plain sentence — replacing it with ` +
+          'one would change what kind of thing it is. Nothing was written.',
+      )
+    }
+    const written = withField(next, bounds, String(held.id), one.key, quoted(one.value))
+    if (written === undefined) {
+      refuse(`\`${one.key}\` could not be written on \`${String(held.id)}\`. Nothing was written.`)
+    }
+    next = written
+  }
+
+  for (const [list, found] of groups) {
+    const bounds = listBounds(next, inList)
+    if (bounds === undefined) break
+    const put = withField(next, bounds, String(held.id), list, arrayValue('    ', list, '', found))
+    if (put === undefined) {
+      refuse(`${list} could not be written on ${String(held.id)}, so nothing was written. Run npx thread read ${shown} to see what that row states now.`)
+    }
+    next = put
+  }
+
+  writeFileSync(file, next, 'utf8')
+
+  if (goesTo !== '') {
+    if (existsSync(join(TREE.at, wasAt))) {
+      mkdirSync(dirname(join(TREE.at, goesTo)), { recursive: true })
+      renameSync(join(TREE.at, wasAt), join(TREE.at, goesTo))
+      stdout.write(`create: moved ${wasAt} to ${goesTo}, because that is where ${String(held.id)} now says it is.\n`)
+    } else {
+      stdout.write(
+        `create: nothing was at ${wasAt}, so nothing moved. \`${String(held.id)}\` now says ${goesTo} and that ` +
+          'address is empty, which `npx thread descent` will name until something is put there.\n',
+      )
+    }
+  }
+
+  const nowAt = goesTo === '' ? wasAt : goesTo
+  const mine = listBounds(next, inList)
+  const source = mine === undefined ? undefined : rowsIn(next, mine).find((one) => one.id === held.id)?.source
+  if (kid === undefined && nowAt !== '' && source !== undefined) {
+    const sheet = join(TREE.at, nowAt)
+    if (existsSync(sheet)) {
+      const there = readFileSync(sheet, 'utf8')
+      const settled = reconciled(there, `const HEAD = ${source.trim().replace(/,$/, '')}\n`, STATED)
+      if (settled !== there) writeFileSync(sheet, settled, 'utf8')
+    }
+  }
+
+  stdout.write(
+    `create: ${String(held.id)} now says ${answers.map((one) => `\`${one.key}\``).join(', ')} in ${shown}.\n`,
+  )
+  exit(0)
+}
+
+if (words[0] === 'add') {
+  const which = words[1]
+  const one = existing.find((each) => mark(each) === which || each.id === which)
+  if (one === undefined) {
+    refuse(
+      `\`${which ?? '(nothing)'}\` is not something ${at} declares. Give the id, or the mark printed in brackets ` +
+        'beside it above.',
+    )
+  }
+  if (one.at === undefined) {
+    refuse(
+      `\`${one.id}\` is a value ${at} holds, so it has no sheet of its own for a child to go in. ` +
+        `\`thread create ${NOUN} new\` is how one more is declared.`,
+    )
+  }
+
+  const sheet = join(TREE.at, one.at)
+  if (!existsSync(sheet)) {
+    refuse(`\`${one.id}\` names ${one.at} and nothing is there, so there is no list to declare a child in.`)
+  }
+  if (listBounds(readFileSync(sheet, 'utf8'), LIST) === undefined) {
+    refuse(`${one.at} states no \`${LIST}\` list, so there is nowhere in it for a child to go.`)
+  }
+
+  const fields = listFields(sheet, LIST)
+  if (fields.length === 0) {
+    refuse(
+      `${one.at} states a \`${LIST}\` this cannot read the shape of, so what a row there must say is unknown. ` +
+        'Write it as a list with a declared row type — the fields `add` asks for are read off that type, and ' +
+        'guessing them is how a row gets written that the tree then refuses.',
+    )
+  }
+  if (!fields.some((each) => each.name === 'at')) {
+    refuse(
+      `${one.at} holds values rather than files, so there is nothing on disk to point a row at. ` +
+        `\`thread create ${NOUN} new\` is how one is declared.`,
+    )
+  }
+
+  const flaggedAt = argv.indexOf(RECEIPT)
+  if (flaggedAt === -1) {
+    const nonce = issue(TREE.at, listing)
+    stdout.write(
+      [
+        '',
+        `\`${one.id}\` — ${one.describes}`,
+        `  its sheet is ${one.at}, and a row put there names a file that is ALREADY on disk.`,
+        '',
+        'what `add` takes, one answer per line, in any order:',
+        '',
+        ...asks(fields),
+        '',
+        `  thread create ${NOUN} add ${which ?? one.id} ${RECEIPT} ${nonce}`,
+        '',
+        '  it writes no file. It points this node at one somebody already wrote, and from then on',
+        '  that file is held to everything this tree refuses.',
+        '',
+      ].join('\n'),
+    )
+    stdout.write(`create: receipt ${nonce} — spent on use, and stale the moment ${at} changes.\n`)
+    exit(0)
+  }
+  spend(TREE.at, listing, argv[flaggedAt + 1], at)
+
+  const answers = pipedIn()
+  const { piped: fed, ask: asked, shut: close } = asking(answers)
+  if (fed) only(answers, mustSay(fields), '`add`')
+
+  const said = fed ? needed(answers, 'at', '`add`') : await asked('at', 'at — the path of a file that already exists: ')
+  const target = join(TREE.at, said)
+  const childAt = within(TREE.at, target)
+  if (!existsSync(target)) {
+    close()
+    refuse(`nothing is at ${childAt}. \`add\` points this node at a file that already exists — it writes none.`)
+  }
+  if (statSync(target).isDirectory()) {
+    close()
+    refuse(
+      `${childAt} is a directory. Name the file — a directory threads nothing beneath it, so everything under it ` +
+        'would still read as declared by nobody while the row itself looked answered.',
+    )
+  }
+
+  const childId = kebab(fed ? needed(answers, 'id', '`add`') : await asked('id', 'id — the word this row coins: '))
+  if (!KEBAB.test(childId)) {
+    close()
+    refuse(`\`${childId}\` cannot be an id — it is kebab-case, e.g. glossary-generator.`)
+  }
+
+  const saying = fed
+    ? needed(answers, 'describes', '`add`')
+    : await asked('describes', 'describes — one sentence saying what this file is: ')
+  if (saying === '') {
+    close()
+    refuse(`${childAt} was given no meaning, and a row without one is a path nobody can read.`)
+  }
+  close()
+
+  const now = readFileSync(sheet, 'utf8')
+  const place = listBounds(now, LIST)
+  if (place === undefined) refuse(`${one.at} states no \`${LIST}\` list.`)
+  if (holdsRow(now, place, childId)) refuse(`\`${childId}\` is already declared in ${one.at}. One id, one row.`)
+
+  const row = [
+    '    {',
+    `      id: ${quoted(childId)},`,
+    `      at: ${quoted(childAt)},`,
+    `      describes: ${quoted(saying)},`,
+    '      version: 1,',
+    '    },',
+  ].join('\n')
+
+  writeFileSync(sheet, withRow(now, place, row), 'utf8')
+  stdout.write(`create: ${one.id} now declares ${childAt}.\n`)
+  exit(0)
+}
+
+stdout.write(`${listing}\n`)
+for (const line of shown) stdout.write(`${line}\n`)
+
+const flagged = argv.indexOf(RECEIPT)
+
+if (flagged === -1) {
+  const nonce = issue(TREE.at, listing)
+  stdout.write(
+    [
+      '',
+      ...VERBS,
+      '',
+      'what `new` takes, one answer per line, in any order:',
+      '',
+      ...guidance(ASKS),
+      ...(FILES === undefined
+        ? []
+        : [
+            `  ${'at:'.padEnd(WIDTH)}${FILES.replace('*', '<name>')} — where it lives is never typed`,
+            `  ${`${asFlag(BODY)}:`.padEnd(WIDTH)}what goes in that file, given on the command. Leave it out and the settle writes the starter`,
+          ]),
+      ...(teaches.length === 0 ? [] : ['', ...teaches]),
+      '',
+      `  thread create ${NOUN} new <name> ${RECEIPT} ${nonce}`,
+      `  thread create ${NOUN} read <mark>           no receipt, writes nothing`,
+      ...(ADDRESSED
+        ? [
+            `  thread create ${NOUN} add <mark> ${RECEIPT} ${nonce}`,
+            '              points a node at a file that already exists — it writes none',
+          ]
+        : []),
+      `  thread create ${NOUN} remove <id> ${RECEIPT} ${nonce}`,
+      '              only a node governing nothing — it refuses one with anything under it',
+      `  thread create ${NOUN} edit <row> ${RECEIPT} ${nonce}`,
+      '              changes what one field of an existing row says. One command, so a refusal leaves',
+      '              the row exactly as it stands',
+      '',
+      `${RECEIPT} is spent by one run, and is refused if ${at} changed after it was issued.`,
+      '',
+    ].join('\n'),
+  )
+  stdout.write(`create: receipt ${nonce} — spent on use, and stale the moment ${at} changes.\n`)
+  exit(0)
+}
+
+spend(TREE.at, listing, argv[flagged + 1], at)
+
+const all = gathered(pipedIn(), FIELDS)
+const { piped, ask, line, shut } = asking(all)
+
+const own = ownAnswers(all)
+const TAKES: readonly string[] = FILES === undefined ? answerNames(ASKS) : [...answerNames(ASKS), BODY]
+if (piped) only(own, TAKES, '`new`')
+
+const name = kebab(words[1] ?? (piped ? needed(own, 'name', '`new`') : await ask('name', said('name'))))
+if (!KEBAB.test(name)) {
+  shut()
+  refuse(`\`${name}\` cannot be the id of a governing node — it is kebab-case, e.g. billing.`)
+}
+if (existing.some((one) => one.id === name)) {
+  shut()
+  refuse(`\`${name}\` is already declared in ${at}. One id, one row.`)
+}
+
+let taken: ReadonlyMap<string, string> = new Map()
+try {
+  taken = nouns(await generators(TREE), 'create')
+} catch {
+  taken = new Map()
+}
+if (taken.has(name)) {
+  shut()
+  refuse(
+    `\`${name}\` is already a noun this tree makes — \`thread create ${name}\` runs ${taken.get(name) ?? 'a command'}. ` +
+      'One word, one meaning: a governing node called that would be reachable only by its mark, and the two would ' +
+      'be told apart by nothing. Choose another name. Nothing was written.',
+  )
+}
+
+const target = join(TREE.dir, `${name}.ts`)
+const sheetAt = within(TREE.at, target)
+if (NOUN === 'meta' && existsSync(target)) {
+  shut()
+  refuse(`${sheetAt} is already there and no row names it. Choose another name, or delete it first.`)
+}
+
+const describes = piped
+  ? needed(own, 'describes', '`new`')
+  : await ask('describes', said('describes'))
+if (describes === '') {
+  shut()
+  refuse(`\`${name}\` was given no meaning, and a governing node without one is a name nobody can read.`)
+}
+
+const address =
+  NOUN === 'meta'
+    ? sheetAt
+    : FILES !== undefined
+      ? FILES.replace('*', name)
+      : !ADDRESSED
+        ? undefined
+        : piped
+          ? needed(own, 'at', '`new`')
+          : await ask('at', said('at'))
+
+const { stated, kids } = await stating(ASKS, all, piped, ask, line, ['name', 'id', 'at', 'describes', 'version'])
+
+const body =
+  FILES === undefined || address === undefined
+    ? undefined
+    : await bodied(`${address} itself — this is ${asFlag(BODY)}`, '', piped, all, line)
+
+shut()
+
+if (body !== undefined && address !== undefined && existsSync(join(TREE.at, address))) {
+  refuse(
+    `${address} is already on disk, so the body you gave has nowhere to go without being put over somebody's file. ` +
+      `Leave the body out and the row names what is there, or run \`${TYPED} read ${address}\` and move it first. Nothing was written.`,
+  )
+}
+
+const row = [
+  '    {',
+  `      id: ${quoted(name)},`,
+  ...(address === undefined ? [] : [`      at: ${quoted(address)},`]),
+  `      describes: ${quoted(describes)},`,
+  '      version: 1,',
+  ...rowLines('      ', stated, NOUN === 'meta' ? new Map() : kids),
+  '    },',
+].join('\n')
+
+const text = readFileSync(join(TREE.at, at), 'utf8')
+const where = listBounds(text, LIST)
+if (where === undefined) refuse(`${at} states no \`${LIST}\` list to declare a governing node in.`)
+if (holdsRow(text, where, name)) refuse(`\`${name}\` is already declared in ${at}.`)
+
+writeFileSync(join(TREE.at, at), withRow(text, where, row), 'utf8')
+stdout.write(`create: declared ${name} in ${at}.\n`)
+
+for (const said of seeding(kids, TREE.at)) stdout.write(`create: ${said}\n`)
+
+if (FILES !== undefined && address !== undefined) {
+  if (body === undefined) {
+    stdout.write(`create: ${address} follows — the settle writes its starter, and \`${TYPED} edit ${address} --from <path>\` replaces it.\n`)
+  } else {
+    mkdirSync(dirname(join(TREE.at, address)), { recursive: true })
+    writeFileSync(join(TREE.at, address), body.endsWith('\n') ? body : `${body}\n`, 'utf8')
+    stdout.write(`create: wrote ${address} with the body you gave it.\n`)
+  }
+}
+
+if (NOUN !== 'meta') {
+  stdout.write(`create: \`npx thread read ${at}\` prints what that list says now.\n`)
+  exit(0)
+}
+
+const opens = (readFileSync(join(TREE.at, at), 'utf8').split('\n')[0] ?? '').trim()
+if (!opens.includes('Threaded')) {
+  refuse(
+    `${at} does not open by importing \`Threaded\`, so a new sheet cannot be given the same import and would be ` +
+      'written unable to compile. Nothing was scaffolded.',
+  )
+}
+
+const CONST = name.toUpperCase().replace(/-/g, '_')
+const SHAPED = name.split('-').map((one) => `${one.slice(0, 1).toUpperCase()}${one.slice(1)}`).join('')
+writeFileSync(
+  target,
+  [
+    opens,
+    '',
+    `export interface ${SHAPED} extends Threaded {`,
+    `  readonly declares?: readonly ${SHAPED}[]`,
+    '}',
+    '',
+    `export const ${CONST}: ${SHAPED} = {`,
+    `  id: ${quoted(name)},`,
+    `  at: ${quoted(sheetAt)},`,
+    `  describes: ${quoted(describes)},`,
+    '  version: 1,',
+    ...(kids.size > 0 ? rowLines('  ', [], kids) : ['  declares: [],']),
+    '}',
+    '',
+  ].join('\n'),
+  'utf8',
+)
+stdout.write(
+  `create: wrote ${sheetAt}, declaring nothing under it yet.\n` +
+    `create: every ${name} carries what any row carries — a name, an address and a sentence. To give ${name}s a ` +
+    `field of their own, change the shape at the top of ${sheetAt}. What you add lands on this node and on ` +
+    `everything declared under it, and \`npx thread create\` starts asking for it.\n`,
+)
+stdout.write(['', ...VERBS, '', ...grows(sheetAt, name), ''].join('\n'))
+
+exit(0)