treadstone 0.1.1__tar.gz

treadstone-0.1.1/.agents/skills/database-migration/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: database-migration
+description: Database model design and Alembic migration workflow for Treadstone. Use whenever adding or modifying SQLAlchemy models, generating Alembic migrations, or applying schema changes to Neon. Also use when the user mentions "migration", "add table", "add column", "schema change", "database model", or any task involving treadstone/models/.
+---
+
+# Database Model & Migration Workflow
+
+All schema changes flow through this pipeline — never modify a production database by hand:
+
+```
+SQLAlchemy model → Alembic autogenerate → review migration → apply to test branch → verify → apply to production
+```
+
+Quick reference:
+
+```bash
+make migration MSG="add example table"   # Generate migration
+make migrate                             # Apply to DB
+make downgrade                           # Rollback last migration
+```
+
+---
+
+## Step 1: Design the Model
+
+Create or modify files in `treadstone/models/`.
+
+```
+treadstone/models/
+├── __init__.py     # Re-exports all models (critical for Alembic)
+├── user.py         # User, OAuthAccount, Invitation
+├── api_key.py      # ApiKey
+└── <new_model>.py  # Your new model
+```
+
+### Model Template
+
+```python
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from treadstone.core.database import Base
+from treadstone.models.user import random_id, utc_now
+
+
+class Example(Base):
+    __tablename__ = "example"
+
+    id: Mapped[str] = mapped_column(
+        String(24), primary_key=True, default=lambda: "ex" + random_id()
+    )
+    name: Mapped[str] = mapped_column(String(256), nullable=False)
+    owner_id: Mapped[str] = mapped_column(
+        String(24), ForeignKey("user.id", ondelete="cascade"), nullable=False
+    )
+    gmt_created: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=utc_now, nullable=False
+    )
+    gmt_deleted: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+```
+
+### Conventions
+
+| Convention | Rationale |
+|-----------|-----------|
+| `String(24)` PK with prefix (`"user"`, `"key"`, `"ex"`) | Human-readable IDs, no UUID overhead |
+| `gmt_created` / `gmt_updated` / `gmt_deleted` timestamps | Consistent audit trail, soft-delete support |
+| `ForeignKey(..., ondelete="cascade")` | Prevent orphan rows |
+| `DateTime(timezone=True)` | Always store timezone-aware timestamps |
+| `Mapped[...]` + `mapped_column()` | Modern SQLAlchemy 2.0 style with type safety |
+| `StrEnum` (not `str, Enum`) | Python 3.12+ idiomatic, passes ruff UP042 |
+| Soft-delete via `gmt_deleted` | Prefer soft-delete over hard-delete for important data |
+
+### Joined Eager Loading Gotcha
+
+Models with `relationship(..., lazy="joined")` (e.g. `User.oauth_accounts`) require `.unique()` before extracting results, otherwise SQLAlchemy raises `InvalidRequestError`:
+
+```python
+result = await session.execute(select(User))
+users = result.unique().scalars().all()  # .unique() required!
+```
+
+---
+
+## Step 2: Register the Model
+
+Every new model **must** be imported in `treadstone/models/__init__.py`. Alembic autogenerate only detects models registered with `Base.metadata` at import time.
+
+```python
+# treadstone/models/__init__.py
+from treadstone.models.api_key import ApiKey
+from treadstone.models.example import Example       # <-- add
+from treadstone.models.user import Invitation, OAuthAccount, Role, User
+
+__all__ = ["User", "OAuthAccount", "Invitation", "Role", "ApiKey", "Example"]
+```
+
+If you skip this, `alembic revision --autogenerate` generates an empty migration.
+
+---
+
+## Step 3: Write a Test for the Model
+
+```python
+# tests/unit/test_example_model.py
+from treadstone.models.example import Example
+
+def test_example_fields_exist():
+    e = Example()
+    assert hasattr(e, "id")
+    assert hasattr(e, "name")
+    assert hasattr(e, "owner_id")
+```
+
+```bash
+make test
+```
+
+---
+
+## Step 4: Generate and Review the Migration
+
+```bash
+make migration MSG="add example table"
+```
+
+Open the generated file in `alembic/versions/` and verify:
+
+- Correct table name and columns
+- Foreign keys point to the right tables
+- Indexes on frequently queried columns
+- `nullable` settings match intent
+- `downgrade()` correctly reverses changes
+- No unintended changes to existing tables
+
+### Common Pitfalls
+
+| Pitfall | Symptom | Fix |
+|---------|---------|-----|
+| Model not in `__init__.py` | Empty migration | Add import to `treadstone/models/__init__.py` |
+| Pooled connection string | Intermittent migration errors | Use direct (non-pooled) connection for Alembic |
+| `+asyncpg` in Alembic URL | `RuntimeError: cannot use async engine` | `env.py` strips it automatically — don't add it back |
+| Enum value changes | Alembic doesn't detect them | Handle enum migrations manually |
+| Column rename | Autogenerate sees drop + add | Write manual migration with `op.alter_column()` |
+
+---
+
+## Step 5: Apply to Neon Test Branch First
+
+Never migrate production directly. Neon branches are instant, copy-on-write clones — use one as a staging environment.
+
+```
+Production (main branch)
+    └── Test branch (fork, apply migration here first)
+```
+
+1. Create a test branch via Neon Console or CLI (if not already existing)
+2. Apply migration to the test branch:
+   ```bash
+   TREADSTONE_DATABASE_URL="<test-branch-url>" make migrate
+   ```
+3. Run integration tests:
+   ```bash
+   make test-all
+   ```
+4. If tests pass, apply to production:
+   ```bash
+   make migrate   # with .env pointing to production
+   ```
+5. If tests fail, fix and retry. Use `make downgrade` or reset the branch via Neon Console.
+
+---
+
+## Step 6: Commit
+
+Commit the model, migration file, and tests together as one logical unit:
+
+```bash
+git add treadstone/models/ alembic/versions/ tests/
+git commit -m "feat: add example model and migration"
+```
+
+---
+
+## Rollback
+
+```bash
+make downgrade                   # Rollback last migration
+uv run alembic downgrade -2      # Rollback 2 steps
+uv run alembic downgrade base    # Rollback to empty
+```
+
+To reset a Neon test branch entirely, use the Neon Console "Reset from parent" feature.
+
+---
+
+## Checklist
+
+- [ ] Model defined in `treadstone/models/<name>.py` with type hints
+- [ ] Model imported in `treadstone/models/__init__.py`
+- [ ] Unit test written and passing
+- [ ] Migration generated with `make migration MSG="..."`
+- [ ] Migration file reviewed manually
+- [ ] Migration applied to Neon test branch
+- [ ] Integration tests passing (`make test-all`)
+- [ ] Migration applied to production
+- [ ] Committed together: model + migration + tests

