confctl 2.2.2 → 3.0.0

data/skills/confctl-configuration-update/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: confctl-configuration-update
+description: >-
+  Upgrade confctl-managed flake configuration repositories from one
+  NixOS/nixpkgs release to another, such as 25.11 to 26.05. Use only for NixOS
+  release upgrades that require reading target release notes, moving nixpkgs
+  release channels, updating release-coupled inputs such as home-manager when
+  needed, handling NixOS release deprecations, and validating machines with
+  confctl build. Do not use for routine flake input bumps, service updates,
+  dependency refreshes, or ordinary staging/production rollouts that do not
+  change the NixOS/nixpkgs release.
+---
+
+# confctl NixOS Release Upgrade
+
+## Overview
+
+Use this skill only for configuration repositories built by `confctl` when
+upgrading machines from one NixOS/nixpkgs release to another. The goal is not
+only to move release inputs, but to produce a reviewable, deployable release
+port: release notes understood, generated input commits isolated, machines
+built or explicitly blocked, warnings fixed, and compatibility implications
+recorded.
+
+Do not use this skill for routine flake input bumps, ordinary service updates,
+dependency refreshes, or staging/production rollouts that keep the same NixOS
+release.
+
+## Rules
+
+- Read local repository instructions before editing. Do not assume a specific
+  organization, directory layout, branch naming scheme, or tracking-file
+  convention.
+- Use the repository's documented development environment. If it provides a
+  Nix shell, prefer `nix develop` before running `confctl`.
+- Use `confctl` commands for flake input revision changes. Do not edit
+  `flake.lock` manually.
+- Let `confctl` create generated input commits with `--commit`; use
+  `--no-editor` in non-interactive runs.
+- Use `--no-changelog` for noisy inputs such as `nixpkgs`, `home-manager`, or
+  other large upstreams when they are moved as part of the release upgrade.
+  Keep changelogs for smaller controlled repositories when the log is useful.
+- Treat Nix evaluation warnings and deprecation notices as work items. Fix
+  them before calling the port done unless the user explicitly accepts a
+  documented deferral.
+- Try to build all existing machines. If local secrets, ISO images, private
+  paths, or other operator-only inputs block the sweep, record the exact
+  target and path, then continue with representative builds.
+
+## Preparation
+
+Before changing release inputs, identify and record the upgrade plan in
+whatever place the project uses: an issue, PR description, local notes, or the
+conversation. Include:
+
+- source and target NixOS/nixpkgs releases;
+- affected configuration repository and branch;
+- intended channel order, for example shared stable hosts first, then staging,
+  then production;
+- compatibility checks for persisted state, database schemas, service APIs,
+  generated configs, rollback, and mixed-version operation.
+
+Read current release material from official NixOS sources. Do not rely on
+memory for current release notes:
+
+- NixOS release announcement;
+- NixOS release notes for the target release;
+- relevant nixpkgs, NixOS module, or service documentation linked from the
+  notes.
+
+Extract a short checklist of likely issues: removed options, renamed packages
+or aliases, default flips, required option changes, service module removals,
+systemd behavior changes, filesystem changes, compiler/runtime changes, and
+rollback-sensitive state changes.
+
+## Inventory
+
+From the configuration repository root:
+
+```shell
+nix develop
+confctl inputs ls
+confctl inputs channel ls
+confctl ls
+rg -n 'nixos-[0-9][0-9]\.[0-9][0-9]|release-[0-9][0-9]\.[0-9][0-9]|nixpkgs' \
+  flake.nix cluster configs modules overlays environments packages
+```
+
+If the repository does not use `nix develop`, use its documented shell or run
+the same `confctl` commands with `confctl` available on `PATH`. Omit inventory
+paths that do not exist in the target repository.
+
+Map each release-related channel to the machines it affects. Common channel
+roles include:
+
+- `nixpkgs`: the nixpkgs input used by machines in a channel;
+- `home-manager`: a release branch that often follows the same nixpkgs
+  release;
+- `confctl`: the tool version used by the configuration shell, if the current
+  tool cannot evaluate or build the target release;
+- service-specific roles: application, module, package, or operating-system
+  inputs consumed by a subset of machines and coupled to the NixOS release;
+- environment channels: names such as `stable`, `staging`, `production`, or
+  project-specific equivalents.
+
+Decide whether each channel should move now or remain a separate rollout. Do
+not assume every environment channel must move together.
+
+## Updating Inputs
+
+Use `confctl` from the configuration repo's normal tool environment. Update
+only inputs that are part of the release upgrade or are required to make the
+target release evaluate. Common patterns:
+
+```shell
+nix develop -c confctl inputs channel update \
+  --commit --no-changelog --no-editor stable nixpkgs
+
+nix develop -c confctl inputs channel update \
+  --commit --no-changelog --no-editor home-manager home-manager
+
+nix develop -c confctl inputs channel set \
+  --commit --no-changelog --no-editor '{production,staging}' nixpkgs <rev>
+
+nix develop -c confctl inputs channel set \
+  --commit --no-editor <channel> <role> <rev>
+
+# Only when the current confctl input cannot handle the target release:
+nix develop -c confctl inputs update \
+  --commit --no-changelog --no-editor confctl
+
+# Only when pinning a specific confctl revision for the release upgrade:
+nix develop -c confctl inputs set \
+  --commit --no-changelog --no-editor confctl <rev>
+```
+
+Use `channel update` when following the input's configured target release
+branch/ref. Use `channel set` or `inputs set` for an exact revision, especially
+when pinning an unmerged release-port branch or a known branch tip.
+
+If a channel selector touches an input that is also used by another channel,
+`confctl` can require `--allow-shared`. Only pass it after confirming the
+shared move is intentional, and record the affected channels wherever the
+project tracks validation.
+
+Current `confctl` `set`/`update` commands own `flake.lock` revision changes
+and commit only `flake.lock`. If a release port also needs `flake.nix` URL
+refs changed, such as `github:NixOS/nixpkgs/nixos-25.11` to `nixos-26.05`,
+treat that as a separate configuration edit. Never hand-edit `flake.lock`.
+
+After each generated commit:
+
+```shell
+git show --stat --format=fuller HEAD
+nix develop -c confctl inputs channel ls '<affected-channel-pattern>'
+```
+
+Keep generated `confctl` commit messages in their generated form unless
+repository-local rules explicitly say to edit them.
+
+## Build And Warning Loop
+
+Start with a focused sample if the release upgrade is broad, then attempt the
+full fleet:
+
+```shell
+nix develop -c confctl build -y '<critical-pattern>'
+nix develop -c confctl build -y
+```
+
+Choose representative targets that cover every release-affected input and
+machine type. Examples include one machine per environment channel, one
+machine per custom nixpkgs input, critical infrastructure hosts, service hosts
+that use release-coupled application inputs, and machines with unusual local
+hardware or filesystem configuration.
+
+Watch evaluation output and `confctl` logs for warnings:
+
+```shell
+rg -n -i 'warning:|deprecated|deprecat|renamed|obsolete|removed|will be removed' \
+  .confctl/logs
+```
+
+Fix warnings and evaluation failures in small logical commits. Common fixes
+include:
+
+- removed NixOS option: stop reading or setting it, or gate the common path;
+- renamed package/alias: use the new package name;
+- required filesystem option: set an explicit `fsType`;
+- stale custom nixpkgs fork: replace the missing behavior locally, then remove
+  the unused input;
+- package wrapper regression: add a local overlay/patch and verify the built
+  wrapper;
+- local-only build input missing: record the path and target, then validate
+  neighboring machines that do not require it.
+
+If the full build is blocked, keep reducing to direct targets until every
+category touched by the release upgrade has either built or has a documented
+external blocker. Record generation IDs, log paths, and blocked targets in the
+project's normal validation notes.
+
+## Compatibility Fix Commits
+
+Keep release input bumps and functional fixes separate.
+
+Recommended ordering:
+
+1. Generated release-input commits.
+2. Configuration fixes required by evaluation/build failures.
+3. Warning/deprecation cleanup.
+4. Removal of obsolete inputs after no machines use them.
+5. Follow-up service-specific release fixes discovered by targeted builds.
+
+For manual commits, use the repository's required commit workflow. Explain what
+broke, why the new release requires the change, and what hosts/services are
+affected. Do not put command transcripts or test logs in commit messages;
+record validation in the project's normal notes or PR text.
+
+## Completion
+
+Before finishing:
+
+- run repository formatting/hooks required by local rules;
+- run `git status --short --branch`;
+- record commands, validation results, warnings fixed, blockers, commit
+  hashes, and cleanup notes in the project-appropriate place;
+- push the branch if requested or if that is the normal project flow;
+- check CI when the repository has branch workflows.

