Gforge CLI

gforge CLI Reference

The gforge CLI is the operational heart of GherkinForge. It enforces dual-audience Gherkin standards and generates hexagonal Go skeletons from feature files.

---

Install

go install github.com/spannersync/gherkinforge/cmd/gforge@latest

---

gforge lint

Validates .feature files against dual-audience Gherkin rules.

gforge lint <directory>

Examples

# Lint all feature files in the project
gforge lint features/

# Lint a single file
gforge lint features/business/create_order.feature

What it checks

Rule	Description
Tier tag required	Every .feature must have exactly one of @business, @integration, @nfr
Single tier	A file with two tier tags is rejected
DataTable / DocString anchor	@business files must use at least one structured data anchor
Forbidden implementation symbols	SELECT, /api/, .handler, data-testid banned in all steps
UI/DOM vocabulary ban (Zero Trust P2)	28 UI terms banned in @business steps — whole-word regex matching

Exit codes

Code	Meaning
0	No violations
1	One or more violations found — output written to stderr

Output format

features/business/create_order.feature:17: ZERO TRUST VIOLATION: UI-specific term "click" found in @business tier step
features/legacy/old.feature:1: missing tier tag — add @business, @integration, or @nfr
2 violation(s) found

---

gforge scaffold

Generates a hexagonal Go skeleton from a @business feature file.

gforge scaffold --feature <path> --out <directory>

Flags

Flag	Required	Description
--feature	Yes	Path to the @business .feature file to read
--out	No	Output directory (default: .)

Example

gforge scaffold \
  --feature features/business/create_order.feature \
  --out pkg/context/shipment

Generated files

<out>/
├── domain/
│   ├── <name>.go       — Aggregate root with int64 measurements
│   └── ports.go        — Repository + EventPublisher interfaces
├── usecases/
│   └── create_<name>.go — Orchestration use case stub
└── adapters/
    └── inmemory/
        └── repository.go — Thread-safe in-memory adapter

How scaffold derives names

The bounded context name is taken from the first word of the Feature: title. Feature: Order Management → context name Order, package name order.

Column headers from DataTables become Go struct field names (snake_case → CamelCase). DocString JSON keys become command struct fields.

---

Makefile Targets

make build          # compile gforge binary to bin/
make test           # go test -race -count=1 ./...
make bdd            # go test -race -run TestFeatures ./tests/...
make lint-go        # golangci-lint run ./...
make lint-features  # gforge lint features/
make lint           # lint-go + lint-features
make integration    # @integration suite (requires Docker)
make mutation       # go-mutesting domain layer (requires install)
make ci             # lint-go + lint-features + test + mutation