afcli

Documentation

Overview

Package afcli provides Cobra command factories for the Donmai CLI. Downstream projects can import this package and call RegisterCommands to add the shared donmai subcommands to their own root command.

Package afcli exports.go — public factory functions for the four daemon-targeted command trees (provider, kit, workarea, routing).

Most afcli factories stay unexported and reach root via RegisterCommands. The four daemon-targeted families need public factories so downstream binaries can graft them under their own parent commands (e.g. `rensei host provider`, `rensei host kit`, `rensei host workarea`) without re-implementing the surface.

The factories return a fresh *cobra.Command tree on each call so callers can attach the same logical surface under multiple parents (e.g. both at top-level via RegisterCommands and nested under `host`) without sharing mutable command state.

All four trees target the local daemon's HTTP control API per ADR-2026-05-07-daemon-http-control-api.md. They never hit the SaaS platform and never attach an Authorization header (D2 — localhost-only). The ds argument is accepted for signature consistency with the rest of afcli but is unused — daemon-targeted commands resolve their client via DONMAI_DAEMON_URL or the 127.0.0.1:7734 default.

Package afcli kit.go — `donmai kit …` Cobra commands. The commands target the local daemon's HTTP control API at /api/daemon/kits* and /api/daemon/kit-sources* per ADR-2026-05-07-daemon-http-control-api.md § D1; they NEVER hit the SaaS platform and never attach an Authorization header (D2 — localhost-only).

Package afcli provider.go — `donmai provider …` Cobra commands. The commands target the local daemon's HTTP control API at /api/daemon/providers* per ADR-2026-05-07-daemon-http-control-api.md §D1; they NEVER hit the SaaS platform and never attach an Authorization header (D2 — localhost-only).

Package afcli routing.go — `donmai routing …` Cobra commands. The commands target the local daemon's HTTP control API at /api/daemon/routing/* per ADR-2026-05-07-daemon-http-control-api.md §D1; they NEVER hit the SaaS platform and never attach an Authorization header (D2 — localhost-only).

Package afcli workarea.go — `donmai workarea …` Cobra commands. The commands target the local daemon's HTTP control API at /api/daemon/workareas* per ADR-2026-05-07-daemon-http-control-api.md §D1 + §D4a; they NEVER hit the SaaS platform and never attach an Authorization header (D2 — localhost-only).

Index

• Constants
• func BuildAgentRunRegistry(logger *slog.Logger) *runner.Registry
• func NewKitCmd(ds func() afclient.DataSource) *cobra.Command
• func NewProviderCmd(ds func() afclient.DataSource) *cobra.Command
• func NewRoutingCmd(ds func() afclient.DataSource) *cobra.Command
• func NewWorkareaCmd(ds func() afclient.DataSource) *cobra.Command
• func RegisterCommands(root *cobra.Command, cfg Config)
• type AnalysisResult
• type BranchCleanResult
• type BranchError
• type CleanupResult
• type Config
• type DraftedIssue
• type PatternMatch
• type WorktreeError
• type WorktreeResult

Constants

const DefaultAgentRunDaemonURL = "http://127.0.0.1:7734"

DefaultAgentRunDaemonURL is the local control HTTP address the daemon binds to (127.0.0.1:7734). The `donmai agent run` subcommand fetches its session detail from <DefaultAgentRunDaemonURL>/api/daemon/sessions/<id>.

Functions

func BuildAgentRunRegistry

func BuildAgentRunRegistry(logger *slog.Logger) *runner.Registry

BuildAgentRunRegistry constructs the runner.Registry of the providers compiled into this binary — the SINGLE SOURCE for the agent-run provider set. It is the public, importable entry point downstream Go binaries (e.g. the closed-source `rensei` TUI) call so they do NOT have to fork the hand-authored ctor list; calling this builder keeps every embedder on the exact same eight providers donmai resolves, eliminating the documented fork-rot between donmai and rensei-tui.

Stub is always registered; the others register on best-effort (their probes return errors when the underlying CLI / app-server / API key is missing — we log + skip rather than fail the whole worker so a misconfigured host does not silently lose stub-mode smoke runs).

