structured-context 0.9.0

package/dist/filter/augment-nodes.js

@@ -0,0 +1,95 @@
+/** Flatten a SpaceNode's data fields for use in an augmented representation. */
+function flattenData(node) {
+    return {
+        ...node.schemaData,
+        label: node.label,
+        title: node.title,
+        resolvedType: node.resolvedType,
+    };
+}
+/**
+ * Build the augmented flat representation of a node, including pre-computed
+ * ancestors[] and descendants[] arrays with edge metadata.
+ *
+ * - 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).
+ */
+export function augmentNode(node, nodeIndex, childrenIndex) {
+    const ancestors = buildAncestors(node, nodeIndex);
+    const descendants = buildDescendants(node, childrenIndex);
+    return {
+        ...flattenData(node),
+        resolvedType: node.resolvedType,
+        resolvedParentTitles: node.resolvedParents.map((r) => r.title),
+        ancestors,
+        descendants,
+    };
+}
+function buildAncestors(node, nodeIndex) {
+    const visited = new Set();
+    const result = [];
+    // BFS queue holds: { parentRef that led to this node, the node itself }
+    const queue = [];
+    for (const ref of node.resolvedParents) {
+        const parentNode = nodeIndex.get(ref.title);
+        if (parentNode)
+            queue.push({ ref, node: parentNode });
+    }
+    while (queue.length > 0) {
+        const item = queue.shift();
+        const title = item.node.title;
+        if (visited.has(title))
+            continue;
+        visited.add(title);
+        result.push({
+            ...flattenData(item.node),
+            _field: item.ref.field,
+            _source: item.ref.source,
+            _selfRef: item.ref.selfRef,
+        });
+        // Continue BFS upward
+        for (const ref of item.node.resolvedParents) {
+            const parentNode = nodeIndex.get(ref.title);
+            if (parentNode && !visited.has(ref.title)) {
+                queue.push({ ref, node: parentNode });
+            }
+        }
+    }
+    return result;
+}
+function buildDescendants(node, childrenIndex) {
+    const nodeTitle = node.title;
+    const visited = new Set();
+    const result = [];
+    // BFS queue holds: child node + the resolvedParents entry on that child that points to its parent
+    const queue = [];
+    const directChildren = childrenIndex.get(nodeTitle) ?? [];
+    for (const child of directChildren) {
+        const ref = child.resolvedParents.find((r) => r.title === nodeTitle);
+        if (ref)
+            queue.push({ childNode: child, ref });
+    }
+    while (queue.length > 0) {
+        const item = queue.shift();
+        const title = item.childNode.title;
+        if (visited.has(title))
+            continue;
+        visited.add(title);
+        result.push({
+            ...flattenData(item.childNode),
+            _field: item.ref.field,
+            _source: item.ref.source,
+            _selfRef: item.ref.selfRef,
+        });
+        const grandchildren = childrenIndex.get(title) ?? [];
+        for (const grandchild of grandchildren) {
+            if (!visited.has(grandchild.title)) {
+                const ref = grandchild.resolvedParents.find((r) => r.title === title);
+                if (ref)
+                    queue.push({ childNode: grandchild, ref });
+            }
+        }
+    }
+    return result;
+}

package/dist/filter/expand-include.d.ts

