precursor-ai 2026.7.0__tar.gz

precursor_ai-2026.7.0/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{ts,tsx,js,jsx,json,html,css,yml,yaml,md}]
+indent_size = 2

precursor_ai-2026.7.0/.env.example

@@ -0,0 +1,35 @@
+# Precursor configuration. Every setting has a built-in default (see
+# precursor/backend/config.py), so this file is optional — Precursor runs fine
+# with no .env. Copy to `.env` and uncomment only what you want to override.
+
+# --- Server ---
+# `--port` (PRECURSOR_PORT) is always the URL you open. In `--dev` the Vite UI
+# runs there and the backend moves to PORT + 1 (override with `--api-port`).
+# A busy port auto-bumps to the next free one (use `--strict-port` to fail
+# instead, or `--port 0` for any free port).
+# PRECURSOR_HOST=127.0.0.1
+# PRECURSOR_PORT=8000
+# PRECURSOR_LOG_LEVEL=info
+# Seconds to wait for in-flight requests (e.g. SSE streams) before force-closing
+# on Ctrl-C, so the port is released promptly instead of hanging.
+# PRECURSOR_SHUTDOWN_GRACE_SECONDS=3
+
+# --- Database ---
+# Defaults to a local SQLite file; point at Postgres for production.
+# PRECURSOR_DATABASE_URL=sqlite+aiosqlite:///./precursor.db
+# PRECURSOR_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/precursor
+
+# --- LLM provider ---
+# The provider (GitHub Copilot, GitHub Models, Azure AI Foundry, OpenAI,
+# Mistral, Hugging Face, Ollama, or Mock) and its credentials are configured at
+# runtime in the app — Settings → Model — not via the environment. The GitHub
+# providers fall back to your `gh auth login` session when no token is saved.
+
+# --- Backup ---
+# Periodic copy of the SQLite DB + attachment blobs into a plain folder (e.g. a
+# OneDrive/Dropbox/iCloud-synced directory). Enable it, pick the target folder
+# and set snapshot retention at runtime in the app — Settings → Backup. Only the
+# scheduling knobs below are env-level (the ticker polls every poll interval and
+# runs once the interval has elapsed since the last success).
+# PRECURSOR_BACKUP_INTERVAL_SECONDS=86400
+# PRECURSOR_BACKUP_POLL_SECONDS=3600

