eidosmd 0.1.0 → 0.3.0

package/dist/src/core/links.js

@@ -0,0 +1,87 @@
+// Rewriting the markdown links a move breaks. When a folder or a file moves,
+// every `[text](path)` anywhere in the root whose target lands inside the
+// moved path is rewritten to point at the new place, relative to where the
+// file holding it ends up. It is a path substitution and nothing else: a
+// link's text is untouched, a link in a fenced code block, in inline code,
+// or inside a tool's region is left as it is, and a filename typed in prose
+// without link syntax is not a link.
+import path from 'node:path';
+import { regionLines } from './regions.js';
+export function movePath(absolute, moves) {
+    for (const move of moves) {
+        if (absolute === move.from)
+            return move.to;
+        if (absolute.startsWith(move.from + path.sep))
+            return path.join(move.to, path.relative(move.from, absolute));
+    }
+    return absolute;
+}
+const LINK = /\[([^\]]*)\]\(\s*(<[^>]*>|[^)\s]+)((?:\s+"[^"]*")?)\s*\)/g;
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+function isFileTarget(target) {
+    return target !== '' && !/^[a-z][a-z0-9+.-]*:/i.test(target) && !target.startsWith('#') && !target.startsWith('//');
+}
+// The spans of inline code on a line, so a link quoted in code is left alone.
+function codeSpans(line) {
+    const out = [];
+    const pattern = /`+[^`]*`+/g;
+    let match = pattern.exec(line);
+    while (match !== null) {
+        out.push([match.index, match.index + match[0].length]);
+        match = pattern.exec(line);
+    }
+    return out;
+}
+// The text of a file with every link a move breaks rewritten. `before` is
+// where the file is now and `after` where it will be once the moves are
+// made, so a file inside a moved folder gets its outward links right too.
+export function rewriteLinks(text, before, after, moves) {
+    const lines = text.replace(/\r\n?/g, '\n').split('\n');
+    const owned = regionLines(text);
+    let count = 0;
+    let fence = null;
+    const out = lines.map((line, index) => {
+        if (owned.has(index))
+            return line;
+        const fenced = FENCE.exec(line);
+        if (fence) {
+            if (fenced && fenced[1] && fenced[1][0] === fence.char && fenced[1].length >= fence.length && line.trim() === fenced[1])
+                fence = null;
+            return line;
+        }
+        if (fenced && fenced[1]) {
+            fence = { char: fenced[1][0] ?? '`', length: fenced[1].length };
+            return line;
+        }
+        const code = codeSpans(line);
+        return line.replace(LINK, (whole, label, rawTarget, title, offset) => {
+            if (code.some(([start, end]) => offset >= start && offset < end))
+                return whole;
+            const wrapped = rawTarget.startsWith('<') && rawTarget.endsWith('>');
+            const target = wrapped ? rawTarget.slice(1, -1) : rawTarget;
+            const hash = target.indexOf('#');
+            const file = hash === -1 ? target : target.slice(0, hash);
+            const anchor = hash === -1 ? '' : target.slice(hash);
+            if (!isFileTarget(file))
+                return whole;
+            let decoded = file;
+            try {
+                decoded = decodeURIComponent(file);
+            }
+            catch {
+                return whole;
+            }
+            const absolute = path.resolve(path.dirname(before), decoded);
+            const moved = movePath(absolute, moves);
+            let relative = path.relative(path.dirname(after), moved).split(path.sep).join('/');
+            if (relative === decoded.replace(/\\/g, '/'))
+                return whole;
+            if (relative === '')
+                relative = path.basename(moved);
+            count += 1;
+            const encoded = wrapped ? `<${relative}>` : /%20/.test(file) ? relative.replace(/ /g, '%20') : /\s/.test(relative) ? `<${relative}>` : relative;
+            return `[${label}](${encoded}${anchor}${title})`;
+        });
+    });
+    return { text: out.join('\n'), count };
+}

package/dist/src/core/markdown.js

@@ -1,6 +1,7 @@
 // Small markdown readers shared by the framework, shape, and blueprint parsers:
 // splitting frontmatter from body, and finding headings and sections outside
