@atolis-hq/corum 0.1.0

package/README.md

@@ -0,0 +1,223 @@
+<div width="100%" align="center">
+<img src="assets/corum-logo.svg" width="120" height="120" /><br>
+ <h1>Corum</h1>
+</div>
+
+Corum loads design graph files from disk into an in-memory graph and exposes the graph through MCP tools.
+
+## Requirements
+
+- Node.js 20 or newer
+- npm
+
+## Install
+
+From the repository root:
+
+```powershell
+npm install
+```
+
+This installs TypeScript, the MCP SDK, and YAML parsing dependencies.
+
+## Build
+
+Compile the TypeScript sources into `dist/`:
+
+```powershell
+npm run build
+```
+
+The build command runs `tsc`.
+
+## Test
+
+Run the full test suite:
+
+```powershell
+npm test
+```
+
+This compiles the project and runs the Node test runner against:
+
+- `test/schema.test.ts`
+- `test/loader.test.ts`
+- `test/graph.test.ts`
+- `test/mcp.test.ts`
+- `test/writer.test.ts`
+- `test/serializer.test.ts`
+
+The fixture graph used by the tests is in `fixtures/sample-graph`. The tests verify that it loads as `45` nodes and `38` edges.
+
+## Run The MCP Server
+
+Build first:
+
+```powershell
+npm run build
+```
+
+Run the MCP server against the default graph path:
+
+```powershell
+npm run mcp
+```
+
+By default, the server loads:
+
+```text
+.corum/graph
+```
+
+To run it against the sample graph fixture instead:
+
+```powershell
+$env:CORUM_GRAPH_PATH = "fixtures/sample-graph"
+npm run mcp
+```
+
+To reload the in-memory graph when graph YAML or template YAML files change, pass `--watch` to the built server:
+
+```powershell
+node dist/src/mcp/index.js --watch
+```
+
+The same watcher can be enabled for the web server with `node dist/src/web/server.js --watch`, or for either server by setting `CORUM_FILE_WATCHER=true`.
+
+Starting with powershell
+```
+ $env:CORUM_GRAPH_PATH = "fixtures/sample-graph";
+ $env:CORUM_WEB_PORT = 3001;
+ $env:CORUM_FILE_WATCHER="true";
+ npm run web
+```
+
+To run the web app against a git repository instead of a filesystem graph path, set `CORUM_SOURCE=git` before starting the app.
+
+For a local git repository:
+
+```powershell
+$env:CORUM_SOURCE = "git"
+$env:CORUM_GIT_LOCAL_PATH = "C:\git\atolis-hq\corum-design-graph"
+$env:CORUM_GIT_BRANCH = "main"
+$env:CORUM_GIT_POLL_SECONDS = 10
+$env:CORUM_WEB_PORT = 3001
+npm run web
+```
+
+For a remote repository:
+
+```powershell
+$env:CORUM_SOURCE = "git"
+$env:CORUM_GIT_REMOTE_URL = "https://github.com/org/design-repo.git"
+$env:CORUM_GIT_BRANCH = "main"
+$env:CORUM_GIT_POLL_SECONDS = 10
+$env:CORUM_WEB_PORT = 3001
+npm run web
+```
+
+For private remote repositories, also set `CORUM_GIT_TOKEN`. `CORUM_GIT_USERNAME` defaults to `x-access-token` when a token is present.
+
+The same git source config is used by `npm run mcp`. Git-backed startup expects graph files in `.corum/graph` and template packs in `.corum/packs`, and loads the selected branch at process start.
+
+`CORUM_GIT_POLL_SECONDS` is optional. When set to a positive number of seconds, the web server polls the git source for branch/ref changes, invalidates its cached multi-branch view, and reloads the app automatically. If it is not set, git-backed content is not polled.
+
+`CORUM_FILE_WATCHER` only watches filesystem graph paths. It does not watch git refs. For git-backed web sessions, you can either enable `CORUM_GIT_POLL_SECONDS` or use the always-visible `Reload` button in the branch bar to force a refresh.
+
+The MCP server exposes these tools:
+
+- `list_nodes`: lists graph nodes, optionally filtered by `template`, `component`, `state`, or `stability`
+- `list_templates`: lists loaded graph templates with summary metadata
+- `get_template`: returns full details for a loaded graph template
+- `get_cluster`: returns a root node, owned child nodes, and edges inside that cluster
+- `get_linked_fields`: returns `maps-to` edges touching fields owned by a root node
+
+Each tool accepts an optional `format` argument:
+
+- `yaml`: default, human-readable YAML
+- `json`: pretty JSON
+- `toon`: TOON output via the official `@toon-format/toon` encoder for lower token use
+
+Each tool also accepts `compact_keys: true` to shorten common graph keys before serialization. This works with all formats:
+
+```text
+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
+```
+
+## MCP Client Configuration
+
+This repo includes a project-level `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "corum": {
+      "command": "node",
+      "args": ["dist/src/mcp/index.js"],
+      "env": {
+        "CORUM_GRAPH_PATH": "fixtures/sample-graph"
+      }
+    }
+  }
+}
+```
+
+Build the project before using this config from an MCP client:
+
+```powershell
+npm run build
+```
+
+The checked-in config points at `fixtures/sample-graph` so the tools return sample nodes immediately. Change `CORUM_GRAPH_PATH` to `.corum/graph` when you have graph component files there.
+
+## MCP Smoke Test
+
+Run a local MCP client against the configured server and print graph data:
+
+```powershell
+npm run mcp:smoke
+```
+
+The smoke test starts the MCP server over stdio and calls:
+
+- `list_nodes`
+- `list_nodes` filtered to `APIEndpoint`
+- `get_cluster` for `orders.DomainModel.order`
+- `get_linked_fields` for `orders.DomainModel.order`
+
+## Useful Development Commands
+
+Type-check without emitting files:
+
+```powershell
+npx tsc --noEmit
+```
+
+Run one compiled test file after building:
+
+```powershell
+npm run build
+node --test dist/test/loader.test.js
+```
+
+Clean generated build output manually if needed:
+
+```powershell
+Remove-Item -Recurse -Force dist
+```

