morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #650] [Docs] README says `rea setup --dry-run` (status `planned`) exits 1, but it exits 0 #307

New issue

Closed

opened 2026-10-15 18:23:43 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:23:43 +00:00

Owner

Originally created by @coygeek on GitHub (Oct 6, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/650

Before submitting

I searched the existing issues for a related documentation report.
I removed credentials, tokens, private paths, and sensitive target data.

Documentation location

README.md#cli-exit-status (the paragraph below the exit-status table, README.md line 535)

Problem

The README's "CLI exit status" section states that setup returns 1 for planned, needs_confirmation, or needs_human. planned is the status rea setup --dry-run reports, and the CLI exits 0 for it, as docs/installation.md documents. The README sentence contradicts both the shipped behavior and the installation guide, so a script written from the README would expect a dry run to fail and would misread its exit status. needs_confirmation and needs_human still exit 1, so only the planned part of the sentence is wrong.

Expected content

The README and the installation guide should describe the same exit status for planned as the CLI actually returns. The installation guide says "--dry-run returns a read-only plan with status planned and exit code 0", the 4.0.0 changelog lists "Cancellation and successful dry runs now exit successfully" among its breaking changes, and the source treats planned as a non-failure for the setup command. The README should therefore not list planned among the statuses that return 1; needs_confirmation and needs_human returning 1 remain correct.

Supporting evidence

Runtime or environment

Package: rea-agents 4.0.1 from npm (the latest dist-tag; release tag rea-agents-4.0.1, commit feeb19b8b3172b2827b80fde8f09570ce5aeed88).
Source checked: main at 19f8cddfd6f283188567b8ff1e49b810d79952ee; the README sentence and the setup status mapping are the same there as in the release.
Node.js v22.23.2 on macOS 27.0.

Steps to reproduce

Use a throwaway home directory so nothing touches real client configuration (the dry run writes no client configuration, but isolation keeps the check clean).
Run a dry run and print its exit status:

REA_HOME="$(mktemp -d)"
HOME="$REA_HOME" npx -y rea-agents@4.0.1 setup --client codex --skill=false --dry-run --json > dry-run.json
echo "exit=$?"

As a control, run the same command without --dry-run or --yes, with stdin not a terminal, so setup stops for confirmation without applying anything:

HOME="$REA_HOME" npx -y rea-agents@4.0.1 setup --client codex --skill=false --json < /dev/null > apply.json
echo "exit=$?"

Compare both results with the README "CLI exit status" section.

Actual behavior

README.md line 535 (identical in the 4.0.1 release and on main) says:

`setup` returns `1` for `planned`, `needs_confirmation`, or `needs_human`
because configuration is not ready; rerun it after approval or remediation.

Observed locally with the 4.0.1 package (exit status and the relevant JSON fields; the rest of the JSON output is omitted):

# step 2: --dry-run
exit=0
"status": "planned"

# step 3: control without --dry-run or --yes, stdin not a terminal
exit=1
"status": "needs_confirmation"
"remediation": "Review the setup plan, then rerun interactively or with --yes."

The dry run reported planned and exited 0, which contradicts the README. The control reported needs_confirmation and exited 1, which matches the README. Neither run created .codex/config.toml in the throwaway home directory.

Evidence

Expected source: docs/installation.md lines 117-121 ("--dry-run returns a read-only plan with status planned and exit code 0"), github.com/morluto/rea@19f8cddfd6/docs/installation.md (L117-L121), and the 4.0.0 breaking-change entry in CHANGELOG.md line 16 ("Cancellation and successful dry runs now exit successfully"), github.com/morluto/rea@19f8cddfd6/CHANGELOG.md (L16)
Failure source: README.md line 535 lists planned among the statuses for which setup returns 1, github.com/morluto/rea@19f8cddfd6/README.md (L535-L536), contradicted by the observed exit status 0 in step 2.
Evidence provenance: observed
Local verification: reproduced
Reproduction completeness: complete

Source breadcrumbs on main: isSetupFailure in src/application/SetupTypes.ts lines 83-92 returns false for planned, cancelled, and ready, and true for needs_confirmation and needs_human; src/cli/setupCommands.ts lines 88-90 passes it to logCliCommand, which sets process.exitCode = 1 for a returned result only when the predicate returns true. In the 4.0.1 release the same predicate is in src/application/Setup.ts lines 134-152. src/cliLogging.test.ts line 57 keeps ["requested dry run", { status: "planned" }] among the outcomes that the generic isCliOperationFailure predicate must treat as successful; the setup-specific isSetupFailure test cases cover only needs_confirmation and needs_human.

History: the README sentence was added with fix(cli): return nonzero status for operation failures (#121), when planned was still a failure status. feat(setup)!: expand agent integrations and verify updates (#577), first released in rea-agents-4.0.0, removed planned from the failure statuses without updating that README sentence.

Additional context

Restoration check

Run step 2 and step 3 against a build with the documentation corrected. The README "CLI exit status" section must describe planned with the same exit status the dry run actually returns (currently 0, as in docs/installation.md), and must still document exit status 1 for needs_confirmation, which the step 3 control must still return. The README and docs/installation.md must not disagree about the planned exit status.

The translated READMEs (README_ar.md, README_ja.md, README_ko.md, README_zh.md) do not contain this sentence. I found no existing issue or pull request covering it.

Triage assessment

Impact level: P3
Assessment status: supported
Impact basis: The CLI behavior is correct and matches docs/installation.md and the 4.0.0 changelog; only one README sentence misstates the exit status for planned. A script written from the README would expect exit status 1 from a dry run and could take the wrong branch when it gets 0, but no behavior or data is affected, and no affected user has been reported.
Workaround status: available
Workaround basis: docs/installation.md documents the correct exit code, and scripts can read the status field of rea setup --json output, which was planned for the dry run and needs_confirmation for the control in the observed runs.

Originally created by @coygeek on GitHub (Oct 6, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/650 ### Before submitting - [x] I searched the existing issues for a related documentation report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Documentation location README.md#cli-exit-status (the paragraph below the exit-status table, README.md line 535) ### Problem The README's "CLI exit status" section states that `setup` returns `1` for `planned`, `needs_confirmation`, or `needs_human`. `planned` is the status `rea setup --dry-run` reports, and the CLI exits `0` for it, as `docs/installation.md` documents. The README sentence contradicts both the shipped behavior and the installation guide, so a script written from the README would expect a dry run to fail and would misread its exit status. `needs_confirmation` and `needs_human` still exit `1`, so only the `planned` part of the sentence is wrong. ### Expected content The README and the installation guide should describe the same exit status for `planned` as the CLI actually returns. The installation guide says "`--dry-run` returns a read-only plan with status `planned` and exit code 0", the 4.0.0 changelog lists "Cancellation and successful dry runs now exit successfully" among its breaking changes, and the source treats `planned` as a non-failure for the `setup` command. The README should therefore not list `planned` among the statuses that return `1`; `needs_confirmation` and `needs_human` returning `1` remain correct. ### Supporting evidence #### Runtime or environment - Package: `rea-agents` 4.0.1 from npm (the `latest` dist-tag; release tag `rea-agents-4.0.1`, commit `feeb19b8b3172b2827b80fde8f09570ce5aeed88`). - Source checked: `main` at `19f8cddfd6f283188567b8ff1e49b810d79952ee`; the README sentence and the setup status mapping are the same there as in the release. - Node.js v22.23.2 on macOS 27.0. #### Steps to reproduce 1. Use a throwaway home directory so nothing touches real client configuration (the dry run writes no client configuration, but isolation keeps the check clean). 2. Run a dry run and print its exit status: ```bash REA_HOME="$(mktemp -d)" HOME="$REA_HOME" npx -y rea-agents@4.0.1 setup --client codex --skill=false --dry-run --json > dry-run.json echo "exit=$?" ``` 3. As a control, run the same command without `--dry-run` or `--yes`, with stdin not a terminal, so setup stops for confirmation without applying anything: ```bash HOME="$REA_HOME" npx -y rea-agents@4.0.1 setup --client codex --skill=false --json < /dev/null > apply.json echo "exit=$?" ``` 4. Compare both results with the README "CLI exit status" section. #### Actual behavior README.md line 535 (identical in the 4.0.1 release and on `main`) says: ```text `setup` returns `1` for `planned`, `needs_confirmation`, or `needs_human` because configuration is not ready; rerun it after approval or remediation. ``` Observed locally with the 4.0.1 package (exit status and the relevant JSON fields; the rest of the JSON output is omitted): ```text # step 2: --dry-run exit=0 "status": "planned" # step 3: control without --dry-run or --yes, stdin not a terminal exit=1 "status": "needs_confirmation" "remediation": "Review the setup plan, then rerun interactively or with --yes." ``` The dry run reported `planned` and exited `0`, which contradicts the README. The control reported `needs_confirmation` and exited `1`, which matches the README. Neither run created `.codex/config.toml` in the throwaway home directory. #### Evidence - Expected source: `docs/installation.md` lines 117-121 ("`--dry-run` returns a read-only plan with status `planned` and exit code 0"), https://github.com/morluto/rea/blob/19f8cddfd6f283188567b8ff1e49b810d79952ee/docs/installation.md#L117-L121, and the 4.0.0 breaking-change entry in `CHANGELOG.md` line 16 ("Cancellation and successful dry runs now exit successfully"), https://github.com/morluto/rea/blob/19f8cddfd6f283188567b8ff1e49b810d79952ee/CHANGELOG.md?plain=1#L16 - Failure source: README.md line 535 lists `planned` among the statuses for which `setup` returns `1`, https://github.com/morluto/rea/blob/19f8cddfd6f283188567b8ff1e49b810d79952ee/README.md#L535-L536, contradicted by the observed exit status `0` in step 2. - Evidence provenance: observed - Local verification: reproduced - Reproduction completeness: complete Source breadcrumbs on `main`: `isSetupFailure` in `src/application/SetupTypes.ts` lines 83-92 returns `false` for `planned`, `cancelled`, and `ready`, and `true` for `needs_confirmation` and `needs_human`; `src/cli/setupCommands.ts` lines 88-90 passes it to `logCliCommand`, which sets `process.exitCode = 1` for a returned result only when the predicate returns `true`. In the 4.0.1 release the same predicate is in `src/application/Setup.ts` lines 134-152. `src/cliLogging.test.ts` line 57 keeps `["requested dry run", { status: "planned" }]` among the outcomes that the generic `isCliOperationFailure` predicate must treat as successful; the setup-specific `isSetupFailure` test cases cover only `needs_confirmation` and `needs_human`. History: the README sentence was added with `fix(cli): return nonzero status for operation failures (#121)`, when `planned` was still a failure status. `feat(setup)!: expand agent integrations and verify updates (#577)`, first released in `rea-agents-4.0.0`, removed `planned` from the failure statuses without updating that README sentence. ### Additional context #### Restoration check Run step 2 and step 3 against a build with the documentation corrected. The README "CLI exit status" section must describe `planned` with the same exit status the dry run actually returns (currently `0`, as in `docs/installation.md`), and must still document exit status `1` for `needs_confirmation`, which the step 3 control must still return. The README and `docs/installation.md` must not disagree about the `planned` exit status. The translated READMEs (`README_ar.md`, `README_ja.md`, `README_ko.md`, `README_zh.md`) do not contain this sentence. I found no existing issue or pull request covering it. #### Triage assessment - Impact level: P3 - Assessment status: supported - Impact basis: The CLI behavior is correct and matches `docs/installation.md` and the 4.0.0 changelog; only one README sentence misstates the exit status for `planned`. A script written from the README would expect exit status 1 from a dry run and could take the wrong branch when it gets 0, but no behavior or data is affected, and no affected user has been reported. - Workaround status: available - Workaround basis: `docs/installation.md` documents the correct exit code, and scripts can read the `status` field of `rea setup --json` output, which was `planned` for the dry run and `needs_confirmation` for the control in the observed runs.

bsakaguchi

2026-10-15 18:23:43 +00:00

closed this issue
added the
area: setup

documentation
labels

bsakaguchi referenced this issue

2026-10-16 21:12:43 +00:00

[PR #307] [MERGED] feat(cli): add explicit package-runner setup wizard #1943

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#307

No description provided.

Rows
Columns

[GH-ISSUE #650] [Docs] README says rea setup --dry-run (status planned) exits 1, but it exits 0 #307