wild-cloud/wild-pc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rename Castle -> Wild PC across the repo

Browse Source 
Repo-side rename only (Phases 1-3 of the migration plan); the live box
(~/.castle, systemd units, /data/castle, domains) is a separate cutover.

- Slug `castle` -> `wildpc`: CLI command, module names (wildpc_core/cli/api),
  dist names, entry point `wildpc = wildpc_cli.main:main`.
- Identifiers: CastleConfig/NATSClient/DirError/MDNS -> Wildpc*.
- Env/constants: CASTLE_* -> WILDPC_*; ~/.castle -> ~/.wildpc, castle.yaml ->
  wildpc.yaml, /data/castle -> /data/wildpc.
- Systemd UNIT_PREFIX castle- -> wildpc-; own programs castle-api/gateway/etc.
- Display prose "Castle" -> "Wild PC" in docs, agent-guide files, README, frontend.
- Package dirs and bootstrap yaml renamed via git mv; lockfiles regenerated;
  redundant nested uv.lock files dropped (workspace root lock is authoritative).

Tests: core 273, cli 47, wildpc-api 120 all pass. Frontend type-checks + builds.
Fixed a stale test fixture (secret_env_path kind arg) broken pre-rename.
This commit is contained in:
Paul Payne
2026-07-18 22:55:08 -07:00
parent 25d7a522cc
commit 05b28cb584
190 changed files with 2428 additions and 3337 deletions
Download Patch File Download Diff File Expand all files Collapse all files

196
AGENTS.md
View File