@@ -0,0 +1,62 @@
+import type { SpaceNode } from '../types';
+import type { AugmentedFlatNode } from './augment-nodes';
+export type AncestorsDirective = {
+    kind: 'ancestors';
+    /** Filter by resolved type of the ancestor node. Absent means include all. */
+    typeFilter?: string;
+};
+export type DescendantsDirective = {
+    kind: 'descendants';
+    /** Filter by resolved type of the descendant node. Absent means include all. */
+    typeFilter?: string;
+};
+export type SiblingsDirective = {
+    kind: 'siblings';
+};
+/**
+ * Relationship directive covers all non-hierarchy edges.
+ * Progressive specification mirrors the `parent_type:field:child_type` naming convention.
+ * Any combination of filters may be present; absent fields are treated as wildcards.
+ */
+export type RelationshipsDirective = {
+    kind: 'relationships';
+    /** Filter by the child side's resolved type. */
+    childType?: string;
+    /** Filter by the parent side's resolved type. */
+    parentType?: string;
+    /** Filter by the edge field name. */
+    field?: string;
+};
+export type IncludeDirective = AncestorsDirective | DescendantsDirective | SiblingsDirective | RelationshipsDirective;
+/**
+ * Parse a SELECT include spec string into a list of directives.
+ *
+ * Grammar:
+ *   spec       = directive (',' directive)*
+ *   directive  = 'ancestors' ('(' type ')')?
+ *              | 'descendants' ('(' type ')')?
+ *              | 'siblings'
+ *              | 'relationships' ('(' relSpec ')')?
+ *   type       = identifier
+ *   relSpec    = childType
+ *              | parentType ':' childType
+ *              | parentType ':' field ':' childType
+ *
+ * Keywords are case-insensitive. Identifiers match \w+.
+ * Range syntax (type..type) is reserved for a future release.
+ */
+export declare function parseIncludeSpec(spec: string): IncludeDirective[];
+/**
+ * Expand the matched node set by adding nodes specified by the include directives.
+ *
+ * Processes each matched node and each directive, collecting additional nodes to
+ * include. The result is `matched ∪ expanded`, preserving original order with new
+ * nodes appended in the order they are discovered.
+ *
+ * @param matchedNodes - Nodes already matched by the WHERE clause (or all nodes for SELECT-only)
+ * @param directives - Parsed include directives from the SELECT clause
+ * @param nodeIndex - Title → SpaceNode lookup
+ * @param childrenIndex - Title → direct children (all edges)
+ * @param augmented - Title → AugmentedFlatNode with pre-computed ancestors/descendants
+ */
+export declare function expandInclude(matchedNodes: SpaceNode[], directives: IncludeDirective[], nodeIndex: ReadonlyMap<string, SpaceNode>, childrenIndex: ReadonlyMap<string, readonly SpaceNode[]>, augmented: Map<string, AugmentedFlatNode>): SpaceNode[];

package/dist/filter/expand-include.js

