README
¶
goforge
A Polylith-style workspace tool for Go. goforge
organizes a single Go module into reusable bricks — components (with a
public interface package and a hidden internal/ implementation) and bases
(entry-point layers) — composed into deployable projects. It scans the
workspace, derives the brick dependency graph from Go imports, detects what
changed since a stable git point, and validates and tests incrementally.
Worker types
Every component is classified along two axes (see principles.yaml):
- determinism —
deterministic|non_deterministic - effectfulness —
pure|[input_effect]|[output_effect]|[input_effect, output_effect]
goforge check enforces effect propagation (a pure component may not depend on
an effectful brick; a deterministic brick may not depend on a non_deterministic
one), and goforge classify shows each brick's declared vs. effective worker
type, propagated through its dependency closure.
Install
go install goforge.dev/goforge@latest
Commands
| Command | Purpose |
|---|---|
create |
Scaffold a workspace, component, base, or project |
info |
Brick × project matrix, with changed bricks/projects marked (:loc for line counts) |
check |
Validate structure, the interface boundary, worker-type rules, and project deps |
classify |
Declared vs. effective worker type per brick |
deps |
Brick dependencies, forward and reverse (brick: / project:) |
diff |
Files, bricks, and projects changed since the stable point (since:) |
test |
Run tests for changed bricks/projects (:all, :dev, brick:, project:) |
libs |
Third-party libraries and which bricks use them |
ws |
Workspace as YAML data (get:KEY.PATH, out:FILE) |
migrate |
Bootstrap goforge config for an existing Go module |
shell |
Interactive command shell |
version / help |
Tool version / usage |
Arguments use poly-style syntax: key:value and :flag, e.g.
goforge create component name:user interface:api, goforge info :loc,
goforge test :all. Add color-mode:none to disable ANSI color.
Quick start
goforge create workspace name:demo top-ns:com.demo module:goforge.dev/demo
cd demo
goforge create component name:user
goforge create base name:cli
goforge create project name:app
goforge check
goforge info
See scripts/e2e.sh for a full worked example.
Layout of a workspace
go.mod · workspace.yaml · principles.yaml
components/<name>/ <name>.go (interface) · internal/ (impl) · component.yaml
bases/<name>/ <name>.go · base.yaml
projects/<name>/ main.go · project.yaml
development/ deps.go (generated; imports every brick)
Documentation
¶
Overview ¶
Command goforge is a Polylith-style workspace tool for Go: it scaffolds and inspects a single-module workspace built from reusable bricks (components and bases) composed into deployable projects.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
change
Package change detects what changed in a workspace since a stable git point, mapping changed files to bricks and projects so that info, diff, and test can work incrementally.
|
Package change detects what changed in a workspace since a stable git point, mapping changed files to bricks and projects so that info, diff, and test can work incrementally. |
|
check
Package check validates a workspace: structural integrity (cycles, brick kinds), the interface boundary, worker-type effect-propagation rules, and project declared-vs-imported consistency.
|
Package check validates a workspace: structural integrity (cycles, brick kinds), the interface boundary, worker-type effect-propagation rules, and project declared-vs-imported consistency. |
|
config
Package config defines the on-disk YAML schemas for a goforge workspace and helpers to read and write them.
|
Package config defines the on-disk YAML schemas for a goforge workspace and helpers to read and write them. |
|
deps
Package deps derives the brick dependency graph by parsing the Go imports of each brick, and provides cycle detection and transitive-closure helpers used by check, info, change, and test.
|
Package deps derives the brick dependency graph by parsing the Go imports of each brick, and provides cycle detection and transitive-closure helpers used by check, info, change, and test. |
|
loader
Package loader scans a goforge workspace on disk and builds the in-memory model.Workspace.
|
Package loader scans a goforge workspace on disk and builds the in-memory model.Workspace. |
|
principles
Package principles loads the worker-type taxonomy (determinism × effectfulness) from the embedded principles.yaml.
|
Package principles loads the worker-type taxonomy (determinism × effectfulness) from the embedded principles.yaml. |
|
render
Package render provides terminal output helpers: optional ANSI color and simple aligned tables.
|
Package render provides terminal output helpers: optional ANSI color and simple aligned tables. |
|
scaffold
Package scaffold renders new workspaces, components, bases, and projects from embedded templates.
|
Package scaffold renders new workspaces, components, bases, and projects from embedded templates. |