python.go

// Copyright 2022-2026 Salesforce, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package python

import (
	"bytes"
	"context"
	_ "embed"
	"fmt"
	"path/filepath"
	"regexp"
	"runtime"
	"strings"

	"github.com/pelletier/go-toml/v2"
	"github.com/slackapi/slack-cli/internal/hooks"
	"github.com/slackapi/slack-cli/internal/iostreams"
	"github.com/slackapi/slack-cli/internal/shared/types"
	"github.com/slackapi/slack-cli/internal/style"
	"github.com/spf13/afero"
)

//go:embed hooks.json
var hooksJSON []byte

// slackBoltPackageName is the name of the Bolt for Python dependency in requirements.txt
const slackBoltPackageName = "slack-bolt"

const (
	// slackCLIHooksPackageName the name of the Python Hooks dependency in requirements.txt
	slackCLIHooksPackageName = "slack-cli-hooks"

	// slackCLIHooksPackageVersion is the version range of the Python Hooks dependency in requirements.txt
	slackCLIHooksPackageVersion = "<1.0.0"

	// slackCLIHooksPackageSpecifier is the package name and version range of the Python Hooks dependency in requirements.txt
	slackCLIHooksPackageSpecifier = slackCLIHooksPackageName + slackCLIHooksPackageVersion
)

// Python runtime type
type Python struct {
}

// New creates a new Python runtime
func New() *Python {
	return &Python{}
}

// IgnoreDirectories is a list of directories to ignore when packaging the runtime for deployment.
func (p *Python) IgnoreDirectories() []string {
	return []string{}
}

// getVenvPath returns the path to the virtual environment directory
func getVenvPath(projectDirPath string) string {
	return filepath.Join(projectDirPath, ".venv")
}

// getPythonExecutable returns the Python executable name for the current OS
func getPythonExecutable() string {
	if runtime.GOOS == "windows" {
		return "python"
	}
	return "python3"
}

// getVenvBinDir returns the platform-specific bin directory inside a virtual environment
func getVenvBinDir(venvPath string) string {
	if runtime.GOOS == "windows" {
		return filepath.Join(venvPath, "Scripts")
	}
	return filepath.Join(venvPath, "bin")
}

// ActivateVenvIfPresent sets the process environment variables that a Python
// virtual environment's activate script would set, so that child processes
// (hook scripts) inherit the activated venv. This is a no-op when no .venv
// directory exists in projectDir.
//
// The three env vars (VIRTUAL_ENV, PATH, PYTHONHOME) are the stable contract
// defined by PEP 405 (Python 3.3, 2012). Other tools (Poetry, tox, pipx) use
// the same approach. Sourcing the shell-specific activate script (activate,
// activate.fish, Activate.ps1) would be higher maintenance because it varies
// by shell.
func ActivateVenvIfPresent(fs afero.Fs, osClient types.Os, projectDir string) (bool, error) {
	venvPath := getVenvPath(projectDir)
	if !venvExists(fs, venvPath) {
		return false, nil
	}

	binDir := getVenvBinDir(venvPath)

	if err := osClient.Setenv("VIRTUAL_ENV", venvPath); err != nil {
		return false, err
	}
	if err := osClient.Setenv("PATH", binDir+string(filepath.ListSeparator)+osClient.Getenv("PATH")); err != nil {
		return false, err
	}
	if err := osClient.Unsetenv("PYTHONHOME"); err != nil {
		return false, err
	}

	return true, nil
}

// getPipExecutable returns the path to the pip executable in the virtual environment
func getPipExecutable(venvPath string) string {
	if runtime.GOOS == "windows" {
		return filepath.Join(venvPath, "Scripts", "pip.exe")
	}
	return filepath.Join(venvPath, "bin", "pip")
}

// venvExists checks if a virtual environment exists at the given path
func venvExists(fs afero.Fs, venvPath string) bool {
	pipPath := getPipExecutable(venvPath)
	if _, err := fs.Stat(pipPath); err == nil {
		return true
	}
	return false
}