data/skills/confctl-configuration-update/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "confctl NixOS release upgrade"
+  short_description: "Upgrade NixOS releases with confctl"
+  default_prompt: "Use $confctl-configuration-update for a confctl NixOS release upgrade."

data/skills/confctl-release/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: confctl-release
+description: Prepare and publish confctl version releases, including changelog, dependency metadata, final release commit and verified RubyGems artifact. Use for confctl releases, not releases of configurations managed by confctl.
+---
+
+# confctl releases
+
+Read the repository's `AGENTS.md` and applicable workspace instructions first.
+Distinguish release preparation from authorized publication. If the user asks
+to prepare a release and wait, stop before default-branch integration, tagging
+and RubyGems upload. Updating a release candidate does not expand that approval.
+
+## Prepare the changes
+
+1. Confirm the target version and inspect the latest release tag, current remote
+   default branch and RubyGems versions. Summarize material operator-visible
+   changes from the previous tag to the selected source, checking current code
+   and project guides. Record runtime requirements, upgrade steps and explicit
+   deprecation decisions. Preserve the dated `CHANGELOG.md` format.
+2. Finish requested dependency updates and release-procedure changes before
+   the release commit. For a full lock refresh, run `bundle update` within the
+   existing Gemfile/gemspec constraints. Resolve using the minimum supported
+   Ruby from `confctl.gemspec`, not just the development shell's newer Ruby.
+   Inspect updates for runtime compatibility; changing declared constraints or
+   Ruby support is a separate compatibility decision.
+3. Regenerate `gemset.nix` with Bundix after lock changes:
+
+   ```sh
+   nix develop -c nix shell --inputs-from . nixpkgs#bundix -c bundix
+   nix develop -c nixfmt gemset.nix
+   ```
+
+   `gemset.nix` is generated dependency metadata. Do not maintain it by hand.
+   `nix/package.nix` and the flake RSpec check pass `gemdir` to `bundlerEnv`,
+   which imports that directory's `gemset.nix`. The development shell instead
+   runs Bundler directly, so passing shell tests does not validate the Nix
+   package's gemset. Keep a dependency refresh in its own commit.
+4. Update `lib/confctl/version.rb`, refresh the confctl path-gem version in
+   `Gemfile.lock` with Bundler, and regenerate `gemset.nix` with Bundix again.
+   Add the changelog entry. Verify all four release identifiers agree:
+   changelog, version constant, lockfile's `confctl` entry and gemset's
+   `confctl.version`. Other gems can legitimately have the old release's
+   version number; do not replace matching numbers globally.
+5. Commit this release unit with subject `Version <version>` and a concise
+   rationale. The release commit must be the final commit, after dependency
+   and procedure changes. If preparation needs a correction, consolidate the
+   unmerged history so this remains true; preserve published default-branch
+   history. Run the declared hooks rather than bypassing them.
+
+## Verify the candidate
+
+Run quick metadata, syntax, whitespace and hook checks, then follow the
+applicable independent final-review procedure for the complete committed
+branch. Provide its full commit series, final diff and migration inventory.
+After review, run the repository's RSpec, RuboCop and Nix formatting checks,
+including the minimum supported Ruby when dependencies changed. Build the
+flake's actual `confctl` package as well as the Ruby gem. Verify Nix's installed
+confctl gem metadata matches the release version.
+
+The gemspec uses a directory glob when `.git` is not a directory. In a Git
+worktree this can include local `.gems`, `.bin`, caches or the `.git` file.
+Build from a clean `git archive` export of the final commit, reusing the
+provisioned Bundler dependency paths, then run `bundle exec rake build` there.
+The rake build task generates the manual and HTML pages. Inspect the archive's
+file list against committed source plus those generated files. Verify version,
+Ruby requirement, executable and changelog, and retain the artifact's checksum.
+Do not run `rake release` to prepare a candidate: it also tags, pushes and uploads.
+
+For a packaged CLI smoke test, extract the gem and load its libraries directly.
+Clear Bundler injection with `Bundler.with_unbundled_env` (or an equivalent
+clean child environment), retain dependency `GEM_HOME`/`GEM_PATH`, and set
+`RUBYLIB` to the extracted `lib`. Assert `ConfCtl.root` and the loaded
+`confctl.rb` come from the extracted tree before running `--help`. In the
+current CLI, GLI's `--version` is unset; inspect `ConfCtl::VERSION` and gemspec
+metadata rather than accepting a version check that only exercises source code.
+
+Publish the development branch according to repository/workspace policy and
+check CI for its exact final head. When replacing a published candidate,
+use the expected old head as the force-with-lease condition and handle
+superseded CI under the applicable workspace rules. Present the final head,
+diff, review/check results and artifact checksum for approval.
+
+## Publish after authorization
+
+Confirm authorization covers the repository's default branch, release tag and
+RubyGems upload. Recheck the remote default branch and existing tag/version.
+Integrate the approved branch under the repository/workspace Git policy. If
+the source changes, rebuild and verify the artifact and reconcile approval
+scope before publication. Keep the final release commit at the tip.
+
+Create an annotated `v<version>` tag at the approved release commit and push
+the authorized branch and tag over SSH. Upload the exact verified gem with
+`gem push <artifact>` using the configured RubyGems authentication; never print
+credentials. Verify that RubyGems reports the expected version, Ruby requirement
+and artifact SHA-256, and that the remote tag resolves to the approved commit.
+
+If any publication step fails, inspect which branch, tag and gem writes
+succeeded before retrying. RubyGems versions cannot be overwritten. Do not
+delete a tag, yank a gem, substitute a rebuilt artifact or bump the version
+as an automatic recovery step. Record the partial result and obtain direction
+for any action outside the approved release. Keep the session available for
+follow-up under its lifecycle policy.

