agent-contracts 0.19.3 → 0.19.5

package/cli-contract.yaml

@@ -3,7 +3,7 @@ cliContracts: 0.1.0
 
 info:
   title: agent-contracts CLI
-  version: 0.19.2
+  version: 0.19.4
   description: >-
     Declarative YAML DSL toolkit for defining, validating, and rendering
     multi-agent development workflows. Provides static validation,
@@ -625,44 +625,81 @@ commandSets:
             schema:
               type: string
 
+          - name: fail-on
+            description: >-
+              Minimum finding severity that causes exit 10
+              (info|warning|error|critical).
+            valueName: level
+            schema:
+              type: string
+              enum: [info, warning, error, critical]
+              default: critical
+
+          - name: output
+            aliases: [o]
+            description: Write result to a file instead of stdout.
+            valueName: file
+            schema:
+              type: string
+            file:
+              mode: write
+              encoding: utf-8
+
+          - name: report-format
+            description: >-
+              Alias for --format. When both are specified, --report-format
+              takes precedence.
+            valueName: fmt
+            schema:
+              type: string
+              enum: [text, json, markdown]
+              default: text
+
         exits:
           '0':
-            description: No critical findings detected.
+            description: Audit succeeded. No findings at or above --fail-on threshold.
             stdout:
               format: '{options.format}'
-              schemaNote: >-
-                Audit findings are always emitted on stdout as the primary
-                output. Format depends on --format option (text, json, or
-                markdown).
+              schema:
+                $ref: './dsl_base/components.yaml#/schemas/agent-audit-result'
 
           '1':
-            description: Critical findings detected.
+            description: Unexpected error (invalid input, config error, or internal failure).
             stderr:
               format: text
-              schemaNote: >-
-                Summary diagnostic on stderr. Structured findings are
-                emitted on stdout in the requested --format.
+
+          '10':
+            description: Findings at or above --fail-on severity threshold detected.
             stdout:
               format: '{options.format}'
+              schema:
+                $ref: './dsl_base/components.yaml#/schemas/agent-audit-result'
+            stderr:
+              format: text
               schemaNote: >-
-                Full findings output. Exit 1 indicates at least one
-                critical-severity finding exists; the findings themselves
-                are valid structured data, not error messages.
+                Summary diagnostic on stderr. Structured findings are
+                emitted on stdout in the requested format.
 
-          '2':
-            description: Invalid input or configuration error.
+          '11':
+            description: >-
+              Runtime dependency missing (agent-contracts-runtime not installed).
             stderr:
               format: text
 
-          '3':
-            description: LLM adapter error (API failure, runtime not installed).
+          '12':
+            description: LLM provider or adapter error (API failure, auth error).
             stderr:
               format: text
 
         x-agent:
           riskLevel: medium
           requiresConfirmation: false
-          idempotent: true
+          idempotent: false
+          idempotentNote: >-
+            Safe to repeat (no persistent side effects beyond network calls),
+            but LLM inference is non-deterministic — identical inputs may
+            produce different findings, severity assignments, and
+            recommendation text across runs.
           sideEffects:
             - network
           sideEffectNote: >-
@@ -671,7 +708,7 @@ commandSets:
             cost and sends DSL content to the LLM provider.
           safeDryRunOption: dry-run
           expectedDurationMs: 120000
-          retryableExitCodes: [3]
+          retryableExitCodes: [12]
           recommendedBeforeUse:
             - Ensure agent-contracts.config.yaml exists with render targets.
             - Run validate first to confirm DSL is valid.

package/dist/cli.js

@@ -49565,18 +49565,27 @@ async function resolveRefsDeep(data, baseDir, resolving, rootDoc) {
       }
       resolving.add(refValue);
       const target = resolveJsonPointer(rootDoc, refValue);
-      const resolved2 = await resolveRefsDeep(
+      const resolved = await resolveRefsDeep(
         deepClone(target),
         baseDir,
         resolving,
         rootDoc
       );
       resolving.delete(refValue);
-      return resolved2;
+      return resolved;
     }
