@atolis-hq/corum 0.1.0

package/dist/src/loader/index.js

@@ -0,0 +1,108 @@
+import { FileGraphSource } from '../source/file-source.js';
+import { SourceError } from '../source/index.js';
+import { LoadError, QueryError } from '../schema/index.js';
+import { computeDiff, computeOverlay } from '../graph/overlay.js';
+import { loadClusters } from './cluster-loader.js';
+import { loadEdges } from './edge-loader.js';
+import { loadPacks } from './pack-loader.js';
+export async function loadGraph(options) {
+    const { strict = true } = options;
+    const diagnostics = [];
+    const source = options.source ?? new FileGraphSource({
+        graphDir: options.graphPath,
+        packsPath: options.packsPath,
+    });
+    const defaultRef = await source.defaultBranch();
+    const ref = options.ref ?? defaultRef;
+    const packContent = await source.loadPackContent(defaultRef);
+    const templates = loadPacks(packContent, diagnostics);
+    const graphContent = await source.loadGraphContent(ref);
+    const clusterResult = loadClusters(graphContent, templates, diagnostics);
+    const edgeResult = loadEdges(graphContent, clusterResult.nodes, diagnostics);
+    const edgesByFrom = cloneEdgeMap(clusterResult.edgesByFrom);
+    const edgesByTo = cloneEdgeMap(clusterResult.edgesByTo);
+    mergeEdgeMaps(edgesByFrom, edgeResult.edgesByFrom);
+    mergeEdgeMaps(edgesByTo, edgeResult.edgesByTo);
+    const graph = {
+        nodesById: clusterResult.nodes,
+        edgesByFrom,
+        edgesByTo,
+        templates,
+        diagnostics,
+        sourceContent: graphContent,
+    };
+    if (strict && diagnostics.some(d => d.severity === 'error')) {
+        throw new LoadError(diagnostics);
+    }
+    return graph;
+}
+export async function loadMultiGraph(options) {
+    const { source, strict = true } = options;
+    const defaultRef = await source.defaultBranch();
+    let defaultBranch;
+    try {
+        defaultBranch = {
+            ref: defaultRef,
+            isDefault: true,
+            graph: await loadGraph({ source, ref: defaultRef, strict }),
+        };
+    }
+    catch (err) {
+        throw new SourceError(`failed to load default branch '${defaultRef}'`, err);
+    }
+    const requestedBranches = options.branches ?? await source.listBranches();
+    const nonDefaultRefs = requestedBranches.filter(ref => ref !== defaultRef);
+    const settledBranches = await Promise.allSettled(nonDefaultRefs.map(async (ref) => ({
+        ref,
+        isDefault: false,
+        graph: await loadGraph({ source, ref, strict }),
+    })));
+    const branches = [defaultBranch];
+    const branchResults = [{ ref: defaultRef, status: 'loaded' }];
+    for (let index = 0; index < settledBranches.length; index++) {
+        const result = settledBranches[index];
+        const ref = nonDefaultRefs[index];
+        if (result.status === 'fulfilled') {
+            branches.push(result.value);
+            branchResults.push({ ref, status: 'loaded' });
+        }
+        else {
+            const diagnostics = result.reason instanceof LoadError ? result.reason.diagnostics : undefined;
+            branchResults.push({
+                ref,
+                status: 'failed',
+                error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+                diagnostics,
+            });
+        }
+    }
+    const overlayCache = new Map();
+    return {
+        default: defaultBranch,
+        branches,
+        branchResults,
+        overlay(viewingRef) {
+            let overlay = overlayCache.get(viewingRef);
+            if (!overlay) {
+                overlay = computeOverlay(viewingRef, defaultBranch, branches);
+                overlayCache.set(viewingRef, overlay);
+            }
+            return overlay;
+        },
+        diff(branchRef) {
+            const branch = branches.find(item => item.ref === branchRef);
+            if (!branch)
+                throw new QueryError(`branch '${branchRef}' not found or failed to load`);
+            return computeDiff(branch, defaultBranch);
+        },
+    };
+}
+function cloneEdgeMap(source) {
+    return new Map([...source.entries()].map(([key, edges]) => [key, [...edges]]));
+}
+function mergeEdgeMaps(target, source) {
+    for (const [key, edges] of source) {
+        const existing = target.get(key) ?? [];
+        target.set(key, [...existing, ...edges]);
+    }
+}

