feat: keep every provider's hosts grouped under one header

Provider group headers are now resolved through the registry everywhere,
so all 16 providers behave the same. OVHcloud, Leaseweb, i3D.net and
TransIP kept their group header on startup only by coincidence before;
their display name was maintained in a separate list that had drifted.

Group-comment repair derives its known-provider set from the registry
too, so absorbed headers relocate for every provider.

Sync decides whether to write a group header from the same top-level
lookup it uses to place the host, so a newly synced host gets its header
even when the provider's existing hosts live only in an Included file.

Adds a per-provider scenario matrix and startup-cleanup coverage across
all 16 providers.

Author: erickochen

CHANGELOG.md

@@ -1,3 +1,10 @@
+## 3.21.1 - 2026-05-31
+
+- feat: Your cloud hosts stay grouped under their provider.
+- feat: Every cloud provider keeps one clean group header in ~/.ssh/config and the purple host list, so your hosts read the same in the file and on screen.
+- feat: Newly synced and imported hosts always land inside their provider's group, so your config stays organized as it grows.
+- feat: Grouping holds whether your hosts live in your main config or an Included file.
+
 ## 3.21.0 - 2026-05-31
 
 - feat: Tidy SSH config with a blank line between hosts.

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "purple-ssh"
-version = "3.21.0"
+version = "3.21.1"
 edition = "2024"
 description = "Open-source terminal SSH manager that keeps ~/.ssh/config in sync with your cloud infra. Spin up a VM on AWS, GCP, Azure, Hetzner or 12 other cloud providers and it appears in your host list. Destroy it and the entry dims. Search hundreds of hosts, transfer files, manage Docker and Podman over SSH, sign Vault SSH certs. Rust TUI, MIT licensed."
 license = "MIT"

Cargo.toml

