coding-os 0.3.2__py3-none-any.whl

core/logging_os/config.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import os
+import re
+import sys
+from enum import IntEnum
+from pathlib import Path
+
+DEFAULT_SCOPE_WIDTH = 20
+SCOPE_PATTERN = re.compile(r"^[a-z0-9_]+(\.[a-z0-9_]+)+$")
+SCOPE_MAX_LENGTH = 40
+INVALID_SCOPE_FALLBACK = "invalid.scope"
+
+
+class Level(IntEnum):
+    DEBUG = 10
+    INFO = 20
+    OK = 21
+    WARN = 30
+    ERROR = 40
+    FATAL = 50
+
+    @classmethod
+    def from_name(cls, name: str) -> Level:
+        upper = name.upper()
+        if upper not in cls.__members__:
+            raise ValueError(f"unknown log level: {name}")
+        return cls[upper]
+
+    @property
+    def label(self) -> str:
+        return self.name
+
+
+STATE_DIR_NAME = ".coding-os"
+LOG_BASENAME = ".cos.log"
+
+
+def _discover_project_root() -> Path | None:
+    # Walk up from the process CWD for a project marker so the .coding-os state
+    # dir anchors to the PROJECT ROOT, not wherever the process happened to start.
+    # Returns None when no marker is found (caller keeps the CWD fallback).
+    # Marker set + $HOME hard-stop mirror
+    # thinking_os.database._find_project_root_from_cwd (kept aligned by hand so
+    # logging_os stays dependency-free of thinking_os; TASK-498).
+    markers = (".git", ".coding-os.yaml", "pyproject.toml", "package.json", "go.mod", "AGENTS.md")
+    try:
+        here = Path.cwd().resolve()
+        home = Path.home().resolve()
+    except (OSError, RuntimeError):
+        return None
+    for parent in (here, *here.parents):
+        if parent == home:  # never anchor at $HOME (the global hub lives there)
+            break
+        if any((parent / m).exists() for m in markers):
+            return parent
+    return None
+
+
+def state_dir() -> Path:
+    explicit = os.environ.get("COS_STATE_DIR")
+    if explicit:
+        return Path(explicit)
+    # Anchor .coding-os to the project root, not the process CWD. Without this a
+    # process started from a subdir (e.g. the MCP server under src/core/thinking_os)
+    # wrote its logs/DB to a sibling .coding-os/ the Hub (rooted at the repo) never
+    # reads, fragmenting the log feed across CWDs (TASK-263). COS_STATE_DIR still
+    # wins; no project marker falls back to the legacy CWD-relative path.
+    root = _discover_project_root()
+    return (root / STATE_DIR_NAME) if root else Path(STATE_DIR_NAME)
+
+
+def text_log_path(root: Path | None = None) -> Path:
+    # An explicit project root is authoritative — the multi-project Hub resolves
+    # a specific project's sink and must not be overridden by the ambient
+    # COS_LOG_FILE (the launch project's). root=None keeps the env/cwd default.
+    if root is not None:
+        return root / STATE_DIR_NAME / LOG_BASENAME
+    explicit = os.environ.get("COS_LOG_FILE")
+    if explicit:
+        return Path(explicit)
+    return state_dir() / LOG_BASENAME
+
+
+def jsonl_log_path(root: Path | None = None) -> Path:
+    base = text_log_path(root)
+    return base.with_name(base.name + ".jsonl")
+
+
+def current_level() -> Level:
+    raw = os.environ.get("COS_LOG_LEVEL", "info")
+    try:
+        return Level.from_name(raw)
+    except ValueError:
+        return Level.INFO
+
+
+def db_path() -> Path:
+    explicit = os.environ.get("COS_DB_PATH")
+    if explicit:
+        return Path(explicit)
+    return state_dir() / "coding-os.db"
+
+
+def db_min_level() -> Level:
+    raw = os.environ.get("COS_LOG_DB_MIN_LEVEL", "WARN")
+    try:
+        return Level.from_name(raw)
+    except ValueError:
+        return Level.WARN
+
+
+def session_id() -> str:
+    return os.environ.get("COS_SESSION_ID") or os.environ.get("COS_PANEL_ID", "")
+
+
+def trace_id() -> str:
+    return os.environ.get("COS_TRACE_ID", "")
+
+
+def detect_render() -> str:
+    if os.environ.get("COS_LOG_JSON") == "1":
+        return "json"
+    if os.environ.get("COS_LOG_FORCE_PRETTY") == "1":
+        return "pretty"
+    if os.environ.get("NO_COLOR"):
+        return "short"
+    if not sys.stderr.isatty():
+        return "short"
+    return "pretty"
+
+
+def max_log_lines() -> int:
+    raw = os.environ.get("COS_LOG_MAX_LINES", "5000")
+    try:
+        value = int(raw)
+    except ValueError:
+        return 5000
+    return max(100, value)
+
+
+def scope_width() -> int:
+    raw = os.environ.get("COS_LOG_SCOPE_WIDTH", str(DEFAULT_SCOPE_WIDTH))
+    try:
+        value = int(raw)
+    except ValueError:
+        return DEFAULT_SCOPE_WIDTH
+    return max(4, min(value, 60))
+
+
+def normalize_scope(scope: str) -> tuple[str, str | None]:
+    if not isinstance(scope, str) or not scope:
+        return INVALID_SCOPE_FALLBACK, ""
+    candidate = scope.strip()
+    if len(candidate) > SCOPE_MAX_LENGTH:
+        return INVALID_SCOPE_FALLBACK, candidate
+    if not SCOPE_PATTERN.match(candidate):
+        return INVALID_SCOPE_FALLBACK, candidate
+    return candidate, None
+
+
+def setup(level: str | Level = "info", install_stdlib_bridge: bool = True) -> None:
+    if isinstance(level, Level):
+        resolved = level
+        os.environ["COS_LOG_LEVEL"] = level.name.lower()
+    else:
+        resolved = Level.from_name(level)
+        os.environ["COS_LOG_LEVEL"] = level.lower()
+    if install_stdlib_bridge:
+        from .bridge import install_bridge
+
+        install_bridge(resolved)