package/dist/src/loader/pack-loader.js

@@ -0,0 +1,99 @@
+import { parse as parseYaml } from 'yaml';
+import { listYamlKeys, readYaml } from '../source/content-utils.js';
+function topoSortTemplates(templates) {
+    const sorted = [];
+    const visited = new Set();
+    function visit(name) {
+        if (visited.has(name))
+            return;
+        visited.add(name);
+        const t = templates.get(name);
+        if (!t)
+            return;
+        if (t.extends)
+            visit(t.extends);
+        sorted.push(t);
+    }
+    for (const name of templates.keys())
+        visit(name);
+    return sorted;
+}
+const RESERVED_TEMPLATE_KEYS = new Set([
+    'name', 'info', 'extends', 'properties', 'edge-types', 'ui',
+]);
+export function getOwnedSections(template) {
+    const result = {};
+    for (const [key, value] of Object.entries(template)) {
+        if (!RESERVED_TEMPLATE_KEYS.has(key) &&
+            typeof value === 'object' &&
+            value !== null &&
+            'item-template' in value &&
+            typeof value['item-template'] === 'string') {
+            result[key] = value['item-template'];
+        }
+    }
+    return result;
+}
+export function loadPacks(content, diagnostics) {
+    const templates = new Map();
+    let base;
+    const templateKeys = listYamlKeys(content, '').filter(key => key.includes('/templates/'));
+    for (const key of templateKeys) {
+        let raw;
+        try {
+            raw = parseYaml(readYaml(content, key));
+        }
+        catch (err) {
+            diagnostics.push({ severity: 'error', file: key, message: `failed to parse YAML: ${err}` });
+            continue;
+        }
+        const templateRecord = raw;
+        const info = typeof templateRecord.info === 'object' && templateRecord.info !== null
+            ? templateRecord.info
+            : null;
+        if (typeof templateRecord.name !== 'string' || typeof info?.version !== 'string') {
+            diagnostics.push({ severity: 'error', file: key, message: 'template missing required name or info.version' });
+            continue;
+        }
+        const template = templateRecord;
+        if (template.name === 'base') {
+            base = template;
+        }
+        else {
+            templates.set(template.name, template);
+        }
+    }
+    if (base) {
+        for (const template of templates.values()) {
+            inheritNonReserved(template, base);
+        }
+    }
+    for (const template of topoSortTemplates(templates)) {
+        if (!template.extends)
+            continue;
+        const parent = templates.get(template.extends);
+        if (!parent) {
+            diagnostics.push({
+                severity: 'error',
+                file: `template:${template.name}`,
+                message: `extends references unknown template: ${template.extends}`,
+            });
+            continue;
+        }
+        if (parent.properties && template.properties) {
+            template.properties = { allOf: [parent.properties, template.properties] };
+        }
+        else if (parent.properties) {
+            template.properties = parent.properties;
+        }
+        inheritNonReserved(template, parent);
+    }
+    return templates;
+}
+function inheritNonReserved(template, parent) {
+    for (const [key, value] of Object.entries(parent)) {
+        if (!RESERVED_TEMPLATE_KEYS.has(key) && !(key in template)) {
+            template[key] = value;
+        }
+    }
+}

package/dist/src/mcp/index.js

