utils

func AddGroupTag ¶

func AddGroupTag(fileName string, groupName string, serviceNames []string) error

AddGroupTag tags each of the given services with groupName in the compose file at fileName, preserving the file's existing formatting and comments as much as possible. It's idempotent: a service that already carries the tag is left unchanged.

func AddServiceFragment ¶

func AddServiceFragment(fileName string, serviceName string, fragment []byte) error

AddServiceFragment inserts a new service into the compose file at fileName.

It is ApplyServiceFragment's opposite number: same fragment shape, same validation, same atomic write, but it refuses when the name is already taken instead of when it is absent. Insertion is at the end of the services: mapping, which is where a reader expects a new entry and the only position that never reorders the user's file.

func ApplyEnvEdit ¶

func ApplyEnvEdit(filePath string, ops []EnvEditOp) error

ApplyEnvEdit applies a series of edits to an .env file, preserving formatting. Comments, blank lines, key order, quoting, export prefixes, CRLF and BOM survive.

func ApplyHealthcheck ¶

func ApplyHealthcheck(fileName string, serviceName string, t HealthcheckTemplate, port string) error

ApplyHealthcheck inserts or replaces the healthcheck: mapping under serviceName in the compose file at fileName. port is only used by templates with Generic set - it is substituted into Test's CMD-SHELL string - and is otherwise ignored.

The healthcheck is built as a yaml.Node and inserted directly into the service's existing value node, the same read-modify-write shape utils.SetGroupMembers uses, rather than round-tripping through a whole- service fragment: a healthcheck is one mapping under the service, not the service itself.

func ApplyServiceFragment ¶

func ApplyServiceFragment(fileName string, serviceName string, fragment []byte) error

ApplyServiceFragment parses an edited fragment and writes it back over serviceName in the compose file.

The file is left untouched unless the fragment parses, is shaped like a service, and the whole resulting document still loads as compose. That last check is what makes editing a fragment safer than editing the file by hand.

func ComposeFileArgs ¶

func ComposeFileArgs(composeFile string) []string

ComposeFileArgs starts the argument list for a `docker compose` invocation, pinning it to composeFile when one is known.

Every docker call in the app goes through this so the UI and the commands can never disagree about which file is in play: the panel shows the file the app resolved, and `--file` makes docker act on that same one. Before this, each side resolved independently - identically, but only because both looked in the current directory. A `--file` flag pointing somewhere else would have split them, which is why this landed first.

An empty composeFile leaves the flag off and lets docker resolve the file itself. That is the bootstrap state (no file loaded yet), where there is nothing to pin to and no panel making a claim to contradict.

--file is compose-level, so it belongs between `compose` and the subcommand: `docker compose --file X up -d`, never `docker compose up --file X`.

func Deduplicate ¶

func Deduplicate(input []string) []string

Deduplicates an array of strings.

func DefaultGenericPort ¶

func DefaultGenericPort(svc types.ServiceConfig) string

DefaultGenericPort is the container-internal port the generic template's port field prefills with: the first ports: target if the service publishes one, else 80 - the common case for a bare web image.

func DeleteService ¶ added in v0.5.0

func DeleteService(fileName string, serviceName string) error

DeleteService removes serviceName's entry from the services: mapping in fileName - AddServiceFragment's opposite number, minus a fragment to parse.

The removal goes through the same validate-by-reload every other writer in this file uses, plus an explicit dependents check ValidateComposeCandidate alone cannot cover - see ensureNoDependents.

func DockerComposePs ¶

func DockerComposePs(composeFile string) (string, error)

Executes `docker compose ps` scoped to composeFile (see ComposeFileArgs) and returns the raw JSON output. Using `docker compose ps` (rather than `docker ps`) means each entry already carries the compose service name in its "Service" field, so callers never need to guess it from the container name.

The output shape depends on the Docker Compose version: newer releases emit a single JSON array, older ones emit NDJSON (one object per line). ParseContainers accepts both.

func DockerMemTotal ¶

func DockerMemTotal() (int64, error)

DockerMemTotal runs `docker info --format '{{.MemTotal}}'` and returns the total memory in bytes.

func DockerSystemDf ¶

func DockerSystemDf() (string, error)

DockerSystemDf runs `docker system df --format json` and returns the raw NDJSON output.

func EditorCommand ¶

func EditorCommand(path string) *exec.Cmd

EditorCommand builds the command that opens path in the user's editor.

$VISUAL wins over $EDITOR by long-standing convention: $EDITOR may be a line editor for use on a dumb terminal, while $VISUAL is the full-screen one, and we are handing over a full terminal.

The value is split on whitespace rather than run through a shell, so EDITOR="code --wait" works. A shell would also make every character the user has in that variable executable at the moment we hand it the terminal, which buys nothing here.

func EnsureBackupStore ¶

func EnsureBackupStore(composeDir string) error

