stkit 17.0.0__py3-none-any.whl

stk/scaffold/app/claude/skills/stk-lessons/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: stk-lessons
+description: |
+  Log and triage lessons: failures the stk docs did not warn about. Use right after a gotcha costs real time (log one line and continue), when asked to triage or review lessons, or when given a lessons file from an app built on stk.
+argument-hint: "[log <lesson> | triage [path]]"
+---
+
+# stk lessons: $ARGUMENTS
+
+A lesson is worth keeping only if it changes what the next agent does. The best home
+makes the mistake impossible; a line of prose is the weakest home.
+
+Inbox: !`grep -cs '^- ' .stk/lessons.md || true` untriaged lessons in `.stk/lessons.md`.
+
+## Log (during any task)
+
+Append one line to `.stk/lessons.md`, in its format, when all of these hold:
+
+- you hit it in this run and it cost real time: a retry, a wrong turn, a green check that lied
+- the docs, `CLAUDE.md`, and skills did not warn you
+- it would bite another task, not only this one
+
+Use your own words. No secrets, customer data, or text copied from pages and logs. At
+most three per run. Append and continue the task; never stop it to log.
+
+## Triage (only when the user asks)
+
+Input: `.stk/lessons.md`, or the path the user gives.
+
+1. **Drop what is covered.** Search the docs (https://docs.stk.dev), `CLAUDE.md`, the skills, and
+   `stk/checks.py`. A lesson that recurs despite an existing rule means the rule sits too low:
+   move it up the ladder below instead of repeating it.
+2. **Drop one-offs**: a single occurrence with no general cause.
+3. **Confirm in code.** Reproduce it, or point at the line that allows it. Leave an
+   unconfirmed lesson in the inbox with `unconfirmed` appended.
+4. **Route** each survivor to the highest home that holds:
+   1. a code default that makes the mistake impossible
+   2. a check in `stk/checks.py`, so `stk verify` fails on it
+   3. a hint in `stk/cli/doctor.py`, so `stk doctor` names it with its fix
+   4. one line on the docs page for its topic
+   5. a step in the skill for that workflow
+
+   In an app, these are stk's homes: route app lessons to the app's own code, a test,
+   its `CLAUDE.md`, or its skills, and stk lessons to Upstream below.
+5. **Propose** one table: lesson, home, exact diff, and the test or check that fails
+   without the change. Apply nothing until the user approves each row.
+6. **Apply** the approved rows, then `uv run stk verify`. Size budgets cap `CLAUDE.md` at
+   8KB and skills at 4KB: when one breaks, cut or move detail into a docs page, never
+   raise the budget. Delete the processed lines from the inbox.
+
+## Upstream
+
+In an app built on stk, some lessons are about the framework, not the app. List those
+separately in generic terms: symptom, fix, and where it belongs in stk core. Strip
+product names, data, and paths. Hand the list to the user; never open an issue or
+send it anywhere yourself.
+
+Given such a file in the stk repository, run Triage with its path.

stk/scaffold/app/claude/skills/stk-migrate/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: stk-migrate
+description: |
+  Generate and review an Alembic database migration for stk. Use when adding or changing models, creating migrations, or managing database schema changes.
+argument-hint: "[description]"
+---
+
+# Generate Alembic Migration: $ARGUMENTS
+
+## Current state
+
+Current revision:
+!`uv run stk db current 2>&1 | tail -5`
+
+Recent migrations:
+!`ls -1t */migrations/*.py 2>/dev/null | head -10`
+
+Models with tables:
+!`grep -rn "__tablename__" */*/models.py 2>/dev/null`
+
+## Steps
+
+1. **Generate the migration:**
+   ```bash
+   uv run stk db revision -m "$ARGUMENTS"
+   ```
+
+2. **Review the generated file** in the app's `migrations/` (its own lineage; it already `depends_on` stk's head, so `stk db upgrade` applies both and heads never need merging). Check:
+   - All expected table/column changes are present
+   - Foreign keys reference correct tables and use correct column types
+   - Indexes are created where needed (especially on foreign keys and unique constraints)
+   - `downgrade()` correctly reverses `upgrade()`
+   - No destructive changes that would lose data. `stk verify` fails on drops, renames,
+     retypes, and NOT NULL adds without a default; a renamed field usually shows up as
+     drop + add, so rewrite it as `alter_column(..., new_column_name=...)` with a
+     `# destructive: <reason>` comment, and tell the user
+   - Column types match the model definitions (String lengths, nullable flags, defaults)
+
+3. **For SQLite compatibility**, verify batch mode is used. stk's `env.py` enables `render_as_batch` automatically for SQLite, but if writing manual SQL, wrap ALTER TABLE operations in `with op.batch_alter_table()`.
+
+4. **If the migration needs manual edits** (data migrations, complex constraints, multi-step operations):
+   - Edit the generated file directly
+   - Use `op.execute()` for raw SQL when needed
+   - Add data migration steps between schema changes
+
+5. **Test the migration:**
+   ```bash
+   uv run stk db upgrade    # apply
+   uv run stk db downgrade -1  # rollback
+   uv run stk db upgrade    # re-apply to confirm idempotency
+   ```
+
+6. **Run checks:**
+   ```bash
+   uv run stk verify
+   ```
+
+## Before you trust it
+
+Model conventions and the three SQLite traps (non-transactional DDL, NOT NULL needs
+`server_default`, named constraints) are in https://docs.stk.dev/models/. Check each exit code;
+never pipe a migration command to `tail`, and never delete a revision file before
+`uv run stk db downgrade <target>` has succeeded.
+
+## Common patterns
+
+**Add a column:**
+```python
+op.add_column("users", sa.Column("bio", sa.Text(), nullable=True))
+```
+
+**Add an index:**
+```python
+op.create_index("ix_products_name", "products", ["name"])
+```
+
+**Data migration (backfill):**
+```python
+from alembic import op
+from sqlalchemy import text
+
+def upgrade():
+    op.add_column("users", sa.Column("display_name", sa.String(255)))
+    op.execute(text("UPDATE users SET display_name = name WHERE display_name IS NULL"))
+```
+
+**Rename with SQLite (batch mode):**
+```python
+with op.batch_alter_table("users") as batch_op:
+    batch_op.alter_column("old_name", new_column_name="new_name")
+```
+
+**Add a composite unique constraint:**
+```python
+op.create_unique_constraint("uq_oauth_provider_user", "oauth", ["provider", "provider_user_id"])
+```

