tracelink 0.2.0__py3-none-any.whl

tracelink/__init__.py

@@ -0,0 +1,44 @@
+"""
+TraceLink — Python core tracer.
+
+Unified debug logging for FastAPI / Starlette apps. Writes to the same
+NDJSON + readable file pair as the TypeScript core, so frontend and
+backend events are correlated by traceId.
+
+Quick start:
+    from tracelink import debug_tracer
+    debug_tracer.start_scope('delete-work')
+    debug_tracer.entry('router.py:delete', 'Delete work', {'id': 123}, scope='delete-work')
+    debug_tracer.end_scope('delete-work')
+
+For automatic scope sync from frontend, also register the middleware:
+    from tracelink import TraceMiddleware
+    app.add_middleware(TraceMiddleware)
+
+Layer system — see docs/LAYERS.md (English) / docs/LAYERS.zh-CN.md (Chinese)
+for the rules on custom X-* layers.
+"""
+
+from .tracer import DebugTracer, debug_tracer
+from .types import TraceLayer
+from .middleware import TraceMiddleware
+from .types import (
+    BUILTIN_LAYERS,
+    is_builtin_layer,
+    is_custom_layer,
+    normalize_layer,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "DebugTracer",
+    "debug_tracer",
+    "TraceMiddleware",
+    "TraceLayer",
+    "BUILTIN_LAYERS",
+    "is_builtin_layer",
+    "is_custom_layer",
+    "normalize_layer",
+    "__version__",
+]

tracelink/_paths.py

@@ -0,0 +1,41 @@
+"""Resolve log file paths from env / project root."""
+
+import os
+from pathlib import Path
+
+
+def resolve_log_dir() -> Path:
+    """Resolve the project root where .cursor/ and .RandP/ live.
+
+    Priority:
+      1. TRACELINK_DIR env (absolute path)
+      2. Current working directory
+      3. Walk up from cwd until we find a package.json or pyproject.toml
+    """
+    env_dir = os.getenv("TRACELINK_DIR")
+    if env_dir:
+        return Path(env_dir)
+
+    cwd = Path.cwd()
+    # Walk up looking for project markers
+    for parent in [cwd, *cwd.parents]:
+        if any((parent / m).exists() for m in ("package.json", "pyproject.toml", "Cargo.toml", "go.mod")):
+            return parent
+
+    return cwd
+
+
+def cursor_dir() -> Path:
+    return resolve_log_dir() / ".cursor"
+
+
+def readable_dir() -> Path:
+    return resolve_log_dir() / ".RandP"
+
+
+def ndjson_path() -> Path:
+    return cursor_dir() / "debug.log"
+
+
+def readable_path() -> Path:
+    return readable_dir() / "debug.log"

tracelink/_time.py

@@ -0,0 +1,27 @@
+"""Time and ID helpers."""
+
+import os
+import time
+from datetime import datetime
+
+
+def now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def format_ts(ts: int | None = None) -> str:
+    if ts is None:
+        ts = now_ms()
+    dt = datetime.fromtimestamp(ts / 1000)
+    return f"[{dt.strftime('%H:%M:%S')}.{dt.microsecond // 1000:03d}]"
+
+
+def make_trace_id(scope: str) -> str:
+    """Generate traceId with format `<scope>-<timestamp6>-<rand3>`."""
+    ts_suffix = str(now_ms())[-6:]
+    rand_suffix = os.urandom(2).hex()[:3]
+    return f"{scope}-{ts_suffix}-{rand_suffix}"
+
+
+def make_span_id(counter: int) -> str:
+    return f"span-{counter}"

tracelink/cli.py

