feat(help): layered usage - one screen, help all, per-command help - #555
Conversation
- usage() is now a 43-line summary: agents, commands, common flags, examples, pointers. The 130-line wall moved to usage_full() behind `deva.sh help all` (also `--help all`) - every management command answers `<cmd> --help` / `help <cmd>` with its own usage_command() block; token order does not matter because help routing rides the same PRE_ARGS scan that sets MANAGEMENT_MODE - `all` counts only after a help token, so it stays a free word - launch-path help (deva.sh claude --help) keeps the global summary; `-- --help` passthrough to the agent is untouched; tmux keeps its own help (dispatches before the scan) - scripts/test-help-surface.sh: 24 asserts, wired into CI Close #554 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 24f4c16125
ℹ️ 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".
|
|
||
| Remove a container (picker when several match). | ||
|
|
||
| -g, --global Choose among containers from all projects |
There was a problem hiding this comment.
When the current workspace has any labeled container, deva.sh rm -g does not choose among all projects as documented here: the rm dispatch populates matching_names from the current workspace first and consults GLOBAL_MODE only when that result is empty. With one local container it can therefore remove that container immediately instead of presenting the expected global selection. Either apply the global filter before the workspace lookup or document the actual behavior.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Implements a layered deva.sh help surface so global help is a one-screen summary, help all shows the full reference, and management commands expose per-command usage (e.g., ps --help).
Changes:
- Split the previous “wall” help into a short global
usage(), a fullusage_full()(viahelp all), and per-commandusage_command(). - Updated argument scanning/routing so help tokens are handled after management-mode detection, enabling
help ps,--help ps, andps --helpto converge. - Added a CI-pinned shell test to validate help routing and wired it into the workflow.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
deva.sh |
Adds short/full/per-command help functions and defers help routing until after management-mode scan. |
scripts/test-help-surface.sh |
New regression test validating the 3-layer help behavior and passthrough invariants. |
DEV-LOGS.md |
Records the design/mechanism and verification notes for #554. |
CHANGELOG.md |
Documents the user-facing help behavior changes under Unreleased. |
.github/workflows/ci.yml |
Runs the new help-surface routing test in CI. |
Suppressed comments (1)
deva.sh:3819
- Because help handling no longer exits immediately,
--versioncan now override an earlier help token (e.g.,deva.sh --help --versionprints version and exits) which differs from the prior behavior where help won when encountered first. If--versionshould not preempt a previously-seen help request, gate the--versionearly-exit on HELP_REQUESTED.
--version)
echo "deva.sh v${VERSION}"
echo "Docker Image: $(docker_image_ref)"
exit 0
;;
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| all) | ||
| [ "$HELP_REQUESTED" = true ] && HELP_ALL=true | ||
| ;; |
Close #554
The help surface was one 130-line wall;
deva.sh ps --helpprinted the same wall; cloak VNC passwords sat next to-v. First shipment of the framework-vnext wrapper-UX track (W1).Three layers:
deva.sh --help/-h/help: 43-line summary - agents, commands, common flags, 4 examples, pointers.deva.sh help all(also--help all): the full reference, unchanged content plus a pointer footer.deva.sh <cmd> --help/help <cmd>: per-command usage for ps/status/shell/stop/rm/clean/sessions/insight/ccx.Mechanism: help tokens set HELP_REQUESTED instead of exiting the PRE_ARGS scan - the same pass already sets MANAGEMENT_MODE, so
ps --help,--help ps, andhelp psconverge for free.allcounts only after a help token, so it stays a free word otherwise.Deliberately unchanged: launch-path help (
deva.sh claude --helpshows the global summary),-- --helppassthrough to the agent (proven by dry-run assert), tmux (owns its help, dispatches before the scan),--version.Verified: scripts/test-help-surface.sh 24/24 (wired into CI Basic Tests); pi/opencode/kimi auth tests, release-utils 67/67, shellcheck severity=error all green.
Port follow-up: deva-bun mirrors the routing + fixture re-pin next (its serve.ts already carries per-command help that the old interception made unreachable).
🤖 Generated with Claude Code