substack-gateway-oss: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Install dependencies (dev included, all workspace members)
uv sync --all-packages --dev

# Run the server (dev mode with reload)
uv run python -m substack_gateway.main

# Lint
uv run ruff check .

# Format check / fix
uv run ruff format --check .
uv run ruff format .

# Type-check
uv run ty check .

# Unit tests (pytest)
uv run pytest packages/gateway_oss/tests/
uv run pytest packages/gateway_drafts/tests/
uv run pytest packages/gateway_stats/tests/

# Run a single test file
uv run pytest packages/gateway_oss/tests/test_markdown.py

# BDD integration tests (pytest-bdd; also part of plain `uv run pytest`)
uv run pytest packages/gateway_oss/features/

# Run matching BDD scenarios by name
uv run pytest packages/gateway_oss/features/ -k "draft"

# Live E2E tests (pytest-bdd) against SUBSTACK_GATEWAY_BASE_URL or a local gateway on :5001
uv run pytest packages/gateway_oss/e2e/

# Build all workspace packages (shell + gateway_core + every domain trio)
uv build --all-packages

When introducing changes, validate them before finishing the task. Prefer targeted runs first, but the expected OSS validation set is:

• uv run ruff check .
• uv run ruff format --check .
• uv run ty check .
• uv build --all-packages
• uv run pytest (includes the BDD scenarios in packages/gateway_oss/features/)

Before committing or pushing, always run the relevant lint, format, type-check, and test commands for the touched area. Do not skip validation just because the change looks small.

Commit and PR titles must use Conventional Commits / semver-style prefixes such as feat:, fix:, chore:, docs:, refactor:, test:, or ci:. Prefer the narrowest correct prefix and keep the subject concise and imperative. For breaking changes, use Conventional Commits semver signaling with ! in the type or scope, and/or include a BREAKING CHANGE: footer in the commit body.