create-caspian-app 1.0.0 → 1.0.2

package/dist/settings/serve-static.py

@@ -1,188 +1,188 @@
-"""Robust static preview server for the exported `static/` build.
-
-Replaces the fragile ``python -m http.server ... 8000`` one-liner, which crashes
-with ``OSError: [Errno 98/10048] address already in use`` the moment port 8000 is
-taken (a second preview, another dev tool, XAMPP, etc.). This script instead:
-
-  - serves ONLY the ``static/`` directory (no traversal outside it),
-  - binds to loopback ``127.0.0.1`` by default so the preview is NOT exposed to
-    the local network,
-  - auto-selects a free port: it tries the preferred port and walks upward until
-    one binds, so an occupied port never aborts the preview,
-  - fails fast with a clear message if ``static/`` was never built,
-  - shuts down cleanly on Ctrl+C.
-
-Config via environment (all optional):
-  HOST         bind address           (default 127.0.0.1; use 0.0.0.0 to expose)
-  PORT         preferred start port   (default 8000)
-  PORT_TRIES   how many ports to try  (default 50)
-
-Run via ``npm run static:serve`` (after ``npm run static`` has produced static/).
-"""
-
-from __future__ import annotations
-
-import errno
-import os
-import socket
-import sys
-from functools import partial
-from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent
-STATIC_DIR = ROOT / "static"
-
-DEFAULT_HOST = "127.0.0.1"
-DEFAULT_PORT = 8000
-DEFAULT_PORT_TRIES = 50
-
-GREEN = "\033[32m"
-YELLOW = "\033[33m"
-RED = "\033[31m"
-DIM = "\033[2m"
-RESET = "\033[0m"
-
-# Errnos that mean "this port is taken, try the next one" across platforms.
-# EADDRINUSE covers POSIX (98) and Windows WSAEADDRINUSE (10048);
-# EACCES/WSAEACCES can appear on Windows when a port is held by another owner.
-_PORT_TAKEN = {errno.EADDRINUSE, errno.EACCES}
-if hasattr(errno, "WSAEADDRINUSE"):  # Windows-only alias
-    _PORT_TAKEN.add(errno.WSAEADDRINUSE)  # type: ignore[attr-defined]
-
-
-class SecureThreadingHTTPServer(ThreadingHTTPServer):
-    """Threaded server with reliable "is this port really free?" semantics.
-
-    ``allow_reuse_address`` maps to ``SO_REUSEADDR``. On Windows that flag lets a
-    NEW socket bind a port another socket is ACTIVELY listening on, which would
-    make our probe silently "succeed" onto an occupied port and collide. So we
-    disable it here: bind() then genuinely fails on a taken port and our
-    port-walk loop can move on. (On POSIX SO_REUSEADDR only affects TIME_WAIT
-    sockets, but keeping it off is harmless and keeps behavior identical.)
-    """
-
-    allow_reuse_address = False
-    daemon_threads = True
-
-
-class StaticRequestHandler(SimpleHTTPRequestHandler):
-    """Serve static/ with light hardening and quieter, useful logging.
-
-    SimpleHTTPRequestHandler already normalizes and confines paths to the served
-    ``directory`` (no ``..`` traversal), so this only adds conservative response
-    headers appropriate for a local static preview.
-    """
-
-    def end_headers(self) -> None:
-        self.send_header("X-Content-Type-Options", "nosniff")
-        self.send_header("Cache-Control", "no-store")
-        super().end_headers()
-
-    def log_message(self, format: str, *args) -> None:
-        sys.stderr.write(f"{DIM}  {self.address_string()} - {format % args}{RESET}\n")
-
-
-def _looks_built(static_dir: Path) -> bool:
-    """True only if static/ exists and holds a real export (an index.html)."""
-    return static_dir.is_dir() and (static_dir / "index.html").is_file()
-
-
-def _env_int(name: str, default: int) -> int:
-    raw = os.environ.get(name, "").strip()
-    if not raw:
-        return default
-    try:
-        value = int(raw)
-    except ValueError:
-        print(f"{YELLOW}  Ignoring invalid {name}={raw!r}; using {default}.{RESET}")
-        return default
-    return value
-
-
-def _serve(host: str, start_port: int, tries: int) -> int:
-    handler = partial(StaticRequestHandler, directory=str(STATIC_DIR))
-
-    last_error: OSError | None = None
-    for offset in range(max(1, tries)):
-        port = start_port + offset
-        if port > 65535:
-            break
-        try:
-            httpd = SecureThreadingHTTPServer((host, port), handler)
-        except OSError as exc:
-            if exc.errno in _PORT_TAKEN:
-                last_error = exc
-                if offset == 0:
-                    print(
-                        f"{YELLOW}  Port {start_port} is busy; searching for a free "
-                        f"port...{RESET}"
-                    )
-                continue
-            # A different error (bad host, permissions, etc.) is not recoverable
-            # by trying another port -- surface it.
-            print(f"{RED}  Failed to bind {host}:{port} -- {exc}{RESET}")
-            return 1
-
-        with httpd:
-            shown_host = "localhost" if host in ("127.0.0.1", "0.0.0.0") else host
-            url = f"http://{shown_host}:{port}"
-            if port != start_port:
-                print(
-                    f"{YELLOW}  Default port {start_port} was occupied; "
-                    f"using {port} instead.{RESET}"
-                )
-            print(f"\n{GREEN}Serving{RESET} {DIM}{STATIC_DIR}{RESET}")
-            print(f"{GREEN}  -> {url}{RESET}")
-            if host == "0.0.0.0":
-                lan = _lan_hint(port)
-                if lan:
-                    print(f"{DIM}  -> {lan} (exposed on your network){RESET}")
-            print(f"{DIM}  Press Ctrl+C to stop.{RESET}\n")
-            try:
-                httpd.serve_forever()
-            except KeyboardInterrupt:
-                print(f"\n{DIM}  Stopped.{RESET}")
-            return 0
-
-    ports = f"{start_port}-{start_port + max(1, tries) - 1}"
-    print(
-        f"{RED}  Could not find a free port in {ports} on {host}.{RESET}\n"
-        f"{DIM}  Last error: {last_error}. Free a port or set PORT to another "
-        f"start value.{RESET}"
-    )
-    return 1
-
-
-def _lan_hint(port: int) -> str | None:
-    """Best-effort LAN URL to show only when the user opted into 0.0.0.0."""
-    try:
-        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
-            s.connect(("8.8.8.8", 80))
-            ip = s.getsockname()[0]
-        return f"http://{ip}:{port}"
-    except OSError:
-        return None
-
-
-def main() -> int:
-    if not _looks_built(STATIC_DIR):
-        print(
-            f"{RED}No static build found at {STATIC_DIR}.{RESET}\n"
-            f"{DIM}  Build it first: {RESET}{GREEN}npm run static{RESET}"
-        )
-        return 1
-
-    host = os.environ.get("HOST", "").strip() or DEFAULT_HOST
-    start_port = _env_int("PORT", DEFAULT_PORT)
-    tries = _env_int("PORT_TRIES", DEFAULT_PORT_TRIES)
-
-    if not (1 <= start_port <= 65535):
-        print(f"{RED}  PORT must be 1-65535 (got {start_port}).{RESET}")
-        return 1
-
-    return _serve(host, start_port, tries)
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+"""Robust static preview server for the exported `static/` build.
+
+Replaces the fragile ``python -m http.server ... 8000`` one-liner, which crashes
+with ``OSError: [Errno 98/10048] address already in use`` the moment port 8000 is
+taken (a second preview, another dev tool, XAMPP, etc.). This script instead:
+
+  - serves ONLY the ``static/`` directory (no traversal outside it),
+  - binds to loopback ``127.0.0.1`` by default so the preview is NOT exposed to
+    the local network,
+  - auto-selects a free port: it tries the preferred port and walks upward until
+    one binds, so an occupied port never aborts the preview,
+  - fails fast with a clear message if ``static/`` was never built,
+  - shuts down cleanly on Ctrl+C.
+
+Config via environment (all optional):
+  HOST         bind address           (default 127.0.0.1; use 0.0.0.0 to expose)
+  PORT         preferred start port   (default 8000)
+  PORT_TRIES   how many ports to try  (default 50)
+
+Run via ``npm run static:serve`` (after ``npm run static`` has produced static/).
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import socket
+import sys
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+STATIC_DIR = ROOT / "static"
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8000
+DEFAULT_PORT_TRIES = 50
+
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+RED = "\033[31m"
+DIM = "\033[2m"
+RESET = "\033[0m"
+
+# Errnos that mean "this port is taken, try the next one" across platforms.
+# EADDRINUSE covers POSIX (98) and Windows WSAEADDRINUSE (10048);
+# EACCES/WSAEACCES can appear on Windows when a port is held by another owner.
+_PORT_TAKEN = {errno.EADDRINUSE, errno.EACCES}
+if hasattr(errno, "WSAEADDRINUSE"):  # Windows-only alias
+    _PORT_TAKEN.add(errno.WSAEADDRINUSE)  # type: ignore[attr-defined]
+
+
+class SecureThreadingHTTPServer(ThreadingHTTPServer):
+    """Threaded server with reliable "is this port really free?" semantics.
+
+    ``allow_reuse_address`` maps to ``SO_REUSEADDR``. On Windows that flag lets a
+    NEW socket bind a port another socket is ACTIVELY listening on, which would
+    make our probe silently "succeed" onto an occupied port and collide. So we
+    disable it here: bind() then genuinely fails on a taken port and our
+    port-walk loop can move on. (On POSIX SO_REUSEADDR only affects TIME_WAIT
+    sockets, but keeping it off is harmless and keeps behavior identical.)
+    """
+
+    allow_reuse_address = False
+    daemon_threads = True
+
+
+class StaticRequestHandler(SimpleHTTPRequestHandler):
+    """Serve static/ with light hardening and quieter, useful logging.
+
+    SimpleHTTPRequestHandler already normalizes and confines paths to the served
+    ``directory`` (no ``..`` traversal), so this only adds conservative response
+    headers appropriate for a local static preview.
+    """
+
+    def end_headers(self) -> None:
+        self.send_header("X-Content-Type-Options", "nosniff")
+        self.send_header("Cache-Control", "no-store")
+        super().end_headers()
+
+    def log_message(self, format: str, *args) -> None:
+        sys.stderr.write(f"{DIM}  {self.address_string()} - {format % args}{RESET}\n")
+
+
+def _looks_built(static_dir: Path) -> bool:
+    """True only if static/ exists and holds a real export (an index.html)."""
+    return static_dir.is_dir() and (static_dir / "index.html").is_file()
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        print(f"{YELLOW}  Ignoring invalid {name}={raw!r}; using {default}.{RESET}")
+        return default
+    return value
+
+
+def _serve(host: str, start_port: int, tries: int) -> int:
+    handler = partial(StaticRequestHandler, directory=str(STATIC_DIR))
+
+    last_error: OSError | None = None
+    for offset in range(max(1, tries)):
+        port = start_port + offset
+        if port > 65535:
+            break
+        try:
+            httpd = SecureThreadingHTTPServer((host, port), handler)
+        except OSError as exc:
+            if exc.errno in _PORT_TAKEN:
+                last_error = exc
+                if offset == 0:
+                    print(
+                        f"{YELLOW}  Port {start_port} is busy; searching for a free "
+                        f"port...{RESET}"
+                    )
+                continue
+            # A different error (bad host, permissions, etc.) is not recoverable
+            # by trying another port -- surface it.
+            print(f"{RED}  Failed to bind {host}:{port} -- {exc}{RESET}")
+            return 1
+
+        with httpd:
+            shown_host = "localhost" if host in ("127.0.0.1", "0.0.0.0") else host
+            url = f"http://{shown_host}:{port}"
+            if port != start_port:
+                print(
+                    f"{YELLOW}  Default port {start_port} was occupied; "
+                    f"using {port} instead.{RESET}"
+                )
+            print(f"\n{GREEN}Serving{RESET} {DIM}{STATIC_DIR}{RESET}")
+            print(f"{GREEN}  -> {url}{RESET}")
+            if host == "0.0.0.0":
+                lan = _lan_hint(port)
+                if lan:
+                    print(f"{DIM}  -> {lan} (exposed on your network){RESET}")
+            print(f"{DIM}  Press Ctrl+C to stop.{RESET}\n")
+            try:
+                httpd.serve_forever()
+            except KeyboardInterrupt:
+                print(f"\n{DIM}  Stopped.{RESET}")
+            return 0
+
+    ports = f"{start_port}-{start_port + max(1, tries) - 1}"
+    print(
+        f"{RED}  Could not find a free port in {ports} on {host}.{RESET}\n"
+        f"{DIM}  Last error: {last_error}. Free a port or set PORT to another "
+        f"start value.{RESET}"
+    )
+    return 1
+
+
+def _lan_hint(port: int) -> str | None:
+    """Best-effort LAN URL to show only when the user opted into 0.0.0.0."""
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+            s.connect(("8.8.8.8", 80))
+            ip = s.getsockname()[0]
+        return f"http://{ip}:{port}"
+    except OSError:
+        return None
+
+
+def main() -> int:
+    if not _looks_built(STATIC_DIR):
+        print(
+            f"{RED}No static build found at {STATIC_DIR}.{RESET}\n"
+            f"{DIM}  Build it first: {RESET}{GREEN}npm run static{RESET}"
+        )
+        return 1
+
+    host = os.environ.get("HOST", "").strip() or DEFAULT_HOST
+    start_port = _env_int("PORT", DEFAULT_PORT)
+    tries = _env_int("PORT_TRIES", DEFAULT_PORT_TRIES)
+
+    if not (1 <= start_port <= 65535):
+        print(f"{RED}  PORT must be 1-65535 (got {start_port}).{RESET}")
+        return 1
+
+    return _serve(host, start_port, tries)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/tests/README.md

@@ -1,135 +1,135 @@
-# App tests & quality gate
-
-Type check + lint + template lint + tests for the **application** code
-(`main.py`, `src/**`, and authored markup) — not the Caspian framework under
-`.venv/` or `node_modules/`.
-
-## The command
-
-```bash
-npm run check
-```
-
-That is the single production gate. It runs **pyright** (types), **ruff**
-(lint), **templates** (markup lint), and **pytest** (tests) in one pass, prints
-every problem as `path:line:col  [tool:code] message`, and exits non-zero on
-failure — so CI, a pre-commit hook, or an agent is told exactly which file and
-location to fix.
-
-While debugging you can narrow to one tool:
-
-```bash
-uv run python settings/check.py --only pyright   # or ruff / templates / pytest
-```
-
-## The `templates` check
-
-`settings/check_templates.py` scans `src/**/*.html` and the markup inside
-single-file Python components for JSX and directives PulsePoint does not have.
-
-PulsePoint borrows React's hook API inside `<script>` and React's component
-decomposition — never React's markup syntax. Before this check existed, the
-whole `.html` surface was unvalidated, and two failures shipped repeatedly:
-
-- `{users.map(user => (<tr/>))}` renders one literal row plus stray text.
-- `class={...}` (unquoted) is **invalid HTML** — the parser shreds the element,
-  the component root never compiles, and the route serves a blank page with *no
-  console error at all*.
-
-It skips `<script>`, `<pre>`/`<code>`, and HTML comments, so real component
-JavaScript (`rows.map(...)` is correct there) and documentation samples do not
-trip it. Run it alone with:
-
-```bash
-uv run python settings/check_templates.py
-```
-
-Its own coverage lives in `tests/test_check_templates.py`, which asserts both
-directions — every JSX shape is caught, and correct markup stays silent — plus a
-repo-wide assertion that `src/` is currently clean.
-
-## Browser errors in the dev terminal — and in a file
-
-`npm run dev` forwards PulsePoint's browser-side `[PP-ERROR]` / `[PP-WARN]`
-output, uncaught errors, and unhandled rejections into the terminal, so a broken
-route is visible without opening DevTools. See the `AGENTS.md` entry for how the
-pieces fit (`settings/dev-log-bridge.ts` + `_inject_dev_console_bridge` in
-`main.py`). It is development-only: the injecting branch is gated on
-`CASPIAN_BROWSER_SYNC_PORT`, which only the dev stack sets.
-
-The same events are appended to `.casp/browser-log.jsonl`, because stdout only
-reaches whoever owns that terminal. Read it with:
-
-```bash
-npm run logs
-```
-
-`npm run check` prints the same digest at the end of its run, but never lets it
-change the exit code — whether a route has been exercised depends on someone
-opening a browser, and a gate that flaky gets ignored. Use `--fail-on-error` if
-you want a non-zero exit in a script you control.
-
-The log records **successful page loads too**, which is what makes it safe to
-trust: a route's status is whatever happened during its most recent load, so a
-fixed error stops being reported after one clean reload, and an empty log reads
-as "nothing observed" rather than "healthy".
-
-A reload only proves what a reload re-runs. Errors are classified by how long
-after their page load they arrived: a **mount** error is cleared by a later load,
-an **interaction** error (a click handler throwing seconds later) is not — it
-carries forward as `NEEDS RECHECK` until you repeat the interaction. Reporting
-those as clean is how a live bug gets signed off.
-
-Every source change **compacts** the log to the session header, a `restart`
-marker, and the errors still open, so a dev session running for hours cannot grow
-an unbounded file. **Don't diagnose from the raw JSONL** — it is history, not
-state. `npm run logs` derives the current status and costs the same tokens
-regardless of session length. An error with no matching load — a tab left open
-across a dev restart — is reported as `UNCONFIRMED` rather than as a fresh
-failure. Coverage is in `tests/test_browser_log.py`.
-
-## Auto-fixing lint issues
-
-`npm run check` only **reports**. To auto-fix the ruff findings it lists, run:
-
-```bash
-npm run check:fix
-```
-
-That runs `settings/fix.py` (safely fixes lint issues — dead imports, redundant
-code, etc.) and then re-runs the full gate so you see what's left. Type errors
-(pyright) and failing tests (pytest) are never auto-fixed — fix those at the
-reported `path:line:col`.
-
-### How unused-import (F401) removal stays safe
-
-Removing "unused" imports is the one fix that is dangerous in this app. Caspian
-single-file components import their children and then use them only as `<x-*>`
-tags inside `html(...)`/`render_html(...)` template strings (e.g. `from .Dialog
-import DialogContent` → `<x-dialog-content>`). Ruff can't parse the template, so
-it sees the import as unused — but casp resolves the tag from the module's
-globals at render time, so deleting it breaks the page.
-
-Two layers keep this safe, so `check:fix` still cleans real dead imports:
-
-- **A raw `ruff check --fix` never deletes any import.** `F401` is marked
-  `unfixable` in `pyproject.toml`, so even if someone runs ruff directly, no
-  component import is ever stripped.
-- **`npm run check:fix` removes only genuinely dead imports.** `settings/fix.py`
-  asks ruff which files have an `F401`, skips any file that contains an import
-  used as an `<x-*>` tag (leaving those whole), and removes dead imports from the
-  rest via an isolated ruff run. Component-guarded files are left for the gate to
-  report, so you decide by hand there.
-
-`settings/check.py` also suppresses the `F401` *reports* whose symbol is used as
-an `<x-*>` tag, so **the gate fails only on genuinely dead imports**. The
-`<x-*>`-tag detection is shared between the fixer and the gate in
-`settings/_component_imports.py`.
-
-## Tools (Python dev group in `pyproject.toml`)
-
-- **pyright** — type checker. Config in `[tool.pyright]`: `include = ["main.py", "src", "settings/*.py"]` with `exclude = [".venv", "node_modules", "**/__pycache__"]`, so it checks `main.py`, all of `src` (including the generated `src/lib/prisma/**` ORM), and the top-level `settings/*.py` tooling scripts (mirroring ruff's `include`). Pylance reads the same config, so the IDE and `npm run check` agree.
-- **ruff** — linter. Config in `[tool.ruff]`; correctness-focused rules.
-- **pytest** — test runner. Tests live in `tests/`.
-
-Install/refresh them with `uv sync --group dev`.
+# App tests & quality gate
+
+Type check + lint + template lint + tests for the **application** code
+(`main.py`, `src/**`, and authored markup) — not the Caspian framework under
+`.venv/` or `node_modules/`.
+
+## The command
+
+```bash
+npm run check
+```
+
+That is the single production gate. It runs **pyright** (types), **ruff**
+(lint), **templates** (markup lint), and **pytest** (tests) in one pass, prints
+every problem as `path:line:col  [tool:code] message`, and exits non-zero on
+failure — so CI, a pre-commit hook, or an agent is told exactly which file and
+location to fix.
+
+While debugging you can narrow to one tool:
+
+```bash
+uv run python settings/check.py --only pyright   # or ruff / templates / pytest
+```
+
+## The `templates` check
+
+`settings/check_templates.py` scans `src/**/*.html` and the markup inside
+single-file Python components for JSX and directives PulsePoint does not have.
+
+PulsePoint borrows React's hook API inside `<script>` and React's component
+decomposition — never React's markup syntax. Before this check existed, the
+whole `.html` surface was unvalidated, and two failures shipped repeatedly:
+
+- `{users.map(user => (<tr/>))}` renders one literal row plus stray text.
+- `class={...}` (unquoted) is **invalid HTML** — the parser shreds the element,
+  the component root never compiles, and the route serves a blank page with *no
+  console error at all*.
+
+It skips `<script>`, `<pre>`/`<code>`, and HTML comments, so real component
+JavaScript (`rows.map(...)` is correct there) and documentation samples do not
+trip it. Run it alone with:
+
+```bash
+uv run python settings/check_templates.py
+```
+
+Its own coverage lives in `tests/test_check_templates.py`, which asserts both
+directions — every JSX shape is caught, and correct markup stays silent — plus a
+repo-wide assertion that `src/` is currently clean.
+
+## Browser errors in the dev terminal — and in a file
+
+`npm run dev` forwards PulsePoint's browser-side `[PP-ERROR]` / `[PP-WARN]`
+output, uncaught errors, and unhandled rejections into the terminal, so a broken
+route is visible without opening DevTools. See the `AGENTS.md` entry for how the
+pieces fit (`settings/dev-log-bridge.ts` + `_inject_dev_console_bridge` in
+`main.py`). It is development-only: the injecting branch is gated on
+`CASPIAN_BROWSER_SYNC_PORT`, which only the dev stack sets.
+
+The same events are appended to `.casp/browser-log.jsonl`, because stdout only
+reaches whoever owns that terminal. Read it with:
+
+```bash
+npm run logs
+```
+
+`npm run check` prints the same digest at the end of its run, but never lets it
+change the exit code — whether a route has been exercised depends on someone
+opening a browser, and a gate that flaky gets ignored. Use `--fail-on-error` if
+you want a non-zero exit in a script you control.
+
+The log records **successful page loads too**, which is what makes it safe to
+trust: a route's status is whatever happened during its most recent load, so a
+fixed error stops being reported after one clean reload, and an empty log reads
+as "nothing observed" rather than "healthy".
+
+A reload only proves what a reload re-runs. Errors are classified by how long
+after their page load they arrived: a **mount** error is cleared by a later load,
+an **interaction** error (a click handler throwing seconds later) is not — it
+carries forward as `NEEDS RECHECK` until you repeat the interaction. Reporting
+those as clean is how a live bug gets signed off.
+
+Every source change **compacts** the log to the session header, a `restart`
+marker, and the errors still open, so a dev session running for hours cannot grow
+an unbounded file. **Don't diagnose from the raw JSONL** — it is history, not
+state. `npm run logs` derives the current status and costs the same tokens
+regardless of session length. An error with no matching load — a tab left open
+across a dev restart — is reported as `UNCONFIRMED` rather than as a fresh
+failure. Coverage is in `tests/test_browser_log.py`.
+
+## Auto-fixing lint issues
+
+`npm run check` only **reports**. To auto-fix the ruff findings it lists, run:
+
+```bash
+npm run check:fix
+```
+
+That runs `settings/fix.py` (safely fixes lint issues — dead imports, redundant
+code, etc.) and then re-runs the full gate so you see what's left. Type errors
+(pyright) and failing tests (pytest) are never auto-fixed — fix those at the
+reported `path:line:col`.
+
+### How unused-import (F401) removal stays safe
+
+Removing "unused" imports is the one fix that is dangerous in this app. Caspian
+single-file components import their children and then use them only as `<x-*>`
+tags inside `html(...)`/`render_html(...)` template strings (e.g. `from .Dialog
+import DialogContent` → `<x-dialog-content>`). Ruff can't parse the template, so
+it sees the import as unused — but casp resolves the tag from the module's
+globals at render time, so deleting it breaks the page.
+
+Two layers keep this safe, so `check:fix` still cleans real dead imports:
+
+- **A raw `ruff check --fix` never deletes any import.** `F401` is marked
+  `unfixable` in `pyproject.toml`, so even if someone runs ruff directly, no
+  component import is ever stripped.
+- **`npm run check:fix` removes only genuinely dead imports.** `settings/fix.py`
+  asks ruff which files have an `F401`, skips any file that contains an import
+  used as an `<x-*>` tag (leaving those whole), and removes dead imports from the
+  rest via an isolated ruff run. Component-guarded files are left for the gate to
+  report, so you decide by hand there.
+
+`settings/check.py` also suppresses the `F401` *reports* whose symbol is used as
+an `<x-*>` tag, so **the gate fails only on genuinely dead imports**. The
+`<x-*>`-tag detection is shared between the fixer and the gate in
+`settings/_component_imports.py`.
+
+## Tools (Python dev group in `pyproject.toml`)
+
+- **pyright** — type checker. Config in `[tool.pyright]`: `include = ["main.py", "src", "settings/*.py"]` with `exclude = [".venv", "node_modules", "**/__pycache__"]`, so it checks `main.py`, all of `src` (including the generated `src/lib/prisma/**` ORM), and the top-level `settings/*.py` tooling scripts (mirroring ruff's `include`). Pylance reads the same config, so the IDE and `npm run check` agree.
+- **ruff** — linter. Config in `[tool.ruff]`; correctness-focused rules.
+- **pytest** — test runner. Tests live in `tests/`.
+
+Install/refresh them with `uv sync --group dev`.