chore: agentic upgrade
This commit is contained in:
Daniil
@@ -0,0 +1,45 @@
|
||||
---
|
||||
name: infra-best-practices
|
||||
description: Use when changing, reviewing, or debugging CI, deployment, environment configuration, secrets, observability, generated artifacts, or infrastructure workflows in ui_harness_manager.
|
||||
---
|
||||
|
||||
# Infra Best Practices
|
||||
|
||||
## Project Guidance
|
||||
|
||||
Treat infrastructure as a small, explicit support layer for the Bun, React, Elysia, and Tauri surfaces. Prefer boring, reproducible workflows over clever automation.
|
||||
|
||||
Configuration that varies by deploy belongs in environment variables. Use `API_HOST` and `API_PORT` as granular, orthogonal settings; do not hardcode deploy hosts, ports, credentials, or machine-local paths into source. The repo should remain safe to open-source without exposing secrets.
|
||||
|
||||
Use Bun as the package and CI runtime. Keep `bun.lock` committed, install with `bun ci` in CI, and avoid adding npm, Yarn, or pnpm lockfiles unless the repo intentionally changes package managers.
|
||||
|
||||
For CI, prove build health before adding release complexity: run `bun run check`, then `bun run build`; use `bun run tauri:build` when native packaging, Tauri config, permissions, Rust commands, or desktop release behavior changes. Install/cache Tauri system and Rust prerequisites on each platform runner before expecting native packaging to work.
|
||||
|
||||
Packaged desktop builds do not automatically include the local Elysia dev server. Before release work, decide whether backend behavior moves into Rust commands, a Tauri sidecar, or an external service, then verify the packaged app can reach it.
|
||||
|
||||
Use IaC or checked-in config for new infrastructure changes when possible. Keep manual console steps as temporary exceptions and document the owner, reason, and rollback path.
|
||||
|
||||
Keep logs and observability useful but proportional. Capture startup config shape, API bind failures, build/package failures, and deployment errors without logging secrets or flooding small-app workflows with heavyweight telemetry.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Area | Default |
|
||||
| --- | --- |
|
||||
| Deploy config | Env vars, especially `API_HOST` and `API_PORT` |
|
||||
| Secrets | Secret manager or CI secrets, never source files |
|
||||
| CI install | `bun ci` with committed `bun.lock` |
|
||||
| First CI checks | `bun run check`, then `bun run build` |
|
||||
| Desktop release check | Install Tauri prerequisites, then `bun run tauri:build` |
|
||||
| Generated dirs | Do not treat `dist`, `node_modules`, `src-tauri/gen`, or `src-tauri/target` as source |
|
||||
| Infra changes | Prefer IaC or reviewed config over undocumented manual changes |
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
- Using `bun install` in reproducible CI instead of `bun ci`.
|
||||
- Adding deploy-specific constants when `API_HOST` or `API_PORT` should be env-driven.
|
||||
- Committing credentials, tokens, private URLs, or local absolute paths.
|
||||
- Editing or reviewing generated output in `dist`, `node_modules`, `src-tauri/gen`, or `src-tauri/target` as if it were source.
|
||||
- Shipping a packaged desktop build that still assumes the local Bun/Elysia dev server is running.
|
||||
- Building release pipelines before CI reliably checks and builds the app.
|
||||
- Adding observability that hides the important failure path behind noisy dashboards.
|
||||
- Making manual infra changes without a rollback note or future IaC/config follow-up.
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
name: python-practices
|
||||
description: Use when writing, reviewing, refactoring, or debugging Python code in this repository, including style, typing, error handling, async work, tests, packaging, security, and verification.
|
||||
---
|
||||
|
||||
# Python Practices
|
||||
|
||||
## Core Rule
|
||||
|
||||
Write Python that is boring to maintain: explicit, typed, small, tested, and easy
|
||||
to inspect in production. Prefer this repository's existing conventions over
|
||||
generic advice. When a library, framework, SDK, CLI, or cloud-service detail
|
||||
matters, fetch current docs with Context7; use Tavily for broader ecosystem
|
||||
practice research.
|
||||
|
||||
## Source Priority
|
||||
|
||||
1. Project files: `AGENTS.md`, `pyproject.toml`, existing `cpv3/` code, tests.
|
||||
2. Current official docs and PEPs.
|
||||
3. High-quality community research for trade-offs, checked against project needs.
|
||||
4. Memory or intuition, only after the above.
|
||||
|
||||
## Readability
|
||||
|
||||
- Keep functions small enough to read in one pass. Extract helpers when branching,
|
||||
parsing, or side effects start competing for attention.
|
||||
- Use intention-revealing names: `snake_case` for functions and variables,
|
||||
`CapWords` for classes, `UPPER_SNAKE_CASE` for constants.
|
||||
- Prefer direct control flow, early returns, and clear condition names over nested
|
||||
cleverness.
|
||||
- Avoid ad hoc string parsing when Python, Pydantic, SQLAlchemy, JSON, pathlib,
|
||||
or another structured API can express the operation.
|
||||
- Comments should explain non-obvious reasons, not repeat the code.
|
||||
|
||||
## Types And Data
|
||||
|
||||
- Annotate public functions, service/repository boundaries, async helpers, and
|
||||
values that cross module boundaries.
|
||||
- Prefer precise built-in generics such as `list[str]`, `dict[str, Any]`, and
|
||||
`tuple[int, int]`; avoid bare `dict`, `list`, or `Any` unless the shape is
|
||||
genuinely unknown.
|
||||
- Use Pydantic schemas for API and validation boundaries. Use dataclasses or small
|
||||
typed objects for internal value bundles when Pydantic validation is not needed.
|
||||
- Do not mutate default containers. Use `None` plus initialization or a factory.
|
||||
- Convert external data at the boundary, then keep internal code working with typed
|
||||
values instead of raw payload dictionaries.
|
||||
|
||||
## Errors And Logging
|
||||
|
||||
- Catch specific exceptions. Avoid bare `except`, silent fallbacks, and swallowing
|
||||
errors without observability.
|
||||
- Preserve context with exception chaining: `raise DomainError(...) from exc`.
|
||||
- Define reusable user-facing or domain error strings as `ERROR_...` constants.
|
||||
- Use `logging.getLogger(__name__)` for diagnostics. Do not use `print` in
|
||||
application code.
|
||||
- Error messages should help the next maintainer find the failing input, dependency,
|
||||
or state without leaking secrets.
|
||||
|
||||
## Async And Resources
|
||||
|
||||
- Do not block the event loop. Use async APIs, subprocess APIs, or
|
||||
`anyio.to_thread.run_sync` for sync I/O and CPU-bound library calls.
|
||||
- Use context managers for files, sessions, locks, temporary resources, and network
|
||||
clients. Cleanup must be visible in normal and exceptional paths.
|
||||
- Add timeouts around network, subprocess, and external-service operations when the
|
||||
called API supports them.
|
||||
- Do not share mutable state across concurrent tasks unless access is synchronized.
|
||||
- For this backend, do not share one SQLAlchemy `AsyncSession` across concurrent
|
||||
tasks; use a session per task/request.
|
||||
|
||||
## Tests
|
||||
|
||||
- Test behavior, not implementation details. Name tests after the observable rule.
|
||||
- Prefer deterministic fixtures, explicit inputs, and parametrized edge cases.
|
||||
- Cover failure paths for parsing, permissions, missing data, external services,
|
||||
and persistence boundaries.
|
||||
- Use unit tests for pure helpers and service/repository rules. Use integration tests
|
||||
for endpoint contracts and dependency overrides.
|
||||
- For bug fixes, write or update the failing test first when practical, then make
|
||||
the smallest code change that proves the fix.
|
||||
|
||||
## Security And Configuration
|
||||
|
||||
- Keep secrets in environment-backed settings, never source files, tests, fixtures,
|
||||
generated docs, or logs.
|
||||
- Validate paths, object keys, URLs, filenames, and user-controlled identifiers at
|
||||
the boundary.
|
||||
- Prefer allowlists for modes, providers, file types, and status transitions.
|
||||
- Treat serialization as a boundary: expose only fields that should leave the module
|
||||
or API.
|
||||
|
||||
## Project Tooling
|
||||
|
||||
Use the repository's Python 3.11+ and `uv` workflow. Keep Ruff formatting with the
|
||||
configured 100-character line length.
|
||||
|
||||
```bash
|
||||
uv run ruff format cpv3 tests
|
||||
uv run ruff check cpv3 tests
|
||||
uv run pytest
|
||||
```
|
||||
|
||||
Run narrower checks while iterating, then broaden when the change touches shared
|
||||
behavior. If verification cannot run, record the exact blocker.
|
||||
|
||||
## Project Overlay
|
||||
|
||||
- FastAPI HTTP concerns belong in `router.py`.
|
||||
- Pydantic DTOs belong in `schemas.py` and usually inherit
|
||||
`cpv3.common.schemas.Schema`.
|
||||
- Business orchestration belongs in `service.py`.
|
||||
- SQLAlchemy statements belong in `repository.py`.
|
||||
- Database shape changes need Alembic migrations and tests.
|
||||
- Do not rely on `.claude/` directory contents.
|
||||
@@ -0,0 +1,18 @@
|
||||
interface:
|
||||
display_name: "Python Practices"
|
||||
short_description: "Python quality practices for this repo"
|
||||
default_prompt: "Use $python-practices to guide Python changes in this repository."
|
||||
dependencies:
|
||||
tools:
|
||||
- type: "mcp"
|
||||
value: "context7"
|
||||
description: "Fetch current documentation for library, framework, SDK, API, CLI, and cloud-service details."
|
||||
transport: "streamable_http"
|
||||
url: "https://mcp.context7.com/mcp"
|
||||
- type: "mcp"
|
||||
value: "tavily_search"
|
||||
description: "Search the web for current Python ecosystem practices and trade-offs."
|
||||
transport: "streamable_http"
|
||||
url: "https://mcp.tavily.com/mcp/"
|
||||
policy:
|
||||
allow_implicit_invocation: true
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
name: rest-api-best-practices
|
||||
description: Use when designing, reviewing, or changing REST HTTP API routes, request and response shapes, status codes, idempotency, versioning, CORS, or Elysia handlers in this project.
|
||||
---
|
||||
|
||||
# REST API Best Practices
|
||||
|
||||
## Project Guidance
|
||||
|
||||
Treat HTTP semantics as part of the contract. Resource URLs should name things, while methods describe intentions. Keep the local Elysia API predictable for both the renderer and future Tauri callers.
|
||||
|
||||
Current routes include `/health`, `/api/status`, and `/api/echo`; preserve simple health/status behavior and use `/api/*` for application API surface unless the surrounding code establishes otherwise. Use JSON bodies and Elysia validation schemas at route boundaries. Return a consistent error envelope for validation and domain errors.
|
||||
|
||||
Prefer least-open CORS. `origin: true` is acceptable only for local development or clearly trusted callers. For production-facing API behavior, restrict origins to the renderer/Tauri app needs.
|
||||
|
||||
Version only when the public contract breaks. Do not add `/v2` for additive fields, new endpoints, or internal refactors.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
- `GET`: transfer the current representation. It is safe and should not mutate server state.
|
||||
- `POST`: process the enclosed representation. Use for creation under a collection or workflows where the server chooses the result URI. On successful creation, return `201 Created` and `Location` when a stable resource URL exists.
|
||||
- `PUT`: create or replace the target resource state at the request URI. Use when the client knows the target URI and repeated requests should have the same effect.
|
||||
- `PATCH`: partial update only when the patch format and merge semantics are explicit.
|
||||
- `DELETE`: remove the URI association. Repeated deletes should be safe to retry by outcome.
|
||||
- `200 OK`: successful response with a body.
|
||||
- `201 Created`: new resource created; include `Location` when applicable.
|
||||
- `202 Accepted`: work accepted but not finished.
|
||||
- `204 No Content`: success with no response body.
|
||||
- `400 Bad Request`: malformed syntax, invalid JSON, framing, or request structure.
|
||||
- `422 Unprocessable Content`: well-formed input that fails schema or semantic validation, when this project chooses to expose that distinction.
|
||||
- `401`: authentication required. `403`: authenticated caller lacks permission. `404`: resource not found.
|
||||
- `409`: request conflicts with current state.
|
||||
- `500`: unexpected server fault; do not expose internals.
|
||||
|
||||
Use idempotency keys for duplicate-prone `POST` workflows such as purchases, imports, job creation, or retry-heavy Tauri/native operations.
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
- Using verbs in paths like `/api/createUser` instead of resource paths like `/api/users`.
|
||||
- Mutating data in `GET` handlers.
|
||||
- Returning `200` for every outcome and hiding failures in JSON fields.
|
||||
- Creating resources with `POST` but omitting `201` and `Location` when the new URL is known.
|
||||
- Treating `POST` and `PUT` as interchangeable.
|
||||
- Returning different error shapes from validation, auth, and domain logic.
|
||||
- Adding API versions before there is a breaking contract change.
|
||||
- Leaving permissive CORS in code intended for non-local use.
|
||||
Reference in New Issue
Block a user