Documentation
¶
Overview ¶
Package cmdutil holds cross-cutting helpers shared by forge's own CLI across MORE THAN ONE command group (internal/cli and its dir-nested subpackages). It is a leaf package — it imports only neutral internal packages — so any command group can depend on it without an import cycle back to internal/cli.
Helpers used by a single command stay with that command; trivial stdlib wrappers (a one-line os.Stat check) are duplicated locally rather than shared. Only genuinely shared logic lives here.
Index ¶
- Variables
- func CountLineStartScaffoldMarkers(data []byte) int
- func FindProjectRoot() (string, error)
- func HideDevFlags(cmd *cobra.Command, names ...string)
- func IsMarkerScannable(name string) bool
- func Name() string
- func ProjectRoot() (string, error)
- func ValidateFrontendName(name string) error
- func ValidateIdentifier(name string) error
- func ValidateProjectName(name string) error
- func ValidateServiceName(name string) error
Constants ¶
This section is empty.
Variables ¶
var ErrProjectConfigNotFound = errors.New("forge.yaml not found in current directory (run 'forge new' to create a project)")
ErrProjectConfigNotFound is returned when forge.yaml does not exist. The canonical sentinel lives here (the shared leaf package) so both internal/cli and the dir-nested command groups compare against the same value; internal/cli's config.ErrProjectConfigNotFound aliases this.
var GoKeywords = map[string]bool{ "break": true, "case": true, "chan": true, "const": true, "continue": true, "default": true, "defer": true, "else": true, "fallthrough": true, "for": true, "func": true, "go": true, "goto": true, "if": true, "import": true, "interface": true, "map": true, "package": true, "range": true, "return": true, "select": true, "struct": true, "switch": true, "type": true, "var": true, }
GoKeywords is the set of Go reserved keywords.
var GoPredeclaredIdentifiers = map[string]bool{ "bool": true, "byte": true, "complex64": true, "complex128": true, "error": true, "float32": true, "float64": true, "int": true, "int8": true, "int16": true, "int32": true, "int64": true, "rune": true, "string": true, "uint": true, "uint8": true, "uint16": true, "uint32": true, "uint64": true, "uintptr": true, "any": true, "comparable": true, "true": true, "false": true, "iota": true, "nil": true, "append": true, "cap": true, "close": true, "complex": true, "copy": true, "delete": true, "imag": true, "len": true, "make": true, "new": true, "panic": true, "print": true, "println": true, "real": true, "recover": true, "min": true, "max": true, "clear": true, }
GoPredeclaredIdentifiers is the set of Go predeclared types, constants, zero value, and builtin functions.
var ReservedServiceNames = map[string]bool{ "worker": true, "scheduler": true, "cron": true, "job": true, }
ReservedServiceNames are names that conflict with forge's worker/scheduler subsystems. Using them as HTTP Connect service names causes confusion.
Functions ¶
func CountLineStartScaffoldMarkers ¶
CountLineStartScaffoldMarkers counts line-start `// FORGE_SCAFFOLD:` and `# FORGE_SCAFFOLD:` markers in data. (The lint analyzer is Go-only, but audit/map are allowed to span more file types — hence both comment styles.)
func FindProjectRoot ¶
FindProjectRoot walks upward from the cwd looking for a forge.yaml. Returns the directory or "" when no project is found. Mirrors the loadProjectConfig walk-up behavior in config.go.
func HideDevFlags ¶
HideDevFlags is the user-vs-maintainer CLI surface split, shared by `forge generate` (internal/cli) and `forge lint` (internal/cli/lint).
Commands like `forge lint` and `forge generate` accumulate flags for two very different audiences: project users (the 5-7 flags they actually reach for) and forge maintainers / debugging agents (wiring audits, pipeline narrowing, migration escape hatches). Showing all of them in --help buries the user-facing surface. HideDevFlags marks the named flags Hidden — fully functional, just invisible in --help — and adds a visible --help-dev flag that lists exactly the hidden set, so the flags stay discoverable in one place.
Must be called after cmd.RunE and all flags are set. Panics on an unknown flag name: that's a programmer error at command-construction time, and panicking keeps a typo from silently leaving a dev flag visible.
It lives here in the shared leaf so the dir-nested lint group reaches it without importing internal/cli (which would cycle — internal/cli blank-imports the groups).
func IsMarkerScannable ¶
IsMarkerScannable identifies file types whose FORGE_SCAFFOLD markers are real unfilled placeholders rather than documentation references. Markdown and JSON commonly cite the marker syntax in prose / fixtures, so they're excluded — those occurrences would otherwise generate noisy "scaffold present" warnings on every project that documents how scaffolds work.
func Name ¶
func Name() string
Name returns the command name users should type to invoke Forge. When the binary is "forge" (standalone install) it returns "forge"; when embedded in another binary (e.g. "reliant") it returns "reliant forge". Shared so group commands can print copy-pasteable next-step hints without importing internal/cli.
func ProjectRoot ¶
ProjectRoot finds the project root by looking for forge.yaml in the cwd (NOT a walk-up — see FindProjectRoot for that). Returns a user-facing error when forge.yaml is absent from the current directory.
func ValidateFrontendName ¶
ValidateFrontendName checks that a frontend name is filesystem-safe.
func ValidateIdentifier ¶
ValidateIdentifier checks that a name is valid for use as a service, worker, or operator name. Hyphens and underscores are allowed in the display name; templates use snakeCase/pascalCase helpers to convert when a Go identifier is needed (e.g. "admin-server" / "admin_server" -> package "admin_server" and field "AdminServer" — snake_case is the canonical on-disk form post-2026-06-08). The leading-character and reserved-word rules match ValidateProjectName so all top-level scaffold names share one shape.
func ValidateProjectName ¶
ValidateProjectName checks that a project name is valid for use as a directory name and in Go module paths. Hyphens are allowed since they are valid in module paths and directory names; templates use snakeCase/pascalCase helpers to convert when a Go identifier is needed.
func ValidateServiceName ¶
ValidateServiceName checks that a name is valid for a service and not a reserved service name. For background workers use 'forge add worker <name>'.
Types ¶
This section is empty.
Source Files