fuigo

README

fuigo

go install with pre-build steps.

Why

go install cannot run go generate or any pre-build step, so projects that need code generation or a frontend build must either commit generated artifacts or document a multi-step manual build. fuigo is a drop-in go install replacement that runs a module's declared pre-build steps first. It is a temporary solution until Go adds native pre-build support.

Install

go install github.com/sopranoworks/fuigo/cmd/fuigo@latest

Usage

fuigo <package>[@version]

fuigo github.com/sopranoworks/shoka/cmd/shoka@latest

If the target module has a fuigo.yaml at its root, fuigo runs the declared steps before go install. If it does not, fuigo behaves exactly like go install.

Flags:

• --yes — skip the confirmation prompt (for CI)
• --list — show the steps without executing them
• --version — print the fuigo version

fuigo.yaml

A list of pre-build steps, run in order from the module root:

steps:
  - npmgo install --cache-only --lockfile web/package-lock.json
  - esbuild --entry web/src/main.tsx --bundle --outdir server/dist/
  - go generate ./...

Steps must start with one of three commands:

• go — runs the external go tool
• npmgo — installs npm packages (built-in, no Node.js required)
• esbuild — bundles TS/JSX/CSS (built-in)

npmgo and esbuild are compiled into fuigo, so a single go install fuigo gives you npm install + bundling + Go build orchestration. No external commands other than go are ever executed.

Running a step in a subdirectory

A step may be written as a map with a workdir (relative to the module root) instead of a bare string. fuigo runs the command with that directory as its working directory — there is no shell, so cd …&& … does not work. The workdir must stay within the module root.

steps:
  - command: go run .
    workdir: build/frontend
  - go generate ./server/...

How it works

1. Resolve the module version and download its source zip from the Go module proxy (proxy.golang.org) — the same mechanism as go install, no git. Private modules fall back to a git clone.
2. Extract to a temporary directory.
3. Read fuigo.yaml, show the steps, prompt for confirmation.
4. Run the steps, then go install.
5. Clean up the temporary directory.

Security

Steps are defined by the module author, in the repository — the same trust model as go install, which already compiles and runs the module's code. fuigo shows the steps and asks before running them; --yes skips the prompt. Only go, npmgo, and esbuild steps are permitted.

License

MIT © 2026 Sopranoworks, Osamu Takahashi

Documentation

Overview

Package fuigo wraps "go install" with optional pre-build steps. It reads a fuigo.yaml from the target module (fetched from the Go module proxy), runs the declared steps, then delegates to go install. Without a fuigo.yaml it behaves exactly like go install.

Index

• Constants
• func ExecuteSteps(root string, steps []Step, builtins Builtins) error
• func Install(dir, relPkg string) error
• func InstallDir() string
• func ResolveModule(pkg, version string) (srcDir string, resolved string, cleanup func(), err error)
• func Run(opts Options) error
• func SplitModulePath(pkg string) (module, relPkg string)
• type Builtins
  • func DefaultBuiltins(logf func(format string, args ...any)) Builtins
• type Config
  • func LoadConfig(dir string) (*Config, error)
• type Options
• type Step
  • func (s Step) String() string
  • func (s *Step) UnmarshalYAML(value *yaml.Node) error

Constants

const ConfigFile = "fuigo.yaml"

ConfigFile is the name of the per-module configuration file fuigo looks for.

Functions

func ExecuteSteps

func ExecuteSteps(root string, steps []Step, builtins Builtins) error

ExecuteSteps runs each step with root as the module root. A step is dispatched by its first token: "go" runs the external go tool; "npmgo" and "esbuild" invoke the built-in libraries. Any other command is rejected. When a step sets a Workdir it runs in root/Workdir, which must stay within root. Execution stops at the first failing step, returning an error that names it.

func Install

func Install(dir, relPkg string) error

Install delegates to "go install" for the package at relPkg within the module source rooted at dir. relPkg is the package path relative to the module root (e.g. "cmd/shoka"); an empty relPkg installs the module root package. Output is streamed live.

func InstallDir

func InstallDir() string

InstallDir reports the directory go install writes binaries to: GOBIN if set, otherwise GOPATH/bin.

func ResolveModule

func ResolveModule(pkg, version string) (srcDir string, resolved string, cleanup func(), err error)

ResolveModule fetches the source of the module containing pkg at the given version and extracts it to a temporary directory. version may be "", "latest" or an explicit "vX.Y.Z". It returns the extracted source directory, a cleanup function that removes it, and the resolved concrete version.

The primary path downloads a zip from the Go module proxy (no git). If the module is not available on the proxy (e.g. GOPRIVATE repositories) it falls back to a shallow git clone via go-git.

func Run

func Run(opts Options) error

Run resolves the target module, runs any pre-build steps and installs the package. It is the entry point used by the CLI.

func SplitModulePath

func SplitModulePath(pkg string) (module, relPkg string)

SplitModulePath splits a full package import path into its module root and the package path relative to that root. For the common VCS hosts the module root is host/owner/repo; e.g. "github.com/sopranoworks/shoka/cmd/shoka" becomes module "github.com/sopranoworks/shoka" and relPkg "cmd/shoka".

Types

type Builtins

type Builtins struct {
	Npmgo   func(dir string, args []string) error
	Esbuild func(dir string, args []string) error
	Logf    func(format string, args ...any)
}

Builtins holds the implementations fuigo dispatches built-in steps to. They are injectable so tests can substitute fakes. Logf, when set, receives progress messages; a nil Logf discards them.

func DefaultBuiltins

func DefaultBuiltins(logf func(format string, args ...any)) Builtins

DefaultBuiltins returns Builtins wired to the compiled-in npmgo and esbuild libraries, logging progress through logf.

type Config

type Config struct {
	Steps []Step `yaml:"steps"`
}

Config is the parsed contents of a module's fuigo.yaml.

func LoadConfig

func LoadConfig(dir string) (*Config, error)

LoadConfig reads fuigo.yaml from dir. If the file does not exist it returns (nil, nil): a module without a fuigo.yaml is valid and means "plain go install". Any present config is validated: steps must be non-empty and every step must start with one of the allowed commands.

type Options

type Options struct {
	// Package is the target package path, optionally with an "@version" suffix
	// (e.g. "github.com/sopranoworks/shoka/cmd/shoka@latest").
	Package string
	// Yes skips the confirmation prompt before executing steps.
	Yes bool
	// List prints the pre-build steps without executing anything.
	List bool

	// Logf receives progress messages (without a trailing newline). If nil,
	// messages are discarded.
	Logf func(format string, args ...any)
	// In is the source of the confirmation answer; defaults handled by caller.
	In io.Reader
	// Out is where the confirmation prompt is written.
	Out io.Writer
}

Options configures a Run.

type Step

type Step struct {
	Command string
	Workdir string
}

Step is a single pre-build step. It is either a bare command (string form) or a command plus a workdir (map form). Workdir is a path relative to the module root; an empty Workdir means the module root itself.

func (Step) String

func (s Step) String() string

String renders a step for display, noting the workdir when present.

func (*Step) UnmarshalYAML

func (s *Step) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML accepts a step as either a scalar string ("go generate ./...") or a mapping ({command: ..., workdir: ...}).