feat: krater v1 with proposal review, weave sign-in, skypilot budgets, slack and gallery

.dockerignore

@@ -0,0 +1,18 @@
+# Keep the host's virtualenv out of the build context: `COPY . .` would otherwise merge it into the image's
+# own /app/.venv (on Windows that overwrites its pyvenv.cfg with a C:\ interpreter path).
+.venv/
+venv/
+# Never bake local env files (live secrets) into an image.
+.env
+.env.*
+!.env.example
+.weave_e2e_fixture.json
+.git/
+**/__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.log
+backups/

.env.example

@@ -0,0 +1,86 @@
+# Copy to `.env` and adjust (or keep it outside the repo and set KRATER_ENV_FILE; see docs/dev/staging.md
+# section 4). See krater/config.py for the full list of settings.
+
+KRATER_ENV=development
+# In docker-compose, the db host is the `db` service; for `bin/dev` locally, use localhost.
+KRATER_DATABASE_URL=postgresql+psycopg://krater:krater@db:5432/krater
+# Generate a real one for anything beyond local dev:
+#   python -c "import secrets; print(secrets.token_urlsafe(48))"
+# Production refuses short keys and anything containing "change-me".
+KRATER_SECRET_KEY=change-me-in-production
+KRATER_BASE_URL=http://localhost:8000
+
+# Weave (Patchwork Labs identity provider). Weave signs people in and owns their Krater roles. Krater asks
+# for the scopes `openid profile email groups roles slack`, and uses a client_credentials token (scope
+# `directory`) of the same app for the directory API. See docs/weave-integration.md.
+# `stub` replaces Weave with a local fixture of fake users; required outside of production.
+KRATER_WEAVE_MODE=stub
+KRATER_WEAVE_ISSUER=
+KRATER_WEAVE_CLIENT_ID=
+KRATER_WEAVE_CLIENT_SECRET=
+# Base URL of Weave's directory API. Leave blank to use KRATER_WEAVE_ISSUER.
+KRATER_WEAVE_API_BASE_URL=
+KRATER_WEAVE_STUB_USERS_FILE=
+
+# Krater's role keys on its Weave app, and the group slugs Krater falls back to when Weave sends no
+# `roles` field at all. The defaults match the Weave setup in docs/weave-integration.md.
+# KRATER_WEAVE_ROLE_MEMBER=member
+# KRATER_WEAVE_ROLE_REVIEWER=reviewer
+# KRATER_WEAVE_ROLE_ADMIN=admin
+# KRATER_WEAVE_GROUP_MEMBER=ganymede-members
+# KRATER_WEAVE_GROUP_REVIEWER=krater-reviewers
+# KRATER_WEAVE_GROUP_ADMIN=krater-admins
+
+# Which compute layer launches members' machines: `vast` (Krater Compute, docs/compute/) or `off`. Off by default.
+KRATER_COMPUTE_MODE=off
+
+
+# Slack integration (review happens in Slack). See docs/SPEC.md "Slack integration" and
+# docs/dev/slack-setup.md. `fake` = in-memory Slack for local dev/tests; required outside of production.
+KRATER_SLACK_MODE=fake
+# Bot token (`xoxb-...`) for Krater's own Slack app -- see docs/dev/slack-setup.md for the required scopes.
+KRATER_SLACK_BOT_TOKEN=
+# Signing secret from the app's "Basic Information" page, used to verify requests to /slack/interactions.
+KRATER_SLACK_SIGNING_SECRET=
+# The master feed channel's id (e.g. `C0123456789`), for the one-line post on each new proposal.
+KRATER_SLACK_FEED_CHANNEL_ID=
+# How often the worker invites new reviewers (anyone granted ganymede:reviewer in Krater), posts missed
+# budget warnings, and archives channels of projects that were missed.
+KRATER_SLACK_RECONCILE_INTERVAL_MINUTES=10
+
+# S3-compatible object storage for gallery screenshots. See docs/dev/storage.md.
+# docker-compose runs a temporary SeaweedFS container as `storage`. The app talks to it on the internal endpoint;
+# browsers get presigned URLs on the public one. Change the secret for anything beyond local dev.
+# `live` uses that container; `fake` is in-memory and hands browsers unusable `fake://` upload URLs.
+KRATER_S3_MODE=live
+KRATER_S3_ENDPOINT_URL=http://storage:8333
+KRATER_S3_PUBLIC_ENDPOINT_URL=http://localhost:8333
+KRATER_S3_REGION=us-east-1
+KRATER_S3_BUCKET=krater-screenshots
+KRATER_S3_ACCESS_KEY_ID=krater
+KRATER_S3_SECRET_ACCESS_KEY=krater-dev-secret
+
+# docker-compose only: the `db` service's own credentials.
+POSTGRES_USER=krater
+POSTGRES_PASSWORD=krater
+POSTGRES_DB=krater
+PORT=8000
+
+# Production only (docs/dev/production.md). Leave unset for dev and staging.
+# Set to 127.0.0.1 so published ports are reachable only from the host, behind the TLS proxy.
+# KRATER_BIND_ADDRESS=127.0.0.1
+# Number of reverse proxies in front of the portal (1 with the `proxy` profile), for rate limiting.
+# KRATER_TRUSTED_PROXY_COUNT=1
+# SeaweedFS version; defaults to 4.47, the one staging ran. Change it only after a staging run, never to `latest`.
+# SEAWEEDFS_VERSION=4.47
+# `--profile proxy`: the public hostnames Caddy gets certificates for.
+# KRATER_DOMAIN=krater.example.org
+# KRATER_S3_DOMAIN=storage.krater.example.org
+# `--profile backup`: where nightly database dumps go, how often, and how long they're kept.
+# KRATER_BACKUP_DIR=/srv/krater/backups
+# KRATER_BACKUP_INTERVAL_SECONDS=86400
+# KRATER_BACKUP_KEEP_DAYS=14
+
+# The public GPU price catalog behind /pricing and the budget estimator (docs/dev/pricing.md). `live` fetches it
+# from GitHub; production refuses `fake`. KRATER_SKYPILOT_MODE still works as the old name for one release.
+KRATER_PRICING_MODE=fake

