eidosmd 0.2.0 → 0.3.1

package/dist/src/core/edits.js

@@ -0,0 +1,1381 @@
+// Framework edits: every mechanical change to the framework document, the
+// frontmatter, the files, and the links between them, as a plan that is
+// shown before it is applied. `eidos configure:<noun> <operation>` and
+// Framework Settings both run these, so a rename from the shell and one from
+// the page produce the same files.
+//
+// A plan is built without touching anything, lists every step with its file
+// and its before and after, every value that would be lost, and every
+// conflict, and is applied step by step in the order listed. After a plan
+// the index is rewritten and the check runs, so a command never leaves the
+// root with a finding it caused; the one way to is `preserve`, the owner's
+// choice, which the plan says out loud.
+//
+// The line is data, not prose: a body's text is never edited, a link is a
+// path substitution, and a value a property held is shown before it goes,
+// never placed anywhere.
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
+import { listBlueprints, propertyString } from './blueprint.js';
+import { checkRoot, optionProblem } from './check.js';
+import { appliesTo, defaultVariant, findCollection, findVariant, FRAMEWORK_DIR, isCollection, loadFramework, PROPERTY_TYPES, unitOf } from './framework.js';
+import { editFrontmatterKey, formatScalar, hasKey } from './frontmatter.js';
+import { moveFile } from './git.js';
+import { buildIndexes } from './index-leaf.js';
+import { movePath, rewriteLinks } from './links.js';
+import { isRoleName, listRoles, meFile, readActor, roleFile, rolesDir } from './me.js';
+import { convert, kebab } from './naming.js';
+import { readSettings, writeSettings } from './settings.js';
+export class EditError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EditError';
+    }
+}
+export function editContext(root) {
+    const framework = loadFramework(root);
+    return { root, framework, blueprints: listBlueprints(framework) };
+}
+const rel = (root, file) => path.relative(root, file).split(path.sep).join('/');
+const isEmpty = (value) => value === undefined || value === null || value === '' || (Array.isArray(value) && value.length === 0);
+// ---- the framework document, edited in place with its comments kept ---------
+class FrameworkDoc {
+    doc;
+    file;
+    original;
+    constructor(framework) {
+        this.file = framework.file;
+        this.original = readFileSync(framework.file, 'utf8');
+        this.doc = parseDocument(this.original);
+    }
+    changed() {
+        return this.text() !== this.original;
+    }
+    text() {
+        return this.doc.toString({ lineWidth: 0 });
+    }
+    write() {
+        writeFileSync(this.file, this.text(), 'utf8');
+    }
+    // A sequence at a path, created empty when absent.
+    seq(keys) {
+        const held = this.doc.getIn(keys);
+        if (isSeq(held))
+            return held;
+        const node = this.doc.createNode([]);
+        this.doc.setIn(keys, node);
+        return node;
+    }
+    // The map in a sequence whose scalar field equals the value.
+    static find(seq, field, value) {
+        if (!seq)
+            return null;
+        for (const item of seq.items) {
+            if (isMap(item) && String(item.get(field) ?? '') === value)
+                return item;
+        }
+        return null;
+    }
+    // A new entry in the style its siblings use: flow (`{ ... }`, one row per
+    // line) when any of them is, since a row a tool expanded with its own
+    // nested fields sits beside rows the seed wrote flat.
+    add(seq, value) {
+        const node = this.doc.createNode(value);
+        if (seq.items.some((item) => isMap(item) && item.flow))
+            node.flow = true;
+        seq.add(node);
+        return node;
+    }
+    static remove(seq, entry) {
+        const index = seq.items.indexOf(entry);
+        if (index !== -1)
+            seq.items.splice(index, 1);
+    }
+    custom() {
+        return this.seq(['properties', 'custom']);
+    }
+    topLevel() {
+        return this.seq(['top_level']);
+    }
+    // `folders` since 5.3.0; a root not yet migrated still keeps `collections`,
+    // and an edit lands where the document declares them rather than opening a
+    // second list beside it.
+    folders() {
+        const held = this.doc.getIn(['folders']);
+        if (isSeq(held))
+            return held;
+        const legacy = this.doc.getIn(['collections']);
+        if (isSeq(legacy))
+            return legacy;
+        return this.seq(['folders']);
+    }
+    collection(name) {
+        return FrameworkDoc.find(this.folders(), 'name', name);
+    }
+}
+// Every `applies_to` list in the document that names a collection.
+function renameAppliesTo(doc, from, to) {
+    let count = 0;
+    const blocks = [doc.doc.getIn(['properties', 'custom'])];
+    const tools = doc.doc.getIn(['properties', 'tools']);
+    if (isMap(tools))
+        for (const pair of tools.items)
+            blocks.push(pair.value);
+    for (const block of blocks) {
+        if (!isSeq(block))
+            continue;
+        for (const entry of block.items) {
+            if (!isMap(entry))
+                continue;
+            const applies = entry.get('applies_to', true);
+            if (isSeq(applies)) {
+                for (const item of applies.items) {
+                    if (isScalar(item) && String(item.value) === from) {
+                        item.value = to;
+                        count += 1;
+                    }
+                }
+            }
+            else if (isScalar(applies) && String(applies.value) === from) {
+                applies.value = to;
+                count += 1;
+            }
+        }
+    }
+    return count;
+}
+// ---- the files: frontmatter keys and links, one write per file -------------
+// Edits gathered per file before anything is written, so a key change and a
+// link rewrite on the same file land in one write.
+class Files {
+    root;
+    edits = new Map();
+    constructor(root) {
+        this.root = root;
+    }
+    load(file) {
+        let held = this.edits.get(file);
+        if (!held) {
+            held = { text: readFileSync(file, 'utf8'), steps: [] };
+            this.edits.set(file, held);
+        }
+        return held;
+    }
+    key(blueprint, op, key, extra = {}) {
+        const held = this.load(blueprint.path);
+        const before = blueprint.properties?.[key];
+        if (op === 'rename' && extra.to !== undefined) {
+            held.text = editFrontmatterKey(held.text, { kind: 'rename', key, to: extra.to });
+            held.steps.push({ kind: 'key', path: blueprint.rel, op, key, to: extra.to });
+        }
+        else if (op === 'set') {
+            held.text = editFrontmatterKey(held.text, { kind: 'set', key, value: extra.value ?? '' });
+            held.steps.push({ kind: 'key', path: blueprint.rel, op, key, before, after: extra.value ?? '' });
+        }
+        else if (op === 'delete') {
+            held.text = editFrontmatterKey(held.text, { kind: 'delete', key });
+            held.steps.push({ kind: 'key', path: blueprint.rel, op, key, before });
+        }
+    }
+    // Every markdown file in the root with its links rewritten for the moves.
+    links(moves) {
+        if (moves.length === 0)
+            return;
+        for (const file of markdownFiles(this.root)) {
+            const held = this.edits.get(file) ?? { text: readFileSync(file, 'utf8'), steps: [] };
+            const after = movePath(file, moves);
+            const result = rewriteLinks(held.text, file, after, moves);
+            if (result.count === 0)
+                continue;
+            held.text = result.text;
+            held.steps.push({ kind: 'links', path: rel(this.root, file), count: result.count });
+            this.edits.set(file, held);
+        }
+    }
+    steps() {
+        return [...this.edits.values()].flatMap((held) => held.steps);
+    }
+    files() {
+        return [...this.edits.keys()];
+    }
+    write() {
+        for (const [file, held] of this.edits) {
+            if (held.steps.length > 0)
+                writeFileSync(file, held.text, 'utf8');
+        }
+    }
+}
+const SKIPPED = new Set(['.git', 'node_modules', '.DS_Store']);
+function markdownFiles(dir) {
+    const out = [];
+    let entries = [];
+    try {
+        entries = readdirSync(dir).sort();
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (SKIPPED.has(entry))
+            continue;
+        const full = path.join(dir, entry);
+        let isDir = false;
+        try {
+            isDir = statSync(full).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir)
+            out.push(...markdownFiles(full));
+        else if (/\.md$/i.test(entry))
+            out.push(full);
+    }
+    return out;
+}
+function draft() {
+    return { steps: [], lost: [], conflicts: [], notes: [], destructive: false, actions: [] };
+}
+function finish(context, command, doc, files, work) {
+    const steps = [...files.steps(), ...work.steps];
+    if (doc && doc.changed())
+        steps.unshift({ kind: 'document', path: rel(context.root, doc.file), what: work.steps.filter((step) => step.kind === 'document').length > 0 ? '' : 'edited' });
+    const documentSteps = steps.filter((step) => step.kind === 'document');
+    // one line for the document, naming everything that changes in it
+    const merged = documentSteps.length > 1 ? [{ kind: 'document', path: rel(context.root, doc?.file ?? ''), what: documentSteps.map((step) => (step.kind === 'document' ? step.what : '')).filter((what) => what !== '' && what !== 'edited').join('; ') }, ...steps.filter((step) => step.kind !== 'document')] : steps;
+    return {
+        root: context.root,
+        command,
+        steps: merged,
+        lost: work.lost,
+        conflicts: work.conflicts,
+        notes: work.notes,
+        destructive: work.destructive || work.lost.length > 0,
+        apply: () => {
+            files.write();
+            for (const action of work.actions)
+                action();
+            if (doc && doc.changed())
+                doc.write();
+        },
+    };
+}
+// The plan as --json prints it: everything but the closure.
+export function planJson(plan) {
+    return { root: plan.root, command: plan.command, steps: plan.steps, lost: plan.lost, conflicts: plan.conflicts, notes: plan.notes, destructive: plan.destructive };
+}
+// Run a plan, then rewrite the index and check the root, reporting what the
+// run introduced: a finding (by file and code) the root did not have before,
+// with a file that moved followed to its new path.
+export function applyPlan(plan, standardVersion) {
+    const before = editContext(plan.root);
+    const was = checkRoot(before.framework, before.blueprints, { standardVersion });
+    plan.apply();
+    const after = editContext(plan.root);
+    buildIndexes(after.framework, after.blueprints, { check: false });
+    const reloaded = editContext(plan.root);
+    const report = checkRoot(reloaded.framework, reloaded.blueprints, { standardVersion });
+    const moves = plan.steps.flatMap((step) => (step.kind === 'move' ? [{ from: step.from.replace(/\/$/, ''), to: step.to.replace(/\/$/, '') }] : []));
+    const followed = (file) => {
+        if (file === null)
+            return null;
+        for (const move of moves) {
+            if (file === move.from)
+                return move.to;
+            if (file.startsWith(`${move.from}/`))
+                return `${move.to}/${file.slice(move.from.length + 1)}`;
+        }
+        return file;
+    };
+    const seen = new Set(was.findings.map((finding) => `${followed(finding.path)}|${finding.code}`));
+    const newFindings = report.findings.filter((finding) => !seen.has(`${finding.path}|${finding.code}`));
+    return { plan, newFindings, errors: report.errors, warnings: report.warnings };
+}
+function propertyOf(context, name) {
+    const custom = context.framework.schema.custom.find((property) => property.name === name);
+    if (custom)
+        return custom;
+    if (context.framework.schema.core.some((property) => property.name === name))
+        throw new EditError(`${name} is the standard's own; its block moves with eidos_version and is never edited here`);
+    const tool = Object.entries(context.framework.schema.tools).find(([, block]) => block.some((property) => property.name === name));
+    if (tool)
+        throw new EditError(`${name} is declared by ${tool[0]}, in its own block; only that tool writes there`);
+    throw new EditError(`no custom property '${name}' (eidos framework lists them)`);
+}
+function assertFreeName(context, name) {
+    if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(name))
+        throw new EditError(`'${name}' is not a frontmatter key: letters, digits, _ and -, no spaces`);
+    const every = [...context.framework.schema.core, ...context.framework.schema.custom, ...Object.values(context.framework.schema.tools).flat()];
+    if (every.some((property) => property.name === name))
+        throw new EditError(`a property named '${name}' already exists`);
+}
+function checkType(type) {
+    const known = PROPERTY_TYPES.find((candidate) => candidate.toLowerCase() === type.toLowerCase());
+    if (!known)
+        throw new EditError(`'${type}' is not one of the standard's types: ${PROPERTY_TYPES.join(', ')}`);
+    return known;
+}
+function resolveAppliesTo(context, given) {
+    if (given === 'all')
+        return 'all';
+    return given.map((name) => {
+        const collection = findCollection(context.framework, name);
+        if (!collection)
+            throw new EditError(`no collection '${name}' (declared: ${context.framework.collections.map((entry) => entry.name).join(', ')})`);
+        return collection.name;
+    });
+}
+const blank = (type) => (type.toLowerCase() === 'list' ? [] : '');
+// A declared list of options: non-empty, no repeats, on a Text or List
+// property; the standard's one refinement of a type.
+function checkOptions(type, options) {
+    const cleaned = [...new Set(options.map((option) => option.trim()).filter((option) => option !== ''))];
+    if (cleaned.length === 0)
+        throw new EditError('options must be a non-empty list of values (an open set is what no options already says)');
+    if (!['text', 'list'].includes(type.toLowerCase()))
+        throw new EditError(`options close a Text or List value; ${type} has none`);
+    return cleaned;
+}
+// `options` sits among the standard's six, before `meaning`, whether the
+// entry is written whole or the key is added to one already there.
+function setOptions(doc, entry, options) {
+    entry.delete('options');
+    if (options === null)
+        return;
+    const pair = doc.doc.createPair('options', options);
+    if (isSeq(pair.value))
+        pair.value.flow = true;
+    const at = entry.items.findIndex((item) => isScalar(item.key) && String(item.key.value) === 'meaning');
+    entry.items.splice(at === -1 ? entry.items.length : at, 0, pair);
+}
+// A blueprint value the new list does not hold, one conflict naming them
+// all: narrowing a list is retiring values, so the owner sees every one
+// before it leaves, and --force proceeds. Nothing is written to a blueprint;
+// check reports each afterwards.
+function surfaceOffList(context, work, name, property, options) {
+    const held = [];
+    for (const blueprint of context.blueprints) {
+        const problem = optionProblem({ ...property, options }, blueprint.properties?.[name]);
+        if (problem)
+            held.push(`${blueprint.rel}: ${problem.off.join(', ')}`);
+    }
+    if (held.length > 0)
+        work.conflicts.push({ message: `${held.length} blueprint${held.length === 1 ? ' carries' : 's carry'} a value off the list (${held.join('; ')}); check will report each, and --force declares it anyway`, force: true });
+}
+function inScope(blueprint, applies) {
+    return appliesTo({ name: '', type: 'Text', appliesTo: applies, required: false, meaning: '', core: false, owner: 'custom' }, blueprint.collection.name);
+}
+export function planPropertyAdd(context, spec) {
+    assertFreeName(context, spec.name);
+    const type = checkType(spec.type);
+    const applies = resolveAppliesTo(context, spec.appliesTo);
+    const options = spec.options ? checkOptions(type, spec.options) : null;
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const entry = doc.add(doc.custom(), { name: spec.name, type, applies_to: applies, ...(spec.required ? { required: true } : {}), meaning: spec.meaning });
+    if (options)
+        setOptions(doc, entry, options);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `properties.custom: add ${spec.name}` });
+    if (spec.required) {
+        for (const blueprint of context.blueprints) {
+            if (inScope(blueprint, applies) && blueprint.properties && !(spec.name in blueprint.properties))
+                files.key(blueprint, 'set', spec.name, { value: blank(type) });
+        }
+    }
+    return finish(context, `configure:property add ${spec.name}`, doc, files, work);
+}
+export function planPropertyRename(context, name, to) {
+    const property = propertyOf(context, name);
+    assertFreeName(context, to);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const entry = FrameworkDoc.find(doc.custom(), 'name', name);
+    if (!entry)
+        throw new EditError(`the document has no custom entry '${name}'`);
+    entry.set('name', to);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `properties.custom: ${name} → ${to}` });
+    for (const collection of context.framework.collections) {
+        if (collection.grouping?.property === name) {
+            const node = doc.collection(collection.name);
+            const grouping = node?.get('grouping', true);
+            if (isMap(grouping) && String(grouping.get('property') ?? '') === name) {
+                grouping.set('property', to);
+                work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `${collection.name}.grouping.property → ${to}` });
+            }
+        }
+    }
+    for (const blueprint of context.blueprints) {
+        if (blueprint.properties && name in blueprint.properties)
+            files.key(blueprint, 'rename', name, { to });
+    }
+    renameInSettings(context, work, name, to);
+    void property;
+    return finish(context, `configure:property rename ${name} ${to}`, doc, files, work);
+}
+// This CLI's own references to a property: on-save rules and hidden columns.
+function renameInSettings(context, work, name, to) {
+    const settings = readSettings(context.root);
+    const rules = settings.shared.on_save.filter((rule) => rule.property === name);
+    if (rules.length > 0) {
+        work.steps.push({ kind: 'settings', path: settings.files.shared, what: to ? `on_save: ${name} → ${to}` : `on_save: drop the rule on ${name}` });
+        work.actions.push(() => writeSettings(context.root, { shared: { on_save: readSettings(context.root).shared.on_save.flatMap((rule) => (rule.property === name ? (to ? [{ ...rule, property: to }] : []) : [rule])) } }));
+    }
+    const columns = Object.entries(settings.local.tables.columns).filter(([, hidden]) => hidden.includes(name));
+    if (columns.length > 0) {
+        work.steps.push({ kind: 'settings', path: settings.files.local, what: to ? `tables.columns: ${name} → ${to}` : `tables.columns: drop ${name}` });
+        work.actions.push(() => {
+            const current = readSettings(context.root).local.tables.columns;
+            const next = {};
+            for (const [collection, hidden] of Object.entries(current))
+                next[collection] = hidden.flatMap((key) => (key === name ? (to ? [to] : []) : [key]));
+            writeSettings(context.root, { local: { tables: { columns: next } } });
+        });
+    }
+}
+export function planPropertySet(context, name, changes, options) {
+    const property = propertyOf(context, name);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const entry = FrameworkDoc.find(doc.custom(), 'name', name);
+    if (!entry)
+        throw new EditError(`the document has no custom entry '${name}'`);
+    const what = [];
+    const type = changes.type !== undefined ? checkType(changes.type) : property.type;
+    if (changes.type !== undefined && type !== property.type) {
+        entry.set('type', type);
+        what.push(`type ${property.type} → ${type}`);
+    }
+    if (changes.meaning !== undefined && changes.meaning !== property.meaning) {
+        entry.set('meaning', changes.meaning);
+        what.push('meaning');
+    }
+    const applies = changes.appliesTo !== undefined ? resolveAppliesTo(context, changes.appliesTo) : property.appliesTo;
+    if (changes.appliesTo !== undefined) {
+        entry.set('applies_to', applies === 'all' ? 'all' : doc.doc.createNode(applies));
+        what.push(`applies_to → ${applies === 'all' ? 'all' : applies.join(', ')}`);
+        for (const blueprint of context.blueprints) {
+            if (!blueprint.properties || !(name in blueprint.properties) || inScope(blueprint, applies))
+                continue;
+            if (options.preserve)
+                continue;
+            if (!isEmpty(blueprint.properties[name]))
+                work.lost.push({ path: blueprint.rel, key: name, value: blueprint.properties[name] });
+            files.key(blueprint, 'delete', name);
+        }
+    }
+    const required = changes.required ?? property.required;
+    if (changes.required !== undefined && required !== property.required) {
+        if (required)
+            entry.set('required', true);
+        else
+            entry.delete('required');
+        what.push(required ? 'required' : 'optional');
+        if (required) {
+            for (const blueprint of context.blueprints) {
+                if (inScope(blueprint, applies) && blueprint.properties && !(name in blueprint.properties))
+                    files.key(blueprint, 'set', name, { value: blank(type) });
+            }
+        }
+    }
+    const held = property.options ?? null;
+    if (changes.options === null && held !== null) {
+        setOptions(doc, entry, null);
+        what.push('options dropped: any value is valid again');
+    }
+    else if (changes.options !== undefined && changes.options !== null) {
+        const options = checkOptions(type, changes.options);
+        if (held === null || options.join('\u0000') !== held.join('\u0000')) {
+            setOptions(doc, entry, options);
+            what.push(`options ${held === null ? 'declared' : '→'} ${options.join(', ')}`);
+            // declaring a list, or narrowing one, changes what conforms; widening touches nothing
+            if (held === null || held.some((option) => !options.includes(option)))
+                surfaceOffList(context, work, name, property, options);
+        }
+    }
+    else if (held !== null && !['text', 'list'].includes(type.toLowerCase())) {
+        throw new EditError(`${name} declares options, which a ${type} cannot hold; drop them with --open first`);
+    }
+    if (what.length === 0)
+        throw new EditError(`nothing to change on '${name}'`);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `properties.custom ${name}: ${what.join(', ')}` });
+    return finish(context, `configure:property set ${name}`, doc, files, work);
+}
+export function planPropertyRemap(context, name, pairs) {
+    const property = propertyOf(context, name);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const entry = FrameworkDoc.find(doc.custom(), 'name', name);
+    const styles = entry?.getIn(['eidosmd', 'canvas', 'styles'], true);
+    let options = property.options ?? null;
+    for (const [from, to] of pairs) {
+        for (const blueprint of context.blueprints) {
+            if (propertyString(blueprint, name) === from)
+                files.key(blueprint, 'set', name, { value: to });
+        }
+        // a value the list declares follows its rename, so the list still holds what the blueprints say
+        if (options && entry && options.includes(from) && !options.includes(to)) {
+            options = options.map((option) => (option === from ? to : option));
+            setOptions(doc, entry, options);
+            work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `${name}: option ${from} → ${to}` });
+        }
+        if (isMap(styles) && styles.has(from)) {
+            const pair = styles.items.find((item) => isScalar(item.key) && String(item.key.value) === from);
+            if (pair && isScalar(pair.key)) {
+                pair.key.value = to;
+                work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `${name}: canvas style ${from} → ${to}` });
+            }
+        }
+    }
+    return finish(context, `configure:property remap ${name}`, doc, files, work);
+}
+export function planPropertyRemove(context, name, options) {
+    propertyOf(context, name);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const entry = FrameworkDoc.find(doc.custom(), 'name', name);
+    if (!entry)
+        throw new EditError(`the document has no custom entry '${name}'`);
+    FrameworkDoc.remove(doc.custom(), entry);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `properties.custom: remove ${name}` });
+    for (const collection of context.framework.collections) {
+        if (collection.grouping?.property === name) {
+            const grouping = doc.collection(collection.name)?.get('grouping', true);
+            if (isMap(grouping) && grouping.has('property')) {
+                grouping.delete('property');
+                work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `${collection.name}.grouping.property dropped` });
+            }
+        }
+    }
+    for (const blueprint of context.blueprints) {
+        if (!blueprint.properties || !(name in blueprint.properties))
+            continue;
+        if (!isEmpty(blueprint.properties[name]))
+            work.lost.push({ path: blueprint.rel, key: name, value: blueprint.properties[name] });
+        if (!options.preserve)
+            files.key(blueprint, 'delete', name);
+    }
+    if (options.preserve && work.lost.length > 0)
+        work.notes.push(`--preserve leaves ${name} in ${work.lost.length} file(s), which check will report as property-unknown`);
+    renameInSettings(context, work, name, null);
+    return finish(context, `configure:property remove ${name}`, doc, files, work);
+}
+// ---- collections ------------------------------------------------------------
+function collectionOf(context, name) {
+    const collection = findCollection(context.framework, name);
+    if (!collection)
+        throw new EditError(`no collection '${name}' (declared: ${context.framework.collections.map((entry) => entry.name).join(', ')})`);
+    return collection;
+}
+const templatePath = (unit, variant) => `templates/${kebab(unit)}.${kebab(variant)}.md`;
+const BARE_TEMPLATE = '# {{title}}\n\n## Intent\n\n_Why this exists: the problem and who has it._\n';
+// A folder name is taken by any folder the document declares, whatever its type.
+function folderTaken(context, name) {
+    return context.framework.folders.some((folder) => folder.name.toLowerCase() === name.toLowerCase() || kebab(folder.name) === kebab(name));
+}
+export function planCollectionAdd(context, spec) {
+    const name = convert(spec.name, context.framework.naming);
+    if (folderTaken(context, name))
+        throw new EditError(`a folder named '${name}' is already declared`);
+    if (!/^[A-Za-z0-9][A-Za-z0-9 _-]*$/.test(name))
+        throw new EditError(`'${name}' is not a folder name`);
+    const unit = kebab(spec.unit);
+    if (unit === '')
+        throw new EditError('a collection needs a unit, the word for one of its blueprints (spec, chapter, decision)');
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const template = templatePath(unit, 'default');
+    const templateFile = path.join(context.root, FRAMEWORK_DIR, template);
+    const folder = path.join(context.root, name);
+    doc.add(doc.folders(), { name, type: 'collection', ...(spec.description ? { description: spec.description } : {}), variants: [{ name: 'default', template, default: true }], ...(spec.grouping ? { grouping: { label: spec.grouping, groups: [] } } : {}) });
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `folders: add ${name} (collection, unit ${unit})` });
+    if (existsSync(templateFile))
+        work.notes.push(`${rel(context.root, templateFile)} already exists and is kept as it is`);
+    else {
+        work.steps.push({ kind: 'write', path: rel(context.root, templateFile), what: 'the default variant\'s template: a title and an Intent section' });
+        work.actions.push(() => {
+            mkdirSync(path.dirname(templateFile), { recursive: true });
+            writeFileSync(templateFile, BARE_TEMPLATE, 'utf8');
+        });
+    }
+    if (!existsSync(folder)) {
+        work.steps.push({ kind: 'write', path: `${name}/`, what: 'the collection folder' });
+        work.actions.push(() => mkdirSync(folder, { recursive: true }));
+    }
+    return finish(context, `configure:collection add ${name}`, doc, files, work);
+}
+export function planCollectionRename(context, name, to, unit) {
+    const collection = collectionOf(context, name);
+    const target = convert(to, context.framework.naming);
+    if (target !== collection.name && folderTaken(context, target))
+        throw new EditError(`a folder named '${target}' is already declared`);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const node = doc.collection(collection.name);
+    if (!node)
+        throw new EditError(`the document has no collection '${collection.name}'`);
+    const moves = [];
+    if (target !== collection.name) {
+        node.set('name', target);
+        const count = renameAppliesTo(doc, collection.name, target);
+        work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `folders: ${collection.name} → ${target}${count > 0 ? `; applies_to in ${count} propert${count === 1 ? 'y' : 'ies'}` : ''}` });
+        const from = path.join(context.root, collection.name);
+        const dest = path.join(context.root, target);
+        if (existsSync(dest))
+            work.conflicts.push({ message: `${target}/ already exists`, force: false });
+        else if (existsSync(from)) {
+            moves.push({ from, to: dest });
+            work.steps.push({ kind: 'move', from: `${collection.name}/`, to: `${target}/` });
+            work.actions.push(() => moveFile(context.root, from, dest));
+        }
+        const columns = readSettings(context.root).local.tables.columns;
+        if (columns[collection.name]) {
+            work.steps.push({ kind: 'settings', path: readSettings(context.root).files.local, what: `tables.columns: ${collection.name} → ${target}` });
+            work.actions.push(() => {
+                const current = { ...readSettings(context.root).local.tables.columns };
+                current[target] = current[collection.name] ?? [];
+                // null drops the old entry on the merge
+                current[collection.name] = null;
+                writeSettings(context.root, { local: { tables: { columns: current } } });
+            });
+        }
+    }
+    if (unit !== null) {
+        const nextUnit = kebab(unit);
+        const variants = node.get('variants', true);
+        if (isSeq(variants)) {
+            for (const variant of variants.items) {
+                if (!isMap(variant))
+                    continue;
+                const held = String(variant.get('template') ?? '');
+                const variantName = String(variant.get('name') ?? '');
+                const next = templatePath(nextUnit, variantName);
+                if (held === next)
+                    continue;
+                variant.set('template', next);
+                const from = path.join(context.root, FRAMEWORK_DIR, held);
+                const dest = path.join(context.root, FRAMEWORK_DIR, next);
+                if (existsSync(dest))
+                    work.conflicts.push({ message: `${rel(context.root, dest)} already exists`, force: false });
+                else if (existsSync(from)) {
+                    moves.push({ from, to: dest });
+                    work.steps.push({ kind: 'move', from: rel(context.root, from), to: rel(context.root, dest) });
+                    work.actions.push(() => moveFile(context.root, from, dest));
+                }
+            }
+            work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `${target}: unit → ${nextUnit}` });
+        }
+    }
+    if (moves.length === 0 && !doc.changed())
+        throw new EditError('nothing to rename');
+    files.links(moves);
+    return finish(context, `configure:collection rename ${collection.name} ${target}`, doc, files, work);
+}
+export function planCollectionRemove(context, name, options) {
+    const collection = collectionOf(context, name);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const node = doc.collection(collection.name);
+    if (!node)
+        throw new EditError(`the document has no collection '${collection.name}'`);
+    FrameworkDoc.remove(doc.folders(), node);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `folders: remove ${collection.name}` });
+    const index = doc.doc.getIn(['index']);
+    if (isMap(index) && index.has(collection.name))
+        index.delete(collection.name);
+    for (const variant of collection.variants) {
+        const file = path.join(context.root, FRAMEWORK_DIR, variant.template);
+        if (existsSync(file)) {
+            work.steps.push({ kind: 'remove', path: rel(context.root, file), what: `the ${variant.name} variant's template` });
+            work.actions.push(() => rmSync(file, { force: true }));
+        }
+    }
+    // a property scoped only to this collection goes with it, its values shown
+    for (const property of context.framework.schema.custom) {
+        if (property.appliesTo === 'all' || !property.appliesTo.some((entry) => entry.toLowerCase() === collection.name.toLowerCase()))
+            continue;
+        const remaining = property.appliesTo.filter((entry) => entry.toLowerCase() !== collection.name.toLowerCase());
+        const entry = FrameworkDoc.find(doc.custom(), 'name', property.name);
+        if (!entry)
+            continue;
+        if (remaining.length === 0) {
+            FrameworkDoc.remove(doc.custom(), entry);
+            work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `properties.custom: remove ${property.name} (applied only to ${collection.name})` });
+            for (const blueprint of context.blueprints) {
+                if (blueprint.collection !== collection && blueprint.properties && property.name in blueprint.properties) {
+                    if (!isEmpty(blueprint.properties[property.name]))
+                        work.lost.push({ path: blueprint.rel, key: property.name, value: blueprint.properties[property.name] });
+                    if (!options.preserve)
+                        files.key(blueprint, 'delete', property.name);
+                }
+            }
+        }
+        else {
+            entry.set('applies_to', doc.doc.createNode(remaining));
+        }
+    }
+    const folder = path.join(context.root, collection.name);
+    const own = context.blueprints.filter((blueprint) => blueprint.collection === collection);
+    if (existsSync(folder)) {
+        if (options.preserve)
+            work.notes.push(`--preserve leaves ${collection.name}/ with ${own.length} blueprint(s), which check will report as folder-undeclared`);
+        else {
+            for (const blueprint of own) {
+                work.steps.push({ kind: 'remove', path: blueprint.rel, what: 'a blueprint' });
+                for (const [key, value] of Object.entries(blueprint.properties ?? {}))
+                    if (!isEmpty(value))
+                        work.lost.push({ path: blueprint.rel, key, value });
+            }
+            work.steps.push({ kind: 'remove', path: `${collection.name}/`, what: 'the collection folder' });
+            work.destructive = own.length > 0;
+            work.actions.push(() => rmSync(folder, { recursive: true, force: true }));
+        }
+    }
+    return finish(context, `configure:collection remove ${collection.name}`, doc, files, work);
+}
+// ---- folders that are not collections (assets, other) -----------------------
+function folderOf(context, name) {
+    const found = context.framework.folders.find((folder) => !isCollection(folder) && (folder.name.toLowerCase() === name.toLowerCase() || kebab(folder.name) === kebab(name)));
+    if (found)
+        return found;
+    if (findCollection(context.framework, name))
+        throw new EditError(`'${name}' is a collection; configure:collection edits it`);
+    const declared = context.framework.folders.filter((folder) => !isCollection(folder)).map((folder) => folder.name);
+    throw new EditError(`no assets or other folder '${name}' (declared: ${declared.join(', ') || 'none'})`);
+}
+// Every file under a folder, whatever its kind: what a remove lists before it asks.
+function filesUnder(dir) {
+    const out = [];
+    let entries = [];
+    try {
+        entries = readdirSync(dir).sort();
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry);
+        let isDir = false;
+        try {
+            isDir = statSync(full).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir)
+            out.push(...filesUnder(full));
+        else
+            out.push(full);
+    }
+    return out;
+}
+export function planFolderAdd(context, spec) {
+    const name = convert(spec.name, context.framework.naming);
+    if (folderTaken(context, name))
+        throw new EditError(`a folder named '${name}' is already declared`);
+    if (!/^[A-Za-z0-9][A-Za-z0-9 _-]*$/.test(name))
+        throw new EditError(`'${name}' is not a folder name`);
+    const doc = new FrameworkDoc(context.framework);
+    const work = draft();
+    doc.add(doc.folders(), { name, type: spec.type, description: spec.description.trim() });
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `folders: add ${name} (${spec.type})` });
+    const folder = path.join(context.root, name);
+    if (!existsSync(folder)) {
+        work.steps.push({ kind: 'write', path: `${name}/`, what: `the ${spec.type} folder` });
+        work.actions.push(() => mkdirSync(folder, { recursive: true }));
+    }
+    else {
+        work.notes.push(`${name}/ already exists and is declared as it is`);
+    }
+    return finish(context, `configure:folder add ${name}`, doc, new Files(context.root), work);
+}
+export function planFolderRename(context, name, to) {
+    const folder = folderOf(context, name);
+    const target = convert(to, context.framework.naming);
+    if (target === folder.name)
+        throw new EditError('nothing to rename');
+    if (folderTaken(context, target))
+        throw new EditError(`a folder named '${target}' is already declared`);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const node = FrameworkDoc.find(doc.folders(), 'name', folder.name);
+    if (!node)
+        throw new EditError(`the document has no folder '${folder.name}'`);
+    node.set('name', target);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `folders: ${folder.name} → ${target}` });
+    const from = path.join(context.root, folder.name);
+    const dest = path.join(context.root, target);
+    const moves = [];
+    if (existsSync(dest))
+        work.conflicts.push({ message: `${target}/ already exists`, force: false });
+    else if (existsSync(from)) {
+        moves.push({ from, to: dest });
+        work.steps.push({ kind: 'move', from: `${folder.name}/`, to: `${target}/` });
+        work.actions.push(() => moveFile(context.root, from, dest));
+    }
+    files.links(moves);
+    return finish(context, `configure:folder rename ${folder.name} ${target}`, doc, files, work);
+}
+export function planFolderSet(context, name, changes) {
+    const folder = folderOf(context, name);
+    const doc = new FrameworkDoc(context.framework);
+    const work = draft();
+    const node = FrameworkDoc.find(doc.folders(), 'name', folder.name);
+    if (!node)
+        throw new EditError(`the document has no folder '${folder.name}'`);
+    const what = [];
+    if (changes.type !== undefined && changes.type !== folder.type) {
+        node.set('type', changes.type);
+        what.push(`type → ${changes.type}`);
+    }
+    if (changes.description !== undefined) {
+        node.set('description', changes.description.trim());
+        what.push('description');
+    }
+    if (!doc.changed())
+        throw new EditError(`nothing to change on '${folder.name}'`);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `folders ${folder.name}: ${what.join('; ')}` });
+    return finish(context, `configure:folder set ${folder.name}`, doc, new Files(context.root), work);
+}
+// The entry goes and, unless preserved, the folder with every file in it,
+// each listed: a folder with files needs a person's yes or --force.
+export function planFolderRemove(context, name, options) {
+    const folder = folderOf(context, name);
+    const doc = new FrameworkDoc(context.framework);
+    const work = draft();
+    const node = FrameworkDoc.find(doc.folders(), 'name', folder.name);
+    if (!node)
+        throw new EditError(`the document has no folder '${folder.name}'`);
+    FrameworkDoc.remove(doc.folders(), node);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `folders: remove ${folder.name}` });
+    const dir = path.join(context.root, folder.name);
+    if (existsSync(dir)) {
+        const held = filesUnder(dir);
+        if (options.preserve)
+            work.notes.push(`--preserve leaves ${folder.name}/ with ${held.length} file(s), which check will report as folder-undeclared`);
+        else {
+            for (const file of held)
+                work.steps.push({ kind: 'remove', path: rel(context.root, file), what: 'a file' });
+            work.steps.push({ kind: 'remove', path: `${folder.name}/`, what: `the ${folder.type} folder` });
+            work.destructive = held.length > 0;
+            work.actions.push(() => rmSync(dir, { recursive: true, force: true }));
+        }
+    }
+    return finish(context, `configure:folder remove ${folder.name}`, doc, new Files(context.root), work);
+}
+// ---- groups -----------------------------------------------------------------
+function groupingOf(doc, collection) {
+    const node = doc.collection(collection.name);
+    const grouping = node?.get('grouping', true);
+    if (!isMap(grouping))
+        throw new EditError(`${collection.name} declares no grouping; add one under Framework Settings → Collections, or with configure:collection`);
+    return grouping;
+}
+function groupOf(collection, name) {
+    const found = collection.grouping?.groups.find((group) => group.name.toLowerCase() === name.toLowerCase() || kebab(group.name) === kebab(name));
+    if (!found)
+        throw new EditError(`no group '${name}' under ${collection.name}${collection.grouping ? ` (declared: ${collection.grouping.groups.map((group) => group.name).join(', ') || 'none'})` : ''}`);
+    return found.name;
+}
+export function planGroupAdd(context, collectionName, name, description) {
+    const collection = collectionOf(context, collectionName);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const grouping = groupingOf(doc, collection);
+    const groupName = convert(name, context.framework.naming);
+    if (collection.grouping?.groups.some((group) => group.name.toLowerCase() === groupName.toLowerCase()))
+        throw new EditError(`${collection.name} already has a group '${groupName}'`);
+    const held = grouping.get('groups');
+    let groups;
+    if (isSeq(held))
+        groups = held;
+    else {
+        groups = doc.doc.createNode([]);
+        grouping.set('groups', groups);
+    }
+    doc.add(groups, { name: groupName, ...(description ? { description } : {}) });
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `${collection.name}.grouping.groups: add ${groupName}` });
+    const folder = path.join(context.root, collection.name, groupName);
+    if (!existsSync(folder)) {
+        work.steps.push({ kind: 'write', path: `${collection.name}/${groupName}/`, what: 'the group folder' });
+        work.actions.push(() => mkdirSync(folder, { recursive: true }));
+    }
+    return finish(context, `configure:group add ${collection.name} ${groupName}`, doc, files, work);
+}
+export function planGroupRename(context, collectionName, name, to) {
+    const collection = collectionOf(context, collectionName);
+    const groupName = groupOf(collection, name);
+    const target = convert(to, context.framework.naming);
+    if (collection.grouping?.groups.some((group) => group.name.toLowerCase() === target.toLowerCase()))
+        throw new EditError(`${collection.name} already has a group '${target}'`);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const grouping = groupingOf(doc, collection);
+    const held = grouping.get('groups');
+    const entry = FrameworkDoc.find(isSeq(held) ? held : null, 'name', groupName);
+    if (entry)
+        entry.set('name', target);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `${collection.name}.grouping.groups: ${groupName} → ${target}` });
+    const property = collection.grouping?.property ?? null;
+    for (const blueprint of context.blueprints) {
+        if (blueprint.collection === collection && blueprint.group === groupName && property && blueprint.properties && property in blueprint.properties)
+            files.key(blueprint, 'set', property, { value: target });
+    }
+    const from = path.join(context.root, collection.name, groupName);
+    const dest = path.join(context.root, collection.name, target);
+    const moves = [];
+    if (existsSync(dest))
+        work.conflicts.push({ message: `${collection.name}/${target}/ already exists`, force: false });
+    else if (existsSync(from)) {
+        moves.push({ from, to: dest });
+        work.steps.push({ kind: 'move', from: `${collection.name}/${groupName}/`, to: `${collection.name}/${target}/` });
+        work.actions.push(() => moveFile(context.root, from, dest));
+    }
+    files.links(moves);
+    return finish(context, `configure:group rename ${collection.name} ${groupName} ${target}`, doc, files, work);
+}
+export function planGroupRemove(context, collectionName, name, options) {
+    const collection = collectionOf(context, collectionName);
+    const groupName = groupOf(collection, name);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const grouping = groupingOf(doc, collection);
+    const groups = grouping.get('groups');
+    const entry = isSeq(groups) ? FrameworkDoc.find(groups, 'name', groupName) : null;
+    if (entry && isSeq(groups))
+        FrameworkDoc.remove(groups, entry);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `${collection.name}.grouping.groups: remove ${groupName}` });
+    const folder = path.join(context.root, collection.name, groupName);
+    const own = context.blueprints.filter((blueprint) => blueprint.collection === collection && blueprint.group === groupName);
+    if (existsSync(folder)) {
+        if (options.preserve)
+            work.notes.push(`--preserve leaves ${collection.name}/${groupName}/ with ${own.length} blueprint(s), which check will report as group-undeclared`);
+        else {
+            for (const blueprint of own) {
+                work.steps.push({ kind: 'remove', path: blueprint.rel, what: 'a blueprint' });
+                for (const [key, value] of Object.entries(blueprint.properties ?? {}))
+                    if (!isEmpty(value))
+                        work.lost.push({ path: blueprint.rel, key, value });
+            }
+            work.steps.push({ kind: 'remove', path: `${collection.name}/${groupName}/`, what: 'the group folder' });
+            work.destructive = own.length > 0;
+            work.actions.push(() => rmSync(folder, { recursive: true, force: true }));
+        }
+    }
+    return finish(context, `configure:group remove ${collection.name} ${groupName}`, doc, files, work);
+}
+// ---- variants ---------------------------------------------------------------
+function variantsSeq(doc, collection) {
+    const node = doc.collection(collection.name);
+    const variants = node?.get('variants', true);
+    if (!isSeq(variants))
+        throw new EditError(`${collection.name} declares no variants list in the document`);
+    return variants;
+}
+export function planVariantAdd(context, collectionName, name, description, from) {
+    const collection = collectionOf(context, collectionName);
+    const variantName = kebab(name);
+    if (variantName === '')
+        throw new EditError('a variant needs a name');
+    if (findVariant(collection, variantName))
+        throw new EditError(`${collection.name} already has a variant '${variantName}'`);
+    const unit = unitOf(collection);
+    if (!unit)
+        throw new EditError(`${collection.name} has no unit yet: its first variant's template names it (templates/<unit>.<variant>.md)`);
+    const source = from ? findVariant(collection, from) : defaultVariant(collection);
+    if (from && !source)
+        throw new EditError(`no variant '${from}' in ${collection.name}`);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const template = templatePath(unit, variantName);
+    doc.add(variantsSeq(doc, collection), { name: variantName, template, ...(description ? { description } : {}) });
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `${collection.name}.variants: add ${variantName}` });
+    const file = path.join(context.root, FRAMEWORK_DIR, template);
+    const sourceFile = source ? path.join(context.root, FRAMEWORK_DIR, source.template) : null;
+    if (existsSync(file))
+        work.notes.push(`${rel(context.root, file)} already exists and is kept as it is`);
+    else {
+        work.steps.push({ kind: 'write', path: rel(context.root, file), what: sourceFile && existsSync(sourceFile) ? `a copy of ${source?.name}'s template` : 'a bare template' });
+        work.actions.push(() => {
+            mkdirSync(path.dirname(file), { recursive: true });
+            if (sourceFile && existsSync(sourceFile))
+                cpSync(sourceFile, file);
+            else
+                writeFileSync(file, BARE_TEMPLATE, 'utf8');
+        });
+    }
+    return finish(context, `configure:variant add ${collection.name} ${variantName}`, doc, files, work);
+}
+export function planVariantRename(context, collectionName, name, to) {
+    const collection = collectionOf(context, collectionName);
+    const variant = findVariant(collection, name);
+    if (!variant)
+        throw new EditError(`no variant '${name}' in ${collection.name}`);
+    const target = kebab(to);
+    if (findVariant(collection, target))
+        throw new EditError(`${collection.name} already has a variant '${target}'`);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const entry = FrameworkDoc.find(variantsSeq(doc, collection), 'name', variant.name);
+    if (!entry)
+        throw new EditError(`the document has no variant '${variant.name}'`);
+    const template = templatePath(variant.unit || unitOf(collection) || kebab(collection.name), target);
+    entry.set('name', target);
+    entry.set('template', template);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `${collection.name}.variants: ${variant.name} → ${target}` });
+    const from = path.join(context.root, FRAMEWORK_DIR, variant.template);
+    const dest = path.join(context.root, FRAMEWORK_DIR, template);
+    if (existsSync(dest))
+        work.conflicts.push({ message: `${rel(context.root, dest)} already exists`, force: false });
+    else if (existsSync(from)) {
+        work.steps.push({ kind: 'move', from: rel(context.root, from), to: rel(context.root, dest) });
+        work.actions.push(() => moveFile(context.root, from, dest));
+    }
+    for (const blueprint of context.blueprints) {
+        if (blueprint.collection === collection && propertyString(blueprint, 'variant')?.toLowerCase() === variant.name.toLowerCase())
+            files.key(blueprint, 'set', 'variant', { value: target });
+    }
+    return finish(context, `configure:variant rename ${collection.name} ${variant.name} ${target}`, doc, files, work);
+}
+export function planVariantSetDefault(context, collectionName, name) {
+    const collection = collectionOf(context, collectionName);
+    const variant = findVariant(collection, name);
+    if (!variant)
+        throw new EditError(`no variant '${name}' in ${collection.name}`);
+    if (variant.isDefault)
+        throw new EditError(`${variant.name} is already the default`);
+    const doc = new FrameworkDoc(context.framework);
+    const work = draft();
+    for (const item of variantsSeq(doc, collection).items) {
+        if (!isMap(item))
+            continue;
+        if (String(item.get('name') ?? '') === variant.name)
+            item.set('default', true);
+        else if (item.has('default'))
+            item.delete('default');
+    }
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `${collection.name}.variants: default → ${variant.name}` });
+    return finish(context, `configure:variant set-default ${collection.name} ${variant.name}`, doc, new Files(context.root), work);
+}
+export function planVariantRemove(context, collectionName, name, options) {
+    const collection = collectionOf(context, collectionName);
+    const variant = findVariant(collection, name);
+    if (!variant)
+        throw new EditError(`no variant '${name}' in ${collection.name}`);
+    if (variant.isDefault && collection.variants.length > 1)
+        throw new EditError(`${variant.name} is ${collection.name}'s default; set another with configure:variant set-default first`);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const seq = variantsSeq(doc, collection);
+    const entry = FrameworkDoc.find(seq, 'name', variant.name);
+    if (entry)
+        FrameworkDoc.remove(seq, entry);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `${collection.name}.variants: remove ${variant.name}` });
+    const on = context.blueprints.filter((blueprint) => blueprint.collection === collection && propertyString(blueprint, 'variant')?.toLowerCase() === variant.name.toLowerCase());
+    if (on.length > 0) {
+        work.conflicts.push({ message: `${on.length} blueprint(s) name the variant ${variant.name}: ${on.map((blueprint) => blueprint.rel).join(', ')}; --force clears their variant so they follow the default`, force: true });
+        if (options.force)
+            for (const blueprint of on)
+                files.key(blueprint, 'delete', 'variant');
+    }
+    const file = path.join(context.root, FRAMEWORK_DIR, variant.template);
+    if (existsSync(file)) {
+        work.steps.push({ kind: 'remove', path: rel(context.root, file), what: 'its template' });
+        work.actions.push(() => rmSync(file, { force: true }));
+    }
+    return finish(context, `configure:variant remove ${collection.name} ${variant.name}`, doc, files, work);
+}
+function termEntry(doc, term) {
+    const vocabulary = doc.doc.getIn(['vocabulary']);
+    if (!isSeq(vocabulary))
+        return null;
+    for (const item of vocabulary.items) {
+        if (isMap(item) && String(item.get('term') ?? '').toLowerCase() === term.toLowerCase())
+            return item;
+    }
+    return null;
+}
+export function planTermAdd(context, spec) {
+    if (spec.term.trim() === '')
+        throw new EditError('a term needs a word');
+    if (context.framework.vocabulary.some((entry) => entry.term.toLowerCase() === spec.term.toLowerCase()))
+        throw new EditError(`the Vocabulary already declares '${spec.term}'`);
+    const doc = new FrameworkDoc(context.framework);
+    const work = draft();
+    doc.add(doc.seq(['vocabulary']), { term: spec.term, means: spec.means, not: spec.not, ...(spec.see ? { see: spec.see } : {}) });
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `vocabulary: add ${spec.term}` });
+    return finish(context, `configure:term add ${spec.term}`, doc, new Files(context.root), work);
+}
+export function planTermSet(context, term, changes) {
+    const doc = new FrameworkDoc(context.framework);
+    const entry = termEntry(doc, term);
+    if (!entry)
+        throw new EditError(`the Vocabulary declares no term '${term}'`);
+    const work = draft();
+    const what = [];
+    if (changes.term !== undefined && changes.term !== term) {
+        if (context.framework.vocabulary.some((held) => held.term.toLowerCase() === changes.term?.toLowerCase()))
+            throw new EditError(`the Vocabulary already declares '${changes.term}'`);
+        entry.set('term', changes.term);
+        what.push(`term → ${changes.term}`);
+    }
+    if (changes.means !== undefined) {
+        entry.set('means', changes.means);
+        what.push('means');
+    }
+    if (changes.not !== undefined) {
+        entry.set('not', doc.doc.createNode(changes.not));
+        what.push('not');
+    }
+    if (changes.see !== undefined) {
+        if (changes.see === null || changes.see === '')
+            entry.delete('see');
+        else
+            entry.set('see', changes.see);
+        what.push('see');
+    }
+    if (what.length === 0)
+        throw new EditError(`nothing to change on '${term}'`);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `vocabulary ${term}: ${what.join(', ')}` });
+    return finish(context, `configure:term set ${term}`, doc, new Files(context.root), work);
+}
+export function planTermRemove(context, term) {
+    const doc = new FrameworkDoc(context.framework);
+    const entry = termEntry(doc, term);
+    if (!entry)
+        throw new EditError(`the Vocabulary declares no term '${term}'`);
+    const work = draft();
+    FrameworkDoc.remove(doc.seq(['vocabulary']), entry);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `vocabulary: remove ${term}` });
+    return finish(context, `configure:term remove ${term}`, doc, new Files(context.root), work);
+}
+// ---- top-level docs -----------------------------------------------------------
+// A top-level doc's file is named for its title in the root's convention, so
+// what a person sees in the file system is what the page calls it, the
+// convention's casing apart; a title change renames the file, a README
+// included.
+export function docFileName(title, naming) {
+    return `${convert(title.trim(), naming)}.md`;
+}
+// One `top_level` entry as declared, by title (case-insensitive) or by its file name.
+function docOf(context, ref) {
+    const wanted = ref.trim().toLowerCase();
+    const held = context.framework.topLevel.find((doc) => doc.title.toLowerCase() === wanted || path.basename(doc.path).toLowerCase() === wanted || path.basename(doc.path).toLowerCase() === `${wanted}.md`);
+    if (!held)
+        throw new EditError(`no top-level doc '${ref}' (eidos framework lists them)`);
+    return { title: held.title, path: held.path, file: path.resolve(path.dirname(context.framework.file), held.path) };
+}
+// Files moved, every link in the root following: what a plan does through its
+// Files and actions, done at once for the browser, which saves the framework
+// document itself and only needs the files to follow.
+export function moveWithLinks(root, moves) {
+    const files = new Files(root);
+    files.links(moves);
+    files.write();
+    for (const move of moves)
+        if (existsSync(move.from) && !existsSync(move.to))
+            moveFile(root, move.from, move.to);
+}
+export function planDocAdd(context, title, description) {
+    const clean = title.trim();
+    if (clean === '')
+        throw new EditError('a top-level doc needs a title');
+    if (context.framework.topLevel.some((doc) => doc.title.toLowerCase() === clean.toLowerCase()))
+        throw new EditError(`a top-level doc titled '${clean}' is already declared`);
+    const name = docFileName(clean, context.framework.naming);
+    const doc = new FrameworkDoc(context.framework);
+    const work = draft();
+    doc.add(doc.topLevel(), { title: clean, path: `../${name}`, description: description.trim() });
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `top_level: add ${clean} (${name})` });
+    const file = path.join(context.root, name);
+    if (!existsSync(file)) {
+        work.steps.push({ kind: 'write', path: name, what: 'a title, nothing else' });
+        work.actions.push(() => writeFileSync(file, `# ${clean}\n\n`, 'utf8'));
+    }
+    else {
+        work.notes.push(`${name} already exists and is declared as it is`);
+    }
+    return finish(context, `configure:doc add ${clean}`, doc, new Files(context.root), work);
+}
+export function planDocRename(context, ref, to) {
+    const held = docOf(context, ref);
+    const title = to.trim();
+    if (title === '')
+        throw new EditError('a top-level doc needs a title');
+    if (title !== held.title && context.framework.topLevel.some((doc) => doc.title.toLowerCase() === title.toLowerCase()))
+        throw new EditError(`a top-level doc titled '${title}' is already declared`);
+    const doc = new FrameworkDoc(context.framework);
+    const files = new Files(context.root);
+    const work = draft();
+    const entry = FrameworkDoc.find(doc.topLevel(), 'path', held.path);
+    if (!entry)
+        throw new EditError(`the document has no top_level entry at ${held.path}`);
+    const what = [];
+    if (title !== held.title) {
+        entry.set('title', title);
+        what.push(`${held.title} → ${title}`);
+    }
+    const moves = [];
+    // the file follows the title; one that drifted (a seeded README.md under a
+    // title of its own) is brought in line by a rename to the same title
+    if (path.dirname(held.file) === context.root) {
+        const name = docFileName(title, context.framework.naming);
+        const dest = path.join(context.root, name);
+        if (dest !== held.file) {
+            entry.set('path', `../${name}`);
+            what.push(`${path.basename(held.file)} → ${name}`);
+            // a file system that ignores case says the target exists when only the casing differs
+            const sameFile = dest.toLowerCase() === held.file.toLowerCase();
+            if (existsSync(dest) && !sameFile)
+                work.conflicts.push({ message: `${name} already exists`, force: false });
+            else if (existsSync(held.file)) {
+                moves.push({ from: held.file, to: dest });
+                work.steps.push({ kind: 'move', from: rel(context.root, held.file), to: name });
+                work.actions.push(() => moveFile(context.root, held.file, dest));
+            }
+        }
+    }
+    if (!doc.changed())
+        throw new EditError('nothing to rename');
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `top_level: ${what.join('; ')}` });
+    files.links(moves);
+    return finish(context, `configure:doc rename ${held.title} ${title}`, doc, files, work);
+}
+export function planDocSet(context, ref, changes) {
+    const held = docOf(context, ref);
+    const doc = new FrameworkDoc(context.framework);
+    const work = draft();
+    const entry = FrameworkDoc.find(doc.topLevel(), 'path', held.path);
+    if (!entry)
+        throw new EditError(`the document has no top_level entry at ${held.path}`);
+    if (changes.description !== undefined)
+        entry.set('description', changes.description.trim());
+    if (!doc.changed())
+        throw new EditError(`nothing to change on '${held.title}'`);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `top_level ${held.title}: description` });
+    return finish(context, `configure:doc set ${held.title}`, doc, new Files(context.root), work);
+}
+// The entry goes and, unless preserved, the file with it: an explicit remove
+// removes, and git holds what was there.
+export function planDocRemove(context, ref, options) {
+    const held = docOf(context, ref);
+    const doc = new FrameworkDoc(context.framework);
+    const work = draft();
+    const entry = FrameworkDoc.find(doc.topLevel(), 'path', held.path);
+    if (!entry)
+        throw new EditError(`the document has no top_level entry at ${held.path}`);
+    FrameworkDoc.remove(doc.topLevel(), entry);
+    work.steps.push({ kind: 'document', path: rel(context.root, doc.file), what: `top_level: remove ${held.title}` });
+    if (existsSync(held.file)) {
+        if (options.preserve)
+            work.notes.push(`--preserve leaves ${rel(context.root, held.file)} at the root, undeclared`);
+        else {
+            work.steps.push({ kind: 'remove', path: rel(context.root, held.file), what: 'the document' });
+            work.actions.push(() => rmSync(held.file, { force: true }));
+            work.destructive = true;
+        }
+    }
+    return finish(context, `configure:doc remove ${held.title}`, doc, new Files(context.root), work);
+}
+// ---- roles ------------------------------------------------------------------
+const roleSkeleton = (title) => `# ${title}\n\n## Who they are\n\n_Who holds this role, and what they own._\n\n## How to respond\n\n- **Vocabulary & depth:** _the terms to lead with._\n- **Decisions:** _which are theirs._\n- **Surface / hide:** _what to bring forward, what to fold away._\n`;
+export function planRoleAdd(context, name, from) {
+    const roleName = kebab(name);
+    if (!isRoleName(roleName))
+        throw new EditError(`'${name}' is not a role name (lowercase words joined by hyphens)`);
+    if (listRoles(context.root).some((role) => role.name === roleName))
+        throw new EditError(`a role '${roleName}' already exists`);
+    const source = from ? listRoles(context.root).find((role) => role.name === kebab(from)) : null;
+    if (from && !source)
+        throw new EditError(`no role '${from}' to copy (eidos roles lists them)`);
+    const work = draft();
+    const file = roleFile(context.root, roleName);
+    work.steps.push({ kind: 'write', path: rel(context.root, file), what: source ? `a copy of ${source.name}` : 'a bare role file' });
+    work.actions.push(() => {
+        mkdirSync(rolesDir(context.root), { recursive: true });
+        if (source)
+            cpSync(source.file, file);
+        else
+            writeFileSync(file, roleSkeleton(roleName.split('-').map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(' ')), 'utf8');
+    });
+    return finish(context, `configure:role add ${roleName}`, null, new Files(context.root), work);
+}
+// A role's name is its file: renaming one moves the file and follows the name
+// into me.md (the link and the role line) and the users who hold it.
+export function renameRoleFiles(root, from, to) {
+    const source = roleFile(root, from);
+    const target = roleFile(root, to);
+    if (existsSync(source) && !existsSync(target))
+        moveFile(root, source, target);
+    const me = meFile(root);
+    if (existsSync(me)) {
+        const text = readFileSync(me, 'utf8');
+        const next = text.split(`roles/${from}.md`).join(`roles/${to}.md`);
+        if (next !== text)
+            writeFileSync(me, next, 'utf8');
+    }
+    const users = readSettings(root).shared.users;
+    if (users.some((user) => user.role === from))
+        writeSettings(root, { shared: { users: users.map((user) => (user.role === from ? { ...user, role: to } : user)) } });
+}
+export function planRoleRename(context, name, to) {
+    const role = listRoles(context.root).find((held) => held.name === kebab(name));
+    if (!role)
+        throw new EditError(`no role '${name}' (eidos roles lists them)`);
+    const target = kebab(to);
+    if (!isRoleName(target))
+        throw new EditError(`'${to}' is not a role name (lowercase words joined by hyphens)`);
+    if (target === role.name)
+        throw new EditError('nothing to rename');
+    if (listRoles(context.root).some((held) => held.name === target))
+        throw new EditError(`a role '${target}' already exists`);
+    const work = draft();
+    work.steps.push({ kind: 'move', from: rel(context.root, role.file), to: rel(context.root, roleFile(context.root, target)) });
+    const actor = readActor(context.root);
+    if (actor.exists && actor.actor.roleFile?.endsWith(`roles/${role.name}.md`))
+        work.steps.push({ kind: 'write', path: rel(context.root, meFile(context.root)), what: `the role link → roles/${target}.md` });
+    const settings = readSettings(context.root);
+    if (settings.shared.users.some((user) => user.role === role.name))
+        work.steps.push({ kind: 'settings', path: settings.files.shared, what: `users: role ${role.name} → ${target}` });
+    work.actions.push(() => renameRoleFiles(context.root, role.name, target));
+    return finish(context, `configure:role rename ${role.name} ${target}`, null, new Files(context.root), work);
+}
+export function planRoleRemove(context, name, options) {
+    const role = listRoles(context.root).find((held) => held.name === kebab(name));
+    if (!role)
+        throw new EditError(`no role '${name}' (eidos roles lists them)`);
+    const work = draft();
+    const actor = readActor(context.root);
+    if (actor.exists && actor.actor.role && kebab(actor.actor.role) === role.name) {
+        work.conflicts.push({ message: `me.md names the role ${role.name}; --force removes it anyway`, force: true });
+    }
+    work.steps.push({ kind: 'remove', path: rel(context.root, role.file), what: 'the role file' });
+    work.actions.push(() => rmSync(role.file, { force: true }));
+    void options;
+    return finish(context, `configure:role remove ${role.name}`, null, new Files(context.root), work);
+}
+// ---- one blueprint's frontmatter ----------------------------------------------
+// The value a set writes, checked against the property's declared type.
+export function blueprintKeySet(blueprint, key, value) {
+    return editFrontmatterKey(readFileSync(blueprint.path, 'utf8'), { kind: 'set', key, value });
+}
+export function blueprintKeyUnset(blueprint, key) {
+    const text = readFileSync(blueprint.path, 'utf8');
+    return hasKey(text, key) ? editFrontmatterKey(text, { kind: 'delete', key }) : null;
+}
+export { formatScalar };