eidosmd 0.1.0 → 0.2.0

package/dist/src/core/seed.js

@@ -1,19 +1,20 @@
-// Installing a seed: copy a starting framework into a new root's `_eidos/`,
-// write it as Framework.yaml with its naming convention and starting groups,
-// scaffold a folder per collection, and drop one blank blueprint per framing
-// flavor.
+// Installing a seed: copy a starting framework into a new root's `.eidos/`,
+// set the naming convention, the starting groups, and the collection names in
+// its Framework.yaml (the seed's own comments kept), scaffold a folder per
+// collection, and drop one blank blueprint per framing variant.
 // It writes no prose: the README's one-liner, each group's description, and
 // every scaffolded blueprint's summary and body stay the owner's.
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { formatFrontmatter } from './frontmatter.js';
 import { parseFramework, propertiesFor } from './framework.js';
-import { frameworkToDocument, serializeDocument } from './framework-structured.js';
 import { buildIndexes } from './index-leaf.js';
 import { listBlueprints } from './blueprint.js';
 import { convert, kebab, titleize } from './naming.js';
-import { renderShape } from './shape.js';
-const GROUP_PROMPT = '_(one line on what belongs here)_';
+import { renderTemplate } from './template.js';
+import { TOOL_KEY } from './framework-model.js';
+import { DEFAULT_CANVAS_HINTS } from './canvas.js';
+import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
 const GITIGNORE_SHIPPED = '_gitignore';
 export function listSeeds(seedsDir) {
     if (!existsSync(seedsDir)) {
@@ -22,12 +23,12 @@ export function listSeeds(seedsDir) {
     return readdirSync(seedsDir)
         .sort()
         .map((name) => path.join(seedsDir, name))
-        .filter((dir) => existsSync(path.join(dir, 'Framework.md')))
+        .filter((dir) => existsSync(path.join(dir, 'Framework.yaml')))
         .map((dir) => ({ name: path.basename(dir), dir, framework: readSeedFramework(dir) }));
 }
 function readSeedFramework(dir) {
-    const file = path.join(dir, 'Framework.md');
-    return parseFramework(readFileSync(file, 'utf8'), 'md', dir, file);
+    const file = path.join(dir, 'Framework.yaml');
+    return parseFramework(readFileSync(file, 'utf8'), 'yaml', dir, file);
 }
 export class InstallError extends Error {
     constructor(message) {
@@ -73,26 +74,57 @@ class Writer {
         }
     }
 }
-function setNaming(text, naming) {
-    if (/^naming:.*$/m.test(text)) {
-        return text.replace(/^naming:.*$/m, `naming: ${naming}`);
+const mapsIn = (value) => (isSeq(value) ? value.items.filter((item) => isMap(item)) : []);
+const nameOf = (map) => String(map.get('name') ?? '');
+// The seed's collections and the properties scoped to them, renamed into the
+// root's convention; every other key, and every comment, stays as the seed wrote it.
+function renameCollections(document, renames) {
+    for (const collection of mapsIn(document.get('collections'))) {
+        const to = renames.get(nameOf(collection));
+        if (to !== undefined)
+            collection.set('name', to);
+    }
+    const properties = document.get('properties');
+    if (!isMap(properties))
+        return;
+    const blocks = [properties.get('custom'), ...(isMap(properties.get('tools')) ? properties.get('tools').items.map((pair) => pair.value) : [])];
+    for (const block of blocks) {
+        for (const property of mapsIn(block)) {
+            const applies = property.get('applies_to');
+            if (!isSeq(applies))
+                continue;
+            for (const item of applies.items) {
+                if (isScalar(item)) {
+                    const to = renames.get(String(item.value));
+                    if (to !== undefined)
+                        item.value = to;
+                }
+            }
+        }
     }
-    return text.replace(/^---\n/, `---\nnaming: ${naming}\n`);
 }
-// The grouping bullet's placeholder becomes one bullet per starting group, each
-// in the framework's convention so a grouping property's value can match its folder.
-function setGroups(text, label, groups) {
-    const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const pattern = new RegExp(`^-\\s+\\*\\*${escaped}:\\*\\*.*$`, 'm');
-    const bullets = groups.map((group) => `  - **${group}** — ${GROUP_PROMPT}`).join('\n');
-    return text.replace(pattern, `- **${label}:**\n${bullets}`);
+// The canvas hint is the one field the CLI prescribes; a fresh root gets the
+// legend as its default palette on the seed's own status and type.
+function applyDefaultCanvasHints(document) {
+    const properties = document.get('properties');
+    if (!isMap(properties))
+        return;
+    for (const property of mapsIn(properties.get('custom'))) {
+        const hint = DEFAULT_CANVAS_HINTS[nameOf(property)];
+        if (!hint || property.has(TOOL_KEY))
+            continue;
+        // a hint is a map of maps; a seed writes its rows in flow style, which would put all of it on one line
+        property.flow = false;
+        property.set(TOOL_KEY, document.createNode({ canvas: hint }));
+    }
 }
-function renameCollection(text, from, to) {
+// Comments name the seed's collections too; a word-bounded rename follows them.
+function renameInText(text, from, to) {
     const escaped = from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     return text.replace(new RegExp(`(?<![\\w-])${escaped}(?!\\w)`, 'g'), to);
 }
 // A blank blueprint: every property that applies to the collection, with the
-// values given and `[]` for an empty list, then the flavor's shape as the body.
+// values given and `[]` for an empty list, then the variant's template as the body.
 export function blankBlueprint(framework, collectionName, values, shapeTemplate, title) {
     const entries = propertiesFor(framework, collectionName).map((property) => {
         const value = values[property.name];
@@ -101,77 +133,136 @@ export function blankBlueprint(framework, collectionName, values, shapeTemplate,
         }
         return [property.name, value ?? ''];
     });
-    return formatFrontmatter(entries) + '\n' + renderShape(shapeTemplate, title);
+    return formatFrontmatter(entries) + '\n' + renderTemplate(shapeTemplate, title);
 }
 export function installSeed(options) {
     const seedDir = path.join(options.seedsDir, options.seed);
-    const frameworkSrc = path.join(seedDir, 'Framework.md');
+    const frameworkSrc = path.join(seedDir, 'Framework.yaml');
     if (!existsSync(frameworkSrc)) {
-        throw new InstallError(`no seed '${options.seed}' under ${options.seedsDir} (needs a Framework.md)`);
+        throw new InstallError(`no seed '${options.seed}' under ${options.seedsDir} (needs a Framework.yaml)`);
     }
     const root = path.resolve(options.root);
-    if (existsSync(path.join(root, '_eidos'))) {
-        throw new InstallError(`${root}/_eidos already exists: that is a root; use migrate`);
+    if (existsSync(path.join(root, '.eidos'))) {
+        throw new InstallError(`${root}/.eidos already exists: that is a root; use migrate`);
     }
-    let text = readFileSync(frameworkSrc, 'utf8');
-    const seedFramework = parseFramework(text, 'md', seedDir, frameworkSrc);
+    const text = readFileSync(frameworkSrc, 'utf8');
+    const seedFramework = parseFramework(text, 'yaml', seedDir, frameworkSrc);
+    const document = parseDocument(text);
     if (seedFramework.collections.length === 0) {
         throw new InstallError(`${frameworkSrc} declares no collections`);
     }
     const writer = new Writer(options.dryRun);
     const naming = options.naming;
-    // 1. the framework itself. The seed's README is the root's visible door, so it
-    //    moves to the root; roles/, shapes/, me.md, and .gitignore travel as they are.
-    writer.copyTree(seedDir, path.join(root, '_eidos'));
-    writer.remove(path.join(root, '_eidos', 'README.md'));
+    // The framing collection is the recommendation, not the standard's rule: an
+    // owner who keeps the framing elsewhere leaves it out, templates and all.
+    const leftOut = options.framing === false ? seedFramework.collections.filter((collection) => collection.framing) : [];
+    const installing = seedFramework.collections.filter((collection) => !leftOut.includes(collection));
+    if (installing.length === 0) {
+        throw new InstallError(`'${options.seed}' has only its framing collection; nothing would be left to install`);
+    }
+    // 1. the framework itself. The seed's README is the root's visible door, and so
+    //    is any other top-level doc the seed declares (the software seed's
+    //    Vocabulary), so those move to the root; roles/, templates/, me.md, and
+    //    .gitignore travel as they are.
+    const topLevelDocs = seedFramework.topLevel.filter((doc) => /^\.\.\/[^/]+\.md$/.test(doc.path) && doc.path !== '../README.md').map((doc) => ({ title: doc.title, file: doc.path.slice(3) }));
+    writer.copyTree(seedDir, path.join(root, '.eidos'));
+    writer.remove(path.join(root, '.eidos', 'README.md'));
+    for (const doc of topLevelDocs) {
+        writer.remove(path.join(root, '.eidos', doc.file));
+    }
     // npm never packs a file named .gitignore, so a seed ships it as _gitignore.
     if (existsSync(path.join(seedDir, GITIGNORE_SHIPPED))) {
-        writer.rename(path.join(root, '_eidos', GITIGNORE_SHIPPED), path.join(root, '_eidos', '.gitignore'));
+        writer.rename(path.join(root, '.eidos', GITIGNORE_SHIPPED), path.join(root, '.eidos', '.gitignore'));
+    }
+    // 2. the framework document: naming, starting groups, and each collection in
+    //    convention, edited in place so the seed's comments travel with it.
+    document.set('naming', naming);
+    for (const collection of leftOut) {
+        const collections = document.get('collections');
+        if (isSeq(collections))
+            collections.items = collections.items.filter((item) => !(isMap(item) && nameOf(item) === collection.name));
+        for (const variant of collection.variants)
+            writer.remove(path.join(root, '.eidos', variant.template));
     }
-    // 2. the Framework: naming, starting groups, and each collection in convention.
-    text = setNaming(text, naming);
     const grouped = seedFramework.collections.find((collection) => collection.grouping && !collection.framing) ?? null;
     if (options.groups.length > 0) {
         if (!grouped || !grouped.grouping) {
             throw new InstallError(`no collection in '${options.seed}' declares a grouping`);
         }
-        text = setGroups(text, grouped.grouping.label, options.groups.map((group) => convert(group, naming)));
+        const groupedNode = mapsIn(document.get('collections')).find((collection) => nameOf(collection) === grouped.name);
+        const grouping = groupedNode?.get('grouping');
+        if (!isMap(grouping)) {
+            throw new InstallError(`${frameworkSrc}: ${grouped.name} declares a grouping the document does not carry`);
+        }
+        grouping.set('groups', document.createNode(options.groups.map((group) => ({ name: convert(group, naming), description: '' }))));
     }
     const readmeSrc = path.join(seedDir, 'README.md');
     let readme = existsSync(readmeSrc) ? readFileSync(readmeSrc, 'utf8') : null;
     if (readme !== null && options.product !== null) {
         readme = readme.replace(/\{\{Product\}\}/g, options.product);
     }
-    if (readme !== null) {
-        readme = readme.replace(/Framework\.md/g, 'Framework.yaml');
+    // A declared top-level doc is a file a person reads, so it takes the naming
+    // convention (README.md alone keeps its name), and the links to it in the
+    // framework and the README move with it.
+    const docs = [];
+    for (const doc of topLevelDocs) {
+        const source = path.join(seedDir, doc.file);
+        if (!existsSync(source)) {
+            continue;
+        }
+        let body = readFileSync(source, 'utf8');
+        if (options.product !== null) {
+            body = body.replace(/\{\{Product\}\}/g, options.product);
+        }
+        const target = `${convert(doc.title, naming)}.md`;
+        if (target !== doc.file) {
+            for (const entry of mapsIn(document.get('top_level'))) {
+                if (entry.get('path') === `../${doc.file}`)
+                    entry.set('path', `../${target}`);
+            }
+            if (readme !== null) {
+                readme = readme.split(`(${doc.file})`).join(`(${target})`);
+            }
+        }
+        docs.push({ target, body });
     }
     const folders = new Map();
-    for (const collection of seedFramework.collections) {
+    const renames = new Map();
+    if (readme !== null && leftOut.length > 0) {
+        readme = readme
+            .split('\n')
+            .filter((line) => !leftOut.some((collection) => line.includes(`[${collection.name}]`)))
+            .join('\n');
+    }
+    for (const collection of installing) {
         const folder = convert(collection.name, naming);
         folders.set(collection.name, folder);
         if (folder !== collection.name) {
-            text = renameCollection(text, collection.name, folder);
+            renames.set(collection.name, folder);
             if (readme !== null) {
-                readme = renameCollection(readme, collection.name, folder);
+                readme = renameInText(readme, collection.name, folder);
             }
         }
     }
-    // The seed's markdown is the source; the root gets the same framework as
-    // YAML, with the guidance as comments. The seed's prose (section intros,
-    // HTML comments) has no field to land in and stays in the seed.
-    const fromSeed = parseFramework(text, 'md', root, path.join(root, '_eidos', 'Framework.md'));
-    writer.remove(path.join(root, '_eidos', 'Framework.md'));
-    const frameworkFile = path.join(root, '_eidos', 'Framework.yaml');
-    const serialized = serializeDocument(frameworkToDocument(fromSeed));
+    renameCollections(document, renames);
+    applyDefaultCanvasHints(document);
+    let serialized = document.toString({ lineWidth: 0 });
+    for (const [from, to] of renames) {
+        serialized = renameInText(serialized, from, to);
+    }
+    const frameworkFile = path.join(root, '.eidos', 'Framework.yaml');
     writer.write(frameworkFile, serialized);
     const installed = parseFramework(serialized, 'yaml', root, frameworkFile);
     if (readme !== null) {
         writer.write(path.join(root, 'README.md'), readme);
     }
+    for (const doc of docs) {
+        writer.write(path.join(root, doc.target), doc.body);
+    }
     // 3. a folder per collection; blank blueprints for the framing one.
     const scaffolded = [];
     const groupsInConvention = options.groups.map((group) => convert(group, naming));
-    for (const collection of seedFramework.collections) {
+    for (const collection of installing) {
         const folderName = folders.get(collection.name) ?? collection.name;
         const folder = path.join(root, folderName);
         writer.mkdir(folder);
@@ -183,22 +274,22 @@ export function installSeed(options) {
         if (!collection.framing) {
             continue;
         }
-        for (const flavor of collection.flavors) {
-            const shapeFile = path.join(seedDir, flavor.shape);
-            if (!existsSync(shapeFile)) {
-                writer.actions.push(`skip   ${collection.name}/${flavor.name}: no shape at ${flavor.shape}`);
+        for (const variant of collection.variants) {
+            const templateFile = path.join(seedDir, variant.template);
+            if (!existsSync(templateFile)) {
+                writer.actions.push(`skip   ${collection.name}/${variant.name}: no template at ${variant.template}`);
                 continue;
             }
-            const title = titleize(flavor.name);
+            const title = titleize(variant.name);
             const values = {
-                id: kebab(flavor.name),
+                id: kebab(variant.name),
                 title,
-                flavor: flavor.name,
+                variant: variant.name,
                 status: 'Draft',
                 date_created: options.date,
                 date_modified: options.date,
             };
-            const body = blankBlueprint(installed, folderName, values, readFileSync(shapeFile, 'utf8'), title);
+            const body = blankBlueprint(installed, folderName, values, readFileSync(templateFile, 'utf8'), title);
             const file = path.join(folder, `${convert(title, naming)}.md`);
             writer.write(file, body);
             scaffolded.push(`${folderName}/${convert(title, naming)}.md`);
@@ -214,7 +305,7 @@ export function installSeed(options) {
         eidosVersion: installed.eidosVersion,
         naming,
         frameworkFile,
-        collections: seedFramework.collections.map((collection) => folders.get(collection.name) ?? collection.name),
+        collections: installing.map((collection) => folders.get(collection.name) ?? collection.name),
         groupedCollection: grouped ? (folders.get(grouped.name) ?? grouped.name) : null,
         groups: groupsInConvention,
         scaffolded,