Documentation
¶
Overview ¶
Package generator handles template execution and file writing for the HAMR CLI.
Index ¶
- Constants
- Variables
- func DetectGoVersion() string
- func GenerateProject(dir string, cfg *ProjectConfig) error
- func GenerateService(dir string, cfg *ServiceConfig) error
- func InstallSkill(skill, destDir string, force bool, data SkillData) error
- func IsValidProjectName(name string) bool
- func ProjectSlug(name string) string
- func ReadExistingGoMod(dir string) (module, goVersion string, err error)
- func RenameModule(dir, newModule string, dryRun bool) (oldModule string, filesUpdated int, err error)
- func SkillDirName(skill string) string
- func ValidateProjectName(name string) error
- func VendorAll(dir string, update bool, deps []string) error
- func VendorCustom(dir, url, out string) error
- func VendorOne(dir, nameArg string, update bool) error
- func VendorVerify(dir string) error
- type ProjectConfig
- type ServiceConfig
- type SkillData
- type VendorDep
- type VendorLock
Constants ¶
const ProjectNameFormatMessage = "must start with a letter and contain only letters, digits, periods, hyphens, or underscores"
Variables ¶
var ServiceTypes = []string{"empty", "worker", "api", "html"}
ServiceTypes lists the supported `hamr add service` types.
var SkillNames = []string{"hamr", "qa-loop", "pr-publish"}
SkillNames lists the skills we publish, in install/picker order. Each maps to a directory under templates/skills/<target>/<name>.
var SupportedSkillTargets = []string{"claude", "codex", "opencode"}
SupportedSkillTargets lists the AI agents skills can be installed for. The SKILL.md format is a cross-tool standard, so targets differ only in where the files go: claude reads .claude/skills/, codex and opencode read the shared .agents/skills/ (opencode reads .claude/skills/ too).
Functions ¶
func DetectGoVersion ¶
func DetectGoVersion() string
DetectGoVersion returns the Go version installed on the system (e.g. "1.25.0") by running "go env GOVERSION". Returns "" if detection fails. Build metadata suffixes (e.g. "-X:nodwarf5") are stripped because go.mod only accepts versions matching the format 1.N or 1.N.P.
func GenerateProject ¶
func GenerateProject(dir string, cfg *ProjectConfig) error
GenerateProject scaffolds a new project directory with all required files. When cfg.InPlace is true, it generates into an existing directory, skipping files that already exist (notably go.mod).
func GenerateService ¶
func GenerateService(dir string, cfg *ServiceConfig) error
GenerateService scaffolds a new service into an existing project at dir: cmd/<name>/ (main.go + Dockerfile), internal/<name>/, a [[dev.watch]] block appended to hamr.toml, and (for HTTP types) a port line appended to .env and .env.example.
func InstallSkill ¶
InstallSkill copies the embedded tree for one skill into destDir. The tree is target-independent (the SKILL.md format is a cross-tool standard). Files with a .tmpl suffix are rendered as Go text/template (with [[ ]] delimiters so they don't collide with templ's {{ ... }} references) and written with the suffix stripped. All other files are copied verbatim. When destDir already exists and force is false, it returns an error. When force is true, the existing destDir is removed before writing.
func IsValidProjectName ¶
IsValidProjectName reports whether name is a valid HAMR project name.
func ProjectSlug ¶
ProjectSlug returns a lowercase, hyphenated identifier safe for generated infrastructure defaults such as Docker Compose, database names, and buckets.
func ReadExistingGoMod ¶
ReadExistingGoMod reads go.mod from dir and returns the module path and Go version. Returns empty strings (not an error) if go.mod doesn't exist.
func RenameModule ¶
func RenameModule(dir, newModule string, dryRun bool) (oldModule string, filesUpdated int, err error)
RenameModule rewrites the module directive in go.mod and updates all import paths in .go files under dir. When dryRun is true it detects changes and prints affected files but does not write anything. It returns the old module path and the number of .go files that were (or would be) modified.
func SkillDirName ¶
SkillDirName is the directory a skill installs into under .claude/skills/. The framework skill keeps the bare "hamr" name it has always had; the workflow skills are prefixed so they don't squat generic names.
func ValidateProjectName ¶
ValidateProjectName validates a HAMR project name.
func VendorAll ¶
VendorAll downloads the selected registry dependencies into dir. When deps is nil or empty, all registry deps are vendored. If update is true, it re-downloads even if the lock file already has the dep.
func VendorCustom ¶
VendorCustom downloads a file from an arbitrary URL and saves it at the given output path relative to dir.
func VendorOne ¶
VendorOne downloads a single dependency by name. The name may include a version suffix like "alpine@3.14.9".
func VendorVerify ¶
VendorVerify checks that all locked dependencies exist on disk and match their recorded SHA256 checksums.
Types ¶
type ProjectConfig ¶
type ProjectConfig struct {
Name string // "myproject"
Module string // "github.com/user/myproject"
CSS string // "plain" | "tailwind"
Database string // "postgres" | "sqlite"
DBConnector string // "sqlx" | "gorm"
MigrateAtStartup bool // run migrations when server starts
GoVersion string // "1.25.0"
InPlace bool // generate into existing directory
IncludeSessions bool
IncludeAuth bool
AuthWithTables bool
IncludeStorage bool // true when StorageBackend != ""
StorageBackend string // "" | "local" | "s3"
StaticS3 bool // sync static/ to a dedicated S3 bucket
IncludeWS bool
IncludeE2E bool
IncludeStripe bool
// StripeWebhookSecret is the dev-only signing secret shared between the
// scaffolded app's STRIPE_WEBHOOK_SECRET (.env) and hamr.toml's
// [dev.stripe].webhook_secret. Generated at scaffold time so the two stay
// in sync without manual coordination.
StripeWebhookSecret string
IncludeEmailMock bool // wire pkg/emailmock + enable /__hamr/mail in hamr.toml
IncludeLocale bool
IncludeAlpine bool
DefaultLocale string // default: "en"
HamrVersion string // HAMR version at scaffold time
ScaffoldedAt string // date the project was scaffolded (YYYY-MM-DD)
}
ProjectConfig holds the data used to render project templates.
func (*ProjectConfig) Validate ¶
func (cfg *ProjectConfig) Validate() error
Validate checks that the ProjectConfig has all required fields and valid values.
type ServiceConfig ¶
type ServiceConfig struct {
Name string // service name, e.g. "billing" — used for cmd/<name>, internal/<name>, bin/<name>
Type string // "empty" | "worker" | "api" | "html"
Module string // project module path from go.mod
GoVersion string // from go.mod, used in the Dockerfile base image
ProjectSlug string // slug of the project directory name, for sqlite defaults
Port int // listen port (api/html only)
WithDB bool // wire the project's repo store
WithAuth bool // wire session auth middleware (api/html, requires WithDB)
WithLocale bool // wire the locale bundle (html only)
// HasTemplRule is true when the project's hamr.toml has a [[dev.watch]]
// rule named "templ". Only then does an html service's watch rule get
// depends = ["templ"] — an unresolvable dependency is a hard config error
// that stops hamr dev entirely.
HasTemplRule bool
// Copied from the project's hamr.toml [options] so DB wiring matches.
Database string // "postgres" | "sqlite"
DBConnector string // "sqlx" | "gorm"
DefaultLocale string // from [locale].default, "en" fallback
}
ServiceConfig holds the data used to render service templates.
func (*ServiceConfig) EnvPrefix ¶
func (cfg *ServiceConfig) EnvPrefix() string
EnvPrefix returns the env-var prefix for the service ("billing-svc" → "BILLING_SVC").
func (*ServiceConfig) HTTP ¶
func (cfg *ServiceConfig) HTTP() bool
HTTP reports whether the service type listens on a port.
func (*ServiceConfig) PkgName ¶
func (cfg *ServiceConfig) PkgName() string
PkgName returns the Go package name for internal/<name>: lowercase with separators stripped ("billing-svc" → "billingsvc").
func (*ServiceConfig) Validate ¶
func (cfg *ServiceConfig) Validate() error
Validate checks the ServiceConfig and applies defaults.
type SkillData ¶
type SkillData struct {
IncludeAlpine bool
}
SkillData is the render context passed to skill templates. Fields mirror scaffold options that the skill's guidance depends on.
type VendorDep ¶
type VendorDep struct {
Version string `json:"version"`
URL string `json:"url"`
Out string `json:"out"`
SHA256 string `json:"sha256,omitempty"`
}
VendorDep describes a vendored JavaScript dependency.
type VendorLock ¶
VendorLock is the structure of the hamr.vendor.json lock file.