sandbox apply: values documents and a built-in template (ENG-1187)

[joehorsnell]

The decision this asks for

Should the CLI know how to build a sandbox spec from a flat description of what to fork,
so that adopting PR-validation sandboxes does not require authoring a spec template?

This is the proposal, dog-fooded end to end, but it is a draft for design feedback,
not code review. The alternative — the CLI stays minimal and every CI integration
carries this logic itself — is written up and costed in the
design overview
and its Notion mirror.

Stacked on #362, which adds --dry-run
on its own and stands independently of whatever is decided here. Review that one first;
it is small and uncontroversial. This PR's diff is only the values work.

What it adds

A values document. -f accepts one, and it says what to fork rather than how a spec
is shaped:

cluster: prod-eks
defaults:
  namespace: hotrod
  imageTemplate: ghcr.io/acme/{workload}:{short-sha}
forks:
  - workload: route
  - workload: frontend
    env:
      LOG_LEVEL: debug

A document with a top-level spec is a sandbox spec and takes the existing path
untouched. Unknown fields are rejected, so envs: fails rather than being silently
dropped.

Rendering through a template embedded in the binary, using the same @{var} engine
that renders a template of your own. signadot sandbox template show prints it; save it,
edit it, pass it to -f, and you have taken over the structure. That is the upgrade path
off the values schema when it stops fitting.

The hybrid is deliberate. The document's shape lives in a template, where it is
inspectable. The parts a template cannot compute — the fork list, whose length depends on
its input, plus resolved images, merged env and labels — are computed in Go and injected
as @{var[yaml]}, which embeds a parsed structure rather than a string.

Flags for what CI knows and a file does not: --name, --ttl, --patch,
--ci-context auto|github|none, --default-labels. Context detection is what completes
the templateless path: it derives a deterministic sandbox name from repo and PR, so every
push updates one sandbox in place, and stamps the labels the Signadot GitHub App uses for
teardown.

Why it might belong here rather than in each integration

The @{var} engine is pure substitution — no iteration — so something has to build the
fork list. That something can live in the CLI once, or in every CI integration.

In the CLI: one implementation, and every CLI user gets the templateless path, not just
Actions users. A CircleCI orb is then YAML that writes a values document, which matters
because an orb cannot reuse TypeScript.

In each integration: the CLI keeps a smaller surface and commits to no values schema
before we know the Action is the right shape. The cost is roughly the 550 lines in
internal/render/compile.go and context.go reimplemented per provider, and the second
provider either repeats it or moves it here anyway.

Dog-fooded

signadot#7315 drives this from CI and is
green: both sandbox jobs render a values document, apply the rendered spec, reach Ready,
and run contract and RBAC suites behind it. It replaced two spec templates, two
curl | sh installs and four jq reads of the apply response, and it deleted both of its
templates once a default-route-group input existed.

That run also found the label bug. The apiserver reserves the whole signadot/ prefix and
accepts only signadot/github-repo and signadot/github-pull-request under it, requiring
them set together or not at all; a third built-in label had the whole spec refused with a
400. Both rules are now checked while rendering.

Open questions

1. Two surfaces or one? The values schema and @{var} templates coexist, bridged by
   template show. Should they converge, and in which direction?
2. Is the built-in template the right seam? It is the mechanism and the
   documentation of the templateless path, and a compatibility surface the moment someone
   saves a copy.
3. Does the schema cover enough for the templateless path to be the default for new
   customers? One dog-fooding pass added defaultRouteGroup and description.
4. How much local validation should mirror the API? The label rules are here because
   the API's message arrives late and opaquely, but every mirrored rule can drift.

Test plan

• go test ./internal/...
• Golden fixtures for values and spec documents, --set, --patch, CI-derived and
  authored names, and long-name hashing
• TestRenderedSpecIsAFixedPoint
• End to end against staging via signadot#7315: two sandboxes created and Ready
• Docs page for the values schema and built-in template, before any announcement