@prestack/thread 0.0.1 → 0.0.3

package/dist/derivation/generators/build.ts

@@ -0,0 +1,232 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { relative, resolve } from 'node:path'
+import { argv, stderr, stdout } from 'node:process'
+import { pathToFileURL } from 'node:url'
+
+import { build } from 'esbuild'
+
+import { descend, reached, type Pass } from '../../core/descend.ts'
+import { exit, invoked } from '../../core/invoked.ts'
+import { findTree } from '../../core/tree.ts'
+import type { Secret } from '../../integrations/secret.ts'
+import { servesBrowser, type Target } from '../../integrations/target.ts'
+
+const TREE = findTree()
+
+const ROOT = TREE.at
+
+const OUTSIDE = /(^|\/)node_modules(\/|$)/
+
+const BUILDS = 'thread build'
+
+const here = (path: string): string => relative(ROOT, path).split('\\').join('/')
+
+function wanted(pass: Pass): readonly { entry: string; out: string }[] {
+
+  const owns = new Map<string, string>()
+  for (const [at, threadings] of pass.threaded) {
+    for (const one of threadings) {
+      const id = one.row.id
+      if (id !== undefined && !owns.has(id)) owns.set(id, at)
+    }
+  }
+
+  const found: { entry: string; out: string }[] = []
+  for (const [at, threadings] of pass.threaded) {
+    for (const one of threadings) {
+      if (one.list !== 'derives' || one.row.by !== BUILDS) continue
+      const entry = owns.get(one.by)
+      if (entry !== undefined) found.push({ entry, out: at })
+    }
+  }
+  return found
+}
+
+function compilers(pass: Pass): readonly string[] {
+  const found: string[] = []
+  for (const [at, threadings] of pass.threaded) {
+    for (const one of threadings) {
+      if (one.list !== 'declares' || one.row.by !== BUILDS) continue
+      if (!found.includes(at)) found.push(at)
+    }
+  }
+  return found
+}
+
+const JSX = /\.(c|m)?(t|j)sx$/
+
+function browsing(entry: string): boolean {
+  return JSX.test(entry)
+}
+
+async function sheet<T>(file: string, list: string): Promise<readonly T[]> {
+  const path = resolve(ROOT, `${TREE.name}/${file}`)
+  if (!existsSync(path)) return []
+  try {
+    const held = (await import(pathToFileURL(path).href)) as Record<string, readonly T[] | undefined>
+    return held[list] ?? []
+  } catch {
+    return []
+  }
+}
+
+async function withheld(pass: Pass): Promise<ReadonlyMap<string, string>> {
+  const targets = await sheet<Target>('targets.ts', 'TARGETS')
+  if (targets.length === 0) return new Map()
+  const secrets = await sheet<Secret>('secrets.ts', 'SECRETS')
+
+  const because = new Map<string, string>()
+  for (const one of targets) {
+    const said = servesBrowser(one, secrets)
+    if (said !== true) because.set(one.id, said)
+  }
+  if (because.size === 0) return new Map()
+
+  const guilty = new Map<string, string>()
+  const consider = (row: { readonly id?: string; readonly requires?: readonly string[] }): void => {
+    if (row.id === undefined || row.requires === undefined) return
+    for (const word of row.requires) {
+      const said = because.get(word)
+      if (said === undefined) continue
+      guilty.set(row.id, `\`${row.id}\` requires \`${word}\`, and that target cannot be reached from a page. ${said}`)
+    }
+  }
+  for (const one of pass.stated.values()) consider(one)
+  for (const held of pass.threaded.values()) for (const each of held) consider(each.row)
+  if (guilty.size === 0) return new Map()
+
+  const found = new Map<string, string>()
+  for (const [at, held] of pass.threaded) {
+    for (const each of held) {
+      const said = guilty.get(each.by)
+      if (said !== undefined) found.set(resolve(ROOT, at), said)
+    }
+  }
+  return found
+}
+
+function withholding(refusals: ReadonlyMap<string, string>): {
+  readonly name: string
+  readonly setup: (build: { onLoad: (opts: { filter: RegExp }, run: (args: { path: string }) => unknown) => void }) => void
+} {
+  return {
+    name: 'thread-withheld',
+    setup(build) {
+      build.onLoad({ filter: /.*/ }, (args) => {
+        const said = refusals.get(args.path)
+        if (said === undefined) return undefined
+        return {
+          errors: [
+            {
+              text:
+                `${said} This entry is JSX, so it is built for a browser, and everything a browser bundle ` +
+                'reaches is in the bundle. Move the operation behind something the page calls, or take the ' +
+                'target off its row.',
+            },
+          ],
+        }
+      })
+    },
+  }
+}
+
+function declared(): { readonly name: string; readonly setup: (build: { onLoad: (opts: { filter: RegExp }, run: (args: { path: string }) => unknown) => void }) => void } {
+  const wired = new Set(reached())
+  return {
+    name: 'thread-declared',
+    setup(held) {
+      held.onLoad({ filter: /\.(c|m)?(t|j)sx?$/ }, (args) => {
+        const path = here(args.path)
+        if (OUTSIDE.test(path) || path.startsWith('..') || wired.has(path)) return undefined
+        return {
+          errors: [
+            {
+              text:
+                `${path} is not declared — the descent from ${TREE.name}/thread.ts never reaches it, so nothing ` +
+                'in this app agreed it exists. Declare it from the row that owns it, or delete it. A file nothing ' +
+                'names cannot be part of what this app ships',
+            },
+          ],
+        }
+      })
+    },
+  }
+}
+
+async function main(): Promise<void> {
+  const pass = descend()
+  const all = wanted(pass)
+  const checking = argv.includes('--check')
+
+  const compiling: unknown[] = []
+  for (const one of compilers(pass)) {
+    const held = (await import(pathToFileURL(resolve(ROOT, one)).href)) as { plugin?: unknown }
+    if (held.plugin === undefined) {
+      stderr.write(
+        `build: ${one} is declared \`by: '${BUILDS}'\` and exports no \`plugin\`, so the build has nothing to run ` +
+          'from it. A file that says it compiles and compiles nothing is worse than one that says neither.\n',
+      )
+      exit(1)
+    }
+    compiling.push(held.plugin)
+  }
+
+  if (all.length === 0) {
+    if (checking) {
+      stdout.write(`build: nothing in ${TREE.name}/ derives a file \`by: '${BUILDS}'\`, so there is no artifact to be out of date.\n`)
+      return
+    }
+    stderr.write(
+      `build: nothing in ${TREE.name}/ derives a file \`by: '${BUILDS}'\`, so this app states no artifact to build. ` +
+        'Declare one from the row that owns the entry, and the build reads its entry from that row.\n',
+    )
+    exit(1)
+  }
+
+  for (const { entry, out } of all) {
+    const at = resolve(ROOT, out)
+    const before = checking && existsSync(at) ? readFileSync(at, 'utf8') : undefined
+
+    if (checking && before === undefined) {
+      stderr.write(`build: ${out} is declared and not on disk. Run \`${BUILDS}\` and commit what it writes.\n`)
+      exit(1)
+    }
+
+    const forBrowser = browsing(entry)
+    const refusals = forBrowser ? await withheld(pass) : new Map<string, string>()
+
+    const held = await build({
+      entryPoints: [resolve(ROOT, entry)],
+      bundle: true,
+      format: 'esm',
+      platform: forBrowser ? 'browser' : 'node',
+      ...(forBrowser ? {} : { packages: 'external' as const }),
+      outfile: at,
+      write: !checking,
+      plugins: [declared() as never, ...(refusals.size === 0 ? [] : [withholding(refusals) as never]), ...(compiling as never[])],
+      logLevel: 'silent',
+    }).catch((thrown: unknown) => {
+      stderr.write(`build: ${out} was not written — ${thrown instanceof Error ? thrown.message : String(thrown)}\n`)
+      exit(1)
+      return undefined
+    })
+
+    if (checking) {
+      const now = held?.outputFiles?.[0]?.text
+      if (now !== before) {
+        stderr.write(
+          `build: ${out} is not what ${BUILDS} writes. A built artifact has no author — run \`${BUILDS}\` and commit the result.\n`,
+        )
+        exit(1)
+      }
+      stdout.write(`build: ${out} is up to date — ${String(new Set(reached()).size)} declared file(s) reachable.\n`)
+      continue
+    }
+
+    stdout.write(`build: wrote ${out} from ${entry} — ${String(new Set(reached()).size)} declared file(s) reachable.\n`)
+  }
+}
+
+if (invoked(import.meta.url)) await main()
+
+export { declared, wanted }

