[PR #1983] [MERGED] fix(setup): configure an empty Hermes config.yaml #4947

New issue

Closed

opened 2026-10-31 00:57:16 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 00:57:16 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1983
Author: @viniciusdsandrade
Created: 10/11/2026
Status: ✅ Merged
Merged: 10/12/2026
Merged by: @morluto

Base: main ← Head: fix/setup-empty-hermes-config

📝 Commits (2)

462e917 fix(setup): treat an empty Hermes config.yaml as a new document
96f8321 test(setup): configure an empty Hermes config.yaml

📊 Changes

2 files changed (+26 additions, -2 deletions)

View changed files

📝 src/application/ClientConfigurationDocument.ts (+2 -2)
📝 tests/boundary/filesystem/hermesClientConfiguration.test.ts (+24 -0)

📄 Description

Summary

rea setup fails for Hermes when config.yaml exists but is empty. YAML parses an empty file to null, and the Hermes branch of parseDocument checked that value as an object before the shared empty-file rule, so the configuration was rejected as malformed. Apply the empty-file rule before the Hermes YAML parse, as #1117 did for JSON clients.

Related: #1633 lists an empty Hermes config.yaml as a fresh first-run state. It tracks a separate Hermes version warning, so this PR does not close it.

Problem and expected behavior

parseDocument in src/application/ClientConfigurationDocument.ts returns objectSchema.parse(parseYaml(text)) for Hermes before it reaches isEmptyClientConfigurationText. In yaml 2.9.0 an empty source composes to a document with null contents, so parse("") returns null and the object schema throws. configureClientConfiguration then returns { status: "failed", reason: "readback" }. Setup, uninstall, update maintenance and the shared configuration reader all parse through parseClientConfiguration, so they reject the same file.

A missing config.yaml already works, because setup parses "{}" in its place, and serializeHermesConfiguration already writes a fresh document when the original text is empty; that branch could not be reached. Expected: an empty config.yaml is configured like a missing one.

Change and scope

Move the existing empty-file check above the Hermes branch. Pi still rejects empty files, TOML and Grok still parse directly, and JSON clients keep the same rule. A comment-only config.yaml is not included: it also parses to null, but the Hermes serializer edits the parsed YAML document in place and would need separate handling.

Contract and boundary impact

Semantic owner and earliest changed stage: client configuration parsing in parseDocument.
CLI and MCP/tool-catalog contract: none.
Provider, bridge, target-format, or platform compatibility: Hermes client setup on every platform.
Evidence, artifact, provenance, or reconstruction contract: none.
Process execution, authorization, cleanup, or containment impact: none; backups and readback are unchanged.
Generated metadata (docs/public/product-catalog.json), package, or installation impact: none.

Evidence and regression coverage

Tests added or updated: tests/boundary/filesystem/hermesClientConfiguration.test.ts configures zero-byte and newline-only config.yaml files, checks the written YAML and reads the registration back as aligned.
Base reproduction or other evidence: source-derived. yaml 2.9.0 Composer.end creates a Document with null contents for an empty source and parse returns null; objectSchema.parse(null) throws before the empty-file rule. The new test's configured assertion fails on the base revision.
User-visible CLI/MCP output (if applicable): before, Hermes setup reports a failed configuration readback for an empty config.yaml; after, Hermes is configured.
Remaining proof gaps: no real Hermes client run.

Validation performed

No local commands were run: this environment has no installed dependencies. The evidence above is source-derived; CI runs the deterministic suite.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: not applicable.
Package or release metadata impact: none.
Security, privacy, process, or containment review: none; only the classification of empty files changes.

Review checklist

This PR addresses a concrete problem or an agreed enhancement.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/1983 **Author:** [@viniciusdsandrade](https://github.com/viniciusdsandrade) **Created:** 10/11/2026 **Status:** ✅ Merged **Merged:** 10/12/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `fix/setup-empty-hermes-config` --- ### 📝 Commits (2) - [`462e917`](https://github.com/morluto/rea/commit/462e9174c77c5e1558dfcfd048d731be77bfa481) fix(setup): treat an empty Hermes config.yaml as a new document - [`96f8321`](https://github.com/morluto/rea/commit/96f8321d152e0ffe42b5faecfce9b015f151b4f5) test(setup): configure an empty Hermes config.yaml ### 📊 Changes **2 files changed** (+26 additions, -2 deletions) <details> <summary>View changed files</summary> 📝 `src/application/ClientConfigurationDocument.ts` (+2 -2) 📝 `tests/boundary/filesystem/hermesClientConfiguration.test.ts` (+24 -0) </details> ### 📄 Description ## Summary `rea setup` fails for Hermes when `config.yaml` exists but is empty. YAML parses an empty file to `null`, and the Hermes branch of `parseDocument` checked that value as an object before the shared empty-file rule, so the configuration was rejected as malformed. Apply the empty-file rule before the Hermes YAML parse, as #1117 did for JSON clients. Related: #1633 lists an empty Hermes `config.yaml` as a fresh first-run state. It tracks a separate Hermes version warning, so this PR does not close it. ## Problem and expected behavior `parseDocument` in `src/application/ClientConfigurationDocument.ts` returns `objectSchema.parse(parseYaml(text))` for Hermes before it reaches `isEmptyClientConfigurationText`. In yaml 2.9.0 an empty source composes to a document with null contents, so `parse("")` returns `null` and the object schema throws. `configureClientConfiguration` then returns `{ status: "failed", reason: "readback" }`. Setup, uninstall, update maintenance and the shared configuration reader all parse through `parseClientConfiguration`, so they reject the same file. A missing `config.yaml` already works, because setup parses `"{}"` in its place, and `serializeHermesConfiguration` already writes a fresh document when the original text is empty; that branch could not be reached. Expected: an empty `config.yaml` is configured like a missing one. ## Change and scope Move the existing empty-file check above the Hermes branch. Pi still rejects empty files, TOML and Grok still parse directly, and JSON clients keep the same rule. A comment-only `config.yaml` is not included: it also parses to `null`, but the Hermes serializer edits the parsed YAML document in place and would need separate handling. ## Contract and boundary impact - Semantic owner and earliest changed stage: client configuration parsing in `parseDocument`. - CLI and MCP/tool-catalog contract: none. - Provider, bridge, target-format, or platform compatibility: Hermes client setup on every platform. - Evidence, artifact, provenance, or reconstruction contract: none. - Process execution, authorization, cleanup, or containment impact: none; backups and readback are unchanged. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: none. ## Evidence and regression coverage - Tests added or updated: `tests/boundary/filesystem/hermesClientConfiguration.test.ts` configures zero-byte and newline-only `config.yaml` files, checks the written YAML and reads the registration back as aligned. - Base reproduction or other evidence: source-derived. yaml 2.9.0 `Composer.end` creates a `Document` with null contents for an empty source and `parse` returns `null`; `objectSchema.parse(null)` throws before the empty-file rule. The new test's `configured` assertion fails on the base revision. - User-visible CLI/MCP output (if applicable): before, Hermes setup reports a failed configuration readback for an empty `config.yaml`; after, Hermes is configured. - Remaining proof gaps: no real Hermes client run. ## Validation performed - No local commands were run: this environment has no installed dependencies. The evidence above is source-derived; CI runs the deterministic suite. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: not applicable. - Package or release metadata impact: none. - Security, privacy, process, or containment review: none; only the classification of empty files changes. ## Review checklist - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 00:57:16 +00:00