@@ -1,7 +1,7 @@
# AGENTS.md — Castle
# AGENTS.md — Wild PC
You are working in **Castle**, a personal software platform. Castle is a
monorepo of independent programs managed by the `castle` CLI. From this directory
You are working in **Wild PC**, a personal software platform. Wild PC is a
monorepo of independent programs managed by the `wildpc` CLI. From this directory
you can **manage all the software on this box from source** — create programs,
deploy them as services, jobs, tools, or static frontends, route them through the
gateway, expose them over TLS or a public tunnel, and coordinate across nodes.
@@ -13,7 +13,7 @@ section links to a doc under `docs/`. Read those before non-trivial changes.
## 1. Mental model — two layers
Castle splits every piece of software into **what it is** and **how it runs here**:
Wild PC splits every piece of software into **what it is** and **how it runs here**:
- **`programs/<name>.yaml`** — the software *catalog*: source, stack, build,
system dependencies. "What software exists."
@@ -32,70 +32,70 @@ stored:
| `none` | — | **reference** | an external service on another node |
A program may have **no** deployment (just source you develop), or one/more
deployments. Global settings live in **`castle.yaml`** (`gateway`, `repo`,
`agents`). Config root defaults to `~/.castle/`.
deployments. Global settings live in **`wildpc.yaml`** (`gateway`, `repo`,
`agents`). Config root defaults to `~/.wildpc/`.
**Prime directive:** regular programs must **never depend on castle**. They take
standard config (data dir, port, URLs) via **env vars**; only castle's own
programs (CLI, gateway, api) know castle internals. When you scaffold or adopt a
program, wire it with env vars — not castle imports.
**Prime directive:** regular programs must **never depend on wildpc**. They take
standard config (data dir, port, URLs) via **env vars**; only wildpc's own
programs (CLI, gateway, api) know wildpc internals. When you scaffold or adopt a
program, wire it with env vars — not wildpc imports.
→ Full reference: **`docs/registry.md`** (castle.yaml structure, every field,
→ Full reference: **`docs/registry.md`** (wildpc.yaml structure, every field,
manifest models, lifecycle). Architecture rationale: **`docs/design.md`**.
---
## 2. The `castle` CLI
## 2. The `wildpc` CLI
Resource-first: operations live under the resource they act on. Names can collide
across resource types, so the resource is explicit.
```bash
# Programs — the software catalog
castle program list [--kind service] [--stack python-cli] [--json]
castle program info <name> [--json]
castle program create <name> [--stack ...] [--description ...] # scaffold NEW code
castle program add <path|git-url> [--name ...] # adopt EXISTING repo
castle program clone [name] # provision repo: source
castle program delete <name> [--source] [-y]
castle program run <name> [args...] # declared run command
castle program build|test|lint|format|type-check|check [name] # dev verbs
wildpc program list [--kind service] [--stack python-cli] [--json]
wildpc program info <name> [--json]
wildpc program create <name> [--stack ...] [--description ...] # scaffold NEW code
wildpc program add <path|git-url> [--name ...] # adopt EXISTING repo
wildpc program clone [name] # provision repo: source
wildpc program delete <name> [--source] [-y]
wildpc program run <name> [args...] # declared run command
wildpc program build|test|lint|format|type-check|check [name] # dev verbs
# Services — daemons (manager: systemd, no schedule)
castle service list|info <name> [--json]
castle service create <name> [--program P] [--port N] [--health ...] [--launcher ...]
castle service restart <name> # imperative bounce
castle service logs <name> [-f] [-n 50]
wildpc service list|info <name> [--json]
wildpc service create <name> [--program P] [--port N] [--health ...] [--launcher ...]
wildpc service restart <name> # imperative bounce
wildpc service logs <name> [-f] [-n 50]
# Jobs — scheduled tasks (manager: systemd + schedule). create takes --schedule
castle job create <name> [--program P] --schedule "0 2 * * *" [--launcher ...]
castle job <list|info|delete|restart|logs> ...
wildpc job create <name> [--program P] --schedule "0 2 * * *" [--launcher ...]
wildpc job <list|info|delete|restart|logs> ...
# Tools — CLIs on PATH (manager: path)
castle tool list [--json] # each tool's executable + description + install state
castle tool info <name> [--json]
wildpc tool list [--json] # each tool's executable + description + install state
wildpc tool info <name> [--json]
# Secrets — read/write the ACTIVE backend (file or openbao); never hand-write the store
castle secret list # names in the active backend
castle secret set <NAME> [VALUE] # VALUE omitted → hidden prompt / stdin
castle secret get <NAME> # print a value
castle secret rm <NAME> [-y] # delete
wildpc secret list # names in the active backend
wildpc secret set <NAME> [VALUE] # VALUE omitted → hidden prompt / stdin
wildpc secret get <NAME> # print a value
wildpc secret rm <NAME> [-y] # delete
# Platform-wide
castle apply [name] [--plan] # converge runtime to config — the workhorse
castle list [--kind ...] [--stack ...] [--json] # all deployments
castle status # unified health/status
castle doctor # diagnose setup + runtime, with fix hints
castle restart [name] # imperative bounce (one or all)
castle gateway # gateway status + route table (inspection)
wildpc apply [name] [--plan] # converge runtime to config — the workhorse
wildpc list [--kind ...] [--stack ...] [--json] # all deployments
wildpc status # unified health/status
wildpc doctor # diagnose setup + runtime, with fix hints
wildpc restart [name] # imperative bounce (one or all)
wildpc gateway # gateway status + route table (inspection)
```
`castle service`/`job`/`tool` are **views** over the one deployment set, filtered
by derived kind. Lifecycle is **convergence**: edit config, then **`castle apply`**
`wildpc service`/`job`/`tool` are **views** over the one deployment set, filtered
by derived kind. Lifecycle is **convergence**: edit config, then **`wildpc apply`**
renders units + the Caddyfile and reconciles the runtime (activate what's enabled,
restart what changed, deactivate what's disabled). To durably turn a deployment
off, set `enabled: false` and apply — there is no separate start/stop/enable.
`castle restart` is the one imperative bounce.
`wildpc restart` is the one imperative bounce.
**Dev verbs resolve per-program:** a declared `commands:` entry (or `build:`)
overrides the program's stack default, else the stack handler, else the verb is
@@ -109,11 +109,11 @@ commands. All projects use **uv** (Python) / **pnpm** (frontends).
### Create a new service (HTTP daemon)
```bash
castle program create my-service --stack python-fastapi --description "Does X"
wildpc program create my-service --stack python-fastapi --description "Does X"
cd /data/repos/my-service && uv sync # implement it
castle program test my-service
castle service create my-service --program my-service --port 9001
castle apply my-service # renders the unit + gateway route and starts it
wildpc program test my-service
wildpc service create my-service --program my-service --port 9001
wildpc apply my-service # renders the unit + gateway route and starts it
```
The service reads its port/data dir from env vars that `deployments/my-service.yaml`
@@ -122,12 +122,12 @@ maps via placeholders (see §6). Stack guide: **`docs/stacks/python-fastapi.md`*
### Create a CLI tool
```bash
castle program create my-tool --stack python-cli --description "Does Y"
wildpc program create my-tool --stack python-cli --description "Does Y"
cd /data/repos/my-tool && uv sync
castle apply my-tool # installs the path deployment on PATH
wildpc apply my-tool # installs the path deployment on PATH
```
`castle tool list --json` is the machine-readable tool catalog (each tool's real
`wildpc tool list --json` is the machine-readable tool catalog (each tool's real
**executable**, which may differ from the program name). Stack:
**`docs/stacks/python-cli.md`**.
@@ -137,17 +137,17 @@ A job is a `manager: systemd` deployment with a `schedule` (cron). Generates a
`.service` (Type=oneshot) + a `.timer`.
```bash
castle job create nightly --program my-tool --schedule "0 2 * * *" --launcher command
castle apply nightly
wildpc job create nightly --program my-tool --schedule "0 2 * * *" --launcher command
wildpc apply nightly
```
### Create a static frontend
```bash
# scaffold a Vite/React app under /data/repos/my-frontend (see docs/stacks/react-vite.md)
castle program build my-frontend # produces dist/
wildpc program build my-frontend # produces dist/
# deployments/my-frontend.yaml → manager: caddy, root: dist
castle apply # served at my-frontend.<domain>
wildpc apply # served at my-frontend.<domain>
```
The gateway serves the build **in place** from `<source>/<root>` — no copy, no
@@ -158,11 +158,11 @@ Supabase substrate: **`docs/stacks/supabase.md`**.
### Adopt an existing repo (no stack needed)
```bash
castle program add ~/projects/some-rust-tool # local path
castle program add https://github.com/me/widget.git --name widget
wildpc program add ~/projects/some-rust-tool # local path
wildpc program add https://github.com/me/widget.git --name widget
```
Castle detects dev-verb commands (pyproject→uv/ruff/pytest, Cargo.toml→cargo, …)
Wild PC detects dev-verb commands (pyproject→uv/ruff/pytest, Cargo.toml→cargo, …)
or you declare them under `commands:` in `programs/<name>.yaml`.
---
@@ -191,19 +191,19 @@ public: true # ALSO expose to the internet via Cloudflare tunnel (requires pro
- There are **no path-prefix routes** — a whole subdomain maps to the backend
root, so root-relative assets and `window.location` WebSocket URLs just work.
Inspect routes: `castle gateway` / `GET /gateway`. Regenerate routes + reload the
gateway: `castle apply` (converge). → Field-level detail: **`docs/registry.md`**.
Inspect routes: `wildpc gateway` / `GET /gateway`. Regenerate routes + reload the
gateway: `wildpc apply` (converge). → Field-level detail: **`docs/registry.md`**.
---
## 5. DNS & TLS — making names resolve and be trusted
Two orthogonal questions for `https://foo.<domain>/` to work from a LAN browser:
**resolve** (DNS) and **trust** (TLS). Castle doesn't run DNS — you add one
**resolve** (DNS) and **trust** (TLS). Wild PC doesn't run DNS — you add one
**wildcard** record on the LAN's DNS server (usually the router):
`address=/<domain>/<node-ip>` (dnsmasq) pinned with a DHCP reservation.
`gateway.tls` in `castle.yaml` picks the trust mode:
`gateway.tls` in `wildpc.yaml` picks the trust mode:
| `gateway.tls` | serves | client setup | when |
|---------------|--------|--------------|------|
@@ -215,83 +215,83 @@ Two orthogonal questions for `https://foo.<domain>/` to work from a LAN browser:
the names — the public zone has no A records). HTTPS also unlocks **secure
context** (`crypto.subtle`, service workers), which plain-HTTP LAN hosts lack.
`acme` operational prerequisites (castle can't do these for you):
`acme` operational prerequisites (wildpc can't do these for you):
- **DNS-plugin Caddy** at `/usr/local/bin/caddy` — `./install.sh --with-dns-plugin=cloudflare`.
- **Provider token** stored as a secret and mapped into the gateway service env
(`CLOUDFLARE_API_TOKEN`); `castle apply` warns if missing.
(`CLOUDFLARE_API_TOKEN`); `wildpc apply` warns if missing.
- **Bind :443/:80** — lower the floor once: `net.ipv4.ip_unprivileged_port_start=80`
in `/etc/sysctl.d/` (beats `setcap`, which `NoNewPrivileges` would void).
- **Stage first**: `CASTLE_ACME_STAGING=1` at deploy, verify issuance, then unset
- **Stage first**: `WILDPC_ACME_STAGING=1` at deploy, verify issuance, then unset
and redeploy for a production cert.
→ Full conceptual + step-by-step guide: **`docs/dns-and-tls.md`**. Read the actual
values for *this* node in `~/.castle/castle.yaml` (`gateway.domain`, `tls`, etc.).
values for *this* node in `~/.wildpc/wildpc.yaml` (`gateway.domain`, `tls`, etc.).
---
## 6. Environment, secrets, data, placeholders
`defaults.env` in a deployment is the **single explicit source** of the env a
service/job runs with — castle injects nothing implicitly. Map the vars your
program reads to castle's computed values with placeholders:
service/job runs with — wildpc injects nothing implicitly. Map the vars your
program reads to wildpc's computed values with placeholders:
```yaml
expose: { http: { internal: { port: 9001 }, health_path: /health } }
defaults:
env:
MY_SERVICE_PORT: ${port} # = expose.http.internal.port
MY_SERVICE_DATA_DIR: ${data_dir} # = $CASTLE_DATA_DIR/<name>
MY_SERVICE_DATA_DIR: ${data_dir} # = $WILDPC_DATA_DIR/<name>
PUBLIC_URL: ${public_url} # gateway origin (CORS/allowlists)
API_KEY: ${secret:MY_API_KEY} # reads ~/.castle/secrets/MY_API_KEY
API_KEY: ${secret:MY_API_KEY} # reads ~/.wildpc/secrets/MY_API_KEY
```
| placeholder | expands to |
|-------------|-----------|
| `${port}` | the service's `expose.http.internal.port` |
| `${data_dir}` | `$CASTLE_DATA_DIR/<name>` (default `/data/castle/<name>`) |
| `${data_dir}` | `$WILDPC_DATA_DIR/<name>` (default `/data/wildpc/<name>`) |
| `${name}` | the deployment name |
| `${public_url}` | `https://<name>.<domain>` under acme, else `http://localhost:<port>` |
| `${secret:NAME}` | the secret `NAME` from the active backend |
**Secret backend.** `${secret:NAME}` (and `read_secret()` for direct-read code)
resolve through a backend selected by the **`secrets:` block in `castle.yaml`**
resolve through a backend selected by the **`secrets:` block in `wildpc.yaml`**
(`core/secret_backends.py`):
```yaml
secrets:
backend: openbao # or `file` (default)
addr: https://castle-openbao.<domain>:8200
mount: castle # KV-v2 mount
addr: https://wildpc-openbao.<domain>:8200
mount: wildpc # KV-v2 mount
token_secret: OPENBAO_ROOT_TOKEN # vault token, read from a file
node_prefix: nodes/<host> # optional: per-node overrides
```
- **file** (default) → `~/.castle/secrets/NAME`.
- **file** (default) → `~/.wildpc/secrets/NAME`.
- **openbao** → vault KV-v2 `mount/NAME`, no file fallback. The vault **token** is
still a file (`token_secret`, the bootstrap root of trust — it can't live in the
vault it opens). With `node_prefix`, a read tries `mount/<node_prefix>/NAME`
then shared `mount/NAME`, so one vault serves shared secrets + per-node overrides
(e.g. each node's postgres password). Env vars (`CASTLE_SECRET_BACKEND`,
`CASTLE_OPENBAO_*`) override the block (tests/CI force `file`).
(e.g. each node's postgres password). Env vars (`WILDPC_SECRET_BACKEND`,
`WILDPC_OPENBAO_*`) override the block (tests/CI force `file`).
- **This fleet runs `openbao`**: civil is the authority (root token), primer reads
via a least-privilege `castle-read` token. Only the bootstrap tier stays as
via a least-privilege `wildpc-read` token. Only the bootstrap tier stays as
files (`OPENBAO_ROOT_TOKEN`/`OPENBAO_UNSEAL_KEY`, the `cloudflared` creds dir).
**Write secrets with `castle secret set NAME`, never by hand.** It targets the
**Write secrets with `wildpc secret set NAME`, never by hand.** It targets the
*active* backend, so a value can't land in a store the resolver never reads — the
failure mode where a file-written secret is silently ignored on an openbao fleet
and `${secret:NAME}` degrades to a literal `<MISSING_SECRET:NAME>` that a service
then uses as its credential. `castle apply` **refuses to converge** (exits
then uses as its credential. `wildpc apply` **refuses to converge** (exits
non-zero, writes nothing) any deployment whose `${secret:…}` refs don't resolve in
the active backend, naming the fix.
**Never** put secret *values* in `castle.yaml` or project dirs — use `${secret:…}`.
Roots: **`CASTLE_HOME`** (config/code/artifacts/secrets, default `~/.castle`,
env-only — it *contains* castle.yaml) and **program data** (base of `${data_dir}`,
default `/data/castle`) + **repos** (default `/data/repos`). The latter two resolve
**env > `castle.yaml` > default** — set `data_dir:` / `repos_dir:` in `castle.yaml`
**Never** put secret *values* in `wildpc.yaml` or project dirs — use `${secret:…}`.
Roots: **`WILDPC_HOME`** (config/code/artifacts/secrets, default `~/.wildpc`,
env-only — it *contains* wildpc.yaml) and **program data** (base of `${data_dir}`,
default `/data/wildpc`) + **repos** (default `/data/repos`). The latter two resolve
**env > `wildpc.yaml` > default** — set `data_dir:` / `repos_dir:` in `wildpc.yaml`
(the single source of truth both the CLI and the api read), not a per-shell env var
that only one of them sees. → **`docs/registry.md`** (castle.yaml globals).
that only one of them sees. → **`docs/registry.md`** (wildpc.yaml globals).
---
@@ -299,9 +299,9 @@ that only one of them sees. → **`docs/registry.md`** (castle.yaml globals).
`public: true` (requires `proxy: true`) projects a service to the internet at
`<name>.<gateway.public_domain>` (a **separate** zone, so internal subdomain names
stay out of public DNS). `castle apply` generates the cloudflared ingress from the
stay out of public DNS). `wildpc apply` generates the cloudflared ingress from the
set of public services. Needs `gateway.public_domain` + `gateway.tunnel_id` set and
the `castle-tunnel` service running. → One-time setup: **`docs/tunnel-setup.md`**.
the `wildpc-tunnel` service running. → One-time setup: **`docs/tunnel-setup.md`**.
Routing only moves bytes — it does **not** supply a backend's own auth. Do not make
a service public unless it authenticates or is meant to be open.
@@ -310,19 +310,19 @@ a service public unless it authenticates or is meant to be open.
## 8. Mesh — multi-node coordination (opt-in)
Runs on **NATS JetStream** (`castle-nats`, TLS + token). Enable via env on
`castle-api`: `CASTLE_API_NATS_ENABLED=true`, `CASTLE_API_NATS_URL=tls://castle-nats.<domain>:4222`,
`CASTLE_API_NATS_TOKEN=${secret:NATS_TOKEN}`. Each node publishes its
Runs on **NATS JetStream** (`wildpc-nats`, TLS + token). Enable via env on
`wildpc-api`: `WILDPC_API_NATS_ENABLED=true`, `WILDPC_API_NATS_URL=tls://wildpc-nats.<domain>:4222`,
`WILDPC_API_NATS_TOKEN=${secret:NATS_TOKEN}`. Each node publishes its
(secret-stripped) registry to a JetStream **KV** bucket, renews a **presence**
key, and watches for peers; remote deployments surface as `manager: none`
**reference** kinds. A static **`role`** (`authority`|`follower`, in `castle.yaml`)
**reference** kinds. A static **`role`** (`authority`|`follower`, in `wildpc.yaml`)
gates who may write the shared-config bucket. A consumed cross-node service
(`requires: - ref: X` satisfied by a peer) is routed by the gateway with a
presence-gated circuit-breaker.
Inspect + drive from the CLI: **`castle mesh status`** / **`castle mesh nodes`** /
**`castle mesh config list|get|set`** (or `GET /mesh/status`, `/nodes`,
`/mesh/config`). Modules: `castle_api.nats_client`, `.mesh`, `.mesh_gateway`,
Inspect + drive from the CLI: **`wildpc mesh status`** / **`wildpc mesh nodes`** /
**`wildpc mesh config list|get|set`** (or `GET /mesh/status`, `/nodes`,
`/mesh/config`). Modules: `wildpc_api.nats_client`, `.mesh`, `.mesh_gateway`,
`.mdns`; secrets via `core` `secret_backends` (file default, OpenBao opt-in).
→ Full history + operations: **`docs/fleet-mesh-plan.md`**.
@@ -332,8 +332,8 @@ Inspect + drive from the CLI: **`castle mesh status`** / **`castle mesh nodes`**
| Topic | Doc |
|-------|-----|
| Registry model, `castle.yaml`, every field, lifecycle | **`docs/registry.md`** |
| Why castle is shaped this way | **`docs/design.md`** |
| Registry model, `wildpc.yaml`, every field, lifecycle | **`docs/registry.md`** |
| Why wildpc is shaped this way | **`docs/design.md`** |
| DNS resolution + the two TLS modes, acme recipe | **`docs/dns-and-tls.md`** |
| Public exposure (cloudflared) one-time setup | **`docs/tunnel-setup.md`** |
| Writing FastAPI services | **`docs/stacks/python-fastapi.md`** |
@@ -341,9 +341,9 @@ Inspect + drive from the CLI: **`castle mesh status`** / **`castle mesh nodes`**
| Writing React/Vite frontends | **`docs/stacks/react-vite.md`** |
| Writing Hugo static sites | **`docs/stacks/hugo.md`** |
| Database-backed apps (shared Supabase) | **`docs/stacks/supabase.md`** |
| **Developing Castle itself** (CLI/core/api/app, key files, endpoints) | **`docs/developing-castle.md`** |
| **Developing Wild PC itself** (CLI/core/api/app, key files, endpoints) | **`docs/developing-wildpc.md`** |
Castle's own programs live in this repo (`source: repo:<name>` → cli, core,
castle-api, app). Your programs live under `/data/repos/<name>/` with an absolute
Wild PC's own programs live in this repo (`source: repo:<name>` → cli, core,
wildpc-api, app). Your programs live under `/data/repos/<name>/` with an absolute
`source:`. When in doubt about *this* node's actual config, read
`~/.castle/castle.yaml` and `castle status`.
`~/.wildpc/wildpc.yaml` and `wildpc status`.