@prestack/thread 0.0.1 → 0.0.3

package/dist/core/attach.js

@@ -73,7 +73,7 @@ async function attaching(into, name) {
     }
     catch {
         if (!existsSync(join(into, 'node_modules', owner, 'package.json'))) {
-            throw new UnattachableError(owner, `is not installed in this app — run \`npm i ${owner}\` first, because \`thread attach\` takes on a ` +
+            throw new UnattachableError(owner, `is not installed in this app — run \`npm i -D ${owner}\` first, because \`thread attach\` takes on a ` +
                 'package that is already here rather than fetching one');
         }
         throw new UnattachableError(name, name.endsWith(DOOR) ? `is named in \`attaches\` and ${owner} as installed here ships no such module` : 'exports no `attach`');
@@ -126,7 +126,7 @@ export async function attach(into, name, touched = new Set(), under = []) {
     const one = await attaching(into, name);
     for (const on of one.attaches ?? []) {
         if (!(await attaches(into, on))) {
-            throw new UnattachableError(name, `must have ${on} attached before it, and ${on} is not installed here — run \`npm install ${packageOf(on)}\` and attach ${name} again. ` +
+            throw new UnattachableError(name, `must have ${on} attached before it, and ${on} is not installed here — run \`npm install -D ${packageOf(on)}\` and attach ${name} again. ` +
                 `${on} is named in \`attaches\` and not in dependencies, because a package that only appends a row to a file ` +
                 'another package owns would otherwise carry an npm edge it never imports');
         }

package/dist/core/attach.ts

@@ -0,0 +1,585 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join, relative, resolve } from 'node:path'
+import { stdout } from 'node:process'
+
+import { ROOT, TREE, root as rooted } from './init.ts'
+import { STATED, holdsRow, listBounds, quoted, reconciled, rowsIn, withRow, withoutRow } from './rows.ts'
+import { ours as isOurs } from './scope.ts'
+
+const LISTS = ['declares', 'derives', 'seeds']
+
+const SHAPE = /export interface [A-Za-z0-9_]+ extends Threaded \{[\s\S]*?\n\}\n/
+
+const MEMBERS = 'MEMBERS'
+
+const DOOR = '/attach'
+
+export const packageOf = (name: string): string =>
+  name.startsWith('@') ? name.split('/').slice(0, 2).join('/') : (name.split('/')[0] ?? name)
+
+export interface Appending {
+  readonly into: string
+  readonly list: string
+  readonly id: string
+  readonly source: string
+}
+
+export interface Writing {
+  readonly file: string
+  readonly source: string
+}
+
+export interface Attaching {
+  readonly id: string
+  readonly writes: readonly Writing[]
+  readonly declares: string
+  readonly rows?: readonly Appending[]
+
+  readonly retires?: readonly {
+    readonly into: string
+    readonly list: string
+    readonly id: string
+
+    readonly made?: string
+
+    readonly why: string
+  }[]
+
+  readonly attaches?: readonly string[]
+
+  readonly scripts?: Readonly<Record<string, string>>
+
+  readonly needs?: Readonly<Record<string, string>>
+
+  readonly ignores?: readonly string[]
+}
+
+export class UnattachableError extends Error {
+  constructor(name: string, why: string) {
+    super(`${name} ${why}. A package that attaches exports an \`ATTACH\` from \`${name.endsWith(DOOR) ? name : `${name}${DOOR}`}\`.`)
+    this.name = 'UnattachableError'
+  }
+}
+
+export class StillADependencyError extends Error {
+  constructor(name: string, of: readonly string[]) {
+    super(`${name} is still a dependency of ${of.join(', ')} — detach ${of.length === 1 ? 'it' : 'those'} first, or their rows are left pointing at nothing.`)
+    this.name = 'StillADependencyError'
+  }
+}
+
+export class StillDeclaredError extends Error {
+  constructor(name: string, theirs: readonly string[]) {
+    super(
+      `${name} writes the files this tree declares ${theirs.slice(0, 6).join(', ')}${theirs.length > 6 ? ` and ${String(theirs.length - 6)} more` : ''} in, so detaching it would leave ${theirs.length === 1 ? 'that' : 'those'} declared by nothing. ` +
+        'Remove what this app declared of its own first, or keep the package. Detaching is for a package nothing of yours is built on.',
+    )
+    this.name = 'StillDeclaredError'
+  }
+}
+
+export class DependencyRingError extends Error {
+  constructor(ring: readonly string[]) {
+    super(`${ring.join(' depends on ')} — a ring has no first package, so there is no order to attach them in.`)
+    this.name = 'DependencyRingError'
+  }
+}
+
+export class TakenFileError extends Error {
+  constructor(name: string, file: string) {
+    super(`${file} is already there and the tree does not declare \`${name}\`'s id, so another package holds that name. One file, one owner.`)
+    this.name = 'TakenFileError'
+  }
+}
+
+export class UnthreadedError extends Error {
+  constructor() {
+    super(`there is no ${TREE}/${ROOT} here — run \`thread init\` first.`)
+    this.name = 'UnthreadedError'
+  }
+}
+
+export async function attaches(into: string, name: string): Promise<boolean> {
+  try {
+    await attaching(into, name)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function attaching(into: string, name: string): Promise<Attaching> {
+  const spec = name.endsWith(DOOR) ? name : `${name}${DOOR}`
+  const owner = packageOf(name)
+  let held: { ATTACH?: Attaching }
+  try {
+    held = (await import(createRequire(join(into, 'package.json')).resolve(spec))) as { ATTACH?: Attaching }
+  } catch {
+    if (!existsSync(join(into, 'node_modules', owner, 'package.json'))) {
+      throw new UnattachableError(
+        owner,
+        `is not installed in this app — run \`npm i -D ${owner}\` first, because \`thread attach\` takes on a ` +
+          'package that is already here rather than fetching one',
+      )
+    }
+    throw new UnattachableError(
+      name,
+      name.endsWith(DOOR) ? `is named in \`attaches\` and ${owner} as installed here ships no such module` : 'exports no `attach`',
+    )
+  }
+  if (held.ATTACH === undefined) throw new UnattachableError(name, 'exports no `ATTACH`')
+  return held.ATTACH
+}
+
+export async function behind(into: string, name: string): Promise<readonly { readonly id: string; readonly says?: string }[]> {
+  let one: Attaching
+  try {
+    one = await attaching(into, name)
+  } catch {
+    return []
+  }
+  const dir = resolve(into, TREE)
+  const stale: { id: string; says?: string }[] = []
+  for (const row of one.rows ?? []) {
+    const at = join(dir, row.into)
+    if (!existsSync(at)) continue
+    const text = readFileSync(at, 'utf8')
+    const where = listBounds(text, row.list)
+    if (where === undefined) continue
+    if (text.slice(where.open, where.close).includes(row.source.trim().replace(/,$/, ''))) continue
+
+    const says = /by:\s*'(thread [a-z0-9_ -]+)'/.exec(row.source)?.[1]
+    const known = says !== undefined && text.slice(where.open, where.close).includes(`by: '${says}'`)
+    stale.push(says === undefined || known ? { id: row.id } : { id: row.id, says })
+  }
+  return stale
+}
+
+function edit(at: string, change: (text: string) => string, touched: Set<string>, into: string): void {
+  const text = readFileSync(at, 'utf8')
+  const next = change(text)
+  if (next === text) return
+  writeFileSync(at, next, 'utf8')
+  touched.add(relative(into, at))
+}
+
+export async function attach(
+  into: string,
+  name: string,
+  touched = new Set<string>(),
+  under: readonly string[] = [],
+): Promise<readonly string[]> {
+  if (under.includes(name)) throw new DependencyRingError([...under.slice(under.indexOf(name)), name])
+  const dir = resolve(into, TREE)
+  const root = join(dir, ROOT)
+  if (!existsSync(root)) throw new UnthreadedError()
+
+  const one = await attaching(into, name)
+
+  for (const on of one.attaches ?? []) {
+    if (!(await attaches(into, on))) {
+      throw new UnattachableError(
+        name,
+        `must have ${on} attached before it, and ${on} is not installed here — run \`npm install -D ${packageOf(on)}\` and attach ${name} again. ` +
+          `${on} is named in \`attaches\` and not in dependencies, because a package that only appends a row to a file ` +
+          'another package owns would otherwise carry an npm edge it never imports',
+      )
+    }
+    await attach(into, on, touched, [...under, name])
+  }
+
+  const plan = new Map<string, string>()
+
+  const retired: string[] = []
+
+  const reshaped: string[] = []
+
+  const noticed: string[] = []
+
+  const held = readFileSync(root, 'utf8')
+  const declares = listBounds(held, 'declares')
+
+  const ours = [...one.declares.matchAll(/\bid: '([^']+)'/g)].map((found) => found[1])
+  const mine =
+    declares !== undefined &&
+    (holdsRow(held, declares, one.id) || ours.some((id) => id !== undefined && holdsRow(held, declares, id)))
+
+  const installed = (at: string): boolean => at.startsWith('node_modules/') && isOurs(at.split('/').slice(1, 3).join('/'))
+
+  const pathIn = (source: string): string | undefined => {
+    const listed = `const HELD = {\n  declares: [\n${source}\n  ],\n}\n`
+    const span = listBounds(listed, 'declares')
+    return span === undefined ? undefined : rowsIn(listed, span)[0]?.at
+  }
+
+  const clashes: { readonly id: string; readonly yours: string; readonly theirs: string }[] = []
+
+  for (const write of one.writes) {
+    const at = join(dir, write.file)
+    if (!existsSync(at)) continue
+    const there = readFileSync(at, 'utf8')
+    for (const list of LISTS) {
+      const ships = listBounds(write.source, list)
+      const where = listBounds(there, list)
+      if (ships === undefined || where === undefined) continue
+      const standing = rowsIn(there, where)
+      for (const row of rowsIn(write.source, ships)) {
+        const held = standing.find((each) => each.id === row.id)
+        if (held?.at === undefined || row.at === undefined || held.at === row.at) continue
+        if (installed(held.at)) continue
+        clashes.push({ id: row.id, yours: held.at, theirs: row.at })
+      }
+    }
+  }
+
+  for (const row of one.rows ?? []) {
+    const target = join(dir, row.into)
+    if (!existsSync(target)) continue
+    const text = readFileSync(target, 'utf8')
+    const where = listBounds(text, row.list)
+    if (where === undefined) continue
+    const held = rowsIn(text, where).find((each) => each.id === row.id)
+    const theirs = pathIn(row.source)
+    if (held?.at === undefined || theirs === undefined || held.at === theirs) continue
+    if (installed(held.at)) continue
+    clashes.push({ id: row.id, yours: held.at, theirs })
+  }
+
+  if (clashes.length > 0) {
+    throw new Error(
+      `${name} ships rows this tree already declares under the same names, pointing at different files:\n` +
+        clashes.map((one) => `  ${one.id} — you declare ${one.yours}, this package ships ${one.theirs}`).join('\n') +
+        '\nA name means one thing in a tree, so these cannot both stand. Give yours another name: declare it ' +
+        'under the new name with `thread create meta add` FIRST, and only then take the old row out with ' +
+        '`thread create meta remove`. In that order a refusal costs nothing. The other way round, a remove ' +
+        'that works followed by an add that refuses leaves your file declared by nobody. Nothing has been ' +
+        'written here.',
+    )
+  }
+
+  for (const write of one.writes) {
+    const at = join(dir, write.file)
+    if (existsSync(at) && !mine) throw new TakenFileError(name, `${TREE}/${write.file}`)
+    if (!existsSync(at)) {
+      plan.set(at, write.source)
+      continue
+    }
+    const there = readFileSync(at, 'utf8')
+    let next = reconciled(there, write.source, STATED)
+
+    const shipped = SHAPE.exec(write.source)?.[0]
+    const standing = SHAPE.exec(next)?.[0]
+    if (shipped !== undefined && standing !== undefined && shipped !== standing) {
+      next = next.replace(standing, shipped)
+      reshaped.push(write.file)
+    }
+
+    for (const list of LISTS) {
+      const ships = listBounds(write.source, list)
+      for (const row of ships === undefined ? [] : rowsIn(write.source, ships)) {
+        const body = row.source.trim().replace(/,$/, '')
+        const where = listBounds(next, list)
+        if (where === undefined) break
+        if (next.slice(where.open, where.close).includes(body)) continue
+        const without = holdsRow(next, where, row.id) ? withoutRow(next, where, row.id) : next
+        const bounds = listBounds(without, list)
+        if (bounds === undefined) break
+        next = withRow(without, bounds, row.source)
+      }
+    }
+
+    if (next !== there) plan.set(at, next)
+  }
+
+  if (declares === undefined) {
+    const ends = held.lastIndexOf('\n}')
+    plan.set(root, `${held.slice(0, ends)}\n  declares: [\n${one.declares}\n  ],${held.slice(ends)}`)
+  } else {
+
+    const listed = `const HELD = {\n  declares: [\n${one.declares}\n  ],\n}\n`
+    const span = listBounds(listed, 'declares')
+    for (const meta of span === undefined ? [] : rowsIn(listed, span)) {
+      const text = plan.get(root) ?? held
+      const where = listBounds(text, 'declares')
+      if (where === undefined) break
+      const already = rowsIn(text, where).find((row) => row.id === meta.id)
+      if (already !== undefined && already.source.trim() === meta.source.trim()) continue
+      const without = already === undefined ? text : withoutRow(text, where, meta.id)
+      const bounds = listBounds(without, 'declares')
+      if (bounds !== undefined) plan.set(root, withRow(without, bounds, meta.source))
+    }
+  }
+
+  const today = rooted(into)
+  const owns = listBounds(today, 'declares')
+  for (const grown of owns === undefined ? [] : rowsIn(today, owns)) {
+    const text = plan.get(root) ?? readFileSync(root, 'utf8')
+    const where = listBounds(text, 'declares')
+    if (where === undefined) break
+    if (holdsRow(text, where, grown.id)) continue
+    plan.set(root, withRow(text, where, grown.source))
+    noticed.push(grown.id)
+  }
+
+  const atRoot = plan.get(root) ?? readFileSync(root, 'utf8')
+  const rootList = listBounds(atRoot, 'declares')
+  const holds = new Set(rootList === undefined ? [] : rowsIn(atRoot, rootList).map((row) => row.id))
+  for (const row of one.rows ?? []) {
+    const coined = /by:\s*'thread create ([a-z0-9_-]+)'/.exec(row.source)?.[1]
+    if (coined !== undefined && holds.has(coined)) {
+
+      const waiting = (one.rows ?? []).filter((each) => {
+        const at = join(dir, each.into)
+        if (!existsSync(at)) return false
+        const text = plan.get(at) ?? readFileSync(at, 'utf8')
+        const where = listBounds(text, each.list)
+        if (where === undefined) return false
+        return !text.slice(where.open, where.close).includes(each.source.trim().replace(/,$/, ''))
+      }).length
+      const withdrawing = (one.retires ?? []).filter((gone) => {
+        const at = join(dir, gone.into)
+        if (!existsSync(at)) return false
+        const text = plan.get(at) ?? readFileSync(at, 'utf8')
+        const where = listBounds(text, gone.list)
+        return where !== undefined && holdsRow(text, where, gone.id)
+      }).length
+
+      throw new Error(
+        `${name} brings a noun called \`${coined}\`, and this tree already declares something by that name. One ` +
+          `word, one meaning: if this attached, \`thread create ${coined}\` would run the package's command and the ` +
+          `thing you declared would be reachable only by its mark.\n\n` +
+          `Take yours out with \`thread create meta remove ${coined}\` — it refuses if anything is declared under it, ` +
+          `so read it first with \`thread create meta\` and move whatever it governs. Then attach again. ` +
+          `Nothing was written.\n\n` +
+
+          `A refusal here names a command you can actually run. If the one above does not fit what you are trying ` +
+          `to do, that is a gap in this framework rather than something to work around — say so.` +
+          (waiting + withdrawing === 0
+            ? ''
+            : `\n\nAn attach is all or nothing, so this is also holding back everything else ${name} would have ` +
+              `delivered: ${String(waiting)} row(s) this tree does not hold at the version installed` +
+              `${withdrawing === 0 ? '' : ` and ${String(withdrawing)} it has withdrawn`}. None of that arrives until the ` +
+              `collision above is cleared, and nothing else will tell you — \`npm install\` will go on reporting this ` +
+              `tree current.`),
+      )
+    }
+  }
+
+  for (const row of one.rows ?? []) {
+    const target = join(dir, row.into)
+
+    if (!existsSync(target) && !plan.has(target)) {
+      throw new UnattachableError(name, `wants a row in ${row.into}, which is not here`)
+    }
+    const text = plan.get(target) ?? readFileSync(target, 'utf8')
+    const where = listBounds(text, row.list)
+    if (where === undefined) throw new UnattachableError(name, `wants a row in \`${row.list}\`, which ${row.into} does not export`)
+
+    if (text.slice(where.open, where.close).includes(row.source)) continue
+
+    const held = holdsRow(text, where, row.id) ? withoutRow(text, where, row.id) : text
+    const bounds = listBounds(held, row.list)
+    if (bounds === undefined) throw new UnattachableError(name, `wants a row in \`${row.list}\`, which ${row.into} does not export`)
+    plan.set(target, withRow(held, bounds, row.source))
+  }
+
+  for (const gone of one.retires ?? []) {
+    const shipped = (one.rows ?? []).find(
+      (row) => row.into === gone.into && row.list === gone.list && row.id === gone.id,
+    )
+    if (shipped !== undefined) {
+      throw new UnattachableError(
+        name,
+        `both ships and retires \`${gone.id}\` in ${gone.into}, so attaching it would add and remove one row`,
+      )
+    }
+
+    if (gone.made !== undefined) {
+      const byproduct = join(into, gone.made)
+      if (existsSync(byproduct)) {
+        rmSync(byproduct)
+        retired.push(`${gone.made} — the file \`${gone.id}\` derived, which nothing writes now`)
+      }
+    }
+
+    const target = join(dir, gone.into)
+    if (!existsSync(target) && !plan.has(target)) continue
+    const text = plan.get(target) ?? readFileSync(target, 'utf8')
+    const where = listBounds(text, gone.list)
+    if (where === undefined || !holdsRow(text, where, gone.id)) continue
+    plan.set(target, withoutRow(text, where, gone.id))
+    retired.push(`${gone.into}: ${gone.id} — ${gone.why}`)
+  }
+
+  if (one.scripts !== undefined) {
+    const manifest = join(into, 'package.json')
+    const held = readFileSync(manifest, 'utf8')
+    const parsed = JSON.parse(held) as Record<string, unknown> & { scripts?: Record<string, string> }
+    const scripts = { ...parsed.scripts }
+    let moved = false
+    for (const [name, runs] of Object.entries(one.scripts)) {
+      if (scripts[name] === runs) continue
+      scripts[name] = runs
+      moved = true
+    }
+    if (moved) plan.set(manifest, `${JSON.stringify({ ...parsed, scripts }, null, 2)}\n`)
+  }
+
+  if (one.needs !== undefined) {
+    const manifest = join(into, 'package.json')
+
+    const held = plan.get(manifest) ?? readFileSync(manifest, 'utf8')
+    const parsed = JSON.parse(held) as Record<string, unknown> & { dependencies?: Record<string, string> }
+    const needs = { ...parsed.dependencies }
+    const added: string[] = []
+    for (const [name, at] of Object.entries(one.needs)) {
+      if (needs[name] !== undefined) continue
+      needs[name] = at
+      added.push(name)
+    }
+    if (added.length > 0) {
+      plan.set(manifest, `${JSON.stringify({ ...parsed, dependencies: needs }, null, 2)}\n`)
+      stdout.write(`thread: added ${added.join(', ')} to dependencies — run \`npm install\` to fetch ${added.length === 1 ? 'it' : 'them'}\n`)
+    }
+  }
+
+  if (one.ignores !== undefined && one.ignores.length > 0) {
+    const at = join(into, '.gitignore')
+    const had = existsSync(at) ? readFileSync(at, 'utf8') : ''
+    const lines = had.split('\n').map((line) => line.trim())
+    const adding = one.ignores.filter((path) => !lines.includes(path))
+    if (adding.length > 0) {
+      plan.set(at, `${had === '' ? '' : had.replace(/\n*$/, '\n')}${adding.join('\n')}\n`)
+      stdout.write(`thread: ignoring ${adding.join(', ')} — written by this framework, not declared by your tree\n`)
+    }
+  }
+
+  for (const [path, text] of plan) {
+    writeFileSync(path, text, 'utf8')
+    touched.add(relative(into, path))
+  }
+
+  for (const line of retired) stdout.write(`thread: retired ${line}\n`)
+  for (const file of reshaped) stdout.write(`thread: reshaped ${file} — what a row may state has changed\n`)
+  for (const id of noticed) stdout.write(`thread: declared ${id} — a file this app grew after \`thread init\` ran\n`)
+
+  return [...touched].sort()
+}
+
+async function dependents(into: string, name: string): Promise<readonly string[]> {
+  const root = readFileSync(join(resolve(into, TREE), ROOT), 'utf8')
+  const manifest = JSON.parse(readFileSync(join(into, 'package.json'), 'utf8')) as {
+    dependencies?: Record<string, string>
+    devDependencies?: Record<string, string>
+  }
+  const bounds = listBounds(root, 'declares')
+  if (bounds === undefined) return []
+  const found: string[] = []
+  for (const other of [...Object.keys(manifest.dependencies ?? {}), ...Object.keys(manifest.devDependencies ?? {})]) {
+    if (other === name) continue
+    let held: Attaching
+    try {
+      held = await attaching(into, other)
+    } catch {
+      continue
+    }
+    if (holdsRow(root, bounds, held.id) && (held.attaches ?? []).includes(name)) found.push(other)
+  }
+  return found.sort()
+}
+
+export async function detach(into: string, name: string): Promise<readonly string[]> {
+  const dir = resolve(into, TREE)
+  const root = join(dir, ROOT)
+  if (!existsSync(root)) throw new UnthreadedError()
+
+  const of = await dependents(into, name)
+  if (of.length > 0) throw new StillADependencyError(name, of)
+
+  const one = await attaching(into, name)
+
+  const owned = new Set((one.rows ?? []).map((row) => row.id))
+  const theirs: string[] = []
+  for (const write of one.writes) {
+    const at = join(dir, write.file)
+    if (!existsSync(at)) continue
+    const text = readFileSync(at, 'utf8')
+    for (const list of [...LISTS, MEMBERS]) {
+      const where = listBounds(text, list)
+      if (where === undefined) continue
+      for (const row of rowsIn(text, where)) if (!owned.has(row.id)) theirs.push(row.id)
+    }
+  }
+  if (theirs.length > 0) throw new StillDeclaredError(name, theirs)
+
+  const touched = new Set<string>()
+
+  for (const row of one.rows ?? []) {
+    const target = join(dir, row.into)
+    if (!existsSync(target)) continue
+    edit(target, (text) => {
+      const where = listBounds(text, row.list)
+      return where === undefined ? text : withoutRow(text, where, row.id)
+    }, touched, into)
+  }
+
+  edit(root, (text) => {
+    const where = listBounds(text, 'declares')
+    return where === undefined ? text : withoutRow(text, where, one.id)
+  }, touched, into)
+
+  for (const write of one.writes) {
+    const at = join(dir, write.file)
+    if (!existsSync(at)) continue
+    const text = readFileSync(at, 'utf8')
+    const kept = [...LISTS, MEMBERS].some((list) => {
+      const where = listBounds(text, list)
+      return where !== undefined && rowsIn(text, where).length > 0
+    })
+    if (kept) continue
+    rmSync(at)
+    touched.add(relative(into, at))
+  }
+
+  return [...touched].sort()
+}
+
+const DESCRIBES =
+  'The package every tree installs first: the descent, the CLI, and the makers and generators that used to be separate packages.'
+
+const CORE_SOURCE = `import type { Threaded } from '../core/thread.ts'
+
+export const CORE: Threaded = {
+  id: 'core',
+  at: '_threads/core.ts',
+  describes: ${quoted(DESCRIBES)},
+  version: 1,
+  declares: [],
+}
+
+export const GENERATORS: readonly Threaded[] = []
+`
+
+const SEEDED = {
+  attaches: ['@prestack/thread/derivation/attach', '@prestack/thread/integrations/attach', '@prestack/thread/integrity/attach', '@prestack/thread/knowledge/attach', '@prestack/thread/operations/attach'] as const,
+  id: 'core',
+  declares: [
+    '    {',
+    '      id: \'core\',',
+    '      at: \'_threads/core.ts\',',
+    '      describes: \'The package every tree installs first: the descent, the CLI, and the makers and generators that used to be separate packages.\',',
+    '      version: 1,',
+    '    },',
+  ].join('\n'),
+}
+
+const SHIPPED: readonly { readonly into: string; readonly list: string; readonly id: string; readonly source: string }[] = [
+]
+export const ATTACH: Attaching = {
+  attaches: SEEDED.attaches,
+  id: SEEDED.id,
+  declares: SEEDED.declares,
+  writes: [{ file: 'core.ts', source: CORE_SOURCE }],
+  rows: SHIPPED,
+}

package/dist/core/chain.js

@@ -65,12 +65,19 @@ export function batched(at, commands, within) {
         held = [];
     }
     const orphaned = held.join('\n').trim();
+    const died = out.error !== undefined
+        ? ` The runner itself failed to start or was stopped: ${out.error.message}.`
+        : out.signal !== null && out.signal !== undefined
+            ? ` The runner was killed by ${out.signal}, so everything after the command it was running is unreported rather than refused.`
+            : found.size === 0 && out.status !== 0
+                ? ` The runner exited ${String(out.status)} having reported nothing, so it died before the first command finished.`
+                : '';
     let firstUnreached = true;
     return commands.map((one) => {
         const has = found.get(one);
         if (has !== undefined)
             return has;
-        const why = `settle: the runner never reported on \`${one}\`, so it was not run and is not settled.`;
+        const why = `settle: the runner never reported on \`${one}\`, so it was not run and is not settled.${died}`;
         const said = firstUnreached && orphaned !== '' ? `${orphaned}\n${why}` : why;
         firstUnreached = false;
         return { command: one, ok: false, said };