eidosmd 0.1.0

package/dist/src/core/scaffold.js

@@ -0,0 +1,118 @@
+// Scaffolding one blueprint: frontmatter generated from the properties that
+// apply to its collection, body rendered from its flavor's shape, filename in
+// the framework's convention with a permanent kebab-case id inside. Born
+// conforming; the prose is still the owner's.
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { blueprintId } from './blueprint.js';
+import { defaultFlavor, findCollection, findFlavor, propertiesFor } from './framework.js';
+import { convert, isKebab, kebab } from './naming.js';
+import { loadShape } from './shape.js';
+import { blankBlueprint } from './seed.js';
+export class ScaffoldError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ScaffoldError';
+    }
+}
+function coerce(type, raw) {
+    switch (type.toLowerCase()) {
+        case 'list':
+            return raw
+                .split(',')
+                .map((item) => item.trim())
+                .filter((item) => item !== '');
+        case 'number': {
+            const parsed = Number(raw);
+            return Number.isNaN(parsed) ? raw : parsed;
+        }
+        case 'checkbox':
+            return /^(true|yes|on|1)$/i.test(raw.trim());
+        default:
+            return raw;
+    }
+}
+export function scaffoldBlueprint(framework, existing, options) {
+    const collection = findCollection(framework, options.collection);
+    if (!collection) {
+        const known = framework.collections.map((candidate) => candidate.name).join(', ');
+        throw new ScaffoldError(`no collection '${options.collection}' in this framework (declared: ${known})`);
+    }
+    const flavor = options.flavor === null ? defaultFlavor(collection) : findFlavor(collection, options.flavor);
+    if (!flavor) {
+        const known = collection.flavors.map((candidate) => candidate.name).join(', ');
+        throw new ScaffoldError(options.flavor === null
+            ? `collection '${collection.name}' declares no flavors`
+            : `no flavor '${options.flavor}' in '${collection.name}' (declared: ${known})`);
+    }
+    const shape = loadShape(framework, flavor);
+    if (!shape) {
+        throw new ScaffoldError(`flavor '${flavor.name}' points at a shape that does not exist: _eidos/${flavor.shape}`);
+    }
+    const title = options.title.trim();
+    if (title === '') {
+        throw new ScaffoldError('a blueprint needs a title');
+    }
+    const id = options.id ?? kebab(title);
+    if (!isKebab(id)) {
+        throw new ScaffoldError(`id '${id}' is not kebab-case`);
+    }
+    const clash = existing.find((blueprint) => blueprintId(blueprint) === id);
+    if (clash) {
+        throw new ScaffoldError(`id '${id}' is already taken by ${clash.rel}`);
+    }
+    const notes = [];
+    let group = null;
+    if (options.group !== null) {
+        const declared = collection.grouping?.groups.find((candidate) => candidate.name.toLowerCase() === options.group?.toLowerCase() || kebab(candidate.name) === kebab(options.group ?? ''));
+        group = declared ? declared.name : convert(options.group, framework.naming);
+        if (!declared && collection.grouping && collection.grouping.groups.length > 0) {
+            notes.push(`group '${group}' is not declared under ${collection.grouping.label} in Framework.md; add a bullet for it`);
+        }
+        if (!collection.grouping) {
+            notes.push(`collection '${collection.name}' declares no grouping; the sub-folder alone groups this blueprint`);
+        }
+    }
+    const fileName = framework.naming === 'kebab-case' ? `${id}.md` : `${convert(title, framework.naming)}.md`;
+    const dir = group === null ? path.join(framework.root, collection.name) : path.join(framework.root, collection.name, group);
+    const file = path.join(dir, fileName);
+    if (existsSync(file)) {
+        throw new ScaffoldError(`${path.relative(framework.root, file)} already exists`);
+    }
+    const values = {
+        id,
+        title,
+        summary: options.summary ?? '',
+        flavor: flavor.name,
+        status: 'Draft',
+        date_created: options.date,
+        date_modified: options.date,
+    };
+    if (group !== null && collection.grouping?.property) {
+        values[collection.grouping.property] = group;
+    }
+    const types = new Map(propertiesFor(framework, collection.name).map((property) => [property.name, property.type]));
+    for (const [key, raw] of Object.entries(options.set)) {
+        const type = types.get(key);
+        if (type === undefined) {
+            notes.push(`property '${key}' is not in the Schema for ${collection.name}; written anyway`);
+        }
+        values[key] = coerce(type ?? 'Text', raw);
+    }
+    let content = blankBlueprint(framework, collection.name, values, shape.template, title);
+    const extra = Object.keys(options.set).filter((key) => !types.has(key));
+    if (extra.length > 0) {
+        const lines = extra.map((key) => `${key}: ${String(values[key])}`).join('\n');
+        content = content.replace(/\n---\n/, `\n${lines}\n---\n`);
+    }
+    return {
+        path: file,
+        rel: path.relative(framework.root, file).split(path.sep).join('/'),
+        content,
+        collection,
+        flavor,
+        group,
+        id,
+        notes,
+    };
+}

