eidosmd 0.1.0 → 0.3.0

package/dist/src/core/framework-structured.js

@@ -1,13 +1,16 @@
-// The YAML framework document, `_eidos/Framework.yaml`: the same model as the
+// The YAML framework document, `.eidos/Framework.yaml`: the same model as the
 // markdown form, as fields in the frontmatter's snake_case, for a root that
 // scripts and agents read.
-// Paths are relative to `_eidos/`, as the markdown links are. A structured
+// Paths are relative to `.eidos/`, as the markdown links are. Every folder
+// at the root is declared under `folders` with its type (a 5.2.x root's
+// `collections` still reads, every entry a collection). A structured
 // document also carries the generated index under `index`, one list per
 // collection, which `eidos index` rewrites in place without disturbing
 // anything a person wrote around it.
 import { Document, isMap, isPair, isScalar, parse as parseYaml, parseDocument } from 'yaml';
-import { groupingProperty, STANDARD_CORE, } from './framework-model.js';
+import { readValueStyle, coreRequires, groupingProperty, isCollection, isFolderType, STANDARD_CORE, TOOL_KEY, unitOf } from './framework-model.js';
 import { DEFAULT_NAMING, isNaming } from './naming.js';
+const STANDARD_PROPERTY_KEYS = new Set(['name', 'type', 'applies_to', 'required', 'options', 'meaning']);
 function isPlain(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -51,48 +54,89 @@ function readCanvas(value, where, problems) {
     problems.push(`${where}: canvas must be file, card, or { mode: card, section: <Section> }`);
     return null;
 }
-function readFlavor(value, where, problems) {
-    if (!isPlain(value) || text(value['name']) === '' || text(value['shape']) === '') {
-        problems.push(`${where}: every flavor needs a name and a shape`);
+// `template` (`shape` before 5.0.0) is the file's path relative to `.eidos/`.
+function readVariant(value, where, problems) {
+    const given = isPlain(value) ? text(value['template']) || text(value['shape']) : '';
+    if (!isPlain(value) || text(value['name']) === '' || given === '') {
+        problems.push(`${where}: every variant needs a name and a template`);
         return null;
     }
-    const shape = text(value['shape']).replace(/\\/g, '/');
-    const file = shape.split('/').pop() ?? shape;
+    const template = given.replace(/\\/g, '/');
+    const file = template.split('/').pop() ?? template;
     const stem = file.replace(/\.md$/i, '');
     const dot = stem.indexOf('.');
     return {
         name: text(value['name']),
-        kind: dot === -1 ? stem : stem.slice(0, dot),
-        shape,
+        unit: dot === -1 ? stem : stem.slice(0, dot),
+        template,
         description: text(value['description']),
         isDefault: value['default'] === true,
     };
 }
-function readCollection(value, index, problems) {
-    const where = `collections[${index}]`;
+// `vocabulary`: one entry per term; `not` is a list (a single string reads as one entry).
+function readVocabulary(value, problems) {
+    const out = [];
+    list(value).forEach((entry, index) => {
+        if (!isPlain(entry) || text(entry['term']) === '') {
+            problems.push(`vocabulary[${index}]: a term needs a term`);
+            return;
+        }
+        const nots = Array.isArray(entry['not']) ? entry['not'] : entry['not'] === undefined || entry['not'] === null ? [] : [entry['not']];
+        out.push({
+            term: text(entry['term']),
+            means: text(entry['means']),
+            not: nots.map((item) => text(item)).filter((item) => item !== ''),
+            see: text(entry['see']) === '' ? null : text(entry['see']),
+        });
+    });
+    return out;
+}
+// One entry of `folders` (or of a 5.2.x root's `collections`, every one a
+// collection). A type outside the standard's three is a fault; the folder is
+// still read as declared (as `other`) so the root is not also reported as
+// undeclared.
+function readFolder(value, key, index, problems) {
+    const where = `${key}[${index}]`;
     if (!isPlain(value) || text(value['name']) === '') {
-        problems.push(`${where}: a collection needs a name`);
+        problems.push(`${where}: a folder needs a name`);
         return null;
     }
     const name = text(value['name']);
-    const flavors = list(value['flavors'])
-        .map((flavor, position) => readFlavor(flavor, `${where} (${name}) flavors[${position}]`, problems))
-        .filter((flavor) => flavor !== null);
-    if (flavors.length > 0 && !flavors.some((flavor) => flavor.isDefault)) {
-        const first = flavors[0];
+    const declared = value['type'];
+    let type = 'collection';
+    if (isFolderType(declared)) {
+        type = declared;
+    }
+    else if (key === 'folders') {
+        problems.push(`${where} (${name}): type must be one of collection, assets, other${declared === undefined || declared === null ? '' : `, not ${text(declared)}`}`);
+        type = 'other';
+    }
+    if (type !== 'collection') {
+        return { type, name, description: text(value['description']) };
+    }
+    return readCollection(value, where, name, problems);
+}
+function readCollection(value, where, name, problems) {
+    const variants = list(value['variants'] ?? value['flavors'])
+        .map((variant, position) => readVariant(variant, `${where} (${name}) variants[${position}]`, problems))
+        .filter((variant) => variant !== null);
+    if (variants.length > 0 && !variants.some((variant) => variant.isDefault)) {
+        const first = variants[0];
         if (first) {
             first.isDefault = true;
         }
     }
     const collection = {
+        type: 'collection',
         name,
         description: text(value['description']),
-        framing: index === 0,
+        framing: false,
         leaf: null,
-        flavors,
+        variants,
         canvas: readCanvas(value['canvas'], `${where} (${name})`, problems),
         grouping: null,
     };
+    collection.framing = unitOf(collection) === 'frame';
     const grouping = value['grouping'];
     if (grouping !== undefined && grouping !== null) {
         if (!isPlain(grouping) || text(grouping['label']) === '') {
@@ -111,7 +155,7 @@ function readCollection(value, index, problems) {
     }
     return collection;
 }
-function readProperty(value, where, core, problems) {
+function readProperty(value, where, core, problems, owner = core ? 'eidos' : 'custom') {
     if (!isPlain(value) || text(value['name']) === '') {
         problems.push(`${where}: a property needs a name`);
         return null;
@@ -132,7 +176,94 @@ function readProperty(value, where, core, problems) {
             problems.push(`${where}: applies_to must be all or a list of collections`);
         }
     }
-    return { name: text(value['name']), type: text(value['type']) || 'Text', appliesTo: applies, meaning: text(value['meaning']), core };
+    // `required` is true or false, absent meaning false; on the standard's own
+    // block an absent key means what the core for this version says, so a root
+    // written before the key existed still requires its id and title.
+    const declaredRequired = value['required'];
+    let required = declaredRequired === true;
+    if (declaredRequired === undefined || declaredRequired === null) {
+        required = core && coreRequires(text(value['name']));
+    }
+    else if (typeof declaredRequired !== 'boolean') {
+        problems.push(`${where}: required must be true or false`);
+    }
+    const property = { name: text(value['name']), type: text(value['type']) || 'Text', appliesTo: applies, required, meaning: text(value['meaning']), core, owner };
+    // `options` closes the value to a declared set: a non-empty list on a Text
+    // or List property. An empty list is a fault, since the absent key already
+    // says the set is open; on any other type the list means nothing.
+    const declaredOptions = value['options'];
+    if (declaredOptions !== undefined && declaredOptions !== null) {
+        const options = Array.isArray(declaredOptions) ? declaredOptions.map(text).filter((option) => option !== '') : [];
+        if (!Array.isArray(declaredOptions) || options.length === 0) {
+            problems.push(`${where}: options must be a non-empty list of values`);
+        }
+        else if (!['text', 'list'].includes(property.type.toLowerCase())) {
+            problems.push(`${where}: options apply to a Text or List property, not ${property.type}`);
+        }
+        else {
+            property.options = options;
+        }
+    }
+    const tools = {};
+    for (const [key, field] of Object.entries(value)) {
+        if (!STANDARD_PROPERTY_KEYS.has(key) && key !== 'canvas' && field !== undefined && field !== null) {
+            tools[key] = field;
+        }
+    }
+    if (Object.keys(tools).length > 0) {
+        property.tools = tools;
+    }
+    // This tool's hint sits under its own key; a bare `canvas` (how the first
+    // canvases were written) still reads.
+    const own = isPlain(tools[TOOL_KEY]) ? tools[TOOL_KEY]['canvas'] : undefined;
+    const hint = readCanvasHint(own) ?? readCanvasHint(value['canvas']);
+    if (hint) {
+        property.canvas = hint;
+    }
+    return property;
+}
+function readStringMap(value) {
+    if (!isPlain(value)) {
+        return undefined;
+    }
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof item === 'string' || typeof item === 'number') {
+            out[key] = String(item);
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+// `styles` maps a value to a whole node style; the first canvases wrote a
+// `shape` map and a `color` map instead, which still read, folded into it.
+export function readCanvasHint(value) {
+    if (!isPlain(value)) {
+        return null;
+    }
+    const hint = {};
+    if (value['show'] === true) {
+        hint.show = true;
+    }
+    const styles = {};
+    if (isPlain(value['styles'])) {
+        for (const [key, item] of Object.entries(value['styles'])) {
+            const style = readValueStyle(item);
+            if (style)
+                styles[key] = style;
+        }
+    }
+    const shape = readStringMap(value['shape']);
+    for (const [key, item] of Object.entries(shape ?? {})) {
+        styles[key] = { ...(styles[key] ?? {}), shape: styles[key]?.shape ?? item };
+    }
+    const color = readStringMap(value['color']);
+    for (const [key, item] of Object.entries(color ?? {})) {
+        styles[key] = { ...(styles[key] ?? {}), color: styles[key]?.color ?? item };
+    }
+    if (Object.keys(styles).length > 0) {
+        hint.styles = styles;
+    }
+    return Object.keys(hint).length > 0 ? hint : null;
 }
 export function readEmbeddedIndex(value) {
     if (!isPlain(value)) {
@@ -178,19 +309,31 @@ export function parseFrameworkStructured(source, root, file) {
             namingError = `naming: ${text(declaredNaming)} is not one of kebab-case, TitleCase, Title Case`;
         }
     }
-    const collections = list(document['collections'])
-        .map((collection, index) => readCollection(collection, index, problems))
-        .filter((collection) => collection !== null);
-    if (!Array.isArray(document['collections']) && !error && isPlain(value)) {
-        problems.push('collections must be a list; the first is the framing collection');
+    // `folders` since 5.3.0; a root not yet migrated still declares `collections`,
+    // every one a collection, and reads so that `migrate` and `check` can see it.
+    const foldersKey = document['folders'] === undefined && document['collections'] !== undefined ? 'collections' : 'folders';
+    const folders = list(document[foldersKey])
+        .map((folder, index) => readFolder(folder, foldersKey, index, problems))
+        .filter((folder) => folder !== null);
+    if (!Array.isArray(document[foldersKey]) && !error && isPlain(value)) {
+        problems.push(`${foldersKey} must be a list`);
     }
-    const schema = isPlain(document['schema']) ? document['schema'] : {};
+    const collections = folders.filter(isCollection);
+    const schema = isPlain(document['properties']) ? document['properties'] : isPlain(document['schema']) ? document['schema'] : {};
     const core = list(schema['core'])
         .map((property, index) => readProperty(property, `schema.core[${index}]`, true, problems))
         .filter((property) => property !== null);
     const custom = list(schema['custom'])
         .map((property, index) => readProperty(property, `schema.custom[${index}]`, false, problems))
         .filter((property) => property !== null);
+    const tools = {};
+    if (isPlain(schema['tools'])) {
+        for (const [tool, block] of Object.entries(schema['tools'])) {
+            tools[tool] = list(block)
+                .map((property, index) => readProperty(property, `schema.tools.${tool}[${index}]`, false, problems, tool))
+                .filter((property) => property !== null);
+        }
+    }
     for (const collection of collections) {
         if (collection.grouping && collection.grouping.property === null) {
             collection.grouping.property = groupingProperty(collection, custom);
@@ -208,15 +351,22 @@ export function parseFrameworkStructured(source, root, file) {
         naming,
         namingError,
         topLevel,
+        folders,
         collections,
-        schema: { core: core.length > 0 ? core : STANDARD_CORE, custom },
+        schema: { core: core.length > 0 ? core : STANDARD_CORE, custom, tools },
+        vocabulary: readVocabulary(document['vocabulary'], problems),
         problems,
     };
 }
+// The standard's block as a document writes it: `required` only where it is
+// true, since absent means false. `migrate` writes the same rows.
+export function coreEntries(core) {
+    return core.map(({ name, type, required, options, meaning, tools }) => ({ name, type, ...(required ? { required: true } : {}), ...(options ? { options } : {}), meaning, ...(tools ?? {}) }));
+}
 // The document form of a framework: what `eidos framework --json` prints and
 // what a YAML file holds, without the generated index.
 // Keys land in the order a reader expects: version and naming, then the
-// top-level docs, the collections, and the schema; `index` is added last by
+// top-level docs, the folders, and the schema; `index` is added last by
 // `eidos index`.
 export function frameworkToDocument(framework) {
     const document = {};
@@ -233,11 +383,15 @@ export function frameworkToDocument(framework) {
             return entry;
         });
     }
-    document.collections = framework.collections.map((collection) => {
-        const entry = { name: collection.name };
-        if (collection.description) {
-            entry.description = collection.description;
+    document.folders = framework.folders.map((folder) => {
+        const entry = { name: folder.name, type: folder.type };
+        if (folder.description) {
+            entry.description = folder.description;
+        }
+        if (!isCollection(folder)) {
+            return entry;
         }
+        const collection = folder;
         if (collection.canvas) {
             if (collection.canvas.mode === 'file') {
                 entry.canvas = 'file';
@@ -249,12 +403,12 @@ export function frameworkToDocument(framework) {
                 entry.canvas = { mode: 'card', section: collection.canvas.section };
             }
         }
-        entry.flavors = collection.flavors.map((flavor) => {
-            const item = { name: flavor.name, shape: flavor.shape };
-            if (flavor.description) {
-                item.description = flavor.description;
+        entry.variants = collection.variants.map((variant) => {
+            const item = { name: variant.name, template: variant.template };
+            if (variant.description) {
+                item.description = variant.description;
             }
-            if (flavor.isDefault) {
+            if (variant.isDefault) {
                 item.default = true;
             }
             return item;
@@ -276,23 +430,44 @@ export function frameworkToDocument(framework) {
         }
         return entry;
     });
-    document.schema = {
-        core: framework.schema.core.map(({ name, type, meaning }) => ({ name, type, meaning })),
-        custom: framework.schema.custom.map(({ name, type, appliesTo: applies, meaning }) => ({ name, type, applies_to: applies, meaning })),
+    const entry = ({ name, type, appliesTo: applies, required, options, meaning, canvas, tools }) => {
+        const fields = { ...(tools ?? {}) };
+        if (canvas) {
+            const own = isPlain(fields[TOOL_KEY]) ? fields[TOOL_KEY] : {};
+            fields[TOOL_KEY] = { ...own, canvas };
+        }
+        return { name, type, applies_to: applies, ...(required ? { required: true } : {}), ...(options ? { options } : {}), meaning, ...fields };
+    };
+    document.properties = {
+        core: coreEntries(framework.schema.core),
+        custom: framework.schema.custom.map(entry),
     };
+    if (Object.keys(framework.schema.tools).length > 0) {
+        document.properties.tools = Object.fromEntries(Object.entries(framework.schema.tools).map(([tool, block]) => [tool, block.map(entry)]));
+    }
+    if (framework.vocabulary.length > 0) {
+        document.vocabulary = framework.vocabulary.map((term) => {
+            const entry = { term: term.term, means: term.means, not: term.not };
+            if (term.see)
+                entry.see = term.see;
+            return entry;
+        });
+    }
     return document;
 }
-const YAML_GUIDANCE = {
+export const YAML_GUIDANCE = {
     eidos_version: ' The Eidos version this framework targets; migrate reads and bumps it.',
     naming: ' How files, folders, and links are named: kebab-case | TitleCase | Title Case. Settled once.',
-    top_level: ' The top-level documents, README first: one entry per one-of-a-kind doc (a Roadmap, a Vision).',
-    collections: " The collections, the first of them the framing one. Each declares its flavors (one default), how a canvas draws it, and its grouping.\n Add a group under `grouping.groups` with a one-line description; add a flavor with a shape file in shapes/.",
-    schema: ' The property contract. `core` is the standard\'s and moves with eidos_version; `custom` is yours: name, type (Text | List | Number | Checkbox | Date | Date & time), applies_to (all or a list), meaning.',
+    top_level: ' Every file at the root, one entry each, in the order they are read (the browser lands on the first): a README, a Roadmap, a Vision.',
+    folders: " Every folder at the root, one entry each, with its type: collection | assets | other. A collection 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; an assets or other folder is a name, a type, and a description, and nothing inside it is read.\n Add a group under `grouping.groups` with a one-line description; add a variant with a template file in templates/.",
+    properties: " The Properties table, one block per owner. `core` is the standard's and moves with eidos_version; `custom` is yours: name, type (Text | List | Number | Checkbox | Date | Date & time), applies_to (all or a list), required (true puts it on every new blueprint and notes one that lacks it; absent = false, written when it has a value), options (the closed set a Text value is one of, or a List's elements are, in order; absent = any value), meaning; `tools.<tool>` is a block a tool declared and alone writes.\n A key past those six on a row is a tool's, named for the tool; `eidosmd.canvas` is how this CLI styles a canvas node by the property's value.",
+    vocabulary: " The root's own terms, one entry each: term, means (one line), not (the near-misses, each with why it is a different thing), and see (the blueprint that defines it in full) when one does. Absent = none declared.",
+    versions: " Snapshots of the root, taken on purpose, newest first: version (the root's own number), commit (the sha that is the snapshot), tag (blueprints/<version>, when made). Absent = none recorded, the normal state.",
     index: ' Generated by `eidos index`; never hand-edited. One list per collection, in the order the markdown index would use.',
 };
 // A YAML document a person will edit gets the guidance the markdown seed
 // keeps as prose, as comments above each top-level key.
-function annotateYaml(document) {
+export function annotateYaml(document) {
     if (!isMap(document.contents)) {
         return;
     }

package/dist/src/core/framework.js

@@ -1,6 +1,6 @@
-// Finding and loading the root's framework document: exactly one of
-// `_eidos/Framework.md` or `Framework.yaml`, parsed into
-// the one model every command reads.
+// Finding and loading the root's framework document, `.eidos/Framework.yaml`,
+// parsed into the one model every command reads. A 4.x root's Framework.md
+// is found and parsed too, only so `migrate` can move it.
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { parseFrameworkMarkdown } from './framework-markdown.js';
@@ -8,7 +8,7 @@ import { parseFrameworkStructured } from './framework-structured.js';
 import { appliesTo, FRAMEWORK_DIR, FRAMEWORK_FILES, FrameworkError } from './framework-model.js';
 import { kebab } from './naming.js';
 export * from './framework-model.js';
-// The one framework document in a folder's `_eidos/`, or null; two is an error.
+// The one framework document in a folder's `.eidos/`, or null; two is an error.
 export function findFrameworkFile(dir) {
     const present = FRAMEWORK_FILES.map((candidate) => ({ file: path.join(dir, FRAMEWORK_DIR, candidate.name), format: candidate.format })).filter((candidate) => existsSync(candidate.file));
     if (present.length > 1) {
@@ -28,7 +28,7 @@ export function parseFramework(text, format, root, file) {
 export function loadFramework(root) {
     const found = findFrameworkFile(root);
     if (!found) {
-        throw new FrameworkError(`${path.join(root, FRAMEWORK_DIR)} holds no framework document (Framework.md or Framework.yaml)`);
+        throw new FrameworkError(`${path.join(root, FRAMEWORK_DIR)} holds no framework document (Framework.yaml)`);
     }
     return parseFramework(readFileSync(found.file, 'utf8'), found.format, root, found.file);
 }
@@ -38,19 +38,19 @@ export function findCollection(framework, name) {
         framework.collections.find((collection) => kebab(collection.name) === kebab(name)) ??
         null);
 }
-export function findFlavor(collection, name) {
+export function findVariant(collection, name) {
     const wanted = name.trim().toLowerCase();
-    return (collection.flavors.find((flavor) => flavor.name.toLowerCase() === wanted) ??
-        collection.flavors.find((flavor) => kebab(flavor.name) === kebab(name)) ??
+    return (collection.variants.find((variant) => variant.name.toLowerCase() === wanted) ??
+        collection.variants.find((variant) => kebab(variant.name) === kebab(name)) ??
         null);
 }
-export function defaultFlavor(collection) {
-    return collection.flavors.find((flavor) => flavor.isDefault) ?? collection.flavors[0] ?? null;
+export function defaultVariant(collection) {
+    return collection.variants.find((variant) => variant.isDefault) ?? collection.variants[0] ?? null;
 }
 // The properties a blueprint in this collection carries, core first.
 export function propertiesFor(framework, collectionName) {
-    return [...framework.schema.core, ...framework.schema.custom.filter((property) => appliesTo(property, collectionName))];
+    return [...framework.schema.core, ...[...framework.schema.custom, ...Object.values(framework.schema.tools).flat()].filter((property) => appliesTo(property, collectionName))];
 }
-export function shapePath(framework, flavor) {
-    return path.join(framework.root, FRAMEWORK_DIR, flavor.shape);
+export function templatePath(framework, variant) {
+    return path.join(framework.root, FRAMEWORK_DIR, variant.template);
 }

package/dist/src/core/frontmatter.js

@@ -3,7 +3,7 @@
 // every seed and scaffold already uses, so a generated file diffs cleanly
 // against a hand-written one.
 import { parse as parseYaml } from 'yaml';
-import { splitFrontmatter } from './markdown.js';
+import { normalizeNewlines, splitFrontmatter } from './markdown.js';
 // One `key: value` per line, read without YAML: what an unquoted summary with
 // a colon in it still means to a person, and what Obsidian will refuse to show.
 function parseLeniently(frontmatter) {
@@ -114,3 +114,63 @@ export function formatFrontmatter(entries) {
     lines.push('---');
     return lines.join('\n') + '\n';
 }
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// The lines a top-level key occupies inside [from, to): its own line and
+// every line beneath it that is indented or a `- ` item, so a block list
+// or a folded scalar moves as one.
+export function keySpan(lines, from, to, key) {
+    const head = new RegExp(`^${escapeRegExp(key)}\\s*:`);
+    for (let index = from; index < to; index += 1) {
+        if (!head.test(lines[index] ?? ''))
+            continue;
+        let end = index + 1;
+        while (end < to && /^(\s+\S|-\s)/.test(lines[end] ?? ''))
+            end += 1;
+        return { start: index, end };
+    }
+    return null;
+}
+// Whether a file's frontmatter carries the key at the top level.
+export function hasKey(text, key) {
+    const lines = normalizeNewlines(text).split('\n');
+    const close = closingFence(lines);
+    return close !== null && keySpan(lines, 1, close, key) !== null;
+}
+function closingFence(lines) {
+    if (lines[0]?.trim() !== '---')
+        return null;
+    for (let index = 1; index < lines.length; index += 1) {
+        if (lines[index]?.trim() === '---')
+            return index;
+    }
+    return null;
+}
+// The file with one key edited in its frontmatter. A file with no block, or
+// a rename or delete of a key it lacks, comes back unchanged; a set of a key
+// it lacks appends the key at the end of the block.
+export function editFrontmatterKey(text, edit) {
+    const lines = normalizeNewlines(text).split('\n');
+    const close = closingFence(lines);
+    if (close === null)
+        return text;
+    const span = keySpan(lines, 1, close, edit.key);
+    if (edit.kind === 'rename') {
+        if (!span)
+            return text;
+        const line = lines[span.start] ?? '';
+        lines[span.start] = line.replace(new RegExp(`^${escapeRegExp(edit.key)}(\\s*:)`), `${edit.to}$1`);
+        return lines.join('\n');
+    }
+    if (edit.kind === 'delete') {
+        if (!span)
+            return text;
+        lines.splice(span.start, span.end - span.start);
+        return lines.join('\n');
+    }
+    const rendered = formatFrontmatter([[edit.key, edit.value]]).split('\n').slice(1, -2);
+    if (span)
+        lines.splice(span.start, span.end - span.start, ...rendered);
+    else
+        lines.splice(close, 0, ...rendered);
+    return lines.join('\n');
+}

package/dist/src/core/git.js

@@ -0,0 +1,84 @@
+// The little git the CLI needs: the commit a root sits at, whether a commit
+// exists, a tag on one, and a move that keeps history. Every call is
+// read-only except `gitTag` and `moveFile`, and every one answers null or
+// false rather than throwing where git is absent or the root is not in a
+// repository.
+import { execFileSync } from 'node:child_process';
+import { renameSync } from 'node:fs';
+import path from 'node:path';
+import { readSettings } from './settings.js';
+function git(root, args) {
+    try {
+        return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+// A command run for its effect: true when git exits clean, whatever it prints.
+function gitRun(root, args) {
+    try {
+        execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'ignore', 'ignore'] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Whether git tracks this path (a file, or a folder with tracked files in it).
+export function gitTracks(root, absolute) {
+    return git(root, ['ls-files', '--error-unmatch', '--', absolute]) !== null;
+}
+// A file or folder moved the way the root wants: with git on for the root
+// and the path tracked, `git mv`, so history follows the rename; otherwise,
+// or when git refuses, a plain rename.
+export function moveFile(root, from, to) {
+    if (readSettings(root).shared.features.git && gitTracks(root, from) && gitRun(root, ['mv', '--', from, to]))
+        return;
+    renameSync(from, to);
+}
+export function gitHead(root) {
+    return git(root, ['rev-parse', 'HEAD']);
+}
+// The full sha of a commit named any way git accepts (a short sha, HEAD, a
+// tag), or null when nothing by that name is a commit here.
+export function gitResolve(root, ref) {
+    return git(root, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+}
+export function gitTagExists(root, tag) {
+    return git(root, ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`]) !== null;
+}
+export function gitTag(root, tag, sha) {
+    return git(root, ['tag', tag, sha]) !== null || gitTagExists(root, tag);
+}
+// Who git says is committing here: the repository's configured user, falling
+// back to the global one the way git itself does. Null outside a repository
+// or where no name is set.
+export function gitUser(root) {
+    if (gitHead(root) === null && git(root, ['rev-parse', '--git-dir']) === null)
+        return null;
+    const name = git(root, ['config', 'user.name']);
+    if (name === null)
+        return null;
+    return { name, email: git(root, ['config', 'user.email']) };
+}
+// The commits that touched one file, newest first, following renames.
+export function gitLog(root, file, limit = 50) {
+    const out = git(root, ['log', `--max-count=${limit}`, '--follow', '--format=%H%x1f%h%x1f%an%x1f%ae%x1f%aI%x1f%s', '--', file]);
+    if (out === null)
+        return [];
+    return out
+        .split('\n')
+        .map((line) => line.split('\x1f'))
+        .filter((parts) => parts.length === 6)
+        .map(([sha, short, author, email, date, subject]) => ({ sha: sha ?? '', short: short ?? '', author: author ?? '', email: email ?? '', date: date ?? '', subject: subject ?? '' }));
+}
+// The file as one commit held it, or null when that commit has no such file.
+export function gitShowFile(root, sha, file) {
+    try {
+        return execFileSync('git', ['show', `${sha}:${file.split(path.sep).join('/')}`], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/core/index-leaf.js

@@ -2,8 +2,8 @@
 // `summary`, kept inside the YAML framework document under `index`, one list
 // per collection, regenerated wholesale. `eidos index` rewrites that key and
 // nothing else in the document, so the comments and layout a person chose
-// survive. (A markdown root keeps a per-collection `index.md` instead; the
-// CLI converts such a root rather than maintaining that form.)
+// survive. (A 4.x markdown root kept a per-collection `index.md` instead;
+// `migrate` converts such a root.)
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { blueprintId, blueprintTitle, propertyString } from './blueprint.js';