api-medic 1.0.0__tar.gz

api_medic-1.0.0/.gitattributes

@@ -0,0 +1,23 @@
+* text=auto eol=lf
+*.py     text eol=lf
+*.toml   text eol=lf
+*.yml    text eol=lf
+*.yaml   text eol=lf
+*.json   text eol=lf
+*.md     text eol=lf
+*.sh     text eol=lf
+*.ts     text eol=lf
+*.tsx    text eol=lf
+*.js     text eol=lf
+*.jsx    text eol=lf
+*.css    text eol=lf
+*.html   text eol=lf
+Makefile text eol=lf
+LICENSE  text eol=lf
+*.png    binary
+*.jpg    binary
+*.gif    binary
+*.ico    binary
+*.pdf    binary
+*.zip    binary
+*.tar.gz binary

api_medic-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,139 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check .
+
+      - name: Format check with ruff
+        run: ruff format --check .
+
+      - name: Type-check with mypy
+        run: mypy src
+
+      - name: Run tests
+        run: pytest -m "not integration" --cov --cov-report=term-missing
+
+  checks-coverage:
+    name: 80% coverage gate on core/checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Coverage gate (core/checks ≥ 80%)
+        run: pytest -m "not integration" --cov=src/api_medic/core/checks --cov-report=term-missing --cov-fail-under=80
+
+  integration:
+    name: Integration tests (live, flake-tolerant)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run integration tests
+        run: pytest -m integration -v
+
+  frontend:
+    name: Frontend (typecheck, test, build)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type-check
+        run: npm run typecheck
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+  schema-check:
+    name: Verify TypeScript types are in sync with Pydantic schema
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Regenerate TypeScript types
+        run: make types
+
+      - name: Fail if generated types changed
+        run: |
+          if ! git diff --exit-code frontend/src/lib/types.ts; then
+            echo "::error::Generated TypeScript types are out of sync."
+            echo "::error::Run 'make types' locally and commit the result."
+            exit 1
+          fi

api_medic-1.0.0/.github/workflows/deploy-demo.yml

