@atolis-hq/corum 0.1.39 → 0.1.41

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.
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Node ID grammar — defined once, enforced in the loader and adapters.
3
+ *
4
+ * IDs are dot-separated segments encoding the ownership hierarchy:
5
+ * {component}.{Template}.{name}(.{section}.{localName})*
6
+ *
7
+ * Reserved:
8
+ * - `.` separates segments (never appears inside one).
9
+ * - `__` separates edge ID parts ({from}__{type}__{to}), so it must never
10
+ * appear inside a node ID segment.
11
+ *
12
+ * Segments are non-empty runs of ASCII letters, digits, `_`, and `-`
13
+ * (`__` remains reserved — see the explicit check). Leading `_` marks
14
+ * generated quarantine components such as `_unresolved`.
15
+ */
16
+ export const ID_SEGMENT_RE = /^[A-Za-z0-9_-]+$/;
17
+ /** Minimum segments for a cluster root: component.Template.name */
18
+ export const MIN_ROOT_SEGMENTS = 3;
19
+ /** Returns an error message, or null when the id is well-formed. */
20
+ export function validateNodeId(id) {
21
+ const segments = id.split('.');
22
+ for (const segment of segments) {
23
+ if (segment === '') {
24
+ return `invalid node id '${id}': empty segment ('.' is the hierarchy separator)`;
25
+ }
26
+ if (segment.includes('__')) {
27
+ return `invalid node id '${id}': '__' is reserved for edge ids`;
28
+ }
29
+ if (!ID_SEGMENT_RE.test(segment)) {
30
+ return `invalid node id '${id}': segment '${segment}' must match ${ID_SEGMENT_RE}`;
31
+ }
32
+ }
33
+ return null;
34
+ }
35
+ /** Returns an error message, or null when the id is a well-formed cluster root id. */
36
+ export function validateRootId(id) {
37
+ const base = validateNodeId(id);
38
+ if (base)
39
+ return base;
40
+ if (id.split('.').length < MIN_ROOT_SEGMENTS) {
41
+ return `invalid cluster root id '${id}': expected at least ${MIN_ROOT_SEGMENTS} segments (component.Template.name)`;
42
+ }
43
+ return null;
44
+ }
45
+ /** Returns an error message, or null when the value is a valid single segment. */
46
+ export function validateSegment(segment) {
47
+ if (segment === '')
48
+ return `invalid id segment: empty`;
49
+ if (segment.includes('__'))
50
+ return `invalid id segment '${segment}': '__' is reserved for edge ids`;
51
+ if (!ID_SEGMENT_RE.test(segment)) {
52
+ return `invalid id segment '${segment}': must match ${ID_SEGMENT_RE}`;
53
+ }
54
+ return null;
55
+ }
56
+ /**
57
+ * Make an externally-sourced name (operationId, message name, schema name…)
58
+ * safe to use as a single ID segment. Deterministic: reserved characters
59
+ * become `-`, runs are collapsed, and leading/trailing `-` are trimmed.
60
+ */
61
+ export function sanitizeIdSegment(name) {
62
+ const cleaned = name
63
+ .replace(/[^A-Za-z0-9_-]+/g, '-')
64
+ .replace(/_{2,}/g, '_')
65
+ .replace(/-{2,}/g, '-')
66
+ .replace(/^[-_]+|[-_]+$/g, '');
67
+ return cleaned === '' ? 'unnamed' : cleaned;
68
+ }
@@ -4,7 +4,9 @@ import { LoadError, QueryError } from '../schema/index.js';
4
4
  import { computeDiff, computeOverlay } from '../graph/overlay.js';
5
5
  import { loadClusters } from './cluster-loader.js';
6
6
  import { loadEdges } from './edge-loader.js';
7
+ import { loadEdgeTypes } from './edge-type-loader.js';
7
8
  import { loadPacks } from './pack-loader.js';