@@ -0,0 +1,181 @@
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse a SELECT include spec string into a list of directives.
+ *
+ * Grammar:
+ *   spec       = directive (',' directive)*
+ *   directive  = 'ancestors' ('(' type ')')?
+ *              | 'descendants' ('(' type ')')?
+ *              | 'siblings'
+ *              | 'relationships' ('(' relSpec ')')?
+ *   type       = identifier
+ *   relSpec    = childType
+ *              | parentType ':' childType
+ *              | parentType ':' field ':' childType
+ *
+ * Keywords are case-insensitive. Identifiers match \w+.
+ * Range syntax (type..type) is reserved for a future release.
+ */
+export function parseIncludeSpec(spec) {
+    const items = spec
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (items.length === 0)
+        throw new Error('SELECT spec must not be empty');
+    return items.map(parseDirective);
+}
+function parseDirective(item) {
+    const match = item.match(/^(\w+)(?:\(([^)]*)\))?$/i);
+    if (!match)
+        throw new Error(`Invalid include directive: "${item}"`);
+    const name = match[1].toLowerCase();
+    const arg = match[2]?.trim();
+    if (name === 'siblings') {
+        if (arg !== undefined && arg !== '')
+            throw new Error('siblings() does not accept arguments');
+        return { kind: 'siblings' };
+    }
+    if (name === 'ancestors' || name === 'descendants') {
+        if (!arg)
+            return { kind: name };
+        if (arg.includes('..')) {
+            throw new Error(`Range syntax "${arg}" in SELECT is not yet supported. Use a plain type name for now.`);
+        }
+        if (!/^\w+$/.test(arg))
+            throw new Error(`Invalid type name in ${name}(): "${arg}"`);
+        return { kind: name, typeFilter: arg };
+    }
+    if (name === 'relationships') {
+        if (!arg)
+            return { kind: 'relationships' };
+        const parts = arg.split(':').map((s) => s.trim());
+        if (parts.some((p) => !/^\w+$/.test(p))) {
+            throw new Error(`Invalid relationship spec: "${arg}"`);
+        }
+        if (parts.length === 1)
+            return { kind: 'relationships', childType: parts[0] };
+        if (parts.length === 2)
+            return { kind: 'relationships', parentType: parts[0], childType: parts[1] };
+        if (parts.length === 3) {
+            return { kind: 'relationships', parentType: parts[0], field: parts[1], childType: parts[2] };
+        }
+        throw new Error(`Relationship spec "${arg}" has too many parts (max 3: parent:field:child)`);
+    }
+    throw new Error(`Unknown include directive "${item}". Expected: ancestors, descendants, siblings, relationships`);
+}
+// ---------------------------------------------------------------------------
+// Expander
+// ---------------------------------------------------------------------------
+/**
+ * Expand the matched node set by adding nodes specified by the include directives.
+ *
+ * Processes each matched node and each directive, collecting additional nodes to
+ * include. The result is `matched ∪ expanded`, preserving original order with new
+ * nodes appended in the order they are discovered.
+ *
+ * @param matchedNodes - Nodes already matched by the WHERE clause (or all nodes for SELECT-only)
+ * @param directives - Parsed include directives from the SELECT clause
+ * @param nodeIndex - Title → SpaceNode lookup
+ * @param childrenIndex - Title → direct children (all edges)
+ * @param augmented - Title → AugmentedFlatNode with pre-computed ancestors/descendants
+ */
+export function expandInclude(matchedNodes, directives, nodeIndex, childrenIndex, augmented) {
+    if (directives.length === 0)
+        return matchedNodes;
+    const seen = new Set(matchedNodes.map((n) => n.title));
+    const result = [...matchedNodes];
+    function addByTitle(title) {
+        if (seen.has(title))
+            return;
+        const node = nodeIndex.get(title);
+        if (node) {
+            seen.add(title);
+            result.push(node);
+        }
+    }
+    for (const node of matchedNodes) {
+        const title = node.title;
+        const aug = augmented.get(title);
+        if (!aug)
+            continue;
+        for (const directive of directives) {
+            applyDirective(node, aug, directive, childrenIndex, addByTitle);
+        }
+    }
+    return result;
+}
+function applyDirective(node, aug, directive, childrenIndex, addByTitle) {
+    switch (directive.kind) {
+        case 'ancestors': {
+            for (const a of aug.ancestors) {
+                if (!directive.typeFilter || a.resolvedType === directive.typeFilter) {
+                    addByTitle(a.title);
+                }
+            }
+            break;
+        }
+        case 'descendants': {
+            for (const d of aug.descendants) {
+                if (!directive.typeFilter || d.resolvedType === directive.typeFilter) {
+                    addByTitle(d.title);
+                }
+            }
+            break;
+        }
+        case 'siblings': {
+            // Nodes that share at least one parent with the matched node (any edge type)
+            for (const parentRef of node.resolvedParents) {
+                const siblings = childrenIndex.get(parentRef.title) ?? [];
+                for (const sibling of siblings) {
+                    const siblingTitle = sibling.title;
+                    if (siblingTitle !== node.title) {
+                        addByTitle(siblingTitle);
+                    }
+                }
+            }
+            break;
+        }
+        case 'relationships': {
+            // Relationship-sourced ancestors (matched node is the child side)
+            for (const a of aug.ancestors) {
+                if (a._source === 'relationship' && matchesRelSpec(node, a, directive, true)) {
+                    addByTitle(a.title);
+                }
+            }
+            // Relationship-sourced descendants (matched node is the parent side)
+            for (const d of aug.descendants) {
+                if (d._source === 'relationship' && matchesRelSpec(node, d, directive, false)) {
+                    addByTitle(d.title);
+                }
+            }
+            break;
+        }
+    }
+}
+/**
+ * Check whether a relationship edge entry matches the directive's filter spec.
+ *
+ * @param matchedNode - The node from the matched set
+ * @param entry - An ancestor or descendant entry with edge metadata
+ * @param directive - The relationships directive with optional type/field filters
+ * @param entryIsParent - true if entry is the parent side (ancestor), false if child side (descendant)
+ */
+function matchesRelSpec(matchedNode, entry, directive, entryIsParent) {
+    if (!directive.childType && !directive.parentType && !directive.field)
+        return true;
+    const entryType = entry.resolvedType;
+    const matchedType = matchedNode.resolvedType;
+    // When entry is the parent, matched node is the child, and vice versa
+    const parentType = entryIsParent ? entryType : matchedType;
+    const childType = entryIsParent ? matchedType : entryType;
+    if (directive.parentType && parentType !== directive.parentType)
+        return false;
+    if (directive.childType && childType !== directive.childType)
+        return false;
+    if (directive.field && entry._field !== directive.field)
+        return false;
+    return true;
+}

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