Each spawned `donmai agent run` builds its own Registry — providers are stateless modulo codex's app-server, and that app-server is a per-process singleton that gets a fresh start on every spawn. Sharing a single registry across daemon-life sessions would force lifecycle coupling we explicitly want to avoid (per F.1.1 §7 + the F.2.8 task guidance).

Probe-failure visibility (REN-1462 / v0.5.1): every provider construction or registration failure logs at WARN with the provider name and underlying error so operators can see at a glance which providers are available on this host. If the resulting registry has zero providers, an ERROR-level log fires — that is a fatal misconfiguration and any subsequent runner.Run will fail because no provider can resolve.

Foundation-runtime-stubs adds three more probe-and-skip entries (REN-1499 amp, REN-1500 gemini, REN-1501 opencode). Each follows the same warn-and-skip contract as claude / codex: if the constructor returns ErrProviderUnavailable (no API key, server unreachable) the registry build logs WARN and proceeds without that provider, identical to the existing probe-failure path.

The ctor list below is the single hand-authored source of the agent-run provider set. It is deliberately NOT matrix-generated: each provider's New constructor takes a distinct, package-local Options type (and stub is variadic), so a generated closure could only re-emit these same per-package New(Options{}) call sites verbatim — adding codegen surface for zero single-sourcing gain. Keeping it here, behind a public builder, is the clean realization of "single source + no fork".

func NewKitCmd

func NewKitCmd(ds func() afclient.DataSource) *cobra.Command

NewKitCmd returns a fresh `kit` Cobra command tree (list, show, install, enable, disable, verify, sources) targeting the local daemon. See kit.go for per-subcommand documentation.

func NewProviderCmd

func NewProviderCmd(ds func() afclient.DataSource) *cobra.Command

NewProviderCmd returns a fresh `provider` Cobra command tree (list, show) targeting the local daemon. See provider.go for per-subcommand documentation.

func NewRoutingCmd

func NewRoutingCmd(ds func() afclient.DataSource) *cobra.Command

NewRoutingCmd returns a fresh `routing` Cobra command tree (show, explain) targeting the local daemon. See routing.go for per-subcommand documentation.

func NewWorkareaCmd

func NewWorkareaCmd(ds func() afclient.DataSource) *cobra.Command

NewWorkareaCmd returns a fresh `workarea` Cobra command tree (list, show, restore, diff) targeting the local daemon. See workarea.go for per-subcommand documentation.

func RegisterCommands

func RegisterCommands(root *cobra.Command, cfg Config)

RegisterCommands adds the shared Donmai subcommands to the given root command. Optional local/debug surfaces are controlled by Config. The commands use cfg to resolve API clients and defaults.

This is the primary integration point for downstream CLIs that want to embed Donmai functionality under their own root command (e.g. `mycli agent list`, `mycli daemon status`, etc.).

Types

type AnalysisResult

type AnalysisResult struct {
	LinesScanned  int            `json:"linesScanned"`
	ErrorLines    int            `json:"errorLines"`
	Matches       []PatternMatch `json:"matches"`
	DraftedIssues []DraftedIssue `json:"draftedIssues"`
	AnalyzedAt    time.Time      `json:"analyzedAt"`
}

AnalysisResult is the top-level result produced by the analyze command.

type BranchCleanResult

type BranchCleanResult struct {
	Scanned int           `json:"scanned"`
	Deleted int           `json:"deleted"`
	Errors  []BranchError `json:"errors"`
}

BranchCleanResult holds per-branch cleanup stats.

type BranchError

type BranchError struct {
	Branch string `json:"branch"`
	Error  string `json:"error"`
}

BranchError records a failure deleting one branch.

type CleanupResult

type CleanupResult struct {
	DryRun    bool              `json:"dryRun"`
	Worktrees WorktreeResult    `json:"worktrees"`
	Branches  BranchCleanResult `json:"branches"`
}

CleanupResult is the JSON shape emitted by `donmai admin cleanup`.

type Config

