runtime

type AgentLister interface {
	// ListAgents returns the names of all agents supported by this runtime.
	// Returns an empty slice if no agents are configured.
	ListAgents() ([]string, error)
}

type ConfigTransformer interface {
	TransformConfig(config *workspace.WorkspaceConfiguration) error
}

type CreateParams struct {
	// Name is the human-readable name for the instance.
	Name string

	// SourcePath is the absolute path to the workspace source directory.
	SourcePath string

	// WorkspaceConfig is the workspace configuration (optional, can be nil if no configuration exists).
	WorkspaceConfig *workspace.WorkspaceConfiguration

	// Agent is the agent name for loading agent-specific configuration (required, cannot be empty).
	Agent string

	// AgentSettings contains the agent settings files to embed into the agent user's
	// home directory in the workspace image. Keys are relative file paths using
	// forward slashes (e.g., ".claude/settings.json"), values are file contents.
	// This map can be nil or empty if no default settings are configured.
	AgentSettings map[string][]byte

	// OnecliSecrets contains pre-mapped OneCLI secret definitions to provision
	// when the workspace is first started. These are created by the manager from
	// workspace configuration secrets. Can be nil or empty.
	OnecliSecrets []onecli.CreateSecretInput

	// SecretEnvVars maps environment variable names to placeholder values.
	// These are derived from secret service definitions (e.g. GH_TOKEN, GITHUB_TOKEN
	// for the "github" secret type) and injected into the workspace container so
	// that CLI tools detect a configured credential. Real auth goes through OneCLI proxy.
	SecretEnvVars map[string]string

	// WorkspaceConfigDir is the directory containing the workspace configuration file.
	// Used to resolve relative paths for local devcontainer features (e.g. "./my-feature").
	// Can be empty if no workspace configuration exists.
	WorkspaceConfigDir string

	// ProjectID is the project identifier used to load per-project workspace
	// configuration (e.g. network policy) during subsequent Start() calls.
	ProjectID string

	// RuntimeOptions contains runtime-specific flag values collected from
	// the CLI. Keys are flag names (matching FlagDef.Name), values are the
	// user-provided strings. This map is nil when no runtime flags were set.
	RuntimeOptions map[string]string
}

type Dashboard interface {
	// GetURL returns the dashboard URL for the given runtime instance ID.
	// The instance is guaranteed to be running when this method is called.
	// Returns an error if the dashboard URL cannot be determined.
	GetURL(ctx context.Context, instanceID string) (string, error)
}

type FlagDef struct {
	// Name is the flag name (e.g., "openshell-driver").
	Name string

	// Usage is the help text shown for the flag.
	Usage string

	// Completions is an optional list of static values for shell completion.
	Completions []string
}

type FlagProvider interface {
	Flags() []FlagDef
}

type Registry interface {
	// Register adds a runtime to the registry.
	// Returns an error if a runtime with the same type is already registered.
	Register(runtime Runtime) error

	// Get retrieves a runtime by type.
	// Returns ErrRuntimeNotFound if the runtime type is not registered.
	Get(runtimeType string) (Runtime, error)

	// List returns all registered runtime types.
	List() []string
}

type Runtime interface {
	// Type returns the runtime type identifier (e.g., "podman", "docker", "process", "fake").
	Type() string

	// WorkspaceSourcesPath returns the path where sources will be mounted inside the workspace.
	// This is a constant for each runtime type and doesn't require an instance to exist.
	WorkspaceSourcesPath() string

	// Create creates a new runtime instance without starting it.
	// Returns RuntimeInfo with the assigned instance ID and initial state.
	Create(ctx context.Context, params CreateParams) (RuntimeInfo, error)

	// Start starts a previously created runtime instance.
	// Returns updated RuntimeInfo with running state.
	Start(ctx context.Context, id string) (RuntimeInfo, error)

	// Stop stops a running runtime instance without removing it.
	// The instance can be started again later.
	Stop(ctx context.Context, id string) error

	// Remove removes a runtime instance and cleans up all associated resources.
	// The instance must be stopped before removal.
	Remove(ctx context.Context, id string) error

	// Info retrieves current information about a runtime instance.
	Info(ctx context.Context, id string) (RuntimeInfo, error)
}

type RuntimeInfo struct {
	// ID is the runtime-assigned instance identifier.
	ID string

	// State is the current runtime state.
	State api.WorkspaceState

	// Info contains runtime-specific metadata as key-value pairs.
	// Examples: container_id, pid, created_at, network addresses.
	Info map[string]string
}

type SecretServiceRegistryAware interface {
	SetSecretServiceRegistry(secretservice.Registry)
}

type StorageAware interface {
	// Initialize is called during registration with the runtime's private storage directory.
	// The directory is created before this method is called and is guaranteed to exist.
	// The path will be: REGISTRY_STORAGE/runtimeType
	//
	// Runtimes should store the directory path and use it for persisting private data.
	// This method is called exactly once during registration, before the runtime is available for use.
	Initialize(storageDir string) error
}

type Terminal interface {
	// Terminal starts an interactive terminal session inside a running instance.
	// The command is executed with stdin/stdout/stderr connected directly to the user's terminal.
	// Returns an error if the instance is not running or command execution fails.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout
	//   - instanceID: The runtime instance identifier
	//   - agent: The agent name for loading agent-specific configuration
	//   - command: The command to execute (e.g., ["bash"], ["claude-code", "--debug"]).
	//              If empty, the runtime will use the agent's configured terminal command.
	Terminal(ctx context.Context, instanceID string, agent string, command []string) error
}