engine_constants.go

package constants

// EngineName represents an AI engine name identifier (copilot, claude, codex, custom).
// This semantic type distinguishes engine names from arbitrary strings,
// making engine selection explicit and type-safe.
//
// Example usage:
//
//	const CopilotEngine EngineName = "copilot"
//	func SetEngine(engine EngineName) error { ... }
type EngineName string

// Agentic engine name constants using EngineName type for type safety
const (
	// CopilotEngine is the GitHub Copilot engine identifier
	CopilotEngine EngineName = "copilot"
	// ClaudeEngine is the Anthropic Claude engine identifier
	ClaudeEngine EngineName = "claude"
	// CodexEngine is the OpenAI Codex engine identifier
	CodexEngine EngineName = "codex"
	// GeminiEngine is the Google Gemini engine identifier
	GeminiEngine EngineName = "gemini"
	// OpenCodeEngine is the OpenCode engine identifier
	OpenCodeEngine EngineName = "opencode"

	// DefaultEngine is the default agentic engine used when no engine is explicitly specified.
	// Currently defaults to CopilotEngine.
	DefaultEngine EngineName = CopilotEngine
)

// AgenticEngines lists all supported agentic engine names.
// Deprecated: Use workflow.NewEngineCatalog(workflow.NewEngineRegistry()).IDs() for a
// catalog-derived list. This slice is maintained for backward compatibility and must
// stay in sync with the built-in engines registered in NewEngineCatalog.
var AgenticEngines = []string{string(ClaudeEngine), string(CodexEngine), string(CopilotEngine), string(GeminiEngine), string(OpenCodeEngine)}

// EngineOption represents a selectable AI engine with its display metadata and secret configuration
type EngineOption struct {
	Value              string
	Label              string
	Description        string
	SecretName         string   // The name of the secret required for this engine (e.g., "COPILOT_GITHUB_TOKEN")
	AlternativeSecrets []string // Alternative secret names that can also be used for this engine
	EnvVarName         string   // Alternative environment variable name if different from SecretName (optional)
	KeyURL             string   // URL where users can obtain their API key/token (may be empty if not applicable)
	WhenNeeded         string   // Human-readable description of when this secret is needed
}

// EngineOptions provides the list of available AI engines for user selection.
// Each entry includes secret metadata used by the interactive add wizard.
// Must stay in sync with the built-in engines registered in workflow.NewEngineCatalog;
// the TestEngineCatalogMatchesSchema test in pkg/workflow catches catalog/schema drift.
var EngineOptions = []EngineOption{
	{
		Value:       string(CopilotEngine),
		Label:       "GitHub Copilot",
		Description: "GitHub Copilot CLI with agent support",
		SecretName:  "COPILOT_GITHUB_TOKEN",
		KeyURL:      "https://github.com/settings/personal-access-tokens/new",
		WhenNeeded:  "Copilot workflows (CLI, engine, agent tasks, etc.)",
	},
	{
		Value:              string(ClaudeEngine),
		Label:              "Claude",
		Description:        "Anthropic Claude Code coding agent",
		SecretName:         "ANTHROPIC_API_KEY",
		AlternativeSecrets: []string{},
		KeyURL:             "https://console.anthropic.com/settings/keys",
		WhenNeeded:         "Claude engine workflows",
	},
	{
		Value:              string(CodexEngine),
		Label:              "Codex",
		Description:        "OpenAI Codex/GPT engine",
		SecretName:         "OPENAI_API_KEY",
		AlternativeSecrets: []string{"CODEX_API_KEY"},
		KeyURL:             "https://platform.openai.com/api-keys",
		WhenNeeded:         "Codex/OpenAI engine workflows",
	},
	{
		Value:       string(GeminiEngine),
		Label:       "Gemini",
		Description: "Google Gemini CLI coding agent",
		SecretName:  "GEMINI_API_KEY",
		KeyURL:      "https://aistudio.google.com/app/apikey",
		WhenNeeded:  "Gemini engine workflows",
	},
	{
		Value:              string(OpenCodeEngine),
		Label:              "OpenCode",
		Description:        "OpenCode multi-provider AI coding agent (BYOK)",
		SecretName:         "ANTHROPIC_API_KEY",
		AlternativeSecrets: []string{"OPENAI_API_KEY", "GOOGLE_API_KEY"},
		KeyURL:             "https://opencode.ai/docs/get-started/",
		WhenNeeded:         "OpenCode engine workflows (default: Anthropic provider)",
	},
}

// SystemSecretSpec describes a system-level secret that is not engine-specific
type SystemSecretSpec struct {
	Name        string
	WhenNeeded  string
	Description string
	Optional    bool
}