type Config struct {
	// ClientFactory returns an afclient.DataSource for API calls.
	// Required.
	ClientFactory func() afclient.DataSource

	// DefaultURLFunc is a lazy URL resolution function (for flag-based callers).
	// Optional. Checked before DefaultURL.
	DefaultURLFunc func() string

	// DefaultURL is the fallback API base URL if DefaultURLFunc is nil.
	DefaultURL string

	// EnableDashboard registers the dashboard command when true.
	EnableDashboard bool

	// EnableLegacyWorkerFleet registers the legacy worker/fleet process
	// commands when true. These commands remain available to the standalone
	// OSS af binary for local debugging, but embedders should usually expose
	// daemon as the host lifecycle surface instead.
	EnableLegacyWorkerFleet bool

	// ProjectFunc returns the active project slug (or ID) used to scope
	// list endpoints that support filtering AND to populate the
	// `X-Rensei-Project` header on every request (see OrgFunc note).
	// Returning an empty string means fleet-wide (no scope), preserving
	// the default behavior. Optional. When nil, all commands behave
	// fleet-wide.
	ProjectFunc func() string

	// OrgFunc returns the active org id (or slug, or WorkOS org id)
	// the embedding binary wants every afcli-imported command to scope
	// to. When non-empty, the value is sent as `X-Rensei-Org` on every
	// HTTP request the wrapped ClientFactory produces.
	//
	// Why this matters: the platform's CLI user-token auth selects the
	// caller's org membership from the WorkOS access token's `org_id`
	// claim, which is frozen to whichever org the user happened to be
	// in at token-mint time. With multiple humans + agents on a single
	// host running across many orgs concurrently, that frozen claim
	// silently misroutes commands to the wrong org. Sending an explicit
	// `X-Rensei-Org` per invocation makes the scope authoritative
	// (after a server-side membership check) and removes the implicit
	// dependency on token state.
	//
	// Optional. When nil OR returns an empty string, no header is
	// sent and the server falls back to its own resolution (single-org
	// users keep working unchanged).
	OrgFunc func() string

	// HostBinaryVersion is the version string the embedding binary
	// reports (typically injected via -ldflags into the main package).
	// When non-empty, `daemon run` passes it to daemon.Options.Version
	// so /api/daemon/status reports the running binary's version
	// instead of donmai's vendored package default. Empty
	// falls back to the daemon package's own Version var.
	HostBinaryVersion string

	// BinaryName is the user-facing binary name to embed in error messages,
	// usage hints, and remediation instructions. Defaults to "donmai" when empty.
	// Embedders (e.g. rensei-tui) set this to "rensei".
	BinaryName string
}

Config controls how af commands are wired into a parent CLI.

type DraftedIssue

type DraftedIssue struct {
	Signature   string   `json:"signature"`
	Title       string   `json:"title"`
	Description string   `json:"description"`
	Labels      []string `json:"labels"`
	// Posted is true when the issue was actually created in Linear.
	Posted     bool   `json:"posted"`
	Identifier string `json:"identifier,omitempty"`
	URL        string `json:"url,omitempty"`
}

DraftedIssue is a Linear issue draft derived from detected patterns.

type PatternMatch

type PatternMatch struct {
	SignatureID string                    `json:"signatureId"`
	Type        logsignatures.PatternType `json:"type"`
	Severity    logsignatures.Severity    `json:"severity"`
	Title       string                    `json:"title"`
	Occurrences int                       `json:"occurrences"`
	Examples    []string                  `json:"examples"`
}

PatternMatch records a single matched line.

type WorktreeError

type WorktreeError struct {
	Path  string `json:"path"`
	Error string `json:"error"`
}

WorktreeError records a failure removing one worktree.

type WorktreeResult

type WorktreeResult struct {
	Scanned  int             `json:"scanned"`
	Orphaned int             `json:"orphaned"`
	Cleaned  int             `json:"cleaned"`
	Skipped  int             `json:"skipped"`
	Errors   []WorktreeError `json:"errors"`
}

WorktreeResult holds per-worktree cleanup stats.