eidosmd 0.1.0 → 0.3.0

package/dist/src/commands/property.js

@@ -0,0 +1,125 @@
+// `eidos property get|set|unset @<blueprint> <property> [<value>]`: one
+// blueprint's frontmatter from the shell, so an agent never opens a file to
+// flip a value. A set is typed by the property's declared type, written in
+// the house style with every other line as it was, and applies the root's
+// on-save rules the way a save from the browser does.
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { resolveBlueprint } from '../core/blueprint.js';
+import { checkRoot, optionProblem } from '../core/check.js';
+import { blueprintKeySet, blueprintKeyUnset } from '../core/edits.js';
+import { propertiesFor } from '../core/framework.js';
+import { editFrontmatterKey, parseFrontmatter } from '../core/frontmatter.js';
+import { coerce } from '../core/scaffold.js';
+import { readSettings } from '../core/settings.js';
+import { standardVersion } from '../paths.js';
+import { CliError, EXIT_FINDINGS, EXIT_OK, print, printJson, today } from '../output.js';
+import { strictFor } from './check.js';
+function resolve(context, ref) {
+    const clean = ref.replace(/^@/, '');
+    const blueprint = resolveBlueprint(clean, context.blueprints, context.cwd);
+    if (!blueprint)
+        throw new CliError(`no blueprint '${clean}' (an id, a path, or a filename)`);
+    return blueprint;
+}
+// The local time to the minute, the same stamp an on-save rule writes from the page.
+function localMinute() {
+    const now = new Date();
+    return `${today()} ${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')}`;
+}
+function withOnSaveRules(root, text) {
+    let out = text;
+    for (const rule of readSettings(root).shared.on_save)
+        out = editFrontmatterKey(out, { kind: 'set', key: rule.property, value: rule.set === 'today' ? today() : localMinute() });
+    return out;
+}
+function report(context, blueprint, options, what) {
+    const fresh = context.blueprints.map((held) => (held.path === blueprint.path ? reload(blueprint) : held));
+    const check = checkRoot(context.framework, fresh, { only: new Set([blueprint.path]), standardVersion: standardVersion() });
+    const findings = check.findings.filter((finding) => finding.path === blueprint.rel);
+    const strict = strictFor(context.root, undefined);
+    const failed = findings.some((finding) => finding.level === 'error') || (strict && findings.some((finding) => finding.level === 'warning'));
+    if (options.json) {
+        printJson({ ok: !failed, path: blueprint.rel, ...what, findings });
+        return failed ? EXIT_FINDINGS : EXIT_OK;
+    }
+    for (const finding of findings)
+        print(`  ${finding.level === 'error' ? '✗' : '⚠'} ${finding.code}  ${finding.message}`);
+    return failed ? EXIT_FINDINGS : EXIT_OK;
+}
+function reload(blueprint) {
+    const { properties, body, error } = parseFrontmatter(readFileSync(blueprint.path, 'utf8'));
+    return { ...blueprint, properties, frontmatterError: error, body };
+}
+export function runPropertyGet(context, ref, key, options) {
+    const blueprint = resolve(context, ref);
+    const properties = blueprint.properties ?? {};
+    if (key !== undefined) {
+        if (!(key in properties))
+            throw new CliError(`${blueprint.rel} has no '${key}'`);
+        if (options.json)
+            printJson({ path: blueprint.rel, [key]: properties[key] });
+        else
+            print(typeof properties[key] === 'string' ? properties[key] : JSON.stringify(properties[key]));
+        return EXIT_OK;
+    }
+    if (options.json)
+        printJson({ path: blueprint.rel, properties });
+    else
+        for (const [name, value] of Object.entries(properties))
+            print(`${name}: ${typeof value === 'string' ? value : JSON.stringify(value)}`);
+    return EXIT_OK;
+}
+export function runPropertySet(context, ref, key, raw, options) {
+    const blueprint = resolve(context, ref);
+    const declared = propertiesFor(context.framework, blueprint.collection.name).find((property) => property.name === key);
+    if (!declared) {
+        const elsewhere = [...context.framework.schema.custom, ...Object.values(context.framework.schema.tools).flat()].find((property) => property.name === key);
+        if (!options.force)
+            throw new CliError(elsewhere ? `${key} applies to ${elsewhere.appliesTo === 'all' ? 'all' : elsewhere.appliesTo.join(', ')}, not ${blueprint.collection.name}; check would report it (--force writes it anyway)` : `no block of the Properties table declares '${key}' for ${blueprint.collection.name}; check would report it (--force writes it anyway, configure:property add declares it)`);
+    }
+    if (declared && declared.owner !== 'eidos' && declared.owner !== 'custom' && !options.force)
+        throw new CliError(`${key} is ${declared.owner}'s own property; only that tool writes it (--force writes it anyway)`);
+    const value = coerce(declared?.type ?? 'Text', raw);
+    if (declared && declared.type.toLowerCase() === 'date' && !/^\d{4}-\d{2}-\d{2}$/.test(String(value)))
+        throw new CliError(`${key} is a Date: YYYY-MM-DD`);
+    if (declared && declared.type.toLowerCase() === 'number' && typeof value !== 'number')
+        throw new CliError(`${key} is a Number`);
+    const offList = declared ? optionProblem(declared, value) : null;
+    if (offList && !options.force)
+        throw new CliError(`${key} is one of ${offList.options.join(', ')}; '${offList.off.join(', ')}' is not (--force writes it anyway, and check reports it)`);
+    const text = withOnSaveRules(context.root, blueprintKeySet(blueprint, key, value));
+    if (options.dryRun) {
+        if (options.json)
+            printJson({ path: blueprint.rel, [key]: value, dry_run: true, text });
+        else
+            print(text.split('\n---')[0] + '\n---');
+        return EXIT_OK;
+    }
+    writeFileSync(blueprint.path, text, 'utf8');
+    if (!options.json)
+        print(`✓ ${blueprint.rel}  ${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`);
+    return report(context, blueprint, options, { [key]: value });
+}
+export function runPropertyUnset(context, ref, key, options) {
+    const blueprint = resolve(context, ref);
+    const next = blueprintKeyUnset(blueprint, key);
+    if (next === null)
+        throw new CliError(`${blueprint.rel} has no '${key}'`);
+    const declared = propertiesFor(context.framework, blueprint.collection.name).find((property) => property.name === key);
+    if (declared?.required && !options.dryRun)
+        print(`  ! ${key} is required for ${blueprint.collection.name}; check will report it missing`);
+    const text = withOnSaveRules(context.root, next);
+    if (options.dryRun) {
+        if (options.json)
+            printJson({ path: blueprint.rel, unset: key, dry_run: true, text });
+        else
+            print(text.split('\n---')[0] + '\n---');
+        return EXIT_OK;
+    }
+    writeFileSync(blueprint.path, text, 'utf8');
+    if (!options.json)
+        print(`✓ ${blueprint.rel}  ${key} removed`);
+    return report(context, blueprint, options, { unset: key });
+}
+export const relativeTo = (root, file) => path.relative(root, file).split(path.sep).join('/');

