confctl 2.2.3 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 145a3b775c32414d32bf6dba2e9dbf69db302f1893f92f78cd5c5dc3f7bdca4a
-  data.tar.gz: fb1357049bec71e36b4d6fc9e76d0bf0ac8e620f10e7a3ebed8056ba8d6fc848
+  metadata.gz: 0d4e43b6438198685eefeb53d560cc7d048de7ba59179aa091ddda7d34f9f90c
+  data.tar.gz: 513a4cce72db36f303c996f8d48ea28af1810cdca2dda257345ad3b0ba264e7b
 SHA512:
-  metadata.gz: 30fa519e81a6bc96de302e573cfdef8d4aef4a5f0ce918778e94132c7cc6de661c26d3206c9223b4b9e1dbd295c4d4a902100504d0563f8ba64e015db022c952
-  data.tar.gz: 1158a757fea8cd633edc95b976e6db9ec65797fa1623f3cb20912b870dc0b6180bbdc37e5e7d788c8ddb5505d819a8322ff4d7f4e72e3f9b2fd50fe250a3486b
+  metadata.gz: '04186167e0a5bfc5ac3a691592e531e5b84325097241572d5ad789dfdce7514c98de7f73332967323ff0036b447cd8ef988f9e2a94ea0cbb7ee76c256c0cfea4'
+  data.tar.gz: 8e0ee73aacf5b159c9d81b403fff47deddfc7036d715e47d84c362ffc2938acac63a6b797117f55fef4c3714fe8c22a36088edfa5e1f25aba6d14694fedfc1aa

data/.git-hooks/pre_commit/nixfmt.rb

@@ -0,0 +1,13 @@
+module Overcommit::Hook::PreCommit
+  class Nixfmt < Base
+    def run
+      nix_files = applicable_files.select { |v| v.end_with?('.nix') }
+      return :pass if nix_files.empty?
+
+      output = `nixfmt --check #{nix_files.map { |v| "\"#{v}\"" }.join(' ')}`
+      return :pass if $?.exitstatus == 0
+
+      [:fail, output]
+    end
+  end
+end

data/.github/workflows/rspec.yml

@@ -0,0 +1,64 @@
+name: RSpec
+
+on:
+  push:
+
+jobs:
+  rspec:
+    name: rspec (ruby ${{ matrix.ruby-version }})
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["3.3", "3.4", "4.0"]
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v31
+
+      - name: Prepare per-user Nix gcroots
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          user="$(id -un)"
+          group="$(id -gn)"
+          gcroot_dir="/nix/var/nix/gcroots/per-user/${user}"
+
+          sudo mkdir -p "$gcroot_dir"
+          sudo chown "${user}:${group}" "$gcroot_dir"
+
+      - name: Set up Nix test dependencies
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          nix profile install --accept-flake-config nixpkgs#nix-prefetch-git
+
+          nixpkgs_path="$(
+            nix eval --raw --impure \
+              --extra-experimental-features 'nix-command flakes' \
+              --expr '(let f = builtins.getFlake (toString ./.); in f.inputs.nixpkgs.outPath)'
+          )"
+
+          echo "CONFCTL_TEST_NIXPKGS=${nixpkgs_path}" >>"$GITHUB_ENV"
+          echo "NIX_PATH=nixpkgs=${nixpkgs_path}" >>"$GITHUB_ENV"
+
+      - name: Set up Ruby + Bundler cache
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - name: Run RSpec
+        shell: bash
+        run: |
+          bundle exec rspec

data/.github/workflows/rubocop.yml

@@ -0,0 +1,27 @@
+name: RuboCop
+
+on:
+  push:
+
+jobs:
+  rubocop:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+
+      - name: Set up Ruby + Bundler cache
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Run RuboCop
+        shell: bash
+        run: |
+          bundle exec rubocop --parallel --force-exclusion

data/.github/workflows/tests.yml

