zeroae / zeroae/zae-limiter

📝 Write an ADR for noun-first CLI restructure

Open
#320 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

api-design area/cli
Dominant language
Python
Stars
0
Forks
0
Avg merge
6h 51m
Merged PRs (30d)
104

Description

Note — do not pre-claim an ADR number. This issue deliberately does not name one.
Pick the number when the file is actually written, by checking the highest number both
on main and in open PRs (PR #393 currently holds 126-132 for the multi-region set;
main is at 134 as of this note). This issue previously said ADR-122, then ADR-133 — both
were taken out from under it, because numbers get claimed in titles and branches long
before the file exists while main only knows the numbers already merged.

Description

Write an ADR documenting the decision to restructure the CLI from its current organic layout to a noun-first command hierarchy.

Current State

The CLI has grown organically with a mix of patterns:

Command Pattern Issue
deploy, delete, status Verb at top level Stack operations not grouped
cfn-template, lambda-export Compound at top level Export operations scattered
entity set-limits Noun + compound verb Inconsistent with resource set-defaults
entity list-resources Cross-noun query on entity Belongs under resource
version, upgrade, check Verb at top level Stack lifecycle not grouped
Proposed Structure (ADR Content)

The ADR must document the following decisions:

1. Top-level nouns: stack, system, resource, entity, audit, usage, local, load

2. Consistent verb set: get, list, set, delete, create, deploy (max 2 levels of nesting: noun verb)

3. Global options: --name, --region, --endpoint-url are defined on the root group and inherited by all subcommands

4. Mapping table (current -> new):

Current New Notes
deploy stack deploy
delete stack delete
status stack status / stack get
list stack list
version stack version
upgrade stack upgrade
check stack check
cfn-template stack export-template
lambda-export stack export-lambda
system set-defaults system set
system get-defaults system get
system delete-defaults system delete
resource set-defaults resource set
resource get-defaults resource get
resource delete-defaults resource delete
resource list resource list No change
entity set-limits entity set
entity get-limits entity get
entity delete-limits entity delete (config)
entity create entity create No change
entity show entity show No change
entity list entity list No change
entity list-resources resource list --with-entity-configs Cross-noun query moves to resource
audit list audit list No change
usage list usage list No change
usage summary usage summary No change
local up/down/... local up/down/... No change
load deploy/connect/... load deploy/connect/... No change

5. Entity config sub-operations decision: Whether entity set covers both entity creation and limit configuration, or limits need a sub-noun (entity config set vs entity set --resource). The ADR must decide between:

  • entity set --resource gpt-4 -l rpm:1000 (flat with --resource flag)
  • entity config set --resource gpt-4 -l rpm:1000 (3-level nesting, violates max-2 rule)
  • Keep entity set-limits as a hyphenated verb (exception to the verb set)

6. Legacy alias strategy:

  • Old commands remain as hidden aliases for 2 minor versions
  • Aliases emit deprecation warnings to stderr
  • Removed in the next major version (v2.0.0)

7. Cross-noun query resolution:

  • entity list-resources becomes resource list --with-entity-configs
  • Queries belong under the noun that represents the result type

Acceptance Criteria

  • docs/adr/<N>-noun-first-cli.md exists with Status: Proposed, where <N> is chosen at write time per the note above (highest number on main and in open PRs, +1)
  • ADR follows the format from ADR-000 (max 100 lines, required sections: Context, Decision, Consequences, Alternatives Considered)
  • Decision section contains: (a) the noun list, (b) the verb set, (c) global options list, (d) the entity config sub-operation decision, (e) legacy alias deprecation timeline, (f) cross-noun query rule
  • Alternatives Considered section addresses at least: verb-first hierarchy, flat (no grouping), and 3-level nesting
  • No code examples or implementation checklists in the ADR (per ADR-000)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading docs/adr/ADR-000 and checking the highest ADR number on main and in open PR #393 before choosing the filename. Write a Proposed ADR under docs/adr/ with the required sections, noun-first decisions, alternatives, alias timeline, and cross-noun query rule, staying under 100 lines and omitting code examples and implementation checklists.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.