structured-context 0.9.0

package/dist/commands/schemas.js

@@ -0,0 +1,268 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { loadConfig, resolveSchema } from '../config';
+import { bundledSchemasDir, extractEntityInfo, loadSchema, readRawSchema } from '../schema/schema';
+import { mergeVariantProperties } from '../schema/schema-refs';
+function isBundledPath(schemaPath) {
+    return dirname(schemaPath) === bundledSchemasDir;
+}
+function extractRefs(obj, refs) {
+    if (typeof obj !== 'object' || obj === null)
+        return;
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === '$ref' && typeof value === 'string') {
+            refs.add(value);
+        }
+        else {
+            extractRefs(value, refs);
+        }
+    }
+}
+function extractEntities(oneOf, schemaRefRegistry, schema) {
+    return oneOf.map((entry) => {
+        const entryObj = entry;
+        const { properties, required } = mergeVariantProperties(entryObj, schema, schemaRefRegistry);
+        const typeDef = properties.type;
+        let types = [];
+        if (typeDef?.const)
+            types = [String(typeDef.const)];
+        else if (Array.isArray(typeDef?.enum))
+            types = typeDef.enum.map(String);
+        return {
+            types,
+            description: typeof entryObj.description === 'string' ? entryObj.description : undefined,
+            properties: Object.keys(properties).filter((k) => k !== 'type'),
+            required: required.filter((r) => r !== 'type'),
+        };
+    });
+}
+function showEntities(oneOf, schemaRefRegistry, schema) {
+    const entities = extractEntities(oneOf, schemaRefRegistry, schema);
+    console.log('\nEntities:');
+    for (const { types, description, properties, required } of entities) {
+        const label = types.length > 0 ? types.join(', ') : '(unknown)';
+        if (properties.length === 0) {
+            console.log(`  ${label}${description ? ` — ${description}` : ''}`);
+        }
+        else {
+            const propList = properties.map((p) => (required.includes(p) ? `${p}*` : p)).join('  ');
+            console.log(`  ${label}${description ? ` — ${description}` : ''}`);
+            console.log(`    ${propList}`);
+        }
+    }
+}
+function showDefs(defs) {
+    const keys = Object.keys(defs).filter((k) => !k.startsWith('_'));
+    if (keys.length === 0)
+        return;
+    console.log('\nDefinitions:');
+    for (const key of keys) {
+        const def = defs[key];
+        const props = def.properties ? Object.keys(def.properties) : [];
+        const desc = def.description ? ` — ${def.description}` : '';
+        if (props.length > 0) {
+            console.log(`  ${key}${desc}`);
+            console.log(`    properties: ${props.join(', ')}`);
+        }
+        else {
+            const typeInfo = def.type ? ` (${def.type})` : '';
+            const enumInfo = Array.isArray(def.enum) ? ` [${def.enum.join(', ')}]` : '';
+            console.log(`  ${key}${typeInfo}${enumInfo}${desc}`);
+        }
+    }
+}
+function showMetadata(metadata) {
+    if (metadata.hierarchy?.levels.length) {
+        const parts = metadata.hierarchy.levels.map((l) => (l.selfRef ? `${l.type}(+)` : l.type));
+        console.log(`\nhierarchy: ${parts.join(' → ')}`);
+    }
+    else {
+        console.log('\nhierarchy: (none)');
+    }
+    if (metadata.typeAliases && Object.keys(metadata.typeAliases).length > 0) {
+        const aliasParts = Object.entries(metadata.typeAliases).map(([k, v]) => `${k} → ${v}`);
+        console.log(`type aliases: ${aliasParts.join(', ')}`);
+    }
+    if (metadata.rules) {
+        const groups = new Map();
+        for (const rule of metadata.rules) {
+            const rules = groups.get(rule.category) ?? [];
+            rules.push({ id: rule.id, description: rule.description });
+            groups.set(rule.category, rules);
+        }
+        if (groups.size > 0) {
+            console.log('\nRules:');
+            for (const [group, items] of groups) {
+                console.log(`  ${group}:`);
+                for (const item of items) {
+                    console.log(`    ${item.id}: ${item.description}`);
+                }
+            }
+        }
+    }
+    if (metadata.relationships && metadata.relationships.length > 0) {
+        console.log('\nRelationships:');
+        for (const rel of metadata.relationships) {
+            const fields = rel.embeddedTemplateFields?.length ? ` [fields: ${rel.embeddedTemplateFields.join(', ')}]` : '';
+            const matchers = rel.matchers?.length ? ` (matches: ${rel.matchers.join(', ')})` : '';
+            console.log(`  ${rel.parent} → ${rel.type} [${rel.templateFormat ?? 'page'}]${fields}${matchers}`);
+        }
+    }
+}
+function showRegistry(schemaPath, schemaRefRegistry) {
+    const bundledIds = new Set();
+    if (existsSync(bundledSchemasDir)) {
+        for (const file of readdirSync(bundledSchemasDir).filter((f) => f.endsWith('.json'))) {
+            const s = readRawSchema(join(bundledSchemasDir, file));
+            if (typeof s.$id === 'string')
+                bundledIds.add(s.$id);
+        }
+    }
+    console.log(`\nRegistry (${schemaPath}):`);
+    for (const [id] of schemaRefRegistry) {
+        console.log(`  [${bundledIds.has(id) ? 'bundled' : 'local'}]  ${id}`);
+    }
+}
+/**
+ * Generate Mermaid ERD from schema metadata.
+ * Shows entity types, properties, and parent-child relationships.
+ */
+function generateMermaidErd(metadata, entities) {
+    let mmd = 'erDiagram\n';
+    const hierarchyLevels = metadata.hierarchy?.levels ?? [];
+    // Generate entity definitions with properties
+    for (const entity of entities) {
+        const safeName = entity.type.replace(/[^a-zA-Z0-9_]/g, '_');
+        mmd += `  ${safeName} {\n`;
+        mmd += `    string title PK\n`;
+        for (const prop of entity.properties) {
+            if (prop === 'title')
+                continue; // Skip title since it's already declared as PK
+            const isRequired = entity.required.includes(prop);
+            const optional = isRequired ? '' : ' "optional"';
+            mmd += `    string ${prop}${optional}\n`;
+        }
+        mmd += '  }\n';
+    }
+    // Generate relationships based on hierarchy metadata
+    if (hierarchyLevels.length > 0) {
+        for (let i = 0; i < hierarchyLevels.length - 1; i++) {
+            const current = hierarchyLevels[i];
+            const next = hierarchyLevels[i + 1];
+            if (!current || !next)
+                continue;
+            const currentSafe = current.type.replace(/[^a-zA-Z0-9_]/g, '_');
+            const nextSafe = next.type.replace(/[^a-zA-Z0-9_]/g, '_');
+            // Determine cardinality based on selfRef
+            // If next.selfRef is true, the child type can have parents of the same type
+            if (next.selfRef) {
+                mmd += `  ${currentSafe} ||--|{ ${nextSafe} : "parent"\n`;
+            }
+            else {
+                mmd += `  ${currentSafe} ||--o{ ${nextSafe} : "parent"\n`;
+            }
+        }
+    }
+    return mmd;
+}
+export function listSchemas() {
+    const config = loadConfig();
+    // List all schemas known to config
+    if (existsSync(bundledSchemasDir)) {
+        const files = readdirSync(bundledSchemasDir)
+            .filter((f) => f.endsWith('.json'))
+            .sort();
+        if (files.length > 0) {
+            console.log('Bundled schemas:');
+            for (const file of files) {
+                const schema = readRawSchema(join(bundledSchemasDir, file));
+                const id = typeof schema.$id === 'string' ? schema.$id : '(no $id)';
+                console.log(`  ${file}${file.startsWith('_') ? '  [partial]' : ''}  (${id})`);
+            }
+        }
+    }
+    const configured = [];
+    const seen = new Set();
+    if (config.schema && !isBundledPath(config.schema)) {
+        configured.push({ source: 'global', path: config.schema });
+        seen.add(config.schema);
+    }
+    for (const space of config.spaces) {
+        if (space.schema && !seen.has(space.schema) && !isBundledPath(space.schema)) {
+            configured.push({ source: space.name, path: space.schema });
+            seen.add(space.schema);
+        }
+    }
+    if (configured.length > 0) {
+        console.log('\nConfigured schemas:');
+        for (const { source, path } of configured) {
+            console.log(`  ${source}: ${path}`);
+        }
+    }
+}
+export function showSchema(file, options) {
+    const config = loadConfig();
+    let schemaPath;
+    if (options.space) {
+        const space = config.spaces.find((s) => s.name === options.space);
+        if (!space) {
+            console.error(`Error: Unknown space "${options.space}"`);
+            process.exit(1);
+        }
+        schemaPath = resolveSchema(config, space);
+    }
+    else if (!file) {
+        console.error('Error: specify a file argument or use --space');
+        process.exit(1);
+    }
+    else if (file.startsWith('/') || file.startsWith('./')) {
+        schemaPath = file;
+    }
+    else {
+        schemaPath = join(bundledSchemasDir, file.endsWith('.json') ? file : `${file}.json`);
+    }
+    if (!existsSync(schemaPath)) {
+        console.error(`Schema not found: ${schemaPath}`);
+        console.error('\nHint: Use ./ or / prefix for local paths (e.g. ./schemas/my_schema.json),');
+        console.error("      or use --space to show a space's configured schema.");
+        const matchingSpace = config.spaces.find((s) => s.schema?.includes(file || ''));
+        if (matchingSpace) {
+            console.error(`      Did you mean: --space ${matchingSpace.name}?`);
+        }
+        process.exit(1);
+    }
+    const content = readFileSync(schemaPath, 'utf-8');
+    if (options.raw) {
+        process.stdout.write(content);
+        return;
+    }
+    const { schema, schemaRefRegistry } = loadSchema(schemaPath);
+    // Handle --mermaid-erd: generate ERD and exit
+    if (options.mermaidErd) {
+        const entityInfo = extractEntityInfo(schema, schemaRefRegistry);
+        const mermaid = generateMermaidErd(schema.metadata, entityInfo);
+        process.stdout.write(mermaid);
+        return;
+    }
+    console.log(`$id: ${schema.$id ?? '(none)'}`);
+    if (schema.title)
+        console.log(`title: ${schema.title}`);
+    if (schema.description)
+        console.log(`description: ${schema.description}`);
+    showMetadata(schema.metadata);
+    if (Array.isArray(schema.oneOf)) {
+        showEntities(schema.oneOf, schemaRefRegistry, schema);
+    }
+    const defs = schema.$defs;
+    if (defs)
+        showDefs(defs);
+    const refs = new Set();
+    extractRefs(schema, refs);
+    if (refs.size > 0) {
+        console.log('\n$refs:');
+        for (const ref of [...refs].sort()) {
+            console.log(`  ${ref}`);
+        }
+    }
+    showRegistry(schemaPath, schemaRefRegistry);
+}

