scripts

Scripts Directory

This directory contains utility scripts for uptool development and maintenance.

Available Scripts

gen_integrations.go

Purpose: Automatically generates internal/integrations/all/all.go which imports all integration packages.

Why This Exists:

• Go requires explicit imports to trigger init() functions
• Each integration registers itself in its init() function
• Without this, adding a new integration would require manually updating imports
• This script automates the process by scanning for integration packages

How It Works:

1. Scans internal/integrations/ directory
2. Finds all subdirectories containing .go files
3. Excludes special directories (all, hidden directories, test files)
4. Generates all.go with blank imports for each integration
5. Formats the generated code with go/format

Usage:

# Manual execution (from repository root)
go run scripts/gen_integrations.go

# Or via go generate
go generate ./internal/integrations

When to Run:

• After creating a new integration in internal/integrations/<name>/
• After renaming an integration directory
• After deleting an integration
• If internal/integrations/all/all.go is corrupted or missing

Example Output:

// Code generated by scripts/gen_integrations.go. DO NOT EDIT.

// Package all imports all integration packages to trigger their self-registration.
package all

import (
    // Import all integration packages to trigger init() functions
    _ "github.com/santosr2/uptool/internal/integrations/asdf"
    _ "github.com/santosr2/uptool/internal/integrations/helm"
    _ "github.com/santosr2/uptool/internal/integrations/mise"
    _ "github.com/santosr2/uptool/internal/integrations/npm"
    _ "github.com/santosr2/uptool/internal/integrations/precommit"
    _ "github.com/santosr2/uptool/internal/integrations/terraform"
    _ "github.com/santosr2/uptool/internal/integrations/tflint"
)

Integration Registration Pattern:

Each integration package has an init() function that registers itself:

// internal/integrations/myintegration/myintegration.go
package myintegration

import "github.com/santosr2/uptool/internal/integrations"

func init() {
    integrations.Register("myintegration", func() engine.Integration {
        return New()
    })
}

Automatic Execution:

The script is configured to run via //go:generate directive in internal/integrations/registry.go:

//go:generate go run ../../scripts/gen_integrations.go

Run all generators with:

go generate ./...

Error Handling:

The script will fail if:

• go.mod is not found (not in repository root)
• internal/integrations/ directory doesn't exist
• No integration packages are found
• Generated code fails to format

Development Workflow:

1. Create new integration:

   mkdir -p internal/integrations/myintegration
   # Add myintegration.go with init() function
   

2. Run generator:

   go generate ./internal/integrations
   

3. Verify:

   cat internal/integrations/all/all.go
   # Should include your new integration
   

4. Build and test:

   mise run build
   ./dist/uptool list
   # Should show your integration
   

Troubleshooting:

Problem: "No integrations found"

• Ensure integration directory contains .go files (not just _test.go)
• Directory name should not start with . or _
• Directory should not be named all

Problem: "Generated code won't compile"

• Check that integration package has valid Go code
• Verify module path in go.mod matches modulePath constant
• Run go mod tidy

Problem: "Integration not registering"

• Ensure integration package has init() function
• Verify init() calls integrations.Register()
• Check that internal/integrations/all is imported somewhere
• Import it with blank identifier: _ "github.com/santosr2/uptool/internal/integrations/all"

Future Scripts

As the project grows, additional scripts may be added:

• gen_docs.sh - Generate API documentation
• check_versions.sh - Verify version consistency across files
• validate_integrations.sh - Validate integrations.yaml against code
• build_releases.sh - Build binaries for multiple platforms

Contributing Scripts

When adding new scripts:

1. Documentation: Add clear comments and usage instructions
2. Error Handling: Exit with non-zero status on errors
3. Idempotent: Scripts should be safe to run multiple times
4. Repository Root: Scripts should work from repository root
5. Dependencies: Document any external tool dependencies
6. Testing: Test scripts on clean repository clone

Script Conventions

Naming:

• Go scripts: gen_*.go (generators), check_*.go (validators)
• Shell scripts: *.sh with executable permissions

Error Messages:

• Write errors to stderr: fmt.Fprintf(os.Stderr, "Error: %v\n", err)
• Exit with status 1 on failure: os.Exit(1)

Output:

• Normal output to stdout
• Progress messages to stdout
• Errors to stderr

Location:

• Executable from repository root
• Use findRepoRoot() pattern to locate repository
• Change to repository root before executing logic

See Also

• Contributing Guide - Development workflow
• Adding Integrations - Integration development
• Go Generate - Official Go blog post