feat(template): versioned OCI template registry — push/add/update/diff/verify (spec 19)

Add internal/registry: a pure-Go (oras-go/v2, CGO-free) OCI template-registry
seam behind a TargetResolver interface (real remote.Repository w/ docker creds;
tests round-trip through an in-memory oras store, no network). Deterministic
bundle tar packaging (content-addressed digest), mandatory digest verification
on pull, and a cosign Verifier/Signer seam (shells cosign, matching
internal/selfupdate's CGO-free precedent; mock-able for tests).

Graduate the template.go stubs to real commands: push, add (tag→digest pin +
verify + digest-keyed cache + lockfile entry, lock-guarded), update (re-resolve
w/ --dry-run), diff (render-diff pinned vs remote), verify (re-pull + signature),
and ls. Store config gains a digest-pinned `templates:` lockfile; remote
templates are chained into the generate/lint/test source (embedded < store <
remote), digest-pinned and offline-first so generation stays byte-deterministic.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gustavobertoi

go.mod

@@ -27,6 +27,8 @@ require (
 	github.com/moby/moby/api v1.54.2
 	github.com/moby/moby/client v0.4.1
 	github.com/nats-io/nats.go v1.52.0
+	github.com/opencontainers/go-digest v1.0.0
+	github.com/opencontainers/image-spec v1.1.1
 	github.com/spf13/cobra v1.10.2
 	github.com/twmb/franz-go v1.21.4
 	github.com/twmb/franz-go/pkg/kadm v1.18.0
@@ -35,6 +37,7 @@ require (
 	golang.org/x/sync v0.20.0
 	golang.org/x/term v0.44.0
 	modernc.org/sqlite v1.52.0
+	oras.land/oras-go/v2 v2.6.1
 )
 
 require (
@@ -95,8 +98,6 @@ require (
 	github.com/nats-io/nkeys v0.4.15 // indirect
 	github.com/nats-io/nuid v1.0.1 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
-	github.com/opencontainers/go-digest v1.0.0 // indirect
-	github.com/opencontainers/image-spec v1.1.1 // indirect
 	github.com/pierrec/lz4/v4 v4.1.26 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect

go.sum

@@ -298,5 +298,7 @@ modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
 modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
 modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
 modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
+oras.land/oras-go/v2 v2.6.1 h1:bonOEkjLfp8tt6qXWRRWP6p1F+9octchOf2EqnWB4Zs=
+oras.land/oras-go/v2 v2.6.1/go.mod h1:dhtFrFOuZuDtAVeZ9FUnaa5zfzplG3ZnFX9/uH1J/Yk=
 pgregory.net/rapid v1.2.0 h1:keKAYRcjm+e1F0oAuU5F5+YPAWcyxNNRK2wud503Gnk=
 pgregory.net/rapid v1.2.0/go.mod h1:PY5XlDGj0+V1FCq0o192FdRhpKHGTRIWBgqjDBTrq04=

internal/cli/generate.go

@@ -13,14 +13,26 @@ import (
 )
 
 // builtinSource is the template source used by generation and the template
-// tooling: custom templates in the store (~/.devstack/templates) override the
-// embedded built-ins by name; the embedded set is always the fallback.
+// tooling. Resolution priority is embedded < store < remote (first match wins in
+// the chain, so the highest-priority source is listed first): a digest-pinned
+// REMOTE template (spec 19) overrides a store template, which overrides an
+// embedded built-in of the same name. A cold/missing remote cache contributes
+// nothing, keeping generation offline-first and deterministic (with no remote
+// templates registered the chain is byte-identical to the pre-spec-19 behavior).
 func builtinSource() template.TemplateSource {
 	embedded := template.NewFSSource(templates.FS)
+	var chain []template.TemplateSource
+	if remote := remoteTemplateSource(); remote != nil {
+		chain = append(chain, remote)
+	}
 	if dir := userTemplatesDir(); dir != "" {
-		return template.NewChainSource(template.NewFSSource(os.DirFS(dir)), embedded)
+		chain = append(chain, template.NewFSSource(os.DirFS(dir)))
+	}
+	if len(chain) == 0 {
+		return embedded
 	}
-	return embedded
+	chain = append(chain, embedded)
+	return template.NewChainSource(chain...)
 }
 
 // newGenerateCmd wires `devstack generate` — the M1 deterministic pipeline entry

internal/cli/template.go

@@ -27,13 +27,13 @@ func newTemplateCmd(g *GlobalOpts) *cobra.Command {
 		newTemplateTestCmd(g),
 		newTemplateInitCmd(g),
 		newTemplateNewCmd(g),
-		// Reserved remote-registry verbs (spec 19, v2) — tree-only stubs so
-		// help/completions stay consistent (spec 26 / spec 07).
-		stub("push", "Publish a template to a remote registry", "v2 (spec 19)"),
-		stub("add", "Add a remote template source", "v2 (spec 19)"),
-		stub("update", "Update cached remote templates", "v2 (spec 19)"),
-		stub("diff", "Diff a local template against its remote", "v2 (spec 19)"),
-		stub("verify", "Verify a remote template's signature", "v2 (spec 19)"),
+		// Versioned OCI template registry (spec 19).
+		newTemplatePushCmd(g),
+		newTemplateAddCmd(g),
+		newTemplateUpdateCmd(g),
+		newTemplateDiffCmd(g),
+		newTemplateVerifyCmd(g),
+		newTemplateLsCmd(g),
 	)
 	return cmd
 }