package/dist/commands/show.d.ts

@@ -0,0 +1,4 @@
+import type { SpaceContext } from '../types';
+export declare function show(context: SpaceContext, options?: {
+    filter?: string;
+}): Promise<void>;

package/dist/commands/show.js

@@ -0,0 +1,7 @@
+import { executeRender } from '../render/render';
+export async function show(context, options) {
+    const result = await executeRender('markdown.bullets', context, { filter: options?.filter });
+    process.stdout.write(result);
+    if (!result.endsWith('\n'))
+        process.stdout.write('\n');
+}

package/dist/commands/spaces.d.ts

@@ -0,0 +1 @@
+export declare function listSpaces(): void;

package/dist/commands/spaces.js

@@ -0,0 +1,36 @@
+import { basename, resolve } from 'node:path';
+import { configPath, loadConfig, resolveSchema } from '../config';
+function renderConfigValue(v) {
+    if (typeof v === 'object' && v !== null)
+        return JSON.stringify(v);
+    return String(v);
+}
+export function listSpaces() {
+    const path = resolve(configPath());
+    const config = loadConfig();
+    console.log(`Config: ${path}\n`);
+    for (const space of config.spaces) {
+        console.log(`${space.name}`);
+        console.log(`  path:    ${space.path}`);
+        console.log(`  schema:  ${basename(resolveSchema(config, space))}`);
+        if (space.miroBoardId)
+            console.log(`  miro:    configured`);
+        const plugins = space.plugins ?? {};
+        if (Object.keys(plugins).length > 0) {
+            console.log('  plugins:');
+            for (const [name, cfg] of Object.entries(plugins)) {
+                const entries = Object.entries(cfg);
+                if (entries.length === 0) {
+                    console.log(`    ${name}`);
+                }
+                else {
+                    console.log(`    ${name}:`);
+                    for (const [k, v] of entries) {
+                        console.log(`      ${k}: ${renderConfigValue(v)}`);
+                    }
+                }
+            }
+        }
+        console.log('');
+    }
+}

