eidosmd 0.1.0

package/dist/src/core/framework.js

@@ -0,0 +1,56 @@
+// Finding and loading the root's framework document: exactly one of
+// `_eidos/Framework.md` or `Framework.yaml`, parsed into
+// the one model every command reads.
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseFrameworkMarkdown } from './framework-markdown.js';
+import { parseFrameworkStructured } from './framework-structured.js';
+import { appliesTo, FRAMEWORK_DIR, FRAMEWORK_FILES, FrameworkError } from './framework-model.js';
+import { kebab } from './naming.js';
+export * from './framework-model.js';
+// The one framework document in a folder's `_eidos/`, or null; two is an error.
+export function findFrameworkFile(dir) {
+    const present = FRAMEWORK_FILES.map((candidate) => ({ file: path.join(dir, FRAMEWORK_DIR, candidate.name), format: candidate.format })).filter((candidate) => existsSync(candidate.file));
+    if (present.length > 1) {
+        throw new FrameworkError(`${path.join(dir, FRAMEWORK_DIR)} holds more than one framework document (${present.map((candidate) => path.basename(candidate.file)).join(', ')}); keep exactly one`);
+    }
+    return present[0] ?? null;
+}
+export function isRoot(dir) {
+    return FRAMEWORK_FILES.some((candidate) => existsSync(path.join(dir, FRAMEWORK_DIR, candidate.name)));
+}
+export function parseFramework(text, format, root, file) {
+    if (format === 'md') {
+        return parseFrameworkMarkdown(text, root, file);
+    }
+    return parseFrameworkStructured(text, root, file);
+}
+export function loadFramework(root) {
+    const found = findFrameworkFile(root);
+    if (!found) {
+        throw new FrameworkError(`${path.join(root, FRAMEWORK_DIR)} holds no framework document (Framework.md or Framework.yaml)`);
+    }
+    return parseFramework(readFileSync(found.file, 'utf8'), found.format, root, found.file);
+}
+export function findCollection(framework, name) {
+    const wanted = name.toLowerCase();
+    return (framework.collections.find((collection) => collection.name.toLowerCase() === wanted) ??
+        framework.collections.find((collection) => kebab(collection.name) === kebab(name)) ??
+        null);
+}
+export function findFlavor(collection, name) {
+    const wanted = name.trim().toLowerCase();
+    return (collection.flavors.find((flavor) => flavor.name.toLowerCase() === wanted) ??
+        collection.flavors.find((flavor) => kebab(flavor.name) === kebab(name)) ??
+        null);
+}
+export function defaultFlavor(collection) {
+    return collection.flavors.find((flavor) => flavor.isDefault) ?? collection.flavors[0] ?? null;
+}
+// The properties a blueprint in this collection carries, core first.
+export function propertiesFor(framework, collectionName) {
+    return [...framework.schema.core, ...framework.schema.custom.filter((property) => appliesTo(property, collectionName))];
+}
+export function shapePath(framework, flavor) {
+    return path.join(framework.root, FRAMEWORK_DIR, flavor.shape);
+}

package/dist/src/core/frontmatter.js