@@ -0,0 +1,74 @@
+"""TraceLink CLI — top-level `tracelink ...` entry point.
+
+Subcommands (v0.3):
+    board        Launch the dev-time 看板 (per docs/03-prd.md §10).
+
+Usage:
+    tracelink board [--port 8766] [--host 127.0.0.1] [--open]
+    python -m tracelink board
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+
+def _cmd_board(args: argparse.Namespace) -> int:
+    # Lazy import — keeps `tracelink --help` cheap and lets the dashboard
+    # module stay self-contained.
+    from .dashboard import serve_board
+
+    return serve_board(
+        host=args.host,
+        port=args.port,
+        auto_open=args.open,
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tracelink",
+        description="TraceLink dev-time CLI (v0.3+)",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_board = sub.add_parser(
+        "board",
+        help="Launch the dev-time 看板 (per docs/03-prd.md §10).",
+        description=(
+            "Serve a local browser-based board that reads the project's "
+            ".cursor/debug.log and .RandP/debug.log files, lets you switch "
+            "scopes at runtime, and filter historical events by scope."
+        ),
+    )
+    p_board.add_argument(
+        "--port",
+        type=int,
+        default=8766,
+        help="Port to bind the board server (default: 8766)",
+    )
+    p_board.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host to bind (default: 127.0.0.1 — localhost only by design)",
+    )
+    p_board.add_argument(
+        "--open",
+        action="store_true",
+        help="Open the board in your default browser after starting",
+    )
+    p_board.set_defaults(func=_cmd_board)
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tracelink/dashboard/__init__.py

@@ -0,0 +1,38 @@
+"""TraceLink dev-time dashboard (board).
+
+Public surface:
+    serve_board(...)    — start the stdlib HTTP server (CLI uses this)
+    fastapi_router     — drop-in FastAPI router (embed in your app)
+
+The CLI is `tracelink board` (see `tracelink.cli`). The package directory
+is `dashboard/` (architecture name); the user-facing command is `board`
+(product name). This keeps the package aligned with future dashboard
+expansion (analysis, AI summary, etc.) while the CLI stays short.
+
+Static UI is bundled at `dashboard/static/`. No build step required.
+"""
+
+from .server import serve_board, main
+from ._paths_resolve import (
+    scope_state_path,
+    load_scope_state,
+    save_scope_state,
+    is_scope_enabled,
+    scan_observed_scopes,
+    load_ndjson_events,
+)
+
+# Optional FastAPI router (None if FastAPI not installed)
+from .api import fastapi_router
+
+__all__ = [
+    "serve_board",
+    "main",
+    "fastapi_router",
+    "scope_state_path",
+    "load_scope_state",
+    "save_scope_state",
+    "is_scope_enabled",
+    "scan_observed_scopes",
+    "load_ndjson_events",
+]

tracelink/dashboard/_paths_resolve.py

@@ -0,0 +1,102 @@
+"""Internal path resolvers for the dashboard.
+
+Kept separate from server/api so both can import without circular deps.
+Scope state lives at `.RandP/.scope_state.json` (sibling to debug.log),
+deliberately OUTSIDE the log file pair (per PRD §10.5 — does not modify
+log file schema).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Set
+
+from .._paths import ndjson_path, readable_dir
+
+logger = logging.getLogger(__name__)
+
+
+SCOPE_STATE_FILENAME = ".scope_state.json"
+
+
+def scope_state_path() -> Path:
+    """Path to the persisted scope state JSON file."""
+    return readable_dir() / SCOPE_STATE_FILENAME
+
+
+def load_scope_state() -> Dict[str, bool]:
+    """Read scope state JSON. Empty dict == 'all on' (matches tracer default)."""
+    p = scope_state_path()
+    if not p.exists():
+        return {}
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def save_scope_state(state: Dict[str, bool]) -> None:
+    p = scope_state_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(state, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def is_scope_enabled(state: Dict[str, bool], scope: str) -> bool:
+    """Mirror of DebugTracer._is_scope_enabled at the persisted layer.
+
+    Fallback order: explicit scope -> '*' default -> True (all on).
+    """
+    if scope in state:
+        return bool(state[scope])
+    if "*" in state:
+        return bool(state["*"])
+    return True
+
+
+def scan_observed_scopes() -> List[str]:
+    """Walk the NDJSON file once, return unique scope names in encounter order."""
+    seen: List[str] = []
+    seen_set: Set[str] = set()
+    nd = ndjson_path()
+    if not nd.exists():
+        return seen
+    try:
+        with nd.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except Exception:
+                    continue
+                sc = obj.get("scope")
+                if sc and sc not in seen_set:
+                    seen_set.add(sc)
+                    seen.append(sc)
+    except Exception as e:
+        logger.debug("scan_observed_scopes failed: %s", e)
+    return seen
+
+
+def load_ndjson_events() -> List[Dict[str, Any]]:
+    """Load every parseable event from the NDJSON file (used for tests)."""
+    nd = ndjson_path()
+    if not nd.exists():
+        return []
+    out: List[Dict[str, Any]] = []
+    try:
+        with nd.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    out.append(json.loads(line))
+                except Exception:
+                    continue
+    except Exception:
+        return []
+    return out

tracelink/dashboard/api.py

@@ -0,0 +1,107 @@
+"""FastAPI router for the TraceLink dashboard.
+
+Same endpoints as `server.py` — drop into a FastAPI app for projects that
+already have one running. The standalone `tracelink board` CLI uses the
+stdlib server in `server.py`, not this router.
+
+Usage:
+    from fastapi import FastAPI
+    from tracelink.dashboard import fastapi_router
+
+    app = FastAPI()
+    app.include_router(fastapi_router)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .._paths import cursor_dir, ndjson_path, readable_dir, readable_path
+from ._paths_resolve import (
+    is_scope_enabled,
+    load_scope_state,
+    save_scope_state,
+    scan_observed_scopes,
+    scope_state_path,
+)
+
+
+fastapi_router = None
+try:
+    from fastapi import APIRouter, Request, Response
+
+    fastapi_router = APIRouter(prefix="/__board/api", tags=["tracelink-board"])
+
+    @fastapi_router.get("/logs")
+    async def _logs(request: Request) -> Response:
+        fmt = request.query_params.get("format", "ndjson").lower()
+        if fmt == "readable":
+            rd = readable_path()
+            content = rd.read_text(encoding="utf-8") if rd.exists() else ""
+            return Response(content, media_type="text/plain; charset=utf-8")
+        nd = ndjson_path()
+        content = nd.read_text(encoding="utf-8") if nd.exists() else ""
+        return Response(content, media_type="application/x-ndjson; charset=utf-8")
+
+    @fastapi_router.get("/scopes")
+    async def _scopes() -> Response:
+        observed = scan_observed_scopes()
+        state = load_scope_state()
+        projected = {sc: is_scope_enabled(state, sc) for sc in observed}
+        projected["*"] = is_scope_enabled(state, "*")
+        return Response(
+            json.dumps({"scopes": projected, "observed": observed}, ensure_ascii=False),
+            media_type="application/json; charset=utf-8",
+        )
+
+    @fastapi_router.get("/paths")
+    async def _paths() -> Response:
+        return Response(
+            json.dumps({
+                "cursor_dir":    str(cursor_dir()),
+                "readable_dir":  str(readable_dir()),
+                "ndjson_path":   str(ndjson_path()),
+                "readable_path": str(readable_path()),
+                "scope_state":   str(scope_state_path()),
+            }, ensure_ascii=False),
+            media_type="application/json; charset=utf-8",
+        )
+
+    @fastapi_router.post("/scopes")
+    async def _set_scope(request: Request) -> Response:
+        try:
+            payload: Any = await request.json()
+        except Exception:
+            return Response('{"error":"bad json"}', status_code=400,
+                            media_type="application/json")
+        scope = payload.get("scope")
+        enabled = payload.get("enabled")
+        if not isinstance(scope, str) or not isinstance(enabled, bool):
+            return Response('{"error":"bad payload"}', status_code=400,
+                            media_type="application/json")
+        state = load_scope_state()
+        state[scope] = enabled
+        save_scope_state(state)
+        try:
+            from ..tracer import debug_tracer
+            if enabled:
+                debug_tracer.enable_scope(scope)
+            else:
+                debug_tracer.disable_scope(scope)
+        except Exception:
+            pass
+        return Response('{"ok":true}', media_type="application/json")
+
+    @fastapi_router.delete("/logs")
+    async def _clear() -> Response:
+        for p in (ndjson_path(), readable_path()):
+            try:
+                if p.exists():
+                    p.unlink()
+            except Exception:
+                pass
+        return Response(status_code=204)
+
+except ImportError:
+    pass

tracelink/dashboard/server.py

@@ -0,0 +1,248 @@
+"""Stdlib HTTP server for the TraceLink dashboard.
+
+Used by the `tracelink board` CLI. Endpoints:
+
+    GET    /__board/api/logs?format=ndjson|readable
+    GET    /__board/api/scopes
+    GET    /__board/api/paths
+    POST   /__board/api/scopes       {scope, enabled}
+    DELETE /__board/api/logs
+
+    GET    /__board/...              static UI (index.html, app.js, style.css)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+import threading
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from urllib.parse import parse_qs, urlparse
+
+from .._paths import cursor_dir, ndjson_path, readable_dir, readable_path
+from ._paths_resolve import (
+    is_scope_enabled,
+    load_ndjson_events,
+    load_scope_state,
+    save_scope_state,
+    scan_observed_scopes,
+    scope_state_path,
+)
+
+logger = logging.getLogger(__name__)
+
+API_PREFIX = "/__board/api"
+
+
+# ---------------------------------------------------------------------------
+# Static file serving (sandboxed to dashboard/static/)
+# ---------------------------------------------------------------------------
+
+def _static_root() -> Path:
+    return Path(__file__).parent / "static"
+
+
+def _resolve_static_path(url_path: str) -> Optional[Path]:
+    """Map '/' -> static/index.html, '/app.js' -> static/app.js. Block traversal."""
+    rel = url_path.lstrip("/")
+    if rel in ("", "/"):
+        rel = "index.html"
+    root = _static_root().resolve()
+    target = (root / rel).resolve()
+    try:
+        target.relative_to(root)
+    except ValueError:
+        return None  # path traversal attempt
+    return target if target.is_file() else None
+
+
+# ---------------------------------------------------------------------------
+# Handler
+# ---------------------------------------------------------------------------
+
+def make_handler() -> type:
+    class BoardHandler(BaseHTTPRequestHandler):
+        # Quieter logs (override for full tracing if needed)
+        def log_message(self, format: str, *args: Any) -> None:  # noqa: A002
+            return
+
+        # ----- helpers -----
+        def _send_json(self, code: int, body: Any) -> None:
+            data = json.dumps(body, ensure_ascii=False).encode("utf-8")
+            self.send_response(code)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Content-Length", str(len(data)))
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+            self.wfile.write(data)
+
+        def _send_bytes(self, code: int, body: bytes, ctype: str) -> None:
+            self.send_response(code)
+            self.send_header("Content-Type", ctype)
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+            self.wfile.write(body)
+
+        # ----- GET -----
+        def do_GET(self) -> None:  # noqa: N802
+            if self.path.startswith(f"{API_PREFIX}/logs"):
+                qs = parse_qs(urlparse(self.path).query)
+                fmt = (qs.get("format", ["ndjson"])[0] or "ndjson").lower()
+                if fmt == "readable":
+                    rd = readable_path()
+                    content = rd.read_text(encoding="utf-8") if rd.exists() else ""
+                    self._send_bytes(200, content.encode("utf-8"),
+                                     "text/plain; charset=utf-8")
+                else:
+                    nd = ndjson_path()
+                    content = nd.read_text(encoding="utf-8") if nd.exists() else ""
+                    self._send_bytes(200, content.encode("utf-8"),
+                                     "application/x-ndjson; charset=utf-8")
+                return
+
+            if self.path == f"{API_PREFIX}/scopes":
+                observed = scan_observed_scopes()
+                state = load_scope_state()
+                projected: Dict[str, bool] = {sc: is_scope_enabled(state, sc) for sc in observed}
+                projected["*"] = is_scope_enabled(state, "*")
+                self._send_json(200, {"scopes": projected, "observed": observed})
+                return
+
+            if self.path == f"{API_PREFIX}/paths":
+                self._send_json(200, {
+                    "cursor_dir":   str(cursor_dir()),
+                    "readable_dir": str(readable_dir()),
+                    "ndjson_path":  str(ndjson_path()),
+                    "readable_path": str(readable_path()),
+                    "scope_state":  str(scope_state_path()),
+                })
+                return
+
+            # ----- static UI -----
+            static = _resolve_static_path(self.path)
+            if static is None:
+                self._send_bytes(404, b"not found", "text/plain; charset=utf-8")
+                return
+            ctype = (
+                "text/html; charset=utf-8"           if static.suffix == ".html" else
+                "application/javascript; charset=utf-8" if static.suffix == ".js"  else
+                "text/css; charset=utf-8"            if static.suffix == ".css" else
+                "application/octet-stream"
+            )
+            try:
+                self._send_bytes(200, static.read_bytes(), ctype)
+            except FileNotFoundError:
+                self._send_bytes(404, b"not found", "text/plain; charset=utf-8")
+
+        # ----- POST -----
+        def do_POST(self) -> None:  # noqa: N802
+            if self.path != f"{API_PREFIX}/scopes":
+                self._send_bytes(404, b"not found", "text/plain; charset=utf-8")
+                return
+            length = int(self.headers.get("Content-Length", "0"))
+            raw = self.rfile.read(length).decode("utf-8") if length else ""
+            try:
+                payload = json.loads(raw) if raw else {}
+            except Exception:
+                self._send_json(400, {"error": "bad json"})
+                return
+            scope = payload.get("scope")
+            enabled = payload.get("enabled")
+            if not isinstance(scope, str) or not isinstance(enabled, bool):
+                self._send_json(400, {"error": "expected {scope: str, enabled: bool}"})
+                return
+            state = load_scope_state()
+            state[scope] = bool(enabled)
+            save_scope_state(state)
+            # Best-effort live push to in-process tracer
+            try:
+                from ..tracer import debug_tracer
+                if enabled:
+                    debug_tracer.enable_scope(scope)
+                else:
+                    debug_tracer.disable_scope(scope)
+            except Exception:
+                pass
+            self._send_json(200, {"ok": True, "scope": scope, "enabled": enabled})
+
+        # ----- DELETE -----
+        def do_DELETE(self) -> None:  # noqa: N802
+            if self.path != f"{API_PREFIX}/logs":
+                self._send_bytes(404, b"not found", "text/plain; charset=utf-8")
+                return
+            for p in (ndjson_path(), readable_path()):
+                try:
+                    if p.exists():
+                        p.unlink()
+                except Exception as e:
+                    logger.debug("delete failed: %s", e)
+            self.send_response(204)
+            self.end_headers()
+
+    return BoardHandler
+
+
+# ---------------------------------------------------------------------------
+# Standalone runner
+# ---------------------------------------------------------------------------
+
+def serve_board(
+    host: str = "127.0.0.1",
+    port: int = 8766,
+    auto_open: bool = False,
+) -> int:
+    """Start the dashboard server. Blocks until KeyboardInterrupt."""
+    if not _static_root().is_dir():
+        print(
+            f"[tracelink.dashboard] ERROR: static dir not found: {_static_root()}\n"
+            "  → Did the dashboard/static/ folder ship with the package?",
+            file=sys.stderr,
+        )
+        return 2
+    handler = make_handler()
+    try:
+        server = ThreadingHTTPServer((host, port), handler)
+    except OSError as e:
+        print(f"[tracelink.dashboard] bind {host}:{port} failed: {e}", file=sys.stderr)
+        return 1
+
+    url = f"http://{host}:{port}/"
+    print(
+        f"[tracelink.dashboard] listening on {url}\n"
+        f"  ndjson   : {ndjson_path()}\n"
+        f"  readable : {readable_path()}\n"
+        f"  state    : {scope_state_path()}\n"
+        "  press Ctrl-C to stop.",
+        file=sys.stderr,
+    )
+    if auto_open:
+        threading.Timer(0.4, lambda: webbrowser.open(url)).start()
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\n[tracelink.dashboard] shutting down.", file=sys.stderr)
+    finally:
+        server.server_close()
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m tracelink.dashboard",
+        description="TraceLink dev-time dashboard (per docs/03-prd.md §10).",
+    )
+    parser.add_argument("--port", type=int, default=8766)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--open", action="store_true")
+    args = parser.parse_args(argv)
+    return serve_board(args.host, args.port, args.open)
+
+
+if __name__ == "__main__":
+    sys.exit(main())