package/dist/src/adapters/index.js

@@ -0,0 +1,12 @@
+const registry = new Map();
+export function registerAdapter(adapter) {
+    registry.set(adapter.adapterId, adapter);
+}
+export function getAdapter(adapterId) {
+    const adapter = registry.get(adapterId);
+    if (!adapter)
+        throw new Error(`Unknown adapter: ${adapterId}`);
+    return adapter;
+}
+import { OpenAPIAdapter } from './openapi/index.js';
+registerAdapter(new OpenAPIAdapter());

package/dist/src/adapters/openapi/index.js

@@ -0,0 +1,12 @@
+import { parseSpec } from './parser.js';
+import { mapDocument } from './mapper.js';
+export class OpenAPIAdapter {
+    adapterId = 'openapi';
+    async import(entry, context) {
+        const { document, diagnostics } = await parseSpec(entry.spec);
+        if (!document)
+            return { nodes: [], edges: [], diagnostics };
+        const { nodes, edges, diagnostics: mapDiagnostics } = mapDocument(document, entry, context.packConfig);
+        return { nodes, edges, diagnostics: [...diagnostics, ...mapDiagnostics] };
+    }
+}

package/dist/src/adapters/openapi/mapper.js

@@ -0,0 +1,218 @@
+export function deriveComponent(path, mapping) {
+    if (mapping.strategy === 'hardcoded')
+        return mapping.component;
+    if (mapping.strategy === 'tag')
+        return undefined;
+    const segments = path.split('/').filter(Boolean);
+    if ('pattern' in mapping) {
+        const match = path.match(mapping.pattern);
+        return match?.[1];
+    }
+    return segments[mapping.segment];
+}
+export function deriveScalarType(type, format, scalarTypes) {
+    if (format && scalarTypes[`${type}/${format}`])
+        return scalarTypes[`${type}/${format}`];
+    return scalarTypes[type];
+}
+export function isRefSchema(schema) {
+    return typeof schema === 'object' && schema !== null && '$ref' in schema;
+}
+export function deriveNodeId(kind, component, name, parentId, section) {
+    if (kind === 'operation')
+        return `${component}.APIEndpoint.${name}`;
+    return `${parentId}.${section}.${name}`;
+}
+export function refName(ref) {
+    return ref.split('/').pop() ?? ref;
+}
+export function mapDocument(document, entry, packConfig) {
+    const nodes = [];
+    const edges = [];
+    const diagnostics = [];
+    const sharedSchemas = new Map();
+    if (document.components?.schemas) {
+        for (const [name, schema] of Object.entries(document.components.schemas)) {
+            if (isRefSchema(schema))
+                continue;
+            const s = schema;
+            if (s.type !== 'object' && s.enum) {
+                const component = deriveComponentForSchema(name, document, entry);
+                if (!component)
+                    continue;
+                const enumId = `${component}.EnumDefinition.${name}`;
+                const enumNode = makeNode(packConfig.constructs.enumDefinition?.template ?? 'EnumDefinition', component, entry.spec, enumId);
+                nodes.push(enumNode);
+                sharedSchemas.set(name, enumId);
+                s.enum.forEach((value) => {
+                    const valueId = deriveNodeId('enumValue', undefined, String(value), enumId, 'values');
+                    const valueNode = makeNode(packConfig.constructs.enumValue?.template ?? 'EnumValue', component, entry.spec, valueId);
+                    valueNode.properties = { name: String(value) };
+                    nodes.push(valueNode);
+                    edges.push({ id: `${enumId}__has-value__${valueId}`, from: enumId, to: valueId, type: 'has-value', state: 'implemented', stability: 'unstable' });
+                });
+                continue;
+            }
+            const component = deriveComponentForSchema(name, document, entry);
+            if (!component) {
+                diagnostics.push({ severity: 'warning', file: entry.spec, message: `Cannot derive component for schema ${name}, skipping` });
+                continue;
+            }
+            const schemaId = `${component}.Schema.${name}`;
+            sharedSchemas.set(name, schemaId);
+            const node = makeNode(packConfig.constructs.requestSchema?.template ?? 'Schema', component, entry.spec, schemaId);
+            nodes.push(node);
+            emitFields(s, schemaId, 'fields', packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas);
+        }
+    }
+    for (const [urlPath, pathItem] of Object.entries(document.paths ?? {})) {
+        if (!pathItem)
+            continue;
+        const methods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+        for (const method of methods) {
+            const operation = pathItem[method];
+            if (!operation)
+                continue;
+            const operationId = operation.operationId ?? `${method}-${urlPath.replace(/\//g, '-').replace(/^-/, '')}`;
+            const component = entry.componentMapping.strategy === 'tag'
+                ? operation.tags?.[0]
+                : deriveComponent(urlPath, entry.componentMapping);
+            if (!component) {
+                diagnostics.push({ severity: 'warning', file: entry.spec, message: `Cannot derive component for ${method.toUpperCase()} ${urlPath}, skipping` });
+                continue;
+            }
+            const endpointId = deriveNodeId('operation', component, operationId);
+            const endpointNode = makeNode(packConfig.constructs.operation.template, component, entry.spec, endpointId);
+            endpointNode.properties = {
+                method: method.toUpperCase(),
+                path: urlPath,
+                ...(operation.operationId && { operationId: operation.operationId }),
+                ...(operation.summary && { description: operation.summary }),
+            };
+            nodes.push(endpointNode);
+            const requestBody = operation.requestBody;
+            if (requestBody?.content) {
+                const jsonContent = requestBody.content['application/json'];
+                if (jsonContent?.schema) {
+                    emitSchemaNode(jsonContent.schema, `${operationId}-request`, endpointId, 'schemas', packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas);
+                }
+            }
+            for (const [status, response] of Object.entries(operation.responses ?? {})) {
+                const responseObj = response;
+                const jsonContent = responseObj.content?.['application/json'];
+                if (jsonContent?.schema) {
+                    emitSchemaNode(jsonContent.schema, `${operationId}-response-${status}`, endpointId, 'schemas', packConfig, entry.spec, nodes, edges, diagnostics, sharedSchemas);
+                }
+            }
+        }
+    }
+    return { nodes, edges, diagnostics };
+}
+function makeNode(template, component, specPath, id) {
+    return {
+        id,
+        template,
+        component,
+        state: 'implemented',
+        stability: 'unstable',
+        schemaVersion: '1',
+        lastModifiedAt: new Date().toISOString().split('T')[0],
+        extractedFrom: specPath,
+        derivation: 'determined',
+        derivedBy: 'adapter:openapi',
+        properties: {},
+    };
+}
+function emitSchemaNode(schema, name, parentId, section, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas) {
+    if (isRefSchema(schema)) {
+        const refId = sharedSchemas.get(refName(schema.$ref));
+        if (refId) {
+            const parent = nodes.find(n => n.id === parentId);
+            if (parent)
+                parent.properties[`${section}.${name}`] = refId;
+        }
+        return;
+    }
+    const schemaId = deriveNodeId('schema', undefined, name, parentId, section);
+    const [component] = parentId.split('.');
+    const node = makeNode(packConfig.constructs.requestSchema?.template ?? 'Schema', component, specPath, schemaId);
+    nodes.push(node);
+    edges.push({ id: `${parentId}__has-field__${schemaId}`, from: parentId, to: schemaId, type: 'has-field', state: 'implemented', stability: 'unstable' });
+    emitFields(schema, schemaId, 'fields', packConfig, specPath, nodes, edges, diagnostics, sharedSchemas);
+}
+function emitFields(schema, parentId, section, packConfig, specPath, nodes, edges, diagnostics, sharedSchemas) {
+    for (const [fieldName, fieldSchema] of Object.entries(schema.properties ?? {})) {
+        const fieldId = deriveNodeId('field', undefined, fieldName, parentId, section);
+        const [component] = parentId.split('.');
+        const fieldNode = makeNode(packConfig.constructs.schemaProperty?.template ?? 'Field', component, specPath, fieldId);
+        const required = Array.isArray(schema.required) && schema.required.includes(fieldName);
+        if (isRefSchema(fieldSchema)) {
+            const ref = refName(fieldSchema.$ref);
+            fieldNode.properties = { $ref: sharedSchemas.get(ref) ?? ref, nullable: !required, cardinality: 'one' };
+        }
+        else {
+            const fs = fieldSchema;
+            if (fs.enum && fs.type !== 'object') {
+                const enumRef = sharedSchemas.get(fieldName);
+                fieldNode.properties = { ...(enumRef ? { $ref: enumRef } : { type: 'string' }), nullable: !required, cardinality: 'one' };
+            }
+            else if (fs.type === 'array') {
+                const items = fs.items;
+                if (isRefSchema(items)) {
+                    fieldNode.properties = { objectRef: refName(items.$ref), nullable: !required, cardinality: 'many' };
+                }
+                else {
+                    const itemType = deriveScalarType(items?.type ?? 'string', items?.format, packConfig.scalarTypes);
+                    fieldNode.properties = { type: itemType ?? 'string', nullable: !required, cardinality: 'many' };
+                }
+            }
+            else {
+                const scalarType = deriveScalarType(fs.type ?? 'string', fs.format, packConfig.scalarTypes);
+                if (scalarType) {
+                    fieldNode.properties = { type: scalarType, nullable: !required, cardinality: 'one' };
+                }
+                else {
+                    diagnostics.push({ severity: 'warning', file: specPath, message: `Unknown type for field ${fieldId}: ${fs.type}/${fs.format}` });
+                    fieldNode.properties = { type: 'string', nullable: !required, cardinality: 'one' };
+                }
+            }
+        }
+        nodes.push(fieldNode);
+        edges.push({ id: `${parentId}__has-field__${fieldId}`, from: parentId, to: fieldId, type: 'has-field', state: 'implemented', stability: 'unstable' });
+    }
+}
+function deriveComponentForSchema(name, document, entry, visited = new Set()) {
+    if (visited.has(name))
+        return undefined;
+    visited.add(name);
+    // Direct: find an operation that references this schema
+    for (const [urlPath, pathItem] of Object.entries(document.paths ?? {})) {
+        if (!pathItem)
+            continue;
+        const methods = ['get', 'post', 'put', 'patch', 'delete'];
+        for (const method of methods) {
+            const operation = pathItem[method];
+            if (!operation)
+                continue;
+            if (referencesSchema(operation, name)) {
+                return entry.componentMapping.strategy === 'tag'
+                    ? operation.tags?.[0]
+                    : deriveComponent(urlPath, entry.componentMapping);
+            }
+        }
+    }
+    // Indirect: find another component schema that references this one and use its component
+    for (const [schemaName, schema] of Object.entries(document.components?.schemas ?? {})) {
+        if (schemaName === name || isRefSchema(schema))
+            continue;
+        if (JSON.stringify(schema).includes(`"#/components/schemas/${name}"`)) {
+            const comp = deriveComponentForSchema(schemaName, document, entry, visited);
+            if (comp)
+                return comp;
+        }
+    }
+    return undefined;
+}
+function referencesSchema(operation, schemaName) {
+    return JSON.stringify(operation).includes(`"#/components/schemas/${schemaName}"`);
+}

