indie-stack

Polyglot monorepo: framework libs under foundation/, product code under stack/.

Layout

This repo is a polyglot monorepo with two top-level halves:

• foundation/ — framework libs, reusable, product-blind:
  • foundation/pg-introspection/ — PostgreSQL introspection helpers (Python)
  • foundation/api-framework/ — declarative HTTP API framework over PostgreSQL (Python)
  • foundation/db-maintainer/ — declarative PostgreSQL schema management (Python)
  • foundation/commons/ — small reusable utilities (Python; stdlib-leaning)
  • foundation/ui-components/ — reusable UI components (TypeScript)
• stack/ — product code, domain-aware:
  • stack/services/ — Python backend services (TBD)
  • stack/apps/ — TypeScript frontends (TBD)
  • stack/db/ — cross-service SQL (TBD)
• integration_tests/ — cross-cutting tests spanning both halves.

Boundary enforcement:

• import-linter enforces foundation/ layering and (post-first-service) forbids foundation/ → stack/ imports. Wired into the pre-commit hook.
• pnpm workspace dep graph enforces the same boundary on the TS side (no declared dep = no possible import).

Historical v1 implementation plans are archived under docs/superpowers/plans/. The cross-cutting roadmap is ROADMAP.md.

Tooling

• uv workspace — install: https://docs.astral.sh/uv/
• Python 3.13+
• ruff for lint + format
• pyright for type-checking (strict)
• pytest + pytest-asyncio for tests

Common commands

uv sync                                           # install / update Python deps
pnpm install                                      # install / update TS deps
uv run pytest                                     # all Python tests
uv run pytest foundation/pg-introspection/tests   # one Python member
pnpm -r typecheck                                 # all TS typecheck
uv run ruff check . && uv run ruff format --check .
uv run pyright
uv run lint-imports                               # foundation layering check

Diagnostics (periodic)

Tools we don't run daily but pull in on-demand to audit code health. Run as one-offs via uv run --with so they don't enter the resolved dependency set.

CRAP score (Change Risk Anti-Patterns)

Flags functions that are both complex and poorly tested (CC² × (1−cov)³ + CC). Useful as a one-shot diagnostic, not as a CI gate — enforcing it would punish refactors that legitimately worsen the metric mid-flight.

Per-member invocations:

uv run --with pytest-crap --with pytest-cov pytest --crap --cov=pg_introspection foundation/pg-introspection/tests
uv run --with pytest-crap --with pytest-cov pytest --crap --cov=api_framework foundation/api-framework/tests
uv run --with pytest-crap --with pytest-cov pytest --crap --cov=db_maintainer foundation/db-maintainer/tests

Workflow. Once a subsystem has settled (no major refactors imminent), consult the metric from time to time. For every flagged function, the outcome is one of:

• Act on it — add targeted tests, remove dead code, or refactor.
• Dismiss it with a recorded reason — e.g., "CC is intrinsic to this dispatch; coverage gap is the catch-all branch we keep for X."

Record both kinds of outcomes so the next periodic run can be a drift check rather than a fresh audit: a function dismissed at CRAP 35 last quarter that's now at 50 means either the original justification still holds (and the higher score reflects more intrinsic complexity of the same kind), or the situation has changed and the dismissal should be challenged. Re-derive the verdict against current code; don't trust the old reasoning by inertia.

Git hooks (local-only CI)

Install hooks that block commits/pushes on ruff/pyright/pytest failure:

./tooling/install-hooks.sh

Hooks are tracked under tooling/hooks/; the install script symlinks them into .git/hooks/ and is idempotent.

pre-commit runs the full validation suite on every commit:

• regenerates issues/INDEX.md and auto-stages if changed (side effect, not a gate)
• uv run ruff check .
• uv run ruff format --check .
• uv run pyright
• uv run lint-imports (foundation layering contract)
• pnpm -r typecheck (only when TS/JSON/YAML files are staged)
• uv run pytest (full workspace suite — typically 30–60s)

The workspace has no git remote, so pre-push is not the primary gate; pre-commit is. pre-push retains the same pytest invocation as belt-and-suspenders for the day a remote is added.