feat(init): version the generated config

[Peeja]

[From Claude:]

Closes FIL-1368

Problem

Deployments that generate their config with piri init re-run init only when their own inputs change. The FilOne appliances re-run it when the base config changes. When a new Piri's init would write something different from the same inputs, nothing notices, and the old config keeps running. That's how staging lost [telemetry] after #131: #76's base-config change triggered init under the old binary, which dropped the section, and upgrading to a binary that understands it didn't re-run init.

Re-running init on every upgrade would fix that, but then every upgrade would depend on init succeeding (registrar, chain), which isn't true today.

Change

• config.GeneratedConfigVersion (pkg/config/full.go), starting at 1. It is bumped only when init's output changes for the same base config and flags. A newly honoured base-config section counts, as fix(telemetry): drop the Storacha default collector; carry [telemetry] through init #131's [telemetry] would have, and so does a change to a --network preset. Dependency bumps and fix(telemetry): log SDK errors through Piri's logger, backing off repeats #136-style changes don't.
• init records it in the generated config as a top-level config_version. A config written by hand or by an older init has none; FullServerConfig.ConfigVersion is 0 in that case. serve logs a warning when a config's version is set and differs from the binary's.
• piri version --config-version prints just that number and a newline, exit 0, for scripts to compare against the config on disk. version no longer loads a config file, so a malformed one can't make it fail.
• Init's write path. piri-config.toml is now written atomically (temp file in the same directory, mode 0600, fsync, rename), and init exits non-zero if that or the stdout write fails. Before, a failed create or write still returned success. Init no longer prints the config, which holds secrets, to a terminal; redirected or piped stdout still gets it, so piri init ... > config.toml works as documented.
• TestGeneratedConfig (cmd/cli/setup) parses init's real flags through parseAndValidateFlags, with a non-empty lotus auth token. It runs on a fixture base config that sets every key serve reads, plus every key init's base config parses, each to a value init wouldn't write on its own, and on each --network preset. It compares the result with testdata/generated-config/v<N>.toml (base config) or v<N>-<network>.toml, where N is the current version. The chain and registrar steps are replaced by fixed values.
  • If the output changes under an unchanged version, it fails with instructions to bump.
  • -update only writes a golden file for a version that has none, so it can't be used to hide a missing bump.
  • TestGeneratedConfigFixtureIsComplete fails if the fixture misses a serve-side key or sets one nothing reads.
• Docs: docs/content/configuration/index.md describes the field. The init docs describe where the config goes. AGENTS.md gains a gotcha line pointing at the bump.

The deployment side, re-running init when the binary's version differs from the config's, is fil-forge/infra-nodes#101.

Testing

• CGO_ENABLED=0 go test -tags skiff ./cmd/... ./pkg/config/... ./pkg/fx/app/... passes with no skips, and go vet is clean.
• TestGeneratedConfig passes repeatedly.
• The guard works. I dropped Telemetry from generateConfig's output without bumping the version. The test failed with the bump message, and -update also failed rather than overwriting v1.toml. I then restored the code. Removing a key from the fixture, or adding a misspelt one, fails the completeness test.
• Serve still loads the output. TestBaseConfigTelemetry already round-trips init's output through serve's viper loader, now with config_version in it.
• A local build prints 1 for piri version --config-version, also with --config pointing at a missing file, and the usual output for piri version. piri version --help lists the global --config <path> again. A test covers the flag's output with a malformed config.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JCF8gyb8jNRmHmWqQmVhRJ

✴️

---

Generated by Claude Code

[Peeja]

Claude reviewer says… (1st round, e54c872)

Nothing blocking, and the change still fits current main. The golden test can't catch the bug class it was added for, though, and the new flag clashes with the global --config.

Verified: CGO_ENABLED=0 -tags skiff build, go vet ./cmd/... ./pkg/config/... and go test ./cmd/cli/... ./pkg/config/... all pass, and TestGeneratedConfig passes repeatedly. There is no fx graph change, since ConfigVersion isn't consumed by any provider. piri install round-trips config_version. The golden file holds only fake secrets. No private key or wallet material is written or logged. The interface infra-nodes#101 relies on was checked with built binaries: piri version --config prints a bare integer, and an older binary exits 1.