core/logging_os/fingerprint.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import hashlib
+import re
+
+# Order matters: collapse paths first (before hex/digit rules mangle their
+# segments), then hex/uuid runs, then bare digits. Keeps identical errors that
+# differ only in ids/paths/counts on a single stable fingerprint.
+_PATHS = re.compile(r"(?:/[^\s:/]+){2,}")
+_HEX = re.compile(r"\b[0-9a-f]{8,}\b")
+_DIGITS = re.compile(r"\d+")
+_WS = re.compile(r"\s+")
+
+
+def normalize_msg(msg: str) -> str:
+    text = msg.lower()
+    text = _PATHS.sub("<path>", text)
+    text = _HEX.sub("<id>", text)
+    text = _DIGITS.sub("#", text)
+    return _WS.sub(" ", text).strip()
+
+
+def fingerprint(scope: str, exc_type: str | None, msg: str) -> str:
+    basis = f"{scope}|{exc_type or ''}|{normalize_msg(msg)}"
+    return hashlib.sha1(basis.encode("utf-8")).hexdigest()[:16]

core/logging_os/redact.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+# High-precision secret shapes. Conservative by design — better to miss an
+# exotic secret than to mangle ordinary error text. Runs before EVERY sink so
+# nothing secret reaches the durable store (a secret there is permanent).
+_PATTERNS = [
+    re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._\-]{12,}"),  # Bearer tokens
+    re.compile(r"\beyJ[A-Za-z0-9_\-]{6,}\.[A-Za-z0-9_\-]{6,}\.[A-Za-z0-9_\-]{6,}"),  # JWT
+    re.compile(r"\b(?:sk|pk|rk|ghp|gho|ghs|xox[baprs])[-_][A-Za-z0-9]{16,}"),  # API key prefixes
+    re.compile(r"\bAKIA[0-9A-Z]{16}\b"),  # AWS access key id
+    re.compile(
+        r"(?i)\b(?:password|passwd|secret|token|api[_-]?key|authorization)\s*[=:]\s*\S+"
+    ),  # k=v secrets
+]
+_REDACTED = "<redacted>"
+
+_SENSITIVE_KEYS = {
+    "password",
+    "passwd",
+    "secret",
+    "token",
+    "api_key",
+    "apikey",
+    "authorization",
+    "auth",
+    "key",
+    "access_token",
+    "refresh_token",
+}
+
+
+def redact_text(text: str) -> str:
+    if not text:
+        return text
+    out = text
+    for pat in _PATTERNS:
+        out = pat.sub(_REDACTED, out)
+    return out
+
+
+def redact_kv(kv: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for key, value in kv.items():
+        if key.lower() in _SENSITIVE_KEYS:
+            out[key] = _REDACTED
+        elif isinstance(value, str):
+            out[key] = redact_text(value)
+        else:
+            out[key] = value
+    return out

core/logging_os/render.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .config import scope_width
+
+EMOJI: dict[str, str] = {
+    "DEBUG": "🔍",
+    "INFO": "ℹ️ ",
+    "OK": "✅",
+    "WARN": "⚠️ ",
+    "ERROR": "❌",
+    "FATAL": "💀",
+}
+
+COLOR: dict[str, str] = {
+    "DEBUG": "\x1b[90m",
+    "INFO": "\x1b[36m",
+    "OK": "\x1b[32m",
+    "WARN": "\x1b[33m",
+    "ERROR": "\x1b[31m",
+    "FATAL": "\x1b[1;31m",
+}
+
+RESET = "\x1b[0m"
+
+
+def _format_kv(kv: dict[str, Any]) -> str:
+    if not kv:
+        return ""
+    parts = []
+    for key, value in kv.items():
+        text = str(value)
+        if " " in text or "=" in text:
+            text = json.dumps(text, ensure_ascii=False)
+        parts.append(f"{key}={text}")
+    return " ".join(parts)
+
+
+def render_pretty(event: dict[str, Any]) -> str:
+    lvl = event["lvl"]
+    emoji = EMOJI.get(lvl, "  ")
+    color = COLOR.get(lvl, "")
+    short_ts = event["ts"][11:19]
+    scope = event["scope"].ljust(scope_width())
+    kv_text = _format_kv(event.get("kv") or {})
+    body = event["msg"] if not kv_text else f"{event['msg']}  {kv_text}"
+    return f"{emoji}  {short_ts}  {color}{lvl:<5}{RESET}  {scope}  {body}"
+
+
+def render_short(event: dict[str, Any]) -> str:
+    lvl = event["lvl"]
+    short_ts = event["ts"][11:19]
+    kv_text = _format_kv(event.get("kv") or {})
+    body = event["msg"] if not kv_text else f"{event['msg']} {kv_text}"
+    return f"{short_ts} {lvl:<5} {event['scope']} {body}"
+
+
+def render_json(event: dict[str, Any]) -> str:
+    payload: dict[str, Any] = {
+        "ts": event["ts"],
+        "lvl": event["lvl"],
+        "scope": event["scope"],
+        "msg": event["msg"],
+    }
+    for key, value in (event.get("kv") or {}).items():
+        if key in payload:
+            continue
+        payload[key] = value
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+
+
+RENDERERS = {
+    "pretty": render_pretty,
+    "short": render_short,
+    "json": render_json,
+}
+
+
+def render(mode: str, event: dict[str, Any]) -> str:
+    renderer = RENDERERS.get(mode, render_short)
+    return renderer(event)

core/logging_os/sinks.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import sys
+from pathlib import Path
+from typing import Any
+
+from .config import (
+    Level,
+    current_level,
+    db_min_level,
+    db_path,
+    detect_render,
+    jsonl_log_path,
+    max_log_lines,
+    text_log_path,
+)
+from .fingerprint import fingerprint
+from .render import render
+
+_dropped_events = 0
+
+
+def _event_level(event: dict[str, Any]) -> Level | None:
+    try:
+        return Level.from_name(event.get("lvl", ""))
+    except ValueError:
+        return None
+
+
+def _below_console_floor(event: dict[str, Any]) -> bool:
+    """True when this event is under the console floor (COS_LOG_LEVEL) — the
+    gate for the human-facing sinks (stderr + text mirror + jsonl tail). An
+    unparseable level fails OPEN (printed) rather than silently dropped."""
+    level = _event_level(event)
+    return level is not None and level < current_level()
+
+
+def _write_stderr(event: dict[str, Any]) -> None:
+    if _below_console_floor(event):
+        return
+    line = render(detect_render(), event)
+    try:
+        sys.stderr.write(line + "\n")
+        sys.stderr.flush()
+    except (BrokenPipeError, OSError, ValueError):
+        return
+
+
+def _truncate_if_needed(path: Path, cap: int) -> None:
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            lines = handle.readlines()
+        if len(lines) <= cap * 2:
+            return
+        keep = lines[-cap:]
+        with path.open("w", encoding="utf-8") as handle:
+            handle.writelines(keep)
+    except OSError:
+        return
+
+
+def _append_line(path: Path, line: str) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(line + "\n")
+    except OSError:
+        return
+    _truncate_if_needed(path, max_log_lines())
+
+
+def _write_text_file(event: dict[str, Any]) -> None:
+    if _below_console_floor(event):
+        return
+    _append_line(text_log_path(), render("short", event))
+
+
+def _write_jsonl_file(event: dict[str, Any]) -> None:
+    if _below_console_floor(event):
+        return
+    _append_line(jsonl_log_path(), render("json", event))
+
+
+def append_jsonl_event(event: dict[str, Any], *, root: Path | None = None) -> None:
+    """Append one pre-built event to a specific project's jsonl sink.
+
+    The scoped-write counterpart to dispatch(): the multi-project Hub records a
+    browser beacon into the ACTIVE project's sink, not the process's ambient
+    one. Path resolution goes through jsonl_log_path(root) (the SSOT), and the
+    line matches render("json") so the log readers parse it identically."""
+    _append_line(jsonl_log_path(root), render("json", event))
+
+
+def _record_dropped() -> None:
+    global _dropped_events
+    _dropped_events += 1
+    # Last-resort notice to raw stderr. MUST NOT route through logging_os — a
+    # sink failure re-entering the producer would recurse (invariant I1).
+    try:
+        sys.stderr.write(f"logging_os: dropped 1 durable log event (total={_dropped_events})\n")
+    except Exception:
+        return
+
+
+def dropped_events() -> int:
+    return _dropped_events
+
+
+def _insert_log_event(path: Path, event: dict[str, Any]) -> None:
+    kv = event.get("kv") or {}
+    exc_type = kv.get("exc")
+    base = (
+        event["ts"],
+        event["lvl"],
+        event["scope"],
+        event["msg"],
+        json.dumps(kv, ensure_ascii=False) if kv else None,
+        exc_type,
+        event.get("stack"),
+        event.get("session_id"),
+        event.get("trace_id"),
+        fingerprint(event["scope"], exc_type, event["msg"]),
+    )
+    cols = "ts, lvl, scope, msg, kv, exc_type, stack, session_id, trace_id, fingerprint"
+    conn = sqlite3.connect(str(path), timeout=2.0)
+    try:
+        conn.execute("PRAGMA busy_timeout=2000")
+        try:
+            conn.execute(
+                f"INSERT INTO log_events ({cols}, event_class) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (*base, event.get("event_class", "fault")),
+            )
+        except sqlite3.OperationalError:
+            # pre-v46 DB without event_class — never drop an event over a column
+            conn.execute(
+                f"INSERT INTO log_events ({cols}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                base,
+            )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def _write_db(event: dict[str, Any]) -> None:
+    level = _event_level(event)
+    if level is None or level < db_min_level():
+        return  # hot path: debug/info/ok never touch the durable store
+    path = db_path()
+    if not path.exists():
+        return  # no durable store here — the jsonl tail still has the event
+    try:
+        _insert_log_event(path, event)
+    except Exception:
+        _record_dropped()  # fail-open + observable (I1) — never raise to the caller
+
+
+def dispatch(event: dict[str, Any]) -> None:
+    _write_stderr(event)
+    _write_text_file(event)
+    _write_jsonl_file(event)
+    _write_db(event)

core/rules/anti-overengineering.md

@@ -0,0 +1,44 @@
+# Anti-Overengineering (Always Active)
+
+> **Hard rule:** Solve the problem in front of you with the smallest correct change. Reuse what exists. Don't speculate. Don't duplicate. Cross-cutting — applies to every artifact (code, docs, hooks, skills, templates, tests, CLI, configs).
+
+Why (cumulative cost of every line): [critical-rules.md § Rule 22](../../docs/governance/critical-rules.md#rule-22--anti-overengineering).
+
+## The five sub-rules
+
+**1. Reuse-First** (mirrors P1 SSOT-first) — before writing **anything**, search `cos_graph_query`/`cos_graph_context` (similar symbol?), `cos_search` (solved before?), `cos_doc_search` (spec exists?), grep/find (literal present?). Sibling exists → extend or reuse, never copy-paste, never reimplement a stdlib/framework primitive.
+
+**2. No-Speculation** — build only what the current task requires. Reject "might need it later", "in case we add X", generic helpers with zero callers, one-branch config switches, `IFoo` with one implementation. Documented future work goes to `docs/tasks/`, not code.
+
+**3. Diff-Minimal** (mirrors P4 Diff-first) — bug fix touches just the bug; no ride-along cleanup; one-shot operation gets no helper extraction; three similar lines beat a premature abstraction. Unrelated cleanup → its own task.
+
+**4. No-Premature-Abstraction (Rule of Three)** — extract only when **three** real, divergent call sites need it. Two (or two-and-a-half)? Inline. If the parameter list is already weird at three callers, the abstraction axis is wrong.
+
+**5. Defer-by-Default** — at task close ask "what can I remove?", not "what should I add?". Sweep for unused params, dead imports, unreferenced functions, shipped/never-shipped feature flags, `# TODO` with no task, code-restating comments, unimported re-exports.
+
+## When refactoring / adding *is* justified
+
+At least one must be true: the current code actively prevents the task (blocking edit, broken type, deadlock); three call sites converged independently; a documented incident demanded it; the user explicitly asked. Otherwise — file a task, ship the smallest fix.
+
+## Reality check — run before any non-trivial addition
+
+| Question | Tool |
+|---|---|
+| Does this already exist? | `cos_graph_query`, `cos_doc_search`, grep |
+| Does this need to exist *now*? | Is there a real current caller, or is this speculation? |
+| Will I remove this if the next task is canceled? | If yes, don't add it now — file a task. |
+| Is this someone else's already-solved problem? | stdlib, framework, existing skill / playbook. |
+| Is the abstraction earned? | Three divergent call sites — not two, not "could see three coming". |
+| Could three inlined lines be clearer than one helper? | Often yes. Pick clarity. |
+
+## Anti-patterns (reject in review, fix on sight)
+
+New file when an existing namespace fits · new skill/hook/rule when one already covers the matcher · a class wrapping one method that calls one external function · one-branch config switch · helper "for testability" when the original was testable · refactor bundled with a bug fix · reimplementing a stdlib function · `IFoo` with one implementation · new doc when an existing one has the scope · two skills/rules with overlapping triggers (merge them).
+
+## Enforcement
+
+Convention — no hook reliably detects over-engineering. Backed by self-review, code review rejecting reality-check failures, `cos_search` surfacing prior incidents, and the `clean-code` skill enforcing the tactical instances (no abbreviations, no magic numbers, no positional booleans, nesting ≤ 2).
+
+## See also
+
+[api-contract-discipline.md](api-contract-discipline.md) (producer shape) · [test-discipline.md](test-discipline.md) (matrix not full sweep) · [clean-code SKILL](../skills/clean-code/SKILL.md) (tactical naming) · [critical-rules.md § Rule 22](../../docs/governance/critical-rules.md#rule-22--anti-overengineering) (rationale).

core/rules/api-contract-discipline.md

@@ -0,0 +1,41 @@
+# API Contract Discipline — Don't Guess Field Names
+
+> **Source of truth for field names is the producer, not the consumer.**
+> Frontend components, CLI parsers, dashboards, and tests are consumers — they MUST verify every field they read against the producer's actual response, not against memory, naming intuition, or another consumer.
+
+Drift between producer shape and consumer expectation is a silent bug: TS reads `undefined`, Python returns `None`, `JSON.parse` never fails — the agent only notices when a human says "the page is empty." Hooks can't catch it. Canonical example: `cos_graph_export` emits `source_uid`/`target_uid`, but the Hub Graph tab read `e.source`/`e.target` → every edge silently dropped, empty canvas, zero errors (TASK-117).
+
+## Rule (mandatory before Write/Edit on any API consumer)
+
+Before authoring or editing **any** code that reads an API / MCP / RPC / CLI response, perform ONE of the following two checks and quote the result in your reasoning before producing the diff:
+
+1. **Read the producer.** Open the handler / Pydantic model / dataclass / SSOT type that emits the response and copy the exact field names. Canonical types: `src/core/graph_os/types.py`, `src/core/board_os/types.py`, `src/core/thinking_os/tools/_shared.py`. The tool docstring and `cos_graph_contracts` are NOT a substitute — read the emit site.
+2. **Hit the live endpoint.** Run one request (`curl`/`cos`/`mcp tool`) and pretty-print one item's `.keys()`. Use when no SSOT type exists or the route layer wraps/renames.
+
+Both checks are cheap. Either one alone is sufficient. **Skipping both is a critical error** — equivalent to writing code from imagination.
+
+## Anti-patterns (reject in review, fix on sight)
+
+- Naming a field by intuition ("`source` is natural") — it's whatever the producer emits.
+- Copy-pasting an interface from a sibling consumer — that consumer might be wrong; verify against the producer.
+- Inferring shape from a consumer-side type alias — the alias is the *expectation*, not the contract.
+- "The API used to return X" — re-verify; schema changes don't page the consumer.
+- Adding `?` / `| null` to silence a TS error without checking the producer — that hides drift instead of fixing it.
+
+## Where this rule applies
+
+| Consumer | Producer to verify against |
+|---|---|
+| `src/core/web/ui/src/**` (React fetch / TanStack Query / EventSource) | `src/core/web/routes/**` + the `cos_*` tool the route wraps |
+| `src/cli/**` (parsing CLI output of another `cos` command) | the producing CLI's `*_commands.py` or its underlying tool |
+| `tests/**` asserting envelope shape | `src/core/thinking_os/tools/_shared.py` (`ok` / `fail` envelope) |
+| `src/adapters/<agent>/**` writing presence / state files | the reader hook in `src/core/hooks/` |
+| External integration glue (webhooks, Slack, GitHub) | the third-party docs / a real captured payload, not your memory |
+
+**Spotting drift after the fact:** a UI panel empty with no console error, a CLI summary suddenly showing zeros, or a test passing after a backend rename → suspect contract drift first. Run the producer check and diff field names; don't add fallbacks until you've confirmed the producer's current shape.
+
+## See also
+
+- [docs/engineering/mcp-error-envelope.md](../../docs/engineering/mcp-error-envelope.md) — `ok` / `fail` envelope contract
+- `cos_graph_contracts` MCP tool — list of HTTP/MCP/event handlers in the graph
+- [test-discipline.md § Run the deliverable](test-discipline.md) — the runtime/behaviour sibling of this rule (Critical Rule 26: don't guess a *behaviour* contract — verify by executing, not by reading)