treadstone-0.1.1/.agents/skills/dev-lifecycle/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: dev-lifecycle
+description: Treadstone daily development lifecycle — the step-by-step loop from creating a branch to merging a PR. Use this skill every time you develop a new feature, fix a bug, refactor code, or make any code change that will be shipped. Covers branching, TDD cycle, shipping, PR creation, CI monitoring, and merging. If the user says "add feature X", "fix bug Y", "implement Z", or anything that implies writing and shipping code, this skill applies.
+---
+
+# Development Lifecycle
+
+Never push directly to main. All code merges go through Pull Requests — this includes AI Agents.
+
+## The Loop
+
+```
+branch → TDD (write test → fail → implement → pass → refactor) → ship → PR → CI → merge
+```
+
+## Step 1: Create a Feature Branch
+
+```bash
+git checkout main && git pull
+git checkout -b feat/descriptive-name
+```
+
+Branch naming: `feat/`, `fix/`, `chore/`, `refactor/`, `docs/`, `test/`.
+
+## Step 2: TDD Cycle
+
+Repeat per unit of work — keep iterations small.
+
+1. **Write a failing test** in the appropriate directory (`tests/unit/`, `tests/api/`, or `tests/integration/`). See the Testing section in `AGENTS.md` for which directory to use.
+
+2. **Confirm it fails:**
+   ```bash
+   make test
+   ```
+
+3. **Write the minimal implementation** to make the test pass — nothing more.
+
+4. **Confirm it passes:**
+   ```bash
+   make test
+   ```
+
+5. **Refactor** if needed, re-run `make test` to confirm nothing broke.
+
+## Step 3: Ship to Feature Branch
+
+```bash
+make ship MSG="feat: add user registration endpoint"
+```
+
+This runs `git add -A && git commit && git push` on the current feature branch.
+
+Verify you are NOT on main before shipping: `git branch --show-current`.
+
+Commit messages follow Conventional Commits format (`feat:`, `fix:`, `test:`, `refactor:`, `chore:`, `docs:`). Keep commits small — one logical unit each. See `AGENTS.md` Git Workflow section for full conventions.
+
+All GitHub-visible content (commit messages, PR titles/bodies, review comments) must be in English.
+
+## Step 4: Create a Pull Request
+
+```bash
+gh pr create --title "feat: add user registration" --body "$(cat <<'EOF'
+## Summary
+- Implement user registration and login
+- Support email/password + Cookie session
+
+## Test Plan
+- [x] make test
+- [x] make lint
+EOF
+)"
+```
+
+Use HEREDOC for the body to avoid quote escaping issues.
+
+## Step 5: Monitor CI
+
+```bash
+gh run watch
+```
+
+If CI fails:
+
+```bash
+gh run view <run-id> --log-failed   # inspect failure
+make test                           # reproduce locally
+make lint                           # check formatting
+```
+
+Fix, then `make ship MSG="fix: ..."` to push the fix.
+
+## Step 6: Merge
+
+Once CI is green:
+
+```bash
+gh pr merge --squash
+git checkout main && git pull
+```
+
+## K8s Verification (When Needed)
+
+If the change affects sandbox orchestration or deployment, verify on a local Kind cluster before merging. Follow `deploy/README.md` for the full workflow:
+
+```bash
+make up          # build + deploy to Kind
+make test-e2e    # run E2E tests against the cluster
+make down        # tear down when done
+```
+
+## Quick Reference
+
+Run `make help` for the full command list.

