Decide and implement the TOML write strategy #919

Closed
opened 2026-10-27 13:38:17 +00:00 by sam · 0 comments
Owner

Settle how setup persists config before any prompting code is written; everything else depends on it. BurntSushi/toml loses comments on re-marshal, and config.example.toml carries substantial inline documentation users are meant to read and edit by hand. Options: (a) generate a fresh commented config from a template on first run and only line-patch specific keys on re-run; (b) full re-marshal and accept losing comments; (c) adopt a comment-preserving TOML editor.

Design

Decision: text-based line patching, not decode/re-marshal, not a comment-preserving TOML AST library (none exist for Go that are safe to depend on).

New package internal/infrastructure/configuration/tomlwrite:

  • Apply(src []byte, edits []Edit) ([]byte, error): for each {Table, Key, Value} edit, finds an active "key = value" line in that table and replaces just the value (preserving indent + trailing inline comment); else finds a commented "# key = value" line in that table, uncomments the table header and the line; else appends the key at the end of the table's content (or appends a brand new [table] section at EOF if the table doesn't exist at all, active or commented). Lines not named by an edit are copied through byte-for-byte.
  • Generate(template, edits) is Apply against configtemplate.Example (config.example.toml embedded at the module root via configtemplate.go, since go:embed can't reach outside its own directory tree -- this keeps config.example.toml the single source of truth instead of a second copy, which is exactly the drift bug this epic exists to fix).
  • Value callers pre-render TOML literals; String() and Ref(engine,key) helpers cover the two shapes setup needs (quoted strings, secret.SecretRef inline tables). Deliberately does not import internal/secret -- it edits text, not Go values.

Trade-off: only understands single-line scalar/inline-table values. Does not handle multi-line arrays or array-of-tables (e.g. repos) -- those aren't setup's targets and must not be routed through this patcher.

Tests (internal/infrastructure/configuration/tomlwrite/tomlwrite_test.go) cover: active-key replace preserving trailing comment, active inline-table replace, commented-table uncomment-one-key-leave-siblings-commented, append into existing active table, append brand-new table, byte-identical-elsewhere on a single edit, byte-identical-elsewhere across two sequential runs (the rs9 acceptance criterion), and a full run against the real config.example.toml verified to decode via BurntSushi/toml and round-trip bot_user/forge.token correctly.

go build ./... and task check pass clean; no other files touched.

Acceptance Criteria

The chosen strategy is documented with its trade-off. A first run produces a config a human can read and hand-edit afterwards. A second run changing one value leaves every other line, including comments, byte-identical -- asserted by a test. No strategy is adopted that silently discards user edits.


Imported from beads archie-core-1786637500066-391-e36986c2 · GitHub #412 · type task · priority P2 · created 2026-08-08 · closed 2026-08-08

Settle how setup persists config before any prompting code is written; everything else depends on it. BurntSushi/toml loses comments on re-marshal, and config.example.toml carries substantial inline documentation users are meant to read and edit by hand. Options: (a) generate a fresh commented config from a template on first run and only line-patch specific keys on re-run; (b) full re-marshal and accept losing comments; (c) adopt a comment-preserving TOML editor. ### Design Decision: text-based line patching, not decode/re-marshal, not a comment-preserving TOML AST library (none exist for Go that are safe to depend on). New package internal/infrastructure/configuration/tomlwrite: - Apply(src []byte, edits []Edit) ([]byte, error): for each {Table, Key, Value} edit, finds an active "key = value" line in that table and replaces just the value (preserving indent + trailing inline comment); else finds a commented "# key = value" line in that table, uncomments the table header and the line; else appends the key at the end of the table's content (or appends a brand new [table] section at EOF if the table doesn't exist at all, active or commented). Lines not named by an edit are copied through byte-for-byte. - Generate(template, edits) is Apply against configtemplate.Example (config.example.toml embedded at the module root via configtemplate.go, since go:embed can't reach outside its own directory tree -- this keeps config.example.toml the single source of truth instead of a second copy, which is exactly the drift bug this epic exists to fix). - Value callers pre-render TOML literals; String() and Ref(engine,key) helpers cover the two shapes setup needs (quoted strings, secret.SecretRef inline tables). Deliberately does not import internal/secret -- it edits text, not Go values. Trade-off: only understands single-line scalar/inline-table values. Does not handle multi-line arrays or [[array-of-tables]] (e.g. [[repos]]) -- those aren't setup's targets and must not be routed through this patcher. Tests (internal/infrastructure/configuration/tomlwrite/tomlwrite_test.go) cover: active-key replace preserving trailing comment, active inline-table replace, commented-table uncomment-one-key-leave-siblings-commented, append into existing active table, append brand-new table, byte-identical-elsewhere on a single edit, byte-identical-elsewhere across two sequential runs (the rs9 acceptance criterion), and a full run against the real config.example.toml verified to decode via BurntSushi/toml and round-trip bot_user/forge.token correctly. `go build ./...` and `task check` pass clean; no other files touched. ### Acceptance Criteria The chosen strategy is documented with its trade-off. A first run produces a config a human can read and hand-edit afterwards. A second run changing one value leaves every other line, including comments, byte-identical -- asserted by a test. No strategy is adopted that silently discards user edits. --- _Imported from beads `archie-core-1786637500066-391-e36986c2` · GitHub #412 · type task · priority P2 · created 2026-08-08 · closed 2026-08-08_
sam added the mediumtask labels 2026-10-27 13:38:17 +00:00
sam self-assigned this 2026-10-27 13:38:17 +00:00
sam closed this issue 2026-10-27 13:38:17 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sam/archie#919