@prestack/thread 0.0.1 → 0.0.2

package/dist/integrations/attach.ts

@@ -0,0 +1,207 @@
+import type { Attaching } from '../core/attach.ts'
+import { named } from '../core/scope.ts'
+
+const VERSION = 1
+
+const DESCRIBES =
+  'The system that states every place this app reaches and every credential it reaches with. A target is a destination and the prefix on its id is how it is reached; what it accepts is entities if it keeps them, calls if it is called over https, and the methods or subcommands it answers to if it is an npm package or a program; what it requires is secrets, and where the reach has an address one of them is it. Nothing else in this app names a host, a connection string or an environment variable, so an operation says which place it needs and the rest is worked out from the declaration.'
+
+const TARGETS =
+  'Where this app states the places it reaches and what each one accepts. Declare one with `thread create target`, which asks how it is reached and puts the matching prefix on its id — `pg_` for a postgres over the network, `pl_` for one in this process, `zu_` for a store in the browser, `ht_` for something called over https, `mod_` for something this app brings in from outside the repository and calls, `cli_` for a program it runs at a command line — and writes what it accepts and the secrets reaching it needs. A place that keeps things accepts entities; a place that is called accepts the calls declared beside it; a package or a program says in `uses` what it is and in `offers` what it responds to, and takes nothing, because a method name belongs to something outside this tree and `takes` is a demand this tree has to be able to meet. This is the one place the split between what reaches a server and what stays local is written down.'
+
+const SECRETS =
+  'Where this app states every value it must be given and may not hold. A row here is a name and a sentence and never a value: `sec_` for one only a server may ever hold, `pub_` for one that may reach a browser, and that prefix is the whole of what decides where the target requiring it can be reached from. A secret with a `sends` goes into a header on every call; the one without is the address of the target that requires it.'
+
+const VAULT =
+  'What opens a secret\'s value at the moment of use, written once and then yours. It reads the names off _threads/secrets.ts and opens the values sealed beside the tree, refusing any other name; add a secret with `thread create secret`, which is the only thing that ever takes a value. To open values from somewhere else in production, replace what opens them here.'
+
+const SECRET =
+  'A value this app must be given and may never hold — a key, a token, a connection string. The row names it and says what it is for, and there is no field on it for the value, because a row is read by everything and a credential is read by one thing at one moment. The prefix says who may ever hold it: `sec_` a server and nothing else, `pub_` anybody including whoever opens the page. That one letter is what refuses a server credential its way into a browser bundle, so it is on the id rather than in a field somebody could forget.'
+
+const CALL =
+  'One thing a target can be asked to do — the verb and the path, named so that a node names the call and never writes a url. It is a row rather than a field because it is a thing with a name and a sentence like everything else here, and because what a vendor offers is a list that grows: an app reaches one more endpoint by declaring one more of these, not by editing a body.'
+
+const REACH =
+  'How a target is got at — over a network to a postgres, inside this process, in the browser\'s own memory, over https, as an npm package this app installs and calls directly, or as a program run at a command line. It is the prefix on the target\'s id and never a field, because how a thing is reached decides everything else that may be said about it: what it accepts, whether it can be reached from a page at all, whether anything has to say where it is, and whether anything has to arrive on the machine before it can be reached at all. A field beside the id would be a second answer to a question the id already answers.'
+
+export const CONCEPTS: readonly { readonly id: string; readonly describes: string }[] = [
+  { id: 'secret', describes: SECRET },
+  { id: 'call', describes: CALL },
+  { id: 'reach', describes: REACH },
+]
+
+import { quoted } from '../core/rows.ts'
+
+const concept = (one: { readonly id: string; readonly describes: string }): string =>
+  [
+    '  {',
+    `    id: '${one.id}',`,
+    "    at: '_threads/concepts.ts',",
+    `    describes: ${quoted(one.describes)},`,
+    `    version: ${String(VERSION)},`,
+    '    cites: [',
+    "      { on: '2026-08-29', said: 'SSOT for the integrations, as a whole meta inside thread core' },",
+    "      { on: '2026-08-29', said: 'seams declare BOTH target AND secrets' },",
+    '    ],',
+    '  },',
+  ].join('\n')
+
+const INTEGRATIONS_SOURCE = `import type { Threaded } from '../core/thread.ts'
+
+export const INTEGRATIONS: Threaded = {
+  id: 'integrations',
+  at: '_threads/integrations.ts',
+  describes: ${quoted(DESCRIBES)},
+  version: ${String(VERSION)},
+  declares: [
+    {
+      id: 'targets',
+      at: '_threads/targets.ts',
+      describes: ${quoted(TARGETS)},
+      version: ${String(VERSION)},
+    },
+    {
+      id: 'secrets',
+      at: '_threads/secrets.ts',
+      describes: ${quoted(SECRETS)},
+      version: ${String(VERSION)},
+    },
+  ],
+}
+`
+
+const TARGETS_SOURCE = `import type { Call, Target } from './target.ts'
+
+export const TARGETS: readonly Target[] = []
+
+export const CALLS: readonly Call[] = []
+`
+
+const SECRETS_SOURCE = `import type { Secret } from './secret.ts'
+
+export const SECRETS: readonly Secret[] = []
+`
+
+const OWN: readonly { readonly into: string; readonly list: string; readonly id: string; readonly source: string }[] = [
+  ...CONCEPTS.map((one) => ({
+    into: 'concepts.ts',
+    list: 'CONCEPTS',
+    id: one.id,
+    source: concept(one),
+  })),
+  {
+    into: 'integrations.ts',
+    list: 'declares',
+    id: 'vault',
+    source: [
+      '    {',
+      "      id: 'vault',",
+      "      at: 'src/vault.ts',",
+      `      describes: ${quoted(VAULT)},`,
+      `      version: ${String(VERSION)},`,
+      "      by: 'thread vault',",
+      "      runs: 'thread vault --check',",
+      '    },',
+    ].join('\n'),
+  },
+]
+
+const SEEDED = {
+  attaches: ['@prestack/thread/derivation/attach'] as const,
+  id: 'integrations',
+  declares: [
+    '    {',
+    '      id: \'integrations\',',
+    '      at: \'_threads/integrations.ts\',',
+    '      describes: \'The system that states every place this app reaches and every credential it reaches with. A target is a destination and the prefix on its id is how it is reached; what it accepts is entities if it keeps them, calls if it is called over https, and the methods or subcommands it answers to if it is an npm package or a program; what it requires is secrets, and where the reach has an address one of them is it. Nothing else in this app names a host, a connection string or an environment variable, so an operation says which place it needs and the rest is worked out from the declaration.\',',
+    '      version: 1,',
+    '    },',
+  ].join('\n'),
+}
+
+const SHIPPED: readonly { readonly into: string; readonly list: string; readonly id: string; readonly source: string }[] = [
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'target-generator',
+    source: "  {\n    id: 'target-generator',\n    at: 'node_modules/@prestack/thread/dist/integrations/generators/target.js',\n    describes: 'The command that declares a place this app reaches. Asked for nothing it lists every target already here with what it accepts and what it requires, every way a target may be reached and what each way can hold, and every secret this app declares. It then asks what the place is called and how it is reached, puts the prefix on the id, asks which secret is its address and which go into a header, and writes the row — so a target arrives declared with its credential named rather than with an environment variable typed into whatever needed it.',\n    version: 1,\n    by: 'thread create target',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'secret-generator',
+    source: "  {\n    id: 'secret-generator',\n    at: 'node_modules/@prestack/thread/dist/integrations/generators/secret.js',\n    describes: 'The command that declares a value this app must be given, and the only thing that ever takes one. It asks what the secret is for and who may hold it, puts `sec_` or `pub_` on the id accordingly, and writes the row. Then it asks a person for the value, with the terminal\\'s echo off, and seals it into the store beside the tree under a key it generates and never prints. The value goes from the keyboard into the sealed store and nowhere else: not into the row, not into the output, not into whatever transcript is being kept of the session that ran it.',\n    version: 1,\n    by: 'thread create secret',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'vault-generator',
+    source: "  {\n    id: 'vault-generator',\n    at: 'node_modules/@prestack/thread/dist/integrations/generators/vault.js',\n    describes: 'The writer of the file that opens this app\\'s sealed store. It reads the secrets this app declares and writes one function that resolves them by name, refusing any name no row declares — so a value can be asked for only by something that declared it needed it, and a secret taken off the tree stops resolving rather than lingering as a name that still works.',\n    version: 1,\n    by: 'thread vault',\n    runs: 'thread vault --check',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'inspect-generator',
+    source: "  {\n    id: 'inspect-generator',\n    at: 'node_modules/@prestack/thread/dist/integrations/generators/read.js',\n    describes: 'The one command for reading what this app declares. Asked for nothing it prints every sheet and what each holds; asked for a word it prints every row whose id or sentence carries it. It reads the tree rather than the files, which is the whole reason it exists: a row is a nested TypeScript literal and a search over lines answers questions about text while the questions people actually ask are about rows.',\n    version: 1,\n    by: 'thread inspect',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'call-noun',
+    source: "  {\n    id: 'call-noun',\n    at: 'node_modules/@prestack/thread/dist/integrations/generators/target.js',\n    describes: 'The command that makes an already-declared call happen. `thread run call <id>` asks for whatever its path leaves to be filled in — `{like_this}` — by name, and for a call that writes (POST, PUT, PATCH) a JSON body, then resolves the target\\'s address and every credential it requires through the vault at the moment of the call and never before. Nothing here ever names a vendor: a call already states its target, its method and its path, and which one runs is read off its own id, exactly as `thread run trial` reads an operation\\'s.',\n    version: 1,\n    by: 'thread run call',\n  },",
+  },
+]
+export const ATTACH: Attaching = {
+  attaches: SEEDED.attaches,
+  id: SEEDED.id,
+  declares: SEEDED.declares,
+  writes: [
+    { file: 'integrations.ts', source: INTEGRATIONS_SOURCE },
+    { file: 'targets.ts', source: TARGETS_SOURCE },
+    { file: 'secrets.ts', source: SECRETS_SOURCE },
+  ],
+  rows: [...OWN, ...SHIPPED],
+
+  retires: [
+    {
+      into: 'derivation.ts',
+      list: 'GENERATORS',
+      id: 'read-generator',
+      why: 'renamed to `inspect-generator`. `thread read` is a verb of the CLI itself now — it reads FILES, and this package reads ROWS, which is `thread inspect`. Both were called read, and only one of them could answer.',
+    },
+    {
+      into: 'integrations.ts',
+      list: 'declares',
+      id: 'trace',
+      made: `src/integrations.trace.${'jsonl'}`,
+      why: 'the record of what went out through an integration is gone. It sealed every line against the one before it, and a chain nobody reads guards nothing. What an integration did is what the tool itself reports, at the moment it runs',
+    },
+    {
+      into: 'derivation.ts',
+      list: 'GENERATORS',
+      id: 'trace-generator',
+      why: 'the record it wrote is gone, so there is nothing for it to make and nothing for `--check` to read',
+    },
+
+    {
+      into: 'derivation.ts',
+      list: 'GENERATORS',
+      id: 'sdk-generator',
+      why:
+        '`sdk` is a way a target is reached now, not a noun beside one — `thread create target` declares an SDK with ' +
+        '`--reach sdk`, which installs it, reads what it answers to, and writes one row instead of three. The noun ' +
+        'also raised the collision guard against any app declaring a meta called `sdk`, which made every other ' +
+        'withdrawal this package ships undeliverable to the trees that needed them.',
+    },
+    {
+      into: 'concepts.ts',
+      list: 'CONCEPTS',
+      id: 'sdk',
+      why:
+        '`sdk` is no longer a noun beside a target — it is one of the ways a target is reached, and its meaning is ' +
+        `now \`SAID.module\` in \`${named('integrations')}/target\`, beside \`https\` and every other reach, none of which is ` +
+        'coined here either. It also collided with an app declaring a meta called `sdk`, which coins the word: two ' +
+        'meanings for one word is what `twice-meant` refuses, and it was holding the glossary and the docs red.',
+    },
+  ],
+}