@@ -108,10 +108,18 @@ pub fn sync_provider(
     // Track which server IDs are still in the remote set (also deduplicates)
     let mut remote_ids: std::collections::HashSet<String> = std::collections::HashSet::new();
 
-    // Only add group header if this PROVIDER (any config) has no existing hosts.
-    // Group headers are shared across labeled configs of the same provider so
-    // both `[do:work]` and `[do:personal]` hosts live under one "DigitalOcean" header.
-    let mut needs_header = !dry_run && config.find_hosts_by_provider(provider.name()).is_empty();
+    // Add a group header when this provider has no TOP-LEVEL host yet. The
+    // header and every synced host live at top level (Include files are
+    // read-only), so this must agree with find_provider_insert_position, which
+    // is also top-level only. Using the include-aware find_hosts_by_provider
+    // here left a new host header-less when the provider's existing hosts lived
+    // solely in an Include. Group headers are still shared across labeled
+    // configs of one provider: the second labeled config finds the first
+    // config's top-level host and skips a duplicate header.
+    let mut needs_header = !dry_run
+        && config
+            .find_provider_insert_position(provider.name())
+            .is_none();
 
     for remote in remote_hosts {
         if !remote_ids.insert(remote.server_id.clone()) {

src/providers/sync.rs

@@ -5797,6 +5797,199 @@ fn test_sync_consecutive_provider_hosts_separated() {
     assert!(!output.contains("\n\n\n"), "triple blank lines:\n{output}");
 }
 
+// --- Include-file and grouping consistency tests ---
+
+#[test]
+fn sync_includes_only_host_gets_top_level_group_header() {
+    // A provider whose only existing host lives in an Include file. A newly
+    // synced host must be written at top level WITH its group header, not
+    // appended bare at the end of the file. needs_header (include-aware) and
+    // find_provider_insert_position (top-level only) must agree.
+    use crate::ssh_config::model::{IncludeDirective, IncludedFile};
+    let included_file = IncludedFile {
+        path: PathBuf::from("/tmp/inc_grp_config"),
+        elements: SshConfigFile::parse_content(
+            "Host do-inc\n  HostName 1.2.3.4\n  # purple:provider digitalocean:inc1\n",
+        ),
+    };
+    let mut config = SshConfigFile {
+        elements: vec![ConfigElement::Include(IncludeDirective {
+            raw_line: "Include inc_grp_config".to_string(),
+            pattern: "inc_grp_config".to_string(),
+            resolved_files: vec![included_file],
+        })],
+        path: test_config_path(),
+        crlf: false,
+        bom: false,
+    };
+    let section = make_section();
+    // Remote: the included host (dedup, no add) plus a brand-new one.
+    let remote = vec![
+        ProviderHost::new("inc1".into(), "inc".into(), "1.2.3.4".into(), Vec::new()),
+        ProviderHost::new("999".into(), "fresh".into(), "9.9.9.9".into(), Vec::new()),
+    ];
+    let result = sync_provider(
+        &mut config,
+        &MockProvider,
+        &remote,
+        &section,
+        false,
+        false,
+        false,
+    );
+    assert_eq!(
+        result.added, 1,
+        "only the new host is added (included host deduped)"
+    );
+
+    let output = config.serialize();
+    // The new top-level host must be present.
+    assert!(
+        output.contains("Host do-fresh"),
+        "new host missing:\n{output}"
+    );
+    // It must carry a DigitalOcean group header at top level.
+    let has_top_level_header = config.elements.iter().any(
+        |e| matches!(e, ConfigElement::GlobalLine(l) if l.trim() == "# purple:group DigitalOcean"),
+    );
+    assert!(
+        has_top_level_header,
+        "new top-level synced host must get a DigitalOcean group header:\n{output}"
+    );
+}
+
+#[test]
+fn sync_labeled_configs_share_one_group_header() {
+    // Two labeled configs of the same provider (do:work, do:personal) must
+    // share exactly ONE group header (the documented design), with both hosts
+    // grouped under it. Locks in the adversarial verdict that this is correct.
+    let mut config = empty_config();
+    let work = ProviderSection {
+        id: crate::providers::config::ProviderConfigId::labeled("digitalocean", "work"),
+        alias_prefix: "do-work".to_string(),
+        ..make_section()
+    };
+    let personal = ProviderSection {
+        id: crate::providers::config::ProviderConfigId::labeled("digitalocean", "personal"),
+        alias_prefix: "do-personal".to_string(),
+        ..make_section()
+    };
+    sync_provider(
+        &mut config,
+        &MockProvider,
+        &[ProviderHost::new(
+            "1".into(),
+            "a".into(),
+            "1.1.1.1".into(),
+            Vec::new(),
+        )],
+        &work,
+        false,
+        false,
+        false,
+    );
+    sync_provider(
+        &mut config,
+        &MockProvider,
+        &[ProviderHost::new(
+            "2".into(),
+            "b".into(),
+            "2.2.2.2".into(),
+            Vec::new(),
+        )],
+        &personal,
+        false,
+        false,
+        false,
+    );
+
+    let header_count = config
+        .elements
+        .iter()
+        .filter(|e| matches!(e, ConfigElement::GlobalLine(l) if l.trim() == "# purple:group DigitalOcean"))
+        .count();
+    assert_eq!(
+        header_count,
+        1,
+        "labeled configs of one provider share exactly one header:\n{}",
+        config.serialize()
+    );
+    // Both hosts present and after the single header.
+    let header_pos = config
+        .elements
+        .iter()
+        .position(|e| matches!(e, ConfigElement::GlobalLine(l) if l.trim() == "# purple:group DigitalOcean"))
+        .expect("header present");
+    let work_pos = config
+        .elements
+        .iter()
+        .position(|e| matches!(e, ConfigElement::HostBlock(b) if b.host_pattern == "do-work-a"))
+        .expect("work host present");
+    let personal_pos = config
+        .elements
+        .iter()
+        .position(|e| matches!(e, ConfigElement::HostBlock(b) if b.host_pattern == "do-personal-b"))
+        .expect("personal host present");
+    assert!(work_pos > header_pos && personal_pos > header_pos);
+}
+
+#[test]
+fn sync_orphan_top_level_header_plus_include_no_duplicate() {
+    // Edge case for the needs_header fix: a top-level group header already
+    // exists (no top-level host under it yet) AND the provider has a host in an
+    // Include. Syncing a new host must not pile up a second top-level header;
+    // serialize collapses and at most one header should remain meaningful.
+    use crate::ssh_config::model::{IncludeDirective, IncludedFile};
+    let included_file = IncludedFile {
+        path: PathBuf::from("/tmp/inc_orphan_config"),
+        elements: SshConfigFile::parse_content(
+            "Host do-inc\n  HostName 1.2.3.4\n  # purple:provider digitalocean:inc1\n",
+        ),
+    };
+    let mut config = SshConfigFile {
+        elements: vec![
+            ConfigElement::GlobalLine("# purple:group DigitalOcean".to_string()),
+            ConfigElement::GlobalLine(String::new()),
+            ConfigElement::Include(IncludeDirective {
+                raw_line: "Include inc_orphan_config".to_string(),
+                pattern: "inc_orphan_config".to_string(),
+                resolved_files: vec![included_file],
+            }),
+        ],
+        path: test_config_path(),
+        crlf: false,
+        bom: false,
+    };
+    let section = make_section();
+    let remote = vec![
+        ProviderHost::new("inc1".into(), "inc".into(), "1.2.3.4".into(), Vec::new()),
+        ProviderHost::new("999".into(), "fresh".into(), "9.9.9.9".into(), Vec::new()),
+    ];
+    sync_provider(
+        &mut config,
+        &MockProvider,
+        &remote,
+        &section,
+        false,
+        false,
+        false,
+    );
+
+    let output = config.serialize();
+    // The new host is present.
+    assert!(
+        output.contains("Host do-fresh"),
+        "new host missing:\n{output}"
+    );
+    // No more than two headers, and serialize must not stack blank-line noise.
+    let header_count = output.matches("# purple:group DigitalOcean").count();
+    assert!(
+        header_count <= 2,
+        "excessive duplicate headers ({header_count}):\n{output}"
+    );
+    assert!(!output.contains("\n\n\n"), "triple blank lines:\n{output}");
+}
+
 // --- Multi-config provider tests ---
 
 #[test]

src/providers/sync_tests.rs

@@ -12,25 +12,13 @@
 
 use super::model::{ConfigElement, SshConfigFile};
 
-/// Display name for a provider used in `# purple:group` headers.
-/// Mirrors `providers::provider_display_name()` without a cross-module
-/// dependency.
+/// Display name for a provider used in `# purple:group` headers. Delegates to
+/// the provider registry so the cleanup matcher and the sync writer can never
+/// disagree. A previous hand-maintained copy here drifted: ovh, i3d, leaseweb
+/// and transip were missing, so their headers were deleted on startup despite
+/// active hosts.
 pub(super) fn provider_group_display_name(name: &str) -> &str {
-    match name {
-        "digitalocean" => "DigitalOcean",
-        "vultr" => "Vultr",
-        "linode" => "Linode",
-        "hetzner" => "Hetzner",
-        "upcloud" => "UpCloud",
-        "proxmox" => "Proxmox VE",
-        "aws" => "AWS EC2",
-        "scaleway" => "Scaleway",
-        "gcp" => "GCP",
-        "azure" => "Azure",
-        "tailscale" => "Tailscale",
-        "oracle" => "Oracle Cloud",
-        other => other,
-    }
+    crate::providers::provider_display_name(name)
 }
 
 impl SshConfigFile {
@@ -77,26 +65,14 @@ impl SshConfigFile {
     /// group header. This protects hand-written comments from being silently
     /// scrubbed by the next-startup `remove_all_orphaned_group_headers` pass.
     pub fn repair_absorbed_group_comments(&mut self) -> usize {
-        // Build the set of known provider display names once. The list is
-        // closed under purple's supported providers and tiny, so allocation
-        // cost is negligible.
-        let known_providers: std::collections::HashSet<&str> = [
-            "DigitalOcean",
-            "Vultr",
-            "Linode",
-            "Hetzner",
-            "UpCloud",
-            "Proxmox VE",
-            "AWS EC2",
-            "Scaleway",
-            "GCP",
-            "Azure",
-            "Tailscale",
-            "Oracle Cloud",
-        ]
-        .iter()
-        .copied()
-        .collect();
+        // Derive known provider display names from the registry so this matcher
+        // can never drift from the sync writer. A hand-maintained copy here
+        // previously omitted ovh, leaseweb, i3d and transip, so their absorbed
+        // group comments were never relocated to top-level GlobalLines.
+        let known_providers: std::collections::HashSet<&str> = crate::providers::PROVIDER_NAMES
+            .iter()
+            .map(|n| crate::providers::provider_display_name(n))
+            .collect();
 
         let is_known_group = |raw: &str| -> bool {
             raw.trim()