structured-context 0.9.0

package/dist/plugins/markdown/read-space.js

@@ -0,0 +1,89 @@
+import { readFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { Glob } from 'bun';
+import matter from 'gray-matter';
+import { extractSchemaTypeNames } from '../../schema/schema';
+import { extractEmbeddedNodes, ON_A_PAGE_TYPES } from './parse-embedded';
+import { applyFieldMap, coerceDates, inferTypeFromPath } from './util';
+export function readSpaceOnAPage(context) {
+    const { space, resolvedSchemaPath, schema: { metadata }, } = context;
+    const filePath = resolve(space.path);
+    const raw = readFileSync(filePath, 'utf-8');
+    const { data: frontmatter, content: body } = matter(raw);
+    const pageType = frontmatter.type;
+    if (pageType !== undefined && !ON_A_PAGE_TYPES.includes(pageType)) {
+        throw new Error(`Expected a space_on_a_page file but got type "${pageType}" in ${filePath}. ` +
+            `Use a directory path to validate a space containing typed node files.`);
+    }
+    const hierarchyLevels = metadata.hierarchy?.levels;
+    if (!hierarchyLevels || hierarchyLevels.length === 0) {
+        throw new Error(`Schema at ${resolvedSchemaPath} must define "$metadata.hierarchy.levels" to read a space_on_a_page file.`);
+    }
+    const pageTitle = basename(filePath, '.md');
+    const { nodes, preambleNodeCount, terminatedHeadings } = extractEmbeddedNodes(body, {
+        pageTitle,
+        pageType: 'space_on_a_page',
+        metadata,
+    });
+    return { nodes, parseIgnored: terminatedHeadings, diagnostics: { kind: 'page', preambleNodeCount } };
+}
+export async function readSpaceDirectory(context, options) {
+    const { space, schema: { metadata }, } = context;
+    const directory = resolve(space.path);
+    const mdCfg = context.pluginConfig;
+    const fieldMap = mdCfg.fieldMap;
+    const templateDir = mdCfg.templateDir;
+    const absoluteTemplateDir = templateDir ? resolve(templateDir) : undefined;
+    const typeInferenceCfg = mdCfg.typeInference;
+    const knownTypes = typeInferenceCfg?.mode !== 'off' ? extractSchemaTypeNames(context.schema, context.schemaRefRegistry) : undefined;
+    const files = await Array.fromAsync(new Glob('**/*.md').scan({ cwd: directory, followSymlinks: true }));
+    const nodes = [];
+    const skipped = [];
+    const nonSpace = [];
+    for (const file of files) {
+        const absoluteFilePath = resolve(directory, file);
+        if (absoluteTemplateDir && absoluteFilePath.startsWith(absoluteTemplateDir)) {
+            continue;
+        }
+        const content = readFileSync(join(directory, file), 'utf-8');
+        const parsed = matter(content);
+        if (!parsed.data || Object.keys(parsed.data).length === 0) {
+            skipped.push(file);
+            continue;
+        }
+        const data = coerceDates(applyFieldMap(parsed.data, fieldMap));
+        if (!data.type && typeInferenceCfg && knownTypes) {
+            data.type = inferTypeFromPath(file, typeInferenceCfg, knownTypes, context.schema.metadata.typeAliases);
+        }
+        if (!data.type) {
+            nonSpace.push(file);
+            continue;
+        }
+        if (ON_A_PAGE_TYPES.includes(data.type) && !options?.includeOnAPageFiles) {
+            continue;
+        }
+        const pageType = data.type;
+        const fileBase = basename(file, '.md');
+        const title = data.title ?? fileBase;
+        nodes.push({
+            label: file,
+            title,
+            schemaData: { title, ...data },
+            linkTargets: [title, fileBase],
+            type: pageType,
+        });
+        if (!ON_A_PAGE_TYPES.includes(pageType)) {
+            const { nodes: embedded, terminatedHeadings } = extractEmbeddedNodes(parsed.content, {
+                pageTitle: fileBase,
+                pageType,
+                metadata,
+                fieldMap,
+            });
+            nodes.push(...embedded);
+            for (const heading of terminatedHeadings) {
+                nonSpace.push(`${file} > ${heading}`);
+            }
+        }
+    }
+    return { nodes, parseIgnored: [...skipped, ...nonSpace], diagnostics: { kind: 'directory' } };
+}

package/dist/plugins/markdown/render-bullets.d.ts

@@ -0,0 +1,2 @@
+import type { SpaceGraph } from '../../space-graph';
+export declare function renderBullets(graph: SpaceGraph): string;

package/dist/plugins/markdown/render-bullets.js

@@ -0,0 +1,42 @@
+export function renderBullets(graph) {
+    const { hierarchyRoots, orphans, nonHierarchy, hierarchyChildren: children } = graph;
+    const lines = [];
+    const seen = new Set();
+    function renderNode(node, depth) {
+        const indent = '  '.repeat(depth);
+        const type = node.resolvedType;
+        const title = node.title;
+        const nodeChildren = children.get(title) ?? [];
+        if (seen.has(title)) {
+            if (nodeChildren.length > 0) {
+                lines.push(`${indent}- ${type}: ${title} (*)`);
+            }
+            return;
+        }
+        seen.add(title);
+        lines.push(`${indent}- ${type}: ${title}`);
+        for (const child of nodeChildren) {
+            renderNode(child, depth + 1);
+        }
+    }
+    for (const root of hierarchyRoots) {
+        renderNode(root, 0);
+    }
+    if (orphans.length > 0) {
+        lines.push('');
+        lines.push('Orphans (missing parent):');
+        for (const node of orphans) {
+            renderNode(node, 0);
+        }
+    }
+    if (nonHierarchy.length > 0) {
+        lines.push('');
+        lines.push('Other (not in hierarchy):');
+        for (const node of nonHierarchy) {
+            const type = node.resolvedType;
+            const title = node.title;
+            lines.push(`  - ${type}: ${title}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/plugins/markdown/render-mermaid.d.ts

@@ -0,0 +1,2 @@
+import type { SpaceGraph } from '../../space-graph';
+export declare function renderMermaid(graph: SpaceGraph): string;

package/dist/plugins/markdown/render-mermaid.js

@@ -0,0 +1,57 @@
+function escapeMermaidString(str) {
+    return str.replace(/"/g, '"');
+}
+function safeNodeId(id) {
+    return id.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+export function renderMermaid(graph) {
+    const { hierarchyRoots, orphans, hierarchyChildren: children, hierarchyTitles: hierarchyNodeSet } = graph;
+    let mmd = 'graph TD\n';
+    mmd += '  classDef vision fill:#ff9999,stroke:#ff0000,stroke-width:2px\n';
+    mmd += '  classDef mission fill:#99ccff,stroke:#0066cc,stroke-width:2px\n';
+    mmd += '  classDef goal fill:#99ff99,stroke:#00cc00,stroke-width:2px\n';
+    mmd += '  classDef opportunity fill:#ffcc99,stroke:#cc9900,stroke-width:2px\n';
+    mmd += '  classDef solution fill:#cc99ff,stroke:#6600cc,stroke-width:2px\n';
+    mmd += '  classDef identified fill:#f0f0f0,stroke:#999999,stroke-dasharray: 5 5\n';
+    mmd += '  classDef wondering fill:#fff0cc,stroke:#cccc00,stroke-dasharray: 5 5\n';
+    mmd += '  classDef exploring fill:#ffcc99,stroke:#cc9900,stroke-dasharray: 5 5\n';
+    mmd += '  classDef active fill:#99ff99,stroke:#00cc00,stroke-width:2px\n';
+    mmd += '  classDef paused fill:#ffcc99,stroke:#cc9900,stroke-width:2px\n';
+    mmd += '  classDef completed fill:#ccccff,stroke:#6666cc,stroke-width:2px\n';
+    mmd += '  classDef archived fill:#e0e0e0,stroke:#999999,stroke-width:2px\n';
+    const addedNodes = new Set();
+    function addNodeAndChildren(node) {
+        const nodeId = node.title;
+        if (addedNodes.has(nodeId))
+            return;
+        addedNodes.add(nodeId);
+        const type = node.resolvedType;
+        const status = node.schemaData.status;
+        const priority = node.schemaData.priority;
+        const label = priority ? `${nodeId} (${priority})` : nodeId;
+        const className = `${type}_${status}`;
+        const safeId = safeNodeId(nodeId);
+        const escapedLabel = escapeMermaidString(label);
+        mmd += `  ${safeId}["${escapedLabel}"]:::${className}\n`;
+        const nodeChildren = children.get(nodeId) ?? [];
+        for (const child of nodeChildren) {
+            const childTitle = child.title;
+            if (hierarchyNodeSet.has(childTitle)) {
+                const safeChildId = safeNodeId(childTitle);
+                mmd += `  ${safeId} --> ${safeChildId}\n`;
+                addNodeAndChildren(child);
+            }
+        }
+    }
+    for (const root of hierarchyRoots) {
+        addNodeAndChildren(root);
+    }
+    if (orphans.length > 0) {
+        mmd += '\n  subgraph Orphans\n';
+        for (const orphan of orphans) {
+            addNodeAndChildren(orphan);
+        }
+        mmd += '  end\n';
+    }
+    return mmd;
+}

package/dist/plugins/markdown/template-sync.d.ts

@@ -0,0 +1,16 @@
+import type { AnySchemaObject } from 'ajv';
+import type { HierarchyLevel, Relationship, SchemaWithMetadata } from '../../plugin-api';
+import type { PluginContext, TemplateSyncOptions } from '../util';
+export interface TypeVariant {
+    required: string[];
+    optional: string[];
+    properties: Record<string, AnySchemaObject>;
+    example: Record<string, string | number | boolean>;
+    description: string | undefined;
+    relationships: Relationship[];
+    /** Hierarchy child levels where this type is the parent and the level has templateFormat/matchers. */
+    hierarchyChildren: HierarchyLevel[];
+}
+export declare function getTypeVariants(schema: SchemaWithMetadata, schemaRefRegistry: Map<string, AnySchemaObject>): Map<string, TypeVariant>;
+export declare function generateNewContent(nodeType: string, variant: TypeVariant, schema: SchemaWithMetadata, schemaRefRegistry: Map<string, AnySchemaObject>, allVariants: Map<string, TypeVariant>, body?: string, fieldMap?: Record<string, string>): string;
+export declare function templateSync(context: PluginContext, options: TemplateSyncOptions): Promise<true | null>;

package/dist/plugins/markdown/template-sync.js

@@ -0,0 +1,294 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Glob } from 'bun';
+import matter from 'gray-matter';
+import yaml from 'js-yaml';
+import { mergeVariantProperties, resolveRef } from '../../schema/schema-refs';
+import { invertFieldMap } from './util';
+// Fields derived from the filesystem — present at validation time but not written to frontmatter
+const DERIVED_FIELDS = new Set(['title', 'content']);
+function enumPlaceholder(def) {
+    return def.enum?.join('|') ?? '';
+}
+function withEnumPlaceholders(example, properties, schema, schemaRefRegistry) {
+    return Object.fromEntries(Object.entries(example).map(([key, value]) => {
+        const def = resolveRef(properties[key], schema, schemaRefRegistry);
+        return def && 'enum' in def ? [key, enumPlaceholder(def)] : [key, value];
+    }));
+}
+function commentedHint(fieldName, propDef, schema, schemaRefRegistry) {
+    const def = resolveRef(propDef, schema, schemaRefRegistry);
+    let value;
+    const defTyped = def;
+    if (defTyped?.enum) {
+        value = enumPlaceholder(defTyped);
+    }
+    else if (defTyped?.type === 'integer') {
+        value = String(Math.ceil(((defTyped.minimum ?? 1) + (defTyped.maximum ?? 5)) / 2));
+    }
+    else if (defTyped?.type === 'array') {
+        value = '[]';
+    }
+    else {
+        value = '""';
+    }
+    const description = defTyped?.description;
+    return `# ${fieldName}: ${value}${description ? `  # ${description}` : ''}`;
+}
+export function getTypeVariants(schema, schemaRefRegistry) {
+    const map = new Map();
+    for (const variant of schema.oneOf) {
+        const typeName = variant.properties?.type?.const;
+        if (!typeName || typeName === 'dashboard' || typeName === 'ost_on_a_page')
+            continue;
+        if (!variant.examples?.[0])
+            continue;
+        const required = variant.required.filter((k) => k !== 'type' && !DERIVED_FIELDS.has(k));
+        const allProperties = Object.fromEntries(Object.entries(mergeVariantProperties(variant, schema, schemaRefRegistry).properties).filter(([k]) => k !== 'type' && !DERIVED_FIELDS.has(k)));
+        const optional = Object.keys(allProperties).filter((k) => !required.includes(k));
+        const example = variant.examples[0];
+        const description = variant.description;
+        const allRelationships = schema.metadata.relationships ?? [];
+        const typeRelationships = allRelationships.filter((rel) => rel.parent === typeName);
+        const allLevels = schema.metadata.hierarchy?.levels ?? [];
+        const typeIdx = allLevels.findIndex((l) => l.type === typeName);
+        const hierarchyChildren = typeIdx !== -1 && typeIdx < allLevels.length - 1
+            ? allLevels.slice(typeIdx + 1).filter((l) => l.templateFormat && l.matchers)
+            : [];
+        map.set(typeName, {
+            required,
+            optional,
+            properties: allProperties,
+            example,
+            description,
+            relationships: typeRelationships,
+            hierarchyChildren,
+        });
+    }
+    return map;
+}
+export function generateNewContent(nodeType, variant, schema, schemaRefRegistry, allVariants, body = '\nTODO\n', fieldMap = {}) {
+    const { example, optional, properties, description } = variant;
+    const exampleKeys = new Set(Object.keys(example));
+    // fieldMap is file→canonical; invert once to get canonical→file for template output
+    const canonicalToFile = invertFieldMap(fieldMap);
+    const toFileKey = (k) => canonicalToFile[k] ?? k;
+    const toCanonicalKey = (k) => fieldMap[k] ?? k;
+    const exampleWithPlaceholders = withEnumPlaceholders(example, properties, schema, schemaRefRegistry);
+    const remappedExample = Object.fromEntries(Object.entries(exampleWithPlaceholders).map(([k, v]) => [toFileKey(k), v]));
+    let frontmatterYaml = yaml.dump(remappedExample, { lineWidth: -1 }).trim();
+    // Append property descriptions as comments
+    // YAML lines use file field names; look up properties using canonical key.
+    const lines = frontmatterYaml.split('\n');
+    const commentedLines = lines.map((line) => {
+        const match = line.match(/^([^:]+):/);
+        if (match) {
+            const fileKey = match[1].trim();
+            const canonicalKey = toCanonicalKey(fileKey);
+            const propDef = resolveRef(properties[canonicalKey], schema, schemaRefRegistry);
+            const propDescription = propDef?.description;
+            if (propDescription) {
+                return `${line}  # ${propDescription}`;
+            }
+        }
+        return line;
+    });
+    frontmatterYaml = `# Template for a \`${nodeType}\`${schema.title ? ` from schema: ${schema.title}` : ''}\n${description ? `# ${description}\n` : ''}${commentedLines.join('\n')}`;
+    const hints = optional
+        .filter((field) => !exampleKeys.has(field))
+        .map((field) => commentedHint(toFileKey(field), properties[field], schema, schemaRefRegistry));
+    const newFrontmatter = hints.length > 0 ? `${frontmatterYaml}\n${hints.join('\n')}` : frontmatterYaml;
+    let relationshipStubs = '';
+    for (const rel of variant.relationships) {
+        const matcher = rel.matchers?.[0] || rel.type;
+        if (body.includes(`### ${matcher}`)) {
+            continue;
+        }
+        const childVariant = allVariants.get(rel.type);
+        const childExample = childVariant?.example || {};
+        if (rel.templateFormat === 'table' && rel.embeddedTemplateFields) {
+            const header = `| ${rel.embeddedTemplateFields.join(' | ')} |`;
+            const sep = `| ${rel.embeddedTemplateFields.map(() => '---|').join('')}`;
+            const exampleValues = rel.embeddedTemplateFields.map((field) => {
+                const val = childExample[field];
+                return val !== undefined ? String(val) : ' ';
+            });
+            const exampleRow = `| ${exampleValues.join(' | ')} |`;
+            relationshipStubs += `\n### ${matcher}\n\n${header}\n${sep}\n${exampleRow}\n`;
+        }
+        else if (rel.templateFormat === 'heading') {
+            let stub = `\n### ${matcher}\n\n`;
+            if (childVariant) {
+                // Include inline fields from example if it's a heading
+                const fields = Object.entries(childExample)
+                    .filter(([k]) => k !== 'type' && k !== 'title' && k !== 'parent')
+                    .map(([k, v]) => `[${k}:: ${v}]`)
+                    .join(' ');
+                stub += `${fields}${fields ? ' ' : ''}TODO: Describe ${rel.type}\n`;
+            }
+            else {
+                stub += `TODO: Describe ${rel.type}\n`;
+            }
+            relationshipStubs += stub;
+        }
+        else if (rel.templateFormat === 'list') {
+            let stub = `\n### ${matcher}\n\n- [type:: ${rel.type}] `;
+            if (childVariant) {
+                const fields = Object.entries(childExample)
+                    .filter(([k]) => k !== 'type' && k !== 'title' && k !== 'parent')
+                    .map(([k, v]) => `[${k}:: ${v}]`)
+                    .join(' ');
+                stub += `${fields}${fields ? ' ' : ''}TODO`;
+            }
+            else {
+                stub += 'TODO';
+            }
+            relationshipStubs += `${stub}\n`;
+        }
+    }
+    for (const level of variant.hierarchyChildren) {
+        const matcher = level.matchers?.[0] || level.type;
+        if (body.includes(`### ${matcher}`)) {
+            continue;
+        }
+        const childVariant = allVariants.get(level.type);
+        const childExample = childVariant?.example || {};
+        if (level.templateFormat === 'table' && level.embeddedTemplateFields) {
+            const header = `| ${level.embeddedTemplateFields.join(' | ')} |`;
+            const sep = `| ${level.embeddedTemplateFields.map(() => '---|').join('')}`;
+            const exampleValues = level.embeddedTemplateFields.map((field) => {
+                const val = childExample[field];
+                return val !== undefined ? String(val) : ' ';
+            });
+            const exampleRow = `| ${exampleValues.join(' | ')} |`;
+            relationshipStubs += `\n### ${matcher}\n\n${header}\n${sep}\n${exampleRow}\n`;
+        }
+        else if (level.templateFormat === 'list') {
+            let stub = `\n### ${matcher}\n\n- [type:: ${level.type}] `;
+            if (childVariant) {
+                const fields = Object.entries(childExample)
+                    .filter(([k]) => k !== 'type' && k !== 'title' && k !== 'parent')
+                    .map(([k, v]) => `[${k}:: ${v}]`)
+                    .join(' ');
+                stub += `${fields}${fields ? ' ' : ''}TODO`;
+            }
+            else {
+                stub += 'TODO';
+            }
+            relationshipStubs += `${stub}\n`;
+        }
+    }
+    const finalBody = relationshipStubs ? `\n${relationshipStubs}${body.trimStart()}` : body;
+    return `---\n${newFrontmatter}\n---${finalBody}`;
+}
+export async function templateSync(context, options) {
+    const { templateDir, templatePrefix = '', fieldMap = {} } = context.pluginConfig;
+    if (!templateDir) {
+        console.error('Error: templateDir not set in markdown config for this space');
+        process.exit(1);
+    }
+    const { schema, schemaRefRegistry } = context;
+    const typeVariants = getTypeVariants(schema, schemaRefRegistry);
+    const matchedTypes = new Set();
+    const files = await Array.fromAsync(new Glob('*.md').scan({ cwd: templateDir, absolute: true }));
+    const dryRun = options.dryRun ?? false;
+    let filesModified = 0;
+    let filesCreated = 0;
+    console.log(`\n🔄 Template Sync`);
+    console.log('━'.repeat(50));
+    if (dryRun)
+        console.log('(dry run — no files will be modified)\n');
+    for (const file of files.sort()) {
+        const filename = file.split('/').pop();
+        const content = readFileSync(file, 'utf-8');
+        const fmMatch = content.match(/^---\n[\s\S]*?\n---/);
+        if (!fmMatch) {
+            continue;
+        }
+        const body = content.slice(fmMatch[0].length);
+        const parsed = matter(content);
+        const nodeType = parsed.data.type;
+        if (!nodeType) {
+            continue;
+        }
+        const variant = typeVariants.get(nodeType);
+        if (!variant) {
+            continue;
+        }
+        matchedTypes.add(nodeType);
+        // Warning if filename doesn't match convention
+        const expectedFilename = `${templatePrefix}${nodeType}.md`;
+        if (filename !== expectedFilename) {
+            console.log(`⚠  ${filename}: type "${nodeType}" should be named "${expectedFilename}"`);
+        }
+        const newContent = generateNewContent(nodeType, variant, schema, schemaRefRegistry, typeVariants, body, fieldMap);
+        if (newContent === content) {
+            console.log(`✓  ${filename}`);
+        }
+        else {
+            console.log(`📝 ${filename}: updated`);
+            if (dryRun) {
+                // Simple line-based diff for preview
+                const oldLines = content.split('\n');
+                const newLines = newContent.split('\n');
+                const maxLines = Math.max(oldLines.length, newLines.length);
+                let inFrontmatter = true;
+                for (let i = 0; i < maxLines; i++) {
+                    const isFmEnd = inFrontmatter && oldLines[i] === '---' && i > 0;
+                    if (isFmEnd)
+                        inFrontmatter = false;
+                    if (oldLines[i] !== newLines[i]) {
+                        if (i < oldLines.length)
+                            console.log(`\x1b[31m- ${oldLines[i] || ''}\x1b[0m`);
+                        if (i < newLines.length)
+                            console.log(`\x1b[32m+ ${newLines[i] || ''}\x1b[0m`);
+                    }
+                    else if (i < 15) {
+                        // Show some context but not too much
+                        console.log(`  ${oldLines[i]}`);
+                    }
+                    if (isFmEnd) {
+                        // After frontmatter ends, only continue if next line differs
+                        if (i + 1 >= maxLines || oldLines[i + 1] === newLines[i + 1]) {
+                            break;
+                        }
+                    }
+                }
+                console.log('');
+            }
+            if (!dryRun) {
+                writeFileSync(file, newContent);
+                filesModified++;
+            }
+        }
+    }
+    // Handle missing types
+    const missingTypes = Array.from(typeVariants.keys()).filter((t) => !matchedTypes.has(t));
+    if (missingTypes.length > 0) {
+        console.log(`\nMissing templates for: ${missingTypes.join(', ')}`);
+        if (options.createMissing) {
+            for (const type of missingTypes) {
+                const variant = typeVariants.get(type);
+                const newContent = generateNewContent(type, variant, schema, schemaRefRegistry, typeVariants, undefined, fieldMap);
+                const newFilename = `${templatePrefix}${type}.md`;
+                const newFilePath = join(templateDir, newFilename);
+                console.log(`✨ ${newFilename}: creating`);
+                if (!dryRun) {
+                    writeFileSync(newFilePath, newContent);
+                    filesCreated++;
+                }
+            }
+        }
+        else {
+            console.log('(use --create-missing to scaffold them)');
+        }
+    }
+    console.log(`\n${'━'.repeat(50)}`);
+    if (dryRun) {
+        console.log('No files modified or created (dry run)\n');
+    }
+    else {
+        console.log(`${filesModified} file(s) updated, ${filesCreated} file(s) created\n`);
+    }
+    return true;
+}

package/dist/plugins/markdown/util.d.ts

@@ -0,0 +1,19 @@
+import type { TypeInferenceConfig } from '.';
+export declare function inferTypeFromPath(filePath: string, config: TypeInferenceConfig, knownTypes: Set<string>, typeAliases: Record<string, string> | undefined): string | undefined;
+/**
+ * Coerce Date objects in frontmatter/YAML data to ISO date strings (YYYY-MM-DD).
+ * gray-matter and js-yaml parse unquoted ISO dates (e.g. `date: 2026-03-31`) as
+ * JavaScript Date objects, which are not valid JSON and fail string type validation.
+ */
+export declare function coerceDates(data: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Apply field remapping to a data object.
+ * Renames keys according to fieldMap (file field name → canonical field name).
+ * Fields not in the map are passed through unchanged.
+ */
+export declare function applyFieldMap(data: Record<string, unknown>, fieldMap: Record<string, string> | undefined): Record<string, unknown>;
+/**
+ * Invert a fieldMap (file→canonical) to produce a reverse map (canonical→file).
+ * Used for write operations (e.g. template-sync) to translate back to file field names.
+ */
+export declare function invertFieldMap(fieldMap: Record<string, string>): Record<string, string>;

package/dist/plugins/markdown/util.js

@@ -0,0 +1,80 @@
+import { posix } from 'node:path';
+export function inferTypeFromPath(filePath, config, knownTypes, typeAliases) {
+    if (config.mode === 'off')
+        return undefined;
+    const normalized = filePath.replace(/\\/g, '/');
+    const dir = posix.dirname(normalized);
+    if (dir === '.')
+        return undefined;
+    if (config.folderMap) {
+        const normalizedMap = Object.fromEntries(Object.entries(config.folderMap).map(([k, v]) => [k.replace(/\\/g, '/').replace(/\/+$/, ''), v]));
+        let bestKey;
+        for (const key of Object.keys(normalizedMap)) {
+            if (dir === key || dir.startsWith(`${key}/`)) {
+                if (!bestKey || key.length > bestKey.length)
+                    bestKey = key;
+            }
+        }
+        if (!bestKey)
+            return undefined;
+        const value = normalizedMap[bestKey];
+        if (typeAliases?.[value] !== undefined)
+            return typeAliases[value];
+        if (knownTypes.has(value))
+            return value;
+        throw new Error(`typeInference.folderMap: "${value}" does not resolve to a known type or alias (from key "${bestKey}")`);
+    }
+    const leafDir = posix.basename(dir).toLowerCase();
+    for (const type of knownTypes) {
+        if (type.toLowerCase() === leafDir)
+            return type;
+    }
+    if (typeAliases) {
+        for (const [alias, canonical] of Object.entries(typeAliases)) {
+            if (alias.toLowerCase() === leafDir)
+                return canonical;
+        }
+    }
+    return undefined;
+}
+/**
+ * Coerce Date objects in frontmatter/YAML data to ISO date strings (YYYY-MM-DD).
+ * gray-matter and js-yaml parse unquoted ISO dates (e.g. `date: 2026-03-31`) as
+ * JavaScript Date objects, which are not valid JSON and fail string type validation.
+ */
+export function coerceDates(data) {
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (value instanceof Date) {
+            result[key] = value.toISOString().slice(0, 10);
+        }
+        else if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            result[key] = coerceDates(value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Apply field remapping to a data object.
+ * Renames keys according to fieldMap (file field name → canonical field name).
+ * Fields not in the map are passed through unchanged.
+ */
+export function applyFieldMap(data, fieldMap) {
+    if (!fieldMap || Object.keys(fieldMap).length === 0)
+        return data;
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        result[fieldMap[key] ?? key] = value;
+    }
+    return result;
+}
+/**
+ * Invert a fieldMap (file→canonical) to produce a reverse map (canonical→file).
+ * Used for write operations (e.g. template-sync) to translate back to file field names.
+ */
+export function invertFieldMap(fieldMap) {
+    return Object.fromEntries(Object.entries(fieldMap).map(([src, canonical]) => [canonical, src]));
+}

package/dist/plugins/util.d.ts

@@ -0,0 +1,60 @@
+import type { AnySchemaObject } from 'ajv';
+import type { SpaceGraph } from '../space-graph';
+import type { BaseNode, SpaceContext } from '../types';
+export declare const PLUGIN_PREFIX = "sctx-";
+export declare const CONFIG_PLUGINS_DIR = "plugins";
+/** Normalize a plugin name to its canonical prefixed form. */
+export declare function normalizePluginName(name: string): string;
+export type PluginContext = SpaceContext & {
+    /** Validated config for this plugin invocation. */
+    pluginConfig: Record<string, unknown>;
+};
+export type ParseResult = {
+    nodes: BaseNode[];
+    /** Paths/items the plugin skipped during parsing, for any reason. */
+    parseIgnored: string[];
+    /** Plugin diagnostics: keyed scalar or list values. */
+    diagnostics: Record<string, number | string | string[]>;
+};
+export type ParseHook = (context: PluginContext) => Promise<ParseResult | null>;
+export type TemplateSyncOptions = {
+    dryRun?: boolean;
+    createMissing?: boolean;
+};
+export type TemplateSyncHook = (context: PluginContext, options: TemplateSyncOptions) => Promise<true | null>;
+/** A single render output format provided by a plugin. */
+export type RenderFormat = {
+    /** Short name, unique within the plugin (e.g. 'bullets', 'mermaid'). */
+    name: string;
+    /** Human-readable description shown in `render list`. */
+    description: string;
+};
+/** Options passed to a render function. */
+export type RenderOptions = {
+    /** The format name being rendered (e.g. 'bullets', 'mermaid'). */
+    format: string;
+};
+/**
+ * The render hook on a plugin: declares available formats and handles rendering.
+ * Unlike parse/templateSync (first-responder), render hooks are additive —
+ * all formats from all plugins are available simultaneously.
+ */
+export type RenderHook = {
+    formats: RenderFormat[];
+    render: (context: PluginContext, graph: SpaceGraph, options: RenderOptions) => Promise<string> | string;
+};
+/**
+ * Plugin contract:
+ * - A hook not implemented on the plugin → that plugin is skipped for that operation.
+ * - parse/templateSync return `T | null` → null means "didn't handle, try next plugin".
+ * - render is additive: all plugins' formats are registered and dispatched by name.
+ */
+export type StructuredContextPlugin = {
+    name: string;
+    /** JSON Schema used to validate the plugin's config block. Fields with `format: 'path'`
+     * are resolved relative to the config directory by `resolveConfigPaths` in the loader. */
+    configSchema: AnySchemaObject;
+    parse?: ParseHook;
+    templateSync?: TemplateSyncHook;
+    render?: RenderHook;
+};