wild-pc/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

Castle is a personal software platform — a monorepo of independent projects (services, tools, libraries) managed by the castle CLI. Components declare what they do (expose HTTP, manage via systemd, install to PATH) and roles are derived, not labeled.

Key principle: Regular projects must never depend on castle. They accept standard configuration (data dir, port, URLs) via env vars. Only castle-components (CLI, gateway, event bus) know about castle internals.

Creating Components

When creating a new service, tool, or frontend, follow the detailed guides:

• @docs/component-registry.md — Manifest architecture, castle.yaml structure, role derivation, lifecycle
• @docs/web-apis.md — FastAPI service patterns (config, routes, models, testing)
• @docs/python-tools.md — CLI tool patterns (argparse, stdin/stdout, piping, testing)
• @docs/web-frontends.md — React/Vite/TypeScript frontend patterns

Quick start

# Service
castle create my-service --type service --description "Does something"
cd my-service && uv sync
uv run my-service               # starts on auto-assigned port
castle service enable my-service # register with systemd
castle gateway reload            # update reverse proxy routes

# Standalone tool
castle create my-tool --type tool --description "Does something"
cd my-tool && uv sync

# Category tool (adds to existing tools/<category>/ package)
castle create my-tool --type tool --category document --description "Does something"
cd tools/document && uv sync

The castle create command scaffolds the project, generates a CLAUDE.md, and registers it in castle.yaml as a ComponentManifest.

Castle CLI

The CLI lives in cli/ and is installed via uv tool install --editable cli/.

castle list                              # List all components
castle list --role service               # Filter by derived role
castle info <component>                  # Show manifest details (--json for machine-readable)
castle create <name> --type service      # Scaffold new project
castle test [project]                    # Run tests (one or all)
castle lint [project]                    # Run linter (one or all)
castle sync                              # Update submodules + uv sync all
castle run <component>                   # Run component in foreground
castle logs <component> [-f] [-n 50]     # View component logs
castle tool list                         # List tools grouped by category
castle tool info <name>                  # Show tool details + docs
castle gateway start|stop|reload|status  # Manage Caddy reverse proxy
castle service enable|disable <name>     # Manage individual systemd service
castle service status                    # Show all service statuses
castle services start|stop               # Start/stop everything

Infrastructure

• Gateway: Caddy reverse proxy at port 9000, config generated from castle.yaml into ~/.castle/generated/Caddyfile. Dashboard served at root.
• Systemd: User units generated under ~/.config/systemd/user/castle-*.service
• Data: Service data lives in /data/castle/<service-name>/, passed via env var.
• Secrets: ~/.castle/secrets/ — never in project directories.

Per-Project Commands

All projects use uv. Commands run from each project's directory:

uv sync                     # Install deps
uv run pytest tests/ -v     # Run tests
uv run ruff check .         # Lint
uv run ruff format .        # Format

Services also support: uv run <service-name> to start.

Code Style

• Linting/formatting: ruff — shared ruff.toml at repo root (100-char lines)
• Type checking: pyright — shared pyrightconfig.json at repo root
• Testing: pytest, pytest-asyncio for async tests
• Python: 3.13 for services, 3.11+ minimum for tools/libraries

Key Files

• castle.yaml — Component registry (single source of truth)
• cli/src/castle_cli/manifest.py — Pydantic models (ComponentManifest, RunSpec, etc.)
• cli/src/castle_cli/config.py — Config loader (castle.yaml → CastleConfig)
• cli/src/castle_cli/templates/scaffold.py — Project scaffolding templates
• cli/src/castle_cli/commands/service.py — Systemd unit generation
• ruff.toml / pyrightconfig.json — Shared lint/type config