package/dist/derivation/generators/check.ts

@@ -0,0 +1,118 @@
+import { bodyHash, parseGenerated, type GeneratedFile } from './determinism.ts'
+
+export type CheckStatus = 'ok' | 'missing' | 'stale' | 'hand-edited' | 'orphaned'
+
+export interface FileCheck {
+  readonly path: string
+  readonly status: CheckStatus
+  readonly detail: string
+}
+
+export interface CheckReport {
+  readonly ok: boolean
+  readonly checks: readonly FileCheck[]
+}
+
+export type ReadFile = (path: string) => string | null
+
+export interface CheckOptions {
+
+  readonly previouslyGenerated?: readonly string[]
+}
+
+export function checkGenerated(
+  expected: readonly GeneratedFile[],
+  read: ReadFile,
+  options: CheckOptions = {},
+): CheckReport {
+  const checks: FileCheck[] = []
+  const expectedPaths = new Set(expected.map((file) => file.path))
+
+  for (const file of expected) {
+    const actual = read(file.path)
+
+    if (actual === null) {
+      checks.push({ path: file.path, status: 'missing', detail: 'not committed — run `thread generate`' })
+      continue
+    }
+
+    if (actual === file.contents) {
+      checks.push({ path: file.path, status: 'ok', detail: 'up to date' })
+      continue
+    }
+
+    const parsed = parseGenerated(file.path, actual)
+    if (parsed === null) {
+      checks.push({
+        path: file.path,
+        status: 'hand-edited',
+        detail: 'the generated header is gone — this file was replaced by hand',
+      })
+      continue
+    }
+
+    if (bodyHash(parsed.body) !== parsed.declaredHash) {
+      checks.push({
+        path: file.path,
+        status: 'hand-edited',
+        detail:
+          'the body no longer matches its own header hash. Move the change into ' +
+          `${parsed.source} first — regenerating will discard it.`,
+      })
+      continue
+    }
+
+    checks.push({
+      path: file.path,
+      status: 'stale',
+      detail: `out of date with ${parsed.source} — run \`thread generate\``,
+    })
+  }
+
+  for (const path of options.previouslyGenerated ?? []) {
+    if (expectedPaths.has(path)) continue
+    checks.push({
+      path,
+      status: 'orphaned',
+      detail: 'generation no longer owns this file — delete it',
+    })
+  }
+
+  const sorted = checks.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+  return { ok: sorted.every((check) => check.status === 'ok'), checks: sorted }
+}
+
+export function formatCheckReport(report: CheckReport): string {
+  if (report.ok) return `generated output is up to date (${report.checks.length} files).`
+
+  const problems = report.checks.filter((check) => check.status !== 'ok')
+  return [
+    `${problems.length} of ${report.checks.length} generated file(s) need attention:`,
+    ...problems.map((check) => `  ${check.status.padEnd(12)} ${check.path}\n               ${check.detail}`),
+  ].join('\n')
+}
+
+export function detectHandEdits(
+  paths: readonly string[],
+  read: ReadFile,
+): readonly FileCheck[] {
+  const edited: FileCheck[] = []
+
+  for (const path of [...paths].sort()) {
+    const contents = read(path)
+    if (contents === null) continue
+
+    const parsed = parseGenerated(path, contents)
+    if (parsed === null) continue
+
+    if (bodyHash(parsed.body) !== parsed.declaredHash) {
+      edited.push({
+        path,
+        status: 'hand-edited',
+        detail: `edited by hand. The change belongs in ${parsed.source}.`,
+      })
+    }
+  }
+
+  return edited
+}

