Metic 3.0.0: unified TypeScript core + Bun server (#532)

.dockerignore

@@ -43,9 +43,12 @@ data/
 logs/
 *.log
 
-# Node modules (web builder stage installs fresh)
+# Node modules (builder stages install fresh)
 apps/web/node_modules/
 apps/web/dist/
+apps/bun-server/node_modules/
+apps/bun-server/dist/
+packages/core/node_modules/
 
 # Python cache
 __pycache__/

.github/CONVENTIONS.md

@@ -17,9 +17,9 @@
 
 | Purpose | Pattern | Example |
 |---------|---------|---------|
-| Milestone work | `version/X.Y.Z` | `version/2.2.0` |
+| Milestone work | `version/X.Y.Z` | `version/3.0.0` |
 | Feature branch | `feat/<name>` | `feat/temp-variables` |
-| Website updates | `website/<name>` | `website/v2.2-redesign` |
+| Website updates | `website/<name>` | `website/v3-redesign` |
 | Bugfix | `fix/<name>` | `fix/cache-overflow` |
 | Pages deployment | `pages` | `pages` (protected) |
 
@@ -30,40 +30,43 @@
 
 These are **non-negotiable**. Every PR, every push, every completion claim:
 
-1. **CI must be completely green.** The Test Suite has 5 jobs (Web Tests, Server Tests, Code Quality, Web E2E, Docker Build Test) plus a separate Build and Publish workflow. All must pass.
+1. **CI must be completely green.** The Test Suite jobs plus the separate Build and Publish workflow must pass.
 2. **Zero tech debt.** Address all issues immediately. Never defer tasks to "later".
 3. **No deferred tasks.** If a task is in scope, it gets done now — not added to a backlog.
 4. **All code review comments addressed.** Including suppressed/collapsed threads. Don't dismiss without clear justification.
 5. **Tests pass locally before pushing.** Don't rely on CI as your first test run.
 6. **Wide review on bug discovery.** When discovering a bug or potential issue, always do a wide review to look for the same or similar issues across the codebase. Bugs are often part of a pattern — fix the pattern, not just the instance.
-7. **Dual-runtime feature parity (server + native).** Metic ships in two runtimes (see *Architecture Patterns → Dual runtime*). Any change to analysis, profile generation, target-curve math, recommendations, dial-in, or machine-API behavior **must be applied to both** the Python server path *and* the native/Capacitor DirectMode path **in the same PR** — even when the user only reports it against one. Before claiming a fix complete, search the *other* runtime for a parallel implementation and update it too. Mismatched behavior between runtimes is a release-blocking defect.
+7. **Dual-runtime feature parity (server + native).** Metic ships in two runtimes (see *Architecture Patterns → Dual runtime*) that consume shared `@metic/core` business logic. Any change to analysis, profile generation, target-curve math, recommendations, dial-in, or machine-API behavior belongs in `@metic/core` whenever possible and must be tested in both server mode and native/direct mode. Runtime-specific code should stay limited to thin platform adapters and native-only UI.
 8. **Browser testing before release.** Run the full browser testing protocol (`.github/skills/browser-testing.md`) against a live Docker container before any non-beta version bump.
 
 ## Testing
 
-### Backend (Python)
+### Shared Core (TypeScript)
 ```bash
-cd apps/server && TEST_MODE=true .venv/bin/python -m pytest test_main.py -x -q
+cd packages/core && bun test && bun run typecheck
 ```
-- Currently 750+ tests. New code must include tests in `test_main.py`.
-- Test both success and failure/edge-case paths.
+- Add tests under `packages/core/test/` for shared business logic, route behavior, and failure/edge-case paths.
+
+### Bun Server (TypeScript)
+```bash
+cd apps/bun-server && bun test && bun run typecheck
+```
+- Add tests under `apps/bun-server/test/` for server-only behavior: static serving, machine proxying, storage/config wiring, and telemetry.
 
 ### Frontend (TypeScript/React)
 ```bash
 cd apps/web && bun run test:run
 ```
-- Currently 277+ tests.
-- Lint must be clean: `bun run lint` (0 errors; warnings OK per eslint v7 migration issue #256).
+- Lint must be clean: `bun run lint` (0 errors; warnings OK per eslint migration issues).
 - Build must succeed: `bun run build`.
 
 ### Full Local Gate (run before pushing)
 ```bash
-cd apps/server && TEST_MODE=true .venv/bin/python -m pytest test_main.py -x -q && \
-cd ../web && bun run lint && bun run test:run && bun run build
+cd packages/core && bun test && bun run typecheck && cd ../../apps/bun-server && bun test && bun run typecheck && cd ../web && bun run lint && bun run test:run && bun run build
 ```
 
+- After all tests pass, also rebuild the Docker dev container (`docker compose -f docker-compose.yml -f docker-compose.dev.yml build`) and the Capacitor iOS app (`npx cap sync ios` + Xcode build) before marking a task complete when the change can affect container or native behavior.
 
-- After all tests pass, also rebuild the Docker dev container (`docker compose -f docker-compose.yml -f docker-compose.dev.yml build`) and the Capacitor iOS app (`npx cap sync ios` + Xcode build) before marking a task complete.
 ## Commits
 
 - **Format:** [Conventional Commits](https://www.conventionalcommits.org/) — `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `ci:`.
@@ -93,37 +96,39 @@ cd ../web && bun run lint && bun run test:run && bun run build
 - Bun version is pinned at **1.3.14** in both `docker/Dockerfile.unified` and CI workflows.
 - Import from `lucide-react` public paths only (never private `dist` paths).
 
-### Backend
-- Pin versions in `apps/server/requirements.txt`.
+### Core / Bun Server
+- Use `bun add <package>` in the affected package (`packages/core` or `apps/bun-server`).
+- Always commit that package's `bun.lock` alongside `package.json` changes.
 - Rebuild the container after dependency changes.
 
 ## Code Style
 
-### Python (apps/server/)
-- PEP 8 strict. Extensive type hints. Google-style docstrings.
-- Functions: focused and single-purpose.
-- Concurrency: `threading.Lock` for synchronous file I/O, `asyncio.Lock` for async operations.
-- Lazy lock creation (`_get_lock()` pattern) to avoid "attached to different loop" errors in tests.
+### TypeScript Core / Server (`packages/core/`, `apps/bun-server/`)
+- Use strict TypeScript with clear public types.
+- Keep shared product behavior in `@metic/core`; do not duplicate it in runtime-specific adapters.
+- Keep runtime-specific I/O behind `packages/core/src/platform.ts` abstractions.
+- Routes live in `packages/core/src/routes/`; request handling is coordinated by `packages/core/src/handler.ts`.
 
-### TypeScript/React (apps/web/)
+### TypeScript/React (`apps/web/`)
 - Functional components with hooks only. No class components.
-- ESLint compliance (react-hooks rules). 5 strict v7 rules downgraded to warn (issue #256).
+- ESLint compliance (react-hooks rules). Strict rules downgraded to warnings remain warnings only; do not introduce errors.
 - Extend shadcn/ui components in `apps/web/src/components/ui/`; don't replace them.
 - Mobile-first responsive design.
 
 ## Architecture Patterns
 
-- **Dual runtime (server + native) — feature parity is mandatory.** Metic runs in two modes that re-implement the same product behavior in two languages:
-  - **Server mode:** the React web app talks to the Python FastAPI backend (`apps/server/`), which performs AI analysis, profile generation, target-curve math, recommendations, and machine I/O.
-  - **Native/Capacitor mode:** the iOS app has **no Python server**. The same behavior is reimplemented client-side and served by a fetch interceptor. Key files: `apps/web/src/services/interceptor/DirectModeInterceptor.ts` (route/API parity + curve generation), `apps/web/src/services/ai/` (`BrowserAIService`, prompts), `apps/web/src/lib/directModeAI.ts`, and `apps/web/src/lib/profileAnalysis.ts`.
+- **Dual runtime (server + native) — shared core is mandatory.** Metic runs in two modes that share product behavior through `@metic/core`:
+  - **Server mode:** the React web app is served by the Bun server (`apps/bun-server`, `@metic/server`), which delegates `/api/*` REST requests to the shared `@metic/core` `handle()` function.
+  - **Native/Capacitor mode:** iOS/Android (Capacitor) or PWA on-machine has no server. The web app installs the core interceptor (`installCoreInterceptor`) so `/api/*` calls route through the same `@metic/core` `handle()` in-process.
 
-  **Rule:** logic that exists in both runtimes must stay in sync. When you touch a backend service in `apps/server/services/` (or vice-versa), grep the DirectMode layer for the parallel implementation and apply the equivalent change **in the same PR**, with tests on both sides. Treat the Python function and its TypeScript port as one feature with two implementations. Examples of paired logic: target-curve generation (`analysis_service.py` ↔ `DirectModeInterceptor.ts`), shot analysis, profile/variable handling, recommendation patching, dial-in. This parity requirement is non-negotiable (Quality Gate #7) and applies even when the user only mentions one runtime.
+  **Rule:** business logic for analysis, profile generation, target-curve math, recommendations, dial-in, and machine-API behavior belongs once in `packages/core`. Changes there apply to both runtimes. What still differs per runtime is the thin platform adapter (server platform vs browser/native platform) and native-only UI such as iOS Live Activity and widgets. Test both runtimes when user-visible behavior can differ.
 
-- **Dual route registration:** Both `/endpoint` and `/api/endpoint` are registered for every route. This is intentional to support clients that include or omit the `/api` prefix. Not a defect.
-- **Unified container:** Single Docker container managed by s6-overlay. Port 3550 is the only exposed port (nginx proxy).
-- **Settings hot-reload:** Changing `METICULOUS_IP` or `GEMINI_API_KEY` triggers `s6-svc -r` (service restart, not container restart).
+- **Unified container:** Single Docker container (`meticai`) running one self-contained Bun binary at `/app/metic` on port 3550. The image is distroless and has no process supervisor.
+- **Bun server:** `apps/bun-server` serves the built React SPA, delegates REST API handling under `/api/*` to `@metic/core`, transparently proxies the machine API (`/api/v1/*` → the Meticulous machine), and streams live telemetry over `/api/ws/live` while connecting upstream to the machine over Socket.IO.
+- **Storage:** Persistent data lives in `/data`; `STORAGE_BACKEND` is `json` by default or `sqlite`.
+- **Settings:** `METICULOUS_IP` and `GEMINI_API_KEY` changes are applied by the running Bun process or by restarting the container (`docker compose restart meticai` / `docker restart meticai`).
 - **Cache bounding:** In-memory caches must be bounded (e.g., 50 entries max). On insert: purge expired, then clear all if still over limit.
-- **Safe parsing:** Use helper functions (e.g., `_safe_float()`) for user-provided numeric values. Never trust raw input.
+- **Safe parsing:** Use helper functions for user-provided numeric values. Never trust raw input.
 
 ## Release Process
 
@@ -140,16 +145,16 @@ cd ../web && bun run lint && bun run test:run && bun run build
 - **Profile Generation Output:** Always include "Profile Created:", "Description:", "Preparation:", "Why This Works:", and "Special Notes:".
 - **Reference:** See `PROFILING_AXIOMS.md` for extraction principles, stage-based profiling, and exit trigger rules.
 - **Profile Variables:** Two types — INFO (`info_` prefix, display-only, emoji names) and ADJUSTABLE (no prefix, user-modifiable types: pressure/flow/weight/power/time).
-- **Temporary Profiles:** Managed via `temp_profile_service.py` — create_and_load → cleanup/force_cleanup lifecycle.
+- **Temporary Profiles:** Managed through shared `@metic/core` route/logic behavior and machine I/O; keep the lifecycle consistent across server and native/direct mode.
 
 ## CI Structure
 
-- **Test Suite workflow:** 5 jobs — Web Tests, Server Tests, Code Quality, Web E2E, Docker Build Test.
+- **Test Suite workflow:** includes web tests, core/server tests, code quality, web E2E, Docker build testing, and platform-specific checks.
 - **Build and Publish workflow:** Separate, runs on merge to main.
 - **Bun setup in CI:** Uses 3-attempt retry pattern to handle transient download failures.
 - **Triggers:** Test Suite runs on PRs to `main`. Build and Publish on push to `main`.
 
 ---
 
-*Last updated: 2026-06-16 | Maintained by the Metic team and AI agents*
+*Last updated: 2026-08-26 | Maintained by the Metic team and AI agents*
 *To add a new convention, use the `learn_convention` extension tool or edit this file directly.*

.github/copilot-instructions.md

@@ -1,21 +1,23 @@
 # Metic — Agent Instructions
 
-Metic is an AI-powered controller for the Meticulous Espresso Machine. Stack: Python 3.13 (FastAPI), React + TypeScript (Vite/Bun), Google Gemini Python SDK, Docker + s6-overlay. Repository: https://github.com/hessius/MeticAI. The `VERSION` file triggers the auto-release workflow.
+Metic is an AI-powered controller for the Meticulous Espresso Machine. Stack: Bun single-binary server (`apps/bun-server`, `@metic/server`) + shared TypeScript core (`packages/core`, `@metic/core`), React + TypeScript (Vite/Bun), Google Gemini, Docker distroless single container. Repository: https://github.com/hessius/MeticAI. The `VERSION` file triggers the auto-release workflow.
 
 ## Core Architecture
 
-- **Unified Container:** Single container (`meticai`) via s6-overlay. Port 3550 exposed (nginx proxy).
-- **Settings Hot-Reload:** Changing `METICULOUS_IP` or `GEMINI_API_KEY` restarts services (`s6-svc -r`) without full container restart.
-- **Environment:** Requires `.env` with `GEMINI_API_KEY` and `METICULOUS_IP`.
+- **Unified Container:** Single container (`meticai`) with one self-contained Bun binary at `/app/metic`. Port 3550 is exposed directly by the Bun server.
+- **Bun Server:** `apps/bun-server` serves the built React SPA, delegates REST API handling under `/api/*` to `@metic/core`, transparently proxies machine API calls (`/api/v1/*` → the Meticulous machine), and streams live telemetry on `/api/ws/live` via native WebSocket while connecting upstream to the machine over Socket.IO.
+- **Shared Core:** Business logic for AI analysis, profile generation, target-curve math, recommendations, dial-in, and machine I/O lives once in `packages/core` (`@metic/core`).
+- **Storage & Environment:** Persistent data lives in `/data`; `STORAGE_BACKEND` is `json` (default) or `sqlite`. Common env: `GEMINI_API_KEY`, `GEMINI_MODEL`, `METICULOUS_IP`, `DATA_DIR=/data`.
+- **Settings Changes:** `METICULOUS_IP` and `GEMINI_API_KEY` are applied by the running Bun process or by restarting the container (`docker compose restart meticai` / `docker restart meticai`).
 
-## Dual Runtime — Feature Parity (read before any logic change)
+## Dual Runtime — Shared Core (read before any logic change)
 
-Metic ships in **two runtimes** that implement the same behavior twice:
+Metic ships in **two runtimes** that consume the same `@metic/core` behavior:
 
-- **Server mode:** React web app + Python FastAPI backend (`apps/server/`) for AI analysis, profile generation, target-curve math, recommendations, machine I/O.
-- **Native/Capacitor mode:** iOS app with **no Python server** — that logic is reimplemented client-side in `apps/web/src/services/interceptor/DirectModeInterceptor.ts`, `apps/web/src/services/ai/`, `apps/web/src/lib/directModeAI.ts`, and `apps/web/src/lib/profileAnalysis.ts`.
+- **Server mode:** React web app served by the Bun server, which calls the shared `@metic/core` `handle()` function.
+- **Native/Capacitor mode:** iOS/Android (Capacitor) or PWA on-machine with no server; the web app installs the core interceptor (`installCoreInterceptor`) and routes `/api/*` calls through the same `@metic/core` `handle()` in-process.
 
-**Guardrail (do this automatically, without being asked):** any change to analysis / profile / curve / recommendation / dial-in / machine-API logic in one runtime **must** be mirrored in the other within the same change, with tests on both sides. After fixing one side, always grep the other runtime for the parallel implementation. Mismatched behavior between runtimes is a release-blocking bug. See `.github/CONVENTIONS.md` → Quality Gate #7 and *Architecture Patterns → Dual runtime*.
+**Guardrail (do this automatically, without being asked):** business logic belongs in `@metic/core`; changes there apply to both runtimes. Do not duplicate logic in runtime-specific adapters. What still differs per runtime is the thin platform adapter (server platform vs browser/native platform) and native-only UI (Live Activity, widgets). Test both server mode and native/direct mode for analysis / profile / curve / recommendation / dial-in / machine-API behavior. See `.github/CONVENTIONS.md` → Quality Gate #7 and *Architecture Patterns → Dual runtime*.
 
 ## Conventions
 

.github/dependabot.yml

@@ -3,51 +3,49 @@
 
 version: 2
 updates:
-  # Python — FastAPI server
-  - package-ecosystem: "pip"
-    directory: "/apps/server"
+  # npm — Web frontend (Bun uses package.json)
+  - package-ecosystem: "npm"
+    directory: "/apps/web"
     schedule:
       interval: "weekly"
       day: "monday"
-    open-pull-requests-limit: 5
+    open-pull-requests-limit: 10
     labels:
       - "dependencies"
-      - "python"
+      - "javascript"
     commit-message:
       prefix: "chore(deps)"
+    groups:
+      dev-dependencies:
+        dependency-type: "development"
+        update-types: ["minor", "patch"]
+      production-dependencies:
+        dependency-type: "production"
+        update-types: ["patch"]
 
-  # Python — MCP server
-  - package-ecosystem: "pip"
-    directory: "/apps/mcp-server"
+  # npm — Bun server host (@metic/server)
+  - package-ecosystem: "npm"
+    directory: "/apps/bun-server"
     schedule:
       interval: "weekly"
       day: "monday"
-    open-pull-requests-limit: 3
     labels:
       - "dependencies"
-      - "python"
+      - "javascript"
     commit-message:
       prefix: "chore(deps)"
 
-  # npm — Web frontend (Bun uses package.json)
+  # npm — shared @metic/core handler
   - package-ecosystem: "npm"
-    directory: "/apps/web"
+    directory: "/packages/core"
     schedule:
       interval: "weekly"
       day: "monday"
-    open-pull-requests-limit: 10
     labels:
       - "dependencies"
       - "javascript"
     commit-message:
       prefix: "chore(deps)"
-    groups:
-      dev-dependencies:
-        dependency-type: "development"
-        update-types: ["minor", "patch"]
-      production-dependencies:
-        dependency-type: "production"
-        update-types: ["patch"]
 
   # Docker — unified Dockerfile
   - package-ecosystem: "docker"