@@ -0,0 +1,333 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { pathToFileURL } from 'node:url';
+import { computeClusterOverlay, getCluster, getLinkedFields, listNodes } from '../graph/index.js';
+import { loadGraph, loadMultiGraph } from '../loader/index.js';
+import { QueryError } from '../schema/index.js';
+import { createGraphRuntimeConfig } from '../source/config.js';
+import { startGraphFileWatcher, startWebServer } from '../web/server.js';
+import { compactKeys, getSerializer } from './serializers.js';
+export function createMcpHandlers(graph, source, cache) {
+    const resolveMulti = (src) => cache ? cache.get() : loadMultiGraph({ source: src });
+    return {
+        list_nodes(args) {
+            const run = (targetGraph) => {
+                const filter = {
+                    template: typeof args.template === 'string' ? args.template : undefined,
+                    component: typeof args.component === 'string' ? args.component : undefined,
+                    state: typeof args.state === 'string' ? args.state : undefined,
+                    stability: typeof args.stability === 'string' ? args.stability : undefined,
+                };
+                const summaries = listNodes(targetGraph, filter).map(node => ({
+                    id: node.id,
+                    template: node.template,
+                    component: node.component,
+                    state: node.state,
+                    stability: node.stability,
+                }));
+                return formatResult(summaries, args.format, getCompactKeys(args));
+            };
+            if (hasBranch(args)) {
+                return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
+            }
+            try {
+                return run(graph);
+            }
+            catch (err) {
+                return errorResult(err);
+            }
+        },
+        list_templates(args) {
+            const run = (targetGraph) => {
+                const summaries = [...targetGraph.templates.values()]
+                    .map(template => ({
+                    name: template.name,
+                    version: template.info?.version,
+                    core: template.info?.core ?? false,
+                    abstract: template.info?.abstract ?? false,
+                    extends: template.extends,
+                    description: template.info?.description,
+                }))
+                    .sort((a, b) => a.name.localeCompare(b.name));
+                return formatResult(summaries, args.format, getCompactKeys(args));
+            };
+            if (hasBranch(args) && source) {
+                return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
+            }
+            try {
+                return run(graph);
+            }
+            catch (err) {
+                return errorResult(err);
+            }
+        },
+        get_template(args) {
+            try {
+                const name = String(args.name);
+                const template = graph.templates.get(name);
+                if (!template) {
+                    throw new QueryError(`Template not found: ${name}`);
+                }
+                return formatResult(template, args.format, getCompactKeys(args));
+            }
+            catch (err) {
+                return errorResult(err);
+            }
+        },
+        get_cluster(args) {
+            const overlayRefs = Array.isArray(args.overlay_refs)
+                ? args.overlay_refs.filter((ref) => typeof ref === 'string')
+                : [];
+            const run = async (targetGraph, branchRef) => {
+                const cluster = getCluster(targetGraph, String(args.node_id));
+                if (overlayRefs.length === 0 || !source || !branchRef) {
+                    return formatResult(cluster, args.format, getCompactKeys(args));
+                }
+                const multi = await resolveMulti(source);
+                const overlay = computeClusterOverlay(multi, branchRef, overlayRefs, String(args.node_id));
+                return formatResult({ ...cluster, overlay }, args.format, getCompactKeys(args));
+            };
+            const branchRef = hasBranch(args) ? String(args.branch) : undefined;
+            if (branchRef) {
+                return withBranchGraph(source, branchRef, branch => run(branch.graph, branchRef), cache);
+            }
+            return run(graph).catch(err => errorResult(err));
+        },
+        get_linked_fields(args) {
+            const run = (targetGraph) => formatResult(getLinkedFields(targetGraph, String(args.node_id)), args.format, getCompactKeys(args));
+            if (hasBranch(args)) {
+                return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
+            }
+            try {
+                return run(graph);
+            }
+            catch (err) {
+                return errorResult(err);
+            }
+        },
+        async list_branches(args) {
+            try {
+                if (!source)
+                    throw new QueryError('GraphSource is required for list_branches');
+                const multi = await resolveMulti(source);
+                const summaries = multi.branchResults.map(result => ({
+                    ref: result.ref,
+                    status: result.status,
+                    error: result.error,
+                    isDefault: result.ref === multi.default.ref,
+                }));
+                return formatResult(summaries, args.format, getCompactKeys(args));
+            }
+            catch (err) {
+                return errorResult(err);
+            }
+        },
+        async diff_branch(args) {
+            try {
+                if (!source)
+                    throw new QueryError('GraphSource is required for diff_branch');
+                if (typeof args.branch !== 'string' || args.branch.length === 0) {
+                    throw new QueryError('branch is required');
+                }
+                const multi = await resolveMulti(source);
+                return formatResult(multi.diff(args.branch), args.format, getCompactKeys(args));
+            }
+            catch (err) {
+                return errorResult(err);
+            }
+        },
+    };
+}
+async function withBranchGraph(source, branchRef, fn, cache) {
+    try {
+        if (!source)
+            throw new QueryError('GraphSource is required when branch is provided');
+        const multi = cache ? await cache.get() : await loadMultiGraph({ source });
+        const branch = multi.branches.find(item => item.ref === branchRef);
+        if (!branch)
+            throw new QueryError(`branch '${branchRef}' not found or failed to load`);
+        return fn(branch);
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+function hasBranch(args) {
+    return typeof args.branch === 'string' && args.branch.length > 0;
+}
+function formatResult(value, format, compact = false) {
+    const payload = compact === true ? compactKeys(value) : value;
+    return { content: [{ type: 'text', text: getSerializer(format).serialize(payload) }] };
+}
+function getCompactKeys(args) {
+    return args.compact_keys === true || args.compactKeys === true;
+}
+function errorResult(err) {
+    const message = err instanceof QueryError ? err.message : String(err);
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+export async function startMcpServer(options = {}) {
+    const { noWeb = false, watch = false } = options;
+    const config = createGraphRuntimeConfig();
+    let graph;
+    let loadError;
+    try {
+        graph = await loadGraph({ source: config.source, strict: true });
+    }
+    catch (err) {
+        loadError = String(err);
+        graph = {
+            nodesById: new Map(),
+            edgesByFrom: new Map(),
+            edgesByTo: new Map(),
+            templates: new Map(),
+            diagnostics: [],
+        };
+    }
+    const handlers = createMcpHandlers(graph, config.source);
+    if (!noWeb) {
+        await startWebServer(graph, {
+            graphPath: config.graphPath,
+            fileWatcher: config.fileWatcherGraphPath && watch ? true : undefined,
+            source: config.source,
+        });
+    }
+    else if (watch && config.fileWatcherGraphPath) {
+        startGraphFileWatcher(graph, { graphPath: config.fileWatcherGraphPath });
+    }
+    const server = new Server({ name: 'corum', version: '0.1.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: 'list_nodes',
+                description: 'List nodes in the graph. Returns id, template, component, state, stability for each matched node.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        template: { type: 'string', description: 'Filter by template name' },
+                        component: { type: 'string', description: 'Filter by component name' },
+                        state: { type: 'string', description: 'Filter by lifecycle state' },
+                        stability: { type: 'string', description: 'Filter by stability' },
+                        branch: { type: 'string', description: 'Branch ref to load nodes from' },
+                        format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
+                        compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
+                    },
+                },
+            },
+            {
+                name: 'list_templates',
+                description: 'List loaded graph templates. Returns name, version, core, abstract, extends, and description for each template.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        branch: { type: 'string', description: 'Branch ref to load templates from' },
+                        format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
+                        compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
+                    },
+                },
+            },
+            {
+                name: 'get_template',
+                description: 'Get full details for a loaded graph template.',
+                inputSchema: {
+                    type: 'object',
+                    required: ['name'],
+                    properties: {
+                        name: { type: 'string', description: 'Template name' },
+                        format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
+                        compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
+                    },
+                },
+            },
+            {
+                name: 'get_cluster',
+                description: 'Get the full cluster for a root node.',
+                inputSchema: {
+                    type: 'object',
+                    required: ['node_id'],
+                    properties: {
+                        node_id: { type: 'string', description: 'Fully qualified node ID' },
+                        branch: { type: 'string', description: 'Branch ref to load the cluster from' },
+                        overlay_refs: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Branch refs to overlay. Returns ghost field data alongside the cluster.',
+                        },
+                        format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
+                        compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
+                    },
+                },
+            },
+            {
+                name: 'get_linked_fields',
+                description: 'Get all maps-to edges touching fields owned by the given root node.',
+                inputSchema: {
+                    type: 'object',
+                    required: ['node_id'],
+                    properties: {
+                        node_id: { type: 'string', description: 'Fully qualified root node ID' },
+                        branch: { type: 'string', description: 'Branch ref to load linked fields from' },
+                        format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
+                        compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
+                    },
+                },
+            },
+            {
+                name: 'list_branches',
+                description: 'List branches available from the configured graph source and their load status.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
+                        compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
+                    },
+                },
+            },
+            {
+                name: 'diff_branch',
+                description: 'Diff a branch against the default branch.',
+                inputSchema: {
+                    type: 'object',
+                    required: ['branch'],
+                    properties: {
+                        branch: { type: 'string', description: 'Branch ref to diff against the default branch' },
+                        format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
+                        compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
+                    },
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        if (loadError) {
+            return { content: [{ type: 'text', text: `Graph load error: ${loadError}` }], isError: true };
+        }
+        const args = (request.params.arguments ?? {});
+        switch (request.params.name) {
+            case 'list_nodes':
+                return await handlers.list_nodes(args);
+            case 'list_templates':
+                return await handlers.list_templates(args);
+            case 'get_template':
+                return await handlers.get_template(args);
+            case 'get_cluster':
+                return await handlers.get_cluster(args);
+            case 'get_linked_fields':
+                return await handlers.get_linked_fields(args);
+            case 'list_branches':
+                return await handlers.list_branches(args);
+            case 'diff_branch':
+                return await handlers.diff_branch(args);
+            default:
+                return { content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }], isError: true };
+        }
+    });
+    await server.connect(new StdioServerTransport());
+}
+function isEntrypoint() {
+    return process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+}
+if (isEntrypoint()) {
+    await startMcpServer();
+}