package/dist/derivation/generators/derivation.ts

@@ -0,0 +1,347 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { argv, stdout } from 'node:process'
+
+import { exit } from '../../core/invoked.ts'
+import { ELSEWHERE, RECEIPT, answer, answering, asking, asksOf, given as pipedIn, guidance, issue, marked, named as answerNames, needed, only, ownAnswers, refuse, rowLines, seeding, spend, stating, within, wordsIn, type Asked } from '../../core/asking.ts'
+import { holdsRow, listBounds, withRow, withoutRow } from '../../core/rows.ts'
+import { NAMED } from '../../core/scope.ts'
+import { findTree, inTree } from '../../core/tree.ts'
+
+import { generators } from '../../core/chain.ts'
+import { quoted } from '../../core/rows.ts'
+
+const TREE = findTree()
+
+const FILE = 'derivation.ts'
+
+const LIST = 'GENERATORS'
+
+const at = within(TREE.at, inTree(TREE, FILE))
+
+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 COMMAND = /^thread [a-z][a-z0-9]*(?:[ -][a-z0-9]+)*(?: --[a-z][a-z0-9-]*)*$/
+
+export const ASKS: readonly Asked[] = asksOf(
+  'generator',
+  'Threaded',
+  {
+    name: {
+      guide: 'kebab-case, and it is the id of the row AND the file this seeds, e.g. manifest',
+      asks: 'name: ',
+    },
+    describes: {
+      guide: 'one sentence a reader who has not seen the code could act on',
+      asks: 'describes — one sentence a reader who has not seen the code could act on: ',
+    },
+    folder: {
+      guide: 'where the file goes, relative to this tree, e.g. src/generators',
+      asks: 'folder — where the file goes, e.g. src/generators: ',
+    },
+    by: {
+      guide: 'the command that WRITES it, e.g. thread manifest',
+      asks: 'by — the command that writes it, e.g. thread manifest: ',
+      optional: false,
+    },
+    runs: {
+      guide: 'the command that SETTLES it, e.g. thread manifest --check',
+      asks: 'runs — the command that settles it, blank for none: ',
+    },
+    body: {
+      guide: 'what this generator does, written out — every line until one holding only a full stop',
+      asks: 'body — what it derives, ended by a line holding only a full stop: ',
+    },
+  },
+  ['id', 'at', 'version'],
+)
+
+export const ADDS: readonly Asked[] = asksOf(
+  'generator',
+  'Threaded',
+  {
+    at: {
+      guide: 'the path of a generator already on disk, relative to this tree, e.g. thread/integrity/generators/seal.ts',
+      asks: 'at — the generator already on disk: ',
+    },
+    name: {
+      guide: 'kebab-case, and it is the id of the row, e.g. seal-generator',
+      asks: 'name: ',
+    },
+    describes: {
+      guide: 'one sentence a reader who has not seen the code could act on',
+      asks: 'describes — one sentence a reader who has not seen the code could act on: ',
+    },
+    by: {
+      guide: 'the command that runs it, e.g. thread seal',
+      asks: 'by — the command that runs it, e.g. thread seal: ',
+      optional: false,
+    },
+    runs: {
+      guide: 'the command that SETTLES what it writes, e.g. thread seal --check',
+      asks: 'runs — the command that settles it, blank for none: ',
+    },
+  },
+  ['id', 'version'],
+)
+
+const said = (one: string, from: readonly Asked[] = ASKS): string => from.find((each) => each.at === one)?.asks ?? `${one}: `
+
+const existing = await generators(TREE)
+
+const mark = (one: { readonly id?: string; readonly at?: string; readonly describes?: string }): string =>
+  marked([one.id ?? '', one.at ?? '', one.describes ?? ''])
+
+const listing = [
+  existing.length === 0
+    ? 'no generators yet — nothing in this tree derives a file, so nothing here is written by a command.'
+    : `${String(existing.length)} generator(s) this tree already has. Read them before you declare another:`,
+  ...existing.map(
+    (one) =>
+      `  [${mark(one)}] ${one.id ?? '(NO ID)'} — written by \`${one.by ?? '(NOTHING)'}\` — ${one.describes ?? '(NO SENTENCE)'}`,
+  ),
+].join('\n')
+
+const words = wordsIn(['new', 'add'])
+
+stdout.write(`${listing}\n`)
+
+const flagged = argv.indexOf(RECEIPT)
+
+if (flagged === -1) {
+  const nonce = issue(TREE.at, listing)
+  stdout.write(
+    [
+      '',
+      ...answering('generator'),
+      '',
+      ...guidance(ASKS),
+      '',
+      `  npx thread create generator new <name> ${RECEIPT} ${nonce}`,
+      '',
+      'or point a row at a generator that is already on disk — it writes no file:',
+      '',
+      ...guidance(ADDS),
+      '',
+      `  npx thread create generator add <path> ${RECEIPT} ${nonce}`,
+      '',
+      ...ELSEWHERE,
+      '',
+      `${RECEIPT} is spent by one run, and is refused if ${at} changed after it was issued.`,
+      '',
+      'DO NOT DECLARE WHAT ALREADY EXISTS. The list above is every generator this tree has, each with ' +
+        'the sentence it states. Read it before you answer — a second generator writing the same file is ' +
+        'two owners for one address, and the tree keeps whichever ran last. If nothing above fits, say so ' +
+        'and stop rather than coining a name.',
+      '',
+      'Whatever you name as `runs:` becomes a step in `npx thread gate`, and the gate fails when it ' +
+        'fails. Leave it blank and nothing ever checks what this generator wrote — the file gets written ' +
+        'and nobody asks whether it is right.',
+      '',
+      'The body is the generator. You write it here and this command puts it at the address above, so the ' +
+        'command you named exists and answers from the moment this run finishes. Hand it nothing and this ' +
+        'refuses, because a generator that writes nothing cannot be told from one that had nothing to do.',
+      '',
+    ].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)
+
+if (words[0] === 'add') {
+  const all = pipedIn()
+  const { piped, ask, line, shut } = asking(all)
+  const own = ownAnswers(all)
+
+  if (piped) only(own, answerNames(ADDS), '\`add\`')
+
+  const source = (words[1] ?? (piped ? needed(own, 'at', '\`add\`') : await ask('at', said('at', ADDS)))).trim().replace(/^\.?\/+/, '')
+  if (!existsSync(join(TREE.at, source))) {
+    shut()
+    refuse(`nothing is at ${source}. \`add\` points a row at a generator that is already on disk — it writes none.`)
+  }
+  if (existing.some((one) => one.at === source)) {
+    shut()
+    refuse(`${source} is already the address of a generator in ${at}. One address has one owner.`)
+  }
+
+  const name = kebab(piped ? needed(own, 'name', '\`add\`') : await ask('name', said('name', ADDS)))
+  if (!KEBAB.test(name)) {
+    shut()
+    refuse(`\`${name}\` cannot be the id of a generator — it is kebab-case, e.g. seal-generator.`)
+  }
+  if (existing.some((one) => one.id === name)) {
+    shut()
+    refuse(`\`${name}\` is already declared in ${at}. One id, one generator — two would silently keep whichever ran second.`)
+  }
+
+  const describes = piped ? needed(own, 'describes', '\`add\`') : await ask('describes', said('describes', ADDS))
+  if (describes === '') {
+    shut()
+    refuse(`\`${name}\` was given no meaning, and a row without one is a name nobody can read.`)
+  }
+
+  const by = (piped ? needed(own, 'by', '\`add\`') : await ask('by', said('by', ADDS))).trim()
+  if (!COMMAND.test(by)) {
+    shut()
+    refuse(`\`${by}\` is not a command this tree can run — it reads \`thread <word>\`, e.g. thread seal.`)
+  }
+
+  const runsSaid = (piped ? (answer(own, 'runs') ?? '') : await ask('runs', said('runs', ADDS))).trim()
+  if (runsSaid !== '' && !COMMAND.test(runsSaid)) {
+    shut()
+    refuse(`\`${runsSaid}\` is not a command this tree can run — it reads \`thread <word> [--flag]\`, e.g. thread seal --check.`)
+  }
+
+  const { stated, kids } = await stating(ADDS, all, piped, ask, line, ['name', 'id', 'at', 'describes', 'version', 'by', 'runs'])
+
+  shut()
+
+  const row = [
+    '  {',
+    `    id: ${quoted(name)},`,
+    `    at: ${quoted(source)},`,
+    `    describes: ${quoted(describes)},`,
+    '    version: 1,',
+    `    by: ${quoted(by)},`,
+    ...(runsSaid === '' ? [] : [`    runs: ${quoted(runsSaid)},`]),
+    ...rowLines('    ', stated, kids),
+    '  },',
+  ].join('\n')
+
+  const path = inTree(TREE, FILE)
+  const text = readFileSync(path, 'utf8')
+  const where = listBounds(text, LIST)
+  if (where === undefined) {
+    refuse(`${at} states no \`${LIST}\` list to declare a generator in.`)
+  }
+  if (holdsRow(text, where, name)) refuse(`\`${name}\` is already declared in ${at}.`)
+
+  writeFileSync(path, withRow(text, where, row), 'utf8')
+  stdout.write(`create: declared ${name} in ${at}, pointing at ${source}, which it left untouched.\n`)
+  for (const told of seeding(kids, TREE.at)) stdout.write(`create: ${told}\n`)
+  stdout.write(`create: \`${by}\` exists from now on, because the CLI reads every \`by:\` this tree declares. Run it and ${source} is what answers.\n`)
+  exit(0)
+}
+
+const all = pipedIn()
+const { piped, ask, line, shut } = asking(all)
+
+const own = ownAnswers(all)
+
+if (piped) only(own, answerNames(ASKS), '`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 generator — it is kebab-case, e.g. manifest or release-config.`)
+}
+if (existing.some((one) => one.id === name)) {
+  shut()
+  refuse(
+    `\`${name}\` is already declared in ${at}. One id, one generator — two would silently keep whichever ran second.`,
+  )
+}
+
+const describes = piped
+  ? needed(own, 'describes', '`new`')
+  : await ask('describes', said('describes'))
+if (describes === '') {
+  shut()
+  refuse(`\`${name}\` was given no meaning, and a row without one is a name nobody can read.`)
+}
+
+const folderSaid = piped ? needed(own, 'folder', '`new`') : await ask('folder', said('folder'))
+const folder = folderSaid.trim().replace(/^\.?\/+/, '').replace(/\/+$/, '')
+if (folder === '') {
+  shut()
+  refuse(`\`${name}\` names no folder, so there is no address to seed it at and no path for its row to state.`)
+}
+
+const by = (piped ? needed(own, 'by', '`new`') : await ask('by', said('by'))).trim()
+if (!COMMAND.test(by)) {
+  shut()
+  refuse(
+    `\`${by}\` is not a command this tree can run — it reads \`thread <word>\`, e.g. thread manifest. ` +
+      'That string is what makes the command exist: the CLI builds its list from the `by:` every generator row states, ' +
+      'so a row with no `by:` declares a file nothing writes.',
+  )
+}
+
+const runsSaid = (piped ? (answer(own, 'runs') ?? '') : await ask('runs', said('runs'))).trim()
+if (runsSaid !== '' && !COMMAND.test(runsSaid)) {
+  shut()
+  refuse(`\`${runsSaid}\` is not a command this tree can run — it reads \`thread <word> [--flag]\`, e.g. thread manifest --check.`)
+}
+
+const body = (piped ? needed(own, 'body', '`new`') : await ask('body', said('body'))).replace(/\s+$/, '')
+if (body === '') {
+  shut()
+  refuse(
+    `\`${name}\` was given no body, so this would write a file that derives nothing. A generator that returns ` +
+      'having written nothing cannot be told from one that ran and had nothing left to do, and the settle chain ' +
+      'would go green on it. Write what it derives and run this again.',
+  )
+}
+
+
+const { stated, kids } = await stating(ASKS, all, piped, ask, line, ['name', 'id', 'at', 'describes', 'version', 'folder', 'by', 'runs', 'body'])
+
+shut()
+
+const source = `${folder}/${name}.ts`
+
+if (existing.some((one) => one.at === source)) {
+  refuse(
+    `${source} is already the address of a generator in ${at}. One address has one owner, so declaring a ` +
+      'second would leave the tree keeping whichever wrote last.',
+  )
+}
+
+const row = [
+  '  {',
+  `    id: ${quoted(name)},`,
+  `    at: ${quoted(source)},`,
+  `    describes: ${quoted(describes)},`,
+  '    version: 1,',
+  `    by: ${quoted(by)},`,
+  ...(runsSaid === '' ? [] : [`    runs: ${quoted(runsSaid)},`]),
+  ...rowLines('    ', stated, kids),
+  '  },',
+].join('\n')
+
+const path = inTree(TREE, FILE)
+const text = readFileSync(path, 'utf8')
+const where = listBounds(text, LIST)
+if (where === undefined) {
+  refuse(
+    `${at} states no \`${LIST}\` list to declare a generator in. Run \`npx thread attach ${NAMED}\` — ` +
+      "the sheet is the package's to write, not yours.",
+  )
+}
+if (holdsRow(text, where, name)) refuse(`\`${name}\` is already declared in ${at}.`)
+
+writeFileSync(path, withRow(text, where, row), 'utf8')
+stdout.write(`create: declared ${name} in ${at}.\n`)
+
+for (const told of seeding(kids, TREE.at)) stdout.write(`create: ${told}\n`)
+
+const seeded = join(TREE.at, source)
+if (existsSync(seeded)) {
+  stdout.write(`create: ${source} is already on disk — left untouched, and declared above.\n`)
+} else {
+  mkdirSync(dirname(seeded), { recursive: true })
+  writeFileSync(seeded, `${body}\n`, 'utf8')
+  stdout.write(`create: wrote ${source} — ${String(body.split('\n').length)} line(s), the body you gave it.\n`)
+}
+
+stdout.write(
+  `create: \`${by}\` exists from now on, because the CLI reads every \`by:\` this tree declares — nothing had ` +
+    `to be added to a list of commands. Run it and ${source} is what answers.\n`,
+)
+
+exit(0)