v0 infra: docker, compose, justfile, alembic, ci

.dockerignore

@@ -0,0 +1,56 @@
+# vcs
+.git
+.gitignore
+.github
+
+# python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info
+.eggs
+build
+dist
+
+# venv + caches
+.venv
+.uv-cache
+.pytest_cache
+.coverage
+.coverage.*
+htmlcov
+.mypy_cache
+.ruff_cache
+
+# editors
+.vscode
+.idea
+*.swp
+.DS_Store
+
+# docker
+Dockerfile*
+.dockerignore
+docker-compose*.yml
+
+# secrets
+.env
+.env.local
+.env.*.local
+
+# tests + tooling not needed in image
+tests
+notes
+scratch
+*.md
+# but pyproject.toml references README.md — include it.
+!README.md
+
+# nothing in these belongs in the python image build context
+frontend
+mizu
+node_modules
+nagara-planning
+nagara-private

.env.example

@@ -0,0 +1,90 @@
+# nagara environment template.
+# Copy to .env and fill in values for local dev. NEVER commit a real .env.
+#
+# Every variable has a sensible default in src/nagara/config.py — only set
+# the ones you need to override.
+
+# ── App ─────────────────────────────────────────────────────────────────
+# Selects which .env file is loaded and switches behavior helpers.
+# One of: development | test | staging | production
+NAGARA_ENV=development
+
+# Logging level for the app (matches Python logging values).
+NAGARA_LOG_LEVEL=INFO
+
+# ── Security (REQUIRED in production) ──────────────────────────────────
+# Used to sign sessions, JWTs, etc. In production, generate with:
+#   python -c "import secrets; print(secrets.token_urlsafe(64))"
+# Empty string here means "unset" — verify_settings() will reject it in prod.
+NAGARA_SECRET_KEY=
+
+# ── HTTP ────────────────────────────────────────────────────────────────
+# Public-facing base URL. Used to build absolute links in emails, webhooks, etc.
+NAGARA_BASE_URL=http://127.0.0.1:8000
+
+# Frontend URL — used by the API to redirect after auth flows.
+NAGARA_FRONTEND_BASE_URL=http://127.0.0.1:3000
+
+# Comma-separated list of allowed CORS origins. Empty = none.
+# Pydantic settings parses JSON arrays for list fields:
+#   NAGARA_CORS_ORIGINS=["http://localhost:3000"]
+NAGARA_CORS_ORIGINS=[]
+
+# Optional regex matched against the Origin header (in addition to the list above).
+# Useful for ephemeral preview hosts.
+# NAGARA_CORS_ORIGIN_REGEX=
+
+# Allow cookies/auth on cross-origin requests. Cannot combine with "*" origin.
+# NAGARA_CORS_ALLOW_CREDENTIALS=false
+
+# Trust X-Forwarded-* headers from an upstream reverse proxy. Only enable when
+# the proxy strips these from client requests (otherwise spoofable).
+# NAGARA_TRUST_PROXY=false
+
+# Reject requests whose Content-Length exceeds this many bytes with 413.
+# NAGARA_REQUEST_MAX_BYTES=10485760
+
+# How often the request-cancel middleware checks for client disconnect.
+# NAGARA_REQUEST_CANCEL_POLL_SECONDS=0.1
+
+# ── Database ────────────────────────────────────────────────────────────
+# Override the assembled DSN entirely (Render/Heroku/Supabase typically
+# inject DATABASE_URL — both NAGARA_DATABASE_URL and DATABASE_URL work).
+# DATABASE_URL=postgresql+asyncpg://user:pwd@host:5432/dbname
+
+# Or set the parts and we'll assemble the DSN at runtime.
+NAGARA_POSTGRES_USER=nagara
+NAGARA_POSTGRES_PWD=nagara
+NAGARA_POSTGRES_HOST=127.0.0.1
+NAGARA_POSTGRES_PORT=5432
+NAGARA_POSTGRES_DB=nagara
+
+# Minimum supported Postgres major version. Boot fails if the server reports
+# a lower version. Set to 0 to disable the check.
+# NAGARA_POSTGRES_MIN_VERSION=15
+
+# Pool tuning. Defaults are reasonable for a single-process dev app.
+# NAGARA_DATABASE_POOL_SIZE=5
+# NAGARA_DATABASE_POOL_RECYCLE_SECONDS=600
+# NAGARA_DATABASE_COMMAND_TIMEOUT_SECONDS=30
+
+# ── Redis ───────────────────────────────────────────────────────────────
+# Used by the rate limiter.
+# NAGARA_REDIS_URL=redis://127.0.0.1:6379/0
+
+# ── Observability ───────────────────────────────────────────────────────
+# Sentry DSN. No-op when unset.
+# NAGARA_SENTRY_DSN=
+
+# Release version reported by /health endpoints (commit SHA / git tag).
+# NAGARA_RELEASE_VERSION=dev
+
+# ── Sessions ───────────────────────────────────────────────────────────
+# How long a user session lasts before requiring re-auth.
+# Pydantic parses this as a timedelta (e.g., "P31D" / "31 days").
+# NAGARA_USER_SESSION_TTL=31 days
+
+# ── Profile (optional, CLI feature) ─────────────────────────────────────
+# Selects an active profile from ~/.config/nagara/profiles.toml
+# (only applies if you've set up profiles via the CLI).
+# NAGARA_PROFILE=dev

