# 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.