119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
# CLI Surface and Mutating Operations Agenda
|
|
|
|
## Status
|
|
|
|
Closed
|
|
|
|
Resolved by [`006-studio-first-asset-services-and-event-lane-decision.md`](../decisions/006-studio-first-asset-services-and-event-lane-decision.md).
|
|
|
|
## Purpose
|
|
|
|
Define the stable Studio-facing service 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 target is different:
|
|
|
|
- packer should be fully integrated with Studio;
|
|
- asset UI and packer services should evolve together;
|
|
- operations should exist as Studio-consumable services first;
|
|
- asset workflows should be observable through a dedicated background event lane for UI integration;
|
|
- CLI, if retained, should be treated as a later adapter rather than the design center.
|
|
|
|
This means the architectural work should focus on service semantics and UI integration points first, not on freezing a command-line contract too early.
|
|
|
|
## Source Sections
|
|
|
|
- `13. CLI Commands (Comprehensive)`
|
|
|
|
## Key Questions
|
|
|
|
1. Which packer operations are core Studio services in v1 and which are later capabilities?
|
|
2. Which identifiers should Studio-facing services accept for normal asset workflows: name, id, uuid, root path?
|
|
3. Which operations mutate registry only versus mutate workspace files?
|
|
4. What requires explicit confirmation, preview, or staged apply behavior in Studio?
|
|
5. How should safe fix flows be exposed as service operations rather than CLI flags?
|
|
6. Which responses must be structured for UI consumption and automation?
|
|
7. What, if anything, should remain CLI-specific in the future adapter layer?
|
|
8. Should assets have a dedicated background event lane that reports changes, diagnostics, and build activity to the UI?
|
|
|
|
## Options
|
|
|
|
### Option A
|
|
|
|
Define a minimal stable v1 Studio service surface and mark the rest as future or optional.
|
|
|
|
### Option B
|
|
|
|
Freeze a larger command catalog immediately.
|
|
|
|
## Tradeoffs
|
|
|
|
- Option A lowers the early compatibility burden.
|
|
- Option A matches the Studio-integrated direction better because services and UI can stabilize together before any CLI freeze.
|
|
- 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 around the wrong adapter.
|
|
|
|
## Recommendation
|
|
|
|
Adopt Option A and distinguish:
|
|
|
|
- required core services,
|
|
- optional future adapters,
|
|
- future operations not yet in the normative contract.
|
|
|
|
Current design target:
|
|
|
|
- Studio integration is primary;
|
|
- asset UI and packer services should be designed together;
|
|
- service contracts should describe intent, preview, apply, and result models suitable for UI workflows;
|
|
- asset-oriented operations should publish structured background events suitable for logs, progress, and live UI refresh;
|
|
- CLI should not drive the core architecture in this phase.
|
|
|
|
Also adopt this integration direction:
|
|
|
|
- the system should have a dedicated asset workspace event lane;
|
|
- this lane observes relevant asset and registry changes, triggers analysis/rebuild workflows as appropriate, and reports structured events to the UI;
|
|
- the architectural contract is the event/reporting surface, not a commitment to a specific threading primitive;
|
|
- dangerous mutations still require explicit user intent and must not be silently auto-applied by the background lane.
|
|
|
|
## Expected Decisions to Produce
|
|
|
|
1. Core v1 Studio service set.
|
|
2. Mutation safety and preview/apply model.
|
|
3. Identifier resolution rules.
|
|
4. Structured response contracts for UI and automation.
|
|
5. Boundary between core services and future adapters.
|
|
6. Asset workspace event lane and structured event model for UI reporting.
|
|
|
|
## Expected Spec Follow-up
|
|
|
|
- Service operation contract spec.
|
|
- Studio asset workflow integration spec.
|
|
- Mutation and confirmation policy spec.
|
|
- Structured response/output contract spec.
|
|
- Asset event/reporting integration spec.
|
|
|
|
## Non-Goals
|
|
|
|
- Asset payload binary layout.
|
|
- Format-specific `asset.json` rules.
|
|
- Detailed cache internals.
|
|
- Freezing a comprehensive CLI contract in the current phase.
|