eidosmd 0.2.0 → 0.3.1

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

@@ -5,7 +5,7 @@
 // spellings (Schema, Flavors, shape) still read, so `migrate` can load a root
 // it is about to move.
 import { parseFrontmatter } from './frontmatter.js';
-import { groupingProperty, STANDARD_CORE, unitOf } from './framework-model.js';
+import { coreRequires, groupingProperty, STANDARD_CORE, unitOf } from './framework-model.js';
 import { DEFAULT_NAMING, isNaming } from './naming.js';
 import { section, sections, stripInlineCode } from './markdown.js';
 import path from 'node:path';
@@ -64,6 +64,7 @@ function parseCollections(body) {
     const out = [];
     for (const { heading, body: text } of sections(block, 3)) {
         const collection = {
+            type: 'collection',
             name: heading.text,
             description: firstParagraph(text),
             framing: false,
@@ -175,9 +176,12 @@ function parseProperties(block, core, owner = core ? 'eidos' : 'custom') {
             continue;
         }
         const type = (cells[1] ?? 'Text').trim();
+        // the 4.x table had no Required column: the core requires what the
+        // standard says it does, and every other property is optional
+        const required = core && coreRequires(name);
         const property = core || cells.length < 4
-            ? { name, type, appliesTo: 'all', meaning: (cells[Math.min(cells.length, standard) - 1] ?? '').trim(), core, owner }
-            : { name, type, appliesTo: parseAppliesTo(cells[2] ?? ''), meaning: (cells[3] ?? '').trim(), core, owner };
+            ? { name, type, appliesTo: 'all', required, meaning: (cells[Math.min(cells.length, standard) - 1] ?? '').trim(), core, owner }
+            : { name, type, appliesTo: parseAppliesTo(cells[2] ?? ''), required, meaning: (cells[3] ?? '').trim(), core, owner };
         const tools = {};
         for (let index = standard; index < cells.length; index += 1) {
             const tool = header[index];
@@ -304,6 +308,8 @@ export function parseFrameworkMarkdown(text, root, file) {
         naming,
         namingError,
         topLevel: parseTopLevel(body),
+        // the markdown form predates folder types: every folder it declares is a collection
+        folders: collections,
         collections,
         schema: { core: core.length > 0 ? core : STANDARD_CORE, custom, tools },
         vocabulary: parseVocabulary(body),

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

@@ -1,8 +1,8 @@
 // The framework model: everything a framework document declares, whichever
 // of `.eidos/Framework.md` or `.yaml` it is. The version and naming
-// convention, the Top-Level docs, the Collections (each with variants and
-// grouping), the Properties table (`schema` here, `properties` on disk), the
-// Vocabulary, and the root's own Versions.
+// convention, the Top-Level docs, the Folders (every folder at the root with
+// its type; a collection carries its variants and grouping), the Properties
+// table (`schema` here, `properties` on disk), and the Vocabulary.
 import { kebab } from './naming.js';
 export const FRAMEWORK_DIR = '.eidos';
 // This tool's name, as the standard has a tool sign what it keeps in a
@@ -19,6 +19,35 @@ export const FRAMEWORK_FILES = [
     { name: 'Framework.yml', format: 'yaml' },
 ];
 export const PROPERTY_TYPES = ['Text', 'List', 'Number', 'Checkbox', 'Date', 'Date & time'];
+export function readValueStyle(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const given = value;
+    const text = (field) => (typeof field === 'string' || typeof field === 'number' ? String(field).trim() : '');
+    const style = {};
+    if (text(given['shape']) !== '')
+        style.shape = text(given['shape']);
+    if (text(given['color']) !== '')
+        style.color = text(given['color']);
+    if (given['fill'] === 'solid' || given['fill'] === 'tint' || given['fill'] === 'none')
+        style.fill = given['fill'];
+    if (text(given['fill_color']) !== '')
+        style.fill_color = text(given['fill_color']);
+    if (given['size'] === 'small' || given['size'] === 'medium' || given['size'] === 'large')
+        style.size = given['size'];
+    return Object.keys(style).length > 0 ? style : null;
+}
+// Every folder at the root is declared with one of the standard's three
+// types (Eidos 5.3.0): a collection holds blueprints; an assets folder holds
+// files that are not markdown; an other folder is whatever its description
+// says. The standard reads nothing inside the last two.
+export const FOLDER_TYPES = ['collection', 'assets', 'other'];
+export function isFolderType(value) {
+    return typeof value === 'string' && FOLDER_TYPES.includes(value);
+}
+export function isCollection(folder) {
+    return folder.type === 'collection';
+}
 // The unit a collection speaks in, the word for one of its blueprints: what
 // its template files are named for (`<unit>.<variant>.md`), read off the
 // default variant. A collection whose unit is `frame` is the framing one, this
@@ -33,13 +62,19 @@ export class FrameworkError extends Error {
         this.name = 'FrameworkError';
     }
 }
-// The standard's own four (Eidos 5.0.0), used when a Framework.md carries no core block.
+// The standard's own four (Eidos 5.3.0), two of them required, used when a
+// framework document carries no core block.
 export const STANDARD_CORE = [
-    { name: 'id', type: 'Text', appliesTo: 'all', meaning: 'Stable, unique identity, in any form: a slug, a number, a GUID. Assigned once, never changed.', core: true, owner: 'eidos' },
-    { name: 'title', type: 'Text', appliesTo: 'all', meaning: 'Human-readable name.', core: true, owner: 'eidos' },
-    { name: 'summary', type: 'Text', appliesTo: 'all', meaning: 'One plain line: what this blueprint is. The source for the collection index.', core: true, owner: 'eidos' },
-    { name: 'variant', type: 'Text', appliesTo: 'all', meaning: 'Which variant this blueprint follows. Absent = the collection default.', core: true, owner: 'eidos' },
+    { name: 'id', type: 'Text', appliesTo: 'all', required: true, meaning: 'Stable, unique identity, in any form. Assigned once, never changed.', core: true, owner: 'eidos' },
+    { name: 'title', type: 'Text', appliesTo: 'all', required: true, meaning: 'Human-readable name.', core: true, owner: 'eidos' },
+    { name: 'summary', type: 'Text', appliesTo: 'all', required: false, meaning: 'One line: what this blueprint is. Feeds the index; absent, the index flags it.', core: true, owner: 'eidos' },
+    { name: 'variant', type: 'Text', appliesTo: 'all', required: false, meaning: "Which variant this blueprint follows. Absent = the collection's default.", core: true, owner: 'eidos' },
 ];
+// Whether the standard's core requires a property of this name: what an
+// absent `required` on a core row means, since the block is the standard's.
+export function coreRequires(name) {
+    return STANDARD_CORE.some((property) => property.name === name && property.required);
+}
 // Every property of the Properties table, whichever block owns it, core first.
 export function allProperties(schema) {
     return [...schema.core, ...schema.custom, ...Object.values(schema.tools).flat()];

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

@@ -1,14 +1,16 @@
 // 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, TOOL_KEY, unitOf } 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', 'meaning']);
+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);
 }
@@ -89,13 +91,32 @@ function readVocabulary(value, problems) {
     });
     return out;
 }
-function readCollection(value, index, problems) {
-    const where = `collections[${index}]`;
+// 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 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);
@@ -106,6 +127,7 @@ function readCollection(value, index, problems) {
         }
     }
     const collection = {
+        type: 'collection',
         name,
         description: text(value['description']),
         framing: false,
@@ -154,7 +176,34 @@ function readProperty(value, where, core, problems, owner = core ? 'eidos' : 'cu
             problems.push(`${where}: applies_to must be all or a list of collections`);
         }
     }
-    const property = { name: text(value['name']), type: text(value['type']) || 'Text', appliesTo: applies, meaning: text(value['meaning']), core, owner };
+    // `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) {
@@ -185,6 +234,8 @@ function readStringMap(value) {
     }
     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;
@@ -193,13 +244,24 @@ export function readCanvasHint(value) {
     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']);
-    if (shape) {
-        hint.shape = shape;
+    for (const [key, item] of Object.entries(shape ?? {})) {
+        styles[key] = { ...(styles[key] ?? {}), shape: styles[key]?.shape ?? item };
     }
     const color = readStringMap(value['color']);
-    if (color) {
-        hint.color = 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;
 }
@@ -247,12 +309,16 @@ 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');
+    // `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 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))
@@ -285,16 +351,22 @@ export function parseFrameworkStructured(source, root, file) {
         naming,
         namingError,
         topLevel,
+        folders,
         collections,
         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 = {};
@@ -311,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';
@@ -354,16 +430,16 @@ export function frameworkToDocument(framework) {
         }
         return entry;
     });
-    const entry = ({ name, type, appliesTo: applies, meaning, canvas, tools }) => {
+    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, meaning, ...fields };
+        return { name, type, applies_to: applies, ...(required ? { required: true } : {}), ...(options ? { options } : {}), meaning, ...fields };
     };
     document.properties = {
-        core: framework.schema.core.map(({ name, type, meaning, tools }) => ({ name, type, meaning, ...(tools ?? {}) })),
+        core: coreEntries(framework.schema.core),
         custom: framework.schema.custom.map(entry),
     };
     if (Object.keys(framework.schema.tools).length > 0) {
@@ -379,12 +455,12 @@ export function frameworkToDocument(framework) {
     }
     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. 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/.",
-    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), meaning; `tools.<tool>` is a block a tool declared and alone writes.\n A key past those four 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.",
+    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.',

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

@@ -1,9 +1,12 @@
 // The little git the CLI needs: the commit a root sits at, whether a commit
-// exists, and a tag on one. Every call is read-only except `gitTag`, and
-// every one answers null or false rather than throwing where git is absent
-// or the root is not in a repository.
+// 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;
@@ -12,6 +15,28 @@ function git(root, args) {
         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']);
 }

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) {