85 lines
1.9 KiB
Markdown
85 lines
1.9 KiB
Markdown
# CLI Surface and Mutating Operations Agenda
|
|
|
|
## Status
|
|
|
|
Open
|
|
|
|
## Purpose
|
|
|
|
Define the stable CLI contract for packer commands, especially commands that mutate registry state or user files.
|
|
|
|
## Context
|
|
|
|
The draft already lists a substantial command surface:
|
|
|
|
- `init`
|
|
- `add`
|
|
- `adopt`
|
|
- `forget`
|
|
- `rm`
|
|
- `list`
|
|
- `show`
|
|
- `doctor`
|
|
- `build`
|
|
- `watch`
|
|
- `gc`
|
|
- `quarantine`
|
|
|
|
This is enough surface area that command semantics need architectural review before turning into normative CLI specs.
|
|
|
|
## Source Sections
|
|
|
|
- `13. CLI Commands (Comprehensive)`
|
|
|
|
## Key Questions
|
|
|
|
1. Which commands are core v1 and which are aspirational?
|
|
2. Which identifiers must every command accept: name, id, uuid, path?
|
|
3. Which commands mutate registry only versus mutate workspace files?
|
|
4. What requires confirmation, force flags, or dry-run support?
|
|
5. How explicit should `--fix` and auto-materialization behavior be?
|
|
6. Should CLI output contracts be stable for automation, or only JSON/structured output modes?
|
|
|
|
## Options
|
|
|
|
### Option A
|
|
|
|
Define a minimal stable v1 CLI and mark the rest as future or optional.
|
|
|
|
### Option B
|
|
|
|
Freeze the larger command catalog immediately.
|
|
|
|
## Tradeoffs
|
|
|
|
- Option A lowers the early compatibility burden.
|
|
- Option A gives room to validate mutating operations safely before promising too much.
|
|
- Option B gives a bigger product surface up front, but it increases long-term compatibility cost.
|
|
|
|
## Recommendation
|
|
|
|
Adopt Option A and distinguish:
|
|
|
|
- required core commands,
|
|
- optional commands,
|
|
- future commands not yet in the normative CLI contract.
|
|
|
|
## Expected Decisions to Produce
|
|
|
|
1. Core v1 command set.
|
|
2. Mutation safety model.
|
|
3. Identifier resolution rules.
|
|
4. Structured output and automation expectations.
|
|
|
|
## Expected Spec Follow-up
|
|
|
|
- CLI command contract spec.
|
|
- Mutation and confirmation policy spec.
|
|
- Command output contract spec.
|
|
|
|
## Non-Goals
|
|
|
|
- Asset payload binary layout.
|
|
- Format-specific `asset.json` rules.
|
|
- Detailed cache internals.
|