Proposal: Introduce `atd` dispatcher CLI and prepare unified Cmdliner interface (ATD 4.x → 5.0)

[mjambon]

Summary

Introduce a top-level atd command that dispatches to existing tools (atdgen, atdpy, atdml, …) via the atd <subcommand> pattern.

This change will:

• Provide a modern and discoverable CLI entry point.
• Allow gradual migration to a consistent CLI based on Cmdliner.
• Preserve compatibility with existing scripts and users.

The full CLI cleanup (consistent options, help output, etc.) would happen in ATD 5.0.0.

---

Goals

1. Introduce a unified entry point:

atd gen
atd py
atd ml

2. Preserve backward compatibility:

atdgen
atdpy
atdml

continue to work.

3. Avoid large refactors in the short term.

4. Enable gradual migration of all tools to Cmdliner.

---

Proposed design

Dispatcher model

atd is a small executable that runs:

atd-<subcommand>

Example:

atd gen  → exec atd-gen
atd py   → exec atd-py

This follows the common CLI pattern used by tools such as git.

Advantages:

• Minimal implementation complexity
• No need to merge all programs into one binary
• Supports future plugins/extensions
• Compatible with opam packaging

---

Naming plan

Move toward this naming convention:

atd-gen
atd-py
atd-ml
...

Compatibility names will be preserved:

atdgen → symlink to atd-gen
atdpy  → symlink to atd-py
atdml  → symlink to atd-ml

This ensures:

• No breakage for existing scripts
• Cleaner subcommand dispatch

---

Behavior

Help

atd --help

should display available commands:

Commands:
  gen
  py
  ml
  ...

Each command forwards arguments:

atd gen --help

→ runs

atd-gen --help

---

Unknown commands

Example:

atd foo

Behavior:

• attempt to execute atd-foo
• if not found, display an error:

Unknown command: foo
Tried to execute: atd-foo

---

Packaging and distribution

Binary distributions will include:

bin/
  atd
  atd-gen
  atd-py
  atd-ml
  atdgen
  atdpy
  atdml

Where:

• atdgen, atdpy, etc. are symlinks for compatibility.

This layout works well for:

• GitHub release binaries
• package managers later (Homebrew, Scoop, etc.)

---

Implementation plan

Phase 1 — Introduce dispatcher (ATD 4.x)

Tasks:

• Implement atd dispatcher executable
• Add subcommand discovery
• Add atd --help
• Rename internal binaries to atd-*
• Provide compatibility symlinks
• Update build system (dune/opam)
• Update documentation
• Add tests

No CLI behavior changes in individual tools yet.

---

Phase 2 — CLI unification (ATD 5.0.0)

Migrate all tools to Cmdliner and clean up interfaces.

Goals:

• Consistent --help format
• Consistent option naming
• Consistent error handling
• Consistent version output

Example:

atd version

instead of tool-specific flags.

Tasks:

• Migrate remaining Arg-based CLIs to Cmdliner
• Align option names across tools
• Improve help messages
• Document CLI conventions
• Deprecation notice (if needed)

---

Compatibility policy

The following will continue to work indefinitely:

atdgen
atdpy
atdml

These may eventually become thin wrappers calling:

atd gen

but should remain available for scripts and CI systems.

---

Open questions

1. Should we fully rename binaries to atd-* immediately, or introduce them gradually?
2. Should atd support command aliases?
3. Should we add plugin support later (atd-foo from PATH)?
4. Should we expose a machine-readable command list?

---

Expected benefits

• Cleaner user experience
• Easier discoverability
• Simpler installation story
• Better long-term CLI consistency
• Smooth migration path