diff --git a/.forgejo/workflows/ci.yml b/.forgejo/workflows/ci.yml index d86579ba..4d5297ea 100644 --- a/.forgejo/workflows/ci.yml +++ b/.forgejo/workflows/ci.yml @@ -4,27 +4,15 @@ # Push to main: typecheck + lint + test + build :latest + : # Tag v* (release): typecheck + lint + test + build :latest + : + : # -# Both dev and main are gated AND built. dev pushes move :dev; main pushes move -# :latest — main IS the production line, so :latest tracks main's tip and there -# is no separate :main tag. Every push also gets an immutable : (the -# rollback point). A v* release tag additionally publishes the dated :; -# since main already moved :latest, the release tag's distinct job is that -# : marker (it refreshes :latest too, harmlessly). +# main is the production line, so :latest tracks main's tip. Every push also +# gets an immutable :, the rollback point. A release (a v* tag created on +# main in the Forgejo UI) adds the dated :. # -# Successive pushes to the SAME ref supersede each other (see concurrency -# below), so rapid pushes don't stack identical work; dev and main runs are -# independent refs and never cancel one another. +# A newer push to the same ref cancels the older run; dev and main never cancel +# each other. Pull requests don't trigger runs: branch pushes already gate. # -# To cut a release: -# Create a release via the Forgejo UI on main with a v* tag name. -# The tag push triggers this workflow; build job pushes :latest + :. -# -# PRs aren't triggered on purpose — this is a solo dev→main flow, so -# gating on branch push is already enough. -# -# NOTE on the `if:` guards below: Forgejo Actions does not consistently -# honor `on.push.branches` as a filter, so every job repeats the ref check -# explicitly — permitting dev, main, and v* tags, rejecting anything else. +# Forgejo Actions doesn't reliably honour `on.push.branches` as a filter, so +# every job repeats the ref check in its `if:`. # # Required secrets (repo → Settings → Secrets → Actions): # REGISTRY_USER — your Forgejo username @@ -40,31 +28,22 @@ on: - "frontend/**" - "tests/**" - "pyproject.toml" - # The lock now determines what gets installed, so a lock-only change has - # to trigger a run — otherwise a dependency bump lands untested. + # The lock decides what is installed, so a lock-only change must run CI. - "uv.lock" - "alembic/**" - "alembic.ini" - "Dockerfile" - # The plugin ships straight from this repo — installs fetch it via - # .claude-plugin/marketplace.json, NOT from the image. So a push here is - # the release, with no build step in between. Omitting these paths meant - # plugin changes triggered no workflow at all, which is how #2198's three - # broken hooks and then #2209's missing version bump both reached a live - # install. See the `plugin` job below. + # The plugin ships straight from git (via .claude-plugin/marketplace.json), + # not in the image, so a push here is its release. See the `plugin` job. - "plugin/**" - ".claude-plugin/**" - "scripts/check_plugin.py" - ".forgejo/workflows/ci.yml" - # Manual trigger from the Forgejo Actions UI. Useful when an image has - # been built but the deployment didn't pick it up, or when re-running - # against the same source produces different upstream behaviour - # (e.g. a transient HF download flake during the voice-bundle step). + # Manual run from the Forgejo Actions UI, e.g. to rebuild an image. workflow_dispatch: {} -# Cancel older runs on the same branch when a newer push lands. Tag runs -# get their own group implicitly (refs/tags/v1.2.3 ≠ refs/heads/dev) and -# are never cancelled, so a release build can't kill itself mid-flight. +# A newer push cancels the older run on the same branch. Tag runs are never +# cancelled, so a release build can't be cut off mid-flight. concurrency: group: ci-${{ github.ref }} cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }} @@ -91,10 +70,7 @@ jobs: - name: Cache npm download cache uses: actions/cache@v4 - # Non-fatal: a transient cache-backend hiccup must NOT fail the whole - # typecheck job (it was skipping install + type check and reporting red - # on backend-only pushes — see issue task #828). On cache miss/error the - # job just installs without the cache. + # Non-fatal: a cache-backend error just means installing without it. continue-on-error: true with: path: ~/.npm @@ -110,8 +86,7 @@ jobs: working-directory: frontend # Guards the one part of this repo that ships to users without a build step. - # See scripts/check_plugin.py for what it checks and, as importantly, what it - # can't check yet (shellcheck is absent from ci-python). + # scripts/check_plugin.py says what it checks and what it can't. plugin: name: Plugin hooks if: github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') @@ -119,25 +94,14 @@ jobs: container: image: git.fabledsword.com/bvandeusen/ci-python:3.14 steps: - # Bare `uses:`, no `with:` block. Adding one made this action fail to - # extract on the act_runner ("Cannot find module .../dist/index.js") while - # every bare checkout in the same run succeeded — see run 3027. Nothing - # here needs `fetch-depth: 0` anyway: the version check diffs two trees, - # and a tree diff needs both trees, not a common ancestor. A depth-1 fetch - # of main's tip is enough, and cheaper. + # Keep this a bare `uses:`: with a `with:` block the action fails to + # extract on act_runner ("Cannot find module .../dist/index.js"). The + # version check diffs two trees, so a depth-1 fetch of main is enough. - uses: actions/checkout@v6 - # Per-job, not in the image, per CI-runner's docs/process.md: "If only one - # project needs the dep, prefer that project installing it per-job in - # their workflow — at least until a second consumer arrives." Scribe is - # the only consumer today. Promotion into ci-python is filed as an issue - # on CI-runner rather than assumed here. - # - # jq WAS installed here too, because every hook exited at line 1 without - # it and the smoke test would have passed while exercising nothing. The - # hooks need no jq since #4107 — they use only what POSIX guarantees — so - # the smoke test now runs on a bare image, which is the condition it is - # actually meant to be asserting. + # Per-job rather than in the image: Scribe is shellcheck's only consumer. + # Install nothing else here; the hooks use only POSIX tools, and the + # smoke test runs on a bare image to prove it. - name: Install shell tooling run: | apt-get update -qq @@ -163,28 +127,19 @@ jobs: steps: - uses: actions/checkout@v6 - # ruff is pre-installed in the ci-python image — no install - # step needed, lint runs in ~2s. + # ruff is pre-installed in the ci-python image. - name: Lint run: ruff check src/ scripts/ - # Design tokens: does the frontend's CSS agree with the stylesheet the - # design system generates? Fails only on an unresolvable var() reference — - # that count is at zero, so this is a ratchet rather than a backlog. The - # literal findings are printed, not gated; hundreds exist and a - # permanently-red job is one nobody reads. - # - # Stdlib only, no install, no network: the source of truth is theme.css, - # which is generated from the design system and committed. + # Checks the frontend's CSS against the committed, generated theme.css. + # Fails only on an unresolvable var() reference; hard-coded literals are + # reported, not gated. - name: Design token check run: python3 scripts/check_design_tokens.py --report-literals - # Dangling styles: an element whose classes have only modifier rules and - # no base — a deleted CSS rule that left its `:hover` behind. Two shipped - # this way (a link rendering as raw browser blue, a flex row whose parent - # was gone so every child stacked). Neither is visible to vue-tsc; a dead - # style typechecks perfectly. Reported, not gated — a bare wrapper is - # legitimate, so the signal is the count growing. + # Reports elements whose classes have modifier rules but no base rule, + # which vue-tsc can't see. Not gated: a bare wrapper is legitimate, so + # the signal is the count growing. - name: Dangling style check run: python3 scripts/check_dangling_styles.py @@ -201,63 +156,41 @@ jobs: uses: actions/cache@v4 with: path: ~/.cache/uv - # Keyed on the LOCK, not pyproject: the lock is what determines the - # installed set now, and a pyproject edit that doesn't change - # resolution shouldn't throw the cache away. + # Keyed on the lock, which decides the installed set. key: uv-${{ hashFiles('uv.lock') }} restore-keys: uv- - # Installs exactly what uv.lock pins, and resolves nothing itself. - # - # This replaced `uv pip install -e ".[dev]"`, which resolved from the - # pyproject constraints and ignored the lock entirely. Every dependency - # floated: on 2026-07-28 mcp 2.0.0 shipped mid-session and turned `main` - # red with no repo change (issue #2194). Green CI has to mean "these exact - # versions passed", or it isn't evidence of anything. - # - # `--locked` also FAILS when uv.lock is stale against pyproject, so a - # dependency edit has to go through a deliberate `uv lock` — it can't - # arrive on its own. That check earned its place immediately: it caught - # that the lock had been missing `pgvector` entirely (added to pyproject, - # never re-locked), which the old install path had been silently papering - # over by resolving from pyproject instead. + # Installs exactly what uv.lock pins, so green means these exact versions + # passed. `--locked` fails if the lock is stale against pyproject, so a + # dependency change needs a deliberate `uv lock`. - name: Install locked dependencies env: UV_PROJECT_ENVIRONMENT: /opt/venv run: uv sync --locked --extra dev - # An "Install jq for hook execution tests" step stood here. The hook - # EXECUTION tests run the real bash hook, which exited silently without - # jq and skipped rather than failed, so the step existed to stop them - # being silently unverified. Since #4107 the hooks need no jq, so the - # step is gone and those tests run against a bare image — and the point - # of removing a dependency is lost if CI keeps installing it anyway. + # The hook execution tests run on a bare image (no jq), like a user's + # machine might be. - name: Run tests # Integration tests (real Postgres) run in the `integration` job below. run: /opt/venv/bin/python -m pytest tests/ -q -m "not integration" - # Real-Postgres lane (family rule 6). Exercises the async SQLAlchemy connection - # path the unit stubs can't reach — the un-awaited execution_options regression - # that made every VACUUM report 0/6 lived here. Like `test`, it runs for - # visibility and does NOT gate the build. + # Real Postgres, built by the real migrations: covers the async SQLAlchemy + # paths unit stubs can't reach. # - # Job key stays separator-free ("integration"): act_runner derives the service- - # container name from the (truncated) job display name and the discovery step - # filters `docker ps` by it. Service hostnames aren't routable on this runner, - # so the step resolves the Postgres container's bridge IP. No `name:` on purpose. + # Service hostnames aren't routable on this runner, so the step finds the + # Postgres container's bridge IP. The job has no `name:` and a separator-free + # key because act_runner names service containers after it. integration: if: github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') runs-on: python-ci container: image: git.fabledsword.com/bvandeusen/ci-python:3.14 env: - # Config + the module engine read these at import time. DATABASE_URL itself - # is built from the discovered service IP in the run step. + # Read at import time. DATABASE_URL is built from the discovered IP below. SECRET_KEY: ci_integration_placeholder services: postgres: - # pgvector image so `alembic upgrade head` can run migration 0067 - # (CREATE EXTENSION vector). PG17 — matches the prod/quickstart image. + # Same image as the shipped compose files: Postgres 17 with pgvector. image: pgvector/pgvector:pg17 env: POSTGRES_USER: scribe @@ -270,25 +203,19 @@ jobs: --health-retries 10 steps: - uses: actions/checkout@v6 - # Same locked install as the unit lane — the two must agree on versions, - # or "unit green, integration red" stops being a signal about the code. + # Same locked install as the unit lane, so both test the same versions. - name: Install locked dependencies env: UV_PROJECT_ENVIRONMENT: /opt/venv run: uv sync --locked --extra dev - # Standing answers to the checks carried by rules 81 and 79 — two facts - # about THIS runner that conditional rules assert as fact, and that - # otherwise need a throwaway job to confirm (#3237). Printing them on - # every integration run makes the next rulebook sweep a log read. - # Rule 80's evidence is the container listing the next step already - # prints. Every command is guarded: a diagnostic that can break the lane - # it observes is worse than no diagnostic. - - name: Runner facts (rules 79 and 81) + # Prints two facts about the runner that the steps below depend on. + # Every command is guarded so the diagnostic can't fail the lane. + - name: Runner facts (shell, service hostnames) run: | - echo "--- rule 81: which shell runs a run: step ---" + echo "--- which shell runs a run: step ---" readlink -f /bin/sh || echo "/bin/sh: not a symlink" ps -p $$ -o comm= || true - echo "--- rule 79: is a service reachable by its hostname yet? ---" + echo "--- is a service reachable by its hostname? ---" getent hosts postgres \ || echo "no — 'postgres' does not resolve; the bridge-IP lookup is still required" - name: Integration suite (resolve service IP, migrate, test) @@ -296,12 +223,10 @@ jobs: set -eux echo "=== container landscape (diagnostic for the name filter) ===" docker ps -a --format '{{.ID}} {{.Image}} -> {{.Names}}' - # Only THIS job's services. The runner's docker daemon is shared, so another - # repo's job can be running beside this one, and a job-name filter matches its - # containers too (Steward run 8358 and Inkwell run 8653 each took another repo's - # Postgres). act names every container of a task GITEA-ACTIONS-TASK--...: read - # from our own container (its id is in the /etc/hostname bind mount) and - # require exactly one match. + # Only this job's services: the docker daemon is shared, so a job-name + # filter can match another repo's Postgres. act names a task's containers + # GITEA-ACTIONS-TASK--...; read from our own container (its id is in + # the /etc/hostname bind mount) and require exactly one match. SELF=$(grep -o '/containers/[0-9a-f]\{64\}/' /proc/self/mountinfo | head -n1 | cut -d/ -f3 || true) SELF=${SELF:-$(hostname)} TASK=$(docker inspect -f '{{.Name}}' "$SELF" | grep -o 'GITEA-ACTIONS-TASK-[0-9]*-') @@ -311,9 +236,7 @@ jobs: PG_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$PG") test -n "$PG_IP" export DATABASE_URL="postgresql+asyncpg://scribe:ci_integration@${PG_IP}:5432/scribe_test" - # Wait for Postgres to accept connections. The run: shell is dash - # (/bin/sh -> /usr/bin/dash on this Debian-based image, confirmed by - # the step above) — no bash /dev/tcp, so use Python. + # Wait for Postgres. The run: shell is dash (no bash /dev/tcp), so use Python. /opt/venv/bin/python - "$PG_IP" <<'PY' import socket, sys, time for _ in range(30): @@ -332,21 +255,12 @@ jobs: build: name: Build & push image - # `plugin` is deliberately NOT in needs. The plugin isn't in the image — - # installs fetch it from git — so gating the server image on a hook lint - # would couple two things that don't ship together, and blocking the build - # wouldn't un-publish a bad hook anyway: the push already did that. A failed - # `plugin` job still turns the whole run red, which is the signal that - # matters. - # - # `integration` IS in needs (rule 177, #4958). It was added after this - # gate and left out of it, so on 2026-10-05 main run 8212 published - # :latest with integration red. The image carries the migrations and the - # queries that lane runs against real Postgres; a red integration run is - # a red image. + # `plugin` is not in needs: the plugin ships from git, not in the image, so + # holding the image back wouldn't stop a bad hook. A red `plugin` job still + # turns the run red. `integration` is: the image carries the migrations and + # queries that lane tests. needs: [typecheck, lint, test, integration] - # Build on dev, main, and v* tag pushes. dev → :dev, main → :latest, - # tag → :latest + :; every build also gets an immutable :. + # dev → :dev, main → :latest, tag → :latest + :; all get :. if: github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') runs-on: python-ci container: @@ -357,53 +271,37 @@ jobs: steps: - uses: actions/checkout@v6 with: - # Rule 149 asks for this on any job deriving the version NAME. The - # name here comes from HEAD's commit TIME, which a depth-1 clone - # already has — but the rule states it unconditionally because the - # failure it guards is silent (a too-low value, every lane green), - # and a later change to how the name is derived would inherit the - # landmine rather than the guard. + # Full history for the version derivation. Today it needs only HEAD's + # commit time, but a shallow clone fails silently (a too-low value) if + # the derivation ever reads further back. fetch-depth: 0 - name: Generate image tags and version id: tags - # POSIX `case` instead of bash `[[ ]]` because act_runner invokes - # `sh -e` (dash on the ci-python:3.14 image, which has no bash on - # the default PATH for /bin/sh). Previous `[[ ]]` form failed - # silently — only the SHA tag got appended, so :dev / :latest - # never updated in the registry and the deployed stack kept - # pulling stale images. Verified via `[[: not found` lines in - # the runner log on commit 2a374d9. + # POSIX `case`, not bash `[[ ]]`: the run: shell is dash, where `[[` + # fails silently and only the : tag would be pushed. run: | TAGS="${{ env.IMAGE }}:${{ github.sha }}" - # THREE VALUES, NEVER FOLDED TOGETHER (rule 149). Until 2026-08-31 - # BUILD_VERSION was the CHANNEL — "dev" / "main" / the tag — so the - # image self-reported {"version":"main"}, a channel name where a - # build identifier belongs. That cost a debugging session: with the - # deploy misbehaving, nothing on the running instance could say - # which commit was serving it. + # Three values kept separate; the Dockerfile describes each. - # 1. ORDERING KEY — BUILD time, monotonic by construction. Minutes - # since 2020-01-01. Never a commit count (not monotonic across - # branches) and never commit time (goes DOWN when an older - # commit is rebuilt). + # 1. Ordering key: build time in minutes since 2020-01-01, so it only + # goes up. Commit time would go down when an older commit is + # rebuilt; a commit count isn't monotonic across branches. BUILD_KEY=$(( ( $(date -u +%s) - 1577836800 ) / 60 )) - # 2. NAME — COMMIT time, so the same source reports the same string - # on every lane and the channel is the only thing that differs. + # 2. Name: commit time, so the same source reads the same on every lane. COMMIT_TS=$(git log --format=%ct -1 HEAD) BUILD_NAME=$(date -u -d "@$COMMIT_TS" +%Y.%m.%d.%H%M) - # 3. CHANNEL — its own value. Never a suffix, never a segment. + # 3. Channel: its own value, never part of the name. CHANNEL="dev" case "${{ github.ref }}" in refs/heads/dev) TAGS="$TAGS,${{ env.IMAGE }}:dev" ;; refs/heads/main) - # main IS the production line: publish :latest (plus the : - # set above). No separate :main tag. + # main is the production line, so it publishes :latest. TAGS="$TAGS,${{ env.IMAGE }}:latest" CHANNEL="stable" ;; @@ -418,12 +316,8 @@ jobs: echo "channel=$CHANNEL" >> $GITHUB_OUTPUT - name: Free disk space - # Self-hosted runner housekeeping. Two-step cleanup: - # 1. Prune dangling containers/images globally (stops the runner - # from accumulating cruft from past failed builds). - # 2. Trim the BuildKit layer cache to a 5GB ceiling so the pip - # mount cache survives but old intermediate layers don't - # accumulate indefinitely. + # Prunes unused containers and images, and caps the BuildKit cache at + # 5 GB so the package caches survive but old layers don't pile up. run: | docker system prune -af || true docker builder prune --keep-storage 5g -f || true @@ -445,19 +339,13 @@ jobs: push: true provenance: false tags: ${{ steps.tags.outputs.value }} - # All three, plus the commit — rule 145: the registry's identity for - # a build (:) and the artifact's identity for itself must - # agree, and they can only be checked against each other if the - # artifact says which commit it is. + # The commit lets the image's self-report be checked against :. build-args: | BUILD_VERSION=${{ steps.tags.outputs.build_name }} BUILD_KEY=${{ steps.tags.outputs.build_key }} BUILD_CHANNEL=${{ steps.tags.outputs.channel }} BUILD_COMMIT=${{ github.sha }} - # Registry-backed layer cache. Pull from :cache to prime - # BuildKit, push updated layers back to :cache so the next - # build starts warm even if the runner's local cache was - # pruned. `mode=max` exports all intermediate layers, not - # just the final image, which is what gives the ~80% speedup. + # Layer cache kept in the registry, so a build starts warm even after + # the runner prunes. `mode=max` caches intermediate layers too. cache-from: type=registry,ref=${{ env.IMAGE }}:cache cache-to: type=registry,ref=${{ env.IMAGE }}:cache,mode=max,ignore-error=true diff --git a/Dockerfile b/Dockerfile index c94d3854..248d0b9d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -12,11 +12,8 @@ RUN npm run build FROM python:3.14-slim AS runtime WORKDIR /app -# Installed from uv.lock, exactly like CI (issue #2194). This used to be -# `COPY pyproject.toml .` + `pip install .`, which never even copied the lock: -# the shipped image resolved its own dependency set, so CI could be green on one -# set of versions while the published image ran another. On 2026-07-28 that -# class of drift turned `main` red when mcp 2.0.0 shipped mid-session. +# Installed from uv.lock, exactly like CI, so the image runs the dependency +# versions CI tested. RUN --mount=type=cache,target=/root/.cache/pip \ pip install --no-cache-dir uv @@ -41,21 +38,15 @@ COPY alembic/ alembic/ # Ensure Python finds the source tree (where static files live) before site-packages ENV PYTHONPATH=/app/src -# THREE VALUES, NEVER FOLDED TOGETHER (rule 149), plus the commit. -# -# BUILD_VERSION is the NAME (YYYY.MM.DD.HHMM, from COMMIT time) — the same -# string on every lane for the same source, so it answers "is this the same -# code?" rather than "which lane built it?". -# BUILD_KEY is the ORDERING KEY (minutes since 2020-01-01, from BUILD time) — -# the only value anything may compare to decide what is newer. -# BUILD_CHANNEL is its own field. Never a suffix, never a segment of the name. -# BUILD_COMMIT lets the artifact's self-report be checked against the : -# it was published under (rule 145). -# -# Each defaults to empty rather than to a placeholder, EXCEPT the name: a -# local build genuinely has no ordering key or channel, and the endpoint says -# so by omitting them. Inventing values would make a local image claim a -# position in an update order it is not part of. +# Three values kept separate, plus the commit: +# BUILD_VERSION is the name (YYYY.MM.DD.HHMM from commit time), the same on +# every lane for the same source. +# BUILD_KEY is the ordering key (minutes since 2020-01-01 from build time), the +# only value compared to decide which build is newer. +# BUILD_CHANNEL is its own field, never part of the name. +# BUILD_COMMIT lets the image's self-report be checked against its : tag. +# A local build leaves the key and channel empty: it has no place in an update +# order, and /api/version omits them. ARG BUILD_VERSION=dev ARG BUILD_KEY= ARG BUILD_CHANNEL= diff --git a/Makefile b/Makefile index 231f991b..2c74805f 100644 --- a/Makefile +++ b/Makefile @@ -39,9 +39,8 @@ check: lint typecheck test # --- Plugin --- -# Run this after changing anything under plugin/ or .claude-plugin/, BEFORE -# committing. The plugin ships straight from git with no build step, so its -# version is minted here rather than stamped by CI; the lane fails if you -# forget, but this is what makes remembering cheap. +# Run after changing plugin/ or .claude-plugin/, before committing: the plugin +# ships from git with no build step, so its version is minted here. CI fails if +# the version wasn't bumped. mint-plugin: python3 scripts/mint_plugin_version.py diff --git a/README.md b/README.md index efa16218..48c10735 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ export SECRET_KEY=your-random-secret-here docker compose -f docker-compose.quickstart.yml up -d ``` -Open `http://localhost:5000`. The first user to register becomes admin. To connect Claude, create an API key under **Settings → API Keys** and install the Claude Code plugin — see [API Keys & MCP](docs/api-keys-and-mcp.md). +Open `http://localhost:5000`. The first user to register becomes admin. To connect Claude, create an API key under **Settings → MCP Access** and install the Claude Code plugin — see [API Keys & MCP](docs/api-keys-and-mcp.md). > **Development:** To build from source, see [Development](docs/development.md). @@ -31,7 +31,7 @@ Open `http://localhost:5000`. The first user to register becomes admin. To conne | [Configuration](docs/configuration.md) | Environment variables, Docker Compose, production setup, security | | [Features](docs/features.md) | Detailed feature breakdown and keyboard shortcuts | | [Development](docs/development.md) | Dev workflow, CI/CD, migrations, release process | -| [API Keys & MCP](docs/api-keys-and-mcp.md) | API key management and Fable MCP install guide | +| [API Keys & MCP](docs/api-keys-and-mcp.md) | API keys and installing the Claude Code plugin | | [SSO / OAuth](docs/sso-oauth.md) | OIDC setup for Authentik, Keycloak, and other providers | | [API Reference](docs/api-reference.md) | All REST API endpoints | diff --git a/ci-requirements.md b/ci-requirements.md index 41972e9d..830dae4f 100644 --- a/ci-requirements.md +++ b/ci-requirements.md @@ -16,11 +16,10 @@ real Postgres), build (docker buildx). ## Image deps used - python 3.14 -- node 24 (used for `npm ci` + `vue-tsc` in the typecheck job, and as the - frontend builder stage inside the production `Dockerfile`) -- ruff (lint job runs `ruff check src/` with zero install overhead) -- uv (test + integration jobs run `uv sync --locked`; installed in the - image since the ci-python Dockerfile started pip-installing it) +- node 24 (`npm ci` + `vue-tsc` in the typecheck job; the production + `Dockerfile` builds the frontend on `node:22-alpine`) +- ruff (lint job runs `ruff check src/ scripts/` with zero install overhead) +- uv (test + integration jobs run `uv sync --locked`) - docker CLI + buildx (build job pushes the production image to the Fabled-Git registry) @@ -30,24 +29,15 @@ Anything CI installs at job time that isn't in the image. Promotion candidates if more than one project needs them. - `shellcheck` — apt-installed in the **plugin** job, which lints the - Claude Code hook scripts and runs their fail-open smoke test. Per - `docs/process.md`'s decision checkpoint, single-consumer deps stay - per-job until a second consumer wants them; Scribe is the only one so - far. It is small (~20 MB) and would be a promotion candidate the moment - another project lints shell. + Claude Code hook scripts and runs their fail-open smoke test. Scribe is + its only consumer, so per `docs/process.md` it stays per-job. It is small + (~20 MB) and a promotion candidate once another project lints shell. -- `jq` — **no longer installed anywhere, and should not be promoted.** - It was installed in two jobs, and this file used to record it as "load- - bearing for the smoke test specifically", because every hook opened - `command -v jq || exit 0` and the test would otherwise pass while - exercising nothing. That was the tail wagging the dog: the hooks ship to - users, jq is absent by default on macOS, the Debian/Ubuntu slim images, - Alpine and most CI containers, and a machine without it got no context, - no rules, no prior art and no process sync in silence. #4107 removed the - dependency rather than documenting it, so the smoke test now runs on a - bare image — which is the condition it was always meant to assert. The - hooks use only POSIX tools (awk, sed, tr, od, cut, head, tail, grep, - sort, date, printf) plus `git` and `curl`. +The hooks ship to users' machines, so they use only POSIX tools (awk, sed, +tr, od, cut, head, tail, grep, sort, date, printf) plus `git` and `curl`. +The smoke test runs on a bare image to keep it that way: a tool such as `jq` +is missing on macOS, slim Debian/Ubuntu and Alpine, and a hook that needed it +would give those machines nothing. ## Notes diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml index a540bf62..15bf444b 100644 --- a/docker-compose.prod.yml +++ b/docker-compose.prod.yml @@ -21,10 +21,7 @@ services: max_attempts: 5 db: - # pgvector image (Debian/glibc, PG17) — bundles the `vector` extension that - # migration 0067 enables. Moved off postgres:16-alpine via logical - # dump/restore (which doubles as the PG16->PG17 major upgrade); see the - # TRANSITION runbook in the PR. + # Postgres 17 with the vector extension Scribe needs. image: pgvector/pgvector:pg17 stop_grace_period: 120s volumes: @@ -35,9 +32,8 @@ services: POSTGRES_DB: scribe networks: - scribe_backend - # Lenient by design: a transient host exec/healthcheck stall (incident: - # runc setns failures -> "unhealthy" -> SIGKILL -> crash loop) must never - # escalate to killing the DB. Health here only gates app startup order. + # Lenient on purpose: health only orders app startup, so a stalled check + # must not get the database killed. healthcheck: test: ["CMD-SHELL", "pg_isready -U scribe"] interval: 30s diff --git a/docker-compose.quickstart.yml b/docker-compose.quickstart.yml index 80011b38..dc79f5eb 100644 --- a/docker-compose.quickstart.yml +++ b/docker-compose.quickstart.yml @@ -1,16 +1,7 @@ -# Fabled Scribe — Quick Start -# -# No build required. Pulls the latest pre-built image from the registry. -# -# Usage: -# 1. Download this file -# 2. docker compose -f docker-compose.quickstart.yml up -d -# 3. Open http://localhost:5000 — the first account registered becomes admin -# 4. Go to Settings → MCP Access and connect Claude (Code or Desktop) via the -# bearer-token URL shown there. -# -# Set SECRET_KEY via environment variable or a .env file alongside this file: -# SECRET_KEY=your-random-secret-here +# Fabled Scribe from the pre-built image: +# docker compose -f docker-compose.quickstart.yml up -d +# Then open http://localhost:5000 (the first account registered becomes admin) +# and connect Claude from Settings → MCP Access. services: app: @@ -19,6 +10,7 @@ services: - "5000:5000" environment: DATABASE_URL: "postgresql+asyncpg://scribe:scribe@db:5432/scribe" + # Set SECRET_KEY in the environment or a .env file beside this one. SECRET_KEY: "${SECRET_KEY:-change-me-in-production}" LOG_LEVEL: "${LOG_LEVEL:-INFO}" volumes: @@ -35,7 +27,7 @@ services: start_period: 30s db: - # pgvector image (PG17) — bundles the `vector` extension (migration 0067). + # Postgres 17 with the vector extension Scribe needs. image: pgvector/pgvector:pg17 stop_grace_period: 120s volumes: @@ -44,8 +36,8 @@ services: POSTGRES_USER: scribe POSTGRES_PASSWORD: scribe POSTGRES_DB: scribe - # Lenient by design: a transient host exec/healthcheck stall must never - # escalate to killing the DB. Health here only gates app startup order. + # Lenient on purpose: health only orders app startup, so a stalled check + # must not get the database killed. healthcheck: test: ["CMD-SHELL", "pg_isready -U scribe"] interval: 30s diff --git a/docker-compose.yml b/docker-compose.yml index eba260df..a074ceca 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -8,13 +8,12 @@ services: condition: service_healthy volumes: - app_data:/data - # To use a bind mount instead (gives direct host access to all app data): + # Or a bind mount, for direct host access to the app's data: # - ./data:/data environment: DATABASE_URL: "postgresql+asyncpg://${POSTGRES_USER:-scribe}:${POSTGRES_PASSWORD:-scribe}@db:5432/${POSTGRES_DB:-scribe}" SECRET_KEY: "${SECRET_KEY:-dev-secret-change-me}" - # Uncomment if you have a SearXNG instance you want to surface in the - # Integrations tab as a configured web-search backend: + # Optional: a SearXNG instance to list as the web-search backend in Integrations. # SEARXNG_URL: "http://searxng:8080" healthcheck: test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/api/health')"] @@ -33,8 +32,8 @@ services: POSTGRES_USER: ${POSTGRES_USER:-scribe} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-scribe} POSTGRES_DB: ${POSTGRES_DB:-scribe} - # Lenient by design: a transient host exec/healthcheck stall must never - # escalate to killing the DB. Health here only gates app startup order. + # Lenient on purpose: health only orders app startup, so a stalled check + # must not get the database killed. healthcheck: test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-scribe}"] interval: 30s