@@ -0,0 +1,21 @@
+import { type SpaceGraph } from '../space-graph';
+/**
+ * Filter a SpaceGraph using a filter expression, returning a new SpaceGraph.
+ *
+ * The expression follows the SELECT...WHERE DSL:
+ *   WHERE {jsonata}                — return nodes where the JSONata predicate is truthy
+ *   SELECT {spec} WHERE {jsonata}  — filter + expand result via include spec
+ *   SELECT {spec}                  — expand from all nodes via include spec
+ *   {jsonata}                      — bare JSONata treated as WHERE predicate
+ *
+ * Each node's WHERE predicate is evaluated against an augmented context that includes
+ * pre-computed ancestors[] and descendants[] arrays with edge metadata.
+ *
+ * The SELECT spec may contain: ancestors[(type)], descendants[(type)], siblings,
+ * relationships[(childType | parentType:childType | parentType:field:childType)]
+ *
+ * @param expression - Filter DSL expression or view expression string
+ * @param graph - The full space graph
+ * @returns A new SpaceGraph containing only the filtered+expanded nodes
+ */
+export declare function filterNodes(expression: string, graph: SpaceGraph): Promise<SpaceGraph>;

package/dist/filter/filter-nodes.js

@@ -0,0 +1,73 @@
+import jsonata from 'jsonata';
+import { buildSpaceGraph } from '../space-graph';
+import { augmentNode } from './augment-nodes';
+import { expandInclude, parseIncludeSpec } from './expand-include';
+import { parseFilterExpression } from './parse-expression';
+const expressionCache = new Map();
+/**
+ * Filter a SpaceGraph using a filter expression, returning a new SpaceGraph.
+ *
+ * The expression follows the SELECT...WHERE DSL:
+ *   WHERE {jsonata}                — return nodes where the JSONata predicate is truthy
+ *   SELECT {spec} WHERE {jsonata}  — filter + expand result via include spec
+ *   SELECT {spec}                  — expand from all nodes via include spec
+ *   {jsonata}                      — bare JSONata treated as WHERE predicate
+ *
+ * Each node's WHERE predicate is evaluated against an augmented context that includes
+ * pre-computed ancestors[] and descendants[] arrays with edge metadata.
+ *
+ * The SELECT spec may contain: ancestors[(type)], descendants[(type)], siblings,
+ * relationships[(childType | parentType:childType | parentType:field:childType)]
+ *
+ * @param expression - Filter DSL expression or view expression string
+ * @param graph - The full space graph
+ * @returns A new SpaceGraph containing only the filtered+expanded nodes
+ */
+export async function filterNodes(expression, graph) {
+    const { where, include } = parseFilterExpression(expression);
+    const nodeIndex = graph.nodes;
+    const childrenIndex = graph.children;
+    // Pre-augment all nodes once (ancestors/descendants needed for WHERE predicates and SELECT expansion)
+    const augmented = new Map();
+    for (const node of nodeIndex.values()) {
+        augmented.set(node.title, augmentNode(node, nodeIndex, childrenIndex));
+    }
+    // Step 1: apply WHERE clause to get the matched set
+    let matched;
+    if (where === undefined) {
+        // SELECT-only: start from all nodes
+        matched = [...nodeIndex.values()];
+    }
+    else {
+        const allAugmented = Array.from(augmented.values());
+        // Compile and cache the JSONata expression
+        let expr = expressionCache.get(where);
+        if (!expr) {
+            expr = jsonata(where);
+            expressionCache.set(where, expr);
+        }
+        matched = [];
+        for (const node of nodeIndex.values()) {
+            const current = augmented.get(node.title);
+            if (!current)
+                continue;
+            // Spread current node fields at root level so bare field names work in expressions
+            // (e.g. `resolvedType='solution'` rather than `current.resolvedType='solution'`).
+            // Also expose `ancestors` and `descendants` directly, and `nodes` for cross-node access.
+            const input = { ...current, nodes: allAugmented };
+            const result = await expr.evaluate(input);
+            if (result)
+                matched.push(node);
+        }
+    }
+    // Step 2: apply SELECT clause to expand the result set
+    let matchedNodes;
+    if (include !== undefined) {
+        const directives = parseIncludeSpec(include);
+        matchedNodes = expandInclude(matched, directives, nodeIndex, childrenIndex, augmented);
+    }
+    else {
+        matchedNodes = matched;
+    }
+    return buildSpaceGraph(matchedNodes, graph.levels);
+}