treadstone-0.1.1/.agents/skills/dev-setup/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: dev-setup
+description: First-time Treadstone local development environment setup. Run once after cloning the repo and before starting any development. Covers system dependency installation, Python environment, Neon database connection, migrations, and environment verification. Use this skill when the user/agent just entered the project, needs to rebuild the environment, or encounters setup-related issues like missing dependencies, broken .env, or failed migrations.
+---
+
+# First-Time Dev Environment Setup
+
+Run this once. After completion, switch to the `dev-lifecycle` skill for daily development.
+
+## 1. System Dependencies
+
+Verify these tools are installed:
+
+```bash
+python3 --version        # 3.12+
+uv --version             # Python package manager
+gh --version             # GitHub CLI (optional, for PR/issue ops)
+docker --version         # Container builds + Kind cluster
+kind --version           # Local K8s cluster (sandbox dev only)
+kubectl version --client # K8s CLI
+helm version --short     # Helm chart deployment
+hurl --version           # E2E testing (HTTP request runner)
+```
+
+Install missing tools (macOS):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+brew install kind kubectl helm hurl
+```
+
+## 2. Install Python Dependencies
+
+```bash
+make install
+```
+
+This runs `uv sync` (creates `.venv`, installs all deps) and configures git hooks.
+
+## 3. Configure Database (Neon)
+
+The project uses [Neon](https://neon.tech) Serverless PostgreSQL — no local Postgres needed.
+
+Get the connection string from https://console.neon.tech, then:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and set the connection string in asyncpg format:
+
+```
+TREADSTONE_DATABASE_URL=postgresql+asyncpg://neondb_owner:xxx@ep-xxx.ap-southeast-1.aws.neon.tech/neondb?sslmode=require
+TREADSTONE_DEBUG=true
+```
+
+The URL scheme must be `postgresql+asyncpg://` (not `postgresql://`). Keep `?sslmode=require`.
+
+## 4. Apply Database Migrations
+
+```bash
+make migrate
+```
+
+Expected: `INFO [alembic.runtime.migration] Context impl PostgresqlImpl.` with migration details listed.
+
+## 5. Verify Environment
+
+```bash
+make test
+```
+
+Expected: all tests pass (integration tests are excluded by default). If tests pass, the environment is ready.
+
+## 6. Local K8s Cluster (Sandbox Development)
+
+For sandbox-related features that require a real Kubernetes cluster, follow `deploy/README.md` — it covers Kind cluster creation, image building, Helm deployment, and smoke testing end-to-end.
+
+Quick start:
+
+```bash
+make up   # One-command: Kind cluster + build + deploy
+```
+
+Pure API development (`make dev`) does not require a K8s cluster.
+
+---
+
+## Troubleshooting
+
+**`uv sync` fails:**
+- Confirm Python 3.12+: `python3 --version`
+- Try: `uv python install 3.12`
+
+**Database connection fails (`could not connect`):**
+- Check the connection string in `.env`
+- Confirm the URL uses `postgresql+asyncpg://` not `postgresql://`
+- Neon free-tier projects auto-suspend; first connection may be slow (~1s cold start)
+
+**`alembic upgrade head` reports `authentication failed`:**
+- Confirm `.env` exists in the project root
+- URL-encode special characters in the password