package/dist/integrations/generators/read.ts

@@ -0,0 +1,127 @@
+import { stdout } from 'node:process'
+
+import { exit } from '../../core/invoked.ts'
+import { wordsIn } from '../../core/asking.ts'
+import { descend, type Row } from '../../core/descend.ts'
+
+const words = wordsIn([])
+
+const looking = words.join(' ').trim().toLowerCase()
+
+const pass = descend()
+
+const said = (one: Row): string => (one.describes ?? '').replace(/\s+/g, ' ')
+
+const carries = (one: Row, list: string, file: string): boolean => {
+  if (looking === '') return true
+  const held = [one.id ?? '', one.at ?? '', said(one), one.by ?? '', one.runs ?? '', list, file, ...(one.requires ?? []), ...(one.takes ?? [])]
+  return held.some((each) => each.toLowerCase().includes(looking))
+}
+
+const shown = (one: Row, list: string, pad: string, alone = false): readonly string[] => {
+  const marks = [
+    ...(one.by === undefined ? [] : [`written by \`${one.by}\``]),
+    ...(one.runs === undefined ? [] : [`checked by \`${one.runs}\``]),
+    ...((one.requires ?? []).length === 0 ? [] : [`requires ${(one.requires ?? []).join(', ')}`]),
+    ...((one.takes ?? []).length === 0 ? [] : [`takes ${(one.takes ?? []).join(', ')}`]),
+  ]
+  const sentence = said(one)
+  return [
+    `${pad}${one.id ?? '(unnamed)'}  [${list}]`,
+    ...(marks.length === 0 ? [] : [`${pad}  ${marks.join(' · ')}`]),
+
+    ...(sentence === ''
+      ? []
+      : [`${pad}  ${alone || sentence.length <= 160 ? sentence : `${sentence.slice(0, 157)}...`}`]),
+  ]
+}
+
+const files = [...pass.threaded.keys()].sort()
+
+const matched =
+  files.reduce((sum, file) => sum + (pass.threaded.get(file) ?? []).filter((each) => carries(each.row, each.list, file)).length, 0) +
+  [...pass.stated.entries()].filter(
+    ([, one]) =>
+      !files.some((file) => (pass.threaded.get(file) ?? []).some((each) => each.row === one)) && carries(one, 'stated', one.at ?? ''),
+  ).length
+
+const only = matched === 1
+
+let rows = 0
+const out: string[] = []
+
+if (looking === '') {
+  for (const file of files) {
+    const held = pass.threaded.get(file) ?? []
+    if (held.length === 0) continue
+    rows += held.length
+    out.push(`  ${String(held.length).padStart(4)}  ${file}`)
+  }
+  out.unshift(`${String(files.length)} sheet(s) in this tree, and what each holds:`, '')
+  out.push(
+    '',
+    'Name a word to read the rows themselves — every row whose id, sentence, path, command or',
+    'requirement carries it, each with what it means:',
+    '',
+    '  npx thread inspect element',
+    '  npx thread inspect variant',
+    '  npx thread inspect <any word above, or any word this tree coins>',
+    '',
+  )
+  stdout.write(`${out.join('\n')}\n`)
+  stdout.write(
+    `read: ${String(rows)} row(s) across ${String(pass.declarations)} declaration(s), ` +
+      `and ${String(pass.findings.length)} finding(s) the gate would report.\n`,
+  )
+  exit(0)
+}
+
+for (const file of files) {
+  const held = (pass.threaded.get(file) ?? []).filter((each) => carries(each.row, each.list, file))
+  if (held.length === 0) continue
+  out.push(file)
+  for (const each of held) {
+    rows += 1
+    out.push(...shown(each.row, each.list, '  ', only))
+  }
+  out.push('')
+}
+
+const loose = [...pass.stated.entries()]
+  .filter(([, one]) => !files.some((file) => (pass.threaded.get(file) ?? []).some((each) => each.row === one)))
+  .filter(([, one]) => carries(one, 'stated', one.at ?? ''))
+
+if (loose.length > 0) {
+  out.push('stated outright, in no parent\'s list')
+  for (const [, one] of loose) {
+    rows += 1
+    out.push(...shown(one, 'stated', '  ', only))
+  }
+  out.push('')
+}
+
+if (looking !== '') {
+  const coined = [...pass.coined.entries()].filter(([word]) => word.toLowerCase().includes(looking))
+  if (coined.length > 0) {
+    out.push('words this tree coins')
+    for (const [word, held] of coined) out.push(`  ${word} — declared under ${held.under}`)
+    out.push('')
+  }
+}
+
+stdout.write(`${out.join('\n')}\n`)
+
+if (rows === 0) {
+  stdout.write(
+    looking === ''
+      ? 'read: this tree declares nothing yet. Attach a package with `thread attach`.\n'
+      : `read: nothing in this tree carries "${looking}" — not an id, a sentence, a path, a command, a requirement or a thing taken.\n`,
+  )
+  exit(0)
+}
+
+stdout.write(
+  `read: ${String(rows)} row(s)${looking === '' ? '' : ` carrying "${looking}"`} across ` +
+    `${String(pass.declarations)} declaration(s), and ${String(pass.findings.length)} finding(s) the gate would report.\n`,
+)
+exit(0)