@@ -0,0 +1,116 @@
+// Reading and writing a blueprint's frontmatter. Parsing is real YAML, because
+// list properties hold quoted markdown links; writing uses the flat house style
+// every seed and scaffold already uses, so a generated file diffs cleanly
+// against a hand-written one.
+import { parse as parseYaml } from 'yaml';
+import { splitFrontmatter } from './markdown.js';
+// One `key: value` per line, read without YAML: what an unquoted summary with
+// a colon in it still means to a person, and what Obsidian will refuse to show.
+function parseLeniently(frontmatter) {
+    const out = {};
+    let found = false;
+    for (const raw of frontmatter.split('\n')) {
+        const line = raw.replace(/\s+$/, '');
+        if (line === '' || /^[\s#-]/.test(line)) {
+            continue;
+        }
+        const colon = line.indexOf(':');
+        if (colon === -1) {
+            continue;
+        }
+        const key = line.slice(0, colon).trim();
+        const value = line.slice(colon + 1).trim();
+        if (key === '') {
+            continue;
+        }
+        found = true;
+        let parsed = value;
+        try {
+            parsed = value === '' ? null : parseYaml(value);
+        }
+        catch {
+            parsed = value;
+        }
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            parsed = value;
+        }
+        out[key] = parsed;
+    }
+    return found ? out : null;
+}
+export function parseFrontmatter(text) {
+    const { frontmatter, body } = splitFrontmatter(text);
+    if (frontmatter === null) {
+        return { properties: null, body, error: null };
+    }
+    let problem;
+    try {
+        const parsed = parseYaml(frontmatter);
+        if (parsed === null || parsed === undefined) {
+            return { properties: {}, body, error: null };
+        }
+        if (typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return { properties: parsed, body, error: null };
+        }
+        problem = 'frontmatter is not a mapping of properties';
+    }
+    catch (cause) {
+        problem = describeYamlError(cause, frontmatter);
+    }
+    return { properties: parseLeniently(frontmatter), body, error: problem };
+}
+// The parser's first line, with the offending property named when the error
+// points at a line, so the fix ("quote the summary") is obvious.
+function describeYamlError(cause, frontmatter) {
+    const raw = cause instanceof Error ? cause.message : String(cause);
+    const firstLine = (raw.split('\n')[0] ?? raw).replace(/\s+at line \d+, column \d+:?$/, '').replace(/:$/, '');
+    const at = /at line (\d+)/.exec(raw);
+    let key = null;
+    if (at && at[1]) {
+        const line = frontmatter.split('\n')[Number.parseInt(at[1], 10) - 1] ?? '';
+        const match = /^([^\s:#][^:]*):/.exec(line);
+        key = match && match[1] ? match[1].trim() : null;
+    }
+    const subject = key ? `\`${key}\` is not valid YAML` : 'the frontmatter is not valid YAML';
+    return `${subject} (${firstLine}); read leniently here, but Obsidian will not show these properties. Quote the value`;
+}
+function needsQuotes(value) {
+    if (value === '') {
+        return false;
+    }
+    if (/^[\s"'[\]{}#&*!|>%@`,?:-]/.test(value) || /[:#]\s/.test(value) || /\s$/.test(value)) {
+        return true;
+    }
+    return /^(true|false|null|yes|no|on|off|~)$/i.test(value) || /^[-+]?(\d[\d_]*\.?\d*|\.\d+)([eE][-+]?\d+)?$/.test(value);
+}
+function quote(value) {
+    return '"' + value.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+export function formatScalar(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (typeof value === 'string') {
+        return needsQuotes(value) ? quote(value) : value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return quote(JSON.stringify(value));
+}
+// `key: value` per line; lists in flow style (`[]`, `["a", "b"]`); an empty
+// value leaves the key alone with nothing after the colon.
+export function formatFrontmatter(entries) {
+    const lines = ['---'];
+    for (const [key, value] of entries) {
+        if (Array.isArray(value)) {
+            const items = value.map((item) => (typeof item === 'string' ? quote(item) : formatScalar(item)));
+            lines.push(`${key}: [${items.join(', ')}]`);
+            continue;
+        }
+        const scalar = formatScalar(value);
+        lines.push(scalar === '' ? `${key}:` : `${key}: ${scalar}`);
+    }
+    lines.push('---');
+    return lines.join('\n') + '\n';
+}

package/dist/src/core/index-leaf.js

@@ -0,0 +1,83 @@
+// The generated index: every collection's blueprints with their one-line
+// `summary`, kept inside the YAML framework document under `index`, one list
+// per collection, regenerated wholesale. `eidos index` rewrites that key and
+// nothing else in the document, so the comments and layout a person chose
+// survive. (A markdown root keeps a per-collection `index.md` instead; the
+// CLI converts such a root rather than maintaining that form.)
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { blueprintId, blueprintTitle, propertyString } from './blueprint.js';
+import { embeddedIndexOf, withEmbeddedIndex } from './framework-structured.js';
+import { compareLower } from './naming.js';
+// One collection's entries: flat blueprints first, then each group, titles
+// sorted the way a person would scan them. A missing summary is null, never invented.
+export function renderEmbeddedEntries(collection, blueprints) {
+    const own = blueprints.filter((blueprint) => blueprint.collection === collection);
+    const toEntry = (blueprint) => {
+        const summary = (propertyString(blueprint, 'summary') ?? '').trim();
+        const entry = {
+            id: blueprintId(blueprint),
+            title: blueprintTitle(blueprint),
+            summary: summary === '' ? null : summary,
+            path: blueprint.group === null ? blueprint.file : `${blueprint.group}/${blueprint.file}`,
+        };
+        if (blueprint.group !== null) {
+            entry.group = blueprint.group;
+        }
+        return entry;
+    };
+    const flat = own.filter((blueprint) => blueprint.group === null).sort((a, b) => compareLower(blueprintTitle(a), blueprintTitle(b)));
+    const grouped = own
+        .filter((blueprint) => blueprint.group !== null)
+        .sort((a, b) => compareLower(a.group ?? '', b.group ?? '') || compareLower(blueprintTitle(a), blueprintTitle(b)));
+    return [...flat, ...grouped].map(toEntry);
+}
+export function renderEmbeddedIndex(framework, blueprints, collections = framework.collections) {
+    const index = {};
+    for (const collection of collections) {
+        index[collection.name] = renderEmbeddedEntries(collection, blueprints);
+    }
+    return index;
+}
+function sameEntries(a, b) {
+    return JSON.stringify(a ?? null) === JSON.stringify(b);
+}
+// Compare each collection's entries with what the document holds, and rewrite
+// the document's `index` once if anything moved. Collections outside
+// `collections` keep the entries they had.
+export function buildIndexes(framework, blueprints, options) {
+    const targets = options.collections ?? framework.collections;
+    const source = readFileSync(framework.file, 'utf8');
+    const current = embeddedIndexOf(source) ?? {};
+    const wanted = renderEmbeddedIndex(framework, blueprints, targets);
+    const results = [];
+    let changed = false;
+    for (const collection of targets) {
+        const own = blueprints.filter((blueprint) => blueprint.collection === collection);
+        const result = {
+            collection,
+            file: framework.file,
+            count: own.length,
+            missingSummary: own.filter((blueprint) => (propertyString(blueprint, 'summary') ?? '').trim() === '').map((blueprint) => blueprint.rel),
+            status: 'current',
+        };
+        if (!existsSync(path.join(framework.root, collection.name))) {
+            result.status = 'folder-missing';
+        }
+        else if (!sameEntries(current[collection.name], wanted[collection.name] ?? [])) {
+            result.status = options.check ? 'stale' : 'written';
+            changed = true;
+        }
+        results.push(result);
+    }
+    if (changed && !options.check) {
+        const merged = { ...current };
+        for (const collection of targets) {
+            if (existsSync(path.join(framework.root, collection.name))) {
+                merged[collection.name] = wanted[collection.name] ?? [];
+            }
+        }
+        writeFileSync(framework.file, withEmbeddedIndex(source, merged), 'utf8');
+    }
+    return results;
+}

package/dist/src/core/markdown.js

@@ -0,0 +1,100 @@
+// Small markdown readers shared by the framework, shape, and blueprint parsers:
+// splitting frontmatter from body, and finding headings and sections outside
+// code fences and HTML comments.
+export function normalizeNewlines(text) {
+    return text.replace(/\r\n?/g, '\n');
+}
+// A leading `---` block. Returns null frontmatter when the file has none; the
+// body is everything after the closing fence (or the whole text).
+export function splitFrontmatter(text) {
+    const lines = normalizeNewlines(text).split('\n');
+    if (lines[0]?.trim() !== '---') {
+        return { frontmatter: null, body: lines.join('\n') };
+    }
+    for (let index = 1; index < lines.length; index += 1) {
+        if (lines[index]?.trim() === '---') {
+            return {
+                frontmatter: lines.slice(1, index).join('\n'),
+                body: lines.slice(index + 1).join('\n'),
+            };
+        }
+    }
+    return { frontmatter: null, body: lines.join('\n') };
+}
+// Every line with a flag saying whether it sits inside a fenced code block or
+// an HTML comment, so a `## heading` quoted in guidance is not read as one.
+function visibleLines(text) {
+    const out = [];
+    let inFence = false;
+    let inComment = false;
+    for (const line of normalizeNewlines(text).split('\n')) {
+        const trimmed = line.trim();
+        if (!inComment && /^(```|~~~)/.test(trimmed)) {
+            inFence = !inFence;
+            out.push({ line, visible: false });
+            continue;
+        }
+        if (inFence) {
+            out.push({ line, visible: false });
+            continue;
+        }
+        if (!inComment && trimmed.startsWith('<!--')) {
+            inComment = !trimmed.includes('-->');
+            out.push({ line, visible: false });
+            continue;
+        }
+        if (inComment) {
+            if (trimmed.includes('-->')) {
+                inComment = false;
+            }
+            out.push({ line, visible: false });
+            continue;
+        }
+        out.push({ line, visible: true });
+    }
+    return out;
+}
+export function headings(text) {
+    const found = [];
+    visibleLines(text).forEach(({ line, visible }, index) => {
+        if (!visible) {
+            return;
+        }
+        const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+        if (match && match[1] && match[2]) {
+            found.push({ level: match[1].length, text: match[2].trim(), line: index + 1 });
+        }
+    });
+    return found;
+}
+// The sections at one heading level: each heading with the text beneath it, up
+// to the next heading of the same or a higher level.
+export function sections(text, level) {
+    const lines = normalizeNewlines(text).split('\n');
+    const all = headings(text);
+    const out = [];
+    all.forEach((heading, index) => {
+        if (heading.level !== level) {
+            return;
+        }
+        let end = lines.length;
+        for (let next = index + 1; next < all.length; next += 1) {
+            const candidate = all[next];
+            if (candidate && candidate.level <= level) {
+                end = candidate.line - 1;
+                break;
+            }
+        }
+        out.push({ heading, body: lines.slice(heading.line, end).join('\n').trim() });
+    });
+    return out;
+}
+// The body of the first section with this heading text at this level.
+export function section(text, level, headingText) {
+    const wanted = headingText.trim().toLowerCase();
+    const found = sections(text, level).find((candidate) => candidate.heading.text.toLowerCase() === wanted);
+    return found ? found.body : null;
+}
+export function stripInlineCode(text) {
+    return text.replace(/`([^`]*)`/g, '$1');
+}

package/dist/src/core/me.js

@@ -0,0 +1,89 @@
+// The actor: `_eidos/me.md`, personal and gitignored, naming a role from
+// `_eidos/roles/` and calibrating it on three axes.
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { headings, section } from './markdown.js';
+import { kebab } from './naming.js';
+export function rolesDir(root) {
+    return path.join(root, '_eidos', 'roles');
+}
+export function meFile(root) {
+    return path.join(root, '_eidos', 'me.md');
+}
+export function listRoles(root) {
+    const dir = rolesDir(root);
+    if (!existsSync(dir)) {
+        return [];
+    }
+    return readdirSync(dir)
+        .filter((entry) => /\.md$/i.test(entry) && entry.toLowerCase() !== 'readme.md' && !entry.startsWith('.'))
+        .sort()
+        .map((entry) => {
+        const file = path.join(dir, entry);
+        const text = readFileSync(file, 'utf8');
+        const title = headings(text).find((heading) => heading.level === 1)?.text ?? entry.replace(/\.md$/i, '');
+        const who = section(text, 2, 'Who they are');
+        const summary = (who ?? '').split('\n').find((line) => line.trim() !== '')?.trim() ?? '';
+        return { name: entry.replace(/\.md$/i, ''), file, title, summary };
+    });
+}
+export function findRole(root, name) {
+    const wanted = kebab(name);
+    return listRoles(root).find((role) => role.name === wanted || kebab(role.title) === wanted) ?? null;
+}
+export function readActor(root) {
+    const file = meFile(root);
+    if (!existsSync(file)) {
+        return { exists: false, text: '', actor: emptyActor() };
+    }
+    const text = readFileSync(file, 'utf8');
+    return { exists: true, text, actor: parseActor(text) };
+}
+function emptyActor() {
+    return { role: null, roleFile: null, note: null, ownership: null, experience: null, capacity: null };
+}
+export function parseActor(text) {
+    const actor = emptyActor();
+    const youAre = headings(text).find((heading) => heading.level === 2 && /^you are\b/i.test(heading.text));
+    if (youAre) {
+        const declared = youAre.text.replace(/^you are\s*:?\s*/i, '').trim();
+        actor.role = declared === '' ? null : declared;
+        const body = section(text, 2, youAre.text) ?? '';
+        const link = /\[[^\]]*\]\(([^)]+)\)/.exec(body);
+        actor.roleFile = link && link[1] ? link[1] : null;
+        const note = body.replace(/^Role:.*$/m, '').trim();
+        actor.note = note === '' ? null : note;
+    }
+    const calibration = section(text, 2, 'Calibration') ?? '';
+    const axis = (label) => {
+        const match = new RegExp(`^-[ \\t]+\\*\\*${label}[^*\\n]*\\*\\*[ \\t]*:?[ \\t]*(.*)$`, 'im').exec(calibration);
+        const value = match && match[1] ? match[1].trim() : '';
+        return value === '' ? null : value;
+    };
+    actor.ownership = axis('Ownership');
+    actor.experience = axis('Experience');
+    actor.capacity = axis('Technical capacity');
+    return actor;
+}
+export function renderActor(role, custom, axes) {
+    const lines = ['# Me', '', 'Personal and per-actor — gitignored, never shared. The agent reads it before acting.', ''];
+    if (role) {
+        lines.push(`## You are: ${role.title}`, '', `Role: [_eidos/roles/${role.name}.md](roles/${role.name}.md).`, '');
+    }
+    else if (custom) {
+        lines.push(`## You are: ${custom}`, '', 'A custom role: describe how you want to be helped here.', '');
+    }
+    else {
+        lines.push('## You are:', '', '<!-- Name your role, or pick one with `eidos whoami --role <role>`. -->', '');
+    }
+    lines.push('## Calibration', '');
+    lines.push(`- **Ownership:** ${axes.ownership ?? ''}`.trimEnd());
+    lines.push(`- **Experience with the scope:** ${axes.experience ?? ''}`.trimEnd());
+    lines.push(`- **Technical capacity:** ${axes.capacity ?? ''}`.trimEnd());
+    return lines.join('\n') + '\n';
+}
+export function writeActor(root, text) {
+    const file = meFile(root);
+    writeFileSync(file, text, 'utf8');
+    return file;
+}

package/dist/src/core/naming.js

@@ -0,0 +1,46 @@
+// The framework's naming convention, applied to everything a human reads in the
+// tree: collection folders, group folders, blueprint filenames, and the links
+// that reach them. The id is always kebab-case regardless.
+export const NAMINGS = ['kebab-case', 'TitleCase', 'Title Case'];
+export const DEFAULT_NAMING = 'kebab-case';
+export function isNaming(value) {
+    return typeof value === 'string' && NAMINGS.includes(value);
+}
+export function kebab(label) {
+    return label
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+export function isKebab(value) {
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+}
+// `prior work` -> `Prior Work`; a declared flavor label as a human title.
+export function titleize(label) {
+    return label
+        .split(' ')
+        .map((word) => word.slice(0, 1).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+// A Title Case display name in the framework's convention.
+export function convert(display, naming) {
+    if (naming === 'TitleCase') {
+        return display.split(/\s+/).join('');
+    }
+    if (naming === 'kebab-case') {
+        return kebab(display);
+    }
+    return display;
+}
+// Compare the way Python sorts lowercased strings: by code point, not locale.
+export function compareLower(a, b) {
+    const left = a.toLowerCase();
+    const right = b.toLowerCase();
+    if (left < right) {
+        return -1;
+    }
+    if (left > right) {
+        return 1;
+    }
+    return 0;
+}

package/dist/src/core/root.js

@@ -0,0 +1,88 @@
+// Finding the root: the one folder with `_eidos/` inside it, never a folder
+// with a particular name. Looks at the starting folder, then its ancestors,
+// then one and two levels beneath it, so `eidos check` works from a repo root
+// that keeps its blueprints in `Blueprints/`.
+import { readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { FRAMEWORK_DIR, isRoot } from './framework.js';
+const SKIPPED_DIRS = new Set(['node_modules', 'dist', 'build', 'out', 'target', 'vendor']);
+export class RootError extends Error {
+    candidates;
+    constructor(message, candidates = []) {
+        super(message);
+        this.name = 'RootError';
+        this.candidates = candidates;
+    }
+}
+function childDirs(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (entry.startsWith('.') || entry === FRAMEWORK_DIR || SKIPPED_DIRS.has(entry)) {
+            continue;
+        }
+        const full = path.join(dir, entry);
+        try {
+            if (statSync(full).isDirectory()) {
+                out.push(full);
+            }
+        }
+        catch {
+            // unreadable entries are simply not candidates
+        }
+    }
+    return out.sort();
+}
+// Every root at or beneath `dir`, at most two levels down.
+export function rootsBeneath(dir) {
+    const found = [];
+    if (isRoot(dir)) {
+        found.push(dir);
+    }
+    for (const child of childDirs(dir)) {
+        if (isRoot(child)) {
+            found.push(child);
+            continue;
+        }
+        for (const grandchild of childDirs(child)) {
+            if (isRoot(grandchild)) {
+                found.push(grandchild);
+            }
+        }
+    }
+    return found;
+}
+export function findRoot(start, explicit) {
+    if (explicit !== undefined) {
+        const resolved = path.resolve(start, explicit);
+        if (!isRoot(resolved)) {
+            throw new RootError(`${resolved} is not a root: no ${FRAMEWORK_DIR}/Framework.md inside it`);
+        }
+        return resolved;
+    }
+    let current = path.resolve(start);
+    for (;;) {
+        if (isRoot(current)) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    const beneath = rootsBeneath(path.resolve(start));
+    if (beneath.length === 1 && beneath[0]) {
+        return beneath[0];
+    }
+    if (beneath.length > 1) {
+        throw new RootError(`several roots beneath ${path.resolve(start)}; pass --root to pick one:\n` + beneath.map((candidate) => `  ${candidate}`).join('\n'), beneath);
+    }
+    throw new RootError(`no root found from ${path.resolve(start)}: nothing here has a ${FRAMEWORK_DIR}/ folder. Run \`eidos init\` to create one, or pass --root.`);
+}