Development Setup#
Everything you need to get an Osprey checkout building and testing on your machine, and the standards your change is held to once it does.
Environment Setup#
Prerequisites: Python 3.11+, Git, a GitHub account, and uv.
The check command in step 4 also needs Node.js with npm, for the
front-end checks, and Claude Code at the version this tree pins, for the test sweep.
uv run python scripts/pinned_claude.py --pin prints that version. A binary of the
pinned version at ~/.local/share/claude/versions/<pin> is found beside the
claude on your PATH, so you do not have to replace the one you use.
Building the docs also needs Graphviz (the dot command).
1. Fork and Clone
git clone https://github.com/YOUR-USERNAME/osprey.git
cd osprey
# The package versions come from the upstream release tags: the framework's
# v* and osprey-connectors' own osprey-connectors-v* tags. A fork or mirror
# that lacks them builds osprey-connectors as 0.0.postN.
git remote add upstream https://github.com/als-apg/osprey.git
git fetch --tags upstream
2. Install Dependencies
# Install all dev and docs dependencies (creates .venv automatically)
uv sync --extra dev --extra docs
# Add a new dependency
uv add <package>
3. Set Up Pre-commit Hooks
uv run pre-commit install
Hooks auto-fix formatting and prevent commits with common problems.
4. Verify Installation
uv run python scripts/check.py quick
This runs the quick tier of the merge gate: lint, format, type and import
checks, and the parallel test sweep. The sweep selects tests from the same
declaration as CI’s unit lane, and leaves out the tests marked slow.
Before any check runs, the command puts the tree’s pins in place: it runs
npm ci when node_modules differs from package-lock.json, and puts the
pinned Claude Code first on PATH. When a tool it needs is missing, it runs
nothing and names what to install. The last line is the verdict. When it says
the run is clean, you are ready to contribute.
Code Standards#
Design Principles#
Before designing a new connector, MCP server, provider, capability, or any
non-trivial feature, consult OSPREY’s design and architecture principles – the
safe-state default, facility-neutral core, measured symmetry with peer
subsystems, swappable components, and discoverable user-facing features.
The /osprey:design-philosophy skill applies them as the OSPREY agent
designs and reviews with you. It ships in the osprey plugin; installing it
is on Agent Skills.
The principles guide decisions; they are not mechanical rules. When a change feels wrong but the reason is hard to name, they help you name the drift and correct it before you open the PR.
Principle 8, where two lines of work meet, design from the end product,
applies to every merge and conflict resolution, and to every plan or spec
written against an older tree. In its own words: at such a point the question
is never “how do these two combine” but “what does the finished OSPREY need
here”. The /osprey:design-philosophy skill carries the principle in full.
Python Style#
We follow PEP 8 with Ruff enforcement:
Line length: 100 characters
Type hints: Gradual typing enforced with mypy
Docstrings: Google style
Classes: PascalCase, Functions: snake_case, Constants: UPPER_SNAKE_CASE
Hygiene: Ruff also judges debug prints in shipped code, debugger calls, commented-out code, quoted credentials outside tests and work markers without a link; a deliberate exception is a
# noqa: CODE -- reasonon its line, or a# ruff: noqa: CODE -- reasonat the top of a program module
Import organization: standard library, then third-party, then local (from osprey...).
Linting and Formatting#
# Lint and format
uv run ruff check .
uv run ruff format .
# Auto-fix lint issues
uv run ruff check --fix .
# Type checking
uv run mypy
# All of the above as checks, with the fast tests
uv run python scripts/check.py quick
The type check must report zero errors. uv run mypy prints the full report over the
declared trees. CI and both tiers of scripts/check.py run the same check through
scripts/mypy_gate.py, which fails on any error and refuses a run made without the stub
packages the dev extra declares (fix: uv sync --extra dev). There is no list of
tolerated errors: an error is fixed where it is reported.
The check’s targets are declared in pyproject.toml: it covers the framework source
and the connectors package together, and the gate reads that same list, so CI and a local
run check the same trees. A run that names a single file is for a quick look only — it
resolves less than the full run and reports errors the full run does not.
Testing#
All new functionality must include tests.
Type |
When to Use |
Cost/Speed |
|---|---|---|
Unit |
Pure functions, business logic, utilities |
Fast, no external dependencies |
Integration |
Component interactions, API endpoints |
Medium |
E2E |
Critical user flows, deployment validation |
Slow, requires API keys ($0.10-$0.25/run) |
Browser |
Real-browser page loads, theming, JS module loading (Playwright + Chromium) |
Slow; needs Chromium (auto-installed in CI, skips locally if absent) |
Running tests:
# The unit sweep, as CI's unit lane selects it (no API keys required)
uv run python scripts/check.py run pytest -- -n auto
# Single test file
uv run pytest tests/path/to/test_file.py -v
# Single test function
uv run pytest tests/path/to/test_file.py::test_function_name -v
# E2E tests (requires API keys) -- MUST use path, NOT marker.
# Name the provider: a run that names none is refused before the first test
# when it selects a test not marked model_free.
# Sync the extras the suite reaches for too -- the chat-bridge modules skip
# themselves without theirs, which looks like a pass.
uv sync --extra dev --extra teams --extra gchat --extra virtual-accelerator
OSPREY_E2E_PROVIDER=als-apg uv run pytest tests/e2e/ -v
# The e2e tests that reach no model need no provider.
uv run pytest tests/e2e/ -m model_free -v
# Browser smokes (Playwright + Chromium; skips if the browser is absent)
uv run pytest tests/interfaces/ -m browser -v
# With coverage
uv run python scripts/check.py run pytest -- -n auto --cov=src/osprey
Front-End (JavaScript) Testing#
Front-end code (static/js/ under each src/osprey/interfaces/<name>/) gets
its own dev/CI-only Node toolchain – tsc --noEmit for types and
Vitest for unit tests. Neither is needed to install or
run Osprey; both run only in dev and CI, the front-end analogues of mypy
and pytest.
# Type-check every front-end file tsconfig.json includes
npm run typecheck
# All Vitest units (happy-dom, no real browser)
npm run test:js
# A single Vitest file
npx vitest run tests/interfaces/artifacts/preview.test.mjs
A front-end change is covered by up to five rails, narrowest/fastest to broadest/slowest:
Rail |
Covers |
Run |
|---|---|---|
Vitest unit |
Pure logic in one module: mocked |
|
Loads-clean |
Page boots in a real browser with no uncaught JS exception and no failed same-origin script/stylesheet fetch |
|
Contract |
Shell<->panel chrome contract: |
|
Visual |
Pixel-level screenshot diff per interface x theme against a committed baseline PNG |
|
Interaction pin |
A real user flow through a real browser and a real backend, proving a multi-module wiring didn’t drop a call across a split – the one net a per-module Vitest suite (which mocks its neighbors) cannot cast |
|
Warning
test_visual.py is marked slow, not browser – an
-m browser selector silently matches zero of its cases. Select it with
-k <target-name> (or run the file directly) instead.
What a new panel or extracted module must ship with:
Full JSDoc (
@param/@returns) on anything the module exports.tsconfig.jsonsetscheckJs: true, so every file itsincludeglobs match is type-checked from the moment it lands – there is no per-file opt-in. Most modules still carry a// @ts-checkline at the top; it is a house habit now, not a switch, and leaving it off does not exempt a file fromnpm run typecheck.A Vitest file, one-to-one by name (
foo.js->foo.test.mjs), covering the module’s pure logic and DOM-visible behavior in isolation.If the module is wired into a page: a
test_load_smokes.pyentry for that page, so a broken import or a typo’d export name surfaces as a real thrown exception instead of a silent no-op.If it’s a panel (embedded in the Web Terminal hub):
applyEmbedded()on load, which also sends a direct visit to the hub; no page chrome of its own, since the hub owns theme and header – plus atest_contract_params.pycase, which is the up-to-date spec for the embedding checklist and well-known parameters. See Panels for how panels embed in the hub.If the change is visible on screen: a
test_visual.pyTARGETSentry and a committed baseline PNG (regenerate with--regen-baselineson Linux/CI – a baseline captured on macOS will mismatch there).If the change moves real behavior across a module boundary (a callback that used to call a sibling directly now goes through an injected factory, a delegator, or a re-exported method): an interaction pin that drives the whole chain through a real browser, not just each module’s own mocked-neighbor Vitest suite.
JSDoc / cast conventions (src/osprey/interfaces/vendor-globals.d.ts and
the exemplars below have worked examples):
Vendored classic-script globals that never get real npm types (Plotly,
marked,hljs, KaTeX) get one shared ambient-declarations file (vendor-globals.d.ts,declare const X: any;) rather than a per-call-site cast.A
document.getElementById/querySelectorresult that needs a property the genericElement/HTMLElementtype doesn’t have (.value,.checked,.dataset,.disabled) gets an inline type-assertion cast to the concrete element type at the call site –/** @type {HTMLInputElement} */ (document.getElementById("foo")).For
querySelectorAll(...).forEach(callback)where the callback needs a narrower element type thanElement: cast the collection, not the per-item callback parameter. TypeScript’s contravariant function-parameter checking rejects a callback typed to accept onlyHTMLInputElementwhere one accepting anyElementis expected, even thoughHTMLInputElementnarrowsElement.catch (e)blocks that read the error message usee instanceof Error ? e.message : String(e)(eisunknownunderstrict); acatchthat only logs the raw value needs no cast.Shared design-system helpers are imported by the absolute
/design-system/js/*specifier, mapped in bothtsconfig.jsonandvitest.config.js’sresolve.alias– the same import path resolves under the type-checker, Vitest, and the real browser.Shared visual parts (surface tokens, sidebar rows, popovers, the tooltip layer, icons) come from the design system, not from a local copy. Design Language gives the rules and the list of primitives.
Exemplars (concrete, complete, worth reading before writing your own):
Vitest unit, factory-with-injected-callbacks pattern:
tests/interfaces/artifacts/preview.test.mjs,tests/interfaces/web_terminal/scaffold/detail.test.mjs.Interaction pin, proving a multi-module split still wires up end to end:
tests/interfaces/artifacts/test_gallery_interactions.py,tests/interfaces/web_terminal/test_scaffold_detail.py,tests/interfaces/web_terminal/test_session_page.py.Contract + dual-mode chrome:
tests/interfaces/web_terminal/test_contract_params.py.Visual baselines:
tests/interfaces/design_system/test_visual.py.Loads-clean:
tests/interfaces/test_load_smokes.py.
Docstrings#
All public functions, classes, and methods need Google-style docstrings:
def capability_function(param1: str, param2: int) -> bool:
"""Short description of function.
Args:
param1: Description of first parameter.
param2: Description of second parameter.
Returns:
Description of return value.
Raises:
ValueError: When parameter is invalid.
"""