rework-file-structure

[hsablonniere]

👋 Welcome reviewers

Summary

This PR completely restructures the clever-tools CLI architecture.
The main goal is to move from a monolithic structure (a single clever.js file with all commands) to a modular architecture where each command lives in its own file with a typed declarative API.

It also contains improvements about documentation:

• We patched cliparse to improve the display of --help
• We added a new npm script to generate a reference documentation for each commands and a single document with everything for LLMs

Overall stats: ~296 files changed, +14,834 / -6,754 lines

Phase 1: Documentation Preparation

Normalize argument and option documentation before the refactoring:

• Clarify argument names for id-or-name parameters (c99a3385)
• Normalize metavar to lowercase kebab-case (270b7368)
• Remove redundant metavar on wgPublicKey (54763a7e)
• Add missing metavar on output option (0fb533a0)

Why first? These changes reduce noise in later diffs and ensure consistent documentation before transformation.

Phase 2: Preparatory Refactoring

Simplify existing code to ease the migration:

• Move domain utility functions to models/domain.js (715a298d)
• Make getEmailNotificationTargets function private (be1ab98d)
• Rename some constants to avoid naming conflicts (dc3165f7)
  • We're going to need options as a function argument
• Extract cliparse patches into a dedicated module (cd046782)
• Simplify parsers: they now throw errors instead of returning cliparse result objects (5810a03c)
• Simplify autocomplete: functions now return plain arrays (4bd1d817)

Impact: These changes decouple our code from cliparse's internal API.

Phase 3: Analysis and Automated Transformation Scripts

Create temporary scripts to analyze and transform the code:

• Add CSV file with versions and dates for each command (737cbe47)
• Script to analyze commands, arguments, and options (df843913)
• Script to transform command function signatures (c48d3226)
• Script to analyze command dependencies and usage (7166e2e6)
• Script to generate new CLI command structure (23e60b9e)

Note: These scripts are removed at the end of Phase 4.

Phase 4: Apply Transformations

Apply scripts and create the new architecture:

• Apply automated script to convert command function signatures (d2b56f65)
• Update cliparse command function signature to pass options and args (5258e1c6)
• Introduce type-safe helpers defineArgument, defineOption, defineCommand (af21b84d)
• Apply generation script: create all *.command.js files (3949a5b4)
• Remove temporary refactoring scripts (6a992607)

New structure:

src/commands/
├── addon/
│   ├── addon.command.js
│   ├── addon.args.js
│   ├── addon.create.command.js
│   ├── addon.delete.command.js
│   └── ...
├── domain/
│   ├── domain.command.js
│   └── ...
├── global.commands.js
├── global.options.js
└── ...

Phase 5: Cleanup and Improvements

Post-migration cleanup and structure improvements:

• Add curl command to new file structure (0d31d307)
• Add argument definition to addon env command (7d3427f1)
• Fix options schemas, descriptions, and parsers (97ece541)
• Normalize option keys to camelCase (95973b96)
• Remove unused options (b2946200)
• Improve option placeholders for clarity (40554379)
• Move single-usage options to their respective commands (c438b079)
• Deduplicate: when root and list commands are the same (9877b49f)
• Move deprecation messages to option definitions (57257270)
• Remove redundant "(optional)" from argument descriptions (149de624)
• Migrate config update command to new option definition system (1f80cfe6)
• Use .default('1y') for token expiration (3165698f)

Phase 6: Final Integration

Activate the new structure as default:

• Add --help and --version to global options (76e92ab5)
• Add help command to global commands (a4bd6b3a)
• New entry point using the new file structure (958fa568)
• Remove old CLI structure (old clever.js and commands/) (ce5514e9)
• Make new CLI structure the default (b776128e)
• Remove unused parsers (2c6cafa7)
• Remove unused command-options module (e398115c)

Phase 7: Documentation

Improve help display and generate documentation:

• Improve --help display (52bf70d5)
• Add documentation generation scripts (reference & LLM) (b4436995)
• Generate comprehensive command reference and LLM documentation (d4eaba58)
• Update CONTRIBUTING.md with new command structure and docs (a28b13de)
• Add architecture decision record for file structure rework (da07c1b9)

Chore

• Add mise.toml with node and npm versions (4c5a4531)

How to Review

I recommend following the phase order for review:

1. Phase 1-2: Simple preparatory changes
2. Phase 4: Look at src/lib/define-*.js and a command example (e.g., addon/)
3. Phase 6: Check the new clever.js entry point
4. Phase 7: Review the generated documentation and the ADR

Phase 3 and parts of phase 6 are migration "noise" - temporary scripts and cleanup.

[github-actions]

🔎 The preview has been automatically deleted.

[davlgd]

Thanks for this amazing work, especially on automatic documentation. After using this version, and implemented new commands/options in it, LGTM. Using zod is way better than previous parsers. Just some nitpicks/reflexions:

--version as global option prevents us to add --version option to commands. I suppose this is related to cliparse and we can't do much about it for now.

As discussed, in --help I would be more for :

• USAGE
• COMMANDS (without AVAILABLE)
• OPTIONS

In options such as :

  -F, --format <format>    Output format (human, json) (default: human)

Default value is in grey. But sometimes we add default value in the option description (if it's managed from API for example). So it's incoherent. We must choose if we go all white or grey for such information.

About command metadata:

defineCommand({
  description: 'Restart a Kubernetes cluster',
  since: '4.5.0',
  sinceDate: '2025-10-22',

IMHO, since is a good addition, as discussed for documentation, and it will be easy to add/maintain in release process. But sinceDate seems too much here. We can't plan when a release will be effective and it will need us to update this just before release. Additionally, this information already lives somewhere else.

If we don't plan to use it, we can just remove. If we plan to use it, maybe we can infer the date from the release semver.

[hsablonniere]

--version as global option prevents us to add --version option to commands. I suppose this is related to cliparse and we can't do much about it for now.

Yes, we cannot do much better for now because of cliparse but we're very close to be able to remove it.

As discussed, in --help I would be more for : USAGE, COMMANDS (without AVAILABLE), OPTIONS

Fixed, I wonder what others think.

Default value is in grey. But sometimes we add default value in the option description (if it's managed from API for example). So it's incoherent. We must choose if we go all white or grey for such information.

If we don't plan to use it, we can just remove. If we plan to use it, maybe we can infer the date from the release semver.

I agree, this is fixed.