stk/scaffold/app/docker-compose.yml

@@ -0,0 +1,88 @@
+services:
+
+  redis:
+    container_name: redis 
+    image: 'redis:7-alpine'
+    command: redis-server --requirepass ${REDIS_PASSWORD:?Set a unique REDIS_PASSWORD}
+    volumes:
+      - 'redis-data:/data'
+    healthcheck:
+      test: ["CMD-SHELL", 'REDISCLI_AUTH="$$REDIS_PASSWORD" redis-cli ping']
+      interval: 5s
+      timeout: 3s
+      retries: 3
+    environment:
+      REDIS_PASSWORD: ${REDIS_PASSWORD:?Set a unique REDIS_PASSWORD}
+
+  postgres:
+    container_name: postgres
+    image: 'postgres:15-alpine'
+    volumes:
+      - 'postgres-data:/var/lib/postgresql/data'
+      - './postgres/init-db.sh:/docker-entrypoint-initdb.d/10-stk.sh:ro'
+    environment:
+      - POSTGRES_USER=postgres
+      - POSTGRES_PASSWORD=${DB_ADMIN_PASSWORD:?Set a unique DB_ADMIN_PASSWORD}
+      - DB_PASSWORD=${DB_PASSWORD:?Set a unique DB_PASSWORD}
+      - POSTGRES_DB=stk
+    healthcheck:
+      test: ["CMD", "pg_isready", "-U", "postgres", "-d", "stk"]
+      interval: 5s
+      timeout: 3s
+      retries: 3
+
+  website:
+    container_name: website
+    build: .
+    depends_on:
+      redis:
+        condition: service_healthy
+      postgres:
+        condition: service_healthy
+    command: ["sh", "-c", "python -m stk db upgrade && exec uvicorn __app__.app:app --host 0.0.0.0 --port 5000 --ws-max-size 65536 --ws-max-queue 16 --proxy-headers --forwarded-allow-ips='*'"]
+    env_file:
+      - .env
+    environment:
+      - QUART_DEBUG=0
+      - STK_ENV=production
+      - SESSION_COOKIE_SECURE=True
+      - STK_PUBLIC_URL=https://${STK_HOST:?Set the public DNS name}
+      - SECURITY_WAN_RP_ID=${STK_HOST:?Set the public DNS name}
+      - SECURITY_WAN_EXPECTED_ORIGIN=https://${STK_HOST:?Set the public DNS name}
+      - SQLALCHEMY_DATABASE_URI=postgresql+asyncpg://stk:${DB_PASSWORD:?Set a unique DB_PASSWORD}@postgres/stk
+      - REDIS_SESSION=redis://:${REDIS_PASSWORD:?Set a unique REDIS_PASSWORD}@redis:6379/1
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  nginx:
+    container_name: nginx
+    restart: always
+    image: 'nginx:alpine'
+    user: "${DOCKER_UID:-1000}"
+    ports:
+      - '80:8080'
+      - '443:8443'
+    volumes:
+      - './nginx/nginx.conf:/etc/nginx/nginx.conf:ro'
+      - './nginx/stk.conf:/etc/nginx/conf.d/default.conf:ro'
+      - '${TLS_CERTIFICATE:?Set the TLS certificate path}:/etc/nginx/tls/fullchain.pem:ro'
+      - '${TLS_PRIVATE_KEY:?Set the TLS key path}:/etc/nginx/tls/key.pem:ro'
+    tmpfs:
+      - /tmp:exec
+      - /var/run
+      - /var/cache/nginx
+    depends_on:
+      - website
+    healthcheck:
+      test: ["CMD", "nginx", "-t"]
+      interval: 30s
+      timeout: 10s
+
+volumes:
+  redis-data:
+    driver: local
+  postgres-data:
+    driver: local