@@ -0,0 +1,139 @@
+name: Tests
+
+on:
+  workflow_dispatch:
+    inputs:
+      stop_on_failure:
+        description: Stop scheduling after the first unexpected result
+        required: true
+        default: false
+        type: boolean
+  push:
+    paths:
+      - .github/workflows/tests.yml
+      - flake.nix
+      - flake.lock
+      - Gemfile
+      - Gemfile.lock
+      - bin/**
+      - lib/**
+      - libexec/**
+      - nix/**
+      - tests/**
+      - test-runner.sh
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Run ci-tagged tests
+    runs-on: self-hosted
+    timeout-minutes: 360
+
+    steps:
+      - name: Checkout confctl
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+
+      - name: Reset per-user Nix gcroots
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          user="$(id -un)"
+          gcroot_dir="/nix/var/nix/gcroots/per-user/${user}"
+
+          if [ ! -d "$gcroot_dir" ]; then
+            echo "Missing gcroots directory: $gcroot_dir" >&2
+            exit 1
+          fi
+
+          if [ ! -w "$gcroot_dir" ]; then
+            echo "Gcroots directory is not writable: $gcroot_dir" >&2
+            ls -ld "$gcroot_dir" >&2
+            exit 1
+          fi
+
+          find "$gcroot_dir" -mindepth 1 -maxdepth 1 -exec rm -rf -- {} +
+
+      - name: Prepare test state
+        id: prepare-tests
+        uses: vpsfreecz/vpsadminos/.github/actions/prepare-test-state@staging
+
+      - name: Run tests
+        id: run-tests
+        timeout-minutes: 320
+        shell: bash
+        env:
+          STOP_ON_FAILURE: ${{ github.event.inputs.stop_on_failure || 'false' }}
+        run: |
+          set -o pipefail
+
+          args=(
+            test
+            -f
+            --jobs auto
+            -t ci
+            --state-dir "$TEST_RUNNER_STATE_DIR"
+          )
+
+          if [[ "$STOP_ON_FAILURE" == "true" ]]; then
+            args+=(--stop-on-failure)
+          fi
+
+          ./test-runner.sh "${args[@]}" | tee test.log
+
+      - name: Upload full test logs
+        id: upload-test-logs
+        if: >-
+          (failure() || cancelled()) &&
+          steps.prepare-tests.outcome == 'success' &&
+          steps.run-tests.outcome != 'skipped'
+        uses: vpsfreecz/vpsadminos/.github/actions/upload-test-logs@staging
+        with:
+          name: confctl-test-logs-${{ github.run_id }}
+          paths: |
+            ${{ steps.prepare-tests.outputs.state-directory }}/**/*.log
+            ${{ steps.prepare-tests.outputs.state-directory }}/**/*.txt
+
+      - name: Evaluate test results
+        if: >-
+          always() &&
+          steps.prepare-tests.outcome == 'success' &&
+          steps.run-tests.outcome != 'skipped'
+        uses: vpsfreecz/vpsadminos/.github/actions/evaluate-test-results@staging
+        with:
+          log-file: test.log
+
+      - name: Summarise test logs
+        if: >-
+          always() &&
+          steps.prepare-tests.outcome == 'success' &&
+          steps.run-tests.outcome != 'skipped'
+        uses: vpsfreecz/vpsadminos/.github/actions/summarise-test-logs@staging
+        with:
+          logs-root: ${{ steps.prepare-tests.outputs.state-directory }}
+
+      - name: Cleanup test state
+        if: always()
+        uses: vpsfreecz/vpsadminos/.github/actions/cleanup-test-state@staging
+        with:
+          state-directory: ${{ steps.prepare-tests.outputs.state-directory }}
+          prepare-outcome: ${{ steps.prepare-tests.outcome }}
+          test-outcome: ${{ steps.run-tests.outcome }}
+          upload-outcome: ${{ steps.upload-test-logs.outcome }}
+
+      - name: Cleanup per-user Nix gcroots
+        if: always()
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          user="$(id -un)"
+          gcroot_dir="/nix/var/nix/gcroots/per-user/${user}"
+
+          if [ -d "$gcroot_dir" ] && [ -w "$gcroot_dir" ]; then
+            find "$gcroot_dir" -mindepth 1 -maxdepth 1 -exec rm -rf -- {} +
+          fi

data/.gitignore

