Manager-first deployment model: split runner, merge service/job, frontend→static

Replace the conflated `runner` axis with two orthogonal ones: `manager` (systemd|caddy|path|none) — who supervises/realizes a deployment — and, for systemd only, a nested `launcher` (python|command|container|compose|node) — how the process starts. ServiceSpec and JobSpec collapse into one manager- discriminated DeploymentSpec union (Systemd/Caddy/Path/Remote); the services/ and jobs/ config dirs collapse into one deployments/ dir. The human "kind" (service|job|tool|static|reference) is fully derived (kind_for), never stored — the frontend kind is renamed static. behavior is gone. - core: DeploymentSpec union + LaunchSpec + kind_for; legacy-aware loader normalizes old runner shapes; CastleConfig.deployments with derived services/jobs/tools views; registry.Deployment carries manager/launcher/kind. - cli: service/job/tool as filtered views + a deployment group; --behavior→--kind, create --runner→--launcher; lifecycle dispatches over config.deployments. - castle-api: /deployments primary with /services,/jobs as views; summaries derive kind; PUT/DELETE /config/deployments/{name} (services/jobs aliased). - app: KindBadge, frontend→static everywhere, pick-a-kind creation wizard, per-kind config editors. - docs: single deployments/ layout, manager/launcher, static kind throughout. Live migration verified byte-identical: regenerated Caddyfile and every unit ExecStart line unchanged, so nothing restarted. Suites: core 124, cli 25, castle-api 55; dashboard build + type-check clean.
2026-07-01 10:23:03 -07:00
parent 00e8d58c6a
commit 317232ca6a
73 changed files with 1525 additions and 1442 deletions
--- a/docs/stacks/python-cli.md
+++ b/docs/stacks/python-cli.md
@@ -318,30 +318,33 @@ uv run ruff check .         # Lint
 uv run ruff format .        # Format
 ```

-## Registering in castle.yaml
+## Registering in the registry

 ```yaml
-programs:
-  my-tool:
-    description: Does something useful
-    source: /data/repos/my-tool
-    stack: python-cli
-    behavior: tool
+# programs/my-tool.yaml
+description: Does something useful
+source: /data/repos/my-tool
+stack: python-cli
+```
+```yaml
+# deployments/my-tool.yaml (manager: path → kind: tool)
+program: my-tool
+manager: path
 ```

 Tools with system dependencies declare them directly on the program:

 ```yaml
-programs:
-  pdf2md:
-    description: Convert PDF files to Markdown
-    source: /data/repos/pdf2md
-    stack: python-cli
-    behavior: tool
-    system_dependencies: [pandoc, poppler-utils]
+# programs/pdf2md.yaml
+description: Convert PDF files to Markdown
+source: /data/repos/pdf2md
+stack: python-cli
+system_dependencies: [pandoc, poppler-utils]
 ```

-Tools live in the `programs:` section. If a tool also runs on a schedule,
-add a separate entry in the `jobs:` section referencing the program.
+A tool is a `programs/<name>.yaml` entry plus a `deployments/<name>.yaml` with
+`manager: path` (derived **kind: tool**). If a tool also runs on a schedule, add
+a *second* deployment with `manager: systemd` + `schedule` (derived **kind:
+job**) referencing the same program.

 See @docs/registry.md for the full registry reference.
--- a/docs/stacks/python-fastapi.md
+++ b/docs/stacks/python-fastapi.md
@@ -103,42 +103,42 @@ class Settings(BaseSettings):
 settings = Settings()
 ```

