cmd

Create a new file defining the Cobra command, its flags, and its run function. Define an options struct to hold parsed flags.

Pattern: Follow the exact structure in cmd/compose/down.go: define an options struct (e.g., downOptions), a constructor function (e.g., downCommand) that returns *cobra.Command, parse flags in the command definition, and wire the run function through the adapter pattern

Add the new operation method signature to the Service interface and define any new option/result types needed

Pattern: Follow how DownOptions and the Down method are defined in the Service interface in pkg/api — add your new options struct and method signature in the same file or a new types file in pkg/api

Create a new file implementing the Service interface method for the new command against the Docker daemon

Pattern: Follow the pattern in pkg/compose (the engine implementation files) — each operation is typically in its own file, receives a context and options, and interacts with the Docker client

Register the new subcommand by calling your constructor function and adding it to the root command's subcommands list

Pattern: Look at how existing commands like downCommand are instantiated and added via rootCmd.AddCommand() in cmd/compose/compose.go

Add a mock implementation of the new Service method for testing

Pattern: Follow the existing mock patterns in pkg/mocks where each Service method has a corresponding mock function field and implementation

Add end-to-end tests exercising the new command through the full CLI

Pattern: Follow existing E2E test patterns in pkg/e2e that invoke the CLI binary with arguments and assert on stdout/stderr output and container state

Add the new field to the command's options struct and register the flag using cmd.Flags() in the command constructor

Pattern: See how cmd/compose/down.go defines flags like --volumes, --remove-orphans using cmd.Flags().BoolVar, cmd.Flags().StringVar, etc., binding them to fields on the options struct

If the flag maps to a new API-level option, add the corresponding field to the relevant Options struct in pkg/api

Pattern: See how DownOptions in pkg/api includes fields like RemoveOrphans, Volumes that correspond to CLI flags

Handle the new option in the engine implementation, reading it from the options struct and adjusting behavior

Pattern: See how the compose engine reads DownOptions fields to decide which Docker API calls to make

Add or modify the formatting logic for container data, including new fields or format templates

Pattern: See how cmd/formatter/container.go transforms api.ContainerSummary into formatted output with field-level control over truncation and display

If modifying log output, update the log formatting and colorization logic here

Pattern: See how cmd/formatter/logs.go handles log line formatting, container name prefixing, and color assignment

If modifying the TTY progress display, update the real-time terminal UI components here

Pattern: See how cmd/display/tty.go manages concurrent status updates, hierarchical task visualization, and terminal size constraints

Define the new method on the Service interface with its options and return types

Pattern: Follow how existing methods like Down(ctx context.Context, projectName string, options DownOptions) error are defined in the Service interface in pkg/api

Create a new file (or add to an existing one) implementing the method on the composeService struct

Pattern: Each operation file in pkg/compose receives the composeService receiver, uses s.dockerCli or s.apiClient() to interact with Docker, and follows the context/cancellation patterns seen in other operation files

Add a dry-run implementation that simulates the operation without side effects

Pattern: Follow the pattern in pkg/dryrun where each Service method is wrapped to log what would happen without actually calling Docker

Add a mock implementation for the new method

Pattern: Follow the mock pattern in pkg/mocks where each method has a function field that can be set in tests

Modify or extend the file system watcher, debouncing logic, or path filtering rules

Pattern: See how pkg/watch implements file system watching with debounce intervals and path matchers for ignoring files

Update the watch/dev-mode integration in the compose engine to handle the new scenario

Pattern: See how the compose engine's watch-related code connects file change events to rebuild/restart/sync actions

Add the new shortcut key handler and update the menu rendering to display it

Pattern: See how cmd/formatter/shortcut.go defines keyboard shortcuts for watch, detach, and Docker Desktop integration — each shortcut has a key binding, a handler function, and a menu label

If the shortcut needs to trigger a compose operation, wire it through the backend service in the command adapter

Pattern: See how existing shortcuts in cmd/formatter/shortcut.go interact with the compose service and how the shortcut manager is initialized in the command flow

Add or extend span definitions and attribute constants for the new operation

Pattern: See how internal/tracing defines span management and how cmd/cmdtrace/cmd_span.go instruments CLI command execution with start/end spans and attribute recording

If the operation is a CLI command, add tracing instrumentation in the command span lifecycle

Pattern: See how cmd/cmdtrace/cmd_span.go wraps command execution with OpenTelemetry spans, recording command name, flags, and duration

Add conversion logic between compose model types and the new external format

Pattern: See how pkg/bridge converts between compose and external formats, and how cmd/compose/bridge.go provides CLI command handlers for bridge operations

Add or modify CLI command handlers for the new bridge/provider integration

Pattern: See how cmd/compose/bridge.go defines command handlers for compose-to-model conversion and transformer image management

Add the new source type handler alongside existing Git and OCI registry loaders

Pattern: See how pkg/remote implements Git repo and OCI registry loading with caching — each source type has a loader that resolves the remote reference, downloads the project, and caches it locally