package/dist/integrations/generators/secret.ts

@@ -0,0 +1,289 @@
+import { spawnSync } from 'node:child_process'
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { argv, stdin, stdout } from 'node:process'
+import { createInterface } from 'node:readline'
+
+import { exit } from '../../core/invoked.ts'
+import type { Env } from '../../core/actor.ts'
+import { ELSEWHERE, RECEIPT, answer, asking, asksOf, given, issue, needed, only, ownAnswers, refuse, rowLines, seeding, slug, spend, stating, wordsIn } from '../../core/asking.ts'
+import { holdsRow, listBounds, rowsIn, withRow } from '../../core/rows.ts'
+import { named as packageOf } from '../../core/scope.ts'
+import { findTree, inTree } from '../../core/tree.ts'
+
+import { SAID, SECRECY, secrecyOf, type Secret } from '../secret.ts'
+import { IGNORES, KEY_AT, SEALED_AT, keyOf, seal, sealedIn } from '../vault.ts'
+
+const TREE = findTree()
+
+const FILE = 'secrets.ts'
+
+const LIST = 'SECRETS'
+
+const NAME = /^[a-z][a-z0-9_]*$/
+
+const ENVS: readonly Env[] = ['sandbox', 'production']
+
+const WORDS = Object.keys(SECRECY) as (keyof typeof SECRECY)[]
+
+const ASKS: readonly { readonly key: string; readonly says: readonly string[]; readonly edits?: true }[] = [
+  { key: 'name', says: ['lower_snake_case, and the prefix is added for you'] },
+  { key: 'holder', says: [`who may hold it — ${WORDS.join(', ')}`] },
+  { key: 'describes', says: ['what it is for, in one sentence'], edits: true },
+  { key: 'header', says: ['blank if this value IS the address of what requires it'], edits: true },
+  { key: 'prefix', says: ['what precedes it in that header, trailing space and all'], edits: true },
+]
+
+const TAKES: readonly string[] = ASKS.map((one) => one.key)
+
+const EDITS: readonly string[] = ASKS.filter((one) => one.edits === true).map((one) => one.key)
+
+const ASKED: readonly string[] = ASKS.flatMap((one) =>
+  one.says.map((line, at) => `  ${at === 0 ? `${one.key}:`.padEnd(32) : ' '.repeat(32)}${line}`),
+)
+
+const here = (one: string): string => relative(TREE.at, one).split('\\').join('/')
+
+const path = inTree(TREE, FILE)
+
+const at = here(path)
+
+import { quoted } from '../../core/rows.ts'
+
+let secrets: readonly Secret[] = []
+try {
+  const taken = (await import(new URL(`file://${path}`).href)) as { SECRETS?: readonly Secret[] }
+  secrets = taken.SECRETS ?? []
+} catch {
+  refuse(`${at} could not be read. Attach \`${packageOf('integrations')}\` first — an app states its secrets there.`)
+}
+
+const held = new Map(ENVS.map((env) => [env, new Set(sealedIn(TREE.at, env))]))
+
+const setIn = (id: string): string => {
+  const found = ENVS.filter((env) => held.get(env)?.has(id) === true)
+  return found.length === 0 ? 'no value anywhere yet' : `set for ${found.join(' and ')}`
+}
+
+async function sealing(id: string): Promise<number> {
+  const hidden = async (question: string): Promise<string> => {
+    stdout.write(question)
+    const rl = createInterface({ input: stdin, output: stdout, terminal: true })
+    ;(rl as unknown as { _writeToOutput: (one: string) => void })._writeToOutput = () => {}
+    const value = await new Promise<string>((done) => rl.question('', done))
+    rl.close()
+    stdout.write('\n')
+    return value
+  }
+
+  let sealed = 0
+  for (const env of ENVS) {
+    const value = await hidden(`  ${id} for ${env} (paste it, or press enter to skip): `)
+    if (value.trim() === '') continue
+    seal(TREE.at, id, env, value)
+    sealed += 1
+  }
+  if (sealed === 0) return 0
+
+  const ignore = join(TREE.at, '.gitignore')
+  const already = existsSync(ignore) ? readFileSync(ignore, 'utf8') : ''
+  const missing = IGNORES.filter((one) => !already.split('\n').some((line) => line.trim() === one))
+  if (missing.length > 0) {
+    appendFileSync(ignore, `${already.endsWith('\n') || already === '' ? '' : '\n'}${missing.join('\n')}\n`)
+    stdout.write(`secret: added ${missing.join(', ')} to .gitignore — the key is never committed.\n`)
+  }
+
+  stdout.write(`secret: sealed ${id} for ${String(sealed)} environment(s) into ${SEALED_AT}.\n`)
+  return sealed
+}
+
+const listing =
+  secrets.length === 0
+    ? 'no secrets yet.'
+    : [
+        `${String(secrets.length)} secret(s):`,
+        ...secrets.flatMap((one) => [
+          `  ${one.id} — ${secrecyOf(one.id) ?? 'wearing no prefix, which is refused'}, ${setIn(one.id)}`,
+          `      ${one.sends === undefined ? 'no `sends`, so it is an address' : `sent as ${one.sends.header}: ${one.sends.prefix ?? ''}<value>`}`,
+        ]),
+      ].join('\n')
+
+const words = wordsIn(['new', 'set'])
+
+const verb = words[0]
+
+stdout.write(`${listing}\n`)
+if (keyOf(TREE.at) === undefined && secrets.length > 0) {
+  stdout.write(
+    `\nthere is no vault key at ${KEY_AT}, so nothing above can be opened here. It is never committed — ` +
+      'whoever set this app up has it.\n',
+  )
+}
+
+const method = (nonce: string): string =>
+  [
+    '',
+    'what this makes:',
+    '',
+    `  thread create secret new <name> ${RECEIPT} ${nonce}`,
+    `  thread create secret set <id> ${RECEIPT} ${nonce}`,
+    '',
+    ...ELSEWHERE,
+    '',
+    `  ${RECEIPT} is spent by one run and refused if ${at} moved after it was issued.`,
+    '',
+    'who may hold a value. The word is what you send; the prefix is what the id wears, and the prefix',
+    'IS who may hold it — no field says so:',
+    '',
+    ...WORDS.flatMap((one) => [`  ${one.padEnd(7)} → ${SECRECY[one]}<name>`, `      ${SAID[one]}`, '']),
+    '`new` asks, in this order:',
+    '',
+    ...ASKED,
+    '',
+    'and then, at a terminal only, it asks for the value itself — echo off, sealed as you press enter.',
+    'A piped run declares the row and says so instead, because there is no terminal to read one from.',
+    '',
+    '`edit` asks the same three, and a blank answer keeps what is already there — except that naming',
+    'a DIFFERENT header drops the old prefix unless you give a new one, because a prefix belongs to',
+    'the scheme its header names. `-` as the header removes the header and makes this an address.',
+    '',
+    'It will not change who may hold a value. That is the prefix, the prefix is the id, and an id that',
+    'changes is a different secret — every target requiring the old name would go on requiring a name',
+    'nothing declares. Declare the other one and move what requires it.',
+    '',
+    '`set` is the same prompt on its own, for changing a value later or giving one a `new` run skipped.',
+    'It takes no answers and cannot be piped. The value goes from the keyboard into the sealed store and',
+    `nowhere else — not into a row, not into this output, not into ${SEALED_AT} in any readable form.`,
+    '',
+    'So an agent may declare a secret and may never give it one. That is the point of the split.',
+  ].join('\n')
+
+const flagged = argv.indexOf(RECEIPT)
+
+if (verb === undefined && flagged === -1) {
+  const nonce = issue(TREE.at, listing)
+  stdout.write(`${method(nonce)}\n`)
+  stdout.write(`\nsecret: receipt ${nonce} — spent on use, and stale the moment ${at} changes.\n`)
+  exit(0)
+}
+
+spend(TREE.at, listing, argv[flagged + 1], at)
+
+if (verb !== 'new' && verb !== 'set' && verb !== 'edit') {
+  refuse(`there is nothing called "${verb ?? ''}" to do here — say new, edit or set`)
+}
+
+const text = readFileSync(path, 'utf8')
+const where = listBounds(text, LIST)
+if (where === undefined) refuse(`${at} states no \`${LIST}\` list to declare a secret in`)
+
+if (verb === 'set') {
+  const id = words[1] ?? refuse('`set` takes the id of a secret this app already declares')
+  const one = secrets.find((each) => each.id === id)
+  if (one === undefined) {
+    refuse(
+      `\`${id}\` is not a secret this app declares. Declare it first with \`thread create secret new\` — a value is ` +
+        'given to something that said it needed it, or not at all.',
+    )
+  }
+  if (stdin.isTTY !== true) {
+    refuse(
+      'a value is typed by a person at a terminal, and this run is piped. Nothing was written. Run ' +
+        `\`thread create secret set ${id}\` yourself — an agent may declare a secret and may never give it one.`,
+    )
+  }
+
+  if ((await sealing(id)) === 0) {
+    stdout.write('secret: nothing typed, so nothing was sealed.\n')
+    exit(0)
+  }
+
+  const kept = spawnSync('npx', ['thread', 'vault'], { cwd: TREE.at, encoding: 'utf8' })
+  stdout.write(`${`${kept.stdout ?? ''}${kept.stderr ?? ''}`.trim()}\n`)
+  exit(kept.status === 0 ? 0 : 1)
+}
+
+const piped = given()
+only(piped, TAKES, 'a secret')
+
+const { ask, line, shut } = asking(piped)
+
+const own = ownAnswers(piped)
+
+const name = slug(words[1] ?? (await ask('name', 'name: ')))
+if (name === '') {
+  shut()
+  refuse('a secret has to be called something')
+}
+if (!NAME.test(name)) {
+  shut()
+  refuse(`"${name}" cannot be the name of a secret — it is written in lower_snake_case`)
+}
+
+const holder = (piped.length > 0 ? needed(own, 'holder', 'a secret') : await ask('holder', `who may hold it — ${WORDS.join(', ')}: `)).trim()
+if (!WORDS.includes(holder as keyof typeof SECRECY)) {
+  shut()
+  refuse(
+    `there is no such holder as "${holder}". A secret is held by a ${WORDS.join(' or a ')}, and that prefix is the ` +
+      'only thing standing between a server credential and a browser bundle.',
+  )
+}
+const word = holder as keyof typeof SECRECY
+const id = `${SECRECY[word]}${name}`
+
+if (secrets.some((one) => one.id === id) || holdsRow(text, where, id)) {
+  shut()
+  refuse(`\`${id}\` is already declared in ${at}`)
+}
+
+const describes = (piped.length > 0 ? needed(own, 'describes', 'a secret') : await ask('describes', 'what is it for? ')).trim()
+if (describes === '') {
+  shut()
+  refuse('a secret says what it is for — the sentence is what somebody reads before requiring it')
+}
+
+const header = (piped.length > 0 ? (answer(own, 'header') ?? '') : await ask('header', 'header (blank if this value IS an address): ')).trim()
+const typed = header === '' ? '' : (piped.length > 0 ? (answer(own, 'prefix') ?? '') : await ask('prefix', 'prefix in that header, e.g. "Bearer ": '))
+
+const { stated, kids } = await stating(asksOf('secret', 'Secret', {}, ['id', 'at', 'describes', 'version', 'sends']), piped, piped.length > 0, ask, line, [])
+
+shut()
+
+const prefix = typed === '' || typed.endsWith(' ') ? typed : `${typed} `
+
+const row = [
+  '  {',
+  `    id: ${quoted(id)},`,
+  `    at: '_threads/${FILE}',`,
+  `    describes: ${quoted(describes)},`,
+  '    version: 1,',
+  ...(header === ''
+    ? []
+    : [`    sends: { header: ${quoted(header.toLowerCase())}${prefix === '' ? '' : `, prefix: ${quoted(prefix)}`} },`]),
+  ...rowLines('    ', stated, kids),
+  '  },',
+].join('\n')
+
+writeFileSync(path, withRow(text, where, row), 'utf8')
+
+for (const told of seeding(kids, TREE.at)) stdout.write(`secret: ${told}\n`)
+
+stdout.write(
+  `secret: declared ${id} in ${at}${header === '' ? ' — it has no `sends`, so it is the address of whatever requires it' : ''}.\n`,
+)
+
+if (stdin.isTTY === true) {
+  stdout.write(`\n${SAID[word]}\n\nThe value is not echoed and is sealed straight into ${SEALED_AT}.\n`)
+  if ((await sealing(id)) === 0) {
+    stdout.write(`secret: nothing typed, so ${id} has no value yet. Run \`thread create secret set ${id}\` when you have it.\n`)
+  }
+} else {
+  stdout.write(
+    `secret: it has no value anywhere yet, and this run is piped — a value is typed by a person at a terminal. ` +
+      `Run \`thread create secret set ${id}\` yourself.\n`,
+  )
+}
+
+const kept = spawnSync('npx', ['thread', 'vault'], { cwd: TREE.at, encoding: 'utf8' })
+stdout.write(`${`${kept.stdout ?? ''}${kept.stderr ?? ''}`.trim()}\n`)
+exit(kept.status === 0 ? 0 : 1)