package/dist/filter/parse-expression.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Parser for the filter expression DSL.
+ *
+ * Grammar (keywords are case-insensitive):
+ *   WHERE {jsonata}                    — filter predicate only
+ *   SELECT {spec} WHERE {jsonata}      — include spec + filter predicate
+ *   SELECT {spec}                      — include spec only (Phase 2: expansion from all nodes)
+ *   {jsonata}                          — bare JSONata treated as WHERE predicate (convenience)
+ */
+export type ParsedFilterExpression = {
+    /** JSONata predicate evaluated per node. Absent means match all. */
+    where?: string;
+    /** Include spec for result expansion (Phase 1: stored but not evaluated). */
+    include?: string;
+};
+/**
+ * Parse a filter expression string into its WHERE and SELECT parts.
+ * Throws a descriptive error on malformed input.
+ */
+export declare function parseFilterExpression(expr: string): ParsedFilterExpression;

package/dist/filter/parse-expression.js

@@ -0,0 +1,60 @@
+/**
+ * Parser for the filter expression DSL.
+ *
+ * Grammar (keywords are case-insensitive):
+ *   WHERE {jsonata}                    — filter predicate only
+ *   SELECT {spec} WHERE {jsonata}      — include spec + filter predicate
+ *   SELECT {spec}                      — include spec only (Phase 2: expansion from all nodes)
+ *   {jsonata}                          — bare JSONata treated as WHERE predicate (convenience)
+ */
+/**
+ * Parse a filter expression string into its WHERE and SELECT parts.
+ * Throws a descriptive error on malformed input.
+ */
+export function parseFilterExpression(expr) {
+    const trimmed = expr.trim();
+    if (!trimmed) {
+        throw new Error('Filter expression must not be empty');
+    }
+    // Case-insensitive keyword detection using regex
+    // SELECT ... WHERE ... (both present)
+    const selectWhereMatch = trimmed.match(/^SELECT\s+([\s\S]+?)\s+WHERE\s+([\s\S]+)$/i);
+    if (selectWhereMatch) {
+        const include = selectWhereMatch[1].trim();
+        const where = selectWhereMatch[2].trim();
+        if (!include)
+            throw new Error('SELECT clause must not be empty');
+        if (!where)
+            throw new Error('WHERE clause must not be empty');
+        return { include, where };
+    }
+    // SELECT ... (no WHERE)
+    const selectOnlyMatch = trimmed.match(/^SELECT\s+([\s\S]+)$/i);
+    if (selectOnlyMatch) {
+        const include = selectOnlyMatch[1].trim();
+        if (!include)
+            throw new Error('SELECT clause must not be empty');
+        // Detect SELECT {spec} WHERE (trailing WHERE with no content)
+        if (/\sWHERE\s*$/i.test(include)) {
+            throw new Error('WHERE clause must not be empty');
+        }
+        return { include };
+    }
+    // WHERE ... (no SELECT)
+    const whereOnlyMatch = trimmed.match(/^WHERE\s+([\s\S]+)$/i);
+    if (whereOnlyMatch) {
+        const where = whereOnlyMatch[1].trim();
+        if (!where)
+            throw new Error('WHERE clause must not be empty');
+        return { where };
+    }
+    // Detect a keyword used without any content (e.g. just "WHERE" or "SELECT")
+    if (/^WHERE\s*$/i.test(trimmed)) {
+        throw new Error('WHERE clause must not be empty');
+    }
+    if (/^SELECT\s*$/i.test(trimmed)) {
+        throw new Error('SELECT clause must not be empty');
+    }
+    // Bare JSONata — treat as WHERE predicate
+    return { where: trimmed };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+import type { SpaceContext } from './types';
+export declare function buildSpaceContext(spaceName: string): SpaceContext;

package/dist/index.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env bun
+import { createRequire } from 'node:module';
+import { Command } from 'commander';
+import { diagram } from './commands/diagram';
+import { docs } from './commands/docs';
+import { dump } from './commands/dump';
+import { listPlugins } from './commands/plugins';
+import { render, renderList } from './commands/render';
+import { listSchemas, showSchema } from './commands/schemas';
+import { show } from './commands/show';
+import { listSpaces } from './commands/spaces';
+import { templateSync } from './commands/template-sync';
+import { validate, watchValidate } from './commands/validate';
+import { validateFile } from './commands/validate-file';
+import { getSpaceConfigDir, loadConfig, resolveSchema, setConfigPath } from './config';
+import { CLI_NAME } from './constants';
+import { miroSync } from './integrations/miro/sync';
+import { loadSchema } from './schema/schema';
+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);
+    }
+    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');
+const program = new Command();
+program
+    .name(CLI_NAME)
+    .description('Structured context validation and diagram generation tool')
+    .version(packageJson.version)
+    .option('--config <path>', 'Path to config file (overrides default config.json locations)');
+program.hook('preAction', () => {
+    setConfigPath(program.opts().config);
+});
+program
+    .command('validate-file')
+    .description('Validate a single file within its space')
+    .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 validateFile(filePath, { json: options.json });
+    process.exit(exitCode);
+});
+program
+    .command('validate')
+    .description('Validate space against JSON schema')
+    .argument('<space-name>', 'Space name')
+    .option('-w, --watch', 'Watch for changes and re-run validation')
+    .option('--json', 'Output results as JSON')
+    .action(async (spaceName, options) => {
+    const context = buildSpaceContext(spaceName);
+    if (options.watch) {
+        await watchValidate(context);
+    }
+    else {
+        const exitCode = await validate(context, { json: options.json });
+        process.exit(exitCode);
+    }
+});
+program
+    .command('diagram')
+    .description('Generate mermaid diagram from space')
+    .argument('<space-name>', 'Space name')
+    .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
+    .option('-o, --output <path>', 'Output file path (default: stdout)')
+    .action((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));
+program
+    .command('dump')
+    .description('Dump parsed space nodes as JSON')
+    .argument('<space-name>', 'Space name')
+    .action((spaceName) => dump(buildSpaceContext(spaceName)));
+program
+    .command('miro-sync')
+    .description('Sync space to a Miro board')
+    .argument('<space-name>', 'Space name (must have miroBoardId in config)')
+    .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));
+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) => {
+    const context = buildSpaceContext(spaceName);
+    templateSync(context, options);
+});
+program
+    .command('plugins')
+    .description('List available plugins')
+    .action(async () => listPlugins());
+const spacesCmd = new Command('spaces').description('List configured spaces');
+spacesCmd
+    .command('list', { isDefault: true })
+    .description('List all configured spaces and their paths')
+    .action(listSpaces);
+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());
+schemasCmd
+    .command('show')
+    .description('Show schema structure (or raw JSON with --raw, or Mermaid ERD with --mermaid-erd)')
+    .argument('[file]', 'Schema filename or path (omit to use --space)')
+    .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, {
+    space: options.space,
+    raw: options.raw ?? false,
+    mermaidErd: options.mermaidErd ?? false,
+}));
+program.addCommand(schemasCmd);
+program
+    .command('docs [topic]')
+    .description('Show documentation (no arg: README; topics: concepts, config, schema, rules)')
+    .action((topic) => docs(topic));
+const renderCmd = new Command('render').description('Render a space in a given format');
+renderCmd
+    .command('list', { isDefault: false })
+    .description('List available render formats')
+    .argument('[space-name]', 'Space name (optional, to show space-specific formats)')
+    .action(async (spaceName) => {
+    const context = spaceName ? buildSpaceContext(spaceName) : undefined;
+    await renderList(context);
+});
+renderCmd
+    .argument('<space-name>', 'Space name')
+    .argument('<format>', 'Render format (e.g. markdown.bullets)')
+    .option('--filter <filter>', 'Filter view name (from config) or inline filter expression')
+    .option('-o, --output <path>', 'Output file path (default: stdout)')
+    .action(async (spaceName, format, options) => {
+    await render(buildSpaceContext(spaceName), format, options);
+});
+program.addCommand(renderCmd);
+program.parse();