preset

preset

This package loads and applies presets — curated scaffolds that sit on top of an existing maestro project. A preset declares one or more services and ships a tree of source files the loader writes into them.

This is a contributor reference. End-user docs live in the top-level README under maestro preset.

What a preset is

A preset is a directory under internal/preset/presets/ containing:

<preset-name>/
├── preset.toml                      # manifest (required)
├── <overlay-dir>/                   # overlay tree for one service
│   └── …
└── <another-overlay-dir>/           # overlay tree for another service
    └── …

Presets ship inside the maestro binary via //go:embed (see embed.go). The loader takes any fs.FS, so tests hand it synthetic trees from testdata/.

The preset root holds the manifest plus one directory per service that ships an overlay. Each directory's name must match the dir field of a [[service]] block in preset.toml. Other root-level files (README, LICENSE, …) are silently ignored; an unknown directory is rejected as an authoring typo.

The manifest

preset.toml is the on-disk shape of preset.Manifest. The fields are:

name = "auth-jwt"                          # stable id used by `maestro preset apply <name>`
description = "JWT auth · …"               # one-liner shown in the picker

[[service]]                                # one or more service blocks
name = "PRESETSERVICE"                     # sentinel — resolved at apply time
dir  = "main"                              # overlay dir under the preset root
shape = "http"                             # http | grpc | worker | bare
db = "postgres"                            # optional; mutually exclusive with db_ref

[[service]]
name = "PRESETSERVICE-cleanup"
dir  = "cleanup"
shape = "worker"
db_ref = "PRESETSERVICE"                   # borrow another service's postgres sidecar

[[parameter]]                              # zero or more interactive prompts
key = "methods"
prompt = "Sign-in methods"
type = "multiselect"                       # v1 ships multiselect only
options  = ["password", "google"]
preselect = ["password"]                   # ticks at wizard open
min_pick = 1                               # floor before "continue" advances

Rules the manifest must satisfy

Manifest.Validate (preset.go) enforces these at load time so apply never trips on a malformed preset halfway through scaffolding:

• name is required.
• At least one [[service]] block, each with a non-empty name and a valid shape.
• db and db_ref are mutually exclusive on a service.
• A db_ref must point at another service declared in the same manifest, not at itself.
• dir is optional, but if set must be a single path component (no separators, no ./..), not collide with the manifest filename, and unique across services.
• Parameter keys are unique; preselect must be a subset of options; min_pick must be between 0 and len(options).

The first service in Services is the main service — the one PRESETSERVICE resolves to and the one the wizard collects DB mode + port for. Overlays are routed per-service via the dir field, not by service order.

Sentinel substitution

Preset files (both manifest strings and overlay file contents) contain sentinels: bare uppercase Go identifiers the loader rewrites at apply time. The convention is gonew-style — every sentinel is a single token so preset source files compile as ordinary Go in the author's editor.

Sentinels are substituted in both file paths and file contents (see SubstitutePath / Substitute in subst.go). Substitution is longest-token-first so a future PRESETSERVICEROLE wouldn't get half-replaced by PRESETSERVICE.

An empty Vars field leaves its sentinel in the output — resolveServices (apply.go) catches that as a caller bug rather than letting the empty string flow downstream. Add a new sentinel by:

1. Declaring a constant in subst.go.
2. Adding a field to Vars.
3. Adding a pair to Vars.pairs().

Filename-suffix conditional inclusion

A preset that asks "which sign-in methods?" doesn't put the conditional files in separate directories — that breaks gopls because cross-file symbol references span Go packages. Instead, the filename suffix decides inclusion.

The rule (see walker.go):

• A file whose basename ends in _<option>.<ext> is included only when <option> is among the user's picks for the parameter that declared it.
• Every other file is included unconditionally.

For auth-jwt:

main/internal/routes/
├── routes.go            # always — Register() entry point, mounts slice
├── auth.go              # always — /auth/refresh, /auth/logout
├── auth_password.go     # only if methods includes "password"
└── auth_google.go       # only if methods includes "google"