treadstone-0.1.1/.agents/skills/neon-postgres/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: neon-postgres
+description: Guides and best practices for working with Neon Serverless Postgres. Covers getting started, local development with Neon, choosing a connection method, Neon features, authentication (@neondatabase/auth), PostgREST-style data API (@neondatabase/neon-js), Neon CLI, and Neon's Platform API/SDKs. Use for any Neon-related questions.
+---
+
+# Neon Serverless Postgres
+
+Neon is a serverless Postgres platform that separates compute and storage to offer autoscaling, branching, instant restore, and scale-to-zero. It's fully compatible with Postgres and works with any language, framework, or ORM that supports Postgres.
+
+## Neon Documentation
+
+The Neon documentation is the source of truth for all Neon-related information. Always verify claims against the official docs before responding. Neon features and APIs evolve, so prefer fetching current docs over relying on training data.
+
+### Fetching Docs as Markdown
+
+Any Neon doc page can be fetched as markdown in two ways:
+
+1. **Append `.md` to the URL** (simplest): https://neon.com/docs/introduction/branching.md
+2. **Request `text/markdown`** on the standard URL: `curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching`
+
+Both return the same markdown content. Use whichever method your tools support.
+
+### Finding the Right Page
+
+The docs index lists every available page with its URL and a short description:
+
+```
+https://neon.com/docs/llms.txt
+```
+
+Common doc URLs are organized in the topic links below. If you need a page not listed here, search the docs index: https://neon.com/docs/llms.txt — don't guess URLs.
+
+## What Is Neon
+
+Use this for architecture explanations and terminology (organizations, projects, branches, endpoints) before giving implementation advice.
+
+Link: https://neon.com/docs/ai/skills/neon-postgres/references/what-is-neon.md
+
+## Getting Started
+
+Use this for first-time setup: org/project selection, connection strings, driver installation, optional auth, and initial schema setup.
+
+Link: https://neon.com/docs/ai/skills/neon-postgres/references/getting-started.md
+
+## Connection Methods & Drivers
+
+Use this when you need to pick the correct transport and driver based on runtime constraints (TCP, HTTP, WebSocket, edge, serverless, long-running).
+
+Link: https://neon.com/docs/ai/skills/neon-postgres/references/connection-methods.md
+
+### Serverless Driver
+
+Use this for `@neondatabase/serverless` patterns, including HTTP queries, WebSocket transactions, and runtime-specific optimizations.
+
+Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-serverless.md
+
+### Neon JS SDK
+
+Use this for combined Neon Auth + Data API workflows with PostgREST-style querying and typed client setup.
+
+Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-js.md
+
+## Developer Tools
+
+Use this for local development enablement with `npx neonctl@latest init`, VSCode extension setup, and Neon MCP server configuration.
+
+Link: https://neon.com/docs/ai/skills/neon-postgres/references/devtools.md
+
+### Neon CLI
+
+Use this for terminal-first workflows, scripts, and CI/CD automation with `neonctl`.
+
+Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-cli.md
+
+## Neon Admin API
+
+The Neon Admin API can be used to manage Neon resources programmatically. It is used behind the scenes by the Neon CLI and MCP server, but can also be used directly for more complex automation workflows or when embedding Neon in other applications.
+
+### Neon REST API
+
+Use this for direct HTTP automation, endpoint-level control, API key auth, rate-limit handling, and operation polling.
+
+Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-rest-api.md
+
+### Neon TypeScript SDK
+
+Use this when implementing typed programmatic control of Neon resources in TypeScript via `@neondatabase/api-client`.
+
+Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-typescript-sdk.md
+
+### Neon Python SDK
+
+Use this when implementing programmatic Neon management in Python with the `neon-api` package.
+
+Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-python-sdk.md
+
+## Neon Auth
+
+Use this for managed user authentication setup, UI components, auth methods, and Neon Auth integration pitfalls in Next.js and React apps.
+
+Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-auth.md
+
+Neon Auth is also embedded in the Neon JS SDK - so depending on your use case, you may want to use the Neon JS SDK instead of Neon Auth. See https://neon.com/docs/ai/skills/neon-postgres/references/connection-methods.md for more details.
+
+## Branching
+
+Use this when the user is planning isolated environments, schema migration testing, preview deployments, or branch lifecycle automation.
+
+Key points:
+
+- Branches are instant, copy-on-write clones (no full data copy).
+- Each branch has its own compute endpoint.
+- Use the neonctl CLI or MCP server to create, inspect, and compare branches.
+
+Link: https://neon.com/docs/ai/skills/neon-postgres/references/branching.md
+
+## Autoscaling
+
+Use this when the user needs compute to scale automatically with workload and wants guidance on CU sizing and runtime behavior.
+
+Link: https://neon.com/docs/introduction/autoscaling.md
+
+## Scale to Zero
+
+Use this when optimizing idle costs and discussing suspend/resume behavior, including cold-start trade-offs.
+
+Key points:
+
+- Idle computes suspend automatically (default 5 minutes, configurable) (unless disabled - launch & scale plan only)
+- First query after suspend typically has a cold-start penalty (around hundreds of ms)
+- Storage remains active while compute is suspended.
+
+Link: https://neon.com/docs/introduction/scale-to-zero.md
+
+## Instant Restore
+
+Use this when the user needs point-in-time recovery or wants to restore data state without traditional backup restore workflows.
+
+Key points:
+
+- Restore windows depend on plan limits.
+- Users can create branches from historical points-in-time.
+- Time Travel queries can be used for historical inspection workflows.
+
+Link: https://neon.com/docs/introduction/branch-restore.md
+
+## Read Replicas
+
+Use this for read-heavy workloads where the user needs dedicated read-only compute without duplicating storage.
+
+Key points:
+
+- Replicas are read-only compute endpoints sharing the same storage.
+- Creation is fast and scaling is independent from primary compute.
+- Typical use cases: analytics, reporting, and read-heavy APIs.
+
+Link: https://neon.com/docs/introduction/read-replicas.md
+
+## Connection Pooling
+
+Use this when the user is in serverless or high-concurrency environments and needs safe, scalable Postgres connection management.
+
+Key points:
+
+- Neon pooling uses PgBouncer.
+- Add `-pooler` to endpoint hostnames to use pooled connections.
+- Pooling is especially important in serverless runtimes with bursty concurrency.
+
+Link: https://neon.com/docs/connect/connection-pooling.md
+
+## IP Allow Lists
+
+Use this when the user needs to restrict database access by trusted networks, IPs, or CIDR ranges.
+
+Link: https://neon.com/docs/introduction/ip-allow.md
+
+## Logical Replication
+
+Use this when integrating CDC pipelines, external Postgres sync, or replication-based data movement.
+
+Key points:
+
+- Neon supports native logical replication workflows.
+- Useful for replicating to/from external Postgres systems.
+
+Link: https://neon.com/docs/guides/logical-replication-guide.md