@@ -1,9 +1,14 @@
-Gemfile.lock
-pkg
-man/style.css
-man/*.html
-man/**/*.html
-man/man?/*.?
-html_doc
+.bin/
+.bundle/
+.cache/
+.confctl/
 .gems
+.man/
+.rubocop_cache/
 .yardoc
+html_doc
+man/**/*.html
+man/*.html
+man/man?/*.?
+man/style.css
+pkg

data/.overcommit.yml

@@ -1,4 +1,6 @@
 PreCommit:
+  Nixfmt:
+    enabled: true
   RuboCop:
     enabled: true
 CommitMsg:

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -1,7 +1,10 @@
 inherit_from: .rubocop_todo.yml
+inherit_mode:
+  merge:
+    - Exclude
 
 AllCops:
-  TargetRubyVersion: 3.1.0
+  TargetRubyVersion: 3.3.0
   NewCops: enable
   Exclude:
     - '*.rb'
@@ -41,6 +44,8 @@ Naming/HeredocDelimiterNaming:
   Enabled: false
 Naming/MethodParameterName:
   Enabled: false
+Naming/PredicateMethod:
+  Enabled: false
 
 Style/CaseEquality:
   Enabled: false
@@ -59,6 +64,8 @@ Style/MultilineBlockChain:
   Enabled: false
 Style/NumericPredicate:
   EnforcedStyle: comparison
+Style/OneClassPerFile:
+  Enabled: false
 Style/PreferredHashMethods:
   EnforcedStyle: verbose
 Style/SafeNavigation:

data/AGENTS.md

@@ -0,0 +1,42 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `lib/` Ruby sources; CLI commands under `lib/confctl/cli`, Nix build helpers in `lib/confctl/nix*`, health checks in `lib/confctl/health_checks`.
+- `bin/confctl` entrypoint; `libexec/` helper scripts; `template/` ERB for generated docs; rendered man pages live in `man/man8/`.
+- `nix/` contains Nix modules and overlays; `example/` provides a sample cluster and swpins setup; `docs/` holds focused guides; release gems are stored in `pkg/`.
+
+## Build, Test, and Development Commands
+- Enter `nix develop` to get Ruby, bundler, nixfmt, and the `confctl` binstub wired to the local sources.
+- `bundle exec rubocop` lints Ruby; pre-commit hook also runs `nixfmt` on Nix files.
+- `bundle exec rspec` (or `bundle exec rake spec`) runs the automated Ruby tests.
+- Format Nix code with `nixfmt` (or `nixfmt-tree` to format directories) from inside the shell.
+- `bundle exec rake md2man:man` regenerates manpages; `bundle exec rake confctl-options` rebuilds the options reference from templates.
+- Package the gem with `bundle exec rake build` (outputs to `pkg/`) and install locally with `bundle exec rake install`.
+
+## Coding Style & Naming Conventions
+- Ruby target version 3.1; use 2-space indents, LF endings, UTF-8 (`.editorconfig`).
+- Snake_case for methods/variables, CamelCase for classes/modules, kebab-case for CLI commands/flags; keep option names consistent with existing Nix modules.
+- RuboCop config is permissive on metrics—still prefer small, single-purpose methods and early returns; avoid introducing new global state.
+
+## Testing Guidelines
+- Run `bundle exec rspec` for automated coverage and `bundle exec rubocop` for linting.
+- Keep focused manual runs of the commands you touch (build, deploy, swpins, health checks) against a local configuration such as `example/`.
+- When fixing a bug, add a minimal regression check in RSpec if practical and document the manual steps you executed.
+
+## Commit & Pull Request Guidelines
+- Before preparing or publishing a confctl version release, read
+  [`skills/confctl-release/SKILL.md`](skills/confctl-release/SKILL.md). It covers
+  Bundix metadata, release commit ordering, package verification and publication.
+- Commit subjects are short and imperative. Without a prefix, capitalize the first word. With a `topic/component:` prefix, keep the first word after `:` lowercase. Avoid trailing periods and bundle related changes together.
+- Write commit messages in a temporary file and pass them to `git commit -F`
+  or `git commit --amend -F`. Wrap message lines to 80 columns.
+- Commit messages must explain what problem or goal the change addresses.
+- For fixes, explain how the change fixes or works around the problem. For
+  new functionality, explain how the new behavior works.
+- Flake input updates (`vpsadminos`) flow:
+  1. Read current rev: `nix flake metadata --json . | jq -r '.locks.nodes.vpsadminos.locked.rev'`.
+  2. Update input: `nix flake update vpsadminos` (or `nix flake lock --update-input vpsadminos`).
+  3. Verify only `flake.lock` changed for this update commit.
+  4. Commit with subject format: `flake: vpsadminos <old9> -> <new9>` (example: `flake: vpsadminos 2cab01000 -> 08bb11324`).
+- Describe PRs clearly with motivation, scope, and manual verification notes; link relevant issues and update docs/manpages when behavior changes.
+- Run rspec, rubocop, and nixfmt before pushing; ensure generated artifacts (`man/`, `pkg/` when releasing) reflect your changes.

data/CHANGELOG.md

@@ -1,3 +1,57 @@
+# Wed Oct 07 2026 -- version 3.0.0
+
+Software pins (`swpins`) remain supported in v3.0.0 and will be removed in v4.
+Use [the migration guide](docs/swpins-to-flakes.md) to move existing
+configurations to flake inputs.
+
+## Flake configurations
+
+- Add a flake backend for building and deploying NixOS and vpsAdminOS machines
+- Create flake-based configurations by default with `confctl init`; use
+  `confctl init --swpins` for the legacy software pin workflow
+- Add `confctl inputs` commands to list, update and set input revisions at the
+  root, channel and machine levels, with optional commits and changelogs
+- Map dependency roles to flake inputs through channels and per-machine overrides;
+  see [docs/flake-inputs.md](docs/flake-inputs.md)
+- Add `confctl migrate swpins-to-flakes`, including `--dry-run` and individual
+  migration steps
+- Record flake inputs in build generations and show their revisions in generation
+  listings, status, diffs and changelogs
+- Record the configuration source revision in deployed machine metadata
+- Add flake packages, configuration development shells and an example flake
+  configuration
+- Support optional impure evaluation and legacy `NIX_PATH` mappings for flake
+  builds
+- Evaluate only requested flake build outputs and build machine metadata as JSON
+- Group shared input changelogs and report resolved revisions after setting inputs
+- Fail input updates when Nix falls back to cached GitHub metadata
+
+## Deployment and fixes
+
+- Skip deployment to machines already using the target generation, avoiding
+  unnecessary copying, activation, reboots and health checks
+- Support custom SSH ports through `host.port`, including Nix copies
+- Preserve spaces and shell metacharacters in remote command arguments
+- Fix deployment confirmation on localhost
+- Support CLI output and progress reporting without a terminal
+- Reuse prefetched Git checkouts when updating software pins and fix commits of
+  changed software pin files
+- Fix garbage collection roots for software pin paths
+- Support NixOS in `kexec-netboot`, stream downloads and add `--no-sync`
+- Honor NixOS PXE kernel parameters and preserve the init path for carried images
+- Add RSpec coverage and integration tests for flakes, software pins, automatic
+  rollback, carriers and netboot
+- Refresh Ruby dependencies, including the vpsAdmin and HaveAPI clients
+
+## Upgrade notes
+
+- Require Ruby 3.3 or newer (previously Ruby 3.1)
+- Remove the `confReplaceVarsWith` compatibility wrapper; confctl's Nix modules
+  now require `pkgs.replaceVarsWith`
+- Existing software pin configurations and generations remain supported. Migrating
+  to flakes is optional in v3.0.0. Keep the migration on a configuration branch;
+  confctl v2 cannot use the resulting flake configuration.
+
 # Fri Jun 06 2025 -- version 2.2.3
 - Open git commit editor only when running in a terminal
 

data/Gemfile

@@ -1,8 +1,9 @@
 source 'https://rubygems.org'
 gemspec
 
-group :development do
+group :development, :test do
   gem 'overcommit'
-  gem 'rubocop', '~> 1.75.0'
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.85.0'
   gem 'rubocop-rake'
 end

data/Gemfile.lock

@@ -0,0 +1,198 @@
+PATH
+  remote: .
+  specs:
+    confctl (3.0.0)
+      curses
+      gli (~> 2.22.0)
+      json
+      md2man
+      rainbow (~> 3.1.1)
+      rake
+      require_all (~> 2.0.0)
+      tty-command (~> 0.10.1)
+      tty-cursor (~> 0.7.1)
+      tty-pager (~> 0.14.0)
+      tty-progressbar (~> 0.18.2)
+      tty-spinner (~> 0.9.3)
+      vpsfree-client (~> 0.19.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (8.1.4)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.1.3)
+    binman (5.1.0)
+      opener (>= 0.1.0, < 1)
+    childprocess (5.1.0)
+      logger (~> 1.5)
+    concurrent-ruby (1.3.8)
+    connection_pool (3.0.2)
+    curses (1.7.0)
+    diff-lcs (1.6.2)
+    domain_name (0.6.20260921)
+    drb (2.2.3)
+    gli (2.22.2)
+      ostruct
+    hana (1.3.7)
+    haveapi-client (0.29.8)
+      activesupport (>= 7.0)
+      highline (~> 3.1)
+      json
+      require_all (~> 2.0.0)
+      rest-client (~> 2.1.0)
+      ruby-progressbar (~> 1.13.0)
+    highline (3.1.2)
+      reline
+    http-accept (1.7.0)
+    http-cookie (1.1.6)
+      domain_name (~> 0.5)
+    i18n (1.15.2)
+      concurrent-ruby (~> 1.0)
+    iniparse (1.5.0)
+    io-console (0.9.4)
+    json (2.21.2)
+    json_schemer (2.5.0)
+      bigdecimal
+      hana (~> 1.3)
+      regexp_parser (~> 2.0)
+      simpleidn (~> 0.2)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    mcp (0.25.0)
+      json_schemer (>= 2.4)
+    md2man (5.1.2)
+      binman (~> 5.0)
+      redcarpet (~> 3.0)
+      rouge (~> 3.0)
+    mime-types (3.7.0)
+      logger
+      mime-types-data (~> 3.2025, >= 3.2025.0507)
+    mime-types-data (3.2026.1006)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    netrc (0.11.0)
+    opener (0.1.0)
+    ostruct (0.6.3)
+    overcommit (0.73.0)
+      childprocess (>= 0.6.3, < 6)
+      iniparse (~> 1.4)
+      rexml (>= 3.4.2)
+    parallel (1.28.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
+    pastel (0.8.0)
+      tty-color (~> 0.5)
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    redcarpet (3.6.1)
+    regexp_parser (2.13.1)
+    reline (0.7.0)
+      io-console (~> 0.5)
+    require_all (2.0.0)
+    rest-client (2.1.0)
+      http-accept (>= 1.7.0, < 2.0)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 4.0)
+      netrc (~> 0.8)
+    rexml (3.4.4)
+    rouge (3.30.0)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    simpleidn (0.3.0)
+    strings (0.2.1)
+      strings-ansi (~> 0.2)
+      unicode-display_width (>= 1.5, < 3.0)
+      unicode_utils (~> 1.4)
+    strings-ansi (0.2.0)
+    tty-color (0.6.0)
+    tty-command (0.10.1)
+      pastel (~> 0.8)
+    tty-cursor (0.7.1)
+    tty-pager (0.14.0)
+      strings (~> 0.2.0)
+      tty-screen (~> 0.8)
+    tty-progressbar (0.18.3)
+      strings-ansi (~> 0.2)
+      tty-cursor (~> 0.7)
+      tty-screen (~> 0.8)
+      unicode-display_width (>= 1.6, < 3.0)
+    tty-screen (0.8.2)
+    tty-spinner (0.9.3)
+      tty-cursor (~> 0.7)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.6.0)
+    unicode_utils (1.4.0)
+    uri (1.1.1)
+    vpsadmin-client (4.2.1)
+      base64
+      curses
+      haveapi-client (~> 0.29.6)
+      json
+      ruby-progressbar
+    vpsfree-client (0.19.0)
+      vpsadmin-client (~> 4.0)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  confctl!
+  overcommit
+  rspec (~> 3.13)
+  rubocop (~> 1.85.0)
+  rubocop-rake
+
+BUNDLED WITH
+   2.5.7