Skip to content

[codex] split command adapters and enforce public contract checks#64

Merged
6uclz1 merged 2 commits intomainfrom
codex/split-command-adapters-public-contract-checks
Mar 3, 2026
Merged

[codex] split command adapters and enforce public contract checks#64
6uclz1 merged 2 commits intomainfrom
codex/split-command-adapters-public-contract-checks

Conversation

@6uclz1
Copy link
Owner

@6uclz1 6uclz1 commented Mar 3, 2026

What changed

This PR refactors the CLI command layer into smaller, focused modules and adds explicit public-contract guardrails so internal refactors can proceed safely without silently changing user-facing behavior.

Issue and user impact

The command implementation had grown into large, multi-responsibility modules (notably arrangement.py and track.py) with transport, parsing, and command adaptation concerns mixed together. That made routine changes harder to reason about and increased the chance of accidental regressions in CLI behavior, JSON output shape, protocol handling, and exit-code semantics that users depend on in scripts.

Root cause

Public/stable boundaries were documented only implicitly, and there was no automated snapshot gate to detect contract drift. At the same time, command adapters accumulated too many responsibilities in single files, which increased coupling and made intent-preserving changes expensive and error-prone.

Fix

The refactor splits command responsibilities into dedicated internal modules (for arrangement/track subdomains and shared command-runner utilities), while keeping the public command surface unchanged. It also introduces explicit contract enforcement by adding a generated public snapshot (tests/snapshots/public_contract_snapshot.json), a contract check module, and a regeneration tool (tools/update_public_contract_snapshot.py).

In addition, client/backend responsibilities are separated (src/ableton_cli/client/backends.py), remote/contract paths and error mapping were tightened, and contributor guidance now documents the public contract boundary and snapshot update workflow.

Validation

The following checks were run on this branch:

  • uv run python -m ableton_cli.dev_checks
  • uv run ruff check .
  • uv run ruff format --check .
  • uv run pytest

All checks passed (including 515 passed in pytest).

@6uclz1 6uclz1 changed the title split command adapters and enforce public contract checks [codex] split command adapters and enforce public contract checks Mar 3, 2026
@6uclz1 6uclz1 marked this pull request as ready for review March 3, 2026 16:57
@6uclz1 6uclz1 merged commit 45830c7 into main Mar 3, 2026
8 checks passed
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.

1 participant