95 lines
2.4 KiB
Markdown
95 lines
2.4 KiB
Markdown
# CLI Surface and Mutating Operations Agenda
|
|
|
|
## Status
|
|
|
|
Open
|
|
|
|
## Purpose
|
|
|
|
Define the stable service and adapter contract for packer operations, especially operations 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`
|
|
|
|
Historically, packer was framed as a CLI-first tool.
|
|
The current direction is different:
|
|
|
|
- packer should be fully integrated with Studio;
|
|
- operations should exist as services;
|
|
- CLI, if retained, should be an adapter over those services.
|
|
|
|
This is enough surface area that operation semantics need architectural review before turning into normative service and CLI contracts.
|
|
|
|
## Source Sections
|
|
|
|
- `13. CLI Commands (Comprehensive)`
|
|
|
|
## Key Questions
|
|
|
|
1. Which operations are core v1 and which are aspirational?
|
|
2. Which identifiers must every command accept: name, id, uuid, path?
|
|
3. Which operations 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. Which parts of the contract belong to Studio services versus optional CLI adapters?
|
|
7. Should adapter output contracts be stable for automation, or only JSON/structured output modes?
|
|
|
|
## Options
|
|
|
|
### Option A
|
|
|
|
Define a minimal stable v1 service surface 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 matches the Studio-integrated direction better because services can stabilize before adapters.
|
|
- 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 services,
|
|
- optional adapters,
|
|
- future operations not yet in the normative contract.
|
|
|
|
## Expected Decisions to Produce
|
|
|
|
1. Core v1 service set.
|
|
2. Mutation safety model.
|
|
3. Identifier resolution rules.
|
|
4. Adapter and structured output expectations.
|
|
|
|
## Expected Spec Follow-up
|
|
|
|
- Service operation contract spec.
|
|
- CLI adapter 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.
|