agent-contracts 0.11.0 → 0.11.1

package/README.md

@@ -1003,6 +1003,76 @@ outputs:
     template: ./templates/cursor-hook-wrapper.sh.hbs
 ````
 
+### Binding inheritance
+
+Binding files support `extends` for inheriting and extending a base binding, using the same mechanism as DSL-level `extends`.
+
+A base binding defines shared guardrail implementations and outputs:
+
+````yaml
+# skeleton/bindings/cursor.yaml (base)
+software: cursor
+version: 1
+
+guardrail_impl:
+  no-force-push:
+    checks:
+      - hook_event: beforeShellExecution
+        matcher:
+          type: command_regex
+          pattern: "git\\s+push\\s+.*--force"
+        message: "Force push is forbidden"
+
+outputs:
+  policy-bundle:
+    target: "{cursor_root}/guardrails/policy.json"
+    mode: write
+    inline_template: "{{json resolved_checks}}"
+````
+
+A project binding extends the base and adds project-specific guardrail implementations:
+
+````yaml
+# project/bindings/cursor.yaml
+extends: ../../skeleton/bindings/cursor.yaml
+software: cursor
+version: 1
+
+guardrail_impl:
+  lint-on-save:
+    checks:
+      - hook_event: afterFileEdit
+        matcher:
+          type: file_glob
+          pattern: "**/*.{ts,tsx}"
+        message: "TS file edited — lint results attached."
+````
+
+The result is a single merged binding with all guardrail implementations from both base and project.
+
+Merge behavior:
+
+| Field | Behavior |
+|-------|----------|
+| `software` | Project wins |
+| `guardrail_impl` | Map merge by guardrail ID (new IDs added; same ID deep-merged) |
+| `outputs` | Map merge by output ID (project overrides base) |
+| `reporting` | Deep merge (project fields override base) |
+| passthrough fields | Project wins |
+
+All merge operators (`$append`, `$prepend`, `$insert_after`, `$replace`, `$remove`) work within binding `extends`, the same as DSL `extends`.
+
+Chained inheritance (grandparent → parent → child) and both local path (`./`, `../`) and npm package references are supported. Circular extends are detected and rejected.
+
+When using binding `extends`, the config only needs to list the child binding:
+
+````yaml
+# agent-contracts.config.yaml
+bindings:
+  - ./bindings/cursor.yaml    # extends base internally
+  - ./bindings/git.yaml
+````
+
 ### Config
 
 ````yaml

package/dist/cli.js