data/skills/confctl-release/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "confctl version release"
+  short_description: "Prepare and publish verified confctl releases"
+  default_prompt: "Use $confctl-release to prepare a confctl version release."

data/spec/confctl/cli/cluster_health_check_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'confctl'
+require 'confctl/cli'
+
+RSpec.describe ConfCtl::Cli::Cluster do
+  let(:gopts) { { color: 'never' } }
+  let(:opts) { { yes: true } }
+  let(:command) { described_class.new(gopts, opts, [nil]) }
+
+  def machine(managed: true, runnable: true, checks: [])
+    instance_double(
+      ConfCtl::Machine,
+      managed:,
+      runnable?: runnable,
+      health_checks: checks
+    )
+  end
+
+  it 'runs checks only for runnable machines' do
+    direct_check = instance_double(ConfCtl::HealthChecks::Base)
+    carried_check = instance_double(ConfCtl::HealthChecks::Base)
+    direct = machine(checks: [direct_check])
+    carried = machine(runnable: false, checks: [carried_check])
+    machines = ConfCtl::MachineList.new(
+      machines: {
+        'direct' => direct,
+        'carried' => carried
+      }
+    )
+
+    allow(command).to receive(:select_machines).with(nil).and_return(machines)
+
+    expect(command).to receive(:run_health_checks) do |selected, run_checks|
+      expect(selected.to_a).to eq([direct])
+      expect(run_checks).to eq([direct_check])
+      []
+    end
+
+    command.health_check
+  end
+end

