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
18 changes: 17 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,16 @@ Colima and Linux, formerly 9), 14 service and installer (formerly 10), 15 operat
the context; the reference apps (formerly 13) became the acceptance of Phases 10 and 16. The Mac
lock-in is dropped; exposure stays the operator's decision; LAN access with certificates stays
rejected and previews are reached by port-forward.
Next: Phase 9 (agent interface: `--json`, `shelf app status --wait`, `shelf app open`).
Phase 9 complete (2026-10-27): the agent interface. `--json` on `app status`, `app tags`,
`connection list` and `version` prints versioned documents (`shelf.dev/v1alpha1` plus a `kind`);
`shelf app status <app> --wait --commit <sha>` waits until the app runs the artifact built from
that commit and ends with a verdict (exit 0 Ready, 1 Failed, 2 TimedOut), read-only;
`shelf app status` shows the running commit; `shelf app open` forwards 127.0.0.1 to Traefik
with the app's Host; `examples/tenant` ships a Claude Code skill and `CLAUDE.md`. Accepted with
`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).

## Working agreements

Expand Down Expand Up @@ -253,6 +262,13 @@ it there when it belongs to one smoke test.
server-sent events. One change runs at a time, and every one is written to `~/.shelf/audit.log`
- Files under `~/.shelf` belong to `internal/hostcfg`: mode 0600 in a 0700 directory, written
atomically. Passwords are PBKDF2-SHA256 with the algorithm in the stored string
- What `--json` prints are document types of their own in `internal/cli/json.go`, never the
structs of `ops` or `cluster`: `apiVersion` `shelf.dev/v1alpha1`, a `kind`, empty fields left
out rather than null, one golden file per kind in `internal/cli/testdata/json`. Within a version
fields are only added; a failing command prints an `Error` document
- Which values a Helm release holds is decided by its `configDigest`, which `cluster.ConfigDigest`
computes as helm-controller does, never by timestamps: after a failed upgrade, its failure and
its rollback are both newer than the values that replaced it
- Chart tests run `helm template` from Go (`internal/chart`); they read the chart files
themselves so that go test's cache notices chart changes
- Adding a Go module in a devcontainer built before the `/go/pkg` fix (see Phase 1 results):
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ one starts.
| 8 | Adding, changing and removing apps from the browser | ✅ done |
| 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` | planned |
| 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 |
| 11 | Verification chain: signatures, scans, provenance; exposure only for verified digests | planned |
| 12 | Hardening: Pod Security, NetworkPolicies, smoke tests per preview | planned |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@
- [x] 7.2 Rework `.github/workflows/ci.yml` as in design decision 8 (plan job, label and draft rules, concurrency, `SMOKE_FULL`, Go cache, `ci-main-red` issue on main); verify the plan logic by running its script for every event kind
- [x] 7.3 Add `SMOKE_FULL` and the Flux nudge to `hack/smoke/agent.sh`, and limit `gofmt` in `just test` to tracked files; verify with `just test` and `just smoke-agent` with `SMOKE_FULL=0` and `1`
- [x] 7.4 Gate `release.yml` on a successful CI run on main; verify the query against the GitHub API for a green commit and an unknown one
- [ ] 7.5 Update the spec `dev-environment` (delta), CLAUDE.md and the context; verify `openspec validate --all --strict` and that a pull request run shows the selected matrix in its summary
- [x] 7.5 Update the spec `dev-environment` (delta), CLAUDE.md and the context; verify `openspec validate --all --strict` and that a pull request run shows the selected matrix in its summary

## Workflow follow-up

Expand Down
7 changes: 5 additions & 2 deletions openspec/config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,11 @@ context: |
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. Previews are reached by port-forward through
the API server to Traefik (`shelf app open`, Phase 9); LAN access stays rejected.
operator's decision, never part of app.yaml. Apps, and from Phase 10 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
from a forge API.
- Test levels: 1 is `just test` without a cluster (also CI), 2 the k3d cluster `shelf-dev` in
the devcontainer (`just smoke-*`; in CI when a pull request is ready or labelled `level-2`,
chosen by changed paths, and in full on main), 3 the mini and real Cloudflare.
Expand Down
145 changes: 145 additions & 0 deletions openspec/specs/agent-interface/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
# agent-interface Specification