treadstone-0.1.1/.env.example

@@ -0,0 +1,36 @@
+# === Database ===
+# Get connection string from Neon Console: https://console.neon.tech
+TREADSTONE_DATABASE_URL=postgresql+asyncpg://user:password@ep-xxx.region.aws.neon.tech/neondb?sslmode=require
+
+# === App ===
+TREADSTONE_DEBUG=false
+TREADSTONE_AUTH_TYPE=cookie
+TREADSTONE_REGISTER_MODE=unlimited
+
+# === Auth Secrets ===
+TREADSTONE_JWT_SECRET=CHANGE_ME_IN_PROD
+TREADSTONE_OAUTH_REDIRECT_URL=http://localhost:3000/auth/callback
+
+# === OAuth Social (leave empty to disable) ===
+TREADSTONE_GOOGLE_OAUTH_CLIENT_ID=
+TREADSTONE_GOOGLE_OAUTH_CLIENT_SECRET=
+TREADSTONE_GITHUB_OAUTH_CLIENT_ID=
+TREADSTONE_GITHUB_OAUTH_CLIENT_SECRET=
+
+# === Auth0 / Authing / Logto (leave empty to disable) ===
+TREADSTONE_AUTH0_DOMAIN=
+TREADSTONE_AUTH0_CLIENT_ID=
+TREADSTONE_AUTHING_DOMAIN=
+TREADSTONE_AUTHING_APP_ID=
+TREADSTONE_LOGTO_DOMAIN=
+TREADSTONE_LOGTO_APP_ID=
+
+# === Sandbox ===
+# Subdomain-based sandbox routing (for browser Web UI access)
+# Dev: "sandbox.localhost"  ->  {sandbox_id}.sandbox.localhost:8000
+# Prod: "sandbox.example.com"  ->  {sandbox_id}.sandbox.example.com
+# Empty string disables subdomain routing.
+TREADSTONE_SANDBOX_DOMAIN=
+TREADSTONE_SANDBOX_NAMESPACE=treadstone
+TREADSTONE_SANDBOX_PORT=8080
+TREADSTONE_SANDBOX_PROXY_TIMEOUT=180.0

treadstone-0.1.1/.githooks/pre-commit

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "=== pre-commit: format + lint ==="
+
+uv run ruff check --fix treadstone/ tests/
+uv run ruff format treadstone/ tests/
+
+# Re-stage files that were auto-formatted
+git diff --name-only | xargs -r git add
+
+if ! uv run ruff check treadstone/ tests/; then
+    echo "ERROR: Lint check failed. Fix issues above, then commit again."
+    exit 1
+fi
+
+if ! uv run ruff format --check treadstone/ tests/; then
+    echo "ERROR: Format check failed."
+    exit 1
+fi
+
+echo "pre-commit checks passed."

treadstone-0.1.1/.githooks/pre-push

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+#
+# Prevent direct pushes to the remote `main` branch.
+# All branch updates to main must go through Pull Requests.
+#
+# Tag pushes (e.g. git push origin v0.1.1) are allowed from any local branch.
+
+while read -r local_ref local_sha remote_ref remote_sha; do
+  [ -z "$remote_ref" ] && continue
+  if [[ "$remote_ref" == "refs/heads/main" ]]; then
+    echo ""
+    echo "ERROR: Direct push to remote 'main' is not allowed."
+    echo "       Please create a feature branch and open a Pull Request."
+    echo ""
+    exit 1
+  fi
+done