specverb-gen: merge multiple guardfiles per repo into one binary #133

New issue

Closed

opened 2026-06-10 23:09:07 +00:00 by coilysiren · 0 comments

coilysiren commented

2026-06-10 23:09:07 +00:00

Owner

Goal

Swap the kdl build process so the specverb-gen driver reads every *.guardfile.kdl in a directory, groups them by binary name (wrap <binary> ..., i.e. Group[0]), and merges a group into one binary while keeping per-API artifacts separate.

Concretely: define ward.forgejo.guardfile.kdl and ward.aws.guardfile.kdl, both wrap ward ops <api>, and have them merge during build/run into a single ward binary exposing ward ops forgejo and ward ops aws.

Decisions (confirmed with Kai)

Merge trigger: shared binary name (Group[0]). Different wrap names build as separate binaries - that is the "separate output artifacts where possible".
Dep lock: one merged specverb.lock per binary (it is one go build; the module graph is the union, already identical today since the template always imports the aws sdk).
Stays separate per guardfile: spec lock (forgejo.swagger.lock.json, aws.swagger.lock.json) and reference doc (ward.forgejo.guardfile.md, ...).

Design

specverb.Mount already find-or-creates the command path and appends, so mounting N guardfiles onto one root *cli.Command already coexists under a shared ops parent. No mount-engine change.
http/specgen: merged main.go template embedding N (guardfile, spec lock) pairs, looping Mount once per pair, hoisting the audit writer. Per-spec env override derived from the full group (WARD_OPS_FORGEJO_SPEC) to avoid collision on the shared binary name.
http/specdrv: discover + group the dir's guardfiles; gen/lock/skew fan out per guardfile (each hits its own upstream + writes its own lock/doc), lock resolves one merged dep lock, build/run build one merged binary. Cache keyed by the sorted set of member paths; stamp hashes combined over all members.
cmd/specverb-gen: --guardfile selects a group by its binary name; cwd discovery proceeds when exactly one binary is present, errors listing binaries otherwise.

Consumer (ward)

Rename ward-kdl.guardfile.kdl -> ward.forgejo.guardfile.kdl, rewrap to wrap ward ..., add ward.aws.guardfile.kdl, update the Makefile to drop the per-guardfile flags.

## Goal Swap the kdl build process so the specverb-gen driver reads every `*.guardfile.kdl` in a directory, groups them by binary name (`wrap <binary> ...`, i.e. `Group[0]`), and merges a group into **one** binary while keeping per-API artifacts separate. Concretely: define `ward.forgejo.guardfile.kdl` and `ward.aws.guardfile.kdl`, both `wrap ward ops <api>`, and have them merge during `build`/`run` into a single `ward` binary exposing `ward ops forgejo` and `ward ops aws`. ## Decisions (confirmed with Kai) - **Merge trigger**: shared binary name (`Group[0]`). Different `wrap` names build as separate binaries - that is the "separate output artifacts where possible". - **Dep lock**: one merged `specverb.lock` per binary (it is one `go build`; the module graph is the union, already identical today since the template always imports the aws sdk). - **Stays separate per guardfile**: spec lock (`forgejo.swagger.lock.json`, `aws.swagger.lock.json`) and reference doc (`ward.forgejo.guardfile.md`, ...). ## Design - `specverb.Mount` already find-or-creates the command path and appends, so mounting N guardfiles onto one root `*cli.Command` already coexists under a shared `ops` parent. No mount-engine change. - `http/specgen`: merged `main.go` template embedding N (guardfile, spec lock) pairs, looping `Mount` once per pair, hoisting the audit writer. Per-spec env override derived from the full group (`WARD_OPS_FORGEJO_SPEC`) to avoid collision on the shared binary name. - `http/specdrv`: discover + group the dir's guardfiles; `gen`/`lock`/`skew` fan out per guardfile (each hits its own upstream + writes its own lock/doc), `lock` resolves one merged dep lock, `build`/`run` build one merged binary. Cache keyed by the sorted set of member paths; stamp hashes combined over all members. - `cmd/specverb-gen`: `--guardfile` selects a group by its binary name; cwd discovery proceeds when exactly one binary is present, errors listing binaries otherwise. ## Consumer (ward) - Rename `ward-kdl.guardfile.kdl` -> `ward.forgejo.guardfile.kdl`, rewrap to `wrap ward ...`, add `ward.aws.guardfile.kdl`, update the Makefile to drop the per-guardfile flags.

coilysiren referenced this issue from a commit

2026-06-11 00:39:08 +00:00

feat(specverb): merge multiple guardfiles per binary

coilysiren closed this issue

2026-06-11 00:39:09 +00:00