## Purpose
The contract between shelf and the coding agents that work in tenant repositories: machine-readable
JSON documents for the read-only commands, a wait that ends in a verdict an agent can act on, and
the instructions the tenant template gives an agent about that loop.

## Requirements

### Requirement: Versioned JSON documents
A command run with `--json` SHALL print exactly one JSON object to stdout and nothing else there,
with the fields `apiVersion` (`shelf.dev/v1alpha1`) and `kind` naming the document. Progress,
hints and warnings SHALL go to stderr only.

#### Scenario: Status of all apps as JSON
- **WHEN** a user runs `shelf app status --json` against a cluster with the apps `greeter` and `hello`
- **THEN** stdout is one JSON object with `apiVersion` `shelf.dev/v1alpha1`, `kind` `AppList` and an `items` array with one entry per app
- **AND** stdout parses as JSON without stripping any line

#### Scenario: No apps
- **WHEN** a user runs `shelf app status --json` against a cluster without apps
- **THEN** it prints an `AppList` with an empty `items` array instead of "No apps yet."

### Requirement: Errors as JSON
A command run with `--json` that fails SHALL print a document of kind `Error` with a `message` to
stdout, write the same message to stderr, and exit with status 1.

#### Scenario: Unknown app
- **WHEN** a user runs `shelf app status nope --json` and no app `nope` exists
- **THEN** stdout is `{"apiVersion":"shelf.dev/v1alpha1","kind":"Error","message":"app nope does not exist"}` and the exit status is 1

#### Scenario: Cluster unreachable
- **WHEN** a user runs `shelf app status --json` and the API server does not answer
- **THEN** stdout is an `Error` document with the reason, and the exit status is 1

### Requirement: Stable fields within a version
Within one `apiVersion`, a field of a JSON document SHALL never be removed, renamed or change its
type or meaning; new fields MAY be added, and a consumer is expected to ignore fields it does not
know. A field without a value SHALL be omitted, never set to `null`.

#### Scenario: Field added in a later release
- **WHEN** a later release adds a field to `AppStatus`
- **THEN** `apiVersion` stays `shelf.dev/v1alpha1` and every earlier field keeps its name, type and meaning

#### Scenario: Incompatible change
- **WHEN** a field has to change its meaning
- **THEN** the change ships as a new `apiVersion`, and the golden file of the old document fails until it is renamed with it

### Requirement: Commands with JSON output
`--json` SHALL be offered by `shelf app status` (kind `AppList` without a name, `AppStatus` with
one, `WaitResult` with `--wait`), `shelf app tags` (`TagList`), `shelf connection list`
(`ConnectionList`) and `shelf version` (`Version`).

#### Scenario: One app in detail
- **WHEN** a user runs `shelf app status hello --json` for a healthy app
- **THEN** the `AppStatus` holds the app's name, phase, address, artifact, registry connection, exposure, revision, commit, deploy time, components with their addresses, and the five stages each with name, object, phase and, where present, reason, message and hint

#### Scenario: Tags
- **WHEN** a user runs `shelf app tags hello --json`
- **THEN** the `TagList` lists the tags newest first, and the tag the app runs with has `current: true`

#### Scenario: Version
- **WHEN** a user runs `shelf version --json`
- **THEN** the `Version` document holds the shelf version and the app.yaml `apiVersion` it reads

### Requirement: No secret values in JSON
No JSON document SHALL contain a secret value or a token. `shelf app secrets` SHALL NOT offer
`--json`, and `ConnectionList` SHALL hold each connection's kind, name, account or user, and the
apps that use it, never its token.

#### Scenario: Connections as JSON
- **WHEN** a user runs `shelf connection list --json` with a registry and a Cloudflare connection
- **THEN** each entry has `kind`, `name` and `apps`, the registry entry its user, the Cloudflare entry its account or that this machine does not hold it, and no field of the document holds either token

#### Scenario: Secrets
- **WHEN** a user runs `shelf app secrets hello --json`
- **THEN** the command fails because the flag is unknown

