Skip to content

fix(setup): configure an empty Hermes config.yaml - #1983

Merged
morluto merged 2 commits into
morluto:mainfrom
viniciusdsandrade:fix/setup-empty-hermes-config
Oct 12, 2026
Merged

morluto merged 2 commits into
morluto:mainfrom
viniciusdsandrade:fix/setup-empty-hermes-config

Conversation

@viniciusdsandrade

Copy link
Copy Markdown
Contributor

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.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 11, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-11T22:47:04.922762Z 96f8321 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

YAML parses an empty file to null, so Hermes configuration was checked
as an object before the shared empty-file rule and rejected. Setup then
failed its readback gate for a zero-byte config.yaml, although a missing
file is configured and the Hermes serializer already writes a fresh
document for empty original text. Apply the empty-file rule before the
Hermes YAML parse, as morluto#1117 did for JSON clients.
Configure zero-byte and newline-only config.yaml files through the
real filesystem workflow, then read the registration back as aligned.
@viniciusdsandrade
viniciusdsandrade force-pushed the fix/setup-empty-hermes-config branch from 0457428 to 96f8321 Compare October 11, 2026 22:44
@morluto
morluto merged commit 43f9c39 into morluto:main Oct 12, 2026
20 checks passed
@github-actions github-actions Bot mentioned this pull request Oct 12, 2026
3 tasks done
@morluto

morluto commented Oct 12, 2026 •

Copy link
Copy Markdown
Owner

@viniciusdsandrade, thank you for catching the Hermes empty-file case and moving the existing empty-document rule ahead of YAML parsing. That small ordering fix lets first-run setup reach the serializer while keeping the separate comment-only YAML case clearly scoped. Glad to have you contributing to REA!

JayOfTheKeyboard added a commit to JayOfTheKeyboard/rea that referenced this pull request Oct 13, 2026
comments, or only a `---` marker, also parses to a null YAML document.
Setup still rejected it as malformed ("expected record, received null")
and reported Hermes as invalid.

Treat a null Hermes document as holding no settings, as morluto#1983 does for
an empty file. The serializer already edits a comment-only document in
place. A bare `---` document holds a null scalar that takes no keys, so
replace it with a map and keep the comments written after the marker.
morluto added a commit that referenced this pull request Oct 13, 2026
* fix(setup): configure a comment-only Hermes config.yaml

comments, or only a `---` marker, also parses to a null YAML document.
Setup still rejected it as malformed ("expected record, received null")
and reported Hermes as invalid.

Treat a null Hermes document as holding no settings, as #1983 does for
an empty file. The serializer already edits a comment-only document in
place. A bare `---` document holds a null scalar that takes no keys, so
replace it with a map and keep the comments written after the marker.

* fix(setup): keep rejecting an explicit null Hermes root

Only a document with no root, or a bare --- marker whose null scalar has
no source text, holds no settings. An explicit null or ~ is a value, so
setup and uninstall reject it as before, the same as any other non-map
root.

* test(setup): split the Hermes empty-configuration tests under the function length limit

The Hermes YAML registration block reached 159 lines, past oxlint's
max-lines-per-function limit of 150. Move the empty-document cases and
the multiple-document rejection into their own block.

* fix(setup): type the Hermes edit document as a plain Document

parseDocument with options returns a Document.Parsed, whose contents
accept only parsed nodes, so assigning the new map for a bare --- root
failed typecheck (TS2322). Annotate the edited document as Document, as
the code did before it moved into HermesConfigurationYaml.ts.

* fix(ci): isolate Linux Hopper process fixture inventory

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
@morluto morluto added bug Something isn't working area: setup Setup, packaging, upgrade, install, Doctor, and client registration labels Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: setup Setup, packaging, upgrade, install, Doctor, and client registration bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants