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

CLI Surface and Mutating Operations Agenda

Status

Closed

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