Update rshell help command output by AlexandreYang · Pull Request #213 · DataDog/rshell

AlexandreYang · 2026-05-03T19:13:25Z

Summary

Add rshell feature topics to the in-shell help command
Show concise unsupported-feature summary in top-level help output
Use command terminology in help output and add scenario/unit coverage

Example output

`help` (all commands allowed)

rshell (dev) — All 28 commands available

Features:
commands            Registered commands run inside the interpreter; no unregistered commands without an external handler.
variables           Assignments, expansion, inline env, command substitution; no arrays/arithmetic/advanced params.
control-flow        for/if/&&/||/!/groups/subshells; no while/case/select/functions.
pipes-redirections  Pipes, stdin/heredocs, /dev/null redirects, fd dup; no arbitrary file writes.
quoting-expansion   Quotes, globbing, continuations, comments; no extglob/tilde/process substitution.
execution           AllowedCommands, AllowedPaths, timeouts, ProcPath; no background jobs/coprocs/time.
environment         Empty by default, caller Env, IFS/ALLOWED_PATHS; no host env inheritance/export.
bash-divergences    Intentional bash differences captured here. Currently: one shared time reference per Run().

Not supported:
  - Expansions: arithmetic $((...)), arrays, advanced ${...} operations, tilde expansion, process substitution, extended globbing.
  - Control flow: while/until, case, select, C-style for ((...)), and shell functions.
  - Execution: external commands by default, background jobs, coprocesses, time, [[...]], ((...)), declare/export/local/readonly/let.
  - I/O and environment: arbitrary output file redirects, |&, herestrings, read-write redirects, input fd duplication, host env inheritance.