-Castle passes config via env vars in castle.yaml:
+Castle passes config via env vars in the deployment's `defaults.env`:

 ```yaml
-programs:
-  my-service:
-    description: Does something useful
-    source: /data/repos/my-service
-    stack: python-fastapi
-    behavior: daemon
-
-services:
-  my-service:
-    program: my-service
-    run:
-      runner: python
-      program: my-service
-    expose:
-      http:
-        internal: { port: 9001 }
-        health_path: /health
-    proxy: true   # expose at my-service.<gateway.domain>
-    manage:
-      systemd: {}
+# programs/my-service.yaml
+description: Does something useful
+source: /data/repos/my-service
+stack: python-fastapi
+```
+```yaml
+# deployments/my-service.yaml (manager: systemd → kind: service)
+program: my-service
+manager: systemd
+run:
+  launcher: python
+  program: my-service
+expose:
+  http:
+    internal: { port: 9001 }
+    health_path: /health
+proxy: true   # expose at my-service.<gateway.domain>
+manage:
+  systemd: {}
 ```

 The env a service runs with is exactly what's in `defaults.env` — castle injects
 nothing implicitly. Map the vars your settings read (above, `env_prefix:
 "MY_SERVICE_"` → `MY_SERVICE_PORT`/`MY_SERVICE_DATA_DIR`) to castle's computed
-values with the `${port}`/`${data_dir}` placeholders:
+values with the `${port}`/`${data_dir}` placeholders — add to
+`deployments/my-service.yaml`:

 ```yaml
-    defaults:
-      env:
-        MY_SERVICE_PORT: ${port}            # = expose.http.internal.port
-        MY_SERVICE_DATA_DIR: ${data_dir}    # = $CASTLE_DATA_DIR/my-service
-        CENTRAL_CONTEXT_URL: http://localhost:9001
+defaults:
+  env:
+    MY_SERVICE_PORT: ${port}            # = expose.http.internal.port
+    MY_SERVICE_DATA_DIR: ${data_dir}    # = $CASTLE_DATA_DIR/my-service
+    CENTRAL_CONTEXT_URL: http://localhost:9001
 ```

 `castle program create` scaffolds the `${port}`/`${data_dir}` lines for you.
--- a/docs/stacks/react-vite.md
+++ b/docs/stacks/react-vite.md
@@ -123,41 +123,47 @@ The `build` output is a static SPA in `dist/` — just HTML, JS, and CSS files.

 ## Registering as a program

-A frontend program has a `build` spec (produces static output). Register it
-in the `programs:` section of `castle.yaml`. No `run` block needed if Caddy
-handles serving directly from the build output.
+A frontend program has a `build` spec (produces static output). Register it in
+`programs/<name>.yaml`, plus a `deployments/<name>.yaml` with `manager: caddy`
+(derived **kind: static**) that names the built directory in `root:` — no `run`
+block, since Caddy serves the build output directly.

 ```yaml
-# castle.yaml
-programs:
-  my-frontend:
-    description: Web dashboard
-    source: /data/repos/my-frontend
-    build:
-      commands:
-        - ["pnpm", "build"]
-      outputs:
-        - dist/
+# programs/my-frontend.yaml
+description: Web dashboard
+source: /data/repos/my-frontend
+build:
+  commands:
+    - ["pnpm", "build"]
+  outputs:
+    - dist/
+```
+```yaml
+# deployments/my-frontend.yaml (manager: caddy → kind: static)
+program: my-frontend
+manager: caddy
+root: dist    # served at my-frontend.<gateway.domain>
 ```

 For production, Caddy serves the build output **in place** from the program's
