Skip to content

The Build Loop

Every stk command lives under stk. Run stk --help to see them grouped by purpose.

Terminal window
uv run stk --help

Prefer bare stk? Activate the venv once per shell:

Terminal window
source .venv/bin/activate
stk run
Terminal window
uv run stk doctor
✓ env file .env
✓ app myapp.app:app
✓ secrets SECRET_KEY and password salt look random
✓ database sqlite stk.db (124 KiB)
! migrations database is behind: stk_0002 not applied
→ uv run stk db upgrade
✓ admin user 1 admin(s)
✓ assets vue 3.5.40 vuetify 4.1.6
✓ agent login disabled
✓ overrides no copies of stk files
✓ browser chromium ready for stk smoke
✓ shell ptpython: highlighting and completion
Usable, with the warnings above.

overrides warns about each app template or static file that replaces one of stk’s whole (a copy that no longer receives stk’s fixes). Templates that extend stk/<name>, _brand.html, _head.html, index.html, dashboard.html, static/css/app.css, and images are meant to be replaced and pass.

Every line that is not ✓ tells you the command that fixes it. A ! is a warning, a ✗ is a failure, and the exit code is 1 only on a failure, so it works in scripts. --json for tooling.

Terminal window
uv run stk new invoice

NAME is a lowercase snake_case identifier. This writes an extension package into your app (myapp/invoice/: model, views, template, and an init_app that registers the blueprint and its sidebar entry), adds it to extensions in myapp/app.py, generates the migration for the new model in the app’s lineage, applies it, and then tells you where to look. It never touches stk’s files:

Open: http://localhost:5000/invoices/ (start it with: stk run)

Pass --no-migrate if you would rather write the migration yourself, and --port if your dev server is not on 5000.

Terminal window
uv run stk verify --watch

It checks everything once, then polls for saved files and re-runs only what the change can break. A .py edit re-runs ruff, the sanity checks, and migration drift; a template, JS, or CSS edit re-runs only the sanity checks.

changed: myapp/invoice/models.py
✗ migration-drift
add_column: invoice due_date
→ uv run stk db revision -m "describe change" && uv run stk db upgrade
✓ ruff
✓ checks

Leave it in a split pane. You find out the moment you break something, not ten minutes later, and the fix is on screen.

Terminal window
uv run stk smoke

Boots a throwaway app on a free port against a temporary database, drives Chromium through the home page, login, dashboard, and admin users page, then visits every other GET page that takes no URL arguments. It fails on any of: an HTTP status of 400 or above, a console or uncaught error, a failed request, or button, chip, and alert text below 3:1 contrast with its background. That last one catches the class of bug no console error ever reports. Each page leaves a full-page screenshot in .stk/smoke/, named after it (dashboard.png, /monitor/runs as monitor-runs.png), and each run clears the last run’s. The signed-in pages then run again in the dark theme, with the same checks except copy, as dashboard dark with dashboard-dark.png, because a colour that only breaks in one theme passes in the other. --json emits the per-page report, with each page’s screenshot path.

Smoke also fails on a page that works but reads badly. It reads the visible text of each page (not scripts, styles, hidden elements, input values, or code and pre blocks) and flags:

Rule Catches
uuid A uuid where a name belongs
hex-id A raw id or hash fragment, such as Request 1fbaac41; a run labelled SHA-256: or hash passes, and so does a mixed-case name such as Ed25519
snake-case A storage token such as pending_review instead of words
raw-score A decimal after score, similarity, confidence, distance, or cosine
one-plural A count of 1 with a plural noun, such as 1 items
broken-value undefined, null, NaN, or [object Object] printed as a value
repeated-row The same row three or more times in one list

Each finding prints as reads badly: <rule> '<text>' under its page, and --json lists them in the page’s copy array as {rule, text}. When the text is deliberate, add a regex for it to STK_SMOKE_COPY_ALLOW on your app’s Config; a finding whose text matches any entry passes:

class Config(stk.Config):
STK_SMOKE_COPY_ALLOW = (r"Ed25519",)

An empty database renders every list as its empty state, so a template that breaks only on a row (a missing method in a v-for, a field that is sometimes null) passes. Give the app one seed.py next to app.py:

async def run(session):
from myapp.invoice.models import Invoice
session.add_all(Invoice(name=f"Sample invoice {n}") for n in range(1, 4))

stk smoke runs it on its temporary database after migrations, locally and in CI, so every page renders with the same rows each time. uv run stk db seed adds the same rows to your dev database. It runs inside the app context and commits after run; it does not clear tables, so run it on a fresh database. stk new writes seed.py with three rows of its model when the app has none, and leaves an existing one to you. Seed every state a page branches on (an item waiting for review, an assigned one), since smoke only sees what the seed creates. Without seed.py, smoke says it ran on an empty database and --json reports "seeded": false.

Smoke needs Playwright’s Chromium. stk doctor tells you if it is missing.

Terminal window
uv run stk verify && uv run stk smoke
uv run stk report # docs/stk-report.html: routes, auth, gate results

stk verify runs ruff, the sanity checks in stk/checks.py against your app, and migration drift, and exits 1 if any fail. Each failure prints its reason and a remedy. In stk verify --json, the checks entry also carries results: one {name, status, detail} per sanity check, so a tool or agent reads which check failed and why without parsing text. CI runs both stk verify --json and stk smoke --json (after the unit tests), so the pair above is the same gate locally. stk report --json prints the routes and verify results instead of writing HTML, and -o picks another output path.

stk verify and stk smoke are the gate for everything. Some changes need one more look:

You changed Also run
Templates, JS, or CSS uv run stk smoke, then look at the screenshot with real rows
Models uv run stk db check and uv run stk db current
Routes or auth uv run stk inspect routes --json, then uv run stk report
Anything with logic uv run python -m unittest discover -s tests

A 200 response and green tests do not prove that columns, labels, or buttons render. Look at the page.

Test configs subclass TestingConfig from stk/settings.py, not Config: .env loads at import, and TestingConfig pins the database, sessions, mail, OAuth, rate limits, and agent login so a developer’s settings never reach a test. Pin anything else your test depends on. Never name a test method run: on IsolatedAsyncioTestCase it replaces TestCase.run and the class silently runs nothing. Run a new test once by its full name and see it reported.

To stop a dev server, stop the process on its port (lsof -tiTCP:5000 -sTCP:LISTEN | xargs kill), not a process name pattern that can match another checkout’s server.

Agents and scripts that drive a browser can skip the login form with a short-lived token:

Terminal window
STK_ENV=development STK_ENABLE_AGENT_LOGIN=1 uv run stk browser-token create --user admin@example.com --ttl 60 --next /dashboard/

Open the printed /_test/login?token=... path: it creates a normal session and redirects to --next. The route exists only when all of these hold, and startup fails if it is enabled anywhere else:

  1. STK_ENABLE_AGENT_LOGIN=1
  2. STK_ENV=development, or the app is in testing mode
  3. the token is signed and younger than STK_AGENT_LOGIN_MAX_TTL_SECONDS
  4. the user’s email ends in @example.com

stk smoke uses the same route with a throwaway smoke@example.com admin.

Terminal window
uv run stk doctor # am I ready?
uv run stk new invoice # scaffold to a clickable URL
uv run stk verify --watch # instant feedback while editing
uv run stk smoke # real browser before shipping