package/dist/src/commands/seeds.js

@@ -1,4 +1,4 @@
-// `eidos seeds`: the bundled starting frameworks, read from their own Framework.md.
+// `eidos seeds`: the bundled starting frameworks, read from their own Framework.yaml.
 import { listSeeds } from '../core/seed.js';
 import { seedsDir } from '../paths.js';
 import { EXIT_OK, print, printJson } from '../output.js';
@@ -13,7 +13,7 @@ export function runSeeds(options) {
                 framing: collection.framing,
                 description: collection.description,
                 grouping: collection.grouping?.label ?? null,
-                flavors: collection.flavors.map((flavor) => ({ name: flavor.name, description: flavor.description, default: flavor.isDefault })),
+                variants: collection.variants.map((variant) => ({ name: variant.name, description: variant.description, default: variant.isDefault })),
             })),
         })));
         return EXIT_OK;
@@ -29,9 +29,9 @@ export function runSeeds(options) {
                 role = `grouped by ${collection.grouping.label.toLowerCase()}`;
             }
             print(`  ${collection.name} — ${role}`, `    ${collection.description}`);
-            for (const flavor of collection.flavors) {
-                const marker = flavor.isDefault ? ' (default)' : '';
-                print(flavor.description ? `    · ${flavor.name} — ${flavor.description}${marker}` : `    · ${flavor.name}${marker}`);
+            for (const variant of collection.variants) {
+                const marker = variant.isDefault ? ' (default)' : '';
+                print(variant.description ? `    · ${variant.name} — ${variant.description}${marker}` : `    · ${variant.name}${marker}`);
             }
         }
     }

