werkrevisor/docs/prs/2026-10-13-PR#101-sync-host-config.md

PR#101: A tool compares and syncs the host configs on the Werkator host

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

Problem

Each reviewed repository has its host config twice: as config/<repo>.toml in werkrevisor, and inline as WERKREVISOR_CONFIG_TOML in its machine config on mih09, ~/<repo>/.git/werkator/.werkator.yml. The machine config also holds tokens, so nobody may print it. For PR#100, a throwaway script compared and replaced the block and printed only line numbers; no tool shows whether the other machine configs still match their files.

Non-Goals

• No change of the tokens or of the build definition in a machine config.
• No automatic sync after a merge.

Specification

Feature: sync the inline host config without printing it

Scenario#101.01: compare

So that the operator sees a drift without seeing a token.

• Given a machine config whose inline host config differs from config/<repo>.toml in two lines
• When the operator runs tools/sync-host-config <ssh-target> <repo>
• Then the tool prints the numbers of the two lines and the names of their keys, no value, and exits with 1

Verified by

• test_sync_host_config.HostConfigBlockTest.test_check_prints_only_line_numbers_and_key_names
• test_sync_host_config.HostConfigBlockTest.test_a_changed_comment_changes_no_key
• test_sync_host_config.HostConfigBlockTest.test_a_key_only_on_the_host
• test_sync_host_config.SyncHostConfigScriptTest.test_check_and_apply_over_one_connection_each

Scenario#101.02: replace

So that a changed host config reaches the review with one command.

• Given the same machine config
• When the operator runs tools/sync-host-config --apply <ssh-target> <repo>
• Then the inline host config equals the file, every other line stays, and a backup holds the old version

Verified by

• test_sync_host_config.HostConfigBlockTest.test_apply_replaces_the_block_and_keeps_every_other_line
• test_sync_host_config.HostConfigBlockTest.test_a_block_with_a_chomping_indicator

Scenario#101.03: no inline host config

So that a machine config of another layout stays untouched.

• Given a machine config without WERKREVISOR_CONFIG_TOML
• When the operator runs the tool with --apply
• Then the tool reports the missing block for this repository and changes nothing

Verified by

• test_sync_host_config.HostConfigBlockTest.test_a_machine_config_without_the_block_stays_unchanged
• test_sync_host_config.HostConfigBlockTest.test_a_missing_machine_config

Scenario#101.04: backups

So that the backups do not pile up.

• Given two earlier backups of the tool
• When the tool replaces the inline host config again
• Then only the two newest backups stay

Verified by

• test_sync_host_config.HostConfigBlockTest.test_only_the_two_newest_backups_stay

Solution

tools/host_config_block.py runs on the Werkator host and gets the files as JSON on stdin. It finds the block below WERKREVISOR_CONFIG_TOML: |, also with |- or |+, compares it line by line with the file, and names the keys of both TOML texts by kind: changed, only in the file, only on the host. With apply it writes the file into the block with the indentation of the block, and keeps every other line.

tools/sync-host-config sends the module and the files over one ssh connection, and retries a refused one like tools/deploy-rootfs. Its tests run it with a fake ssh that runs the remote command locally.

A first check on mih09 found:

• werkrevisor, werkregie and werkbaum: equal.
• werkator and werkcrappit: only keys that their own .werkrevisor.toml sets are missing, as intended.
• werkprobe: on the host, [engine] model_role, [hard_yellow] judged_paths and [path_judge] judge and scope are set, and [hard_yellow] paths differs; config/werkprobe.toml lacks these changes.

Additional Changes

• The operations document names version 0.41.0.

Open Questions

None.

Follow-up PRs

• Bring config/werkprobe.toml and the machine config of werkprobe together; the human decides which one is right.