@prestack/thread 0.0.1 → 0.0.2

package/dist/integrations/generators/target.ts

@@ -0,0 +1,944 @@
+import { spawnSync } from 'node:child_process'
+import { readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { argv, stdout } from 'node:process'
+
+import ts from 'typescript'
+
+import type { Env } from '../../core/actor.ts'
+import { exit } from '../../core/invoked.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, showing, withRow, withoutRow } from '../../core/rows.ts'
+import { named as packageOf } from '../../core/scope.ts'
+import { findTree, inTree } from '../../core/tree.ts'
+
+import type { Secret } from '../secret.ts'
+import { secrecyOf } from '../secret.ts'
+import {
+  CALL_PREFIX,
+  HOLDS,
+  REACH,
+  SAID,
+  addressOf,
+  credentialsOf,
+  fills,
+  holdsOf,
+  misnamed,
+  reachOf,
+  refusals,
+  type Call,
+  type Target,
+} from '../target.ts'
+import { opened } from '../vault.ts'
+
+const TREE = findTree()
+
+const FILE = 'targets.ts'
+
+const TARGET_LIST = 'TARGETS'
+
+const CALL_LIST = 'CALLS'
+
+const NAME = /^[a-z][a-z0-9_]*$/
+
+const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const
+
+const WORDS = Object.keys(REACH) as (keyof typeof REACH)[]
+
+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: 'reach', says: [`how it is reached — ${WORDS.join(', ')}`] },
+  {
+    key: 'describes',
+    edits: true,
+    says: [
+      'what it is for, in one sentence, and it has to be yours — blank is',
+      'refused, because copying the reach paragraph above would give two',
+      'targets the same meaning',
+    ],
+  },
+  {
+    key: 'uses',
+    edits: true,
+    says: [
+      'ONLY for module and cli — the npm package to install, or the',
+      'program to run. Not asked for the other four, and refused on them',
+    ],
+  },
+  {
+    key: 'address',
+    edits: true,
+    says: ['the id of a secret with no `sends`. Blank only for a reach', 'that is addressed by nothing'],
+  },
+  { key: 'credentials', edits: true, says: ['comma-separated ids of secrets that DO have a `sends`'] },
+  {
+    key: 'accepts',
+    edits: true,
+    says: [
+      'comma-separated — entity ids for a place that keeps things, call',
+      'ids for one that is called. For module and cli it is what the thing',
+      'can do, read off its published types and offered to you. Usually',
+      'left blank here and filled by `call`, by `thread entity`, or by `edit`',
+    ],
+  },
+]
+
+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 CALLS: readonly { readonly key: string; readonly says: readonly string[] }[] = [
+  {
+    key: 'of',
+    says: ['which target the call belongs to — not needed when it is', 'named as <target> on the command line'],
+  },
+  { key: 'name', says: ['lower_snake_case; the id becomes cl_<name>'] },
+  { key: 'describes', says: ['what it does, in one sentence'] },
+  { key: 'method', says: [`one of ${METHODS.join(', ')}`] },
+  {
+    key: 'path',
+    says: [
+      'under the target address, leading slash and all. Anything that',
+      'varies is written {like_this}',
+    ],
+  },
+]
+
+const MAKES: readonly string[] = CALLS.map((one) => one.key)
+
+const CALLED: readonly string[] = CALLS.flatMap((one) =>
+  one.says.map((line, at) => `  ${at === 0 ? `${one.key}:`.padEnd(32) : ' '.repeat(32)}${line}`),
+)
+
+const PRODUCTION = '--production'
+
+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 targets: readonly Target[] = []
+let calls: readonly Call[] = []
+try {
+  const taken = (await import(new URL(`file://${path}`).href)) as {
+    TARGETS?: readonly Target[]
+    CALLS?: readonly Call[]
+  }
+  targets = taken.TARGETS ?? []
+  calls = taken.CALLS ?? []
+} catch {
+  refuse(`${at} could not be read. Attach \`${packageOf('integrations')}\` first — an app states where it reaches there.`)
+}
+
+let secrets: readonly Secret[] = []
+try {
+  const taken = (await import(new URL(`file://${inTree(TREE, 'secrets.ts')}`).href)) as { SECRETS?: readonly Secret[] }
+  secrets = taken.SECRETS ?? []
+} catch {
+  secrets = []
+}
+
+let entities: readonly string[] = []
+try {
+  const taken = (await import(new URL(`file://${inTree(TREE, 'entities.ts')}`).href)) as {
+    ENTITIES?: readonly { readonly id: string }[]
+  }
+  entities = (taken.ENTITIES ?? []).map((one) => one.id)
+} catch {
+  entities = []
+}
+
+const holdingOf = (id: string): string => {
+  const holds = holdsOf(id)
+  if (holds === undefined) return 'nothing — its id wears no prefix a target is reached by'
+  const yes = [
+    ...(holds.migrations ? ['migrations'] : []),
+    ...(holds.references ? ['references'] : []),
+  ]
+  return `accepts ${holds.takes}, reached from ${holds.from}, ${yes.length === 0 ? 'holds no enforcement of its own' : `holds ${yes.join(', ')}`}`
+}
+
+const requiredBy = (one: Target): string => {
+  if (one.requires.length === 0) return 'nothing, so nothing says where it is'
+  const address = addressOf(one, secrets)
+  return one.requires
+    .map((each) => `${each}${each === address?.id ? ' (its address)' : ''}`)
+    .join(', ')
+}
+
+const listing = [
+  targets.length === 0
+    ? 'no targets yet.'
+    : [
+        `${String(targets.length)} target(s):`,
+        ...targets.flatMap((one) => [
+          `  ${one.id} — ${holdingOf(one.id)}`,
+
+          `      accepts ${[...one.takes, ...(one.offers ?? [])].join(', ') || 'nothing'}`,
+          `      requires ${requiredBy(one)}`,
+        ]),
+      ].join('\n'),
+  calls.length === 0
+    ? 'no calls yet.'
+    : [
+        `${String(calls.length)} call(s):`,
+        ...calls.map((one) => `  ${one.id} — ${one.method} ${one.path} on ${one.of}`),
+      ].join('\n'),
+  secrets.length === 0
+    ? 'no secrets yet — declare one with `thread create secret` before a target can require it.'
+    : [
+        `${String(secrets.length)} secret(s) a target may require:`,
+        ...secrets.map(
+          (one) =>
+            `  ${one.id} — ${secrecyOf(one.id) ?? '?'}, ${one.sends === undefined ? 'no `sends`, so it can be an address' : `sent as ${one.sends.header}`}`,
+        ),
+      ].join('\n'),
+].join('\n\n')
+
+const wrong = refusals(targets, secrets, calls, entities)
+
+const words = wordsIn(['new', 'call'])
+
+const verb = words[0]
+
+const asCall = calls.find((one) => one.id === verb)
+if (asCall !== undefined) {
+  const of = targets.find((one) => one.id === asCall.of)
+
+  const targetWrong = wrong.filter((each) => each.includes(asCall.id) || (of !== undefined && each.includes(of.id)))
+  if (targetWrong.length > 0) refuse(targetWrong.join('\n'))
+  if (of === undefined) refuse(`\`${asCall.of}\` is not a target this app declares`)
+
+  const address = addressOf(of, secrets)
+  if (address === undefined) refuse(`\`${of.id}\` names no address, and the check above should already have said so`)
+  const required = credentialsOf(of, secrets)
+
+  const names = [...new Set(fills(asCall))]
+  const writes = asCall.method === 'POST' || asCall.method === 'PUT' || asCall.method === 'PATCH'
+  const allowed = writes ? [...names, 'body'] : names
+
+  const piped = given()
+  only(piped, allowed, `\`${asCall.id}\``)
+  const { ask, shut } = asking(piped)
+
+  const values = new Map<string, string>()
+  for (const name of names) {
+    const value = piped.length > 0 ? needed(piped, name, `\`${asCall.id}\``) : await ask(name, `${name} (fills the path): `)
+    values.set(name, value.trim())
+  }
+
+  let body: string | undefined
+  if (writes) {
+    const typed = (piped.length > 0 ? (answer(piped, 'body') ?? '') : await ask('body', 'body, as JSON (blank for none): ')).trim()
+    if (typed !== '') {
+      try {
+        JSON.parse(typed)
+      } catch (thrown) {
+        shut()
+        refuse(`that is not JSON: ${thrown instanceof Error ? thrown.message : String(thrown)}. Nothing was called.`)
+      }
+      body = typed
+    }
+  }
+  shut()
+
+  let route = asCall.path
+  for (const name of fills(asCall)) route = route.replace(`{${name}}`, encodeURIComponent(values.get(name) ?? ''))
+
+  const env: Env = argv.includes(PRODUCTION) ? 'production' : 'sandbox'
+
+  const opening = opened(TREE.at, secrets.map((one) => one.id), env)
+  let resolved: Readonly<Record<string, string>>
+  try {
+    resolved = await opening(of.requires)
+  } catch (thrown) {
+    refuse(thrown instanceof Error ? thrown.message : String(thrown))
+  }
+
+  const host = resolved[address.id] ?? ''
+  const based = /^https?:\/\//.test(host) ? host : `https://${host}`
+  const url = `${based.replace(/\/+$/, '')}${route.startsWith('/') ? route : `/${route}`}`
+
+  const headers: Record<string, string> = {}
+  for (const credential of required) {
+    const value = resolved[credential.id]
+    if (value === undefined || credential.sends === undefined) continue
+    headers[credential.sends.header] = `${credential.sends.prefix ?? ''}${value}`
+  }
+  if (body !== undefined) headers['content-type'] = 'application/json'
+
+  let response: Response
+  try {
+    response = await fetch(url, { method: asCall.method, headers, ...(body === undefined ? {} : { body }) })
+  } catch (thrown) {
+    refuse(
+      `\`${asCall.id}\` — ${asCall.method} ${route} on \`${of.id}\` — threw before a response came back: ` +
+        `${thrown instanceof Error ? thrown.message : String(thrown)}`,
+    )
+  }
+
+  const text = await response.text()
+  stdout.write(`call: ${asCall.method} ${route} on \`${of.id}\` (${env}) — ${String(response.status)} ${response.statusText}\n`)
+  if (text.trim() !== '') {
+    try {
+      stdout.write(`${JSON.stringify(JSON.parse(text), null, 2)}\n`)
+    } catch {
+      stdout.write(`${text}\n`)
+    }
+  }
+  exit(response.ok ? 0 : 1)
+}
+
+if (verb !== undefined && verb.startsWith(CALL_PREFIX)) {
+  refuse(
+    `\`${verb}\` is not a call this app declares. What is here is ${calls.map((one) => one.id).join(', ') || '(nothing yet)'} — ` +
+      'declare one with `thread create target call <target> <name>`.',
+  )
+}
+
+stdout.write(`${listing}\n`)
+if (wrong.length > 0) {
+  stdout.write(`\n${String(wrong.length)} thing(s) this app already states that will not hold:\n`)
+  for (const one of wrong) stdout.write(`  ${one}\n`)
+}
+
+const method = (nonce: string): string =>
+  [
+    '',
+    'what this makes:',
+    '',
+    `  thread create target new <name> ${RECEIPT} ${nonce}`,
+    `  thread create target call <target> <name> ${RECEIPT} ${nonce}`,
+    '  thread run call <id>                       no receipt — makes an already-declared call, through',
+    '                                              the vault. Add --production to call it there; the',
+    '                                              default is sandbox.',
+    '',
+    ...ELSEWHERE,
+    '',
+    `  ${RECEIPT} is spent by one run and refused if ${at} moved after it was issued.`,
+    '',
+    'how a target may be reached. The word is what you send; the prefix is what its id wears, and the',
+    'prefix IS how it is reached — no field says so:',
+    '',
+    ...WORDS.flatMap((one) => [
+      `  ${one.padEnd(9)} → ${REACH[one]}<name>`,
+      `      accepts ${HOLDS[one].takes}, from ${HOLDS[one].from}, ${HOLDS[one].addressed ? 'addressed' : 'addressed by nothing'}`,
+      `      ${SAID[one]}`,
+      '',
+    ]),
+    '`new` asks, in this order:',
+    '',
+    ...ASKED,
+    '  and then, at a terminal only, for a module whose package holds resources: naming one above asks',
+    '  which of its methods you want, and what is written is the whole path — `customers.create`.',
+    '  Blank there takes every method it just listed. There is no key for it, because a piped answer',
+    '  names whole paths in `accepts` and never needs asking twice.',
+    '',
+    `\`edit\` takes: ${EDITS.join(', ')} — and for a module it reads the package again, so a version`,
+    'that gained methods offers them without the row being retyped.',
+    '',
+    '`call` asks, in this order:',
+    '',
+    ...CALLED,
+    '',
+    'A node then names the call. It never writes a url, a method or a secret: what a target is, where',
+    'it is and what opens it are all read off these rows when the operation is compiled.',
+  ].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(`\ntarget: 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 !== 'call') {
+  refuse(`there is nothing called "${verb ?? ''}" to do here — say new, or call`)
+}
+
+const text = readFileSync(path, 'utf8')
+
+const listed = (one: string | undefined): readonly string[] =>
+  (one ?? '')
+    .split(',')
+    .map((each) => each.trim())
+    .filter((each) => each !== '')
+
+if (verb === 'call') {
+  const piped = given()
+  only(piped, MAKES, 'a call')
+  const { ask, shut } = asking(piped)
+
+  const of = (words[1] ?? (await ask('of', `which target — ${targets.map((one) => one.id).join(', ') || '(none yet)'}: `))).trim()
+  const target = targets.find((one) => one.id === of)
+  if (target === undefined) {
+    shut()
+    refuse(`this app declares no target \`${of}\`. A call belongs to one place, and that place is declared first.`)
+  }
+  if (holdsOf(target.id)?.takes !== 'calls') {
+    shut()
+    refuse(
+      `\`${target.id}\` is reached over ${String(reachOf(target.id))} and keeps entities. A place you keep rows in is ` +
+        'not a place you issue verbs at.',
+    )
+  }
+
+  const name = slug(words[2] ?? (await ask('name', 'name: ')))
+  if (name === '' || !NAME.test(name)) {
+    shut()
+    refuse(`"${name}" cannot be the name of a call — it is written in lower_snake_case`)
+  }
+  const id = `${CALL_PREFIX}${name}`
+  if (calls.some((one) => one.id === id)) {
+    shut()
+    refuse(`\`${id}\` is already declared in ${at}`)
+  }
+
+  const describes = (piped.length > 0 ? needed(piped, 'describes', 'a call') : await ask('describes', 'what does it do? ')).trim()
+  if (describes === '') {
+    shut()
+    refuse('a call says what it does — the sentence is what somebody reads before making it')
+  }
+
+  const verbWord = (piped.length > 0 ? needed(piped, 'method', 'a call') : await ask('method', `method — ${METHODS.join(', ')}: `))
+    .trim()
+    .toUpperCase()
+  if (!(METHODS as readonly string[]).includes(verbWord)) {
+    shut()
+    refuse(`there is no such method as "${verbWord}" — it is one of ${METHODS.join(', ')}`)
+  }
+
+  const route = (piped.length > 0 ? needed(piped, 'path', 'a call') : await ask('path', 'path, leading slash and all: ')).trim()
+  shut()
+  if (!route.startsWith('/')) refuse(`"${route}" is not a path under an address — it opens with a slash`)
+
+  const callWhere = listBounds(text, CALL_LIST)
+  if (callWhere === undefined) refuse(`${at} states no \`${CALL_LIST}\` list to declare a call in`)
+
+  const row = [
+    '  {',
+    `    id: ${quoted(id)},`,
+    `    at: '_threads/${FILE}',`,
+    `    describes: ${quoted(describes)},`,
+    '    version: 1,',
+    `    of: ${quoted(target.id)},`,
+    `    method: ${quoted(verbWord)},`,
+    `    path: ${quoted(route)},`,
+    '  },',
+  ].join('\n')
+
+  const withCall = withRow(text, callWhere, row)
+
+  const targetWhere = listBounds(withCall, TARGET_LIST)
+  if (targetWhere === undefined) refuse(`${at} states no \`${TARGET_LIST}\` list`)
+  const taking = [...target.takes, id]
+  const replaced = withCall.replace(
+    new RegExp(`(id: '${target.id}',[\\s\\S]*?takes: )\\[[^\\]]*\\]`),
+    `$1[${taking.map((one) => quoted(one)).join(', ')}]`,
+  )
+  if (replaced === withCall) {
+    refuse(`\`${target.id}\` has no \`takes\` this could add \`${id}\` to. Nothing was written.`)
+  }
+  writeFileSync(path, replaced, 'utf8')
+
+  stdout.write(`target: declared ${id} — ${verbWord} ${route} on ${target.id}, and ${target.id} now accepts it.\n`)
+  exit(0)
+}
+
+const piped = given()
+const own = ownAnswers(piped)
+only(own, TAKES, 'a target')
+const { ask, line, shut } = asking(piped)
+
+const name = slug(words[1] ?? (await ask('name', 'name: ')))
+if (name === '') {
+  shut()
+  refuse('a target has to be called something')
+}
+if (!NAME.test(name)) {
+  shut()
+  refuse(`"${name}" cannot be the name of a target — it is written in lower_snake_case`)
+}
+
+const reach = (piped.length > 0 ? needed(own, 'reach', 'a target') : await ask('reach', `how is it reached — ${WORDS.join(', ')}: `)).trim()
+if (!WORDS.includes(reach as keyof typeof REACH)) {
+  shut()
+  refuse(`there is no such reach as "${reach}". A target is reached ${WORDS.join(', ')}.`)
+}
+const word = reach as keyof typeof REACH
+const id = `${REACH[word]}${name}`
+
+if (targets.some((one) => one.id === id)) {
+  shut()
+  refuse(`\`${id}\` is already declared in ${at}`)
+}
+
+const answered = (piped.length > 0 ? (answer(own, 'describes') ?? '') : await ask('describes', 'what is it for? ')).trim()
+
+if (answered === '') {
+  shut()
+  refuse(
+    `a target says what IT is, and blank would have copied the ${word} paragraph above onto this row — so ` +
+      `\`${REACH[word]}${name}\` would carry a sentence about ${word} reaches in general and nothing about this one. ` +
+      'Say what it is to somebody who has not seen it: what this app reaches through it, and what for.',
+  )
+}
+const describes = answered
+
+const PACKAGE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/
+const PROGRAM = /^[a-z][a-z0-9._-]*$/
+
+const arrives = HOLDS[word].arrives
+const uses = (
+  arrives === null
+    ? ''
+    : piped.length > 0
+      ? needed(own, 'uses', `a target reached as ${word}`)
+      : await ask(
+          'uses',
+          arrives === 'npm'
+            ? 'npm package to install — the name `npm install` is given: '
+            : 'program to run — the name you would type at a shell, e.g. `git`: ',
+        )
+).trim()
+
+if (arrives !== null) {
+  if (uses === '') {
+    shut()
+    refuse(
+      arrives === 'npm'
+        ? 'a module installs something — the npm package is what `npm install` is given'
+        : 'a command runs something — the program is what you would type at a shell',
+    )
+  }
+  if (!(arrives === 'npm' ? PACKAGE : PROGRAM).test(uses)) {
+    shut()
+    refuse(`"${uses}" does not read as ${arrives === 'npm' ? 'an npm package name' : 'a program name'}`)
+  }
+}
+
+if (arrives === 'npm') {
+  stdout.write(`target: installing ${uses} …\n`)
+  const got = spawnSync('npm', ['install', uses], { cwd: TREE.at, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+  if (got.status !== 0) {
+    shut()
+    refuse(`\`npm install ${uses}\` failed, so nothing was declared:\n${`${got.stdout ?? ''}${got.stderr ?? ''}`.trim()}`)
+  }
+  stdout.write(`target: installed ${uses}.\n`)
+} else if (arrives === 'machine') {
+  const found = spawnSync(uses, ['--version'], { cwd: TREE.at, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+  if (found.error !== undefined || found.status === null) {
+    shut()
+    refuse(
+      `\`${uses}\` is not on this machine, so there is nothing to declare. It is a program rather than a dependency ` +
+        '— install it the way this machine installs programs and run this again. Nothing was written.',
+    )
+  }
+}
+
+const driver = HOLDS[word].driver
+
+if (driver !== null) {
+  stdout.write(`target: installing ${driver} …\n`)
+  const opened = spawnSync('npm', ['install', driver], { cwd: TREE.at, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+  if (opened.status !== 0) {
+    shut()
+    refuse(`npm install ${driver} failed, so nothing was declared. A ${word} target is opened with ${driver}, and the store written for it imports that package:\n${`${opened.stdout ?? ''}${opened.stderr ?? ''}`.trim()}`)
+  }
+  stdout.write(`target: installed ${driver} — what a ${word} target is opened with.\n`)
+}
+
+let offered: readonly string[] = []
+let deeper: ReadonlyMap<string, readonly string[]> = new Map()
+if (HOLDS[word].takes === 'names' && arrives === 'npm') {
+  const read = surfaceOf(uses, id)
+  offered = read.offered
+  deeper = read.deeper
+  stdout.write(
+    offered.length === 0
+      ? `target: ${uses} publishes no types this could read, so name what it can do yourself.\n`
+      : `target: read ${String(offered.length)} name(s) off \`${uses}\`, ${String(deeper.size)} of which hold methods.\n`,
+  )
+}
+
+const PROBES: readonly (readonly string[])[] = [
+  ['help', '-a'],
+  ['--help'],
+  ['help'],
+]
+
+const COLUMN = /^\s{2,}([a-z][a-z0-9-]*):?\s{2,}\S/
+
+const LISTED = /^\s{2,}[a-z][a-z0-9-]+(?:,\s*[a-z][a-z0-9-]+)*,?\s*$/
+
+const readOff = (text: string): readonly string[] => {
+  const found = new Set<string>()
+  for (const line of text.split('\n')) {
+    const column = COLUMN.exec(line)
+    if (column?.[1] !== undefined) {
+      found.add(column[1])
+      continue
+    }
+    if (!LISTED.test(line)) continue
+    for (const each of line.split(',')) {
+      const one = each.trim()
+      if (/^[a-z][a-z0-9-]*$/.test(one)) found.add(one)
+    }
+  }
+  return [...found]
+}
+
+if (HOLDS[word].takes === 'names' && arrives === 'machine') {
+  for (const probe of PROBES) {
+    const asked = spawnSync(uses, [...probe], { cwd: TREE.at, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+
+    const said = readOff(`${asked.stdout ?? ''}\n${asked.stderr ?? ''}`)
+    if (said.length < 3) continue
+    offered = said.filter((one) => misnamed(id, one) === undefined).sort()
+    stdout.write(`target: read ${String(offered.length)} command(s) off \`${uses} ${probe.join(' ')}\`.\n`)
+    break
+  }
+}
+
+const addresses = secrets.filter((one) => one.sends === undefined)
+const credentials = secrets.filter((one) => one.sends !== undefined)
+
+const address = HOLDS[word].addressed
+  ? (piped.length > 0
+      ? needed(own, 'address', 'a target that is reached somewhere')
+      : await ask('address', `address — one of ${addresses.map((one) => one.id).join(', ') || '(declare one with `thread create secret`)'}: `)
+    ).trim()
+  : ''
+
+if (HOLDS[word].addressed) {
+  const found = secrets.find((one) => one.id === address)
+  if (found === undefined) {
+    shut()
+    refuse(
+      `\`${address}\` is not a secret this app declares. A target reached over ${word} needs one saying where it is — ` +
+        'declare it with `thread create secret`, leaving the header blank.',
+    )
+  }
+  if (found.sends !== undefined) {
+    shut()
+    refuse(
+      `\`${address}\` has a \`sends\`, so it is a credential and not an address — it goes into the ` +
+        `\`${found.sends.header}\` header on every call. An address is the one secret with nowhere to be sent.`,
+    )
+  }
+} else if (address !== '') {
+  shut()
+  refuse(`a target reached over ${word} is addressed by nothing, and \`${address}\` was offered as its address`)
+}
+
+const carrying = listed(piped.length > 0 ? answer(own, 'credentials') : await ask('credentials', `credentials, comma-separated — ${credentials.map((one) => one.id).join(', ') || '(none declared)'}: `))
+for (const one of carrying) {
+  const found = secrets.find((each) => each.id === one)
+  if (found === undefined) {
+    shut()
+    refuse(`\`${one}\` is not a secret this app declares`)
+  }
+
+  if (HOLDS[word].addressed && found.sends === undefined) {
+    shut()
+    refuse(`\`${one}\` has no \`sends\`, so it is an address rather than something to send. One target, one address.`)
+  }
+}
+
+const asked =
+  HOLDS[word].takes === 'names'
+    ? offered.length === 0
+      ? 'what it can do, comma-separated — nothing was readable off it, so name them: '
+      : deeper.size === 0
+        ? `what it can do, comma-separated (blank takes all ${String(offered.length)}):\n  ${offered.join(', ')}\n  > `
+        : `what it can do, comma-separated (blank takes none). ${String(deeper.size)} of these hold methods, and naming ` +
+          `one asks which of them you want; the rest are called directly:\n  ${offered.join(', ')}\n  > `
+    : `accepts, comma-separated ${HOLDS[word].takes} (blank for none yet): `
+
+const named = listed(piped.length > 0 ? answer(own, 'accepts') : await ask('accepts', asked))
+const wide = named.length === 0 && HOLDS[word].takes === 'names' && deeper.size === 0 ? offered : named
+
+const accepts: string[] = []
+for (const one of wide) {
+  const beneath = deeper.get(one)
+  if (beneath === undefined) {
+    accepts.push(one)
+    continue
+  }
+  const picked = listed(
+    await ask(
+      `accepts_${one}`,
+      `what may run on \`${one}\` (blank takes all ${String(beneath.length)}):\n  ${beneath.join(', ')}\n  > `,
+    ),
+  )
+  for (const each of picked.length === 0 ? beneath : picked) accepts.push(`${one}.${each}`)
+}
+
+for (const one of accepts) {
+  const wrong = misnamed(id, one)
+  if (wrong !== undefined) {
+    shut()
+    refuse(wrong)
+  }
+}
+
+if (accepts.length > 0 && HOLDS[word].takes === 'entities') {
+  shut()
+  refuse(
+    `a target keeps entities, and which entities it keeps is written by \`thread create entity\` — it is the ` +
+      `command that also writes what this target then derives: its schema, its migrations, its reference. Naming ` +
+      `${accepts.map((one) => `\`${one}\``).join(', ')} here would put ${accepts.length === 1 ? 'it' : 'them'} in ` +
+      'the target and leave those rows unwritten, so `thread schema` would refuse and ask you to edit a sheet by ' +
+      'hand. Declare the target with `accepts` blank, then run `thread create entity` — a new one asks where it is ' +
+      'kept, and one that already exists is offered a home by `thread create entity edit`. Nothing was written.',
+  )
+}
+
+
+const { stated, kids } = await stating(asksOf('target', 'Target', {}, ['id', 'at', 'describes', 'version', 'uses', 'offers', 'takes', 'requires', 'accepts']), piped, piped.length > 0, ask, line, [])
+
+shut()
+
+const requires = [...(address === '' ? [] : [address]), ...carrying]
+
+const where = listBounds(text, TARGET_LIST)
+if (where === undefined) refuse(`${at} states no \`${TARGET_LIST}\` list to declare a target in`)
+if (holdsRow(text, where, id)) refuse(`\`${id}\` is already declared in ${at}`)
+
+const row = [
+  '  {',
+  `    id: ${quoted(id)},`,
+  `    at: '_threads/${FILE}',`,
+  `    describes: ${quoted(describes)},`,
+  '    version: 1,',
+
+  ...(uses === '' ? [] : [`    uses: ${quoted(uses)},`]),
+
+  ...(HOLDS[word].takes === 'names'
+    ? [`    offers: [${accepts.map((one) => quoted(one)).join(', ')}],`, '    takes: [],']
+    : [`    takes: [${accepts.map((one) => quoted(one)).join(', ')}],`]),
+  `    requires: [${requires.map((one) => quoted(one)).join(', ')}],`,
+  ...rowLines('    ', stated, kids),
+  '  },',
+].join('\n')
+
+writeFileSync(path, withRow(text, where, row), 'utf8')
+
+for (const told of seeding(kids, TREE.at)) stdout.write(`target: ${told}\n`)
+
+if (HOLDS[word].takes === 'names') grows(id, name, uses, accepts)
+
+const after = refusals(
+  [
+    ...targets,
+    {
+      id,
+      at: `_threads/${FILE}`,
+      describes,
+      version: 1,
+      ...(HOLDS[word].takes === 'names' ? { takes: [], offers: accepts } : { takes: accepts }),
+      requires,
+      ...(uses === '' ? {} : { uses }),
+    },
+  ],
+  secrets,
+  calls,
+  entities,
+)
+const mine = after.filter((one) => one.includes(id))
+
+stdout.write(`target: declared ${id} in ${at} — ${holdingOf(id)}.\n`)
+if (mine.length > 0) {
+  for (const one of mine) stdout.write(`target: ${one}\n`)
+}
+
+const kept = spawnSync('npx', ['thread', 'vault'], { cwd: TREE.at, encoding: 'utf8' })
+if (kept.status !== 0) stdout.write(`${`${kept.stdout ?? ''}${kept.stderr ?? ''}`.trim()}\n`)
+exit(0)
+
+function surfaceOf(
+  uses: string,
+  target: string,
+): {
+  readonly offered: readonly string[]
+  readonly deeper: ReadonlyMap<string, readonly string[]>
+} {
+  const nothing = { offered: [] as readonly string[], deeper: new Map<string, readonly string[]>() }
+
+  const options: ts.CompilerOptions = {
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    module: ts.ModuleKind.ESNext,
+    target: ts.ScriptTarget.ESNext,
+    skipLibCheck: true,
+    allowJs: true,
+    noEmit: true,
+  }
+  const found = ts.resolveModuleName(uses, join(TREE.at, 'package.json'), options, ts.sys)
+  const declaration = found.resolvedModule?.resolvedFileName
+  if (declaration === undefined) return nothing
+
+  const program = ts.createProgram([declaration], options)
+  const checker = program.getTypeChecker()
+  const file = program.getSourceFile(declaration)
+  if (file === undefined) return nothing
+  const held = checker.getSymbolAtLocation(file)
+  if (held === undefined) return nothing
+
+  const unaliased = (one: ts.Symbol): ts.Symbol =>
+    (one.flags & ts.SymbolFlags.Alias) === 0 ? one : checker.getAliasedSymbol(one)
+  const exported = checker.getExportsOfModule(held)
+  const named = exported.find((one) => one.getName() === 'default' || one.getName() === 'export=')
+  const entry = named === undefined ? undefined : unaliased(named)
+
+  const typeOf = (one: ts.Symbol): ts.Type => checker.getTypeOfSymbolAtLocation(one, one.declarations?.[0] ?? file)
+  const calls = (one: ts.Type): readonly ts.Signature[] => checker.getSignaturesOfType(one, ts.SignatureKind.Call)
+
+  let top: ts.Type | undefined
+  if (entry !== undefined) {
+    const declared = checker.getDeclaredTypeOfSymbol(entry)
+    if (checker.getPropertiesOfType(declared).length > 0) top = declared
+    else {
+      const signature = calls(typeOf(entry))[0]
+      if (signature !== undefined) top = checker.getReturnTypeOfSignature(signature)
+    }
+  }
+
+  const HIDDEN = /^_/
+  const inherits = (one: ts.Type): ReadonlySet<string> => {
+    const names = new Set<string>()
+    for (const base of one.getBaseTypes() ?? []) for (const each of checker.getPropertiesOfType(base)) names.add(each.getName())
+    return names
+  }
+  const own = (one: ts.Type, entry = false): readonly ts.Symbol[] => {
+    const skip = entry ? new Set<string>() : inherits(one)
+    return checker.getPropertiesOfType(one).filter((each) => !HIDDEN.test(each.getName()) && !skip.has(each.getName()))
+  }
+
+  const DEEP = 3
+  const under = (one: ts.Type, depth: number, seen: ReadonlySet<string>): readonly string[] => {
+    if (depth > DEEP) return []
+    const out: string[] = []
+    for (const each of own(one)) {
+      const mine = typeOf(each)
+      if (calls(mine).length > 0) {
+        out.push(each.getName())
+        continue
+      }
+      const shape = checker.typeToString(mine)
+      if (seen.has(shape)) continue
+      for (const deep of under(mine, depth + 1, new Set([...seen, shape]))) out.push(`${each.getName()}.${deep}`)
+    }
+    return out.sort()
+  }
+
+  const walked = top !== undefined && checker.getPropertiesOfType(top).length > 0 ? own(top, true) : exported.map(unaliased)
+  const offered: string[] = []
+  const deeper = new Map<string, readonly string[]>()
+  for (const one of walked) {
+    const name = one.getName()
+    if (HIDDEN.test(name) || name === 'default' || name === 'export=') continue
+    if (misnamed(target, name) !== undefined) continue
+    const mine = typeOf(one)
+    if (calls(mine).length > 0) {
+      offered.push(name)
+      continue
+    }
+    const beneath = under(mine, 1, new Set()).filter((each) => misnamed(target, `${name}.${each}`) === undefined)
+    if (beneath.length > 0) {
+      offered.push(name)
+      deeper.set(name, beneath)
+    }
+  }
+  return { offered: offered.sort(), deeper }
+}
+
+function grows(id: string, name: string, uses: string, held: readonly string[]): void {
+
+  const said =
+    `The command this app gained by declaring \`${id}\`. \`thread run ${name} <command>\` runs one of the ` +
+    `command(s) read off \`${uses}\` when it was declared, with every argument and flag reaching it untouched; ` +
+    'asked for nothing it prints that set. A command outside the set was never declared here and does not run. ' +
+    `The row states \`_threads/run_${name}.ts\`, one line naming this integration so the shared runner knows ` +
+    'which it is — there is nothing in that file to change that declaring this again would not write the same ' +
+    'way. This verb exists only because the integration is declared: take the target away and it goes.'
+
+  writeFileSync(
+    inTree(TREE, `run_${name}.ts`),
+    `import { ran } from '../module.ts'\n\nawait ran(${quoted(name)})\n`,
+    'utf8',
+  )
+
+  const owner = inTree(TREE, 'integrations.ts')
+  try {
+    const owned = readFileSync(owner, 'utf8')
+    const under = listBounds(owned, 'declares')
+    if (under !== undefined && !holdsRow(owned, under, `run_${name}`)) {
+      writeFileSync(
+        owner,
+        withRow(
+          owned,
+          under,
+          [
+            '  {',
+            `    id: ${quoted(`run_${name}`)},`,
+            `    at: ${quoted(`_threads/run_${name}.ts`)},`,
+            `    describes: ${quoted(said)},`,
+            '    version: 1,',
+            '  },',
+          ].join('\n'),
+        ),
+        'utf8',
+      )
+    }
+  } catch {
+    stdout.write(`target: _threads/integrations.ts could not be read, so \`run_${name}\` is registered but not declared.\n`)
+  }
+
+  const seat = inTree(TREE, 'derivation.ts')
+  let listed = ''
+  try {
+    listed = readFileSync(seat, 'utf8')
+  } catch {
+    listed = ''
+  }
+  const into = listed === '' ? undefined : listBounds(listed, 'GENERATORS')
+  if (into === undefined) {
+    stdout.write(
+      `target: ${id} is declared, but _threads/derivation.ts states no \`GENERATORS\` list, so \`thread run ${name}\` ` +
+        `does not exist yet. Attach \`${packageOf('derivation')}\` and declare this again.\n`,
+    )
+  } else if (holdsRow(listed, into, `run_${name}`)) {
+    stdout.write(`target: \`thread run ${name}\` already resolves — left as it was.\n`)
+  } else {
+    writeFileSync(
+      seat,
+      withRow(
+        listed,
+        into,
+        [
+          '  {',
+          `    id: ${quoted(`run_${name}`)},`,
+          `    at: ${quoted(`_threads/run_${name}.ts`)},`,
+          `    describes: ${quoted(said)},`,
+          '    version: 1,',
+          `    by: ${quoted(`thread run ${name}`)},`,
+          '  },',
+        ].join('\n'),
+      ),
+      'utf8',
+    )
+    stdout.write(`target: \`thread run ${name}\` is now a command on this tree — ${String(held.length)} of them under it.\n`)
+  }
+}
+