9
+ import { lintGraph } from '../linter/index.js';
8
10
  export async function loadGraph(options) {
9
11
  const { strict = true } = options;
10
12
  const diagnostics = [];
@@ -16,9 +18,10 @@ export async function loadGraph(options) {
16
18
  const ref = options.ref ?? defaultRef;
17
19
  const packContent = await source.loadPackContent(defaultRef);
18
20
  const templates = loadPacks(packContent, diagnostics);
21
+ const edgeTypes = loadEdgeTypes(packContent, diagnostics);
19
22
  const graphContent = await source.loadGraphContent(ref);
20
23
  const clusterResult = loadClusters(graphContent, templates, diagnostics);
21
- const edgeResult = loadEdges(graphContent, clusterResult.nodes, diagnostics);
24
+ const edgeResult = loadEdges(graphContent, clusterResult.nodes, diagnostics, edgeTypes);
22
25
  const edgesByFrom = cloneEdgeMap(clusterResult.edgesByFrom);
23
26
  const edgesByTo = cloneEdgeMap(clusterResult.edgesByTo);
24
27
  mergeEdgeMaps(edgesByFrom, edgeResult.edgesByFrom);
@@ -28,9 +31,11 @@ export async function loadGraph(options) {
28
31
  edgesByFrom,
29
32
  edgesByTo,
30
33
  templates,
34
+ edgeTypes,
31
35
  diagnostics,
32
36
  sourceContent: graphContent,
33
37
  };
38
+ diagnostics.push(...lintGraph(graph));
34
39
  if (strict && diagnostics.some(d => d.severity === 'error')) {
35
40
  throw new LoadError(diagnostics);
36
41
  }
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Shared helper for resolving a template's flattened property-schema map.
3
+ *
4
+ * Templates express inheritance via nested `allOf` (see ADR-008): a
5
+ * template's `properties` block is either a plain JSON-schema-like object
6
+ * with a `properties` map, or an `allOf` array of such objects (accumulated
7
+ * from `extends` resolution at pack-load time). This walks that structure
8
+ * and merges all declared properties into a single flat map, keyed by
9
+ * property name.
10
+ *
11
+ * Used by both the cluster loader (to find node-ref targets) and the linter
12
+ * (to validate node properties against their owning template's schema).
13
+ */
14
+ export function getPropertySchemasFromTemplate(props) {
15
+ if (Array.isArray(props.allOf)) {
16
+ const merged = {};
17
+ for (const schema of props.allOf) {
18
+ Object.assign(merged, getPropertySchemasFromTemplate(schema));
19
+ }
20
+ return merged;
21
+ }
22
+ if (typeof props.properties === 'object' && props.properties !== null) {
23
+ return props.properties;
24
+ }
25
+ return {};
26
+ }
27
+ /**
28
+ * Merge a template's `properties` block (including its `allOf` inheritance
29
+ * chain) into a flat schema view: the combined property map, the union of
30
+ * all `required` lists, and whether unknown properties are disallowed
31
+ * anywhere in the chain. Used by the linter for shallow property validation.
32
+ */
33
+ export function getTemplateSchema(templateProperties) {
34
+ const properties = {};
35
+ const required = new Set();
36
+ let additionalProperties = true;
37
+ const walk = (props) => {
38
+ if (typeof props !== 'object' || props === null)
39
+ return;
40
+ const record = props;
41
+ if (Array.isArray(record.allOf)) {
42
+ for (const schema of record.allOf)
43
+ walk(schema);
44
+ return;
45
+ }
46
+ if (typeof record.properties === 'object' && record.properties !== null) {
47
+ Object.assign(properties, record.properties);
48
+ }
49
+ if (Array.isArray(record.required)) {
50
+ for (const name of record.required) {
51
+ if (typeof name === 'string')
52
+ required.add(name);
53
+ }
54
+ }
55
+ if (record.additionalProperties === false)
56
+ additionalProperties = false;
57
+ };
58
+ walk(templateProperties);
59
+ return { properties, required, additionalProperties };
60
+ }
@@ -3,27 +3,14 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
3
3
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
4
4
  import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
5
5
  import { pathToFileURL } from 'node:url';
6
- import { computeClusterOverlay, expandExternalNodes, getClusterView, getGraphSummary, getLineage, getLinkedFields, listNodes, SEMANTIC_EDGE_TYPES, searchNodes, STRUCTURAL_NODE_TEMPLATES, } from '../graph/index.js';
6
+ import { computeClusterOverlay, expandExternalNodes, getClusterView, getGraphSummary, getLineage, getLinkedFields, getStructuralNodeTemplates, getVisibleEdgeTypes, isVisibleEdgeType, listNodes, searchNodes, } from '../graph/index.js';
7
7
  import { loadGraph, loadMultiGraph } from '../loader/index.js';
8
8
  import { QueryError } from '../schema/index.js';
9
9
  import { createGraphRuntimeConfig } from '../source/config.js';
10
- import { startGraphFileWatcher, startWebServer } from '../web/server.js';
10
+ import { createMultiGraphCache, replaceGraph, startGraphFileWatcher, startWebServer } from '../web/server.js';
11
11
  import { USAGE_GUIDE_PROMPT } from './prompts/usage-guide.js';
12
12
  import { collapseClusterSchemas } from '../graph/schema-collapse.js';
13
13
  import { compactKeys, getSerializer } from './serializers.js';
14
- const EDGE_TYPES = [
15
- 'triggers',
16
- 'produces',
17
- 'reads',
18
- 'calls',
19
- 'implements',
20
- 'maps-to',
21
- 'derived-from',
22
- 'renamed-from',
23
- 'has-field',
24
- 'has-value',
25
- ];
26
- const EDGE_TYPE_SET = new Set(EDGE_TYPES);
27
14
  const STATE_VALUES = ['draft', 'proposed', 'agreed', 'future', 'removed', 'implemented'];
28
15
  const STABILITY_VALUES = ['unstable', 'stable', 'deprecated'];
29
16
  const LINEAGE_DIRECTIONS = ['downstream', 'upstream', 'both'];
@@ -31,11 +18,14 @@ const OUTPUT_FORMATS = ['yaml', 'json', 'toon'];
31
18
  function toStringArray(value) {
32
19
  return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : undefined;
33
20
  }
34
- function parseEdgeTypes(value) {
21
+ function parseEdgeTypes(value, graph) {
35
22
  const requested = toStringArray(value);
36
23
  if (!requested)
37
24
  return undefined;
38
- const invalid = requested.filter(type => !EDGE_TYPE_SET.has(type));
25
+ const known = graph.edgeTypes;
26
+ const invalid = known
27
+ ? requested.filter(type => !known.has(type))
28
+ : [];
39
29
  if (invalid.length > 0) {
40
30
  throw new QueryError(`Unknown edge type: ${invalid.join(', ')}`);
41
31
  }
@@ -150,7 +140,7 @@ export function createMcpHandlers(graph, source, cache) {
150
140
  return formatResult(summaries, args.format, getCompactKeys(args));
151
141
  };
152
142
  if (hasBranch(args)) {
153
- return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
143
+ return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
154
144
  }
155
145
  try {
156
146
  return run(graph);
@@ -162,7 +152,7 @@ export function createMcpHandlers(graph, source, cache) {
162
152
  get_graph_summary(args) {
163
153
  const run = (targetGraph) => formatResult(getGraphSummary(targetGraph), args.format, getCompactKeys(args));
164
154
  if (hasBranch(args) && source) {
165
- return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
155
+ return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
166
156
  }
167
157
  try {
168
158
  return run(graph);
@@ -196,7 +186,7 @@ export function createMcpHandlers(graph, source, cache) {
196
186
  return formatResult(results, args.format, getCompactKeys(args));
197
187
  };
198
188
  if (hasBranch(args) && source) {
199
- return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
189
+ return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
200
190
  }
201
191
  try {
202
192
  return run(graph);
@@ -220,7 +210,7 @@ export function createMcpHandlers(graph, source, cache) {
220
210
  return formatResult(summaries, args.format, getCompactKeys(args));
221
211
  };
222
212
  if (hasBranch(args) && source) {
223
- return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
213
+ return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
224
214
  }
225
215
  try {
226
216
  return run(graph);
@@ -247,8 +237,8 @@ export function createMcpHandlers(graph, source, cache) {
247
237
  ? args.overlay_refs.filter((ref) => typeof ref === 'string')
248
238
  : [];
249
239
  const run = async (targetGraph, branchRef) => {
250
- const edgeTypes = parseEdgeTypes(args.edge_types)
251
- ?? [...SEMANTIC_EDGE_TYPES];
240
+ const edgeTypes = parseEdgeTypes(args.edge_types, targetGraph)
241
+ ?? getVisibleEdgeTypes(targetGraph);
252
242
  const rawCluster = getClusterView(targetGraph, String(args.node_id), edgeTypes);
253
243
  const clusterIds = new Set([rawCluster.root.id, ...rawCluster.descendants.map(n => n.id)]);
254
244
  const externalIds = new Set();
@@ -331,7 +321,7 @@ export function createMcpHandlers(graph, source, cache) {
331
321
  const run = (targetGraph) => {
332
322
  const filter = parseListNodesFilter(args.filter);
333
323
  const effectiveFilter = (!filter.templates?.length && !filter.excludeTemplates?.length)
334
- ? { ...filter, excludeTemplates: [...STRUCTURAL_NODE_TEMPLATES] }
324
+ ? { ...filter, excludeTemplates: [...getStructuralNodeTemplates(targetGraph)] }
335
325
  : filter;
336
326
  const nodes = listNodes(targetGraph, effectiveFilter)
337
327
  .map(node => summarizeNode(node, includesProvenance(args)));
@@ -341,7 +331,7 @@ export function createMcpHandlers(graph, source, cache) {
341
331
  const edges = [];
342
332
  for (const edgeList of targetGraph.edgesByFrom.values()) {
343
333
  for (const edge of edgeList) {
344
- if (!SEMANTIC_EDGE_TYPES.has(edge.type) || !nodeIds.has(edge.from) || !nodeIds.has(edge.to))
334
+ if (!isVisibleEdgeType(targetGraph, edge.type) || !nodeIds.has(edge.from) || !nodeIds.has(edge.to))
345
335
  continue;
346
336
  edges.push({ id: edge.id, from: edge.from, to: edge.to, type: edge.type });
347
337
  }
@@ -351,7 +341,7 @@ export function createMcpHandlers(graph, source, cache) {
351
341
  return formatResult(payload, args.format, getCompactKeys(args));
352
342
  };
353
343
  if (hasBranch(args) && source) {
354
- return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
344
+ return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
355
345
  }
356
346
  try {
357
347
  return run(graph);
@@ -376,7 +366,7 @@ export function createMcpHandlers(graph, source, cache) {
376
366
  node_templates_in_use: [...nodeTemplatesInUse].sort(),
377
367
  edge_types_in_use: [...edgeTypesInUse].sort(),
378
368
  ...(includeStatic ? {
379
- valid_edge_types: [...EDGE_TYPES],
369
+ valid_edge_types: [...(targetGraph.edgeTypes?.keys() ?? [])],
380
370
  states: [...STATE_VALUES],
381
371
  stabilities: [...STABILITY_VALUES],
382
372
  lineage_directions: [...LINEAGE_DIRECTIONS],
@@ -385,7 +375,7 @@ export function createMcpHandlers(graph, source, cache) {
385
375
  }, args.format, getCompactKeys(args));
386
376
  };
387
377
  if (hasBranch(args) && source) {
388
- return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
378
+ return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
389
379
  }
390
380
  try {
391
381
  return run(graph);
@@ -407,7 +397,7 @@ export function createMcpHandlers(graph, source, cache) {
407
397
  const options = {
408
398
  depth: typeof args.depth === 'number' ? args.depth : 2,
409
399
  direction,
410
- edgeTypes: parseEdgeTypes(args.edge_types),
400
+ edgeTypes: parseEdgeTypes(args.edge_types, targetGraph),
411
401
  nodeTypes: toStringArray(args.node_types),
412
402
  excludeNodeTypes: toStringArray(args.exclude_node_types),
413
403
  includeDanglingEdges: args.include_dangling_edges === true,
@@ -428,7 +418,7 @@ export function createMcpHandlers(graph, source, cache) {
428
418
  return formatResult(payload, args.format, getCompactKeys(args));
429
419
  };
430
420
  if (hasBranch(args) && source) {
431
- return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
421
+ return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
432
422
  }
433
423
  try {
434
424
  return run(graph);
@@ -448,7 +438,7 @@ export function createMcpHandlers(graph, source, cache) {
448
438
  }, args.format, getCompactKeys(args));
449
439
  };
450
440
  if (hasBranch(args)) {
451
- return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
441
+ return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
452
442
  }
453
443
  try {
454
444
  return run(graph);
@@ -507,6 +497,26 @@ async function withBranchGraph(source, branchRef, fn, cache) {
507
497
  function hasBranch(args) {
508
498
  return typeof args.branch === 'string' && args.branch.length > 0;
509
499
  }
500
+ /**
501
+ * Retries a previously-failed graph load. Only attempts the load when `loadError` is set —
502
+ * a healthy graph is never re-loaded on the hot call path. On success, `graph` is mutated in
503
+ * place (via `replaceGraph`) so existing closures over it observe the fresh data, and
504
+ * `onReload` fires so callers can invalidate any dependent caches (e.g. a MultiGraphCache).
505
+ * Returns the resulting error, if any (undefined once recovered).
506
+ */
507
+ export async function ensureGraphLoaded(graph, loadError, loader, onReload) {
508
+ if (!loadError)
509
+ return undefined;
510
+ try {
511
+ const fresh = await loader();
512
+ replaceGraph(graph, fresh);
513
+ onReload?.();
514
+ return undefined;
515
+ }
516
+ catch (err) {
517
+ return String(err);
518
+ }
519
+ }
510
520
  function formatResult(value, format, compact = false) {
511
521
  const payload = compact === true ? compactKeys(value) : value;
512
522
  return { content: [{ type: 'text', text: getSerializer(format).serialize(payload) }] };
@@ -672,7 +682,7 @@ export function getMcpToolDefinitions() {
672
682
  node_types: { type: 'array', items: { type: 'string' }, description: 'Allowlist of node templates.' },
673
683
  exclude_node_types: { type: 'array', items: { type: 'string' }, description: 'Denylist of node templates.' },
674
684
  include_dangling_edges: { type: 'boolean', description: 'Include dangling edges in the response when present. Default false.' },
675
- reads_outbound_only: { type: 'boolean', description: 'Do not follow inbound reads edges in upstream traversal. Default true.' },
685
+ reads_outbound_only: { type: 'boolean', description: 'Do not follow inbound reads/uses-type edges in upstream traversal. Default true.' },
676
686
  lean: { type: 'boolean', description: 'Return minimal lineage node shape. Default true.' },
677
687
  include_edges: { type: 'boolean', description: 'Include the edges list in the response. Default false.' },
678
688
  include_edge_ids: { type: 'boolean', description: 'Include edge id field in edge output. Default false.' },
@@ -780,16 +790,26 @@ export async function startMcpServer(options = {}) {
780
790
  diagnostics: [],
781
791
  };
782
792
  }
783
- const handlers = createMcpHandlers(graph, config.source);
793
+ const mcpCache = config.source ? createMultiGraphCache(config.source) : undefined;
794
+ const handlers = createMcpHandlers(graph, config.source, mcpCache);
784
795
  if (!noWeb) {
785
- await startWebServer(graph, {
786
- graphPath: config.graphPath,
787
- fileWatcher: config.fileWatcherGraphPath && watch ? true : undefined,
788
- source: config.source,
789
- });
796
+ try {
797
+ await startWebServer(graph, {
798
+ graphPath: config.graphPath,
799
+ fileWatcher: config.fileWatcherGraphPath && watch ? true : undefined,
800
+ source: config.source,
801
+ onReload: () => mcpCache?.invalidate(),
802
+ });
803
+ }
804
+ catch (err) {
805
+ process.stderr.write(`[corum] web server failed to start, continuing MCP-only: ${err}\n`);
806
+ }
790
807
  }
791
808
  else if (watch && config.fileWatcherGraphPath) {
792
- startGraphFileWatcher(graph, { graphPath: config.fileWatcherGraphPath });
809
+ startGraphFileWatcher(graph, {
810
+ graphPath: config.fileWatcherGraphPath,
811
+ onReload: () => mcpCache?.invalidate(),
812
+ });
793
813
  }
794
814
  const server = new Server({ name: 'corum', version: '0.1.0' }, { capabilities: { tools: {}, prompts: {} } });
795
815
  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
@@ -815,6 +835,7 @@ export async function startMcpServer(options = {}) {
815
835
  tools: getMcpToolDefinitions(),
816
836
  }));
817
837
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
838
+ loadError = await ensureGraphLoaded(graph, loadError, () => loadGraph({ source: config.source, strict: true }), () => mcpCache?.invalidate());
818
839
  if (loadError) {
819
840
  return { content: [{ type: 'text', text: `Graph load error: ${loadError}` }], isError: true };
820
841
  }
@@ -69,6 +69,7 @@ export function compactKeys(value) {
69
69
  }
70
70
  return Object.fromEntries(Object.entries(value).map(([key, child]) => [
71
71
  COMPACT_KEY_MAP[key] ?? key,
72
- compactKeys(child),
72
+ // `properties` values are user-authored data; compact envelope keys only.
73
+ key === 'properties' ? child : compactKeys(child),
73
74
  ]));
74
75
  }
@@ -1,6 +1,12 @@
1
1
  import { mkdir, writeFile } from 'node:fs/promises';
2
2
  import path from 'node:path';
3
3
  import { parse } from 'yaml';
4
+ import { resolveContentPath } from '../source/safe-path.js';
5
+ function validateTemplateName(name) {
6
+ if (!/^[^/\\]+$/.test(name) || name === '.' || name === '..') {
7
+ throw new Error(`invalid template name in pack.yaml: ${name}`);
8
+ }
9
+ }
4
10
  export async function installPackFiles(baseUrl, destDir, fetchFn = fetch) {
5
11
  const packYamlUrl = `${baseUrl}/pack.yaml`;
6
12
  const packRes = await fetchFn(packYamlUrl);
@@ -8,6 +14,14 @@ export async function installPackFiles(baseUrl, destDir, fetchFn = fetch) {
8
14
  throw new Error(`Failed to fetch pack.yaml: ${packRes.status} ${packRes.statusText}`);
9
15
  const packText = await packRes.text();
10
16
  const meta = parse(packText);
17
+ // Remote pack.yaml content is untrusted: validate every declared name/path
18
+ // before any file is written so a malicious pack cannot escape destDir.
19
+ for (const templateName of meta.templates)
20
+ validateTemplateName(templateName);
21
+ const fileDests = new Map();
22
+ for (const filePath of meta.files ?? []) {
23
+ fileDests.set(filePath, resolveContentPath(destDir, filePath));
24
+ }
11
25
  await mkdir(path.join(destDir, 'templates'), { recursive: true });
12
26
  await writeFile(path.join(destDir, 'pack.yaml'), packText);
13
27
  for (const templateName of meta.templates) {
@@ -17,12 +31,11 @@ export async function installPackFiles(baseUrl, destDir, fetchFn = fetch) {
17
31
  throw new Error(`Failed to fetch template ${templateName}: ${res.status} ${res.statusText}`);
18
32
  await writeFile(path.join(destDir, 'templates', `${templateName}.yaml`), await res.text());
19
33
  }
20
- for (const filePath of meta.files ?? []) {
34
+ for (const [filePath, dest] of fileDests) {
21
35
  const fileUrl = `${baseUrl}/${filePath}`;
22
36
  const res = await fetchFn(fileUrl);
23
37
  if (!res.ok)
24
38
  throw new Error(`Failed to fetch file ${filePath}: ${res.status} ${res.statusText}`);
25
- const dest = path.join(destDir, filePath);
26
39
  await mkdir(path.dirname(dest), { recursive: true });
27
40
  await writeFile(dest, await res.text());
28
41
  }
@@ -1,10 +1,11 @@
1
- import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
1
+ import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
2
2
  import fs from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import * as git from 'isomorphic-git';
5
5
  import { parse as parseYaml } from 'yaml';
6
6
  import { isPackRef } from '../loader/fs-utils.js';
7
7
  import { SourceError } from './index.js';
8
+ import { resolveContentPath } from './safe-path.js';
8
9
  const DEFAULT_GRAPH_DIR = '.corum/graph';
9
10
  const DEFAULT_PACKS_PATH = '.corum/packs';
10
11
  export class FileGraphSource {
@@ -73,23 +74,116 @@ export class FileGraphSource {
73
74
  return [];
74
75
  }
75
76
  }
76
- async commit(branch, changes, _message, options = {}) {
77
+ async commit(branch, changes, message, options = {}) {
77
78
  const defaultBranch = await this.defaultBranch();
78
79
  if (branch !== defaultBranch) {
79
80
  throw new SourceError(`FileGraphSource only supports its local branch '${defaultBranch}', got '${branch}'`);
80
81
  }
81
- if (options.replaceGraphContent && existsSync(this.graphDir)) {
82
- rmSync(this.graphDir, { recursive: true, force: true });
82
+ if (options.replaceGraphContent) {
83
+ this.replaceGraphContent(changes);
83
84
  }
84
- for (const [key, content] of changes) {
85
- const filePath = resolveContentPath(this.graphDir, key);
86
- mkdirSync(path.dirname(filePath), { recursive: true });
87
- writeFileSync(filePath, content);
85
+ else {
86
+ writeContentMap(this.graphDir, changes);
87
+ }
88
+ await commitToGitIfRepo(this.graphDir, message);
89
+ }
90
+ /**
91
+ * Replace the full graph directory contents with `changes`, closing the
92
+ * crash window that a naive `rmSync` + rewrite leaves open (a crash between
93
+ * delete and rewrite used to lose the graph entirely) and never deleting
94
+ * non-YAML files a user kept alongside the graph.
95
+ *
96
+ * Approach: stage the new content in a sibling temp directory (copying over
97
+ * the old directory first so untouched non-YAML files survive, then
98
+ * overlaying the new files and dropping stale YAML that's no longer in the
99
+ * ContentMap), then atomically swap it in via two renames. The original
100
+ * directory is never observably empty or partially written.
101
+ *
102
+ * Exception: if `graphDir` is itself a git repository root (contains a
103
+ * `.git` entry), renaming it away would move `.git` too, so we fall back to
104
+ * an in-place selective delete — write new content first, then remove only
105
+ * the stale `.yaml` files no longer present in `changes`.
106
+ */
107
+ replaceGraphContent(changes) {
108
+ if (!existsSync(this.graphDir)) {
109
+ writeContentMap(this.graphDir, changes);
110
+ return;
111
+ }
112
+ if (existsSync(path.join(this.graphDir, '.git'))) {
113
+ writeContentMap(this.graphDir, changes);
114
+ deleteStaleYamlFiles(this.graphDir, changes);
115
+ return;
116
+ }
117
+ const parent = path.dirname(this.graphDir);
118
+ const base = path.basename(this.graphDir);
119
+ const suffix = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
120
+ const tmpDir = path.join(parent, `${base}.corum-tmp-${suffix}`);
121
+ const oldDir = path.join(parent, `${base}.corum-old-${suffix}`);
122
+ rmSync(tmpDir, { recursive: true, force: true });
123
+ cpSync(this.graphDir, tmpDir, { recursive: true });
124
+ writeContentMap(tmpDir, changes);
125
+ deleteStaleYamlFiles(tmpDir, changes);
126
+ renameSync(this.graphDir, oldDir);
127
+ try {
128
+ renameSync(tmpDir, this.graphDir);
129
+ }
130
+ catch (err) {
131
+ renameSync(oldDir, this.graphDir);
132
+ throw err;
133
+ }
134
+ rmSync(oldDir, { recursive: true, force: true });
135
+ }
136
+ }
137
+ function writeContentMap(baseDir, changes) {
138
+ for (const [key, content] of changes) {
139
+ const filePath = resolveContentPath(baseDir, key);
140
+ mkdirSync(path.dirname(filePath), { recursive: true });
141
+ writeFileSync(filePath, content);
142
+ }
143
+ }
144
+ function deleteStaleYamlFiles(baseDir, changes) {
145
+ const existingYaml = new Map();
146
+ walkYamlFilesIntoMap(baseDir, baseDir, existingYaml);
147
+ for (const key of existingYaml.keys()) {
148
+ if (!changes.has(key)) {
149
+ rmSync(resolveContentPath(baseDir, key), { force: true });
88
150
  }
89
- // TODO: create a git commit for these changes via git.add() + git.commit().
90
- // Currently _message is unused — file writes are persisted but not committed to git history.
91
151
  }
92
152
  }
153
+ async function commitToGitIfRepo(graphDir, message) {
154
+ let repoRoot;
155
+ try {
156
+ repoRoot = await git.findRoot({ fs, filepath: path.resolve(graphDir) });
157
+ }
158
+ catch {
159
+ return; // Not inside a git repo — plain directory writes only.
160
+ }
161
+ const rel = path.relative(repoRoot, path.resolve(graphDir)).split(path.sep).join('/');
162
+ const matrix = await git.statusMatrix({
163
+ fs,
164
+ dir: repoRoot,
165
+ filepaths: rel === '' ? undefined : [rel],
166
+ });
167
+ let staged = false;
168
+ for (const [filepath, head, workdir] of matrix) {
169
+ if (head === 1 && workdir === 0) {
170
+ await git.remove({ fs, dir: repoRoot, filepath });
171
+ staged = true;
172
+ }
173
+ else if (workdir === 2) {
174
+ await git.add({ fs, dir: repoRoot, filepath });
175
+ staged = true;
176
+ }
177
+ }
178
+ if (!staged)
179
+ return;
180
+ await git.commit({
181
+ fs,
182
+ dir: repoRoot,
183
+ message,
184
+ author: { name: 'corum', email: 'corum@localhost' },
185
+ });
186
+ }
93
187
  function readPackTemplatesIntoMap(packDir, map) {
94
188
  if (!existsSync(packDir))
95
189
  return;
@@ -100,25 +194,6 @@ function readPackTemplatesIntoMap(packDir, map) {
100
194
  map.set(`${packName}/${relKey}`, content);
101
195
  }
102
196
  }
103
- function resolveContentPath(baseDir, key) {
104
- if (key.includes('\\') ||
105
- key.includes('\0') ||
106
- path.posix.isAbsolute(key) ||
107
- path.win32.isAbsolute(key)) {
108
- throw new SourceError(`invalid ContentMap key: ${key}`);
109
- }
110
- const normalised = path.posix.normalize(key);
111
- if (normalised === '..' || normalised.startsWith('../') || normalised === '.') {
112
- throw new SourceError(`invalid ContentMap key: ${key}`);
113
- }
114
- const resolvedBase = path.resolve(baseDir);
115
- const resolvedPath = path.resolve(resolvedBase, ...normalised.split('/'));
116
- const relative = path.relative(resolvedBase, resolvedPath);
117
- if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
118
- throw new SourceError(`ContentMap key escapes graphDir: ${key}`);
119
- }
120
- return resolvedPath;
121
- }
122
197
  function walkYamlFilesIntoMap(baseDir, currentDir, map, excludeDirs = new Set()) {
123
198
  for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
124
199
  const fullPath = path.join(currentDir, entry.name);