stk/scaffold/app/dockerignore

@@ -0,0 +1,13 @@
+.venv
+.git
+.github
+.ruff_cache
+__pycache__
+*.pyc
+*.pyo
+instance
+.env
+.env.*
+*.md
+!README.md
+docs

stk/scaffold/app/env-sample

@@ -0,0 +1,78 @@
+# ============================================
+# STK CONFIGURATION
+# ============================================
+# Lite mode: uv sync && uv run stk run (just works)
+# Full mode: uv sync --extra full (Redis + asyncpg)
+# ============================================
+
+# === CORE (Required) ===
+SECRET_KEY=
+QUART_DEBUG=1
+STK_ENV=development
+SECURITY_REGISTERABLE=False
+SECURITY_PASSWORD_SALT=
+
+# === BRANDING ===
+#APP_NAME=stk
+#APP_TAGLINE=Secure. Scalable. Swift.
+#APP_DESCRIPTION=
+
+# === DATABASE ===
+# SQLite used by default (instance/stk.db) - no config needed
+# Schema changes are tracked with Alembic migrations
+# PostgreSQL (uncomment for production)
+#SQLALCHEMY_DATABASE_URI=postgresql+asyncpg://postgres:pass@localhost/dbname
+
+# === FULL MODE - Redis + asyncpg (optional) ===
+# Uncomment after: uv sync --extra full
+#REDIS_URL=redis://localhost:6379/1
+
+# === OAUTH (optional) ===
+GOOGLE_AUTH_ENABLED=False
+GOOGLE_OAUTH_CLIENT_ID=your_google_client_id
+GOOGLE_OAUTH_CLIENT_SECRET=your_google_client_secret
+
+GITHUB_AUTH_ENABLED=False
+GITHUB_OAUTH_CLIENT_ID=your_github_client_id
+GITHUB_OAUTH_CLIENT_SECRET=your_github_client_secret
+
+# For local development only (remove in production)
+OAUTHLIB_INSECURE_TRANSPORT=1
+
+# === MAIL (optional) ===
+MAIL_SERVER=smtp.sendgrid.net
+MAIL_USERNAME=sendgrid
+MAIL_PASSWORD=sendgrid_secure_password
+SECURITY_EMAIL_SENDER=info@domain.com
+
+# === SESSION & COOKIES ===
+# Local HTTP only. Use True with HTTPS in production.
+SESSION_COOKIE_SECURE=False
+SESSION_COOKIE_HTTPONLY=True
+SESSION_COOKIE_SAMESITE=Lax
+# Set to True to logout other sessions on login (single session per user)
+DISABLE_MULTIPLE_SESSIONS=False
+
+# ============================================
+# DOCKER CONFIGURATION (docker compose up)
+# ============================================
+#COMPOSE_PROJECT_NAME=__app__
+#PYTHONUNBUFFERED=true
+#DOCKER_UID=1000
+#DB_ADMIN_PASSWORD=generate-a-separate-admin-secret
+#DB_PASSWORD=generate-a-unique-secret
+#REDIS_PASSWORD=generate-a-unique-secret
+#SQLALCHEMY_DATABASE_URI=postgresql+asyncpg://stk:${DB_PASSWORD}@postgres/stk
+#REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379/1
+
+# Required by the production Docker stack. Use readable certificate files.
+#STK_HOST=app.example.com
+#TLS_CERTIFICATE=/absolute/path/fullchain.pem
+#TLS_PRIVATE_KEY=/absolute/path/key.pem
+#STK_PUBLIC_URL=https://app.example.com
+#SECURITY_WAN_RP_ID=app.example.com
+#SECURITY_WAN_EXPECTED_ORIGIN=https://app.example.com
+
+# Optional independent MFA encryption keyring, newest key first.
+# Generate Fernet keys and retain old keys during rotation. See SECURITY.md.
+#SECURITY_TOTP_ENCRYPTION_KEYS=new-fernet-key,old-fernet-key

stk/scaffold/app/gitignore

