Contributing to Taskuary

Thanks for helping build the local-first way to automate your job. Small, focused PRs are the fastest path to merge — a new report connector is ~15 lines and the single best first contribution.

Dev setup

git clone https://github.com/ldbumble/taskuary && cd taskuary
pip install -e ".[dev,mssql,desktop]"     # dev = pytest; extras optional
python -m pytest -q                        # the whole suite runs offline in ~2s
taskuary --debug                           # run the server with debug logging

UI work needs Node 20+ (build-time only — users never need node):

cd website && npm ci
npm run build        # builds into taskuary/web/ (COMMIT the built assets)
node render_check.mjs http://127.0.0.1:7787   # headless smoke: every tab, zero console errors

The headless checks drive Microsoft Edge through puppeteer-core (a devDependency — no browser is downloaded). website/shot_*.mjs regenerate the README screenshots against a demo dataset: TASKUARY_HOME=/tmp/demo python website/seed_demo.py, start the server on that home, then node website/shot_timeline.mjs http://127.0.0.1:7787. If Edge lives somewhere else on your machine, edit the executablePath at the top of the script.

Repo map

path	what lives there
taskuary/live.py	one WebSocket bus — Timeline/Board/Studio refetch on feed-changed / task-changed / run-tail
taskuary/store.py	SQLite store — schema, seeds, one dict-shaped contract (MemoryStore for tests)
taskuary/testing.py	picture factory for regression tests — named Timeline/Board states, inbound() for ingest
taskuary/ingest.py / triage.py / routing.py / policy.py	the funnel: dedupe → policy → route → AI triage
taskuary/agents.py / coder.py	CLI agents: live-streamed runs, diffs, the coder report contract
taskuary/channels.py	Outlook / Teams / Slack / GitHub connectors + live Test probes
taskuary/reports.py	scheduled report executors (start here — see below)
taskuary/llm.py	AI connectors (Anthropic / OpenAI / Azure) → one llm(system, user) callable
taskuary/server.py	the FastAPI API
Dockerfile / docker-compose.yml	the no-Python-on-the-host path
website/src/	React 18 + MUI 6 UI (Vite)
tests/	offline unit tests — no network, no credentials

The 15-line contribution: a report connector

Every type in the "planned" list (postgres, google_sheets, snowflake, prometheus, jira, …) is one function away. In taskuary/reports.py:

def run_postgres(cfg):
    """{"dsn", "query"} - rows from a Postgres query."""
    import psycopg
    with psycopg.connect(cfg['dsn']) as cx:
        rows = cx.execute(cfg['query']).fetchall()[:20]
    body = '\n'.join(str(r) for r in rows)
    return f'{len(rows)} rows', body[:4000]

Then: add it to REGISTRY, remove it from PLANNED, add its fields to FIELDS in website/src/ReportsView.jsx, keep any heavy import inside the function (optional dependency), and add one offline test (see test_report_schedule_and_run). Done — the Reports wizard, scheduling, AI summaries, and the Timeline all work automatically.

Ground rules

• Tests must pass offline. python -m pytest -q uses MemoryStore and mocks — never real credentials or network. New behavior needs a test.
• Timeline / Board / Review chips get a named picture. taskuary.testing.Factory builds the graph the JOINs actually show (pending_draft, running, filed_fyi, old_done, ...). Pin the chip in tests/test_factory.py; do not INSERT a bare task row and hope the feed agrees. Ingest tests use inbound() (the dict ingest_message accepts). Load a realistic db with python -m taskuary.testing desk or load 2000 against TASKUARY_HOME (docker compose --profile regression run --rm desk seeds a separate taskuary-regression volume, never the live taskuary-data). The CLI refuses a home that already has tasks unless you pass --force.
• Match the code style you see — dense, screen-fitting, comments say why not how. Don't run black/autopep8; there is no format check on purpose.
• taskuary/web/ is generated — never hand-edit it; rebuild from website/ and commit the output.
• UI changes: run render_check.mjs and include a screenshot in the PR.
• Update the README when behavior users can see changes.
• CI runs the suite on Ubuntu/Windows/macOS × Python 3.10/3.12 on every push and pull request (the web build and Docker image smoke too; the exe is push-to-master only). Green CI is required to merge. A first pull request from a fork sits on Waiting for approval until a maintainer clicks Approve and run workflows — that is GitHub's default for outside collaborators, not a missing pull_request trigger.

Reporting bugs & proposing features

Use the issue templates. For bugs, taskuary --debug and the log at ~/.taskuary/taskuary.log usually contain the answer — paste the relevant lines.