@atolis-hq/corum 0.1.6 → 0.1.8

package/README.md

@@ -30,13 +30,13 @@ npm update -g @atolis-hq/corum
 
 ## Quick Start
 
-Scaffold a config file in your project:
+Scaffold a new project in the current directory:
 
 ```bash
 corum init
 ```
 
-This creates `.corum/config.yaml` with commented defaults. Edit it to point at your graph directory or git repository, then start the MCP server:
+This creates `.corum/config.yaml`, scaffolds a graph at `.corum/graph/`, and downloads the official template packs (`core`, `domain`, `rest`, `messaging`). Then start the MCP server:
 
 ```bash
 corum mcp
@@ -71,12 +71,43 @@ Options:
 
 ### `corum init`
 
-Scaffold `.corum/config.yaml` with commented defaults. Does not overwrite an existing file.
+Scaffold a `.corum/` project structure and install the four default template packs (`core`, `domain`, `rest`, `messaging`). Skips any step where the target already exists.
 
 ```bash
 corum init
 ```
 
+Creates:
+- `.corum/config.yaml` - project configuration
+- `.corum/graph/graph.yaml` - graph definition
+- `.corum/graph/components/` and `.corum/graph/edges/` - empty directories ready for nodes
+- `.corum/packs/` - downloaded template packs
+- `.corum/packs.yaml` - local manifest of installed packs
+
+### `corum pack install`
+
+Install a template pack from the registry into `.corum/packs/`. Appends the pack to `.corum/graph/graph.yaml` and records it in `.corum/packs.yaml`.
+
+```bash
+corum pack install <name>          # install latest tag
+corum pack install <name>@<ref>    # install a specific tag
+```
+
+Examples:
+
+```bash
+corum pack install domain
+corum pack install domain@v0.1.5
+```
+
+### `corum pack list`
+
+List installed packs with their resolved version and install date.
+
+```bash
+corum pack list
+```
+
 ### `corum import`
 
 Import specifications into the graph.
@@ -108,6 +139,7 @@ Run `corum init` to generate a `.corum/config.yaml` with all available options.
 
 | Config key | Environment variable | Description |
 |---|---|---|
+| `pack_registry` | - | URL of the pack registry YAML (set by `corum init`) |
 | `source` | `CORUM_SOURCE` | `file` (default) or `git` |
 | `graph` | `CORUM_GRAPH_PATH` | Path to the graph directory |
 | `git_local_path` | `CORUM_GIT_LOCAL_PATH` | Local git repo path |

package/dist/src/bin/corum.js

@@ -1,11 +1,18 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { readFile as fsReadFile } from 'node:fs/promises';
 import path from 'node:path';
-import { loadImportConfig, buildOpenAPIConfig } from '../import/config.js';
+import { parse as parseYaml } from 'yaml';
+import { buildOpenAPIConfig, loadImportConfig } from '../import/config.js';
 import { runImport } from '../import/runner.js';
 import { loadGraph } from '../loader/index.js';
 import { startMcpServer } from '../mcp/index.js';
+import { parseGitHubRepo, toPackRawBaseUrl } from '../pack/github-urls.js';
+import { registerPackInGraph } from '../pack/graph-yaml.js';
+import { installPackFiles } from '../pack/installer.js';
+import { readManifest, upsertPack } from '../pack/manifest.js';
+import { fetchRegistry, findPack, resolveRef } from '../pack/registry.js';
 import { createGraphRuntimeConfig } from '../source/config.js';
 import { startWebServer } from '../web/server.js';
 const program = new Command();
@@ -13,7 +20,6 @@ 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)')
@@ -25,7 +31,6 @@ program
         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')
@@ -49,21 +54,23 @@ program
         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.
 
+# Registry URL for discovering and installing template packs.
+pack_registry: https://github.com/atolis-hq/corum/packs/registry.yaml
+
 # Source type: 'file' (default) or 'git'
 # Maps to: CORUM_SOURCE
 # source: file
 
-# ── File source (default) ─────────────────────────────────────────────────────
+# File source (default)
 # Local path to the graph directory.
 # Maps to: CORUM_GRAPH_PATH
 # graph: .corum/graph
 
-# ── Git source ────────────────────────────────────────────────────────────────
+# Git source
 # Uncomment 'source: git' above and configure one of the following:
 
 # Local path to a git repository containing the graph.
@@ -90,20 +97,47 @@ const CONFIG_TEMPLATE = `# Corum project configuration
 # Maps to: CORUM_GIT_USERNAME
 # git_username: x-access-token
 `;
+const GRAPH_TEMPLATE = `schema-version: '1.0'
+name: My Graph
+templatePacks: []
+components: []
+`;
 program
     .command('init')
-    .description('Scaffold .corum/config.yaml with commented defaults')
-    .action(() => {
-    const configPath = path.join(process.cwd(), '.corum', 'config.yaml');
+    .description('Scaffold .corum project structure and install default packs')
+    .action(async () => {
+    const cwd = process.cwd();
+    const corumDir = path.join(cwd, '.corum');
+    const configPath = path.join(corumDir, 'config.yaml');
+    const graphPath = path.join(corumDir, 'graph', 'graph.yaml');
     if (existsSync(configPath)) {
-        process.stdout.write(`.corum/config.yaml already exists — not overwriting\n`);
-        return;
+        process.stdout.write('.corum/config.yaml already exists - not overwriting\n');
+    }
+    else {
+        mkdirSync(path.dirname(configPath), { recursive: true });
+        writeFileSync(configPath, CONFIG_TEMPLATE);
+        process.stdout.write('Created .corum/config.yaml\n');
+    }
+    if (existsSync(graphPath)) {
+        process.stdout.write('.corum/graph/graph.yaml already exists - not overwriting\n');
+    }
+    else {
+        mkdirSync(path.dirname(graphPath), { recursive: true });
+        writeFileSync(graphPath, GRAPH_TEMPLATE);
+        mkdirSync(path.join(corumDir, 'graph', 'components'), { recursive: true });
+        mkdirSync(path.join(corumDir, 'graph', 'edges'), { recursive: true });
+        process.stdout.write('Created .corum/graph/graph.yaml\n');
+    }
+    for (const packName of ['core', 'domain', 'rest', 'messaging']) {
+        try {
+            await installPack(packName, cwd);
+        }
+        catch (err) {
+            process.stderr.write(`[ERROR] Failed to install pack ${packName}: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
     }
