diff --git a/CLAUDE.md b/CLAUDE.md index 74646e0..eefebf8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 --wait --commit ` 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 @@ -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): diff --git a/README.md b/README.md index aa19f0d..0a2f1de 100644 --- a/README.md +++ b/README.md @@ -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 | diff --git a/openspec/changes/phase-9-agent-interface/.openspec.yaml b/openspec/changes/archive/2026-10-27-phase-9-agent-interface/.openspec.yaml similarity index 100% rename from openspec/changes/phase-9-agent-interface/.openspec.yaml rename to openspec/changes/archive/2026-10-27-phase-9-agent-interface/.openspec.yaml diff --git a/openspec/changes/phase-9-agent-interface/design.md b/openspec/changes/archive/2026-10-27-phase-9-agent-interface/design.md similarity index 100% rename from openspec/changes/phase-9-agent-interface/design.md rename to openspec/changes/archive/2026-10-27-phase-9-agent-interface/design.md diff --git a/openspec/changes/phase-9-agent-interface/proposal.md b/openspec/changes/archive/2026-10-27-phase-9-agent-interface/proposal.md similarity index 100% rename from openspec/changes/phase-9-agent-interface/proposal.md rename to openspec/changes/archive/2026-10-27-phase-9-agent-interface/proposal.md diff --git a/openspec/changes/phase-9-agent-interface/specs/agent-interface/spec.md b/openspec/changes/archive/2026-10-27-phase-9-agent-interface/specs/agent-interface/spec.md similarity index 100% rename from openspec/changes/phase-9-agent-interface/specs/agent-interface/spec.md rename to openspec/changes/archive/2026-10-27-phase-9-agent-interface/specs/agent-interface/spec.md diff --git a/openspec/changes/phase-9-agent-interface/specs/app-delivery/spec.md b/openspec/changes/archive/2026-10-27-phase-9-agent-interface/specs/app-delivery/spec.md similarity index 100% rename from openspec/changes/phase-9-agent-interface/specs/app-delivery/spec.md rename to openspec/changes/archive/2026-10-27-phase-9-agent-interface/specs/app-delivery/spec.md diff --git a/openspec/changes/phase-9-agent-interface/specs/app-exposure/spec.md b/openspec/changes/archive/2026-10-27-phase-9-agent-interface/specs/app-exposure/spec.md similarity index 100% rename from openspec/changes/phase-9-agent-interface/specs/app-exposure/spec.md rename to openspec/changes/archive/2026-10-27-phase-9-agent-interface/specs/app-exposure/spec.md diff --git a/openspec/changes/phase-9-agent-interface/specs/dev-environment/spec.md b/openspec/changes/archive/2026-10-27-phase-9-agent-interface/specs/dev-environment/spec.md similarity index 100% rename from openspec/changes/phase-9-agent-interface/specs/dev-environment/spec.md rename to openspec/changes/archive/2026-10-27-phase-9-agent-interface/specs/dev-environment/spec.md diff --git a/openspec/changes/phase-9-agent-interface/tasks.md b/openspec/changes/archive/2026-10-27-phase-9-agent-interface/tasks.md similarity index 99% rename from openspec/changes/phase-9-agent-interface/tasks.md rename to openspec/changes/archive/2026-10-27-phase-9-agent-interface/tasks.md index baca79e..d67d448 100644 --- a/openspec/changes/phase-9-agent-interface/tasks.md +++ b/openspec/changes/archive/2026-10-27-phase-9-agent-interface/tasks.md @@ -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 diff --git a/openspec/config.yaml b/openspec/config.yaml index c372ba6..0050029 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -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. diff --git a/openspec/specs/agent-interface/spec.md b/openspec/specs/agent-interface/spec.md new file mode 100644 index 0000000..4bcce8d --- /dev/null +++ b/openspec/specs/agent-interface/spec.md @@ -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 --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 `, 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 --wait --commit --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 diff --git a/openspec/specs/app-delivery/spec.md b/openspec/specs/app-delivery/spec.md index fe19749..6c31d79 100644 --- a/openspec/specs/app-delivery/spec.md +++ b/openspec/specs/app-delivery/spec.md @@ -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 ` 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 @@ -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 diff --git a/openspec/specs/app-exposure/spec.md b/openspec/specs/app-exposure/spec.md index 7f8451d..13f47b2 100644 --- a/openspec/specs/app-exposure/spec.md +++ b/openspec/specs/app-exposure/spec.md @@ -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 ` 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:/`, 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 diff --git a/openspec/specs/dev-environment/spec.md b/openspec/specs/dev-environment/spec.md index 7da1ec2..1244147 100644 --- a/openspec/specs/dev-environment/spec.md +++ b/openspec/specs/dev-environment/spec.md @@ -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