migraguard 0.9.0 → 0.9.1

package/cli-contract.yaml

@@ -900,12 +900,23 @@ commandSets:
               enum: [warning, error, critical]
               default: error
 
+          - name: output
+            aliases: [o]
+            description: Write result to a file instead of stdout.
+            valueName: file
+            schema:
+              type: string
+            file:
+              mode: write
+              mediaType: application/json
+              encoding: utf-8
+
           - name: report-format
             description: Output format for the audit report.
             valueName: fmt
             schema:
               type: string
-              enum: [text, json]
+              enum: [json, text, yaml]
               default: text
 
         exits:
@@ -947,9 +958,13 @@ commandSets:
           riskLevel: low
           requiresConfirmation: false
           idempotent: true
-          sideEffects:
-            - network
+          sideEffects: [network]
+          sideEffectNote: >-
+            Network calls to LLM provider when adapter is not mock.
+            Filesystem write only when --output is specified.
           safeDryRunOption: dry-run
+          expectedDurationMs: 120000
+          retryableExitCodes: [1, 12]
 
       # ── propose-expand-contract ───────────────────────
       propose-expand-contract:
@@ -1005,11 +1020,38 @@ commandSets:
               type: boolean
               default: false
 
+          - name: fail-on
+            description: Minimum severity that causes a non-zero exit.
+            valueName: level
+            schema:
+              type: string
+              enum: [warning, error, critical]
+              default: error
+
+          - name: output
+            aliases: [o]
+            description: Write result to a file instead of stdout.
+            valueName: file
+            schema:
+              type: string
+            file:
+              mode: write
+              mediaType: application/json
+              encoding: utf-8
+
+          - name: report-format
+            description: Output format for the proposal report.
+            valueName: fmt
+            schema:
+              type: string
+              enum: [json, text, yaml]
+              default: json
+
         exits:
           '0':
             description: Proposal generated successfully.
             stdout:
-              format: json
+              format: '{options.report-format}'
               schema:
                 $ref: '#/components/schemas/ExpandContractProposal'
 
@@ -1023,6 +1065,13 @@ commandSets:
             stderr:
               format: text
 
+          '10':
+            description: Completed with blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/ExpandContractProposal'
+
           '11':
             description: Runtime dependency missing (agent-contracts-runtime).
             stderr:
@@ -1037,10 +1086,13 @@ commandSets:
           riskLevel: low
           requiresConfirmation: false
           idempotent: true
-          sideEffects:
-            - network
-            - file_write
+          sideEffects: [network, file_write]
+          sideEffectNote: >-
+            Network calls to LLM provider when adapter is not mock.
+            Filesystem write when --output or --output-dir is specified.
           safeDryRunOption: dry-run
+          expectedDurationMs: 120000
+          retryableExitCodes: [1, 12]
 
       # ── explain ───────────────────────────────────────
       explain:
@@ -1084,11 +1136,38 @@ commandSets:
               type: boolean
               default: false
 
+          - name: fail-on
+            description: Minimum severity that causes a non-zero exit.
+            valueName: level
+            schema:
+              type: string
+              enum: [warning, error, critical]
+              default: error
+
+          - name: output
+            aliases: [o]
+            description: Write result to a file instead of stdout.
+            valueName: file
+            schema:
+              type: string
+            file:
+              mode: write
+              mediaType: application/json
+              encoding: utf-8
+
+          - name: report-format
+            description: Output format for the explanation report.
+            valueName: fmt
+            schema:
+              type: string
+              enum: [json, text, yaml]
+              default: json
+
         exits:
           '0':
             description: Explanation generated.
             stdout:
-              format: json
+              format: '{options.report-format}'
               schema:
                 $ref: '#/components/schemas/ExplainResult'
 
@@ -1102,6 +1181,13 @@ commandSets:
             stderr:
               format: text
 
+          '10':
+            description: Completed with blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/ExplainResult'
+
           '11':
             description: Runtime dependency missing (agent-contracts-runtime).
             stderr:
@@ -1116,9 +1202,13 @@ commandSets:
           riskLevel: low
           requiresConfirmation: false
           idempotent: true
-          sideEffects:
-            - network
+          sideEffects: [network]
+          sideEffectNote: >-
+            Network calls to LLM provider when adapter is not mock.
+            Filesystem write only when --output is specified.
           safeDryRunOption: dry-run
+          expectedDurationMs: 120000
+          retryableExitCodes: [1, 12]
 
 components:
   schemas:

package/dist/cli.js

@@ -314,10 +314,11 @@ var init_handoffs = __esm({
         recommendation: z.string().optional(),
         confidence: z.number().optional(),
         evidence: z.array(z.object({
-          kind: z.enum(["file", "command", "schema", "diff", "stdout", "stderr", "text"]),
-          target: z.string().optional(),
-          location: z.string().optional(),
-          excerpt: z.string().optional()
+          type: z.string().optional(),
+          content: z.string().optional(),
+          source: z.string().optional(),
+          kind: z.enum(["file", "command", "schema", "diff", "stdout", "stderr", "text"]).optional(),
+          location: z.string().optional()
         })).optional(),
         details: z.record(z.string(), z.unknown()).optional()
       })),