Commands:
[         evaluate conditional expression
break     exit from a loop
cat       concatenate and print files
continue  continue a loop iteration
cut       remove sections from each line
echo      write arguments to stdout
exit      exit the shell
false     return unsuccessful exit status
find      search for files in a directory hierarchy
grep      print lines that match patterns
head      output the first part of files
help      display help for features and commands
ip        show network interface and routing information
ls        list directory contents
ping      send ICMP echo requests to a network host
printf    format and print data
ps        report process status
sed       stream editor for filtering and transforming text
sort      sort lines of text files
ss        display socket statistics
strings   print printable character sequences
tail      output the last part of files
test      evaluate conditional expression
tr        translate or delete characters
true      return successful exit status
uname     print system information
uniq      report or omit repeated lines
wc        print newline, word, and byte counts

Run 'help <feature|command>' for more information on a specific topic.

`help variables` (feature topic with Supported + Not supported)

variables - Assignments, expansion, inline env, command substitution; no arrays/arithmetic/advanced params.

Supported:
  - VAR=value assignment and expansion with $VAR or ${VAR}.
  - Inline assignment with VAR=value command, scoped to that command.
  - $? expands to the previous command's exit code.
  - Command substitution with $(cmd), legacy backquotes, and $(<file) when cat is allowed; output is capped at 1 MiB.

Not supported:
  - Arithmetic expansion: $(( expr )).
  - Arrays and array assignments.
  - Append assignment with VAR+=value.
  - Advanced parameter expansion operations such as ${#var}, defaults, slicing, pattern replacement, indirect expansion, and case conversion.
  - Positional parameters ($1, $@, $#, $0) and special variables such as $! and $LINENO.

`help bash-divergences` (feature topic with only Notes)

bash-divergences - Intentional bash differences captured here. Currently: one shared time reference per Run().

Notes:
  - rshell captures time.Now() once at the start of each Run() call and shares it across commands that need a reference time, such as find -mmin/-mtime and ls -l.
  - Bash evaluates each command against its own invocation time. The difference matters only for long-running scripts where time-sensitive predicates are evaluated much later than Run() started.

Restricted policy (`AllowedCommands=[rshell:echo, rshell:help]`)

When the policy restricts commands, the Commands: table only lists what's enabled and the rest collapses into a compact Disabled commands: line:

rshell (dev) — 2 of 28 commands enabled

Features: ... (same as above)

Not supported: ... (same as above)

Commands:
echo  write arguments to stdout
help  display help for features and commands

Disabled commands: [, break, cat, continue, cut, exit, false, find, grep, head, ip, ls, ping,
  printf, ps, sed, sort, ss, strings, tail, test, tr, true, uname, uniq, wc

Run 'help <feature|command>' for more information on a specific topic.

Tests

make fmt
go test ./...
TMPDIR=$PWD/tmp/bash-comparison-tmp RSHELL_BASH_TEST=1 go test ./tests/ -run TestShellScenariosAgainstBash -timeout 120s

AlexandreYang · 2026-05-04T08:37:32Z

@codex review this PR

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: eeacd0e55a

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

AlexandreYang

Self-review summary

Adds a feature-topic dimension to help (in addition to commands) and re-labels output from "builtins" to "commands". Code is small, contained to the help builtin and a new builtins/features.go registry, with no filesystem or external command access introduced. Sandbox integrity is unaffected — features and unsupported summaries are read-only static data, and the only new code path (builtins.Feature(name)) is a map lookup, so no path traversal, injection, or DoS vector.

Overall assessment: safe to merge after the P3 nits below. Only minor robustness/coverage suggestions.

Findings

#	File	Finding
1	`builtins/features.go:165-169`	`Features()` is a shallow copy — inner slices share backing arrays with the registry
2	`builtins/features.go:131-138`	No coverage / vague description for a Notes-only feature (`bash-divergences`)
3	`builtins/features.go:24`	`commands` feature description format diverges from the consistent "…; no …" pattern used by other features
4	`builtins/help/help.go:64-69`	`--all` is silently ignored when a topic is given (e.g. `help --all variables`)
5	`builtins/builtins.go:254-256`	Feature-collision check inside `addToRegistry` is unreachable today (the check at `Register()` line 68 fires first)

Test coverage

Code path	Scenario test	Go test	Status
`help` (no args, all allowed)	unrestricted.yaml	TestHelpListsFeaturesAndUnsupportedSummary	Covered
`help` (restricted)	restricted.yaml	TestHelpRestrictedShowsOnlyAllowedInTable	Covered
`help --all`	restricted_all_flag.yaml / unrestricted_all_flag.yaml	TestHelpAllFlag*	Covered
`help --help`	help_flag.yaml	TestHelpFlagPrintsUsage	Covered
`help <feature>` w/ Supported+Unsupported	feature_detail.yaml	TestHelpShowsFeatureHelp	Covered
`help <feature>` Notes-only (bash-divergences)	—	—	Missing
`help unsupported` (label not topic)	unsupported_not_topic.yaml	TestUnsupportedIsSummaryNotTopic	Covered
`help <unknown>`	too_many_args.yaml	TestHelpUnknownTopicShowsError	Covered
Builtin-vs-feature name collision panic	—	TestCommandRegisterPanicsOnFeatureName	Covered

Overall: Adequate, with one small gap (Notes-only feature display).

Positive observations

Sandbox stays clean: no new filesystem access, no os package functions introduced, no use of os/exec, unsafe, or net/http.
The feature/builtin name collision is detected at registration time via panic, which fails loud at startup rather than at runtime. The init-time featureByName map and the sync.Once-guarded registerBuiltins() make ordering safe.
Documentation (README.md, SHELL_FEATURES.md) is kept in sync with the new behaviour, and the help builtin's Description field is updated, satisfying the project rule about builtin metadata.
New scenario tests use skip_assert_against_bash: true correctly (help is rshell-specific).
printBulletSection correctly skips empty sections, so bash-divergences (Notes-only) renders without orphan headers.

AlexandreYang · 2026-05-04T08:44:53Z

Iteration 1 — self-review: 5 findings, all P3 (no P0/P1/P2). No sandbox/security or correctness issues. Findings: shallow copy in Features(), missing test for Notes-only feature (bash-divergences), inconsistent description for commands feature, --all silently ignored when topic given, redundant collision check in addToRegistry. See review.

- builtins/features.go: deep-copy returned FeatureMeta slices so callers cannot mutate the registry. Reword `commands` description to follow the consistent "...; no ..." pattern. Reword `bash-divergences` description to drop "including" since only one divergence is captured here. - builtins/help/help.go: document in the --all flag help text that --all is ignored when a topic argument is given. - builtins/builtins.go: add comment explaining the redundant feature-collision check in addToRegistry is defense-in-depth. - tests/scenarios/cmd/help: update existing scenarios to match the new feature descriptions and add feature_notes_only.yaml covering the Notes-only feature display path (help bash-divergences).

AlexandreYang · 2026-05-04T09:01:19Z

@codex review this PR

AlexandreYang

Self-review summary (iteration 2)

Iteration 1 fixed all 5 P3 nits flagged previously. PR is in good shape — all CI green, all prior threads resolved. One small consistency finding remains:

Findings

#	Priority	File	Finding
1		`builtins/features.go:181-185`	`Feature(name)` still returns a FeatureMeta with shared inner slices — `Features()` was deep-copied in iter 1 but the single-getter wasn't

Test coverage

feature_notes_only.yaml was added in iter 1 covering the previously-uncovered Notes-only feature display path. Coverage now adequate.

Positive observations

Iter 1 fixes are consistent with the original review feedback; no regressions introduced.
make fmt, go build, full test suite, and bash comparison all pass locally; CI green for the new commit.
Defense-in-depth comment in addToRegistry clearly explains the redundancy.

AlexandreYang · 2026-05-04T09:03:55Z

Iteration 2 — self-review: 1 finding (P3). Inconsistency: Feature(name) still returns shared inner slices, while Features() was deep-copied in iter 1. See review.

chatgpt-codex-connector · 2026-05-04T09:04:47Z

Codex Review: Didn't find any major issues. You're on a roll.

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Iter 1 deep-copied Features() so callers cannot mutate the registry. Apply the same treatment to the single-feature getter — featureByName returns the registry's FeatureMeta value whose Supported/Unsupported/Notes slices share backing arrays with featureRegistry.

AlexandreYang · 2026-05-04T09:06:01Z

@codex review this PR

AlexandreYang

Self-review summary (iteration 3)

Iter 1 fixed the original 5 P3 nits. Iter 2 fixed the Feature(name) shared-slice consistency issue. The PR now reads cleanly — all sandbox/security invariants preserved, no filesystem access, no new external-command handling, all CI green.

Findings

No new findings from this self-review.

Note: outstanding Codex comment

A pre-existing Codex review comment (builtins/features.go:32) was not picked up by the loop's filter (the GitHub login is chatgpt-codex-connector without the [bot] suffix the filter uses). It points at the commands feature's "Command options that would … execute programs … are rejected." line — find -exec / -execdir are supported under AllowedCommands, so the wording is misleading. I'll address it in the next sub-step.

AlexandreYang · 2026-05-04T09:09:38Z

Iteration 3 — self-review: 0 new findings. Will address the pre-existing Codex comment on builtins/features.go:32 in this iteration's fix step. See review.

Codex flagged that "Command options that would ... execute programs ... are rejected." is misleading because find -exec / -execdir are supported predicates gated by AllowedCommands. Reword to keep the write-files / sandbox-bypass restriction but explicitly note that external program execution is allowed when the policy permits it.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cb81ec7def

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Codex flagged that the project rule "Set exit code 0 and return. Help is not an error." (docs/RULES.md, Help Flag) was being violated — help --help printed usage but returned exit 1. Make it return 0 and update the package doc comment, scenario test, and Go test to match. Too-many-args still exits 1 (real misuse).

AlexandreYang · 2026-05-04T09:13:14Z

@codex review this PR

AlexandreYang

Self-review summary (iteration 4)

All previously flagged findings (5 P3 from iter 1, 1 P3 from iter 2, 1 P3 + 1 P2 from Codex in iter 3) are addressed and resolved. The PR is fully clean — sandbox-safe, bash-compatible (where applicable), well-tested, well-documented.

Findings

No new findings.

Iteration recap

Iter	New findings	Fixed
1	5 P3 (self)	5
2	1 P3 (self)	1
3	1 P3 + 1 P2 (Codex)	2
4	0	—

AlexandreYang · 2026-05-04T09:13:29Z

Iteration 4 — self-review: 0 findings. PR fully clean across all dimensions.

AlexandreYang · 2026-05-04T09:14:25Z

@codex review this PR

AlexandreYang

Self-review summary (iteration 5)

PR remains fully clean. No new findings; no fixes applied. This is the fifth and final consecutive clean iteration.

AlexandreYang · 2026-05-04T09:14:29Z

Iteration 5 — self-review: 0 findings. Final clean iteration.

AlexandreYang · 2026-05-04T09:15:03Z

Review-Fix Loop Summary

PR: Update rshell help command output #213 (Update rshell help command output #213)
Iterations completed: 5
Final status: CLEAN

Iteration log

#	Unresolved threads	Fixes applied	CI status
1	5	5 fixed	Passing
2	1	1 fixed	Passing
3	2	2 fixed	Passing
4	0	—	Passing
5	0	—	Passing

Final state

Unresolved threads: 0
CI: Passing (all GitHub Actions checks SUCCESS; devflow/mergegate IN_PROGRESS, non-blocking)

Fixes applied across iterations

Iter 1 (commit 505457e):

Deep-copy Features() to prevent registry mutation
Reword commands and bash-divergences feature descriptions
Document --all ignored when topic given
Add defense-in-depth comment to addToRegistry
Add feature_notes_only.yaml scenario covering Notes-only feature display

Iter 2 (commit cb81ec7):

Deep-copy Feature(name) for consistency with Features()

Iter 3 (commits 36e6fd4, bd0f1f9):

Reword commands unsupported text re: find -exec (Codex P3)
help --help now returns exit 0 per docs/RULES.md (Codex P2)

Remaining issues

None.

AlexandreYang · 2026-05-04T09:16:46Z

@codex review this PR

AlexandreYang

Iteration 1 self-review: no new findings; PR is clean.

AlexandreYang · 2026-05-04T09:16:48Z

Iteration 1 (run 2) — self-review: 0 findings. PR clean.

AlexandreYang · 2026-05-04T09:17:01Z

@codex review this PR

AlexandreYang

Iteration 2 self-review: no new findings; PR is clean.

AlexandreYang · 2026-05-04T09:17:04Z

Iteration 2 (run 2) — self-review: 0 findings. PR clean.

AlexandreYang · 2026-05-04T09:17:14Z

@codex review this PR

AlexandreYang

Iteration 3 self-review: no new findings; PR is clean.

AlexandreYang · 2026-05-04T09:17:16Z

Iteration 3 (run 2) — self-review: 0 findings. PR clean.

AlexandreYang · 2026-05-04T09:17:26Z

@codex review this PR

AlexandreYang

Iteration 4 self-review: no new findings; PR is clean.

AlexandreYang · 2026-05-04T09:17:28Z

Iteration 4 (run 2) — self-review: 0 findings. PR clean.

AlexandreYang · 2026-05-04T09:17:38Z

@codex review this PR

AlexandreYang

Iteration 5 self-review: no new findings; PR is clean.

AlexandreYang · 2026-05-04T09:17:40Z

Iteration 5 (run 2) — self-review: 0 findings. PR clean. Final iteration.

AlexandreYang · 2026-05-04T09:17:54Z

Review-Fix Loop Summary (run 2)

PR: Update rshell help command output #213 (Update rshell help command output #213)
Iterations completed: 5
Final status: CLEAN

Iteration log

#	Fixes applied	CI status
1	—	Passing
2	—	Passing
3	—	Passing
4	—	Passing
5	—	Passing

Final state

Unresolved threads: 0
CI: Passing (all GitHub Actions checks SUCCESS)

Remaining issues

None.

(All actionable findings were addressed in the previous loop run; this run confirms the PR remains clean across 5 consecutive iterations.)

chatgpt-codex-connector · 2026-05-04T09:21:28Z

Codex Review: Didn't find any major issues. 🚀

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Update help with rshell feature topics

eeacd0e

chatgpt-codex-connector Bot reviewed May 4, 2026

View reviewed changes

Comment thread builtins/features.go Outdated

AlexandreYang commented May 4, 2026

View reviewed changes

Comment thread builtins/features.go

Comment thread builtins/features.go

Comment thread builtins/features.go Outdated

Comment thread builtins/help/help.go

Comment thread builtins/builtins.go

AlexandreYang commented May 4, 2026

View reviewed changes

Comment thread builtins/features.go Outdated

AlexandreYang commented May 4, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed May 4, 2026

View reviewed changes

Comment thread builtins/help/help.go Outdated

AlexandreYang commented May 4, 2026

View reviewed changes

AlexandreYang marked this pull request as ready for review May 4, 2026 09:29

AlexandreYang requested review from astuyve, julesmcrt, matt-dz, thieman and val06 as code owners May 4, 2026 09:29

Conversation

AlexandreYang commented May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Example output

help (all commands allowed)

help variables (feature topic with Supported + Not supported)

help bash-divergences (feature topic with only Notes)

Restricted policy (AllowedCommands=[rshell:echo, rshell:help])

Tests

Uh oh!

AlexandreYang commented May 4, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

AlexandreYang left a comment

Choose a reason for hiding this comment

Self-review summary

Findings

Test coverage

Positive observations

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AlexandreYang commented May 4, 2026

Uh oh!

AlexandreYang commented May 4, 2026

Uh oh!

AlexandreYang left a comment

Choose a reason for hiding this comment

Self-review summary (iteration 2)

Findings

Test coverage

Positive observations

Uh oh!

Uh oh!

AlexandreYang commented May 4, 2026

Uh oh!

chatgpt-codex-connector Bot commented May 4, 2026

Uh oh!

AlexandreYang commented May 4, 2026

Uh oh!

AlexandreYang left a comment

Choose a reason for hiding this comment

Self-review summary (iteration 3)

Findings

Note: outstanding Codex comment

Uh oh!

AlexandreYang commented May 4, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

AlexandreYang commented May 4, 2026

Uh oh!

AlexandreYang left a comment

Choose a reason for hiding this comment

Self-review summary (iteration 4)

Findings

Iteration recap

Uh oh!

AlexandreYang commented May 4, 2026

Uh oh!

AlexandreYang commented May 4, 2026

Uh oh!

AlexandreYang left a comment

Choose a reason for hiding this comment

Self-review summary (iteration 5)

Uh oh!

AlexandreYang commented May 4, 2026

Uh oh!

AlexandreYang commented May 4, 2026

AlexandreYang commented May 3, 2026 •

edited

Loading

`help` (all commands allowed)

`help variables` (feature topic with Supported + Not supported)

`help bash-divergences` (feature topic with only Notes)

Restricted policy (`AllowedCommands=[rshell:echo, rshell:help]`)