// createVirtualEnvironment creates a Python virtual environment
func createVirtualEnvironment(ctx context.Context, projectDirPath string, hookExecutor hooks.HookExecutor) error {
	hookScript := hooks.HookScript{
		Name:    "CreateVirtualEnvironment",
		Command: fmt.Sprintf("%s -m venv .venv", getPythonExecutable()),
	}
	stdout := bytes.Buffer{}
	hookExecOpts := hooks.HookExecOpts{
		Hook:      hookScript,
		Stdout:    &stdout,
		Directory: projectDirPath,
	}
	_, err := hookExecutor.Execute(ctx, hookExecOpts)
	if err != nil {
		return fmt.Errorf("failed to create virtual environment: %w\nOutput: %s", err, stdout.String())
	}
	return nil
}

// runPipInstall runs pip install with the given arguments.
// The venv does not need to be activated because pip is invoked by its full
// path inside the venv, which ensures packages are installed into the venv's
// site-packages directory.
func runPipInstall(ctx context.Context, venvPath string, projectDirPath string, hookExecutor hooks.HookExecutor, args ...string) (string, error) {
	pipPath := getPipExecutable(venvPath)
	cmdArgs := append([]string{pipPath, "install"}, args...)
	hookScript := hooks.HookScript{
		Name:    "InstallProjectDependencies",
		Command: strings.Join(cmdArgs, " "),
	}
	stdout := bytes.Buffer{}
	hookExecOpts := hooks.HookExecOpts{
		Hook:      hookScript,
		Stdout:    &stdout,
		Directory: projectDirPath,
	}
	_, err := hookExecutor.Execute(ctx, hookExecOpts)
	output := stdout.String()
	if err != nil {
		return output, fmt.Errorf("pip install failed: %w", err)
	}
	return output, nil
}

// installRequirementsTxt handles adding slack-cli-hooks to requirements.txt
func installRequirementsTxt(fs afero.Fs, projectDirPath string) (output string, err error) {
	requirementsFilePath := filepath.Join(projectDirPath, "requirements.txt")

	file, err := afero.ReadFile(fs, requirementsFilePath)
	if err != nil {
		return fmt.Sprintf("Error reading requirements.txt: %s", err), err
	}

	fileData := string(file)

	// Skip when slack-cli-hooks is already declared in requirements.txt
	if containsPackage(fileData, slackCLIHooksPackageName) {
		return fmt.Sprintf("Found requirements.txt with %s", style.Highlight(slackCLIHooksPackageName)), nil
	}

	// Add slack-cli-hooks to requirements.txt
	//
	// Regex finds all lines that match "slack-bolt" including optional version specifier (e.g. slack-bolt==1.21.2)
	re := regexp.MustCompile(fmt.Sprintf(`(%s.*)`, slackBoltPackageName))
	matches := re.FindAllString(fileData, -1)

	if len(matches) > 0 {
		// Inserted under the slack-bolt dependency
		fileData = re.ReplaceAllString(fileData, fmt.Sprintf("$1\n%s", slackCLIHooksPackageSpecifier))
	} else {
		// Insert at bottom of file
		fileData = fmt.Sprintf("%s\n%s", strings.TrimSpace(fileData), slackCLIHooksPackageSpecifier)
	}

	// Save requirements.txt
	err = afero.WriteFile(fs, requirementsFilePath, []byte(fileData), 0644)
	if err != nil {
		return fmt.Sprintf("Error updating requirements.txt: %s", err), err
	}

	return fmt.Sprintf("Updated requirements.txt with %s", style.Highlight(slackCLIHooksPackageSpecifier)), nil
}