.gitattributes

@@ -0,0 +1,6 @@
+# Shell scripts must keep LF endings even in a Windows checkout (core.autocrlf=true): WSL and Linux
+# bash reject CRLF, and some dev scripts run in WSL2.
+*.sh text eol=lf
+
+# Self-hosted fonts are binary; never let autocrlf touch them.
+*.woff2 binary

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: root
+          POSTGRES_PASSWORD: root
+          POSTGRES_DB: krater_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U root"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    env:
+      KRATER_ENV: test
+      KRATER_DATABASE_URL: postgresql+psycopg://root:root@localhost:5432/krater_test
+      KRATER_TEST_DATABASE_URL: postgresql+psycopg://root:root@localhost:5432/krater_test
+      KRATER_SECRET_KEY: ci-test-secret
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "0.8.17"
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Lint (ruff check)
+        run: uv run ruff check .
+
+      - name: Format check (ruff format)
+        run: uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run pytest

.github/workflows/deploy.yml

@@ -0,0 +1,40 @@
+name: Deploy
+
+# Deploys a commit of this repo to alastor. There's no registry image: the NixOS module
+# (patchworklabsorg/infra, modules/krater) builds the image on alastor from the commit written to
+# /var/lib/krater/source-rev. This workflow writes that file, builds while the running site keeps
+# serving, then restarts krater-web, which migrates and starts; krater-worker follows it. Manual only,
+# like Weave's production deploys. See docs/dev/production.md.
+#
+# Required repository secrets:
+#   ALASTOR_HOST           - alastor's SSH host / IP
+#   KRATER_DEPLOY_SSH_KEY  - private key for the krater-deploy user on alastor (its public key goes in
+#                            the infra repo's hosts/alastor/krater.nix, deployAuthorizedKeys)
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: deploy-krater
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Deploy ${{ github.sha }}
+        uses: appleboy/ssh-action@v1
+        with:
+          host: ${{ secrets.ALASTOR_HOST }}
+          username: krater-deploy
+          key: ${{ secrets.KRATER_DEPLOY_SSH_KEY }}
+          # The first build of the Python dependencies takes several minutes on alastor.
+          command_timeout: 50m
+          script: |
+            set -e
+            echo "${{ github.sha }}" > /var/lib/krater/source-rev
+            sudo systemctl start krater-build
+            sudo systemctl restart krater-web
+            systemctl is-active krater-web krater-worker