data/spec/confctl/cli/cluster_skip_current_deploy_spec.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'confctl'
+require 'confctl/cli'
+
+RSpec.describe ConfCtl::Cli::Cluster do
+  let(:gopts) { { color: 'never' } }
+  let(:opts) { { yes: true } }
+  let(:command) { described_class.new(gopts, opts, []) }
+  let(:target_toplevel) { '/nix/store/target-system' }
+  let(:generation) do
+    instance_double(
+      ConfCtl::Generation::Build,
+      name: '2026-06-04--12-00-00',
+      toplevel: target_toplevel
+    )
+  end
+
+  def status_with(current_toplevel:, profile_toplevel: nil)
+    profile_generation =
+      if profile_toplevel
+        instance_double(ConfCtl::Generation::Host, toplevel: profile_toplevel)
+      end
+
+    generations =
+      if profile_generation
+        instance_double(ConfCtl::Generation::HostList, current: profile_generation)
+      end
+
+    instance_double(
+      ConfCtl::MachineStatus,
+      current_toplevel:,
+      generations:
+    )
+  end
+
+  def machine_with(carried:)
+    instance_double(ConfCtl::Machine, carried?: carried)
+  end
+
+  def already_using_target?(action:, current_toplevel:, profile_toplevel:, carried: false)
+    command.send(
+      :already_using_target_generation?,
+      machine_with(carried:),
+      status_with(current_toplevel:, profile_toplevel:),
+      generation,
+      action
+    )
+  end
+
+  it 'skips standalone boot and switch when runtime and profile match' do
+    %w[boot switch].each do |action|
+      expect(
+        already_using_target?(
+          action:,
+          current_toplevel: target_toplevel,
+          profile_toplevel: target_toplevel
+        )
+      ).to be(true)
+    end
+  end
+
+  it 'does not skip standalone boot and switch when the profile is stale' do
+    %w[boot switch].each do |action|
+      expect(
+        already_using_target?(
+          action:,
+          current_toplevel: target_toplevel,
+          profile_toplevel: '/nix/store/old-system'
+        )
+      ).to be(false)
+    end
+  end
+
+  it 'skips standalone test and dry-activate when runtime matches' do
+    %w[test dry-activate].each do |action|
+      expect(
+        already_using_target?(
+          action:,
+          current_toplevel: target_toplevel,
+          profile_toplevel: '/nix/store/old-system'
+        )
+      ).to be(true)
+    end
+  end
+
+  it 'skips carried machines when their carrier-managed profile matches' do
+    expect(
+      already_using_target?(
+        action: 'switch',
+        current_toplevel: target_toplevel,
+        profile_toplevel: nil,
+        carried: true
+      )
+    ).to be(true)
+  end
+
+  it 'does not skip carried machines when their carrier-managed profile is stale' do
+    expect(
+      already_using_target?(
+        action: 'switch',
+        current_toplevel: '/nix/store/old-system',
+        profile_toplevel: nil,
+        carried: true
+      )
+    ).to be(false)
+  end
+
+  it 'does not skip when status data is unavailable' do
+    expect(
+      command.send(
+        :already_using_target_generation?,
+        machine_with(carried: false),
+        status_with(current_toplevel: nil, profile_toplevel: target_toplevel),
+        generation,
+        'switch'
+      )
+    ).to be(false)
+  end
+
+  it 'does not pre-filter copy-only deployments' do
+    copy_command = described_class.new(gopts, opts.merge('copy-only' => true), [])
+    machine = machine_with(carried: false)
+    machines = ConfCtl::MachineList.new(machines: { 'host' => machine })
+    host_generations = { 'host' => generation }
+
+    allow(copy_command).to receive(:deploy_target_statuses).and_raise('unexpected status query')
+
+    filtered_machines, filtered_generations =
+      copy_command.send(:skip_current_deploy_targets, machines, host_generations, 'switch')
+
+    expect(filtered_machines).to equal(machines)
+    expect(filtered_generations).to equal(host_generations)
+  end
+
+  it 'removes skipped hosts from deploy inputs' do
+    machine = machine_with(carried: false)
+    machines = ConfCtl::MachineList.new(machines: { 'host' => machine })
+    host_generations = { 'host' => generation }
+
+    allow(command).to receive(:deploy_target_statuses).and_return(
+      'host' => status_with(
+        current_toplevel: target_toplevel,
+        profile_toplevel: target_toplevel
+      )
+    )
+
+    expect do
+      @filtered_machines, @filtered_generations =
+        command.send(:skip_current_deploy_targets, machines, host_generations, 'switch')
+    end.to output(/Skipping host: already using target generation 2026-06-04--12-00-00/).to_stdout
+
+    expect(@filtered_machines).to be_empty
+    expect(@filtered_generations).to be_empty
+  end
+end

