Skip to content

docs: add an "add a command" checklist to AGENTS.md#1057

Open
joshrotenberg wants to merge 1 commit into
mainfrom
docs/1049-add-a-command-checklist
Open

docs: add an "add a command" checklist to AGENTS.md#1057
joshrotenberg wants to merge 1 commit into
mainfrom
docs/1049-add-a-command-checklist

Conversation

@joshrotenberg

Copy link
Copy Markdown
Collaborator

Part of #1049 (Phase 3, CODE-09). Docs-only; no code touched.

Problem

The enterprise command groups share one dispatch shape, but it is only discoverable by reading an existing module and inferring the convention. #1049 Phase 3 calls for writing it down.

Change

A new ## Adding a Command section in AGENTS.md, between the module-organization notes and the conventions section. It covers:

  • The three-way split: clap enum, dispatch module (commands/enterprise/<name>.rs), implementation module (commands/enterprise/<name>_impl.rs).
  • A checklist: declare the enum, add the EnterpriseCommands variant, write the dispatch function, write the handlers, register both modules in mod.rs, wire the match arm in main.rs, run fmt/clippy/test.
  • The dispatch signature verbatim:
pub async fn handle_<name>_command(
    conn_mgr: &ConnectionManager,
    profile_name: Option<&str>,
    command: &<Name>Commands,
    output_format: OutputFormat,
    query: Option<&str>,
) -> CliResult<()>
  • A handler-body sketch showing conn_mgr.create_enterprise_client(profile_name), handle_output, resolve_auto and print_formatted_output, and where those helpers come from (super::utils::*, re-exporting crate::output).

Placement conventions

Enum placement genuinely varies in the tree and both forms are current, so the checklist records both rather than declaring one wrong:

  • cli/enterprise.rs as Enterprise<Name>Commands for database, cluster, node, crdb
  • commands/enterprise/<name>.rs as <Name>Commands for logs, module

It suggests cli/enterprise.rs for flag-heavy groups, and notes two pre-existing variations that are not worth churning: logs keeps its dispatch function in logs_impl.rs, and some older main.rs call sites pass the command enum by value.

Checks

markdownlint AGENTS.md --disable MD013 MD033 MD041 (the flags CI uses) reports no errors in the new section. The pre-existing errors elsewhere in the file are unchanged, and that job is continue-on-error in docs.yml regardless. No Rust changed.

Relationship to #1056

Independent. #1056 converts alerts/license/license_workflow to this pattern; this PR documents the pattern. Either can land first. Together they close #1049 Phase 3.

Part of #1049 (Phase 3, CODE-09). The enterprise command groups share one
dispatch shape, but it was only discoverable by reading the existing
modules. Document it: where the clap enum goes, the handle_x_command free
function signature taking &ConnectionManager, the handler bodies in a
sibling *_impl.rs, and the mod.rs and main.rs wiring.

Records the two placement conventions in the tree (cli/enterprise.rs for
database/cluster/node/crdb, commands/enterprise/<name>.rs for logs/module)
rather than picking one, and notes the logs dispatch-in-_impl and
clone-at-call-site variations as pre-existing.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

De-complexification: slice dead features and consolidate patterns

1 participant