.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# uv
+# (uv.lock IS committed -- do not ignore it)
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+# Live-Weave e2e fixture (scripts/dev/weave_e2e_setup.py) -- carries a live OAuth client secret
+# and service API key, regenerated on every run. See docs/dev/weave-e2e.md.
+.weave_e2e_fixture.json
+
+# Testing / tooling
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Logs
+*.log
+
+# Database dumps from the db-backup service (docker-compose.yml, --profile backup).
+/backups/

.python-version

@@ -0,0 +1 @@
+3.12

CLAUDE.md

@@ -0,0 +1,90 @@
+# CLAUDE.md
+
+Guidance for Claude Code (and humans) working in this repo.
+
+## What this is
+
+Krater is the Project Ganymede portal (Patchwork Labs): proposal review, compute budget allocation/enforcement, and a
+public gallery. **Read `docs/SPEC.md` before changing behavior.** Integration contracts live in
+`docs/weave-integration.md` (sign-in and roles) and
+`docs/quilt-integration.md` (submission and budget events to Quilt).
+
+## Stack
+
+- Python 3.12, managed with **uv** (`pyproject.toml` + `uv.lock`)
+- **FastAPI** web app, server-rendered **Jinja2** templates (no SPA; progressive enhancement with HTMX is fine)
+- **SQLAlchemy 2.0** (typed `Mapped[...]` models, sync sessions, psycopg 3) + **Alembic** migrations
+- **Postgres** (16+)
+- **procrastinate** (Postgres-backed) for background jobs and periodic tasks — no Redis
+- **Authlib** for OIDC against Weave; Starlette `SessionMiddleware` for the session cookie
+- **pytest** against a real Postgres test database; **ruff** for lint + format
+
+## Commands
+
+```bash
+uv sync                                   # install deps (incl. dev)
+uv run alembic upgrade head               # migrate (DATABASE_URL must be set)
+uv run alembic revision --autogenerate -m "..."   # new migration; always review the output
+uv run uvicorn krater.web.app:create_app --factory --reload   # web
+uv run procrastinate --app=krater.worker.app.app worker        # worker
+uv run pytest                             # tests (TEST_DATABASE_URL, see tests/conftest.py)
+uv run ruff check . && uv run ruff format --check .
+docker compose up --build                 # full stack: portal, worker, db
+```
+
+## Layout
+
+```
+krater/
+  config.py        Settings (pydantic-settings, env vars prefixed KRATER_)
+  db.py            engine, session factory, Base
+  models/          SQLAlchemy models, one module per aggregate
+  services/        domain logic (framework-free): approval_policy, projects, budget, audit, users
+  weave/           WeaveClient protocol: OIDC sign-in, directory API, role mapping, dev stub
+  quilt/           Quilt patch API client and the outbox sender (the only code that knows Quilt's URLs)
+  web/             FastAPI app factory, routers, deps (current user, authz), templates/, static/
+  worker/          procrastinate app + tasks
+alembic/           migrations
+tests/             mirrors krater/ layout
+```
+
+## Conventions
+
+- **Services own the rules.** Routers parse input, call a service, render. Services take a `Session` plus an explicit
+  actor and raise domain errors (`krater.services.errors`); they never import FastAPI.
+- **Money is integer cents** (`*_cents` columns, `int` in Python). Never floats.
+- **Primary keys are UUIDs** (`uuid.uuid4`), safe to show in URLs.
+- **Weave owns roles.** Krater's role keys in Weave are `member`, `reviewer` and `admin`, sent in the `roles` claim
+  and in directory records. Only when the `roles` field is absent does Krater fall back to the group slugs
+  `ganymede-members`, `krater-reviewers` and `krater-admins`. `krater.weave.roles` is the one place that maps them to
+  Krater's internal names `ganymede:member`, `ganymede:reviewer`, `ganymede:admin`; nothing else knows the keys or slugs.
+  Every state-changing action (`fresh_actor`, the Slack click path) re-checks Weave's directory by `sub` through
+  `krater.services.users.authorize`, and fails closed if Weave is down. `users.roles_cached` is for display only.
+  Krater has no role tables, no admin users page and no disable switch: those are done in Weave.
+- **Weave owns member data.** Krater stores a member's Patchwork ID (`users.weave_sub`), never their name, email or
+  other personal details: read those from Weave when needed (`krater.services.people`) and record who acted by
+  Patchwork ID (`docs/weave-integration.md` "Member data").
+- **All Weave access goes through `krater.weave`.** Nothing else imports httpx for Weave or knows Weave's URLs.
+  Krater asks for `openid profile email groups roles slack`, and calls the directory with a client_credentials token
+  of its own app (scope `directory`). Its token for Quilt (scope `quilt`) comes from `WeaveClient.quilt_token`.
+- **Events for Quilt go through the outbox.** A service that changes a project's status, title, ledger or spend
+  calls `krater.services.quilt_events.sync_project` in the same transaction. Never post to Quilt from a request.
+- **Every admin override writes an `AuditEvent`** (who, what, reason). Budget changes write a `BudgetEntry` (append-only;
+  never update or delete ledger rows).
+- **Stub mode** (`KRATER_WEAVE_MODE=stub`) replaces Weave with a local fixture of fake users for dev and tests. The
+  fixture carries the same `roles`, `groups` and `slack_id` fields a real Weave sends, and the stub answers the
+  directory lookups too. Tests change a user mid-test with `StubWeaveClient.set_roles` and friends. The app must
+  refuse to start in stub mode when `KRATER_ENV=production`.
+- Timestamps are timezone-aware UTC (`DateTime(timezone=True)`).
+- Tests: every service rule gets a unit test; every route gets at least a happy-path and an authz test.
+- Keep comments for the *why*; match the surrounding style.
+
+## Brand
+
+Krater uses the Patchwork palette with the same role tokens as Quilt's stylesheet: Ink `#2a2050` text on Quilt
+`#f7f5fb`, Grape `#6c3ec1` as the primary accent, Deep Purple `#4b006e` for hover, Lavender `#c7b7e2` in the brand
+mark, solid hairline cards, Geist for all text, and a dark mode. The tokens live on `:root` in
+`krater/web/static/css/main.css`; components use the role tokens (`--surface`, `--text`, `--accent` ...), never raw
+colors. Style through the existing classes (`.page-head`, `.card`, `.stats`, `.button--primary`, `.badge--<status>`,
+`.table-scroll` ...). Pages give only their own name in `{% block title %}`; `base.html` adds " · Krater". Every
+page must work at 360px wide with no horizontal page scroll.

