feat(structure): enforce 1000-line module cap and split oversized files

[jpage-godaddy]

Summary

• Port the sibling cli repo's module-size convention: cli-engine/scripts/check-module-size.sh enforces a 1000-line ceiling on every hand-written .rs file, wired into CI (.github/workflows/ci.yml).
• Update AGENTS.md with a "Code File Structure" section: the 1000-line file cap, a ~35-line function guideline, and a comment-quality rule (write for a future reader with no session context).
• Split every file the new check flagged into a directory module grouped by concern, with no behavior changes: cli.rs, output/human.rs, auth/pkce.rs, command.rs, transport/client.rs, middleware.rs, flags.rs.
• Where a type's combined methods would exceed 1000 lines as a single impl block (required by this crate's multiple_inherent_impl = "deny" lint), the largest methods were converted to free functions with thin delegating wrappers (Cli in particular); smaller single-impl-block types just had their whole impl block relocated intact.

Test plan

• cargo fmt --all --check
• cargo check --all-targets (default and --features pkce-auth)
• cargo clippy --all-targets -- -D warnings (both feature sets) — confirmed exactly one impl Cli block exists crate-wide
• cargo test --all-targets (both feature sets) — 0 failures
• cargo test --doc (both feature sets)
• RUSTDOCFLAGS='-D warnings' cargo doc --no-deps (both feature sets)
• cargo rustdoc --lib -- -W missing-docs — 0 warnings
• ./cli-engine/scripts/check-module-size.sh — zero violations

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The raw-arg flag introspection currently misclassifies optional-value flags (notably --debug/--verbose) as non-consuming, which can break command-path/version detection, and there’s also a concrete table-alignment bug risk from Unicode-length-changing uppercasing.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR ports a module-size convention into cli-engine by enforcing a 1000-line cap for hand-written Rust modules (via a new script wired into CI) and refactors previously oversized files into directory modules grouped by concern, aiming to preserve behavior while improving maintainability.

Changes:

• Add a CI-enforced 1000-line limit for .rs files (cli-engine/scripts/check-module-size.sh) and document the convention in AGENTS.md.
• Split large modules into submodules (notably transport client, middleware, flags, command, cli, human output, and PKCE auth helpers).
• Minor doc/comment improvements and internal refactors to keep lints/structure consistent after the splits.

File summaries

File	Description
cli-engine/src/transport/client/mod.rs	New transport::client module root with shared constants, default UA/logger globals, and error helpers after split.
cli-engine/src/transport/client/methods.rs	Transport client method implementations updated to import shared items from client::mod.
cli-engine/src/prompt.rs	Adds rustdoc detail to RecoveryResult variants.
cli-engine/src/output/human/mod.rs	New human output module root defining registry/view types and human rendering entry points.
cli-engine/src/output/human/body.rs	Extracted human “data body” rendering (tables/property bags, nested rendering).
cli-engine/src/output/human/columns.rs	Extracted terminal width + column fitting utilities for human tables.
cli-engine/src/output/human/footer.rs	Extracted human footer rendering (next actions, pagination summary, truncation notes).
cli-engine/src/output/human/value_format.rs	Extracted value formatting, truncation, indentation, and dotted-path resolution helpers.
cli-engine/src/middleware/mod.rs	Middleware module trimmed; core execution moved into middleware/run.rs.
cli-engine/src/middleware/run.rs	New module containing Middleware::run and related execution/rendering helpers after split.
cli-engine/src/lib.rs	Adjusts module doc comments/order (prompt/search) after refactors.
cli-engine/src/flags/mod.rs	New flags module root consolidating submodules and re-exports; defines interactivity + global flag ordering.
cli-engine/src/flags/register.rs	Extracted clap flag registration helpers (global flags, reason flag, pagination args, parsers).
cli-engine/src/flags/resolve.rs	Extracted raw-arg helpers and global flag extraction/default resolution helpers.
cli-engine/src/flags/introspect.rs	Extracted clap tree introspection utilities (derive flag sets, debug component matcher).
cli-engine/src/command/mod.rs	New command module root with core runtime types (context, results, streaming sender) and submodules.
cli-engine/src/command/runtime.rs	Extracted RuntimeCommandSpec constructors and handler wiring.
cli-engine/src/command/matches.rs	Extracted clap-match parsing helpers for command paths and argument-to-JSON mapping.
cli-engine/src/command/group.rs	Extracted group specs/runtime group types and clap command construction.
cli-engine/src/cli/render.rs	Extracted rendering helpers for built-in commands/help/discovery/schema paths.
cli-engine/src/cli/registration.rs	Extracted post-construction registration/mounting helpers for modules and built-in groups.
cli-engine/src/cli/lookup.rs	Extracted clap tree lookup, search document generation, and raw-arg normalization helpers.
cli-engine/src/cli/argv0.rs	Extracted argv0 (busybox/git-style) dispatch and link/shim management.
cli-engine/src/auth/pkce/scopes.rs	Split PKCE scope parsing/step-up planning/identity extraction utilities into their own module.
cli-engine/src/auth/pkce/callback_server.rs	Split PKCE callback server + PKCE challenge/state helpers into their own module.
cli-engine/scripts/check-module-size.sh	New script that fails CI when any hand-written .rs exceeds 1000 lines.
AGENTS.md	Documents the new code file structure rules and adds the module-size check to the recommended test commands.
.github/workflows/ci.yml	Wires the new module-size script into CI.

Review details

• Files reviewed: 37/43 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The refactor spans many core modules (CLI, middleware, output, transport, flags, command runtime), so it merits a final human review for subtle behavior/visibility regressions despite the stated “no behavior change” intent.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

cli-engine/src/output/human/footer.rs:43

• append_render_notes uses out.push_str(&format!(...)), which allocates a temporary String even though the comment (and render_human_with_view in mod.rs) describe footer content being appended without per-footer temporaries. Using write! against out keeps the in-place behavior and avoids the extra allocation.

This issue also appears on line 78 of the same file.

cli-engine/src/output/human/footer.rs:82

• append_pagination_summary also uses out.push_str(&format!(...)), which creates a temporary String. If the intent is to keep footer rendering allocation-light (as described in render_human_with_view), write! can append directly into out.

• Files reviewed: 37/43 changed files
• Comments generated: 0 new
• Review effort level: Lite