data/spec/confctl/cli/cluster_status_flake_spec.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'confctl'
+require 'confctl/cli'
+
+RSpec.describe ConfCtl::Cli::Cluster do
+  let(:gopts) { { color: 'never' } }
+  let(:opts) { { yes: true, generation: 'none' } }
+  let(:command) { described_class.new(gopts, opts, [nil]) }
+  let(:host) { 'cz.vpsfree/vpsadmin/int.api1' }
+  let(:machine) do
+    instance_double(
+      'ConfCtl::Machine',
+      managed: true,
+      target_host: 'int.api1',
+      carried?: false
+    )
+  end
+  let(:machines) { ConfCtl::MachineList.new(machines: { host => machine }) }
+  let(:status_class) do
+    Struct.new(
+      :uptime,
+      :inputs_info,
+      :target_inputs_info,
+      :target_toplevel,
+      :current_toplevel,
+      :generations
+    ) do
+      def query(**)
+        nil
+      end
+    end
+  end
+  let(:status) do
+    status_class.new(
+      31.7 * 24 * 60 * 60,
+      {
+        'nixpkgs' => { 'rev' => '71caefce01234567', 'shortRev' => '71caefce' },
+        'vpsadmin' => { 'rev' => 'cb29516601234567', 'shortRev' => 'cb295166' }
+      },
+      nil,
+      nil,
+      nil,
+      nil
+    )
+  end
+  let(:nix) { instance_double(ConfCtl::Nix) }
+  let(:build_generations) { instance_double(ConfCtl::Generation::BuildList, count: 29) }
+
+  before do
+    allow(command).to receive(:select_machines).with(nil).and_return(machines)
+    allow(ConfCtl::MachineStatus).to receive(:new).with(machine).and_return(status)
+    allow(ConfCtl::Nix).to receive(:new).and_return(nix)
+    allow(nix).to receive(:eval_inputs_info).with(host).and_return(
+      'nixpkgs' => { 'rev' => 'fea3b36789abcdef', 'shortRev' => 'fea3b367' },
+      'vpsadmin' => { 'rev' => 'cb29516601234567', 'shortRev' => 'cb295166' }
+    )
+    allow(ConfCtl::Generation::BuildList).to receive(:new).with(host).and_return(build_generations)
+  end
+
+  it 'shows deployed input revisions without target arrows' do
+    captured_rows = nil
+    captured_cols = nil
+
+    allow(ConfCtl::Cli::OutputFormatter).to receive(:print) do |rows, cols, **|
+      captured_rows = rows
+      captured_cols = cols
+    end
+
+    command.status_flake
+
+    expect(captured_cols).to include('nixpkgs', 'vpsadmin')
+
+    row = captured_rows.fetch(0)
+
+    expect(row['status'].to_s).to eq('outdated')
+    expect(row['nixpkgs'].to_s).to eq('71caefce')
+    expect(row['vpsadmin'].to_s).to eq('cb295166')
+    expect(row['nixpkgs'].to_s).not_to include('->')
+    expect(row['vpsadmin'].to_s).not_to include('->')
+  end
+end