Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 14 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-<slug>` for every branch and deletes it with the branch, with a registry build
cache; a provider `<app>--previews` follows those tags and the ResourceSet `previews` runs each
in its own namespace `<app>--<slug>` with a quota, limits and generated secrets, never exposed.
`shelf app status|open --preview <branch>`. 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

Expand Down Expand Up @@ -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 `<app>` (inputs `name`,
`url`, `tag`, `insecure`, `domain`, `tunnel`, `quick`, `registry`, `cloudflare` — the last two
are connection names; `tunnel` and `quick` never both), `app-<app>` (secret values),
`tunnel-<app>` (named tunnels only). Registry connections are
`tunnel-<app>` (named tunnels only), and with previews `<app>--previews` (label
`shelf.dev/previews=<app>`). A preview runs in namespace `<app>--<slug>` (labels
`shelf.dev/app`, `shelf.dev/preview`), so an app name never contains `--`; the slug is
`schema.BranchSlug` of the branch, the tag `branch-<slug>`. Registry connections are
`connection-registry-<name>` (label `shelf.dev/connection=registry`), and `registry-anonymous`
is what an app without one gets. An app's tunnel is `shelf<host-suffix>-<app>`, its host
`<app><host-suffix>.<domain>`; a cluster has no domain, and an app without one answers at
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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 <app> --wait --commit <sha> --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 <app> --wait --commit <sha> --json`
(with `--preview <branch>` 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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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/<owner>/<package>/<component>`, render the
app.yaml, and push the deploy artifact as `ghcr.io/<owner>/<package>` tagged `sha-<shortsha>`
and `main` for the default branch or `branch-<slug>` for another branch, with the annotation
`dev.shelf.package=<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/<owner>/<package>` tagged `sha-<shortsha>` and
`main` for the default branch or `branch-<slug>` for another branch, annotated with
`dev.shelf.package=<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
Expand All @@ -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/<owner>/<package>/<component>: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/<owner>/<package>`, and nothing else
Expand Down Expand Up @@ -126,3 +121,13 @@ their branch tag, state and commit; `--preview <branch>` 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/<owner>/<package>/<component>: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/<owner>/<package>/<component>:buildcache`, a publishing run writes that cache back, and a pull request only reads it
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 6 additions & 1 deletion openspec/config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<app>--previews` (type
OCIArtifactTag) that follows the `branch-*` tags of its deploy artifact; the ResourceSet
`previews` runs each tag in a namespace `<app>--<slug>` 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
Expand Down
42 changes: 39 additions & 3 deletions openspec/specs/agent-interface/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <app> --wait --commit <sha> --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 <app> --wait --commit <sha> --json`
(with `--preview <branch>` 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
Expand All @@ -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 <branch>` 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 <app> --preview <branch>` 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
22 changes: 22 additions & 0 deletions openspec/specs/app-chart/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-<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
Loading
Loading