@@ -6089,8 +6090,6 @@ async function runAgentTask(userRequest, taskId, auditConfig, options) {
     retriesUsed: result.retries_used
   };
 }
-
-// src/agents/formatter.ts
 function computeExitCode(result, options) {
   if (result.dryRun) return 0;
   if (result.status !== "success" || !result.data) return 1;
@@ -6149,6 +6148,35 @@ function formatResultJson(result) {
   }
   return JSON.stringify(result.data, null, 2);
 }
+function formatResultYaml(result) {
+  if (result.dryRun) {
+    return `dryRun: true
+prompt: |
+${indent(result.prompt)}`;
+  }
+  if (!result.data) {
+    return `error: ${JSON.stringify(result.errorMessage)}
+status: ${result.status}`;
+  }
+  return toSimpleYaml(result.data);
+}
+function formatResult(result, format) {
+  switch (format) {
+    case "json":
+      return formatResultJson(result);
+    case "yaml":
+      return formatResultYaml(result);
+    case "text":
+      return formatResultText(result);
+  }
+}
+async function writeOutput(content, outputPath) {
+  if (outputPath) {
+    await writeFile(outputPath, content + "\n", "utf-8");
+  } else {
+    process.stdout.write(content + "\n");
+  }
+}
 function severityIcon(severity) {
   switch (severity) {
     case "critical":
@@ -6161,6 +6189,47 @@ function severityIcon(severity) {
       return "\u2139";
   }
 }
+function indent(text, spaces = 2) {
+  const pad = " ".repeat(spaces);
+  return text.split("\n").map((l) => pad + l).join("\n");
+}
+function toSimpleYaml(obj, depth = 0) {
+  const pad = "  ".repeat(depth);
+  if (obj === null || obj === void 0) return `${pad}null`;
+  if (typeof obj === "string") {
+    if (obj.includes("\n")) return `|
+${indent(obj, (depth + 1) * 2)}`;
+    return JSON.stringify(obj);
+  }
+  if (typeof obj === "number" || typeof obj === "boolean") return String(obj);
+  if (Array.isArray(obj)) {
+    if (obj.length === 0) return "[]";
+    return obj.map((item) => {
+      const val = toSimpleYaml(item, depth + 1);
+      if (typeof item === "object" && item !== null) {
+        return `${pad}- ${val.trimStart()}`;
+      }
+      return `${pad}- ${val}`;
+    }).join("\n");
+  }
+  if (typeof obj === "object") {
+    const entries = Object.entries(obj);
+    if (entries.length === 0) return "{}";
+    return entries.map(([k, v]) => {
+      const val = toSimpleYaml(v, depth + 1);
+      if (typeof v === "object" && v !== null && !Array.isArray(v)) {
+        return `${pad}${k}:
+${val}`;
+      }
+      if (Array.isArray(v) && v.length > 0) {
+        return `${pad}${k}:
+${val}`;
+      }
+      return `${pad}${k}: ${val}`;
+    }).join("\n");
+  }
+  return String(obj);
+}
 
 // src/commands/audit.ts
 async function commandAudit(config, target, opts) {
@@ -6180,12 +6249,8 @@ async function commandAudit(config, target, opts) {
       auditConfig,
       auditOpts
     );
-    const format = opts.reportFormat ?? "text";
-    if (format === "json") {
-      process.stdout.write(formatResultJson(result) + "\n");
-    } else {
-      process.stdout.write(formatResultText(result) + "\n");
-    }
+    const content = formatResult(result, opts.reportFormat ?? "text");
+    await writeOutput(content, opts.output);
     const exitCode = computeExitCode(result, auditOpts);
     if (exitCode !== 0) process.exit(exitCode);
   } catch (err) {
@@ -6208,7 +6273,8 @@ async function commandProposeExpandContract(config, file, opts) {
     model: opts.model
   };
   const auditOpts = {
-    dryRun: opts.dryRun
+    dryRun: opts.dryRun,
+    failOn: opts.failOn
   };
   try {
     const result = await runAgentTask(
@@ -6217,10 +6283,6 @@ async function commandProposeExpandContract(config, file, opts) {
       auditConfig,
       auditOpts
     );
-    if (result.dryRun) {
-      process.stdout.write(formatResultText(result) + "\n");
-      return;
-    }
     if (result.data && opts.outputDir && result.data.recommendedActions) {
       const outDir = resolve(opts.outputDir);
       await mkdir(outDir, { recursive: true });
@@ -6232,7 +6294,8 @@ async function commandProposeExpandContract(config, file, opts) {
         }
       }
     }
-    process.stdout.write(formatResultJson(result) + "\n");
+    const content = formatResult(result, opts.reportFormat ?? "json");
+    await writeOutput(content, opts.output);
     const exitCode = computeExitCode(result, auditOpts);
     if (exitCode !== 0) process.exit(exitCode);
   } catch (err) {
@@ -6261,7 +6324,8 @@ async function commandExplain(_config, opts) {
     model: opts.model
   };
   const auditOpts = {
-    dryRun: opts.dryRun
+    dryRun: opts.dryRun,
+    failOn: opts.failOn
   };
   try {
     const result = await runAgentTask(
@@ -6270,11 +6334,10 @@ async function commandExplain(_config, opts) {
       auditConfig,
       auditOpts
     );
-    if (result.dryRun) {
-      process.stdout.write(formatResultText(result) + "\n");
-    } else {
-      process.stdout.write(formatResultJson(result) + "\n");
-    }
+    const content = formatResult(result, opts.reportFormat ?? "json");
+    await writeOutput(content, opts.output);
+    const exitCode = computeExitCode(result, auditOpts);
+    if (exitCode !== 0) process.exit(exitCode);
   } catch (err) {
     const exitCode = err.exitCode;
     if (exitCode === EXIT_RUNTIME_MISSING) {
@@ -6413,23 +6476,32 @@ program.command("deps").description("Analyze and display migration dependency gr
   const result = await commandDeps(config, { html: opts.html });
   if (!result.ok) process.exit(1);
 }));
-program.command("audit [target]").description("Run LLM-based migration safety audit").option("-a, --adapter <name>", "SDK adapter (cursor, claude, openai, gemini, mock)").option("--model <name>", "LLM model override").option("-n, --dry-run", "Output prompt without calling LLM").option("--fail-on <level>", "Minimum severity for non-zero exit (warning, error, critical)", "error").option("--report-format <fmt>", "Output format (text, json)", "text").action((target, opts) => run(async () => {
+program.command("audit [target]").description("Run LLM-based migration safety audit").option("-a, --adapter <name>", "SDK adapter (cursor, claude, openai, gemini, mock)").option("--model <name>", "LLM model override").option("-n, --dry-run", "Output prompt without calling LLM").option("--fail-on <level>", "Minimum severity for non-zero exit (warning, error, critical)", "error").option("-o, --output <file>", "Write result to a file instead of stdout").option("--report-format <fmt>", "Output format (json, text, yaml)", "text").action((target, opts) => run(async () => {
   const config = await loadConfig();
   await commandAudit(config, target, {
     adapter: opts.adapter,
     model: opts.model,
     dryRun: opts.dryRun,
     failOn: opts.failOn,
+    output: opts.output,
     reportFormat: opts.reportFormat
   });
 }));
-program.command("propose-expand-contract <file>").description("Propose expand/contract migration group from unsafe DDL").option("-a, --adapter <name>", "SDK adapter (cursor, claude, openai, gemini, mock)").option("--model <name>", "LLM model override").option("-n, --dry-run", "Output prompt without calling LLM").option("--output-dir <dir>", "Directory to write proposed phase files").action((file, opts) => run(async () => {
+program.command("propose-expand-contract <file>").description("Propose expand/contract migration group from unsafe DDL").option("-a, --adapter <name>", "SDK adapter (cursor, claude, openai, gemini, mock)").option("--model <name>", "LLM model override").option("-n, --dry-run", "Output prompt without calling LLM").option("--fail-on <level>", "Minimum severity for non-zero exit (warning, error, critical)", "error").option("-o, --output <file>", "Write result to a file instead of stdout").option("--report-format <fmt>", "Output format (json, text, yaml)", "json").option("--output-dir <dir>", "Directory to write proposed phase files").action((file, opts) => run(async () => {
   const config = await loadConfig();
-  await commandProposeExpandContract(config, file, opts);
+  await commandProposeExpandContract(config, file, {
+    ...opts,
+    failOn: opts.failOn,
+    reportFormat: opts.reportFormat
+  });
 }));
-program.command("explain").description("Explain command output in human-readable form using LLM").option("-a, --adapter <name>", "SDK adapter (cursor, claude, openai, gemini, mock)").option("--model <name>", "LLM model override").option("-n, --dry-run", "Output prompt without calling LLM").action((opts) => run(async () => {
+program.command("explain").description("Explain command output in human-readable form using LLM").option("-a, --adapter <name>", "SDK adapter (cursor, claude, openai, gemini, mock)").option("--model <name>", "LLM model override").option("-n, --dry-run", "Output prompt without calling LLM").option("--fail-on <level>", "Minimum severity for non-zero exit (warning, error, critical)", "error").option("-o, --output <file>", "Write result to a file instead of stdout").option("--report-format <fmt>", "Output format (json, text, yaml)", "json").action((opts) => run(async () => {
   const config = await loadConfig();
-  await commandExplain(config, opts);
+  await commandExplain(config, {
+    ...opts,
+    failOn: opts.failOn,
+    reportFormat: opts.reportFormat
+  });
 }));
 program.parse();
 //# sourceMappingURL=cli.js.map