bvandeusenandClaude Opus 5.5
a07547447f
The forge repo is now bvandeusen/FabledGrimoire. The plugin marketplace default, the install commands in the docs and plugin README, the CI requirements title and the example repo URLs in comments and tests follow it. docs/development.md now names the image the build actually publishes, fabledgrimoire. Two test names still said "scribes_own"; they now say "grimoires_own". What still says scribe does so on purpose: - the backup reader's accepted archive names and prefix; - the label every stored secret is sealed under; - the notes on keeping an old install's database names; - the old migrations. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.2 KiB
Development
Running it
docker compose up --build # app + PostgreSQL at http://localhost:5000
docker compose up --build app # rebuild after a change
docker compose down -v # stop and wipe the database
The image builds the frontend, so a frontend change needs a rebuild too. For quicker frontend work, run Vite against the running app; it proxies /api to port 5000:
cd frontend && npm ci && npm run dev # http://localhost:5173
Checks
CI runs these on every push; locally they need uv sync --extra dev and cd frontend && npm ci.
make lint # ruff check src/
make typecheck # vue-tsc --noEmit
make test # pytest tests/
make check # all three
Unit tests run without a database. Tests marked integration need a real PostgreSQL and run in CI's integration job, against a schema built by the real migrations.
Database migrations
The container runs alembic upgrade head on every start, after waiting for the database to accept connections.
docker compose exec app alembic revision -m "short_description"
- Number revisions sequentially (
0123_...). Revision ids must fit in 32 characters, the width ofalembic_version.version_num. - Write both
upgrade()anddowngrade(). - Adding a value to a
CHECK-constrained column means dropping and re-adding the constraint in the same migration. - Keep migrations to schema changes. Filling a derived table from a large one belongs in a background backfill after startup, where its cost doesn't hold up the boot.
- A migration that depends on application code (a key derivation, a serialiser) copies what it needs rather than importing it, so a later edit can't change what an old migration does.
The plugin
plugin/ ships straight from git: installs fetch it through .claude-plugin/marketplace.json, and there is no build step. After changing anything under plugin/ or .claude-plugin/, run make mint-plugin before committing. Claude Code only refreshes an installed plugin when its version changes, and CI fails a plugin change that didn't bump it.
The hooks must run on a bare machine: POSIX shell, awk, sed and the usual coreutils, plus git and curl. They fail open, so a slow or unreachable Grimoire never blocks Claude Code.
CI and releases
CI runs on Gitea Actions (workflow in .forgejo/workflows/ci.yml) in the shared ci-python:3.14 image (ci-requirements.md lists what it relies on). Six jobs: TypeScript typecheck, plugin hooks, Python lint (plus design-token and dangling-style checks), unit tests, integration tests, and the image build, which waits on all of them except the plugin job.
| Push | Image tags |
|---|---|
dev |
:dev, :<sha> |
main |
:latest, :<sha> |
a v* tag |
:latest, :<version>, :<sha> |
:<sha> never moves, so it is the rollback point. Images publish to git.fabledsword.com/bvandeusen/fabledgrimoire, with a registry layer cache at :cache. The build needs the REGISTRY_USER and REGISTRY_TOKEN (a token with write:packages) repository secrets.
Work happens on dev. A release merges dev into main with a plain merge commit; a dated vYYYY.MM.DD.HHMM tag, matching the version the image reports, can mark it.
Conventions
Backend
- Services open their own session:
async with async_session() as session:(fromgrimoire.models). - Routes and MCP tools stay thin; the logic lives in
services/, shared by both. - Access checks go through
services/access.py, never inline ownership checks. - Every wait on something outside the process has a deadline.
Frontend
- API calls go through the typed helpers in
frontend/src/api/client.ts. - Pinia stores for shared state,
ref()for state local to a component; composables for reusable behaviour. - Colours, spacing and type come from the design system's tokens in
theme.css, which is generated, so CI rejects an unknownvar().
Commits
type(scope): what the change does
Why, and anything a reader tracing this change later needs.
Types: feat, fix, refactor, docs, chore, test. Comments in the code describe how it works today; the history of a change belongs in its commit message.