package/dist/commands/template-sync.d.ts

@@ -0,0 +1,3 @@
+import type { TemplateSyncOptions } from '../plugins/util';
+import type { SpaceContext } from '../types';
+export declare function templateSync(context: SpaceContext, options: TemplateSyncOptions): Promise<void>;

package/dist/commands/template-sync.js

@@ -0,0 +1,13 @@
+import { loadPlugins } from '../plugins/loader';
+export async function templateSync(context, options) {
+    const pluginMap = context.space?.plugins ?? {};
+    const loaded = await loadPlugins(pluginMap, context.configDir);
+    for (const { plugin, pluginConfig } of loaded) {
+        if (!plugin.templateSync)
+            continue;
+        const result = await plugin.templateSync({ ...context, pluginConfig }, options);
+        if (result !== null)
+            return;
+    }
+    throw new Error('No plugin supports template-sync for this space');
+}

package/dist/commands/validate-file.d.ts

@@ -0,0 +1,28 @@
+export interface FileValidationResult {
+    file: string;
+    label: string;
+    space: string;
+    /** Errors keyed by composite id (e.g. `schema:/status:enum:active`, `rule:my-rule-id`). */
+    errors: Record<string, {
+        kind: string;
+        message: string;
+    }>;
+    errorCount: number;
+    inSpace: true;
+}
+export interface FileNotInSpaceResult {
+    file: string;
+    inSpace: false;
+    message: string;
+}
+export type ValidateFileOutput = FileValidationResult | FileNotInSpaceResult;
+/**
+ * Validate a single file within its space.
+ *
+ * Reads the full space (required for graph correctness) but filters all reported
+ * errors to only those attributable to the target file. Exits 0 if the file is
+ * not in any configured space (not an error — hooks call this on all file writes).
+ */
+export declare function validateFile(filePath: string, options?: {
+    json?: boolean;
+}): Promise<number>;