package/dist/src/adapters/openapi/parser.js

@@ -0,0 +1,16 @@
+import SwaggerParser from '@apidevtools/swagger-parser';
+export async function parseSpec(specPath) {
+    const diagnostics = [];
+    try {
+        const document = await SwaggerParser.bundle(specPath);
+        return { document, diagnostics };
+    }
+    catch (err) {
+        diagnostics.push({
+            severity: 'error',
+            file: specPath,
+            message: `Failed to parse OpenAPI spec: ${err instanceof Error ? err.message : String(err)}`,
+        });
+        return { document: null, diagnostics };
+    }
+}

package/dist/src/bin/corum.js

@@ -0,0 +1,164 @@
+import { Command } from 'commander';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { loadImportConfig, buildOpenAPIConfig } from '../import/config.js';
+import { runImport } from '../import/runner.js';
+import { loadGraph } from '../loader/index.js';
+import { startMcpServer } from '../mcp/index.js';
+import { createGraphRuntimeConfig } from '../source/config.js';
+import { startWebServer } from '../web/server.js';
+const program = new Command();
+program
+    .name('corum')
+    .description('Corum graph CLI')
+    .version('0.1.0');
+// ── mcp ──────────────────────────────────────────────────────────────────────
+program
+    .command('mcp')
+    .description('Start the MCP stdio server (+ web UI by default)')
+    .option('--no-web', 'Suppress the web UI')
+    .option('--watch', 'Enable file watcher')
+    .option('--graph <path>', 'Override graph path')
+    .action(async (opts) => {
+    if (opts.graph)
+        process.env.CORUM_GRAPH_PATH = path.resolve(opts.graph);
+    await startMcpServer({ noWeb: !opts.web, watch: opts.watch ?? false });
+});
+// ── web ──────────────────────────────────────────────────────────────────────
+program
+    .command('web')
+    .description('Start the web UI')
+    .option('--port <n>', 'Port to listen on', parseInt)
+    .option('--graph <path>', 'Override graph path')
+    .action(async (opts) => {
+    if (opts.graph)
+        process.env.CORUM_GRAPH_PATH = path.resolve(opts.graph);
+    const config = createGraphRuntimeConfig();
+    let graph;
+    try {
+        graph = await loadGraph({ source: config.source, strict: true });
+    }
+    catch (err) {
+        process.stderr.write(`[ERROR] ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(2);
+    }
+    await startWebServer(graph, {
+        graphPath: config.graphPath,
+        source: config.source,
+        port: opts.port,
+    });
+});
+// ── init ─────────────────────────────────────────────────────────────────────
+const CONFIG_TEMPLATE = `# Corum project configuration
+# Uncomment and set the options relevant to your setup.
+# All values can be overridden by environment variables (CORUM_*) or CLI flags.
+
+# Source type: 'file' (default) or 'git'
+# Maps to: CORUM_SOURCE
+# source: file
+
+# ── File source (default) ─────────────────────────────────────────────────────
+# Local path to the graph directory.
+# Maps to: CORUM_GRAPH_PATH
+# graph: .corum/graph
+
+# ── Git source ────────────────────────────────────────────────────────────────
+# Uncomment 'source: git' above and configure one of the following:
+
+# Local path to a git repository containing the graph.
+# Maps to: CORUM_GIT_LOCAL_PATH
+# git_local_path: /path/to/repo
+
+# Remote URL of a git repository containing the graph.
+# Maps to: CORUM_GIT_REMOTE_URL
+# git_remote_url: https://github.com/org/repo
+
+# Default branch to load (git source only).
+# Maps to: CORUM_GIT_BRANCH
+# git_branch: main
+
+# How often to poll the remote for changes, in seconds (remote git only).
+# Maps to: CORUM_GIT_POLL_SECONDS
+# git_poll_seconds: 30
+
+# Auth token for private repositories. Prefer setting CORUM_GIT_TOKEN as an
+# environment variable rather than storing a token in this file.
+# git_token: ""
+
+# Auth username (default: x-access-token, suits GitHub PATs and Actions tokens).
+# Maps to: CORUM_GIT_USERNAME
+# git_username: x-access-token
+`;
+program
+    .command('init')
+    .description('Scaffold .corum/config.yaml with commented defaults')
+    .action(() => {
+    const configPath = path.join(process.cwd(), '.corum', 'config.yaml');
+    if (existsSync(configPath)) {
+        process.stdout.write(`.corum/config.yaml already exists — not overwriting\n`);
+        return;
+    }
+    mkdirSync(path.dirname(configPath), { recursive: true });
+    writeFileSync(configPath, CONFIG_TEMPLATE);
+    process.stdout.write(`Created .corum/config.yaml\n`);
+});
+// ── import ───────────────────────────────────────────────────────────────────
+const importCmd = program.command('import')
+    .description('Import specifications into the graph')
+    .option('--config <path>', 'Path to import config YAML')
+    .option('--graph <path>', 'Override CORUM_GRAPH_PATH')
+    .action(async (opts) => {
+    if (!opts.config) {
+        importCmd.help();
+        return;
+    }
+    try {
+        const runtimeConfig = buildRuntimeConfig(opts.graph);
+        const config = loadImportConfig(path.resolve(opts.config));
+        const result = await runImport(config, runtimeConfig);
+        reportDiagnostics(result.diagnostics);
+        if (result.diagnostics.some(d => d.severity === 'error'))
+            process.exit(1);
+    }
+    catch (err) {
+        process.stderr.write(`[ERROR] ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(2);
+    }
+});
+importCmd
+    .command('openapi <spec>')
+    .description('Import an OpenAPI spec into the graph')
+    .option('--component-strategy <strategy>', 'Component mapping: uri-segment, tag, hardcoded', 'uri-segment')
+    .option('--segment <n>', 'URI segment index (uri-segment strategy)', parseInt)
+    .option('--pattern <regex>', 'Regex pattern (uri-segment strategy)')
+    .option('--component <name>', 'Component name (hardcoded strategy)')
+    .option('--graph <path>', 'Override CORUM_GRAPH_PATH')
+    .action(async (spec, opts) => {
+    try {
+        const runtimeConfig = buildRuntimeConfig(opts.graph);
+        const entry = buildOpenAPIConfig(spec, opts.componentStrategy, opts.segment, opts.pattern, opts.component);
+        const result = await runImport({ imports: [entry] }, runtimeConfig);
+        reportDiagnostics(result.diagnostics);
+        if (result.diagnostics.some(d => d.severity === 'error'))
+            process.exit(1);
+    }
+    catch (err) {
+        process.stderr.write(`[ERROR] ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(2);
+    }
+});
+function buildRuntimeConfig(graphOverride) {
+    if (graphOverride)
+        process.env.CORUM_GRAPH_PATH = path.resolve(graphOverride);
+    return createGraphRuntimeConfig();
+}
+function reportDiagnostics(diagnostics) {
+    for (const d of diagnostics) {
+        const prefix = d.severity === 'error' ? 'ERROR' : 'WARN';
+        process.stderr.write(`[${prefix}] ${d.file}: ${d.message}\n`);
+    }
+    const errors = diagnostics.filter(d => d.severity === 'error').length;
+    const warnings = diagnostics.filter(d => d.severity === 'warning').length;
+    process.stdout.write(`Import complete. ${errors} error(s), ${warnings} warning(s).\n`);
+}
+program.parse();

package/dist/src/cli.js

@@ -0,0 +1,20 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parse } from "yaml";
+import { convertOpenApiToApiEndpointDocuments, serializeApiEndpointDocument, } from "./openapi-to-api-endpoints.js";
+const [sourcePath, targetRoot] = process.argv.slice(2);
+if (!sourcePath || !targetRoot) {
+    console.error("Usage: node dist/src/cli.js <openapi-yaml> <graph-component-dir>");
+    process.exit(1);
+}
+const source = await readFile(sourcePath, "utf8");
+const openApi = parse(source);
+const component = path.basename(targetRoot);
+const outputDir = path.join(targetRoot, "api-endpoints");
+const documents = convertOpenApiToApiEndpointDocuments(openApi, { component });
+await rm(outputDir, { recursive: true, force: true });
+await mkdir(outputDir, { recursive: true });
+for (const { fileName, document } of documents) {
+    await writeFile(path.join(outputDir, fileName), serializeApiEndpointDocument(document), "utf8");
+}
+console.log(`Wrote ${documents.length} APIEndpoint files to ${outputDir}`);