@atolis-hq/corum 0.1.0

package/dist/src/openapi-to-api-endpoints.js

@@ -0,0 +1,240 @@
+import { stringify } from "yaml";
+const HTTP_METHODS = new Set(["get", "put", "post", "delete", "options", "head", "patch", "trace"]);
+export function convertOpenApiToApiEndpointDocuments(openApi, options) {
+    const output = [];
+    for (const [path, pathItem] of Object.entries(openApi.paths ?? {})) {
+        if (!isRecord(pathItem)) {
+            continue;
+        }
+        for (const [method, operation] of Object.entries(pathItem)) {
+            if (!HTTP_METHODS.has(method) || !isRecord(operation)) {
+                continue;
+            }
+            const slug = slugify(operation.operationId ?? `${method}-${path}`);
+            const ctx = {
+                openApi,
+                schemas: {},
+                enums: {},
+                schemaNamesInProgress: new Set(),
+            };
+            const properties = {
+                method: method.toUpperCase(),
+                path,
+                responses: {},
+            };
+            const requestSchema = firstContentSchema(operation.requestBody?.content);
+            if (requestSchema) {
+                const requestName = `${slug}-request`;
+                createSchema(requestName, requestSchema, ctx, operation.requestBody?.description);
+                properties.request = requestName;
+            }
+            for (const [status, response] of Object.entries(operation.responses ?? {})) {
+                if (!isRecord(response)) {
+                    continue;
+                }
+                const responseName = `${slug}-response-${status}`;
+                const responseSchema = firstContentSchema(response.content);
+                if (responseSchema) {
+                    createSchema(responseName, responseSchema, ctx, response.description);
+                }
+                else {
+                    createEmptyBodySchema(responseName, response.description, ctx);
+                }
+                properties.responses[status] = responseName;
+            }
+            const document = {
+                "schema-version": "1.0",
+                id: `${options.component}.api-endpoints.${slug}`,
+                template: "APIEndpoint",
+                state: "proposed",
+                stability: "unstable",
+                name: `${method.toUpperCase()} ${path}`,
+                ...(operation.description || operation.summary
+                    ? { description: operation.description ?? operation.summary }
+                    : {}),
+                properties,
+                schemas: ctx.schemas,
+            };
+            if (Object.keys(ctx.enums).length > 0) {
+                document.enums = ctx.enums;
+            }
+            output.push({
+                fileName: `${slug}.yaml`,
+                document,
+            });
+        }
+    }
+    return output.sort((left, right) => left.fileName.localeCompare(right.fileName));
+}
+export function serializeApiEndpointDocument(document) {
+    return stringify(document, {
+        lineWidth: 0,
+        sortMapEntries: false,
+    });
+}
+function createSchema(name, sourceSchema, ctx, description) {
+    if (ctx.schemas[name] || ctx.schemaNamesInProgress.has(name)) {
+        return;
+    }
+    ctx.schemaNamesInProgress.add(name);
+    ctx.schemas[name] = {
+        ...(description ? { description } : {}),
+        fields: {},
+    };
+    const schema = resolveSchema(sourceSchema, ctx.openApi);
+    const logicalName = typeof sourceSchema.$ref === "string" ? refTail(sourceSchema.$ref) : name;
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const fields = {};
+    if (schema.type === "array") {
+        fields.items = createField(`${name}Item`, schema.items ?? {}, ctx, false, logicalName);
+        fields.items.cardinality = "many";
+    }
+    else if (schema.type === "object" || isRecord(schema.properties) || isRecord(schema.additionalProperties)) {
+        for (const [fieldName, propertySchema] of Object.entries(schema.properties ?? {})) {
+            if (!isRecord(propertySchema)) {
+                continue;
+            }
+            fields[fieldName] = createField(fieldName, propertySchema, ctx, required.has(fieldName), logicalName);
+        }
+        if (Object.keys(fields).length === 0 && isRecord(schema.additionalProperties)) {
+            fields.additionalProperties = createField("additionalProperties", schema.additionalProperties, ctx, true, logicalName);
+        }
+    }
+    else {
+        fields.value = createField("value", schema, ctx, true, logicalName);
+    }
+    ctx.schemas[name] = {
+        ...(description || schema.description ? { description: description ?? schema.description } : {}),
+        fields,
+    };
+    ctx.schemaNamesInProgress.delete(name);
+}
+function createEmptyBodySchema(name, description, ctx) {
+    ctx.schemas[name] = {
+        ...(description ? { description } : {}),
+        fields: {
+            message: {
+                scalarType: "string",
+                nullable: true,
+                cardinality: "one",
+            },
+        },
+    };
+}
+function createField(fieldName, sourceSchema, ctx, required, ownerName) {
+    const cardinality = sourceSchema.type === "array" ? "many" : "one";
+    const schema = sourceSchema.type === "array" && isRecord(sourceSchema.items) ? sourceSchema.items : sourceSchema;
+    if (isRecord(schema) && typeof schema.$ref === "string") {
+        const refName = refTail(schema.$ref);
+        const target = resolveSchema(schema, ctx.openApi);
+        createSchema(refName, target, ctx, target.description);
+        return {
+            objectRef: refName,
+            nullable: !required,
+            cardinality,
+        };
+    }
+    if (Array.isArray(schema.enum)) {
+        const enumName = enumNameFor(ownerName, fieldName);
+        ctx.enums[enumName] = {
+            ...(schema.description ? { description: schema.description } : {}),
+            values: Object.fromEntries(schema.enum.map((value) => [
+                slugify(String(value)),
+                {
+                    name: String(value),
+                },
+            ])),
+        };
+        return {
+            objectRef: enumName,
+            nullable: !required,
+            cardinality,
+        };
+    }
+    if (schema.type === "object" || isRecord(schema.properties) || isRecord(schema.additionalProperties)) {
+        const objectName = pascalCase(fieldName);
+        createSchema(objectName, schema, ctx, schema.description);
+        return {
+            objectRef: objectName,
+            nullable: !required,
+            cardinality,
+        };
+    }
+    return {
+        scalarType: scalarTypeFor(schema),
+        nullable: !required,
+        cardinality,
+    };
+}
+function firstContentSchema(content) {
+    if (!isRecord(content)) {
+        return undefined;
+    }
+    const mediaType = ["application/json", "application/xml", "application/x-www-form-urlencoded"].find((type) => isRecord(content[type]?.schema)) ?? Object.keys(content).find((type) => isRecord(content[type]?.schema));
+    if (!mediaType) {
+        return undefined;
+    }
+    return content[mediaType].schema;
+}
+function resolveSchema(schema, openApi) {
+    if (typeof schema.$ref !== "string") {
+        return schema;
+    }
+    const pointer = schema.$ref.replace(/^#\//, "").split("/");
+    let current = openApi;
+    for (const segment of pointer) {
+        current = current?.[segment.replace(/~1/g, "/").replace(/~0/g, "~")];
+    }
+    if (!isRecord(current)) {
+        throw new Error(`Unable to resolve OpenAPI reference ${schema.$ref}`);
+    }
+    return current;
+}
+function scalarTypeFor(schema) {
+    if (schema.type === "integer") {
+        return "integer";
+    }
+    if (schema.type === "number") {
+        return "decimal";
+    }
+    if (schema.type === "boolean") {
+        return "boolean";
+    }
+    if (schema.type === "string" && schema.format === "date-time") {
+        return "datetime";
+    }
+    if (schema.type === "string" && schema.format === "date") {
+        return "date";
+    }
+    if (schema.type === "string" && schema.format === "time") {
+        return "time";
+    }
+    return "string";
+}
+function enumNameFor(ownerName, fieldName) {
+    if (fieldName.toLowerCase() === "status") {
+        return `${pascalCase(ownerName)}Status`;
+    }
+    return `${pascalCase(ownerName)}${pascalCase(fieldName)}`;
+}
+function refTail(ref) {
+    return ref.split("/").at(-1) ?? ref;
+}
+function slugify(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/[^a-zA-Z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .toLowerCase();
+}
+function pascalCase(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[^a-zA-Z0-9]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/src/reconcile/index.js

@@ -0,0 +1,46 @@
+const ADAPTER_OWNED = new Set(['method', 'path', 'operationId', 'type', 'nullable', 'cardinality', '$ref']);
+const HUMAN_OWNED = new Set(['state', 'stability', 'notes']);
+export function diffNodes(incoming, existing, specPath) {
+    const toAdd = [];
+    const toUpdate = [];
+    const incomingIds = new Set(incoming.map(n => n.id));
+    for (const node of incoming) {
+        const current = existing.get(node.id);
+        if (!current) {
+            toAdd.push(node);
+            continue;
+        }
+        const merged = {
+            ...current,
+            properties: mergeProperties(current.properties, node.properties),
+            extractedFrom: node.extractedFrom,
+            derivation: node.derivation,
+            derivedBy: node.derivedBy,
+            lastModifiedAt: node.lastModifiedAt,
+            state: current.state,
+            stability: current.stability,
+        };
+        if (!nodesEqual(current, merged)) {
+            toUpdate.push(merged);
+        }
+    }
+    const toRemove = [];
+    for (const [id, node] of existing) {
+        if (node.extractedFrom === specPath && !incomingIds.has(id)) {
+            toRemove.push({ ...node, state: 'removed' });
+        }
+    }
+    return { toAdd, toUpdate, toRemove };
+}
+function mergeProperties(current, incoming) {
+    const merged = { ...current };
+    for (const [key, value] of Object.entries(incoming)) {
+        if (ADAPTER_OWNED.has(key)) {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+function nodesEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}

package/dist/src/schema/index.js

@@ -0,0 +1,16 @@
+export class LoadError extends Error {
+    diagnostics;
+    constructor(diagnostics) {
+        const errorCount = diagnostics.filter(d => d.severity === 'error').length;
+        super(`Graph load failed with ${errorCount} error(s)`);
+        this.diagnostics = diagnostics;
+        this.name = 'LoadError';
+    }
+}
+export class QueryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'QueryError';
+    }
+}
+export { SourceError } from '../source/index.js';

package/dist/src/source/config-file.js

@@ -0,0 +1,22 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+export function loadProjectConfig(cwd) {
+    const configPath = findConfigFile(cwd);
+    if (!configPath)
+        return {};
+    const content = readFileSync(configPath, 'utf8');
+    return parseYaml(content) ?? {};
+}
+function findConfigFile(cwd) {
+    let dir = cwd;
+    while (true) {
+        const candidate = path.join(dir, '.corum', 'config.yaml');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}

package/dist/src/source/config.js

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import { FileGraphSource } from './file-source.js';
+import { GitGraphSource } from './git-source.js';
+import { SourceError } from './index.js';
+import { loadProjectConfig } from './config-file.js';
+export function createGraphRuntimeConfig(env = process.env, cwd = process.cwd()) {
+    const fileConfig = loadProjectConfig(cwd);
+    const e = {
+        ...env,
+        CORUM_SOURCE: env.CORUM_SOURCE ?? fileConfig.source,
+        CORUM_GRAPH_PATH: env.CORUM_GRAPH_PATH ?? fileConfig.graph,
+        CORUM_GIT_LOCAL_PATH: env.CORUM_GIT_LOCAL_PATH ?? fileConfig.git_local_path,
+        CORUM_GIT_REMOTE_URL: env.CORUM_GIT_REMOTE_URL ?? fileConfig.git_remote_url,
+        CORUM_GIT_BRANCH: env.CORUM_GIT_BRANCH ?? fileConfig.git_branch,
+        CORUM_GIT_POLL_SECONDS: env.CORUM_GIT_POLL_SECONDS ?? (fileConfig.git_poll_seconds !== undefined ? String(fileConfig.git_poll_seconds) : undefined),
+        CORUM_GIT_TOKEN: env.CORUM_GIT_TOKEN ?? fileConfig.git_token,
+        CORUM_GIT_USERNAME: env.CORUM_GIT_USERNAME ?? fileConfig.git_username,
+    };
+    const sourceKind = (e.CORUM_SOURCE ?? 'filesystem').toLowerCase();
+    if (sourceKind === 'filesystem' || sourceKind === 'file' || sourceKind === 'fs') {
+        const graphPath = e.CORUM_GRAPH_PATH ?? path.join(cwd, '.corum/graph');
+        return {
+            kind: 'filesystem',
+            source: new FileGraphSource({ graphDir: graphPath }),
+            graphPath,
+            fileWatcherGraphPath: graphPath,
+        };
+    }
+    if (sourceKind !== 'git') {
+        throw new SourceError(`unsupported CORUM_SOURCE: ${e.CORUM_SOURCE}`);
+    }
+    const localPath = emptyToUndefined(e.CORUM_GIT_LOCAL_PATH);
+    const remoteUrl = emptyToUndefined(e.CORUM_GIT_REMOTE_URL);
+    if (!localPath && !remoteUrl) {
+        throw new SourceError('CORUM_SOURCE=git requires CORUM_GIT_LOCAL_PATH or CORUM_GIT_REMOTE_URL');
+    }
+    if (localPath && remoteUrl) {
+        throw new SourceError('CORUM_SOURCE=git requires only one of CORUM_GIT_LOCAL_PATH or CORUM_GIT_REMOTE_URL');
+    }
+    const graphDir = '.corum/graph';
+    const token = emptyToUndefined(e.CORUM_GIT_TOKEN);
+    const auth = token
+        ? { username: e.CORUM_GIT_USERNAME ?? 'x-access-token', token }
+        : undefined;
+    const repoLabel = localPath ?? remoteUrl;
+    const gitPollSeconds = parseOptionalSeconds(e.CORUM_GIT_POLL_SECONDS);
+    return {
+        kind: 'git',
+        source: new GitGraphSource({
+            localPath,
+            remoteUrl,
+            graphDir,
+            defaultBranch: emptyToUndefined(e.CORUM_GIT_BRANCH),
+            auth,
+        }),
+        graphPath: `git:${repoLabel}/${graphDir.replace(/\\/g, '/')}`,
+        gitPollSeconds,
+    };
+}
+function emptyToUndefined(value) {
+    return value && value.trim() !== '' ? value : undefined;
+}
+function parseOptionalSeconds(value) {
+    if (!value || value.trim() === '')
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new SourceError('CORUM_GIT_POLL_SECONDS must be a positive number of seconds');
+    }
+    return parsed;
+}

package/dist/src/source/content-utils.js

@@ -0,0 +1,13 @@
+export function listYamlKeys(content, prefix) {
+    const normalised = prefix && !prefix.endsWith('/') ? `${prefix}/` : prefix;
+    return [...content.keys()].filter(key => key.endsWith('.yaml') && (normalised === '' || key.startsWith(normalised)));
+}
+export function readYaml(content, key) {
+    const value = content.get(key);
+    if (value === undefined)
+        throw new Error(`${key} not found in ContentMap`);
+    return value;
+}
+export function hasKey(content, key) {
+    return content.has(key);
+}

package/dist/src/source/file-source.js

@@ -0,0 +1,135 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as git from 'isomorphic-git';
+import { parse as parseYaml } from 'yaml';
+import { isPackRef } from '../loader/fs-utils.js';
+import { SourceError } from './index.js';
+const DEFAULT_GRAPH_DIR = '.corum/graph';
+const DEFAULT_PACKS_PATH = '.corum/packs';
+export class FileGraphSource {
+    graphDir;
+    defaultBranchOverride;
+    packsPath;
+    constructor(options = {}) {
+        this.graphDir = options.graphDir ?? DEFAULT_GRAPH_DIR;
+        this.defaultBranchOverride = options.defaultBranch;
+        this.packsPath = options.packsPath;
+    }
+    async defaultBranch() {
+        if (this.defaultBranchOverride)
+            return this.defaultBranchOverride;
+        try {
+            const repoRoot = await git.findRoot({ fs, filepath: this.graphDir });
+            const branch = await git.currentBranch({ fs, dir: repoRoot });
+            if (branch)
+                return branch;
+        }
+        catch {
+            // Not a git repo, or detached HEAD.
+        }
+        return 'main';
+    }
+    async listBranches() {
+        return [await this.defaultBranch()];
+    }
+    async loadPackContent(_ref) {
+        const map = new Map();
+        const graphYamlPath = path.join(this.graphDir, 'graph.yaml');
+        if (!existsSync(graphYamlPath)) {
+            const packDir = path.resolve(this.graphDir, this.packsPath ?? DEFAULT_PACKS_PATH);
+            readPackTemplatesIntoMap(packDir, map);
+            return map;
+        }
+        const doc = parseYaml(readFileSync(graphYamlPath, 'utf-8'));
+        const packs = Array.isArray(doc.templatePacks) ? doc.templatePacks : [];
+        for (const pack of packs) {
+            if (!isPackRef(pack))
+                continue;
+            const packDir = path.resolve(this.graphDir, pack.path);
+            readPackTemplatesIntoMap(packDir, map);
+        }
+        return map;
+    }
+    async loadGraphContent(_ref) {
+        const map = new Map();
+        if (!existsSync(this.graphDir))
+            return map;
+        const excludeDirs = new Set(this.resolvePackDirs().map(d => path.resolve(d)));
+        walkYamlFilesIntoMap(this.graphDir, this.graphDir, map, excludeDirs);
+        return map;
+    }
+    resolvePackDirs() {
+        const graphYamlPath = path.join(this.graphDir, 'graph.yaml');
+        if (!existsSync(graphYamlPath)) {
+            return [path.resolve(this.graphDir, this.packsPath ?? DEFAULT_PACKS_PATH)];
+        }
+        try {
+            const doc = parseYaml(readFileSync(graphYamlPath, 'utf-8'));
+            const packs = Array.isArray(doc.templatePacks) ? doc.templatePacks : [];
+            return packs.filter(isPackRef).map(p => path.resolve(this.graphDir, p.path));
+        }
+        catch {
+            return [];
+        }
+    }
+    async commit(branch, changes, _message, options = {}) {
+        const defaultBranch = await this.defaultBranch();
+        if (branch !== defaultBranch) {
+            throw new SourceError(`FileGraphSource only supports its local branch '${defaultBranch}', got '${branch}'`);
+        }
+        if (options.replaceGraphContent && existsSync(this.graphDir)) {
+            rmSync(this.graphDir, { recursive: true, force: true });
+        }
+        for (const [key, content] of changes) {
+            const filePath = resolveContentPath(this.graphDir, key);
+            mkdirSync(path.dirname(filePath), { recursive: true });
+            writeFileSync(filePath, content);
+        }
+        // TODO: create a git commit for these changes via git.add() + git.commit().
+        // Currently _message is unused — file writes are persisted but not committed to git history.
+    }
+}
+function readPackTemplatesIntoMap(packDir, map) {
+    if (!existsSync(packDir))
+        return;
+    const packName = path.basename(packDir);
+    const packContent = new Map();
+    walkYamlFilesIntoMap(packDir, packDir, packContent);
+    for (const [relKey, content] of packContent) {
+        map.set(`${packName}/${relKey}`, content);
+    }
+}
+function resolveContentPath(baseDir, key) {
+    if (key.includes('\\') ||
+        key.includes('\0') ||
+        path.posix.isAbsolute(key) ||
+        path.win32.isAbsolute(key)) {
+        throw new SourceError(`invalid ContentMap key: ${key}`);
+    }
+    const normalised = path.posix.normalize(key);
+    if (normalised === '..' || normalised.startsWith('../') || normalised === '.') {
+        throw new SourceError(`invalid ContentMap key: ${key}`);
+    }
+    const resolvedBase = path.resolve(baseDir);
+    const resolvedPath = path.resolve(resolvedBase, ...normalised.split('/'));
+    const relative = path.relative(resolvedBase, resolvedPath);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new SourceError(`ContentMap key escapes graphDir: ${key}`);
+    }
+    return resolvedPath;
+}
+function walkYamlFilesIntoMap(baseDir, currentDir, map, excludeDirs = new Set()) {
+    for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+        const fullPath = path.join(currentDir, entry.name);
+        if (entry.isDirectory()) {
+            if (!excludeDirs.has(path.resolve(fullPath))) {
+                walkYamlFilesIntoMap(baseDir, fullPath, map, excludeDirs);
+            }
+        }
+        else if (entry.isFile() && entry.name.endsWith('.yaml')) {
+            const key = path.relative(baseDir, fullPath).split(path.sep).join('/');
+            map.set(key, readFileSync(fullPath, 'utf-8'));
+        }
+    }
+}

package/dist/src/source/git-cache.js

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import * as git from 'isomorphic-git';
+import { SourceError } from './index.js';
+const CACHE_BASE = path.join(os.homedir(), '.config', 'corum', 'cache');
+export class GitCacheManager {
+    cacheDir(remoteUrl) {
+        const hash = createHash('sha256').update(remoteUrl).digest('hex').slice(0, 16);
+        return path.join(CACHE_BASE, hash);
+    }
+    async ensureCloned(remoteUrl, onAuth) {
+        const dir = this.cacheDir(remoteUrl);
+        mkdirSync(dir, { recursive: true });
+        if (!existsSync(path.join(dir, '.git'))) {
+            await clone(remoteUrl, dir, onAuth);
+            return dir;
+        }
+        try {
+            await git.fetch({
+                fs,
+                http: (await import('isomorphic-git/http/node')).default,
+                dir,
+                remote: 'origin',
+                singleBranch: false,
+                onAuth,
+            });
+        }
+        catch {
+            rmSync(dir, { recursive: true, force: true });
+            mkdirSync(dir, { recursive: true });
+            await clone(remoteUrl, dir, onAuth, 'failed to recover cache');
+        }
+        return dir;
+    }
+}
+async function clone(remoteUrl, dir, onAuth, message = 'failed to clone') {
+    try {
+        await git.clone({
+            fs,
+            http: (await import('isomorphic-git/http/node')).default,
+            dir,
+            url: remoteUrl,
+            noCheckout: true,
+            singleBranch: false,
+            onAuth,
+        });
+    }
+    catch (err) {
+        throw new SourceError(`${message} ${remoteUrl}`, err);
+    }
+}