-    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')
@@ -148,6 +182,38 @@ importCmd
         process.exit(2);
     }
 });
+const packCmd = program.command('pack').description('Manage template packs');
+packCmd
+    .command('install <name>')
+    .description('Install a pack from the registry (e.g. core, domain@v0.1.5)')
+    .action(async (name) => {
+    try {
+        await installPack(name);
+    }
+    catch (err) {
+        process.stderr.write(`[ERROR] ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+});
+packCmd
+    .command('list')
+    .description('List installed packs')
+    .action(async () => {
+    try {
+        const manifest = await readManifest(path.join(process.cwd(), '.corum', 'packs.yaml'));
+        if (manifest.packs.length === 0) {
+            process.stdout.write('No packs installed. Run: corum pack install <name>\n');
+            return;
+        }
+        for (const p of manifest.packs) {
+            process.stdout.write(`${p.name}@${p.ref}  (${p.installedAt})\n`);
+        }
+    }
+    catch (err) {
+        process.stderr.write(`[ERROR] ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+});
 function buildRuntimeConfig(graphOverride) {
     if (graphOverride)
         process.env.CORUM_GRAPH_PATH = path.resolve(graphOverride);
@@ -162,4 +228,33 @@ function reportDiagnostics(diagnostics) {
     const warnings = diagnostics.filter(d => d.severity === 'warning').length;
     process.stdout.write(`Import complete. ${errors} error(s), ${warnings} warning(s).\n`);
 }
+async function readPackRegistryUrl(cwd) {
+    const configPath = path.join(cwd, '.corum', 'config.yaml');
+    const text = await fsReadFile(configPath, 'utf8');
+    const config = parseYaml(text);
+    if (!config.pack_registry)
+        throw new Error('pack_registry not set in .corum/config.yaml - run corum init first');
+    return config.pack_registry;
+}
+export async function installPack(nameWithRef, cwd = process.cwd()) {
+    const atIdx = nameWithRef.indexOf('@');
+    const name = atIdx >= 0 ? nameWithRef.slice(0, atIdx) : nameWithRef;
+    const specifiedRef = atIdx >= 0 ? nameWithRef.slice(atIdx + 1) : undefined;
+    const registryUrl = await readPackRegistryUrl(cwd);
+    const registry = await fetchRegistry(registryUrl);
+    const pack = findPack(registry, name);
+    const { owner, repo } = parseGitHubRepo(pack.repo);
+    const ref = await resolveRef(owner, repo, specifiedRef);
+    const baseUrl = toPackRawBaseUrl(owner, repo, ref, pack.path);
+    await installPackFiles(baseUrl, path.join(cwd, '.corum', 'packs', name));
+    await upsertPack(path.join(cwd, '.corum', 'packs.yaml'), {
+        name,
+        repo: pack.repo,
+        path: pack.path,
+        ref,
+        installedAt: new Date().toISOString(),
+    });
+    await registerPackInGraph(path.join(cwd, '.corum', 'graph', 'graph.yaml'), name, `../packs/${name}`);
+    process.stdout.write(`Installed pack: ${name}@${ref}\n`);
+}
 program.parse();

package/dist/src/pack/github-urls.js

@@ -0,0 +1,30 @@
+export function parseGitHubUrl(url) {
+    const u = new URL(url);
+    if (u.hostname !== 'github.com')
+        throw new Error(`Not a github.com URL: ${url}`);
+    const segments = u.pathname.replace(/^\//, '').split('/').filter(Boolean);
+    if (segments.length < 3)
+        throw new Error(`Missing path in GitHub URL: ${url}`);
+    const [owner, repo, ...rest] = segments;
+    return { owner, repo, path: rest.join('/') };
+}
+export function parseGitHubRepo(repoUrl) {
+    const u = new URL(repoUrl);
+    if (u.hostname !== 'github.com')
+        throw new Error(`Not a github.com URL: ${repoUrl}`);
+    const segments = u.pathname.replace(/^\//, '').split('/').filter(Boolean);
+    if (segments.length < 2)
+        throw new Error(`Missing repository in GitHub URL: ${repoUrl}`);
+    const [owner, repo] = segments;
+    return { owner, repo };
+}
+export function toRegistryFetchUrl(configUrl) {
+    const { owner, repo, path } = parseGitHubUrl(configUrl);
+    return `https://raw.githubusercontent.com/${owner}/${repo}/HEAD/${path}`;
+}
+export function toPackRawBaseUrl(owner, repo, ref, packPath) {
+    return `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${packPath}`;
+}
+export function toTagsApiUrl(owner, repo) {
+    return `https://api.github.com/repos/${owner}/${repo}/tags?per_page=1`;
+}

package/dist/src/pack/graph-yaml.js

@@ -0,0 +1,12 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { parse, stringify } from 'yaml';
+export async function registerPackInGraph(graphYamlPath, packName, relativePath) {
+    const text = await readFile(graphYamlPath, 'utf8');
+    const graph = parse(text);
+    if (!Array.isArray(graph.templatePacks))
+        graph.templatePacks = [];
+    if (graph.templatePacks.some(p => p.name === packName))
+        return;
+    graph.templatePacks.push({ name: packName, path: relativePath });
+    await writeFile(graphYamlPath, stringify(graph));
+}

package/dist/src/pack/installer.js

@@ -0,0 +1,29 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parse } from 'yaml';
+export async function installPackFiles(baseUrl, destDir, fetchFn = fetch) {
+    const packYamlUrl = `${baseUrl}/pack.yaml`;
+    const packRes = await fetchFn(packYamlUrl);
+    if (!packRes.ok)
+        throw new Error(`Failed to fetch pack.yaml: ${packRes.status} ${packRes.statusText}`);
+    const packText = await packRes.text();
+    const meta = parse(packText);
+    await mkdir(path.join(destDir, 'templates'), { recursive: true });
+    await writeFile(path.join(destDir, 'pack.yaml'), packText);
+    for (const templateName of meta.templates) {
+        const templateUrl = `${baseUrl}/templates/${templateName}.yaml`;
+        const res = await fetchFn(templateUrl);
+        if (!res.ok)
+            throw new Error(`Failed to fetch template ${templateName}: ${res.status} ${res.statusText}`);
+        await writeFile(path.join(destDir, 'templates', `${templateName}.yaml`), await res.text());
+    }
+    for (const filePath of meta.files ?? []) {
+        const fileUrl = `${baseUrl}/${filePath}`;
+        const res = await fetchFn(fileUrl);
+        if (!res.ok)
+            throw new Error(`Failed to fetch file ${filePath}: ${res.status} ${res.statusText}`);
+        const dest = path.join(destDir, filePath);
+        await mkdir(path.dirname(dest), { recursive: true });
+        await writeFile(dest, await res.text());
+    }
+}

package/dist/src/pack/manifest.js

@@ -0,0 +1,26 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parse, stringify } from 'yaml';
+export async function readManifest(manifestPath) {
+    try {
+        const text = await readFile(manifestPath, 'utf8');
+        return parse(text) ?? { packs: [] };
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { packs: [] };
+        throw err;
+    }
+}
+export async function upsertPack(manifestPath, entry) {
+    const manifest = await readManifest(manifestPath);
+    const idx = manifest.packs.findIndex(p => p.name === entry.name);
+    if (idx >= 0) {
+        manifest.packs[idx] = entry;
+    }
+    else {
+        manifest.packs.push(entry);
+    }
+    await mkdir(path.dirname(manifestPath), { recursive: true });
+    await writeFile(manifestPath, stringify(manifest));
+}

package/dist/src/pack/registry.js

@@ -0,0 +1,29 @@
+import { parse } from 'yaml';
+import { toRegistryFetchUrl, toTagsApiUrl } from './github-urls.js';
+export async function fetchRegistry(configUrl, fetchFn = fetch) {
+    const rawUrl = toRegistryFetchUrl(configUrl);
+    const res = await fetchFn(rawUrl);
+    if (!res.ok)
+        throw new Error(`Failed to fetch registry: ${res.status} ${res.statusText}`);
+    return parse(await res.text());
+}
+export function findPack(registry, name) {
+    const pack = registry.packs.find(p => p.name === name);
+    if (!pack) {
+        const available = registry.packs.map(p => p.name).join(', ');
+        throw new Error(`Pack "${name}" not found in registry. Available: ${available}`);
+    }
+    return pack;
+}
+export async function resolveRef(owner, repo, specifiedRef, fetchFn = fetch) {
+    if (specifiedRef)
+        return specifiedRef;
+    const url = toTagsApiUrl(owner, repo);
+    const res = await fetchFn(url);
+    if (!res.ok)
+        throw new Error(`Failed to resolve latest tag: ${res.status} ${res.statusText}`);
+    const data = await res.json();
+    if (data.length === 0 || !data[0].name)
+        throw new Error(`Failed to resolve latest tag: no tags found for ${owner}/${repo}`);
+    return data[0].name;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolis-hq/corum",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "type": "module",
   "repository": {
     "type": "git",