@prestack/thread 0.0.1

package/dist/core/generators/meta.js

@@ -0,0 +1,823 @@
+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 { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { argv, env, stdout } from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { exit } from "../invoked.js";
+import { BODY, RECEIPT, TYPED, answer, arrayValue, asBoolean, asFlag, asMap, asking, bodied, childrenIn, asksOf, declared, gathered, given as pipedIn, grows, guidance, issue, mapped, marked, named as answerNames, needed, nouns, only, ownAnswers, refuse, rowLines, seeding, spend, stating, VERBS, within, wordsIn } from "../asking.js";
+import { generators } from "../chain.js";
+import { listFields, shapeFields } from "../descend.js";
+import { STATED, fieldIn, holdsRow, listBounds, quoted, reconciled, rowsIn, withField, withRow, withoutRow, } from "../rows.js";
+import { findTree } from "../tree.js";
+const TREE = findTree();
+const NOUN = env.THREAD_NOUN ?? 'meta';
+const MINE = NOUN === 'meta' ? undefined : (await declared(TREE)).get(NOUN);
+const FILES = MINE?.files;
+const LIST = MINE?.list ?? 'declares';
+const SHAPE = MINE?.shape ?? 'Threaded';
+const FIELDS = MINE?.fields ?? shapeFields(SHAPE).map((one) => ({ ...one, boolean: false }));
+const ADDRESSED = FIELDS.some((one) => one.name === 'at');
+export const ASKS = asksOf(NOUN, FIELDS, {
+    name: {
+        guide: NOUN === 'meta'
+            ? 'kebab-case, e.g. billing — this becomes its id, and its own sheet is scaffolded empty beside it, ready for whatever this app declares under it next'
+            : `kebab-case, e.g. billing — this becomes its id, and no other ${NOUN} in this tree may carry it`,
+        asks: 'name: ',
+    },
+    ...(NOUN === 'meta' || !ADDRESSED || FILES !== undefined
+        ? {}
+        : {
+            at: {
+                guide: 'the path of a file that already exists, relative to this tree',
+                asks: 'at — the file this names: ',
+            },
+        }),
+    describes: {
+        guide: NOUN === 'meta'
+            ? 'one sentence a reader who has not seen the code could act on — what this governs'
+            : `one sentence a reader who has not seen the code could act on — what this ${NOUN} is`,
+        asks: 'describes — one sentence saying what this governs: ',
+    },
+}, NOUN === 'meta' || FILES !== undefined ? ['id', 'at', 'version'] : ['id', 'version']);
+const said = (one) => ASKS.find((each) => each.at === one)?.asks ?? `${one}: `;
+const WIDTH = Math.max(...ASKS.map((one) => one.at.length)) + 3;
+const kebab = (one) => one.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const at = MINE?.at ?? within(TREE.at, TREE.root);
+let sheet = {};
+try {
+    sheet = (await import(__rewriteRelativeImportExtension(pathToFileURL(join(TREE.at, at)).href)));
+}
+catch {
+    sheet = {};
+}
+const inSheet = (() => {
+    const only = sheet[LIST];
+    if (Array.isArray(only))
+        return only;
+    for (const value of Object.values(sheet)) {
+        const rows = value?.[LIST];
+        if (Array.isArray(rows))
+            return rows;
+    }
+    return undefined;
+})();
+if (inSheet === undefined) {
+    refuse(`${at} states no \`${LIST}\` list, so there is nowhere in it for a ${NOUN} to go. \`npx thread read ${at}\` prints what it does state.`);
+}
+const existing = inSheet;
+const mark = (one) => marked([one.id, one.at ?? '', one.describes, String(one.version ?? '')]);
+const listing = [
+    existing.length === 0
+        ? `${at} declares nothing yet.`
+        : `${String(existing.length)} thing(s) ${at} already declares:`,
+    ...existing.map((one) => `  [${mark(one)}] ${one.id} — ${one.describes}`),
+].join('\n');
+const words = wordsIn(['new', 'read', 'remove', 'add', 'edit']);
+const mustSay = (fields = FIELDS) => fields.filter((one) => one.required).map((one) => one.name);
+const kept = () => [...mustSay(), 'version'];
+const SAYS = new Map([
+    ['id', 'the word this row coins — kebab-case, and not already in that sheet'],
+    ['at', 'the path of a file that already exists, relative to this tree'],
+    ['describes', 'one sentence a reader who has not seen the file could act on'],
+]);
+function asks(fields) {
+    const named = mustSay(fields).filter((one) => one !== 'version');
+    const mute = named.filter((one) => !SAYS.has(one));
+    if (mute.length > 0) {
+        refuse(`every ${NOUN} states ${mute.join(', ')}, and \`add\` has no sentence to ask for ` +
+            `${mute.length === 1 ? 'it' : 'them'} with. The sentence goes beside the others in \`SAYS\`.`);
+    }
+    const pad = Math.max(...named.map((one) => one.length)) + 3;
+    return named.map((one) => `  ${`${one}:`.padEnd(pad)}${SAYS.get(one) ?? ''}`);
+}
+function unrestorable(row) {
+    const keeps = kept();
+    const worn = Object.keys(row).filter((one) => !keeps.includes(one) && row[one] !== undefined);
+    if (worn.length === 0)
+        return [];
+    return [
+        '',
+        `  \`add\` writes ${keeps.join(', ')} and nothing else, so ${worn.length === 1 ? 'this field goes' : 'these fields go'}`,
+        '  and no command here puts it back. Copy it now if this is a repoint rather than a deletion:',
+        '',
+        ...worn.map((one) => `      ${one}: ${JSON.stringify(row[one])}`),
+    ];
+}
+const rowLike = (one) => one !== null && typeof one === 'object' && typeof one.id === 'string';
+const HELD = ['declares', 'holds'];
+const under = async (row, from, seen) => {
+    const sheet = row.at;
+    if (typeof sheet !== 'string' || sheet === '' || sheet === from || seen.has(sheet))
+        return [];
+    if (!sheet.startsWith(`${TREE.name}/`))
+        return [];
+    seen.add(sheet);
+    let read;
+    try {
+        read = (await import(__rewriteRelativeImportExtension(pathToFileURL(join(TREE.at, sheet)).href)));
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const [name, value] of Object.entries(read)) {
+        if (Array.isArray(value)) {
+            for (const each of value)
+                if (rowLike(each))
+                    found.push({ row: each, list: name, sheet });
+            continue;
+        }
+        for (const list of HELD) {
+            const held = value?.[list];
+            if (Array.isArray(held))
+                for (const each of held)
+                    if (rowLike(each))
+                        found.push({ row: each, list, sheet });
+        }
+    }
+    for (const each of [...found])
+        found.push(...(await under(each.row, sheet, seen)));
+    return found;
+};
+async function pointedAt(which, inNode) {
+    const byNode = inNode === undefined ? existing : existing.filter((each) => mark(each) === inNode || each.id === inNode);
+    const sheeted = inNode !== undefined && byNode.length === 0 && inNode.endsWith('.ts');
+    const looking = sheeted ? existing : byNode;
+    const metas = inNode === undefined ? existing.filter((each) => mark(each) === which || each.id === which) : [];
+    const kids = [];
+    const seen = new Set();
+    for (const meta of looking) {
+        for (const held of await under(meta, at, seen)) {
+            if (mark(held.row) !== which && held.row.id !== which)
+                continue;
+            if (sheeted && held.sheet !== inNode)
+                continue;
+            kids.push({ meta, row: held.row, list: held.list, sheet: held.sheet });
+        }
+    }
+    return { looking, metas, kids };
+}
+if (words[0] === 'read') {
+    const which = words[2] ?? words[1];
+    const inNode = words[2] === undefined ? undefined : words[1];
+    const pointed = await pointedAt(which, inNode);
+    const kid = pointed.kids[0];
+    const one = pointed.metas[0] ?? kid?.row;
+    if (one === undefined) {
+        refuse(`\`${which ?? '(nothing)'}\` is not a row this tree declares. Give its id, or the mark printed in brackets ` +
+            `beside it — \`${TYPED} create ${NOUN}\` with nothing after it lists every one.`);
+    }
+    const sheet = kid === undefined ? at : kid.sheet;
+    const said = Object.entries(one).filter(([name, value]) => name !== 'id' && name !== 'describes' && value !== undefined);
+    const pad = Math.max(0, ...said.map(([name]) => name.length)) + 3;
+    stdout.write(`${one.id} — ${one.describes}\n`);
+    stdout.write(`  it is a row in ${sheet}\n\n`);
+    for (const [name, value] of said) {
+        stdout.write(`  ${`${name}:`.padEnd(pad)}${typeof value === 'string' ? value : JSON.stringify(value)}\n`);
+    }
+    if (one.at === undefined) {
+        stdout.write(`\n${one.id} is a value ${sheet} holds rather than a file of its own.\n`);
+        exit(0);
+    }
+    if (one.at === sheet) {
+        stdout.write(`\n${one.at} is the sheet this row sits in rather than a file of its own.\n`);
+        exit(0);
+    }
+    stdout.write(`\n${one.at}:\n`);
+    try {
+        stdout.write(readFileSync(join(TREE.at, one.at), 'utf8'));
+    }
+    catch {
+        stdout.write('(nothing is there)\n');
+    }
+    exit(0);
+}
+if (words[0] === 'remove') {
+    const which = words[2] ?? words[1];
+    const inNode = words[2] === undefined ? undefined : words[1];
+    const { looking, metas, kids } = await pointedAt(which, inNode);
+    if (inNode !== undefined && looking.length === 0) {
+        refuse(`\`${inNode}\` is not a governing node ${at} declares, so there is nothing under it to take out.`);
+    }
+    if (metas.length + kids.length === 0) {
+        refuse(`\`${which ?? '(nothing)'}\` is not a row this tree declares. Every governing node in ${at} was ` +
+            'searched, and every list under each of them. Give the id, or the mark printed in brackets beside it above.');
+    }
+    if (metas.length + kids.length > 1) {
+        const named = [
+            ...metas.map((each) => `\`${each.id ?? '(unnamed)'}\` — the governing node in ${at}`),
+            ...kids.map((each) => `\`${each.row.id ?? '(unnamed)'}\` — under \`${each.meta.id ?? '(unnamed)'}\`, in ${each.sheet}`),
+        ];
+        refuse(`\`${which}\` names ${String(named.length)} rows: ${named.join('; ')}. Say which node or which sheet to look in — ` +
+            `\`thread create ${NOUN} remove <node|sheet> ${String(which)}\` — because two rows carrying the same values carry the ` +
+            'same mark AND the same id, so naming the row again cannot separate them. Nothing was written.');
+    }
+    const kid = kids[0];
+    if (kid !== undefined) {
+        const sheet = join(TREE.at, kid.sheet);
+        const wrote = kid.list === 'derives' && kid.row.at !== undefined && kid.row.at !== kid.sheet;
+        const flaggedKid = argv.indexOf(RECEIPT);
+        if (flaggedKid === -1) {
+            const nonce = issue(TREE.at, listing);
+            stdout.write([
+                '',
+                `\`${kid.row.id ?? '(unnamed)'}\` — ${kid.row.describes ?? ''}`,
+                kid.row.at === undefined
+                    ? `  it is a value held under \`${kid.meta.id ?? '(unnamed)'}\` in ${kid.sheet}.`
+                    : `  it names ${kid.row.at}, under \`${kid.meta.id ?? '(unnamed)'}\` in ${kid.sheet}.`,
+                '',
+                `  thread create ${NOUN} remove ${String(kid.meta.id)} ${String(kid.row.id)} ${RECEIPT} ${nonce}`,
+                '',
+                ...(wrote
+                    ? [
+                        `  this takes the row out of ${kid.sheet} and deletes ${kid.row.at}, because that row derives`,
+                        '  it: a command wrote every byte of it, and with the row gone nothing writes it again. Any',
+                        `  command the row names stops existing at the same moment, because \`${TYPED} create\` reads`,
+                        '  the rows to know what commands there are.',
+                    ]
+                    : kid.row.at === undefined
+                        ? [`  this takes the row out of ${kid.sheet} and deletes no file, because a held value names none.`]
+                        : [
+                            `  this takes the row out of ${kid.sheet} and LEAVES ${kid.row.at} exactly where it is.`,
+                            '  Nothing here wrote that file, so nothing here deletes it — it goes back to being declared',
+                            '  by nobody, which the descent will say.',
+                        ]),
+                ...unrestorable(kid.row),
+                '',
+            ].join('\n'));
+            stdout.write(`create: receipt ${nonce} — spent on use, and stale the moment ${at} changes.\n`);
+            exit(0);
+        }
+        spend(TREE.at, listing, argv[flaggedKid + 1], at);
+        const text = readFileSync(sheet, 'utf8');
+        const where = listBounds(text, kid.list);
+        if (where === undefined) {
+            refuse(`${kid.sheet} states no \`${kid.list}\` list, so there is nothing to take a row out of.`);
+        }
+        writeFileSync(sheet, withoutRow(text, where, String(kid.row.id)), 'utf8');
+        stdout.write(`create: took ${String(kid.row.id)} out of ${kid.sheet}.\n`);
+        if (!wrote) {
+            if (kid.row.at !== undefined)
+                stdout.write(`create: ${kid.row.at} is still there, and now declared by nobody.\n`);
+            exit(0);
+        }
+        try {
+            rmSync(join(TREE.at, String(kid.row.at)));
+            stdout.write(`create: deleted ${kid.row.at} — the row derived it, so nothing writes it any more.\n`);
+        }
+        catch {
+            stdout.write(`create: ${kid.row.at} was not there to delete, so only the row came out.\n`);
+        }
+        exit(0);
+    }
+    const one = metas[0];
+    if (one === undefined)
+        refuse(`\`${which ?? '(nothing)'}\` names nothing this tree declares.`);
+    const owns = typeof one.at === 'string' && one.at !== at;
+    const inside = await under(one, at, new Set());
+    if (inside.length > 0) {
+        refuse(`\`${one.id}\` governs ${String(inside.length)} thing(s) — ${inside.map((each) => each.row.id).join(', ')}. Removing it would ` +
+            'leave every one of them answering to nothing, and this will not cascade on your behalf. Take those out first, ' +
+            'and this becomes an empty node you can remove. Nothing was written.');
+    }
+    const flaggedAt = argv.indexOf(RECEIPT);
+    if (flaggedAt === -1) {
+        const nonce = issue(TREE.at, listing);
+        stdout.write([
+            '',
+            `\`${one.id}\` — ${one.describes}`,
+            owns
+                ? `  it governs nothing, and its sheet ${one.at ?? ''} declares an empty list.`
+                : one.at === undefined
+                    ? `  it is a value ${at} holds, and names no file.`
+                    : `  it governs nothing, and ${one.at} is the sheet this row sits in rather than a file of its own.`,
+            '',
+            `  thread create ${NOUN} remove ${which ?? one.id} ${RECEIPT} ${nonce}`,
+            '',
+            owns
+                ? `  this takes the row out of ${at} and deletes ${one.at ?? ''}. It is the one command here that`
+                : `  this takes the row out of ${at} and deletes no file.`,
+            owns
+                ? '  running again will not undo.'
+                : one.at === undefined
+                    ? `  ${at} holds every other value in that list and is left exactly as it is.`
+                    : `  ${one.at} holds every other row in that list and is left exactly as it is.`,
+            ...unrestorable(one),
+            '',
+        ].join('\n'));
+        exit(0);
+    }
+    spend(TREE.at, listing, argv[flaggedAt + 1], at);
+    const text = readFileSync(join(TREE.at, at), 'utf8');
+    const where = listBounds(text, LIST);
+    if (where === undefined)
+        refuse(`${at} states no \`${LIST}\` list, so there is nothing to take a row out of.`);
+    writeFileSync(join(TREE.at, at), withoutRow(text, where, one.id), 'utf8');
+    stdout.write(`create: took ${one.id} out of ${at}.\n`);
+    if (owns) {
+        try {
+            rmSync(join(TREE.at, one.at ?? ''));
+            stdout.write(`create: deleted ${one.at ?? ''}.\n`);
+        }
+        catch {
+            stdout.write(`create: ${one.at ?? ''} was not there to delete.\n`);
+        }
+    }
+    exit(0);
+}
+const FIELD_KEY = 'field';
+const FIELD = asFlag(FIELD_KEY);
+const FIELD_ASKS = [
+    { at: 'describes', guide: 'the sentence the CLI asks with. One a person who has not seen the code could answer' },
+    { at: 'options', guide: 'the values it may take, separated by |, e.g. framework|optional. Leave it off to take any text' },
+    {
+        at: 'optional',
+        guide: 'answer y and a row may leave the field unstated. Anything else and every row must state it, and each row ' +
+            'that does not is named below with the command that fills it in',
+    },
+];
+const FIELD_TAKES = [FIELD_KEY, ...answerNames(FIELD_ASKS)];
+if (words[0] === 'edit' && argv.includes(FIELD)) {
+    const name = (argv[argv.indexOf(FIELD) + 1] ?? '').trim();
+    if (!/^[a-z][A-Za-z0-9]*$/.test(name)) {
+        refuse('`' + name + '` cannot be a field. A field is one camelCase word, e.g. folder. Nothing was written.');
+    }
+    const answers = pipedIn();
+    only(answers, FIELD_TAKES, '`edit ' + FIELD + '`');
+    const sentence = (answer(answers, 'describes') ?? '').trim();
+    const options = (answer(answers, 'options') ?? '').split('|').map((one) => one.trim()).filter((one) => one !== '');
+    const optional = (answer(answers, 'optional') ?? '').trim().toLowerCase().startsWith('y');
+    const flaggedField = argv.indexOf(RECEIPT);
+    if (flaggedField === -1) {
+        const nonce = issue(TREE.at, listing);
+        stdout.write([
+            '',
+            '`edit ' + FIELD + '` gives every ' + NOUN + ' a new field, written into the shape at the top of ' + at + '. From then on',
+            '`thread create ' + NOUN + '` asks for it with the sentence you give here, and `thread edit` can set it on any row.',
+            '',
+            ...guidance(FIELD_ASKS),
+            '',
+            '  thread create ' + NOUN + ' edit ' + FIELD + ' <name> --describes <sentence> ' + RECEIPT + ' ' + nonce,
+            '',
+        ].join('\n'));
+        stdout.write('create: receipt ' + nonce + ' — spent on use, and stale the moment ' + at + ' changes.\n');
+        exit(0);
+    }
+    spend(TREE.at, listing, argv[flaggedField + 1], at);
+    if (sentence === '') {
+        refuse('`' + name + '` was given no sentence, and the sentence is what `thread create ' + NOUN + '` asks with. Give --describes. Nothing was written.');
+    }
+    const file = join(TREE.at, at);
+    const text = readFileSync(file, 'utf8');
+    const opens = 'export interface ' + SHAPE + ' extends Threaded {';
+    const from = text.indexOf(opens);
+    if (from === -1) {
+        refuse(at + ' has no shape at its top for this to write into. Every sheet `thread create meta new` writes has one. Run `thread read ' + at + '` to see what is there. Nothing was written.');
+    }
+    const close = text.indexOf('\n}', from);
+    if (close === -1) {
+        refuse('the shape at the top of ' + at + ' never closes, so nothing can be added to it. Run `thread read ' + at + '` to see where it stops. Nothing was written.');
+    }
+    const block = text.slice(from, close);
+    if (block.includes('readonly ' + name + ':') || block.includes('readonly ' + name + '?:')) {
+        refuse('the shape at the top of ' + at + ' already states `' + name + '`. One field, one statement. Nothing was written.');
+    }
+    const type = options.length === 0 ? 'string' : options.map((one) => quoted(one)).join(' | ');
+    const line = '\n  /** ' + sentence + ' */\n  readonly ' + name + (optional ? '?' : '') + ': ' + type;
+    writeFileSync(file, text.slice(0, close) + line + text.slice(close), 'utf8');
+    stdout.write('create: every ' + NOUN + ' now states `' + name + '`, and `thread create ' + NOUN + '` asks for it with the sentence you gave.\n');
+    if (!optional) {
+        const lacking = existing.filter((one) => one[name] === undefined);
+        if (lacking.length > 0) {
+            stdout.write('create: ' + String(lacking.length) + ' ' + NOUN + '(s) already here state no `' + name + '`, and the shape now requires it. Fill each in:\n');
+            for (const one of lacking)
+                stdout.write('  thread edit ' + mark(one) + ' --' + name + ' <value>\n');
+        }
+    }
+    exit(0);
+}
+if (words[0] === 'edit') {
+    const which = words[2] ?? words[1];
+    const inNode = words[2] === undefined ? undefined : words[1];
+    const { looking, metas, kids } = await pointedAt(which, inNode);
+    if (inNode !== undefined && looking.length === 0) {
+        refuse(`\`${inNode}\` is not a governing node ${at} declares, so there is nothing under it to change.`);
+    }
+    if (metas.length + kids.length === 0) {
+        refuse(`\`${which ?? '(nothing)'}\` is not a row this tree declares. Every governing node in ${at} was ` +
+            'searched, and every list under each of them. Give the id, or the mark printed in brackets beside it above.');
+    }
+    if (metas.length + kids.length > 1) {
+        const named = [
+            ...metas.map((each) => `\`${each.id ?? '(unnamed)'}\` — the governing node in ${at}`),
+            ...kids.map((each) => `\`${each.row.id ?? '(unnamed)'}\` — under \`${each.meta.id ?? '(unnamed)'}\`, in ${each.sheet}`),
+        ];
+        refuse(`\`${String(which)}\` names ${String(named.length)} rows: ${named.join('; ')}. Say which node to look ` +
+            `under — \`thread create ${NOUN} edit <node> ${String(which)}\` — because two rows carrying the same ` +
+            'values carry the same mark AND the same id, so naming the row again cannot separate them. Nothing was ' +
+            'written.');
+    }
+    const kid = kids[0];
+    const held = kid === undefined ? metas[0] : kid.row;
+    if (held?.id === undefined) {
+        refuse(`\`${String(which)}\` names a row with no id, and a row is reached by its id. Nothing was written.`);
+    }
+    const file = kid === undefined ? join(TREE.at, at) : join(TREE.at, kid.sheet);
+    const shown = kid === undefined ? at : kid.sheet;
+    const inList = kid === undefined ? LIST : kid.list;
+    const shaped = listFields(file, inList).filter((one) => one.name !== 'id');
+    if (shaped.length === 0) {
+        refuse(`${shown} states a \`${inList}\` this cannot read the shape of, so which fields a row there may carry is ` +
+            'unknown. Editing one blind is how a row stops being the shape its own list declares.');
+    }
+    const editable = shaped.map((one) => one.name);
+    const listed = new Set(shaped.filter((one) => one.list).map((one) => one.name));
+    const flagged = new Set(shaped.filter((one) => one.boolean).map((one) => one.name));
+    const text = readFileSync(file, 'utf8');
+    const where = listBounds(text, inList);
+    if (where === undefined)
+        refuse(`${shown} states no \`${inList}\` list, so there is no row in it to change.`);
+    const standing = editable.map((one) => ({ field: one, value: fieldIn(text, where, String(held.id), one) }));
+    const flaggedEdit = argv.indexOf(RECEIPT);
+    if (flaggedEdit === -1) {
+        const nonce = issue(TREE.at, listing);
+        stdout.write([
+            '',
+            `\`${String(held.id)}\` — ${String(held.describes ?? '')}`,
+            `  it is a row in ${shown}, and \`edit\` changes what one of its fields says. One command, so a refusal`,
+            '  leaves the row exactly as it stands — which is the thing `remove` then `add` cannot promise.',
+            '',
+            'what it says now:',
+            '',
+            ...standing.map((one) => `  ${`${one.field}:`.padEnd(12)}${one.value === undefined ? '(not stated)' : one.value}`),
+            '',
+            'answer only the field you are changing, one per line, in any order:',
+            '',
+            `  thread edit ${String(which)} --<field> <value> ${RECEIPT} ${nonce}`,
+            '',
+            '  a field it is not handed is left alone, and `id` is not among them: changing one retires a word',
+            '  and coins another, which is a decision rather than a replacement.',
+            '',
+        ].join('\n'));
+        stdout.write(`create: receipt ${nonce} — spent on use, and stale the moment ${at} changes.\n`);
+        exit(0);
+    }
+    spend(TREE.at, listing, argv[flaggedEdit + 1], at);
+    const answers = gathered(pipedIn(), shaped);
+    const own = ownAnswers(answers);
+    const groups = childrenIn(answers);
+    only(answers, editable, '`edit`');
+    if (answers.length === 0) {
+        refuse('`edit` was handed no field to change. Answer one of the fields it listed. Nothing was written.');
+    }
+    const wasAt = typeof held.at === 'string' ? held.at : '';
+    const moving = own.find((one) => one.key === 'at');
+    const goesTo = moving === undefined || moving.value === wasAt ? '' : moving.value;
+    if (goesTo !== '' && existsSync(join(TREE.at, goesTo))) {
+        refuse(`${goesTo} is already there, and one address holds one thing. Moving \`${String(held.id)}\` onto it would ` +
+            'leave two rows pointing at one file and no way to say which owns it. Nothing was written.');
+    }
+    let next = text;
+    for (const one of own) {
+        const bounds = listBounds(next, inList);
+        if (bounds === undefined)
+            refuse(`${shown} states no \`${LIST}\` list.`);
+        const now = fieldIn(next, bounds, String(held.id), one.key);
+        if (flagged.has(one.key)) {
+            const set = withField(next, bounds, String(held.id), one.key, asBoolean(one.value));
+            if (set !== undefined) {
+                next = set;
+                continue;
+            }
+        }
+        const field = shaped.find((each) => each.name === one.key);
+        if (field !== undefined && mapped(field, one.value)) {
+            const set = withField(next, bounds, String(held.id), one.key, asMap(one.value));
+            if (set !== undefined) {
+                next = set;
+                continue;
+            }
+        }
+        if (listed.has(one.key)) {
+            const put = withField(next, bounds, String(held.id), one.key, arrayValue('    ', one.key, one.value, groups.get(one.key)));
+            if (put !== undefined) {
+                next = put;
+                continue;
+            }
+        }
+        if (now === undefined && listed.has(one.key)) {
+            refuse(`\`${String(held.id)}\` states no \`${one.key}\`, and that field holds rows rather than a sentence. ` +
+                `Write what goes in it with \`${TYPED} create meta add\`, which writes the whole row. Nothing was written.`);
+        }
+        if (now !== undefined && !now.startsWith("'")) {
+            refuse(`\`${one.key}\` on \`${String(held.id)}\` is ${now}, which is not a plain sentence — replacing it with ` +
+                'one would change what kind of thing it is. Nothing was written.');
+        }
+        const written = withField(next, bounds, String(held.id), one.key, quoted(one.value));
+        if (written === undefined) {
+            refuse(`\`${one.key}\` could not be written on \`${String(held.id)}\`. Nothing was written.`);
+        }
+        next = written;
+    }
+    for (const [list, found] of groups) {
+        const bounds = listBounds(next, inList);
+        if (bounds === undefined)
+            break;
+        const put = withField(next, bounds, String(held.id), list, arrayValue('    ', list, '', found));
+        if (put === undefined) {
+            refuse(`${list} could not be written on ${String(held.id)}, so nothing was written. Run npx thread read ${shown} to see what that row states now.`);
+        }
+        next = put;
+    }
+    writeFileSync(file, next, 'utf8');
+    if (goesTo !== '') {
+        if (existsSync(join(TREE.at, wasAt))) {
+            mkdirSync(dirname(join(TREE.at, goesTo)), { recursive: true });
+            renameSync(join(TREE.at, wasAt), join(TREE.at, goesTo));
+            stdout.write(`create: moved ${wasAt} to ${goesTo}, because that is where ${String(held.id)} now says it is.\n`);
+        }
+        else {
+            stdout.write(`create: nothing was at ${wasAt}, so nothing moved. \`${String(held.id)}\` now says ${goesTo} and that ` +
+                'address is empty, which `npx thread descent` will name until something is put there.\n');
+        }
+    }
+    const nowAt = goesTo === '' ? wasAt : goesTo;
+    const mine = listBounds(next, inList);
+    const source = mine === undefined ? undefined : rowsIn(next, mine).find((one) => one.id === held.id)?.source;
+    if (kid === undefined && nowAt !== '' && source !== undefined) {
+        const sheet = join(TREE.at, nowAt);
+        if (existsSync(sheet)) {
+            const there = readFileSync(sheet, 'utf8');
+            const settled = reconciled(there, `const HEAD = ${source.trim().replace(/,$/, '')}\n`, STATED);
+            if (settled !== there)
+                writeFileSync(sheet, settled, 'utf8');
+        }
+    }
+    stdout.write(`create: ${String(held.id)} now says ${answers.map((one) => `\`${one.key}\``).join(', ')} in ${shown}.\n`);
+    exit(0);
+}
+if (words[0] === 'add') {
+    const which = words[1];
+    const one = existing.find((each) => mark(each) === which || each.id === which);
+    if (one === undefined) {
+        refuse(`\`${which ?? '(nothing)'}\` is not something ${at} declares. Give the id, or the mark printed in brackets ` +
+            'beside it above.');
+    }
+    if (one.at === undefined) {
+        refuse(`\`${one.id}\` is a value ${at} holds, so it has no sheet of its own for a child to go in. ` +
+            `\`thread create ${NOUN} new\` is how one more is declared.`);
+    }
+    const sheet = join(TREE.at, one.at);
+    if (!existsSync(sheet)) {
+        refuse(`\`${one.id}\` names ${one.at} and nothing is there, so there is no list to declare a child in.`);
+    }
+    if (listBounds(readFileSync(sheet, 'utf8'), LIST) === undefined) {
+        refuse(`${one.at} states no \`${LIST}\` list, so there is nowhere in it for a child to go.`);
+    }
+    const fields = listFields(sheet, LIST);
+    if (fields.length === 0) {
+        refuse(`${one.at} states a \`${LIST}\` this cannot read the shape of, so what a row there must say is unknown. ` +
+            'Write it as a list with a declared row type — the fields `add` asks for are read off that type, and ' +
+            'guessing them is how a row gets written that the tree then refuses.');
+    }
+    if (!fields.some((each) => each.name === 'at')) {
+        refuse(`${one.at} holds values rather than files, so there is nothing on disk to point a row at. ` +
+            `\`thread create ${NOUN} new\` is how one is declared.`);
+    }
+    const flaggedAt = argv.indexOf(RECEIPT);
+    if (flaggedAt === -1) {
+        const nonce = issue(TREE.at, listing);
+        stdout.write([
+            '',
+            `\`${one.id}\` — ${one.describes}`,
+            `  its sheet is ${one.at}, and a row put there names a file that is ALREADY on disk.`,
+            '',
+            'what `add` takes, one answer per line, in any order:',
+            '',
+            ...asks(fields),
+            '',
+            `  thread create ${NOUN} add ${which ?? one.id} ${RECEIPT} ${nonce}`,
+            '',
+            '  it writes no file. It points this node at one somebody already wrote, and from then on',
+            '  that file is held to everything this tree refuses.',
+            '',
+        ].join('\n'));
+        stdout.write(`create: receipt ${nonce} — spent on use, and stale the moment ${at} changes.\n`);
+        exit(0);
+    }
+    spend(TREE.at, listing, argv[flaggedAt + 1], at);
+    const answers = pipedIn();
+    const { piped: fed, ask: asked, shut: close } = asking(answers);
+    if (fed)
+        only(answers, mustSay(fields), '`add`');
+    const said = fed ? needed(answers, 'at', '`add`') : await asked('at', 'at — the path of a file that already exists: ');
+    const target = join(TREE.at, said);
+    const childAt = within(TREE.at, target);
+    if (!existsSync(target)) {
+        close();
+        refuse(`nothing is at ${childAt}. \`add\` points this node at a file that already exists — it writes none.`);
+    }
+    if (statSync(target).isDirectory()) {
+        close();
+        refuse(`${childAt} is a directory. Name the file — a directory threads nothing beneath it, so everything under it ` +
+            'would still read as declared by nobody while the row itself looked answered.');
+    }
+    const childId = kebab(fed ? needed(answers, 'id', '`add`') : await asked('id', 'id — the word this row coins: '));
+    if (!KEBAB.test(childId)) {
+        close();
+        refuse(`\`${childId}\` cannot be an id — it is kebab-case, e.g. glossary-generator.`);
+    }
+    const saying = fed
+        ? needed(answers, 'describes', '`add`')
+        : await asked('describes', 'describes — one sentence saying what this file is: ');
+    if (saying === '') {
+        close();
+        refuse(`${childAt} was given no meaning, and a row without one is a path nobody can read.`);
+    }
+    close();
+    const now = readFileSync(sheet, 'utf8');
+    const place = listBounds(now, LIST);
+    if (place === undefined)
+        refuse(`${one.at} states no \`${LIST}\` list.`);
+    if (holdsRow(now, place, childId))
+        refuse(`\`${childId}\` is already declared in ${one.at}. One id, one row.`);
+    const row = [
+        '    {',
+        `      id: ${quoted(childId)},`,
+        `      at: ${quoted(childAt)},`,
+        `      describes: ${quoted(saying)},`,
+        '      version: 1,',
+        '    },',
+    ].join('\n');
+    writeFileSync(sheet, withRow(now, place, row), 'utf8');
+    stdout.write(`create: ${one.id} now declares ${childAt}.\n`);
+    exit(0);
+}
+stdout.write(`${listing}\n`);
+const flagged = argv.indexOf(RECEIPT);
+if (flagged === -1) {
+    const nonce = issue(TREE.at, listing);
+    stdout.write([
+        '',
+        ...VERBS,
+        '',
+        'what `new` takes, one answer per line, in any order:',
+        '',
+        ...guidance(ASKS),
+        ...(FILES === undefined
+            ? []
+            : [
+                `  ${'at:'.padEnd(WIDTH)}${FILES.replace('*', '<name>')} — where it lives is never typed`,
+                `  ${`${asFlag(BODY)}:`.padEnd(WIDTH)}what goes in that file, given on the command. Leave it out and the settle writes the starter`,
+            ]),
+        '',
+        `  thread create ${NOUN} new <name> ${RECEIPT} ${nonce}`,
+        `  thread create ${NOUN} read <mark>           no receipt, writes nothing`,
+        ...(ADDRESSED
+            ? [
+                `  thread create ${NOUN} add <mark> ${RECEIPT} ${nonce}`,
+                '              points a node at a file that already exists — it writes none',
+            ]
+            : []),
+        `  thread create ${NOUN} remove <id> ${RECEIPT} ${nonce}`,
+        '              only a node governing nothing — it refuses one with anything under it',
+        `  thread create ${NOUN} edit <row> ${RECEIPT} ${nonce}`,
+        '              changes what one field of an existing row says. One command, so a refusal leaves',
+        '              the row exactly as it stands',
+        '',
+        `${RECEIPT} is spent by one run, and is refused if ${at} changed after it was issued.`,
+        '',
+    ].join('\n'));
+    stdout.write(`create: receipt ${nonce} — spent on use, and stale the moment ${at} changes.\n`);
+    exit(0);
+}
+spend(TREE.at, listing, argv[flagged + 1], at);
+const all = gathered(pipedIn(), FIELDS);
+const { piped, ask, line, shut } = asking(all);
+const own = ownAnswers(all);
+const TAKES = FILES === undefined ? answerNames(ASKS) : [...answerNames(ASKS), BODY];
+if (piped)
+    only(own, TAKES, '`new`');
+const name = kebab(words[1] ?? (piped ? needed(own, 'name', '`new`') : await ask('name', said('name'))));
+if (!KEBAB.test(name)) {
+    shut();
+    refuse(`\`${name}\` cannot be the id of a governing node — it is kebab-case, e.g. billing.`);
+}
+if (existing.some((one) => one.id === name)) {
+    shut();
+    refuse(`\`${name}\` is already declared in ${at}. One id, one row.`);
+}
+let taken = new Map();
+try {
+    taken = nouns(await generators(TREE), 'create');
+}
+catch {
+    taken = new Map();
+}
+if (taken.has(name)) {
+    shut();
+    refuse(`\`${name}\` is already a noun this tree makes — \`thread create ${name}\` runs ${taken.get(name) ?? 'a command'}. ` +
+        'One word, one meaning: a governing node called that would be reachable only by its mark, and the two would ' +
+        'be told apart by nothing. Choose another name. Nothing was written.');
+}
+const target = join(TREE.dir, `${name}.ts`);
+const sheetAt = within(TREE.at, target);
+if (NOUN === 'meta' && existsSync(target)) {
+    shut();
+    refuse(`${sheetAt} is already there and no row names it. Choose another name, or delete it first.`);
+}
+const describes = piped
+    ? needed(own, 'describes', '`new`')
+    : await ask('describes', said('describes'));
+if (describes === '') {
+    shut();
+    refuse(`\`${name}\` was given no meaning, and a governing node without one is a name nobody can read.`);
+}
+const address = NOUN === 'meta'
+    ? sheetAt
+    : FILES !== undefined
+        ? FILES.replace('*', name)
+        : !ADDRESSED
+            ? undefined
+            : piped
+                ? needed(own, 'at', '`new`')
+                : await ask('at', said('at'));
+const { stated, kids } = await stating(ASKS, all, piped, ask, line, ['name', 'id', 'at', 'describes', 'version']);
+const body = FILES === undefined || address === undefined
+    ? undefined
+    : await bodied(`${address} itself — this is ${asFlag(BODY)}`, '', piped, all, line);
+shut();
+if (body !== undefined && address !== undefined && existsSync(join(TREE.at, address))) {
+    refuse(`${address} is already on disk, so the body you gave has nowhere to go without being put over somebody's file. ` +
+        `Leave the body out and the row names what is there, or run \`${TYPED} read ${address}\` and move it first. Nothing was written.`);
+}
+const row = [
+    '    {',
+    `      id: ${quoted(name)},`,
+    ...(address === undefined ? [] : [`      at: ${quoted(address)},`]),
+    `      describes: ${quoted(describes)},`,
+    '      version: 1,',
+    ...rowLines('      ', stated, NOUN === 'meta' ? new Map() : kids),
+    '    },',
+].join('\n');
+const text = readFileSync(join(TREE.at, at), 'utf8');
+const where = listBounds(text, LIST);
+if (where === undefined)
+    refuse(`${at} states no \`${LIST}\` list to declare a governing node in.`);
+if (holdsRow(text, where, name))
+    refuse(`\`${name}\` is already declared in ${at}.`);
+writeFileSync(join(TREE.at, at), withRow(text, where, row), 'utf8');
+stdout.write(`create: declared ${name} in ${at}.\n`);
+for (const said of seeding(kids, TREE.at))
+    stdout.write(`create: ${said}\n`);
+if (FILES !== undefined && address !== undefined) {
+    if (body === undefined) {
+        stdout.write(`create: ${address} follows — the settle writes its starter, and \`${TYPED} edit ${address} --from <path>\` replaces it.\n`);
+    }
+    else {
+        mkdirSync(dirname(join(TREE.at, address)), { recursive: true });
+        writeFileSync(join(TREE.at, address), body.endsWith('\n') ? body : `${body}\n`, 'utf8');
+        stdout.write(`create: wrote ${address} with the body you gave it.\n`);
+    }
+}
+if (NOUN !== 'meta') {
+    stdout.write(`create: \`npx thread read ${at}\` prints what that list says now.\n`);
+    exit(0);
+}
+const opens = (readFileSync(join(TREE.at, at), 'utf8').split('\n')[0] ?? '').trim();
+if (!opens.includes('Threaded')) {
+    refuse(`${at} does not open by importing \`Threaded\`, so a new sheet cannot be given the same import and would be ` +
+        'written unable to compile. Nothing was scaffolded.');
+}
+const CONST = name.toUpperCase().replace(/-/g, '_');
+const SHAPED = name.split('-').map((one) => `${one.slice(0, 1).toUpperCase()}${one.slice(1)}`).join('');
+writeFileSync(target, [
+    opens,
+    '',
+    `export interface ${SHAPED} extends Threaded {`,
+    `  readonly declares?: readonly ${SHAPED}[]`,
+    '}',
+    '',
+    `export const ${CONST}: ${SHAPED} = {`,
+    `  id: ${quoted(name)},`,
+    `  at: ${quoted(sheetAt)},`,
+    `  describes: ${quoted(describes)},`,
+    '  version: 1,',
+    ...(kids.size > 0 ? rowLines('  ', [], kids) : ['  declares: [],']),
+    '}',
+    '',
+].join('\n'), 'utf8');
+stdout.write(`create: wrote ${sheetAt}, declaring nothing under it yet.\n` +
+    `create: every ${name} carries what any row carries — a name, an address and a sentence. To give ${name}s a ` +
+    `field of their own, change the shape at the top of ${sheetAt}. What you add lands on this node and on ` +
+    `everything declared under it, and \`npx thread create\` starts asking for it.\n`);
+stdout.write(['', ...VERBS, '', ...grows(sheetAt, name), ''].join('\n'));
+exit(0);