package/dist/src/commands/setup.js

@@ -0,0 +1,131 @@
+// `eidos setup`: the CLI's own settings for a root, asked in the terminal or
+// given as flags: whether git is read, the people who work here (name, alias
+// for @mentions, role from .eidos/roles/, email), and who this machine acts
+// as. Writes .eidos/plugins/eidosmd/settings.yaml (shared) and local.yaml
+// (personal); nothing of the standard's changes.
+import { createInterface } from 'node:readline/promises';
+import { gitHead, gitUser } from '../core/git.js';
+import { listRoles } from '../core/me.js';
+import { cleanAlias, findUser, matchesIdentity, readSettings, writeSettings } from '../core/settings.js';
+import { CliError, EXIT_OK, print, printJson } from '../output.js';
+export const interactive = () => process.stdin.isTTY === true && process.stdout.isTTY === true;
+// One line, with a default shown in brackets; an empty answer takes it.
+async function ask(question, fallback) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`${question}${fallback === '' ? '' : ` [${fallback}]`}: `)).trim();
+        return answer === '' ? fallback : answer;
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function askYesNo(question, fallback) {
+    const answer = (await ask(`${question} (${fallback ? 'Y/n' : 'y/N'})`, '')).toLowerCase();
+    if (answer === '')
+        return fallback;
+    return answer.startsWith('y');
+}
+const onOff = (value) => (value === undefined ? null : /^(on|true|yes|1)$/i.test(value) ? true : /^(off|false|no|0)$/i.test(value) ? false : null);
+function describe(root, settings) {
+    const inRepo = gitHead(root) !== null;
+    const identity = inRepo ? gitUser(root) : null;
+    const lines = [
+        `git features: ${settings.shared.features.git ? 'on' : 'off'}${inRepo ? '' : ' (this root is not in a git repository)'}${identity ? `; git identity ${identity.name}${identity.email ? ` <${identity.email}>` : ''}` : ''}`,
+        `strict checks: ${settings.shared.check.strict ? 'on (a warning fails eidos check)' : 'off (only an error fails eidos check)'}`,
+        settings.shared.users.length === 0 ? 'users: none' : `users: ${settings.shared.users.map((user) => `${user.name}${user.alias ? ` (@${user.alias})` : ''}${user.role ? ` · ${user.role}` : ''}`).join(', ')}`,
+        `acting as: ${settings.local.user ?? (identity ? `the git identity (${identity.name})` : 'the role in me.md')}`,
+        `files: ${settings.files.shared} (shared), ${settings.files.local} (yours, gitignored)`,
+    ];
+    return lines;
+}
+// After `eidos init`: the two settings a framework owner decides once and
+// commits with the root, whether the browser reads git and whether a warning
+// fails the check. A flag answers either without a question; in a terminal
+// the rest is asked; anywhere else the root stays as the flags left it and
+// the browser asks about git instead.
+export async function offerSetup(root, given) {
+    if (given.strict !== undefined)
+        writeSettings(root, { shared: { check: { strict: given.strict } } });
+    if (!interactive())
+        return;
+    const settings = readSettings(root);
+    const inRepo = gitHead(root) !== null;
+    const git = settings.configured ? settings.shared.features.git : await askYesNo(`Use git features in the browser (history, authors, versions)?${inRepo ? '' : ' The root is not in a repository yet'}`, true);
+    const strict = given.strict ?? (await askYesNo('Should a warning fail `eidos check`, the way an error does? (strict; kept with the root for CI and everyone)', false));
+    writeSettings(root, { shared: { features: { git }, check: { strict } } });
+    print(`  git features ${git ? 'on' : 'off'}; strict checks ${strict ? 'on' : 'off'} (eidos setup changes both, and adds the people who work here)`);
+}
+export async function runSetup(context, options) {
+    const root = context.root;
+    let settings = readSettings(root);
+    const flagged = options.git !== undefined || options.strict !== undefined || options.addUser.length > 0 || options.as !== undefined;
+    if (flagged) {
+        const git = onOff(options.git);
+        if (options.git !== undefined && git === null)
+            throw new CliError('--git takes on or off');
+        const strict = onOff(options.strict);
+        if (options.strict !== undefined && strict === null)
+            throw new CliError('--strict takes on or off');
+        const users = settings.shared.users.map((user) => ({ ...user }));
+        for (const name of options.addUser) {
+            if (name.trim() === '')
+                throw new CliError('--add-user needs a name');
+            const alias = cleanAlias(options.alias) ?? null;
+            const holder = alias ? findUser(users, alias) : undefined;
+            if (holder && holder.name !== name.trim())
+                throw new CliError(`the alias @${alias} is taken`);
+            const held = users.find((user) => user.name.toLowerCase() === name.trim().toLowerCase());
+            const entry = { name: name.trim(), alias: alias ?? held?.alias ?? null, role: options.role ?? held?.role ?? null, email: options.email ?? held?.email ?? null };
+            if (entry.role && !listRoles(root).some((role) => role.name === entry.role))
+                throw new CliError(`no role '${entry.role}' under .eidos/roles/ (eidos roles lists them)`);
+            if (held)
+                Object.assign(held, entry);
+            else
+                users.push(entry);
+        }
+        if (options.as !== undefined && options.as !== '' && !findUser(users, options.as))
+            throw new CliError(`no user '${options.as}'; add one with --add-user`);
+        settings = writeSettings(root, {
+            shared: { ...(git === null ? {} : { features: { git } }), ...(strict === null ? {} : { check: { strict } }), ...(options.addUser.length > 0 ? { users } : {}) },
+            ...(options.as !== undefined ? { local: { user: options.as === '' ? null : options.as } } : {}),
+        });
+    }
+    else if (interactive()) {
+        print(...describe(root, settings), '');
+        const inRepo = gitHead(root) !== null;
+        const git = await askYesNo(`Use git features in the browser (history, authors, versions)?${inRepo ? '' : ' The root is not in a repository yet'}`, settings.shared.features.git);
+        const strict = await askYesNo('Should a warning fail `eidos check`, the way an error does? (strict; kept with the root)', settings.shared.check.strict);
+        const users = settings.shared.users.map((user) => ({ ...user }));
+        const identity = git && inRepo ? gitUser(root) : null;
+        let acting = settings.local.user;
+        if (identity && !users.some((user) => matchesIdentity(user, identity))) {
+            if (await askYesNo(`Add ${identity.name}${identity.email ? ` <${identity.email}>` : ''} as a user?`, true)) {
+                const alias = cleanAlias(await ask('Alias for @mentions (no spaces)', identity.name.split(/\s+/)[0]?.toLowerCase() ?? ''));
+                const roles = listRoles(root).map((role) => role.name);
+                const role = roles.length === 0 ? '' : await ask(`Role in this framework (${roles.join(', ')}; blank for none)`, '');
+                if (role !== '' && !roles.includes(role))
+                    throw new CliError(`no role '${role}' under .eidos/roles/`);
+                users.push({ name: identity.name, alias, role: role === '' ? null : role, email: identity.email });
+                acting = alias ?? identity.name;
+            }
+        }
+        if (users.length > 0) {
+            const answer = await ask(`Act as (${users.map((user) => user.alias ?? user.name).join(', ')}; blank for the git identity)`, acting ?? '');
+            if (answer !== '' && !findUser(users, answer))
+                throw new CliError(`no user '${answer}'`);
+            acting = answer === '' ? null : answer;
+        }
+        settings = writeSettings(root, { shared: { features: { git }, check: { strict }, users }, local: { user: acting } });
+    }
+    else {
+        print(...describe(root, settings), '', 'not a terminal: set values with flags, e.g. eidos setup --git on --strict off --add-user "Ada Lovelace" --alias ada --role developer --as ada');
+        return EXIT_OK;
+    }
+    if (options.json) {
+        printJson({ shared: settings.shared, local: settings.local, files: settings.files });
+        return EXIT_OK;
+    }
+    print('✓ settings written', ...describe(root, settings).map((line) => `  ${line}`));
+    return EXIT_OK;
+}

