Cli

The CLI is organized under root.go with these main command groups:

Hidden Internal Commands Policy

CRITICAL: All invowk internal * commands MUST remain hidden.

&cobra.Command{
    Use:    "internal",
    Hidden: true,  // ALWAYS true for internal commands
}

Rules:

• Internal commands are for inter-process communication and subprocess execution
• Do NOT document in website docs
• Only mention in .agents/ and README.md
• Used by container runtime, SSH server, TUI server internals

Current internal commands:

• invowk internal exec-virtual — Runs virtual shell in subprocess context
• invowk internal check-cmd <name> — Returns exit 0 if command is discoverable, exit 1 otherwise. Used by runtime-level cmds dependency validation inside containers to verify auto-provisioning worked.

Dynamic Command Registration

The discovery → registration flow (cmd_discovery.go):

Discovery → Validation → Command Registration
                ↓
        DiscoveredCommandSet
         ├── Commands: all discovered
         ├── AmbiguousNames: conflicts
         └── SourceOrder: sorted sources

Startup Gate (Important)

Dynamic registration must stay lazy for startup-sensitive paths.

• Register discovered commands only when argv targets the cmd subtree (or completion requests for it).
• Do not trigger discovery registration for unrelated root paths like --version or --help.
• This keeps non-cmd startup latency low while preserving full invowk cmd behavior.

Transparent Namespace

Unambiguous commands are registered under their SimpleName:

# Only one source defines "build" → user can run directly
invowk cmd build

# Multiple sources define "deploy" → requires disambiguation
invowk cmd @foo deploy      # Using @source prefix
invowk cmd --ivk-from foo deploy  # Using --ivk-from flag

Hierarchical Tree Building

Multi-word commands (e.g., "deploy staging") are built into a command tree with automatically created parent commands.

TUI Component Wrapper Pattern

All TUI components follow a dual-layer delegation pattern (tui_*.go):

func runTuiInput(cmd *cobra.Command, args []string) error {
    // Layer 1: Check if running under parent TUI server
    if client := tuiserver.NewClientFromEnv(); client != nil {
        // Delegate to parent TUI server via HTTP/IPC
        result, err := client.Input(tuiserver.InputRequest{...})
        return handleResult(result)
    }

    // Layer 2: Direct TUI rendering
    result, err := tui.Input(tui.InputOptions{...})
    return handleResult(result)
}

Available TUI Commands

Benefits:

• Commands work both standalone and nested in TUI server
• Output to stdout for piping/variable assignment
• Consistent behavior across execution contexts

Discovery → Runtime → Execution Flow

The execution is decomposed into a pipeline of focused methods on commandsvc.Service (internal/app/commandsvc/service.go), with runtime selection and context construction delegated to internal/app/execute/:

commandService.Execute(ctx, req)
    │
    ├── discoverCommand()       ← Uses req.ResolvedCommand when provided by CLI/disambiguation path;
    │                              otherwise loads config and calls s.discovery.GetCommand(ctx, name)
    │
    ├── resolveDefinitions()    ← Resolves flag/arg defs with fallbacks
    │
    ├── validateInputs()        ← Validates flags, args, platform compatibility
    │
    ├── resolveRuntime()        ← Delegates to appexec.ResolveRuntime() (3-tier precedence),
    │                              wraps errors as ServiceError
    │
    ├── ensureSSHIfNeeded()     ← Conditional SSH server start for container host access
    │
    ├── buildExecContext()      ← Delegates to appexec.BuildExecutionContext() for env var projection
    │                              (includes INVOWK_CMD_NAME, INVOWK_RUNTIME, INVOWK_SOURCE, INVOWK_PLATFORM)
    │
    ├── [DRY-RUN SHORT-CIRCUIT] ← If req.DryRun: renderDryRun() and return (no execution)
    │
    └── dispatchExecution()     ← Calls runtime.BuildRegistry(), then executes pipeline:
        ├── Container init fail-fast (via runtimeRegistryResult.ContainerInitErr)
        ├── Timeout validation (parse-only, fail-fast on invalid strings)
        ├── Timeout wrapping (context.WithTimeout)
        ├── Dependency validation (validateAndRenderDeps)
        ├── Interactive mode (alternate screen + TUI server) OR standard execution
        └── Error classification via classifyExecutionError()

Error Classification Pipeline

classifyExecutionError() (internal/app/commandsvc/errors.go) maps runtime errors to issue catalog IDs using type-safe errors.Is() chains:

switch {
case errors.Is(err, container.ErrNoEngineAvailable):  → ContainerEngineNotFoundId
case errors.Is(err, runtime.ErrRuntimeNotAvailable):  → RuntimeNotAvailableId
case errors.Is(err, os.ErrPermission):                → PermissionDeniedId
default (ActionableError "find shell"):               → ShellNotFoundId