prometeu-studio/docs/packer/agendas/01.6. CLI Surface and Mutating Operations Agenda.md

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.