package/dist/src/commands/version.js

@@ -0,0 +1,44 @@
+// `eidos version`: the root's own versions, this CLI's own record under
+// .eidos/plugins/eidosmd/, listed, or one recorded because the owner asked: a
+// name, a commit that exists, and a tag only on --tag. Never proposed; an
+// empty list is the normal state.
+import path from 'node:path';
+import { readVersions, recordVersion, tagPrefix, VersionError, versionsFile } from '../core/versions.js';
+import { CliError, EXIT_OK, print, printJson } from '../output.js';
+export function runVersionList(context, options) {
+    const versions = readVersions(context.root);
+    if (options.json) {
+        printJson(versions);
+        return EXIT_OK;
+    }
+    if (versions.length === 0) {
+        print('no versions recorded (the normal state); record one when a team needs a fixed point: eidos version record <version> [--commit <sha>] [--tag]');
+        return EXIT_OK;
+    }
+    for (const version of versions) {
+        print(`${version.version}  ${version.commit}${version.tag ? `  ${version.tag}` : ''}`);
+    }
+    return EXIT_OK;
+}
+export function runVersionRecord(context, version, options) {
+    let recorded;
+    try {
+        recorded = recordVersion(context.root, { version, commit: options.commit, tag: options.tag });
+    }
+    catch (cause) {
+        if (cause instanceof VersionError) {
+            throw new CliError(cause.message);
+        }
+        throw cause;
+    }
+    if (options.json) {
+        printJson({ ...recorded.version, tagged: recorded.tagged });
+        return EXIT_OK;
+    }
+    print(`✓ ${recorded.version.version} → ${recorded.version.commit}${recorded.version.tag ? `  tagged ${recorded.version.tag}` : ''}`);
+    if (!recorded.version.tag) {
+        print(`  (no tag; --tag would have created ${tagPrefix(context.root)}${recorded.version.version})`);
+    }
+    print(`  recorded in ${path.relative(context.root, versionsFile(context.root))}; the commit that adds it is not the one it names, the way a tag follows the commit it marks`);
+    return EXIT_OK;
+}

