structured-context 0.10.0 → 0.12.0

package/dist/config.js

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import Ajv from 'ajv';
+import Ajv2020 from 'ajv/dist/2020';
 import JSON5 from 'json5';
 import { ENV_CONFIG_VAR, XDG_CONFIG_DIR } from './constants';
-import { normalizePluginName } from './plugins/util';
+import { normalizePluginName, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from './plugins/util';
 import { bundledSchemasDir } from './schema/schema';
 const CONFIG_SCHEMA = {
     type: 'object',
@@ -17,8 +17,6 @@ const CONFIG_SCHEMA = {
                     name: { type: 'string', pattern: '^[a-z0-9_-]+$' },
                     path: { type: 'string' },
                     schema: { type: 'string' },
-                    miroBoardId: { type: 'string' },
-                    miroFrameId: { type: 'string' },
                     plugins: { type: 'object', additionalProperties: { type: 'object' } },
                     views: {
                         type: 'object',
@@ -37,7 +35,7 @@ const CONFIG_SCHEMA = {
         schema: { type: 'string' },
         includeSpacesFrom: { type: 'array', items: { type: 'string' } },
     },
-    required: ['spaces'],
+    anyOf: [{ required: ['spaces'] }, { required: ['includeSpacesFrom'] }],
     additionalProperties: false,
 };
 let _configPathOverride;
@@ -54,18 +52,6 @@ export function getConfigSourceFiles() {
     }
     return new Set(_spaceSourceFiles.values());
 }
-/**
- * Get the directory of the config file that defines a given space.
- */
-export function getSpaceConfigDir(spaceName) {
-    if (_spaceSourceFiles.size === 0) {
-        loadConfig();
-    }
-    const spaceConfigPath = _spaceSourceFiles.get(spaceName);
-    if (!spaceConfigPath)
-        throw new Error('Space config path not found');
-    return dirname(spaceConfigPath);
-}
 export function configPath() {
     if (_configPathOverride) {
         return _configPathOverride;
@@ -101,13 +87,10 @@ function resolveRelativePaths(config, configDir) {
     const relSchema = (p) => {
         if (!p || isAbsolute(p) || isUrl(p))
             return p;
-        if (!p.includes('/') && !p.includes('\\')) {
-            const localPath = resolve(configDir, p);
-            if (existsSync(localPath))
-                return localPath;
-            return join(bundledSchemasDir, p);
+        if (p.startsWith('./') || p.startsWith('../')) {
+            return resolve(configDir, p);
         }
-        return resolve(configDir, p);
+        return p;
     };
     return {
         ...config,
@@ -125,11 +108,13 @@ function _loadConfig(path) {
         throw new Error(`Config file not found: ${path}`);
     }
     const config = JSON5.parse(readFileSync(path, 'utf-8'));
-    const ajv = new Ajv();
+    const ajv = new Ajv2020();
     const validate = ajv.compile(CONFIG_SCHEMA);
     if (!validate(config)) {
         throw new Error(`Invalid config in ${path}: ${JSON.stringify(validate.errors)}`);
     }
+    if (!config.spaces)
+        config.spaces = [];
     return config;
 }
 export function loadConfig() {
@@ -141,8 +126,10 @@ export function loadConfig() {
     const config = _loadConfig(path);
     _spaceSourceFiles.clear();
     // Track which spaces come from the main config file
+    const mainSourceDir = dirname(resolve(path));
     for (const space of config.spaces) {
         _spaceSourceFiles.set(space.name, path);
+        space.sourceDir = mainSourceDir;
     }
     // Load includeSpacesFrom configs and merge their spaces in, with later entries taking precedence over earlier ones
     if (config.includeSpacesFrom) {
@@ -154,8 +141,10 @@ export function loadConfig() {
                 throw new Error(`Included config contains spaces with duplicate names: ${resolvedIncludePath}`);
             }
             // Track which spaces come from this included config file
+            const includeSourceDir = dirname(resolvedIncludePath);
             for (const space of includedConfig.spaces) {
                 _spaceSourceFiles.set(space.name, resolvedIncludePath);
+                space.sourceDir = includeSourceDir;
             }
             config.spaces.push(...includedConfig.spaces);
         }
@@ -170,25 +159,109 @@ export function getSpaceConfig(name, config) {
     }
     return space;
 }
+/**
+ * Resolve a schema identifier or path to an absolute file path.
+ *
+ * Precedence:
+ * 1. Absolute path or URL → used directly.
+ * 2. Explicit relative path (./... or ../...) → resolved relative to configDir.
+ * 3. Plugin-qualified path (e.g. "sctx-wardley-mapping/wardley_map.json" or "wardley-mapping/wardley_map.json"):
+ *    resolved against the matching loaded plugin's schemasDir.
+ * 4. Simple filename without directory (e.g. "wardley_map.json" or "strategy_general.json"):
+ *    - configDir/filename if it exists
+ *    - plugin.schemasDir/filename for any loaded plugin with schemasDir
+ *    - bundledSchemasDir/filename if it exists
+ *    - fallback: configDir/filename
+ */
+export function resolveSchemaPath(rawSchema, configDir, space, config) {
+    if (!rawSchema) {
+        throw new Error('No schema configured. Set "schema" in the space config or at the top level of the config file.');
+    }
+    if (isAbsolute(rawSchema) || isUrl(rawSchema)) {
+        return rawSchema;
+    }
+    if (rawSchema.startsWith('./') || rawSchema.startsWith('../')) {
+        return resolve(configDir, rawSchema);
+    }
+    if (rawSchema.includes('/') || rawSchema.includes('\\')) {
+        const normalizedSlash = rawSchema.replace(/\\/g, '/');
+        const slashIdx = normalizedSlash.indexOf('/');
+        const prefix = normalizedSlash.slice(0, slashIdx);
+        const subPath = normalizedSlash.slice(slashIdx + 1);
+        const pluginSchemasDir = resolvePluginSchemasDir(prefix, configDir);
+        if (pluginSchemasDir) {
+            const candidate = resolve(pluginSchemasDir, subPath);
+            if (existsSync(candidate)) {
+                return candidate;
+            }
+        }
+        // Check if relative to configDir exists
+        const localCandidate = resolve(configDir, rawSchema);
+        if (existsSync(localCandidate)) {
+            return localCandidate;
+        }
+        // If plugin schemas dir was found, return candidate under it
+        if (pluginSchemasDir) {
+            return resolve(pluginSchemasDir, subPath);
+        }
+        return localCandidate;
+    }
+    // Simple filename without directory:
+    // 1. configDir/filename
+    const localCandidate = resolve(configDir, rawSchema);
+    if (existsSync(localCandidate)) {
+        return localCandidate;
+    }
+    // 2. Plugin schemas from declared space / config plugins
+    if (space || config) {
+        const pluginSources = resolveSpacePluginSchemas(space, config ?? { spaces: [] }, configDir);
+        for (const source of pluginSources) {
+            const pluginCandidate = resolve(source.schemasDir, rawSchema);
+            if (existsSync(pluginCandidate)) {
+                return pluginCandidate;
+            }
+        }
+    }
+    // 3. Bundled schemas
+    const bundledCandidate = join(bundledSchemasDir, rawSchema);
+    if (existsSync(bundledCandidate)) {
+        return bundledCandidate;
+    }
+    return localCandidate;
+}
 /** Resolve schema path: CLI arg > space-level config > global config. Throws if none configured. */
-export function resolveSchema(config, space) {
+export function resolveSchema(config, space, options) {
     const schema = space?.schema ?? config.schema;
     if (!schema) {
         throw new Error('No schema configured. Set "schema" in the space config or at the top level of the config file.');
     }
+    const configDir = options?.configDir ?? space?.sourceDir;
+    if (configDir) {
+        return resolveSchemaPath(schema, configDir, space, config);
+    }
     return schema;
 }
-/** Update a string field on a space entry and persist config. */
-export function updateSpaceField(spaceName, field, value) {
+/** Update a string field on a space entry and persist config. When `plugin` is given, updates that field inside `space.plugins[plugin]` instead. */
+export function updateSpaceField(spaceName, field, value, plugin) {
     const sourcePath = _spaceSourceFiles.get(spaceName);
-    if (!sourcePath) {
+    if (!sourcePath)
         throw new Error(`Space "${spaceName}" not found in any config file`);
-    }
     const config = _loadConfig(sourcePath);
     const space = config.spaces?.find((s) => s.name === spaceName);
-    if (!space) {
+    if (!space)
         throw new Error(`Unknown space config: "${spaceName}". Check config.`);
+    if (plugin !== undefined) {
+        if (!space.plugins)
+            space.plugins = {};
+        const normalized = normalizePluginName(plugin);
+        const shortName = shortenPluginName(normalized);
+        const existingKey = Object.keys(space.plugins).find((k) => k === normalized || k === shortName) ?? normalized;
+        if (!space.plugins[existingKey])
+            space.plugins[existingKey] = {};
+        space.plugins[existingKey][field] = value;
+    }
+    else {
+        space[field] = value;
     }
-    space[field] = value;
     writeFileSync(sourcePath, `${JSON5.stringify(config, null, 2)}\n`);
 }

package/dist/filter/augment-nodes.d.ts

@@ -3,6 +3,8 @@ import type { SpaceNode } from '../types';
 export type EdgeMetadata = {
     _field: string;
     _source: 'hierarchy' | 'relationship';
+    /** Hierarchy name, present only for hierarchy edges. */
+    _hierarchy?: string;
     _selfRef: boolean;
 };
 /** A flat node representation augmented with ancestor and descendant traversal arrays. */
@@ -18,6 +20,6 @@ export type AugmentedFlatNode = Record<string, unknown> & {
  *
  * - ancestors: BFS from node via resolvedParents, nearest first, deduplicated by title.
  * - descendants: BFS via childrenIndex, nearest first, deduplicated by title.
- * - Each entry merges the parent/child node's fields with edge metadata (_field, _source, _selfRef).
+ * - Each entry merges the parent/child node's fields with edge metadata (_field, _source, _hierarchy, _selfRef).
  */
 export declare function augmentNode(node: SpaceNode, nodeIndex: ReadonlyMap<string, SpaceNode>, childrenIndex: ReadonlyMap<string, readonly SpaceNode[]>): AugmentedFlatNode;

package/dist/filter/augment-nodes.js

@@ -1,3 +1,12 @@
+/** Edge metadata for the resolvedParents entry connecting two nodes. */
+function edgeMetadata(ref) {
+    return {
+        _field: ref.field,
+        _source: ref.source,
+        ...(ref.hierarchy !== undefined ? { _hierarchy: ref.hierarchy } : {}),
+        _selfRef: ref.selfRef,
+    };
+}
 /** Flatten a SpaceNode's data fields for use in an augmented representation. */
 function flattenData(node) {
     return {
@@ -13,7 +22,7 @@ function flattenData(node) {
  *
  * - ancestors: BFS from node via resolvedParents, nearest first, deduplicated by title.
  * - descendants: BFS via childrenIndex, nearest first, deduplicated by title.
- * - Each entry merges the parent/child node's fields with edge metadata (_field, _source, _selfRef).
+ * - Each entry merges the parent/child node's fields with edge metadata (_field, _source, _hierarchy, _selfRef).
  */
 export function augmentNode(node, nodeIndex, childrenIndex) {
     const ancestors = buildAncestors(node, nodeIndex);
@@ -44,9 +53,7 @@ function buildAncestors(node, nodeIndex) {
         visited.add(title);
         result.push({
             ...flattenData(item.node),
-            _field: item.ref.field,
-            _source: item.ref.source,
-            _selfRef: item.ref.selfRef,
+            ...edgeMetadata(item.ref),
         });
         // Continue BFS upward
         for (const ref of item.node.resolvedParents) {
@@ -78,9 +85,7 @@ function buildDescendants(node, childrenIndex) {
         visited.add(title);
         result.push({
             ...flattenData(item.childNode),
-            _field: item.ref.field,
-            _source: item.ref.source,
-            _selfRef: item.ref.selfRef,
+            ...edgeMetadata(item.ref),
         });
         const grandchildren = childrenIndex.get(title) ?? [];
         for (const grandchild of grandchildren) {

package/dist/filter/filter-nodes.js

@@ -69,5 +69,5 @@ export async function filterNodes(expression, graph) {
     else {
         matchedNodes = matched;
     }
-    return buildSpaceGraph(matchedNodes, graph.levels);
+    return buildSpaceGraph(matchedNodes, graph.hierarchy);
 }

package/dist/index.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env bun
 import { createRequire } from 'node:module';
+import { format } from 'node:util';
 import { Command } from 'commander';
 import { diagram } from './commands/diagram';
 import { docs } from './commands/docs';
 import { dump } from './commands/dump';
+import { miroSyncCommand } from './commands/miro-sync';
 import { listPlugins } from './commands/plugins';
 import { render, renderList } from './commands/render';
 import { listSchemas, showSchema } from './commands/schemas';
@@ -12,29 +14,25 @@ import { listSpaces } from './commands/spaces';
 import { templateSync } from './commands/template-sync';
 import { validate, watchValidate } from './commands/validate';
 import { validateFileCommand } from './commands/validate-file';
-import { getSpaceConfigDir, loadConfig, resolveSchema, setConfigPath } from './config';
+import { loadConfig, setConfigPath } from './config';
 import { CLI_NAME } from './constants';
-import { miroSync } from './integrations/miro/sync';
-import { loadSchema } from './schema/schema';
+import { createSpaceContext, SpaceNotFoundError } from './space-context';
+// Once node:process is loaded (vfile, via unified, loads it), Bun's console.log drops piped output
+// past 64KB when the reader is slow. process.stdout.write delivers all of it before exit.
+console.log = (...args) => {
+    process.stdout.write(`${format(...args)}\n`);
+};
 export function buildSpaceContext(spaceName) {
-    const config = loadConfig();
-    const space = config.spaces.find((s) => s.name === spaceName);
-    if (!space) {
-        console.error(`Error: Unknown space "${spaceName}"`);
-        process.exit(1);
+    try {
+        return createSpaceContext(spaceName, loadConfig());
+    }
+    catch (err) {
+        if (err instanceof SpaceNotFoundError) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        throw err;
     }
-    const resolvedSchemaPath = resolveSchema(config, space);
-    const { schema, schemaRefRegistry, schemaValidator } = loadSchema(resolvedSchemaPath);
-    const configDir = getSpaceConfigDir(space.name);
-    return {
-        space,
-        config,
-        resolvedSchemaPath,
-        schema,
-        schemaRefRegistry,
-        schemaValidator,
-        configDir,
-    };
 }
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
@@ -53,8 +51,7 @@ program
     .argument('<path>', 'Path to the file to validate')
     .option('--json', 'Output results as JSON (machine-readable, for hooks)')
     .action(async (filePath, options) => {
-    const exitCode = await validateFileCommand(filePath, { json: options.json });
-    process.exit(exitCode);
+    process.exitCode = await validateFileCommand(filePath, { json: options.json });
 });
 program
     .command('validate')
@@ -68,8 +65,8 @@ program
         await watchValidate(context);
     }
     else {
-        const exitCode = await validate(context, { json: options.json });
-        process.exit(exitCode);
+        // exitCode rather than process.exit(): exiting straight away can cut off large piped output
+        process.exitCode = await validate(context, { json: options.json });
     }
 });
 program
@@ -77,19 +74,23 @@ program
     .description('Generate mermaid diagram from space')
     .argument('<space-name>', 'Space name')
     .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
+    .option('--hierarchy <name>', 'Hierarchy to render (default: the main hierarchy)')
     .option('-o, --output <path>', 'Output file path (default: stdout)')
-    .action((spaceName, options) => diagram(buildSpaceContext(spaceName), options));
+    .action(async (spaceName, options) => diagram(buildSpaceContext(spaceName), options));
 program
     .command('show')
     .description('Print space graph as a bullet list')
     .argument('<space-name>', 'Space name')
     .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
-    .action((spaceName, options) => show(buildSpaceContext(spaceName), options));
+    .option('--hierarchy <name>', 'Hierarchy to render (default: the main hierarchy)')
+    .action(async (spaceName, options) => show(buildSpaceContext(spaceName), options));
 program
     .command('dump')
     .description('Dump parsed space nodes as JSON')
     .argument('<space-name>', 'Space name')
-    .action((spaceName) => dump(buildSpaceContext(spaceName)));
+    .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
+    .option('--hierarchy <name>', 'Hierarchy used to evaluate --filter (default: the main hierarchy)')
+    .action(async (spaceName, options) => dump(buildSpaceContext(spaceName), options));
 program
     .command('miro-sync')
     .description('Sync space to a Miro board')
@@ -97,16 +98,16 @@ program
     .option('--new-frame <title>', 'Create a new frame on the board and sync into it')
     .option('--dry-run', 'Show what would change without touching Miro')
     .option('-v, --verbose', 'Detailed output')
-    .action((spaceName, options) => miroSync(buildSpaceContext(spaceName), options));
+    .action(async (spaceName, options) => miroSyncCommand(buildSpaceContext(spaceName), options));
 program
     .command('template-sync')
     .description('Sync schema examples to templates')
     .argument('<space-name>', 'Space name')
     .option('--create-missing', 'Create missing template files for schema types')
     .option('--dry-run', 'Preview changes without writing files')
-    .action((spaceName, options) => {
+    .action(async (spaceName, options) => {
     const context = buildSpaceContext(spaceName);
-    templateSync(context, options);
+    await templateSync(context, options);
 });
 program
     .command('plugins')
@@ -116,13 +117,14 @@ const spacesCmd = new Command('spaces').description('List configured spaces');
 spacesCmd
     .command('list', { isDefault: true })
     .description('List all configured spaces and their paths')
-    .action(listSpaces);
+    .option('--json', 'Output as JSON: config files, and each space with its path and schema')
+    .action((options) => listSpaces(options));
 program.addCommand(spacesCmd);
 const schemasCmd = new Command('schemas').alias('schema').description('List and inspect schemas');
 schemasCmd
     .command('list', { isDefault: true })
     .description('List available schemas')
-    .action(() => listSchemas());
+    .action(async () => await listSchemas());
 schemasCmd
     .command('show')
     .description('Show schema structure (or raw JSON with --raw, or Mermaid ERD with --mermaid-erd)')
@@ -130,7 +132,7 @@ schemasCmd
     .option('--space <name>', 'Resolve schema from space config')
     .option('--raw', 'Output raw JSON file content')
     .option('--mermaid-erd', 'Output Mermaid Entity Relationship Diagram')
-    .action((file, options) => showSchema(file, {
+    .action(async (file, options) => await showSchema(file, {
     space: options.space,
     raw: options.raw ?? false,
     mermaidErd: options.mermaidErd ?? false,
@@ -149,11 +151,25 @@ renderCmd
     const context = spaceName ? buildSpaceContext(spaceName) : undefined;
     await renderList(context);
 });
+function parseDataOptions(val, prev = {}) {
+    const eqIdx = val.indexOf('=');
+    if (eqIdx >= 0) {
+        prev[val.slice(0, eqIdx).trim()] = val.slice(eqIdx + 1).trim();
+    }
+    else {
+        prev[val.trim()] = 'true';
+    }
+    return prev;
+}
 renderCmd
     .argument('<space-name>', 'Space name')
-    .argument('<format>', 'Render format (e.g. markdown.bullets)')
+    .argument('<format>', 'Render format (e.g. markdown.bullets, markdown.directory)')
     .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
-    .option('-o, --output <path>', 'Output file path (default: stdout)')
+    .option('--hierarchy <name>', 'Hierarchy to render (default: the main hierarchy)')
+    .option('-o, --output <path>', 'Output file or directory path (default: stdout)')
+    .option('--out <path>', 'Output directory or file path')
+    .option('-f, --force', 'Overwrite existing files when writing to disk')
+    .option('-d, --data <key=value...>', 'Format-specific key=value options', parseDataOptions)
     .action(async (spaceName, format, options) => {
     await render(buildSpaceContext(spaceName), format, options);
 });

package/dist/load-space-graph.d.ts

@@ -0,0 +1,42 @@
+import type { Config } from './config';
+import { type SpaceGraph } from './space-graph';
+import type { ReadSpaceResult, SpaceContext } from './types';
+export interface AssembleSpaceGraphOptions {
+    /** Named view (resolved via space.views) or a raw filter DSL expression. */
+    filter?: string;
+    /** Name of the hierarchy to structure the graph by. Defaults to the schema's main hierarchy. */
+    hierarchy?: string;
+    /** Pre-loaded read result to assemble from, avoiding a re-read of the space. */
+    readResult?: ReadSpaceResult;
+}
+/**
+ * Assemble a SpaceGraph from a space context: read the space, drop nodes that
+ * fail schema validation, build the graph for the selected hierarchy (the main
+ * hierarchy by default), and apply an optional view/filter expression.
+ *
+ * Nodes that fail schema validation are silently excluded so the graph is
+ * well-formed enough to render and traverse. This is NOT a validation pass —
+ * schema-valid nodes may still have broken references, rule violations, or
+ * duplicates. Use validateSpace for a full validation report.
+ *
+ * Shared by the render pipeline and the public loadSpaceGraph API so their
+ * graph-assembly behaviour cannot drift.
+ */
+export declare function assembleSpaceGraph(context: SpaceContext, options?: AssembleSpaceGraphOptions): Promise<SpaceGraph>;
+export interface LoadSpaceGraphOptions extends AssembleSpaceGraphOptions {
+    /**
+     * Directory to anchor relative plugin paths against. Required when config is
+     * hand-assembled (has no source file); see {@link createSpaceContext}.
+     */
+    configDir?: string;
+}
+/**
+ * Load a named space and return its assembled, filtered SpaceGraph.
+ *
+ * Convenience entry point over createSpaceContext + assembleSpaceGraph: pass a
+ * space name, config, and optional filter. Pass options.readResult to reuse an
+ * already-loaded read (e.g. when also calling validateSpace) and skip re-reading.
+ * When you already hold a SpaceContext, call assembleSpaceGraph directly to avoid
+ * rebuilding (and recompiling the schema for) the context.
+ */
+export declare function loadSpaceGraph(spaceName: string, config: Config, options?: LoadSpaceGraphOptions): Promise<SpaceGraph>;

package/dist/load-space-graph.js

@@ -0,0 +1,53 @@
+import { filterNodes } from './filter/filter-nodes';
+import { readSpace } from './read/read-space';
+import { createSpaceContext } from './space-context';
+import { buildSpaceGraph } from './space-graph';
+/**
+ * Assemble a SpaceGraph from a space context: read the space, drop nodes that
+ * fail schema validation, build the graph for the selected hierarchy (the main
+ * hierarchy by default), and apply an optional view/filter expression.
+ *
+ * Nodes that fail schema validation are silently excluded so the graph is
+ * well-formed enough to render and traverse. This is NOT a validation pass —
+ * schema-valid nodes may still have broken references, rule violations, or
+ * duplicates. Use validateSpace for a full validation report.
+ *
+ * Shared by the render pipeline and the public loadSpaceGraph API so their
+ * graph-assembly behaviour cannot drift.
+ */
+export async function assembleSpaceGraph(context, options = {}) {
+    const { nodes: allNodes } = options.readResult ?? (await readSpace(context));
+    const { schemaValidator } = context;
+    const validNodes = allNodes.filter((node) => schemaValidator(node.schemaData));
+    let graph = buildSpaceGraph(validNodes, selectHierarchy(context.schema.metadata, options.hierarchy));
+    if (options.filter) {
+        const expression = context.space.views?.[options.filter]?.expression ?? options.filter;
+        graph = await filterNodes(expression, graph);
+    }
+    return graph;
+}
+/** Resolve a hierarchy by name, or the main hierarchy when no name is given. */
+function selectHierarchy(metadata, name) {
+    if (name === undefined)
+        return metadata.hierarchy;
+    const hierarchies = metadata.hierarchies ?? [];
+    const hierarchy = hierarchies.find((h) => h.name === name);
+    if (!hierarchy) {
+        const available = hierarchies.map((h) => h.name).join(', ');
+        throw new Error(`Unknown hierarchy: "${name}".${available ? ` Available: ${available}` : ' The schema defines no hierarchies.'}`);
+    }
+    return hierarchy;
+}
+/**
+ * Load a named space and return its assembled, filtered SpaceGraph.
+ *
+ * Convenience entry point over createSpaceContext + assembleSpaceGraph: pass a
+ * space name, config, and optional filter. Pass options.readResult to reuse an
+ * already-loaded read (e.g. when also calling validateSpace) and skip re-reading.
+ * When you already hold a SpaceContext, call assembleSpaceGraph directly to avoid
+ * rebuilding (and recompiling the schema for) the context.
+ */
+export async function loadSpaceGraph(spaceName, config, options = {}) {
+    const context = createSpaceContext(spaceName, config, { configDir: options.configDir });
+    return assembleSpaceGraph(context, options);
+}

package/dist/plugins/index.js

@@ -1,3 +1,5 @@
 import { markdownPlugin } from './markdown';
+import { mermaidPlugin } from './mermaid';
+import { miroPlugin } from './miro';
 /** All built-in plugins, in default load order. */
-export const builtinPlugins = [markdownPlugin];
+export const builtinPlugins = [markdownPlugin, mermaidPlugin, miroPlugin];

package/dist/plugins/loader.js

@@ -1,9 +1,9 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import Ajv, {} from 'ajv';
+import Ajv2020 from 'ajv/dist/2020';
 import { getConfigSourceFiles } from '../config';
 import { builtinPlugins } from '.';
-import { CONFIG_PLUGINS_DIR, normalizePluginName, PLUGIN_PREFIX } from './util';
+import { CONFIG_PLUGINS_DIR, normalizePluginName, PLUGIN_PREFIX, shortenPluginName, } from './util';
 /**
  * Walk a plugin's configSchema and resolve any string fields annotated with
  * format:'path' relative to configDir.
@@ -71,7 +71,7 @@ export async function discoverPlugins() {
  */
 export async function loadPlugins(pluginMap, configDir) {
     const builtinsByName = new Map(builtinPlugins.map((p) => [p.name, p]));
-    const ajv = new Ajv();
+    const ajv = new Ajv2020();
     ajv.addFormat('path', (value) => value.length > 0 && !value.includes('\0'));
     const loaded = [];
     // External plugins: entries in the map that are not built-in names
@@ -92,7 +92,7 @@ export async function loadPlugins(pluginMap, configDir) {
     }
     // Built-in plugins: always loaded, config taken from map if declared (with or without prefix)
     for (const builtin of builtinPlugins) {
-        const rawConfig = pluginMap[builtin.name] ?? pluginMap[builtin.name.slice(PLUGIN_PREFIX.length)] ?? {};
+        const rawConfig = pluginMap[builtin.name] ?? pluginMap[shortenPluginName(builtin.name)] ?? {};
         const pluginConfig = resolveConfigPaths(builtin.configSchema, rawConfig, configDir);
         const validate = ajv.compile(builtin.configSchema);
         if (!validate(pluginConfig)) {

package/dist/plugins/markdown/extract-content-links.d.ts

@@ -0,0 +1,23 @@
+import type { Node } from 'mdast';
+import type { ContentLink, SchemaMetadata } from '../../types';
+/**
+ * Recursively walk an mdast subtree and collect all links.
+ * Handles standard markdown link/image nodes and scans text nodes for wikilinks.
+ */
+export declare function extractLinksFromAstNode(node: Node): ContentLink[];
+/**
+ * Extract all links from a raw markdown body string.
+ * Parses the full document and collects links from every node in the tree.
+ */
+export declare function extractLinksFromBody(body: string): ContentLink[];
+/**
+ * Build the set of field names that serve as graph edges (hierarchy + relationship fields).
+ * Used to exclude edge fields from frontmatter link extraction.
+ */
+export declare function getEdgeFieldNames(metadata: SchemaMetadata): Set<string>;
+/**
+ * Extract links from frontmatter data fields, excluding known graph edge fields.
+ * Parses each string value as markdown (via mdast) to keep link extraction consistent
+ * with body content parsing — handles wikilinks, markdown links, images, and bare URLs.
+ */
+export declare function extractLinksFromFrontmatter(data: Record<string, unknown>, edgeFields: Set<string>): ContentLink[];