@atolis-hq/corum 0.1.51 → 0.1.53

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -89,394 +89,14 @@ If you only want the web UI:
89
89
  corum web
90
90
  ```
91
91
 
92
- ## Commands
93
-
94
- ### `corum mcp`
95
-
96
- Start the MCP stdio server. Also starts a web UI by default.
97
-
98
- ```bash
99
- corum mcp [options]
100
-
101
- Options:
102
- --no-web Suppress the web UI
103
- --watch Reload file-backed graphs on local file changes
104
- --graph <path> Override the graph directory
105
- ```
106
-
107
- Notes:
108
- - `corum mcp` starts the web UI unless you pass `--no-web`.
109
- - `--watch` applies to filesystem graphs. Git-backed graphs reload through polling instead.
110
-
111
- ### `corum web`
112
-
113
- Start the web UI only.
114
-
115
- ```bash
116
- corum web [options]
117
-
118
- Options:
119
- --port <n> Port to listen on (default: 3000)
120
- --graph <path> Override the graph directory
121
- ```
122
-
123
- Notes:
124
- - Filesystem graphs can be watched for local YAML changes with `CORUM_FILE_WATCHER=true` or `CORUM_WATCH=true`.
125
- - Git-backed graphs reload through polling when `git_poll_seconds` / `CORUM_GIT_POLL_SECONDS` is set.
126
-
127
- ### `corum lint`
128
-
129
- Lint the graph and report diagnostics.
130
-
131
- ```bash
132
- corum lint [options]
133
-
134
- Options:
135
- --graph <path> Override the graph directory
136
- ```
137
-
138
- ### `corum init`
139
-
140
- Scaffold a `.corum/` project structure and install the four default template packs (`core`, `domain`, `rest`, `messaging`). Skips any step where the target already exists.
141
-
142
- ```bash
143
- corum init
144
- ```
145
-
146
- Creates:
147
- - `.corum/config.yaml` - project configuration
148
- - `.corum/graph/graph.yaml` - graph definition
149
- - `.corum/graph/components/` and `.corum/graph/edges/` - empty directories ready for nodes
150
- - `.corum/packs/` - downloaded template packs
151
- - `.corum/packs.yaml` - local manifest of installed packs
152
-
153
- ### `corum pack install`
154
-
155
- 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`.
156
-
157
- ```bash
158
- corum pack install <name> # install latest tag
159
- corum pack install <name>@<ref> # install a specific tag
160
- ```
161
-
162
- Examples:
163
-
164
- ```bash
165
- corum pack install domain
166
- corum pack install domain@v0.1.5
167
- corum pack install extract # required for corum-extract import adapter
168
- ```
169
-
170
- ### `corum pack list`
171
-
172
- List installed packs with their resolved version and install date.
173
-
174
- ```bash
175
- corum pack list
176
- ```
177
-
178
- ### `corum import`
179
-
180
- Import specifications into the graph.
181
-
182
- ```bash
183
- corum import --config <path> Import using a config YAML file
184
- ```
185
-
186
- #### Import config file
187
-
188
- The `--config` flag accepts a YAML file that can combine multiple imports in a single run and configure cross-adapter options:
189
-
190
- ```yaml
191
- # Optional: remap extracted component names before node IDs are built.
192
- # Useful when the same component appears under different names in different specs
193
- # (e.g. "order-shipping" from a URI segment vs "ordershipping" from a topic name).
194
- componentNameReplacements:
195
- - from: ordershipping
196
- to: order-shipping
197
-
198
- # Optional: deduplicate nodes emitted by different adapters after all imports
199
- # complete. For each rule, keep nodes from the primary adapter and merge/drop
200
- # matching nodes from the secondary adapter.
201
- deduplication:
202
- - primary: openapi
203
- secondary: corum
204
-
205
- imports:
206
- - adapter: openapi
207
- spec: ./specs/order-shipping.openapi.yaml
208
- componentMapping:
209
- strategy: uri-segment
210
- segment: 0
211
-
212
- - adapter: asyncapi
213
- spec: ./specs/order-shipping.asyncapi.yaml
214
- componentMapping:
215
- strategy: channel-segment
216
- separator: "."
217
- segment: 0
218
- messageNaming:
219
- strategy: name-segment
220
- separator: "."
221
- segment: -1
222
- ```
223
-
224
- Replacements are applied in order; the first matching `from` wins. Unmatched names are passed through unchanged.
225
- Deduplication rules are applied after all adapters finish. They are intended for
226
- cross-adapter reconciliation, for example keeping OpenAPI endpoints as canonical
227
- while merging matching extractor-emitted Corum nodes into them.
228
-
229
- #### `corum import openapi <spec>`
230
-
231
- Import an OpenAPI spec directly.
232
-
233
- ```bash
234
- corum import openapi <spec> [options]
235
-
236
- Options:
237
- --component-strategy <strategy> Component mapping: uri-segment (default), tag, hardcoded
238
- --segment <n> URI segment index (uri-segment strategy)
239
- --pattern <regex> Regex pattern (uri-segment strategy)
240
- --component <name> Component name (hardcoded strategy)
241
- --graph <path> Override the graph directory
242
- ```
243
-
244
- #### `corum import asyncapi <spec>`
245
-
246
- Import an AsyncAPI spec directly.
247
-
248
- ```bash
249
- corum import asyncapi <spec> [options]
250
-
251
- Options:
252
- --component-strategy <strategy> Component mapping: channel-segment (default), channel-pattern,
253
- name-segment, name-pattern, tag, hardcoded
254
- --separator <char> Separator for segment strategies (default: .)
255
- --segment <n> Segment index (negative counts from end)
256
- --pattern <regex> Regex pattern for pattern strategies
257
- --component <name> Component name (hardcoded strategy)
258
- --event-classification <mode> always-integration (default) or always-domain
259
- --include-consumed Also import receive (consumed) operations
260
- --graph <path> Override the graph directory
261
- ```
262
-
263
- #### `corum import corum <spec>`
264
-
265
- Import a corum interchange file (`*.corum.yaml`) produced by `corum-extract` or compatible extraction tooling.
266
-
267
- ```bash
268
- corum import corum <spec> [options]
269
-
270
- Options:
271
- --graph <path> Override the graph directory
272
- ```
273
-
274
- The interchange format is self-describing - no component mapping strategy is needed. Node IDs, template names, and field references are already corum-native. Gaps reported by the extractor (unresolved types, name collisions) are surfaced as warnings.
275
-
276
- Requires the `extract` pack to be active in your graph:
277
-
278
- ```bash
279
- corum pack install extract
280
- ```
281
-
282
- You can also configure corum imports in a config file:
283
-
284
- ```yaml
285
- # .corum/imports.yaml
286
- imports:
287
- - adapter: corum
288
- spec: path/to/output.corum.yaml
289
- ```
290
-
291
- ## Configuration
292
-
293
- Run `corum init` to generate a `.corum/config.yaml` with all available options. Corum walks up from the current directory to find it, so you can place it at your project root.
294
-
295
- **Precedence (highest to lowest):** CLI flags -> environment variables -> `.corum/config.yaml`
296
-
297
- | Config key | Environment variable | Description |
298
- |---|---|---|
299
- | `pack_registry` | - | URL of the pack registry YAML (set by `corum init`) |
300
- | `source` | `CORUM_SOURCE` | Source mode: `file` / `filesystem` / `fs` (default) or `git` |
301
- | `graph` | `CORUM_GRAPH_PATH` | Path to the graph directory |
302
- | `git_local_path` | `CORUM_GIT_LOCAL_PATH` | Local git repo path |
303
- | `git_remote_url` | `CORUM_GIT_REMOTE_URL` | Remote git repo URL |
304
- | `git_branch` | `CORUM_GIT_BRANCH` | Default branch ref used when loading a git-backed graph |
305
- | `git_poll_seconds` | `CORUM_GIT_POLL_SECONDS` | Poll interval, in seconds, for git-backed web reloads |
306
- | `git_token` | `CORUM_GIT_TOKEN` | Auth token for private repos |
307
- | `git_username` | `CORUM_GIT_USERNAME` | Auth username (default: `x-access-token`) |
308
-
309
- Additional environment-only runtime settings:
310
-
311
- | Environment variable | Description |
312
- |---|---|
313
- | `CORUM_WEB_PORT` | Default port for `corum web` |
314
- | `CORUM_FILE_WATCHER` | Enable local file watching for filesystem graphs when running the web UI |
315
- | `CORUM_WATCH` | Alias for `CORUM_FILE_WATCHER` |
316
-
317
- ### File source (default)
318
-
319
- ```yaml
320
- # .corum/config.yaml
321
- source: file
322
- graph: .corum/graph
323
- ```
324
-
325
- Use this when the graph lives directly on the local filesystem with no git source abstraction.
326
-
327
- ### Git source
328
-
329
- ```yaml
330
- # .corum/config.yaml
331
- source: git
332
- git_remote_url: https://github.com/org/design-repo
333
- git_branch: main
334
- git_poll_seconds: 30
335
- ```
336
-
337
- Or for a local git repository:
338
-
339
- ```yaml
340
- # .corum/config.yaml
341
- source: git
342
- git_local_path: /path/to/repo
343
- git_branch: main
344
- ```
345
-
346
- Rules:
347
- - Set exactly one of `git_local_path` or `git_remote_url`.
348
- - `git_branch` selects the default branch Corum loads for read operations and the web UI.
349
- - `git_poll_seconds` is only used for git-backed web reloads.
350
-
351
- For private repositories, set `CORUM_GIT_TOKEN` as an environment variable rather than storing it in the config file.
352
-
353
- ## MCP Client Configuration
354
-
355
- Configure your MCP client to run Corum. For Claude Code or Claude Desktop:
356
-
357
- ```json
358
- {
359
- "mcpServers": {
360
- "corum": {
361
- "command": "npx",
362
- "args": ["@atolis-hq/corum", "mcp", "--no-web"],
363
- "env": {
364
- "CORUM_GRAPH_PATH": "/path/to/your/graph"
365
- }
366
- }
367
- }
368
- }
369
- ```
370
-
371
- Or if installed globally:
372
-
373
- ```json
374
- {
375
- "mcpServers": {
376
- "corum": {
377
- "command": "corum",
378
- "args": ["mcp", "--no-web"],
379
- "env": {
380
- "CORUM_GRAPH_PATH": "/path/to/your/graph"
381
- }
382
- }
383
- }
384
- }
385
- ```
386
-
387
- ## MCP Tools
388
-
389
- | Tool | Description |
390
- |---|---|
391
- | `list_nodes` | List graph nodes using a `filter` object with `templates`, `exclude_templates`, `component`, `state`, and `stability` |
392
- | `list_templates` | List loaded templates with summary metadata |
393
- | `get_template` | Return full details for a template |
394
- | `get_cluster` | Return a node's structural contents. By default, schema and enum child nodes are collapsed into compact `schemas` and `enums` blocks on the root. Pass `collapse_schemas: false` to restore the full node-per-field representation |
395
- | `get_graph` | Return the semantic graph as `{ nodes, edges }`, excluding structural templates and structural edges by default |
396
- | `get_graph_metadata` | Return discoverable metadata: template names, node templates in use, edge types, and valid enum values |
397
- | `get_lineage` | Traverse lineage from one or more start nodes. Lean nodes and no `edges` by default; opt in to fuller payloads when needed |
398
- | `get_graph_summary` | Return high-level graph statistics: node count, component count, orphan breakdown, edge counts, diagnostics |
399
- | `search_nodes` | Fuzzy-search root-level nodes by ID, with optional template filters and property search |
400
- | `get_linked_fields` | Return `maps-to` edges touching fields owned by a root node |
401
- | `list_branches` | List available branches and their load status from the configured source |
402
- | `diff_branch` | Diff a branch against the default branch |
403
- | `start_changes` | Open a working mutation session |
404
- | `apply_cluster` | Upsert a cluster-style document in `merge` or `replace` mode |
405
- | `create_node` | Create a root cluster or owned child node |
406
- | `update_node` | Patch node properties, state, or stability |
407
- | `rename_node` | Rename a node while preserving identity trail metadata |
408
- | `delete_node` | Soft-delete or hard-delete a node subtree |
409
- | `create_edges` | Batch-create explicit edges as one atomic operation |
410
- | `update_edge` | Patch an explicit edge |
411
- | `delete_edge` | Delete an explicit edge |
412
- | `create_fields` | Batch-create fields across schemas (grouped and applied per parent) |
413
- | `pending_changes` | Show the open session's journal and summary diff |
414
- | `discard_changes` | Abort the working session |
415
- | `commit_changes` | Lint, serialize, and persist the session's changes |
416
-
417
- All tools accept an optional `format` argument: `toon` (default; leanest for the LLM), `yaml`, or `json`. All tools also accept `compact_keys: true` to shorten common keys before serialization, reducing token usage further.
418
-
419
- All node-returning MCP tools accept `include_provenance: true` to include `extractedFrom`, `lastModifiedAt`, `derivation`, and `derivedBy`. These fields are omitted by default. `schemaVersion` is never returned by MCP.
420
-
421
- Common notes:
422
- - `branch` is supported on graph-query tools when Corum is running against a source-backed graph.
423
- - `list_nodes` is a breaking-change surface from older builds: use `filter.templates` instead of top-level `template`.
424
- - `search_nodes` accepts `queries: string[]`.
425
- - `get_graph_metadata` should usually be your first call. Use `edge_types_in_use` to avoid traversing edge types that do not exist in the current graph.
426
- - `get_graph_metadata` returns `valid_edge_types`, `states`, `stabilities`, `lineage_directions`, and `output_formats` when you pass `include_static_enums: true`.
427
- - Prefer `search_nodes` over `list_nodes` for discovery. Use `list_nodes` when you need a full inventory under explicit filters.
428
- - `get_lineage` accepts `node_ids: string[]`, `depth`, `direction`, `edge_types`, `node_types`, `exclude_node_types`, `include_dangling_edges`, `reads_outbound_only`, `lean`, and `include_edges`.
429
- - `get_lineage` defaults to `lean: true` and `include_edges: false`. Lean lineage nodes contain only `id`, `origin_id`, `depth`, `via_edge_type`, and `via_node_id`.
430
- - Pass multiple `node_ids` to `get_lineage` in one call instead of making separate traversal calls.
431
- - Use `get_cluster` only when you need full structural contents for one node. By default it returns compact `schemas` and `enums` blocks on the root rather than individual field nodes, which keeps response size manageable for large aggregates. Use `get_lineage` for relationship traversal.
432
- - Read tools reflect the open working session while one exists. Unbranched reads, and branch-scoped reads for that same session branch, show uncommitted changes.
433
- - The graph reflects modeled relationships, not guaranteed complete truth. Missing edges do not prove no relationship exists; agents should treat naming and schema similarity as hypotheses and then verify via cluster inspection or source material.
434
-
435
- ## MCP Write Workflow
436
-
437
- Corum's write tools are session-based:
438
-
439
- 1. Call `start_changes`.
440
- 2. Make one or more mutations with `apply_cluster`, `create_node`, `update_node`, `rename_node`, `delete_node`, `create_edges`, `update_edge`, `delete_edge`, or `create_fields`.
441
- 3. Inspect the session with `pending_changes`.
442
- 4. Finish with `commit_changes` or abort with `discard_changes`.
443
-
444
- Important behavior:
445
- - No write tool works without an open session.
446
- - `rename_node` is the only rename path. `apply_cluster` and imports never infer renames.
447
- - `apply_cluster` `replace` mode is authoritative for the root's owned sections: absent children are deleted, and an absent owned section means "empty section".
448
- - `delete_node` defaults to soft delete for nodes that already exist on the default branch, and hard delete for branch-local design work.
449
- - `discard_changes` closes the session. On file-backed autosave sessions it does not roll back mutations already written through to disk.
450
-
451
- Source-mode defaults:
452
- - Filesystem source: `start_changes` defaults `autosave` on. Each mutation writes through immediately; `commit_changes` mainly lint-gates and closes the session.
453
- - Git source: `start_changes` defaults `autosave` off. Changes stay in memory until `commit_changes`.
454
- - Git source with `autosave: true`: each mutation creates a `corum-wip:` checkpoint commit; `commit_changes` squashes that run when no external commit interleaved.
455
-
456
- Typical sequence:
457
-
458
- ```yaml
459
- start_changes:
460
- branch: feat/order-design
461
- create: true
462
-
463
- rename_node:
464
- id: orders.Schema.invoice
465
- new_name: bill
466
-
467
- pending_changes: {}
468
-
469
- commit_changes:
470
- message: rename invoice schema to bill
471
- ```
472
-
473
- ## MCP Prompts
474
-
475
- The server also exposes a discoverable MCP prompt:
476
-
477
- | Prompt | Description |
478
- |---|---|
479
- | `usage-guide` | Orientation guide covering graph structure, read and write workflow, output-format choices, graph-completeness caveats, and inference guidance |
92
+ ## Documentation
93
+
94
+ - [Getting started](docs/getting-started.md) - install, initialise, connect an agent
95
+ - [Concepts](docs/concepts.md) - nodes, edges, clusters, IDs, lineage, branches
96
+ - [Templates and packs](docs/templates-and-packs.md) - defining and extending node types
97
+ - [Importing](docs/importing.md) - OpenAPI, AsyncAPI and extractor output
98
+ - [Working with agents](docs/working-with-agents.md) - reading and changing the graph
99
+ - [MCP tools](docs/mcp-tools.md), [CLI](docs/cli.md), [Configuration](docs/configuration.md) - reference
480
100
 
481
101
  ## Contributing
482
102
 
@@ -13,7 +13,7 @@ import { getTemplateSchema } from '../loader/template-props.js';
13
13
  * in memory (mutations): the loader drops such edges before they ever reach
14
14
  * a loaded Graph, so `strict` loads are unaffected in practice.
15
15
  *
16
- * Rules implemented (see docs/adr/REF-006-rules.md for the full catalogue):
16
+ * Rules implemented (see project/adrs/REF-006-rules.md for the full catalogue):
17
17
  * - T-003/T-004/T-005: node properties validated (shallow) against the
18
18
  * owning template's JSON-schema-like `properties` block.
19
19
  * - E-005/E-006: explicit (non-generated) edges validated against the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atolis-hq/corum",
3
- "version": "0.1.51",
3
+ "version": "0.1.53",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",