agent-wiki-cli 0.3.28__py3-none-any.whl

llm_wiki_cli/services/circuit_breaker.py

@@ -0,0 +1,79 @@
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+MAX_CONSECUTIVE_FAILURES = 3
+_STATE_FILE = "llm-wiki-breaker.json"
+
+_DEFAULT_STATE = {
+    "consecutive_failures": 0,
+    "last_failure_ts": None,
+    "state": "closed",
+}
+
+
+def _state_path(git_dir: Path) -> Path:
+    return git_dir / _STATE_FILE
+
+
+def load_state(git_dir: Path) -> dict:
+    path = _state_path(git_dir)
+    if not path.exists():
+        return dict(_DEFAULT_STATE)
+    try:
+        with open(path, encoding="utf-8") as f:
+            state = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return dict(_DEFAULT_STATE)
+    if not isinstance(state, dict):
+        return dict(_DEFAULT_STATE)
+    return {**_DEFAULT_STATE, **state}
+
+
+def save_state(git_dir: Path, state: dict) -> None:
+    """Persist state atomically (write to tmp + rename)."""
+    path = _state_path(git_dir)
+    fd, tmp = tempfile.mkstemp(dir=git_dir, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(state, f, indent=2)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def check_breaker(git_dir: Path) -> bool:
+    """Return True if the circuit is open (should block execution)."""
+    state = load_state(git_dir)
+    return state.get("state") == "open"
+
+
+def record_success(git_dir: Path) -> None:
+    state = load_state(git_dir)
+    state["consecutive_failures"] = 0
+    state["state"] = "closed"
+    save_state(git_dir, state)
+
+
+def record_failure(git_dir: Path) -> None:
+    state = load_state(git_dir)
+    state["consecutive_failures"] = state.get("consecutive_failures", 0) + 1
+    state["last_failure_ts"] = datetime.now(timezone.utc).isoformat()
+    if state["consecutive_failures"] >= MAX_CONSECUTIVE_FAILURES:
+        state["state"] = "open"
+        print(
+            f"Circuit breaker OPEN after {state['consecutive_failures']} consecutive failures."
+        )
+        print("Wiki auto-sync is now disabled.")
+        print("To re-enable: llm-wiki trigger-agent --reset-breaker")
+    save_state(git_dir, state)
+
+
+def reset_breaker(git_dir: Path) -> None:
+    save_state(git_dir, dict(_DEFAULT_STATE))

llm_wiki_cli/services/io.py

@@ -0,0 +1,47 @@
+"""Encoding-safe I/O helpers for wiki markdown files.
+
+All wiki reads go through :func:`read_md` so that files containing
+non-UTF-8 bytes (e.g. Windows cp1252 punctuation like ``0x97`` en-dash)
+don't crash the tool.  All writes go through :func:`write_md` to
+normalize output to UTF-8 with Unix line-endings.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def read_md(path: Path) -> str:
+    """Read a markdown file, tolerating non-UTF-8 encodings.
+
+    Tries UTF-8 first; if that fails, falls back to cp1252 which covers
+    common Windows-encoded punctuation (en-dash, em-dash, smart quotes).
+    """
+    data = path.read_bytes()
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        return data.decode("cp1252")
+
+
+def write_md(path: Path, text: str) -> None:
+    """Write *text* to *path* as UTF-8 with Unix line-endings.
+
+    Writes through a same-directory temporary file and atomically replaces
+    the destination so an interrupted process does not leave a truncated page.
+    """
+    normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(normalized.encode("utf-8"))
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise

llm_wiki_cli/services/lockfile.py

@@ -0,0 +1,60 @@
+import os
+import sys
+from pathlib import Path
+
+
+_LOCK_SIZE = 4096
+
+
+class LockAcquisitionError(Exception):
+    """Raised when the wiki lock cannot be acquired (another sync is running)."""
+
+
+class WikiLock:
+    """Exclusive file lock to prevent concurrent wiki syncs.
+
+    Uses fcntl.flock() on POSIX and msvcrt.locking() on Windows
+    for non-blocking exclusive locking on .git/llm-wiki.lock.
+    """
+
+    def __init__(self, git_dir: Path = Path(".git")):
+        self._lock_path = git_dir / "llm-wiki.lock"
+        self._fd = None
+
+    def __enter__(self):
+        self._fd = open(self._lock_path, "a+")
+        try:
+            if sys.platform == "win32":
+                import msvcrt
+                msvcrt.locking(self._fd.fileno(), msvcrt.LK_NBLCK, _LOCK_SIZE)
+            else:
+                import fcntl
+                fcntl.flock(self._fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except (BlockingIOError, OSError):
+            self._fd.close()
+            self._fd = None
+            raise LockAcquisitionError(
+                "Another llm-wiki sync is already running. Skipping."
+            )
+        # Write PID for diagnostics
+        self._fd.seek(0)
+        self._fd.truncate()
+        self._fd.write(str(os.getpid()))
+        self._fd.flush()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self._fd is not None:
+            if sys.platform == "win32":
+                import msvcrt
+                try:
+                    self._fd.seek(0)
+                    msvcrt.locking(self._fd.fileno(), msvcrt.LK_UNLCK, _LOCK_SIZE)
+                except OSError:
+                    print("Warning: failed to release wiki lock file.", file=sys.stderr)
+            else:
+                import fcntl
+                fcntl.flock(self._fd, fcntl.LOCK_UN)
+            self._fd.close()
+            self._fd = None
+        return False

llm_wiki_cli/services/packages.py

@@ -0,0 +1,173 @@
+"""Discover Python packages within a source tree.
+
+Walks the directory tree under *src_dir* looking for ``pyproject.toml``
+and ``setup.py`` markers, then extracts package metadata (name, version,
+source root).  Each discovered package is represented as a
+:class:`PackageInfo` dataclass.
+"""
+
+from __future__ import annotations
+
+import ast
+import configparser
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Sequence
+
+from ..config import EXCLUDED_DIRS
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - exercised on Python 3.9/3.10
+    try:
+        import tomli as tomllib
+    except ModuleNotFoundError:  # pragma: no cover - dependency missing in ad-hoc envs
+        tomllib = None
+
+
+@dataclass(frozen=True)
+class PackageInfo:
+    """Metadata for a single Python package discovered on disk."""
+
+    name: str
+    root: str  # directory containing the package marker, relative to src_dir
+    version: str
+    marker_path: str  # relative path of pyproject.toml / setup.py
+
+
+def _parse_pyproject_toml(text: str) -> dict[str, str]:
+    """Parse project metadata from PEP 621 first, then Poetry metadata."""
+    info: dict[str, str] = {}
+    if tomllib is None:
+        return info
+    try:
+        data = tomllib.loads(text)
+    except Exception:
+        return info
+
+    project = data.get("project", {})
+    if isinstance(project, dict) and project.get("name"):
+        info["name"] = str(project["name"])
+        if isinstance(project.get("version"), str):
+            info["version"] = str(project["version"])
+        elif "version" in project.get("dynamic", []):
+            info["version"] = "dynamic"
+        return info
+
+    poetry = data.get("tool", {}).get("poetry", {})
+    if isinstance(poetry, dict) and poetry.get("name"):
+        info["name"] = str(poetry["name"])
+        if isinstance(poetry.get("version"), str):
+            info["version"] = str(poetry["version"])
+
+    return info
+
+
+def _parse_setup_py(text: str) -> dict[str, str]:
+    """Extract *name* and *version* from a ``setup.py`` via AST inspection."""
+    info: dict[str, str] = {}
+    try:
+        tree = ast.parse(text)
+    except SyntaxError:
+        return info
+
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        func = node.func
+        # match setup(...) or setuptools.setup(...)
+        is_setup = (
+            (isinstance(func, ast.Name) and func.id == "setup")
+            or (isinstance(func, ast.Attribute) and func.attr == "setup")
+        )
+        if not is_setup:
+            continue
+        for kw in node.keywords:
+            if kw.arg in ("name", "version") and isinstance(kw.value, ast.Constant):
+                info[kw.arg] = str(kw.value.value)
+    return info
+
+
+def discover_packages(src_dir: str) -> list[PackageInfo]:
+    """Return all Python packages found under *src_dir*.
+
+    A "package" is a directory containing ``pyproject.toml`` or
+    ``setup.py`` with a discoverable project name.  Directories matching
+    :data:`EXCLUDED_DIRS` are skipped.
+    """
+    src_path = Path(src_dir).resolve()
+    packages: list[PackageInfo] = []
+
+    for marker in sorted(src_path.rglob("pyproject.toml")):
+        rel = marker.relative_to(src_path)
+        if not EXCLUDED_DIRS.isdisjoint(rel.parts):
+            continue
+        try:
+            text = marker.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        info = _parse_pyproject_toml(text)
+        name = info.get("name", "")
+        if not name:
+            continue
+        packages.append(PackageInfo(
+            name=name,
+            root=rel.parent.as_posix() if rel.parent != Path(".") else ".",
+            version=info.get("version", "0.0.0"),
+            marker_path=rel.as_posix(),
+        ))
+
+    for marker in sorted(src_path.rglob("setup.py")):
+        rel = marker.relative_to(src_path)
+        if not EXCLUDED_DIRS.isdisjoint(rel.parts):
+            continue
+        # Skip if a pyproject.toml already covers this directory
+        rel_root = rel.parent.as_posix() if rel.parent != Path(".") else "."
+        if any(p.root == rel_root for p in packages):
+            continue
+        try:
+            text = marker.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        info = _parse_setup_py(text)
+        name = info.get("name", "")
+        if not name:
+            continue
+        packages.append(PackageInfo(
+            name=name,
+            root=rel.parent.as_posix() if rel.parent != Path(".") else ".",
+            version=info.get("version", "0.0.0"),
+            marker_path=rel.as_posix(),
+        ))
+
+    return packages
+
+
+def stamp_inventory_packages(
+    inventory: dict,
+    packages: Sequence[PackageInfo],
+) -> None:
+    """Add a ``"package"`` key to each inventory entry in-place.
+
+    Files are matched to the *most specific* (longest root) package
+    whose root is a prefix of the file path.  Files that don't belong
+    to any package get ``package: None``.
+    """
+    # Sort packages longest-root-first for greedy matching
+    sorted_pkgs = sorted(packages, key=lambda p: len(p.root), reverse=True)
+
+    for filepath, data in inventory.items():
+        if data.get("language") != "python":
+            data["package"] = None
+            continue
+        fp_posix = filepath.replace("\\", "/")
+        matched = None
+        for pkg in sorted_pkgs:
+            prefix = pkg.root
+            if prefix == ".":
+                matched = pkg.name
+                break
+            if fp_posix == prefix or fp_posix.startswith(prefix + "/"):
+                matched = pkg.name
+                break
+        data["package"] = matched

llm_wiki_cli/services/paths.py

@@ -0,0 +1,31 @@
+"""Shared path normalization helpers."""
+
+from __future__ import annotations
+
+import shlex
+from pathlib import Path
+
+
+def normalize_source_path(value: str | None, src_dir: str | None = None) -> str | None:
+    """Normalize a source path from generated markdown or Docker instructions."""
+    if not value:
+        return None
+    normalized = value.strip().strip("`").strip().strip('"').strip("'")
+    normalized = normalized.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    candidate = Path(normalized)
+    if src_dir and candidate.is_absolute():
+        try:
+            return candidate.resolve().relative_to(Path(src_dir).resolve()).as_posix()
+        except ValueError:
+            return candidate.as_posix()
+    return normalized
+
+
+def shell_quote(value: str | Path) -> str:
+    """Quote a value for POSIX shell snippets, including Git Bash on Windows."""
+    if isinstance(value, Path):
+        return shlex.quote(value.as_posix())
+    return shlex.quote(str(value))

llm_wiki_cli/services/schema.py

@@ -0,0 +1,214 @@
+"""Shared schema utilities for agent constraint blocks.
+
+Provides functions to build, strip, and replace the LLM Wiki constraint
+block that is injected into agent schema files (CLAUDE.md, .cursorrules, etc.).
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from ..config import IDE_AGENTS
+from .io import read_md, write_md
+
+# Marker boundaries used to wrap the entire generated block
+CONSTRAINT_START = "# --- LLM Wiki Maintainer Constraints ---"
+CONSTRAINT_END = "# --- End LLM Wiki Constraints ---"
+
+# Map from agent name to the schema file it uses
+SCHEMA_FILENAMES: dict[str, str] = {
+    "claude": "CLAUDE.md",
+    "cursor": ".cursorrules",
+    "copilot": ".github/copilot-instructions.md",
+    "aider": ".aider.conf.yml",
+    "opencode": ".opencode/instructions.md",
+    "generic": ".agents.md",
+}
+
+# All possible schema files (superset — includes legacy names for uninstall)
+ALL_SCHEMA_FILES: list[str] = [
+    "CLAUDE.md",
+    "AGENTS.md",
+    ".cursorrules",
+    ".github/copilot-instructions.md",
+    ".agents.md",
+    ".aider.conf.yml",
+    ".opencode/instructions.md",
+]
+
+_IDE_SYNC_INSTRUCTIONS = """\
+
+## How to sync the wiki in this IDE session
+Because you run inside the IDE (not as a background CLI process), the wiki is NOT
+updated automatically on commit. You are responsible for keeping it current:
+
+1. **After every code change in this session** that adds, removes, or modifies a
+   class, function, module, or cross-module flow:
+   - Update the affected `entities/`, `modules/`, `workflows/`, and `infrastructure/` pages.
+   - Append a one-line summary to `log.md`.
+   - Run `llm-wiki lint` to verify your changes. Fix any issues until it exits 0.
+2. **To do a full re-sync manually**, run in the terminal:
+   ```
+   llm-wiki generate-prompt
+   ```
+   This builds a diff + AST prompt in `.git/llm-wiki-prompt.txt`. Open that file
+   and paste its contents into this chat to trigger a full wiki update.
+3. **Never skip the update** — a stale wiki defeats the purpose of the system.
+
+## Using `llm-wiki sync` for incremental updates
+`sync` compares source file hashes against a stored manifest and regenerates only
+the wiki pages whose source has changed. Use it instead of a full re-bootstrap:
+
+```
+llm-wiki sync
+```
+
+- **When to use:** after pulling new code, after a rebase, or whenever you suspect
+  the wiki is stale but don't want to regenerate everything.
+- Sync creates/updates entity and module pages for new or changed files, marks
+  removed files with a ⚠️ Stale header, and rebuilds `index.md`.
+- If no manifest exists yet (project bootstrapped by an older version), sync will
+  **seed a baseline manifest** from the current source state without modifying
+  pages. Subsequent runs then work incrementally.
+- After sync finishes, always run `llm-wiki lint` to verify consistency.
+
+## Using `llm-wiki context` for large codebases
+`context` produces a token-budgeted, priority-ranked snapshot of the codebase —
+ideal for feeding into an LLM prompt when the full extract output is too large:
+
+```
+llm-wiki context --budget <TOKENS> --src-dir . --format markdown --focus changed
+```
+
+- **`--budget`** (required): maximum token count for the output.
+- **`--focus changed`** (default): prioritises files from the last git commit.
+  Changed files get full detail, their 1-hop import neighbours get slim detail,
+  everything else gets names only. Use `--focus all` to treat every file equally.
+- **`--format`**: `json` (default, structured) or `markdown` (human-readable with
+  tier-labelled sections).
+- **When to use:** before starting a complex task on a large project, pass the
+  context output to the agent so it has an accurate, right-sized view of the
+  codebase without exceeding the context window.
+"""
+
+_QUALITY_HINTS = """\
+
+## Agent quality guidelines
+- **Surgical Changes:** Only modify wiki pages directly affected by your code change.
+  Don't "improve" adjacent pages, reformat existing content, or refactor unrelated docs.
+- **Think Before Editing:** If a wiki page structure is unclear, state what's confusing
+  rather than guessing. Don't silently rewrite pages you don't fully understand.
+"""
+
+
+def _wiki_instructions(wiki_dir: str) -> str:
+    return f"""You are operating within an LLM Wiki architecture. The project's persistent memory is stored in `{wiki_dir}/`.
+
+## Before you start
+- ALWAYS read `{wiki_dir}/index.md` before planning a new feature or making architectural changes.
+- Consult relevant entity and module pages to understand existing patterns before writing new code.
+
+## When you change code
+- UPDATE entity pages in `{wiki_dir}/entities/` when you add, modify, or remove a class.
+- UPDATE module pages in `{wiki_dir}/modules/` when you add, modify, or remove a module.
+- UPDATE `{wiki_dir}/workflows/<name>.md` when a cross-module flow changes.
+- UPDATE infrastructure pages in `{wiki_dir}/infrastructure/` when a Dockerfile or docker-compose file changes.
+- LOG a concise summary of your changes in `{wiki_dir}/log.md` (append-only, newest at bottom).
+
+## Wiki file naming rules
+Page filenames **must** match the conventions enforced by `llm-wiki lint`:
+
+- Treat `{wiki_dir}/index.md` as the source of truth for existing page names.
+  Do not guess links from raw class names or filenames when collisions are
+  possible. If in doubt, run `llm-wiki extract --src-dir .` and match the
+  source path to the existing index entry.
+- **Entity pages** (`entities/`): Use the class name as the file stem when it is
+  unique (e.g., class `MyClass` → `MyClass.md`). When two classes in different
+  modules share the same name, prefix with the disambiguated module page stem:
+  `<module_page_stem>_<ClassName>.md` (e.g., `pkg_a_cli_Parser.md`).
+- **Module pages** (`modules/`): Use the source path from the extractor,
+  relative to `--src-dir`. A unique file stem uses `<stem>.md`
+  (e.g., `cli.py` → `cli.md`, `main.rs` → `main.md`). When two files share the
+  same stem in different directories, parent directory components are prepended
+  with underscores until unique (e.g., `pkg_a/cli.py` and `pkg_b/cli.py` →
+  `pkg_a_cli.md` and `pkg_b_cli.md`).
+- **Infrastructure pages** (`infrastructure/`): Take the relative path of the
+  Docker/Compose file and replace `/` and `.` with `_`
+  (e.g., `Dockerfile` → `Dockerfile.md`, `test_project/Dockerfile` →
+  `test_project_Dockerfile.md`, `docker-compose.yml` → `docker-compose_yml.md`).
+  Links from infrastructure pages to source modules must target the actual
+  module page stem from `index.md`; if a COPY/ADD source is ambiguous, leave it
+  as code text instead of creating a guessed link.
+- **Workflow pages** (`workflows/`): Free-form descriptive names.
+
+## Quality checks
+- Your wiki changes are **complete** when `llm-wiki lint --wiki-dir {wiki_dir} --src-dir .` exits 0.
+- Run lint after every wiki update. If it reports issues, fix them and re-run until it passes.
+- Run `llm-wiki extract --src-dir .` to see the live AST inventory when you need detail.
+- Never leave the wiki in a state where lint reports errors.
+
+## Formatting rules
+- Entity pages must have: Location, Bases, Module link, Attributes table, Methods table, Relationships.
+- Module pages must have: Path, Imports table, Classes summary, Functions table.
+- Infrastructure pages must have: Path, type-specific sections (stages, services, ports, env vars, etc.).
+- Use relative markdown links between pages (e.g., `../entities/User.md`).
+"""
+
+
+def build_schema_content(agent: str, wiki_dir: str, *, quality_hints: bool = True) -> str:
+    """Build the full constraint block for the given agent and wiki directory."""
+    instructions = _wiki_instructions(wiki_dir)
+    preambles = {
+        "claude": f"# Project Wiki\n\nThis project uses an LLM Wiki for persistent architectural memory.\nRead `{wiki_dir}/index.md` first when starting any task.\n\n",
+        "cursor": f"# Cursor Rules — LLM Wiki Project\n\nThis project maintains a living wiki at `{wiki_dir}/`.\nAlways consult it before making changes.\n\n",
+        "copilot": f"# Copilot Instructions — LLM Wiki Project\n\nThis project uses `{wiki_dir}/` as persistent documentation.\nConsult the wiki before suggesting changes.\n\n",
+    }
+    preamble = preambles.get(agent, f"# Agent Instructions — LLM Wiki Project\n\nThis project uses `{wiki_dir}/` for architectural memory.\n\n")
+    hints = _QUALITY_HINTS if quality_hints else ""
+    extra = _IDE_SYNC_INSTRUCTIONS if agent in IDE_AGENTS else ""
+    body = preamble + instructions + hints + extra
+    return f"{CONSTRAINT_START}\n{body.strip()}\n{CONSTRAINT_END}\n"
+
+
+def strip_wiki_block(content: str) -> str:
+    """Remove the LLM Wiki constraint block from file content.
+
+    Handles the block including surrounding blank lines so the file
+    stays clean after removal.
+    """
+    pattern = re.compile(
+        r'\n*' + re.escape(CONSTRAINT_START) + r'.*?' + re.escape(CONSTRAINT_END) + r'\n*',
+        re.DOTALL,
+    )
+    cleaned = pattern.sub('\n', content)
+    return cleaned.strip() + '\n' if cleaned.strip() else ''
+
+
+def replace_schema_block(schema_path: Path, new_content: str) -> None:
+    """Replace the constraint block in an existing schema file, preserving user content.
+
+    If the file has no existing block, the new content is appended.
+    """
+    if not schema_path.exists():
+        schema_path.parent.mkdir(parents=True, exist_ok=True)
+        write_md(schema_path, new_content)
+        return
+
+    existing = read_md(schema_path)
+    # Normalize newlines for consistent matching
+    existing = existing.replace("\r\n", "\n").replace("\r", "\n")
+    if CONSTRAINT_START not in existing:
+        # No existing block — append
+        sep = "\n\n" if existing and not existing.endswith("\n\n") else ("\n" if existing and not existing.endswith("\n") else "")
+        write_md(schema_path, existing + sep + new_content)
+        return
+
+    # Replace existing block (consume any trailing whitespace after CONSTRAINT_END
+    # so repeated runs don't accumulate blank lines)
+    pattern = re.compile(
+        re.escape(CONSTRAINT_START) + r'.*?' + re.escape(CONSTRAINT_END) + r'\n*',
+        re.DOTALL,
+    )
+    updated = pattern.sub(lambda _m: new_content, existing)
+    write_md(schema_path, updated)

llm_wiki_cli/services/secure_file.py

@@ -0,0 +1,22 @@
+"""Helpers for writing local runtime files with best-effort privacy."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def write_private_text(path: str | Path, text: str, *, encoding: str = "utf-8") -> Path:
+    """Write text and restrict file permissions where the platform supports it.
+
+    POSIX platforms support owner-only mode bits. Windows' ``chmod`` support is
+    limited to read-only toggling, so this remains a best-effort operation there.
+    """
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(text, encoding=encoding)
+    try:
+        os.chmod(target, 0o600)
+    except OSError:
+        pass
+    return target