### Requirement: Waiting for an app to settle
`shelf app status <app> --wait` SHALL poll the app's chain until it is Ready or a stage is
Failed, or until `--timeout` (default 10 minutes) runs out, and then print a verdict.

#### Scenario: App already healthy
- **WHEN** a user runs `shelf app status hello --wait` for a Ready app
- **THEN** it returns at once with the outcome `Ready`

#### Scenario: Rollout still running
- **WHEN** the app's pods are starting and become ready a minute later
- **THEN** the command returns after they are ready, with the outcome `Ready`

### Requirement: Waiting for a commit
With `--commit <sha>`, the wait SHALL first wait until the app's deploy artifact was built from that
git commit, matching a full SHA or a prefix of at least 7 hex digits, and then until every stage
has caught up with that artifact; it SHALL NOT report Ready for the previous artifact.

#### Scenario: Push still in CI
- **WHEN** an agent runs `shelf app status hello --wait --commit 42a964e --json` right after `git push`, and the artifact of that commit arrives four minutes later
- **THEN** the command keeps waiting while the previous artifact runs, and returns `Ready` only once the release built from `42a964e` has rolled out

#### Scenario: Short prefix
- **WHEN** `--commit` is given fewer than 7 hex digits or something that is not hex
- **THEN** the command fails at once without waiting

#### Scenario: Artifact without a commit
- **WHEN** the app's deploy artifact carries no git revision, as one pushed by hand may not
- **THEN** the wait for a commit runs into its timeout, and the verdict says that the artifact names no commit

### Requirement: Wait verdict and exit status
The wait SHALL end with a verdict: outcome `Ready`, `Failed` or `TimedOut`, the commit and revision
that run, and, unless Ready, the first stage that is not Ready with its reason, message and hint.
The exit status SHALL be 0 for Ready, 1 for Failed and 2 for TimedOut.

#### Scenario: Image cannot be pulled
- **WHEN** the awaited commit's release starts a pod that waits in `ImagePullBackOff`
- **THEN** the verdict is `Failed` with the stage "the pods", the reason `ImagePullBackOff` and the hint that the image cannot be pulled, and the exit status is 1

#### Scenario: Timeout
- **WHEN** the app is still Working when `--timeout 2m` runs out
- **THEN** the verdict is `TimedOut` naming the stage that is still Working, and the exit status is 2

#### Scenario: Error before a verdict
- **WHEN** the app does not exist or the cluster cannot be reached
- **THEN** the command prints an error, not a verdict, and exits with status 1

### Requirement: Waiting is read-only
`shelf app status` with or without `--wait` SHALL NOT write to the cluster, ask a Flux controller
to reconcile, or write to `~/.shelf`.

#### Scenario: Waiting for a new artifact
- **WHEN** an agent waits for a commit that is not yet in the cluster
- **THEN** shelf only reads, and the artifact arrives at the deploy artifact's own polling interval

### 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.

#### Scenario: Agent loop described
- **WHEN** an agent working in a copy of `examples/tenant` reads the skill
- **THEN** it finds the wait command with `--commit` and `--json`, the meaning of the three exit statuses, and that it cannot make the app public

#### Scenario: No hook
- **WHEN** the tenant template is inspected
- **THEN** it ships no Claude Code hook that runs the wait
12 changes: 10 additions & 2 deletions openspec/specs/app-delivery/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -290,8 +290,8 @@ state is that of the first stage that is not Ready.
### Requirement: App status command
`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 <app>` SHALL print the app's address, artifact, registry
connection, running revision, deploy time, components, and every stage with its message and, if
not Ready, its hint.
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.

#### Scenario: No apps
- **WHEN** the cluster has no registered apps
Expand All @@ -301,6 +301,14 @@ not Ready, its hint.
- **WHEN** a user runs `shelf app status hello` for a healthy app
- **THEN** the output shows `hello: Ready`, the artifact reference, the revision, and all five stages as Ready

#### Scenario: Commit of the running artifact
- **WHEN** the app's deploy artifact was pushed by the reusable workflow for commit `42a964eb0b4b…`
- **THEN** `shelf app status hello` shows that commit, read from the artifact's revision annotation as the cluster reports it, without calling a forge API