Dockerfile

@@ -0,0 +1,37 @@
+# syntax=docker/dockerfile:1
+#
+# Builds for both amd64 and arm64 (e.g. `docker buildx build --platform linux/amd64,linux/arm64 .`):
+# both `python:3.12-slim` and the `uv` image below publish multi-arch manifests, and nothing here
+# pins an architecture.
+FROM python:3.12-slim
+
+# Copy the `uv` and `uvx` binaries from Astral's official image rather than installing via pip.
+COPY --from=ghcr.io/astral-sh/uv:0.8.17 /uv /uvx /usr/local/bin/
+
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=never \
+    PYTHONUNBUFFERED=1 \
+    PATH="/app/.venv/bin:$PATH"
+
+WORKDIR /app
+
+# Install dependencies before copying the rest of the source, so `docker build` caches this layer as
+# long as pyproject.toml / uv.lock haven't changed.
+COPY pyproject.toml uv.lock ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-install-project --no-dev
+
+COPY . .
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev
+
+RUN groupadd --system krater \
+    && useradd --system --gid krater --create-home --home-dir /home/krater krater \
+    && chown -R krater:krater /app
+USER krater
+
+EXPOSE 8000
+
+# The portal is the default; docker-compose.yml overrides `command` for `migrate` and `worker`.
+CMD ["uvicorn", "krater.web.app:create_app", "--factory", "--host", "0.0.0.0", "--port", "8000"]