seam-code 0.3.0__py3-none-any.whl

seam/installer/markdownfile.py

@@ -0,0 +1,146 @@
+"""LEAF: pure text/Markdown file operations for the installer (stdlib only).
+
+Two kinds of write the guidance installer needs, neither expressible through the
+JSON/TOML leaves:
+
+  * **owned files** — files Seam fully owns (a Claude Code skill `SKILL.md`, a
+    Cursor `seam.mdc`). `write_file` / `remove_file` treat the whole file as ours.
+  * **shared files** — files that hold the user's own content too (`AGENTS.md`,
+    `CLAUDE.md`). `upsert_block` / `remove_block` edit ONLY a marker-delimited
+    region (`<!-- seam:start -->` … `<!-- seam:end -->`) and never touch the rest.
+
+Every write is atomic (temp + os.replace): an agent reads these files at startup,
+so a crash mid-write must never leave a half-written instruction file behind.
+
+No Seam dependencies → targets compose these without import cycles.
+"""
+
+import os
+import re
+import tempfile
+from pathlib import Path
+
+
+def read_text(path: Path) -> str | None:
+    """Return the file's text, or None if it is absent or unreadable.
+
+    None is the "treat as empty / nothing to remove" signal for callers — a
+    missing or undecodable file is not an error here (we degrade, never raise).
+    """
+    if not path.exists():
+        return None
+    try:
+        return path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    """Write `text` to `path` atomically; create parent dirs as needed."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(text)
+        os.replace(tmp, path)
+    except BaseException:
+        # Never leave the temp file behind on failure (disk-full, signal, etc.).
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+# ── owned files (SKILL.md, seam.mdc) ──────────────────────────────────────────
+
+
+def write_file(path: Path, content: str) -> str:
+    """Write a Seam-owned file. Returns created | updated | unchanged.
+
+    Idempotent: identical content (after trailing-newline normalisation) is a
+    no-op so re-running `seam install` does not churn the file's mtime.
+    """
+    normalized = content if content.endswith("\n") else content + "\n"
+    if read_text(path) == normalized:
+        return "unchanged"
+    action = "updated" if path.exists() else "created"
+    atomic_write_text(path, normalized)
+    return action
+
+
+def remove_file(path: Path) -> str:
+    """Delete a Seam-owned file if present. Returns removed | not_present."""
+    if path.exists():
+        path.unlink()
+        return "removed"
+    return "not_present"
+
+
+# ── shared files (AGENTS.md, CLAUDE.md) — marker-delimited block ──────────────
+
+
+def _markers(marker: str) -> tuple[str, str]:
+    """The start/end HTML-comment sentinels for a marker name.
+
+    HTML comments render invisibly in Markdown across every agent, so the block
+    is unobtrusive in a file the user also reads.
+    """
+    return f"<!-- {marker}:start -->", f"<!-- {marker}:end -->"
+
+
+def _block_re(marker: str) -> re.Pattern[str]:
+    """Regex matching the whole start…end region (inclusive), non-greedy."""
+    start, end = _markers(marker)
+    return re.compile(re.escape(start) + r".*?" + re.escape(end), re.DOTALL)
+
+
+def wrap_block(content: str, marker: str) -> str:
+    """Wrap `content` in the marker sentinels — the canonical block form."""
+    start, end = _markers(marker)
+    return f"{start}\n{content.strip()}\n{end}"
+
+
+def upsert_block(path: Path, content: str, *, marker: str) -> str:
+    """Insert or replace the marked block in a shared file.
+
+    Returns created | updated | unchanged. Replaces an existing block IN PLACE
+    (never duplicates) and appends a new one without disturbing foreign content.
+    """
+    block = wrap_block(content, marker)
+    existing = read_text(path)
+
+    if existing is None:
+        atomic_write_text(path, block + "\n")
+        return "created"
+
+    pattern = _block_re(marker)
+    if pattern.search(existing):
+        # Replace via a function so backslashes/group-refs in `block` stay literal.
+        new_text = pattern.sub(lambda _m: block, existing, count=1)
+        if new_text == existing:
+            return "unchanged"
+        atomic_write_text(path, new_text)
+        return "updated"
+
+    base = existing.rstrip("\n")
+    new_text = f"{base}\n\n{block}\n" if base else f"{block}\n"
+    atomic_write_text(path, new_text)
+    return "updated"
+
+
+def remove_block(path: Path, *, marker: str) -> str:
+    """Remove the marked block from a shared file. Returns removed | not_present.
+
+    Preserves all foreign content and collapses the blank lines left behind so
+    the file does not accrete empty space across install/uninstall cycles.
+    """
+    existing = read_text(path)
+    if existing is None:
+        return "not_present"
+
+    pattern = _block_re(marker)
+    if not pattern.search(existing):
+        return "not_present"
+
+    new_text = pattern.sub("", existing, count=1)
+    new_text = re.sub(r"\n{3,}", "\n\n", new_text).strip("\n")
+    atomic_write_text(path, (new_text + "\n") if new_text else "")
+    return "removed"

seam/installer/tomlfile.py

@@ -0,0 +1,72 @@
+"""LEAF: TOML config-file operations for the Codex target.
+
+Codex stores MCP servers in ~/.codex/config.toml as [mcp_servers.<name>] tables.
+Stdlib `tomllib` is read-only, so we use `tomlkit` — crucially, it round-trips a
+user's existing comments and formatting, so installing a Seam entry never mangles
+a hand-tuned config. No Seam dependencies (leaf).
+"""
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import tomlkit
+from tomlkit import TOMLDocument
+
+
+def load_toml(path: Path) -> TOMLDocument | None:
+    """Parse the TOML document at `path`, or None if absent OR unparseable."""
+    if not path.exists():
+        return None
+    try:
+        return tomlkit.parse(path.read_text(encoding="utf-8"))
+    except (tomlkit.exceptions.TOMLKitError, OSError, UnicodeDecodeError):
+        return None
+
+
+def atomic_write_toml(path: Path, doc: TOMLDocument) -> None:
+    """Write `doc` to `path` atomically (temp + os.replace); create parent dirs."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(tomlkit.dumps(doc))
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def get_server_table(doc: TOMLDocument, server: str) -> dict[str, Any] | None:
+    """Return [mcp_servers.<server>] as a plain dict for comparison, or None if absent."""
+    servers = doc.get("mcp_servers")
+    if not isinstance(servers, dict) or server not in servers:
+        return None
+    # Unwrap tomlkit items to plain Python so equality checks are value-based.
+    return {k: _plain(v) for k, v in servers[server].items()}
+
+
+def set_server_table(doc: TOMLDocument, server: str, table: dict[str, Any]) -> None:
+    """Set [mcp_servers.<server>] = table, creating the parent table if needed."""
+    if "mcp_servers" not in doc:
+        doc["mcp_servers"] = tomlkit.table()
+    doc["mcp_servers"][server] = table
+
+
+def delete_server_table(doc: TOMLDocument, server: str) -> bool:
+    """Delete [mcp_servers.<server>]. Return True iff it existed."""
+    servers = doc.get("mcp_servers")
+    if isinstance(servers, dict) and server in servers:
+        del servers[server]
+        return True
+    return False
+
+
+def _plain(value: Any) -> Any:
+    """Recursively unwrap tomlkit containers to plain dict/list for equality checks."""
+    if isinstance(value, dict):
+        return {k: _plain(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_plain(v) for v in value]
+    return value

seam/query/clusters.py

@@ -0,0 +1,206 @@
+"""Read-only query layer for cluster data (Phase 2 — community detection).
+
+Provides three entry points:
+    list_clusters(conn)         → [{id, label, size}] — all clusters
+    cluster_members(conn, id)   → [{name, file, line, kind}] — members of one cluster
+    cluster_peers(conn, symbol) → (cluster_id, label, peer_names) | None
+
+No server or CLI imports — pure query/read layer.
+Callers (handler, CLI, engine) are responsible for path relativization.
+
+Pre-v4 guard: when the clusters table or cluster_id column is missing
+(index built before Phase 2), all functions return empty results + a one-time
+warning. This mirrors the _comments_table_exists guard in query/comments.py.
+"""
+
+import logging
+import sqlite3
+from typing import TypedDict
+
+logger = logging.getLogger(__name__)
+
+# One-time warning state — avoids log spam when MCP server calls repeatedly
+_pre_v4_warned = False
+
+
+# ── Output TypedDicts ─────────────────────────────────────────────────────────
+
+
+class ClusterRow(TypedDict):
+    """One cluster summary row returned by list_clusters()."""
+    id: int
+    label: str
+    size: int
+
+
+class MemberRow(TypedDict):
+    """One symbol member row returned by cluster_members()."""
+    name: str
+    file: str
+    line: int
+    kind: str
+
+
+# ── Internal guards ───────────────────────────────────────────────────────────
+
+
+def _clusters_table_exists(conn: sqlite3.Connection) -> bool:
+    """Return True if the clusters table exists in this database.
+
+    WHY: The MCP server opens a bare connect() (no schema script), so a pre-v4
+    index won't have the clusters table. Querying it would raise OperationalError.
+    We detect the missing table and degrade gracefully to empty results.
+    """
+    row = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name='clusters' LIMIT 1"
+    ).fetchone()
+    return row is not None
+
+
+def _cluster_id_column_exists(conn: sqlite3.Connection) -> bool:
+    """Return True if symbols.cluster_id column exists."""
+    col_names = {row["name"] for row in conn.execute("PRAGMA table_info(symbols)").fetchall()}
+    return "cluster_id" in col_names
+
+
+def _warn_pre_v4_once() -> None:
+    """Log a one-time warning when a pre-v4 index is detected."""
+    global _pre_v4_warned
+    if not _pre_v4_warned:
+        logger.warning(
+            "seam_clusters: clusters table or cluster_id column missing "
+            "(index predates Phase 2 clustering) — run 'seam init' to populate. "
+            "Returning empty results."
+        )
+        _pre_v4_warned = True
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+
+def list_clusters(conn: sqlite3.Connection) -> list[ClusterRow]:
+    """Return all cluster summary rows.
+
+    Args:
+        conn: Open read-only SQLite connection.
+
+    Returns:
+        List of ClusterRow dicts sorted by id. Empty list when no clusters exist
+        or when the index predates Phase 2 (pre-v4 index).
+    """
+    if not _clusters_table_exists(conn):
+        _warn_pre_v4_once()
+        return []
+
+    rows = conn.execute(
+        "SELECT id, label, size FROM clusters ORDER BY id"
+    ).fetchall()
+
+    return [ClusterRow(id=row["id"], label=row["label"], size=row["size"]) for row in rows]
+
+
+def cluster_members(conn: sqlite3.Connection, cluster_id: int) -> list[MemberRow]:
+    """Return the member symbols of a specific cluster.
+
+    Args:
+        conn:       Open read-only SQLite connection.
+        cluster_id: The clusters.id value to look up.
+
+    Returns:
+        List of MemberRow dicts sorted by name. Empty list when the cluster
+        doesn't exist or the index predates Phase 2.
+    """
+    if not _clusters_table_exists(conn) or not _cluster_id_column_exists(conn):
+        _warn_pre_v4_once()
+        return []
+
+    rows = conn.execute(
+        """
+        SELECT s.name, f.path AS file, s.start_line AS line, s.kind
+        FROM symbols s
+        JOIN files f ON f.id = s.file_id
+        WHERE s.cluster_id = ?
+        ORDER BY s.name
+        """,
+        (cluster_id,),
+    ).fetchall()
+
+    return [
+        MemberRow(
+            name=row["name"],
+            file=row["file"],
+            line=row["line"],
+            kind=row["kind"],
+        )
+        for row in rows
+    ]
+
+
+def cluster_peers(
+    conn: sqlite3.Connection,
+    symbol: str,
+) -> tuple[int, str, list[str]] | None:
+    """Return the cluster context for a symbol: (cluster_id, label, peer_names).
+
+    Peers are all members of the same cluster EXCLUDING the queried symbol itself.
+
+    Args:
+        conn:   Open read-only SQLite connection.
+        symbol: Symbol name to look up.
+
+    Returns:
+        (cluster_id, label, peer_names) if the symbol is clustered.
+        None if the symbol is not in the index, has no cluster assignment,
+        or the index predates Phase 2.
+    """
+    if not _clusters_table_exists(conn) or not _cluster_id_column_exists(conn):
+        _warn_pre_v4_once()
+        return None
+
+    # Resolve the symbol the same way context() does: lowest id wins when ambiguous.
+    # WHY (issue #5): if two rows share a name, the one with the lowest id may be
+    # unclustered (cluster_id=NULL) while a higher-id row is clustered. Using a JOIN
+    # on clusters would silently skip the NULL row and return the wrong definition's
+    # cluster. We resolve the symbol first, THEN fetch the cluster info — consistent
+    # with engine.py::context() which uses `ORDER BY s.id LIMIT 1` on a plain query.
+    sym_row = conn.execute(
+        "SELECT id, cluster_id FROM symbols WHERE name = ? ORDER BY id LIMIT 1",
+        (symbol,),
+    ).fetchone()
+
+    if sym_row is None:
+        # Symbol not in the index at all
+        return None
+
+    if sym_row["cluster_id"] is None:
+        # Symbol exists but is unclustered (below min_size or no edges)
+        return None
+
+    cluster_id_val: int = sym_row["cluster_id"]
+
+    # Fetch the cluster label
+    cluster_row = conn.execute(
+        "SELECT label FROM clusters WHERE id = ?",
+        (cluster_id_val,),
+    ).fetchone()
+
+    if cluster_row is None:
+        # Orphan cluster_id (shouldn't happen; be defensive)
+        return None
+
+    cluster_id: int = cluster_id_val
+    label: str = cluster_row["label"]
+
+    # Fetch all other members of the same cluster (peers)
+    peer_rows = conn.execute(
+        """
+        SELECT DISTINCT s.name
+        FROM symbols s
+        WHERE s.cluster_id = ? AND s.name != ?
+        ORDER BY s.name
+        """,
+        (cluster_id, symbol),
+    ).fetchall()
+
+    peers = [r["name"] for r in peer_rows]
+    return cluster_id, label, peers