// installPyProjectToml handles adding slack-cli-hooks to pyproject.toml
func installPyProjectToml(ctx context.Context, ios iostreams.IOStreamer, fs afero.Fs, projectDirPath string) (output string, err error) {
	pyProjectFilePath := filepath.Join(projectDirPath, "pyproject.toml")

	file, err := afero.ReadFile(fs, pyProjectFilePath)
	if err != nil {
		ios.PrintDebug(ctx, "Warning: could not read pyproject.toml: %s", err)
		return "Skipped updating pyproject.toml because file cannot be read", nil
	}

	fileData := string(file)

	// Check if slack-cli-hooks is already declared
	if containsPackage(fileData, slackCLIHooksPackageName) {
		return fmt.Sprintf("Found pyproject.toml with %s", style.Highlight(slackCLIHooksPackageName)), nil
	}

	// Parse only to validate the file structure
	var config map[string]interface{}
	err = toml.Unmarshal(file, &config)
	if err != nil {
		ios.PrintDebug(ctx, "Warning: could not parse pyproject.toml: %s", err)
		return "Skipped updating pyproject.toml because invalid TOML", nil
	}

	// Verify `project` section and `project.dependencies` array exist
	projectSection, exists := config["project"]
	if !exists {
		ios.PrintDebug(ctx, "Warning: pyproject.toml missing [project] section")
		return "Skipped updating pyproject.toml because project section missing", nil
	}

	projectMap, ok := projectSection.(map[string]interface{})
	if !ok {
		ios.PrintDebug(ctx, "Warning: pyproject.toml [project] section is not a valid format")
		return "Skipped updating pyproject.toml because project section invalid", nil
	}

	if _, exists := projectMap["dependencies"]; !exists {
		ios.PrintDebug(ctx, "Warning: pyproject.toml missing dependencies array in [project] section")
		return "Skipped updating pyproject.toml because dependencies missing", nil
	}

	// Use string manipulation to add the dependency while preserving formatting.
	// This regex matches the dependencies array and its contents, handling both single-line and multi-line formats.
	// Note: This regex may not correctly handle commented-out dependencies arrays or nested brackets in string values.
	// These edge cases are uncommon in practice and the TOML validation above will catch malformed files.
	dependenciesRegex := regexp.MustCompile(`(?s)(dependencies\s*=\s*\[)([^\]]*?)(\])`)
	matches := dependenciesRegex.FindStringSubmatch(fileData)

	if len(matches) == 0 {
		ios.PrintDebug(ctx, "Warning: pyproject.toml dependencies array could not be located")
		return "Skipped updating pyproject.toml because dependencies missing", nil
	}

	prefix := matches[1]  // "...dependencies = ["
	content := matches[2] // array contents
	suffix := matches[3]  // "]..."

	// Always append slack-cli-hooks at the end of the dependencies array.
	// Formatting:
	// - Multi-line arrays get a trailing comma to match Python/TOML conventions
	//   and make future additions cleaner.
	// - Single-line arrays omit the trailing comma for a compact appearance,
	//   which is the typical style for short dependency lists.
	var newContent string
	content = strings.TrimRight(content, " \t\n")
	if !strings.HasSuffix(content, ",") {
		content += ","
	}
	if strings.Contains(content, "\n") {
		// Multi-line format: append with proper indentation and trailing comma
		newContent = content + "\n" + `    "` + slackCLIHooksPackageSpecifier + `",` + "\n"
	} else {
		// Single-line format: append inline without trailing comma
		newContent = content + ` "` + slackCLIHooksPackageSpecifier + `"`
	}

	// Replace the dependencies array content
	fileData = dependenciesRegex.ReplaceAllString(fileData, prefix+newContent+suffix)

	// Save pyproject.toml
	err = afero.WriteFile(fs, pyProjectFilePath, []byte(fileData), 0644)
	if err != nil {
		return fmt.Sprintf("Error updating pyproject.toml: %s", err), err
	}

	return fmt.Sprintf("Updated pyproject.toml with %s", style.Highlight(slackCLIHooksPackageSpecifier)), nil
}

