From 17e46de34b7f6a82c371490f4507281e0d411f36 Mon Sep 17 00:00:00 2001 From: tweinmann Date: Wed, 28 Oct 2026 10:47:56 +0000 Subject: [PATCH] Archive Phase 10: branch previews Merge the Phase 10 delta specs into openspec/specs (new spec branch-previews), record the level-3 acceptance with shelf-hello and v0.7.0, and mark Phase 10 complete in CLAUDE.md, the README and the context. Three changed requirements were over 500 characters for a main spec; their wording is tightened and the build cache is a requirement of its own. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 16 ++- README.md | 2 +- .../.openspec.yaml | 0 .../design.md | 18 ++- .../proposal.md | 0 .../specs/agent-interface/spec.md | 10 +- .../specs/app-chart/spec.md | 0 .../specs/app-delivery/spec.md | 23 +-- .../specs/app-exposure/spec.md | 0 .../specs/branch-previews/spec.md | 0 .../specs/cluster-init/spec.md | 7 +- .../specs/dev-environment/spec.md | 0 .../tasks.md | 2 +- openspec/config.yaml | 7 +- openspec/specs/agent-interface/spec.md | 42 +++++- openspec/specs/app-chart/spec.md | 22 +++ openspec/specs/app-delivery/spec.md | 64 +++++++-- openspec/specs/app-exposure/spec.md | 13 ++ openspec/specs/branch-previews/spec.md | 134 ++++++++++++++++++ openspec/specs/cluster-init/spec.md | 8 +- openspec/specs/dev-environment/spec.md | 8 +- 21 files changed, 329 insertions(+), 47 deletions(-) rename openspec/changes/{phase-10-branch-previews => archive/2026-10-28-phase-10-branch-previews}/.openspec.yaml (100%) rename openspec/changes/{phase-10-branch-previews => archive/2026-10-28-phase-10-branch-previews}/design.md (95%) rename openspec/changes/{phase-10-branch-previews => archive/2026-10-28-phase-10-branch-previews}/proposal.md (100%) rename openspec/changes/{phase-10-branch-previews => archive/2026-10-28-phase-10-branch-previews}/specs/agent-interface/spec.md (87%) rename openspec/changes/{phase-10-branch-previews => archive/2026-10-28-phase-10-branch-previews}/specs/app-chart/spec.md (100%) rename openspec/changes/{phase-10-branch-previews => archive/2026-10-28-phase-10-branch-previews}/specs/app-delivery/spec.md (92%) rename openspec/changes/{phase-10-branch-previews => archive/2026-10-28-phase-10-branch-previews}/specs/app-exposure/spec.md (100%) rename openspec/changes/{phase-10-branch-previews => archive/2026-10-28-phase-10-branch-previews}/specs/branch-previews/spec.md (100%) rename openspec/changes/{phase-10-branch-previews => archive/2026-10-28-phase-10-branch-previews}/specs/cluster-init/spec.md (61%) rename openspec/changes/{phase-10-branch-previews => archive/2026-10-28-phase-10-branch-previews}/specs/dev-environment/spec.md (100%) rename openspec/changes/{phase-10-branch-previews => archive/2026-10-28-phase-10-branch-previews}/tasks.md (99%) create mode 100644 openspec/specs/branch-previews/spec.md diff --git a/CLAUDE.md b/CLAUDE.md index 77a4128..811043b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -95,7 +95,16 @@ with the app's Host; `examples/tenant` ships a Claude Code skill and `CLAUDE.md` `tweinmann/shelf-hello`: a push reached a Ready verdict on `greeter` in 127 s. CI runs level 2 when a pull request is ready, chosen by changed paths, and in full after every merge to main. Results in `openspec/changes/archive/2026-10-27-phase-9-agent-interface`. -Next: Phase 10 (branch previews). +Phase 10 complete (2026-10-28): branch previews. `shelf app add|credentials --previews[=N]` +(default 3, at most 10; `--no-previews`) is the operator's decision; the reusable workflow +publishes `branch-` for every branch and deletes it with the branch, with a registry build +cache; a provider `--previews` follows those tags and the ResourceSet `previews` runs each +in its own namespace `--` with a quota, limits and generated secrets, never exposed. +`shelf app status|open --preview `. Release v0.7.0. Accepted with `tweinmann/shelf-hello`: +a new branch reached a Ready preview in about 1 min 45 s (CI 93 s, then 11 s), deleting it +removed the preview within a minute with the workflow's `GITHUB_TOKEN`. Results in +`openspec/changes/archive/2026-10-28-phase-10-branch-previews`. +Next: Phase 11 (verification chain). ## Working agreements @@ -231,7 +240,10 @@ it there when it belongs to one smoke test. - Per app in `shelf-system`, all labelled `shelf.dev/app`: the provider `` (inputs `name`, `url`, `tag`, `insecure`, `domain`, `tunnel`, `quick`, `registry`, `cloudflare` — the last two are connection names; `tunnel` and `quick` never both), `app-` (secret values), - `tunnel-` (named tunnels only). Registry connections are + `tunnel-` (named tunnels only), and with previews `--previews` (label + `shelf.dev/previews=`). A preview runs in namespace `--` (labels + `shelf.dev/app`, `shelf.dev/preview`), so an app name never contains `--`; the slug is + `schema.BranchSlug` of the branch, the tag `branch-`. Registry connections are `connection-registry-` (label `shelf.dev/connection=registry`), and `registry-anonymous` is what an app without one gets. An app's tunnel is `shelf-`, its host `.`; a cluster has no domain, and an app without one answers at diff --git a/README.md b/README.md index 6da9b75..fd7761c 100644 --- a/README.md +++ b/README.md @@ -110,7 +110,7 @@ one starts. | 8b | Connections instead of platform credentials: registry logins and Cloudflare accounts chosen per app, one tunnel per app | ✅ done | | 8d | Apps stay inside the cluster by default, quick tunnels, no cluster domain | ✅ done | | 9 | Agent interface: `--json`, `shelf app status --wait`, `shelf app open` | ✅ done | -| 10 | Branch previews: one isolated preview per branch, discovered from the registry | planned | +| 10 | Branch previews: one isolated preview per branch, discovered from the registry | ✅ done | | 11 | Verification chain: signatures, scans, provenance; exposure only for verified digests | planned | | 12 | Hardening: Pod Security, NetworkPolicies, smoke tests per preview | planned | | 13 | Host: macOS with Colima and Linux with k3s, `shelf doctor`, `shelf destroy` | planned | diff --git a/openspec/changes/phase-10-branch-previews/.openspec.yaml b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/.openspec.yaml similarity index 100% rename from openspec/changes/phase-10-branch-previews/.openspec.yaml rename to openspec/changes/archive/2026-10-28-phase-10-branch-previews/.openspec.yaml diff --git a/openspec/changes/phase-10-branch-previews/design.md b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/design.md similarity index 95% rename from openspec/changes/phase-10-branch-previews/design.md rename to openspec/changes/archive/2026-10-28-phase-10-branch-previews/design.md index 762bb31..7328d6e 100644 --- a/openspec/changes/phase-10-branch-previews/design.md +++ b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/design.md @@ -283,9 +283,8 @@ agent's flow as little as possible. ## Open Questions -- Whether GHCR lets the workflow's `GITHUB_TOKEN` delete a package version of a user-owned - package without a separate PAT. This is answered at level 3. If not, deleting falls back to a - documented manual step, and the specs stay as they are. +- ~~Whether GHCR lets the workflow's `GITHUB_TOKEN` delete a package version of a user-owned + package without a separate PAT.~~ It does: answered at level 3 on 2026-10-28 (see Results). ## Results @@ -302,3 +301,16 @@ from the moment the tag is in the registry, so without the CI build: Both previews kept their own password and volume across a new commit, the limit of two held with three branch tags, and `--no-previews` removed the previews and kept the app. The push to Ready of a real tenant, CI build included, is measured in the level-3 acceptance. + +Level 3 with the private tenant `tweinmann/shelf-hello` and release v0.7.0 on 2026-10-28, app +`gretter` (four components, two databases) with `--previews`: + +| Measurement | Value | +|---|---| +| CI run of the branch push (build, render, push), first build with v0.7.0, cache empty | 1 min 33 s | +| Deploy artifact `branch-try-preview` pushed by CI to the preview Ready | 11 s (10:38:14 to 10:38:25) | +| Push of a new branch to a Ready preview, in total | about 1 min 45 s | +| Branch deleted on GitHub to the preview namespace gone | under 1 min; the tag left GHCR, then 20 s to the namespace gone | + +The `delete-branch` job deleted the tag with the workflow's `GITHUB_TOKEN`; no separate token +is needed. diff --git a/openspec/changes/phase-10-branch-previews/proposal.md b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/proposal.md similarity index 100% rename from openspec/changes/phase-10-branch-previews/proposal.md rename to openspec/changes/archive/2026-10-28-phase-10-branch-previews/proposal.md diff --git a/openspec/changes/phase-10-branch-previews/specs/agent-interface/spec.md b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/agent-interface/spec.md similarity index 87% rename from openspec/changes/phase-10-branch-previews/specs/agent-interface/spec.md rename to openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/agent-interface/spec.md index 8598984..b3995e8 100644 --- a/openspec/changes/phase-10-branch-previews/specs/agent-interface/spec.md +++ b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/agent-interface/spec.md @@ -28,11 +28,11 @@ and `previewLimit` and `previewLimitReached` when the app has previews. ### Requirement: Agent instructions in the tenant template `examples/tenant` SHALL hold a Claude Code skill `.claude/skills/shelf/SKILL.md` and a `CLAUDE.md` -section that tell an agent to push, run `shelf app status --wait --commit --json`, read -the verdict, and fix what its stage and hint name; the app name is a placeholder the operator -fills in. The skill SHALL tell the agent to start the wait in the background and keep working -until it needs the verdict, to check the CI run of its push first when the GitHub CLI is -available, and to wait for its branch's preview with `--preview` when it works on a branch. +section that tell an agent to push, run `shelf app status --wait --commit --json` +(with `--preview ` on a branch), read the verdict, and fix what its stage and hint name; +the app name is a placeholder the operator fills in. The skill SHALL tell the agent to run the +wait in the background and, when the GitHub CLI is available, to check the CI run of its push +first. #### Scenario: Agent loop described - **WHEN** an agent working in a copy of `examples/tenant` reads the skill diff --git a/openspec/changes/phase-10-branch-previews/specs/app-chart/spec.md b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/app-chart/spec.md similarity index 100% rename from openspec/changes/phase-10-branch-previews/specs/app-chart/spec.md rename to openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/app-chart/spec.md diff --git a/openspec/changes/phase-10-branch-previews/specs/app-delivery/spec.md b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/app-delivery/spec.md similarity index 92% rename from openspec/changes/phase-10-branch-previews/specs/app-delivery/spec.md rename to openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/app-delivery/spec.md index 4f9bb30..22e9b47 100644 --- a/openspec/changes/phase-10-branch-previews/specs/app-delivery/spec.md +++ b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/app-delivery/spec.md @@ -41,11 +41,10 @@ branch. ### Requirement: Reusable tenant workflow The reusable workflow `.github/workflows/build.yml` SHALL validate the app.yaml, build every `build:` component for `linux/arm64` as `ghcr.io///`, render the -app.yaml, and push the deploy artifact as `ghcr.io//` tagged `sha-` -and `main` for the default branch or `branch-` for another branch, with the annotation -`dev.shelf.package=` and the source and revision of the commit; when a branch is -deleted, it SHALL delete that branch's artifact. It SHALL reuse image layers between runs -through a build cache in the registry, which only runs that publish write. +app.yaml, and push the deploy artifact `ghcr.io//` tagged `sha-` and +`main` for the default branch or `branch-` for another branch, annotated with +`dev.shelf.package=` and the commit's source and revision. When a branch is deleted, it +SHALL delete that branch's artifact. #### Scenario: Push to the default branch - **WHEN** the workflow runs for a push to the repository's default branch @@ -61,10 +60,6 @@ through a build cache in the registry, which only runs that publish write. - **THEN** it builds the images but pushes neither images nor a deploy artifact - **AND** a push to another branch is no longer such a case: it publishes, as in "Push to another branch" -#### Scenario: Build cache -- **WHEN** a push changes only the source of one component -- **THEN** the build of every component reads its layers from `ghcr.io///:buildcache`, a publishing run writes that cache back, and a pull request only reads it - #### Scenario: Branch deleted - **WHEN** the workflow runs for the deletion of the branch `feature/login` - **THEN** it deletes the package version that carries `branch-feature-login` from `ghcr.io//`, and nothing else @@ -126,3 +121,13 @@ their branch tag, state and commit; `--preview ` SHALL print the same fo #### Scenario: One preview - **WHEN** a user runs `shelf app status hello --preview feature/login` - **THEN** the output shows the preview's namespace `hello--feature-login`, its host, artifact tag, commit, components and five stages + +## ADDED Requirements + +### Requirement: Build cache in the tenant workflow +The reusable workflow SHALL reuse image layers between runs through a build cache in the +registry, `ghcr.io///:buildcache`, which only runs that publish write. + +#### Scenario: Build cache +- **WHEN** a push changes only the source of one component +- **THEN** the build of every component reads its layers from `ghcr.io///:buildcache`, a publishing run writes that cache back, and a pull request only reads it diff --git a/openspec/changes/phase-10-branch-previews/specs/app-exposure/spec.md b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/app-exposure/spec.md similarity index 100% rename from openspec/changes/phase-10-branch-previews/specs/app-exposure/spec.md rename to openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/app-exposure/spec.md diff --git a/openspec/changes/phase-10-branch-previews/specs/branch-previews/spec.md b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/branch-previews/spec.md similarity index 100% rename from openspec/changes/phase-10-branch-previews/specs/branch-previews/spec.md rename to openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/branch-previews/spec.md diff --git a/openspec/changes/phase-10-branch-previews/specs/cluster-init/spec.md b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/cluster-init/spec.md similarity index 61% rename from openspec/changes/phase-10-branch-previews/specs/cluster-init/spec.md rename to openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/cluster-init/spec.md index 15e24dc..aba2511 100644 --- a/openspec/changes/phase-10-branch-previews/specs/cluster-init/spec.md +++ b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/cluster-init/spec.md @@ -5,10 +5,9 @@ ### Requirement: Platform contents The platform artifact SHALL contain Traefik (Helm chart from `oci://ghcr.io/traefik/helm/traefik` in namespace `traefik`, Service of type ClusterIP, ingress class `traefik` that is not the -default, Kubernetes Ingress and CRD providers enabled) the ResourceSet `apps` in -`shelf-system`, which generates every app from the ResourceSetInputProviders labelled -`shelf.dev/app`, and the ResourceSet `previews` in `shelf-system`, which generates every preview -from the providers labelled `shelf.dev/previews`. +default, Kubernetes Ingress and CRD providers enabled) and, in `shelf-system`, the ResourceSet +`apps`, which generates every app from the providers labelled `shelf.dev/app`, and the +ResourceSet `previews`, which generates every preview from those labelled `shelf.dev/previews`. #### Scenario: Platform applied - **WHEN** the installation completes diff --git a/openspec/changes/phase-10-branch-previews/specs/dev-environment/spec.md b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/dev-environment/spec.md similarity index 100% rename from openspec/changes/phase-10-branch-previews/specs/dev-environment/spec.md rename to openspec/changes/archive/2026-10-28-phase-10-branch-previews/specs/dev-environment/spec.md diff --git a/openspec/changes/phase-10-branch-previews/tasks.md b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/tasks.md similarity index 99% rename from openspec/changes/phase-10-branch-previews/tasks.md rename to openspec/changes/archive/2026-10-28-phase-10-branch-previews/tasks.md index af98740..78db8c3 100644 --- a/openspec/changes/phase-10-branch-previews/tasks.md +++ b/openspec/changes/archive/2026-10-28-phase-10-branch-previews/tasks.md @@ -43,7 +43,7 @@ - [x] 7.1 Enable deletes in the dev registry in `hack/cluster-up.sh`, idempotently; verify that `just cluster-up` twice leaves `storage.delete.enabled: true` and that a tag can be deleted (spec dev-environment "Deleting a tag") - [x] 7.2 Add `hack/smoke/previews.sh` and `just smoke-previews` as in design decision 8, including the seconds from push to Ready for a first push and a later commit; verify that it passes on the dev cluster and record RAM per preview and both times in design.md under "Results" -- [ ] 7.3 Add `smoke-previews` to the full set in `.github/workflows/ci.yml` and to `.github/scripts/select-smokes.sh` (`platform/*`, `charts/*`, `hack/smoke/previews.sh`, `internal/cluster/*`); verify the selection on example paths and that the PR run shows it +- [x] 7.3 Add `smoke-previews` to the full set in `.github/workflows/ci.yml` and to `.github/scripts/select-smokes.sh` (`platform/*`, `charts/*`, `hack/smoke/previews.sh`, `internal/cluster/*`); verify the selection on example paths and that the PR run shows it - [x] 7.4 Add `just smoke-previews` to the CLAUDE.md dev-environment table and the README; run `just test` and `openspec validate --all --strict`; both pass ## Workflow follow-up diff --git a/openspec/config.yaml b/openspec/config.yaml index 0050029..776554a 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -40,12 +40,17 @@ context: | `shelf-system`). Each app is a `ResourceSetInputProvider`; the ResourceSet renders its namespace, the deploy artifact source and the HelmRelease of the generic chart `shelf-app`. An exposed app has cloudflared in its namespace with one rule to Traefik, which routes by Host. + - Previews: an app with `--previews` has a second provider `--previews` (type + OCIArtifactTag) that follows the `branch-*` tags of its deploy artifact; the ResourceSet + `previews` runs each tag in a namespace `--` with a quota, limits and secrets the + chart generates, never exposed. A branch build publishes the tag, deleting the branch deletes + it, and the platform only reads the registry. - `shelf init` is split into idempotent layers: `init host` (Phase 13: provide the environment, macOS or Linux), `init cluster` (any kubecontext, no Colima or distribution assumptions) and the wrapper. - Three separate states per app and preview: build (built, scanned, signed), deployment (which digest runs where) and exposure (cluster only, port-forward, tunnel). Exposure is the - operator's decision, never part of app.yaml. Apps, and from Phase 10 previews, are reached by + operator's decision, never part of app.yaml. Apps and previews are reached by port-forward through the API server to Traefik (`shelf app open`); LAN access stays rejected. - Agents read the platform through `--json` documents and `shelf app status --wait --commit`, which only reads: the commit comes from the deploy artifact's revision annotation, never diff --git a/openspec/specs/agent-interface/spec.md b/openspec/specs/agent-interface/spec.md index 4bcce8d..476cbe0 100644 --- a/openspec/specs/agent-interface/spec.md +++ b/openspec/specs/agent-interface/spec.md @@ -132,9 +132,11 @@ to reconcile, or write to `~/.shelf`. ### Requirement: Agent instructions in the tenant template `examples/tenant` SHALL hold a Claude Code skill `.claude/skills/shelf/SKILL.md` and a `CLAUDE.md` -section that tell an agent to push, run `shelf app status --wait --commit --json`, read -the verdict, and fix what its stage and hint name; the app name is a placeholder the operator -fills in. +section that tell an agent to push, run `shelf app status --wait --commit --json` +(with `--preview ` on a branch), read the verdict, and fix what its stage and hint name; +the app name is a placeholder the operator fills in. The skill SHALL tell the agent to run the +wait in the background and, when the GitHub CLI is available, to check the CI run of its push +first. #### Scenario: Agent loop described - **WHEN** an agent working in a copy of `examples/tenant` reads the skill @@ -143,3 +145,37 @@ fills in. #### Scenario: No hook - **WHEN** the tenant template is inspected - **THEN** it ships no Claude Code hook that runs the wait + +#### Scenario: Waiting without idling +- **WHEN** an agent reads the skill after a push +- **THEN** it is told to run the wait in the background, to go on with other work, and to read the verdict before it reports the work as done + +#### Scenario: Broken build found early +- **WHEN** the CI run of the push fails +- **THEN** the skill tells the agent to read the failed run (`gh run watch --exit-status`, `gh run view --log-failed`) instead of waiting for the wait's timeout + +#### Scenario: Work on a branch +- **WHEN** the agent pushed to a branch other than `main` +- **THEN** the skill tells it to add `--preview ` to the wait, and that a first push of a branch takes about a minute longer than a later one + +### Requirement: Previews in the agent interface +`shelf app status --preview ` SHALL accept `--wait`, `--commit`, `--timeout` and +`--json` exactly as for the app, about that preview; the `AppStatus` of an app SHALL list its +previews under `previews`, each with `slug`, `tag`, `namespace`, `host`, `phase` and `commit`, +and `previewLimit` and `previewLimitReached` when the app has previews. + +#### Scenario: Agent waits for its branch +- **WHEN** an agent pushes commit `3f2a9c1` to the branch `feature/login` and runs `shelf app status hello --preview feature/login --wait --commit 3f2a9c1 --json` +- **THEN** it gets a `WaitResult` for `hello--feature-login` with exit status 0, 1 or 2 as for an app, and the app's own verdict plays no part + +#### Scenario: Preview appears only after the push +- **WHEN** the agent waits for a branch whose first artifact is still being built +- **THEN** the wait counts the missing preview as Working and does not fail before its timeout + +#### Scenario: Previews in the JSON of an app +- **WHEN** a user runs `shelf app status hello --json` for an app with two previews and `--previews=3` +- **THEN** `previews` has two entries, `previewLimit` is 3 and `previewLimitReached` is false + +#### Scenario: App without previews +- **WHEN** an app has no previews switched on +- **THEN** its `AppStatus` has no `previews`, `previewLimit` or `previewLimitReached` field diff --git a/openspec/specs/app-chart/spec.md b/openspec/specs/app-chart/spec.md index 92cfe96..585537c 100644 --- a/openspec/specs/app-chart/spec.md +++ b/openspec/specs/app-chart/spec.md @@ -189,3 +189,25 @@ it to that component's Ingress only, through the annotation - **WHEN** the component `api` of app `features` routes `/api` with `stripPrefix: true` - **THEN** a Middleware `api` strips the prefix `/api` - **AND** the Ingress `api` carries `traefik.ingress.kubernetes.io/router.middlewares: features-api@kubernetescrd` + +### Requirement: Generated secrets in preview mode +With `platform.preview` set, the chart SHALL render the Secret `shelf-secrets` itself, with one key +per secret app.yaml declares as `generate: true`: the value already stored in that Secret if it +exists, otherwise a new random URL-safe value of the same length shelf generates for apps. +Without `platform.preview`, the chart MUST NOT render `shelf-secrets`. + +#### Scenario: First install of a preview +- **WHEN** a preview of an app that declares `db-password: { generate: true }` is installed +- **THEN** `shelf-secrets` in the preview namespace has a key `db-password` with a new random value + +#### Scenario: Upgrade of a preview +- **WHEN** the preview is upgraded to a new artifact +- **THEN** `db-password` keeps the value it had + +#### Scenario: An app +- **WHEN** the chart renders an app without `platform.preview` +- **THEN** it renders no `shelf-secrets`, which the platform copies from `shelf-system/app-` as before + +#### Scenario: Golden files +- **WHEN** the chart tests render preview mode +- **THEN** the golden files hold a placeholder instead of the random value, and no generated value is written to any file in the repository diff --git a/openspec/specs/app-delivery/spec.md b/openspec/specs/app-delivery/spec.md index 6c31d79..b72e386 100644 --- a/openspec/specs/app-delivery/spec.md +++ b/openspec/specs/app-delivery/spec.md @@ -69,7 +69,8 @@ chart to resolve in the cluster. ### Requirement: Build plan for tenant CI `shelf build-plan ` SHALL print JSON `{package, builds}`, where `package` is app.yaml's `name` and `builds` lists each component with a `build` directory and its context relative to -the working directory. +the working directory; with `--branch ` it SHALL also print `tag`, the branch tag of that +branch. #### Scenario: Component with a build directory - **WHEN** app.yaml declares a component with `build: ./web` and that directory exists @@ -79,26 +80,48 @@ the working directory. - **WHEN** a component's build directory does not exist - **THEN** the command fails naming the component and the directory +#### Scenario: Branch tag +- **WHEN** the workflow runs `shelf build-plan app.yaml --branch feature/Login` +- **THEN** the JSON holds `"tag": "branch-feature-login"` + ### Requirement: Reusable tenant workflow The reusable workflow `.github/workflows/build.yml` SHALL validate the app.yaml, build every `build:` component for `linux/arm64` as `ghcr.io///`, render the -app.yaml, and push the deploy artifact as `ghcr.io//` tagged `sha-` -and `main`, with the annotation `dev.shelf.package=` and the source and revision of the -commit. +app.yaml, and push the deploy artifact `ghcr.io//` tagged `sha-` and +`main` for the default branch or `branch-` for another branch, annotated with +`dev.shelf.package=` and the commit's source and revision. When a branch is deleted, it +SHALL delete that branch's artifact. #### Scenario: Push to the default branch - **WHEN** the workflow runs for a push to the repository's default branch - **THEN** it pushes the images and the deploy artifact, and outputs `oci://ghcr.io//:main` - **AND** its job summary shows a `shelf app add` command for that artifact +#### Scenario: Push to another branch +- **WHEN** the workflow runs for a push to the branch `feature/login` +- **THEN** it pushes the images and the deploy artifact tagged `sha-` and `branch-feature-login`, and never `main` + #### Scenario: Pull request or other branch -- **WHEN** the workflow runs for a pull request or a non-default branch +- **WHEN** the workflow runs for a pull request, from a fork or not - **THEN** it builds the images but pushes neither images nor a deploy artifact +- **AND** a push to another branch is no longer such a case: it publishes, as in "Push to another branch" + +#### Scenario: Branch deleted +- **WHEN** the workflow runs for the deletion of the branch `feature/login` +- **THEN** it deletes the package version that carries `branch-feature-login` from `ghcr.io//`, and nothing else #### Scenario: Pinned shelf release - **WHEN** the caller sets the input `shelf-version` - **THEN** the workflow installs that release's linux/arm64 binary after checking its checksum, and otherwise the latest release +### Requirement: Build cache in the tenant workflow +The reusable workflow SHALL reuse image layers between runs through a build cache in the +registry, `ghcr.io///:buildcache`, which only runs that publish write. + +#### Scenario: Build cache +- **WHEN** a push changes only the source of one component +- **THEN** the build of every component reads its layers from `ghcr.io///:buildcache`, a publishing run writes that cache back, and a pull request only reads it + ### Requirement: Release publication Pushing a `v*` tag MUST publish a shelf release: CLI binaries for linux and darwin (amd64 and arm64) with checksums, the `shelf-app` chart, and the platform artifact, all at the release @@ -110,9 +133,9 @@ version, and then move the major tag (for example `v0`) before marking the relea ### Requirement: App naming The system SHALL name an app at `shelf app add `, independent of app.yaml's `name`, and MUST -reject a name that is not a DNS label of at most 40 characters or that is reserved for the -platform (`default`, `flux-system`, `traefik`, `cloudflared`, or a name starting with `kube-` or -`shelf-`). +reject a name that is not a DNS label of at most 40 characters, that contains `--` (which separates +an app from its previews), or that is reserved for the platform (`default`, `flux-system`, +`traefik`, `cloudflared`, or a name starting with `kube-` or `shelf-`). #### Scenario: Reserved name - **WHEN** a user runs `shelf app add shelf-web oci://ghcr.io/acme/web:main` @@ -122,6 +145,10 @@ platform (`default`, `flux-system`, `traefik`, `cloudflared`, or a name starting - **WHEN** the name contains upper-case letters or is longer than 40 characters - **THEN** the command fails saying it must be a DNS label of at most 40 characters +#### Scenario: Double hyphen +- **WHEN** a user runs `shelf app add hello--copy oci://ghcr.io/acme/hello:main` +- **THEN** the command fails saying `--` is reserved for previews, before contacting the cluster + ### Requirement: One artifact as several apps The system SHALL allow the same deploy artifact to be added under several app names, each in its own namespace, with the app's name from shelf overriding the package name in app.yaml. @@ -231,15 +258,19 @@ reference and wait for the rollout, changing nothing about the app. ### Requirement: App removal `shelf app rm ` SHALL ask for confirmation unless `--yes` is given, delete the app's -provider, wait until its namespace with all objects and volumes is gone, and delete -`app-` and `tunnel-` from `shelf-system`, while keeping the host secret backup and -saying where it is. +provider and its preview provider, wait until its namespace and every preview namespace with all +objects and volumes are gone, and delete `app-` and `tunnel-` from `shelf-system`, +while keeping the host secret backup and saying where it is. #### Scenario: Remove an app - **WHEN** a user confirms `shelf app rm hello` - **THEN** the namespace `hello`, its volumes and the app's Secrets in `shelf-system` are deleted - **AND** the output names the kept backup file, so a later `shelf app add hello` restores the old secret values +#### Scenario: Remove an app with previews +- **WHEN** a user confirms `shelf app rm hello` and `hello` has the previews `hello--feature-login` and `hello--fix-typo` +- **THEN** both preview namespaces and their volumes are deleted along with the app + #### Scenario: Namespace not created by the platform - **WHEN** a namespace named after the app exists without the label `shelf.dev/app=` - **THEN** removal fails saying the namespace does not belong to the app @@ -291,7 +322,8 @@ state is that of the first stage that is not Ready. `shelf app status` SHALL list every app with its state and, when not Ready, the failing stage and reason in one line; `shelf app status ` SHALL print the app's address, artifact, registry connection, running revision, the git commit that revision was built from, deploy time, -components, and every stage with its message and, if not Ready, its hint. +components, every stage with its message and, if not Ready, its hint, and the app's previews with +their branch tag, state and commit; `--preview ` SHALL print the same for one preview. #### Scenario: No apps - **WHEN** the cluster has no registered apps @@ -309,6 +341,14 @@ components, and every stage with its message and, if not Ready, its hint. - **WHEN** the deploy artifact carries no git revision - **THEN** the commit line is left out +#### Scenario: App with previews +- **WHEN** `hello` has previews for `feature/login` and `fix-typo` +- **THEN** `shelf app status hello` lists both with their tags, states and commits, and the list of all apps shows them under `hello`, not as apps of their own + +#### Scenario: One preview +- **WHEN** a user runs `shelf app status hello --preview feature/login` +- **THEN** the output shows the preview's namespace `hello--feature-login`, its host, artifact tag, commit, components and five stages + ### Requirement: App operations require the platform `shelf app add`, `shelf app credentials` and `shelf app redeploy`, and their admin UI jobs, MUST fail at once when the ResourceSet `apps` is missing from `shelf-system`, before writing anything to diff --git a/openspec/specs/app-exposure/spec.md b/openspec/specs/app-exposure/spec.md index 13f47b2..356a6c5 100644 --- a/openspec/specs/app-exposure/spec.md +++ b/openspec/specs/app-exposure/spec.md @@ -279,3 +279,16 @@ admin UI. #### Scenario: Status while forwarding - **WHEN** `shelf app open hello` runs and the user runs `shelf app status hello` - **THEN** the app's exposure and address are unchanged + +### Requirement: Local access to a preview +`shelf app open --preview ` SHALL forward like `shelf app open `, on the +loopback interface only, with the Host header of the preview's host `--.shelf.internal`, +so that the preview's routes and `stripPrefix` behave as the app's. + +#### Scenario: Preview in a browser +- **WHEN** a user runs `shelf app open hello --preview feature/login` +- **THEN** it prints `http://127.0.0.1:/`, and requests reach the preview `hello--feature-login`, not the app + +#### Scenario: Branch without a preview +- **WHEN** `hello` has no preview for the branch `gone` +- **THEN** the command fails saying so and naming the previews `hello` has, before it listens on any port diff --git a/openspec/specs/branch-previews/spec.md b/openspec/specs/branch-previews/spec.md new file mode 100644 index 0000000..804bc83 --- /dev/null +++ b/openspec/specs/branch-previews/spec.md @@ -0,0 +1,134 @@ +# branch-previews Specification + +## Purpose +Gives each branch of an app its own isolated, running copy of the app's complete stack on the +user's own hardware, discovered from the registry, reachable only from the operator's machine, +and removed when the branch is. + +## Requirements +### Requirement: Previews are the operator's decision +`shelf app add` and `shelf app credentials` SHALL take `--previews[=N]`, which gives the app at +most N previews (3 without a number, at most 10), and `--no-previews`, which removes them all; an app has +no previews unless the operator chose them, and nothing in app.yaml or the tenant repository can +change that. + +#### Scenario: Previews switched on +- **WHEN** a user runs `shelf app add hello oci://ghcr.io/acme/hello:main --previews` +- **THEN** the app gets previews for at most 3 branches + +#### Scenario: Default is off +- **WHEN** an app is added without `--previews` +- **THEN** no branch of it gets a preview, whatever the registry holds + +#### Scenario: Switched off again +- **WHEN** a user runs `shelf app credentials hello --no-previews` +- **THEN** every preview of `hello` is removed with its namespace and volumes, and the app itself keeps running + +#### Scenario: Platform without previews +- **WHEN** `--previews` is given for a cluster whose platform has no ResourceSet `previews` +- **THEN** the command fails at once saying the platform predates previews and that `shelf init cluster` updates it, and writes nothing + +#### Scenario: Limit out of range +- **WHEN** `--previews=0` or `--previews=11` is given +- **THEN** the command fails before contacting the cluster + +#### Scenario: Number without `=` +- **WHEN** `--previews 5` is given +- **THEN** the command fails saying to write `--previews=5`, before contacting the cluster + +### Requirement: Preview provider +An app with previews SHALL have a `ResourceSetInputProvider` `--previews` in `shelf-system`, +labelled `shelf.dev/previews=` and not `shelf.dev/app`, of type `OCIArtifactTag` on the +app's deploy artifact, filtered to tags `branch-*` and limited to N, reading the registry with +the app's registry connection, and checked every 30 seconds. + +#### Scenario: Provider of an app with a registry connection +- **WHEN** `hello` with registry connection `ghcr` and artifact `oci://ghcr.io/acme/hello:main` gets previews +- **THEN** `shelf-system/hello--previews` has type `OCIArtifactTag`, url `oci://ghcr.io/acme/hello`, `includeTag` `^branch-`, limit 3 and the image pull secret `connection-registry-ghcr` + +#### Scenario: Not an app +- **WHEN** the platform lists the apps +- **THEN** `hello--previews` is not among them + +### Requirement: Branch tag +A branch SHALL be published as the tag `branch-`, where the slug is the branch name in +lower case with every run of characters other than letters and digits replaced by one `-`, +without leading or trailing `-`, and, when longer than 20 characters, its first 13 characters +followed by `-` and the first 6 hex digits of the SHA-256 of the branch name. + +#### Scenario: Short branch name +- **WHEN** the branch is `feature/Login` +- **THEN** the tag is `branch-feature-login` + +#### Scenario: Long branch name +- **WHEN** two branches share their first 20 characters after slugging +- **THEN** their tags still differ, and neither slug is longer than 20 characters + +### Requirement: Preview naming +A preview of `` for the tag `branch-` SHALL run in the namespace `--`, +answer at `--.shelf.internal` inside the cluster, and carry the labels +`shelf.dev/app=` and `shelf.dev/preview=`. + +#### Scenario: Preview of a branch +- **WHEN** `hello` has previews and the registry holds `branch-feature-login` +- **THEN** the namespace `hello--feature-login` exists with those labels, and its web component answers at `hello--feature-login.shelf.internal` + +### Requirement: Preview contents +The platform SHALL give each preview the same deploy chain as an app (its deploy artifact at the +branch tag, checked every 30 seconds, the app values, the chart, the release), the app's registry login, a ResourceQuota +(requests of 1 CPU, 2Gi memory, 5Gi storage) and a LimitRange that gives containers without +requests a default; it MUST NOT give a preview a tunnel, cloudflared or a DNS record. + +#### Scenario: Preview of an exposed app +- **WHEN** an app exposed through a Cloudflare connection has a preview +- **THEN** the preview namespace has no cloudflared, and nothing outside the cluster reaches it + +#### Scenario: Over the quota +- **WHEN** a preview's pods would request more than 2Gi memory together +- **THEN** the pods beyond it are refused, and the preview's pods stage says so + +### Requirement: A preview's own state +A preview SHALL have its own volumes and its own secret values, generated in the cluster when the +preview is first created and kept for its lifetime; it MUST NOT share a volume, a secret value or a +database with the app or with another preview, and its secrets have no host backup. + +#### Scenario: Two branches with a database each +- **WHEN** `hello` with a Postgres component has previews for two branches +- **THEN** each preview runs its own Postgres with its own volume and its own generated password, both different from the app's + +#### Scenario: Preview updated +- **WHEN** a new commit is pushed to a branch that has a preview +- **THEN** the preview rolls out the new artifact and keeps its secret values and its data + +### Requirement: Preview removal +The platform SHALL remove a preview, with its namespace and volumes, when its tag disappears from +the registry, when the app's previews are switched off, and when the app is removed. + +#### Scenario: Branch deleted +- **WHEN** the tag `branch-feature-login` is deleted from the registry +- **THEN** within a few minutes the namespace `hello--feature-login` and its volumes are gone, and the app and its other previews are unchanged + +### Requirement: Preview limit +An app SHALL have at most N previews at a time, chosen by the provider from the branch tags, and +`shelf app status ` SHALL say when the limit is reached. + +#### Scenario: More branches than the limit +- **WHEN** `hello` has `--previews=2` and the registry holds three branch tags +- **THEN** exactly two previews exist, and `shelf app status hello` says the preview limit of 2 is reached + +### Requirement: Previews are never exposed +`--cloudflare`, `--domain` and `--quick` SHALL apply to the app only; a preview MUST be reachable +only inside the cluster and through `shelf app open --preview `. + +#### Scenario: Quick tunnel app +- **WHEN** an app with a quick tunnel has previews +- **THEN** its previews have no quick tunnel and no `*.trycloudflare.com` address + +### Requirement: Turnaround of a preview +A new commit on a branch with a preview SHALL be Ready in the preview within the CI run plus at +most 30 seconds plus its rollout, and a first push of a new branch within the CI run plus at most +60 seconds plus the first install; `smoke-previews` SHALL measure both without CI. + +#### Scenario: Measured at level 2 +- **WHEN** `just smoke-previews` pushes the first artifact of a branch and later a second one +- **THEN** it prints the seconds from each push to the preview's Ready verdict, and the results of the change record them diff --git a/openspec/specs/cluster-init/spec.md b/openspec/specs/cluster-init/spec.md index ae0f210..fdf1c02 100644 --- a/openspec/specs/cluster-init/spec.md +++ b/openspec/specs/cluster-init/spec.md @@ -85,13 +85,13 @@ from the ConfigMap `flux-system/shelf-config`. ### Requirement: Platform contents The platform artifact SHALL contain Traefik (Helm chart from `oci://ghcr.io/traefik/helm/traefik` in namespace `traefik`, Service of type ClusterIP, ingress class `traefik` that is not the -default, Kubernetes Ingress and CRD providers enabled) and the ResourceSet `apps` in -`shelf-system`, which generates every app from the ResourceSetInputProviders labelled -`shelf.dev/app`. +default, Kubernetes Ingress and CRD providers enabled) and, in `shelf-system`, the ResourceSet +`apps`, which generates every app from the providers labelled `shelf.dev/app`, and the +ResourceSet `previews`, which generates every preview from those labelled `shelf.dev/previews`. #### Scenario: Platform applied - **WHEN** the installation completes -- **THEN** Traefik runs in `traefik` reachable at `traefik.traefik.svc.cluster.local:80` and the ResourceSet `shelf-system/apps` exists +- **THEN** Traefik runs in `traefik` reachable at `traefik.traefik.svc.cluster.local:80` and the ResourceSets `shelf-system/apps` and `shelf-system/previews` exist ### Requirement: System namespace and cluster settings The system SHALL apply the namespace `shelf-system` (labelled diff --git a/openspec/specs/dev-environment/spec.md b/openspec/specs/dev-environment/spec.md index 1244147..268147b 100644 --- a/openspec/specs/dev-environment/spec.md +++ b/openspec/specs/dev-environment/spec.md @@ -41,7 +41,7 @@ container's own host name. `just cluster-up` SHALL create, or start if it exists, the k3d cluster `shelf-dev` with the k3s image pinned in the Dockerfile, without k3s's own Traefik and without k3d's load balancer, its API server on the container's loopback, and the plain-HTTP registry `shelf-registry:5000`, reachable -by that name from pods and from the devcontainer. It MUST write the kubeconfig only to +by that name from pods and from the devcontainer, which allows deleting manifests. It MUST write the kubeconfig only to `KUBECONFIG` and never change a default kubeconfig or switch a context. #### Scenario: After a container restart @@ -52,6 +52,10 @@ by that name from pods and from the devcontainer. It MUST write the kubeconfig o - **WHEN** `just cluster-reset` runs - **THEN** cluster and registry are deleted and created empty, and `just init-cluster` pushes the platform and chart again before installing them +#### Scenario: Deleting a tag +- **WHEN** a smoke test deletes a branch tag from `shelf-registry:5000` +- **THEN** the registry accepts the deletion, so a preview can be removed at level 2 as on GHCR + ### Requirement: Three test levels Checks SHALL be split into level 1 (no cluster: `just test`, which runs gofmt, `go vet`, `go test -race`, Helm lint, kubeconform, example validation and `openspec validate --all --strict`), @@ -72,7 +76,7 @@ Cloudflare), and a task that needs level 2 or 3 MUST say so. #### Scenario: Level 2 in full - **WHEN** a commit is pushed to `main`, or a pull request carries the label `level-2-full` -- **THEN** CI runs `smoke-secrets`, `smoke-chart`, `smoke-init`, `smoke-apps` and `smoke-agent` with `SMOKE_FULL=1` +- **THEN** CI runs `smoke-secrets`, `smoke-chart`, `smoke-init`, `smoke-apps`, `smoke-agent` and `smoke-previews` with `SMOKE_FULL=1` #### Scenario: main fails - **WHEN** CI fails on `main`