agent-contracts 0.5.0 → 0.5.2

package/README.md

@@ -1,6 +1,9 @@
 
 # agent-contracts
 
+[![npm version](https://img.shields.io/npm/v/agent-contracts.svg)](https://www.npmjs.com/package/agent-contracts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 **Design multi-agent systems as contracts.**
 
 `agent-contracts` is a toolkit for declaratively defining multi-agent development workflows in **YAML DSL**, with **static validation, semantic linting, and prompt rendering**.
@@ -242,6 +245,7 @@ Design regressions become testable.
 * **Artifact ownership and lifecycle modeling**
 * **Config-driven prompt rendering**
 * **Inheritance with merge operators via `extends`**
+* **Flexible file splitting** via `$ref` (replacement) and `$refs` (import + deep-merge)
 * **JSON Schema for editor support and external tooling**
 * **CI-friendly workflow checks**
 
@@ -289,7 +293,7 @@ tasks: { ... }
 artifacts: { ... }
 ````
 
-### Multi-file format
+### Multi-file format (section-level `$ref`)
 
 ````yaml
 version: 1
@@ -309,6 +313,91 @@ workflow: { $ref: "./workflow.yaml" }
 policies: { $ref: "./policies.yaml" }
 ````
 
+### Per-entry `$ref`
+
+`$ref` can be used at any object position. This allows splitting individual entries into separate files:
+
+````yaml
+agents:
+  architect: { $ref: "./agents/architect.yaml" }
+  implementer: { $ref: "./agents/implementer.yaml" }
+  test-writer: { $ref: "./agents/test-writer.yaml" }
+````
+
+Each referenced file contains the agent definition directly (without the key):
+
+````yaml
+# agents/architect.yaml
+role_name: "Architect"
+purpose: "Drive phases and delegate work"
+can_invoke_agents: [implementer]
+````
+
+### Directory `$ref`
+
+When `$ref` points to a directory, all `*.yaml` / `*.yml` files in the directory are loaded and merged:
+
+````yaml
+agents: { $ref: "./agents/" }
+````
+
+Each file in the directory contains one or more keyed entries:
+
+````yaml
+# agents/architect.yaml
+architect:
+  role_name: "Architect"
+  purpose: "Drive phases and delegate work"
+````
+
+Files are loaded in alphabetical order. Conflicting leaf values across files result in an error.
+
+### `$refs` (import and merge)
+
+`$refs` imports multiple files and **deep-merges** them into the containing map.
+Unlike `$ref` (which replaces an object entirely), `$refs` allows mixing inline definitions with external files.
+
+````yaml
+agents:
+  inline-agent:
+    role_name: "Inline Agent"
+    purpose: "Defined right here"
+  $refs:
+    - "./agents/architect.yaml"
+    - "./agents/implementer.yaml"
+    - "./more-agents/"           # directories are also supported
+````
+
+Each referenced file uses the same keyed format:
+
+````yaml
+# agents/architect.yaml
+architect:
+  role_name: "Architect"
+  purpose: "Drive phases and delegate work"
+````
+
+`$refs` can also be used at the root level to compose a DSL from multiple aspect-oriented files:
+
+````yaml
+version: 1
+system:
+  id: my-project
+  name: My Agent Workflow
+  default_phase_order: [analyze, implement]
+$refs:
+  - "./agents-core.yaml"        # agents + artifacts definitions
+  - "./agents-constraints.yaml"  # constraints for the same agents
+  - "./tasks.yaml"
+````
+
+Overlapping map keys are deep-merged recursively. Conflicting leaf values (scalar or array) result in an error.
+
+| Directive | Type   | Behavior                                                 |
+| --------- | ------ | -------------------------------------------------------- |
+| `$ref`    | string | Replace the object at that position with file contents   |
+| `$refs`   | array  | Import files and deep-merge into the containing map      |
+
 ---
 
 ## Example: Agent definition

package/dist/cli.js

@@ -3952,7 +3952,7 @@ var require_lodash = __commonJS({
           }
           return mapped.length && mapped[0] === arrays[0] ? baseIntersection(mapped, undefined2, comparator) : [];
         });
-        function join2(array, separator) {
+        function join3(array, separator) {
           return array == null ? "" : nativeJoin.call(array, separator);
         }
         function last(array) {
@@ -5876,7 +5876,7 @@ var require_lodash = __commonJS({
         lodash.isUndefined = isUndefined;
         lodash.isWeakMap = isWeakMap;
         lodash.isWeakSet = isWeakSet;
-        lodash.join = join2;
+        lodash.join = join3;
         lodash.kebabCase = kebabCase;
         lodash.last = last;
         lodash.lastIndexOf = lastIndexOf;
@@ -7497,7 +7497,7 @@ var require_stable = __commonJS({
       return result;
     }
     function stringifyFullFn(key, parent, stack, replacer, indent) {
-      var i3, res, join2;
+      var i3, res, join3;
       const originalIndentation = indentation;
       var value = parent[key];
       if (typeof value === "object" && value !== null && typeof value.toJSON === "function") {
@@ -7523,12 +7523,12 @@ var require_stable = __commonJS({
             indentation += indent;
             res += `
 ${indentation}`;
-            join2 = `,
+            join3 = `,
 ${indentation}`;
             for (i3 = 0; i3 < value.length - 1; i3++) {
               const tmp2 = stringifyFullFn(i3, value, stack, replacer, indent);
               res += tmp2 !== void 0 ? tmp2 : "null";
-              res += join2;
+              res += join3;
             }
             const tmp = stringifyFullFn(i3, value, stack, replacer, indent);
             res += tmp !== void 0 ? tmp : "null";
@@ -7550,7 +7550,7 @@ ${originalIndentation}`;
           indentation += indent;
           res += `
 ${indentation}`;
-          join2 = `,
+          join3 = `,
 ${indentation}`;
           var separator = "";
           for (i3 = 0; i3 < keys.length; i3++) {
@@ -7558,7 +7558,7 @@ ${indentation}`;
             const tmp = stringifyFullFn(key, value, stack, replacer, indent);
             if (tmp !== void 0) {
               res += `${separator}"${strEscape(key)}": ${tmp}`;
-              separator = join2;
+              separator = join3;
             }
           }
           if (separator !== "") {
@@ -7580,7 +7580,7 @@ ${originalIndentation}`;
       }
     }
     function stringifyFullArr(key, value, stack, replacer, indent) {
-      var i3, res, join2;
+      var i3, res, join3;
       const originalIndentation = indentation;
       if (typeof value === "object" && value !== null && typeof value.toJSON === "function") {
         value = value.toJSON(key);
@@ -7604,12 +7604,12 @@ ${originalIndentation}`;
             indentation += indent;
             res += `
 ${indentation}`;
-            join2 = `,
+            join3 = `,
 ${indentation}`;
             for (i3 = 0; i3 < value.length - 1; i3++) {
               const tmp2 = stringifyFullArr(i3, value[i3], stack, replacer, indent);
               res += tmp2 !== void 0 ? tmp2 : "null";
-              res += join2;
+              res += join3;
             }
             const tmp = stringifyFullArr(i3, value[i3], stack, replacer, indent);
             res += tmp !== void 0 ? tmp : "null";
@@ -7630,7 +7630,7 @@ ${originalIndentation}`;
           indentation += indent;
           res += `
 ${indentation}`;
-          join2 = `,
+          join3 = `,
 ${indentation}`;
           var separator = "";
           for (i3 = 0; i3 < replacer.length; i3++) {
@@ -7639,7 +7639,7 @@ ${indentation}`;
               const tmp = stringifyFullArr(key, value[key], stack, replacer, indent);
               if (tmp !== void 0) {
                 res += `${separator}"${strEscape(key)}": ${tmp}`;
-                separator = join2;
+                separator = join3;
               }
             }
           }
@@ -7662,7 +7662,7 @@ ${originalIndentation}`;
       }
     }
     function stringifyIndent(key, value, stack, indent) {
-      var i3, res, join2;
+      var i3, res, join3;
       const originalIndentation = indentation;
       switch (typeof value) {
         case "object":
@@ -7692,12 +7692,12 @@ ${originalIndentation}`;
             indentation += indent;
             res += `
 ${indentation}`;
-            join2 = `,
+            join3 = `,
 ${indentation}`;
             for (i3 = 0; i3 < value.length - 1; i3++) {
               const tmp2 = stringifyIndent(i3, value[i3], stack, indent);
               res += tmp2 !== void 0 ? tmp2 : "null";
-              res += join2;
+              res += join3;
             }
             const tmp = stringifyIndent(i3, value[i3], stack, indent);
             res += tmp !== void 0 ? tmp : "null";
@@ -7719,7 +7719,7 @@ ${originalIndentation}`;
           indentation += indent;
           res += `
 ${indentation}`;
-          join2 = `,
+          join3 = `,
 ${indentation}`;
           var separator = "";
           for (i3 = 0; i3 < keys.length; i3++) {
@@ -7727,7 +7727,7 @@ ${indentation}`;
             const tmp = stringifyIndent(key, value[key], stack, indent);
             if (tmp !== void 0) {
               res += `${separator}"${strEscape(key)}": ${tmp}`;
-              separator = join2;
+              separator = join3;
             }
           }
           if (separator !== "") {
@@ -52698,7 +52698,7 @@ var require_lodash3 = __commonJS({
           }
           return mapped.length && mapped[0] === arrays[0] ? baseIntersection(mapped, undefined2, comparator) : [];
         });
-        function join2(array, separator) {
+        function join3(array, separator) {
           return array == null ? "" : nativeJoin.call(array, separator);
         }
         function last(array) {
@@ -54617,7 +54617,7 @@ var require_lodash3 = __commonJS({
         lodash.isUndefined = isUndefined;
         lodash.isWeakMap = isWeakMap;
         lodash.isWeakSet = isWeakSet;
-        lodash.join = join2;
+        lodash.join = join3;
         lodash.kebabCase = kebabCase;
         lodash.last = last;
         lodash.lastIndexOf = lastIndexOf;
@@ -58429,12 +58429,12 @@ function resolveDslPath(dirArg, dirArgDefault, config) {
 }
 
 // src/resolver/base-resolver.ts
-import { resolve as resolve3, join } from "path";
+import { resolve as resolve3, join as join2 } from "path";
 import { stat } from "fs/promises";
 
 // src/loader/loader.ts
-import { readFile as readFile2 } from "fs/promises";
-import { dirname as dirname2, resolve as resolve2 } from "path";
+import { readFile as readFile2, readdir, stat as fsStat } from "fs/promises";
+import { dirname as dirname2, resolve as resolve2, join, extname } from "path";
 import { parse as parseYaml2 } from "yaml";
 var DslLoadError = class extends Error {
   constructor(message, filePath) {
@@ -58444,18 +58444,16 @@ var DslLoadError = class extends Error {
   }
   filePath;
 };
-var REF_ELIGIBLE_SECTIONS = [
-  "agents",
-  "tasks",
-  "artifacts",
-  "tools",
-  "validations",
-  "handoff_types",
-  "workflow",
-  "policies"
-];
+function isRecord(v2) {
+  return typeof v2 === "object" && v2 !== null && !Array.isArray(v2);
+}
 function isRef(value) {
-  return typeof value === "object" && value !== null && "$ref" in value && typeof value["$ref"] === "string";
+  return isRecord(value) && "$ref" in value && typeof value["$ref"] === "string";
+}
+function hasRefs(value) {
+  if (!("$refs" in value)) return false;
+  const refs = value["$refs"];
+  return Array.isArray(refs) && refs.every((r3) => typeof r3 === "string");
 }
 async function readYaml(filePath) {
   let content;
@@ -58477,17 +58475,160 @@ async function readYaml(filePath) {
     );
   }
 }
-async function resolveRefs(data, baseDir) {
-  const resolved = { ...data };
-  for (const section of REF_ELIGIBLE_SECTIONS) {
-    const value = resolved[section];
-    if (isRef(value)) {
-      const refPath = resolve2(baseDir, value.$ref);
-      resolved[section] = await readYaml(refPath);
+function deepMergeRefs(a3, b3, sourcePath) {
+  const result = { ...a3 };
+  for (const [key, bVal] of Object.entries(b3)) {
+    const aVal = result[key];
+    if (aVal === void 0) {
+      result[key] = bVal;
+    } else if (isRecord(aVal) && isRecord(bVal)) {
+      result[key] = deepMergeRefs(aVal, bVal, sourcePath);
+    } else {
+      throw new DslLoadError(
+        `Conflicting value for key "${key}" while merging $refs from ${sourcePath}`,
+        sourcePath
+      );
     }
   }
+  return result;
+}
+async function loadRefsSource(refPath, baseDir, resolving) {
+  const target = resolve2(baseDir, refPath);
+  const s2 = await fsStat(target).catch(() => null);
+  if (s2?.isDirectory()) {
+    if (resolving.has(target)) {
+      throw new DslLoadError(`Circular $refs detected: ${target}`, target);
+    }
+    resolving.add(target);
+    const result = await loadDirectoryAsMap(target, resolving);
+    resolving.delete(target);
+    return result;
+  }
+  if (!s2?.isFile()) {
+    throw new DslLoadError(`File not found: ${target}`, target);
+  }
+  if (resolving.has(target)) {
+    throw new DslLoadError(`Circular $refs detected: ${target}`, target);
+  }
+  resolving.add(target);
+  const content = await readYaml(target);
+  if (!isRecord(content)) {
+    throw new DslLoadError(
+      `Expected YAML object in ${target}, got ${Array.isArray(content) ? "array" : typeof content}`,
+      target
+    );
+  }
+  const resolved = await resolveRefsDeep(
+    content,
+    dirname2(target),
+    resolving
+  );
+  resolving.delete(target);
   return resolved;
 }
+async function loadDirectoryAsMap(dirPath, resolving) {
+  let entries;
+  try {
+    entries = await readdir(dirPath);
+  } catch {
+    throw new DslLoadError(
+      `Cannot read directory: ${dirPath}`,
+      dirPath
+    );
+  }
+  const yamlFiles = entries.filter((f2) => [".yaml", ".yml"].includes(extname(f2))).sort();
+  if (yamlFiles.length === 0) {
+    throw new DslLoadError(
+      `No YAML files found in directory: ${dirPath}`,
+      dirPath
+    );
+  }
+  let merged = {};
+  for (const file of yamlFiles) {
+    const filePath = join(dirPath, file);
+    const content = await readYaml(filePath);
+    if (!isRecord(content)) {
+      throw new DslLoadError(
+        `Expected YAML object in ${filePath}, got ${Array.isArray(content) ? "array" : typeof content}`,
+        filePath
+      );
+    }
+    const resolved = await resolveRefsDeep(
+      content,
+      dirPath,
+      resolving
+    );
+    merged = deepMergeRefs(merged, resolved, filePath);
+  }
+  return merged;
+}
+async function processRefs(obj, baseDir, resolving) {
+  const refPaths = obj["$refs"];
+  const inline = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (key !== "$refs") {
+      inline[key] = value;
+    }
+  }
+  let merged = {};
+  for (const refPath of refPaths) {
+    const loaded = await loadRefsSource(refPath, baseDir, resolving);
+    merged = deepMergeRefs(merged, loaded, refPath);
+  }
+  merged = deepMergeRefs(merged, inline, "(inline)");
+  return merged;
+}
+async function resolveRefsDeep(data, baseDir, resolving) {
+  if (typeof data !== "object" || data === null) return data;
+  if (Array.isArray(data)) {
+    return Promise.all(
+      data.map((item) => resolveRefsDeep(item, baseDir, resolving))
+    );
+  }
+  if (isRef(data)) {
+    const refTarget = resolve2(baseDir, data.$ref);
+    const s2 = await fsStat(refTarget).catch(() => null);
+    if (s2?.isDirectory()) {
+      if (resolving.has(refTarget)) {
+        throw new DslLoadError(
+          `Circular $ref detected: ${refTarget}`,
+          refTarget
+        );
+      }
+      resolving.add(refTarget);
+      const result2 = await loadDirectoryAsMap(refTarget, resolving);
+      resolving.delete(refTarget);
+      return result2;
+    }
+    if (!s2?.isFile()) {
+      throw new DslLoadError(`File not found: ${refTarget}`, refTarget);
+    }
+    if (resolving.has(refTarget)) {
+      throw new DslLoadError(
+        `Circular $ref detected: ${refTarget}`,
+        refTarget
+      );
+    }
+    resolving.add(refTarget);
+    const content = await readYaml(refTarget);
+    const resolved = await resolveRefsDeep(
+      content,
+      dirname2(refTarget),
+      resolving
+    );
+    resolving.delete(refTarget);
+    return resolved;
+  }
+  let obj = data;
+  if (hasRefs(obj)) {
+    obj = await processRefs(obj, baseDir, resolving);
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = await resolveRefsDeep(value, baseDir, resolving);
+  }
+  return result;
+}
 function checkVersion(data, filePath) {
   const version = data["version"];
   if (version === void 0) {
@@ -58515,7 +58656,12 @@ async function loadDsl(entryPath) {
   const data = raw;
   checkVersion(data, absPath);
   const baseDir = dirname2(absPath);
-  const resolved = await resolveRefs(data, baseDir);
+  const resolving = /* @__PURE__ */ new Set([absPath]);
+  const resolved = await resolveRefsDeep(
+    data,
+    baseDir,
+    resolving
+  );
   return { data: resolved, filePath: absPath };
 }
 
@@ -58529,7 +58675,7 @@ var BaseResolveError = class extends Error {
 async function findEntryFile(dir) {
   const candidates = ["agent-contracts.yaml", "agent-contracts.yml"];
   for (const name of candidates) {
-    const p2 = join(dir, name);
+    const p2 = join2(dir, name);
     try {
       const s2 = await stat(p2);
       if (s2.isFile()) return p2;
@@ -58581,7 +58727,7 @@ var MergeError = class extends Error {
     this.name = "MergeError";
   }
 };
-function isRecord(v2) {
+function isRecord2(v2) {
   return typeof v2 === "object" && v2 !== null && !Array.isArray(v2);
 }
 function hasOperator(obj) {
@@ -58593,7 +58739,7 @@ function hasOperator(obj) {
 }
 function findIndexById(arr, id) {
   return arr.findIndex(
-    (item) => isRecord(item) && item["id"] === id
+    (item) => isRecord2(item) && item["id"] === id
   );
 }
 function applyArrayMergeOperator(baseArray, operatorObj, path) {
@@ -58629,7 +58775,7 @@ function applyArrayMergeOperator(baseArray, operatorObj, path) {
       const removeList = operatorObj["$remove"];
       const idsToRemove = new Set(removeList.map((r3) => r3["id"]));
       const result = baseArray.filter((item) => {
-        if (isRecord(item) && typeof item["id"] === "string") {
+        if (isRecord2(item) && typeof item["id"] === "string") {
           const itemId = item["id"];
           if (idsToRemove.has(itemId)) {
             idsToRemove.delete(itemId);
@@ -58718,7 +58864,7 @@ function deepMergeEntities(base, project, path, hasExtends) {
   for (const key of Object.keys(project)) {
     const baseVal = result[key];
     const projVal = project[key];
-    if (isRecord(projVal) && hasOperator(projVal)) {
+    if (isRecord2(projVal) && hasOperator(projVal)) {
       if (!hasExtends) {
         throw new MergeError(
           `Merge operator used without extends at ${path}.${key}`
@@ -58726,12 +58872,12 @@ function deepMergeEntities(base, project, path, hasExtends) {
       }
       if (Array.isArray(baseVal)) {
         result[key] = applyArrayMergeOperator(baseVal, projVal, `${path}.${key}`);
-      } else if (isRecord(baseVal)) {
+      } else if (isRecord2(baseVal)) {
         result[key] = applyMapMergeOperator(baseVal, projVal, `${path}.${key}`);
       } else {
         result[key] = applyArrayMergeOperator([], projVal, `${path}.${key}`);
       }
-    } else if (isRecord(projVal) && isRecord(baseVal) && !Array.isArray(projVal) && !Array.isArray(baseVal)) {
+    } else if (isRecord2(projVal) && isRecord2(baseVal) && !Array.isArray(projVal) && !Array.isArray(baseVal)) {
       result[key] = deepMergeEntities(
         baseVal,
         projVal,
@@ -58745,7 +58891,7 @@ function deepMergeEntities(base, project, path, hasExtends) {
   return result;
 }
 function mergeEntityMaps(baseMap, projectMap, path, hasExtends) {
-  if (isRecord(projectMap) && !Array.isArray(projectMap)) {
+  if (isRecord2(projectMap) && !Array.isArray(projectMap)) {
     const op = hasOperator(projectMap);
     if (op) {
       if (!hasExtends) {
@@ -58759,7 +58905,7 @@ function mergeEntityMaps(baseMap, projectMap, path, hasExtends) {
   const result = { ...baseMap };
   for (const [key, projVal] of Object.entries(projectMap)) {
     const baseVal = result[key];
-    if (baseVal !== void 0 && isRecord(baseVal) && isRecord(projVal)) {
+    if (baseVal !== void 0 && isRecord2(baseVal) && isRecord2(projVal)) {
       result[key] = deepMergeEntities(
         baseVal,
         projVal,
@@ -58799,7 +58945,7 @@ function mergeDsl(base, project) {
     if (projVal === void 0) {
       continue;
     }
-    const baseMap = isRecord(baseVal) ? baseVal : {};
+    const baseMap = isRecord2(baseVal) ? baseVal : {};
     result[section] = mergeEntityMaps(
       baseMap,
       projVal,