agent-contracts 0.11.2 → 0.11.4

package/README.md

@@ -297,7 +297,7 @@ Design regressions become testable.
 * **Structured handoff definitions** with formal JSON Schema and `allOf` composition
 * **Reusable schema components** via `components.schemas` and JSON Pointer `$ref`
 * **Artifact ownership and lifecycle modeling**
-* **Config-driven prompt rendering**
+* **Config-driven prompt rendering** with `skip_empty` support for conditional file generation
 * **Variable substitution** via `${vars.xxx}` in DSL values
 * **Inheritance with merge operators via `extends`**
 * **Guardrail definitions** for cross-cutting process constraints
@@ -865,6 +865,44 @@ This lets you generate static outputs for:
 
 all from the same resolved DSL.
 
+### Render target options
+
+Each entry in `renders` supports these fields:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `template` | string | yes | Path to Handlebars template |
+| `context` | string | yes | Context type (see below) |
+| `output` | string | yes | Output file path (supports `{<context>.id}` placeholder) |
+| `include` | string[] | no | Only render these entity IDs (not with `system`) |
+| `exclude` | string[] | no | Skip these entity IDs (not with `system`) |
+| `skip_empty` | boolean | no | When `true`, if the rendered output is empty or whitespace-only, the file is **not written**. If the file already exists, it is **deleted**. |
+
+#### `skip_empty` usage
+
+`skip_empty` is useful when a single template applies to all entities of a context type, but only some entities produce meaningful output.
+
+For example, when using `context: tool` to generate per-tool scripts, tools without an `x-script` property would produce empty files. With `skip_empty: true`, those files are simply not created:
+
+````yaml
+renders:
+  - template: ./templates/tool-script.sh.hbs
+    context: tool
+    output: ./output/scripts/{tool.id}.sh
+    skip_empty: true
+````
+
+````handlebars
+{{!-- tool-script.sh.hbs --}}
+{{#if tool.x-script}}
+{{{tool.x-script}}}
+{{/if}}
+````
+
+Tools with `x-script` get a generated script file; tools without it produce no file at all.
+
+`skip_empty` also works with `render --check` (drift detection): when the expected output is empty, the check expects the file to **not exist** and reports drift if it does.
+
 ### Available context types
 
 Each `context` type provides a different rendering scope:

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(resolve7) {
-      resolve7(value);
+    return value instanceof P2 ? value : new P2(function(resolve8) {
+      resolve8(value);
     });
   }
-  return new (P2 || (P2 = Promise))(function(resolve7, reject) {
+  return new (P2 || (P2 = Promise))(function(resolve8, reject) {
     function fulfilled(value) {
       try {
         step(generator.next(value));
@@ -179,7 +179,7 @@ function __awaiter(thisArg, _arguments, P2, generator) {
       }
     }
     function step(result) {
-      result.done ? resolve7(result.value) : adopt(result.value).then(fulfilled, rejected);
+      result.done ? resolve8(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(resolve7, reject) {
-        v2 = o3[n3](v2), settle(resolve7, reject, v2.done, v2.value);
+      return new Promise(function(resolve8, reject) {
+        v2 = o3[n3](v2), settle(resolve8, reject, v2.done, v2.value);
       });
     };
   }
-  function settle(resolve7, reject, d2, v2) {
+  function settle(resolve8, reject, d2, v2) {
     Promise.resolve(v2).then(function(v3) {
-      resolve7({ value: v3, done: d2 });
+      resolve8({ 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(resolve7) {
-      resolve7(value);
+    return value instanceof P2 ? value : new P2(function(resolve8) {
+      resolve8(value);
     });
   }
-  return new (P2 || (P2 = Promise))(function(resolve7, reject) {
+  return new (P2 || (P2 = Promise))(function(resolve8, reject) {
     function fulfilled(value) {
       try {
         step(generator.next(value));
@@ -13053,7 +13053,7 @@ function __awaiter2(thisArg, _arguments, P2, generator) {
       }
     }
     function step(result) {
-      result.done ? resolve7(result.value) : adopt(result.value).then(fulfilled, rejected);
+      result.done ? resolve8(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(resolve7, reject) {
-        v2 = o3[n3](v2), settle(resolve7, reject, v2.done, v2.value);
+      return new Promise(function(resolve8, reject) {
+        v2 = o3[n3](v2), settle(resolve8, reject, v2.done, v2.value);
       });
     };
   }
-  function settle(resolve7, reject, d2, v2) {
+  function settle(resolve8, reject, d2, v2) {
     Promise.resolve(v2).then(function(v3) {
-      resolve7({ value: v3, done: d2 });
+      resolve8({ value: v3, done: d2 });
     }, reject);
   }
 }
@@ -15152,7 +15152,7 @@ function consumeBody() {
   let accum = [];
   let accumBytes = 0;
   let abort = false;
-  return new Body.Promise(function(resolve7, reject) {
+  return new Body.Promise(function(resolve8, reject) {
     let resTimeout;
     if (_this4.timeout) {
       resTimeout = setTimeout(function() {
@@ -15186,7 +15186,7 @@ function consumeBody() {
       }
       clearTimeout(resTimeout);
       try {
-        resolve7(Buffer.concat(accum, accumBytes));
+        resolve8(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(resolve7, reject) {
+  return new fetch.Promise(function(resolve8, 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");
             }
-            resolve7(fetch(new Request(locationURL, requestOpts)));
+            resolve8(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);
-        resolve7(response);
+        resolve8(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);
-        resolve7(response);
+        resolve8(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);
-          resolve7(response);
+          resolve8(response);
         });
         raw.on("end", function() {
           if (!response) {
             response = new Response(body, response_options);
-            resolve7(response);
+            resolve8(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);
-        resolve7(response);
+        resolve8(response);
         return;
       }
       response = new Response(body, response_options);
-      resolve7(response);
+      resolve8(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((resolve7, reject) => {
+      return new Promise((resolve8, reject) => {
         const path = ref.href();
         fs_1.readFile(path, "utf8", (err, data) => {
           if (err) {
             reject(err);
           } else {
-            resolve7(data);
+            resolve8(data);
           }
         });
       });
@@ -23964,12 +23964,12 @@ var require_reader = __commonJS({
         }
       } else {
         try {
-          return await new Promise((resolve7, reject) => {
+          return await new Promise((resolve8, reject) => {
             fs.readFile(name, opts.encoding, (err, data) => {
               if (err !== null) {
                 reject(err);
               } else {
-                resolve7(data);
+                resolve8(data);
               }
             });
           });
@@ -40854,14 +40854,14 @@ var require_AsyncFromSyncIteratorContinuation = __commonJS({
       if (!$Promise) {
         throw new $SyntaxError("This environment does not support Promises.");
       }
-      return new $Promise(function(resolve7) {
+      return new $Promise(function(resolve8) {
         var done = IteratorComplete(result);
         var value = IteratorValue(result);
         var valueWrapper = PromiseResolve($Promise, value);
         var onFulfilled = function(value2) {
           return CreateIteratorResultObject(value2, done);
         };
-        resolve7($then(valueWrapper, onFulfilled));
+        resolve8($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(resolve7) {
+        return new $Promise(function(resolve8) {
           var syncIteratorRecord = SLOT.get(O2, "[[SyncIteratorRecord]]");
           var result;
           if (argsLength > 0) {
@@ -41417,7 +41417,7 @@ var require_CreateAsyncFromSyncIterator = __commonJS({
           } else {
             result = IteratorNext(syncIteratorRecord);
           }
-          resolve7(AsyncFromSyncIteratorContinuation(result));
+          resolve8(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(resolve7, reject) {
+        return new $Promise(function(resolve8, reject) {
           var syncIterator = SLOT.get(O2, "[[SyncIteratorRecord]]")["[[Iterator]]"];
           var iteratorReturn = GetMethod(syncIterator, "return");
           if (typeof iteratorReturn === "undefined") {
             var iterResult = CreateIteratorResultObject(value, true);
-            Call(resolve7, void 0, [iterResult]);
+            Call(resolve8, 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;
           }
-          resolve7(AsyncFromSyncIteratorContinuation(result));
+          resolve8(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(resolve7, reject) {
+        return new $Promise(function(resolve8, 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;
           }
-          resolve7(AsyncFromSyncIteratorContinuation(
+          resolve8(AsyncFromSyncIteratorContinuation(
             result
             /* , promiseCapability */
           ));
@@ -50425,6 +50425,9 @@ var require_dist13 = __commonJS({
 });
 
 // src/cli/cli.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { resolve as resolve7, dirname as dirname7 } from "path";
 import { Command as Command7 } from "commander";
 
 // src/cli/commands/resolve.ts
@@ -50526,7 +50529,8 @@ var BindingOutputSchema = z3.object({
   inline_template: z3.string().optional(),
   mode: z3.enum(["write", "patch"]).default("write"),
   group_by: z3.string().optional(),
-  executable: z3.boolean().optional()
+  executable: z3.boolean().optional(),
+  skip_empty: z3.boolean().optional()
 }).passthrough().refine(
   (data) => !(data.template && data.inline_template),
   { message: "template and inline_template are mutually exclusive" }
@@ -50860,7 +50864,8 @@ var RenderTargetSchema = z14.object({
   context: ContextTypeSchema,
   output: z14.string(),
   include: z14.array(z14.string()).optional(),
-  exclude: z14.array(z14.string()).optional()
+  exclude: z14.array(z14.string()).optional(),
+  skip_empty: z14.boolean().optional()
 }).refine(
   (data) => !(data.include && data.exclude),
   { message: "include and exclude are mutually exclusive" }
@@ -53281,7 +53286,7 @@ var lintCommand = new Command3("lint").description("Run semantic lint rules on r
 import { Command as Command4 } from "commander";
 
 // src/renderer/renderer.ts
-import { readFile as readFile4, writeFile, mkdir } from "fs/promises";
+import { readFile as readFile4, writeFile, mkdir, unlink } from "fs/promises";
 import { dirname as dirname5 } from "path";
 import Handlebars from "handlebars";
 
@@ -54397,6 +54402,15 @@ function buildEntityContext(dsl, context, entityId) {
 async function loadTemplate(templatePath) {
   return readFile4(templatePath, "utf8");
 }
+function isEffectivelyEmpty(output) {
+  return output.trim().length === 0;
+}
+async function removeIfExists(filePath) {
+  try {
+    await unlink(filePath);
+  } catch {
+  }
+}
 async function renderFromConfig(dsl, renderTargets) {
   const outputFiles = [];
   for (const target of renderTargets) {
@@ -54405,6 +54419,10 @@ async function renderFromConfig(dsl, renderTargets) {
     if (target.context === "system") {
       const ctx = buildSystemContext(dsl);
       const output = compiled(ctx);
+      if (target.skip_empty && isEffectivelyEmpty(output)) {
+        await removeIfExists(target.output);
+        continue;
+      }
       await mkdir(dirname5(target.output), { recursive: true });
       await writeFile(target.output, output, "utf8");
       outputFiles.push(target.output);
@@ -54416,6 +54434,10 @@ async function renderFromConfig(dsl, renderTargets) {
         const ctx = buildEntityContext(dsl, target.context, entityId);
         const output = compiled(ctx);
         const outputPath = expandOutputPath(target.output, target.context, entityId);
+        if (target.skip_empty && isEffectivelyEmpty(output)) {
+          await removeIfExists(outputPath);
+          continue;
+        }
         await mkdir(dirname5(outputPath), { recursive: true });
         await writeFile(outputPath, output, "utf8");
         outputFiles.push(outputPath);
@@ -54424,6 +54446,26 @@ async function renderFromConfig(dsl, renderTargets) {
   }
   return outputFiles;
 }
+async function fileExists2(filePath) {
+  try {
+    await readFile4(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function checkExpectedVsExisting(expected, outputPath, skipEmpty, diffs) {
+  if (skipEmpty && isEffectivelyEmpty(expected)) {
+    return fileExists2(outputPath).then((exists) => {
+      if (exists) diffs.push(outputPath);
+    });
+  }
+  return readFile4(outputPath, "utf8").then((existing) => {
+    if (existing !== expected) diffs.push(outputPath);
+  }).catch(() => {
+    diffs.push(outputPath);
+  });
+}
 async function checkDriftFromConfig(dsl, renderTargets) {
   const diffs = [];
   for (const target of renderTargets) {
@@ -54432,12 +54474,7 @@ async function checkDriftFromConfig(dsl, renderTargets) {
     if (target.context === "system") {
       const ctx = buildSystemContext(dsl);
       const expected = compiled(ctx);
-      try {
-        const existing = await readFile4(target.output, "utf8");
-        if (existing !== expected) diffs.push(target.output);
-      } catch {
-        diffs.push(target.output);
-      }
+      await checkExpectedVsExisting(expected, target.output, target.skip_empty, diffs);
     } else {
       const section = getDslSection(dsl, target.context);
       const allIds = Object.keys(section);
@@ -54446,12 +54483,7 @@ async function checkDriftFromConfig(dsl, renderTargets) {
         const ctx = buildEntityContext(dsl, target.context, entityId);
         const expected = compiled(ctx);
         const outputPath = expandOutputPath(target.output, target.context, entityId);
-        try {
-          const existing = await readFile4(outputPath, "utf8");
-          if (existing !== expected) diffs.push(outputPath);
-        } catch {
-          diffs.push(outputPath);
-        }
+        await checkExpectedVsExisting(expected, outputPath, target.skip_empty, diffs);
       }
     }
   }
@@ -54609,7 +54641,7 @@ var checkCommand = new Command5("check").description("Run full pipeline: resolve
 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 { readFile as readFile5, writeFile as writeFile2, mkdir as mkdir2, chmod, unlink as unlink2 } from "fs/promises";
 import { resolve as resolve6, dirname as dirname6 } from "path";
 import Handlebars2 from "handlebars";
 
@@ -54783,6 +54815,7 @@ async function generateGuardrails(options) {
         });
         continue;
       }
+      const shouldSkipEmpty = outputDef.skip_empty === true;
       if (outputDef.group_by) {
         const groupField = outputDef.group_by;
         const groups = /* @__PURE__ */ new Map();
@@ -54802,6 +54835,15 @@ async function generateGuardrails(options) {
           const compiled = Handlebars2.compile(templateContent, { noEscape: true });
           const output = compiled(groupCtx);
           const groupTarget = resolve6(targetPath, groupKey);
+          if (shouldSkipEmpty && output.trim().length === 0) {
+            if (!dryRun) {
+              try {
+                await unlink2(groupTarget);
+              } catch {
+              }
+            }
+            continue;
+          }
           if (!dryRun) {
             await mkdir2(dirname6(groupTarget), { recursive: true });
             await writeFile2(groupTarget, output, "utf8");
@@ -54814,14 +54856,23 @@ async function generateGuardrails(options) {
       } else {
         const compiled = Handlebars2.compile(templateContent, { noEscape: true });
         const output = compiled(ctx);
-        if (!dryRun) {
-          await mkdir2(dirname6(targetPath), { recursive: true });
-          await writeFile2(targetPath, output, "utf8");
-          if (outputDef.executable) {
-            await chmod(targetPath, 493);
+        if (shouldSkipEmpty && output.trim().length === 0) {
+          if (!dryRun) {
+            try {
+              await unlink2(targetPath);
+            } catch {
+            }
+          }
+        } else {
+          if (!dryRun) {
+            await mkdir2(dirname6(targetPath), { recursive: true });
+            await writeFile2(targetPath, output, "utf8");
+            if (outputDef.executable) {
+              await chmod(targetPath, 493);
+            }
           }
+          outputFiles.push(targetPath);
         }
-        outputFiles.push(targetPath);
       }
     }
   }
@@ -54913,8 +54964,10 @@ var generateGuardrailsCommand = new Command6("generate").description("Generate g
 );
 
 // src/cli/cli.ts
+var __dirname = dirname7(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync(resolve7(__dirname, "../package.json"), "utf8"));
 var program = new Command7();
-program.name("agent-contracts").description("Agent contracts tooling \u2014 validate, lint, render DSL files").version("0.0.2");
+program.name("agent-contracts").description("Agent contracts tooling \u2014 validate, lint, render DSL files").version(pkg.version);
 program.addCommand(resolveCommand);
 program.addCommand(validateCommand);
 program.addCommand(lintCommand);