From 07c94a459a28ac4f904e1a11e04366062ae89d46 Mon Sep 17 00:00:00 2001 From: tweinmann Date: Thu, 29 Oct 2026 19:47:08 +0000 Subject: [PATCH 1/7] Add the onboarding phase as phase 5, move remote host to phase 6 Releases, siding skill --install with the permission snippet, EnvFileMissing, the lint rule LocalhostURL and a default snapshot, as agreed after reviewing the user journey. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 3 +- .../changes/phase-5-onboarding/.openspec.yaml | 3 ++ .../changes/phase-5-onboarding/proposal.md | 35 +++++++++++++++++++ .../.openspec.yaml | 0 .../proposal.md | 2 +- openspec/config.yaml | 6 ++-- 6 files changed, 45 insertions(+), 4 deletions(-) create mode 100644 openspec/changes/phase-5-onboarding/.openspec.yaml create mode 100644 openspec/changes/phase-5-onboarding/proposal.md rename openspec/changes/{phase-5-remote-host => phase-6-remote-host}/.openspec.yaml (100%) rename openspec/changes/{phase-5-remote-host => phase-6-remote-host}/proposal.md (98%) diff --git a/CLAUDE.md b/CLAUDE.md index 9f827cd..1a01618 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,7 +24,8 @@ today: `setup [--port] [--budget] [--builds] [--idle]`, `teardown [--snapshots]` `snapshot save|ls|rm`, `gc`, `lint`, `ui`, `skill`; routing by host and path through `siding-proxy`; a memory budget with a start queue and learned peaks, where idle stacks make room (the verdict `Stopped`); build slots; `just smoke-stacks`, `just build-darwin`. Next: -Phase 5 (`phase-5-remote-host`, v0.5), starting with `/opsx:propose`. +Phase 5 (`phase-5-onboarding`, v0.5), starting with `/opsx:propose`; then Phase 6 +(`phase-6-remote-host`, v0.6). ## Working agreements diff --git a/openspec/changes/phase-5-onboarding/.openspec.yaml b/openspec/changes/phase-5-onboarding/.openspec.yaml new file mode 100644 index 0000000..c1fa2fe --- /dev/null +++ b/openspec/changes/phase-5-onboarding/.openspec.yaml @@ -0,0 +1,3 @@ +schema: spec-driven +created: 2026-10-29 +skip_specs: true diff --git a/openspec/changes/phase-5-onboarding/proposal.md b/openspec/changes/phase-5-onboarding/proposal.md new file mode 100644 index 0000000..102e937 --- /dev/null +++ b/openspec/changes/phase-5-onboarding/proposal.md @@ -0,0 +1,35 @@ +# Proposal + +> Draft. This change holds the roadmap text only and is marked `skip_specs: true`. +> `/opsx:propose` turns it into a full change: it writes the delta specs, `design.md` and +> `tasks.md`, revises this proposal, and removes `skip_specs` from `.openspec.yaml`. + +## Why + +The core works once siding is set up, but the first attempt fails before and beside it: siding +can only be built from source, the skill is missing in new worktrees, Claude Code asks for every +`siding up`, a new worktree has no `.env` and an empty database, and apps that call +`localhost:` break behind the proxy without a warning. + +## What Changes + +Roadmap v0.5 (decisions agreed with the maintainer on 2026-10-29): + +- Releases: unsigned binaries for macOS and Linux (arm64, amd64) on GitHub Releases, built by CI + on every tag; an install note for macOS's quarantine flag. Homebrew and notarisation later. +- `siding skill --install` writes `.claude/skills/siding/SKILL.md` and says to commit it; + without the flag the skill is only printed, as today. siding prints the permission snippet for + `.claude/settings.json` and never writes that file. +- A missing `.env` that the compose file uses: `up` fails with `EnvFileMissing` and the `cp` + command from the main worktree, `lint` warns; siding never copies it. +- `lint` rule `LocalhostURL`: an environment value pointing at `localhost:`. +- A default snapshot: `siding snapshot save --default`; the first `up` of a stack seeds + from it unless `--seed none`; without a default, nothing changes. + +## Capabilities + +To be decided at `/opsx:propose`. + +## Impact + +To be decided at `/opsx:propose`. diff --git a/openspec/changes/phase-5-remote-host/.openspec.yaml b/openspec/changes/phase-6-remote-host/.openspec.yaml similarity index 100% rename from openspec/changes/phase-5-remote-host/.openspec.yaml rename to openspec/changes/phase-6-remote-host/.openspec.yaml diff --git a/openspec/changes/phase-5-remote-host/proposal.md b/openspec/changes/phase-6-remote-host/proposal.md similarity index 98% rename from openspec/changes/phase-5-remote-host/proposal.md rename to openspec/changes/phase-6-remote-host/proposal.md index d7c1709..2f1128e 100644 --- a/openspec/changes/phase-5-remote-host/proposal.md +++ b/openspec/changes/phase-6-remote-host/proposal.md @@ -11,7 +11,7 @@ keeps the same names and the same commands. ## What Changes -Roadmap v0.5: +Roadmap v0.6: - Stacks on a remote Docker host, chosen through a Docker context. - A local forwarder so that `*.localhost` reaches stacks on the remote host. diff --git a/openspec/config.yaml b/openspec/config.yaml index 2da5471..75f12ad 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -103,7 +103,7 @@ context: | mounting the host's Docker socket gives code in the container root on the host, the opposite of why agents run in devcontainers. - ## Roadmap (draft changes phase-1 to phase-5) + ## Roadmap (draft changes phase-1 to phase-6) - v0.1 (phase-1): `setup`, `up`, `ps`, `status --wait --json` with log tail, `logs`, `open`, `down`, hostname and path routing, Claude Code skill. - v0.2 (phase-2): web overview at `siding.localhost` (`siding ui`), `gc` (git-aware), `lint`, @@ -111,7 +111,9 @@ context: | - v0.3 (phase-3): snapshots and `--seed`, queue for capacity, parallel build limit, learned peaks. - v0.4 (phase-4): stopping idle stacks under memory pressure, the verdict `Stopped`. - - v0.5 (phase-5): remote Docker host (Docker context), local forwarder for `*.localhost`, + - v0.5 (phase-5): onboarding: releases, `siding skill --install` and the permission + snippet, `EnvFileMissing`, the lint rule `LocalhostURL`, a default snapshot. + - v0.6 (phase-6): remote Docker host (Docker context), local forwarder for `*.localhost`, `HOST` column in `ps`. - Later: idle stop after a time and wake on request (Sablier ignores `depends_on` on wake, see the phase 4 spike), HTTP errors from the proxy in the verdict, a shared server with a database per From ad0b4cb00ec23d735a4b0c8959d05b9d24436cfa Mon Sep 17 00:00:00 2001 From: tweinmann Date: Thu, 29 Oct 2026 19:59:34 +0000 Subject: [PATCH 2/7] Propose phase 5: onboarding (v0.5) Releases with just dist, siding skill --install for any harness with the AGENTS.md and permission snippets, EnvFileMissing for env files of the main worktree, the lint rule LocalhostURL, the snapshot default, and a README that follows the user journey. Co-Authored-By: Claude Opus 5.5 --- .../changes/phase-5-onboarding/.openspec.yaml | 1 - openspec/changes/phase-5-onboarding/design.md | 146 ++++++++++++++++++ .../changes/phase-5-onboarding/proposal.md | 65 +++++--- .../specs/agent-skill/spec.md | 50 ++++++ .../specs/cli-contract/spec.md | 24 +++ .../specs/compose-lint/spec.md | 30 ++++ .../phase-5-onboarding/specs/releases/spec.md | 43 ++++++ .../phase-5-onboarding/specs/seeding/spec.md | 37 +++++ .../specs/snapshots/spec.md | 25 +++ .../specs/stack-lifecycle/spec.md | 25 +++ openspec/changes/phase-5-onboarding/tasks.md | 50 ++++++ 11 files changed, 473 insertions(+), 23 deletions(-) create mode 100644 openspec/changes/phase-5-onboarding/design.md create mode 100644 openspec/changes/phase-5-onboarding/specs/agent-skill/spec.md create mode 100644 openspec/changes/phase-5-onboarding/specs/cli-contract/spec.md create mode 100644 openspec/changes/phase-5-onboarding/specs/compose-lint/spec.md create mode 100644 openspec/changes/phase-5-onboarding/specs/releases/spec.md create mode 100644 openspec/changes/phase-5-onboarding/specs/seeding/spec.md create mode 100644 openspec/changes/phase-5-onboarding/specs/snapshots/spec.md create mode 100644 openspec/changes/phase-5-onboarding/specs/stack-lifecycle/spec.md create mode 100644 openspec/changes/phase-5-onboarding/tasks.md diff --git a/openspec/changes/phase-5-onboarding/.openspec.yaml b/openspec/changes/phase-5-onboarding/.openspec.yaml index c1fa2fe..5c99d6d 100644 --- a/openspec/changes/phase-5-onboarding/.openspec.yaml +++ b/openspec/changes/phase-5-onboarding/.openspec.yaml @@ -1,3 +1,2 @@ schema: spec-driven created: 2026-10-29 -skip_specs: true diff --git a/openspec/changes/phase-5-onboarding/design.md b/openspec/changes/phase-5-onboarding/design.md new file mode 100644 index 0000000..cca1dd8 --- /dev/null +++ b/openspec/changes/phase-5-onboarding/design.md @@ -0,0 +1,146 @@ +# Design + +## Context + +v0.4 (archived as `2026-10-29-phase-4-idle-and-wake`) works once siding is installed and the +project is prepared; the user journey reviewed with the maintainer on 2026-10-29 found the gaps +listed in proposal.md. The pieces this phase builds on: `cmd/siding` takes its version through +`-ldflags "-X main.version=…"`; `just build-darwin` cross-compiles statically; CI runs +everything inside the devcontainer image; `siding skill` embeds `internal/cli/skill/SKILL.md`; +`internal/lint` checks the normalised Compose config; `seedPlan` in `up` seeds a first `up` +only with `--seed`; `git.Worktree` knows the common git directory. Behaviour: see the delta +specs. Constraints from CLAUDE.md: the user's files are never edited, no real secrets in +output, standard building blocks over custom code. + +Checked before this proposal with Compose 5.6.1: without `.env`, `docker compose config` only +warns that a variable is not set and uses a blank string, so a stack starts with empty values; +a missing `env_file` fails `config` with "env file … not found"; `config --no-env-resolution +--format json` lists every `env_file` with its `path` and `required: false` where set, even +when the files are missing. + +## Goals / Non-Goals + +**Goals:** +- A user who does not build siding can install it from a release in a minute. +- A new worktree either starts right (skill, permissions, env files, data) or says in one line + what is missing and how to fix it. +- Nothing here writes a file of the user's but the one the user asks for with `--install`. + +**Non-Goals:** +- Homebrew, notarised or signed binaries, an install script, Windows. +- Copying `.env` or secrets in any form; reading their values beyond what redaction and + `LocalhostURL` already need. +- Creating worktrees, or integrating with a harness's own worktree feature. +- Rewriting `localhost` in the user's configuration. +- Presets for named harnesses. + +## Decisions + +### D1. Releases: `just dist` and `gh` (maintainer's decision) +`just dist ` runs `go build -trimpath -ldflags "-s -w -X main.version="` with +`CGO_ENABLED=0` for `darwin` and `linux` × `arm64` and `amd64` into `dist/` (git-ignored), and +writes `SHA256SUMS` with `sha256sum`, in the format `shasum -a 256 -c` reads on macOS. A +workflow `.github/workflows/release.yml` runs on tags `v*.*.*`: it runs `just test` and +`just dist "$GITHUB_REF_NAME"` in the devcontainer (as `ci.yml` does), then +`gh release create "$GITHUB_REF_NAME" dist/* --verify-tag --generate-notes` on the runner, with +`permissions: contents: write` for this job only. `just build-darwin` stays for development. +Alternatives, asked: goreleaser (archives, changelog, Homebrew later, but one more tool to pin in +the devcontainer, for four binaries). Homebrew and notarisation need an Apple developer account +and a tap repository and wait for users outside the maintainer's circle. + +### D2. `siding skill --install` (maintainer's decisions: opt-in, `--dir`, snippets) +Without `--install`, `skill` prints as before. With it, `skill` writes +`/siding/SKILL.md` (directories created, an older copy replaced), where `` is `--dir` +(`~` expanded) or `.claude/skills` at the worktree's top, found with `git`; outside a worktree +and without `--dir` it fails with `NotAGitRepository`. It prints the path and, for the default +directory, the hint to commit the file, because a new worktree only has committed files; then +the two snippets of D3. With `--json`, the `Skill` document gains `path`, and the snippets go +to stderr, so stdout stays one document. `--dir` without `--install` is `InvalidArguments`. +The skill text names no harness (it already does not; a test keeps it so). Alternatives, asked: +only print (one more copy step for every repository); presets per harness (`--for codex`; +paths siding would have to track as they change); only an `AGENTS.md` snippet. A global install +is `--dir ~/.claude/skills`. + +### D3. The snippets +The `AGENTS.md` section is a short Markdown section of four lines: run `siding up --wait --json` +after changes the running app depends on, act on the verdict, report `stack.url`, and leave +`down`, `gc` and data to the user; for the details it points to the skill. The permissions +are siding's reading commands, the only ones an agent needs: `up`, `status`, `logs`, `ps`, as +the Claude Code entry `{"permissions": {"allow": ["Bash(siding up:*)", "Bash(siding status:*)", +"Bash(siding logs:*)", "Bash(siding ps:*)"]}}` and as the plain list `siding up`, +`siding status`, `siding logs`, `siding ps` for other harnesses. siding writes neither: +what an agent may run without asking is the human's decision, as the guardrails put exposing +anything to the internet in the human's hands. + +### D4. Env files of the main worktree (maintainer's decision: refuse, never copy) +`internal/git` gains `MainTop(w Worktree)`, the directory holding the common git directory when +it is named `.git` (the main worktree), and `Tracked(ctx, top, path)`, from +`git ls-files --error-unmatch`. In a linked worktree (its top differs from `MainTop`), before +`loadProject`, `up` runs `docker compose config --no-env-resolution --format json` and collects +the `env_file` paths without `required: false`, relative to the worktree, plus `.env`. Each that +is missing in the worktree, present in the main worktree and untracked there is a missing env +file; the first fails `up` with `EnvFileMissing`, the message naming all of them, the hint +`cp
/ /` per file, and `touch .env` when the worktree needs none. +A bare repository or a common directory not named `.git` has no main worktree: no check. `lint` +runs the same check and reports each as the warning `MissingEnvFile`; it then checks the rest +on the `--no-env-resolution` config, because the normal one fails without the file. +Alternatives, asked: only warn (`up` starts with blank values, which an agent would not notice +on stderr). Rejected: copying (`--copy-env`): secrets spread between directories, and an agent +could run it without the human knowing. + +### D5. `LocalhostURL` +For every service and every variable of its normalised environment, a value matching +`(localhost|127\.0\.0\.1|\[::1\]):(\d+)` is a warning naming service, variable and the matched +`host:port`. The message and hint are built from those three only, so no other part of a value +(a password in a URL) reaches the text or the `LintReport`. A value without a port is not +reported: it is usually a cookie domain or a bind address, not a call to another service. +The hint: between services the service name (`http://api:3000`), in the browser a path on the +stack's address. + +### D6. The snapshot `default` (maintainer's decision: by name) +`seedPlan` resolves, for a first `up` without `--seed`, the repository's snapshot `default`; +found, the plan seeds from it exactly as `--seed default`, and `up` prints `Seeding +from the snapshot default (the repository's default; --seed none starts empty)`. `--seed none` +plans no snapshot. `snapshot save none` fails with `InvalidArguments`; `snapshot save default` +adds a line that new stacks start from it. The skill does not mention seeding: an agent's +first `up` gets the data without knowing. Alternatives, asked: a `--default` flag with a label +(Docker cannot change a volume's labels, so a snapshot could not become the default later, and +two defaults need a rule). + +### D7. Codes, documents, tests +New error code `EnvFileMissing` (in `internal/fail` and the error-code table test); new lint +rules `MissingEnvFile` and `LocalhostURL`; `Skill` gains `path`. Golden files: `skill.json` +with a path, the `LintReport` with both rules, an `Error` for `EnvFileMissing`. The end-to-end +test adds: a linked worktree without `.env` refused, then started after the `cp` of the hint; +a first `up` seeded from `default` and one with `--seed none`. `just dist` is checked in CI by +the release workflow and by hand in task 7. + +### D8. The README follows the user journey (maintainer's request) +"Using siding" becomes two parts. "Get started" is the journey in the order a user walks it: +install, once per machine, once per repository, per task with a worktree and an agent, keeping +an eye on it, after the merge; each step a few commands and sentences, linking to the details. +"Reference" keeps today's sections by topic. The tasks of this phase that document something +write into their step and their reference section. Alternative: keep the sections by command +and add the new ones (a first-time user has to find the order themselves). + +## Risks / Trade-offs + +- [Unsigned binaries trip Gatekeeper on macOS] → the README's `xattr` line; notarisation later. +- [A worktree that needs no `.env` although the main worktree has one] → the hint offers + `touch .env`; one empty file, once per worktree. +- [The main worktree's `.env` is outdated for the branch] → siding only says what to copy; the + user decides. +- [Worktrees with a custom layout (common directory not `.git`, bare repositories)] → no main + worktree, no check: `up` behaves as in v0.4. +- [`LocalhostURL` false positives, e.g. a service's own health URL to itself] → a warning, not + an error; the hint explains when it is fine. +- [A snapshot `default` seeds a stack someone wanted empty] → `up` says so on stderr; `--seed + none`, or `down --volumes` and `up --seed none`. +- [`--no-env-resolution` changes in Compose] → pinned Compose in the devcontainer; a test against + `docker compose config` in `just smoke-stacks`. + +## Migration Plan + +Nothing to migrate. Stacks, labels and documents of v0.4 stay valid. A user who has a snapshot +named `none` from v0.4 can still use and remove it; only new saves of that name are refused. +The first release is `v0.5.0`, tagged after this phase is approved. diff --git a/openspec/changes/phase-5-onboarding/proposal.md b/openspec/changes/phase-5-onboarding/proposal.md index 102e937..f6f6f38 100644 --- a/openspec/changes/phase-5-onboarding/proposal.md +++ b/openspec/changes/phase-5-onboarding/proposal.md @@ -1,35 +1,56 @@ # Proposal -> Draft. This change holds the roadmap text only and is marked `skip_specs: true`. -> `/opsx:propose` turns it into a full change: it writes the delta specs, `design.md` and -> `tasks.md`, revises this proposal, and removes `skip_specs` from `.openspec.yaml`. - ## Why -The core works once siding is set up, but the first attempt fails before and beside it: siding -can only be built from source, the skill is missing in new worktrees, Claude Code asks for every -`siding up`, a new worktree has no `.env` and an empty database, and apps that call -`localhost:` break behind the proxy without a warning. +Once siding runs, the core works: a stack per worktree, a verdict, an address. The first +attempt fails before and beside it. siding can only be built from source. The skill is missing +in a new worktree unless it was committed, and Claude Code asks before every `siding up`. A new +worktree has no `.env`, so Compose starts the stack with blank values, and its database is +empty. An app that calls `localhost:` breaks behind the proxy without a warning. Each of +these is small; together they decide whether the first attempt works. ## What Changes -Roadmap v0.5 (decisions agreed with the maintainer on 2026-10-29): - -- Releases: unsigned binaries for macOS and Linux (arm64, amd64) on GitHub Releases, built by CI - on every tag; an install note for macOS's quarantine flag. Homebrew and notarisation later. -- `siding skill --install` writes `.claude/skills/siding/SKILL.md` and says to commit it; - without the flag the skill is only printed, as today. siding prints the permission snippet for - `.claude/settings.json` and never writes that file. -- A missing `.env` that the compose file uses: `up` fails with `EnvFileMissing` and the `cp` - command from the main worktree, `lint` warns; siding never copies it. -- `lint` rule `LocalhostURL`: an environment value pointing at `localhost:`. -- A default snapshot: `siding snapshot save --default`; the first `up` of a stack seeds - from it unless `--seed none`; without a default, nothing changes. +- **Releases.** `just dist` builds static binaries for macOS and Linux, arm64 and amd64, with + the version from the tag, and `SHA256SUMS`. A workflow on `v*` tags publishes them as a + GitHub Release. The README gets an install section, including macOS's quarantine flag. + Homebrew and notarisation come later. +- **`siding skill --install [--dir ]`** writes the skill as `/siding/SKILL.md`, + by default into `.claude/skills` at the worktree's top. It says to commit the file, and prints + two snippets: a section for `AGENTS.md`, which many harnesses read, and the permissions for + siding's reading commands, as a Claude Code `settings.json` entry and as a plain list. siding + writes no other file; without `--install`, `siding skill` prints the skill as before. The + skill's text is harness-neutral. +- **Env files of the main worktree.** When a linked worktree lacks `.env`, or an `env_file` of + the compose file, that the main worktree has as an untracked file, `up` fails with the new + code `EnvFileMissing` and the `cp` command; `lint` warns `MissingEnvFile`. siding never + copies them. +- **`lint` rule `LocalhostURL`**: a service's environment value pointing at `localhost` or + `127.0.0.1` with a port, a warning that names the variable but never its value. +- **A default snapshot.** A snapshot named `default` seeds every first `up` of the repository + that gives no `--seed`; `--seed none` starts empty. Without a snapshot `default`, nothing + changes. `none` becomes a reserved name. ## Capabilities -To be decided at `/opsx:propose`. +### New Capabilities +- `releases`: how siding is built for distribution and published on a tag. + +### Modified Capabilities +- `agent-skill`: `--install` with `--dir`, and the snippets for `AGENTS.md` and permissions. +- `stack-lifecycle`: `up` refuses when env files of the main worktree are missing. +- `compose-lint`: the warnings `MissingEnvFile` and `LocalhostURL`. +- `seeding`: the snapshot `default` and `--seed none`. +- `snapshots`: `none` is not a snapshot name. +- `cli-contract`: the error code `EnvFileMissing`. ## Impact -To be decided at `/opsx:propose`. +- Code: `internal/cli` (`skill`, `up`, `lint`, `snapshot save`), `internal/lint` (two rules), + `internal/git` (the main worktree, tracked files), `internal/seed`, `internal/e2e`. +- Build: `justfile` (`dist`), `.github/workflows/release.yml`; `cmd/siding` already takes the + version through `-ldflags`. +- Documents: `Skill` gains `path` when installed; `Error` gains the code `EnvFileMissing`. Only + additions. +- README: install, the skill for any harness, env files, `localhost` behind the proxy, the + snapshot `default`. CLAUDE.md and `openspec/config.yaml`: status and the new error code. diff --git a/openspec/changes/phase-5-onboarding/specs/agent-skill/spec.md b/openspec/changes/phase-5-onboarding/specs/agent-skill/spec.md new file mode 100644 index 0000000..1d3eb36 --- /dev/null +++ b/openspec/changes/phase-5-onboarding/specs/agent-skill/spec.md @@ -0,0 +1,50 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: siding skill prints the skill +`siding skill` SHALL print the skill (`SKILL.md` with name, description and body) on stdout and +write no file. With `--json` it SHALL print a `Skill` document holding the same text. With +`--install` it SHALL instead write the skill as `/siding/SKILL.md`, where `` is +`--dir` or else `.claude/skills` at the worktree's top, replacing an older copy, and write no +other file. + +#### Scenario: Install the skill +- **WHEN** a user runs `mkdir -p .claude/skills/siding && siding skill > .claude/skills/siding/SKILL.md` +- **THEN** the file is a valid skill named `siding`, and siding wrote nothing itself + +#### Scenario: Install with --install +- **WHEN** `siding skill --install` runs in a worktree of `shop` +- **THEN** `.claude/skills/siding/SKILL.md` at the worktree's top holds the skill, and the output says to commit it so every worktree has it + +#### Scenario: Another harness +- **WHEN** `siding skill --install --dir ~/.agents/skills` runs +- **THEN** `~/.agents/skills/siding/SKILL.md` holds the skill, and nothing under `.claude` is written + +#### Scenario: JSON +- **WHEN** `siding skill --install --json` runs +- **THEN** it prints a `Skill` document with the text and the `path` it wrote + +## ADDED Requirements + +### Requirement: Snippets for the harness +`siding skill --install` SHALL print, after what it wrote, a section for `AGENTS.md` that tells +any agent to use siding as the skill does, and the permissions for siding's reading commands +(`up`, `status`, `logs`, `ps`): as a Claude Code `settings.json` entry and as a plain list for +other harnesses. siding MUST NOT write `AGENTS.md` or any settings file. + +#### Scenario: The snippets +- **WHEN** `siding skill --install` has run +- **THEN** its output holds the `AGENTS.md` section and `"Bash(siding up:*)"`, `"Bash(siding status:*)"`, `"Bash(siding logs:*)"` and `"Bash(siding ps:*)"`, and none of `down`, `gc`, `snapshot rm` or `teardown` + +#### Scenario: No settings written +- **WHEN** `siding skill --install` runs in a repository with `.claude/settings.json` +- **THEN** that file is byte for byte unchanged + +### Requirement: Harness-neutral skill +The skill's text SHALL name no harness: it addresses the agent, so that the same file works +wherever the Agent Skills format is read. + +#### Scenario: No harness named +- **WHEN** the printed skill is read +- **THEN** it does not contain "Claude Code" diff --git a/openspec/changes/phase-5-onboarding/specs/cli-contract/spec.md b/openspec/changes/phase-5-onboarding/specs/cli-contract/spec.md new file mode 100644 index 0000000..1facd37 --- /dev/null +++ b/openspec/changes/phase-5-onboarding/specs/cli-contract/spec.md @@ -0,0 +1,24 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Error document +A command that fails SHALL exit 1, or 3 for `NoCapacity`. With `--json` it SHALL print a +document of kind `Error` with a stable `code` and a human-readable `message`; without `--json` +it SHALL print `error: ` on stderr, followed by a hint line when there is one. + +#### Scenario: An unknown flag with --json +- **WHEN** `siding version --json --nope` runs +- **THEN** it exits 1 and prints an `Error` document with `code` `InvalidArguments`, even though flag parsing failed before `--json` was read + +#### Scenario: A failure without --json +- **WHEN** `siding up` runs outside a git repository +- **THEN** it exits 1 and prints `error: …` and a hint on stderr, and nothing on stdout + +#### Scenario: The error codes +- **WHEN** a command fails +- **THEN** its code is one of `InvalidArguments`, `NotAGitRepository`, `NoBranch`, `ComposeFileNotFound`, `ComposeFailed`, `DockerUnavailable`, `ProxyNotRunning`, `PortInUse`, `InvalidRoute`, `AmbiguousPort`, `SlugCollision`, `StackNotFound`, `UnmergedBranch`, `DirtyWorktree`, `NoCapacity`, `NotInteractive`, `SnapshotNotFound`, `SnapshotExists`, `EnvFileMissing`, or `Internal` for an unexpected error + +#### Scenario: No capacity +- **WHEN** `siding up --json` refuses because the stack does not fit into the memory budget +- **THEN** it prints an `Error` document with `code` `NoCapacity` and exits 3 diff --git a/openspec/changes/phase-5-onboarding/specs/compose-lint/spec.md b/openspec/changes/phase-5-onboarding/specs/compose-lint/spec.md new file mode 100644 index 0000000..5ff7c21 --- /dev/null +++ b/openspec/changes/phase-5-onboarding/specs/compose-lint/spec.md @@ -0,0 +1,30 @@ +# Spec Delta + +## ADDED Requirements + +### Requirement: Missing env files +In a linked worktree, `lint` SHALL warn `MissingEnvFile` for every file that `up` would refuse +to start without (see `stack-lifecycle`, "Env files of the main worktree"), with the `cp` +command as the hint. + +#### Scenario: .env missing +- **WHEN** `siding lint` runs in a new worktree that lacks the main worktree's untracked `.env` +- **THEN** it warns `MissingEnvFile` for `.env` with the `cp` command, and exits 0 + +### Requirement: localhost in the environment +`lint` SHALL warn `LocalhostURL` for every environment variable of a service whose value names +`localhost` or `127.0.0.1` with a port, because behind the proxy that reaches the service's own +container, not the other service or the host. The finding MUST name the service, the variable +and the host and port, and MUST NOT contain the rest of the value. + +#### Scenario: An API URL +- **WHEN** `web` has `API_URL=http://localhost:3000/v1` +- **THEN** lint warns `LocalhostURL` for `web` naming `API_URL` and `localhost:3000`, with the hint to use the service name (`http://api:3000`) between services or a path on the stack's address in the browser + +#### Scenario: A password in the value +- **WHEN** `api` has `DATABASE_URL=postgres://app:not-a-real-token@127.0.0.1:5432/app` +- **THEN** the finding names `DATABASE_URL` and `127.0.0.1:5432`, and neither the text nor the `LintReport` contains `not-a-real-token` + +#### Scenario: Without a port +- **WHEN** `web` has `COOKIE_DOMAIN=localhost` +- **THEN** lint reports nothing for it diff --git a/openspec/changes/phase-5-onboarding/specs/releases/spec.md b/openspec/changes/phase-5-onboarding/specs/releases/spec.md new file mode 100644 index 0000000..2b5d51c --- /dev/null +++ b/openspec/changes/phase-5-onboarding/specs/releases/spec.md @@ -0,0 +1,43 @@ +# Spec Delta + +## Purpose + +Defines how siding reaches users who do not build it: static binaries per platform, published +for every version tag, with checksums and instructions to install them. + +## ADDED Requirements + +### Requirement: Distribution build +`just dist` SHALL build, in the devcontainer, static siding binaries for `darwin` and `linux` +on `arm64` and `amd64` into `dist/`, named `siding--`, with the version given to it, +and a `SHA256SUMS` file over them. + +#### Scenario: A build for a tag +- **WHEN** `just dist v0.5.0` runs in the devcontainer +- **THEN** `dist/` holds four binaries and `SHA256SUMS`, and `dist/siding-linux-arm64 version` reports `v0.5.0` + +#### Scenario: Checksums +- **WHEN** a user runs `shasum -a 256 -c SHA256SUMS` next to the downloaded binaries +- **THEN** every binary checks out + +### Requirement: Release on a tag +A pushed tag `v..` SHALL make CI run `just test`, build with `just dist` +inside the devcontainer, and publish a GitHub Release named after the tag with the four +binaries and `SHA256SUMS`. A failing check MUST publish nothing. + +#### Scenario: Tag v0.5.0 +- **WHEN** the maintainer pushes the tag `v0.5.0` +- **THEN** the release `v0.5.0` exists on GitHub with `siding-darwin-arm64`, `siding-darwin-amd64`, `siding-linux-arm64`, `siding-linux-amd64` and `SHA256SUMS` + +#### Scenario: A failing check +- **WHEN** `just test` fails for the tagged commit +- **THEN** no release is published + +### Requirement: Install instructions +The README SHALL say how to install a released binary on macOS and Linux: download it for the +platform, check it against `SHA256SUMS`, make it executable, put it on the `PATH`, and on macOS +remove the quarantine flag of a downloaded, unsigned binary. + +#### Scenario: Install on a Mac +- **WHEN** a user follows the README on an Apple silicon Mac +- **THEN** `siding version` runs and reports `darwin/arm64` and the release's version diff --git a/openspec/changes/phase-5-onboarding/specs/seeding/spec.md b/openspec/changes/phase-5-onboarding/specs/seeding/spec.md new file mode 100644 index 0000000..ab361df --- /dev/null +++ b/openspec/changes/phase-5-onboarding/specs/seeding/spec.md @@ -0,0 +1,37 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Seed per service +The service label `dev.siding.seed` SHALL choose how a service's volumes are seeded: `volume` +(from the snapshot given with `--seed`, or the snapshot `default` without it; also when the +label is missing), `none` (never), or `script`. A volume used by a service with `none` MUST NOT +be seeded. Another value MUST fail `up` with `InvalidArguments`, naming the service. + +#### Scenario: none +- **WHEN** `cache` carries `dev.siding.seed: none` and `up --seed base` runs first +- **THEN** the volume of `cache` starts empty, and the others come from `base` + +## ADDED Requirements + +### Requirement: The default snapshot +A first `up` without `--seed` SHALL seed from the repository's snapshot named `default` when it +exists, as `--seed default` would, and say on stderr that it does. `--seed none` SHALL start the +stack empty. Without a snapshot `default`, a first `up` without `--seed` MUST start empty, as +before. + +#### Scenario: A new worktree starts with data +- **WHEN** `shop` has the snapshot `default` and an agent runs `siding up --wait --json` in a new worktree +- **THEN** the stack's volumes are copies of `default`, stderr says it seeded from `default`, and the verdict is Ready + +#### Scenario: Empty on purpose +- **WHEN** `shop` has the snapshot `default` and `siding up --seed none` runs first +- **THEN** the stack's volumes start empty + +#### Scenario: No default +- **WHEN** `shop` has the snapshot `base` but none named `default` +- **THEN** a first `up` without `--seed` starts empty + +#### Scenario: Not a first up +- **WHEN** the stack already has volumes and the snapshot `default` exists +- **THEN** `up` seeds nothing and gives no warning about it diff --git a/openspec/changes/phase-5-onboarding/specs/snapshots/spec.md b/openspec/changes/phase-5-onboarding/specs/snapshots/spec.md new file mode 100644 index 0000000..7a3dedb --- /dev/null +++ b/openspec/changes/phase-5-onboarding/specs/snapshots/spec.md @@ -0,0 +1,25 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Snapshot names +A snapshot name SHALL be unique per repository and consist of lowercase letters, digits and +`-`. `save` MUST fail with `SnapshotExists` when the name is taken, unless `--force` replaces it. +The name `none` MUST be refused with `InvalidArguments`, because `--seed none` means no +snapshot; the name `default` makes the snapshot the one a first `up` seeds from. + +#### Scenario: Taken +- **WHEN** `siding snapshot save base` runs and `base` exists for the repository +- **THEN** it fails with `SnapshotExists`, and with `--force` the old snapshot is replaced + +#### Scenario: Another repository +- **WHEN** the repositories `shop` and `blog` both save a snapshot `base` +- **THEN** both exist side by side + +#### Scenario: Reserved +- **WHEN** `siding snapshot save none` runs +- **THEN** it fails with `InvalidArguments` and saves nothing + +#### Scenario: Default +- **WHEN** `siding snapshot save default` runs +- **THEN** the snapshot `default` exists, and the output says that new stacks of the repository start from it diff --git a/openspec/changes/phase-5-onboarding/specs/stack-lifecycle/spec.md b/openspec/changes/phase-5-onboarding/specs/stack-lifecycle/spec.md new file mode 100644 index 0000000..8beb289 --- /dev/null +++ b/openspec/changes/phase-5-onboarding/specs/stack-lifecycle/spec.md @@ -0,0 +1,25 @@ +# Spec Delta + +## ADDED Requirements + +### Requirement: Env files of the main worktree +In a linked worktree, `up` SHALL fail with `EnvFileMissing` before Compose runs when the +worktree lacks `.env`, or a file the compose file names in `env_file`, that the main worktree +has and git does not track. The hint MUST give the `cp` command from the main worktree. siding +MUST NOT copy the file itself. + +#### Scenario: A new worktree without .env +- **WHEN** the main worktree `/src/shop` has an untracked `.env`, and `siding up` runs in the new worktree `/src/shop-feature-x`, which has none +- **THEN** it fails with `EnvFileMissing`, the hint says `cp /src/shop/.env /src/shop-feature-x/.env`, and no container starts + +#### Scenario: An env_file +- **WHEN** `api` has `env_file: [api.env]`, the main worktree has an untracked `api.env`, and the worktree lacks it +- **THEN** `siding up` fails with `EnvFileMissing` naming `api.env` + +#### Scenario: Not needed +- **WHEN** the main worktree has no `.env`, or `.env` is tracked by git +- **THEN** `up` behaves as before + +#### Scenario: The main worktree +- **WHEN** `siding up` runs in the main worktree without `.env` +- **THEN** `up` behaves as before diff --git a/openspec/changes/phase-5-onboarding/tasks.md b/openspec/changes/phase-5-onboarding/tasks.md new file mode 100644 index 0000000..88a37ee --- /dev/null +++ b/openspec/changes/phase-5-onboarding/tasks.md @@ -0,0 +1,50 @@ +# Tasks + +## 1. Foundations + +- [ ] 1.1 Add the error code `EnvFileMissing` and the lint rule names `MissingEnvFile` and `LocalhostURL`; verify with the error-code table test +- [ ] 1.2 Add `MainTop` and `Tracked` to `internal/git` (D4); verify with tests on a real repository with a linked worktree, a bare-like custom layout, and a tracked and an untracked file +- [ ] 1.3 Add reading the `env_file` paths from `docker compose config --no-env-resolution --format json` to `internal/compose`, with `required: false` kept; verify with a captured config and, in `just smoke-stacks`, against `docker compose config` with a missing file +- [ ] 1.4 Restructure the README's "Using siding" as the user journey (D8): "Get started" in the order a user walks it (install, once per machine, once per repository, per task with a worktree and an agent, keeping an eye on it, after the merge), a few commands and sentences per step with links, and "Reference" with today's sections (routing labels, verdict and exit codes, lint rules, snapshots and seeding, memory budget and idle stacks, builds, devcontainer, removing siding); verify that no content of today's README is lost and every link resolves + +## 2. Releases + +- [ ] 2.1 Add `just dist ` (D1): four static binaries in `dist/` with the version and `SHA256SUMS`; verify in the devcontainer that `dist/siding-linux-arm64 version` reports the version and `sha256sum -c SHA256SUMS` passes +- [ ] 2.2 Add `.github/workflows/release.yml` on `v*.*.*` tags: `just test` and `just dist` in the devcontainer, then `gh release create --verify-tag --generate-notes` with `contents: write` for that job only; verify with `actionlint` if available, else by review, and by the first tag after approval +- [ ] 2.3 Write step 1 of the README's journey, the install (download, `shasum -a 256 -c`, `chmod`, `PATH`, `xattr -d com.apple.quarantine` on macOS) and keep "build from source" for development; verify the commands against a `just dist` build in the devcontainer and on the Mac in task 7.2 + +## 3. The skill for any harness + +- [ ] 3.1 Implement `siding skill --install [--dir]` (D2): the default directory at the worktree's top, `~` expanded, an older copy replaced, `NotAGitRepository` outside a worktree without `--dir`, `--dir` without `--install` refused, `path` in `Skill`; verify with fake-based tests per scenario of `agent-skill` and the updated `skill.json` golden +- [ ] 3.2 Print the `AGENTS.md` section and the permissions (D3), on stderr with `--json`; verify with a test that names the four reading commands and none of `down`, `gc`, `snapshot rm`, `teardown`, and that an existing `.claude/settings.json` is unchanged +- [ ] 3.3 Keep the skill harness-neutral; verify with the skill test that it does not contain "Claude Code" +- [ ] 3.4 Write the agent part of the journey's steps 3 and 4 and its reference: `--install`, committing the file, `--dir` for other harnesses and a global install, the snippets; verify the commands run as written in the devcontainer + +## 4. Env files + +- [ ] 4.1 Check the env files of the main worktree in `up` before Compose runs (D4) and fail with `EnvFileMissing`, all missing files in the message and the `cp` commands and `touch .env` in the hint; verify with fake-based tests per scenario of `stack-lifecycle` "Env files of the main worktree" and an `error-envfilemissing.json` golden +- [ ] 4.2 Report `MissingEnvFile` in `lint` and lint the rest on the `--no-env-resolution` config; verify with a fake-based test of a linked worktree without `.env` and one without an `env_file` +- [ ] 4.3 Document env files in the journey's step 4 and the reference (what siding checks, why it never copies, `touch .env`); verify the example matches the tests + +## 5. localhost in the environment + +- [ ] 5.1 Implement `LocalhostURL` in `internal/lint` (D5); verify with table tests for the spec's scenarios (an API URL, a password in the value that never reaches the finding, no port, `[::1]`) and the updated `lintreport.json` golden +- [ ] 5.2 Add `LocalhostURL` and `MissingEnvFile` to the reference's lint table and explain `localhost` behind the proxy in the journey's step 3; verify the table matches the rule names in the code + +## 6. The snapshot default + +- [ ] 6.1 Seed a first `up` without `--seed` from the snapshot `default` and plan none for `--seed none` (D6), with the stderr line; verify with fake-based tests per scenario of `seeding` "The default snapshot" and "Seed per service" +- [ ] 6.2 Refuse `snapshot save none` and say what `default` means on `snapshot save default`; verify with fake-based tests +- [ ] 6.3 Document the snapshot `default` in the journey's step 3 and the reference's snapshots and seeding; verify the shown commands run as written in the devcontainer + +## 7. End-to-end and integration + +- [ ] 7.1 Extend `internal/e2e`: a linked worktree without `.env` refused with `EnvFileMissing`, then Ready after the hint's `cp`; a snapshot `default` seeding a new worktree's first `up`, and `--seed none` starting empty; `siding skill --install` writing into a temporary repository; verify with `just smoke-stacks` and that no `siding-test-*` object is left +- [ ] 7.2 Walk the user journey on the Mac with a binary from `just dist`, following only the README's "Get started" (install, `setup`, `lint`, `skill --install`, a new worktree without `.env`, the snapshot `default`), and note every place where the README left a gap; record the result in this task +- [ ] 7.3 Update the status in CLAUDE.md, the README and `openspec/config.yaml` to v0.5, with `EnvFileMissing` in the conventions where error codes are listed; verify `just test` passes + +## Workflow follow-up + +- Stop and show the result; wait for the maintainer's approval of Phase 5. +- `/opsx:archive` merges the deltas into `openspec/specs/`. +- After approval, tag `v0.5.0` and check the published release. From 7d9ef1b6ef602cb16dedd044c6e5bfb088b5093a Mon Sep 17 00:00:00 2001 From: tweinmann Date: Thu, 29 Oct 2026 20:10:00 +0000 Subject: [PATCH 3/7] Phase 5 work in progress: releases, skill --install, env files, LocalhostURL Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 32 ++++ README.md | 153 +++++++++++++++-- internal/cli/cli.go | 5 +- internal/cli/cli_test.go | 2 +- internal/cli/env_test.go | 23 ++- internal/cli/envfiles.go | 99 +++++++++++ internal/cli/envfiles_test.go | 154 ++++++++++++++++++ internal/cli/json.go | 2 + internal/cli/lint.go | 35 +++- internal/cli/lint_test.go | 2 +- internal/cli/skill.go | 124 ++++++++++++-- internal/cli/skill_test.go | 86 ++++++++++ internal/cli/stack.go | 9 +- .../testdata/json/error-envfilemissing.json | 7 + internal/cli/testdata/json/lintreport.json | 7 + internal/cli/up.go | 5 + internal/compose/compose.go | 13 ++ internal/compose/config.go | 37 +++++ internal/compose/config_test.go | 23 +++ internal/compose/testdata/lint/config.json | 1 + internal/e2e/phase5_test.go | 39 +++++ internal/fail/fail.go | 2 + internal/git/git.go | 41 +++++ internal/git/git_test.go | 63 +++++++ internal/lint/lint.go | 17 ++ internal/lint/lint_test.go | 39 +++++ justfile | 10 ++ openspec/changes/phase-5-onboarding/tasks.md | 32 ++-- 28 files changed, 1010 insertions(+), 52 deletions(-) create mode 100644 .github/workflows/release.yml create mode 100644 internal/cli/envfiles.go create mode 100644 internal/cli/envfiles_test.go create mode 100644 internal/cli/testdata/json/error-envfilemissing.json create mode 100644 internal/e2e/phase5_test.go diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..e2599ef --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,32 @@ +# Publishes a release for a version tag: the level-1 checks and the release binaries run inside +# the devcontainer image, as in ci.yml, so a release is built with the pinned tool versions. +# Only this workflow may write to the repository's contents, and only to create the release. +name: release + +on: + push: + tags: ["v[0-9]+.[0-9]+.[0-9]+"] + +permissions: + contents: read + +jobs: + release: + runs-on: ubuntu-24.04-arm + timeout-minutes: 30 + permissions: + contents: write + steps: + - uses: actions/checkout@v7 + - name: just test and just dist (in the devcontainer) + uses: devcontainers/ci@v0.3 + with: + push: never + runCmd: | + just test + just dist "${{ github.ref_name }}" + # gh comes with the runner. A failed check above stops the job, so nothing is published. + - name: Publish the release + env: + GH_TOKEN: ${{ github.token }} + run: gh release create "${{ github.ref_name }}" dist/* --verify-tag --generate-notes --title "${{ github.ref_name }}" diff --git a/README.md b/README.md index f9e897d..4c0b397 100644 --- a/README.md +++ b/README.md @@ -6,20 +6,109 @@ and tells you and your coding agents whether it actually runs and what it costs. > **Pre-alpha (v0.4).** Stacks per worktree, routing through one local proxy, the verdict of > `siding status`, the overview `siding ui`, a memory budget with a queue, learned peaks and > idle stacks that make room, snapshots and seeding, a build limit, `gc` and `lint` work; expect -> rough edges and changes before v1. There are no releases -> yet: build it from source (see below). The plan is in [openspec/changes/](openspec/changes) +> rough edges and changes before v1. The plan is in [openspec/changes/](openspec/changes) > (one change per phase), what siding does today in [openspec/specs/](openspec/specs). -## Using siding +## Get started -siding needs Docker with Compose 2.24 or later, and git. Your compose file stays as it is. +siding needs Docker with Compose 2.24 or later, and git. Your compose file stays as it is. The +steps below follow the order you walk them in; each links to the details in the +[reference](#reference). -### Once per machine: the proxy +### 1. Install siding + +Download the binary for your platform and `SHA256SUMS` from the +[latest release](https://github.com/tweinmann/siding/releases/latest), then: + +```sh +shasum -a 256 -c SHA256SUMS --ignore-missing # sha256sum on Linux +chmod +x siding-darwin-arm64 # siding-- of your platform +sudo mv siding-darwin-arm64 /usr/local/bin/siding +xattr -d com.apple.quarantine /usr/local/bin/siding # macOS: the binary is not signed yet +siding version +``` + +The binaries are static and need nothing but Docker and git. To build siding yourself, see +[Developing siding](#developing-siding). + +### 2. Once per machine: the proxy + +```sh +siding setup # Traefik as siding-proxy on 127.0.0.1:80 +``` + +Every stack is then reached at `http://..localhost`. Port taken, budget, build +slots: see [The proxy](#the-proxy) and [Memory budget and idle stacks](#memory-budget-and-idle-stacks). + +### 3. Once per repository: prepare it + +```sh +cd shop +siding lint # what breaks parallel stacks, before the first up +siding up --wait # the stack of this worktree, and its verdict +``` + +Fix what [`lint`](#lint-rules) reports as errors in your compose file; siding never edits it. +Label the service that is the app's root `dev.siding.route: "/"`, and give services +healthchecks, so that Ready means ready ([Routing](#routing)). + +Teach your coding agent to use siding ([For coding agents](#for-coding-agents)): + +```sh +siding skill --install # .claude/skills/siding/SKILL.md; --dir for another harness +git add .claude/skills/siding && git commit -m "Add the siding skill" +``` + +Commit it: a new worktree only has committed files. `--install` also prints a section for +`AGENTS.md` and the permissions that let the agent run `siding up`, `status`, `logs` and `ps` +without asking; add them where your harness reads them. + +To start new worktrees with data instead of empty, save a snapshot of a stack with test data +([Snapshots and seeding](#snapshots-and-seeding)). + +### 4. Per task: a worktree and an agent + +```sh +git worktree add ../shop-feature-x -b feature/x +cp .env ../shop-feature-x/ # git does not copy untracked files such as .env +cd ../shop-feature-x +``` + +If you forget, `siding up` refuses with `EnvFileMissing` and the `cp` command to run, instead +of starting the stack with blank values ([Env files](#env-files)). + +Start your agent there. After a change, it runs `siding up --wait --json`, fixes what the +[verdict](#verdict-and-exit-codes) names, and reports the stack's address, e.g. +`http://shop.feature-x.localhost`, for you to try. Each worktree's stack has its own +containers, volumes, address and cookies. + +### 5. Keep an eye on it + +```sh +siding ps # every stack on this machine: state, address, memory +siding ui # the same as a page at http://siding.localhost +siding open # this worktree's stack in the browser +``` + +When a new stack does not fit into the memory budget, stacks nobody requested for a while make +room ([Memory budget and idle stacks](#memory-budget-and-idle-stacks)). + +### 6. After the merge + +```sh +siding gc # remove the stacks of merged branches; --dry-run first +git worktree remove ../shop-feature-x +``` + +See [gc](#gc) for what counts as merged and what stays. + +## Reference + +### The proxy ```sh siding setup # Traefik as siding-proxy on 127.0.0.1:80 siding setup --port 8080 # if port 80 is taken, or inside siding's devcontainer -siding teardown # remove the proxy again; stacks keep running, --dry-run lists it ``` Every stack is reached through this one proxy at `http://..localhost`. Browsers @@ -28,7 +117,7 @@ macOS does not: there, use `curl -H "Host: shop.feature-login.localhost" http:// add the host to `/etc/hosts`, as for other tools. Running `siding setup` again changes nothing unless the port differs. -### In a worktree: start the stack +### Starting a stack ```sh siding up # e.g. shop on feature/login: http://shop.feature-login.localhost/ @@ -40,6 +129,18 @@ siding up --wait # and wait for the verdict, like siding status --wa `.siding/override.yml`. That file resets every published port, so branches never fight over ports, and puts siding's labels and routes on the services. `.siding/` ignores itself in git. +### Env files + +`git worktree add` copies only what git tracks, so a new worktree has no `.env` and none of the +untracked files the compose file names in `env_file`. Compose would start the stack anyway, +with blank values. So in a linked worktree, `siding up` refuses with `EnvFileMissing` when it +lacks `.env` or a required `env_file` that the main worktree has and git does not track; the +hint gives the `cp` command, and `siding lint` warns `MissingEnvFile` for the same files. +siding never copies them itself: they hold secrets, and which values a branch needs is your +call. If a worktree needs none, an empty file will do (`touch .env`). + +### Routing + - A service labelled `dev.siding.route: "/"` is the stack's root, `dev.siding.route: "/api"` answers under that path (the path is passed on unchanged), `dev.siding.route: "false"` hides a service. @@ -49,7 +150,7 @@ ports, and puts siding's labels and routes on the services. `.siding/` ignores i - Published ports are gone, also a database's. Reach it with `docker compose -p - exec db psql …`. -### Does it run? +### Verdict and exit codes ```sh siding status # Ready, Starting, Failed, TimedOut or Stopped, per service @@ -63,7 +164,7 @@ lines. `Stopped` means no container runs and none failed; `siding up` starts it codes: 0 Ready, 1 Failed, 2 TimedOut, Stopped or still starting. Every command prints one JSON document with `--json`, for scripts and agents. -### Before the first up: lint +### Lint rules ```sh siding lint # exits 1 when it finds an error; --json for a LintReport @@ -83,7 +184,7 @@ siding lint # exits 1 when it finds an error; --json for a Lint | `PublishedPort` | info | published ports, which siding resets | | `NoRoot` | info | HTTP services, but none at `/` | -### Snapshots +### Snapshots and seeding ```sh siding snapshot save base # copy this stack's named volumes into the snapshot "base" @@ -96,8 +197,6 @@ per repository. While it copies, `save` stops the services that use those volume database is copied in a consistent state, and starts them again. Snapshots outlive stacks: `down --volumes` and `gc` never remove them; `siding teardown --snapshots` does. -### Seeding a new stack - ```sh siding up --seed base # on the stack's first up: its volumes start as copies of "base" ``` @@ -124,7 +223,7 @@ services: The seed command runs with `docker compose exec` as soon as the service is ready. If it fails, the verdict is `Failed` with the reason `SeedFailed` and the command's output. -### Memory budget +### Memory budget and idle stacks ```sh siding setup --budget 12g # memory for all stacks together; "default" is 75 % of Docker's @@ -196,7 +295,7 @@ siding down --volumes # also the data; refused while the branch is unmerg # worktree dirty, unless --force; --dry-run lists it first ``` -### After a merge: gc +### gc ```sh siding gc --dry-run # what can go, and what stays and why @@ -227,13 +326,33 @@ run in devcontainers, and bind mounts break unless the paths match inside and ou ### For coding agents -`siding skill` prints a Claude Code skill that tells an agent to run `siding up --wait --json` -after a change and to act on the verdict. siding writes no file itself; install it with +`siding skill` prints a skill, in the Agent Skills format, that tells an agent to run +`siding up --wait --json` after a change, to act on the verdict, and to report the stack's +address. It names no harness, so the same file works wherever skills are read. ```sh -mkdir -p .claude/skills/siding && siding skill > .claude/skills/siding/SKILL.md +siding skill --install # .claude/skills/siding/SKILL.md at the worktree's top +siding skill --install --dir ~/.claude/skills # for every repository, nothing to commit +siding skill --install --dir # the skills directory of another harness +siding skill > SKILL.md # print it, write nothing ``` +`--install` replaces an older copy, so run it again after upgrading siding. It then prints two +snippets and writes neither: a short section for `AGENTS.md`, which many harnesses read, and +the permissions for siding's reading commands, as an entry for Claude Code's +`.claude/settings.json` and as a plain list for other harnesses. Only those four commands: +stopping and removing stacks and their data stays your decision. + +### Removing siding + +```sh +siding teardown # remove the proxy; stacks keep running, --dry-run lists it +siding teardown --snapshots # and every snapshot of this machine +``` + +Without siding, your stacks are plain Compose projects that keep running; `docker compose -p +- down` removes one. `~/.siding` is a cache you can delete. + ## Developing siding Everything runs inside the devcontainer, which has its own Docker daemon; nothing is installed diff --git a/internal/cli/cli.go b/internal/cli/cli.go index 17dbee6..a7f8dff 100644 --- a/internal/cli/cli.go +++ b/internal/cli/cli.go @@ -67,6 +67,8 @@ type Options struct { // Git answers questions about worktrees. type Git interface { Worktree(ctx context.Context, dir string) (git.Worktree, error) + Top(ctx context.Context, dir string) (string, error) + Tracked(ctx context.Context, top, path string) (bool, error) Dirty(ctx context.Context, top string) (bool, error) MergeState(ctx context.Context, r git.Repo, branch string) (git.MergeState, error) } @@ -74,6 +76,7 @@ type Git interface { // Compose runs docker compose. type Compose interface { Config(ctx context.Context, inv compose.Invocation) ([]byte, error) + UnresolvedConfig(ctx context.Context, inv compose.Invocation) ([]byte, error) Run(ctx context.Context, inv compose.Invocation, args []string, stdout, stderr io.Writer) error } @@ -144,7 +147,7 @@ func New(opts Options) *cobra.Command { newUICommand(a), newTeardownCommand(a), newSnapshotCommand(a), - newSkillCommand(), + newSkillCommand(a), ) return root } diff --git a/internal/cli/cli_test.go b/internal/cli/cli_test.go index 9924782..ebcd3bb 100644 --- a/internal/cli/cli_test.go +++ b/internal/cli/cli_test.go @@ -114,7 +114,7 @@ func TestErrorCodes(t *testing.T) { fail.ComposeFailed, fail.DockerUnavailable, fail.ProxyNotRunning, fail.PortInUse, fail.InvalidRoute, fail.AmbiguousPort, fail.SlugCollision, fail.StackNotFound, fail.UnmergedBranch, fail.DirtyWorktree, fail.NoCapacity, fail.NotInteractive, - fail.SnapshotNotFound, fail.SnapshotExists, fail.Internal, + fail.SnapshotNotFound, fail.SnapshotExists, fail.EnvFileMissing, fail.Internal, } for _, code := range codes { t.Run(code, func(t *testing.T) { diff --git a/internal/cli/env_test.go b/internal/cli/env_test.go index c0b6bb1..8722a1a 100644 --- a/internal/cli/env_test.go +++ b/internal/cli/env_test.go @@ -438,10 +438,13 @@ type composeRun struct { } type fakeCompose struct { - mu sync.Mutex - config string - runs []composeRun - runErr error + mu sync.Mutex + config string + unresolved string + // configErr fails Config only, as Compose does when an env_file is missing. + configErr error + runs []composeRun + runErr error // execErr fails runs of docker compose exec, after writing execOutput. execErr error execOutput string @@ -451,6 +454,18 @@ type fakeCompose struct { } func (c *fakeCompose) Config(context.Context, compose.Invocation) ([]byte, error) { + if c.configErr != nil { + return nil, c.configErr + } + return []byte(c.config), nil +} + +// UnresolvedConfig is the config without env files read: the same, unless a test sets +// unresolved, e.g. with env_file entries. +func (c *fakeCompose) UnresolvedConfig(context.Context, compose.Invocation) ([]byte, error) { + if c.unresolved != "" { + return []byte(c.unresolved), nil + } return []byte(c.config), nil } diff --git a/internal/cli/envfiles.go b/internal/cli/envfiles.go new file mode 100644 index 0000000..7dd870b --- /dev/null +++ b/internal/cli/envfiles.go @@ -0,0 +1,99 @@ +package cli + +import ( + "context" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "strings" + + "github.com/tweinmann/siding/internal/compose" + "github.com/tweinmann/siding/internal/fail" + "github.com/tweinmann/siding/internal/git" +) + +// missingEnvFiles returns the env files, relative to the worktree's top, that a linked worktree +// lacks and the main worktree has untracked: .env, which Compose reads for interpolation, and +// every required env_file of the compose file (spec stack-lifecycle, design D4). Compose itself +// only warns without .env and starts the stack with blank values. +func (a *app) missingEnvFiles(ctx context.Context, wt git.Worktree, file, project string) ([]string, error) { + if !wt.Linked() { + return nil, nil + } + candidates := []string{".env"} + data, err := a.opts.Compose.UnresolvedConfig(ctx, compose.Invocation{Dir: wt.Top, Project: project, Files: []string{file}}) + if err != nil { + return nil, err + } + envFiles, err := compose.EnvFiles(data) + if err != nil { + return nil, fail.New(fail.ComposeFailed, "%v", err) + } + for _, f := range envFiles { + rel, err := filepath.Rel(wt.Top, f.Path) + if f.Required && err == nil && !strings.HasPrefix(rel, "..") && rel != ".env" { + candidates = append(candidates, rel) + } + } + main := wt.MainTop() + var missing []string + for _, rel := range candidates { + if exists, err := fileExists(filepath.Join(wt.Top, rel)); err != nil || exists { + if err != nil { + return nil, err + } + continue + } + if exists, err := fileExists(filepath.Join(main, rel)); err != nil || !exists { + if err != nil { + return nil, err + } + continue + } + tracked, err := a.opts.Git.Tracked(ctx, main, rel) + if err != nil { + return nil, err + } + if !tracked { + missing = append(missing, rel) + } + } + return missing, nil +} + +func fileExists(path string) (bool, error) { + _, err := os.Stat(path) + switch { + case err == nil: + return true, nil + case errors.Is(err, fs.ErrNotExist): + return false, nil + } + return false, err +} + +// envFileHint is the cp command per missing file, and what to do when the worktree needs none. +func envFileHint(wt git.Worktree, missing []string) string { + var cps []string + for _, rel := range missing { + cps = append(cps, fmt.Sprintf("cp %s %s", filepath.Join(wt.MainTop(), rel), filepath.Join(wt.Top, rel))) + } + it, empty := "it", "an empty one" + if len(missing) > 1 { + it, empty = "them", "empty ones" + } + return fmt.Sprintf("copy %s from the main worktree: %s; or, if this worktree needs none, create %s: touch %s", + it, strings.Join(cps, "; "), empty, strings.Join(missing, " ")) +} + +// checkEnvFiles fails with EnvFileMissing when the worktree lacks env files of the main worktree. +func (a *app) checkEnvFiles(ctx context.Context, wt git.Worktree, file, project string) error { + missing, err := a.missingEnvFiles(ctx, wt, file, project) + if err != nil || len(missing) == 0 { + return err + } + return fail.New(fail.EnvFileMissing, "this worktree lacks %s, which the main worktree %s has and git does not track; without it the stack would start with blank values", + strings.Join(missing, ", "), wt.MainTop()).WithHint("%s", envFileHint(wt, missing)) +} diff --git a/internal/cli/envfiles_test.go b/internal/cli/envfiles_test.go new file mode 100644 index 0000000..1b5fd6e --- /dev/null +++ b/internal/cli/envfiles_test.go @@ -0,0 +1,154 @@ +package cli + +import ( + "os" + "path/filepath" + "strings" + "testing" + + "github.com/tweinmann/siding/internal/fail" + "github.com/tweinmann/siding/internal/testutil" +) + +// linkedEnv: the main worktree /src/shop with an untracked .env, and a linked worktree +// /src/shop-feature-x without it, where siding runs. +func linkedEnv(t *testing.T) (e *env, linked string) { + t.Helper() + e = newEnv(t) + e.git("rm", "-q", "--cached", ".env") + e.git("commit", "-q", "-m", "no .env in git") + linked = filepath.Join(e.base, "shop-feature-x") + e.git("worktree", "add", "-q", "-b", "feature/x", linked) + e.opts.Dir = linked + e.proxyUp(80) + // What Compose prints for this worktree's project. + e.compose.config = strings.ReplaceAll(testConfig, "shop-main", "shop-feature-x") + return e, linked +} + +func composeUps(e *env) int { + n := 0 + for _, r := range e.compose.recorded() { + if r.args[0] == "up" { + n++ + } + } + return n +} + +func TestEnvFiles(t *testing.T) { + t.Parallel() + + t.Run("a new worktree without .env", func(t *testing.T) { + t.Parallel() + e, _ := linkedEnv(t) + code, stdout, _ := e.run("up", "--json") + if code != exitFailed || composeUps(e) != 0 { + t.Fatalf("exit %d, compose ups %d\n%s", code, composeUps(e), stdout) + } + testutil.Golden(t, filepath.Join("testdata", "json", "error-envfilemissing.json"), []byte(stdout)) + if !strings.Contains(stdout, "cp /src/shop/.env /src/shop-feature-x/.env") || strings.Contains(stdout, "not-a-real-token") { + t.Errorf("hint or a value:\n%s", stdout) + } + }) + + t.Run("an env_file", func(t *testing.T) { + t.Parallel() + e, linked := linkedEnv(t) + if err := os.WriteFile(filepath.Join(linked, ".env"), nil, 0o644); err != nil { + t.Fatal(err) + } + e.write("api.env", "API_TOKEN=not-a-real-api-token\n") + e.compose.unresolved = `{"services": {"api": {"env_file": [{"path": "` + filepath.Join(linked, "api.env") + `"}, + {"path": "` + filepath.Join(linked, "optional.env") + `", "required": false}]}}}` + code, stdout, _ := e.run("up", "--json") + if code != exitFailed || !strings.Contains(stdout, `"code": "`+fail.EnvFileMissing+`"`) || + !strings.Contains(stdout, "lacks api.env,") || strings.Contains(stdout, "optional.env") { + t.Errorf("exit %d\n%s", code, stdout) + } + }) + + t.Run("after the cp of the hint", func(t *testing.T) { + t.Parallel() + e, linked := linkedEnv(t) + data, err := os.ReadFile(filepath.Join(e.repo, ".env")) + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(linked, ".env"), data, 0o644); err != nil { + t.Fatal(err) + } + if code, _, stderr := e.run("up"); code != exitOK || composeUps(e) != 1 { + t.Errorf("exit %d, stderr %q", code, stderr) + } + }) + + t.Run("not needed", func(t *testing.T) { + t.Parallel() + e, _ := linkedEnv(t) + if err := os.Remove(filepath.Join(e.repo, ".env")); err != nil { + t.Fatal(err) + } + if code, _, stderr := e.run("up"); code != exitOK || composeUps(e) != 1 { + t.Errorf("main has no .env: exit %d, stderr %q", code, stderr) + } + }) + + t.Run("tracked", func(t *testing.T) { + t.Parallel() + e := newEnv(t) // .env is committed: every worktree has it + linked := filepath.Join(e.base, "shop-feature-x") + e.git("worktree", "add", "-q", "-b", "feature/x", linked) + e.opts.Dir = linked + e.proxyUp(80) + if err := os.Remove(filepath.Join(linked, ".env")); err != nil { + t.Fatal(err) + } + if code, _, stderr := e.run("up"); code != exitOK { + t.Errorf("a tracked .env deleted on the branch: exit %d, stderr %q", code, stderr) + } + }) + + t.Run("the main worktree", func(t *testing.T) { + t.Parallel() + e, _ := linkedEnv(t) + e.opts.Dir = e.repo + if err := os.Remove(filepath.Join(e.repo, ".env")); err != nil { + t.Fatal(err) + } + if code, _, stderr := e.run("up"); code != exitOK { + t.Errorf("exit %d, stderr %q", code, stderr) + } + }) +} + +func TestLintEnvFiles(t *testing.T) { + t.Parallel() + + t.Run(".env missing", func(t *testing.T) { + t.Parallel() + e, _ := linkedEnv(t) + code, stdout, _ := e.run("lint") + if code != exitOK || !strings.Contains(stdout, "warning MissingEnvFile, file .env:") || + !strings.Contains(stdout, "cp /src/shop/.env /src/shop-feature-x/.env") { + t.Errorf("exit %d\n%s", code, stdout) + } + }) + + t.Run("an env_file missing", func(t *testing.T) { + t.Parallel() + e, linked := linkedEnv(t) + if err := os.WriteFile(filepath.Join(linked, ".env"), nil, 0o644); err != nil { + t.Fatal(err) + } + e.write("api.env", "API_TOKEN=not-a-real-api-token\n") + e.compose.unresolved = strings.Replace(e.compose.config, `"api": {`, `"api": {"env_file": [{"path": "`+filepath.Join(linked, "api.env")+`"}], `, 1) + e.compose.configErr = fail.New(fail.ComposeFailed, "env file %s not found", filepath.Join(linked, "api.env")) + code, stdout, _ := e.run("lint", "--json") + // The other rules still run, on the configuration without env files. + if code != exitOK || !strings.Contains(stdout, `"rule": "MissingEnvFile"`) || !strings.Contains(stdout, `"subject": "file api.env"`) || + !strings.Contains(stdout, `"rule": "PublishedPort"`) { + t.Errorf("exit %d\n%s", code, stdout) + } + }) +} diff --git a/internal/cli/json.go b/internal/cli/json.go index cae6e09..a8980d9 100644 --- a/internal/cli/json.go +++ b/internal/cli/json.go @@ -234,6 +234,8 @@ type skillDocument struct { header Name string `json:"name"` Text string `json:"text"` + // Path is where skill --install wrote the skill. + Path string `json:"path,omitempty"` } // gcDocument is what gc prints, and what the overview's /api/gc returns. diff --git a/internal/cli/lint.go b/internal/cli/lint.go index f142b3c..3867954 100644 --- a/internal/cli/lint.go +++ b/internal/cli/lint.go @@ -1,12 +1,15 @@ package cli import ( + "context" "fmt" "path/filepath" "strings" "github.com/spf13/cobra" + "github.com/tweinmann/siding/internal/compose" + "github.com/tweinmann/siding/internal/git" "github.com/tweinmann/siding/internal/lint" "github.com/tweinmann/siding/internal/stack" ) @@ -26,15 +29,24 @@ file. It exits 1 when there is an error.`, ctx := cmd.Context() // The project and worktree siding would use; outside a worktree, the directory. top, project := a.opts.Dir, stack.Slug(filepath.Base(a.opts.Dir)) + var envFindings []lint.Finding + config := a.opts.Compose.Config if wt, err := a.opts.Git.Worktree(ctx, a.opts.Dir); err == nil { top = wt.Top project = stack.Identity{Repo: wt.RepoName(), Branch: wt.Branch}.Project() + if envFindings, err = a.lintEnvFiles(ctx, wt, file, project); err != nil { + return err + } + // Compose refuses the normal configuration while an env_file is missing. + if len(envFindings) > 0 { + config = a.opts.Compose.UnresolvedConfig + } } - path, p, err := a.loadProject(ctx, top, file, project) + path, p, err := a.loadConfig(ctx, top, file, project, config) if err != nil { return err } - findings := lint.Check(p, project, top) + findings := append(envFindings, lint.Check(p, project, top)...) doc := lintDocument{header: newHeader(kindLintReport), File: path} for _, f := range findings { doc.Findings = append(doc.Findings, lintFinding(f)) @@ -58,6 +70,25 @@ file. It exits 1 when there is an error.`, return cmd } +// lintEnvFiles warns MissingEnvFile for every env file up would refuse to start without. +func (a *app) lintEnvFiles(ctx context.Context, wt git.Worktree, file, project string) ([]lint.Finding, error) { + path, err := compose.FindFile(a.opts.Dir, wt.Top, file) + if err != nil { + return nil, nil // loadConfig reports it + } + missing, err := a.missingEnvFiles(ctx, wt, path, project) + if err != nil { + return nil, err + } + var out []lint.Finding + for _, rel := range missing { + out = append(out, lint.Finding{Rule: lint.MissingEnvFile, Severity: lint.Warning, Subject: "file " + rel, + Message: fmt.Sprintf("the main worktree %s has %s, untracked, and this worktree lacks it; siding up refuses to start without it", wt.MainTop(), rel), + Hint: envFileHint(wt, []string{rel})}) + } + return out, nil +} + func printLintText(cmd *cobra.Command, doc lintDocument) error { var b strings.Builder if len(doc.Findings) == 0 { diff --git a/internal/cli/lint_test.go b/internal/cli/lint_test.go index 3121f88..120e92a 100644 --- a/internal/cli/lint_test.go +++ b/internal/cli/lint_test.go @@ -35,7 +35,7 @@ func TestLint(t *testing.T) { for _, want := range []string{ "error ContainerName, service db: db sets container_name \"shop-db\", so a second stack of this file cannot start\n hint: remove container_name", "info NoRoot, stack:", - "/src/shop/compose.yaml: 3 errors, 6 warnings, 3 info\n", + "/src/shop/compose.yaml: 3 errors, 7 warnings, 3 info\n", } { if !strings.Contains(stdout, want) { t.Errorf("the text lacks %q:\n%s", want, stdout) diff --git a/internal/cli/skill.go b/internal/cli/skill.go index 1b8b8cf..9f72917 100644 --- a/internal/cli/skill.go +++ b/internal/cli/skill.go @@ -2,35 +2,139 @@ package cli import ( _ "embed" + "fmt" "io" + "os" + "path/filepath" + "strings" "github.com/spf13/cobra" + + "github.com/tweinmann/siding/internal/fail" ) -// skillText is the Claude Code skill siding ships, kept in the binary so that text and binary -// never drift apart. +// skillText is the skill siding ships, in the Agent Skills format, kept in the binary so that +// text and binary never drift apart. // //go:embed skill/SKILL.md var skillText string -func newSkillCommand() *cobra.Command { - var asJSON bool +// defaultSkillsDir is where skill --install writes without --dir, at the worktree's top. +const defaultSkillsDir = ".claude/skills" + +// agentsSection is what skill --install offers for AGENTS.md, which many harnesses read. It +// says what the skill says, in short, and names no command an agent should leave to the user. +const agentsSection = `## Running the app with siding + +- After a change the running app depends on, run ` + "`siding up --wait --json`" + ` and read + ` + "`verdict`" + ` and the exit code: 0 Ready, 1 Failed, 2 TimedOut or Stopped, 3 NoCapacity. +- Failed or TimedOut: fix the service in ` + "`failure`" + ` from its ` + "`hint`" + ` and ` + "`logs`" + `, then run it again. + Stopped: run it again. NoCapacity: stop and tell the user. +- When Ready, report ` + "`stack.url`" + `. Leave stopping and removing stacks and their data to the user. +- The skill ` + "`siding`" + ` (` + "`siding skill`" + `) has the details. +` + +// readingCommands are what an agent needs and may run without asking (design D3). +var readingCommands = []string{"up", "status", "logs", "ps"} + +func newSkillCommand(a *app) *cobra.Command { + var asJSON, install bool + var dir string cmd := &cobra.Command{ Use: "skill", - Short: "Print a Claude Code skill that teaches an agent to use siding", - Long: `Print a Claude Code skill (SKILL.md) that tells an agent to start its stack and wait -for the verdict. siding writes no file; install it with + Short: "Print the skill that teaches a coding agent to use siding, or install it", + Long: `Print the skill (SKILL.md, in the Agent Skills format) that tells a coding agent to +start its stack and wait for the verdict. Without --install, siding writes no file. - mkdir -p .claude/skills/siding && siding skill > .claude/skills/siding/SKILL.md`, +With --install, it writes the skill to /siding/SKILL.md: .claude/skills at the worktree's +top (commit it, so every worktree has it), or the skills directory of any harness with --dir, +e.g. --dir ~/.claude/skills for every repository. It then prints a section for AGENTS.md and +the permissions for siding's reading commands; it never writes those files.`, Args: noArgs, RunE: func(cmd *cobra.Command, _ []string) error { + if dir != "" && !install { + return fail.New(fail.InvalidArguments, "--dir needs --install"). + WithHint("siding skill --install --dir ") + } + doc := skillDocument{header: newHeader(kindSkill), Name: "siding", Text: skillText} + if !install { + if asJSON { + return printJSON(cmd.OutOrStdout(), doc) + } + _, err := io.WriteString(cmd.OutOrStdout(), skillText) + return err + } + path, replaced, inRepo, err := a.installSkill(cmd, dir) + if err != nil { + return err + } + doc.Path = path + // With --json, stdout holds the one document; the snippets go to stderr. + out := cmd.OutOrStdout() if asJSON { - return printJSON(cmd.OutOrStdout(), skillDocument{header: newHeader(kindSkill), Name: "siding", Text: skillText}) + if err := printJSON(out, doc); err != nil { + return err + } + out = cmd.ErrOrStderr() } - _, err := io.WriteString(cmd.OutOrStdout(), skillText) + _, err = io.WriteString(out, installText(path, replaced, inRepo)) return err }, } + cmd.Flags().BoolVar(&install, "install", false, "write the skill to /siding/SKILL.md instead of printing it") + cmd.Flags().StringVar(&dir, "dir", "", "skills directory of your harness (default: .claude/skills at the worktree's top)") registerJSON(cmd, &asJSON) return cmd } + +// installSkill writes the skill and reports its path, whether it replaced an older copy, and +// whether it went to the default directory of the repository. +func (a *app) installSkill(cmd *cobra.Command, dir string) (path string, replaced, inRepo bool, err error) { + switch { + case dir == "": + top, err := a.opts.Git.Top(cmd.Context(), a.opts.Dir) + if err != nil { + return "", false, false, err + } + dir, inRepo = filepath.Join(top, defaultSkillsDir), true + case dir == "~" || strings.HasPrefix(dir, "~/"): + dir = filepath.Join(a.opts.Home, strings.TrimPrefix(dir, "~")) + case !filepath.IsAbs(dir): + dir = filepath.Join(a.opts.Dir, dir) + } + path = filepath.Join(dir, "siding", "SKILL.md") + if _, err := os.Stat(path); err == nil { + replaced = true + } + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + return "", false, false, fmt.Errorf("install the skill: %w", err) + } + if err := os.WriteFile(path, []byte(skillText), 0o644); err != nil { + return "", false, false, fmt.Errorf("install the skill: %w", err) + } + return path, replaced, inRepo, nil +} + +// installText says what was written, how to share it, and the two snippets of design D3. +func installText(path string, replaced, inRepo bool) string { + var b strings.Builder + verb := "Wrote" + if replaced { + verb = "Updated" + } + fmt.Fprintf(&b, "%s %s\n", verb, path) + if inRepo { + fmt.Fprintf(&b, "Commit it, so every worktree has it:\n git add %s/siding/SKILL.md && git commit -m \"Add the siding skill\"\n", defaultSkillsDir) + } + b.WriteString("\nFor harnesses that read AGENTS.md, add this section to it:\n\n") + b.WriteString(agentsSection) + var allow, plain []string + for _, c := range readingCommands { + allow = append(allow, fmt.Sprintf("%q", "Bash(siding "+c+":*)")) + plain = append(plain, "siding "+c) + } + b.WriteString("\nLet the agent run siding's reading commands without asking.\n") + fmt.Fprintf(&b, "Claude Code, in .claude/settings.json:\n {\"permissions\": {\"allow\": [%s]}}\n", strings.Join(allow, ", ")) + fmt.Fprintf(&b, "Other harnesses: allow %s.\n", strings.Join(plain, ", ")) + return b.String() +} diff --git a/internal/cli/skill_test.go b/internal/cli/skill_test.go index 9634d9c..3ae755f 100644 --- a/internal/cli/skill_test.go +++ b/internal/cli/skill_test.go @@ -2,10 +2,12 @@ package cli import ( "encoding/json" + "os" "path/filepath" "strings" "testing" + "github.com/tweinmann/siding/internal/fail" "github.com/tweinmann/siding/internal/testutil" ) @@ -21,6 +23,10 @@ func TestSkill(t *testing.T) { if !strings.HasPrefix(text, "---\nname: siding\ndescription: ") { t.Errorf("not a skill named siding:\n%s", text[:min(len(text), 80)]) } + // The same file works in any harness that reads the Agent Skills format. + if strings.Contains(text, "Claude Code") { + t.Error("the skill names a harness") + } for _, want := range []string{"siding up --wait --json", "siding status --json", "siding logs --json", "**0, `Ready`**", "**1, `Failed`**", "**2, `TimedOut`**", "**2, `Stopped`**", "**3, `NoCapacity`**", "`stack.url`", "Never give\n `localhost:`"} { if !strings.Contains(text, want) { @@ -45,3 +51,83 @@ func TestSkill(t *testing.T) { t.Errorf("document %+v, err %v", doc, err) } } + +func TestSkillInstall(t *testing.T) { + t.Parallel() + + t.Run("into the repository, from a subdirectory", func(t *testing.T) { + t.Parallel() + e := newEnv(t) + e.write(".claude/settings.json", `{"permissions": {"allow": []}}`+"\n") + e.write("web/app.js", "") + e.opts.Dir = filepath.Join(e.repo, "web") + code, stdout, stderr := e.run("skill", "--install") + if code != exitOK || stderr != "" { + t.Fatalf("exit %d, stderr %q", code, stderr) + } + data, err := os.ReadFile(filepath.Join(e.repo, ".claude", "skills", "siding", "SKILL.md")) + if err != nil || string(data) != skillText { + t.Fatalf("skill not written: %v", err) + } + for _, want := range []string{"Wrote /src/shop/.claude/skills/siding/SKILL.md", "Commit it, so every worktree has it", + "## Running the app with siding", `"Bash(siding up:*)"`, `"Bash(siding status:*)"`, `"Bash(siding logs:*)"`, + `"Bash(siding ps:*)"`, "allow siding up, siding status, siding logs, siding ps"} { + if !strings.Contains(stdout, want) { + t.Errorf("output lacks %q:\n%s", want, stdout) + } + } + // Only reading commands: what removes or stops anything stays the human's. + for _, never := range []string{"down", "gc", "snapshot rm", "teardown", "--force", "--volumes"} { + if strings.Contains(stdout, never) { + t.Errorf("output mentions %q", never) + } + } + if got, _ := os.ReadFile(filepath.Join(e.repo, ".claude", "settings.json")); string(got) != `{"permissions": {"allow": []}}`+"\n" { + t.Errorf("settings.json changed: %s", got) + } + if code, stdout, _ := e.run("skill", "--install"); code != exitOK || !strings.HasPrefix(stdout, "Updated ") { + t.Errorf("again: exit %d, %q", code, stdout) + } + }) + + t.Run("another harness", func(t *testing.T) { + t.Parallel() + e := newEnv(t) + code, stdout, _ := e.run("skill", "--install", "--dir", "~/.agents/skills") + want := filepath.Join(e.opts.Home, ".agents", "skills", "siding", "SKILL.md") + if _, err := os.Stat(want); code != exitOK || err != nil { + t.Fatalf("exit %d, %v\n%s", code, err, stdout) + } + if strings.Contains(stdout, "Commit it") { + t.Error("a skill outside the repository needs no commit") + } + if _, err := os.Stat(filepath.Join(e.repo, ".claude")); err == nil { + t.Error("--dir wrote under .claude") + } + }) + + t.Run("JSON", func(t *testing.T) { + t.Parallel() + e := newEnv(t) + code, stdout, stderr := e.run("skill", "--install", "--json") + if code != exitOK || !strings.Contains(stderr, "## Running the app with siding") { + t.Fatalf("exit %d, stderr %q", code, stderr) + } + var doc skillDocument + if err := json.Unmarshal([]byte(stdout), &doc); err != nil || doc.Path != "/src/shop/.claude/skills/siding/SKILL.md" || doc.Text != skillText { + t.Errorf("document %+v, err %v", doc.Path, err) + } + }) + + t.Run("refusals", func(t *testing.T) { + t.Parallel() + e := newEnv(t) + if code, stdout, _ := e.run("skill", "--dir", "x", "--json"); code != exitFailed || !strings.Contains(stdout, `"code": "`+fail.InvalidArguments+`"`) { + t.Errorf("--dir without --install: exit %d, %s", code, stdout) + } + e.opts.Dir = t.TempDir() // not a git worktree + if code, stdout, _ := e.run("skill", "--install", "--json"); code != exitFailed || !strings.Contains(stdout, `"code": "`+fail.NotAGitRepository+`"`) { + t.Errorf("outside a worktree: exit %d, %s", code, stdout) + } + }) +} diff --git a/internal/cli/stack.go b/internal/cli/stack.go index eb7cf9b..3e78734 100644 --- a/internal/cli/stack.go +++ b/internal/cli/stack.go @@ -101,11 +101,18 @@ func (a *app) shownPort(ctx context.Context) int { // loadProject reads the compose configuration of a worktree as project. func (a *app) loadProject(ctx context.Context, top, file, project string) (string, *compose.Project, error) { + return a.loadConfig(ctx, top, file, project, a.opts.Compose.Config) +} + +// loadConfig is loadProject with the Compose call that prints the configuration, e.g. +// UnresolvedConfig when an env file is missing. +func (a *app) loadConfig(ctx context.Context, top, file, project string, + config func(context.Context, compose.Invocation) ([]byte, error)) (string, *compose.Project, error) { path, err := compose.FindFile(a.opts.Dir, top, file) if err != nil { return "", nil, err } - data, err := a.opts.Compose.Config(ctx, compose.Invocation{Dir: top, Project: project, Files: []string{path}}) + data, err := config(ctx, compose.Invocation{Dir: top, Project: project, Files: []string{path}}) if err != nil { return "", nil, err } diff --git a/internal/cli/testdata/json/error-envfilemissing.json b/internal/cli/testdata/json/error-envfilemissing.json new file mode 100644 index 0000000..bcf22ee --- /dev/null +++ b/internal/cli/testdata/json/error-envfilemissing.json @@ -0,0 +1,7 @@ +{ + "apiVersion": "siding.dev/v1alpha1", + "kind": "Error", + "code": "EnvFileMissing", + "message": "this worktree lacks .env, which the main worktree /src/shop has and git does not track; without it the stack would start with blank values", + "hint": "copy it from the main worktree: cp /src/shop/.env /src/shop-feature-x/.env; or, if this worktree needs none, create an empty one: touch .env" +} diff --git a/internal/cli/testdata/json/lintreport.json b/internal/cli/testdata/json/lintreport.json index 65ee1d4..806a70c 100644 --- a/internal/cli/testdata/json/lintreport.json +++ b/internal/cli/testdata/json/lintreport.json @@ -59,6 +59,13 @@ "message": "tools has no healthcheck and no route path; the verdict only knows that it runs", "hint": "add a healthcheck, so Ready means the service works, not only that it started" }, + { + "rule": "LocalhostURL", + "severity": "warning", + "subject": "service worker", + "message": "worker sets API_URL to localhost:3000, which behind the proxy reaches worker's own container, not another service or your machine", + "hint": "between services use the service's name, e.g. http://:3000; in the browser, a path on the stack's address" + }, { "rule": "NoHealthcheck", "severity": "warning", diff --git a/internal/cli/up.go b/internal/cli/up.go index 436d5a6..048985d 100644 --- a/internal/cli/up.go +++ b/internal/cli/up.go @@ -224,6 +224,11 @@ func (a *app) up(cmd *cobra.Command, f upFlags, w waitFlags, asJSON bool) error } } + if path, err := compose.FindFile(a.opts.Dir, wt.Top, f.file); err == nil { + if err := a.checkEnvFiles(ctx, wt, path, project); err != nil { + return err + } + } file, p, err := a.loadProject(ctx, wt.Top, f.file, project) if err != nil { return err diff --git a/internal/compose/compose.go b/internal/compose/compose.go index 04fe45e..8aae043 100644 --- a/internal/compose/compose.go +++ b/internal/compose/compose.go @@ -98,6 +98,19 @@ func (c *CLI) Config(ctx context.Context, inv Invocation) ([]byte, error) { return out.Bytes(), nil } +// UnresolvedConfig prints the normalised configuration without reading env files, so it +// succeeds even when an env_file is missing; EnvFiles reads their paths from it. +func (c *CLI) UnresolvedConfig(ctx context.Context, inv Invocation) ([]byte, error) { + if err := c.checkVersion(ctx); err != nil { + return nil, err + } + var out, errOut bytes.Buffer + if err := c.exec(ctx, inv, inv.args("config", "--no-env-resolution", "--format", "json"), &out, &errOut); err != nil { + return nil, composeError("read the compose configuration", errOut.String(), err) + } + return out.Bytes(), nil +} + // Run runs docker compose with args, streaming its output. On failure the error carries the // last lines Compose printed on stderr. func (c *CLI) Run(ctx context.Context, inv Invocation, args []string, stdout, stderr io.Writer) error { diff --git a/internal/compose/config.go b/internal/compose/config.go index 8158aff..2fac2e9 100644 --- a/internal/compose/config.go +++ b/internal/compose/config.go @@ -6,6 +6,7 @@ package compose import ( "encoding/json" "fmt" + "maps" "os" "path/filepath" "slices" @@ -268,3 +269,39 @@ func parseExpose(raw json.RawMessage) ([]int, error) { } return []int{first}, nil } + +// EnvFile is an env_file of a service: an absolute path, and whether Compose needs it. +type EnvFile struct { + Path string + Required bool +} + +// EnvFiles returns the env files of every service in the output of UnresolvedConfig, each path +// once, in order. An entry without "required" is required, as Compose has it. +func EnvFiles(data []byte) ([]EnvFile, error) { + var raw struct { + Services map[string]struct { + EnvFile []struct { + Path string `json:"path"` + Required *bool `json:"required"` + } `json:"env_file"` + } `json:"services"` + } + if err := json.Unmarshal(data, &raw); err != nil { + return nil, fmt.Errorf("read compose config: %w", err) + } + seen := map[string]int{} + var out []EnvFile + for _, name := range slices.Sorted(maps.Keys(raw.Services)) { + for _, f := range raw.Services[name].EnvFile { + required := f.Required == nil || *f.Required + if i, ok := seen[f.Path]; ok { + out[i].Required = out[i].Required || required + continue + } + seen[f.Path] = len(out) + out = append(out, EnvFile{Path: f.Path, Required: required}) + } + } + return out, nil +} diff --git a/internal/compose/config_test.go b/internal/compose/config_test.go index 1e3d069..5a84b4d 100644 --- a/internal/compose/config_test.go +++ b/internal/compose/config_test.go @@ -208,3 +208,26 @@ func TestParseConfigBuild(t *testing.T) { t.Errorf("app build %v, db build %v; want true, false", p.Services["app"].Build, p.Services["db"].Build) } } + +func TestEnvFiles(t *testing.T) { + t.Parallel() + // What docker compose config --no-env-resolution --format json printed for two services, + // one env file shared, one optional. + data := []byte(`{"name": "shop-main", "services": { + "web": {"env_file": [{"path": "/src/shop/web.env"}, {"path": "/src/shop/common.env", "required": false}]}, + "api": {"env_file": [{"path": "/src/shop/common.env"}]}, + "db": {} + }}`) + got, err := EnvFiles(data) + if err != nil { + t.Fatal(err) + } + // api comes first; common.env is required because api needs it. + want := []EnvFile{{Path: "/src/shop/common.env", Required: true}, {Path: "/src/shop/web.env", Required: true}} + if !reflect.DeepEqual(got, want) { + t.Errorf("got %+v, want %+v", got, want) + } + if _, err := EnvFiles([]byte("not json")); err == nil { + t.Error("broken output must fail") + } +} diff --git a/internal/compose/testdata/lint/config.json b/internal/compose/testdata/lint/config.json index d8b1858..2e85136 100644 --- a/internal/compose/testdata/lint/config.json +++ b/internal/compose/testdata/lint/config.json @@ -97,6 +97,7 @@ }, "worker": { "scale": 3, + "environment": {"API_URL": "http://localhost:3000/v1", "DATABASE_URL": "postgres://app:not-a-real-token@db:5432/app"}, "command": null, "entrypoint": null, "image": "busybox:1.37.0", diff --git a/internal/e2e/phase5_test.go b/internal/e2e/phase5_test.go new file mode 100644 index 0000000..4dade45 --- /dev/null +++ b/internal/e2e/phase5_test.go @@ -0,0 +1,39 @@ +//go:build docker + +package e2e + +import ( + "context" + "os" + "path/filepath" + "testing" + + "github.com/tweinmann/siding/internal/compose" +) + +// Compose fails its config on a missing env_file, but lists it without env resolution. +func TestEnvFilesFromCompose(t *testing.T) { + dir := t.TempDir() + file := filepath.Join(dir, "compose.yaml") + content := "services:\n web:\n image: busybox:1.37.0\n env_file: [app.env, {path: opt.env, required: false}]\n" + if err := os.WriteFile(file, []byte(content), 0o644); err != nil { + t.Fatal(err) + } + c := &compose.CLI{} + inv := compose.Invocation{Dir: dir, Project: "siding-test-envfiles", Files: []string{file}} + if _, err := c.Config(context.Background(), inv); err == nil { + t.Error("docker compose config accepted a missing env_file") + } + data, err := c.UnresolvedConfig(context.Background(), inv) + if err != nil { + t.Fatal(err) + } + got, err := compose.EnvFiles(data) + if err != nil { + t.Fatal(err) + } + if len(got) != 2 || got[0] != (compose.EnvFile{Path: filepath.Join(dir, "app.env"), Required: true}) || + got[1] != (compose.EnvFile{Path: filepath.Join(dir, "opt.env"), Required: false}) { + t.Errorf("env files %+v", got) + } +} diff --git a/internal/fail/fail.go b/internal/fail/fail.go index 842a8ea..6e59ed6 100644 --- a/internal/fail/fail.go +++ b/internal/fail/fail.go @@ -63,6 +63,8 @@ const ( SnapshotNotFound = "SnapshotNotFound" // SnapshotExists: the repository already has a snapshot of that name. SnapshotExists = "SnapshotExists" + // EnvFileMissing: a linked worktree lacks an untracked env file the main worktree has. + EnvFileMissing = "EnvFileMissing" // Internal: an unexpected error without a code of its own. Internal = "Internal" ) diff --git a/internal/git/git.go b/internal/git/git.go index 33276ec..d6e010f 100644 --- a/internal/git/git.go +++ b/internal/git/git.go @@ -31,6 +31,21 @@ func (w Worktree) RepoName() string { return filepath.Base(filepath.Dir(w.CommonDir)) } +// MainTop is the main worktree's top-level directory: the one holding the common git directory +// when that is named .git. It is "" for a bare repository or a common directory elsewhere. +func (w Worktree) MainTop() string { + if filepath.Base(w.CommonDir) != ".git" { + return "" + } + return filepath.Dir(w.CommonDir) +} + +// Linked reports whether w is a linked worktree of a repository with a main worktree. +func (w Worktree) Linked() bool { + main := w.MainTop() + return main != "" && main != w.Top +} + // Client runs git. type Client struct { // Binary is the git executable; empty means "git" from PATH. @@ -104,6 +119,20 @@ func (c Client) Worktree(ctx context.Context, dir string) (Worktree, error) { return w, nil } +// Top returns the top-level directory of the worktree containing dir, also with a detached +// HEAD. It fails with NotAGitRepository outside a worktree. +func (c Client) Top(ctx context.Context, dir string) (string, error) { + out, err := c.run(ctx, dir, "rev-parse", "--path-format=absolute", "--show-toplevel") + if err != nil { + if exitCode(err) > 0 { + return "", fail.New(fail.NotAGitRepository, "%s is not inside a git worktree", dir). + WithHint("run it in a git worktree, or name the skills directory with --dir") + } + return "", err + } + return strings.TrimSpace(out), nil +} + // Dirty reports whether git status lists any change in the worktree, untracked files // included and ignored files excluded. func (c Client) Dirty(ctx context.Context, top string) (bool, error) { @@ -114,6 +143,18 @@ func (c Client) Dirty(ctx context.Context, top string) (bool, error) { return strings.TrimSpace(out) != "", nil } +// Tracked reports whether git tracks path, relative to the worktree top. +func (c Client) Tracked(ctx context.Context, top, path string) (bool, error) { + _, err := c.run(ctx, top, "ls-files", "--error-unmatch", "--", path) + switch { + case err == nil: + return true, nil + case exitCode(err) == 1: + return false, nil + } + return false, err +} + // Repo names a repository for commands that need no worktree: the worktree's directory, or, // when the worktree is gone, the common git directory. type Repo struct { diff --git a/internal/git/git_test.go b/internal/git/git_test.go index 1cd0b7e..09cbc2b 100644 --- a/internal/git/git_test.go +++ b/internal/git/git_test.go @@ -184,3 +184,66 @@ func TestMergeState(t *testing.T) { }) } } + +func TestMainWorktree(t *testing.T) { + t.Parallel() + ctx := context.Background() + main := newRepo(t) + linked := filepath.Join(filepath.Dir(main), "shop-feature-x") + sh(t, main, "worktree", "add", "-q", "-b", "feature/x", linked) + c := Client{} + for _, tt := range []struct { + dir string + linked bool + }{{main, false}, {linked, true}} { + w, err := c.Worktree(ctx, tt.dir) + if err != nil { + t.Fatal(err) + } + real, _ := filepath.EvalSymlinks(main) + if w.MainTop() != real || w.Linked() != tt.linked { + t.Errorf("%s: main top %q, linked %v", tt.dir, w.MainTop(), w.Linked()) + } + } + // A common git directory not named .git has no main worktree. + if w := (Worktree{Top: "/src/shop", CommonDir: "/src/shop.git"}); w.MainTop() != "" || w.Linked() { + t.Errorf("bare: %q %v", w.MainTop(), w.Linked()) + } +} + +func TestTracked(t *testing.T) { + t.Parallel() + ctx := context.Background() + dir := newRepo(t) + for name, content := range map[string]string{".env.example": "A=1\n", ".env": "A=not-a-real-token\n"} { + if err := os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644); err != nil { + t.Fatal(err) + } + } + sh(t, dir, "add", ".env.example") + c := Client{} + for path, want := range map[string]bool{".env.example": true, ".env": false, "missing.env": false} { + got, err := c.Tracked(ctx, dir, path) + if err != nil || got != want { + t.Errorf("%s: %v, %v, want %v", path, got, err, want) + } + } +} + +func TestTop(t *testing.T) { + t.Parallel() + ctx := context.Background() + dir := newRepo(t) + sh(t, dir, "checkout", "-q", "--detach") + sub := filepath.Join(dir, "web") + if err := os.MkdirAll(sub, 0o755); err != nil { + t.Fatal(err) + } + real, _ := filepath.EvalSymlinks(dir) + if top, err := (Client{}).Top(ctx, sub); err != nil || top != real { + t.Errorf("detached, in a subdirectory: %q, %v", top, err) + } + if _, err := (Client{}).Top(ctx, t.TempDir()); code(err) != fail.NotAGitRepository { + t.Errorf("outside: %v", err) + } +} diff --git a/internal/lint/lint.go b/internal/lint/lint.go index c17f808..9cefe82 100644 --- a/internal/lint/lint.go +++ b/internal/lint/lint.go @@ -5,7 +5,10 @@ package lint import ( "errors" "fmt" + "maps" "path/filepath" + "regexp" + "slices" "sort" "strings" @@ -33,6 +36,8 @@ const ( NoHealthcheck = "NoHealthcheck" PublishedPort = "PublishedPort" NoRoot = "NoRoot" + MissingEnvFile = "MissingEnvFile" + LocalhostURL = "LocalhostURL" ) // Finding is one problem. @@ -45,6 +50,9 @@ type Finding struct { Hint string } +// localhostURL is a loopback host with a port in an environment value. +var localhostURL = regexp.MustCompile(`(?i)(?:^|[^a-z0-9.-])(localhost|127\.0\.0\.1|\[::1\]):(\d+)`) + // Check lints p, the configuration of project, whose worktree is the directory every relative // bind mount lives in. func Check(p *compose.Project, project, worktree string) []Finding { @@ -76,6 +84,15 @@ func Check(p *compose.Project, project, worktree string) []Finding { "%s mounts %s from the host, and every branch's stack writes into the same directory", name, src) } } + for _, key := range slices.Sorted(maps.Keys(s.Environment)) { + // Only service, variable and host:port reach the finding, never the rest of the + // value: it may hold a password. + if m := localhostURL.FindStringSubmatch(s.Environment[key]); m != nil { + add(LocalhostURL, Warning, subject, + fmt.Sprintf("between services use the service's name, e.g. http://:%s; in the browser, a path on the stack's address", m[2]), + "%s sets %s to %s:%s, which behind the proxy reaches %s's own container, not another service or your machine", name, key, m[1], m[2], name) + } + } if s.NetworkMode != "" { add(NetworkMode, Warning, subject, "remove network_mode to make the service reachable through the proxy", "%s uses network_mode %q, so siding cannot route it", name, s.NetworkMode) diff --git a/internal/lint/lint_test.go b/internal/lint/lint_test.go index 057a12a..d097c9a 100644 --- a/internal/lint/lint_test.go +++ b/internal/lint/lint_test.go @@ -4,6 +4,7 @@ import ( "os" "path/filepath" "reflect" + "strings" "testing" "github.com/tweinmann/siding/internal/compose" @@ -35,6 +36,7 @@ func TestCheckEveryRule(t *testing.T) { {NoHealthcheck, Warning, "service db"}, {NetworkMode, Warning, "service tools"}, {NoHealthcheck, Warning, "service tools"}, + {LocalhostURL, Warning, "service worker"}, // API_URL; DATABASE_URL names db, not localhost {NoHealthcheck, Warning, "service worker"}, {PublishedPort, Info, "service db"}, {FixedVolumeName, Info, "volume cache"}, // shared on purpose @@ -80,3 +82,40 @@ func TestCheckRoutes(t *testing.T) { } } } + +func TestLocalhostURL(t *testing.T) { + t.Parallel() + for _, tt := range []struct { + name, value, want string // want is host:port, "" for no finding + }{ + {name: "an API URL", value: "http://localhost:3000/v1", want: "localhost:3000"}, + {name: "a password in the value", value: "postgres://app:not-a-real-token@127.0.0.1:5432/app", want: "127.0.0.1:5432"}, + {name: "IPv6", value: "http://[::1]:8080", want: "[::1]:8080"}, + {name: "upper case", value: "HTTP://LOCALHOST:80", want: "LOCALHOST:80"}, + {name: "without a port", value: "localhost"}, + {name: "another host", value: "http://api:3000"}, + {name: "a longer name", value: "http://mylocalhost:3000"}, + } { + p := &compose.Project{Services: map[string]compose.Service{"web": {Environment: map[string]string{"X_URL": tt.value}}}} + var found []Finding + for _, f := range Check(p, "shop-main", "/src/shop") { + if f.Rule == LocalhostURL { + found = append(found, f) + } + } + switch { + case tt.want == "" && len(found) > 0: + t.Errorf("%s: unexpected %+v", tt.name, found) + case tt.want != "" && len(found) != 1: + t.Errorf("%s: %d findings", tt.name, len(found)) + case tt.want != "": + f := found[0] + if f.Severity != Warning || f.Subject != "service web" || !strings.Contains(f.Message, "X_URL") || !strings.Contains(f.Message, tt.want) { + t.Errorf("%s: %+v", tt.name, f) + } + if strings.Contains(f.Message+f.Hint, "not-a-real-token") || strings.Contains(f.Message+f.Hint, "/v1") { + t.Errorf("%s: the finding holds more of the value than host and port: %+v", tt.name, f) + } + } + } +} diff --git a/justfile b/justfile index f9f9bea..614a94d 100644 --- a/justfile +++ b/justfile @@ -42,6 +42,16 @@ build-darwin: GOOS=darwin GOARCH=$arch CGO_ENABLED=0 go build -trimpath -o bin/siding-darwin-$arch ./cmd/siding; \ done +# Build the release binaries into dist/: static, for macOS and Linux on arm64 and amd64, with +# the version, and SHA256SUMS in the format shasum -a 256 -c reads on macOS +dist version: + rm -rf dist && mkdir -p dist + for os in darwin linux; do for arch in arm64 amd64; do \ + GOOS=$os GOARCH=$arch CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.version={{version}}" \ + -o dist/siding-$os-$arch ./cmd/siding; \ + done; done + cd dist && sha256sum siding-* > SHA256SUMS + # Inner daemon: a compose project with a healthcheck, ports reset by an override, Traefik routing smoke-docker: hack/smoke/docker.sh diff --git a/openspec/changes/phase-5-onboarding/tasks.md b/openspec/changes/phase-5-onboarding/tasks.md index 88a37ee..b3ee189 100644 --- a/openspec/changes/phase-5-onboarding/tasks.md +++ b/openspec/changes/phase-5-onboarding/tasks.md @@ -2,33 +2,35 @@ ## 1. Foundations -- [ ] 1.1 Add the error code `EnvFileMissing` and the lint rule names `MissingEnvFile` and `LocalhostURL`; verify with the error-code table test -- [ ] 1.2 Add `MainTop` and `Tracked` to `internal/git` (D4); verify with tests on a real repository with a linked worktree, a bare-like custom layout, and a tracked and an untracked file -- [ ] 1.3 Add reading the `env_file` paths from `docker compose config --no-env-resolution --format json` to `internal/compose`, with `required: false` kept; verify with a captured config and, in `just smoke-stacks`, against `docker compose config` with a missing file -- [ ] 1.4 Restructure the README's "Using siding" as the user journey (D8): "Get started" in the order a user walks it (install, once per machine, once per repository, per task with a worktree and an agent, keeping an eye on it, after the merge), a few commands and sentences per step with links, and "Reference" with today's sections (routing labels, verdict and exit codes, lint rules, snapshots and seeding, memory budget and idle stacks, builds, devcontainer, removing siding); verify that no content of today's README is lost and every link resolves +- [x] 1.1 Add the error code `EnvFileMissing` and the lint rule names `MissingEnvFile` and `LocalhostURL`; verify with the error-code table test +- [x] 1.2 Add `MainTop` and `Tracked` to `internal/git` (D4); verify with tests on a real repository with a linked worktree, a bare-like custom layout, and a tracked and an untracked file +- [x] 1.3 Add reading the `env_file` paths from `docker compose config --no-env-resolution --format json` to `internal/compose`, with `required: false` kept; verify with a captured config and, in `just smoke-stacks`, against `docker compose config` with a missing file +- [x] 1.4 Restructure the README's "Using siding" as the user journey (D8): "Get started" in the order a user walks it (install, once per machine, once per repository, per task with a worktree and an agent, keeping an eye on it, after the merge), a few commands and sentences per step with links, and "Reference" with today's sections (routing labels, verdict and exit codes, lint rules, snapshots and seeding, memory budget and idle stacks, builds, devcontainer, removing siding); verify that no content of today's README is lost and every link resolves ## 2. Releases -- [ ] 2.1 Add `just dist ` (D1): four static binaries in `dist/` with the version and `SHA256SUMS`; verify in the devcontainer that `dist/siding-linux-arm64 version` reports the version and `sha256sum -c SHA256SUMS` passes -- [ ] 2.2 Add `.github/workflows/release.yml` on `v*.*.*` tags: `just test` and `just dist` in the devcontainer, then `gh release create --verify-tag --generate-notes` with `contents: write` for that job only; verify with `actionlint` if available, else by review, and by the first tag after approval -- [ ] 2.3 Write step 1 of the README's journey, the install (download, `shasum -a 256 -c`, `chmod`, `PATH`, `xattr -d com.apple.quarantine` on macOS) and keep "build from source" for development; verify the commands against a `just dist` build in the devcontainer and on the Mac in task 7.2 +- [x] 2.1 Add `just dist ` (D1): four static binaries in `dist/` with the version and `SHA256SUMS`; verify in the devcontainer that `dist/siding-linux-arm64 version` reports the version and `sha256sum -c SHA256SUMS` passes +- [x] 2.2 Add `.github/workflows/release.yml` on `v*.*.*` tags: `just test` and `just dist` in the devcontainer, then `gh release create --verify-tag --generate-notes` with `contents: write` for that job only; verify with `actionlint` if available, else by review, and by the first tag after approval + - Checked by review and by parsing the YAML (actionlint was not available, its image was not pulled); the run itself is checked by the first tag after approval, see the workflow follow-up. +- [x] 2.3 Write step 1 of the README's journey, the install (download, `shasum -a 256 -c`, `chmod`, `PATH`, `xattr -d com.apple.quarantine` on macOS) and keep "build from source" for development; verify the commands against a `just dist` build in the devcontainer and on the Mac in task 7.2 + - Checked in the devcontainer against `just dist v0.5.0-test`; whether macOS's `shasum` knows `--ignore-missing` is checked on the Mac in 7.2. ## 3. The skill for any harness -- [ ] 3.1 Implement `siding skill --install [--dir]` (D2): the default directory at the worktree's top, `~` expanded, an older copy replaced, `NotAGitRepository` outside a worktree without `--dir`, `--dir` without `--install` refused, `path` in `Skill`; verify with fake-based tests per scenario of `agent-skill` and the updated `skill.json` golden -- [ ] 3.2 Print the `AGENTS.md` section and the permissions (D3), on stderr with `--json`; verify with a test that names the four reading commands and none of `down`, `gc`, `snapshot rm`, `teardown`, and that an existing `.claude/settings.json` is unchanged -- [ ] 3.3 Keep the skill harness-neutral; verify with the skill test that it does not contain "Claude Code" -- [ ] 3.4 Write the agent part of the journey's steps 3 and 4 and its reference: `--install`, committing the file, `--dir` for other harnesses and a global install, the snippets; verify the commands run as written in the devcontainer +- [x] 3.1 Implement `siding skill --install [--dir]` (D2): the default directory at the worktree's top, `~` expanded, an older copy replaced, `NotAGitRepository` outside a worktree without `--dir`, `--dir` without `--install` refused, `path` in `Skill`; verify with fake-based tests per scenario of `agent-skill` and the updated `skill.json` golden +- [x] 3.2 Print the `AGENTS.md` section and the permissions (D3), on stderr with `--json`; verify with a test that names the four reading commands and none of `down`, `gc`, `snapshot rm`, `teardown`, and that an existing `.claude/settings.json` is unchanged +- [x] 3.3 Keep the skill harness-neutral; verify with the skill test that it does not contain "Claude Code" +- [x] 3.4 Write the agent part of the journey's steps 3 and 4 and its reference: `--install`, committing the file, `--dir` for other harnesses and a global install, the snippets; verify the commands run as written in the devcontainer ## 4. Env files -- [ ] 4.1 Check the env files of the main worktree in `up` before Compose runs (D4) and fail with `EnvFileMissing`, all missing files in the message and the `cp` commands and `touch .env` in the hint; verify with fake-based tests per scenario of `stack-lifecycle` "Env files of the main worktree" and an `error-envfilemissing.json` golden -- [ ] 4.2 Report `MissingEnvFile` in `lint` and lint the rest on the `--no-env-resolution` config; verify with a fake-based test of a linked worktree without `.env` and one without an `env_file` -- [ ] 4.3 Document env files in the journey's step 4 and the reference (what siding checks, why it never copies, `touch .env`); verify the example matches the tests +- [x] 4.1 Check the env files of the main worktree in `up` before Compose runs (D4) and fail with `EnvFileMissing`, all missing files in the message and the `cp` commands and `touch .env` in the hint; verify with fake-based tests per scenario of `stack-lifecycle` "Env files of the main worktree" and an `error-envfilemissing.json` golden +- [x] 4.2 Report `MissingEnvFile` in `lint` and lint the rest on the `--no-env-resolution` config; verify with a fake-based test of a linked worktree without `.env` and one without an `env_file` +- [x] 4.3 Document env files in the journey's step 4 and the reference (what siding checks, why it never copies, `touch .env`); verify the example matches the tests ## 5. localhost in the environment -- [ ] 5.1 Implement `LocalhostURL` in `internal/lint` (D5); verify with table tests for the spec's scenarios (an API URL, a password in the value that never reaches the finding, no port, `[::1]`) and the updated `lintreport.json` golden +- [x] 5.1 Implement `LocalhostURL` in `internal/lint` (D5); verify with table tests for the spec's scenarios (an API URL, a password in the value that never reaches the finding, no port, `[::1]`) and the updated `lintreport.json` golden - [ ] 5.2 Add `LocalhostURL` and `MissingEnvFile` to the reference's lint table and explain `localhost` behind the proxy in the journey's step 3; verify the table matches the rule names in the code ## 6. The snapshot default From cf8d82fa7d65117a30e63645a7c0fd911ae47589 Mon Sep 17 00:00:00 2001 From: tweinmann Date: Thu, 29 Oct 2026 20:20:48 +0000 Subject: [PATCH 4/7] Phase 5: default snapshot, end-to-end onboarding test, v0.5 status Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 21 ++-- README.md | 27 ++++- internal/cli/lint.go | 3 +- internal/cli/seed_test.go | 58 ++++++++++ internal/cli/snapshot.go | 3 + internal/cli/snapshot_test.go | 12 ++ internal/cli/up.go | 30 +++-- internal/e2e/phase5_test.go | 111 +++++++++++++++++++ internal/git/git_test.go | 8 +- internal/snapshot/snapshot.go | 11 ++ openspec/changes/phase-5-onboarding/tasks.md | 12 +- openspec/config.yaml | 7 +- 12 files changed, 268 insertions(+), 35 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1a01618..437e36a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,14 +18,15 @@ Phase 0 approved (2026-10-28). Phase 1 (v0.1) and Phase 2 (v0.2) approved and ar (2026-10-28, `openspec/changes/archive/2026-10-28-phase-1-stacks-and-routing` and `…-phase-2-overview-and-budget`). Phase 3 (v0.3) approved and archived (2026-10-29, `…/2026-10-29-phase-3-snapshots-and-queue`). Phase 4 (v0.4) approved and archived (2026-10-29, -`…/2026-10-29-phase-4-idle-and-wake`); its spike dropped Sablier (see its design.md). siding -today: `setup [--port] [--budget] [--builds] [--idle]`, `teardown [--snapshots]`, `up [--wait] -[--force] [--seed]`, `status [--wait]`, `ps`, `logs`, `open`, `down [--volumes]`, -`snapshot save|ls|rm`, `gc`, `lint`, `ui`, `skill`; routing by host and path through -`siding-proxy`; a memory budget with a start queue and learned peaks, where idle stacks make -room (the verdict `Stopped`); build slots; `just smoke-stacks`, `just build-darwin`. Next: -Phase 5 (`phase-5-onboarding`, v0.5), starting with `/opsx:propose`; then Phase 6 -(`phase-6-remote-host`, v0.6). +`…/2026-10-29-phase-4-idle-and-wake`); its spike dropped Sablier (see its design.md). Phase 5 +(v0.5, `phase-5-onboarding`) implemented, waiting for approval. siding today: `setup [--port] +[--budget] [--builds] [--idle]`, `teardown [--snapshots]`, `up [--wait] [--force] [--seed]`, +`status [--wait]`, `ps`, `logs`, `open`, `down [--volumes]`, `snapshot save|ls|rm`, `gc`, +`lint`, `ui`, `skill [--install] [--dir]`; routing by host and path through `siding-proxy`; a +memory budget with a start queue and learned peaks, where idle stacks make room (the verdict +`Stopped`); build slots; `EnvFileMissing` for env files of the main worktree; the snapshot +`default`; `just smoke-stacks`, `just build-darwin`, `just dist` and releases on `v*` tags. +Next: Phase 6 (`phase-6-remote-host`, v0.6), starting with `/opsx:propose`. ## Working agreements @@ -93,6 +94,7 @@ requests and on `main`, all inside the devcontainer image. | `just test` | devcontainer | level-1 checks, as in CI: gofmt, vet, `go test -race`, golangci-lint, `openspec validate --all --strict` | | `just golden` | devcontainer | rewrite golden files after an intended change | | `just build` | devcontainer | build a static `bin/siding` (linux) | +| `just dist ` | devcontainer | build the release binaries (macOS and Linux, arm64 and amd64) and `SHA256SUMS` into `dist/`; CI does it on `v*` tags and publishes a GitHub Release | | `just build-darwin` | devcontainer | build `bin/siding-darwin-arm64` and `-amd64`, to try siding on the Mac against Docker Desktop (product use, not development) | | `just smoke-docker` | devcontainer | inner daemon: compose project with two services and healthchecks, `ports: !reset []`, Traefik on `siding` routing `demo.main.localhost` at `/` and `/api` | | `just smoke-stacks` | devcontainer | inner daemon: siding's own commands end to end (`internal/e2e`, build tag `docker`): setup, `up --wait`, routing, a Failed verdict with log tail, `ps`, `down`, the guard of `down --volumes`; also checks golden overrides with `docker compose config` | @@ -141,7 +143,8 @@ requests and on `main`, all inside the devcontainer image. (`volume|script|none`), `dev.siding.seed.command` (the seed command of `script`). Volume label `dev.siding.shared`. Snapshot volumes: `dev.siding.snapshot` (name), `dev.siding.snapshot-volume` (the stack's volume key), `dev.siding.snapshot-created`, plus - `dev.siding.repo` and `dev.siding.machine`. On `siding-proxy`: `dev.siding.budget` (the memory + `dev.siding.repo` and `dev.siding.machine`. The snapshot named `default` seeds a stack's + first `up` without `--seed`; `none` is not a snapshot name (`--seed none` starts empty). On `siding-proxy`: `dev.siding.budget` (the memory budget in bytes), `dev.siding.builds` (build slots), `dev.siding.idle` (the idle threshold in seconds, `0` for off) and `dev.siding.host-alias` (what `host.docker.internal` resolves to in the proxy). - Compose project `-`, host `..localhost`, proxy diff --git a/README.md b/README.md index 4c0b397..3d52053 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,10 @@ siding gives every git worktree its own Docker Compose stack, at its own `*.localhost` address, and tells you and your coding agents whether it actually runs and what it costs. -> **Pre-alpha (v0.4).** Stacks per worktree, routing through one local proxy, the verdict of +> **Pre-alpha (v0.5).** Stacks per worktree, routing through one local proxy, the verdict of > `siding status`, the overview `siding ui`, a memory budget with a queue, learned peaks and -> idle stacks that make room, snapshots and seeding, a build limit, `gc` and `lint` work; expect +> idle stacks that make room, snapshots and seeding, a build limit, `gc`, `lint` and a skill for +> coding agents work; expect > rough edges and changes before v1. The plan is in [openspec/changes/](openspec/changes) > (one change per phase), what siding does today in [openspec/specs/](openspec/specs). @@ -49,6 +50,9 @@ siding up --wait # the stack of this worktree, and its verdict ``` Fix what [`lint`](#lint-rules) reports as errors in your compose file; siding never edits it. +Take its `LocalhostURL` warnings seriously: behind the proxy, `localhost` inside a container is +that container, so services call each other by name (`http://api:3000`), and the browser uses +paths on the stack's address (`/api`) instead of a fixed `http://localhost:3000`. Label the service that is the app's root `dev.siding.route: "/"`, and give services healthchecks, so that Ready means ready ([Routing](#routing)). @@ -63,8 +67,12 @@ Commit it: a new worktree only has committed files. `--install` also prints a se `AGENTS.md` and the permissions that let the agent run `siding up`, `status`, `logs` and `ps` without asking; add them where your harness reads them. -To start new worktrees with data instead of empty, save a snapshot of a stack with test data -([Snapshots and seeding](#snapshots-and-seeding)). +To start every new worktree with data instead of empty, fill a stack with test data and save +it as the snapshot `default` ([Snapshots and seeding](#snapshots-and-seeding)): + +```sh +siding snapshot save default # every new stack of this repository starts from it +``` ### 4. Per task: a worktree and an agent @@ -181,6 +189,8 @@ siding lint # exits 1 when it finds an error; --json for a Lint | `HostPath` | warning | a bind mount of a path outside the worktree, shared by every stack | | `NetworkMode` | warning | `network_mode`: siding cannot route the service | | `NoHealthcheck` | warning | no healthcheck and no route: Ready only means it started | +| `LocalhostURL` | warning | an environment value with `localhost:` or `127.0.0.1:`: behind the proxy it reaches the service's own container; the finding names the variable, never its value | +| `MissingEnvFile` | warning | in a new worktree, an untracked env file of the main worktree that is missing ([Env files](#env-files)) | | `PublishedPort` | info | published ports, which siding resets | | `NoRoot` | info | HTTP services, but none at `/` | @@ -199,8 +209,14 @@ database is copied in a consistent state, and starts them again. Snapshots outli ```sh siding up --seed base # on the stack's first up: its volumes start as copies of "base" +siding up --seed none # start empty, even with a snapshot default ``` +The snapshot named `default` needs no flag: a stack's first `up` without `--seed` seeds from +it and says so on stderr, so an agent's first `up` in a new worktree gets the data without +knowing about snapshots. Save a newer state with `siding snapshot save default --force`; without +a snapshot `default`, a first `up` starts empty. `none` cannot be a snapshot's name. + A new worktree's stack can start with data instead of empty. On its first `up` (the project has no containers and no volumes yet), `--seed ` creates its volumes as copies of the snapshot before Compose starts it; a later `up` never seeds again. Per service, the label @@ -217,7 +233,7 @@ services: image: redis:7 labels: dev.siding.seed: none # never seeded, starts empty - # without the label, or with dev.siding.seed: volume, the volumes come from --seed + # without the label, or with dev.siding.seed: volume, the volumes come from --seed or default ``` The seed command runs with `docker compose exec` as soon as the service is ready. If it fails, @@ -367,6 +383,7 @@ on your machine and siding's tests never touch your Docker containers. | `just test` | formatting, vet, unit tests with `-race`, golangci-lint, OpenSpec validation (as in CI) | | `just golden` | rewrite golden files after an intended output change | | `just build` | build `bin/siding` | + | `just dist ` | the release binaries and `SHA256SUMS` in `dist/`, as CI builds them for a `v*` tag | | `just build-darwin` | build `bin/siding-darwin-arm64` and `-amd64`, to run siding on your Mac | | `just smoke-docker` | Compose, `ports: !reset []` and Traefik routing against the container's own daemon | | `just smoke-stacks` | siding's own commands end to end against the container's own daemon | diff --git a/internal/cli/lint.go b/internal/cli/lint.go index 3867954..080830f 100644 --- a/internal/cli/lint.go +++ b/internal/cli/lint.go @@ -4,6 +4,7 @@ import ( "context" "fmt" "path/filepath" + "slices" "strings" "github.com/spf13/cobra" @@ -46,7 +47,7 @@ file. It exits 1 when there is an error.`, if err != nil { return err } - findings := append(envFindings, lint.Check(p, project, top)...) + findings := slices.Concat(envFindings, lint.Check(p, project, top)) doc := lintDocument{header: newHeader(kindLintReport), File: path} for _, f := range findings { doc.Findings = append(doc.Findings, lintFinding(f)) diff --git a/internal/cli/seed_test.go b/internal/cli/seed_test.go index 277f0ab..59c8888 100644 --- a/internal/cli/seed_test.go +++ b/internal/cli/seed_test.go @@ -5,7 +5,9 @@ import ( "strings" "testing" + "github.com/tweinmann/siding/internal/docker" "github.com/tweinmann/siding/internal/fail" + "github.com/tweinmann/siding/internal/snapshot" ) // seedConfig is testConfig with seed labels on db (a seed command) and on a cache service @@ -119,3 +121,59 @@ func TestSeedCommandFails(t *testing.T) { } } } + +// withDefault adds the snapshot default of shop, holding data. +func withDefault(e *env) { + e.docker.volumes = append(e.docker.volumes, docker.Volume{Name: snapshot.VolumeName("shop", "default", "data"), + Labels: snapshot.Labels("shop", "default", "data", e.id().Machine, e.clock.now)}) +} + +func TestDefaultSnapshot(t *testing.T) { + t.Parallel() + + t.Run("a new worktree starts with data", func(t *testing.T) { + t.Parallel() + e := seedEnv(t) + withDefault(e) + code, _, stderr := e.run("up") + if code != exitOK || !strings.Contains(stderr, "The repository's snapshot default seeds this first up; --seed none starts empty") || + !strings.Contains(stderr, "Seeding shop-main from the snapshot default: data") { + t.Fatalf("exit %d, stderr %q", code, stderr) + } + if want := []string{"create shop-main_data", "copy siding-snap_shop_default_data shop-main_data"}; !slices.Equal(e.docker.calls, want) { + t.Errorf("docker %q, want %q", e.docker.calls, want) + } + }) + + t.Run("empty on purpose", func(t *testing.T) { + t.Parallel() + e := seedEnv(t) + withDefault(e) + code, _, stderr := e.run("up", "--seed", "none") + if code != exitOK || len(e.docker.calls) != 0 || strings.Contains(stderr, "snapshot default") { + t.Errorf("exit %d, docker %q, stderr %q", code, e.docker.calls, stderr) + } + // The seed command still runs on a first up: none only means no snapshot. + if calls := composeCalls(e); len(calls) != 2 || calls[1] != "shop-main exec -T db sh -c psql -f /seed.sql" { + t.Errorf("compose %q", calls) + } + }) + + t.Run("no default", func(t *testing.T) { + t.Parallel() + e := seedEnv(t) // base and big, no default + if code, _, stderr := e.run("up"); code != exitOK || len(e.docker.calls) != 0 || strings.Contains(stderr, "Seeding shop-main from") { + t.Errorf("exit %d, docker %q, stderr %q", code, e.docker.calls, stderr) + } + }) + + t.Run("not a first up", func(t *testing.T) { + t.Parallel() + e := seedEnv(t) + withDefault(e) + e.stackUp(e.id(), "web") + if code, _, stderr := e.run("up"); code != exitOK || len(e.docker.calls) != 0 || strings.Contains(stderr, "warning") { + t.Errorf("exit %d, docker %q, stderr %q", code, e.docker.calls, stderr) + } + }) +} diff --git a/internal/cli/snapshot.go b/internal/cli/snapshot.go index 84c3128..cab64fa 100644 --- a/internal/cli/snapshot.go +++ b/internal/cli/snapshot.go @@ -45,6 +45,9 @@ those volumes are stopped while copying, so databases are consistent, and starte return printJSON(cmd.OutOrStdout(), doc) } _, err = fmt.Fprintf(cmd.OutOrStdout(), "Saved the snapshot %s of %s: %s\n", doc.Name, doc.Repo, strings.Join(snapshotVolumeKeys(doc), ", ")) + if err == nil && doc.Name == snapshot.DefaultName { + _, err = fmt.Fprintf(cmd.OutOrStdout(), "New stacks of %s start from it on their first up, unless siding up --seed none\n", doc.Repo) + } return err }, } diff --git a/internal/cli/snapshot_test.go b/internal/cli/snapshot_test.go index 0b5df88..6364d89 100644 --- a/internal/cli/snapshot_test.go +++ b/internal/cli/snapshot_test.go @@ -24,6 +24,18 @@ func composeCalls(e *env) []string { func TestSnapshotSave(t *testing.T) { t.Parallel() + t.Run("the names none and default", func(t *testing.T) { + t.Parallel() + e := newEnv(t) + e.stackUp(e.id(), "db", "web") + if code, stdout, _ := e.run("snapshot", "save", "none", "--json"); code != exitFailed || !strings.Contains(stdout, `"code": "InvalidArguments"`) || len(e.docker.calls) != 0 { + t.Errorf("none: exit %d, docker %q\n%s", code, e.docker.calls, stdout) + } + if code, stdout, _ := e.run("snapshot", "save", "default"); code != exitOK || !strings.Contains(stdout, "New stacks of shop start from it on their first up") { + t.Errorf("default: exit %d\n%s", code, stdout) + } + }) + t.Run("save", func(t *testing.T) { t.Parallel() e := newEnv(t) diff --git a/internal/cli/up.go b/internal/cli/up.go index 048985d..176510c 100644 --- a/internal/cli/up.go +++ b/internal/cli/up.go @@ -58,7 +58,7 @@ With --wait, up ends like siding status --wait, with its verdict and exit code.` cmd.Flags().StringVar(&f.repo, "repo", "", "repository name (default: the main worktree's directory name)") cmd.Flags().StringVar(&f.agent, "agent", "", "agent name for the label dev.siding.agent (default: $SIDING_AGENT)") cmd.Flags().BoolVar(&f.force, "force", false, "start the stack even if it does not fit into the memory budget") - cmd.Flags().StringVar(&f.seed, "seed", "", "on the stack's first up, start its volumes as copies of this snapshot") + cmd.Flags().StringVar(&f.seed, "seed", "", "on the stack's first up, start its volumes as copies of this snapshot (default: the snapshot \"default\" if there is one; \"none\" to start empty)") w.register(cmd) registerJSON(cmd, &asJSON) return cmd @@ -326,10 +326,10 @@ func printStackText(cmd *cobra.Command, doc stackDocument) error { } // seedPlan validates the seed labels and plans the seeding of a first up (spec seeding); a later -// up seeds nothing. The snapshot is resolved here, before anything starts. +// up seeds nothing. The snapshot is resolved here, before anything starts: the one --seed names, +// else the repository's snapshot default if there is one; --seed none starts empty. func (a *app) seedPlan(ctx context.Context, project, repo string, p *compose.Project, seedName string, containers int, stderr io.Writer) (seed.Plan, snapshot.Snapshot, error) { - plan, err := seed.Make(p, seedName != "") - if err != nil { + if _, err := seed.Make(p, false); err != nil { return seed.Plan{}, snapshot.Snapshot{}, err } vols, err := a.opts.Docker.Volumes(ctx, map[string]string{stack.LabelProject: project}) @@ -337,22 +337,36 @@ func (a *app) seedPlan(ctx context.Context, project, repo string, p *compose.Pro return seed.Plan{}, snapshot.Snapshot{}, err } if !seed.FirstUp(containers, len(vols)) { - if seedName != "" { + if seedName != "" && seedName != seedNone { warnf(stderr, "%s already has data, so --seed %s seeds nothing; siding down --volumes removes its data", project, seedName) } return seed.Plan{}, snapshot.Snapshot{}, nil } - if seedName == "" { - return plan, snapshot.Snapshot{}, nil + if seedName == seedNone { + plan, err := seed.Make(p, false) + return plan, snapshot.Snapshot{}, err } all, err := a.snapshots(ctx, false) if err != nil { return seed.Plan{}, snapshot.Snapshot{}, err } - snap, err := snapshot.Find(all, repo, seedName) + var snap snapshot.Snapshot + if seedName == "" { + if snap, err = snapshot.Find(all, repo, snapshot.DefaultName); err != nil { + plan, err := seed.Make(p, false) // no default: start empty, as before + return plan, snapshot.Snapshot{}, err + } + _, _ = fmt.Fprintf(stderr, "The repository's snapshot %s seeds this first up; --seed none starts empty\n", snapshot.DefaultName) + } else if snap, err = snapshot.Find(all, repo, seedName); err != nil { + return seed.Plan{}, snapshot.Snapshot{}, err + } + plan, err := seed.Make(p, true) return plan, snap, err } +// seedNone is the --seed that starts a first up empty, even with a snapshot default. +const seedNone = "none" + // seedVolumes creates the planned volumes as copies of the snapshot, with the labels Compose // sets itself, so Compose adopts them (design D3). Volumes the snapshot lacks start empty. func (a *app) seedVolumes(ctx context.Context, id stack.Identity, project string, p *compose.Project, plan seed.Plan, snap snapshot.Snapshot, stderr io.Writer) error { diff --git a/internal/e2e/phase5_test.go b/internal/e2e/phase5_test.go index 4dade45..711d145 100644 --- a/internal/e2e/phase5_test.go +++ b/internal/e2e/phase5_test.go @@ -6,6 +6,7 @@ import ( "context" "os" "path/filepath" + "strings" "testing" "github.com/tweinmann/siding/internal/compose" @@ -37,3 +38,113 @@ func TestEnvFilesFromCompose(t *testing.T) { t.Errorf("env files %+v", got) } } + +// onbCompose: web reads GREETING from .env and keeps a file in its volume. +const onbCompose = `services: + web: + image: busybox:1.37.0 + command: ["sh", "-c", "mkdir -p /www && echo $$GREETING > /www/index.html && exec httpd -f -p 80 -h /www"] + environment: {GREETING: "${GREETING}"} + expose: ["80"] + labels: {dev.siding.route: "/"} + volumes: [data:/data] +volumes: + data: {} +` + +// onboarding is the user journey of phase 5: a main worktree with an untracked .env, linked +// worktrees without it, and the snapshot default. +func TestOnboarding(t *testing.T) { + m := newMachine(t) + if code, out := m.siding(t.TempDir(), "setup", "--json"); code != 0 { + t.Fatalf("setup: exit %d\n%s", code, out) + } + base := t.TempDir() + main := filepath.Join(base, "onb") + if err := os.MkdirAll(main, 0o755); err != nil { + t.Fatal(err) + } + gitIn(t, main, "init", "-q", "-b", "main") + for file, content := range map[string]string{"compose.yaml": onbCompose, ".gitignore": ".env\n"} { + if err := os.WriteFile(filepath.Join(main, file), []byte(content), 0o644); err != nil { + t.Fatal(err) + } + } + gitIn(t, main, "add", ".") + gitIn(t, main, "commit", "-q", "-m", "app") + if err := os.WriteFile(filepath.Join(main, ".env"), []byte("GREETING=hello\n"), 0o644); err != nil { + t.Fatal(err) + } + const repoFlag = "siding-test-onb" + for _, p := range []string{"siding-test-onb-main", "siding-test-onb-feature-b", "siding-test-onb-feature-c"} { + t.Cleanup(func() { run(t, "", "docker", "compose", "-p", p, "down", "-v", "--remove-orphans") }) + } + t.Cleanup(func() { run(t, "", "docker", "volume", "rm", "siding-snap_siding-test-onb_default_data") }) + + if code, out := m.siding(main, "up", "--repo", repoFlag, "--wait", "--json"); code != 0 { + t.Fatalf("up main: exit %d\n%s", code, out) + } + composeExec(t, "siding-test-onb-main", "web", "sh", "-c", "echo from-main > /data/hello") + if code, out := m.siding(main, "snapshot", "save", "default", "--json"); code != 0 { + t.Fatalf("save default: exit %d\n%s", code, out) + } + + b := filepath.Join(base, "onb-feature-b") + gitIn(t, main, "worktree", "add", "-q", "-b", "feature/b", b) + t.Run("a new worktree without .env is refused", func(t *testing.T) { + code, out := m.siding(b, "up", "--repo", repoFlag, "--json") + s := decode(t, out) + if code != 1 || s.Code != "EnvFileMissing" || !strings.Contains(out, "cp "+filepath.Join(main, ".env")+" "+filepath.Join(b, ".env")) { + t.Fatalf("exit %d\n%s", code, out) + } + if out := run(t, "", "docker", "ps", "-aq", "--filter", "label=com.docker.compose.project=siding-test-onb-feature-b"); strings.TrimSpace(out) != "" { + t.Errorf("containers started: %q", out) + } + if code, out := m.siding(b, "lint", "--json"); !strings.Contains(out, `"rule": "MissingEnvFile"`) { + t.Errorf("lint: exit %d\n%s", code, out) + } + }) + + t.Run("after the cp, it starts from the snapshot default", func(t *testing.T) { + data, err := os.ReadFile(filepath.Join(main, ".env")) + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(b, ".env"), data, 0o644); err != nil { + t.Fatal(err) + } + code, out, stderr := m.sidingFull(context.Background(), b, "up", "--repo", repoFlag, "--wait", "--json") + if code != 0 || decode(t, out).Verdict != "Ready" || !strings.Contains(stderr, "snapshot default seeds this first up") { + t.Fatalf("exit %d, stderr %q\n%s", code, stderr, out) + } + if got := composeExec(t, "siding-test-onb-feature-b", "web", "cat", "/data/hello"); got != "from-main" { + t.Errorf("seeded data %q", got) + } + if _, body, _ := get(t, "siding-test-onb.feature-b.localhost", "/"); body != "hello" { + t.Errorf("GREETING from .env: %q", body) + } + }) + + t.Run("--seed none starts empty", func(t *testing.T) { + c := filepath.Join(base, "onb-feature-c") + gitIn(t, main, "worktree", "add", "-q", "-b", "feature/c", c) + if err := os.WriteFile(filepath.Join(c, ".env"), []byte("GREETING=hi\n"), 0o644); err != nil { + t.Fatal(err) + } + if code, out := m.siding(c, "up", "--repo", repoFlag, "--seed", "none", "--wait", "--json"); code != 0 { + t.Fatalf("up: exit %d\n%s", code, out) + } + if got := composeExec(t, "siding-test-onb-feature-c", "web", "sh", "-c", "cat /data/hello 2>/dev/null || echo empty"); got != "empty" { + t.Errorf("data %q, want empty", got) + } + }) + + t.Run("skill --install", func(t *testing.T) { + if code, out := m.siding(main, "skill", "--install"); code != 0 || !strings.Contains(out, "Commit it") { + t.Fatalf("exit %d\n%s", code, out) + } + if _, err := os.Stat(filepath.Join(main, ".claude", "skills", "siding", "SKILL.md")); err != nil { + t.Error(err) + } + }) +} diff --git a/internal/git/git_test.go b/internal/git/git_test.go index 09cbc2b..dad34b0 100644 --- a/internal/git/git_test.go +++ b/internal/git/git_test.go @@ -200,8 +200,8 @@ func TestMainWorktree(t *testing.T) { if err != nil { t.Fatal(err) } - real, _ := filepath.EvalSymlinks(main) - if w.MainTop() != real || w.Linked() != tt.linked { + mainTop, _ := filepath.EvalSymlinks(main) + if w.MainTop() != mainTop || w.Linked() != tt.linked { t.Errorf("%s: main top %q, linked %v", tt.dir, w.MainTop(), w.Linked()) } } @@ -239,8 +239,8 @@ func TestTop(t *testing.T) { if err := os.MkdirAll(sub, 0o755); err != nil { t.Fatal(err) } - real, _ := filepath.EvalSymlinks(dir) - if top, err := (Client{}).Top(ctx, sub); err != nil || top != real { + want, _ := filepath.EvalSymlinks(dir) + if top, err := (Client{}).Top(ctx, sub); err != nil || top != want { t.Errorf("detached, in a subdirectory: %q, %v", top, err) } if _, err := (Client{}).Top(ctx, t.TempDir()); code(err) != fail.NotAGitRepository { diff --git a/internal/snapshot/snapshot.go b/internal/snapshot/snapshot.go index 036a9ec..f64772b 100644 --- a/internal/snapshot/snapshot.go +++ b/internal/snapshot/snapshot.go @@ -33,9 +33,20 @@ func ValidName(name string) error { if len(name) > 40 || !validName.MatchString(name) { return fail.New(fail.InvalidArguments, "snapshot name %q: use lowercase letters, digits and dashes, at most 40 characters", name) } + if name == ReservedName { + return fail.New(fail.InvalidArguments, "the snapshot name %q is reserved: --seed %s starts a stack empty", name, name). + WithHint("choose another name") + } return nil } +const ( + // DefaultName is the snapshot a first up seeds from without --seed (spec seeding). + DefaultName = "default" + // ReservedName is not a snapshot name: --seed none means no snapshot. + ReservedName = "none" +) + // VolumeName is the volume holding one volume of a snapshot. The parts are separated by "_", // which neither slugs nor snapshot names contain, so two snapshots never share a volume. func VolumeName(repo, name, key string) string { diff --git a/openspec/changes/phase-5-onboarding/tasks.md b/openspec/changes/phase-5-onboarding/tasks.md index b3ee189..9ac9545 100644 --- a/openspec/changes/phase-5-onboarding/tasks.md +++ b/openspec/changes/phase-5-onboarding/tasks.md @@ -31,19 +31,19 @@ ## 5. localhost in the environment - [x] 5.1 Implement `LocalhostURL` in `internal/lint` (D5); verify with table tests for the spec's scenarios (an API URL, a password in the value that never reaches the finding, no port, `[::1]`) and the updated `lintreport.json` golden -- [ ] 5.2 Add `LocalhostURL` and `MissingEnvFile` to the reference's lint table and explain `localhost` behind the proxy in the journey's step 3; verify the table matches the rule names in the code +- [x] 5.2 Add `LocalhostURL` and `MissingEnvFile` to the reference's lint table and explain `localhost` behind the proxy in the journey's step 3; verify the table matches the rule names in the code ## 6. The snapshot default -- [ ] 6.1 Seed a first `up` without `--seed` from the snapshot `default` and plan none for `--seed none` (D6), with the stderr line; verify with fake-based tests per scenario of `seeding` "The default snapshot" and "Seed per service" -- [ ] 6.2 Refuse `snapshot save none` and say what `default` means on `snapshot save default`; verify with fake-based tests -- [ ] 6.3 Document the snapshot `default` in the journey's step 3 and the reference's snapshots and seeding; verify the shown commands run as written in the devcontainer +- [x] 6.1 Seed a first `up` without `--seed` from the snapshot `default` and plan none for `--seed none` (D6), with the stderr line; verify with fake-based tests per scenario of `seeding` "The default snapshot" and "Seed per service" +- [x] 6.2 Refuse `snapshot save none` and say what `default` means on `snapshot save default`; verify with fake-based tests +- [x] 6.3 Document the snapshot `default` in the journey's step 3 and the reference's snapshots and seeding; verify the shown commands run as written in the devcontainer ## 7. End-to-end and integration -- [ ] 7.1 Extend `internal/e2e`: a linked worktree without `.env` refused with `EnvFileMissing`, then Ready after the hint's `cp`; a snapshot `default` seeding a new worktree's first `up`, and `--seed none` starting empty; `siding skill --install` writing into a temporary repository; verify with `just smoke-stacks` and that no `siding-test-*` object is left +- [x] 7.1 Extend `internal/e2e`: a linked worktree without `.env` refused with `EnvFileMissing`, then Ready after the hint's `cp`; a snapshot `default` seeding a new worktree's first `up`, and `--seed none` starting empty; `siding skill --install` writing into a temporary repository; verify with `just smoke-stacks` and that no `siding-test-*` object is left - [ ] 7.2 Walk the user journey on the Mac with a binary from `just dist`, following only the README's "Get started" (install, `setup`, `lint`, `skill --install`, a new worktree without `.env`, the snapshot `default`), and note every place where the README left a gap; record the result in this task -- [ ] 7.3 Update the status in CLAUDE.md, the README and `openspec/config.yaml` to v0.5, with `EnvFileMissing` in the conventions where error codes are listed; verify `just test` passes +- [x] 7.3 Update the status in CLAUDE.md, the README and `openspec/config.yaml` to v0.5, with `EnvFileMissing` in the conventions where error codes are listed; verify `just test` passes ## Workflow follow-up diff --git a/openspec/config.yaml b/openspec/config.yaml index 75f12ad..a5e1ad3 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -25,7 +25,9 @@ context: | stacks per worktree, routing through siding-proxy, the verdict of status) are done; Phase 2 (v0.2: the overview siding ui, the memory budget, gc, lint, teardown) is done; Phase 3 (v0.3: snapshots and seeding, the start queue, the build limit, learned peaks) is done; - Phase 4 (v0.4: idle stacks make room under memory pressure, the verdict `Stopped`) is done. + Phase 4 (v0.4: idle stacks make room under memory pressure, the verdict `Stopped`) is done; + Phase 5 (v0.5: releases, `siding skill --install` for any harness, `EnvFileMissing`, the lint + rule `LocalhostURL`, the snapshot `default`, a README that follows the user journey) is done. OpenSpec is the only planning source: `openspec/specs/` is what siding does today, `openspec/changes/` what it is about to do (the roadmap is the `phase--` changes), `openspec/changes/archive/` how it got here. CLAUDE.md holds the @@ -92,7 +94,8 @@ context: | `dev.siding.route` (`/`, `/`, `false`), `dev.siding.port` (the HTTP port of a service with several), `dev.siding.seed` (`volume|script|none`), `dev.siding.seed.command`. Volume label `dev.siding.shared`. Snapshot volumes: `dev.siding.snapshot`, - `dev.siding.snapshot-volume`, `dev.siding.snapshot-created`. On `siding-proxy`: + `dev.siding.snapshot-volume`, `dev.siding.snapshot-created`; the snapshot `default` seeds a + first `up` without `--seed`, and `none` is not a snapshot name. On `siding-proxy`: `dev.siding.budget` (bytes), `dev.siding.builds` (build slots), `dev.siding.idle` (idle threshold in seconds, `0` for off) and `dev.siding.host-alias` (what `host.docker.internal` resolves to). The machine and From 80cfe831b2babab849a1a91932216651bf6d5890 Mon Sep 17 00:00:00 2001 From: tweinmann Date: Thu, 29 Oct 2026 20:47:59 +0000 Subject: [PATCH 5/7] Record the Mac walk-through of phase 5 Co-Authored-By: Claude Opus 5.5 --- openspec/changes/phase-5-onboarding/tasks.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/openspec/changes/phase-5-onboarding/tasks.md b/openspec/changes/phase-5-onboarding/tasks.md index 9ac9545..180ab7d 100644 --- a/openspec/changes/phase-5-onboarding/tasks.md +++ b/openspec/changes/phase-5-onboarding/tasks.md @@ -42,7 +42,8 @@ ## 7. End-to-end and integration - [x] 7.1 Extend `internal/e2e`: a linked worktree without `.env` refused with `EnvFileMissing`, then Ready after the hint's `cp`; a snapshot `default` seeding a new worktree's first `up`, and `--seed none` starting empty; `siding skill --install` writing into a temporary repository; verify with `just smoke-stacks` and that no `siding-test-*` object is left -- [ ] 7.2 Walk the user journey on the Mac with a binary from `just dist`, following only the README's "Get started" (install, `setup`, `lint`, `skill --install`, a new worktree without `.env`, the snapshot `default`), and note every place where the README left a gap; record the result in this task +- [x] 7.2 Walk the user journey on the Mac with a binary from `just dist`, following only the README's "Get started" (install, `setup`, `lint`, `skill --install`, a new worktree without `.env`, the snapshot `default`), and note every place where the README left a gap; record the result in this task + - macOS with Docker Desktop (2026-10-29): passed without problems, following only the README's "Get started" with the `v0.5.0-rc1` binaries of `bin/mac-journey` and its demo project: install with `shasum -a 256 -c --ignore-missing`, `xattr` and `siding version`; `setup`; `lint` with `LocalhostURL` and `NoRoot`; `skill --install`; `snapshot save default`; a new worktree refused with `EnvFileMissing`, then seeded from `default`; `ps`, `ui`, `open`; `gc --dry-run`. The maintainer found no gap in the README. - [x] 7.3 Update the status in CLAUDE.md, the README and `openspec/config.yaml` to v0.5, with `EnvFileMissing` in the conventions where error codes are listed; verify `just test` passes ## Workflow follow-up From 8c59fe5b7d8b5ca236b74133a32f700f2051e643 Mon Sep 17 00:00:00 2001 From: tweinmann Date: Thu, 29 Oct 2026 20:51:08 +0000 Subject: [PATCH 6/7] Add the value proposition to the README Co-Authored-By: Claude Opus 5.5 --- README.md | 47 ++++++++++++++++++++ openspec/changes/phase-5-onboarding/tasks.md | 1 + 2 files changed, 48 insertions(+) diff --git a/README.md b/README.md index 3d52053..c8b295a 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,53 @@ and tells you and your coding agents whether it actually runs and what it costs. > rough edges and changes before v1. The plan is in [openspec/changes/](openspec/changes) > (one change per phase), what siding does today in [openspec/specs/](openspec/specs). +## Why siding + +Coding agents work best in parallel: one per task, each in its own git worktree. Writing the +code is then the easy part. What stays open is whether it runs: an agent reports "done" after +the unit tests pass, but the app, with its database, its API and its frontend, never started. +And if you start it, the worktrees get in each other's way: + +- **They collide.** Two copies of the same compose file fight over port 3000, a fixed + `container_name` or a shared volume. The agent edits the compose file to get around it, or + stops the other branch's stack. +- **"Started" is not "runs".** `docker compose up -d` returns as soon as the containers exist. + Whether the API crashed two seconds later, or listens on the wrong interface, nobody checks. +- **Nobody knows which is which.** `localhost:3000`, `localhost:3001`, `localhost:3002`: which + tab is which branch, and why does the login of one break the other's session? +- **The laptop fills up.** Five stacks at a gigabyte or two each, and the machine swaps. + +siding fixes this for apps that already run with Docker Compose, without changing them: + +- **One stack per worktree.** Your unchanged compose file runs as its own Compose project per + branch, with its own containers, volumes and network. siding adds one override that removes + published ports, so nothing collides. +- **One address per branch.** One local proxy routes `http://shop.feature-login.localhost` to + that branch's stack: a stable address, its own origin and its own cookies. +- **A verdict, not a guess.** `siding up --wait` ends with `Ready` only when every healthcheck is + healthy and every routed service answers through the proxy. Otherwise it names the service, + the reason, a hint and its last log lines, as JSON an agent acts on. A skill teaches your + agent to do exactly that before it says "done". +- **One view of everything.** `siding ps` and `siding ui` show every stack on the machine, its + address and what it costs. A memory budget queues or makes room instead of letting the + machine swap, and `siding gc` removes what is merged. + +What it looks like for an agent: + +```console +$ siding up --wait --json # abridged +{ "kind": "Status", "verdict": "Failed", + "failure": { "service": "api", "reason": "Exited", "hint": "exited with code 1; see its last log lines", + "logs": ["connecting to postgres://app:***@db/app", "cannot connect to db"] } } +``` + +The agent fixes `api`, runs it again, and reports `Ready` with +`http://shop.feature-login.localhost` for you to try. + +siding is not an agent manager, not a sandbox for the agent, not Kubernetes and not production. +It runs your stacks locally, and uninstalling it leaves plain Compose projects that keep +running. + ## Get started siding needs Docker with Compose 2.24 or later, and git. Your compose file stays as it is. The diff --git a/openspec/changes/phase-5-onboarding/tasks.md b/openspec/changes/phase-5-onboarding/tasks.md index 180ab7d..a267966 100644 --- a/openspec/changes/phase-5-onboarding/tasks.md +++ b/openspec/changes/phase-5-onboarding/tasks.md @@ -6,6 +6,7 @@ - [x] 1.2 Add `MainTop` and `Tracked` to `internal/git` (D4); verify with tests on a real repository with a linked worktree, a bare-like custom layout, and a tracked and an untracked file - [x] 1.3 Add reading the `env_file` paths from `docker compose config --no-env-resolution --format json` to `internal/compose`, with `required: false` kept; verify with a captured config and, in `just smoke-stacks`, against `docker compose config` with a missing file - [x] 1.4 Restructure the README's "Using siding" as the user journey (D8): "Get started" in the order a user walks it (install, once per machine, once per repository, per task with a worktree and an agent, keeping an eye on it, after the merge), a few commands and sentences per step with links, and "Reference" with today's sections (routing labels, verdict and exit codes, lint rules, snapshots and seeding, memory budget and idle stacks, builds, devcontainer, removing siding); verify that no content of today's README is lost and every link resolves +- [x] 1.5 Add "Why siding" before "Get started" (maintainer's request): the problem parallel agents and branches have with Compose, what siding does about it, an example verdict, and what siding is not; verify every claim matches `openspec/specs/` ## 2. Releases From 2305c83faa8f6a041b3c2666662f300ab2328278 Mon Sep 17 00:00:00 2001 From: tweinmann Date: Thu, 29 Oct 2026 20:52:47 +0000 Subject: [PATCH 7/7] Archive phase 5 and merge its specs New spec releases; agent-skill, cli-contract, compose-lint, seeding, snapshots and stack-lifecycle updated. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 3 +- .../.openspec.yaml | 0 .../2026-10-29-phase-5-onboarding}/design.md | 0 .../proposal.md | 0 .../specs/agent-skill/spec.md | 0 .../specs/cli-contract/spec.md | 0 .../specs/compose-lint/spec.md | 0 .../specs/releases/spec.md | 0 .../specs/seeding/spec.md | 0 .../specs/snapshots/spec.md | 0 .../specs/stack-lifecycle/spec.md | 0 .../2026-10-29-phase-5-onboarding}/tasks.md | 0 openspec/specs/agent-skill/spec.md | 41 +++++++++++++++++- openspec/specs/cli-contract/spec.md | 2 +- openspec/specs/compose-lint/spec.md | 27 ++++++++++++ openspec/specs/releases/spec.md | 42 +++++++++++++++++++ openspec/specs/seeding/spec.md | 28 +++++++++++-- openspec/specs/snapshots/spec.md | 10 +++++ openspec/specs/stack-lifecycle/spec.md | 22 ++++++++++ 19 files changed, 168 insertions(+), 7 deletions(-) rename openspec/changes/{phase-5-onboarding => archive/2026-10-29-phase-5-onboarding}/.openspec.yaml (100%) rename openspec/changes/{phase-5-onboarding => archive/2026-10-29-phase-5-onboarding}/design.md (100%) rename openspec/changes/{phase-5-onboarding => archive/2026-10-29-phase-5-onboarding}/proposal.md (100%) rename openspec/changes/{phase-5-onboarding => archive/2026-10-29-phase-5-onboarding}/specs/agent-skill/spec.md (100%) rename openspec/changes/{phase-5-onboarding => archive/2026-10-29-phase-5-onboarding}/specs/cli-contract/spec.md (100%) rename openspec/changes/{phase-5-onboarding => archive/2026-10-29-phase-5-onboarding}/specs/compose-lint/spec.md (100%) rename openspec/changes/{phase-5-onboarding => archive/2026-10-29-phase-5-onboarding}/specs/releases/spec.md (100%) rename openspec/changes/{phase-5-onboarding => archive/2026-10-29-phase-5-onboarding}/specs/seeding/spec.md (100%) rename openspec/changes/{phase-5-onboarding => archive/2026-10-29-phase-5-onboarding}/specs/snapshots/spec.md (100%) rename openspec/changes/{phase-5-onboarding => archive/2026-10-29-phase-5-onboarding}/specs/stack-lifecycle/spec.md (100%) rename openspec/changes/{phase-5-onboarding => archive/2026-10-29-phase-5-onboarding}/tasks.md (100%) create mode 100644 openspec/specs/releases/spec.md diff --git a/CLAUDE.md b/CLAUDE.md index 437e36a..b5ea09b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,7 +19,8 @@ Phase 0 approved (2026-10-28). Phase 1 (v0.1) and Phase 2 (v0.2) approved and ar `…-phase-2-overview-and-budget`). Phase 3 (v0.3) approved and archived (2026-10-29, `…/2026-10-29-phase-3-snapshots-and-queue`). Phase 4 (v0.4) approved and archived (2026-10-29, `…/2026-10-29-phase-4-idle-and-wake`); its spike dropped Sablier (see its design.md). Phase 5 -(v0.5, `phase-5-onboarding`) implemented, waiting for approval. siding today: `setup [--port] +(v0.5) approved and archived (2026-10-29, `…/2026-10-29-phase-5-onboarding`); its release +`v0.5.0` is tagged from `main` once phases 3 to 5 are merged. siding today: `setup [--port] [--budget] [--builds] [--idle]`, `teardown [--snapshots]`, `up [--wait] [--force] [--seed]`, `status [--wait]`, `ps`, `logs`, `open`, `down [--volumes]`, `snapshot save|ls|rm`, `gc`, `lint`, `ui`, `skill [--install] [--dir]`; routing by host and path through `siding-proxy`; a diff --git a/openspec/changes/phase-5-onboarding/.openspec.yaml b/openspec/changes/archive/2026-10-29-phase-5-onboarding/.openspec.yaml similarity index 100% rename from openspec/changes/phase-5-onboarding/.openspec.yaml rename to openspec/changes/archive/2026-10-29-phase-5-onboarding/.openspec.yaml diff --git a/openspec/changes/phase-5-onboarding/design.md b/openspec/changes/archive/2026-10-29-phase-5-onboarding/design.md similarity index 100% rename from openspec/changes/phase-5-onboarding/design.md rename to openspec/changes/archive/2026-10-29-phase-5-onboarding/design.md diff --git a/openspec/changes/phase-5-onboarding/proposal.md b/openspec/changes/archive/2026-10-29-phase-5-onboarding/proposal.md similarity index 100% rename from openspec/changes/phase-5-onboarding/proposal.md rename to openspec/changes/archive/2026-10-29-phase-5-onboarding/proposal.md diff --git a/openspec/changes/phase-5-onboarding/specs/agent-skill/spec.md b/openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/agent-skill/spec.md similarity index 100% rename from openspec/changes/phase-5-onboarding/specs/agent-skill/spec.md rename to openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/agent-skill/spec.md diff --git a/openspec/changes/phase-5-onboarding/specs/cli-contract/spec.md b/openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/cli-contract/spec.md similarity index 100% rename from openspec/changes/phase-5-onboarding/specs/cli-contract/spec.md rename to openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/cli-contract/spec.md diff --git a/openspec/changes/phase-5-onboarding/specs/compose-lint/spec.md b/openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/compose-lint/spec.md similarity index 100% rename from openspec/changes/phase-5-onboarding/specs/compose-lint/spec.md rename to openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/compose-lint/spec.md diff --git a/openspec/changes/phase-5-onboarding/specs/releases/spec.md b/openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/releases/spec.md similarity index 100% rename from openspec/changes/phase-5-onboarding/specs/releases/spec.md rename to openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/releases/spec.md diff --git a/openspec/changes/phase-5-onboarding/specs/seeding/spec.md b/openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/seeding/spec.md similarity index 100% rename from openspec/changes/phase-5-onboarding/specs/seeding/spec.md rename to openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/seeding/spec.md diff --git a/openspec/changes/phase-5-onboarding/specs/snapshots/spec.md b/openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/snapshots/spec.md similarity index 100% rename from openspec/changes/phase-5-onboarding/specs/snapshots/spec.md rename to openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/snapshots/spec.md diff --git a/openspec/changes/phase-5-onboarding/specs/stack-lifecycle/spec.md b/openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/stack-lifecycle/spec.md similarity index 100% rename from openspec/changes/phase-5-onboarding/specs/stack-lifecycle/spec.md rename to openspec/changes/archive/2026-10-29-phase-5-onboarding/specs/stack-lifecycle/spec.md diff --git a/openspec/changes/phase-5-onboarding/tasks.md b/openspec/changes/archive/2026-10-29-phase-5-onboarding/tasks.md similarity index 100% rename from openspec/changes/phase-5-onboarding/tasks.md rename to openspec/changes/archive/2026-10-29-phase-5-onboarding/tasks.md diff --git a/openspec/specs/agent-skill/spec.md b/openspec/specs/agent-skill/spec.md index 9961877..99707a4 100644 --- a/openspec/specs/agent-skill/spec.md +++ b/openspec/specs/agent-skill/spec.md @@ -7,13 +7,28 @@ and waits for the verdict instead of guessing whether its work runs. ## Requirements ### Requirement: siding skill prints the skill -`siding skill` SHALL print a Claude Code skill (`SKILL.md` with name, description and body) on -stdout and write no file. With `--json` it SHALL print a `Skill` document holding the same text. +`siding skill` SHALL print the skill (`SKILL.md` with name, description and body) on stdout and +write no file. With `--json` it SHALL print a `Skill` document holding the same text. With +`--install` it SHALL instead write the skill as `/siding/SKILL.md`, where `` is +`--dir` or else `.claude/skills` at the worktree's top, replacing an older copy, and write no +other file. #### Scenario: Install the skill - **WHEN** a user runs `mkdir -p .claude/skills/siding && siding skill > .claude/skills/siding/SKILL.md` - **THEN** the file is a valid skill named `siding`, and siding wrote nothing itself +#### Scenario: Install with --install +- **WHEN** `siding skill --install` runs in a worktree of `shop` +- **THEN** `.claude/skills/siding/SKILL.md` at the worktree's top holds the skill, and the output says to commit it so every worktree has it + +#### Scenario: Another harness +- **WHEN** `siding skill --install --dir ~/.agents/skills` runs +- **THEN** `~/.agents/skills/siding/SKILL.md` holds the skill, and nothing under `.claude` is written + +#### Scenario: JSON +- **WHEN** `siding skill --install --json` runs +- **THEN** it prints a `Skill` document with the text and the `path` it wrote + ### Requirement: What the skill teaches The skill SHALL tell the agent to run `siding up --wait --json` after a change that affects the running app, to read the verdict and exit code, to fix the named service from the failure's @@ -38,3 +53,25 @@ address without starting anything; and that only the addresses siding reports wo #### Scenario: The address - **WHEN** the printed skill is read - **THEN** it says that `siding status --json` holds the stack's `url`, and that `localhost:` from the compose file does not work under siding + +### Requirement: Snippets for the harness +`siding skill --install` SHALL print, after what it wrote, a section for `AGENTS.md` that tells +any agent to use siding as the skill does, and the permissions for siding's reading commands +(`up`, `status`, `logs`, `ps`): as a Claude Code `settings.json` entry and as a plain list for +other harnesses. siding MUST NOT write `AGENTS.md` or any settings file. + +#### Scenario: The snippets +- **WHEN** `siding skill --install` has run +- **THEN** its output holds the `AGENTS.md` section and `"Bash(siding up:*)"`, `"Bash(siding status:*)"`, `"Bash(siding logs:*)"` and `"Bash(siding ps:*)"`, and none of `down`, `gc`, `snapshot rm` or `teardown` + +#### Scenario: No settings written +- **WHEN** `siding skill --install` runs in a repository with `.claude/settings.json` +- **THEN** that file is byte for byte unchanged + +### Requirement: Harness-neutral skill +The skill's text SHALL name no harness: it addresses the agent, so that the same file works +wherever the Agent Skills format is read. + +#### Scenario: No harness named +- **WHEN** the printed skill is read +- **THEN** it does not contain "Claude Code" diff --git a/openspec/specs/cli-contract/spec.md b/openspec/specs/cli-contract/spec.md index 41bae6e..92063b1 100644 --- a/openspec/specs/cli-contract/spec.md +++ b/openspec/specs/cli-contract/spec.md @@ -46,7 +46,7 @@ it SHALL print `error: ` on stderr, followed by a hint line when there #### Scenario: The error codes - **WHEN** a command fails -- **THEN** its code is one of `InvalidArguments`, `NotAGitRepository`, `NoBranch`, `ComposeFileNotFound`, `ComposeFailed`, `DockerUnavailable`, `ProxyNotRunning`, `PortInUse`, `InvalidRoute`, `AmbiguousPort`, `SlugCollision`, `StackNotFound`, `UnmergedBranch`, `DirtyWorktree`, `NoCapacity`, `NotInteractive`, `SnapshotNotFound`, `SnapshotExists`, or `Internal` for an unexpected error +- **THEN** its code is one of `InvalidArguments`, `NotAGitRepository`, `NoBranch`, `ComposeFileNotFound`, `ComposeFailed`, `DockerUnavailable`, `ProxyNotRunning`, `PortInUse`, `InvalidRoute`, `AmbiguousPort`, `SlugCollision`, `StackNotFound`, `UnmergedBranch`, `DirtyWorktree`, `NoCapacity`, `NotInteractive`, `SnapshotNotFound`, `SnapshotExists`, `EnvFileMissing`, or `Internal` for an unexpected error #### Scenario: No capacity - **WHEN** `siding up --json` refuses because the stack does not fit into the memory budget diff --git a/openspec/specs/compose-lint/spec.md b/openspec/specs/compose-lint/spec.md index bde8b07..41d4fe0 100644 --- a/openspec/specs/compose-lint/spec.md +++ b/openspec/specs/compose-lint/spec.md @@ -56,3 +56,30 @@ no `dev.siding.route: "/"`). #### Scenario: A published database port - **WHEN** `db` publishes `5432:5432` - **THEN** lint reports `PublishedPort` as info, with the hint that siding resets it and how to reach the database + +### Requirement: Missing env files +In a linked worktree, `lint` SHALL warn `MissingEnvFile` for every file that `up` would refuse +to start without (see `stack-lifecycle`, "Env files of the main worktree"), with the `cp` +command as the hint. + +#### Scenario: .env missing +- **WHEN** `siding lint` runs in a new worktree that lacks the main worktree's untracked `.env` +- **THEN** it warns `MissingEnvFile` for `.env` with the `cp` command, and exits 0 + +### Requirement: localhost in the environment +`lint` SHALL warn `LocalhostURL` for every environment variable of a service whose value names +`localhost` or `127.0.0.1` with a port, because behind the proxy that reaches the service's own +container, not the other service or the host. The finding MUST name the service, the variable +and the host and port, and MUST NOT contain the rest of the value. + +#### Scenario: An API URL +- **WHEN** `web` has `API_URL=http://localhost:3000/v1` +- **THEN** lint warns `LocalhostURL` for `web` naming `API_URL` and `localhost:3000`, with the hint to use the service name (`http://api:3000`) between services or a path on the stack's address in the browser + +#### Scenario: A password in the value +- **WHEN** `api` has `DATABASE_URL=postgres://app:not-a-real-token@127.0.0.1:5432/app` +- **THEN** the finding names `DATABASE_URL` and `127.0.0.1:5432`, and neither the text nor the `LintReport` contains `not-a-real-token` + +#### Scenario: Without a port +- **WHEN** `web` has `COOKIE_DOMAIN=localhost` +- **THEN** lint reports nothing for it diff --git a/openspec/specs/releases/spec.md b/openspec/specs/releases/spec.md new file mode 100644 index 0000000..6125208 --- /dev/null +++ b/openspec/specs/releases/spec.md @@ -0,0 +1,42 @@ +# releases Specification + +## Purpose +Defines how siding reaches users who do not build it: static binaries per platform, published +for every version tag, with checksums and instructions to install them. + +## Requirements + +### Requirement: Distribution build +`just dist` SHALL build, in the devcontainer, static siding binaries for `darwin` and `linux` +on `arm64` and `amd64` into `dist/`, named `siding--`, with the version given to it, +and a `SHA256SUMS` file over them. + +#### Scenario: A build for a tag +- **WHEN** `just dist v0.5.0` runs in the devcontainer +- **THEN** `dist/` holds four binaries and `SHA256SUMS`, and `dist/siding-linux-arm64 version` reports `v0.5.0` + +#### Scenario: Checksums +- **WHEN** a user runs `shasum -a 256 -c SHA256SUMS` next to the downloaded binaries +- **THEN** every binary checks out + +### Requirement: Release on a tag +A pushed tag `v..` SHALL make CI run `just test`, build with `just dist` +inside the devcontainer, and publish a GitHub Release named after the tag with the four +binaries and `SHA256SUMS`. A failing check MUST publish nothing. + +#### Scenario: Tag v0.5.0 +- **WHEN** the maintainer pushes the tag `v0.5.0` +- **THEN** the release `v0.5.0` exists on GitHub with `siding-darwin-arm64`, `siding-darwin-amd64`, `siding-linux-arm64`, `siding-linux-amd64` and `SHA256SUMS` + +#### Scenario: A failing check +- **WHEN** `just test` fails for the tagged commit +- **THEN** no release is published + +### Requirement: Install instructions +The README SHALL say how to install a released binary on macOS and Linux: download it for the +platform, check it against `SHA256SUMS`, make it executable, put it on the `PATH`, and on macOS +remove the quarantine flag of a downloaded, unsigned binary. + +#### Scenario: Install on a Mac +- **WHEN** a user follows the README on an Apple silicon Mac +- **THEN** `siding version` runs and reports `darwin/arm64` and the release's version diff --git a/openspec/specs/seeding/spec.md b/openspec/specs/seeding/spec.md index 5a6f27c..a5b5a41 100644 --- a/openspec/specs/seeding/spec.md +++ b/openspec/specs/seeding/spec.md @@ -30,9 +30,9 @@ Compose adopts it. Volumes the snapshot lacks start empty. An unknown snapshot M ### Requirement: Seed per service The service label `dev.siding.seed` SHALL choose how a service's volumes are seeded: `volume` -(from the snapshot given with `--seed`; also when the label is missing), `none` (never), or -`script`. A volume used by a service with `none` MUST NOT be seeded. Another value MUST fail -`up` with `InvalidArguments`, naming the service. +(from the snapshot given with `--seed`, or the snapshot `default` without it; also when the +label is missing), `none` (never), or `script`. A volume used by a service with `none` MUST NOT +be seeded. Another value MUST fail `up` with `InvalidArguments`, naming the service. #### Scenario: none - **WHEN** `cache` carries `dev.siding.seed: none` and `up --seed base` runs first @@ -51,3 +51,25 @@ running and healthy if it has a healthcheck. Without the command label, `up` MUS #### Scenario: The command fails - **WHEN** the seed command exits with code 2 - **THEN** the verdict is `Failed` with service `db`, reason `SeedFailed`, the exit code in the hint and the command's last output lines as the log tail + +### Requirement: The default snapshot +A first `up` without `--seed` SHALL seed from the repository's snapshot named `default` when it +exists, as `--seed default` would, and say on stderr that it does. `--seed none` SHALL start the +stack empty. Without a snapshot `default`, a first `up` without `--seed` MUST start empty, as +before. + +#### Scenario: A new worktree starts with data +- **WHEN** `shop` has the snapshot `default` and an agent runs `siding up --wait --json` in a new worktree +- **THEN** the stack's volumes are copies of `default`, stderr says it seeded from `default`, and the verdict is Ready + +#### Scenario: Empty on purpose +- **WHEN** `shop` has the snapshot `default` and `siding up --seed none` runs first +- **THEN** the stack's volumes start empty + +#### Scenario: No default +- **WHEN** `shop` has the snapshot `base` but none named `default` +- **THEN** a first `up` without `--seed` starts empty + +#### Scenario: Not a first up +- **WHEN** the stack already has volumes and the snapshot `default` exists +- **THEN** `up` seeds nothing and gives no warning about it diff --git a/openspec/specs/snapshots/spec.md b/openspec/specs/snapshots/spec.md index 1e94ccf..76b38f3 100644 --- a/openspec/specs/snapshots/spec.md +++ b/openspec/specs/snapshots/spec.md @@ -23,6 +23,8 @@ while copying and start them again afterwards. ### Requirement: Snapshot names A snapshot name SHALL be unique per repository and consist of lowercase letters, digits and `-`. `save` MUST fail with `SnapshotExists` when the name is taken, unless `--force` replaces it. +The name `none` MUST be refused with `InvalidArguments`, because `--seed none` means no +snapshot; the name `default` makes the snapshot the one a first `up` seeds from. #### Scenario: Taken - **WHEN** `siding snapshot save base` runs and `base` exists for the repository @@ -32,6 +34,14 @@ A snapshot name SHALL be unique per repository and consist of lowercase letters, - **WHEN** the repositories `shop` and `blog` both save a snapshot `base` - **THEN** both exist side by side +#### Scenario: Reserved +- **WHEN** `siding snapshot save none` runs +- **THEN** it fails with `InvalidArguments` and saves nothing + +#### Scenario: Default +- **WHEN** `siding snapshot save default` runs +- **THEN** the snapshot `default` exists, and the output says that new stacks of the repository start from it + ### Requirement: List and remove `siding snapshot ls` SHALL list the snapshots of this machine, of the current repository when run in one, with name, repository, volumes, size where Docker reports it, and creation time; diff --git a/openspec/specs/stack-lifecycle/spec.md b/openspec/specs/stack-lifecycle/spec.md index 1c8f82f..0f03f05 100644 --- a/openspec/specs/stack-lifecycle/spec.md +++ b/openspec/specs/stack-lifecycle/spec.md @@ -133,3 +133,25 @@ services' `env_file`s, of 4 or more characters, replaced by `***`. #### Scenario: A password in a log line - **WHEN** `.env` sets `DB_PASSWORD=not-a-real-token` and a service logs that value - **THEN** the log line in the `Logs` and `Status` documents shows `***` instead + +### Requirement: Env files of the main worktree +In a linked worktree, `up` SHALL fail with `EnvFileMissing` before Compose runs when the +worktree lacks `.env`, or a file the compose file names in `env_file`, that the main worktree +has and git does not track. The hint MUST give the `cp` command from the main worktree. siding +MUST NOT copy the file itself. + +#### Scenario: A new worktree without .env +- **WHEN** the main worktree `/src/shop` has an untracked `.env`, and `siding up` runs in the new worktree `/src/shop-feature-x`, which has none +- **THEN** it fails with `EnvFileMissing`, the hint says `cp /src/shop/.env /src/shop-feature-x/.env`, and no container starts + +#### Scenario: An env_file +- **WHEN** `api` has `env_file: [api.env]`, the main worktree has an untracked `api.env`, and the worktree lacks it +- **THEN** `siding up` fails with `EnvFileMissing` naming `api.env` + +#### Scenario: Not needed +- **WHEN** the main worktree has no `.env`, or `.env` is tracked by git +- **THEN** `up` behaves as before + +#### Scenario: The main worktree +- **WHEN** `siding up` runs in the main worktree without `.env` +- **THEN** `up` behaves as before