-    const refTarget = resolve2(baseDir, refValue);
+    const hashIdx = refValue.indexOf("#");
+    const filePart = hashIdx >= 0 ? refValue.slice(0, hashIdx) : refValue;
+    const fragment = hashIdx >= 0 ? refValue.slice(hashIdx) : null;
+    const refTarget = resolve2(baseDir, filePart);
     const s2 = await fsStat(refTarget).catch(() => null);
     if (s2?.isDirectory()) {
+      if (fragment) {
+        throw new DslLoadError(
+          `Cannot use JSON Pointer fragment with directory $ref: ${refValue}`,
+          refTarget
+        );
+      }
       if (resolving.has(refTarget)) {
         throw new DslLoadError(
           `Circular $ref detected: ${refTarget}`,
@@ -49599,14 +49608,24 @@ async function resolveRefsDeep(data, baseDir, resolving, rootDoc) {
     }
     resolving.add(refTarget);
     const content = await readYaml(refTarget);
-    const resolved = await resolveRefsDeep(
+    const fileRoot = fragment ? content : rootDoc;
+    let fileData = await resolveRefsDeep(
       content,
       dirname2(refTarget),
       resolving,
-      rootDoc
+      fileRoot
     );
     resolving.delete(refTarget);
-    return resolved;
+    if (fragment && fragment.startsWith("#/")) {
+      if (!isRecord(fileData)) {
+        throw new DslLoadError(
+          `Cannot resolve fragment "${fragment}" in ${refTarget}: file content is not an object`,
+          refTarget
+        );
+      }
+      fileData = resolveJsonPointer(fileData, fragment);
+    }
+    return fileData;
   }
   let obj = data;
   if (hasRefs(obj)) {
@@ -55898,6 +55917,7 @@ ${issues}
 );
 
 // src/cli/commands/audit.ts
+import { writeFileSync as writeFileSync2 } from "fs";
 import { Command as Command8 } from "commander";
 
 // src/auditor/context-builder.ts
@@ -56632,16 +56652,22 @@ function formatAuditResults(results, format2) {
   }
   return results.map((r3) => formatAuditResult(r3, format2)).join("\n\n");
 }
-function computeExitCode(results) {
+function computeExitCode(results, failOn) {
   for (const r3 of results) {
     if (r3.status === "error") {
-      if (r3.errorMessage?.includes("not installed") || r3.errorMessage?.includes("adapter")) return 3;
-      return 2;
+      if (r3.errorMessage?.includes("not installed")) return 11;
+      if (r3.errorMessage?.includes("adapter") || r3.errorMessage?.includes("API")) return 12;
+      return 1;
     }
   }
+  const severityRank = { info: 0, warning: 1, error: 2, critical: 3 };
+  const threshold = severityRank[failOn ?? "critical"] ?? 3;
   for (const r3 of results) {
-    if (r3.data?.critical_gaps && r3.data.critical_gaps.some((g2) => g2.severity === "critical")) {
-      return 1;
+    if (r3.data?.critical_gaps) {
+      for (const gap of r3.data.critical_gaps) {
+        const rank = severityRank[gap.severity ?? ""] ?? 0;
+        if (rank >= threshold) return 10;
+      }
     }
   }
   return 0;
@@ -56659,13 +56685,13 @@ function parseAuditConfig(config) {
     cache_dir: audit.cache_dir
   };
 }
-async function runAuditForDsl(dslPath, vars, configObj, auditType, opts) {
+async function runAuditForDsl(dslPath, vars, configObj, auditType, opts, failOn) {
   const resolved = await resolve4(dslPath);
   const data = vars ? substituteVars(resolved.data, vars) : resolved.data;
   const schemaResult = validateSchema(data);
   if (!schemaResult.success) {
     process.stderr.write("Schema validation failed. Run 'agent-contracts validate' first.\n");
-    return 2;
+    return { exitCode: 1, output: "" };
   }
   const auditConfig = parseAuditConfig(
     configObj.audit
@@ -56678,17 +56704,18 @@ async function runAuditForDsl(dslPath, vars, configObj, auditType, opts) {
       scope: opts.scope,
       dryRun: opts.dryRun
     });
+    let output2;
     if (opts.dryRun) {
-      for (const r3 of results) {
-        process.stdout.write(`
+      output2 = results.map(
+        (r3) => `
 --- Audit prompt: ${r3.auditType} ---
-`);
-        process.stdout.write(r3.prompt + "\n");
-      }
+${r3.prompt}
+`
+      ).join("");
     } else {
-      process.stdout.write(formatAuditResults(results, opts.format) + "\n");
+      output2 = formatAuditResults(results, opts.format) + "\n";
     }
-    return computeExitCode(results);
+    return { exitCode: computeExitCode(results, failOn), output: output2 };
   }
   const result = await runAudit(schemaResult.data, configObj, auditConfig, {
     auditType,
@@ -56696,67 +56723,78 @@ async function runAuditForDsl(dslPath, vars, configObj, auditType, opts) {
     scope: opts.scope,
     dryRun: opts.dryRun
   });
+  let output;
   if (opts.dryRun) {
-    process.stdout.write(result.prompt + "\n");
+    output = result.prompt + "\n";
   } else {
-    process.stdout.write(formatAuditResult(result, opts.format) + "\n");
+    output = formatAuditResult(result, opts.format) + "\n";
   }
-  return computeExitCode([result]);
+  return { exitCode: computeExitCode([result], failOn), output };
 }
-var auditCommand = new Command8("audit").description("Run LLM-based semantic audit on DSL definitions and generated outputs").argument("[type]", `Audit type: ${AUDIT_TYPES.join(", ")}`, "all").option("-c, --config <path>", "Path to agent-contracts.config.yaml").option("--team <id>", "Limit to one team (multi-team config only)").option("--format <format>", "Output format (text|json|markdown)", "text").option("--scope <entities>", "Limit audit scope (e.g. agents:architect,implementer)").option("--dry-run", "Output the audit prompt without calling LLM", false).option("--adapter <name>", "SDK adapter to use (default from config)").option("--model <name>", "LLM model override").action(
+var auditCommand = new Command8("audit").description("Run LLM-based semantic audit on DSL definitions and generated outputs").argument("[type]", `Audit type: ${AUDIT_TYPES.join(", ")}`, "all").option("-c, --config <path>", "Path to agent-contracts.config.yaml").option("--team <id>", "Limit to one team (multi-team config only)").option("--format <format>", "Output format (text|json|markdown)", "text").option("--scope <entities>", "Limit audit scope (e.g. agents:architect,implementer)").option("--dry-run", "Output the audit prompt without calling LLM", false).option("--adapter <name>", "SDK adapter to use (default from config)").option("--model <name>", "LLM model override").option("--fail-on <level>", "Minimum severity that causes exit 10 (info|warning|error|critical)", "critical").option("-o, --output <file>", "Write result to a file instead of stdout").option("--report-format <fmt>", "Alias for --format (for cli-contracts standard conformance)").action(
   async (type, opts) => {
     if (!AUDIT_TYPES.includes(type)) {
       process.stderr.write(
         `Unknown audit type: "${type}". Use one of: ${AUDIT_TYPES.join(", ")}
 `
       );
-      process.exit(2);
+      process.exit(1);
     }
-    const format2 = opts.format;
+    const format2 = opts.reportFormat ?? opts.format;
     try {
       const config = await loadConfig(opts.config);
       if (!config) {
         process.stderr.write(
           "Error: agent-contracts.config.yaml not found. Use --config to specify path.\n"
         );
-        process.exit(2);
+        process.exit(1);
       }
       if (isMultiTeamConfig(config)) {
         const teamEntries = getTeamEntries(config, opts.team);
         let maxExit = 0;
+        const allOutput = [];
         for (const [teamId, teamConfig] of teamEntries) {
           process.stderr.write(`
 --- Team: ${teamId} ---
 `);
-          const exitCode2 = await runAuditForDsl(
+          const result2 = await runAuditForDsl(
             teamConfig.dsl,
             teamConfig.vars,
             config,
             type,
-            { format: format2, scope: opts.scope, dryRun: opts.dryRun, adapter: opts.adapter, model: opts.model }
+            { format: format2, scope: opts.scope, dryRun: opts.dryRun, adapter: opts.adapter, model: opts.model },
+            opts.failOn
           );
-          if (exitCode2 > maxExit) maxExit = exitCode2;
+          process.stdout.write(result2.output);
+          allOutput.push(result2.output);
+          if (result2.exitCode > maxExit) maxExit = result2.exitCode;
         }
+        if (opts.output) writeFileSync2(opts.output, allOutput.join(""), "utf8");
         process.exit(maxExit);
       }
-      const exitCode = await runAuditForDsl(
+      const result = await runAuditForDsl(
         config.dsl,
         config.vars,
         config,
         type,
-        { format: format2, scope: opts.scope, dryRun: opts.dryRun, adapter: opts.adapter, model: opts.model }
+        { format: format2, scope: opts.scope, dryRun: opts.dryRun, adapter: opts.adapter, model: opts.model },
+        opts.failOn
       );
-      process.exit(exitCode);
+      process.stdout.write(result.output);
+      if (opts.output) writeFileSync2(opts.output, result.output, "utf8");
+      process.exit(result.exitCode);
     } catch (err) {
       if (err instanceof ConfigLoadError) {
         process.stderr.write(`Config error: ${err.message}
 `);
-        process.exit(2);
+        process.exit(1);
       }
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(`Error: ${msg}
 `);
-      process.exit(err instanceof Error && msg.includes("not installed") ? 3 : 2);
+      if (msg.includes("not installed")) process.exit(11);
+      if (msg.includes("adapter") || msg.includes("API")) process.exit(12);
+      process.exit(1);
     }
   }
 );