-// code fences and HTML comments.
+// code fences, HTML comments, and the regions a tool owns.
+import { regionLines } from './regions.js';
 export function normalizeNewlines(text) {
     return text.replace(/\r\n?/g, '\n');
 }
@@ -21,37 +22,43 @@ export function splitFrontmatter(text) {
     }
     return { frontmatter: null, body: lines.join('\n') };
 }
-// Every line with a flag saying whether it sits inside a fenced code block or
-// an HTML comment, so a `## heading` quoted in guidance is not read as one.
+// Every line with a flag saying whether it sits inside a fenced code block, an
+// HTML comment, or a tool's region, so a `## heading` quoted in guidance, or
+// one a tool wrote inside its region, is not read as one of the person's.
 function visibleLines(text) {
     const out = [];
+    const owned = regionLines(text);
     let inFence = false;
     let inComment = false;
-    for (const line of normalizeNewlines(text).split('\n')) {
+    normalizeNewlines(text).split('\n').forEach((line, index) => {
         const trimmed = line.trim();
+        if (owned.has(index)) {
+            out.push({ line, visible: false });
+            return;
+        }
         if (!inComment && /^(```|~~~)/.test(trimmed)) {
             inFence = !inFence;
             out.push({ line, visible: false });
-            continue;
+            return;
         }
         if (inFence) {
             out.push({ line, visible: false });
-            continue;
+            return;
         }
         if (!inComment && trimmed.startsWith('<!--')) {
             inComment = !trimmed.includes('-->');
             out.push({ line, visible: false });
-            continue;
+            return;
         }
         if (inComment) {
             if (trimmed.includes('-->')) {
                 inComment = false;
             }
             out.push({ line, visible: false });
-            continue;
+            return;
         }
         out.push({ line, visible: true });
-    }
+    });
     return out;
 }
 export function headings(text) {

package/dist/src/core/me.js

@@ -1,14 +1,14 @@
-// The actor: `_eidos/me.md`, personal and gitignored, naming a role from
-// `_eidos/roles/` and calibrating it on three axes.
+// The actor: `.eidos/me.md`, personal and gitignored, naming a role from
+// `.eidos/roles/` and calibrating it on three axes.
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { headings, section } from './markdown.js';
 import { kebab } from './naming.js';
 export function rolesDir(root) {
-    return path.join(root, '_eidos', 'roles');
+    return path.join(root, '.eidos', 'roles');
 }
 export function meFile(root) {
-    return path.join(root, '_eidos', 'me.md');
+    return path.join(root, '.eidos', 'me.md');
 }
 export function listRoles(root) {
     const dir = rolesDir(root);
@@ -27,6 +27,11 @@ export function listRoles(root) {
         return { name: entry.replace(/\.md$/i, ''), file, title, summary };
     });
 }
+// A role's file name is its kebab-case name, one level under roles/.
+export const isRoleName = (name) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
+export function roleFile(root, name) {
+    return path.join(rolesDir(root), `${name}.md`);
+}
 export function findRole(root, name) {
     const wanted = kebab(name);
     return listRoles(root).find((role) => role.name === wanted || kebab(role.title) === wanted) ?? null;
@@ -65,13 +70,16 @@ export function parseActor(text) {
     actor.capacity = axis('Technical capacity');
     return actor;
 }
-export function renderActor(role, custom, axes) {
-    const lines = ['# Me', '', 'Personal and per-actor — gitignored, never shared. The agent reads it before acting.', ''];
+// `note` is anything the person adds under their role, in their own words.
+export function renderActor(role, custom, axes, note = null) {
+    const lines = ['# Me', '', 'Personal and per-actor, gitignored, never shared. The agent reads it before acting.', ''];
     if (role) {
-        lines.push(`## You are: ${role.title}`, '', `Role: [_eidos/roles/${role.name}.md](roles/${role.name}.md).`, '');
+        lines.push(`## You are: ${role.title}`, '', `Role: [.eidos/roles/${role.name}.md](roles/${role.name}.md).`, '');
+        if (note)
+            lines.push(note, '');
     }
     else if (custom) {
-        lines.push(`## You are: ${custom}`, '', 'A custom role: describe how you want to be helped here.', '');
+        lines.push(`## You are: ${custom}`, '', note ?? 'A custom role: describe how you want to be helped here.', '');
     }
     else {
         lines.push('## You are:', '', '<!-- Name your role, or pick one with `eidos whoami --role <role>`. -->', '');

package/dist/src/core/migrate.js

@@ -0,0 +1,319 @@
+// `eidos migrate`: the mechanical hop from an older root to the standard this
+// CLI carries. From 4.x, five names move on disk and nothing is dropped:
+// `_eidos/` becomes `.eidos/`, `shapes/` becomes `templates/`, the framework
+// document takes the 5.0.0 keys, every blueprint's `flavor` becomes
+// `variant`, and `eidos_version` is set. A root that kept the markdown
+// Framework.md gets Framework.yaml in its place, the index inside it. A
+// template that opens with frontmatter loses the block; one named off its
+// unit is noted, since only the owner can say which name is right. From
+// 5.0.0 nothing on disk moves: the version is bumped and the standard's core
+// block is rewritten with its required rows, every region carried as found.
+// 5.2.0 named the one personal file a tool keeps, `local.yaml`, and the one
+// line in `.eidos/.gitignore` that covers every tool's: the hop adds that
+// line, and this CLI's own `.gitignore` beside its local file, which did the
+// same job before, goes. 5.3.0 declares every folder at the root with a
+// type: `collections` becomes `folders` and every entry gains
+// `type: collection`; anything at the root the document does not declare is
+// the owner's to declare or move, so it is reported, never touched.
+import { existsSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
+import { FRAMEWORK_DIR, FRAMEWORK_FILES, isCollection, STANDARD_CORE, unitOf } from './framework-model.js';
+import { convertToYaml } from './convert.js';
+import { annotateYaml, coreEntries, YAML_GUIDANCE } from './framework-structured.js';
+import { undeclaredAtRoot } from './check.js';
+import { parseFramework } from './framework.js';
+import { parseVersions } from './framework-markdown.js';
+import { stripFrontmatter } from './template.js';
+import { LOCAL_IGNORE_PATTERN, rootIgnoresLocal, settingsDir } from './settings.js';
+import { readVersions, writeVersions, versionsFile } from './versions.js';
+import { standardVersion } from '../paths.js';
+export const LEGACY_DIR = '_eidos';
+// The comment the seeds write above the pattern, so a migrated root reads as a fresh one does.
+const LOCAL_IGNORE_NOTE = "# Eidos: a tool's local.yaml is personal and never shared.\n# A tool that keeps a folder under plugins/ may keep its personal settings there, one machine's (a\n# viewer command, an editor, a key path); everything else in its folder is the root's. This one\n# line covers every tool, so no tool writes a .gitignore of its own.\n";
+// The guidance this CLI wrote above `collections` before 5.3.0. A document
+// carrying it word for word gets the `folders` guidance in its place; any
+// other comment there is the owner's or the seed's and stays.
+const COLLECTIONS_GUIDANCE = " The collections. Each declares its variants (one default; each a template file named <unit>.<variant>.md under templates/, the unit being the word for one of its blueprints) and its grouping.\n Add a group under `grouping.groups` with a one-line description; add a variant with a template file in templates/.";
+export class MigrationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MigrationError';
+    }
+}
+// A root for this command is a folder with `.eidos/` or the older `_eidos/`,
+// found upward from `start` the way every other command finds one.
+export function findMigratableRoot(start, explicit) {
+    const has = (dir) => existsSync(path.join(dir, FRAMEWORK_DIR)) || existsSync(path.join(dir, LEGACY_DIR));
+    if (explicit !== undefined) {
+        const resolved = path.resolve(start, explicit);
+        if (!has(resolved))
+            throw new MigrationError(`${resolved} is not a root: no ${FRAMEWORK_DIR}/ (or ${LEGACY_DIR}/) inside it`);
+        return resolved;
+    }
+    let current = path.resolve(start);
+    for (;;) {
+        if (has(current))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            throw new MigrationError(`no root found from ${start}: no ${FRAMEWORK_DIR}/ (or ${LEGACY_DIR}/) here or above`);
+        current = parent;
+    }
+}
+const rel = (root, file) => path.relative(root, file).split(path.sep).join('/');
+function markdownFiles(dir) {
+    if (!existsSync(dir) || !statSync(dir).isDirectory())
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir).sort()) {
+        if (entry.startsWith('.'))
+            continue;
+        const full = path.join(dir, entry);
+        if (statSync(full).isDirectory())
+            out.push(...markdownFiles(full));
+        else if (/\.md$/i.test(entry))
+            out.push(full);
+    }
+    return out;
+}
+const keyOf = (pair) => (isScalar(pair.key) ? String(pair.key.value) : null);
+const renameKey = (pair, to) => {
+    if (isScalar(pair.key))
+        pair.key.value = to;
+};
+// The YAML form, key by key, comments kept: `schema` → `properties`,
+// `flavors` → `variants`, each variant's `shape` → `template` (with its path),
+// `unit` gone, `collections` → `folders` with `type: collection` on every
+// entry, the core block rewritten, the version set. A document that still
+// had the 4.x keys gets this CLI's guidance comments in their place; one
+// already on 5.x keeps every comment it had, the seed's included.
+export function migrateYamlDocument(text, version) {
+    const document = parseDocument(text);
+    const top = document.contents;
+    if (!isMap(top))
+        return text;
+    // the root's versions left the framework document in 5.0.0; migrateRoot moves them
+    const legacy = top.items.some((pair) => keyOf(pair) === 'schema' || keyOf(pair) === 'versions');
+    top.items = top.items.filter((pair) => keyOf(pair) !== 'versions');
+    for (const pair of top.items) {
+        const key = keyOf(pair);
+        if (key === 'schema')
+            renameKey(pair, 'properties');
+        if (key === 'collections') {
+            renameKey(pair, 'folders');
+            if (isScalar(pair.key) && pair.key.commentBefore === COLLECTIONS_GUIDANCE)
+                pair.key.commentBefore = YAML_GUIDANCE['folders'] ?? null;
+            if (isSeq(pair.value)) {
+                for (const folder of pair.value.items) {
+                    if (!isMap(folder) || folder.has('type'))
+                        continue;
+                    const map = folder;
+                    // the type sits beside the name, the way the seeds write it
+                    const at = map.items.findIndex((entry) => keyOf(entry) === 'name');
+                    map.items.splice(at === -1 ? 0 : at + 1, 0, document.createPair('type', 'collection'));
+                }
+            }
+        }
+        // the standard's own block is migrate's to rewrite: its rows are this version's core
+        if ((key === 'schema' || key === 'properties') && isMap(pair.value)) {
+            for (const entry of pair.value.items) {
+                if (keyOf(entry) === 'core' && isSeq(entry.value) && entry.value.items.length > 0) {
+                    // one row per line, the flow style the seeds write the block in
+                    const rows = document.createNode(coreEntries(STANDARD_CORE));
+                    if (isSeq(rows)) {
+                        for (const row of rows.items)
+                            if (isMap(row))
+                                row.flow = true;
+                    }
+                    entry.value = rows;
+                }
+            }
+        }
+        if (key === 'eidos_version' && isScalar(pair.value))
+            pair.value.value = version;
+        if (key === 'collections' && isSeq(pair.value)) {
+            for (const collection of pair.value.items) {
+                if (!isMap(collection))
+                    continue;
+                const map = collection;
+                map.items = map.items.filter((entry) => keyOf(entry) !== 'unit');
+                for (const entry of map.items) {
+                    if (keyOf(entry) === 'flavors')
+                        renameKey(entry, 'variants');
+                    if ((keyOf(entry) === 'variants' || keyOf(entry) === 'flavors') && isSeq(entry.value)) {
+                        for (const variant of entry.value.items) {
+                            if (!isMap(variant))
+                                continue;
+                            for (const field of variant.items) {
+                                if (keyOf(field) === 'shape') {
+                                    renameKey(field, 'template');
+                                    if (isScalar(field.value))
+                                        field.value.value = String(field.value.value).replace(/^shapes\//, 'templates/');
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (legacy)
+        annotateYaml(document);
+    return document.toString({ lineWidth: 0 });
+}
+// What a 4.x document recorded under `versions`, in either form, for the move
+// to this CLI's own file.
+export function legacyVersions(text, format) {
+    if (format === 'md')
+        return parseVersions(text);
+    const top = parseDocument(text).contents;
+    if (!isMap(top))
+        return [];
+    const out = [];
+    for (const pair of top.items) {
+        if (keyOf(pair) !== 'versions' || !isSeq(pair.value))
+            continue;
+        for (const row of pair.value.items) {
+            if (!isMap(row))
+                continue;
+            const version = String(row.get('version') ?? '').trim();
+            const commit = String(row.get('commit') ?? '').trim();
+            if (version === '' || commit === '')
+                continue;
+            const tag = String(row.get('tag') ?? '').trim();
+            out.push({ version, commit, tag: tag === '' ? null : tag });
+        }
+    }
+    return out;
+}
+// A document already on this standard is left alone, except for a `versions`
+// key it may still carry.
+function withoutVersions(text) {
+    const document = parseDocument(text);
+    if (!isMap(document.contents) || !document.has('versions'))
+        return text;
+    document.delete('versions');
+    return document.toString({ lineWidth: 0 });
+}
+// The markdown form, line by line: the headings, the bullets, the links, the core row, the version.
+export function migrateMarkdownDocument(text, version) {
+    return text
+        .replace(/^eidos_version:\s*\S+/m, `eidos_version: ${version}`)
+        .replace(/^## Schema\s*$/m, '## Properties')
+        .replace(/^### Eidos Core\s*$/m, '### Eidos')
+        .replace(/^### Custom Properties\s*$/m, '### Custom')
+        .replace(/^### (.+?) Properties\s*$/gm, '### $1')
+        .replace(/^(\s*)- \*\*Flavors:\*\*/gm, '$1- **Variants:**')
+        .replace(/^\s*- \*\*Unit:\*\*[^\n]*\n/gm, '')
+        .replace(/\]\(shapes\//g, '](templates/')
+        .replace(/^(\|\s*)flavor(\s*\|)/gm, '$1variant$2')
+        .replace(/_eidos\//g, '.eidos/');
+}
+export function migrateRoot(root, options) {
+    const actions = [];
+    const notes = [];
+    const version = standardVersion();
+    const act = (what, run) => {
+        actions.push(what);
+        if (!options.dryRun)
+            run();
+    };
+    const legacy = path.join(root, LEGACY_DIR);
+    const dir = path.join(root, FRAMEWORK_DIR);
+    if (existsSync(legacy) && !existsSync(dir))
+        act(`rename ${LEGACY_DIR}/ to ${FRAMEWORK_DIR}/`, () => renameSync(legacy, dir));
+    else if (!existsSync(dir))
+        throw new MigrationError(`${root} is not a root: no ${FRAMEWORK_DIR}/ (or ${LEGACY_DIR}/) inside it`);
+    // on a dry run the folder may still be the old one
+    const live = existsSync(dir) ? dir : legacy;
+    const shapes = path.join(live, 'shapes');
+    const templates = path.join(live, 'templates');
+    if (existsSync(shapes) && !existsSync(templates))
+        act(`rename ${FRAMEWORK_DIR}/shapes/ to ${FRAMEWORK_DIR}/templates/`, () => renameSync(shapes, templates));
+    const liveTemplates = existsSync(templates) ? templates : shapes;
+    const found = FRAMEWORK_FILES.map((entry) => ({ ...entry, file: path.join(live, entry.name) })).find((entry) => existsSync(entry.file));
+    if (!found)
+        throw new MigrationError(`no Framework.yaml or Framework.md under ${rel(root, live)}/`);
+    const text = readFileSync(found.file, 'utf8');
+    const from = /^eidos_version:\s*([^\s#]+)/m.exec(text)?.[1] ?? null;
+    // A YAML root already on this standard is left as it is, its comments included.
+    const next = found.format === 'yaml' ? (from === version ? withoutVersions(text) : migrateYamlDocument(text, version)) : migrateMarkdownDocument(text, version);
+    if (next !== text)
+        act(`rewrite ${FRAMEWORK_DIR}/${found.name} in the ${version} form`, () => writeFileSync(found.file, next, 'utf8'));
+    const recorded = legacyVersions(text, found.format);
+    if (recorded.length > 0) {
+        act(`move ${recorded.length} recorded version${recorded.length === 1 ? '' : 's'} to ${rel(root, versionsFile(root))}, this CLI's own record`, () => {
+            const kept = readVersions(root);
+            writeVersions(root, [...recorded.filter((entry) => !kept.some((held) => held.version === entry.version)), ...kept]);
+        });
+    }
+    const ignore = path.join(root, '.gitignore');
+    if (existsSync(ignore)) {
+        const held = readFileSync(ignore, 'utf8');
+        if (held.includes(`${LEGACY_DIR}/`))
+            act(`point .gitignore at ${FRAMEWORK_DIR}/`, () => writeFileSync(ignore, held.replace(new RegExp(`${LEGACY_DIR}/`, 'g'), `${FRAMEWORK_DIR}/`), 'utf8'));
+    }
+    // 5.2.0: one line keeps every tool's personal file out of the repository,
+    // and this CLI's private .gitignore, which covered only its own, is retired.
+    const frameworkIgnore = path.join(live, '.gitignore');
+    if (!rootIgnoresLocal(root)) {
+        act(`add ${LOCAL_IGNORE_PATTERN} to ${FRAMEWORK_DIR}/.gitignore, the one line every tool's personal file needs`, () => {
+            const held = existsSync(frameworkIgnore) ? readFileSync(frameworkIgnore, 'utf8') : '# Eidos: me.md is personal and never shared.\nme.md\n';
+            writeFileSync(frameworkIgnore, `${held.replace(/\s*$/, '')}\n\n${LOCAL_IGNORE_NOTE}${LOCAL_IGNORE_PATTERN}\n`, 'utf8');
+        });
+    }
+    const ownIgnore = path.join(settingsDir(root), '.gitignore');
+    if (existsSync(ownIgnore) && readFileSync(ownIgnore, 'utf8').trim() === 'local.yaml') {
+        act(`remove ${rel(root, ownIgnore)}; the root's .gitignore covers it now`, () => rmSync(ownIgnore, { force: true }));
+    }
+    const framework = parseFramework(next, found.format, root, path.join(dir, found.name));
+    // The markdown form left the standard in 5.0.0: the same framework is written
+    // as data, and the markdown document and each collection's index.md go.
+    if (found.format === 'md') {
+        act(`write ${FRAMEWORK_DIR}/Framework.yaml from ${found.name}, the index inside it; remove ${found.name} and each collection's index.md`, () => {
+            convertToYaml(framework, false);
+        });
+    }
+    // 5.3.0: everything at the root is declared, and only the owner can say
+    // what an undeclared entry is or whether a declared one with nothing behind
+    // it should stay; each is a note, never a move.
+    const undeclared = undeclaredAtRoot(framework);
+    // on a dry run the framework folder may still be the old one
+    for (const entry of undeclared.folders.filter((name) => name !== LEGACY_DIR))
+        notes.push(`${entry}/ is at the root and no folder declares it; declare it (eidos configure:folder add ${entry} --type assets|other, or configure:collection add) or move it`);
+    for (const entry of undeclared.files)
+        notes.push(`${entry} is at the root and top_level does not list it; declare it (eidos configure:doc add) or move it`);
+    for (const folder of framework.folders) {
+        if (!existsSync(path.join(root, folder.name)))
+            notes.push(`${folder.name}/ is declared as ${isCollection(folder) ? 'a collection' : `an ${folder.type} folder`} but is not there; create it or remove the entry`);
+    }
+    for (const doc of framework.topLevel) {
+        if (/^[a-z][a-z0-9+.-]*:/i.test(doc.path))
+            continue;
+        if (!existsSync(path.resolve(dir, doc.path.split('#')[0] ?? '')))
+            notes.push(`top_level lists ${doc.title} at ${doc.path}, which is not there; write it or remove the entry`);
+    }
+    for (const collection of framework.collections) {
+        for (const file of markdownFiles(path.join(root, collection.name))) {
+            const content = readFileSync(file, 'utf8');
+            const block = /^---\r?\n[\s\S]*?\r?\n---/.exec(content);
+            if (!block || !/^flavor:/m.test(block[0]))
+                continue;
+            act(`rename flavor to variant in ${rel(root, file)}`, () => writeFileSync(file, content.replace(block[0], block[0].replace(/^flavor:/m, 'variant:')), 'utf8'));
+        }
+        const unit = unitOf(collection);
+        for (const variant of collection.variants) {
+            const file = path.join(liveTemplates, path.basename(variant.template));
+            if (existsSync(file)) {
+                const body = readFileSync(file, 'utf8');
+                if (/^---[ \t]*\r?\n/.test(body))
+                    act(`strip the frontmatter block from ${FRAMEWORK_DIR}/templates/${path.basename(file)}`, () => writeFileSync(file, stripFrontmatter(body), 'utf8'));
+            }
+            const expected = unit ? `${unit}.${variant.name}.md` : null;
+            if (expected && path.basename(variant.template) !== expected)
+                notes.push(`${collection.name}/${variant.name} is at ${variant.template}; a template is named templates/${expected}, and only you can say which name is right`);
+        }
+    }
+    return { root, from, to: version, actions, notes, dryRun: options.dryRun };
+}

package/dist/src/core/naming.js

@@ -15,7 +15,7 @@ export function kebab(label) {
 export function isKebab(value) {
     return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
 }
-// `prior work` -> `Prior Work`; a declared flavor label as a human title.
+// `prior work` -> `Prior Work`; a declared variant label as a human title.
 export function titleize(label) {
     return label
         .split(' ')

package/dist/src/core/regions.js

@@ -0,0 +1,117 @@
+// Regions: the span inside a markdown file that a tool owns, fenced by two
+// HTML comments carrying its name (Eidos 5.1.0). `<!-- <tool>:<region> <args> -->`
+// opens one and `<!-- /<tool>:<region> -->` closes it, each alone on its line;
+// what sits between is the tool's, rewritten wholesale by it and read by
+// nothing else. The standard reads none of the contents: a check faults only
+// an opener with no closer, a heading or a link inside is not the person's,
+// and a renderer that does not know the tool shows the contents as they are.
+// A tool's identifier and a region's name: lowercase letters, digits, and hyphens.
+const NAME = '[a-z0-9][a-z0-9-]*';
+// Both closers HTML allows, `-->` and `--!>`, end a marker.
+const OPENER = new RegExp(`^<!--\\s*(${NAME}):(${NAME})(?:\\s+(.*?))?\\s*--!?>$`);
+const CLOSER = new RegExp(`^<!--\\s*/(${NAME}):(${NAME})\\s*--!?>$`);
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+function parseArgs(text) {
+    const args = {};
+    for (const token of (text ?? '').split(/\s+/)) {
+        const eq = token.indexOf('=');
+        if (eq > 0)
+            args[token.slice(0, eq)] = token.slice(eq + 1);
+    }
+    return args;
+}
+// Every region in the text, in order. A marker inside a fenced code block
+// (three or more backticks or tildes, closed by the same) is text; a region
+// closes at the first closer naming its tool and region, and the lines
+// between are not read for markers, so another tool's marker there is content.
+export function parseRegions(text) {
+    const lines = text.replace(/\r\n?/g, '\n').split('\n');
+    const out = [];
+    let fence = null;
+    let index = 0;
+    while (index < lines.length) {
+        const line = (lines[index] ?? '').trim();
+        if (fence) {
+            const closing = FENCE.exec(lines[index] ?? '');
+            if (closing && closing[1] && closing[1][0] === fence.char && closing[1].length >= fence.length && (lines[index] ?? '').trim() === closing[1])
+                fence = null;
+            index += 1;
+            continue;
+        }
+        const opening = FENCE.exec(lines[index] ?? '');
+        if (opening && opening[1]) {
+            fence = { char: opening[1][0] ?? '`', length: opening[1].length };
+            index += 1;
+            continue;
+        }
+        const opener = OPENER.exec(line);
+        if (!opener || !opener[1] || !opener[2]) {
+            index += 1;
+            continue;
+        }
+        const region = { tool: opener[1], region: opener[2], args: parseArgs(opener[3]), open: index, close: null, contents: '' };
+        let end = index + 1;
+        while (end < lines.length) {
+            const closer = CLOSER.exec((lines[end] ?? '').trim());
+            if (closer && closer[1] === region.tool && closer[2] === region.region) {
+                region.close = end;
+                break;
+            }
+            end += 1;
+        }
+        region.contents = lines.slice(index + 1, region.close ?? lines.length).join('\n');
+        out.push(region);
+        index = (region.close ?? lines.length) + 1;
+    }
+    return out;
+}
+// The zero-based lines every region occupies, markers included; an unclosed
+// one runs to the end of the text.
+export function regionLines(text) {
+    const out = new Set();
+    const total = text.replace(/\r\n?/g, '\n').split('\n').length;
+    for (const region of parseRegions(text)) {
+        for (let line = region.open; line <= (region.close ?? total - 1); line += 1)
+            out.add(line);
+    }
+    return out;
+}
+// The text with every region's lines blanked, line count kept, so what the
+// standard does read (headings, links, prose) is only the person's.
+export function stripRegions(text) {
+    const inside = regionLines(text);
+    if (inside.size === 0)
+        return text;
+    return text
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .map((line, index) => (inside.has(index) ? '' : line))
+        .join('\n');
+}
+function escapeHtml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+// The text with each region replaced by one HTML block that shows its
+// contents as they are: a `<pre>` carrying the tool and region name, which a
+// markdown renderer passes through whole (an HTML block that opens with
+// `<pre` runs to `</pre>`, blank lines included), so nothing inside is
+// rendered as markdown. A renderer that knows the tool draws its own view.
+export function regionsAsHtml(text) {
+    const regions = parseRegions(text);
+    if (regions.length === 0)
+        return text;
+    const lines = text.replace(/\r\n?/g, '\n').split('\n');
+    const out = [];
+    let index = 0;
+    for (const region of regions) {
+        out.push(...lines.slice(index, region.open));
+        const args = Object.entries(region.args)
+            .map(([key, value]) => `${key}=${value}`)
+            .join(' ');
+        const attributes = [`data-tool="${escapeHtml(region.tool)}"`, `data-region="${escapeHtml(region.region)}"`, args !== '' ? `data-args="${escapeHtml(args)}"` : '', region.close === null ? 'data-unclosed=""' : ''].filter((attribute) => attribute !== '');
+        out.push('', `<pre class="region" ${attributes.join(' ')}>${escapeHtml(region.contents)}</pre>`, '');
+        index = (region.close ?? lines.length) + 1;
+    }
+    out.push(...lines.slice(index));
+    return out.join('\n');
+}

package/dist/src/core/root.js

@@ -1,4 +1,4 @@
-// Finding the root: the one folder with `_eidos/` inside it, never a folder
+// Finding the root: the one folder with `.eidos/` inside it, never a folder
 // with a particular name. Looks at the starting folder, then its ancestors,
 // then one and two levels beneath it, so `eidos check` works from a repo root
 // that keeps its blueprints in `Blueprints/`.
@@ -62,7 +62,7 @@ export function findRoot(start, explicit) {
     if (explicit !== undefined) {
         const resolved = path.resolve(start, explicit);
         if (!isRoot(resolved)) {
-            throw new RootError(`${resolved} is not a root: no ${FRAMEWORK_DIR}/Framework.md inside it`);
+            throw new RootError(`${resolved} is not a root: no ${FRAMEWORK_DIR}/Framework.yaml inside it`);
         }
         return resolved;
     }