@@ -159,11 +159,11 @@ function __metadata(metadataKey, metadataValue) {
 }
 function __awaiter(thisArg, _arguments, P2, generator) {
   function adopt(value) {
-    return value instanceof P2 ? value : new P2(function(resolve6) {
-      resolve6(value);
+    return value instanceof P2 ? value : new P2(function(resolve7) {
+      resolve7(value);
     });
   }
-  return new (P2 || (P2 = Promise))(function(resolve6, reject) {
+  return new (P2 || (P2 = Promise))(function(resolve7, reject) {
     function fulfilled(value) {
       try {
         step(generator.next(value));
@@ -179,7 +179,7 @@ function __awaiter(thisArg, _arguments, P2, generator) {
       }
     }
     function step(result) {
-      result.done ? resolve6(result.value) : adopt(result.value).then(fulfilled, rejected);
+      result.done ? resolve7(result.value) : adopt(result.value).then(fulfilled, rejected);
     }
     step((generator = generator.apply(thisArg, _arguments || [])).next());
   });
@@ -370,14 +370,14 @@ function __asyncValues(o3) {
   }, i3);
   function verb(n3) {
     i3[n3] = o3[n3] && function(v2) {
-      return new Promise(function(resolve6, reject) {
-        v2 = o3[n3](v2), settle(resolve6, reject, v2.done, v2.value);
+      return new Promise(function(resolve7, reject) {
+        v2 = o3[n3](v2), settle(resolve7, reject, v2.done, v2.value);
       });
     };
   }
-  function settle(resolve6, reject, d2, v2) {
+  function settle(resolve7, reject, d2, v2) {
     Promise.resolve(v2).then(function(v3) {
-      resolve6({ value: v3, done: d2 });
+      resolve7({ value: v3, done: d2 });
     }, reject);
   }
 }
@@ -13033,11 +13033,11 @@ function __metadata2(metadataKey, metadataValue) {
 }
 function __awaiter2(thisArg, _arguments, P2, generator) {
   function adopt(value) {
-    return value instanceof P2 ? value : new P2(function(resolve6) {
-      resolve6(value);
+    return value instanceof P2 ? value : new P2(function(resolve7) {
+      resolve7(value);
     });
   }
-  return new (P2 || (P2 = Promise))(function(resolve6, reject) {
+  return new (P2 || (P2 = Promise))(function(resolve7, reject) {
     function fulfilled(value) {
       try {
         step(generator.next(value));
@@ -13053,7 +13053,7 @@ function __awaiter2(thisArg, _arguments, P2, generator) {
       }
     }
     function step(result) {
-      result.done ? resolve6(result.value) : adopt(result.value).then(fulfilled, rejected);
+      result.done ? resolve7(result.value) : adopt(result.value).then(fulfilled, rejected);
     }
     step((generator = generator.apply(thisArg, _arguments || [])).next());
   });
@@ -13231,14 +13231,14 @@ function __asyncValues2(o3) {
   }, i3);
   function verb(n3) {
     i3[n3] = o3[n3] && function(v2) {
-      return new Promise(function(resolve6, reject) {
-        v2 = o3[n3](v2), settle(resolve6, reject, v2.done, v2.value);
+      return new Promise(function(resolve7, reject) {
+        v2 = o3[n3](v2), settle(resolve7, reject, v2.done, v2.value);
       });
     };
   }
-  function settle(resolve6, reject, d2, v2) {
+  function settle(resolve7, reject, d2, v2) {
     Promise.resolve(v2).then(function(v3) {
-      resolve6({ value: v3, done: d2 });
+      resolve7({ value: v3, done: d2 });
     }, reject);
   }
 }
@@ -15152,7 +15152,7 @@ function consumeBody() {
   let accum = [];
   let accumBytes = 0;
   let abort = false;
-  return new Body.Promise(function(resolve6, reject) {
+  return new Body.Promise(function(resolve7, reject) {
     let resTimeout;
     if (_this4.timeout) {
       resTimeout = setTimeout(function() {
@@ -15186,7 +15186,7 @@ function consumeBody() {
       }
       clearTimeout(resTimeout);
       try {
-        resolve6(Buffer.concat(accum, accumBytes));
+        resolve7(Buffer.concat(accum, accumBytes));
       } catch (err) {
         reject(new FetchError(`Could not create Buffer from response body for ${_this4.url}: ${err.message}`, "system", err));
       }
@@ -15449,7 +15449,7 @@ function fetch(url, opts) {
     throw new Error("native promise missing, set fetch.Promise to your favorite alternative");
   }
   Body.Promise = fetch.Promise;
-  return new fetch.Promise(function(resolve6, reject) {
+  return new fetch.Promise(function(resolve7, reject) {
     const request = new Request(url, opts);
     const options = getNodeRequestOptions(request);
     const send = (options.protocol === "https:" ? https : http).request;
@@ -15582,7 +15582,7 @@ function fetch(url, opts) {
               requestOpts.body = void 0;
               requestOpts.headers.delete("content-length");
             }
-            resolve6(fetch(new Request(locationURL, requestOpts)));
+            resolve7(fetch(new Request(locationURL, requestOpts)));
             finalize();
             return;
         }
@@ -15603,7 +15603,7 @@ function fetch(url, opts) {
       const codings = headers.get("Content-Encoding");
       if (!request.compress || request.method === "HEAD" || codings === null || res.statusCode === 204 || res.statusCode === 304) {
         response = new Response(body, response_options);
-        resolve6(response);
+        resolve7(response);
         return;
       }
       const zlibOptions = {
@@ -15613,7 +15613,7 @@ function fetch(url, opts) {
       if (codings == "gzip" || codings == "x-gzip") {
         body = body.pipe(zlib.createGunzip(zlibOptions));
         response = new Response(body, response_options);
-        resolve6(response);
+        resolve7(response);
         return;
       }
       if (codings == "deflate" || codings == "x-deflate") {
@@ -15625,12 +15625,12 @@ function fetch(url, opts) {
             body = body.pipe(zlib.createInflateRaw());
           }
           response = new Response(body, response_options);
-          resolve6(response);
+          resolve7(response);
         });
         raw.on("end", function() {
           if (!response) {
             response = new Response(body, response_options);
-            resolve6(response);
+            resolve7(response);
           }
         });
         return;
@@ -15638,11 +15638,11 @@ function fetch(url, opts) {
       if (codings == "br" && typeof zlib.createBrotliDecompress === "function") {
         body = body.pipe(zlib.createBrotliDecompress());
         response = new Response(body, response_options);
-        resolve6(response);
+        resolve7(response);
         return;
       }
       response = new Response(body, response_options);
-      resolve6(response);
+      resolve7(response);
     });
     writeToStream(req, request);
   });
@@ -16355,13 +16355,13 @@ var require_file = __commonJS({
     Object.defineProperty(exports, "__esModule", { value: true });
     var fs_1 = __require("fs");
     function resolveFile(ref) {
-      return new Promise((resolve6, reject) => {
+      return new Promise((resolve7, reject) => {
         const path = ref.href();
         fs_1.readFile(path, "utf8", (err, data) => {
           if (err) {
             reject(err);
           } else {
-            resolve6(data);
+            resolve7(data);
           }
         });
       });
@@ -23964,12 +23964,12 @@ var require_reader = __commonJS({
         }
       } else {
         try {
-          return await new Promise((resolve6, reject) => {
+          return await new Promise((resolve7, reject) => {
             fs.readFile(name, opts.encoding, (err, data) => {
               if (err !== null) {
                 reject(err);
               } else {
-                resolve6(data);
+                resolve7(data);
               }
             });
           });
@@ -40854,14 +40854,14 @@ var require_AsyncFromSyncIteratorContinuation = __commonJS({
       if (!$Promise) {
         throw new $SyntaxError("This environment does not support Promises.");
       }
-      return new $Promise(function(resolve6) {
+      return new $Promise(function(resolve7) {
         var done = IteratorComplete(result);
         var value = IteratorValue(result);
         var valueWrapper = PromiseResolve($Promise, value);
         var onFulfilled = function(value2) {
           return CreateIteratorResultObject(value2, done);
         };
-        resolve6($then(valueWrapper, onFulfilled));
+        resolve7($then(valueWrapper, onFulfilled));
       });
     };
   }
@@ -41409,7 +41409,7 @@ var require_CreateAsyncFromSyncIterator = __commonJS({
         var O2 = this;
         SLOT.assert(O2, "[[SyncIteratorRecord]]");
         var argsLength = arguments.length;
-        return new $Promise(function(resolve6) {
+        return new $Promise(function(resolve7) {
           var syncIteratorRecord = SLOT.get(O2, "[[SyncIteratorRecord]]");
           var result;
           if (argsLength > 0) {
@@ -41417,7 +41417,7 @@ var require_CreateAsyncFromSyncIterator = __commonJS({
           } else {
             result = IteratorNext(syncIteratorRecord);
           }
-          resolve6(AsyncFromSyncIteratorContinuation(result));
+          resolve7(AsyncFromSyncIteratorContinuation(result));
         });
       },
       "return": function() {
@@ -41428,12 +41428,12 @@ var require_CreateAsyncFromSyncIterator = __commonJS({
         SLOT.assert(O2, "[[SyncIteratorRecord]]");
         var valueIsPresent = arguments.length > 0;
         var value = valueIsPresent ? arguments[0] : void 0;
-        return new $Promise(function(resolve6, reject) {
+        return new $Promise(function(resolve7, reject) {
           var syncIterator = SLOT.get(O2, "[[SyncIteratorRecord]]")["[[Iterator]]"];
           var iteratorReturn = GetMethod(syncIterator, "return");
           if (typeof iteratorReturn === "undefined") {
             var iterResult = CreateIteratorResultObject(value, true);
-            Call(resolve6, void 0, [iterResult]);
+            Call(resolve7, void 0, [iterResult]);
             return;
           }
           var result;
@@ -41446,7 +41446,7 @@ var require_CreateAsyncFromSyncIterator = __commonJS({
             Call(reject, void 0, [new $TypeError("Iterator `return` method returned a non-object value.")]);
             return;
           }
-          resolve6(AsyncFromSyncIteratorContinuation(result));
+          resolve7(AsyncFromSyncIteratorContinuation(result));
         });
       },
       "throw": function() {
@@ -41457,7 +41457,7 @@ var require_CreateAsyncFromSyncIterator = __commonJS({
         SLOT.assert(O2, "[[SyncIteratorRecord]]");
         var valueIsPresent = arguments.length > 0;
         var value = valueIsPresent ? arguments[0] : void 0;
-        return new $Promise(function(resolve6, reject) {
+        return new $Promise(function(resolve7, reject) {
           var syncIterator = SLOT.get(O2, "[[SyncIteratorRecord]]")["[[Iterator]]"];
           var throwMethod = GetMethod(syncIterator, "throw");
           if (typeof throwMethod === "undefined") {
@@ -41474,7 +41474,7 @@ var require_CreateAsyncFromSyncIterator = __commonJS({
             Call(reject, void 0, [new $TypeError("Iterator `throw` method returned a non-object value.")]);
             return;
           }
-          resolve6(AsyncFromSyncIteratorContinuation(
+          resolve7(AsyncFromSyncIteratorContinuation(
             result
             /* , promiseCapability */
           ));
@@ -50431,8 +50431,10 @@ import { Command as Command7 } from "commander";
 import { Command } from "commander";
 
 // src/config/binding-loader.ts
-import { readFile as readFile2 } from "fs/promises";
-import { parse as parseYaml2 } from "yaml";
+import { readFile as readFile3 } from "fs/promises";
+import { dirname as dirname4, resolve as resolve5 } from "path";
+import { stat as stat2 } from "fs/promises";
+import { parse as parseYaml3 } from "yaml";
 
 // src/schema/agent.ts
 import { z } from "zod";
@@ -50963,51 +50965,14 @@ function resolveDslPath(dirArg, dirArgDefault, config) {
   return resolve(dirArgDefault);
 }
 
-// src/config/binding-loader.ts
-async function loadBindings(bindingPaths) {
-  const results = [];
-  for (const filePath of bindingPaths) {
-    let content;
-    try {
-      content = await readFile2(filePath, "utf8");
-    } catch {
-      throw new ConfigLoadError(
-        `Failed to read binding file: ${filePath}`,
-        filePath
-      );
-    }
-    let raw;
-    try {
-      raw = parseYaml2(content);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      throw new ConfigLoadError(
-        `Invalid YAML syntax in binding file ${filePath}: ${msg}`,
-        filePath
-      );
-    }
-    const result = SoftwareBindingSchema.safeParse(raw);
-    if (!result.success) {
-      const issues = result.error.issues.map((i3) => `  ${i3.path.join(".")}: ${i3.message}`).join("\n");
-      throw new ConfigLoadError(
-        `Invalid binding schema in ${filePath}:
-${issues}`,
-        filePath
-      );
-    }
-    results.push({ filePath, binding: result.data });
-  }
-  return results;
-}
-
 // src/resolver/base-resolver.ts
 import { resolve as resolve3, join as join2 } from "path";
 import { stat } from "fs/promises";
 
 // src/loader/loader.ts
-import { readFile as readFile3, readdir, stat as fsStat } from "fs/promises";
+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 parseYaml3 } from "yaml";
+import { parse as parseYaml2 } from "yaml";
 var DslLoadError = class extends Error {
   constructor(message, filePath) {
     super(message);
@@ -51060,7 +51025,7 @@ function hasRefs(value) {
 async function readYaml(filePath) {
   let content;
   try {
-    content = await readFile3(filePath, "utf8");
+    content = await readFile2(filePath, "utf8");
   } catch {
     throw new DslLoadError(
       `File not found: ${filePath}`,
@@ -51068,7 +51033,7 @@ async function readYaml(filePath) {
     );
   }
   try {
-    return parseYaml3(content);
+    return parseYaml2(content);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     throw new DslLoadError(
@@ -51649,6 +51614,143 @@ function substituteVars(data, vars) {
   return walk(data, vars);
 }
 
+// src/config/binding-merger.ts
+function isRecord3(v2) {
+  return typeof v2 === "object" && v2 !== null && !Array.isArray(v2);
+}
+var BINDING_MERGE_SECTIONS = ["guardrail_impl", "outputs"];
+function mergeBinding(base, project) {
+  const hasExtends = typeof project["extends"] === "string";
+  const result = { ...base, ...project };
+  for (const section of BINDING_MERGE_SECTIONS) {
+    const baseVal = base[section];
+    const projVal = project[section];
+    if (projVal === void 0) {
+      continue;
+    }
+    const baseMap = isRecord3(baseVal) ? baseVal : {};
+    result[section] = mergeEntityMaps(
+      baseMap,
+      projVal,
+      section,
+      hasExtends
+    );
+  }
+  if (project["reporting"] !== void 0 && isRecord3(base["reporting"]) && isRecord3(project["reporting"])) {
+    result["reporting"] = deepMergeEntities(
+      base["reporting"],
+      project["reporting"],
+      "reporting",
+      hasExtends
+    );
+  }
+  delete result["extends"];
+  return result;
+}
+
+// src/config/binding-loader.ts
+async function loadRawBinding(filePath) {
+  let content;
+  try {
+    content = await readFile3(filePath, "utf8");
+  } catch {
+    throw new ConfigLoadError(
+      `Failed to read binding file: ${filePath}`,
+      filePath
+    );
+  }
+  try {
+    return parseYaml3(content);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new ConfigLoadError(
+      `Invalid YAML syntax in binding file ${filePath}: ${msg}`,
+      filePath
+    );
+  }
+}
+async function resolveBindingExtends(raw, filePath, seen) {
+  const extendsValue = raw["extends"];
+  if (typeof extendsValue !== "string") {
+    return raw;
+  }
+  const bindingDir = dirname4(filePath);
+  let basePath;
+  if (extendsValue.startsWith("./") || extendsValue.startsWith("../")) {
+    basePath = resolve5(bindingDir, extendsValue);
+  } else {
+    try {
+      const resolved = import.meta.resolve(extendsValue);
+      basePath = new URL(resolved).pathname;
+    } catch {
+      throw new ConfigLoadError(
+        `Could not resolve binding extends package: ${extendsValue}`,
+        filePath
+      );
+    }
+  }
+  try {
+    const s2 = await stat2(basePath);
+    if (s2.isDirectory()) {
+      const candidates = ["binding.yaml", "binding.yml"];
+      let found = false;
+      for (const name of candidates) {
+        const candidate = resolve5(basePath, name);
+        try {
+          const cs = await stat2(candidate);
+          if (cs.isFile()) {
+            basePath = candidate;
+            found = true;
+            break;
+          }
+        } catch {
+          continue;
+        }
+      }
+      if (!found) {
+        throw new ConfigLoadError(
+          `No binding.yaml found in directory: ${basePath}`,
+          filePath
+        );
+      }
+    }
+  } catch (err) {
+    if (err instanceof ConfigLoadError) throw err;
+    throw new ConfigLoadError(
+      `Base binding path not found: ${basePath}`,
+      filePath
+    );
+  }
+  if (seen.has(basePath)) {
+    throw new ConfigLoadError(
+      `Circular binding extends detected: ${basePath}`,
+      filePath
+    );
+  }
+  seen.add(basePath);
+  const baseRaw = await loadRawBinding(basePath);
+  const resolvedBase = await resolveBindingExtends(baseRaw, basePath, seen);
+  return mergeBinding(resolvedBase, raw);
+}
+async function loadBindings(bindingPaths) {
+  const results = [];
+  for (const filePath of bindingPaths) {
+    const raw = await loadRawBinding(filePath);
+    const merged = await resolveBindingExtends(raw, filePath, /* @__PURE__ */ new Set([filePath]));
+    const result = SoftwareBindingSchema.safeParse(merged);
+    if (!result.success) {
+      const issues = result.error.issues.map((i3) => `  ${i3.path.join(".")}: ${i3.message}`).join("\n");
+      throw new ConfigLoadError(
+        `Invalid binding schema in ${filePath}:
+${issues}`,
+        filePath
+      );
+    }
+    results.push({ filePath, binding: result.data });
+  }
+  return results;
+}
+
 // src/cli/commands/resolve.ts
 import { stringify } from "yaml";
 var DIR_DEFAULT = "agent-contracts.yaml";
@@ -53179,7 +53281,7 @@ import { Command as Command4 } from "commander";
 
 // src/renderer/renderer.ts
 import { readFile as readFile4, writeFile, mkdir } from "fs/promises";
-import { dirname as dirname4 } from "path";
+import { dirname as dirname5 } from "path";
 import Handlebars from "handlebars";
 
 // src/renderer/context.ts
@@ -54302,7 +54404,7 @@ async function renderFromConfig(dsl, renderTargets) {
     if (target.context === "system") {
       const ctx = buildSystemContext(dsl);
       const output = compiled(ctx);
-      await mkdir(dirname4(target.output), { recursive: true });
+      await mkdir(dirname5(target.output), { recursive: true });
       await writeFile(target.output, output, "utf8");
       outputFiles.push(target.output);
     } else {
@@ -54313,7 +54415,7 @@ async function renderFromConfig(dsl, renderTargets) {
         const ctx = buildEntityContext(dsl, target.context, entityId);
         const output = compiled(ctx);
         const outputPath = expandOutputPath(target.output, target.context, entityId);
-        await mkdir(dirname4(outputPath), { recursive: true });
+        await mkdir(dirname5(outputPath), { recursive: true });
         await writeFile(outputPath, output, "utf8");
         outputFiles.push(outputPath);
       }
@@ -54507,7 +54609,7 @@ import { Command as Command6 } from "commander";
 
 // src/guardrail-generator/generator.ts
 import { readFile as readFile5, writeFile as writeFile2, mkdir as mkdir2, chmod } from "fs/promises";
-import { resolve as resolve5, dirname as dirname5 } from "path";
+import { resolve as resolve6, dirname as dirname6 } from "path";
 import Handlebars2 from "handlebars";
 
 // src/guardrail-generator/resolve-checks.ts
@@ -54648,7 +54750,7 @@ async function generateGuardrails(options) {
       if (pathResult.diagnostics.some((d2) => d2.severity === "error")) {
         continue;
       }
-      const targetPath = resolve5(config.configDir, pathResult.resolved);
+      const targetPath = resolve6(config.configDir, pathResult.resolved);
       let templateContent;
       if (outputDef.inline_template) {
         templateContent = outputDef.inline_template;
@@ -54661,7 +54763,7 @@ async function generateGuardrails(options) {
           });
           continue;
         }
-        const templatePath = resolve5(config.configDir, outputDef.template);
+        const templatePath = resolve6(config.configDir, outputDef.template);
         try {
           templateContent = await readFile5(templatePath, "utf8");
         } catch {
@@ -54698,9 +54800,9 @@ async function generateGuardrails(options) {
           };
           const compiled = Handlebars2.compile(templateContent, { noEscape: true });
           const output = compiled(groupCtx);
-          const groupTarget = resolve5(targetPath, groupKey);
+          const groupTarget = resolve6(targetPath, groupKey);
           if (!dryRun) {
-            await mkdir2(dirname5(groupTarget), { recursive: true });
+            await mkdir2(dirname6(groupTarget), { recursive: true });
             await writeFile2(groupTarget, output, "utf8");
             if (outputDef.executable) {
               await chmod(groupTarget, 493);
@@ -54712,7 +54814,7 @@ async function generateGuardrails(options) {
         const compiled = Handlebars2.compile(templateContent, { noEscape: true });
         const output = compiled(ctx);
         if (!dryRun) {
-          await mkdir2(dirname5(targetPath), { recursive: true });
+          await mkdir2(dirname6(targetPath), { recursive: true });
           await writeFile2(targetPath, output, "utf8");
           if (outputDef.executable) {
             await chmod(targetPath, 493);