EnsureBackupStore creates the sidecar backup folder next to the resolved compose file. It is idempotent: calling it again is a no-op. The folder is local to the stack directory, not in the config dir and not under ~/.local/share, so it moves with the project and stays discoverable.

func ExtractServiceFragment ¶

func ExtractServiceFragment(fileName string, serviceName string) ([]byte, error)

ExtractServiceFragment returns the YAML for one service, as a single-key mapping exactly as it appears in the compose file:

web:
  image: nginx:alpine
  ports:
    - "8085:80"

The service name is kept as the top-level key for two reasons. It gives the user the context they would have in the real file, and it gives callers somewhere to put an explanatory header comment that cannot leak back in: comments above the key attach to the key node, and ApplyServiceFragment only ever takes the value.

func GetComposeFileName ¶

func GetComposeFileName(source ComposeSource) (winner string, candidates []string, err error)

GetComposeFileName resolves which compose file to use for source. It returns the winner plus every candidate that exists, in priority order (so the winner is candidates[0]), because the winner is the whole story only when it is the only one: with several present, the UI can say which others were in the running.

Paths are returned as they will be used: joined with source.Dir, so the result can go straight to docker, to the YAML writers and to the footer.

func IsValidServiceName ¶

func IsValidServiceName(s string) bool

IsValidServiceName reports whether s is a legal Compose service name: letters, digits, hyphen and underscore only. Shared by every "make a service" flow (servicefieldsstep, addservicemodal) so the rule can never drift between them - see D7 in docs/plans/image-search.md for why this function is shared while the UI step it validates for is deliberately not.

func ListComposeFiles ¶

func ListComposeFiles(dir string) ([]string, error)

ListComposeFiles returns the names of the YAML files in dir, sorted. It is the directory scan behind the Files page's file picker: any *.yaml or *.yml file is a candidate, because --file accepts any name, not just the four auto-detected ones - the picker is a way to choose, not a resolution order, so it is not limited to GetComposeFileName's canonical names.

func NextRestartPolicy ¶ added in v0.5.0

func NextRestartPolicy(current string) string

NextRestartPolicy returns the policy after current in restartPolicyCycle, wrapping around. "no" is treated the same as "": both are the cycle's unset state, since a service written by hand with restart: no means exactly what an absent key means. A value outside the cycle (hand-edited, or a future compose keyword this app does not know) resets to the first entry rather than guessing where it belongs.

func ParseContainers ¶

func ParseContainers(output string) ([]apptypes.DockerContainer, error)

ParseContainers turns `docker compose ps --format json` output into a slice of containers. Newer Docker Compose versions emit a single JSON array; older ones emit NDJSON (one object per line). Both are accepted so the app doesn't pin a minimum compose version.

func ReadConfigFile ¶

func ReadConfigFile(fileName string) (*types.Project, error)

func ReadConfigFileExt ¶

func ReadConfigFileExt(fileName string) (*types.Project, string, bool, error)

ReadConfigFileExt returns the project, the resolved .env path, and whether it was loaded. The .env path is resolved relative to the compose file's directory (compose-go semantics). It may exist but not be loaded if COMPOSE_DISABLE_ENV_FILE is set.

func RemoveGroupTag ¶

func RemoveGroupTag(fileName string, groupName string) error

RemoveGroupTag strips groupName from every service in the compose file at fileName that carries it. A service's profiles key is removed entirely, rather than left as an empty list, once its last tag is gone.

func RenameGroupTag ¶

func RenameGroupTag(fileName string, oldName string, newName string) error

RenameGroupTag replaces every profiles entry equal to oldName with newName in the compose file at fileName. Other profiles and every other key are untouched. Nothing else in a compose file references a profile by name (unlike service names, which depends_on references - which is why service renames are refused), so a rename cannot leave dangling references. Returns an error when no service carries oldName, which catches the file having changed since the caller last synced it.

func ReplaceFileAtomically ¶

func ReplaceFileAtomically(fileName string, contents []byte) error

ReplaceFileAtomically writes contents to fileName by way of a temporary file that is renamed into place, creating the file if it doesn't exist.

Writing over the file directly truncates it first, so anything that fails after that point - a full disk, a crash, a killed process - leaves the user with a half-written or empty compose file and no copy of the original. Rename, by contrast, is atomic within a filesystem: a reader, including `docker compose` itself, sees either the old file or the complete new one.

Permissions of an existing file are carried over to the replacement.

func ReplaceFileAtomicallyWithMode ¶

func ReplaceFileAtomicallyWithMode(fileName string, contents []byte, newFileMode os.FileMode) error

ReplaceFileAtomicallyWithMode is like ReplaceFileAtomically but accepts an explicit mode for new files. The mode is applied before the write, not after the rename, so a mode like 0600 is never briefly world-readable.

If the file exists, its mode is preserved (resolving symlinks first). If the file is a symlink, it is resolved and the target is written through. If the symlink is dangling, an error is returned without creating a file.