package/dist/src/commands/whoami.js

@@ -11,7 +11,7 @@ export function runRoles(context, options) {
         return EXIT_OK;
     }
     if (roles.length === 0) {
-        print('no roles installed under _eidos/roles/; an older framework, or one that declares none');
+        print('no roles installed under .eidos/roles/; an older framework, or one that declares none');
         return EXIT_OK;
     }
     for (const role of roles) {
@@ -43,7 +43,7 @@ export function runWhoami(context, options) {
             if (!role) {
                 if (options.role !== undefined && listRoles(context.root).length > 0) {
                     const known = listRoles(context.root).map((candidate) => candidate.name).join(', ');
-                    throw new CliError(`no role '${options.role}' under _eidos/roles/ (installed: ${known}); a custom role is set by editing _eidos/me.md`);
+                    throw new CliError(`no role '${options.role}' under .eidos/roles/ (installed: ${known}); a custom role is set by editing .eidos/me.md`);
                 }
                 custom = roleName;
             }
@@ -67,7 +67,7 @@ export function runWhoami(context, options) {
         return EXIT_OK;
     }
     if (!exists) {
-        print('no _eidos/me.md: the actor is unset, so the agent defaults to full facilitation', 'set it: eidos whoami --role <name>');
+        print('no .eidos/me.md: the actor is unset, so the agent defaults to full facilitation', 'set it: eidos whoami --role <name>');
         return EXIT_OK;
     }
     if (actor.role === null) {
@@ -75,7 +75,7 @@ export function runWhoami(context, options) {
         return runRoles(context, { json: false });
     }
     print(`you are: ${actor.role}`);
-    const roleFile = actor.roleFile ? path.resolve(context.root, '_eidos', actor.roleFile) : null;
+    const roleFile = actor.roleFile ? path.resolve(context.root, '.eidos', actor.roleFile) : null;
     if (roleFile && existsSync(roleFile)) {
         print(`role file: ${path.relative(context.root, roleFile).split(path.sep).join('/')}`, '', readFileSync(roleFile, 'utf8').trimEnd(), '');
     }

package/dist/src/context.js

@@ -4,9 +4,9 @@ import { listBlueprints } from './core/blueprint.js';
 import { FrameworkError, loadFramework } from './core/framework.js';
 import { findRoot, RootError } from './core/root.js';
 import { CliError, EXIT_USAGE } from './output.js';
-// The CLI works on Framework.yaml. A root that keeps Framework.md is read only
-// to convert it (or to print it), so every other command points at `convert`.
-export function loadRoot(globals, cwd = process.cwd(), options = {}) {
+// The framework document is Framework.yaml. A root that still keeps the
+// 4.x Framework.md is read only by `migrate`, so every command points there.
+export function loadRoot(globals, cwd = process.cwd()) {
     let root;
     try {
         root = findRoot(cwd, globals.root);
@@ -28,8 +28,8 @@ export function loadRoot(globals, cwd = process.cwd(), options = {}) {
         }
         throw cause;
     }
-    if (framework.format === 'md' && !options.allowMarkdown) {
-        throw new CliError(`${root} keeps its framework as _eidos/Framework.md. The eidos CLI works on Framework.yaml: run \`eidos convert\` to move it (Framework.md and each collection's index.md are removed; the markdown form's prose has no field to land in). \`eidos convert --dry-run\` shows the writes, and \`eidos framework --as yaml\` prints the result without touching anything.`, EXIT_USAGE);
+    if (framework.format === 'md') {
+        throw new CliError(`${root} keeps its framework as .eidos/Framework.md, the form before Eidos 5.0.0. Run \`eidos migrate\` to move it: Framework.yaml takes its place with the index inside, and Framework.md and each collection's index.md are removed (the markdown form's prose has no field to land in). \`eidos migrate --dry-run\` lists the moves without touching anything.`, EXIT_USAGE);
     }
     return { cwd, root, framework, blueprints: listBlueprints(framework) };
 }

package/dist/src/core/blueprint.js

@@ -4,10 +4,13 @@
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { parseFrontmatter } from './frontmatter.js';
-import { defaultFlavor, findFlavor } from './framework.js';
+import { defaultVariant, findVariant } from './framework.js';
 import { headings, sections } from './markdown.js';
 import { kebab } from './naming.js';
-export function blueprintFiles(dir) {
+// Under a markdown framework each collection's `index.md` is the generated
+// leaf, not a blueprint. Under a YAML one the index lives in the document, so
+// `index.md` is an ordinary filename (a blueprint with the id `index`).
+export function blueprintFiles(dir, leafIsIndexMd) {
     let entries;
     try {
         entries = readdirSync(dir);
@@ -16,7 +19,7 @@ export function blueprintFiles(dir) {
         return [];
     }
     return entries
-        .filter((entry) => /\.md$/i.test(entry) && entry.toLowerCase() !== 'index.md' && !entry.startsWith('.'))
+        .filter((entry) => /\.md$/i.test(entry) && !(leafIsIndexMd && entry.toLowerCase() === 'index.md') && !entry.startsWith('.'))
         .filter((entry) => {
         try {
             return statSync(path.join(dir, entry)).isFile();
@@ -69,11 +72,12 @@ export function listBlueprints(framework, collections = framework.collections) {
     const out = [];
     for (const collection of collections) {
         const dir = path.join(framework.root, collection.name);
-        for (const file of blueprintFiles(dir)) {
+        const leafIsIndexMd = framework.format === 'md';
+        for (const file of blueprintFiles(dir, leafIsIndexMd)) {
             out.push(loadBlueprint(framework.root, collection, null, file));
         }
         for (const group of groupDirs(dir)) {
-            for (const file of blueprintFiles(path.join(dir, group))) {
+            for (const file of blueprintFiles(path.join(dir, group), leafIsIndexMd)) {
                 out.push(loadBlueprint(framework.root, collection, group, file));
             }
         }
@@ -99,14 +103,15 @@ export function blueprintId(blueprint) {
 export function blueprintTitle(blueprint) {
     return propertyString(blueprint, 'title') ?? blueprint.stem;
 }
-// The flavor a blueprint follows: the one it names, else its collection's default.
-export function resolveFlavor(blueprint) {
-    const declared = propertyString(blueprint, 'flavor');
+// The variant a blueprint follows: the one it names, else its collection's default.
+export function resolveVariant(blueprint) {
+    // `flavor` is the name before 5.0.0; a root not yet migrated still resolves
+    const declared = propertyString(blueprint, 'variant') ?? propertyString(blueprint, 'flavor');
     if (declared === null) {
-        return { flavor: defaultFlavor(blueprint.collection), declared: null, known: true };
+        return { variant: defaultVariant(blueprint.collection), declared: null, known: true };
     }
-    const flavor = findFlavor(blueprint.collection, declared);
-    return { flavor, declared, known: flavor !== null };
+    const variant = findVariant(blueprint.collection, declared);
+    return { variant, declared, known: variant !== null };
 }
 // A blueprint by path, by id, or by filename stem, in that order.
 export function resolveBlueprint(ref, blueprints, cwd) {

package/dist/src/core/canvas-schema.js

@@ -0,0 +1,148 @@
+// The canvas file, as a JSON Schema (draft 7): what `.eidos/plugins/eidosmd/maps/<id>.yaml`
+// may hold. The file is the whole truth of a canvas; the browser draws it and writes it
+// back, and anything else (a person, an agent) edits it directly.
+import { ANCHORS, EDGE_CAPS } from './canvas.js';
+const hex = { type: 'string', pattern: '^#[0-9a-fA-F]{6}$', description: 'A color as #rrggbb.' };
+const size = { type: 'string', enum: ['small', 'medium', 'large'] };
+const point = { type: 'object', required: ['x', 'y'], additionalProperties: false, properties: { x: { type: 'number' }, y: { type: 'number' } } };
+export const CANVAS_SCHEMA = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    title: 'Eidos canvas map',
+    description: 'One canvas of the eidosmd browser: a title and pages, each with frames, nodes, edges, layout, and comment threads. Kept at .eidos/plugins/eidosmd/maps/<id>.yaml; the id is the file name.',
+    type: 'object',
+    required: ['title', 'pages'],
+    additionalProperties: false,
+    properties: {
+        title: { type: 'string' },
+        pages: { type: 'array', minItems: 1, items: { $ref: '#/definitions/page' } },
+    },
+    definitions: {
+        page: {
+            type: 'object',
+            required: ['id', 'title'],
+            additionalProperties: false,
+            properties: {
+                id: { type: 'string', description: 'Unique within the canvas; the URL names it.' },
+                title: { type: 'string' },
+                frames: { type: 'array', items: { $ref: '#/definitions/frame' } },
+                nodes: { type: 'array', items: { $ref: '#/definitions/node' } },
+                edges: { type: 'array', items: { $ref: '#/definitions/edge' } },
+                layout: { type: 'object', description: 'Where each node sits, by node id. A node without a place is laid out by the browser and given one when it first moves.', additionalProperties: point },
+                comments: { type: 'array', items: { $ref: '#/definitions/comment' } },
+            },
+        },
+        node: {
+            type: 'object',
+            required: ['id'],
+            additionalProperties: false,
+            description: 'Exactly one of blueprint, sketch, sticky, text, or annotation says what the node is.',
+            oneOf: [{ required: ['blueprint'] }, { required: ['sketch'] }, { required: ['sticky'] }, { required: ['text'] }, { required: ['annotation'] }],
+            properties: {
+                id: { type: 'string', description: 'Unique within the page; edges name it.' },
+                blueprint: { type: 'string', description: "A blueprint's id; its title, summary, and styled properties are read from the file when drawn." },
+                sketch: { $ref: '#/definitions/sketch' },
+                sticky: { $ref: '#/definitions/sticky' },
+                text: { $ref: '#/definitions/text' },
+                annotation: { $ref: '#/definitions/annotation' },
+                frame: { type: 'string', description: 'The frame this node is attached to; it moves with the frame.' },
+                link: { type: 'object', additionalProperties: false, properties: { page: { type: 'string' }, canvas: { type: 'string' } }, description: 'What the card opens: another page, or another canvas.' },
+                locked: { type: 'boolean' },
+                style: { $ref: '#/definitions/style' },
+                styled: { type: 'boolean', description: 'Styled by hand: a change to a styling property asks before the default is applied.' },
+                box: { type: 'object', required: ['w', 'h'], additionalProperties: false, properties: { w: { type: 'number', minimum: 40 }, h: { type: 'number', minimum: 24 } }, description: 'An exact size; text wraps and scrolls inside it.' },
+            },
+        },
+        sketch: {
+            type: 'object',
+            required: ['label'],
+            additionalProperties: false,
+            description: 'A node that is not a blueprint yet; eidos new promotes it.',
+            properties: {
+                label: { type: 'string', description: 'The title; may be empty until written.' },
+                kind: { type: 'string' },
+                status: { type: 'string' },
+                note: { type: 'string', description: 'The description.' },
+                properties: { type: 'object', additionalProperties: { type: 'string' }, description: 'Values of schema properties that apply to every collection, held until promotion.' },
+            },
+        },
+        sticky: { type: 'object', required: ['text'], additionalProperties: false, properties: { text: { type: 'string' }, color: { type: 'string', enum: ['yellow', 'pink', 'blue', 'green', 'purple', 'orange'] } } },
+        text: { type: 'object', required: ['text'], additionalProperties: false, properties: { text: { type: 'string' }, size, font: { type: 'integer', minimum: 8, maximum: 64, description: 'An exact size in pixels; wins over size.' } } },
+        annotation: { type: 'object', required: ['text'], additionalProperties: false, description: 'A note that points at a node or a frame through an edge from it; one that points at nothing is removed.', properties: { text: { type: 'string' }, color: hex } },
+        style: {
+            type: 'object',
+            additionalProperties: false,
+            description: "A node's own look over the default its properties give it.",
+            properties: {
+                shape: { type: 'string', enum: ['box', 'pill', 'parallelogram'] },
+                color: { ...hex, description: 'The highlight: the bar and the border.' },
+                fill: { type: 'string', enum: ['solid', 'tint', 'none'] },
+                fill_color: hex,
+                size,
+            },
+        },
+        edge: {
+            type: 'object',
+            required: ['from', 'to'],
+            additionalProperties: false,
+            description: 'A flow between two nodes, or to a frame border as frame:<id>.',
+            properties: {
+                from: { type: 'string' },
+                to: { type: 'string' },
+                label: { type: 'string' },
+                label_at: { type: 'number', minimum: 0, maximum: 1, description: 'Where along the line the label sits.' },
+                bend: { type: 'number', description: 'Where the middle segment turns, along its axis.' },
+                from_anchor: { type: 'string', enum: [...ANCHORS] },
+                to_anchor: { type: 'string', enum: [...ANCHORS] },
+                color: hex,
+                style: { type: 'string', enum: ['solid', 'dashed'] },
+                start: { type: 'string', enum: [...EDGE_CAPS] },
+                end: { type: 'string', enum: [...EDGE_CAPS], description: 'A solid arrowhead (triangle) when absent.' },
+            },
+        },
+        frame: {
+            type: 'object',
+            required: ['id', 'title'],
+            additionalProperties: false,
+            description: 'A region drawn around nodes; what is attached moves with it.',
+            properties: {
+                id: { type: 'string' },
+                title: { type: 'string' },
+                x: { type: 'number' },
+                y: { type: 'number' },
+                w: { type: 'number' },
+                h: { type: 'number' },
+                color: { type: 'string', enum: ['none', 'sand', 'sky', 'mint', 'rose', 'lilac'] },
+                locked: { type: 'boolean' },
+                frame: { type: 'string', description: 'The frame this frame is attached to.' },
+            },
+        },
+        comment: {
+            type: 'object',
+            required: ['id', 'x', 'y', 'messages'],
+            additionalProperties: false,
+            description: 'A thread pinned to a point, or to a node with x and y as the offset from it.',
+            properties: {
+                id: { type: 'string' },
+                x: { type: 'number' },
+                y: { type: 'number' },
+                node: { type: 'string' },
+                resolved: { type: 'boolean' },
+                messages: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        required: ['author', 'text', 'at'],
+                        additionalProperties: false,
+                        properties: {
+                            author: { type: 'string' },
+                            role: { type: 'string', description: 'The role the author held in this root when they wrote it.' },
+                            user: { type: 'string', description: 'The user (alias, else name) from the root\'s settings, when one was known.' },
+                            text: { type: 'string' },
+                            at: { type: 'string', description: 'When, as an ISO 8601 time.' },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};