agent-contracts 0.11.1 → 0.11.3

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

@@ -50498,17 +50498,18 @@ import { z as z3 } from "zod";
 var CommandRegexMatcherSchema = z3.object({
   type: z3.literal("command_regex"),
   pattern: z3.string()
-});
+}).passthrough();
 var ContentRegexMatcherSchema = z3.object({
   type: z3.literal("content_regex"),
   pattern: z3.string(),
   file_glob: z3.string().optional(),
   exclude_glob: z3.string().optional()
-});
+}).passthrough();
 var FileGlobMatcherSchema = z3.object({
   type: z3.literal("file_glob"),
-  pattern: z3.string()
-});
+  pattern: z3.string(),
+  exclude_glob: z3.string().optional()
+}).passthrough();
 var MatcherSchema = z3.discriminatedUnion("type", [
   CommandRegexMatcherSchema,
   ContentRegexMatcherSchema,
@@ -50525,7 +50526,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" }
@@ -50859,7 +50861,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" }
@@ -53280,7 +53283,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";
 
@@ -54396,6 +54399,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) {
@@ -54404,6 +54416,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);
@@ -54415,6 +54431,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);
@@ -54423,6 +54443,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) {
@@ -54431,12 +54471,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);
@@ -54445,12 +54480,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);
       }
     }
   }
@@ -54608,7 +54638,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";
 
@@ -54782,6 +54812,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();
@@ -54801,6 +54832,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");
@@ -54813,14 +54853,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);
       }
     }
   }