// InstallProjectDependencies creates a virtual environment and installs project dependencies.
func (p *Python) InstallProjectDependencies(ctx context.Context, projectDirPath string, hookExecutor hooks.HookExecutor, ios iostreams.IOStreamer, fs afero.Fs, os types.Os) (output string, err error) {
	var outputs []string
	var errs []error

	// Detect which dependency file(s) exist
	requirementsFilePath := filepath.Join(projectDirPath, "requirements.txt")
	pyProjectFilePath := filepath.Join(projectDirPath, "pyproject.toml")

	hasRequirementsTxt := false
	hasPyProjectToml := false

	if _, err := fs.Stat(requirementsFilePath); err == nil {
		hasRequirementsTxt = true
	}

	if _, err := fs.Stat(pyProjectFilePath); err == nil {
		hasPyProjectToml = true
	}

	// Ensure at least one dependency file exists
	if !hasRequirementsTxt && !hasPyProjectToml {
		err := fmt.Errorf("no Python dependency file found (requirements.txt or pyproject.toml)")
		return fmt.Sprintf("Error: %s", err), err
	}

	// Get virtual environment path
	venvPath := getVenvPath(projectDirPath)

	// Create virtual environment if it doesn't exist
	if !venvExists(fs, venvPath) {
		ios.PrintDebug(ctx, "Creating Python virtual environment")
		if err := createVirtualEnvironment(ctx, projectDirPath, hookExecutor); err != nil {
			outputs = append(outputs, fmt.Sprintf("Error creating virtual environment: %s", err))
			return strings.Join(outputs, "\n"), err
		}
		outputs = append(outputs, fmt.Sprintf("Created virtual environment at %s", style.Highlight(".venv")))
	} else {
		outputs = append(outputs, fmt.Sprintf("Found existing virtual environment at %s", style.Highlight(".venv")))
	}

	// Handle requirements.txt if it exists
	if hasRequirementsTxt {
		output, err := installRequirementsTxt(fs, projectDirPath)
		if output != "" {
			outputs = append(outputs, output)
		}
		if err != nil {
			errs = append(errs, err)
		}
	}

	// Handle pyproject.toml if it exists
	if hasPyProjectToml {
		output, err := installPyProjectToml(ctx, ios, fs, projectDirPath)
		if output != "" {
			outputs = append(outputs, output)
		}
		if err != nil {
			errs = append(errs, err)
		}
	}

	// Install dependencies using pip
	// When both files exist, pyproject.toml is installed first to set up the project package
	// and its declared dependencies. Then requirements.txt is installed second so its version
	// pins take precedence, as it typically serves as the lockfile.
	if hasPyProjectToml {
		ios.PrintDebug(ctx, "Installing dependencies from pyproject.toml")
		pipOutput, err := runPipInstall(ctx, venvPath, projectDirPath, hookExecutor, "-e", ".")
		if err != nil {
			errs = append(errs, err)
			outputs = append(outputs, fmt.Sprintf("Error installing from pyproject.toml: %s\n%s", err, pipOutput))
		} else {
			outputs = append(outputs, fmt.Sprintf("Installed dependencies from %s", style.Highlight("pyproject.toml")))
		}
	}

	if hasRequirementsTxt {
		ios.PrintDebug(ctx, "Installing dependencies from requirements.txt")
		pipOutput, err := runPipInstall(ctx, venvPath, projectDirPath, hookExecutor, "-r", "requirements.txt")
		if err != nil {
			errs = append(errs, err)
			outputs = append(outputs, fmt.Sprintf("Error installing from requirements.txt: %s\n%s", err, pipOutput))
		} else {
			outputs = append(outputs, fmt.Sprintf("Installed dependencies from %s", style.Highlight("requirements.txt")))
		}
	}

	// Return result
	output = strings.Join(outputs, "\n")
	if len(errs) > 0 {
		return output, errs[0]
	}
	return output, nil
}

// Name prints the name of the runtime
func (p *Python) Name() string {
	return "Python"
}

// Version is the runtime version used by the hosted app deployment
func (p *Python) Version() string {
	return "python" // the server interprets this as: always the latest version layer
}

// SetVersion sets the Version value
func (p *Python) SetVersion(version string) {
	// Unsupported
}

// HooksJSONTemplate returns the default hooks.json template
func (p *Python) HooksJSONTemplate() []byte {
	return hooksJSON
}

// PreparePackage will prepare and copy the app in projectDirPath to tmpDirPath as a release-ready bundle.
func (p *Python) PreparePackage(ctx context.Context, sdkConfig hooks.SDKCLIConfig, hookExecutor hooks.HookExecutor, opts types.PreparePackageOpts) error {
	return nil // Unsupported
}

// IsRuntimeForProject returns true if dirPath is a Python project
func IsRuntimeForProject(ctx context.Context, fs afero.Fs, dirPath string, sdkConfig hooks.SDKCLIConfig) bool {
	// Is Python project when app manifest says so
	if strings.HasPrefix(sdkConfig.Runtime, "python") {
		return true
	}

	// Python projects must have a requirements.txt or pyproject.toml in the root dirPath
	var requirementsTxtPath = filepath.Join(dirPath, "requirements.txt")
	if _, err := fs.Stat(requirementsTxtPath); err == nil {
		return true
	}

	var pyProjectTomlPath = filepath.Join(dirPath, "pyproject.toml")
	if _, err := fs.Stat(pyProjectTomlPath); err == nil {
		return true
	}

	return false
}