@@ -0,0 +1,103 @@
+name: Deploy hosted demo
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  id-token: write # for OIDC role assumption
+  contents: read
+
+jobs:
+  deploy:
+    name: Deploy api-medic-demo to AWS
+    runs-on: ubuntu-latest
+    # Repo variable DEMO_DEPLOY_ENABLED gates this — set it to 'true' in
+    # repo Settings → Variables once AWS prerequisites are in place
+    # (see deploy/README.md). Manual dispatch always runs so it can be
+    # tested before flipping the gate.
+    if: vars.DEMO_DEPLOY_ENABLED == 'true' || github.event_name == 'workflow_dispatch'
+    env:
+      AWS_REGION: us-east-1
+      STACK_NAME: api-medic-demo
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure AWS credentials (OIDC)
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+          aws-region: ${{ env.AWS_REGION }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install AWS SAM CLI
+        uses: aws-actions/setup-sam@v2
+        with:
+          use-installer: true
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build frontend (captured-mode)
+        working-directory: frontend
+        env:
+          VITE_DEMO_MODE: "1"
+        run: |
+          npm ci
+          npm run build
+
+      - name: Vendor api_medic into Lambda build context
+        run: cp -r src/api_medic deploy/lambda/api_medic
+
+      - name: SAM build
+        working-directory: deploy
+        run: sam build
+
+      - name: SAM deploy
+        working-directory: deploy
+        run: |
+          sam deploy \
+            --no-confirm-changeset \
+            --no-fail-on-empty-changeset \
+            --parameter-overrides \
+              HostedZoneId=${{ secrets.ROUTE53_HOSTED_ZONE_ID }} \
+              CertificateArn=${{ secrets.ACM_CERTIFICATE_ARN }}
+
+      - name: Read stack outputs
+        id: outputs
+        run: |
+          BUCKET=$(aws cloudformation describe-stacks \
+            --stack-name "$STACK_NAME" \
+            --query 'Stacks[0].Outputs[?OutputKey==`WebBucketName`].OutputValue' \
+            --output text)
+          DIST=$(aws cloudformation describe-stacks \
+            --stack-name "$STACK_NAME" \
+            --query 'Stacks[0].Outputs[?OutputKey==`DistributionId`].OutputValue' \
+            --output text)
+          echo "bucket=$BUCKET" >> "$GITHUB_OUTPUT"
+          echo "distribution=$DIST" >> "$GITHUB_OUTPUT"
+
+      - name: Sync frontend to S3
+        run: |
+          aws s3 sync frontend/dist/ "s3://${{ steps.outputs.outputs.bucket }}/" \
+            --delete
+
+      - name: Invalidate CloudFront
+        run: |
+          aws cloudfront create-invalidation \
+            --distribution-id "${{ steps.outputs.outputs.distribution }}" \
+            --paths "/*"
+
+      - name: Print public URL
+        run: |
+          echo "::notice::Deployed to https://api-medic.markandrewmarquez.com"

api_medic-1.0.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,78 @@
+name: Publish to PyPI
+
+# Fires on every v* tag push (e.g. v1.0.0, v1.1.0, v2.0.0-rc1) and via
+# manual dispatch — useful to publish an existing tag without re-tagging.
+#
+# Trusted publishing: no API token in repo secrets. PyPI verifies the
+# upload via an OIDC token that GitHub mints for this workflow. The
+# binding is configured once in PyPI's web UI under Account → Publishing.
+# See deploy/pypi-trusted-publishing.md for the exact one-time steps.
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Tag or branch to publish from (e.g. v1.0.0)"
+        required: true
+        default: "v1.0.0"
+
+jobs:
+  build-and-publish:
+    name: Build wheel + sdist and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for trusted publishing
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Build frontend bundle
+        # Local-web-UI build (no VITE_DEMO_MODE) — the wheel ships the
+        # full-feature UI; the demo-mode build is hosted-demo-only.
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build
+
+      - name: Stage frontend into wheel source tree
+        run: |
+          # pyproject.toml force-includes src/api_medic/web/frontend/ → wheel.
+          # That dir is gitignored at runtime; populate it from the build.
+          rm -f src/api_medic/web/frontend/.gitkeep
+          cp -r frontend/dist/* src/api_medic/web/frontend/
+
+      - name: Build wheel and sdist
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Smoke-check the built distributions
+        run: |
+          ls -lh dist/
+          python -m pip install dist/*.whl
+          python -c "import api_medic; print('imported api_medic', api_medic.__name__)"
+          api-medic --help | head -10
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No `with:` block — trusted publishing reads the project name
+        # from the wheel metadata and verifies via OIDC.

api_medic-1.0.0/.gitignore

@@ -0,0 +1,85 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+/build/
+/develop-eggs/
+/dist/
+/downloads/
+/eggs/
+/.eggs/
+/lib/
+/lib64/
+/parts/
+/sdist/
+/var/
+/wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+coverage.xml
+*.cover
+
+# IDE / agent state
+.idea/
+.vscode/
+.claude/
+*.swp
+*.swo
+.DS_Store
+
+# Node / frontend
+node_modules/
+frontend/dist/
+frontend/.vite/
+*.log
+.npm/
+
+# Built frontend, shipped in wheel — populated at build time, not checked in.
+# .gitkeep keeps the dir in tree so the wheel build's force-include works
+# before Phase 2 has anything to bundle.
+src/api_medic/web/frontend/*
+!src/api_medic/web/frontend/.gitkeep
+
+# AWS / SAM
+.aws-sam/
+samconfig.toml.local
+packaged.yaml
+
+# Secrets — never commit these
+.env
+.env.local
+*.pem
+aws-credentials*
+
+# OS
+Thumbs.db
+
+# SAM build context: vendored copy of api_medic (created before sam build)
+deploy/lambda/api_medic/
+
+# Cert / DNS validation scratch (generated during one-shot ACM setup,
+# not used by builds or deploys)
+/acm-validation.json
+/cert-arn.txt
+
+# One-shot deploy operations scratch (templates fetched from CFN,
+# import maps, etc.)
+/.deploy-tmp/

api_medic-1.0.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to api-medic are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-04-29
+
+First public release. Three input surfaces (CLI, local web UI, hosted demo) sharing one core engine and a single `Report` shape.
+
+### Added — Core engine
+
+- Pydantic v2 data model: `Report`, `Finding`, `RequestSummary`, `ResponseSummary`, `TimingBreakdown`, `CapturedRequest`, `CapturedResponse`, `CapturedDns`, `CapturedTls`. `schema_version` bump-tracked.
+- Parser: HAR 1.2 archives and curl command strings normalized to the same `CapturedRequest` shape.
+- Runner: live HTTP execution via `httpx`, with `dnspython` pre-flight DNS probe and a separate `cryptography`-based TLS cert/protocol probe. Captures DNS / TLS / TTFB / total timing, redirect chain, raw headers (preserving duplicate `Set-Cookie`).
+- Check battery — 20+ diagnostic checks across:
+  - **Network** — `dns.no_records`, `dns.address_class`
+  - **TLS** — `tls.expired`, `tls.expiring_soon`, `tls.hostname_mismatch`, `tls.weak_protocol`
+  - **Transport** — `transport.redirect_loop`, `transport.redirect_to_http`, `transport.slow_tls`
+  - **Auth** — `auth.jwt_expired`, `auth.missing_authorization`, `auth.malformed_authorization`, `auth.suspicious_jwt_signature`
+  - **CORS** — `cors.preflight_failed`, `cors.origin_not_allowed`, `cors.credentials_misconfigured`
+  - **Body** — `body.malformed_json`, `body.content_length_mismatch`, `body.encoding_mismatch`
+  - **Rate limit** — `ratelimit.too_many_requests` (with Retry-After context)
+  - **Status** — `status.client_error`, `status.server_error`
+- Renderers: terminal (rich), JSON, Markdown, HTML — pluggable via `--output`.
+
+### Added — CLI
+
+- `api-medic <URL>` quick GET diagnosis (default subcommand).
+- `api-medic run <URL>` full request with method, headers, body, auth.
+- `api-medic from-curl '<command>'` parse + analyze (or just analyze) a curl command.
+- `api-medic from-har <file.har>` analyze a captured HAR.
+- `api-medic serve [--port 8765]` launch the local web UI.
+- Output flags: `--output {terminal,json,markdown,html}`, `--save <path>`, `--no-color`, `--verbose`.
+
+### Added — Local web UI
+
+- Vite + React 18 + TypeScript + Tailwind, no design system library, no state management library.
+- Three tabs: Demos (fixture browser), Run (request composer hitting `/api/run`), HAR (file upload hitting `/api/analyze`).
+- TypeScript types auto-generated from Pydantic JSON Schema via `make types`; CI fails if regenerated types drift from the committed file.
+- React bundle ships inside the Python wheel — no separate install step for the local UI.
+
+### Added — Hosted demo (AWS)
+
+- `https://api-medic.markandrewmarquez.com` on S3 + CloudFront + API Gateway HTTP API + Lambda.
+- Routes: `POST /api/analyze` (captured-mode parser+engine), `POST /api/run` (live runner), `GET /api/health`.
+- `/api/run` is SSRF-guarded (blocks RFC1918, link-local incl. EC2 metadata, multicast, loopback; HTTPS-only) with a 10-second per-request timeout.
+- API Gateway throttling on `/api/run` (2 req/sec sustained, burst 5) plus a $10/month AWS Budget with 50%/100%/forecast email alerts.
+- Lambda log group is stack-managed with 14-day retention.
+- Same Report shape as the CLI and local web UI — byte-identical given the same input.
+- Deploy via SAM, OIDC-based GitHub Actions role with least-privilege inline policy (committed at `deploy/iam/`).
+
+### Added — Demo polish
+
+- Client-side HAR stripping in three tiers (passthrough → strip request/response bodies → first-entry only) so 12 MB browser exports survive API Gateway's 10 MB body cap. UI banner explains what was dropped.
+- `VITE_DEMO_MODE=1` build path uses same-origin API base so CloudFront routes `/api/*` to the Lambda.
+
+### Added — Quality
+
+- 311 Python tests + 60 frontend tests.
+- CI matrix: 3 operating systems × 3 Python versions = 9 cells.
+- 80% coverage gate on `core/checks`.
+- Static-import audit (`tests/unit/test_lambda_imports.py`) enforces Lambda dep boundaries — no fastapi/uvicorn/typer/rich, and explicit positive assertion that the Lambda surface DOES include the runner + SSRF guard so `/api/run` can't silently regress.
+- Schema-sync gate: CI regenerates `frontend/src/lib/types.ts` from Pydantic and fails if it differs from the committed file.
+
+### Added — Project
+
+- 8 hand-crafted fixture reports covering distinct diagnostic scenarios; double as UI dev data, schema validation, and integration smoke tests.
+- MIT license, public repo, full architecture spec at `docs/architecture.md`.
+
+### Architectural decisions
+
+- **Stateless by design.** No DynamoDB, no S3 writes for user data, no CloudWatch persistence beyond default logs.
+- **No FastAPI / uvicorn on Lambda.** The Lambda dispatches routes inline via `lambda_handler` to keep cold-start budget intact even with the runner deps (httpx, dnspython, cryptography).
+- **Same `Report` shape from every surface** — the contract that makes the future browser extension a thin capture layer rather than a parallel implementation.
+
+[Unreleased]: https://github.com/marky224/api-medic/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/marky224/api-medic/releases/tag/v1.0.0

api_medic-1.0.0/CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md — operating brief for Claude Code in this repo
+
+This is api-medic, an open-source HTTP API troubleshooting tool. Mark Marquez directs the build; Claude implements alongside him.
+
+## Source of truth
+- `docs/architecture.md` — the full v1 build spec. Tech stack, repo structure, data model, invariants, phases. Consult actively.
+- The Pydantic models in `src/api_medic/core/models.py` are the contract every surface produces and consumes. Don''t break them without bumping `schema_version`.
+- `frontend/src/lib/types.ts` is auto-generated from those models via `make types`. Never edit by hand.
+
+## Status
+v1 is shipped. All seven phases in `docs/architecture.md` are complete:
+data model, fixtures, web UI, core engine, CLI, hosted demo on AWS,
+Phase 6 polish. The hosted demo at `https://api-medic.markandrewmarquez.com`
+exposes Demos / Run / HAR tabs and the Lambda runs both captured-mode
+and live requests (SSRF-guarded, throttled).
+
+Default work mode is now polish, bug fixes, and post-launch items.
+Phase 7 (browser extension) is the only remaining planned phase and
+is explicitly post-v1.
+
+## Working style
+- Default to producing actual code, not pseudocode.
+- Write tests alongside the code.
+- Push back when you disagree.
+- One question at a time when scoping.
+- Don''t expand scope without flagging.
+- No emojis unless Mark uses them first.
+- Skip sycophantic openers ("Great question!", etc.).
+
+## Architectural invariants (don''t change without sign-off)
+- Same Report shape from every surface (CLI, web, Lambda, extension).
+- Lambda surface ships parser + checks + renderers + the live runner.
+  Outbound HTTP from the Lambda is allowed and must apply SSRF mitigations
+  (block RFC1918, link-local incl. 169.254.169.254 metadata, multicast,
+  loopback; resolve hostname once and re-check the IP before connecting)
+  plus a conservative per-request timeout (≤10s). FastAPI and uvicorn
+  remain excluded — the Lambda dispatches routes inline via
+  `lambda_handler`, no web framework.
+- Hosted demo exposes both captured-mode (HAR/curl) and live-run tabs.
+  Live runs are bounded by API Gateway throttling, Lambda reserved
+  concurrency, and the AWS Budget; assume any URL the user submits
+  will be fetched by the Lambda.
+- Stateless: no DynamoDB, no S3 writes for user data, no persistence.
+- Public repo, MIT license, no public timelines anywhere.
+
+## Tech stack (locked)
+- Python 3.10+ (3.12 target), httpx, dnspython, cryptography, pydantic v2, typer, rich, fastapi, uvicorn
+- TypeScript + React 18 + Vite + Tailwind. No design system library. No state management library.
+- AWS SAM in us-east-1, API Gateway HTTP API → Lambda, CloudFront + S3
+- GitHub Actions CI
+
+## Quality gates (must pass before pushing)
+- `pytest` — all green
+- `ruff check .` and `ruff format --check .`
+- `mypy` — clean
+- `make types` produces no diff vs committed `types.ts` (also verified by CI)
+
+## Out of scope for v1
+History/share links, comparison mode, OpenAPI validation, OAuth simulation, WebSocket support, plugin system, pre-built binaries, telemetry. Don''t build these unless Mark explicitly asks.
+
+## Audience
+README and marketing copy frame this as a tool for technical support engineers triaging customer-reported API issues. Tool itself is general-purpose.

api_medic-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Marquez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

api_medic-1.0.0/Makefile

@@ -0,0 +1,52 @@
+.PHONY: help install types lint format typecheck test test-cov clean
+
+help:  ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install:  ## Install package + dev dependencies
+	pip install -e ".[dev]"
+
+types:  ## Regenerate TypeScript types from Pydantic JSON Schema
+	@echo "Exporting JSON Schema from Pydantic models..."
+	@python -m api_medic.core.export_schema > /tmp/api-medic-schema.json
+	@echo "Generating TypeScript types via quicktype..."
+	@mkdir -p frontend/src/lib
+	@npx --yes quicktype@23 \
+		--src-lang schema \
+		--lang typescript \
+		--just-types \
+		--prefer-unions \
+		--no-date-times \
+		--top-level Report \
+		-o frontend/src/lib/types.ts \
+		/tmp/api-medic-schema.json
+	@echo "/* eslint-disable */" > /tmp/types.header
+	@echo "/**" >> /tmp/types.header
+	@echo " * AUTO-GENERATED by 'make types' from Pydantic models in src/api_medic/core/models.py." >> /tmp/types.header
+	@echo " * Do not edit by hand. Run 'make types' to regenerate." >> /tmp/types.header
+	@echo " */" >> /tmp/types.header
+	@cat /tmp/types.header frontend/src/lib/types.ts > /tmp/types.combined
+	@mv /tmp/types.combined frontend/src/lib/types.ts
+	@rm /tmp/types.header /tmp/api-medic-schema.json
+	@echo "Wrote frontend/src/lib/types.ts"
+
+lint:  ## Run ruff lint
+	ruff check .
+
+format:  ## Format code with ruff
+	ruff format .
+
+typecheck:  ## Run mypy
+	mypy src
+
+test:  ## Run tests
+	pytest
+
+test-cov:  ## Run tests with coverage
+	pytest --cov --cov-report=term-missing --cov-report=html
+
+clean:  ## Remove build artifacts and caches
+	rm -rf build dist *.egg-info
+	rm -rf .pytest_cache .mypy_cache .ruff_cache htmlcov
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete