@prestack/thread 0.0.1

package/dist/core/asking.js

@@ -0,0 +1,1109 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative } from 'node:path';
+import { argv, env, exit, stderr, stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline';
+import { pathToFileURL } from 'node:url';
+import { CONSTRAINTS } from "../integrity/constraint.js";
+import { LISTS, descend, listFields, listShape, shapeFields, shapesNamed } from "./descend.js";
+import { quoted } from "./rows.js";
+const RECEIPTS = join(tmpdir(), 'thread-create');
+export const RECEIPT = '--receipt';
+export const ENDS = '.';
+export const FROM = '--from';
+export const CHAINED = '--chained';
+export const BODY = 'body';
+export const WRITES = 'writes';
+export const asFlag = (key) => `--${key}`;
+export function refuse(because) {
+    stderr.write(`create: ${because}\n`);
+    exit(1);
+}
+export function slug(one) {
+    return one
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+export function within(root, path) {
+    return relative(root, path).split('\\').join('/');
+}
+const NAMED = /^([a-z][A-Za-z0-9_.-]*):[ \t]?(.*)$/;
+export function parsed(text) {
+    const lines = text.split('\n');
+    const found = [];
+    for (let at = 0; at < lines.length; at += 1) {
+        const line = lines[at] ?? '';
+        if (line.trim() === '' || line.trimStart().startsWith('#'))
+            continue;
+        const held = NAMED.exec(line);
+        if (held === null) {
+            refuse(`line ${String(at + 1)} is neither blank nor an answer: ${JSON.stringify(line.slice(0, 60))}. ` +
+                'Every answer is written `name: value`, and a body is written under `body:` and ended by a line ' +
+                `holding only ${ENDS}.`);
+        }
+        const key = held[1] ?? '';
+        if (key !== 'body') {
+            found.push({ at: at + 1, key, value: (held[2] ?? '').trim() });
+            continue;
+        }
+        const body = [];
+        const beside = held[2] ?? '';
+        if (beside.trim() !== '')
+            body.push(beside);
+        let shut = false;
+        for (at += 1; at < lines.length; at += 1) {
+            if ((lines[at] ?? '').trim() === ENDS) {
+                shut = true;
+                break;
+            }
+            body.push(lines[at] ?? '');
+        }
+        if (!shut) {
+            refuse(`the \`body:\` opened on line ${String(found.length === 0 ? 1 : at)} is never closed — a body ends at a ` +
+                `line holding only ${ENDS}, and this one runs to the end of the input.`);
+        }
+        found.push({ at: at + 1, key, value: body.join('\n').trim() });
+    }
+    return found;
+}
+export function scoped(given, opens) {
+    const own = [];
+    const each = [];
+    const lists = new Set(LISTS);
+    let mine = false;
+    for (const one of given) {
+        if (one.key === opens) {
+            each.push([one]);
+            mine = true;
+            continue;
+        }
+        if (lists.has(one.key)) {
+            mine = false;
+            continue;
+        }
+        if (mine)
+            (each[each.length - 1] ?? []).push(one);
+        else if (each.length === 0)
+            own.push(one);
+    }
+    return { own, each };
+}
+const locate = (one) => one.at > 0 ? `line ${String(one.at)}` : `\`--${one.key}\``;
+let meanings;
+function coined(word) {
+    if (meanings === undefined) {
+        const found = new Map();
+        try {
+            for (const [id, held] of descend().coined) {
+                const first = held.said[0];
+                if (first !== undefined && first !== '')
+                    found.set(id, first);
+            }
+        }
+        catch {
+            found.clear();
+        }
+        meanings = found;
+    }
+    return meanings.get(word);
+}
+export function asksOf(noun, shape, said, computed) {
+    const fields = typeof shape === 'string' ? shapeFields(shape).map((one) => ({ ...one, boolean: false })) : shape;
+    if (fields.length === 0) {
+        refuse(`nothing installed here states what a ${noun} is made of, so \`thread create ${noun}\` has no questions to ` +
+            `ask. It reads that from the shape a ${noun} is declared with rather than from a list kept beside it. ` +
+            'Run `npx thread attach` to see whether the package that states it is taken on.');
+    }
+    const spoken = { ...said };
+    for (const one of fields) {
+        if (spoken[one.name] !== undefined || computed.includes(one.name))
+            continue;
+        const meaning = coined(one.name) ?? (one.guide === '' ? undefined : one.guide);
+        if (meaning === undefined)
+            continue;
+        spoken[one.name] = { guide: meaning };
+    }
+    const mute = fields
+        .filter((one) => one.required && !computed.includes(one.name) && spoken[one.name] === undefined)
+        .map((one) => one.name);
+    if (mute.length > 0) {
+        const one = mute.length === 1;
+        refuse(`every ${noun} states ${mute.join(', ')}, and \`thread create ${noun}\` never asks for ${one ? 'it' : 'them'}. ` +
+            `It would write a ${noun} with no ${mute.join(' and no ')}, and tell you it worked. ` +
+            `Give ${one ? 'it' : 'each'} a sentence where this command lists what it asks, or name ${one ? 'it' : 'them'} ` +
+            'as something the command fills in.');
+    }
+    return Object.keys(spoken).map((one) => {
+        const told = spoken[one];
+        const known = fields.find((each) => each.name === one);
+        const spare = told.optional ?? (known !== undefined && !known.required);
+        return {
+            at: one,
+            guide: known?.boolean === true ? `${told.guide} — yes or no` : told.guide,
+            ...(told.asks === undefined ? {} : { asks: told.asks }),
+            ...(spare ? { optional: true } : {}),
+            ...(known?.list === true ? { list: true } : {}),
+            ...(known?.map === true ? { map: true } : {}),
+            ...(known?.boolean === true ? { boolean: true } : {}),
+            ...(known?.worded === true ? { worded: true } : {}),
+        };
+    });
+}
+export const named = (all) => all.map((one) => one.at);
+export const prompted = (one) => one.asks ?? `${one.at} — ${one.guide}${one.optional === true ? ', or blank' : ''}: `;
+export const mapped = (one, said) => one.map === true && !(one.worded === true && !said.includes('='));
+export const CARRIES = ['cites', 'requires', 'takes', 'by', 'runs'];
+export function ownAnswers(all) {
+    const opens = new Set(LISTS);
+    const at = all.findIndex((one) => opens.has(one.key));
+    return at === -1 ? all : all.slice(0, at);
+}
+export async function stating(asks, all, piped, ask, line, settled) {
+    const own = ownAnswers(all);
+    const skip = new Set([...settled, ...LISTS]);
+    const stated = [];
+    for (const one of asks) {
+        if (skip.has(one.at))
+            continue;
+        const given = (piped ? (answer(own, one.at) ?? '') : await ask(one.at, prompted(one))).trim();
+        if (given === '')
+            continue;
+        stated.push({ field: one.at, said: given, list: one.list === true, map: one.map === true, boolean: one.boolean === true, worded: one.worded === true });
+    }
+    if (piped)
+        return { stated, kids: childrenIn(all) };
+    const kids = new Map();
+    for (const list of LISTS) {
+        if (!asks.some((one) => one.at === list))
+            continue;
+        const found = await children(list, all, ask, line);
+        if (found.length > 0)
+            kids.set(list, found);
+    }
+    return { stated, kids };
+}
+export function arrayValue(pad, key, said, found) {
+    if (found === undefined || found.length === 0)
+        return asList(said);
+    const lines = rowLines(pad, [], new Map([[key, found]]));
+    return ['[', ...lines.slice(1, -1), `${pad}]`].join('\n');
+}
+const BARE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const NUMBER = /^-?\d+(?:\.\d+)?$/;
+const nested = (held) => {
+    const pairs = Object.entries(held).map(([key, value]) => {
+        const name = BARE.test(key) ? key : quoted(key);
+        if (typeof value === 'object' && value !== null)
+            return `${name}: ${nested(value)}`;
+        const said = String(value);
+        return `${name}: ${NUMBER.test(said) ? said : quoted(said)}`;
+    });
+    return pairs.length === 0 ? '{}' : `{ ${pairs.join(', ')} }`;
+};
+export const asMap = (said) => {
+    const held = {};
+    for (const one of said.split(',').map((each) => each.trim()).filter((each) => each !== '')) {
+        const at = one.indexOf('=');
+        if (at < 1) {
+            refuse(`\`${one}\` is one entry of a name-and-value field, and it states no value. Write each one as ` +
+                '`name=value`, separated by commas — `core=*` says that package at any version, and a dot in the name ' +
+                'nests it: `dark.background=colour-surface`. Nothing was written.');
+        }
+        const path = one.slice(0, at).trim().split('.');
+        const last = path[path.length - 1] ?? '';
+        let into = held;
+        for (const step of path.slice(0, -1)) {
+            const next = into[step];
+            if (next !== undefined && (typeof next !== 'object' || next === null)) {
+                refuse(`\`${one}\` nests under \`${step}\`, and \`${step}\` is already given a value of its own. One or the other. Nothing was written.`);
+            }
+            if (next === undefined)
+                into[step] = {};
+            into = into[step];
+        }
+        if (typeof into[last] === 'object' && into[last] !== null) {
+            refuse(`\`${one}\` gives \`${last}\` a value, and entries already nest under it. One or the other. Nothing was written.`);
+        }
+        into[last] = one.slice(at + 1).trim();
+    }
+    return nested(held);
+};
+export function gathered(all, fields) {
+    const maps = new Set(fields.filter((one) => one.map).map((one) => one.name));
+    const entries = new Map();
+    for (const one of all) {
+        const dot = one.key.indexOf('.');
+        if (dot === -1 || !maps.has(one.key.slice(0, dot)))
+            continue;
+        const head = one.key.slice(0, dot);
+        const held = entries.get(head) ?? { at: one.at, parts: [] };
+        held.parts.push(`${one.key.slice(dot + 1)}=${one.value}`);
+        entries.set(head, held);
+    }
+    const written = new Set();
+    const out = [];
+    for (const one of all) {
+        const dot = one.key.indexOf('.');
+        const head = dot === -1 ? one.key : one.key.slice(0, dot);
+        if (dot === -1 || !entries.has(head)) {
+            out.push(one);
+            continue;
+        }
+        if (written.has(head))
+            continue;
+        written.add(head);
+        const held = entries.get(head);
+        out.push({ at: held?.at ?? one.at, key: head, value: (held?.parts ?? []).join(', ') });
+    }
+    return out;
+}
+const asList = (said) => `[${said
+    .split(',')
+    .map((one) => one.trim())
+    .filter((one) => one !== '')
+    .map(quoted)
+    .join(', ')}]`;
+export const asBoolean = (said) => {
+    const word = said.trim().toLowerCase();
+    if (word === 'yes' || word === 'y' || word === 'true')
+        return 'true';
+    if (word === 'no' || word === 'n' || word === 'false')
+        return 'false';
+    refuse(`\`${said}\` is not an answer to a yes-or-no field. Say yes or no. Nothing was written.`);
+};
+export function rowLines(pad, stated, kids) {
+    const kid = (one) => [
+        `${pad}  {`,
+        `${pad}    id: ${quoted(one.id)},`,
+        `${pad}    at: ${quoted(one.at)},`,
+        `${pad}    describes: ${quoted(one.describes)},`,
+        ...(one.by === undefined || one.by === '' ? [] : [`${pad}    by: ${quoted(one.by)},`]),
+        ...(one.runs === undefined || one.runs === '' ? [] : [`${pad}    runs: ${quoted(one.runs)},`]),
+        `${pad}    version: 1,`,
+        `${pad}  },`,
+    ];
+    return [
+        ...stated.map((one) => `${pad}${one.field}: ${mapped(one, one.said) ? asMap(one.said) : one.list ? asList(one.said) : one.boolean === true ? asBoolean(one.said) : quoted(one.said)},`),
+        ...[...kids].flatMap(([list, found]) => [`${pad}${list}: [`, ...found.flatMap(kid), `${pad}],`]),
+    ];
+}
+export function withChildren(row, lines) {
+    if (lines.length === 0)
+        return row;
+    const all = row.split('\n');
+    let at = all.length - 1;
+    while (at >= 0 && (all[at] ?? '').trim() !== '},' && (all[at] ?? '').trim() !== '}')
+        at -= 1;
+    if (at < 0) {
+        refuse('the row just written has no closing brace on a line of its own, so what it declares has nowhere to go. ' +
+            'Nothing more was written, because adding the row and dropping its children quietly is the one outcome ' +
+            'nobody could see.');
+    }
+    return [...all.slice(0, at), ...lines, ...all.slice(at)].join('\n');
+}
+export function childrenIn(all) {
+    const found = new Map();
+    for (const list of LISTS) {
+        const each = [];
+        for (const group of scoped(all, list).each) {
+            const id = (answer(group, list) ?? '').trim();
+            if (id === '')
+                continue;
+            const at = (answer(group, 'at') ?? '').trim();
+            const describes = (answer(group, 'describes') ?? '').trim();
+            if (at === '' || describes === '') {
+                refuse(`\`${list} ${id}\` names no ${at === '' ? 'file' : 'meaning'}. Every row says which file it is about and ` +
+                    'what that file is, and one missing either is a row the next person cannot act on. Nothing more was written.');
+            }
+            const body = (answer(group, BODY) ?? '').trim();
+            const writes = (answer(group, WRITES) ?? '').trim();
+            each.push({
+                id,
+                at,
+                describes,
+                ...(writes === '' ? {} : { writes }),
+                ...(list === 'declares'
+                    ? {}
+                    : { by: (answer(group, 'by') ?? '').trim(), runs: (answer(group, 'runs') ?? '').trim() }),
+                ...(body === '' ? {} : { body }),
+            });
+        }
+        if (each.length > 0)
+            found.set(list, each);
+    }
+    return found;
+}
+export const BODIED = ['declares', 'seeds'];
+export const WRITTEN = ['derives', 'seeds'];
+export function seeding(kids, root) {
+    const said = [];
+    for (const list of BODIED) {
+        for (const one of kids.get(list) ?? []) {
+            const into = join(root, one.at);
+            const there = existsSync(into);
+            if (one.body === undefined || one.body === '') {
+                said.push(there
+                    ? `${one.at} was already on disk, and the row now names it.`
+                    : `${one.at} is declared and nothing is in it yet — write it with ` +
+                        `\`${TYPED} edit ${one.at} --from <path>\`.`);
+                continue;
+            }
+            if (there) {
+                said.push(`${one.at} was already on disk, so the body you wrote was NOT put over it. Nothing was lost — ` +
+                    `\`${TYPED} read ${one.at}\` prints what is there.`);
+                continue;
+            }
+            mkdirSync(dirname(into), { recursive: true });
+            writeFileSync(into, one.body.endsWith('\n') ? one.body : `${one.body}\n`, 'utf8');
+            said.push(`wrote ${one.at} with the body you gave it.`);
+        }
+    }
+    return said;
+}
+const ASKED = {
+    declares: 'name each file a person writes that this one owns',
+    derives: 'name each file a command writes from this one, and the command that writes it',
+    seeds: 'name each file a command shapes here',
+};
+export async function children(list, all, ask, line) {
+    const written = WRITTEN.includes(list);
+    const out = [];
+    const owed = (id, at, describes) => {
+        if (at !== '' && describes !== '')
+            return;
+        refuse(`\`${list} ${id}\` names no ${at === '' ? 'file' : 'meaning'}. Every row says which file it is about and what ` +
+            'that file is, and one missing either is a row the next person cannot act on. Nothing more was written.');
+    };
+    const bodies = [
+        ...(written ? [`${asFlag(WRITES)} is the generator's own body — the code that writes the template`] : []),
+        ...(BODIED.includes(list) ? [`${asFlag(BODY)} is the body of the file itself`] : []),
+    ];
+    stdout.write(`\n  ${list} — ${ASKED[list] ?? ''}. ` +
+        (bodies.length === 0
+            ? ''
+            : `Each one takes ${bodies.length === 1 ? 'one body' : `${String(bodies.length)} bodies, and they are never the same text`}: ` +
+                `${bodies.join('; ')}. `) +
+        'A blank id ends the list.\n');
+    for (;;) {
+        const id = (await ask(list, `  ${list} — id, or blank to stop: `)).trim();
+        if (id === '')
+            break;
+        const at = (await ask('at', '    at — the file this names: ')).trim();
+        const describes = (await ask('describes', '    describes — what that file is, to somebody who has not opened it: ')).trim();
+        owed(id, at, describes);
+        const by = written ? (await ask('by', '    by — the command that writes it: ')).trim() : undefined;
+        const runs = written ? (await ask('runs', '    runs — the command that catches it drifting: ')).trim() : undefined;
+        const writes = written
+            ? await bodied(`the generator behind \`${by ?? 'that command'}\` — this is ${asFlag(WRITES)}`, '', false, all, line)
+            : undefined;
+        const body = BODIED.includes(list)
+            ? await bodied(`${at} itself — this is ${asFlag(BODY)}`, '', false, all, line)
+            : undefined;
+        out.push({
+            id,
+            at,
+            describes,
+            ...(written ? { by, runs } : {}),
+            ...(writes === undefined ? {} : { writes }),
+            ...(body === undefined ? {} : { body }),
+        });
+    }
+    return out;
+}
+export async function bodied(what, shows, piped, all, line) {
+    const from = argv[argv.indexOf(FROM) + 1];
+    if (argv.includes(FROM) && from !== undefined && !from.startsWith('-')) {
+        try {
+            return refuse(`${FROM} seeds the body out of a file, and a file is not a receipt: nothing here checked it and no descent reached it. Give the body with ${asFlag(BODY)} on the command. Nothing was written.`);
+        }
+        catch {
+            refuse(`\`${FROM} ${from}\` names a file nothing could read, so there is no body to seed and nothing was ` +
+                `written. Write it first, then run this again — or drop ${FROM} and type the body when it is asked for.`);
+        }
+    }
+    if (piped) {
+        const said = answer(all, BODY);
+        return said === undefined || said.trim() === '' ? undefined : said;
+    }
+    if (shows.trim() === '')
+        stdout.write(`  body — write what goes in ${what}.\n`);
+    else {
+        stdout.write(`  body — what a ${what} is handed looks like this:\n`);
+        for (const one of shows.split('\n'))
+            stdout.write(`    ${one}\n`);
+    }
+    stdout.write(`  write yours, then a line holding only ${ENDS}. A first line of ${ENDS} leaves it unwritten, and\n` +
+        `  \`${TYPED} trials\` reports it unproven until somebody writes it.\n` +
+        `  Or give ${FROM} <path> instead and the file at that path is what gets seeded, which is the one\n` +
+        '  form that needs no terminal.\n');
+    const held = [];
+    for (;;) {
+        const next = await line();
+        if (next === undefined || next.trim() === ENDS)
+            break;
+        held.push(next);
+    }
+    const written = held.join('\n').trim();
+    return written === '' ? undefined : written;
+}
+export function guidance(all) {
+    const width = Math.max(...all.map((one) => one.at.length)) + 3;
+    const under = ' '.repeat(width + 2);
+    return all.flatMap((one) => {
+        const lines = wrapped(one.optional === true ? `${one.guide.replace(/\.$/, '')}. Leave it blank and it is not stated` : one.guide, '');
+        return [`  ${`${one.at}:`.padEnd(width)}${lines[0] ?? ''}`, ...lines.slice(1).map((each) => `${under}${each}`)];
+    });
+}
+export function only(given, allowed, where) {
+    for (const one of ownAnswers(given)) {
+        if (CARRIES.includes(one.key) || one.key === WRITES)
+            continue;
+        if (allowed.includes(one.key))
+            continue;
+        refuse(`${locate(one)} answers \`${one.key}\`, and ${where} takes ${allowed.map((each) => `\`${each}\``).join(', ')}. ` +
+            'Nothing was written.');
+    }
+}
+export function answer(given, key) {
+    const found = given.filter((one) => one.key === key);
+    if (found.length > 1) {
+        refuse(`\`${key}\` is answered ${String(found.length)} times: ${found.map((one) => locate(one)).join(', ')}. ` +
+            'Nothing was written.');
+    }
+    const held = found[0]?.value;
+    return held === undefined ? undefined : guarded(key, held);
+}
+export function accepted(given) {
+    if (given.length === 0)
+        return 'nothing was accepted before it';
+    return `accepted so far: ${given.map((one) => `${one.key} (${locate(one)})`).join(', ')}`;
+}
+export function needed(given, key, where) {
+    const held = answer(given, key);
+    if (held === undefined || held === '') {
+        refuse(`${where} states no \`${key}\`, and it is not optional. ${accepted(given)}. Nothing was written.`);
+    }
+    return held;
+}
+export function wrapped(text, pad) {
+    const lines = [];
+    let held = '';
+    for (const word of text.split(/\s+/).filter((one) => one !== '')) {
+        if (held !== '' && `${held} ${word}`.length > 92) {
+            lines.push(`${pad}${held}`);
+            held = word;
+        }
+        else
+            held = held === '' ? word : `${held} ${word}`;
+    }
+    if (held !== '')
+        lines.push(`${pad}${held}`);
+    return lines;
+}
+export function marked(parts) {
+    return createHash('sha256').update(parts.join('\n')).digest('hex').slice(0, 6);
+}
+const citesOf = (held) => Array.isArray(held)
+    ? held.filter((one) => one !== null && typeof one === 'object' && typeof one.on === 'string' && typeof one.said === 'string')
+    : [];
+const HELD = ['holds', 'declares'];
+const NAMED_SHAPE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const rowLike = (one) => one !== null && typeof one === 'object' && typeof one.id === 'string' && typeof one.describes === 'string';
+const kinded = (shape) => shape
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase();
+const oneOf = (list) => {
+    const word = list.toLowerCase().split('_').join('-');
+    return word.endsWith('s') ? word.slice(0, -1) : word;
+};
+export async function declared(tree) {
+    const found = new Map();
+    const walked = new Set();
+    const says = new Map();
+    const parents = new Map();
+    const sheetsBy = new Map();
+    const meant = (shape, sheetAt) => {
+        if (shape === undefined)
+            return '';
+        try {
+            const named = shapesNamed();
+            for (const at of named.get(shape) ?? []) {
+                if (at === sheetAt)
+                    continue;
+                let others = 0;
+                for (const [, files] of named)
+                    if (files.includes(at))
+                        others += 1;
+                if (others !== 1)
+                    continue;
+                const told = says.get(at);
+                if (told !== undefined && told !== '')
+                    return told;
+            }
+        }
+        catch {
+            return '';
+        }
+        return '';
+    };
+    const sheet = (one) => {
+        const at = one?.at;
+        return typeof at === 'string' && at.startsWith(`${tree.name}/`) && at.endsWith('.ts') ? at : undefined;
+    };
+    const walk = async (at, top) => {
+        if (walked.has(at))
+            return;
+        walked.add(at);
+        let read;
+        try {
+            read = (await import(__rewriteRelativeImportExtension(pathToFileURL(join(tree.at, at)).href)));
+        }
+        catch {
+            return;
+        }
+        for (const [name, value] of Object.entries(read)) {
+            const node = value;
+            const lists = Array.isArray(value)
+                ? [{ list: name, rows: value }]
+                : HELD.flatMap((list) => {
+                    const rows = node?.[list];
+                    return Array.isArray(rows) ? [{ list, rows }] : [];
+                });
+            const rowed = lists.filter((one) => one.rows.every(rowLike));
+            const first = rowed[0];
+            if (first === undefined)
+                continue;
+            if (Array.isArray(value)) {
+                const noun = oneOf(name);
+                sheetsBy.set(name, new Set([...(sheetsBy.get(name) ?? []), at]));
+                if (!found.has(noun)) {
+                    found.set(noun, {
+                        at,
+                        list: name,
+                        shape: listShape(at, name),
+                        fields: listFields(at, name),
+                        describes: '',
+                        holds: first.rows.length,
+                        cites: [],
+                        top,
+                    });
+                }
+            }
+            else if (at !== within(tree.at, tree.root)) {
+                const files = typeof node?.files === 'string' && node.files !== '' ? node.files : undefined;
+                const held = files === undefined ? first : (rowed.find((one) => one.list === 'declares') ?? first);
+                const kind = listShape(at, held.list);
+                const noun = kind === undefined || (kind === 'Threaded' && files === undefined)
+                    ? undefined
+                    : kind !== 'Threaded' && NAMED_SHAPE.test(kind)
+                        ? kinded(kind)
+                        : typeof node?.id === 'string' && node.id !== ''
+                            ? node.id
+                            : undefined;
+                if (typeof noun === 'string' && noun !== '' && !found.has(noun)) {
+                    found.set(noun, {
+                        at,
+                        list: held.list,
+                        shape: kind,
+                        fields: listFields(at, held.list),
+                        describes: typeof node?.describes === 'string' ? node.describes : '',
+                        holds: held.rows.length,
+                        cites: citesOf(node?.cites),
+                        top,
+                        ...(files === undefined ? {} : { files }),
+                    });
+                }
+            }
+            for (const one of rowed.flatMap((each) => each.rows)) {
+                const where = one.at;
+                const told = one.describes;
+                if (typeof where === 'string' && typeof told === 'string' && !says.has(where))
+                    says.set(where, told);
+                const next = sheet(one);
+                if (next === undefined)
+                    continue;
+                const row = one;
+                if (!parents.has(next))
+                    parents.set(next, row);
+                await walk(next, top ?? { id: typeof row.id === 'string' ? row.id : '', describes: typeof row.describes === 'string' ? row.describes : '' });
+            }
+        }
+    };
+    await walk(within(tree.at, tree.root), undefined);
+    const out = new Map();
+    for (const [noun, one] of found) {
+        const parent = parents.get(one.at);
+        const said = typeof parent?.describes === 'string' ? parent.describes : '';
+        const owned = (sheetsBy.get(one.list)?.size ?? 0) <= 1;
+        out.set(noun, {
+            ...one,
+            describes: one.describes !== '' ? one.describes : owned && said !== '' ? said : meant(one.shape, one.at),
+            cites: one.cites.length > 0 ? one.cites : citesOf(parent?.cites),
+        });
+    }
+    return out;
+}
+export function nouns(all, verb = 'create') {
+    const found = new Map();
+    const opens = `thread ${verb} `;
+    for (const one of all) {
+        const by = one.by;
+        if (typeof by !== 'string' || !by.startsWith(opens))
+            continue;
+        const word = by.slice(opens.length).trim();
+        if (word === '' || typeof one.at !== 'string')
+            continue;
+        const already = found.get(word);
+        if (already !== undefined && already !== one.at) {
+            refuse(`two rows both state \`by: 'thread ${verb} ${word}'\` — ${already} and ${one.at} — so which one answers a ` +
+                `${word} is whichever was written first. One noun, one file.`);
+        }
+        found.set(word, one.at);
+    }
+    return found;
+}
+const spends = (root, nonce) => join(RECEIPTS, `${createHash('sha256').update(root).digest('hex').slice(0, 16)}-${nonce}.txt`);
+const stamp = (listing) => createHash('sha256').update(listing).digest('hex').slice(0, 12);
+function beingMade() {
+    const words = argv.slice(2).filter((one) => !one.startsWith('-'));
+    if (words[0] === 'create' && typeof words[1] === 'string' && words[1] !== '')
+        return words[1];
+    const file = (argv[1] ?? '').split('\\').join('/').split('/').at(-1) ?? '';
+    return file.replace(/\.[^.]+$/, '');
+}
+export const SKILLS_AT = 'thread/knowledge';
+export function skillOf(noun) {
+    return `${SKILLS_AT}/${noun}.md`;
+}
+function readTheSkill() {
+    const noun = env.THREAD_NOUN ?? beingMade();
+    if (noun === '')
+        return [];
+    return [
+        '',
+        `READ ${skillOf(noun)} BEFORE YOU WRITE ANYTHING. It is this command's own output, kept as a`,
+        'file, and it lists everything that already exists. Building a second copy of something the tree',
+        'already has is the most expensive mistake available here and it has already been made: thirteen',
+        'elements were declared in one app that every one of them already shipped.',
+        '',
+        'If that file is not there, run `npx thread skills` and it will be.',
+    ];
+}
+export function issue(root, listing) {
+    const nonce = randomBytes(6).toString('hex');
+    mkdirSync(RECEIPTS, { recursive: true });
+    writeFileSync(spends(root, nonce), `${stamp(listing)}\n`, 'utf8');
+    const said = readTheSkill();
+    if (said.length > 0)
+        stdout.write(`${said.join('\n')}\n`);
+    return nonce;
+}
+export function spend(root, listing, offered, sheet) {
+    if (offered === undefined || offered.startsWith('-')) {
+        refuse(`\`${RECEIPT}\` was handed nothing to check. Run \`thread create\` with no arguments — it lists what is ` +
+            'here and issues a receipt to hand back.');
+    }
+    const path = spends(root, offered);
+    if (!existsSync(path)) {
+        refuse(`\`${offered}\` is not a receipt this tree issued, or it has been spent already — one run per receipt. ` +
+            'Run `thread create` again and use the one it prints.');
+    }
+    let when = '';
+    try {
+        when = readFileSync(path, 'utf8').trim();
+    }
+    catch {
+        when = '';
+    }
+    process.on('exit', (code) => {
+        if (code === 0)
+            rmSync(path, { force: true });
+    });
+    if (when !== stamp(listing)) {
+        refuse(`${sheet} has changed since that receipt was issued, so what you read is not what is here. ` +
+            'Run `thread create` again.');
+    }
+}
+export function asking(held) {
+    const piped = answered();
+    const rl = piped ? undefined : createInterface({ input: stdin, output: stdout });
+    const lines = rl?.[Symbol.asyncIterator]();
+    return {
+        piped,
+        ask: async (key, question, from = held) => {
+            const already = answer(from, key);
+            if (already !== undefined)
+                return guarded(key, already);
+            if (piped)
+                return '';
+            stdout.write(question);
+            const next = await lines?.next();
+            return next === undefined || next.done === true ? '' : guarded(key, next.value.trim());
+        },
+        line: async () => {
+            const next = await lines?.next();
+            return next === undefined || next.done === true ? undefined : next.value;
+        },
+        shut: () => rl?.close(),
+    };
+}
+const ANSWERS = '--answers';
+function fromFile() {
+    const at = argv.indexOf(ANSWERS);
+    if (at === -1)
+        return undefined;
+    const path = argv[at + 1];
+    if (path === undefined || path.startsWith('-')) {
+        refuse(`${ANSWERS} needs the path of a file holding the answers, one \`name: value\` to a line.`);
+    }
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        refuse(`${ANSWERS} names ${path}, and there is no file there to read the answers from.`);
+    }
+}
+const OWN = '--own';
+const CHECK = '--check';
+function flagged() {
+    const found = [];
+    for (let at = 2; at < argv.length; at += 1) {
+        const one = argv[at] ?? '';
+        if (!one.startsWith('--') ||
+            one === RECEIPT ||
+            one === ANSWERS ||
+            one === OWN ||
+            one === CHECK ||
+            one === FROM ||
+            one === CHAINED)
+            continue;
+        const value = argv[at + 1];
+        if (value === undefined || value.startsWith('-')) {
+            refuse(`\`${one}\` was given no value — an answer given as a flag is \`${one} value\`, with the value right after it.`);
+        }
+        found.push({ at: 0, key: one.slice(2), value });
+        at += 1;
+    }
+    return found;
+}
+export function answered() {
+    return argv.includes(ANSWERS) || stdin.isTTY !== true;
+}
+export function given() {
+    const flags = flagged();
+    const fromFlag = new Set(flags.map((one) => one.key));
+    const held = fromFile();
+    if (held !== undefined)
+        return read([...flags, ...parsed(held).filter((one) => !fromFlag.has(one.key))]);
+    const text = handed();
+    if (text === undefined)
+        return read(flags);
+    return read([...flags, ...parsed(text).filter((one) => !fromFlag.has(one.key))]);
+}
+const FROM_END = '-from';
+export const FILED = (key) => `${key}${FROM_END}`;
+function read(all) {
+    return all.map((one) => {
+        if (!one.key.endsWith(FROM_END))
+            return one;
+        const key = one.key.slice(0, -FROM_END.length);
+        if (key === '')
+            return one;
+        if (all.some((each) => each.key === key)) {
+            refuse(`\`${asFlag(key)}\` and \`${asFlag(one.key)}\` both answer ${key}, and they do not have to agree. ` +
+                'Give one of them. Nothing was written.');
+        }
+        try {
+            return refuse(`${asFlag(key)}${FROM_END} takes what this writes out of a file, and a file is not a receipt: nothing here checked it and no descent reached it. Give the text on the command with ${asFlag(key)}. Nothing was written.`);
+        }
+        catch {
+            refuse(`\`${asFlag(one.key)} ${one.value}\` names a file nothing could read, so there is no ${key} to write and ` +
+                `nothing was written. Write that file first, or give the text itself with ${asFlag(key)}.`);
+        }
+    });
+}
+let stood;
+let taken = false;
+export function handed() {
+    if (taken)
+        return stood;
+    taken = true;
+    if (stdin.isTTY === true)
+        return undefined;
+    try {
+        stood = readFileSync(0, 'utf8');
+    }
+    catch {
+        stood = undefined;
+    }
+    return stood;
+}
+export const TYPED = 'npx thread';
+const folded = (said, pad, room = 92) => {
+    const out = [];
+    let line = '';
+    for (const word of said.split(/\s+/)) {
+        if (line === '')
+            line = word;
+        else if (`${line} ${word}`.length <= room)
+            line = `${line} ${word}`;
+        else {
+            out.push(line);
+            line = word;
+        }
+    }
+    if (line !== '')
+        out.push(line);
+    return out.map((one) => `${pad}${one}`);
+};
+const parented = (() => {
+    const one = CONSTRAINTS.find((each) => each.id === 'twice-parented');
+    if (one === undefined) {
+        return [
+            '',
+            'THIS PAGE CANNOT STATE THE RULE. It reads what may declare a file out of the `twice-parented`',
+            'rule, and no rule by that name ships any more. Whatever governs this now, it is not said here —',
+            `\`${TYPED} create rule\` lists every rule that does exist.`,
+        ];
+    }
+    return [
+        '',
+        'which one you pick is a rule rather than a preference, and a check refuses the tree over it:',
+        '',
+        `  ${one.id}`,
+        ...folded(`bans ${one.bans}.`, '    '),
+        ...folded(one.instead.replace(/^./, (each) => each.toUpperCase()), '    '),
+    ];
+})();
+const NEXT = {
+    declares: 'It writes the file from that, and nothing else runs. A file already on disk is left alone and the row simply names it.',
+    derives: `It writes NO file at \`at:\`, because the command in \`by:\` writes that one — which is why there is no ${asFlag(BODY)} here to give. If this tree has no command answering \`by:\`, that generator is declared first and ${asFlag(WRITES)} is what goes in it.`,
+    seeds: `TWO files come out of this and a different hand writes each, which is the whole reason there are two bodies. If this tree has no command answering \`by:\`, that generator is declared here too, so one run leaves the row, the generator and the file.`,
+};
+export const VERBS = [
+    'nothing is in this tree until a row names it, and which of three lists the row sits in says who',
+    'wrote the file. Pick the one that is true and the rest of this framework follows from it:',
+    '',
+    '  declares   a person wrote it. Exactly one row may ever declare an address, and a second is',
+    '             refused: a file with two owners has two answers for where it came from and the tree',
+    '             can give neither.',
+    '  derives    a command wrote it. Delete the file, run the command again, and the same bytes come',
+    '             back. Many rows may derive one address, because a derivation owns nothing — it states',
+    '             `by:`, the command that writes it, and `runs:`, what catches it drifting.',
+    '  seeds      a command wrote the shape and a person fills in the part no machine can supply. Many',
+    '             rows may seed one address as well, and it is proved by shape rather than by bytes,',
+    '             because half of what is on disk is your own writing.',
+    '',
+    `a file in none of them is not in this app at all — \`${TYPED} descent\` names every one it reached`,
+    'and every one it did not, and nothing undeclared is compiled in or shipped.',
+    '',
+    'and the list decides what this command does next, not just what the row says. What it does next is',
+    'ASK FOR BODIES, and there are two of them, which are never the same text and never the same file:',
+    '',
+    `  ${asFlag(BODY).padEnd(10)} the body of the file the row names. A person wrote it.`,
+    `  ${asFlag(WRITES).padEnd(10)} the body of the GENERATOR — the code that writes a template into that file.`,
+    '',
+    'give each as text on the command. Neither may be taken out of a file, because a file is not a',
+    'receipt: nothing here checked it and no descent reached it. Single-quote a body that holds quotes.',
+    '',
+    'so each list takes a different set of them, and giving one where the other belongs is the mistake',
+    'this section exists to stop:',
+    '',
+    ...LISTS.flatMap((list) => {
+        const takes = [
+            ...(WRITTEN.includes(list) ? [asFlag(WRITES)] : []),
+            ...(BODIED.includes(list) ? [asFlag(BODY)] : []),
+        ];
+        const said = folded(`takes ${takes.length === 0 ? 'no body at all' : takes.join(' and ')}. ${NEXT[list] ?? ''}`, '             ');
+        return said.map((line, at) => (at === 0 ? `  ${list.padEnd(11)}${line.trim()}` : line));
+    }),
+    ...parented,
+];
+export const grows = (sheetAt, noun) => {
+    const shaped = noun.split('-').map((one) => `${one.slice(0, 1).toUpperCase()}${one.slice(1)}`).join('');
+    return [
+        `this is also how the CLI grows. A list of rows in ${sheetAt} becomes a command: declare`,
+        `\`export const THINGS: readonly Thing[] = []\` beside what is already there and \`${TYPED} create thing\``,
+        'answers from that moment, asking for whatever a `Thing` states and writing the row into that list.',
+        '',
+        `The same is true of what you have now: \`${TYPED} create ${noun}\` exists because ${sheetAt} declares`,
+        `\`${shaped}\`. Nothing was added to a list of commands anywhere — the CLI reads what your tree says.`,
+    ];
+};
+export const VALUED = 'THREAD_VALUED';
+export function answering(noun) {
+    return [
+        ...(env[VALUED] === '1' ? [] : [...VERBS, '']),
+        'what `new` asks. Give each answer as a flag on one command and close with the receipt:',
+        '',
+        `  ${TYPED} create ${noun} new --<answer> <value> ... ${RECEIPT} <receipt>`,
+        '',
+        'Flags need no terminal, no pipe and no file, so that form works everywhere. The two others',
+        'each need something you may not have: one answer to a line on stdin needs a shell that can',
+        'redirect, and `--answers <path>` needs a way to write the file first. Use them when you have',
+        'them; the line above is the one that never depends on it.',
+        '',
+        'Where a question repeats — a list of things, each with answers of its own — there are no',
+        'separate flag names for the inner ones. Give the group\'s own flag again to begin the next,',
+        'then its answers after it, reusing the same words. They are read in the order you write them,',
+        'and everything before the first group flag belongs to the thing itself.',
+        '',
+        'the answers, in order:',
+    ];
+}
+export const CARRIED = [
+    { verb: 'read', typed: `${TYPED} read <row>`, does: 'prints every field a row states' },
+    { verb: 'edit', typed: `${TYPED} edit <row> --<field> <value>`, does: 'changes any field it was declared with' },
+    { verb: 'remove', typed: `${TYPED} edit <row> --remove`, does: 'takes the row out of the tree' },
+];
+const elsewhere = CARRIED.map((one) => `\`${one.typed}\` ${one.does}`);
+export const ELSEWHERE = [
+    'reading a row, changing one of its answers and taking it out are done in one place, whatever',
+    'declared it \u2014 name the row by its id or by the mark printed beside it above:',
+    '',
+    ...CARRIED.map((one) => `  ${one.typed.padEnd(40)}${one.does}`),
+];
+const opening = (said) => said.split(/(?<=\.)\s/)[0] ?? said;
+const article = (word) => (/^[aeiou]/.test(word) ? 'an' : 'a');
+export function taught(noun, told, commands) {
+    const one = told.get(noun);
+    const opens = [
+        [`${TYPED} read <id>`, 'the row, and the file it names'],
+        [`${TYPED} create ${noun}`, 'this list again, with a fresh receipt'],
+        ...(commands.has('thread inspect')
+            ? [[`${TYPED} inspect <word>`, 'every row whose name or sentence carries the word']]
+            : []),
+    ];
+    const top = one?.top;
+    const siblings = top === undefined
+        ? []
+        : [...told]
+            .filter(([, each]) => each.top?.id === top.id && each.describes !== '')
+            .sort(([left], [right]) => (left < right ? -1 : 1));
+    const pad = Math.max(0, ...siblings.map(([word]) => word.length)) + 3;
+    return [
+        'DO NOT CREATE WHAT ALREADY EXISTS. Everything listed below is declared and yours to use. A thing',
+        'you cannot find is usually one of these under a word you have not met \u2014 read the sentences, not',
+        'the names.',
+        '',
+        'IF NOTHING FITS, SAY SO AND STOP. Do not coin a name: a name is a meaning, and a meaning is',
+        'declared rather than invented. Being told the list is short a thing is a useful answer.',
+        '',
+        'NOW GO AND OPEN ONE. A sentence is a summary, and every expensive mistake here was made from a',
+        'summary. These print the real thing, and none of them writes anything:',
+        '',
+        ...opens.map(([said, does]) => `  ${said.padEnd(30)}${does}`),
+        '',
+        ...(one === undefined || one.describes === ''
+            ? []
+            : [
+                `what ${article(noun)} ${noun} is:`,
+                '',
+                ...wrapped(one.describes, '  '),
+                ...one.cites.flatMap((said) => ['', ...wrapped(`said on ${said.on}: "${said.said}"`, '  ')]),
+                '',
+            ]),
+        ...(top === undefined || siblings.length < 2
+            ? []
+            : [
+                `${top.id} \u2014 ${opening(top.describes)}`,
+                'what it makes, and what each one is. Pick the one that is true before declaring anything:',
+                '',
+                ...siblings.flatMap(([word, each]) => {
+                    const lines = wrapped(opening(each.describes), '');
+                    return [`  ${word.padEnd(pad)}${lines[0] ?? ''}`, ...lines.slice(1).map((line) => `${' '.repeat(pad + 2)}${line}`)];
+                }),
+                '',
+            ]),
+    ];
+}
+export function reminded(noun) {
+    const lists = noun === undefined || noun === 'meta'
+        ? `\`${TYPED} create\` lists what this tree makes, and any noun run bare lists what exists, each with its sentence`
+        : `\`${TYPED} create ${noun}\` lists what exists, each with its sentence`;
+    return `thread: before the next thing, ${lists}. Do not create what already exists, and if nothing fits, say so and stop.`;
+}
+export function wordsIn(offered) {
+    const values = new Set([argv[argv.indexOf(RECEIPT) + 1], argv[argv.indexOf(ANSWERS) + 1], ...flagged().map((one) => one.value)]);
+    const words = argv.slice(2).filter((one) => !one.startsWith('-') && !values.has(one));
+    const first = words[0];
+    if (offered.length === 0 || first === undefined || offered.includes(first))
+        return words;
+    const carried = CARRIED.find((one) => one.verb === first);
+    if (carried !== undefined) {
+        refuse(`\`${first}\` is not a word this command answers, because every row in this tree has it and it is ` +
+            `answered in one place rather than once per thing. \`${carried.typed}\` ${carried.does}, whatever ` +
+            'declared it, and it finds the row by its id or by the mark printed beside it. Nothing was written, ' +
+            'and nothing was read.');
+    }
+    refuse(`\`${first}\` is not one of the things this command does. It does: ${offered.join(', ')}. ` +
+        `Reading, changing and removing a row are done elsewhere, because they reach every row rather than ` +
+        `only this one's: ${elsewhere.join('; ')}. ` +
+        'Run it with none of those to see what already exists and exactly what each of them asks for. ' +
+        'Nothing was written, and nothing was read.');
+}
+const ANNOUNCED = [
+    { what: 'a Stripe secret key', pattern: /\bsk_(?:live|test)_[A-Za-z0-9]{16,}/ },
+    { what: 'a Stripe restricted key', pattern: /\brk_(?:live|test)_[A-Za-z0-9]{16,}/ },
+    { what: 'a GitHub token', pattern: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{30,}/ },
+    { what: 'a GitHub personal access token', pattern: /\bgithub_pat_[A-Za-z0-9_]{30,}/ },
+    { what: 'an AWS access key id', pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/ },
+    { what: 'a Slack token', pattern: /\bxox[abposr]-[A-Za-z0-9-]{10,}/ },
+    { what: 'an OpenAI key', pattern: /\bsk-[A-Za-z0-9_-]{32,}/ },
+    { what: 'an Anthropic key', pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}/ },
+    { what: 'a Google API key', pattern: /\bAIza[A-Za-z0-9_-]{35}\b/ },
+    { what: 'a JSON web token', pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/ },
+    { what: 'a private key', pattern: /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/ },
+    { what: 'a password inside a connection string', pattern: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s:/@]{6,}@/ },
+];
+const ASSIGNED = /\b(?:secret|password|passwd|api_?key|apikey|access_?token|auth_?token|private_?key|client_?secret|credential)s?\b\s*[:=]\s*(['"`])([^'"`\n]{16,})\1/gi;
+const MIXED = /^(?=.*[a-z])(?=.*[A-Z0-9])[A-Za-z0-9_+/=.-]{16,}$/;
+const NOT = [
+    /^(?:sec|pub)_[a-z0-9_]+$/,
+    /^\$\{/,
+    /^(?:x{3,}|X{3,}|\.{3,}|<[^>]+>|change[-_]?me|your[-_]|example|placeholder|redacted|todo|test|dummy|sample|fake|dGhpcyBpcyBub3QgYSBzZWNyZXQ)/i,
+];
+function guarded(key, value) {
+    const carried = credentialIn(value);
+    if (carried !== undefined) {
+        refuse(`\`${key}\` holds ${carried}. A credential is never typed into a declaration — not in a describes, not ` +
+            'anywhere but a secret. Declare it with `thread create secret`, name it where the thing that needs it ' +
+            'states what it requires, and it is resolved through the vault at the moment it is used and never ' +
+            'written down. Nothing was written.');
+    }
+    const address = ADDRESS.exec(value);
+    if (address !== null) {
+        refuse(`\`${key}\` holds the address \`${address[0]}\`. An address is a secret here, not a sentence — the same ` +
+            'thing behind another host is another environment, and one written into a declaration is one nothing ' +
+            'can point elsewhere. Declare it with `thread create secret` and name it where the thing that needs it ' +
+            'states what it requires. Nothing was written.');
+    }
+    return value;
+}
+const ADDRESS = /\b[a-z][a-z0-9+.-]*:\/\/[^\s'"`)]+/i;
+export function credentialIn(text) {
+    for (const one of ANNOUNCED) {
+        if (one.pattern.test(text))
+            return one.what;
+    }
+    for (const found of text.matchAll(ASSIGNED)) {
+        const value = found[2] ?? '';
+        if (NOT.some((each) => each.test(value)))
+            continue;
+        if (!MIXED.test(value))
+            continue;
+        return `a ${(found[0].split(/[:=]/)[0] ?? '').trim()} written down as a literal ${String(value.length)} characters long`;
+    }
+    return undefined;
+}