unifi-cli 0.3.1__tar.gz → 0.3.2__tar.gz

{unifi_cli-0.3.1 → unifi_cli-0.3.2}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.2](https://github.com/rvben/unifi-cli/compare/v0.3.1...v0.3.2) - 2026-08-10
+
+### Fixed
+
+- **config**: write the config atomically on Windows too ([0c2977e](https://github.com/rvben/unifi-cli/commit/0c2977e238ccb09ca2949560568c4f8b8fd528db))
+- **config**: replace the config file atomically instead of writing in place ([9ba19fb](https://github.com/rvben/unifi-cli/commit/9ba19fbde8b498488f43b1af1ab1d2771189d672))
+- **output**: keep 408 and 429 retryable instead of permanent client errors ([1068bae](https://github.com/rvben/unifi-cli/commit/1068baed75ce232028fec0277c1ca38324723a35))
+- **ports**: keep the attachment flag tri-state instead of reading absence as gone ([de2e770](https://github.com/rvben/unifi-cli/commit/de2e770d30cbc3cba64cf5b06640549a9655c776))
+- **config**: create the credentials file with owner-only permissions ([8b7789d](https://github.com/rvben/unifi-cli/commit/8b7789d2d87edc5819e950573130000370c6939f))
+- **schema**: publish an error and confirmation contract that matches runtime ([5176ccf](https://github.com/rvben/unifi-cli/commit/5176ccfefeb08df4fecd0d7a6d83882f5e06c57f))
+- **ports**: report a stale last connection as unattached ([e80cda5](https://github.com/rvben/unifi-cli/commit/e80cda542fce27db385fc43bd69093c265ead464))
+
 ## [0.3.1](https://github.com/rvben/unifi-cli/compare/v0.3.0...v0.3.1) - 2026-08-10
 
 ### Added

{unifi_cli-0.3.1 → unifi_cli-0.3.2}/Cargo.lock

@@ -2786,7 +2786,7 @@ checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
 
 [[package]]
 name = "unifi-cli"
-version = "0.3.1"
+version = "0.3.2"
 dependencies = [
  "clap",
  "clap_complete",

{unifi_cli-0.3.1 → unifi_cli-0.3.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "unifi-cli"
-version = "0.3.1"
+version = "0.3.2"
 edition = "2024"
 rust-version = "1.90"
 description = "CLI for UniFi Network controller"

{unifi_cli-0.3.1 → unifi_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-cli
-Version: 0.3.1
+Version: 0.3.2
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: System Administrators
@@ -79,7 +79,17 @@ export UNIFI_ACCEPT_INVALID_CERTS=true
 
 ### Config file
 
-`~/.config/unifi/config.toml`:
+Linux: `~/.config/unifi/config.toml`.
+macOS: `~/Library/Application Support/unifi/config.toml`.
+Windows: `%APPDATA%\unifi\config.toml`.
+
+`unifi config init` writes a new file and renames it over any existing config
+instead of writing in place, so a failed write leaves the previous config
+intact. On Linux and macOS the new file is created with mode 0600, since it
+holds an API key and optionally a Protect password. Because the credentials go
+straight into a file that is already 0600, they are never readable by another
+local account, not even for the moment between the write and a chmod. On
+Windows the file inherits its directory's ACL.
 
 ```toml
 host = "https://unifi.example.com"
@@ -131,6 +141,11 @@ act. On a terminal you get a yes/no question naming the target; declining exits
 terminal there is nobody to ask, so they refuse with the same error unless you
 pass `--yes`, which skips the question everywhere.
 
+`unifi schema` marks exactly these commands `confirmation_required: true`, so a
+caller can tell them apart from mutating commands that act immediately
+(`devices locate`, `clients set-fixed-ip`, `protect rtsps create`) without
+hardcoding the list.
+
 ## TUI dashboard
 
 ```bash
@@ -211,9 +226,17 @@ A device that has moved between switch ports appears once per port it has
 ever used, with a `connected` field distinguishing its current port from
 stale history.
 
-`ports show` exposes PoE telemetry the CLI previously discarded:
-`poe_mode`, `poe_class`, `poe_voltage`, `poe_current`, `poe_good`, and the
-MAC of the attached device (`attached_mac`).
+`ports show` exposes the port's PoE telemetry: `poe_mode`, `poe_class`,
+`poe_voltage`, `poe_current`, `poe_good`, and the MAC of the attached device
+(`attached_mac`). The controller keeps a port's last connection record after
+the device is unplugged, so `attached_mac` is set only when the controller
+affirms the record is live. The MAC is still reported as
+`attached_last_seen_mac` and the controller's own flag as `attached_connected`
+(true, false, or null when the firmware does not report it), so a caller can
+tell "gone" from "not reported". The text output renders the three cases as
+`aa:bb:cc:dd:ee:ff`, `- (last seen aa:bb:cc:dd:ee:ff)` and
+`unknown (last seen aa:bb:cc:dd:ee:ff)`. Nothing that has been unplugged is
+ever presented as currently attached.
 
 `ports cycle` is destructive. On a terminal it shows what is about to lose
 power and asks for confirmation; when piped it requires `--yes` and
@@ -326,15 +349,21 @@ unifi schema    # Dumps all commands, arguments, output fields as JSON
 
 ### Distinct exit codes
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | General error |
-| 2 | Configuration error |
-| 3 | Authentication error (401/403) |
-| 4 | Not found (404) |
-| 5 | API error (server error) |
-| 6 | Conflict (ambiguous match or failed precondition) |
+| Code | `kind` | Meaning |
+|------|--------|---------|
+| 0 | - | Success |
+| 1 | `general_error` | General error (including transport failures) |
+| 2 | `config_error` | Configuration or usage error |
+| 2 | `confirmation_required` | A destructive command ran without `--yes` and without a TTY |
+| 3 | `auth_error` | Authentication error (401/403) |
+| 4 | `not_found` | Not found (404) |
+| 5 | `client_error` | The controller rejected the request itself (4xx other than 401/403/404/408/429); retrying it unchanged cannot help |
+| 5 | `retry_later` | The controller invited a retry (429 rate limited, 408 request timeout); back off and send the same request again |
+| 5 | `api_error` | The controller failed to serve the request (5xx); may be transient |
+| 6 | `conflict` | The request cannot succeed against the resource's current state, refused locally before any API call |
+
+`unifi schema` publishes the same table under `errors`, with a `retryable` flag
+per kind, so an agent can branch on it without parsing prose.
 
 ## Development
 

{unifi_cli-0.3.1 → unifi_cli-0.3.2}/README.md

@@ -58,7 +58,17 @@ export UNIFI_ACCEPT_INVALID_CERTS=true
 
 ### Config file
 
-`~/.config/unifi/config.toml`:
+Linux: `~/.config/unifi/config.toml`.
+macOS: `~/Library/Application Support/unifi/config.toml`.
+Windows: `%APPDATA%\unifi\config.toml`.
+
+`unifi config init` writes a new file and renames it over any existing config
+instead of writing in place, so a failed write leaves the previous config
+intact. On Linux and macOS the new file is created with mode 0600, since it
+holds an API key and optionally a Protect password. Because the credentials go
+straight into a file that is already 0600, they are never readable by another
+local account, not even for the moment between the write and a chmod. On
+Windows the file inherits its directory's ACL.
 
 ```toml
 host = "https://unifi.example.com"
@@ -110,6 +120,11 @@ act. On a terminal you get a yes/no question naming the target; declining exits
 terminal there is nobody to ask, so they refuse with the same error unless you
 pass `--yes`, which skips the question everywhere.
 
+`unifi schema` marks exactly these commands `confirmation_required: true`, so a
+caller can tell them apart from mutating commands that act immediately
+(`devices locate`, `clients set-fixed-ip`, `protect rtsps create`) without
+hardcoding the list.
+
 ## TUI dashboard
 
 ```bash
@@ -190,9 +205,17 @@ A device that has moved between switch ports appears once per port it has
 ever used, with a `connected` field distinguishing its current port from
 stale history.
 
-`ports show` exposes PoE telemetry the CLI previously discarded:
-`poe_mode`, `poe_class`, `poe_voltage`, `poe_current`, `poe_good`, and the
-MAC of the attached device (`attached_mac`).
+`ports show` exposes the port's PoE telemetry: `poe_mode`, `poe_class`,
+`poe_voltage`, `poe_current`, `poe_good`, and the MAC of the attached device
+(`attached_mac`). The controller keeps a port's last connection record after
+the device is unplugged, so `attached_mac` is set only when the controller
+affirms the record is live. The MAC is still reported as
+`attached_last_seen_mac` and the controller's own flag as `attached_connected`
+(true, false, or null when the firmware does not report it), so a caller can
+tell "gone" from "not reported". The text output renders the three cases as
+`aa:bb:cc:dd:ee:ff`, `- (last seen aa:bb:cc:dd:ee:ff)` and
+`unknown (last seen aa:bb:cc:dd:ee:ff)`. Nothing that has been unplugged is
+ever presented as currently attached.
 
 `ports cycle` is destructive. On a terminal it shows what is about to lose
 power and asks for confirmation; when piped it requires `--yes` and
@@ -305,15 +328,21 @@ unifi schema    # Dumps all commands, arguments, output fields as JSON
 
 ### Distinct exit codes
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | General error |
-| 2 | Configuration error |
-| 3 | Authentication error (401/403) |
-| 4 | Not found (404) |
-| 5 | API error (server error) |
-| 6 | Conflict (ambiguous match or failed precondition) |
+| Code | `kind` | Meaning |
+|------|--------|---------|
+| 0 | - | Success |
+| 1 | `general_error` | General error (including transport failures) |
+| 2 | `config_error` | Configuration or usage error |
+| 2 | `confirmation_required` | A destructive command ran without `--yes` and without a TTY |
+| 3 | `auth_error` | Authentication error (401/403) |
+| 4 | `not_found` | Not found (404) |
+| 5 | `client_error` | The controller rejected the request itself (4xx other than 401/403/404/408/429); retrying it unchanged cannot help |
+| 5 | `retry_later` | The controller invited a retry (429 rate limited, 408 request timeout); back off and send the same request again |
+| 5 | `api_error` | The controller failed to serve the request (5xx); may be transient |
+| 6 | `conflict` | The request cannot succeed against the resource's current state, refused locally before any API call |
+
+`unifi schema` publishes the same table under `errors`, with a `retryable` flag
+per kind, so an agent can branch on it without parsing prose.
 
 ## Development
 

{unifi_cli-0.3.1 → unifi_cli-0.3.2}/src/api/client.rs

@@ -105,7 +105,7 @@ impl UnifiClient {
                 .get_integration("/proxy/network/integration/v1/sites")
                 .await?;
             let site = resp.data.into_iter().next().ok_or_else(|| {
-                ApiError::Other("No sites found — check that the API key has site access".into())
+                ApiError::Other("No sites found. Check that the API key has site access".into())
             })?;
             self.site_id = Some(site.id);
         }
@@ -577,7 +577,7 @@ impl ProtectSession {
     ) -> Result<Self, ApiError> {
         let base_url = normalize_base_url(host)?;
 
-        // Don't use cookie_provider — the `partitioned` cookie attribute
+        // Don't use cookie_provider: the `partitioned` cookie attribute
         // isn't handled by reqwest's jar. We extract the token manually.
         let http = reqwest::Client::builder()
             .danger_accept_invalid_certs(options.accept_invalid_certs)

{unifi_cli-0.3.1 → unifi_cli-0.3.2}/src/api/tests.rs

@@ -773,7 +773,7 @@ fn client_clean_name_falls_back_to_hostname() {
 
 #[test]
 fn client_clean_name_hyphenated_not_stripped() {
-    // "host-ee:ff" has no space before the hex — it's part of the hostname, not a MAC suffix
+    // "host-ee:ff" has no space before the hex, so it's part of the hostname, not a MAC suffix
     let json = r#"{"hostname": "host-ee:ff", "macAddress": "aa:bb:cc:dd:ee:ff"}"#;
     let client: Client = serde_json::from_str(json).unwrap();
     assert_eq!(client.clean_name(), "host-ee:ff");

{unifi_cli-0.3.1 → unifi_cli-0.3.2}/src/commands/ports.rs

@@ -124,6 +124,52 @@ fn speed_cell(p: &PortEntry) -> String {
     }
 }
 
+/// What a port's `last_connection` record says, split into what is attached
+/// *now* and what the record names regardless of state.
+struct Attachment {
+    /// The MAC only when the controller affirms the record is live.
+    attached_mac: Option<String>,
+    /// The MAC whenever the record names one, live or not.
+    last_seen_mac: Option<String>,
+    /// The controller's own `connected` flag, kept tri-state: `None` means the
+    /// firmware did not report it, which is not the same fact as `false`.
+    connected: Option<bool>,
+}
+
+/// Read a port's `last_connection` record.
+///
+/// The controller keeps the record after the device is unplugged, marking it
+/// `connected: false`. A stale record therefore names a device that may have
+/// been gone for months, and reporting it as the attachment would tell an
+/// operator a port is in use moments before they cut its power. So
+/// `attached_mac` is set only when the controller affirms `connected: true`;
+/// a firmware that omits the flag says nothing about the present, which is
+/// not grounds to claim an attachment either. Nothing is lost: the MAC is
+/// always available as `last_seen_mac` and the raw flag as `connected`, so a
+/// caller can tell "gone" from "not reported". `cycle_summary` applies the
+/// same rule to the confirmation prompt.
+fn attachment(p: &PortEntry) -> Attachment {
+    let lc = match p.last_connection.as_ref() {
+        Some(lc) => lc,
+        None => {
+            return Attachment {
+                attached_mac: None,
+                last_seen_mac: None,
+                connected: None,
+            };
+        }
+    };
+    let mac = lc.mac.as_deref().map(format_mac);
+    Attachment {
+        attached_mac: match lc.connected {
+            Some(true) => mac.clone(),
+            _ => None,
+        },
+        last_seen_mac: mac,
+        connected: lc.connected,
+    }
+}
+
 /// Right-pad a table cell to `width` visible columns, deriving the padding
 /// from `plain`'s length rather than `rendered`'s.
 ///
@@ -134,23 +180,23 @@ fn speed_cell(p: &PortEntry) -> String {
 /// go through this instead of a `{:<N}` specifier.
 ///
 /// `rendered` is `plain` itself on the uncoloured path (see call sites), so
-/// that path pads identically to the `{:<width$}` it replaces — this must
+/// that path pads identically to the `{:<width$}` it replaces, and this must
 /// stay true, since existing tests assert on uncoloured output byte-for-byte.
 fn pad_visible(rendered: &str, plain: &str, width: usize) -> String {
     let pad = width.saturating_sub(plain.len());
     format!("{rendered}{}", " ".repeat(pad))
 }
 
-/// "port" for exactly one row, "ports" otherwise — the row-count trailer's
+/// "port" for exactly one row, "ports" otherwise: the row-count trailer's
 /// singular/plural noun.
 fn port_noun(count: usize) -> &'static str {
     if count == 1 { "port" } else { "ports" }
 }
 
 /// Device column width, in characters. Callers that paginate must compute
-/// this from the full result set, not just the page handed to `render_text`
-/// — otherwise two `--offset` pages of the same query can render the column
-/// at different widths.
+/// this from the full result set, not just the page handed to `render_text`.
+/// Otherwise two `--offset` pages of the same query can render the column at
+/// different widths.
 pub fn device_col_width(rows: &[&PortRow]) -> usize {
     rows.iter()
         .map(|r| r.device_name.len())
@@ -537,11 +583,11 @@ pub async fn show(
     let device = client.get_device_ports(mac).await?;
     let p = find_port(&device, port_idx)?;
     let (device_mac, device_name) = device_identity(&device, "-");
-    let attached_mac = p
-        .last_connection
-        .as_ref()
-        .and_then(|lc| lc.mac.as_deref())
-        .map(format_mac);
+    let Attachment {
+        attached_mac,
+        last_seen_mac,
+        connected: attached_connected,
+    } = attachment(p);
 
     if out.is_json() {
         out.print_data(&serde_json::to_string_pretty(&serde_json::json!({
@@ -566,6 +612,8 @@ pub async fn show(
             "poe_current": p.poe_current,
             "poe_good": p.poe_good,
             "attached_mac": attached_mac,
+            "attached_last_seen_mac": last_seen_mac,
+            "attached_connected": attached_connected,
             "tx_bytes": p.tx_bytes,
             "rx_bytes": p.rx_bytes,
             "tx_errors": p.tx_errors,
@@ -631,11 +679,17 @@ pub async fn show(
             println!("  {}  {c:.2} mA", label("Current:  "));
         }
     }
-    println!(
-        "  {}  {}",
-        label("Attached: "),
-        attached_mac.as_deref().unwrap_or("-")
-    );
+    // Only an affirmed connection prints as a bare MAC, so the line can never
+    // be read as "this device is plugged in right now" unless it is. A stale
+    // record and an unreported one are both qualified, and differently: the
+    // first knows the device is gone, the second knows nothing.
+    let attached_cell = match (&attached_mac, &last_seen_mac, attached_connected) {
+        (Some(mac), _, _) => mac.clone(),
+        (None, Some(seen), Some(false)) => format!("- (last seen {seen})"),
+        (None, Some(seen), _) => format!("unknown (last seen {seen})"),
+        (None, None, _) => "-".to_string(),
+    };
+    println!("  {}  {}", label("Attached: "), attached_cell);
     Ok(())
 }
 
@@ -666,16 +720,13 @@ pub fn check_cyclable(port: &PortEntry, device_mac: &str) -> Result<(), ApiError
             "PoE is administratively disabled on port {idx} of {mac} (poe_mode=off)"
         )));
     }
-    // Observed against a live UCG-Max controller: a port with port_poe: true,
-    // poe_mode: "auto", and poe_enable: false rejected `power-cycle` with
-    // HTTP 400 api.err.InvalidTargetPort. poe_enable was the only attribute
-    // that differed from ports that do have power to cycle, so it is used
-    // here as the guard — that inference has not been confirmed by a
-    // successful cycle against a poe_enable: true port, since doing so would
-    // require firing at a port with a live device attached. Surfacing this
-    // locally as `conflict` avoids the alternative: the controller's 400
-    // otherwise falls through to `api_error` (see error_for_status), which
-    // src/schema.rs advertises as retryable even though retrying cannot help.
+    // `poe_enable` is the controller's own precondition, confirmed in both
+    // directions against a live UCG-Max: a port with port_poe: true,
+    // poe_mode: "auto" and poe_enable: false rejects `power-cycle` with HTTP
+    // 400 api.err.InvalidTargetPort, while the same command against a port
+    // with poe_enable: true succeeds and reboots the attached device.
+    // Checking it here turns that 400 into a local `conflict` naming the
+    // reason, instead of an opaque status from the controller.
     if !port.poe_enable {
         return Err(ApiError::Conflict(format!(
             "Port {idx} on {mac} is not currently delivering PoE (poe_enable=false), \
@@ -686,7 +737,7 @@ pub fn check_cyclable(port: &PortEntry, device_mac: &str) -> Result<(), ApiError
 }
 
 /// Whether the cycle actually happened. `Declined` is not an error at this
-/// layer — the caller decides how to report a refused confirmation.
+/// layer; the caller decides how to report a refused confirmation.
 #[derive(Debug, PartialEq, Eq)]
 pub enum CycleOutcome {
     Cycled,
@@ -925,12 +976,10 @@ mod tests {
     // `pad_visible` is what makes coloured Link/Connected cells line up with
     // the header at a TTY. `use_color()` reads `stdout().is_terminal()`
     // directly with no override, so a unit test cannot force colour on for
-    // `render_rows` itself without adding a flag/env override the task this
-    // was written for explicitly ruled out ("no new flags"). Testing the
-    // padding helper directly, with a hand-built ANSI-escaped string standing
-    // in for what `owo_colors` would emit, exercises the actual defect
-    // (padding computed from byte length instead of visible width) without
-    // needing a real TTY.
+    // `render_rows` itself. Testing the padding helper directly, with a
+    // hand-built ANSI-escaped string standing in for what `owo_colors` would
+    // emit, exercises the defect it guards against (padding computed from
+    // byte length instead of visible width) without needing a real TTY.
     #[test]
     fn pad_visible_pads_by_plain_width_not_escaped_byte_length() {
         // The real thing `render_rows` hands `pad_visible` on the coloured
@@ -962,7 +1011,7 @@ mod tests {
     fn pad_visible_matches_the_uncoloured_output_it_replaces() {
         // On the uncoloured path every call site passes `rendered == plain`,
         // so this must reproduce exactly what the old `{:<width$}` specifier
-        // produced — the uncoloured path must not change at all.
+        // produced: the uncoloured path must not change at all.
         assert_eq!(pad_visible("up", "up", 6), format!("{:<6}", "up"));
         assert_eq!(pad_visible("down", "down", 6), format!("{:<6}", "down"));
         assert_eq!(pad_visible("yes", "yes", 9), format!("{:<9}", "yes"));
@@ -1176,9 +1225,8 @@ mod tests {
         );
     }
 
-    // `_id` is required by `LegacyClient` (every other fixture in this codebase
-    // supplies it); the plan's literal fixture omitted it, so it is added here
-    // to make the fixture actually deserialize.
+    // `_id` is required by `LegacyClient`, so every record here supplies one
+    // or the fixture will not deserialize.
     fn clients_fixture() -> Vec<crate::api::LegacyClient> {
         serde_json::from_value(serde_json::json!([
             {"_id": "1", "mac": "aa:bb:cc:dd:ee:10", "name": "garage-pi",   "ip": "10.0.0.5"},
@@ -1211,12 +1259,9 @@ mod tests {
         );
     }
 
-    // `resolve_candidates` no longer decides ambiguity by itself — a name
-    // matching multiple client records is not an error here, since `find`
-    // only calls it a conflict once it also knows more than one candidate
-    // sits on a switch port. This replaces the old
-    // `resolve_identifier_ambiguous_name_is_conflict`, which asserted the
-    // opposite (that a name-match count alone was a `Conflict`).
+    // A name matching multiple client records is not an error here.
+    // `resolve_candidates` returns every candidate; `find` calls it a conflict
+    // only once it also knows more than one of them sits on a switch port.
     #[test]
     fn resolve_candidates_returns_every_name_match_without_erroring() {
         let c = clients_fixture();

unifi_cli-0.3.2/src/lib.rs

@@ -0,0 +1,25 @@
+pub mod api;
+pub mod commands;
+pub mod fields;
+pub mod output;
+pub mod tui;
+
+/// Commands that refuse to act without confirmation: they ask on a terminal,
+/// and exit `confirmation_required` when stdin is not one unless `--yes` is
+/// passed.
+///
+/// One list, three consumers: `unifi schema` publishes it so an agent can tell
+/// which invocations need `--yes` before it runs them, `main` gates these
+/// commands on it, and the contract tests drive every entry to prove the gate
+/// is really there. A mutating command is not automatically on this list;
+/// `devices locate` only blinks an LED, and `clients set-fixed-ip` and
+/// `protect rtsps create` add configuration rather than taking something away.
+pub const CONFIRMATION_GATED_COMMANDS: &[&str] = &[
+    "clients block",
+    "clients unblock",
+    "clients kick",
+    "devices restart",
+    "devices upgrade",
+    "ports cycle",
+    "protect rtsps delete",
+];

{unifi_cli-0.3.1 → unifi_cli-0.3.2}/src/main.rs

@@ -808,15 +808,7 @@ fn run_init_with_io(
     }
     let toml_str = toml::to_string_pretty(&config)
         .map_err(|e| InitError(format!("Failed to serialize config: {e}")))?;
-    std::fs::write(config_path, &toml_str)
-        .map_err(|e| InitError(format!("Failed to write config: {e}")))?;
-
-    // Restrict config file permissions (contains secrets)
-    #[cfg(unix)]
-    {
-        use std::os::unix::fs::PermissionsExt;
-        let _ = std::fs::set_permissions(config_path, std::fs::Permissions::from_mode(0o600));
-    }
+    write_config_file(config_path, &toml_str)?;
 
     Ok(InitOutcome::Saved {
         profile: profile_name,
@@ -855,14 +847,85 @@ fn enable_accept_invalid_certs_in_config(
 
     let toml_str = toml::to_string_pretty(&config)
         .map_err(|e| InitError(format!("Failed to serialize config: {e}")))?;
-    std::fs::write(config_path, &toml_str)
-        .map_err(|e| InitError(format!("Failed to write config: {e}")))?;
-    #[cfg(unix)]
-    {
-        use std::os::unix::fs::PermissionsExt;
-        let _ = std::fs::set_permissions(config_path, std::fs::Permissions::from_mode(0o600));
+    write_config_file(config_path, &toml_str)
+}
+
+/// Write the config file so that only its owner can read it.
+///
+/// The file holds an API key and optionally a password, so it is never written
+/// in place. `OpenOptions::mode` applies only to a file the call creates, so
+/// opening an existing config would fill a possibly world-readable file with
+/// fresh credentials and only tighten it afterwards, leaving a window in which
+/// any local account can read the key (and leaving it readable for good if the
+/// chmod fails). Instead the content goes into a new 0600 file beside the
+/// destination and is renamed over it. The rename is atomic: the credentials
+/// exist only inside a 0600 file, and a concurrent reader sees either the old
+/// config or the new one, never a half-written one.
+///
+/// Off unix the write goes through the same temp file and rename, so the config
+/// is never left half-written, but the mode is not set: the file takes the
+/// inherited ACL of its directory.
+fn write_config_file(config_path: &std::path::Path, toml_str: &str) -> Result<(), InitError> {
+    use std::io::Write;
+
+    // The temp file must share a directory with the destination, since rename
+    // does not cross filesystems.
+    let dir = match config_path.parent() {
+        Some(p) if !p.as_os_str().is_empty() => p,
+        _ => std::path::Path::new("."),
+    };
+    let name = config_path
+        .file_name()
+        .map(|n| n.to_string_lossy().into_owned())
+        .unwrap_or_else(|| "config.toml".to_string());
+    // Unique per process and per call, so two writers never pick the same name.
+    static SEQ: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
+    let seq = SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+    let tmp_path = dir.join(format!(".{name}.{}.{seq}.tmp", std::process::id()));
+
+    let open_tmp = || {
+        let mut opts = std::fs::OpenOptions::new();
+        opts.write(true).create_new(true);
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::OpenOptionsExt;
+            opts.mode(0o600);
+        }
+        opts.open(&tmp_path)
+    };
+    let opened = match open_tmp() {
+        // A temp file left behind by a killed run. Reclaim the name;
+        // `create_new` still guarantees we write a file we created ourselves.
+        Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
+            std::fs::remove_file(&tmp_path)
+                .map_err(|e| InitError(format!("Failed to write config: {e}")))?;
+            open_tmp()
+        }
+        other => other,
+    };
+
+    let write_tmp = |mut file: std::fs::File| -> std::io::Result<()> {
+        #[cfg(unix)]
+        {
+            // The umask can clear bits from the requested mode, so pin it here.
+            // The file is still empty, so no secret has reached the disk yet.
+            use std::os::unix::fs::PermissionsExt;
+            file.set_permissions(std::fs::Permissions::from_mode(0o600))?;
+        }
+        file.write_all(toml_str.as_bytes())?;
+        file.sync_all()
+    };
+
+    match opened.and_then(write_tmp) {
+        Ok(()) => std::fs::rename(&tmp_path, config_path).map_err(|e| {
+            let _ = std::fs::remove_file(&tmp_path);
+            InitError(format!("Failed to write config: {e}"))
+        }),
+        Err(e) => {
+            let _ = std::fs::remove_file(&tmp_path);
+            Err(InitError(format!("Failed to write config: {e}")))
+        }
     }
-    Ok(())
 }
 
 /// Prompt for a yes/no answer on stderr (where init status is shown) and read
@@ -1847,6 +1910,92 @@ api_key = "work_key"
         assert!(!display.contains("secret"));
     }
 
+    #[cfg(unix)]
+    fn mode_of(path: &std::path::Path) -> u32 {
+        use std::os::unix::fs::PermissionsExt;
+        std::fs::metadata(path).unwrap().permissions().mode() & 0o777
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn init_writes_credentials_readable_only_by_owner() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        let mut reader = std::io::Cursor::new(b"\nhttps://unifi.local\nmy-api-key\n\ny\n".to_vec());
+        let mut output = Vec::new();
+
+        run_init_with_io(&mut reader, &mut output, &path, false, false).unwrap();
+
+        assert!(
+            std::fs::read_to_string(&path)
+                .unwrap()
+                .contains("my-api-key")
+        );
+        assert_eq!(mode_of(&path), 0o600);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn init_tightens_permissions_of_a_preexisting_world_readable_config() {
+        use std::os::unix::fs::PermissionsExt;
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(&path, "host = \"https://unifi.local\"\napi_key = \"old\"\n").unwrap();
+        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();
+
+        let mut reader = std::io::Cursor::new(b"\nhttps://unifi.local\nnew-key\n\ny\n".to_vec());
+        let mut output = Vec::new();
+        run_init_with_io(&mut reader, &mut output, &path, false, false).unwrap();
+
+        assert_eq!(mode_of(&path), 0o600);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn init_keeps_credentials_out_of_a_preexisting_world_readable_file() {
+        use std::os::unix::fs::PermissionsExt;
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(&path, "host = \"https://unifi.local\"\napi_key = \"old\"\n").unwrap();
+        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();
+        // A second name for the same inode. Writing the new key into the file
+        // that already exists, even for the instant before a chmod, shows up
+        // here; replacing that file by rename cannot.
+        let witness = dir.path().join("witness.toml");
+        std::fs::hard_link(&path, &witness).unwrap();
+
+        let mut reader = std::io::Cursor::new(b"\nhttps://unifi.local\nnew-key\n\ny\n".to_vec());
+        let mut output = Vec::new();
+        run_init_with_io(&mut reader, &mut output, &path, false, false).unwrap();
+
+        let exposed = std::fs::read_to_string(&witness).unwrap();
+        assert!(
+            !exposed.contains("new-key"),
+            "the API key was written into a world-readable file: {exposed}"
+        );
+        assert_eq!(
+            mode_of(&witness),
+            0o644,
+            "the world-readable file was the one that got written"
+        );
+        assert!(std::fs::read_to_string(&path).unwrap().contains("new-key"));
+        assert_eq!(mode_of(&path), 0o600);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn enable_accept_invalid_certs_keeps_the_config_owner_only() {
+        use std::os::unix::fs::PermissionsExt;
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(&path, "host = \"https://unifi.local\"\napi_key = \"k\"\n").unwrap();
+        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();
+
+        enable_accept_invalid_certs_in_config(&path, None).unwrap();
+
+        assert_eq!(mode_of(&path), 0o600);
+    }
+
     #[test]
     fn init_persists_explicit_invalid_cert_opt_out() {
         let dir = tempfile::tempdir().unwrap();

{unifi_cli-0.3.1 → unifi_cli-0.3.2}/src/output.rs

@@ -130,6 +130,18 @@ pub fn error_kind_and_code(err: &(dyn std::error::Error + 'static)) -> (&'static
         match api_err {
             crate::api::ApiError::Auth(_) => ("auth_error", exit_codes::AUTH_ERROR),
             crate::api::ApiError::NotFound(_) => ("not_found", exit_codes::NOT_FOUND),
+            // 408 and 429 are the two 4xx that invite the same request again,
+            // so they stay retryable even though they are client errors.
+            crate::api::ApiError::Api {
+                status: 408 | 429, ..
+            } => ("retry_later", exit_codes::API_ERROR),
+            // Any other 4xx means the request itself was rejected, so retrying
+            // it unchanged cannot help. It shares exit code 5 with api_error
+            // but reports a distinct kind, so an agent branching on
+            // `retryable` does not loop on a permanent failure.
+            crate::api::ApiError::Api { status, .. } if (400..500).contains(status) => {
+                ("client_error", exit_codes::API_ERROR)
+            }
             crate::api::ApiError::Api { .. } => ("api_error", exit_codes::API_ERROR),
             crate::api::ApiError::Conflict(_) => ("conflict", exit_codes::CONFLICT),
             crate::api::ApiError::Http(_) | crate::api::ApiError::Other(_) => {
@@ -207,6 +219,48 @@ mod tests {
         assert_eq!(code, exit_codes::NOT_FOUND);
     }
 
+    #[test]
+    fn error_kind_and_code_client_error_for_a_rejected_request() {
+        // The controller answers `power-cycle` on a PoE-disabled port with
+        // HTTP 400 api.err.InvalidTargetPort. Retrying that unchanged can only
+        // fail again, so it must not be published as the retryable api_error.
+        let err = ApiError::Api {
+            status: 400,
+            message: "api.err.InvalidTargetPort".into(),
+        };
+        let (kind, code) = error_kind_and_code(&err);
+        assert_eq!(kind, "client_error");
+        assert_eq!(code, exit_codes::API_ERROR);
+    }
+
+    #[test]
+    fn error_kind_and_code_keeps_408_and_429_retryable() {
+        // Both statuses ask for the same request again, so they must not land
+        // in the permanent client_error bucket an agent gives up on.
+        for status in [408u16, 429] {
+            let err = ApiError::Api {
+                status,
+                message: "slow down".into(),
+            };
+            let (kind, code) = error_kind_and_code(&err);
+            assert_eq!(kind, "retry_later", "status {status}");
+            assert_eq!(code, exit_codes::API_ERROR, "status {status}");
+        }
+    }
+
+    #[test]
+    fn error_kind_and_code_api_error_stays_for_server_side_failures() {
+        for status in [500u16, 502, 503] {
+            let err = ApiError::Api {
+                status,
+                message: "upstream failure".into(),
+            };
+            let (kind, code) = error_kind_and_code(&err);
+            assert_eq!(kind, "api_error", "status {status}");
+            assert_eq!(code, exit_codes::API_ERROR, "status {status}");
+        }
+    }
+
     #[test]
     fn error_envelope_is_valid_json() {
         let envelope = serde_json::json!({

{unifi_cli-0.3.1 → unifi_cli-0.3.2}/src/schema.rs

@@ -202,6 +202,8 @@ fn command_metadata() -> HashMap<&'static str, CommandMeta> {
                 ("poe_current", "number"),
                 ("poe_good", "boolean"),
                 ("attached_mac", "string"),
+                ("attached_last_seen_mac", "string"),
+                ("attached_connected", "boolean"),
                 ("tx_bytes", "integer"),
                 ("rx_bytes", "integer"),
                 ("tx_errors", "integer"),
@@ -411,7 +413,7 @@ fn build_global_args(cmd: &clap::Command) -> Vec<serde_json::Value> {
         "name": "--yes",
         "type": "boolean",
         "required": false,
-        "description": "Skip confirmation prompt for destructive commands (required without a TTY)",
+        "description": "Skip the confirmation prompt. Required for any command with confirmation_required: true when stdin is not a terminal; without it those commands exit 2 with kind confirmation_required and send nothing",
     }));
     args
 }
@@ -506,6 +508,16 @@ fn walk_commands(
                     entry["output_fields"] = arr.into();
                 }
                 entry["mutating"] = meta.mutating.into();
+                // Published only for mutating commands, where the answer is
+                // the difference between a run that works unattended and one
+                // that exits 2. The three mutating commands that do not ask
+                // say so explicitly rather than leaving an agent to guess
+                // from the absence of a key.
+                if meta.mutating {
+                    entry["confirmation_required"] = unifi_cli::CONFIRMATION_GATED_COMMANDS
+                        .contains(&path.as_str())
+                        .into();
+                }
                 if let Some(note) = meta.note {
                     entry["note"] = note.into();
                 }
@@ -565,17 +577,29 @@ pub fn print_schema(cmd: clap::Command) {
                 "retryable": false,
                 "description": "Requested resource not found (404)",
             },
+            {
+                "kind": "client_error",
+                "exit_code": 5,
+                "retryable": false,
+                "description": "API rejected the request itself (4xx other than 401/403/404/408/429). The request will not succeed unchanged, so retrying cannot help; the HTTP status is in the error message",
+            },
+            {
+                "kind": "retry_later",
+                "exit_code": 5,
+                "retryable": true,
+                "description": "API declined to serve the request now and invited a retry (429 rate limited, 408 request timeout). Back off and retry the same request",
+            },
             {
                 "kind": "api_error",
                 "exit_code": 5,
                 "retryable": true,
-                "description": "API returned a server-side error (5xx)",
+                "description": "API returned a server-side error (5xx). May be transient",
             },
             {
                 "kind": "conflict",
                 "exit_code": 6,
                 "retryable": false,
-                "description": "Resource already exists with incompatible configuration",
+                "description": "The request cannot succeed against the resource's current state, rejected locally before any API call: an ambiguous match, or a precondition the target does not meet",
             },
         ],
     });

{unifi_cli-0.3.1 → unifi_cli-0.3.2}/tests/cli_contract.rs

@@ -299,17 +299,87 @@ fn every_published_output_field_is_accepted_by_fields() {
     }
 }
 
-#[test]
-fn ports_cycle_requires_yes_without_a_tty() {
-    let out = unifi()
-        .args(["ports", "cycle", "aa:bb:cc:dd:ee:ff", "5"])
-        .stdin(std::process::Stdio::null())
-        .output()
-        .expect("failed to run binary");
+/// One invocation per gated command, with the argument set it needs.
+const GATED_INVOCATIONS: &[(&str, &[&str])] = &[
+    ("clients block", &["aa:bb:cc:dd:ee:ff"]),
+    ("clients unblock", &["aa:bb:cc:dd:ee:ff"]),
+    ("clients kick", &["aa:bb:cc:dd:ee:ff"]),
+    ("devices restart", &["aa:bb:cc:dd:ee:ff"]),
+    ("devices upgrade", &["aa:bb:cc:dd:ee:ff"]),
+    ("ports cycle", &["aa:bb:cc:dd:ee:ff", "5"]),
+    ("protect rtsps delete", &["front-door"]),
+];
 
-    assert_eq!(out.status.code(), Some(2));
+/// Every command the schema publishes as `confirmation_required` must refuse to
+/// act when there is no `--yes` and no TTY to ask on, and must refuse locally.
+/// The host here is unroutable, so a `confirmation_required` envelope is also
+/// proof that nothing was sent to the controller: a command that fell through
+/// to HTTP would report a connection failure instead.
+#[test]
+fn every_confirmation_gated_command_refuses_without_yes_and_no_tty() {
+    let covered: Vec<&str> = GATED_INVOCATIONS.iter().map(|(c, _)| *c).collect();
+    for command in unifi_cli::CONFIRMATION_GATED_COMMANDS {
+        assert!(
+            covered.contains(command),
+            "`{command}` is confirmation-gated but has no invocation in GATED_INVOCATIONS"
+        );
+    }
     assert_eq!(
-        error_envelope(&out.stderr)["error"]["kind"].as_str(),
-        Some("confirmation_required")
+        covered.len(),
+        unifi_cli::CONFIRMATION_GATED_COMMANDS.len(),
+        "GATED_INVOCATIONS lists a command that is not in CONFIRMATION_GATED_COMMANDS"
     );
+
+    for (command, extra) in GATED_INVOCATIONS {
+        let mut args: Vec<&str> = command.split(' ').collect();
+        args.extend_from_slice(extra);
+
+        let out = unifi()
+            .args(&args)
+            .stdin(std::process::Stdio::null())
+            .output()
+            .expect("failed to run binary");
+
+        assert_eq!(
+            out.status.code(),
+            Some(2),
+            "`{command}` should exit 2 without --yes, stderr: {}",
+            String::from_utf8_lossy(&out.stderr)
+        );
+        assert_eq!(
+            error_envelope(&out.stderr)["error"]["kind"].as_str(),
+            Some("confirmation_required"),
+            "`{command}` should report confirmation_required, stderr: {}",
+            String::from_utf8_lossy(&out.stderr)
+        );
+    }
+}
+
+/// A mutating command that is not gated must not start asking for confirmation:
+/// it reaches the controller (and fails on the unroutable host) instead. This is
+/// the negative control for the test above, which would otherwise still pass if
+/// every command refused everything.
+#[test]
+fn ungated_mutating_commands_do_not_ask_for_confirmation() {
+    for args in [
+        vec!["devices", "locate", "aa:bb:cc:dd:ee:ff"],
+        vec!["clients", "set-fixed-ip", "aa:bb:cc:dd:ee:ff", "192.0.2.10"],
+    ] {
+        let out = unifi()
+            .args(&args)
+            .stdin(std::process::Stdio::null())
+            .output()
+            .expect("failed to run binary");
+
+        let kind = error_envelope(&out.stderr)["error"]["kind"]
+            .as_str()
+            .unwrap_or_default()
+            .to_string();
+        assert_ne!(
+            kind,
+            "confirmation_required",
+            "`{}` is not in CONFIRMATION_GATED_COMMANDS but asked for confirmation",
+            args.join(" ")
+        );
+    }
 }

{unifi_cli-0.3.1 → unifi_cli-0.3.2}/tests/mock_server.rs

@@ -1879,14 +1879,10 @@ mod command_output {
             .unwrap();
     }
 
-    // `ports_show_table` above only smoke-tests that the text branch doesn't
-    // panic (matching the pre-existing convention for other `show`-style
-    // commands in this file). But `ports show`'s text branch is new code with
-    // real formatting logic (speed_cell, poe_cell, voltage/current, the
-    // attached MAC), so it gets its own test that spawns the real binary
-    // (same pattern as `ports_list_pagination_reports_full_total_and_truncated_items`
-    // and `devices_ports_bare_array_vs_ports_list_envelope`) and asserts on
-    // the actual rendered text.
+    // `ports_show_table` above only smoke-tests that the text branch does not
+    // panic. The text branch carries real formatting logic (speed_cell,
+    // poe_cell, voltage/current, the attached MAC), so it also gets a test that
+    // spawns the real binary and asserts on the rendered text.
     #[tokio::test]
     async fn ports_show_text_output_renders_expected_fields() {
         let server = MockServer::start().await;
@@ -1947,7 +1943,7 @@ mod command_output {
 
     // Drives the real `unifi` binary so the JSON this command actually prints
     // can be inspected, and cross-checks it against what `unifi schema`
-    // publishes for "ports show" — the two are supposed to be the same
+    // publishes for "ports show": the two are supposed to be the same
     // contract, and nothing else in this suite would catch them drifting
     // apart.
     #[tokio::test]
@@ -2097,6 +2093,138 @@ mod command_output {
         }
     }
 
+    // A `last_connection` the controller has marked `connected: false` is
+    // history, not an attachment: the device may have been unplugged months
+    // ago. Reporting it as attached would tell an operator a port is in use
+    // moments before they cut its power, so `attached_mac` must be null and the
+    // MAC must survive only as `attached_last_seen_mac`.
+    #[tokio::test]
+    async fn ports_show_reports_a_stale_last_connection_as_unattached() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/proxy/network/api/s/default/stat/device"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "meta": {"rc": "ok"},
+                "data": [{
+                    "mac": "9c:05:d6:bc:06:43", "name": "USW-24-PoE",
+                    "port_table": [{
+                        "port_idx": 5, "name": "Port 5", "media": "GE", "up": false,
+                        "port_poe": true, "poe_enable": true, "poe_mode": "auto",
+                        "last_connection": {"mac": "aabbccddeeff", "connected": false}
+                    }]
+                }]
+            })))
+            .mount(&server)
+            .await;
+
+        let run = |format: &str| {
+            std::process::Command::new(env!("CARGO_BIN_EXE_unifi"))
+                .args([
+                    "--host",
+                    &server.uri(),
+                    "--api-key",
+                    "test-key",
+                    "ports",
+                    "show",
+                    "9c:05:d6:bc:06:43",
+                    "5",
+                    "--output",
+                    format,
+                ])
+                .output()
+                .expect("failed to run the unifi binary")
+        };
+
+        let json_out = run("json");
+        assert!(
+            json_out.status.success(),
+            "ports show failed: {}",
+            String::from_utf8_lossy(&json_out.stderr)
+        );
+        let body: serde_json::Value = serde_json::from_slice(&json_out.stdout).unwrap();
+        assert!(
+            body["attached_mac"].is_null(),
+            "a stale last_connection must not be published as attached: {body}"
+        );
+        assert_eq!(
+            body["attached_last_seen_mac"], "aa:bb:cc:dd:ee:ff",
+            "the stale MAC must stay available as history: {body}"
+        );
+        assert_eq!(
+            body["attached_connected"], false,
+            "the controller's own flag must be reported as it stands: {body}"
+        );
+
+        let text_out = run("text");
+        assert!(text_out.status.success());
+        let text = String::from_utf8_lossy(&text_out.stdout);
+        assert!(
+            text.contains("- (last seen aa:bb:cc:dd:ee:ff)"),
+            "the text branch must qualify a stale MAC rather than print it bare: {text}"
+        );
+    }
+
+    // A firmware that reports `last_connection.mac` without a `connected` flag
+    // has said nothing about the present, which is not the same fact as
+    // "disconnected". It is still not grounds to claim an attachment, so
+    // `attached_mac` stays null, but the tri-state `attached_connected` and the
+    // text output both distinguish "not reported" from "gone".
+    #[tokio::test]
+    async fn ports_show_distinguishes_an_unreported_connection_from_a_stale_one() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/proxy/network/api/s/default/stat/device"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "meta": {"rc": "ok"},
+                "data": [{
+                    "mac": "9c:05:d6:bc:06:43", "name": "USW-24-PoE",
+                    "port_table": [{
+                        "port_idx": 5, "name": "Port 5", "media": "GE", "up": true,
+                        "last_connection": {"mac": "aabbccddeeff"}
+                    }]
+                }]
+            })))
+            .mount(&server)
+            .await;
+
+        let run = |format: &str| {
+            std::process::Command::new(env!("CARGO_BIN_EXE_unifi"))
+                .args([
+                    "--host",
+                    &server.uri(),
+                    "--api-key",
+                    "test-key",
+                    "ports",
+                    "show",
+                    "9c:05:d6:bc:06:43",
+                    "5",
+                    "--output",
+                    format,
+                ])
+                .output()
+                .expect("failed to run the unifi binary")
+        };
+
+        let json_out = run("json");
+        assert!(json_out.status.success());
+        let body: serde_json::Value = serde_json::from_slice(&json_out.stdout).unwrap();
+        assert!(
+            body["attached_mac"].is_null(),
+            "an unreported connection must not be claimed as attached: {body}"
+        );
+        assert!(
+            body["attached_connected"].is_null(),
+            "a missing connected flag must stay null, not become false: {body}"
+        );
+        assert_eq!(body["attached_last_seen_mac"], "aa:bb:cc:dd:ee:ff");
+
+        let text = String::from_utf8_lossy(&run("text").stdout).to_string();
+        assert!(
+            text.contains("unknown (last seen aa:bb:cc:dd:ee:ff)"),
+            "the text branch must say the state is unknown, not that the device is gone: {text}"
+        );
+    }
+
     // Locates `unifi ports cycle <MAC> 99` uses the same `find_port` lookup;
     // a bogus port index must be reported as not-found (exit 4) rather than
     // firing a command at the controller for a port that does not exist.
@@ -2144,9 +2272,9 @@ mod command_output {
     }
 
     // The row-count trailer must read "1 port" for a single row and "N ports"
-    // otherwise — it used to say "1 ports" unconditionally. Spawns the real
-    // binary (rather than calling `render_text` in-process) so this observes
-    // literal stderr text, the same surface an operator actually reads.
+    // otherwise. Spawns the real binary (rather than calling `render_text`
+    // in-process) so this observes literal stderr text, the same surface an
+    // operator actually reads.
     #[tokio::test]
     async fn ports_list_trailer_is_singular_for_exactly_one_row() {
         let server = MockServer::start().await;
@@ -2574,9 +2702,8 @@ mod command_output {
     // name matches: `office` genuinely matches two devices here, and both
     // are actually attached to a switch port (unlike the "one interface
     // never shows up" fixtures below), so this must still exit 6 (conflict)
-    // and name both candidates. Modeled on a live-controller case — two
-    // physically distinct office devices on the same switch — reported
-    // against the pre-fix behavior in the original bug report.
+    // and name both candidates. Modeled on a live-controller case: two
+    // physically distinct office devices sharing a name on the same switch.
     #[tokio::test]
     async fn ports_find_ambiguous_name_exits_with_conflict() {
         let server = MockServer::start().await;
@@ -2706,8 +2833,8 @@ mod command_output {
     }
 
     // The other client record sharing the name never appears in any port
-    // table at all — not "only the wireless interface", but no candidate on
-    // a port whatsoever — so this must be not_found, not a conflict.
+    // table at all: not "only the wireless interface", but no candidate on a
+    // port whatsoever, so this must be not_found, not a conflict.
     #[tokio::test]
     async fn ports_find_name_matches_clients_none_on_a_port_is_not_found() {
         let server = MockServer::start().await;
@@ -2769,7 +2896,7 @@ mod command_output {
 
     // `find`'s JSON output has always carried `connected`; only the text
     // table lacked it, leaving the connected-first sort order as the sole
-    // (easy-to-miss) signal for which row is the device's *current* port —
+    // (easy-to-miss) signal for which row is the device's *current* port,
     // a distinction that matters because this lookup feeds the destructive
     // `ports cycle`. Two distinctly-named single-port devices (rather than
     // one device with two ports) so each rendered row can be identified by
@@ -2851,7 +2978,7 @@ mod command_output {
     // `power_cycle_port_sends_correct_command` (in `client_api` above) only
     // covers the client method's endpoint and body. Nothing exercised the
     // orchestration in `commands::ports::cycle` that decides *whether* to call
-    // it at all — and that orchestration is the only place in this CLI that
+    // it at all, and that orchestration is the only place in this CLI that
     // cuts power to physical hardware. These four cases pin down the guard-rail
     // ordering (find_port -> check_cyclable -> confirm -> POST) as a tested
     // property rather than a code-reading exercise: the `.expect(0)` mounts on
@@ -2991,7 +3118,7 @@ mod command_output {
     // third guard rail: a port that is PoE-capable and not administratively
     // off, but that the controller reports as not currently delivering power
     // (poe_enable: false). This is the fixture from the live UCG-Max finding
-    // that motivated the guard — see `check_cyclable` in
+    // that motivated the guard; see `check_cyclable` in
     // `src/commands/ports.rs` for what was actually observed.
     #[tokio::test]
     async fn ports_cycle_poe_enable_false_is_conflict_and_never_posts() {

unifi_cli-0.3.1/src/lib.rs

@@ -1,5 +0,0 @@
-pub mod api;
-pub mod commands;
-pub mod fields;
-pub mod output;
-pub mod tui;