Skip to content

development.md

Latest commit

 

History

History
100 lines (78 loc) · 3.09 KB

development.md

File metadata and controls

100 lines (78 loc) · 3.09 KB
Raw

Development

Requirements

  • Python 3.11 or newer;
  • uv 0.12 or newer;
  • Bun 1.3 or newer for Studio;
  • Git.
uv sync --all-extras --locked
cd apps/studio && bun install --frozen-lockfile

Run Studio

Build the static frontend once, then start the local application process:

cd apps/studio && bun run build && cd ../..
uv run termkit studio examples/packs/demo-hydraulics

For frontend iteration, run bun run dev in apps/studio and the Python server separately. Set TERMKIT_STUDIO_DIST only when testing a non-default static distribution. Studio binds to loopback unless --allow-remote is explicitly provided; that override does not add authentication.

Required checks

uv run ruff check .
uv run mypy src
uv run python scripts/export_schemas.py --check
uv run pytest --cov
cd apps/studio
bun run check
bun run test
bun run build
bun x playwright install chromium  # first run only
bun run test:e2e
cd ../..
uv run python scripts/embed_studio_assets.py --check
uv build

Python tests are offline and use tmp_path for workspaces, registries, archives, imports and runtime indexes. Browser tests must use original fixture data and a temporary copy of a canonical pack.

Schema workflow

TermSpec model changes require:

uv run python scripts/export_schemas.py
uv run python scripts/export_schemas.py --check
git diff -- src/termkit/spec/schemas

Then update CHANGELOG.md, compatibility notes, fixtures, and an ADR when identity, lifecycle or semantic meaning changes.

Workspace persistence changes require a new Alembic revision. Never edit an already released migration to make a current test pass. Test both a fresh database and an upgrade path.

Frontend ownership

apps/studio is a static React application. It may format view state but must not duplicate evidence sufficiency, rights, review or release decisions from the Python application layer. API writes create ChangeSets; no browser code writes JSONL.

Use TanStack Query for server state, TanStack Table/Virtual for dense data, and Radix primitives for accessible overlays. Preserve keyboard navigation, visible focus, resizable panes and non-card list density. Do not introduce an admin dashboard theme, chat-first surface or decorative AI language.

Release rehearsal

uv run termkit validate examples/packs/demo-hydraulics
uv run termkit pack build examples/packs/demo-hydraulics --output /tmp/termkit-dist
uv run termkit pack verify /tmp/termkit-dist/*.termpack
uv run termkit runtime compile \
  --pack examples/packs/demo-hydraulics \
  --output /tmp/termkit-dist/demo.termdb \
  --lock-output /tmp/termkit-dist/termkit.lock
uv build

Build artifacts, .termkit/, downloaded corpora, private source material and credentials must remain untracked.

src/termkit/studio_assets/ is the one intentional generated exception: it is the reproducible, source-map-free Studio build shipped inside Python wheels. After a frontend change, run uv run python scripts/embed_studio_assets.py and review both the source change and the refreshed asset hashes. CI rebuilds Studio and rejects stale embedded assets.