package/dist/commands/validate-file.js

@@ -0,0 +1,133 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+import { getSpaceConfigDir, loadConfig, resolveSchema } from '../config';
+import { readSpace } from '../read/read-space';
+import { loadSchema } from '../schema/schema';
+import { validateGraph } from '../schema/validate-graph';
+import { validateRules } from '../schema/validate-rules';
+import { formatErrors } from './validate';
+/** Find which space a file belongs to by checking directory containment. */
+function resolveFileSpace(filePath, config) {
+    const absFile = isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath);
+    for (const space of config.spaces) {
+        const absSpace = isAbsolute(space.path) ? space.path : resolve(process.cwd(), space.path);
+        // Trailing slash prevents prefix-match false positives (e.g. /foo matching /foobar/)
+        const spaceDir = absSpace.endsWith('/') ? absSpace : `${absSpace}/`;
+        if (absFile.startsWith(spaceDir) || absFile === absSpace) {
+            return { space, label: relative(absSpace, absFile) };
+        }
+    }
+    return null;
+}
+function buildContextForSpace(space, config) {
+    const resolvedSchemaPath = resolveSchema(config, space);
+    const { schema, schemaRefRegistry, schemaValidator } = loadSchema(resolvedSchemaPath);
+    const configDir = getSpaceConfigDir(space.name);
+    return { space, config, resolvedSchemaPath, schema, schemaRefRegistry, schemaValidator, configDir };
+}
+/**
+ * Validate a single file within its space.
+ *
+ * Reads the full space (required for graph correctness) but filters all reported
+ * errors to only those attributable to the target file. Exits 0 if the file is
+ * not in any configured space (not an error — hooks call this on all file writes).
+ */
+export async function validateFile(filePath, options = {}) {
+    const config = loadConfig();
+    const resolved = resolveFileSpace(filePath, config);
+    if (!resolved) {
+        const result = {
+            file: filePath,
+            inSpace: false,
+            message: 'File does not belong to any configured space.',
+        };
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        return 0;
+    }
+    const { space, label } = resolved;
+    const context = buildContextForSpace(space, config);
+    const { schema, schemaRefRegistry, schemaValidator } = context;
+    const metadata = schema.metadata;
+    const readResult = await readSpace(context);
+    const { nodes } = readResult;
+    const errors = {};
+    // Schema validation errors for this node
+    for (const node of nodes) {
+        if (node.label !== label)
+            continue;
+        const valid = schemaValidator(node.schemaData);
+        if (!valid) {
+            const formatted = formatErrors(schemaValidator.errors ?? [], schema, schemaRefRegistry, node.schemaData);
+            for (const { message, dedupeKey } of formatted) {
+                errors[`schema:${dedupeKey}`] = { kind: 'schema', message };
+            }
+        }
+    }
+    // Duplicate key errors — include if this file is one of the duplicates
+    const titleToFiles = new Map();
+    for (const node of nodes) {
+        if (!titleToFiles.has(node.title))
+            titleToFiles.set(node.title, []);
+        titleToFiles.get(node.title).push(node.label);
+    }
+    for (const [title, files] of titleToFiles) {
+        if (files.length > 1 && files.includes(label)) {
+            const others = files.filter((f) => f !== label);
+            errors[`duplicate:${title}`] = {
+                kind: 'duplicate',
+                message: `Duplicate title "${title}" also exists in: ${others.join(', ')}`,
+            };
+        }
+    }
+    // Broken links and hierarchy violations from this file
+    const hierarchyValidation = validateGraph(nodes, metadata, readResult.unresolvedRefs);
+    for (const { file, parent, error } of hierarchyValidation.refErrors) {
+        if (file === label) {
+            errors[`broken-link:${parent}`] = { kind: 'broken-link', message: `${parent} → ${error}` };
+        }
+    }
+    for (const v of hierarchyValidation.violations) {
+        if (v.file === label) {
+            errors[`hierarchy:${v.description}`] = { kind: 'hierarchy', message: v.description };
+        }
+    }
+    // Rule violations for this node
+    if (metadata.rules) {
+        const ruleViolations = await validateRules(nodes, metadata.rules);
+        for (const v of ruleViolations) {
+            if (v.file === label) {
+                errors[`rule:${v.ruleId}`] = { kind: 'rule', message: `[${v.ruleId}] ${v.description}` };
+            }
+        }
+    }
+    const result = {
+        file: isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath),
+        label,
+        space: space.name,
+        errors,
+        errorCount: Object.keys(errors).length,
+        inSpace: true,
+    };
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        printHumanReadable(result);
+    }
+    return Object.keys(errors).length > 0 ? 1 : 0;
+}
+function printHumanReadable(result) {
+    const reset = '\x1b[0m';
+    const green = '\x1b[32m';
+    const red = '\x1b[31m';
+    if (result.errorCount === 0) {
+        console.log(`${green}✓${reset} ${result.label} (space: ${result.space})`);
+        return;
+    }
+    console.log(`\n${red}✗${reset} ${result.label} (space: ${result.space}) — ${result.errorCount} error(s)\n`);
+    for (const { kind, message } of Object.values(result.errors)) {
+        console.log(`  [${kind}] ${message}`);
+    }
+    console.log('');
+}

package/dist/commands/validate.d.ts

@@ -0,0 +1,16 @@
+import type { ErrorObject } from 'ajv';
+import { extractEntityInfo } from '../schema/schema';
+import type { SchemaWithMetadata, SpaceContext } from '../types';
+export interface FormattedError {
+    message: string;
+    dedupeKey: string;
+}
+/**
+ * Format AJV errors for better readability.
+ * Groups related errors and extracts helpful context like allowed values.
+ */
+export declare function formatErrors(errors: ErrorObject[], schema: SchemaWithMetadata, schemaRefRegistry: Parameters<typeof extractEntityInfo>[1], nodeData: Record<string, unknown>): FormattedError[];
+export declare function validate(context: SpaceContext, options?: {
+    json?: boolean;
+}): Promise<number>;
+export declare function watchValidate(context: SpaceContext): Promise<never>;