seam/query/comments.py

@@ -0,0 +1,217 @@
+"""Read-only query layer for semantic comments (WHY/HACK/NOTE/TODO/FIXME).
+
+Provides why() — the single entry point for comment lookup by:
+  - file path (return all comments in that file)
+  - file + line (return comments within ±RADIUS lines)
+  - symbol name (return comments in/above the symbol's body)
+
+No server or CLI imports; this module lives at the query layer only.
+Callers (handler, CLI) are responsible for path resolution and relativization.
+"""
+
+import logging
+import sqlite3
+from typing import TypedDict
+
+logger = logging.getLogger(__name__)
+
+# ── Constants (documented; not env-driven — fixed marker set decision) ────────
+
+# Proximity radius: when querying by line, return comments within ±RADIUS lines.
+# Example: line=20, RADIUS=15 -> window [5, 35].
+RADIUS: int = 15
+
+# Lead lines: for symbol lookup, extend the search range this many lines ABOVE
+# the symbol's start_line to capture "pre-symbol" rationale comments.
+# Example: start_line=10, LEAD=5 -> search from line 5.
+LEAD: int = 5
+
+
+# ── Output TypedDict ──────────────────────────────────────────────────────────
+
+
+class CommentHit(TypedDict):
+    """One semantic comment result returned by why().
+
+    file   — absolute path (DB-stored); handler/CLI relativizes before output.
+    line   — 1-based line number in the source file.
+    marker — normalized UPPERCASE: WHY | HACK | NOTE | TODO | FIXME.
+    text   — comment body after the marker (and optional colon), stripped.
+    """
+
+    file: str
+    line: int
+    marker: str
+    text: str
+
+
+# ── Internal helpers ──────────────────────────────────────────────────────────
+
+
+def _comments_table_exists(conn: sqlite3.Connection) -> bool:
+    """Return True if the comments table exists in this database.
+
+    WHY: connect() (used by `seam start`, `seam status`, `seam why`) opens a bare
+    connection and does NOT run the schema script — only init_db() does. An index
+    created before this slice (schema v2) therefore has no comments table on those
+    connections. Querying it would raise OperationalError, but the MCP/CLI contract
+    is an empty list ("no recorded rationale"), not an error. We detect the missing
+    table and degrade gracefully, logging a one-time hint to re-index.
+    """
+    row = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name='comments' LIMIT 1"
+    ).fetchone()
+    return row is not None
+
+
+def _fetch_by_file_id(
+    conn: sqlite3.Connection,
+    file_id: int,
+    file_path: str,
+    low: int | None = None,
+    high: int | None = None,
+) -> list[CommentHit]:
+    """Fetch comments for a file_id, optionally filtering to a line range [low, high].
+
+    Results are sorted by line number (ascending).
+    """
+    if low is not None and high is not None:
+        rows = conn.execute(
+            """
+            SELECT line, marker, text
+            FROM comments
+            WHERE file_id = ? AND line BETWEEN ? AND ?
+            ORDER BY line
+            """,
+            (file_id, low, high),
+        ).fetchall()
+    else:
+        rows = conn.execute(
+            """
+            SELECT line, marker, text
+            FROM comments
+            WHERE file_id = ?
+            ORDER BY line
+            """,
+            (file_id,),
+        ).fetchall()
+
+    return [
+        CommentHit(file=file_path, line=row["line"], marker=row["marker"], text=row["text"])
+        for row in rows
+    ]
+
+
+def _resolve_file_id(conn: sqlite3.Connection, file_path: str) -> tuple[int, str] | None:
+    """Look up a file_id + stored path by exact path match.
+
+    Returns (file_id, stored_path) or None if not found.
+    The stored_path is what the DB has (resolved absolute path at index time).
+    """
+    row = conn.execute(
+        "SELECT id, path FROM files WHERE path = ?", (file_path,)
+    ).fetchone()
+    if row is None:
+        return None
+    return row["id"], row["path"]
+
+
+def _resolve_symbol(
+    conn: sqlite3.Connection, symbol_name: str
+) -> tuple[int, str, int, int] | None:
+    """Resolve a symbol name to (file_id, file_path, start_line, end_line).
+
+    When multiple symbols share the same name, returns the first by (file path, symbol id)
+    — deterministic ordering consistent with engine.context().
+
+    Returns None if the symbol is not in the index.
+    """
+    row = conn.execute(
+        """
+        SELECT s.file_id, f.path, s.start_line, s.end_line
+        FROM symbols s
+        JOIN files f ON f.id = s.file_id
+        WHERE s.name = ?
+        ORDER BY f.path, s.id
+        LIMIT 1
+        """,
+        (symbol_name,),
+    ).fetchone()
+    if row is None:
+        return None
+    return row["file_id"], row["path"], row["start_line"], row["end_line"]
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+
+def why(
+    conn: sqlite3.Connection,
+    *,
+    file: str | None = None,
+    line: int | None = None,
+    symbol: str | None = None,
+) -> list[CommentHit]:
+    """Return semantic comments near a location or symbol.
+
+    Lookup modes (at least one of file/symbol is required):
+      file only        → all comments for that file (exact path match vs DB).
+      file + line      → comments within ±RADIUS lines of `line`.
+      symbol           → comments in [start_line - LEAD, end_line] of the symbol.
+
+    Args:
+        conn:   Open read-only SQLite connection to the Seam index.
+        file:   Absolute file path to look up (must match files.path exactly).
+        line:   1-based line number (only meaningful with `file`; ignored when
+                `symbol` is given — symbol mode uses the symbol's own line range).
+        symbol: Symbol name to look up (resolved via symbols table).
+
+    Returns:
+        List of CommentHit dicts sorted by line number. Empty list when the
+        file/symbol is not indexed or has no semantic comments.
+
+    Raises:
+        ValueError: When neither `file` nor `symbol` is provided.
+
+    Note on path matching: The DB stores resolved absolute paths. The caller
+    (handler/CLI) must resolve the user-supplied path to an absolute path
+    before passing it here. This function does exact string matching on files.path.
+    """
+    if file is None and symbol is None:
+        raise ValueError("why() requires at least one of: file, symbol")
+
+    # Pre-1b indexes (schema v2) opened via connect() have no comments table.
+    # Degrade to the empty-list contract instead of raising OperationalError.
+    if not _comments_table_exists(conn):
+        logger.warning(
+            "seam_why: comments table missing (index predates this feature) — "
+            "run 'seam init' to enable semantic comments. Returning no results."
+        )
+        return []
+
+    # Symbol mode: resolve symbol -> file + line range, then query comments
+    if symbol is not None:
+        resolved = _resolve_symbol(conn, symbol)
+        if resolved is None:
+            return []
+        file_id, file_path, start_line, end_line = resolved
+        # Extend the range above the symbol by LEAD lines to capture pre-symbol rationale.
+        # Clamp low to 1 so we never search for line < 1.
+        low = max(1, start_line - LEAD)
+        return _fetch_by_file_id(conn, file_id, file_path, low=low, high=end_line)
+
+    # File-only or file+line mode
+    resolved_file = _resolve_file_id(conn, file)  # type: ignore[arg-type]
+    if resolved_file is None:
+        return []
+
+    file_id, file_path = resolved_file
+
+    if line is not None:
+        # Proximity query: [line - RADIUS, line + RADIUS]
+        low = max(1, line - RADIUS)
+        high = line + RADIUS
+        return _fetch_by_file_id(conn, file_id, file_path, low=low, high=high)
+
+    # File-only: all comments for this file
+    return _fetch_by_file_id(conn, file_id, file_path)