morluto/rea

Fork 0

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

[GH-ISSUE #648] [Docs] README pipefail example runs the nonexistent command `rea inventory-artifact` #306

New issue

Closed

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

bsakaguchi commented

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

Owner

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

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 pipefail example at README.md lines 542-548 (line 547 on both the 4.0.1 release and main).

Problem

The README's "CLI exit status" section ends with a pipefail example that runs rea inventory-artifact ./app.asar --json. inventory-artifact is not a registered CLI command, so the example fails for every input. A reader who copies it gets COMMAND_NOT_FOUND, exit status 1, and an inventory.json that contains the error envelope instead of an inventory. The example never shows a working REA invocation. Its nonzero status comes from an unknown command, not from an REA operation failure that pipefail keeps jq from hiding. The localized READMEs do not contain this example.

Actual behavior

On the published release, step 2 prints exit=1, and inventory.json contains the CLI's command-not-found envelope:

{
  "code": "COMMAND_NOT_FOUND",
  "message": "'inventory-artifact' is not a command for 'rea'. Did you mean 'inspect-artifact'?",
  "cta": {
    "description": "Suggested commands:",
    "commands": [
      {
        "command": "rea inspect-artifact ./app.asar --json"
      },
      {
        "command": "rea --help",
        "description": "see all available commands"
      }
    ]
  }
}

In the step 4 control, inspect-artifact ./app.asar --json piped through jq exited 0 and wrote an evidence record with "operation": "inspect_artifact". Its nested evidence includes an inventory_artifact operation. The same inspect-artifact pipeline on the nonexistent ./missing.asar exited 1 with "code": "target_unavailable", so a registered command lets pipefail surface a real operation failure.

In source, src/cliCommandNames.ts defines 69 primary command names in CLI_COMMANDS and one alias, compare-bundles, in CLI_COMMAND_ALIASES. Neither list contains inventory-artifact. inventory_artifact is an internal artifact-provider operation (see src/artifacts/ArtifactProvider.ts) that inspect-artifact runs as its inventory substep, not a CLI command.

Expected content

The README is the user-facing guide for the CLI, and every command it shows should be one the CLI accepts. The example follows the sentence "When REA feeds a shell pipeline, enable pipefail so a downstream formatter cannot hide its failure". Copied unchanged with a valid input, it should run a real REA command: the pipeline exits 0 when the operation succeeds and 1 when the REA operation fails, with pipefail keeping jq from hiding that failure.

Restoration check

Copy the command from the README's pipefail example, give it a valid input for the documented command (the step 1 ASAR if the example still targets one), and run it unchanged. Currently it fails with COMMAND_NOT_FOUND and exit 1. After a fix, the CLI should accept the command and the pipeline should exit 0 with the command's JSON result in the output file. Running the same pipeline on a nonexistent path should still exit 1, which confirms the example still demonstrates pipefail. The maintainers can pick the replacement command. The CLI's own suggestion, inspect-artifact, passed both step 4 controls. If the example is removed instead, the README should show no unregistered command.

Supporting evidence

Runtime or environment

rea-agents 4.0.1 from npm (latest published release, tag rea-agents-4.0.1, commit feeb19b8b3), run with npx -y rea-agents@4.0.1.
Default branch main at commit 19f8cddfd6, inspected as source only; the README example and the CLI command inventory are identical to the release.
Node.js v22.23.2, npm 12.0.2, jq 1.8.2, macOS 27.0 (26A428) on arm64.
ASAR fixture packed with @electron/asar v4.3.1.

Steps to reproduce

Run these steps on the published release named under Runtime or environment, in an empty directory with HOME and the npm cache pointed at a temporary directory:

Create a tiny ASAR fixture: put package.json containing {"name":"demo","main":"index.js"} and index.js containing console.log(1) in a directory src/, then run npx -y @electron/asar pack src app.asar.
Run the README example as written: bash -c 'set -o pipefail; npx -y rea-agents@4.0.1 inventory-artifact ./app.asar --json | jq . > inventory.json; echo "exit=$?"'.
Inspect inventory.json.
Control: run the same pipeline with the registered command inspect-artifact in place of inventory-artifact, once on ./app.asar and once on a nonexistent ./missing.asar.

Evidence

Expected source: README.md lines 542-548 (the pipefail paragraph and example in the "CLI exit status" section) at the release commit: github.com/morluto/rea@feeb19b8b3/README.md (L542-L548)
Failure source: Local run of the published package's CLI (steps 2-3), which returned COMMAND_NOT_FOUND with exit status 1. The registered command inventory at the release commit is at github.com/morluto/rea@feeb19b8b3/src/cliCommandNames.ts (L1-L78)
Evidence provenance: observed
Local verification: reproduced
Reproduction completeness: complete

On main, the example is unchanged at README.md line 547, and src/cliCommandNames.ts still has no such command. I did not run a main build.

Additional context

Triage assessment

Impact level: P3
Assessment status: supported
Impact basis: The defect affects one copy-paste example in the README. Following it fails right away with a clear COMMAND_NOT_FOUND message and exit status 1, and it loses no data and blocks no product workflow. The only side effect is an inventory.json that holds the error envelope.
Workaround status: available
Workaround basis: The CLI's error output names rea inspect-artifact, and in the step 4 control that command ran successfully on the same ASAR fixture and pipeline with exit status 0.

Originally created by @coygeek on GitHub (Oct 6, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/648 ### 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](https://github.com/morluto/rea#cli-exit-status), the `pipefail` example at `README.md` lines 542-548 (line 547 on both the 4.0.1 release and `main`). ### Problem The README's "CLI exit status" section ends with a `pipefail` example that runs `rea inventory-artifact ./app.asar --json`. `inventory-artifact` is not a registered CLI command, so the example fails for every input. A reader who copies it gets `COMMAND_NOT_FOUND`, exit status 1, and an `inventory.json` that contains the error envelope instead of an inventory. The example never shows a working REA invocation. Its nonzero status comes from an unknown command, not from an REA operation failure that `pipefail` keeps `jq` from hiding. The localized READMEs do not contain this example. #### Actual behavior On the published release, step 2 prints `exit=1`, and `inventory.json` contains the CLI's command-not-found envelope: ```json { "code": "COMMAND_NOT_FOUND", "message": "'inventory-artifact' is not a command for 'rea'. Did you mean 'inspect-artifact'?", "cta": { "description": "Suggested commands:", "commands": [ { "command": "rea inspect-artifact ./app.asar --json" }, { "command": "rea --help", "description": "see all available commands" } ] } } ``` In the step 4 control, `inspect-artifact ./app.asar --json` piped through `jq` exited 0 and wrote an evidence record with `"operation": "inspect_artifact"`. Its nested evidence includes an `inventory_artifact` operation. The same `inspect-artifact` pipeline on the nonexistent `./missing.asar` exited 1 with `"code": "target_unavailable"`, so a registered command lets `pipefail` surface a real operation failure. In source, `src/cliCommandNames.ts` defines 69 primary command names in `CLI_COMMANDS` and one alias, `compare-bundles`, in `CLI_COMMAND_ALIASES`. Neither list contains `inventory-artifact`. `inventory_artifact` is an internal artifact-provider operation (see `src/artifacts/ArtifactProvider.ts`) that `inspect-artifact` runs as its inventory substep, not a CLI command. ### Expected content The README is the user-facing guide for the CLI, and every command it shows should be one the CLI accepts. The example follows the sentence "When REA feeds a shell pipeline, enable `pipefail` so a downstream formatter cannot hide its failure". Copied unchanged with a valid input, it should run a real REA command: the pipeline exits 0 when the operation succeeds and 1 when the REA operation fails, with `pipefail` keeping `jq` from hiding that failure. #### Restoration check Copy the command from the README's `pipefail` example, give it a valid input for the documented command (the step 1 ASAR if the example still targets one), and run it unchanged. Currently it fails with `COMMAND_NOT_FOUND` and exit 1. After a fix, the CLI should accept the command and the pipeline should exit 0 with the command's JSON result in the output file. Running the same pipeline on a nonexistent path should still exit 1, which confirms the example still demonstrates `pipefail`. The maintainers can pick the replacement command. The CLI's own suggestion, `inspect-artifact`, passed both step 4 controls. If the example is removed instead, the README should show no unregistered command. ### Supporting evidence #### Runtime or environment - `rea-agents` 4.0.1 from npm (latest published release, tag `rea-agents-4.0.1`, commit feeb19b8b3172b2827b80fde8f09570ce5aeed88), run with `npx -y rea-agents@4.0.1`. - Default branch `main` at commit 19f8cddfd6f283188567b8ff1e49b810d79952ee, inspected as source only; the README example and the CLI command inventory are identical to the release. - Node.js v22.23.2, npm 12.0.2, jq 1.8.2, macOS 27.0 (26A428) on arm64. - ASAR fixture packed with `@electron/asar` v4.3.1. #### Steps to reproduce Run these steps on the published release named under Runtime or environment, in an empty directory with `HOME` and the npm cache pointed at a temporary directory: 1. Create a tiny ASAR fixture: put `package.json` containing `{"name":"demo","main":"index.js"}` and `index.js` containing `console.log(1)` in a directory `src/`, then run `npx -y @electron/asar pack src app.asar`. 2. Run the README example as written: `bash -c 'set -o pipefail; npx -y rea-agents@4.0.1 inventory-artifact ./app.asar --json | jq . > inventory.json; echo "exit=$?"'`. 3. Inspect `inventory.json`. 4. Control: run the same pipeline with the registered command `inspect-artifact` in place of `inventory-artifact`, once on `./app.asar` and once on a nonexistent `./missing.asar`. #### Evidence - Expected source: `README.md` lines 542-548 (the `pipefail` paragraph and example in the "CLI exit status" section) at the release commit: https://github.com/morluto/rea/blob/feeb19b8b3172b2827b80fde8f09570ce5aeed88/README.md#L542-L548 - Failure source: Local run of the published package's CLI (steps 2-3), which returned `COMMAND_NOT_FOUND` with exit status 1. The registered command inventory at the release commit is at https://github.com/morluto/rea/blob/feeb19b8b3172b2827b80fde8f09570ce5aeed88/src/cliCommandNames.ts#L1-L78 - Evidence provenance: observed - Local verification: reproduced - Reproduction completeness: complete On `main`, the example is unchanged at `README.md` line 547, and `src/cliCommandNames.ts` still has no such command. I did not run a `main` build. ### Additional context #### Triage assessment - Impact level: P3 - Assessment status: supported - Impact basis: The defect affects one copy-paste example in the README. Following it fails right away with a clear `COMMAND_NOT_FOUND` message and exit status 1, and it loses no data and blocks no product workflow. The only side effect is an `inventory.json` that holds the error envelope. - Workaround status: available - Workaround basis: The CLI's error output names `rea inspect-artifact`, and in the step 4 control that command ran successfully on the same ASAR fixture and pipeline with exit status 0.

bsakaguchi

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

closed this issue
added the
area: cli

documentation
labels

bsakaguchi referenced this issue

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

[PR #306] [MERGED] feat(cli): improve setup onboarding #1942

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#306

No description provided.

Rows
Columns

[GH-ISSUE #648] [Docs] README pipefail example runs the nonexistent command rea inventory-artifact #306