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