refactor: Align vocabulary — component → program / deployment
Canonical terms (see docs/registry.md glossary): - program: any catalog entry (tool/daemon/frontend) — the software - service / job: how a program is deployed (systemd .service / .timer) - deployment: umbrella for the unified service+job+program view Changes: - core: ServiceSpec/JobSpec component: → program: (component accepted as back-compat validation_alias); DeployedComponent → Deployment. - api: ComponentSummary/Detail → DeploymentSummary/Detail; GET /components → /deployments; GatewayRoute.component → program; GatewayInfo .component_count → deployment_count; ServiceActionResponse/action keys component → program. - app: matching type renames, /components → /deployments hook, route /component/:name → /deployment/:name, GatewayRoute.program. - docs: component-registry.md → registry.md (+ canonical glossary); CLAUDE.md endpoint list refreshed (drop removed /tools, add typed program/service/job + config routes). Tests: core 92, cli 24, api 52 green; app build clean; ruff clean.
This commit is contained in:
@@ -4,6 +4,33 @@ How castle tracks, configures, and manages programs, services, and jobs.
|
||||
This is the central reference for `castle.yaml` structure and the registry
|
||||
architecture.
|
||||
|
||||
## Vocabulary (canonical)
|
||||
|
||||
Use these terms consistently across code, CLI, API, and docs.
|
||||
|
||||
- **program** — any project castle manages, regardless of what it does. The
|
||||
software catalog (`programs:`). Every program has a **behavior** and an
|
||||
optional **stack**. *("component" was the old name for program — don't use it.)*
|
||||
- **behavior** — what a program *is*: `tool` (a CLI you invoke), `daemon` (a
|
||||
long-running server), `frontend` (a web UI). A property of the program,
|
||||
independent of whether/how it's deployed.
|
||||
- **stack** — a creation-time toolchain + scaffold template (`python-cli`,
|
||||
`python-fastapi`, `react-vite`). Optional; seeds a program's default dev
|
||||
commands but isn't required at runtime.
|
||||
- **service** — a program deployed as a long-running systemd `.service`
|
||||
(`services:`).
|
||||
- **job** — a program deployed as a scheduled systemd `.timer` (+ oneshot)
|
||||
(`jobs:`).
|
||||
- **deployment** — the umbrella for "a service or a job" (a program materialized
|
||||
into the runtime). The registry's deployed entries are deployments.
|
||||
|
||||
**Two orthogonal axes.** *behavior* (tool/daemon/frontend) is **what** a program
|
||||
is; *service/job* is **how/when** it's deployed. They're independent: a program
|
||||
may have neither (a tool you just install), a **service** (always-on), or a
|
||||
**job** (scheduled). A `daemon`-behavior program is usually deployed as a
|
||||
service; a `tool`-behavior program may back a job or just be installed for
|
||||
manual use.
|
||||
|
||||
## castle.yaml
|
||||
|
||||
The single source of truth. Lives at `~/.castle/castle.yaml`. Three top-level
|
||||
@@ -4,7 +4,7 @@
|
||||
> A stack is a template + conventions, not a runtime requirement. `castle create
|
||||
> --stack python-cli` scaffolds from it and seeds the program's default dev-verb
|
||||
> commands. An existing CLI adopted with `castle add` doesn't need this stack — it
|
||||
> declares its own `commands:`. See @docs/component-registry.md for `commands:`,
|
||||
> declares its own `commands:`. See @docs/registry.md for `commands:`,
|
||||
> `stack:` (optional), and `repo:`.
|
||||
|
||||
How to build CLI tools following Unix philosophy.
|
||||
@@ -344,4 +344,4 @@ programs:
|
||||
Tools live in the `programs:` section. If a tool also runs on a schedule,
|
||||
add a separate entry in the `jobs:` section referencing the component.
|
||||
|
||||
See @docs/component-registry.md for the full registry reference.
|
||||
See @docs/registry.md for the full registry reference.
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
> A stack is a template + conventions, not a runtime requirement. `castle create
|
||||
> --stack python-fastapi` scaffolds from it and seeds the program's default
|
||||
> dev-verb commands. An existing service adopted with `castle add` doesn't need
|
||||
> this stack — it declares its own `commands:`. See @docs/component-registry.md
|
||||
> this stack — it declares its own `commands:`. See @docs/registry.md
|
||||
> for `commands:`, `stack:` (optional), and `repo:`.
|
||||
|
||||
How to build Python web APIs as castle service components. Based on the
|
||||
@@ -448,5 +448,5 @@ uv run ruff format . # Format
|
||||
castle create my-service --stack python-fastapi --description "Does something useful"
|
||||
```
|
||||
|
||||
See @docs/component-registry.md for manifest fields, castle.yaml structure,
|
||||
See @docs/registry.md for manifest fields, castle.yaml structure,
|
||||
and the full service lifecycle (enable, logs, gateway reload).
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
> A stack is a template + conventions, not a runtime requirement. `castle create
|
||||
> --stack react-vite` scaffolds from it and seeds the program's default dev-verb
|
||||
> commands. An existing frontend adopted with `castle add` doesn't need this
|
||||
> stack — it declares its own `commands:`. See @docs/component-registry.md for
|
||||
> stack — it declares its own `commands:`. See @docs/registry.md for
|
||||
> `commands:`, `stack:` (optional), and `repo:`.
|
||||
|
||||
How to build, serve, and manage web frontends as castle components.
|
||||
@@ -152,7 +152,7 @@ services:
|
||||
caddy: { path_prefix: /app }
|
||||
```
|
||||
|
||||
See @docs/component-registry.md for the full registry reference.
|
||||
See @docs/registry.md for the full registry reference.
|
||||
|
||||
## Serving with Caddy
|
||||
|
||||
|
||||
Reference in New Issue
Block a user