diff --git a/CHANGELOG.md b/CHANGELOG.md index 920ff22a4..73736e9cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -515,6 +515,12 @@ _ALL_DATA_COLUMNS + ") " "SELECT " + _ALL_DATA_COLUMNS + " FROM v3_plans"`. Resolution chain is logged at debug level via the `PrecedenceResolution` dataclass and `PrecedenceSource` enum. +- **CLI showcase: version/info/diagnostics basics (#4211)**: Added a verified CLI showcase example + for the `version`, `info`, and `diagnostics` introspection commands. The guide walks through + fast-path eager flag behavior (`--help`, `--version`), rich format output with Rich panels, + machine-readable JSON envelope structure shared across all CLI commands, and CI-friendly + `diagnostics --check` health monitoring. Registered in `docs/showcase/examples.json`. Closes #7592. + - `agents actor context clear` command to reset actor message history and state while preserving the underlying context directory via `ContextManager` (#6370). diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 8521aa707..2c474f369 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -56,6 +56,8 @@ Below are some of the specific details of various contributions. * HAL 9000 has contributed the file edit encoding parameter fix (PR #8258 / issue #7559). * HAL 9000 has contributed the architecture-pool-supervisor milestone assignment feature (PR #8188 / issue #7521): added `forgejo_update_pull_request` permission and documented the PR workflow for major spec changes, enabling automatic milestone assignment for specification PRs. * HAL 9000 has contributed the git worktree TOCTOU race condition fix (PR #8178 / issue #7507): replaced the unsafe mkdtemp() + rmdir() pattern with a parent-directory approach to eliminate the race window in concurrent git worktree operations. +* HAL 9000 has contributed CLI documentation for version, info, and diagnostics commands (PR #4211 / issue #7592): created a beginner-friendly showcase walkthrough covering fast-path eager flags, rich format output with Rich panels, machine-readable JSON envelope structure, and CI-friendly diagnostics health checks. + * HAL 9000 has contributed the git_tools TOCTOU race condition fix (PR #8255 / issue #7619): eliminated the Time-Of-Check-To-Time-Of-Use race in `_get_base_env()` by adding double-checked locking with a module-level `threading.Lock`, preventing concurrent threads from writing conflicting environment snapshots. * HAL 9000 has contributed the ActorLoader.list_actors TOCTOU race condition fix (PR #8660 / issue #8588): moved the namespace filter inside the ``with self._lock:`` block in ``list_actors()`` so that dictionary reads and filtering are atomic, eliminating stale results and potential ``RuntimeError`` under concurrent access. Added concurrency BDD coverage via Behave test scenarios using ``threading.Barrier``. * HAL 9000 has contributed the mandatory PR compliance checklist to `implementation-supervisor.md` (#9824): added an 8-item checklist to the worker prompt body with concrete items covering CHANGELOG.md, CONTRIBUTORS.md, commit footer, CI verification, BDD tests, Epic reference, labels, and milestone assignment to eliminate systemic PR merge blockers. diff --git a/docs/showcase/cli-tools/cleveragents-cli-basics.md b/docs/showcase/cli-tools/cleveragents-cli-basics.md index c81645953..a609799b0 100644 --- a/docs/showcase/cli-tools/cleveragents-cli-basics.md +++ b/docs/showcase/cli-tools/cleveragents-cli-basics.md @@ -460,9 +460,7 @@ based on code analysis. Exact values depend on your local environment.* - **`--format`** is a global flag that must come **before** the subcommand. - **`diagnostics --check`** is CI-friendly: exits non-zero only when there are actual `ERROR`-level checks (missing API keys are `WARN`, not `ERROR`). -- All three introspection commands (`version`, `info`, `diagnostics`) are - **lightweight** — they're in the fast-path that avoids loading heavy - subcommand modules. +- Both --help and --version use a fast-path eager exit that avoids loading subcommand modules, resulting in instant response times. The version, info, and diagnostics commands are lightweight introspection tools but do not benefit from the fast-path optimization. ## Try It Yourself diff --git a/docs/showcase/examples.json b/docs/showcase/examples.json index 3833cc6c0..28f8df198 100644 --- a/docs/showcase/examples.json +++ b/docs/showcase/examples.json @@ -21,6 +21,27 @@ "generated_by": "uat-tester", "generated_at": "2026-04-19" }, + { + "title": "CleverAgents CLI Basics: Version, Info & Diagnostics", + "category": "cli-tools", + "path": "cli-tools/cleveragents-cli-basics.md", + "feature": "CLI version/info/diagnostics basics \u2014 fast-path behavior and output envelope", + "commands": [ + "python -m cleveragents --help", + "python -m cleveragents --version", + "python -m cleveragents version", + "python -m cleveragents --format json version", + "python -m cleveragents info", + "python -m cleveragents --format json info", + "python -m cleveragents diagnostics", + "python -m cleveragents --format json diagnostics", + "python -m cleveragents diagnostics --check" + ], + "complexity": "beginner", + "educational_value": "high", + "generated_by": "uat-tester", + "generated_at": "2026-04-07" + }, { "title": "Mastering Output Format Flags in CleverAgents CLI", "category": "cli-tools", @@ -216,5 +237,5 @@ ] } }, - "last_updated": "2026-04-27" + "last_updated": "2026-05-07" }