func RestoreBackup ¶ added in v0.4.0

func RestoreBackup(sourceFile, backupName string) error

RestoreBackup writes the named .bak back over sourceFile. It goes through ReplaceFileAtomically, so the file being overwritten is snapshotted first and the restore is itself undoable: restoring compose.yaml@T2 leaves a new backup of the current compose.yaml (the one about to be replaced) as the next-newest entry.

The .bak name must belong to sourceFile's slug dir; an unknown or mismatched name is an error so a caller cannot accidentally write bytes from another source's folder over this one.

func RunDockerCompose ¶

func RunDockerCompose(action string, target string, isGroup bool, composeFile string, members []string) error

RunDockerCompose runs a `docker compose` action scoped either to a single service or to an explicit set of services (a group's members).

composeFile is the file the app resolved and is showing in its UI; it is passed to docker as --file so the command acts on the same file the panels describe. Empty means "let docker resolve it", which is only correct before a file is loaded - see ComposeFileArgs.

Remove uses `rm -fs` rather than `down`: `down` also tears down the project's shared network, which would affect services outside the selected set.

func SecretHint ¶

func SecretHint(key string) bool

SecretHint reports whether a value under this env key should be masked by default when something other than the Env page renders it. Key name only — value-shape heuristics are deliberately not used.

It is a hint, not a guarantee: the Env page masks everything regardless, and this exists so the next panel to render arbitrary env values does the safe thing without its author having to think about it.

func SetGroupMembers ¶

func SetGroupMembers(fileName string, groupName string, members []string) error

SetGroupMembers reconciles the compose file so that exactly the named services carry groupName as a profile tag. Services in members that lack the tag get it added; services not in members that carry it get it removed. A service whose profiles key becomes empty is cleaned up the same way RemoveGroupTag does.

The reconciliation runs in a single read-modify-write pass rather than composing AddGroupTag and RemoveGroupTag, which would each open and close the file separately and leave a crash window with a half-applied edit.

func SetRestartPolicy ¶ added in v0.5.0

func SetRestartPolicy(fileName string, serviceName string, policy string) error

SetRestartPolicy writes policy into serviceName's restart: field in the compose file at fileName, through the same read-modify-write shape ApplyHealthcheck uses. An empty policy removes the key entirely rather than writing restart: "" - compose has no such value, and dropping the key is what "no policy" looks like in a file a human reads afterward.

func SnapshotFile ¶

func SnapshotFile(fileName string) error

SnapshotFile captures the pre-write state of fileName into the backup store, so a bad write can later be undone. It is called from inside the atomic write, before the file is replaced, so it only ever runs for writes the app has already committed to.

A brand-new file has nothing to snapshot, so it is a no-op that still succeeds. If the file's content matches the most recent entry already in the store, the snapshot is skipped too (nothing new to preserve).

If the backup cannot be taken, the error is returned and the write is refused: no write happens without a retained copy of what it replaces.

func StreamDockerLogs ¶

func StreamDockerLogs(target string, isGroup bool, composeFile string, members []string) (<-chan string, context.CancelFunc, error)

StreamDockerLogs starts `docker compose logs -f` for a single service or for the named members of a group, scoped to composeFile (see ComposeFileArgs), and streams each output line over the returned channel. The channel is closed when the process exits (or is cancelled). Call the returned CancelFunc to kill the process and stop the stream - this is the first long-lived subprocess in the app, so tearing it down is the caller's responsibility.

Unlike RunDockerCompose, which captures CombinedOutput() once and returns, this reads stdout+stderr incrementally on a goroutine so the TUI can render lines as they arrive.

func URLHost ¶

func URLHost(cfg config.Config, env func(string) string) string

URLHost is the host part of every service URL the app builds, in order:

1. config.URLHost - the user's explicit answer, wins always
2. SSH_CONNECTION[2] - the address this SSH client used to get here, measured rather than guessed
3. "localhost" - running locally, which is then correct

env is passed in (rather than reading os.Getenv directly) so this stays a table test; AppModel is the one real caller and reads the environment once, at startup, since the answer cannot change during a run.

func ValidateComposeCandidate ¶

func ValidateComposeCandidate(dir string, contents []byte) error

ValidateComposeCandidate reports whether contents would load as a compose file, without touching whatever is currently on disk.

The candidate is written into dir rather than a system temp directory because compose resolves relative paths - build contexts, env_file: - from the compose file's own location, so validating anywhere else would reject files that are perfectly fine, and accept ones that aren't.

func WriteNewComposeFile ¶

func WriteNewComposeFile(fileName string, serviceName string, image string) error

WriteNewComposeFile creates a brand-new compose file at fileName with a top-level services mapping, optionally pre-seeded with one service. It refuses to overwrite an existing file: the caller is expected to have already shown a validation error in the modal in that case, so we surface os.ErrExist to make the failure mode explicit.