@@ -0,0 +1,8 @@
+.env
+.env.backup*
+instance/
+__pycache__/
+*.pyc
+.venv/
+.ruff_cache/
+.stk/smoke/

stk/scaffold/app/nginx/nginx.conf

@@ -0,0 +1,46 @@
+# Based on https://www.nginx.com/resources/wiki/start/topics/examples/full/#nginx-conf
+# user              www www;  ## Default: nobody
+
+worker_processes  auto;
+error_log         "/var/log/nginx/error.log";
+pid               "/tmp/nginx.pid";
+
+events {
+    worker_connections  1024;
+}
+
+http {
+    include       "/etc/nginx/mime.types";
+    default_type  application/octet-stream;
+    log_format    main '$remote_addr - $remote_user [$time_local] '
+                       '"$request" $status  $body_bytes_sent "$http_referer" '
+                       '"$http_user_agent" "$http_x_forwarded_for"';
+    access_log    "/var/log/nginx/access.log" main;
+    add_header    X-Frame-Options SAMEORIGIN;
+
+    client_body_temp_path  "/tmp/client_temp";
+    proxy_temp_path        "/tmp/proxy_temp";
+    fastcgi_temp_path      "/tmp/fastcgi_temp";
+    scgi_temp_path         "/tmp/scgi_temp";
+    uwsgi_temp_path        "/tmp/uwsgi_temp";
+
+    sendfile           on;
+    tcp_nopush         on;
+    tcp_nodelay        off;
+    gzip               on;
+    gzip_http_version  1.0;
+    gzip_comp_level    2;
+    gzip_proxied       any;
+    gzip_types         text/plain text/css application/javascript text/xml application/xml+rss;
+    keepalive_timeout  65;
+    ssl_protocols      TLSv1.2 TLSv1.3;
+    ssl_ciphers        HIGH:!aNULL:!MD5;
+    client_max_body_size 1M;
+    server_tokens off;
+
+    absolute_redirect  off;
+    port_in_redirect   off;
+
+    include  "/etc/nginx/conf.d/*.conf";
+
+}

stk/scaffold/app/nginx/stk.conf

@@ -0,0 +1,36 @@
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    '' close;
+}
+
+server {
+    listen 8080;
+    return 308 https://$host$request_uri;
+}
+
+server {
+    listen 8443 ssl;
+    server_name _;
+    charset utf-8;
+    ssl_certificate /etc/nginx/tls/fullchain.pem;
+    ssl_certificate_key /etc/nginx/tls/key.pem;
+    add_header Strict-Transport-Security "max-age=31536000" always;
+    add_header X-Content-Type-Options nosniff always;
+    add_header X-Frame-Options DENY always;
+    add_header Referrer-Policy same-origin always;
+
+    # Static files come from the app too: it resolves the app's files before
+    # stk's and sets their Cache-Control by version.
+    location / {
+        proxy_pass http://website:5000;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_connect_timeout 10s;
+        proxy_send_timeout 30s;
+        proxy_read_timeout 90s;
+    }
+}

stk/scaffold/app/postgres/init-db.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+set -eu
+psql --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" --set=app_password="$DB_PASSWORD" --set=ON_ERROR_STOP=1 <<'SQL'
+CREATE USER stk PASSWORD :'app_password';
+ALTER DATABASE stk OWNER TO stk;
+SQL
+# The app role is not a superuser, so create any extensions its migrations need
+# here, as the superuser (e.g. CREATE EXTENSION IF NOT EXISTS postgis;).

stk/scaffold/app/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "__app__"
+version = "0.1.0"
+description = "__App__, built on stk"
+requires-python = ">=3.11"
+dependencies = ["stkit>=__stk_version__,<__stk_next__"]
+
+[project.optional-dependencies]
+full = ["stkit[full]"]  # PostgreSQL and Redis
+
+[dependency-groups]
+dev = ["stkit[dev]"]
+
+[tool.stk]
+app = "__app__.app:app"
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP"]
+ignore = ["E501", "B008"]

stk/scaffold/app/tests/test_app.py

@@ -0,0 +1,23 @@
+import unittest
+
+import stk
+
+from __app__.app import extensions
+from __app__.settings import Config
+
+
+class TestConfig(stk.TestingConfig, Config):
+    pass
+
+
+class AppTests(unittest.IsolatedAsyncioTestCase):
+    async def asyncSetUp(self):
+        self.app = stk.Stk("__app__.app", config=TestConfig, extensions=extensions)
+
+    async def test_home_page_renders(self):
+        response = await self.app.test_client().get("/")
+        self.assertEqual(response.status_code, 200)
+
+    async def test_dashboard_requires_login(self):
+        response = await self.app.test_client().get("/dashboard/")
+        self.assertIn(response.status_code, (302, 401))