unitdore/AGENTS.md

Project Overview

Unitdore is a Go CLI tool that bridges container runtimes (Podman, Docker) and systemd. It discovers running containers, stores them in a YAML config, and generates + manages systemd .service unit files for each one.

Agent Rules

Keep answers short. Question everything, never assume or guess. Ask if unsure. You must use the AMCS MCP system tools. Set unitdore as the active project and always capture summaries of what was done as thoughts using the capture_thought tool. If AMCS is not available, write files to docs/llm/log/yyyymmdd_hh.md.

Tools to use

When writing Go: doc/tools/go-skill.md (if present), otherwise follow standard Go conventions.

Commands

make build          # Compile binary: ./unitdore
make install        # Install binary to /usr/bin, man page, create /etc/unitdore
make uninstall      # Remove binary and man page
make test           # go test ./... -v
make test-short     # go test ./...
make lint           # go vet ./...
make clean          # Remove built binary
make release-version  # Bump patch version, commit, tag, and push

Architecture

cmd/           # Cobra commands (edit, install, list, root, start, startall,
               #   status, stop, stopall, syncup, uninstall, update)
config/        # Config struct + YAML load/save (units.yaml)
runtime/       # Docker and Podman runtime abstraction, compose labels
sysuser/       # run commands as root/user (runuser), home/linger lookup
testdata/stack # podman-compose test stack + captured `podman ps` fixture
systemd/       # .service file generator and systemd manager
docs/          # generated-units.md (unit file examples), unitdore.1 (man page)

Key packages

• config — Unit and Config structs; Load, Save, FindUnit, AddUnit
• runtime — ContainerRuntime interface; docker.go, podman.go implementations
• systemd — generator.go builds .service file content; manager.go calls systemctl

Config file

Location: /etc/unitdore/units.yaml

prefix: ""      # prepended to service file name (e.g. "prod-")
suffix: ""      # appended to service file name (e.g. "-svc")
users: []       # root only: rootless users scanned by syncup

units:
  - name: nginx
    runtime: podman        # podman | docker
    user: ""               # empty = system unit; set for rootless user unit
    command: ""            # override ExecStart entirely
    order: 1               # startup order, lower = earlier; same = parallel
    delay: 0s              # delay after previous order group
    enabled: true
    disabled_reason: ""    # auto-set by syncup reconciliation
    restart: false         # Restart=on-failure
    restart_sec: 0         # RestartSec
    restart_retries: 0     # StartLimitBurst
    kind: container        # container | stack (podman-compose project)
    project: ""            # stack: compose project
    working_dir: ""        # stack: compose dir (from labels)
    compose_files: []      # stack: relative to working_dir
    compose_bin: ""        # stack: podman-compose path

Non-root runs use ~/.config/unitdore/units.yaml and manage only own user units.

Generated service file locations

Scenario	Path
System unit (root)	/etc/systemd/system/unitdore-<name>.service
User unit	/home/<user>/.config/systemd/user/unitdore-<name>.service
With prefix prod-	/etc/systemd/system/unitdore-prod-<name>.service
With suffix -svc	/etc/systemd/system/unitdore-<name>-svc.service

Libraries

• github.com/spf13/cobra — CLI framework
• gopkg.in/yaml.v3 — config parsing

Testing

Tests exist in:

• config/config_test.go
• runtime/runtime_test.go
• cmd/syncup_test.go
• sysuser/sysuser_test.go
• systemd/generator_test.go

Always run make test before marking a task complete. Add tests for new behaviour in the same package as the code under test.

Additional documentation

• docs/generated-units.md — full annotated examples of every generated unit file combination
• docs/unitdore.1 — man page