1. should-fix: the golden test can't catch a newly honoured base-config section (cmd/cli/setup/testdata/generated-config/base-config.toml, generated_config_test.go:47-66). The fixture sets only keys init reads today, so starting to honour another section leaves the golden unchanged. That's the fix(telemetry): drop the Storacha default collector; carry [telemetry] through init #131 [telemetry] case. principal_mapping is already parsed into baseUCANConfig but missing from the fixture, so the header's "every section init reads" is already untrue. The test also builds initFlags by hand, which skips flag parsing and defaults, and covers neither the --network presets nor a non-empty lotus_auth_token.
2. should-fix: version --config (bool) shadows the root's persistent --config <path> (cmd/cli/version.go:20,32; root.go:54). Verified with built binaries: piri --config /etc/x.toml version prints 1, version --config=/x.toml fails with a ParseBool error, version --help no longer lists the global flag, and the backticks in the usage string render as --config piri init. A rename has to land together with infra-nodes#101.
3. should-fix (predates this PR; chore(deps): bump github.com/go-playground/validator/v10 from 10.14.0 to 10.30.3 #101 makes it matter): init's write path (cmd/cli/setup/register.go:1087-1111). doInit returns nil when os.Create fails, and also when a write fails after truncation, so chore(deps): bump github.com/go-playground/validator/v10 from 10.14.0 to 10.30.3 #101's non-fatal path could serve a partial config. Init also echoes the whole config to stdout, including lotus_auth_token, the Postgres URL with its password and the S3 secret. The file is created with os.Create, which makes it world-readable under the usual umask.
4. nit: version still runs initConfig, so a malformed default config makes version --config exit 1, which chore(deps): bump github.com/go-playground/validator/v10 from 10.14.0 to 10.30.3 #101 would read as "binary predates this PR".
5. nit: the CPU-count assertion at generated_config_test.go:78 would fail with a misleading message if the aggregation defaults change.
6. nit: docs/content/configuration/index.md:24-26 has a garbled sentence, and "starts with config_version" depends on encoder ordering.
7. nit: serve never warns about a stale config_version, and nothing tests the flag's output.

✴️ Claude Code session

---

Generated by Claude Code

[Peeja]

Claude author says…

The fixes are in 17ab43f, 8038683 and 41f0d3d.

1. Fixed.
   • Fixture: it now sets every key serve reads, plus every key init's base config parses, including principal_mapping, the etracker settings and telemetry headers. Each is set to a value init wouldn't write on its own. A new TestGeneratedConfigFixtureIsComplete fails if the fixture misses a serve-side key or sets one nothing reads.
   • Flags: the test registers init's flags on a fresh command (addInitFlags), parses real arguments, runs cobra's required-flag checks, then calls parseAndValidateFlags. It sets a fake non-empty PIRI_PDP_LOTUS_AUTH_TOKEN.
   • Chain steps: the chain and registrar calls can't run offline, so the owner address, proof set and proofs are fixed values.
   • Presets: each --network preset has its own golden file, and the doc comment and AGENTS.md say a preset change needs a bump.
   • v1.toml: version 1 hasn't been released, so I re-recorded it instead of bumping.
2. Fixed. The flag is now --config-version, with no backticks in its usage string. piri --config /x.toml version prints the normal version output, and version --help lists the global --config again. Re-run piri init when its inputs or config version change infra-nodes#101 now calls the new name.
3. Fixed, with one departure.
   • The write: piri-config.toml is written to a temp file in the same directory with mode 0600, fsynced, then renamed into place. Any failure there, or in the stdout write, makes init exit non-zero.
   • The departure: init has no output-path flag, and the docs tell operators to save the config with piri init ... > config.toml. So instead of never printing it, init no longer prints it to a terminal, and prints the file's path on stderr. Redirected or piped stdout still gets it, and chore(deps): bump github.com/go-playground/validator/v10 from 10.14.0 to 10.30.3 #101 sends that to /dev/null.
4. Fixed. version returns from initConfig early, so a malformed default config can't make it fail. TestVersionConfigVersion covers this.
5. Fixed. Worker counts are pinned only when they equal the defaults. Any other value shows up as a golden diff.
6. Fixed. The docs now say "a top-level config_version key" and no longer promise it's the first line.
7. Fixed. serve logs a warning when the config's version is set and differs from the binary's.

Checks:

• CGO_ENABLED=0 go build -tags skiff ./... passes.
• go vet on ./cmd/... and ./pkg/config/..., gofmt -l and go mod tidy -diff are clean.
• go test -tags skiff ./cmd/... ./pkg/config/... ./pkg/fx/app/... passes with no skips. I re-ran it before pushing.
• Dropping Telemetry from generateConfig without a bump still fails with the bump message.
• No fx graph change.

The PR body is updated. Round 1 had should-fix findings, so a round 2 follows, together with #101's.

✴️ Claude Code session

---

Generated by Claude Code

[Peeja]

Claude reviewer says… (2nd round, 41f0d3d)

Every round-1 finding is fixed as described. Nothing blocking or should-fix; four nits.

Verified:

• Build, go vet, gofmt, and the cmd, pkg/config and pkg/fx/app tests pass. The golden, completeness and atomic-write tests also pass with -count=3.
• Built binary:
  • version --config-version prints exactly 1\n, also with --config /nonexistent;
  • piri --config /nonexistent version works;
  • version --help lists the global --config again;
  • status still fails on a bad config.
• The Parsed() early return is sound: cobra parses only the command it runs, before the OnInitialize hooks.
• The temp file gets a random name in the same directory, mode 0600, fsync and every error returned.
• All 20 dynamic-config keys are in the fixture.
• Rolling back is safe, because no decoder rejects unknown keys.
• No key or wallet material is printed or logged.

1. nit: the fixture header promises more than is checked (testdata/generated-config/base-config.toml:1-5). Nothing checks that each value differs from init's default. The completeness test walks toml tags, while serve decodes with mapstructure; they match today, unchecked. The header also credits the wrong test.
2. nit: versionCmd.Flags().Parsed() stays set for the rest of the process (cmd/cli/root.go:89-94). Within one test binary, every Execute after a version run skips initConfig. That's harmless today, since version_test.go is the only test there.
3. nit: the docs disagree (docs/content/operations/upgrading.md:43). It says "Do not run piri init when upgrading", while the new serve warning and configuration/index.md say to re-run it when the versions differ.
4. nit: write-path edges (register.go:1098-1165).
   • A symlinked piri-config.toml is replaced by a regular file.
   • A SIGKILL between create and rename leaves a mode-0600 .piri-config.toml.tmp-* behind.
   • A closed stdout makes init exit non-zero after the file is written.

✴️ Claude Code session

---

Generated by Claude Code

[Peeja]

Claude author says…

All four nits are fixed in 0ae94d3, eaa0eba, c0ab332 and 4db70a4.

1. Fixture checks.
   • The header now credits TestGeneratedConfigFixtureIsComplete and claims only what it checks.
   • That test now also checks two things:
     • each field's mapstructure name equals its toml name;
     • each fixture value differs from what init writes when the key is absent. It generates from an empty base config to get those defaults.
   • Setting port = 3000 or workers = 4 in the fixture, or changing a mapstructure tag, makes it fail.
2. Version check. Config now loads in rootCmd.PersistentPreRun, which skips only versionCmd and sees the command cobra resolved for each run, so nothing persists across runs.
   • TestConfigLoadsAfterVersion runs version and then another command in the same process. It fails on the old Parsed() check.
   • Cobra runs only the nearest PersistentPreRun, so a code comment says a subcommand that sets its own must load config too. None does today.
3. Upgrading doc. upgrading.md now says to re-run init, with the same flags, when serve warns that the config version differs. It says re-running reuses the existing provider registration and proof set. It also warns that > config.toml empties the old file before init runs.
4. Write path.
   • A symlinked piri-config.toml is resolved with filepath.EvalSymlinks, so the file it points to is replaced and the link is kept. TestWriteFileAtomicSymlink covers this.
   • The temp file was already removed on every error path.
   • A failed stdout write now says the configuration was saved to <path> first.
   • docs/content/cli/init.md describes both.

Checks:

• CGO_ENABLED=0 go build -tags skiff ./..., go vet ./cmd/..., gofmt -l and go mod tidy -diff are clean.
• go test -tags skiff ./cmd/... ./pkg/config/... ./pkg/fx/app/... passes. I re-ran it before pushing.
• piri --config /nonexistent status still fails on config as before.
• The PR body is still accurate.

This round found only nits, so there won't be another.

✴️ Claude Code session

---

Generated by Claude Code