All files in routes/ share a Go package, so cross-file references like mounts (defined in routes.go, appended-to from each handler file's init()) work both in author-mode and after apply.

If a filename suffix isn't a declared option (e.g. auth_helper.go when no parameter declares helper), the walker treats it as just a filename — the file is always included. This means authors can use the convention freely without pre-registering every suffix.

The init() + mounts pattern

Because the conditional files are gated by inclusion (not by build tags), routes.go can't reference symbols from auth_password.go directly — that file might not be on disk after apply. The pattern auth-jwt uses:

// routes/routes.go
var mounts []func(r *gin.Engine)

func Register(r *gin.Engine) {
    for _, fn := range mounts {
        fn(r)
    }
}

// routes/auth_password.go
func init() {
    mounts = append(mounts, func(r *gin.Engine) {
        auth := r.Group("/auth")
        auth.POST("/register", passwordRegister)
        // …
    })
}

server.go calls routes.Register(r) once and never has to know which conditional files are present; each conditional file appends a mount in init(). Pattern reusable for any preset where a central wiring point needs to compose with optional extras.

Apply

Apply (apply.go) is the orchestrator. From a preset name + main service name + MainDB (mode + port the dbwizard captured) + Selections (the parameter picks):

1. Load and validate the manifest.
2. Resolve every [[service]] block — substitute sentinels, merge MainDB into the first service.
3. Pre-flight: validate every resolved ServiceConfig before any side effect lands. Catches caller bugs (e.g. main service missing DBMode when the manifest declares postgres) before half the scaffold is on disk.
4. Scaffold each service in declaration order via the existing service.New(…).WithDB(…).Generate() pipeline. Order matters for db_ref — the target must already be in project.toml when the borrower scaffolds.
5. Walk the preset root, substitute sentinels in path and contents, route each overlay file to its service's on-disk directory via the manifest's dir field.
6. Re-run go mod tidy for every overlaid service so any new direct deps introduced by the overlay (the template's tidy already ran in step 4 and didn't see them) land in go.mod.

There's no rollback. Apply is expected to run on a clean working tree so a botched apply can be undone with git checkout.

Authoring a new preset

1. Create internal/preset/presets/<name>/preset.toml with the manifest fields above.
2. For each service that ships overlay source, set its dir field to a Go-idiomatic role name (main, cleanup, api, …) and put the overlay tree at <preset>/<dir>/. Use PRESETSERVICE / PRESETMODULE inside paths and file contents wherever the user's choices need to land.
3. For conditional content, name files <base>_<option>.<ext> where <option> matches a manifest option.
4. Add the preset to TestFS_List in embed_test.go so the embed inventory stays explicit.
5. Add an end-to-end test in internal/e2e/preset_test.go — scaffold a project, call Apply, assert the result compiles. Skipping this means the loader can drift without a CI signal.

Go imports in overlay files

Overlay .go files compile inside the maestro module during preset authoring (gopls + go build ./...). That gives us two import shapes that both work:

• Stdlib and module-level deps work normally. Any dep in maestro's go.mod is importable from an overlay file (e.g. github.com/gin-gonic/gin, go.uber.org/zap, github.com/golang-jwt/jwt/v5). Add a new dep with go get once and every preset can use it.

• Cross-package imports work via the maestro-internal path. A handler in <preset>/main/internal/routes/auth.go can import <preset>/main/internal/db by writing the full maestro-internal path:

  import "github.com/Zagforge-Org/maestro/internal/preset/presets/auth-jwt/main/internal/db"
  

  That's a real path in author-mode, so gopls resolves it and go build ./... compiles it. At apply time, RewriteSourcePrefix (subst.go) rewrites the prefix to the user's actual service module path — e.g. github.com/owner/proj/auth/internal/db. The rewrite is scoped per overlay dir, so a file in main/ is rewritten against the main service's module and a file in cleanup/ is rewritten against the cleanup service's.

  The prefix is PresetSourceRoot + "/" + presetName + "/" + overlayDir. If maestro itself ever gets renamed, update PresetSourceRoot in subst.go in lockstep.

Run go test ./internal/preset/... to exercise the manifest validator, walker, and substitution. Run go test -tags=e2e ./internal/e2e/... for the compile-the-generated-service check.