package/dist/src/mcp/serializers.js

@@ -0,0 +1,68 @@
+import { encode as encodeToon } from '@toon-format/toon';
+import { stringify as stringifyYaml } from 'yaml';
+import { QueryError } from '../schema/index.js';
+export class JsonSerializer {
+    format = 'json';
+    serialize(value) {
+        return JSON.stringify(value, null, 2);
+    }
+}
+export class YamlSerializer {
+    format = 'yaml';
+    serialize(value) {
+        return stringifyYaml(value);
+    }
+}
+export class ToonSerializer {
+    format = 'toon';
+    serialize(value) {
+        return encodeToon(value);
+    }
+}
+export function getSerializer(format) {
+    switch (format ?? 'yaml') {
+        case 'json':
+            return new JsonSerializer();
+        case 'yaml':
+            return new YamlSerializer();
+        case 'toon':
+            return new ToonSerializer();
+        default:
+            throw new QueryError(`Invalid output format: ${String(format)}. Expected yaml, json, or toon.`);
+    }
+}
+const COMPACT_KEY_MAP = {
+    id: 'i',
+    template: 't',
+    component: 'cp',
+    state: 's',
+    stability: 'st',
+    schemaVersion: 'sv',
+    lastModifiedAt: 'lm',
+    extractedFrom: 'xf',
+    properties: 'p',
+    root: 'r',
+    children: 'ch',
+    edges: 'e',
+    nodes: 'n',
+    from: 'fr',
+    to: 'to',
+    type: 'ty',
+    notes: 'nt',
+    version: 'v',
+    core: 'c',
+    abstract: 'a',
+    extends: 'ex',
+};
+export function compactKeys(value) {
+    if (Array.isArray(value)) {
+        return value.map(item => compactKeys(item));
+    }
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [
+        COMPACT_KEY_MAP[key] ?? key,
+        compactKeys(child),
+    ]));
+}