@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/docs/compose-patterns.md

@@ -0,0 +1,99 @@
+# Compose patterns
+
+cockpit runs your Compose files as written, so a stub vendor, a TLS front end or a data restore is
+a few lines of plain Compose rather than a cockpit setting. Each pattern below keeps to what
+[`check`](environment.md#compose-first-stacks) expects of a Compose file: published ports come from
+a `[ports.bases]` variable and bind `127.0.0.1`, and a container gets only the bind mounts
+`cockpit.toml` declares. `check` also warns about a service with no healthcheck and an image pinned
+by tag rather than digest; pin the tags below before you rely on them. A build context is not a
+bind mount, so the patterns copy their files in with a small Dockerfile instead of mounting them.
+
+## Stub a vendor
+
+Run a local stand-in for a third-party API and point the app at it by service name:
+
+```yaml
+services:
+  api:
+    build: ${API_DIR:-./api}
+    environment:
+      PAYMENTS_URL: http://payments-stub:8080
+    depends_on:
+      payments-stub:
+        condition: service_healthy
+  payments-stub:
+    build: ./stubs/payments
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:8080/health"]
+      interval: 5s
+```
+
+`./stubs/payments` holds the stub's Dockerfile and the responses it serves. The stub publishes no
+host port, because only the app calls it. Keep the real vendor's address out of the stack, and list
+its host under `[guards] vendor_endpoint_hosts` in `cockpit.toml` so the guards keep agents away
+from it too.
+
+## Serve TLS
+
+Put a reverse proxy in front of the app when the product must run on `https`. This one uses Caddy's
+internal certificate authority, so no private key leaves the container:
+
+```yaml
+services:
+  tls:
+    image: caddy:2-alpine # pin this by digest
+    command: ["caddy", "reverse-proxy", "--from", "https://app.sample.localhost", "--to", "api:3000", "--internal-certs"]
+    ports: ["127.0.0.1:${APP_HOST_PORT:-8443}:443"]
+    volumes: ["caddy-data:/data"]
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:2019/config/"]
+      interval: 5s
+volumes:
+  caddy-data: {}
+```
+
+Declare the matching [named local URL](environment.md#named-local-urls) with
+`hostname = "app.sample.localhost"` and `scheme = "https"` on `APP_HOST_PORT`. Each client that
+connects must trust the proxy's root certificate, which Caddy keeps in the `caddy-data` volume
+under `/data/caddy/pki/authorities/local/`; copy it out with `docker compose cp` and trust only
+that public certificate. Leave `caddy-data` out of
+`resettable_volumes`, so a reset does not issue a new root that every client must trust again.
+
+## Seed or restore data
+
+For a seed that talks to the running stack, declare
+[`environment.seed`](environment.md#demo-data-test-users-and-roles): `up` runs it on the host once
+the stack is healthy and again after the data volume is recreated, with the leased ports in its
+environment. A restore is the same declaration with a script that loads a dump:
+
+```toml
+[environment]
+compose_files = ["compose.yml"]
+resettable_volumes = ["postgres-data"]
+seed = { argv = ["sh", "scripts/restore.sh"], timeout_seconds = 900 }
+```
+
+`scripts/restore.sh` connects to `127.0.0.1:$POSTGRES_HOST_PORT`, which cockpit sets from the lease,
+and loads the dump with the product's own tools. Print every table or object it could not restore
+before it exits, because a silent gap looks like a complete copy.
+
+To load data without a host command, let the database image do it on an empty volume. The official
+Postgres image runs the scripts in `/docker-entrypoint-initdb.d` only when its data directory is
+empty, which is the state `reset` leaves a resettable volume in:
+
+```yaml
+services:
+  postgres:
+    build: ./db # FROM postgres:17-alpine, then COPY init/ /docker-entrypoint-initdb.d/
+    environment:
+      POSTGRES_PASSWORD: postgres
+    volumes: ["postgres-data:/var/lib/postgresql/data"]
+    healthcheck:
+      test: ["CMD", "pg_isready", "-U", "postgres"]
+      interval: 5s
+volumes:
+  postgres-data: {}
+```
+
+Keep dumps and fixtures out of tracked files when they hold real data; build them into the image
+from an ignored directory, or have the seed command fetch them.

package/docs/concepts.md

@@ -0,0 +1,171 @@
+# Concepts
+
+This page defines the words cockpit's commands, configuration and diagnostics use. Each term has
+one meaning across the documentation, and other pages link here instead of redefining it.
+
+## Cockpit glossary
+
+Everyday terms, in plain language.
+
+### Agent harness
+
+The AI coding tool an agent runs in, such as Claude Code, Codex CLI or OpenCode. cockpit installs
+its guard hook for those; for Cursor and Grok Build, once `[surfaces] tools` lists them, it writes
+files but installs no guard, and nobody has confirmed those tools load them. The
+[capability matrix](capability-matrix.md) lists the target identifiers and what is confirmed for
+each feature; see also [Capability states](harness-surfaces.md#capability-states).
+
+### Sibling repository
+
+One of the product's Git repositories, declared in a `[[sibling]]` table. Siblings sit side by
+side under one directory, the siblings root. Each says how the stack uses the checkout (`mount`)
+and how the checkout gets onto disk (`acquire`), two deliberately independent settings
+([Architecture](architecture.md#two-axes-mount-and-acquire)).
+
+### Stack
+
+The running product: the Docker Compose project cockpit generates from the declared services,
+volumes and ports, started against the sibling checkouts on your disk.
+
+### Surface
+
+A file cockpit generates for an agent harness: the shared instructions in AGENTS.md, the Claude
+import in CLAUDE.md, skills, subagents, hooks, MCP server entries and permissions. `cockpit sync`
+renders them from templates shipped in the package.
+
+### Overlay
+
+A product-specific addition to the generated surfaces, such as an extra rule or skill; see
+[Cockpit surface overlay](#cockpit-surface-overlay).
+
+### Guard
+
+A check that runs before an agent's tool call and can deny it, for example a push to a protected
+branch, an edit to a declared environment or secret file, or a command aimed at a declared hosted
+database or vendor host. The same policy is installed as a hook in each harness that supports one.
+
+### Drift
+
+A difference between a generated file on disk and what the current configuration would generate.
+`cockpit check` reports it without changing anything. `cockpit sync` rewrites a changed generated
+artifact such as `compose.cockpit.yml`, but refuses a changed surface (a skill, agent settings or
+a cockpit-owned region) with `SURFACE_STATE_CONFLICT`, because it can no longer prove it wrote
+those bytes.
+
+### Holder
+
+A record that one checkout is using the stack. `up` adds one and `sleep` removes it; the stack stops
+only when none remain, so one agent cannot stop another's environment.
+
+### Work order
+
+A file, `workorders/<id>.md`, whose YAML front-matter is the contract for one piece of agent work: its
+objective, the paths it may change, acceptance criteria with the checks that show them, and what it
+leaves alone. cockpit records who accepted it, runs its checks, grades the result against it and
+records how it closed; the [work-order contract](https://github.com/b0dea/cockpit/blob/main/packages/cockpit/src/work-orders/contract.ts)
+holds its schema and limits.
+
+### Evaluator
+
+The grader for a finished work order under the default `independent` grading. It grades each
+acceptance criterion against the checks cockpit ran and the change since the order was accepted, in a
+fresh read-only run that never sees the session that did the work, in another listed agent tool when
+one is available, otherwise the same tool in a new run. It never edits code. A cockpit can instead let the
+checks alone decide, or let the agent report its own verdict; the record says which.
+
+### Enforced, instructed, generated and unavailable
+
+The four states of a harness feature. See
+[Cockpit harness capability state](#cockpit-harness-capability-state).
+
+## Cockpit checkout root
+
+The directory that holds <!-- cockpit:ref consumer=cockpit.toml --> `cockpit.toml`; it identifies one cockpit instance. Generated
+paths, `cockpit.siblings_root` and lifecycle commands resolve from here, even when the
+configuration sits inside a larger Git checkout, so sibling discovery and Compose paths follow
+the configuration you select with `--config`.
+
+The cockpit's runtime identity comes from the main Git checkout and the checkout identity from the
+current one, so linked worktrees share one cockpit but stay distinct checkouts. A standalone
+directory can `sync` before Git exists; `setup` and lifecycle commands need a Git checkout.
+
+## Where the cockpit lives
+
+The cockpit root is the directory that holds `cockpit.toml`, the generated instructions, the guard
+and the harness settings. There are two layouts, and `init` does not ask which to use for a single
+repository:
+
+- **In-repo** is the default for one product repository. The repository itself is the cockpit root
+  (`siblings_root = "."`, the repository is the sibling with `dir = "."`), so the cockpit files are
+  committed with the product.
+- **Dedicated** is the layout for a product made of several repositories. The root is a folder or
+  repository of its own beside them, such as `shop-cockpit`, with `siblings_root = ".."`:
+
+```text
+work/
+  shop/            product repository, first sibling (dir = "shop")
+  shop-cockpit/    cockpit root: cockpit.toml, AGENTS.md, guards, harness settings
+```
+
+A dedicated root keeps cockpit files out of the product repositories and lets one cockpit own several
+neutrally; an in-repo cockpit cannot. Pick it by answering `cockpit.root = "dedicated"` to `init` run
+from the product repository: `init` creates `../<repo>-cockpit` as a local Git repository (the one
+directory it writes outside the folder it ran in; an existing destination must be empty or a local
+Git repository with a plain `.git` directory) and declares the product repository as its first
+sibling. An empty folder or a folder of documents is itself the cockpit: `init` declares it as its
+own first sibling (`dir = "."`), and repositories are added later with
+`cockpit sibling add <slug> --create`.
+
+There is no command to move an in-repo cockpit. Do not delete the ownership manifest or the paths it
+lists by hand; create a new dedicated cockpit as a separate adoption, and remove the old one only
+once a command can preview and check that cleanup. To create one, follow
+[Getting started](getting-started.md).
+
+## Cockpit sibling declaration
+
+The `[[sibling]]` entry for one product repository: its stable slug, directory, acquisition and
+mount modes, toolchain and generated guidance. It names a repository; `setup` and `preflight`
+check that the checkout exists and matches it.
+
+## Cockpit product registry
+
+An optional, validated description of an existing product's repositories, environment, surfaces,
+guards, grading and adoption state, used as input when adopting an established setup. The
+<!-- cockpit:ref consumer=cockpit.toml --> `cockpit.toml` draft it produces still needs your review.
+
+## Cockpit lifecycle record
+
+The state cockpit keeps for one checkout and its shared runtime: which setup and bring-up stages
+completed. Later commands use it to resume safely and to tell the current state from an earlier
+attempt.
+
+## Cockpit generated ownership
+
+The record of every file and delimited region of a shared file that cockpit wrote, with
+the bytes it expects. It lets `check` detect drift and `sync` replace its own output without
+touching anything else.
+
+## Cockpit harness capability state
+
+The confirmed status of one feature for one agent harness:
+
+- `enforced`: a mechanism refuses the prohibited operation, and a dated check shows it doing so.
+- `instructed`: cockpit emits the guidance or setting, but enforcement has not been confirmed.
+- `generated`: cockpit emits the file for a harness with no guard adapter or loading test, so
+  nobody has verified that the tool even loads it.
+- `unavailable`: the harness offers no mechanism, so cockpit emits nothing and records why.
+
+Generating a file never promotes a feature to `enforced`; only a probe of the real tool does.
+
+## Cockpit surface overlay
+
+A product-specific rule, subagent, skill or hook added through `[surfaces].overlays`. It may
+replace a built-in item only with an explicit `replaces` entry naming that item's SHA-256, so a
+later change to the item is reported instead of silently overridden. It cannot replace core
+permissions or MCP approval.
+
+## Cockpit evidence boundary
+
+The line between what cockpit has checked itself and what still needs confirmation elsewhere: a
+running harness, a person, a vendor or a live runtime. A repository test proves cockpit's own
+behaviour, not that a harness loaded a generated file.

package/docs/configuration-essentials.md

@@ -0,0 +1,172 @@
+# Configuration essentials
+
+This page is for people writing or reviewing their first `cockpit.toml`. It covers the tables a
+typical cockpit sets, the ones `init` asks about and the bundled examples declare, each with a
+minimal snippet and a link to its full entry in the generated
+[configuration reference](configuration-reference.md). Everything else is optional and listed by
+area at the end.
+
+## `[cockpit]`
+
+The cockpit's name and where the product's repositories live. The name scopes the cockpit's
+Compose projects, state and generated files, so renaming it later means bringing the stack down
+and syncing again. `siblings_root` is relative to the cockpit directory and defaults to `..`.
+Full entry: [`[cockpit]`](configuration-reference.md#cockpit).
+
+```toml
+[cockpit]
+name = "shop"
+siblings_root = ".."
+```
+
+## `[[sibling]]`
+
+One table per product repository. `mount` says how the stack uses the checkout: `always`
+bind-mounts it, `profile:<name>` mounts it only under that Compose profile, `none` leaves it read
+but never mounted, and `host` runs it outside the stack for the reason given in `host_reason`.
+`acquire` says how it reaches disk: `auto` clones `remote` during `setup`, `manual` expects a
+person to clone it, and `none` never clones it, so it must already be there. The two are
+[independent](architecture.md#two-axes-mount-and-acquire). `var` carries the checkout's path and
+`toolchain` picks the install policy. `cockpit sibling add` writes these tables for you. Full
+entries: [`[[sibling]]`](configuration-reference.md#sibling) and
+[`[[sibling.environment_files]]`](configuration-reference.md#siblingenvironment_files).
+
+```toml
+[[sibling]]
+slug = "api"
+dir = "api"
+mount = "always"
+acquire = "auto"
+remote = "git@example.com:team/api.git"
+var = "API_DIR"
+toolchain = "node"
+purpose = "HTTP API for orders"
+
+[[sibling.environment_files]]
+template = ".env.example"   # tracked in the sibling
+instance = ".env"           # created from it by setup
+```
+
+## `[ports]`
+
+The base host port of every published port, by variable name. Each parallel stack publishes the
+bases plus a multiple of `step`, as
+[Local URLs and port families](environment.md#local-urls-and-port-families) explains. An empty
+`[ports.bases]` table records that nothing is published. Full entry:
+[`[ports]`](configuration-reference.md#ports).
+
+```toml
+[ports.bases]
+API_HOST_PORT = 4100
+```
+
+## `[environment]`: posture and machine floor
+
+How the product is reached and signed in to locally, and the least the container runtime must
+offer. `preflight` refuses a runtime until the posture is declared, and runtime commands refuse to
+start on a machine below the floor;
+[Declare environment postures](environment.md#declare-environment-postures) covers the tags. Full
+entries: [`[environment]`](configuration-reference.md#environment),
+[`[[environment.posture_requirements]]`](configuration-reference.md#environmentposture_requirements)
+and [`[environment.machine]`](configuration-reference.md#environmentmachine).
+
+```toml
+[environment]
+addressing = "port"
+authentication = "none"
+posture_requirements = [{ requirement = "leased-localhost-ports", addressing = "port" }]
+
+[environment.machine]
+runtime_memory_mb = 512
+runtime_cpus = 1
+free_disk_mb = 1024
+cold_start_seconds = 60
+```
+
+## The stack: `compose_files`
+
+A product that runs as a stack lists its Compose files under `[environment]`, and cockpit runs them
+as written ([Compose-first stacks](environment.md#compose-first-stacks)). A small app with no
+Compose file gets a starting one from `cockpit init --scaffold-compose`
+([Scaffold a Compose file](environment.md#scaffold-a-compose-file)). `resettable_volumes` names the
+Compose volumes `reset` may delete, and `seed` the command `up` runs to fill them
+([Demo data, test users and roles](environment.md#demo-data-test-users-and-roles)). Full entry:
+[`[environment]`](configuration-reference.md#environment).
+
+```toml
+[environment]
+compose_files = ["compose.yml"]
+resettable_volumes = ["postgres-data"]
+seed = { argv = ["npm", "run", "db:seed"], timeout_seconds = 300 }
+```
+
+## `[[environment.install_policies]]`
+
+The project build and test commands for one toolchain, selected by the lockfile a sibling
+checkout holds. `setup` needs exactly one matching row for each sibling whose `toolchain` is not
+`none`, and the guard allows the declared `build` and `test` argument vectors in that checkout.
+Full entry: the [`install_policies` shape](configuration-reference.md#environmentinstall_policies).
+
+```toml
+[[environment.install_policies]]
+toolchain = "node"
+lockfile = "package-lock.json"
+build = ["npm", "run", "build"]
+test = ["npm", "test"]
+```
+
+## `[testing]`
+
+The product's test commands as stages, grouped into a targeted gate agents run while iterating and
+a full gate they run before handing back shared changes. A stage command is an argument list run
+without a shell; [Choose the proving test tier](work-and-browser.md#choose-the-proving-test-tier)
+explains the tiers. Full entries: [`[testing]`](configuration-reference.md#testing),
+[`[[testing.stages]]`](configuration-reference.md#testingstages) and
+[`[[testing.gates]]`](configuration-reference.md#testinggates).
+
+```toml
+[testing]
+stages = [
+  { id = "changed", command = ["npx", "vitest", "run", "--changed", "origin/main"], requires_stack = false },
+  { id = "all", command = ["npx", "vitest", "run"], requires_stack = false },
+]
+gates = [
+  { id = "changed", tier = "targeted", stages = ["changed"], changes = "Isolated behaviour" },
+  { id = "all", tier = "full", stages = ["all"], changes = "Shared or cross-project behaviour" },
+]
+```
+
+## `[guards]`
+
+The database and live vendor API hosts of every non-local environment; the guard denies agent
+commands that reach them ([Safety and autonomy](safety-and-autonomy.md)). Empty lists record that
+none exists. Full entry: [`[guards]`](configuration-reference.md#guards).
+
+```toml
+[guards]
+hosted_db_hosts = ["db.prod.example.com"]
+vendor_endpoint_hosts = ["api.payments.example.com"]
+```
+
+## `unconfirmed`
+
+`init` lists each answer no person stated in `unconfirmed`, at the top of the file, and `doctor`
+warns until a person confirms each value and deletes its entry. Full entry:
+[Top-level keys](configuration-reference.md#top-level-keys).
+
+## Everything else
+
+Each optional area links to its tables in the reference and to the guide that explains it. The
+reference also lists the [defaults](configuration-reference.md#defaults) and the
+[checks beyond the schema](configuration-reference.md#checks-beyond-the-schema).
+
+| Area | Tables | Guide |
+|---|---|---|
+| Vendor stubs, TLS, restores | your Compose files | [Compose patterns](compose-patterns.md) |
+| Browser checks | [`[browser]`](configuration-reference.md#browser) | [Browser evidence](work-and-browser.md#browser-evidence) |
+| Work orders | [`[work]`](configuration-reference.md#work) | [Work and browser workflows](work-and-browser.md) |
+| Who decides | [`[autonomy]`](configuration-reference.md#autonomy) | [Who decides](safety-and-autonomy.md#who-decides) |
+| Guard rules | [`[[guards.allow]]`](configuration-reference.md#guardsallow), the `deny` row of [`[guards]`](configuration-reference.md#guards) | [Safety and autonomy](safety-and-autonomy.md) |
+| MCP approvals | [`[mcp]`](configuration-reference.md#mcp) | [MCP servers and restrictions](harness-surfaces.md#mcp-servers-and-restrictions) |
+| Surface overlays | [`[[surfaces.overlays]]`](configuration-reference.md#surfacesoverlays) | [Ownership and extension](harness-surfaces.md#ownership-and-extension) |
+| Custom harnesses | [`[[surfaces.harnesses]]`](configuration-reference.md#surfacesharnesses) | [Custom harnesses](harness-surfaces.md#custom-harnesses) |