// SystemSecrets defines system-level secrets that are not tied to a specific engine
var SystemSecrets = []SystemSecretSpec{
	{
		Name:        "GH_AW_GITHUB_TOKEN",
		WhenNeeded:  "Enables the use of a user identity for GitHub write operations (instead of github-actions identity); may enable cross-repo project ops; may permit use of remote GitHub MCP tools",
		Description: "Fine-grained or classic PAT with contents/issues/pull-requests read+write and other necessary permissions on the repos gh-aw will read or write.",
		Optional:    true,
	},
	{
		Name:        "GH_AW_AGENT_TOKEN",
		WhenNeeded:  "Assigning agents/bots to issues or pull requests",
		Description: "PAT for agent assignment with issues and pull-requests write on the repos where agents act.",
		Optional:    true,
	},
	{
		Name:        "GH_AW_GITHUB_MCP_SERVER_TOKEN",
		WhenNeeded:  "Isolating MCP server permissions (advanced, optional)",
		Description: "Optional read-mostly token for the GitHub MCP server when you want different scopes than GH_AW_GITHUB_TOKEN.",
		Optional:    true,
	},
}

// GetEngineOption returns the EngineOption for the given engine value, or nil if not found
func GetEngineOption(engineValue string) *EngineOption {
	for i := range EngineOptions {
		if EngineOptions[i].Value == engineValue {
			return &EngineOptions[i]
		}
	}
	return nil
}

// GetAllEngineSecretNames returns all unique secret names across all configured engines.
// This includes primary secrets, alternative secrets, and system-level secrets.
// The returned slice contains no duplicates.
func GetAllEngineSecretNames() []string {
	seen := make(map[string]bool)
	var secrets []string

	// Add primary and alternative secrets from all engines
	for _, opt := range EngineOptions {
		if opt.SecretName != "" && !seen[opt.SecretName] {
			seen[opt.SecretName] = true
			secrets = append(secrets, opt.SecretName)
		}
		for _, alt := range opt.AlternativeSecrets {
			if alt != "" && !seen[alt] {
				seen[alt] = true
				secrets = append(secrets, alt)
			}
		}
	}

	// Add system-level secrets from SystemSecrets
	for _, s := range SystemSecrets {
		if s.Name != "" && !seen[s.Name] {
			seen[s.Name] = true
			secrets = append(secrets, s.Name)
		}
	}

	return secrets
}