package/dist/src/core/seed.js

@@ -0,0 +1,223 @@
+// 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.
+// 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)_';
+const GITIGNORE_SHIPPED = '_gitignore';
+export function listSeeds(seedsDir) {
+    if (!existsSync(seedsDir)) {
+        return [];
+    }
+    return readdirSync(seedsDir)
+        .sort()
+        .map((name) => path.join(seedsDir, name))
+        .filter((dir) => existsSync(path.join(dir, 'Framework.md')))
+        .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);
+}
+export class InstallError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InstallError';
+    }
+}
+class Writer {
+    dryRun;
+    actions = [];
+    constructor(dryRun) {
+        this.dryRun = dryRun;
+    }
+    copyTree(src, dest) {
+        this.actions.push(`copy   ${src}/ → ${dest}/`);
+        if (!this.dryRun) {
+            cpSync(src, dest, { recursive: true });
+        }
+    }
+    remove(file) {
+        this.actions.push(`rm     ${file}`);
+        if (!this.dryRun) {
+            rmSync(file, { force: true });
+        }
+    }
+    rename(from, to) {
+        this.actions.push(`mv     ${from} → ${to}`);
+        if (!this.dryRun) {
+            renameSync(from, to);
+        }
+    }
+    mkdir(dir) {
+        this.actions.push(`mkdir  ${dir}/`);
+        if (!this.dryRun) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    write(file, text) {
+        this.actions.push(`write  ${file}`);
+        if (!this.dryRun) {
+            mkdirSync(path.dirname(file), { recursive: true });
+            writeFileSync(file, text, 'utf8');
+        }
+    }
+}
+function setNaming(text, naming) {
+    if (/^naming:.*$/m.test(text)) {
+        return text.replace(/^naming:.*$/m, `naming: ${naming}`);
+    }
+    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}`);
+}
+function renameCollection(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.
+export function blankBlueprint(framework, collectionName, values, shapeTemplate, title) {
+    const entries = propertiesFor(framework, collectionName).map((property) => {
+        const value = values[property.name];
+        if ((value === undefined || value === null || value === '') && property.type.toLowerCase() === 'list') {
+            return [property.name, []];
+        }
+        return [property.name, value ?? ''];
+    });
+    return formatFrontmatter(entries) + '\n' + renderShape(shapeTemplate, title);
+}
+export function installSeed(options) {
+    const seedDir = path.join(options.seedsDir, options.seed);
+    const frameworkSrc = path.join(seedDir, 'Framework.md');
+    if (!existsSync(frameworkSrc)) {
+        throw new InstallError(`no seed '${options.seed}' under ${options.seedsDir} (needs a Framework.md)`);
+    }
+    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`);
+    }
+    let text = readFileSync(frameworkSrc, 'utf8');
+    const seedFramework = parseFramework(text, 'md', seedDir, frameworkSrc);
+    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'));
+    // 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'));
+    }
+    // 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 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');
+    }
+    const folders = new Map();
+    for (const collection of seedFramework.collections) {
+        const folder = convert(collection.name, naming);
+        folders.set(collection.name, folder);
+        if (folder !== collection.name) {
+            text = renameCollection(text, collection.name, folder);
+            if (readme !== null) {
+                readme = renameCollection(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));
+    writer.write(frameworkFile, serialized);
+    const installed = parseFramework(serialized, 'yaml', root, frameworkFile);
+    if (readme !== null) {
+        writer.write(path.join(root, 'README.md'), readme);
+    }
+    // 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) {
+        const folderName = folders.get(collection.name) ?? collection.name;
+        const folder = path.join(root, folderName);
+        writer.mkdir(folder);
+        if (collection === grouped) {
+            for (const group of groupsInConvention) {
+                writer.mkdir(path.join(folder, group));
+            }
+        }
+        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}`);
+                continue;
+            }
+            const title = titleize(flavor.name);
+            const values = {
+                id: kebab(flavor.name),
+                title,
+                flavor: flavor.name,
+                status: 'Draft',
+                date_created: options.date,
+                date_modified: options.date,
+            };
+            const body = blankBlueprint(installed, folderName, values, readFileSync(shapeFile, 'utf8'), title);
+            const file = path.join(folder, `${convert(title, naming)}.md`);
+            writer.write(file, body);
+            scaffolded.push(`${folderName}/${convert(title, naming)}.md`);
+        }
+    }
+    // The framing collection has blueprints now, so the index lists them at once.
+    if (!options.dryRun) {
+        buildIndexes(installed, listBlueprints(installed), { check: false });
+    }
+    return {
+        root,
+        seed: options.seed,
+        eidosVersion: installed.eidosVersion,
+        naming,
+        frameworkFile,
+        collections: seedFramework.collections.map((collection) => folders.get(collection.name) ?? collection.name),
+        groupedCollection: grouped ? (folders.get(grouped.name) ?? grouped.name) : null,
+        groups: groupsInConvention,
+        scaffolded,
+        actions: writer.actions,
+    };
+}

package/dist/src/core/server.js

@@ -0,0 +1,275 @@
+// The local browser's server: a plain Node http server on 127.0.0.1 serving
+// one HTML page and a small JSON API. Every write the page can make goes
+// through the same core function the matching command uses (`new` scaffolds,
+// `index` rebuilds, `check` validates), so nothing is possible here that is
+// not possible from the shell. The root is re-read on every request; files
+// change on disk while the page is open.
+import { createServer as createHttpServer } from 'node:http';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { marked } from 'marked';
+import { loadRoot } from '../context.js';
+import { checkRoot } from './check.js';
+import { buildIndexes } from './index-leaf.js';
+import { frameworkToDocument } from './framework-structured.js';
+import { listRoles, meFile, readActor } from './me.js';
+import { scaffoldBlueprint, ScaffoldError } from './scaffold.js';
+import { blueprintId, blueprintTitle, propertyString, resolveFlavor } from './blueprint.js';
+import { loadShape } from './shape.js';
+import { CliError } from '../output.js';
+import { browserDir, packageVersion, readStandard, standardVersion } from '../paths.js';
+import { guideText, GUIDES } from '../commands/instructions.js';
+import { today } from '../output.js';
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+function json(response, status, body) {
+    const text = JSON.stringify(body);
+    response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(text) });
+    response.end(text);
+}
+async function readBody(request) {
+    const chunks = [];
+    for await (const chunk of request) {
+        chunks.push(chunk);
+        if (chunks.reduce((size, part) => size + part.length, 0) > 8 * 1024 * 1024) {
+            throw new HttpError(413, 'request body too large');
+        }
+    }
+    const text = Buffer.concat(chunks).toString('utf8');
+    if (text.trim() === '') {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        throw new HttpError(400, 'request body is not JSON');
+    }
+}
+function rel(root, file) {
+    return path.relative(root, file).split(path.sep).join('/');
+}
+function blueprintSummary(blueprint) {
+    const { flavor, declared } = resolveFlavor(blueprint);
+    return {
+        id: blueprintId(blueprint),
+        title: blueprintTitle(blueprint),
+        summary: propertyString(blueprint, 'summary'),
+        collection: blueprint.collection.name,
+        group: blueprint.group,
+        flavor: flavor?.name ?? declared,
+        path: blueprint.rel,
+    };
+}
+function findByPath(context, relPath) {
+    const wanted = decodeURIComponent(relPath).replace(/\\/g, '/');
+    const found = context.blueprints.find((blueprint) => blueprint.rel === wanted);
+    if (!found) {
+        throw new HttpError(404, `no blueprint at ${wanted}`);
+    }
+    return found;
+}
+// Only this file's findings; the framework-level ones belong to the check view.
+function findingsFor(context, blueprint) {
+    return checkRoot(context.framework, context.blueprints, { only: new Set([blueprint.path]), standardVersion: standardVersion() }).findings.filter((finding) => finding.path === blueprint.rel);
+}
+function blueprintDetail(context, blueprint) {
+    const raw = readFileSync(blueprint.path, 'utf8');
+    const { flavor } = resolveFlavor(blueprint);
+    const shape = flavor ? loadShape(context.framework, flavor) : null;
+    return {
+        ...blueprintSummary(blueprint),
+        properties: blueprint.properties ?? {},
+        frontmatter_error: blueprint.frontmatterError,
+        sections: blueprint.sections.map((section) => section.heading.text),
+        shape_sections: shape?.sections ?? [],
+        html: marked.parse(blueprint.body, { async: false }),
+        raw,
+        findings: findingsFor(context, blueprint),
+    };
+}
+function rootSnapshot(context) {
+    const actor = readActor(context.root);
+    return {
+        root: context.root,
+        name: path.basename(context.root),
+        cli_version: packageVersion(),
+        standard_version: standardVersion(),
+        framework: { file: rel(context.root, context.framework.file), format: context.framework.format, problems: context.framework.problems, ...frameworkToDocument(context.framework) },
+        blueprints: context.blueprints.map(blueprintSummary),
+        roles: listRoles(context.root).map((role) => ({ name: role.name, title: role.title, summary: role.summary })),
+        actor: { exists: actor.exists, role: actor.actor.role, ownership: actor.actor.ownership, experience: actor.actor.experience, capacity: actor.actor.capacity, path: rel(context.root, meFile(context.root)) },
+        guides: GUIDES,
+    };
+}
+function checkSnapshot(context) {
+    const report = checkRoot(context.framework, context.blueprints, { standardVersion: standardVersion() });
+    return {
+        root: report.root,
+        eidos_version: report.eidosVersion,
+        naming: report.naming,
+        blueprints: report.blueprints,
+        collections: report.collections,
+        errors: report.errors,
+        warnings: report.warnings,
+        findings: report.findings,
+    };
+}
+function indexRebuild(context) {
+    const results = buildIndexes(context.framework, context.blueprints, { check: false });
+    return {
+        indexes: results.map((result) => ({ collection: result.collection.name, path: rel(context.root, result.file), status: result.status, blueprints: result.count })),
+        missing_summary: results.flatMap((result) => result.missingSummary),
+    };
+}
+function createBlueprint(context, body) {
+    const text = (value) => (typeof value === 'string' && value.trim() !== '' ? value : null);
+    const set = {};
+    if (typeof body['set'] === 'object' && body['set'] !== null) {
+        for (const [key, value] of Object.entries(body['set'])) {
+            if (typeof value === 'string' && value.trim() !== '') {
+                set[key] = value;
+            }
+        }
+    }
+    let result;
+    try {
+        result = scaffoldBlueprint(context.framework, context.blueprints, {
+            collection: text(body['collection']) ?? '',
+            title: text(body['title']) ?? '',
+            flavor: text(body['flavor']),
+            group: text(body['group']),
+            id: text(body['id']),
+            summary: text(body['summary']),
+            set,
+            date: today(),
+        });
+    }
+    catch (cause) {
+        if (cause instanceof ScaffoldError) {
+            throw new HttpError(400, cause.message);
+        }
+        throw cause;
+    }
+    mkdirSync(path.dirname(result.path), { recursive: true });
+    writeFileSync(result.path, result.content, 'utf8');
+    return { path: result.rel, id: result.id, collection: result.collection.name, group: result.group, flavor: result.flavor.name, notes: result.notes };
+}
+function saveBlueprint(context, blueprint, body) {
+    const text = body['text'];
+    if (typeof text !== 'string') {
+        throw new HttpError(400, 'expected { text }');
+    }
+    writeFileSync(blueprint.path, text.replace(/\r\n?/g, '\n'), 'utf8');
+    const fresh = loadRoot({ root: context.root }, context.cwd);
+    const reloaded = fresh.blueprints.find((candidate) => candidate.rel === blueprint.rel);
+    return { path: blueprint.rel, findings: reloaded ? findingsFor(fresh, reloaded) : [] };
+}
+export function createServer(options) {
+    const page = path.join(browserDir, 'index.html');
+    const context = () => loadRoot({ root: options.root }, options.cwd);
+    const handle = async (request, response) => {
+        const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+        const method = request.method ?? 'GET';
+        const segments = url.pathname.split('/').filter((segment) => segment !== '');
+        if (segments.length === 0 || (segments[0] !== 'api' && !url.pathname.includes('.'))) {
+            if (!existsSync(page)) {
+                throw new HttpError(500, `the browser page is missing at ${page}`);
+            }
+            const html = readFileSync(page);
+            response.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'content-length': html.length });
+            response.end(html);
+            return;
+        }
+        if (segments[0] !== 'api') {
+            throw new HttpError(404, 'not found');
+        }
+        const resource = segments[1] ?? '';
+        const rest = segments.slice(2).join('/');
+        if (resource === 'root' && method === 'GET') {
+            json(response, 200, rootSnapshot(context()));
+            return;
+        }
+        if (resource === 'blueprints' && rest === '' && method === 'GET') {
+            json(response, 200, context().blueprints.map(blueprintSummary));
+            return;
+        }
+        if (resource === 'blueprints' && rest === '' && method === 'POST') {
+            json(response, 201, createBlueprint(context(), await readBody(request)));
+            return;
+        }
+        if (resource === 'blueprints' && rest !== '' && method === 'GET') {
+            const current = context();
+            json(response, 200, blueprintDetail(current, findByPath(current, rest)));
+            return;
+        }
+        if (resource === 'blueprints' && rest !== '' && method === 'PUT') {
+            const current = context();
+            json(response, 200, saveBlueprint(current, findByPath(current, rest), await readBody(request)));
+            return;
+        }
+        if (resource === 'check' && method === 'GET') {
+            json(response, 200, checkSnapshot(context()));
+            return;
+        }
+        if (resource === 'index' && method === 'POST') {
+            json(response, 200, indexRebuild(context()));
+            return;
+        }
+        if (resource === 'standard' && method === 'GET') {
+            json(response, 200, { version: standardVersion(), html: marked.parse(readStandard(), { async: false }) });
+            return;
+        }
+        if (resource === 'instructions' && method === 'GET') {
+            const guide = rest === '' ? 'overview' : rest;
+            if (!GUIDES.some((entry) => entry.name === guide)) {
+                throw new HttpError(404, `no guide '${guide}'`);
+            }
+            json(response, 200, { guide, html: marked.parse(guideText(guide), { async: false }) });
+            return;
+        }
+        throw new HttpError(404, 'not found');
+    };
+    return createHttpServer((request, response) => {
+        handle(request, response).catch((cause) => {
+            if (cause instanceof HttpError) {
+                json(response, cause.status, { error: cause.message });
+            }
+            else if (cause instanceof CliError) {
+                json(response, 400, { error: cause.message });
+            }
+            else {
+                json(response, 500, { error: cause instanceof Error ? cause.message : String(cause) });
+            }
+        });
+    });
+}
+// The first free port at or after `preferred`, on the loopback interface.
+export function listen(server, preferred) {
+    return new Promise((resolve, reject) => {
+        const tryPort = (port) => {
+            const onError = (error) => {
+                server.removeListener('error', onError);
+                if (error.code === 'EADDRINUSE' && port < preferred + 50) {
+                    tryPort(port + 1);
+                }
+                else {
+                    reject(error);
+                }
+            };
+            server.once('error', onError);
+            server.listen(port, '127.0.0.1', () => {
+                server.removeListener('error', onError);
+                const address = server.address();
+                resolve(typeof address === 'object' && address !== null ? address.port : port);
+            });
+        };
+        tryPort(preferred);
+    });
+}

package/dist/src/core/shape.js

@@ -0,0 +1,26 @@
+// A shape file: one body template in `_eidos/shapes/`, read for the sections
+// it declares (to validate a blueprint against) and as the template a new
+// blueprint's body is rendered from.
+import { existsSync, readFileSync } from 'node:fs';
+import { headings } from './markdown.js';
+import { shapePath } from './framework.js';
+export function loadShape(framework, flavor) {
+    const file = shapePath(framework, flavor);
+    if (!existsSync(file)) {
+        return null;
+    }
+    const template = readFileSync(file, 'utf8');
+    const all = headings(template);
+    return {
+        path: file,
+        flavor,
+        template,
+        sections: all.filter((heading) => heading.level === 2).map((heading) => heading.text),
+        headings: all,
+    };
+}
+// The body a scaffolded blueprint starts from: the template with its title
+// filled in and any leading blank lines dropped.
+export function renderShape(template, title) {
+    return template.replace(/\r\n?/g, '\n').replace(/\{\{title\}\}/g, title).replace(/^\n+/, '');
+}

package/dist/src/output.js

@@ -0,0 +1,38 @@
+// Shared output and exit conventions: 0 done, 1 the check found problems (or
+// an index is stale), 2 the command could not run.
+export const EXIT_OK = 0;
+export const EXIT_FINDINGS = 1;
+export const EXIT_USAGE = 2;
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT_USAGE) {
+        super(message);
+        this.name = 'CliError';
+        this.exitCode = exitCode;
+    }
+}
+export function printJson(value) {
+    process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+}
+export function print(...lines) {
+    process.stdout.write(lines.join('\n') + '\n');
+}
+export function printError(message) {
+    process.stderr.write(message.endsWith('\n') ? message : message + '\n');
+}
+export function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+// Left-aligned columns for a plain table; widths from the widest cell.
+export function table(rows, gap = 2) {
+    const widths = [];
+    for (const row of rows) {
+        row.forEach((cell, index) => {
+            widths[index] = Math.max(widths[index] ?? 0, cell.length);
+        });
+    }
+    return rows.map((row) => row
+        .map((cell, index) => (index === row.length - 1 ? cell : cell.padEnd(widths[index] ?? 0)))
+        .join(' '.repeat(gap))
+        .trimEnd());
+}