-repo (`<source>/<build.outputs[0]>`) — no Node process and no copy into a
-central directory. See [Serving with Caddy](#serving-with-caddy) below.
+repo (`<source>/<root>`) — no Node process and no copy into a central directory.
+See [Serving with Caddy](#serving-with-caddy) below.

-For development with Vite's dev server, add a service entry:
+For development with Vite's dev server, use a `manager: systemd` deployment with
+the `node` launcher instead:

 ```yaml
-services:
-  my-frontend:
-    program: my-frontend
-    run:
-      runner: node
-      script: dev
-      package_manager: pnpm
-    expose:
-      http:
-        internal: { port: 5173 }
-    proxy: true   # expose the dev server at my-frontend.<gateway.domain>
+# deployments/my-frontend.yaml (dev — manager: systemd, node launcher → kind: service)
+program: my-frontend
+manager: systemd
+run:
+  launcher: node
+  script: dev
+  package_manager: pnpm
+expose:
+  http:
+    internal: { port: 5173 }
+proxy: true   # expose the dev server at my-frontend.<gateway.domain>
 ```

 See @docs/registry.md for the full registry reference.
@@ -170,10 +176,10 @@ The flow:

 1. You build the frontend with `castle program build <name>` (deploy does **not**
   build — it only points Caddy at `dist/`).
-2. The Caddyfile generator emits a route per `behavior: frontend` program that
-   has `build.outputs`, rooted **in place** at `<source>/<build.outputs[0]>` —
-   no copy. Each frontend is served at its own subdomain `<name>.<gateway.domain>`
-   (the dashboard, `castle`, is also the target of the `:9000` redirect).
+2. The Caddyfile generator emits a route per `manager: caddy` deployment (kind
+   **static**), rooted **in place** at `<source>/<root>` — no copy. Each static
+   frontend is served at its own subdomain `<name>.<gateway.domain>` (the
+   dashboard, `castle`, is also the target of the `:9000` redirect).

 The build is run with `VITE_BASE=/`, so a `vite.config` that reads it (see
 [Vite config](#vite-config)) emits root-relative asset URLs. The generated block
--- a/docs/stacks/supabase.md
+++ b/docs/stacks/supabase.md
@@ -4,7 +4,7 @@
 > web apps.** A stack is a template + conventions, not a runtime requirement.
 > `castle program create --stack supabase` scaffolds from it and seeds the
 > program's default dev-verb commands. See @docs/registry.md for `commands:`,
-> `stack:` (optional), and `behavior:`.
+> `stack:` (optional), and the deployment `manager` (and derived `kind`).

 How to build tiny, database-backed web apps as castle programs that target a
 **shared Supabase substrate**. This is Castle's "a stack whose default is a
@@ -17,7 +17,8 @@ Unlike the other stacks (which scaffold a self-contained process), a supabase ap
 is **code + migrations that deploy against a shared backend**:

 - **The substrate** is one castle service (`supabase`, the `supabase-substrate`
-  repo) running self-hosted Supabase via the `compose` runner. It is shared by
+  repo) running self-hosted Supabase via a `manager: systemd` deployment with the
+  `compose` launcher. It is shared by
  every supabase app. Stand it up once (see that repo's README).
 - **Each app** is a directory of `migrations/` + `functions/` + `public/` that
  deploys onto the substrate. Its rows/blobs live on the substrate; everything
@@ -55,7 +56,8 @@ my-app/
 └── CLAUDE.md
 ```

-Registered as a `behavior: frontend` program with `build.outputs: [public]`, so the
+Registered as a program with `build.outputs: [public]` plus a `manager: caddy`
+deployment (`root: public`, derived **kind: static**), so the
 gateway serves `public/` in place at `/my-app/` — no service, no process.

 ## supabase.app.yaml
@@ -117,8 +119,9 @@ the function holds credentials and can meter usage.

 ## Gateway & secure context

-A supabase app is a `frontend` program (its `public/` is served in place), so the
-gateway serves it at its own subdomain `<name>.<gateway.domain>`. With
+A supabase app is a static deployment (`manager: caddy`; its `public/` is served
+in place), so the gateway serves it at its own subdomain
+`<name>.<gateway.domain>`. With
 `gateway.tls: acme` that subdomain is HTTPS — a **secure context**, which apps
 using **auth or WebCrypto** require — with no private CA to install. (The substrate
 service itself is likewise at `supabase.<gateway.domain>`.) See
@@ -139,6 +142,6 @@ castle deploy && castle gateway reload    # serve the static UI at /my-app/
 registers the program as a static frontend. Set the anon key in `public/config.js`
 (`cat ~/.castle/secrets/SUPABASE_ANON_KEY`), edit your migrations, and build.

-See @docs/registry.md for the `compose` runner, the substrate service definition,
+See @docs/registry.md for the `compose` launcher, the substrate deployment definition,
 and the full registry reference. The substrate itself lives in the
 `supabase-substrate` repo (vendored, pinned self-hosted Supabase).