eidosmd 0.1.0 → 0.3.0

package/dist/src/core/settings.js

@@ -0,0 +1,232 @@
+// The CLI's own settings, Obsidian-style: plain YAML files in the folder the
+// standard reserves for this tool, never a database. `settings.yaml` is the
+// root's and travels with it (whether git is used, the people who work in
+// the root, what every save does to a blueprint); `local.yaml` is one
+// person's on one machine (who they are acting as, how their canvas
+// behaves, which columns they hide, the diff viewer installed here), the
+// personal file the standard names since 5.2.0, kept out of git by the one
+// pattern the root's `.eidos/.gitignore` carries for every tool. Nothing
+// the browser remembers lives anywhere else.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml, stringify } from 'yaml';
+import { FRAMEWORK_DIR, PLUGINS_DIR, TOOL_KEY } from './framework-model.js';
+export const SETTINGS_DIR = `${PLUGINS_DIR}/${TOOL_KEY}`;
+// The one line in the root's `.eidos/.gitignore` that keeps every tool's
+// personal file out of the repository (Eidos 5.2.0), beside `me.md`.
+export const LOCAL_IGNORE_PATTERN = 'plugins/*/local.yaml';
+// Whether the root's `.eidos/.gitignore` already carries that line.
+export function rootIgnoresLocal(root) {
+    const file = path.join(root, FRAMEWORK_DIR, '.gitignore');
+    if (!existsSync(file))
+        return false;
+    return readFileSync(file, 'utf8')
+        .split(/\r?\n/)
+        .some((line) => line.trim() === LOCAL_IGNORE_PATTERN);
+}
+export const DEFAULT_TAG_PREFIX = 'blueprints/';
+export const DEFAULT_SHARED = { features: { git: true }, users: [], on_save: [], versions: { tag_prefix: DEFAULT_TAG_PREFIX }, check: { strict: false } };
+export const DEFAULT_LOCAL = {
+    user: null,
+    theme: 'system',
+    canvas: { wheel_zoom: true, right_drag_pan: true, ctrl_click_menu: false, enter_commits: true, context_menu: true, resize_all: false },
+    tables: { page_size: 50, columns: {} },
+    source_mode: false,
+    hide_overview: false,
+    reader_width: 'fixed',
+    diff_viewer: null,
+    editor: null,
+    recent_searches: [],
+};
+const SHARED_HEADER = `eidosmd settings shared by everyone in this root. Edit by hand, with eidos setup, or from the browser.
+features.git: whether the browser reads git (history, authors, versions) when the root is in a repository.
+users: the people who work here: { name, alias (for @mentions, no spaces), role (from .eidos/roles/), email (ties to git) }.
+on_save: rules applied to a blueprint's frontmatter on every save from the browser: { property, set: today | now }.
+versions.tag_prefix: what a recorded version's git tag starts with (eidos version record --tag), blueprints/ by default.
+check.strict: whether a warning fails eidos check as an error does; the framework owner's decision for this root (eidos check --strict / --no-strict override one run).`;
+const LOCAL_HEADER = `eidosmd settings for this machine, ignored by git. Edit by hand, with eidos setup, or from the browser's Preferences.
+user: who this machine acts as, by alias or name from users; absent = the git identity, else the role in me.md.
+theme: system | light | dark. canvas: scroll-wheel zoom, right-drag pan, ctrl-click menus, whether Enter finishes an in-place edit, whether a right click opens the menu or the details, whether every node resizes. tables: page size and the columns hidden per collection. source_mode: the reader shows files as text. hide_overview: the sidebar leaves out Eidos Overview. reader_width: fixed (every page but the canvas held to about 1200px, for a wide screen) | fluid (the whole window).
+editor: a command with {file} that opens a file in an external editor; blank = the system's default app.
+diff_viewer: the git plugin's viewer, a command with {a} and {b} for the two files, e.g. "code --diff {a} {b}".`;
+const isPlain = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export function settingsDir(root) {
+    return path.join(root, FRAMEWORK_DIR, SETTINGS_DIR);
+}
+function readYaml(file) {
+    if (!existsSync(file))
+        return {};
+    try {
+        const parsed = parseYaml(readFileSync(file, 'utf8'));
+        return isPlain(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function cleanAlias(value) {
+    if (typeof value !== 'string')
+        return null;
+    const alias = value.replace(/^@/, '').replace(/\s+/g, '').trim();
+    return alias === '' ? null : alias;
+}
+function readUsers(value) {
+    const out = [];
+    for (const entry of Array.isArray(value) ? value : []) {
+        if (!isPlain(entry) || typeof entry['name'] !== 'string' || entry['name'].trim() === '')
+            continue;
+        const text = (field) => (typeof field === 'string' && field.trim() !== '' ? field.trim() : null);
+        out.push({ name: entry['name'].trim(), alias: cleanAlias(entry['alias']), role: text(entry['role']), email: text(entry['email']) });
+    }
+    return out;
+}
+function readShared(value, base = DEFAULT_SHARED) {
+    const features = isPlain(value['features']) ? value['features'] : {};
+    const git = typeof features['git'] === 'boolean' ? features['git'] : base.features.git;
+    const rules = [];
+    for (const entry of Array.isArray(value['on_save']) ? value['on_save'] : []) {
+        if (isPlain(entry) && typeof entry['property'] === 'string' && entry['property'].trim() !== '' && (entry['set'] === 'today' || entry['set'] === 'now')) {
+            rules.push({ property: entry['property'].trim(), set: entry['set'] });
+        }
+    }
+    const versions = isPlain(value['versions']) ? value['versions'] : {};
+    const prefix = typeof versions['tag_prefix'] === 'string' ? versions['tag_prefix'].trim() : base.versions.tag_prefix;
+    const check = isPlain(value['check']) ? value['check'] : {};
+    const strict = typeof check['strict'] === 'boolean' ? check['strict'] : base.check.strict;
+    return {
+        features: { git },
+        users: 'users' in value ? readUsers(value['users']) : base.users.map((user) => ({ ...user })),
+        on_save: 'on_save' in value ? rules : base.on_save.map((rule) => ({ ...rule })),
+        versions: { tag_prefix: prefix },
+        check: { strict },
+    };
+}
+// A user by alias (case-insensitive) or by name.
+export function findUser(users, key) {
+    if (!key)
+        return null;
+    const wanted = key.replace(/^@/, '').toLowerCase();
+    return users.find((user) => user.alias?.toLowerCase() === wanted) ?? users.find((user) => user.name.toLowerCase() === wanted) ?? null;
+}
+// The user this machine acts as, when local.yaml names one that exists.
+export function actingUser(settings) {
+    return findUser(settings.shared.users, settings.local.user);
+}
+// A value the file does not carry, or carries wrongly, keeps `base`: the
+// defaults on a read, the settings already held on a write.
+function readLocal(value, base = DEFAULT_LOCAL) {
+    const out = JSON.parse(JSON.stringify(base));
+    if (value['user'] === null)
+        out.user = null;
+    else if (typeof value['user'] === 'string')
+        out.user = value['user'].trim() === '' ? null : value['user'].trim();
+    if (value['theme'] === 'light' || value['theme'] === 'dark' || value['theme'] === 'system')
+        out.theme = value['theme'];
+    const canvas = isPlain(value['canvas']) ? value['canvas'] : {};
+    for (const key of ['wheel_zoom', 'right_drag_pan', 'ctrl_click_menu', 'enter_commits', 'context_menu', 'resize_all']) {
+        if (typeof canvas[key] === 'boolean')
+            out.canvas[key] = canvas[key];
+    }
+    const tables = isPlain(value['tables']) ? value['tables'] : {};
+    if (typeof tables['page_size'] === 'number' && tables['page_size'] >= 10)
+        out.tables.page_size = Math.round(tables['page_size']);
+    if (isPlain(tables['columns'])) {
+        // a columns map given is the whole map (a write merges per collection
+        // before it gets here), so an entry it lacks is gone
+        out.tables.columns = {};
+        for (const [collection, hidden] of Object.entries(tables['columns'])) {
+            if (Array.isArray(hidden))
+                out.tables.columns[collection] = hidden.filter((name) => typeof name === 'string');
+        }
+    }
+    if (typeof value['source_mode'] === 'boolean')
+        out.source_mode = value['source_mode'];
+    if (typeof value['hide_overview'] === 'boolean')
+        out.hide_overview = value['hide_overview'];
+    if (value['reader_width'] === 'fixed' || value['reader_width'] === 'fluid')
+        out.reader_width = value['reader_width'];
+    if (value['diff_viewer'] === null)
+        out.diff_viewer = null;
+    else if (typeof value['diff_viewer'] === 'string')
+        out.diff_viewer = value['diff_viewer'].trim() === '' ? null : value['diff_viewer'].trim();
+    if (value['editor'] === null)
+        out.editor = null;
+    else if (typeof value['editor'] === 'string')
+        out.editor = value['editor'].trim() === '' ? null : value['editor'].trim();
+    if (Array.isArray(value['recent_searches']))
+        out.recent_searches = value['recent_searches'].filter((entry) => typeof entry === 'string').slice(0, 10);
+    return out;
+}
+export function readSettings(root) {
+    const dir = settingsDir(root);
+    const shared = path.join(dir, 'settings.yaml');
+    const local = path.join(dir, 'local.yaml');
+    return {
+        shared: readShared(readYaml(shared)),
+        local: readLocal(readYaml(local)),
+        files: { shared: path.relative(root, shared).split(path.sep).join('/'), local: path.relative(root, local).split(path.sep).join('/') },
+        configured: existsSync(shared),
+    };
+}
+function writeYaml(file, header, value) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    const comment = header
+        .split('\n')
+        .map((line) => `# ${line}`)
+        .join('\n');
+    writeFileSync(file, `${comment}\n${stringify(value)}`, 'utf8');
+}
+// Each file is written whole from the merged value: a partial patch keeps
+// what it does not name. On a root whose `.eidos/.gitignore` does not yet
+// carry the standard's pattern (one written before 5.2.0 and not migrated),
+// a .gitignore of this tool's own is written beside the local file, so a
+// personal setting never reaches the repository; `eidos migrate` adds the
+// pattern and removes that file.
+export function writeSettings(root, patch) {
+    const current = readSettings(root);
+    const dir = settingsDir(root);
+    if (isPlain(patch.shared)) {
+        const given = patch.shared;
+        const base = toPlain(current.shared);
+        const merged = { ...base, ...given };
+        if (isPlain(given['features']))
+            merged['features'] = { ...base['features'], ...given['features'] };
+        if (isPlain(given['versions']))
+            merged['versions'] = { ...base['versions'], ...given['versions'] };
+        if (isPlain(given['check']))
+            merged['check'] = { ...base['check'], ...given['check'] };
+        writeYaml(path.join(dir, 'settings.yaml'), SHARED_HEADER, readShared(merged, current.shared));
+    }
+    if (isPlain(patch.local)) {
+        const given = patch.local;
+        const base = toPlain(current.local);
+        const merged = { ...base, ...given };
+        if (isPlain(given['canvas']))
+            merged['canvas'] = { ...base['canvas'], ...given['canvas'] };
+        if (isPlain(given['tables'])) {
+            const tables = base['tables'];
+            merged['tables'] = { ...tables, ...given['tables'] };
+            if (isPlain(given['tables']['columns'])) {
+                // a collection given as null drops its entry, for a collection renamed away
+                const columns = { ...tables['columns'] };
+                for (const [collection, hidden] of Object.entries(given['tables']['columns'])) {
+                    if (hidden === null)
+                        delete columns[collection];
+                    else
+                        columns[collection] = hidden;
+                }
+                merged['tables']['columns'] = columns;
+            }
+        }
+        writeYaml(path.join(dir, 'local.yaml'), LOCAL_HEADER, readLocal(merged, current.local));
+        const ignore = path.join(dir, '.gitignore');
+        if (!rootIgnoresLocal(root) && !existsSync(ignore))
+            writeFileSync(ignore, 'local.yaml\n', 'utf8');
+    }
+    return readSettings(root);
+}
+const toPlain = (value) => JSON.parse(JSON.stringify(value));
+// Whether a listed user is the git identity: the same email, else the same name.
+export function matchesIdentity(user, identity) {
+    return (user.email !== null && identity.email !== null && user.email.toLowerCase() === identity.email.toLowerCase()) || user.name.toLowerCase() === identity.name.toLowerCase();
+}

package/dist/src/core/store.js

@@ -0,0 +1,315 @@
+// The browser's cache. The files stay the truth: a read parses the root once
+// and keeps it until something on disk changes, a write goes straight to the
+// file and drops the cache. Beside the parsed root sits a search index in
+// SQLite (node:sqlite, an FTS5 trigram table over title, summary, properties,
+// and body) so `/` finds a phrase inside any blueprint in a keystroke. A
+// runtime without node:sqlite (Node 20) gets a plain substring scorer with
+// the same shape of result, so the page behaves the same everywhere.
+import { createRequire } from 'node:module';
+import { readdirSync, statSync, watch } from 'node:fs';
+import path from 'node:path';
+import { loadRoot } from '../context.js';
+import { blueprintId, blueprintTitle, propertyString, resolveVariant } from './blueprint.js';
+const IGNORED = new Set(['.git', 'node_modules', '.DS_Store']);
+function documentOf(blueprint) {
+    const properties = Object.entries(blueprint.properties ?? {})
+        .filter(([key]) => key !== 'title' && key !== 'summary')
+        .map(([key, value]) => `${key}: ${Array.isArray(value) ? value.map((item) => String(item)).join(', ') : String(value ?? '')}`)
+        .join('\n');
+    return {
+        blueprint,
+        title: blueprintTitle(blueprint),
+        summary: propertyString(blueprint, 'summary') ?? '',
+        properties,
+        body: blueprint.body,
+    };
+}
+function hitOf(doc, snippet, field) {
+    const { variant, declared } = resolveVariant(doc.blueprint);
+    return {
+        path: doc.blueprint.rel,
+        id: blueprintId(doc.blueprint),
+        title: doc.title,
+        summary: doc.summary === '' ? null : doc.summary,
+        collection: doc.blueprint.collection.name,
+        group: doc.blueprint.group,
+        variant: variant?.name ?? declared,
+        snippet,
+        field,
+    };
+}
+// A window of text around the first occurrence of `needle`, the match in [ ].
+function excerpt(text, needle, width = 90) {
+    const at = text.toLowerCase().indexOf(needle.toLowerCase());
+    if (at === -1) {
+        return text.slice(0, width);
+    }
+    const start = Math.max(0, at - Math.floor(width / 3));
+    const end = Math.min(text.length, at + needle.length + width);
+    const before = text.slice(start, at).replace(/\s+/g, ' ');
+    const match = text.slice(at, at + needle.length);
+    const after = text.slice(at + needle.length, end).replace(/\s+/g, ' ');
+    return `${start > 0 ? '…' : ''}${before}[${match}]${after}${end < text.length ? '…' : ''}`;
+}
+// The words of a query: every whitespace-separated piece, quotes stripped.
+function terms(query) {
+    return query
+        .split(/\s+/)
+        .map((term) => term.replace(/["']/g, '').trim())
+        .filter((term) => term !== '');
+}
+// The fallback: every document scanned, title matches first, then summary,
+// then a property line, then the body. Fine into the low thousands.
+class ScanEngine {
+    docs;
+    constructor(docs = []) {
+        this.docs = docs;
+    }
+    rebuild(docs) {
+        this.docs = docs;
+    }
+    search(query, limit) {
+        const words = terms(query).map((term) => term.toLowerCase());
+        if (words.length === 0)
+            return [];
+        const hits = [];
+        for (const doc of this.docs) {
+            const fields = [
+                ['title', doc.title, 0],
+                ['summary', doc.summary, 1],
+                ['properties', doc.properties, 2],
+                ['body', doc.body, 3],
+            ];
+            const all = fields.map(([, text]) => text.toLowerCase()).join('\n');
+            if (!words.every((word) => all.includes(word)))
+                continue;
+            const first = fields.find(([, text]) => words.some((word) => text.toLowerCase().includes(word)));
+            if (!first)
+                continue;
+            const word = words.find((candidate) => first[1].toLowerCase().includes(candidate)) ?? words[0] ?? '';
+            hits.push({ rank: first[2], hit: hitOf(doc, first[0] === 'title' ? doc.title : excerpt(first[1], word), first[0]) });
+        }
+        return hits.sort((a, b) => a.rank - b.rank || a.hit.title.localeCompare(b.hit.title)).slice(0, limit).map((entry) => entry.hit);
+    }
+    close() {
+        this.docs = [];
+    }
+}
+// FTS5 with the trigram tokenizer: a substring anywhere in the document,
+// case-insensitive, ranked by bm25 with the title weighted far above the body.
+class SqliteEngine {
+    db;
+    docs = new Map();
+    constructor(db) {
+        this.db = db;
+        this.db.exec("CREATE VIRTUAL TABLE docs USING fts5(path UNINDEXED, title, summary, properties, body, tokenize='trigram')");
+    }
+    rebuild(docs) {
+        this.docs = new Map(docs.map((doc) => [doc.blueprint.rel, doc]));
+        const insert = this.db.prepare('INSERT INTO docs (path, title, summary, properties, body) VALUES (?, ?, ?, ?, ?)');
+        this.db.exec('BEGIN');
+        try {
+            this.db.exec('DELETE FROM docs');
+            for (const doc of docs) {
+                insert.run(doc.blueprint.rel, doc.title, doc.summary, doc.properties, doc.body);
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (cause) {
+            this.db.exec('ROLLBACK');
+            throw cause;
+        }
+    }
+    search(query, limit) {
+        const words = terms(query);
+        // The trigram tokenizer needs three characters; shorter words narrow the
+        // result in JS instead of the index.
+        const indexed = words.filter((word) => word.length >= 3);
+        const short = words.filter((word) => word.length < 3).map((word) => word.toLowerCase());
+        if (indexed.length === 0) {
+            return new ScanEngine([...this.docs.values()]).search(query, limit);
+        }
+        const match = indexed.map((word) => `"${word.replace(/"/g, '""')}"`).join(' AND ');
+        const rows = this.db
+            .prepare(`SELECT path, bm25(docs, 0, 12, 6, 3, 1) AS rank,
+                highlight(docs, 1, '[', ']') AS title_hit,
+                highlight(docs, 2, '[', ']') AS summary_hit,
+                snippet(docs, 3, '[', ']', '…', 10) AS properties_hit,
+                snippet(docs, 4, '[', ']', '…', 14) AS body_hit
+         FROM docs WHERE docs MATCH ? ORDER BY rank LIMIT ?`)
+            .all(match, Math.max(limit * 3, 30));
+        const hits = [];
+        for (const row of rows) {
+            const doc = this.docs.get(row.path);
+            if (!doc)
+                continue;
+            if (short.length > 0) {
+                const all = `${doc.title}\n${doc.summary}\n${doc.properties}\n${doc.body}`.toLowerCase();
+                if (!short.every((word) => all.includes(word)))
+                    continue;
+            }
+            if (row.title_hit.includes('['))
+                hits.push(hitOf(doc, row.title_hit, 'title'));
+            else if (row.summary_hit.includes('['))
+                hits.push(hitOf(doc, row.summary_hit, 'summary'));
+            else if (row.properties_hit.includes('['))
+                hits.push(hitOf(doc, row.properties_hit.replace(/\s+/g, ' '), 'properties'));
+            else
+                hits.push(hitOf(doc, row.body_hit.replace(/\s+/g, ' '), 'body'));
+            if (hits.length >= limit)
+                break;
+        }
+        return hits;
+    }
+    close() {
+        this.db.close();
+    }
+}
+// node:sqlite, loaded synchronously and quietly: on Node 22 the module prints
+// an ExperimentalWarning the first time it loads, which has no place on the
+// terminal that just printed the browser's URL.
+function openSqlite() {
+    const previous = process.listeners('warning');
+    process.removeAllListeners('warning');
+    process.on('warning', (warning) => {
+        if (warning.name === 'ExperimentalWarning' && /sqlite/i.test(warning.message))
+            return;
+        for (const listener of previous)
+            listener(warning);
+    });
+    try {
+        const sqlite = createRequire(import.meta.url)('node:sqlite');
+        return new sqlite.DatabaseSync(':memory:');
+    }
+    catch {
+        return null;
+    }
+}
+export class Store {
+    root;
+    engine;
+    cwd;
+    cached = null;
+    dirty = true;
+    search_;
+    watcher = null;
+    poller = null;
+    pending = null;
+    // the root-relative paths that changed since the last event went out
+    changed = new Set();
+    listeners = new Set();
+    constructor(options) {
+        this.root = options.root;
+        this.cwd = options.cwd;
+        const db = openSqlite();
+        this.search_ = db ? new SqliteEngine(db) : new ScanEngine();
+        this.engine = db ? 'sqlite' : 'scan';
+        if (options.watch !== false) {
+            this.startWatching();
+        }
+    }
+    // The parsed root, re-read only after a change on disk or a write here.
+    context() {
+        if (this.cached === null || this.dirty) {
+            this.cached = loadRoot({ root: this.root }, this.cwd);
+            this.dirty = false;
+            this.search_.rebuild(this.cached.blueprints.map(documentOf));
+        }
+        return this.cached;
+    }
+    // After a write: the next read parses again.
+    invalidate() {
+        this.dirty = true;
+    }
+    search(query, limit = 20) {
+        this.context();
+        return this.search_.search(query, limit);
+    }
+    // Called after the disk settles, with the root-relative paths that
+    // changed, so a view can tell whether the file it holds is one of them.
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    close() {
+        this.watcher?.close();
+        this.watcher = null;
+        if (this.poller)
+            clearInterval(this.poller);
+        this.poller = null;
+        if (this.pending)
+            clearTimeout(this.pending);
+        this.search_.close();
+    }
+    noticed(name) {
+        if (name.split(/[\\/]/).some((part) => IGNORED.has(part)))
+            return;
+        this.dirty = true;
+        if (name !== '')
+            this.changed.add(name.split(path.sep).join('/'));
+        if (this.pending)
+            clearTimeout(this.pending);
+        this.pending = setTimeout(() => {
+            this.pending = null;
+            const paths = [...this.changed].sort();
+            this.changed.clear();
+            for (const listener of this.listeners)
+                listener(paths);
+        }, 150);
+    }
+    // Recursive watching where the platform has it (macOS, Windows, recent
+    // Linux); elsewhere a poll of the tree's mtimes every two seconds does the
+    // same job, so the page behaves the same on every machine.
+    startWatching() {
+        try {
+            this.watcher = watch(this.root, { recursive: true }, (_event, filename) => this.noticed(typeof filename === 'string' ? filename : ''));
+            this.watcher.unref();
+        }
+        catch {
+            this.watcher = null;
+            let last = snapshotTree(this.root);
+            this.poller = setInterval(() => {
+                const next = snapshotTree(this.root);
+                for (const [file, stamp] of next)
+                    if (last.get(file) !== stamp)
+                        this.noticed(file);
+                for (const file of last.keys())
+                    if (!next.has(file))
+                        this.noticed(file);
+                last = next;
+            }, 2000);
+            this.poller.unref();
+        }
+    }
+}
+// Every file under the root with its mtime, root-relative, for the poll.
+function snapshotTree(root) {
+    const out = new Map();
+    const walk = (dir) => {
+        let entries = [];
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (IGNORED.has(entry))
+                continue;
+            const full = path.join(dir, entry);
+            let stat;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory())
+                walk(full);
+            else
+                out.set(path.relative(root, full).split(path.sep).join('/'), stat.mtimeMs);
+        }
+    };
+    walk(root);
+    return out;
+}

package/dist/src/core/template.js

@@ -0,0 +1,32 @@
+// A template file: one body template in `.eidos/templates/`, read for the
+// sections it declares (to validate a blueprint against) and as the body a
+// new blueprint is rendered from.
+import { existsSync, readFileSync } from 'node:fs';
+import { headings } from './markdown.js';
+import { templatePath } from './framework.js';
+const FRONTMATTER_BLOCK = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
+// The template without the frontmatter block it should never have carried.
+export function stripFrontmatter(text) {
+    return text.replace(FRONTMATTER_BLOCK, '').replace(/^\n+/, '');
+}
+export function loadTemplate(framework, variant) {
+    const file = templatePath(framework, variant);
+    if (!existsSync(file)) {
+        return null;
+    }
+    const text = readFileSync(file, 'utf8');
+    const all = headings(text);
+    return {
+        path: file,
+        variant,
+        text,
+        sections: all.filter((heading) => heading.level === 2).map((heading) => heading.text),
+        headings: all,
+        frontmatter: FRONTMATTER_BLOCK.test(text),
+    };
+}
+// The body a scaffolded blueprint starts from: the template with its title
+// filled in and any leading blank lines dropped.
+export function renderTemplate(template, title) {
+    return template.replace(/\r\n?/g, '\n').replace(/\{\{title\}\}/g, title).replace(/^\n+/, '');
+}

package/dist/src/core/versions.js

@@ -0,0 +1,84 @@
+// The root's own versions: snapshots taken on purpose, this CLI's own record
+// under `.eidos/plugins/eidosmd/versions.yaml` (the standard reads none of a
+// plugin's folder, and since 5.0.0 keeps no `versions` key of its own). A
+// version is a name the owner chose and a commit that already exists in the
+// repository the root lives in; the commit is the snapshot, nothing is copied.
+// A tag, when wanted, is the root's tag prefix (settings.yaml
+// `versions.tag_prefix`, `blueprints/` unless changed) before the version.
+// Nothing here proposes a version: it is written only when asked, and it
+// needs git.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { parse, stringify } from 'yaml';
+import { FRAMEWORK_DIR, TOOL_KEY } from './framework-model.js';
+import { gitResolve, gitTag, gitTagExists } from './git.js';
+import { DEFAULT_TAG_PREFIX, readSettings } from './settings.js';
+export const TAG_PREFIX = DEFAULT_TAG_PREFIX;
+// What a tag on this root starts with, as its settings say.
+export const tagPrefix = (root) => readSettings(root).shared.versions.tag_prefix;
+export class VersionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'VersionError';
+    }
+}
+export const versionsFile = (root) => path.join(root, FRAMEWORK_DIR, 'plugins', TOOL_KEY, 'versions.yaml');
+const GUIDANCE = "# The root's own versions, kept by the eidos CLI (`eidos version`): snapshots taken on purpose, newest first.\n# version is the root's own number, commit the sha that is the snapshot, tag <prefix><version> when one was made.\n";
+// Newest first, as recorded; none when the file is absent.
+export function readVersions(root) {
+    const file = versionsFile(root);
+    if (!existsSync(file))
+        return [];
+    const data = parse(readFileSync(file, 'utf8'));
+    const rows = data && typeof data === 'object' && Array.isArray(data.versions) ? (data.versions) : [];
+    const out = [];
+    for (const row of rows) {
+        if (!row || typeof row !== 'object')
+            continue;
+        const entry = row;
+        const version = String(entry['version'] ?? '').trim();
+        const commit = String(entry['commit'] ?? '').trim();
+        if (version === '' || commit === '')
+            continue;
+        const tag = String(entry['tag'] ?? '').trim();
+        out.push({ version, commit, tag: tag === '' ? null : tag });
+    }
+    return out;
+}
+export function writeVersions(root, versions) {
+    const file = versionsFile(root);
+    mkdirSync(path.dirname(file), { recursive: true });
+    const rows = versions.map((version) => (version.tag ? { version: version.version, commit: version.commit, tag: version.tag } : { version: version.version, commit: version.commit }));
+    writeFileSync(file, GUIDANCE + stringify({ versions: rows }, { lineWidth: 0 }), 'utf8');
+    return file;
+}
+export function recordVersion(root, options) {
+    const version = options.version.trim();
+    if (version === '') {
+        throw new VersionError("a version needs a name (the root's own number, e.g. 1.0.0)");
+    }
+    const existing = readVersions(root);
+    if (existing.some((entry) => entry.version === version)) {
+        throw new VersionError(`version '${version}' is already recorded`);
+    }
+    const ref = options.commit && options.commit.trim() !== '' ? options.commit.trim() : 'HEAD';
+    const sha = gitResolve(root, ref);
+    if (!sha) {
+        throw new VersionError(`'${ref}' is not a commit in the repository this root lives in; a version names a commit that exists`);
+    }
+    const short = sha.slice(0, 12);
+    const tag = options.tag ? `${options.tagPrefix ?? tagPrefix(root)}${version}` : null;
+    let tagged = false;
+    if (tag) {
+        if (gitTagExists(root, tag)) {
+            throw new VersionError(`tag '${tag}' already exists`);
+        }
+        tagged = gitTag(root, tag, sha);
+        if (!tagged) {
+            throw new VersionError(`could not create tag '${tag}'`);
+        }
+    }
+    const row = { version, commit: short, tag };
+    writeVersions(root, [row, ...existing]);
+    return { version: row, tagged };
+}

package/dist/src/output.js

@@ -20,8 +20,11 @@ export function print(...lines) {
 export function printError(message) {
     process.stderr.write(message.endsWith('\n') ? message : message + '\n');
 }
+// The local calendar date, YYYY-MM-DD: an on-save rule at nine in the evening
+// writes today, not UTC's tomorrow.
 export function today() {
-    return new Date().toISOString().slice(0, 10);
+    const now = new Date();
+    return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
 }
 // Left-aligned columns for a plain table; widths from the widest cell.
 export function table(rows, gap = 2) {