@putnami/go

Go build tooling, linting, and development utilities for the Putnami ecosystem.

Installation

bun add @putnami/go

Features

This package provides CLI jobs for Go development workflows. All jobs follow a task-based architecture where jobs orchestrate multiple composable tasks. These jobs are project-scoped; workspace-level runs (no project context) are not supported.

Jobs Overview

| Job | Command | Purpose | Documentation | |-----|---------|---------|---------------| | Build | putnami build | Compile Go packages/binaries with cross-compilation | doc/build.md | | Test | putnami test | Run tests with coverage | doc/test.md | | Lint | putnami lint | Lint code using golangci-lint and staticcheck | doc/lint.md | | Serve | putnami serve | Run Go applications as servers | doc/serve.md |

Scope: Project-only. These jobs require a project context (no workspace-level runs).

Quick Examples

Build

bunx putnami build .
bunx putnami build . --target linux/amd64  # Cross-compile
bunx putnami build . --output ./bin/myapp   # Custom output
bunx putnami build . --readonly             # Module readonly mode
bunx putnami build . --gcflags "-N -l"      # Debug compiler flags

Test

bunx putnami test .
bunx putnami test . --coverage             # Generate coverage
bunx putnami test . --coverage --outputdir coverage  # HTML/report output dir
bunx putnami test . --race                # Race detector

Lint

bunx putnami lint . --fix                  # Auto-fix issues
bunx putnami lint . --tool golangci-lint   # Use specific tool
bunx putnami lint . --tool golangci-lint --out-format json  # CI output

Serve

bunx putnami serve .                        # Start server
bunx putnami serve . --port 8080           # Custom port

Architecture

All jobs follow a task-based architecture:

• Jobs orchestrate multiple tasks
• Tasks are composable units of work
• Tasks can be:
  • Skipped via flags
  • Run in parallel when independent
  • Reused across different jobs

See individual job documentation files in the doc/ directory for detailed task information.

Plugin Configuration

Jobs are registered via plugin.json:

{
  "commands": {
    "build": "./build",
    "test": "./test",
    "lint": "./lint",
    "serve": "./serve"
  },
  "jobs": {
    "build": {
      "implementation": "./build",
      "dependsOn": ["^build"],
      "filePatterns": ["**/*.go", "go.mod", "go.sum", "package.json"]
    },
    "test": {
      "implementation": "./test",
      "filePatterns": ["**/*.go", "go.mod", "go.sum", "package.json"]
    },
    "lint": {
      "implementation": "./lint",
      "filePatterns": ["**/*.go", "go.mod", ".golangci.yml", ".golangci.yaml", "package.json"]
    },
    "serve": {
      "implementation": "./serve",
      "dependsOn": ["build"],
      "filePatterns": ["**/*.go", "go.mod", "go.sum", "package.json"],
      "cache": false
    }
  }
}

Documentation

Each job has its own detailed documentation file:

• build.md - Build job with cross-compilation support
• test.md - Test job with coverage and JSON output parsing
• lint.md - Lint job with golangci-lint and staticcheck
• serve.md - Serve job for running Go servers

Each documentation file includes:

• Job purpose and execution flow
• Detailed task documentation
• Available options
• Usage examples

License

Putnami License (Version 1.0)