// Environment variable names for model configuration
const (
	// EnvVarModelAgentCopilot configures the default Copilot model for agent execution
	EnvVarModelAgentCopilot = "GH_AW_MODEL_AGENT_COPILOT"
	// EnvVarModelAgentClaude configures the default Claude model for agent execution
	EnvVarModelAgentClaude = "GH_AW_MODEL_AGENT_CLAUDE"
	// EnvVarModelAgentCodex configures the default Codex model for agent execution
	EnvVarModelAgentCodex = "GH_AW_MODEL_AGENT_CODEX"
	// EnvVarModelAgentCustom configures the default Custom model for agent execution
	EnvVarModelAgentCustom = "GH_AW_MODEL_AGENT_CUSTOM"
	// EnvVarModelAgentGemini configures the default Gemini model for agent execution
	EnvVarModelAgentGemini = "GH_AW_MODEL_AGENT_GEMINI"
	// EnvVarModelDetectionCopilot configures the default Copilot model for detection
	EnvVarModelDetectionCopilot = "GH_AW_MODEL_DETECTION_COPILOT"
	// EnvVarModelDetectionClaude configures the default Claude model for detection
	EnvVarModelDetectionClaude = "GH_AW_MODEL_DETECTION_CLAUDE"
	// EnvVarModelDetectionCodex configures the default Codex model for detection
	EnvVarModelDetectionCodex = "GH_AW_MODEL_DETECTION_CODEX"
	// EnvVarModelDetectionGemini configures the default Gemini model for detection
	EnvVarModelDetectionGemini = "GH_AW_MODEL_DETECTION_GEMINI"
	// EnvVarModelAgentOpenCode configures the default OpenCode model for agent execution
	EnvVarModelAgentOpenCode = "GH_AW_MODEL_AGENT_OPENCODE"
	// EnvVarModelDetectionOpenCode configures the default OpenCode model for detection
	EnvVarModelDetectionOpenCode = "GH_AW_MODEL_DETECTION_OPENCODE"

	// CopilotCLIModelEnvVar is the native environment variable name supported by the Copilot CLI
	// for selecting the model. Setting this env var is equivalent to passing --model to the CLI.
	CopilotCLIModelEnvVar = "COPILOT_MODEL"

	// CopilotCLIIntegrationIDEnvVar is the native environment variable name supported by the Copilot CLI
	// for identifying the calling integration. This tells the Copilot CLI that it is being invoked
	// by agentic workflows.
	CopilotCLIIntegrationIDEnvVar = "GITHUB_COPILOT_INTEGRATION_ID"

	// CopilotCLIIntegrationIDValue is the value of the integration ID for agentic workflows.
	CopilotCLIIntegrationIDValue = "agentic-workflows"

	// ClaudeCLIModelEnvVar is the native environment variable name supported by the Claude Code CLI
	// for selecting the model. Setting this env var is equivalent to passing --model to the CLI.
	ClaudeCLIModelEnvVar = "ANTHROPIC_MODEL"

	// GeminiCLIModelEnvVar is the native environment variable name supported by the Gemini CLI
	// for selecting the model. Setting this env var is equivalent to passing --model to the CLI.
	GeminiCLIModelEnvVar = "GEMINI_MODEL"

	// OpenCodeCLIModelEnvVar is the native environment variable name for OpenCode model selection.
	// OpenCode uses provider/model format (e.g., "anthropic/claude-sonnet-4-20250514").
	OpenCodeCLIModelEnvVar = "OPENCODE_MODEL"

	// Common environment variable names used across all engines

	// EnvVarPrompt is the path to the workflow prompt file
	EnvVarPrompt = "GH_AW_PROMPT"

	// EnvVarMCPConfig is the path to the MCP configuration file
	EnvVarMCPConfig = "GH_AW_MCP_CONFIG"

	// EnvVarSafeOutputs is the safe-outputs configuration JSON
	EnvVarSafeOutputs = "GH_AW_SAFE_OUTPUTS"

	// EnvVarMaxTurns is the maximum number of turns for agent execution
	EnvVarMaxTurns = "GH_AW_MAX_TURNS"

	// EnvVarStartupTimeout is the tool startup timeout in seconds
	EnvVarStartupTimeout = "GH_AW_STARTUP_TIMEOUT"

	// EnvVarToolTimeout is the tool execution timeout in seconds
	EnvVarToolTimeout = "GH_AW_TOOL_TIMEOUT"

	// EnvVarGitHubToken is the GitHub token for repository access
	EnvVarGitHubToken = "GH_AW_GITHUB_TOKEN"

	// EnvVarGitHubBlockedUsers is the fallback variable for the tools.github.blocked-users guard policy field.
	// When blocked-users is not explicitly set in the workflow frontmatter, this variable is used as
	// a comma- or newline-separated list of GitHub usernames to block. Set as an org or repo variable
	// to apply a consistent block list across all workflows.
	EnvVarGitHubBlockedUsers = "GH_AW_GITHUB_BLOCKED_USERS"

	// EnvVarGitHubApprovalLabels is the fallback variable for the tools.github.approval-labels guard policy field.
	// When approval-labels is not explicitly set in the workflow frontmatter, this variable is used as
	// a comma- or newline-separated list of GitHub label names that promote content to "approved" integrity.
	// Set as an org or repo variable to apply a consistent approval label list across all workflows.
	EnvVarGitHubApprovalLabels = "GH_AW_GITHUB_APPROVAL_LABELS"

	// EnvVarGitHubTrustedUsers is the fallback variable for the tools.github.trusted-users guard policy field.
	// When trusted-users is not explicitly set in the workflow frontmatter, this variable is used as
	// a comma- or newline-separated list of GitHub usernames elevated to "approved" integrity.
	// Set as an org or repo variable to apply a consistent trusted user list across all workflows.
	EnvVarGitHubTrustedUsers = "GH_AW_GITHUB_TRUSTED_USERS"
)

// CopilotStemCommands defines commands that Copilot CLI treats as "stem" commands
// (commands with subcommand matching via tree-sitter). When these appear in bash
// tool lists without an explicit `:*` wildcard, the compiler automatically appends
// `:*` to ensure proper permission matching for all subcommands.
//
// For example, `bash: ["dotnet"]` compiles to `--allow-tool shell(dotnet:*)` so that
// "dotnet build", "dotnet test", etc. are all permitted.
//
// This list must be kept in sync with the stem configurations in Copilot CLI's
// shell command parser (tree-sitter based).
//
// NOTE: Network tools like curl and wget are also included here because the Copilot CLI
// treats them as stem commands — shell(curl) only matches a bare "curl" invocation with
// no arguments. Using shell(curl:*) ensures that "curl -s ...", "curl --max-time 30 ...",
// etc. are all permitted when bash: ["curl"] is specified.
var CopilotStemCommands = map[string]bool{
	"git": true, "gh": true, "glab": true,
	"npm": true, "npx": true, "yarn": true, "pnpm": true,
	"cargo": true, "go": true,
	"composer": true, "pip": true, "pipenv": true, "poetry": true, "conda": true,
	"mvn": true, "gradle": true, "gradlew": true,
	"dotnet": true,
	"bundle": true, "swift": true, "sbt": true, "flutter": true,
	"mix": true, "cabal": true, "stack": true,
	"curl": true, "wget": true,
}