chore: agentic upgrade

2026-05-17 02:11:48 +03:00
parent a2d92a4da9
commit cca1668fee
13 changed files with 325 additions and 549 deletions
@@ -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.