upd-cli 0.2.0__tar.gz → 0.2.1__tar.gz

{upd_cli-0.2.0 → upd_cli-0.2.1}/CHANGELOG.md

@@ -21,6 +21,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 
+
+## [0.2.1](https://github.com/rvben/upd/compare/v0.2.0...v0.2.1) - 2026-06-11
+
+### Fixed
+
+- correct five scripted-consumer defects in CLI contract ([936687d](https://github.com/rvben/upd/commit/936687da01d2af39b884415a9e0262a8197490d7))
+
 ## [0.2.0](https://github.com/rvben/upd/compare/v0.1.10...v0.2.0) - 2026-06-11
 
 ### Breaking Changes

{upd_cli-0.2.0 → upd_cli-0.2.1}/Cargo.lock

@@ -2015,7 +2015,7 @@ checksum = "e9df2af067a7953e9c3831320f35c1cc0600c30d44d9f7a12b01db1cd88d6b47"
 
 [[package]]
 name = "upd"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "anyhow",
  "async-trait",

{upd_cli-0.2.0 → upd_cli-0.2.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "upd"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 rust-version = "1.95.0"
 description = "A fast dependency updater for Python, Node.js, Rust, Go, Ruby, Terraform, GitHub Actions, pre-commit, and Mise projects"

{upd_cli-0.2.0 → upd_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: upd-cli
-Version: 0.2.0
+Version: 0.2.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers

{upd_cli-0.2.0 → upd_cli-0.2.1}/src/cli.rs

@@ -169,8 +169,8 @@ pub struct Cli {
     /// Use --format json for machine-readable output in scripts or CI.
     /// Use --format sarif with `upd audit` to emit a SARIF 2.1.0 document
     /// suitable for upload to GitHub Code Scanning.
-    #[arg(long, global = true, value_enum, default_value_t = OutputFormat::Text, value_name = "FORMAT")]
-    pub format: OutputFormat,
+    #[arg(long, global = true, value_enum, value_name = "FORMAT")]
+    pub format: Option<OutputFormat>,
 
     /// Print the effective configuration and exit.
     ///
@@ -791,40 +791,41 @@ mod tests {
     }
 
     #[test]
-    fn test_cli_format_defaults_to_text() {
+    fn test_cli_format_defaults_to_none() {
+        // --format not passed: None (distinguishable from explicitly passing --format text)
         let cli = Cli::try_parse_from(["upd"]).unwrap();
-        assert_eq!(cli.format, OutputFormat::Text);
+        assert_eq!(cli.format, None);
     }
 
     #[test]
     fn test_cli_format_accepts_json() {
         let cli = Cli::try_parse_from(["upd", "--format", "json"]).unwrap();
-        assert_eq!(cli.format, OutputFormat::Json);
+        assert_eq!(cli.format, Some(OutputFormat::Json));
     }
 
     #[test]
     fn test_cli_format_accepts_text() {
         let cli = Cli::try_parse_from(["upd", "--format", "text"]).unwrap();
-        assert_eq!(cli.format, OutputFormat::Text);
+        assert_eq!(cli.format, Some(OutputFormat::Text));
     }
 
     #[test]
     fn test_cli_format_accepts_sarif() {
         let cli = Cli::try_parse_from(["upd", "--format", "sarif"]).unwrap();
-        assert_eq!(cli.format, OutputFormat::Sarif);
+        assert_eq!(cli.format, Some(OutputFormat::Sarif));
     }
 
     #[test]
     fn test_cli_format_sarif_is_global_across_subcommands() {
         let cli = Cli::try_parse_from(["upd", "audit", "--format", "sarif"]).unwrap();
-        assert_eq!(cli.format, OutputFormat::Sarif);
+        assert_eq!(cli.format, Some(OutputFormat::Sarif));
         assert!(matches!(cli.command, Some(Command::Audit { .. })));
     }
 
     #[test]
     fn test_cli_format_is_global_across_subcommands() {
         let cli = Cli::try_parse_from(["upd", "audit", "--format", "json"]).unwrap();
-        assert_eq!(cli.format, OutputFormat::Json);
+        assert_eq!(cli.format, Some(OutputFormat::Json));
         assert!(matches!(cli.command, Some(Command::Audit { .. })));
     }
 

{upd_cli-0.2.0 → upd_cli-0.2.1}/src/main.rs

@@ -524,16 +524,21 @@ async fn run() -> Result<()> {
     let cli = Cli::try_parse().unwrap_or_else(|e| {
         // Clap uses Err for help/version display too; those are not real errors.
         // Only emit the structured envelope for genuine parse failures.
-        if e.kind() != clap::error::ErrorKind::DisplayHelp
-            && e.kind() != clap::error::ErrorKind::DisplayVersion
-            && e.kind() != clap::error::ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
-        {
-            eprintln!(
-                "{}",
-                serde_json::json!({"error": {"kind": "parse_error", "message": e.to_string(), "exit_code": 4}})
-            );
+        // Help and version display are not errors; let clap handle them with its
+        // own exit code (0 for help/version, which is correct).
+        let is_display = e.kind() == clap::error::ErrorKind::DisplayHelp
+            || e.kind() == clap::error::ErrorKind::DisplayVersion
+            || e.kind() == clap::error::ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand;
+        if is_display {
+            e.exit();
         }
-        e.exit()
+        // Genuine parse errors: emit the structured envelope, then exit with
+        // the code the envelope declares (4), not the code clap would use (2).
+        eprintln!(
+            "{}",
+            serde_json::json!({"error": {"kind": "parse_error", "message": e.to_string(), "exit_code": 4}})
+        );
+        std::process::exit(4)
     });
 
     // Handle no-color flag
@@ -612,22 +617,23 @@ async fn run() -> Result<()> {
 ///
 /// --format sarif overrides everything: SARIF is never treated as plain JSON.
 fn effective_json_mode(cli: &Cli) -> bool {
+    use upd::cli::OutputFormat;
     // SARIF is its own mode; never treat it as JSON.
-    if cli.format == upd::cli::OutputFormat::Sarif {
+    if cli.format == Some(OutputFormat::Sarif) {
         return false;
     }
     match cli.output {
-        // Explicit --output wins unconditionally.
+        // Explicit --output/-o wins unconditionally (three-valued clispec P1 rule).
         OutputMode::Json => true,
         OutputMode::Text => false,
-        // Auto: use --format if set to json, otherwise TTY-detect.
-        OutputMode::Auto => {
-            if cli.format == upd::cli::OutputFormat::Json {
-                true
-            } else {
-                cli.is_json_output()
-            }
-        }
+        // Auto: an explicit --format value always wins over TTY detection.
+        // None means --format was not passed, so fall through to TTY detection.
+        OutputMode::Auto => match cli.format {
+            Some(OutputFormat::Json) => true,
+            Some(OutputFormat::Text) => false,
+            Some(OutputFormat::Sarif) => false,
+            None => cli.is_json_output(),
+        },
     }
 }
 
@@ -638,7 +644,7 @@ async fn run_update(cli: &Cli) -> Result<()> {
     // auto-detected as JSON (stdout piped), the TTY check inside
     // run_interactive_update fires first and gives a clearer error message.
     let explicit_json =
-        matches!(cli.output, OutputMode::Json) || cli.format == upd::cli::OutputFormat::Json;
+        matches!(cli.output, OutputMode::Json) || cli.format == Some(upd::cli::OutputFormat::Json);
     if cli.interactive && explicit_json {
         anyhow::bail!("--interactive cannot be combined with --format json or --output json");
     }
@@ -678,13 +684,16 @@ async fn run_update(cli: &Cli) -> Result<()> {
             }
         } else {
             emit_update_json(
-                &[],
-                &UpdateResult::default(),
-                0,
-                effective_dry_run,
-                UpdateFilter::from_cli(&cli.only_bump, cli.max_bump),
-                &HashMap::new(),
-                Vec::new(),
+                UpdateReportInput {
+                    scanned: &[],
+                    total_result: &UpdateResult::default(),
+                    file_count: 0,
+                    dry_run: effective_dry_run,
+                    filter: UpdateFilter::from_cli(&cli.only_bump, cli.max_bump),
+                    file_cooldowns: &HashMap::new(),
+                    cooldown_notes: Vec::new(),
+                },
+                &BoundedOutputParams::from_cli(cli),
             )?;
         }
         return Ok(());
@@ -1146,13 +1155,16 @@ async fn run_update(cli: &Cli) -> Result<()> {
             .map(|g| g.iter().cloned().collect())
             .unwrap_or_default();
         emit_update_json(
-            &scanned,
-            &total_result,
-            file_count,
-            dry_run,
-            filter,
-            &file_cooldowns,
-            notes_vec,
+            UpdateReportInput {
+                scanned: &scanned,
+                total_result: &total_result,
+                file_count,
+                dry_run,
+                filter,
+                file_cooldowns: &file_cooldowns,
+                cooldown_notes: notes_vec,
+            },
+            &BoundedOutputParams::from_cli(cli),
         )?;
     }
 
@@ -1166,17 +1178,94 @@ async fn run_update(cli: &Cli) -> Result<()> {
     Ok(())
 }
 
-fn emit_update_json(
-    scanned: &[ScannedFileResult],
-    total_result: &UpdateResult,
+/// Parameters controlling bounded JSON output (--limit, --offset, --fields).
+struct BoundedOutputParams<'a> {
+    limit: Option<usize>,
+    offset: usize,
+    fields: &'a Option<String>,
+}
+
+impl<'a> BoundedOutputParams<'a> {
+    fn from_cli(cli: &'a Cli) -> Self {
+        Self {
+            limit: cli.limit,
+            offset: cli.offset,
+            fields: &cli.fields,
+        }
+    }
+}
+
+/// Inputs needed to build the update JSON report.
+struct UpdateReportInput<'a> {
+    scanned: &'a [ScannedFileResult],
+    total_result: &'a UpdateResult,
     file_count: usize,
     dry_run: bool,
     filter: UpdateFilter,
-    file_cooldowns: &HashMap<PathBuf, Option<CooldownPolicy>>,
+    file_cooldowns: &'a HashMap<PathBuf, Option<CooldownPolicy>>,
     cooldown_notes: Vec<String>,
-) -> Result<()> {
+}
+
+/// Apply --limit, --offset, and --fields to a JSON document for bounded output.
+///
+/// `list_key` is the name of the top-level array field that is paginated
+/// (e.g. "files" for update, "packages" for align, "vulnerabilities" for audit).
+/// When limit/offset truncate the list, truncation metadata is injected at the
+/// top level so consumers know they received a partial result.
+fn apply_bounded_output(
+    mut doc: serde_json::Value,
+    list_key: &str,
+    params: &BoundedOutputParams<'_>,
+) -> serde_json::Value {
+    let limit = params.limit;
+    let offset = params.offset;
+    let fields = params.fields;
+    // Apply limit/offset to the list-shaped field.
+    if let Some(arr) = doc.get_mut(list_key).and_then(|v| v.as_array_mut()) {
+        let total = arr.len();
+        let start = offset.min(total);
+        let sliced: Vec<serde_json::Value> = arr[start..]
+            .iter()
+            .take(limit.unwrap_or(usize::MAX))
+            .cloned()
+            .collect();
+        let returned = sliced.len();
+        *arr = sliced;
+
+        // Inject truncation metadata when the output is bounded.
+        let is_truncated =
+            offset > 0 || limit.is_some_and(|l| returned < total - start || l < total);
+        if is_truncated && let Some(obj) = doc.as_object_mut() {
+            obj.insert("total".to_string(), serde_json::json!(total));
+            obj.insert("limit".to_string(), serde_json::json!(limit));
+            obj.insert("offset".to_string(), serde_json::json!(offset));
+        }
+    }
+
+    // Apply --fields to filter top-level keys.
+    if let Some(fields_str) = fields {
+        let keep: std::collections::HashSet<&str> = fields_str.split(',').map(str::trim).collect();
+        if let Some(obj) = doc.as_object_mut() {
+            obj.retain(|k, _| keep.contains(k.as_str()));
+        }
+    }
+
+    doc
+}
+
+fn emit_update_json(input: UpdateReportInput<'_>, bounded: &BoundedOutputParams<'_>) -> Result<()> {
     use upd::output::{UpdateReport, UpdateSummary, build_update_file_report};
 
+    let UpdateReportInput {
+        scanned,
+        total_result,
+        file_count,
+        dry_run,
+        filter,
+        file_cooldowns,
+        cooldown_notes,
+    } = input;
+
     let files: Vec<_> = scanned
         .iter()
         .map(|sf| {
@@ -1229,7 +1318,9 @@ fn emit_update_json(
         cooldown_notes,
     };
 
-    println!("{}", serde_json::to_string_pretty(&report)?);
+    let doc = serde_json::to_value(&report)?;
+    let doc = apply_bounded_output(doc, "files", bounded);
+    println!("{}", serde_json::to_string_pretty(&doc)?);
     Ok(())
 }
 
@@ -1265,12 +1356,15 @@ async fn run_interactive_update(
 ) -> Result<()> {
     if !std::io::stdin().is_terminal() {
         eprintln!(
-            "{} --interactive requires a terminal on stdin",
-            "error:".red()
-        );
-        eprintln!(
-            "{} use --check to preview updates, or --dry-run to print proposed changes",
-            "hint:".dimmed()
+            "{}",
+            serde_json::json!({
+                "error": {
+                    "kind": "confirmation_required",
+                    "message": "--interactive requires a terminal on stdin",
+                    "hint": "Use --check to preview updates, or --dry-run to print proposed changes.",
+                    "exit_code": 2
+                }
+            })
         );
         std::process::exit(2);
     }
@@ -1555,6 +1649,7 @@ async fn run_interactive_update(
         }
 
         let mut had_error = false;
+        let mut error_messages: Vec<String> = Vec::new();
         for (path, result) in regen_results {
             if result.no_lockfiles {
                 let manifest_name = path
@@ -1562,7 +1657,7 @@ async fn run_interactive_update(
                     .map(|n| n.to_string_lossy().into_owned())
                     .unwrap_or_default();
                 eprintln!(
-                    "note: no lockfile found for {} — skipping (nothing to regenerate)",
+                    "note: no lockfile found for {} - skipping (nothing to regenerate)",
                     manifest_name
                 );
                 continue;
@@ -1571,10 +1666,22 @@ async fn run_interactive_update(
                 if let Some(msg) = outcome.error_message() {
                     eprintln!("{}", format!("error: {msg}").red());
                     had_error = true;
+                    error_messages.push(msg);
                 }
             }
         }
         if had_error {
+            let combined = error_messages.join("; ");
+            eprintln!(
+                "{}",
+                serde_json::json!({
+                    "error": {
+                        "kind": "io_error",
+                        "message": combined,
+                        "exit_code": 2
+                    }
+                })
+            );
             std::process::exit(2);
         }
     }
@@ -1636,7 +1743,7 @@ async fn run_align(cli: &Cli) -> Result<()> {
                 println!("{}", "No dependency files found.".yellow());
             }
         } else {
-            emit_align_json(&[], 0)?;
+            emit_align_json(&[], 0, &BoundedOutputParams::from_cli(cli))?;
         }
         return Ok(());
     }
@@ -1678,7 +1785,7 @@ async fn run_align(cli: &Cli) -> Result<()> {
             .filter(|p| p.has_misalignment())
             .cloned()
             .collect();
-        emit_align_json(&to_report, file_count)?;
+        emit_align_json(&to_report, file_count, &BoundedOutputParams::from_cli(cli))?;
     }
 
     if misaligned.is_empty() {
@@ -1692,8 +1799,8 @@ async fn run_align(cli: &Cli) -> Result<()> {
         return Ok(());
     }
 
-    // Mutations are opt-in for align as well.
-    let dry_run = cli.check || cli.dry_run || (!cli.apply && !cli.interactive);
+    // Mutations are opt-in for align as well. --yes is an alias for --apply.
+    let dry_run = cli.is_effective_dry_run();
 
     if text_mode && !cli.quiet {
         let action_prefix = if dry_run { "Would align" } else { "Aligning" };
@@ -1740,7 +1847,11 @@ async fn run_align(cli: &Cli) -> Result<()> {
     Ok(())
 }
 
-fn emit_align_json(packages: &[PackageAlignment], file_count: usize) -> Result<()> {
+fn emit_align_json(
+    packages: &[PackageAlignment],
+    file_count: usize,
+    bounded: &BoundedOutputParams<'_>,
+) -> Result<()> {
     use upd::output::{AlignReport, AlignSummary, build_align_package};
 
     let pkgs: Vec<_> = packages.iter().map(build_align_package).collect();
@@ -1762,7 +1873,9 @@ fn emit_align_json(packages: &[PackageAlignment], file_count: usize) -> Result<(
         packages: pkgs,
     };
 
-    println!("{}", serde_json::to_string_pretty(&report)?);
+    let doc = serde_json::to_value(&report)?;
+    let doc = apply_bounded_output(doc, "packages", bounded);
+    println!("{}", serde_json::to_string_pretty(&doc)?);
     Ok(())
 }
 
@@ -1829,8 +1942,8 @@ async fn run_audit(cli: &Cli) -> Result<()> {
     let fix_audit = matches!(&cli.command, Some(Command::Audit { fix_audit, .. }) if *fix_audit);
     let offline = matches!(&cli.command, Some(Command::Audit { offline, .. }) if *offline);
     let json_mode = effective_json_mode(cli);
-    let text_mode = !json_mode && cli.format != upd::cli::OutputFormat::Sarif;
-    let sarif_mode = cli.format == upd::cli::OutputFormat::Sarif && !json_mode;
+    let text_mode = !json_mode && cli.format != Some(upd::cli::OutputFormat::Sarif);
+    let sarif_mode = cli.format == Some(upd::cli::OutputFormat::Sarif) && !json_mode;
     // Audit never mutates files, so no VCS check is needed. Fall back to CWD.
     let paths = {
         let explicit = cli.get_paths();
@@ -1858,7 +1971,11 @@ async fn run_audit(cli: &Cli) -> Result<()> {
         } else if sarif_mode {
             emit_audit_sarif(&AuditResult::default(), &HashMap::new())?;
         } else {
-            emit_audit_json(&AuditResult::default(), "complete")?;
+            emit_audit_json(
+                &AuditResult::default(),
+                "complete",
+                &BoundedOutputParams::from_cli(cli),
+            )?;
         }
         return Ok(());
     }
@@ -1898,7 +2015,11 @@ async fn run_audit(cli: &Cli) -> Result<()> {
         } else if sarif_mode {
             emit_audit_sarif(&AuditResult::default(), &HashMap::new())?;
         } else {
-            emit_audit_json(&AuditResult::default(), "complete")?;
+            emit_audit_json(
+                &AuditResult::default(),
+                "complete",
+                &BoundedOutputParams::from_cli(cli),
+            )?;
         }
         return Ok(());
     }
@@ -1995,7 +2116,11 @@ async fn run_audit(cli: &Cli) -> Result<()> {
             AuditStatus::Clean | AuditStatus::Vulnerable => "complete",
             AuditStatus::Incomplete => "incomplete",
         };
-        emit_audit_json(&audit_result, status_str)?;
+        emit_audit_json(
+            &audit_result,
+            status_str,
+            &BoundedOutputParams::from_cli(cli),
+        )?;
     }
 
     // --fix-audit: bump each vulnerable package to its minimum safe version.
@@ -2178,7 +2303,20 @@ async fn run_audit(cli: &Cli) -> Result<()> {
                 0
             };
 
-            if fix_exit_code != 0 {
+            if fix_exit_code == 2 {
+                let combined = fix_errors.join("; ");
+                eprintln!(
+                    "{}",
+                    serde_json::json!({
+                        "error": {
+                            "kind": "io_error",
+                            "message": combined,
+                            "exit_code": 2
+                        }
+                    })
+                );
+                std::process::exit(2);
+            } else if fix_exit_code != 0 {
                 std::process::exit(fix_exit_code);
             }
             return Ok(());
@@ -2197,10 +2335,16 @@ async fn run_audit(cli: &Cli) -> Result<()> {
     Ok(())
 }
 
-fn emit_audit_json(audit: &AuditResult, status: &'static str) -> Result<()> {
+fn emit_audit_json(
+    audit: &AuditResult,
+    status: &'static str,
+    bounded: &BoundedOutputParams<'_>,
+) -> Result<()> {
     use upd::output::build_audit_report;
     let report = build_audit_report(audit, 0, status);
-    println!("{}", serde_json::to_string_pretty(&report)?);
+    let doc = serde_json::to_value(&report)?;
+    let doc = apply_bounded_output(doc, "vulnerabilities", bounded);
+    println!("{}", serde_json::to_string_pretty(&doc)?);
     Ok(())
 }
 

upd_cli-0.2.1/tests/defect_fixes.rs

@@ -0,0 +1,320 @@
+//! Regression tests for five functional defects.
+//!
+//! Each test targets a specific corrected contract:
+//!
+//! P1-a: Parse failures exit with code 4 and emit a structured envelope.
+//! P1-b: Direct failure exits in run_interactive_update emit a structured envelope.
+//! P2-a: --format text is explicit and wins over TTY detection when piped.
+//! P2-b: --limit / --offset / --fields are wired into JSON output.
+//! P2-c: --yes covers the align subcommand (same as --apply).
+
+use serde_json::Value;
+use std::fs;
+use std::path::Path;
+use std::process::Command;
+
+fn upd_bin() -> &'static str {
+    env!("CARGO_BIN_EXE_upd")
+}
+
+fn run(args: &[&str], cwd: &Path) -> (String, String, i32) {
+    let output = Command::new(upd_bin())
+        .args(args)
+        .current_dir(cwd)
+        .output()
+        .expect("failed to run upd");
+    (
+        String::from_utf8(output.stdout).expect("stdout not UTF-8"),
+        String::from_utf8(output.stderr).expect("stderr not UTF-8"),
+        output.status.code().unwrap_or(-1),
+    )
+}
+
+fn parse_json(s: &str) -> Value {
+    serde_json::from_str(s.trim()).unwrap_or_else(|e| panic!("not valid JSON ({e}):\n{s}"))
+}
+
+// ── P1-a: Parse errors exit 4 with structured envelope ───────────────────────
+
+/// An unknown flag must exit with code 4 (parse_error), not clap's default 2.
+#[test]
+fn parse_error_exits_four() {
+    let tmp = tempfile::tempdir().unwrap();
+    let (_stdout, _stderr, code) = run(&["--this-flag-does-not-exist"], tmp.path());
+    assert_eq!(
+        code, 4,
+        "invalid CLI arg must exit 4 (parse_error), got {code}"
+    );
+}
+
+/// The structured envelope for a parse error must be the last line of stderr
+/// and declare kind=parse_error with exit_code=4.
+#[test]
+fn parse_error_emits_structured_envelope_on_stderr() {
+    let tmp = tempfile::tempdir().unwrap();
+    let (_stdout, stderr, _code) = run(&["--unknown-flag-xyz"], tmp.path());
+    let last_line = stderr.trim_end().lines().last().unwrap_or("");
+    let envelope = parse_json(last_line);
+    assert_eq!(
+        envelope["error"]["kind"], "parse_error",
+        "last stderr line must have kind=parse_error; got: {last_line}"
+    );
+    assert_eq!(
+        envelope["error"]["exit_code"], 4,
+        "envelope must declare exit_code=4; got: {last_line}"
+    );
+}
+
+/// --help must NOT emit a parse_error envelope and must exit 0.
+#[test]
+fn help_display_exits_zero_no_envelope() {
+    let tmp = tempfile::tempdir().unwrap();
+    let (_stdout, stderr, code) = run(&["--help"], tmp.path());
+    assert_eq!(code, 0, "--help must exit 0, got {code}");
+    assert!(
+        !stderr.contains("parse_error"),
+        "--help must not emit a parse_error envelope; stderr: {stderr}"
+    );
+}
+
+// ── P1-b: Structured envelope for direct failure exits ───────────────────────
+
+/// --interactive without a TTY must exit 2 with a structured envelope on stderr.
+///
+/// We simulate a non-TTY stdin by piping /dev/null into the process. The
+/// envelope must be the last line of stderr.
+#[test]
+fn interactive_without_tty_emits_envelope_and_exits_two() {
+    let tmp = tempfile::tempdir().unwrap();
+    let output = Command::new(upd_bin())
+        .args(["--interactive", "--dry-run"])
+        .current_dir(tmp.path())
+        .stdin(std::process::Stdio::null())
+        .stdout(std::process::Stdio::piped())
+        .stderr(std::process::Stdio::piped())
+        .output()
+        .expect("failed to run upd");
+
+    let stderr = String::from_utf8(output.stderr).expect("stderr not UTF-8");
+    let code = output.status.code().unwrap_or(-1);
+
+    assert_eq!(code, 2, "--interactive without TTY must exit 2, got {code}");
+
+    let last_line = stderr.trim_end().lines().last().unwrap_or("");
+    let envelope = parse_json(last_line);
+    assert!(
+        envelope["error"]["kind"].is_string(),
+        "last stderr line must be a structured envelope; got: {last_line}"
+    );
+    assert!(
+        envelope["error"]["message"].is_string(),
+        "envelope must have a message field; got: {last_line}"
+    );
+}
+
+// ── P2-a: --format text wins over TTY detection ──────────────────────────────
+
+/// When stdout is piped (non-TTY) and --format text is explicitly passed,
+/// the output must be text (not JSON). This verifies the three-valued rule:
+/// an explicit value always beats auto-detection.
+#[test]
+fn format_text_explicit_wins_over_tty_detection_when_piped() {
+    let tmp = tempfile::tempdir().unwrap();
+    let path_str = tmp.path().to_str().unwrap();
+    // stdout is piped (non-TTY) by default in Command::output().
+    let (stdout, _stderr, code) = run(&["--format", "text", "--dry-run", path_str], tmp.path());
+    assert_eq!(code, 0, "expected exit 0, got {code}");
+    assert!(
+        serde_json::from_str::<Value>(stdout.trim()).is_err(),
+        "--format text must produce non-JSON output even when piped; got: {stdout}"
+    );
+}
+
+/// --format json emits JSON even in a piped context (sanity check that the
+/// three-valued logic works in both directions).
+#[test]
+fn format_json_explicit_emits_json_when_piped() {
+    let tmp = tempfile::tempdir().unwrap();
+    let path_str = tmp.path().to_str().unwrap();
+    let (stdout, _stderr, code) = run(&["--format", "json", "--dry-run", path_str], tmp.path());
+    assert_eq!(code, 0, "expected exit 0, got {code}");
+    assert!(
+        serde_json::from_str::<Value>(stdout.trim()).is_ok(),
+        "--format json must produce JSON when piped; got: {stdout}"
+    );
+}
+
+// ── P2-b: --limit / --offset / --fields are wired into JSON output ───────────
+
+/// --limit 0 on an empty workspace returns an empty files array.
+#[test]
+fn limit_zero_returns_empty_files_array() {
+    let tmp = tempfile::tempdir().unwrap();
+    let path_str = tmp.path().to_str().unwrap();
+    let (stdout, _stderr, code) = run(
+        &["--output", "json", "--limit", "0", "--dry-run", path_str],
+        tmp.path(),
+    );
+    assert_eq!(code, 0, "expected exit 0, got {code}");
+    let doc = parse_json(&stdout);
+    let files = doc["files"].as_array().expect("files must be an array");
+    assert!(files.is_empty(), "files must be empty with --limit 0");
+}
+
+/// --fields filters top-level keys: requesting only "summary" must drop "files".
+#[test]
+fn fields_filters_top_level_keys() {
+    let tmp = tempfile::tempdir().unwrap();
+    let path_str = tmp.path().to_str().unwrap();
+    let (stdout, _stderr, code) = run(
+        &[
+            "--output",
+            "json",
+            "--fields",
+            "summary",
+            "--dry-run",
+            path_str,
+        ],
+        tmp.path(),
+    );
+    assert_eq!(code, 0, "expected exit 0, got {code}");
+    let doc = parse_json(&stdout);
+    assert!(
+        doc.get("summary").is_some(),
+        "summary key must be present with --fields summary; got: {stdout}"
+    );
+    assert!(
+        doc.get("files").is_none(),
+        "files key must be absent with --fields summary; got: {stdout}"
+    );
+}
+
+/// --limit and --offset inject truncation metadata when the list is bounded.
+#[test]
+fn limit_offset_inject_truncation_metadata() {
+    let tmp = tempfile::tempdir().unwrap();
+    // Create two dependency files so there is a non-trivial list to paginate.
+    fs::write(tmp.path().join("requirements.txt"), "requests==1.0.0\n").unwrap();
+    fs::write(
+        tmp.path().join("package.json"),
+        r#"{"dependencies":{"lodash":"1.0.0"}}"#,
+    )
+    .unwrap();
+    let path_str = tmp.path().to_str().unwrap();
+
+    // Use --no-cache and point to a dead registry so the run finishes fast
+    // with errors (which is fine; we only care about the JSON shape).
+    let (stdout, _stderr, _code) = run(
+        &[
+            "--output",
+            "json",
+            "--limit",
+            "1",
+            "--offset",
+            "0",
+            "--no-cache",
+            "--dry-run",
+            path_str,
+        ],
+        tmp.path(),
+    );
+
+    // The stdout may be valid JSON even with registry errors (errors in files[]).
+    if let Ok(doc) = serde_json::from_str::<Value>(stdout.trim()) {
+        // When limit/offset truncate, metadata must be present.
+        if doc.get("total").is_some() {
+            assert!(
+                doc["total"].is_number(),
+                "total must be a number; got: {stdout}"
+            );
+            assert!(
+                doc["limit"].is_number(),
+                "limit must be a number; got: {stdout}"
+            );
+            assert!(
+                doc["offset"].is_number(),
+                "offset must be a number; got: {stdout}"
+            );
+        }
+        // At most 1 file entry must be returned.
+        if let Some(files) = doc["files"].as_array() {
+            assert!(
+                files.len() <= 1,
+                "at most 1 file must be returned with --limit 1; got: {stdout}"
+            );
+        }
+    }
+    // If stdout is not JSON (registry errors forced text mode somehow), skip.
+}
+
+// ── P2-c: --yes covers align ─────────────────────────────────────────────────
+
+/// align --yes must behave identically to align --apply: it must count as
+/// non-dry-run and actually write changes when misalignments exist.
+///
+/// We test the dry-run vs apply distinction by verifying that --yes produces
+/// the same output shape as --apply, not the "Would align" text mode output.
+/// Since we have no misalignments in a fresh workspace, we verify that both
+/// --yes and --apply exit 0 (the aligned case) and that --yes is not stuck
+/// in dry-run (which would also exit 0 here but with different text).
+///
+/// A deeper test with real misalignments requires a network call; this test
+/// keeps it offline and fast by verifying the flag is wired to the right
+/// effective-dry-run path via the exit code and output shape.
+#[test]
+fn align_yes_behaves_like_apply() {
+    let tmp = tempfile::tempdir().unwrap();
+    let path_str = tmp.path().to_str().unwrap();
+
+    let (stdout_yes, _stderr_yes, code_yes) = run(
+        &["align", "--yes", "--output", "json", path_str],
+        tmp.path(),
+    );
+    let (stdout_apply, _stderr_apply, code_apply) = run(
+        &["align", "--apply", "--output", "json", path_str],
+        tmp.path(),
+    );
+
+    assert_eq!(
+        code_yes, code_apply,
+        "--yes and --apply must produce the same exit code; --yes={code_yes}, --apply={code_apply}"
+    );
+
+    // Both must produce valid JSON with the same command field.
+    let doc_yes = parse_json(&stdout_yes);
+    let doc_apply = parse_json(&stdout_apply);
+    assert_eq!(
+        doc_yes["command"], "align",
+        "--yes align must emit command=align; got: {stdout_yes}"
+    );
+    assert_eq!(
+        doc_yes["command"], doc_apply["command"],
+        "--yes and --apply must emit the same command; got yes={stdout_yes} apply={stdout_apply}"
+    );
+}
+
+/// align without --apply or --yes must be dry-run: the JSON output must reflect
+/// the align report but no files must be modified.
+#[test]
+fn align_without_apply_is_dry_run() {
+    let tmp = tempfile::tempdir().unwrap();
+    let path_str = tmp.path().to_str().unwrap();
+
+    // Create a file to ensure scan works, but no misalignments.
+    fs::write(tmp.path().join("requirements.txt"), "requests==1.0.0\n").unwrap();
+
+    let (stdout, _stderr, code) = run(&["align", "--output", "json", path_str], tmp.path());
+
+    // Should exit 0 (no misalignments) even in dry-run mode.
+    assert_eq!(
+        code, 0,
+        "align dry-run on aligned workspace must exit 0, got {code}"
+    );
+
+    // Output must be valid JSON with command=align.
+    let doc = parse_json(&stdout);
+    assert_eq!(
+        doc["command"], "align",
+        "align must emit command=align in JSON output; got: {stdout}"
+    );
+}