precursor_ai-2026.7.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,63 @@
+name: Bug report
+description: Something doesn't work as expected.
+labels: ["bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug. Please fill out the sections below.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear and concise description of the problem.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Minimum steps to reproduce.
+      value: |
+        1.
+        2.
+        3.
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Precursor version / commit
+    validations:
+      required: true
+
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Surface
+      options:
+        - Backend (API / streaming)
+        - Frontend (SPA)
+        - GitHub integration
+        - MCP
+        - Plugins
+        - Other / unsure
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs / stack traces
+      render: shell

precursor_ai-2026.7.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Discussions
+    url: https://github.com/lrivallain/precursor/discussions
+    about: Ask a question or propose an idea before opening an issue.

precursor_ai-2026.7.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,38 @@
+name: Feature request
+description: Propose a new capability or improvement.
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem are you trying to solve? Why does it matter?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How would you like Precursor to behave?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Surface
+      options:
+        - Backend
+        - Frontend
+        - GitHub integration
+        - MCP
+        - Plugins
+        - Docs / DX
+    validations:
+      required: true

precursor_ai-2026.7.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+<!--
+Thanks for contributing to Precursor! Please fill out the sections below.
+-->
+
+## Summary
+
+<!-- One or two sentences describing what this PR does and why. -->
+
+## Linked issue
+
+Closes #
+
+## Changes
+
+-
+
+## Verification
+
+- [ ] `ruff check .` passes
+- [ ] `mypy precursor` passes
+- [ ] `pytest` passes
+- [ ] `npm --prefix frontend run typecheck` passes
+- [ ] `npm --prefix frontend run build` succeeds
+- [ ] Manually exercised the affected flow
+
+## Notes for reviewers
+
+<!-- Anything reviewers should know: tradeoffs, follow-ups, screenshots. -->

precursor_ai-2026.7.0/.github/copilot-instructions.md

@@ -0,0 +1,156 @@
+# Copilot / agent instructions for Precursor
+
+Use these notes to stay aligned with the project's conventions when working in
+this repo.
+
+## Architecture in one paragraph
+
+Single uvicorn process. FastAPI exposes a JSON API under `/api/*` and mounts
+the built React SPA at `/`. SQLAlchemy 2 (async) backs `Topic`, `Message`, and
+`AppSetting`. Chat replies stream from an LLM provider (`GitHubModelsProvider`
+or `MockProvider` fallback) over Server-Sent Events. Precursor is both an MCP
+server (exposes conversations) and an MCP client (attaches tool servers).
+Third parties extend the system via the `precursor.plugins` entry-point group
+plus a frontend extension registry.
+
+## Conventions
+
+### Tooling
+
+- **uv** is the Python toolchain — env, run, build, release. Prefer
+  `uv run <cmd>` (e.g. `uv run pytest`, `uv run ruff check .`) over a manually
+  activated venv, and `uv build` for wheels. `make` targets wrap these
+  (`make sync`, `make dev`, `make check`, `make wheel`). Don't reintroduce
+  `pip install` / bare `uvicorn` invocations in docs or scripts.
+
+### Python (backend)
+
+- Target **Python 3.12+**. Always use `from __future__ import annotations`.
+- Async everywhere DB or network is touched. Use `AsyncSession` from
+  `precursor.backend.db` via `Depends(get_session)`.
+- Pydantic v2 models in `schemas/`. Never return ORM objects with secrets
+  embedded — define a read model.
+- Settings come from `precursor.backend.config.get_settings()` (cached).
+  Don't read `os.environ` directly in routers.
+- Routers are thin; logic goes in `services/`.
+- When streaming responses, persist the assistant turn in a **fresh session**
+  (`async with SessionLocal() as ...`) because the request-scoped one may be
+  closed by the time the generator finishes — see `routers/chat.py`.
+
+### TypeScript (frontend)
+
+- React 19 + Tailwind. Components are function components with named exports.
+- Styling uses CSS variables for theme tokens; toggle dark mode by adding
+  `.dark` on `<html>` (see `lib/theme.ts`).
+- All HTTP goes through `src/lib/api.ts`. Streaming chat goes through
+  `src/lib/sse.ts` (we don't use `EventSource` because we POST a JSON body).
+- Keep type definitions in `src/lib/types.ts` mirrored to the Pydantic schemas.
+
+### Plugins
+
+- Backend plugins register via `[project.entry-points."precursor.plugins"]`
+  and a `register(registry)` callable.
+- Frontend extensions are *descriptors* served from `/api/plugins`; the SPA
+  matches them to renderers registered through `frontend/src/lib/plugins.ts`.
+- Don't grow core to host a single use case — write a plugin instead.
+
+## When making changes
+
+1. Update both the Pydantic schema **and** the TS `types.ts` for any API
+   change.
+2. When models change, generate a migration with `make migration m="…"`
+   (Alembic autogenerate), review it, and commit it. Alembic is the single
+   source of truth: `init_db` runs `alembic upgrade head` on startup for dev and
+   prod alike — there is no `create_all` or hand-written dev backfill.
+3. Keep comments to "why", not "what". Don't add docstrings to code you didn't
+   touch.
+4. **Assess documentation impact** — every user-facing change must update the
+   docs in the same PR (see [Documentation](#documentation) below). Treat "docs
+   updated" as part of the definition of done, not a follow-up.
+5. Run the quality gates (`make check`, listed in `CONTRIBUTING.md`).
+
+## Documentation
+
+**Documentation is part of every change, not an afterthought.** Before you call
+a change complete, explicitly assess what documentation it affects and update it
+in the *same* PR. If you conclude nothing needs changing, say so in the PR
+description so the assessment is visible.
+
+### Where documentation lives
+
+- **`README.md`** — the project's front door (motto, quick start, highlights).
+- **`docs/`** — in-repo deep dives (`architecture.md`, `plugins.md`, …).
+- **`website/`** — the VitePress showcase + docs site published to GitHub Pages
+  (`.github/workflows/pages.yml`, base path `/precursor/`):
+  - `website/index.md` — landing page hero + **feature grid**.
+  - `website/guide/` — getting started (installation, quick start, configuration).
+  - `website/features/` — **one page per feature**.
+  - `website/reference/` — stack, architecture, configuration, API, plugins.
+  - `website/contributing/` — contribution, workflow, releasing.
+  - `website/.vitepress/config.mts` — nav + sidebar registration.
+  - `website/public/screenshots/` — product screenshots (see below).
+- **`CHANGELOG.md`** — keep the `[Unreleased]` section current for any
+  user-facing change.
+
+### Decision checklist — what triggers a doc update
+
+| If your change… | …then update |
+| --- | --- |
+| Adds or changes a **user-facing feature** | the relevant `website/features/*.md` page (+ landing feature grid in `index.md` if it's a headline capability), and `CHANGELOG.md` `[Unreleased]` |
+| Adds a **new sidebar section / cockpit** | a new `website/features/<section>.md` **and** its sidebar entry in `config.mts` **and** the landing grid — mirroring the in-app wiring (`Sidebar.tsx`, `sections.ts`, and the **command palette**) |
+| Adds/renames/removes a **setting or env var** | `website/guide/configuration.md` and `website/reference/configuration.md` (and `.env.example` if env-level) |
+| Adds/changes a **slash command** | the surface's feature page (e.g. `/reminder` on `features/scheduler.md`) and `frontend/src/lib/commands.ts` stays the source of truth |
+| Changes the **API** (routes, schemas, SSE events) | `website/reference/api.md` and the architecture request-flow notes |
+| Adds a **built-in MCP server / provider** | `website/features/mcp.md` / `website/reference/architecture.md` |
+| Changes **installation / run** steps | `README.md`, `website/guide/installation.md`, `CONTRIBUTING.md` |
+| Is **experimental / untested** | mark it clearly as WIP (e.g. a `::: warning` admonition), don't present it as stable |
+
+### Exposing a new feature on the site
+
+1. Write `website/features/<feature>.md` (mirror the tone of the existing pages:
+   a one-line intent, a `<Screenshot>` if it has UI, then how it works).
+2. Register it in the sidebar (`website/.vitepress/config.mts`) and, for a
+   headline capability, add a card to the feature grid in `website/index.md`.
+3. Cross-link from related pages (e.g. a scheduler feature links to MCP guards).
+4. Add a `CHANGELOG.md` `[Unreleased]` entry.
+
+### Screenshots
+
+Screenshots live in `website/public/screenshots/` and are **theme-aware**: each
+has a light file (`foo.png`) and a dark file (`foo-dark.png`); the `<Screenshot>`
+component derives the `-dark` variant and swaps by site theme. **When a UI change
+alters a screenshotted screen, retake both variants.**
+
+Capture rules (keep them consistent and privacy-safe):
+
+- Run a **seeded demo instance** with the **account hidden** — no resolvable
+  GitHub token, so the persona shows "Guest / Not connected" (never a real
+  account/avatar). Reuse the demo fixtures (the `precursor-demo` repo + Project
+  board) rather than real data.
+- **Fake missing config** (e.g. a dummy Speech key, disabled remote MCP servers)
+  so shots have **no error/warning banners** — never use real secrets.
+- Capture **both** `colorScheme: light` and `dark` at `deviceScaleFactor: 2`,
+  writing `foo.png` and `foo-dark.png`.
+- **Clip** to the relevant pane when the sidebar/persona footer would leak the
+  account.
+- Reference the new file from a page via
+  `<Screenshot src="/screenshots/foo.png" alt="…" caption="…" />` (light path
+  only — the component finds the dark one).
+
+### Verify before you finish
+
+- Build the site: `cd website && npm run docs:build` — it must pass (checks
+  broken component usage and, effectively, that referenced pages exist).
+- Sanity-check new nav/sidebar links resolve and every referenced screenshot
+  (both variants) exists.
+
+## What *not* to do
+
+- Don't add new top-level dependencies without flagging it in the PR.
+- Don't introduce a Node.js runtime requirement in production — the SPA must
+  be pre-built and served by FastAPI.
+- Don't echo secret values (API tokens) in API responses. Use the
+  `api_keys_present` boolean pattern from `schemas/settings.py`.
+- Don't hardcode the version anywhere — it's CalVer from git tags via hatch-vcs
+  (read `precursor.__version__`). See `RELEASING.md`.
+- Don't add unrelated refactors to a feature PR.

precursor_ai-2026.7.0/.github/dependabot.yml

@@ -0,0 +1,44 @@
+version: 2
+updates:
+  # Python deps (uv-managed; Dependabot reads pyproject.toml).
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+    # Only raise a floor in pyproject.toml when the latest release no longer
+    # satisfies it (e.g. a real breaking floor) or for a security advisory.
+    # Routine minor/patch releases that already satisfy our coarse `>=` floors
+    # produce no manifest PR — the lockfile stays the source of exact versions.
+    versioning-strategy: increase-if-necessary
+    groups:
+      # Group only minor/patch bumps; majors get their own PR so a breaking
+      # upgrade is never bundled with safe ones.
+      python-minor-patch:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+
+  # Frontend deps.
+  - package-ecosystem: npm
+    directory: "/frontend"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+    # Same intent as the pip ecosystem: don't churn package.json for bumps the
+    # existing range already allows; only widen/raise when actually required.
+    versioning-strategy: increase-if-necessary
+    groups:
+      # Group only minor/patch bumps; majors (e.g. Tailwind v4, Vite, TS) get
+      # their own PR so each migration is reviewed in isolation.
+      frontend-minor-patch:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+
+  # GitHub Actions used by the CI / release workflows.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]

precursor_ai-2026.7.0/.github/prompts/release.prompt.md

@@ -0,0 +1,51 @@
+---
+mode: agent
+description: Cut a CalVer release — pick the version, promote the changelog, tag, push, and verify the GitHub Release.
+---
+
+# Tag a release
+
+Cut a CalVer release of Precursor. The version is **derived from the git tag**
+by hatch-vcs — there is no literal to bump. Full reference: `RELEASING.md`.
+
+## Preconditions
+
+- `main` is the source of truth and CI is green on it. Confirm with
+  `git switch main && git pull` and `gh run list --branch main --limit 1`.
+- The working tree is clean.
+
+## Steps
+
+1. **Pick the version (CalVer `YYYY.M.MICRO`).**
+   - `YYYY` = current year, `M` = current month **without leading zero**,
+     `MICRO` = release counter **within that month**, starting at `0` and
+     resetting to `0` on the first release of a new month.
+   - Inspect existing tags (`git tag --list 'v*' | sort -V`) to choose the next
+     value. Example: after `v2026.6.0` in June → `v2026.6.1`; first July release
+     → `v2026.7.0`.
+2. **Promote the changelog.** In `CHANGELOG.md`, rename the `[Unreleased]`
+   section to a dated release heading — `## [<version>] - YYYY-MM-DD` — and open
+   a fresh empty `[Unreleased]` above it. Commit on `main` (or via a quick PR if
+   `main` is protected): `docs(changelog): release <version>`.
+3. **Sanity-check the build version.** `uv build --wheel` and confirm the wheel
+   filename encodes the intended version (or `uvx hatch version`). A clean
+   checkout on the tag must yield exactly `<version>`.
+4. **Tag and push.** The leading `v` is required (the release workflow triggers
+   on `v*`):
+   ```bash
+   git tag v<version>
+   git push origin v<version>
+   ```
+5. **Verify the release.** Watch `release.yml`
+   (`gh run watch` on the tag's run). On success, confirm the GitHub Release
+   exists with the wheel + sdist assets and auto-generated notes
+   (`gh release view v<version>`). Report the release URL.
+
+## Guardrails
+
+- Never edit a version literal — if you find one, that's a bug; flag it.
+- Don't delete or move a tag once pushed (it's published). To fix a bad release,
+  cut a new patch (`MICRO + 1`).
+- If the build's version doesn't match the tag, stop — the release job's own
+  guard will fail; investigate hatch-vcs / git history (shallow clone? missing
+  tags?) before retrying.

precursor_ai-2026.7.0/.github/prompts/ship-change.prompt.md

@@ -0,0 +1,39 @@
+---
+mode: agent
+description: Ship a focused code change — run gates, branch, conventional commit, open a PR, and confirm CI.
+---
+
+# Ship a code change
+
+Drive a code change from working tree to an open, green PR. Follow the repo
+conventions in `.github/copilot-instructions.md` and `CONTRIBUTING.md`.
+
+## Steps
+
+1. **Scope check.** Summarize what changed (`git status`, `git diff --stat`).
+   If the change mixes unrelated concerns, stop and ask whether to split it.
+2. **Quality gates.** Run `make check` (ruff, ruff format --check, mypy,
+   pytest, frontend typecheck + build). Fix anything red before continuing —
+   never commit with failing gates, and don't bypass them.
+3. **Update docs/changelog if user-facing.** If the change affects behavior,
+   add a bullet to the `[Unreleased]` section of `CHANGELOG.md`. If it changes
+   an API, update both the Pydantic schema and `frontend/src/lib/types.ts`.
+4. **Branch.** Create a branch off `main` named for the change:
+   `feat/<slug>`, `fix/<slug>`, `chore/<slug>`, or `docs/<slug>`.
+5. **Commit.** Stage intentionally (never `.env`, `frontend/dist`,
+   `precursor/_version.py`, or the dev DB — verify with `git status`). Use a
+   **Conventional Commits** message: `type(scope): summary`, with a body
+   explaining the *why*.
+6. **Push & PR.** Push the branch and open a PR with `gh pr create` using the
+   repo PR template; reference the issue with `Closes #N` when applicable. If
+   `main` isn't on the remote yet, push it first.
+7. **Confirm CI.** Watch the PR checks (`gh pr checks`); if a check fails, fetch
+   the log (`gh run view --log-failed`), fix on the same branch, and push again.
+   Report the PR URL and final check status.
+
+## Guardrails
+
+- Do not force-push, merge, or tag as part of this workflow — only open the PR.
+- Keep the diff minimal and on-topic; no drive-by refactors.
+- If a gate reveals pre-existing repo-wide debt unrelated to the change, flag it
+  rather than fixing it here.

precursor_ai-2026.7.0/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel superseded runs on the same ref to save CI minutes.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  backend:
+    name: Backend (lint · types · tests)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # Full history + tags so hatch-vcs can resolve the CalVer version.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Mypy
+        run: uv run mypy precursor
+
+      - name: Pytest
+        run: uv run pytest -q
+
+  frontend:
+    name: Frontend (typecheck · build)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Build
+        run: npm run build

precursor_ai-2026.7.0/.github/workflows/pages.yml

@@ -0,0 +1,61 @@
+name: Deploy website
+
+# Build the VitePress showcase + docs (website/) and publish it to GitHub Pages
+# on every push to main. Enable Pages once under Settings → Pages → Source:
+# "GitHub Actions".
+on:
+  push:
+    branches: [main]
+    paths:
+      - "website/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+# Least-privilege token that can publish to Pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; don't cancel an in-progress publish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build site
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: website
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build with VitePress
+        run: npm run docs:build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/.vitepress/dist
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4