#### Scenario: Artifact without a commit
- **WHEN** the deploy artifact carries no git revision
- **THEN** the commit line is left out

### 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
Expand Down
43 changes: 43 additions & 0 deletions openspec/specs/app-exposure/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -236,3 +236,46 @@ on a public domain, and the components' links SHALL follow the app's address.
#### Scenario: Private app
- **WHEN** an app has no tunnel
- **THEN** the pages show its host as inside the cluster only, without a link

### Requirement: Local access through a port-forward
`shelf app open <app>` SHALL listen on a local port and forward every request through the API
server to Traefik with the Host header set to the app's own host, so that routes and `stripPrefix`
behave as through a tunnel; it SHALL work for private and exposed apps alike and run until stopped.

#### Scenario: Private app in a browser
- **WHEN** a user runs `shelf app open hello` for an app without exposure that routes `/` and `/api` with `stripPrefix`
- **THEN** it prints `http://127.0.0.1:<port>/`, a request to `/api/x` reaches the `/api` component as `/x`, and no tunnel, DNS record or cloudflared is created

#### Scenario: Stopped
- **WHEN** the user presses Ctrl-C
- **THEN** the listener and the forward are closed and the command exits with status 0

#### Scenario: App does not exist
- **WHEN** a user runs `shelf app open nope`
- **THEN** it fails saying that app nope does not exist, before it listens on any port

### Requirement: Local access stays on the loopback interface
`shelf app open` MUST listen on `127.0.0.1` only and offer no option for another address. The
port SHALL be chosen freely unless `--port` names one, and `--browser` SHALL open the printed
address in the default browser; without it no browser is started.

#### Scenario: Chosen port
- **WHEN** a user runs `shelf app open hello --port 8081` and the port is free
- **THEN** it listens on `127.0.0.1:8081` and on no other address

#### Scenario: Port in use
- **WHEN** the port given with `--port` is in use
- **THEN** the command fails saying so, without forwarding anything

#### Scenario: No browser by default
- **WHEN** a user runs `shelf app open hello` without `--browser`
- **THEN** no browser is started and only the address is printed

### Requirement: Local access is not an exposure
`shelf app open` SHALL NOT change the app's registration, exposure, tunnel or DNS record, SHALL NOT
write to the cluster beyond the port-forward the API server opens, and SHALL NOT appear in the
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
22 changes: 19 additions & 3 deletions openspec/specs/dev-environment/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,12 +59,28 @@ level 2 (the k3d cluster: the `just smoke-*` recipes), and level 3 (the Mac mini
Cloudflare), and a task that needs level 2 or 3 MUST say so.

#### Scenario: Level 1 in CI
- **WHEN** a commit is pushed to `main` or a pull request is opened
- **WHEN** a commit is pushed to `main` or a pull request is opened or pushed to
- **THEN** CI runs `just test` inside the devcontainer image on an arm64 runner

#### Scenario: Level 2 in CI
- **WHEN** a pull request is opened
- **THEN** CI also runs `smoke-secrets`, `smoke-chart`, `smoke-init` and `smoke-apps`, each against a fresh k3d cluster of its own, side by side
- **WHEN** a pull request is opened or reopened as ready, leaves draft, or is pushed to or labelled while it carries the label `level-2`
- **THEN** CI also runs the smoke tests its changed paths need, chosen by `.github/scripts/select-smokes.sh`, each against a fresh k3d cluster of its own, side by side, with `SMOKE_FULL=0`

#### Scenario: Documentation only
- **WHEN** a pull request changes only planning, documentation or examples
- **THEN** CI runs no smoke test, and a path the selection does not know runs all of them

#### 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`

#### Scenario: main fails
- **WHEN** CI fails on `main`
- **THEN** it opens an issue labelled `ci-main-red`, or comments on the one that is open, with the commit and the run

#### Scenario: Release gate
- **WHEN** a release tag is pushed for a commit whose CI run on `main` did not succeed
- **THEN** `release.yml` stops before it publishes anything

### Requirement: Footprint on the host Docker daemon
The only objects shelf development SHALL create on the host Docker daemon are the devcontainer
Expand Down
Loading