.env.test

@@ -0,0 +1,23 @@
+# Test-suite environment. Loaded by src/nagara/config.py when
+# NAGARA_ENV=test (e.g., ``NAGARA_ENV=test pytest``).
+
+NAGARA_ENV=test
+NAGARA_LOG_LEVEL=WARNING
+
+# Deterministic signing key. 32+ chars to satisfy production-grade
+# secret-length checks even though we're in test.
+NAGARA_SECRET_KEY=test-secret-not-for-production-use-32chars
+
+NAGARA_BASE_URL=http://127.0.0.1:8000
+NAGARA_FRONTEND_BASE_URL=http://127.0.0.1:3000
+NAGARA_CORS_ORIGINS=["http://127.0.0.1:3000","http://localhost:3000"]
+
+# Separate DB so a botched test run can never trash dev data. The
+# matching database needs to exist; create it with
+#   createdb -h 127.0.0.1 -U nagara nagara_test
+# or let CI run ``just createdb-test``.
+NAGARA_POSTGRES_USER=nagara
+NAGARA_POSTGRES_PWD=nagara
+NAGARA_POSTGRES_HOST=127.0.0.1
+NAGARA_POSTGRES_PORT=5432
+NAGARA_POSTGRES_DB=nagara_test

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Report unexpected behavior in nagara
+title: ''
+labels: bug
+---
+
+## Description
+
+<!-- What happened? What did you expect to happen? -->
+
+## Reproduction
+
+```python
+# Minimal code or steps to reproduce.
+```
+
+## Environment
+
+- nagara version / git SHA:
+- Python: `python -V`
+- OS:
+
+## Logs / stack trace
+
+```
+<paste here>
+```

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Propose a new capability for nagara
+title: ''
+labels: enhancement
+---
+
+## Problem
+
+<!-- What can't you do today? Or what's painful? -->
+
+## Proposal
+
+<!-- What would the API / behavior / config look like? -->
+
+## Alternatives considered
+
+<!-- Other approaches you thought about. Helps avoid bikeshedding. -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## What
+
+<!-- One paragraph: what changed and why. -->
+
+## How
+
+<!-- Brief technical approach. Skip for trivial changes. -->
+
+## Test plan
+
+- [ ] `just check` passes locally
+- [ ] New tests added for new behavior
+- [ ] Manually verified the happy path
+- [ ]

.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+# Python deps are managed by .github/workflows/uv-upgrade.yml — Dependabot's
+# `pip` ecosystem can't update uv.lock, so it would open PRs that always fail
+# CI on lock drift. Everything else (npm, GHA, docker) is fine here.
+updates:
+  - package-ecosystem: "npm"
+    directory: "/frontend"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      js-minor-and-patch:
+        update-types: ["minor", "patch"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/ci.yml

@@ -9,6 +9,39 @@ on:
 jobs:
   check:
     runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: nagara
+          POSTGRES_PASSWORD: nagara
+          POSTGRES_DB: nagara
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      NAGARA_POSTGRES_HOST: 127.0.0.1
+      NAGARA_POSTGRES_PORT: "5432"
+      NAGARA_POSTGRES_USER: nagara
+      NAGARA_POSTGRES_PWD: nagara
+      NAGARA_POSTGRES_DB: nagara
+      NAGARA_REDIS_URL: redis://127.0.0.1:6379/0
+
     steps:
       - uses: actions/checkout@v4
 
@@ -26,5 +59,8 @@ jobs:
       - name: ruff lint
         run: uv run ruff check
 
+      - name: ty check
+        run: uv run ty check
+
       - name: pytest
         run: uv run pytest

.github/workflows/docker.yml

@@ -0,0 +1,60 @@
+name: docker
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: set up qemu
+        uses: docker/setup-qemu-action@v3
+
+      - name: set up buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: log in to ghcr
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha
+
+      - name: build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            RELEASE_VERSION=${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max