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

llm_wiki_cli/commands/trigger_cmd.py

@@ -0,0 +1,205 @@
+import os
+import subprocess
+import sys
+from pathlib import Path
+from ..services.lockfile import WikiLock, LockAcquisitionError
+from ..services import circuit_breaker
+from ..services.secure_file import write_private_text
+from ..config import DEFAULT_WIKI_DIR, IDE_AGENTS, validate_path
+import json
+
+GIT_DIR = Path(".git")
+DEFAULT_MAX_PROMPT_BYTES = 2_000_000
+
+
+def run(args):
+    # Handle --reset-breaker early (no lock needed)
+    if getattr(args, "reset_breaker", False):
+        circuit_breaker.reset_breaker(GIT_DIR)
+        print("Circuit breaker reset. Wiki auto-sync is re-enabled.")
+        return
+
+    if args.agent in IDE_AGENTS:
+        print(f"Error: Agent '{args.agent}' is a UI-based assistant for IDEs.")
+        print(f"To use background auto-sync, you must specify a CLI-native agent like 'claude' or 'aider'.")
+        print(f"Example: llm-wiki trigger-agent --agent claude")
+        sys.exit(1)
+
+    # --- Fuse: Concurrency Lock ---
+    try:
+        with WikiLock(GIT_DIR):
+            _run_sync(args)
+    except LockAcquisitionError:
+        print("Another llm-wiki sync is already running. Skipping.")
+
+
+def _run_sync(args):
+    """Core sync logic, executed inside the concurrency lock."""
+
+    wiki_dir = getattr(args, "wiki_dir", DEFAULT_WIKI_DIR)
+    validate_path(wiki_dir, "--wiki-dir")
+
+    # --- Fuse: Circuit Breaker ---
+    if circuit_breaker.check_breaker(GIT_DIR):
+        print("Circuit breaker is OPEN — wiki auto-sync is disabled after repeated failures.")
+        print("To re-enable: llm-wiki trigger-agent --reset-breaker")
+        return
+
+    print("Triggering auto-sync workflow for LLM Wiki...")
+
+    # 1. Get the git diff
+    print("Fetching git diff...")
+    try:
+        git_diff_result = subprocess.run(
+            ["git", "diff", "HEAD~1..HEAD"],
+            capture_output=True, text=True, check=True, timeout=30,
+        )
+        diff_text = git_diff_result.stdout
+    except subprocess.TimeoutExpired:
+        print("Git diff timed out (30s). Aborting.")
+        return
+    except (subprocess.CalledProcessError, FileNotFoundError) as e:
+        print(f"Git diff failed. Are there commits? {e}")
+        return
+
+    if not diff_text.strip():
+        print("No changes in the last commit. Aborting.")
+        return
+
+    # --- Fuse: Diff Size Guard ---
+    max_diff = getattr(args, "max_diff_lines", 1000)
+    force = getattr(args, "force", False)
+    diff_lines = len(diff_text.splitlines())
+    if diff_lines > max_diff and not force:
+        print(f"Diff too large ({diff_lines} lines > {max_diff} limit). Skipping auto-sync.")
+        print("Use --force to override, or increase --max-diff-lines.")
+        return
+
+    # 2. Extract context via current AST
+    print("Extracting current structure context...")
+    from .extract_cmd import get_call_graph, get_inventory_result, print_inventory_failures
+    inventory_result = get_inventory_result(".", deep=True)
+    if inventory_result.failed:
+        print_inventory_failures(inventory_result)
+        return
+    inventory = inventory_result.inventory
+    ast_json = json.dumps(inventory, indent=2)
+
+    # 2b. Build call graph for workflow awareness
+    call_graph = get_call_graph(inventory)
+    graph_json = json.dumps(call_graph, indent=2)
+
+    # 3. Create context prompt for the subagent
+    prompt = f"""
+You are a Wiki synchronizer subagent.
+A new commit was just made. Your task is to update the wiki at `{wiki_dir}/`.
+
+## Context
+
+AST structure of the codebase:
+{ast_json}
+
+Cross-module call graph (functions touching 3+ internal modules):
+{graph_json}
+
+Git diff:
+{diff_text}
+
+## Success Criteria
+
+Your work is done when **all** of the following are true:
+
+1. **`llm-wiki lint --wiki-dir {wiki_dir} --src-dir .` exits 0** — no broken links, \
+no orphan pages, no undocumented classes, no stale entities, no missing modules, \
+no broken workflow links, no undocumented infrastructure files.
+2. **Only affected pages changed** — modify wiki pages that correspond to code \
+touched in the diff. Do not edit unrelated pages or reformat existing content.
+3. **`{wiki_dir}/log.md` has a new entry** — one concise line describing what changed, \
+appended at the bottom.
+
+## Loop
+
+After making your changes, run:
+
+```bash
+llm-wiki lint --wiki-dir {wiki_dir} --src-dir .
+```
+
+If lint reports issues, fix them and re-run. **Repeat until lint exits 0.** Then commit:
+
+```bash
+git add {wiki_dir}/
+LLM_WIKI_AUTO_COMMIT=1 git commit -m "docs(wiki): auto-update [bot]"
+```
+"""
+
+    max_prompt_bytes = _max_prompt_bytes(args)
+    prompt_bytes = len(prompt.encode("utf-8"))
+    if prompt_bytes > max_prompt_bytes and not force:
+        print(
+            f"Prompt too large ({prompt_bytes} bytes > {max_prompt_bytes} limit). "
+            "Skipping auto-sync."
+        )
+        print("Use --force to override, or increase --max-prompt-bytes.")
+        return
+
+    # 4. Save the prompt to a temp file
+    prompt_file = Path(".git/llm-wiki-prompt.txt")
+    write_private_text(prompt_file, prompt)
+
+    # 5. Delegate to Subagent via CLI
+    print(f"Delegating to {args.agent} subagent...")
+    if args.agent == "claude":
+        cmd = ["claude", "-p", "--dangerously-skip-permissions"]
+    elif args.agent == "aider":
+        cmd = ["aider", "--message-file", str(prompt_file), "--no-auto-commits"]
+    elif args.agent == "opencode":
+        cmd = ["opencode", "task", "-f", str(prompt_file)]
+    else:
+        print(f"Unsupported agent {args.agent}")
+        return
+
+    timeout = getattr(args, "timeout", 300)
+
+    try:
+        print(f"Running command: {' '.join(cmd)}")
+
+        if args.agent == "claude":
+            with open(prompt_file, "r", encoding="utf-8") as prompt_in:
+                result = subprocess.run(
+                    cmd, stdin=prompt_in,
+                    timeout=timeout,
+                )
+        else:
+            with open(os.devnull, "r") as devnull:
+                result = subprocess.run(
+                    cmd, stdin=devnull,
+                    timeout=timeout,
+                )
+
+        # --- Fuse: record success / failure based on exit code ---
+        if result.returncode != 0:
+            print(f"Subagent exited with code {result.returncode}.")
+            circuit_breaker.record_failure(GIT_DIR)
+        else:
+            circuit_breaker.record_success(GIT_DIR)
+
+    except subprocess.TimeoutExpired:
+        print(f"Subagent timed out after {timeout}s. Process killed.")
+        circuit_breaker.record_failure(GIT_DIR)
+    except Exception as e:
+        print(f"Error executing agent {args.agent}: {e}")
+        circuit_breaker.record_failure(GIT_DIR)
+
+
+def _max_prompt_bytes(args) -> int:
+    value = getattr(args, "max_prompt_bytes", None)
+    if value is not None:
+        return int(value)
+    env_value = os.environ.get("LLM_WIKI_MAX_PROMPT_BYTES")
+    if env_value:
+        try:
+            return int(env_value)
+        except ValueError:
+            pass
+    return DEFAULT_MAX_PROMPT_BYTES

llm_wiki_cli/commands/uninstall_cmd.py

@@ -0,0 +1,221 @@
+import shutil
+from pathlib import Path
+
+from ..config import DEFAULT_WIKI_DIR, validate_path
+from ..services.io import read_md, write_md
+from ..services.schema import (
+    ALL_SCHEMA_FILES as AGENT_SCHEMA_FILES,
+    CONSTRAINT_START,
+    CONSTRAINT_END,
+    strip_wiki_block as _strip_wiki_block,
+)
+
+# Hook identifier — all llm-wiki hooks contain this string
+HOOK_SIGNATURE = "LLM Wiki"
+
+# Hooks that install-hook may have written
+HOOK_NAMES = ["post-commit", "pre-commit", "pre-push"]
+
+# Local runtime artifacts created by init/hooks/trigger-agent.
+RUNTIME_ARTIFACTS = [
+    ".git/.llm-wiki-agent",
+    ".git/llm-wiki-prompt.txt",
+    ".git/llm-wiki.lock",
+    ".git/llm-wiki-breaker.json",
+    ".git/llm-wiki-sync.log",
+]
+
+
+def _confirm(prompt: str) -> bool:
+    """Ask for y/n confirmation."""
+    try:
+        answer = input(f"  {prompt} [y/N]: ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return False
+    return answer in ("y", "yes")
+
+
+def _remove_hooks(dry_run: bool = False) -> int:
+    """Remove llm-wiki hooks, but only if they contain our signature."""
+    hooks_dir = Path(".git/hooks")
+    removed = 0
+
+    if not hooks_dir.exists():
+        return 0
+
+    for name in HOOK_NAMES:
+        hook_path = hooks_dir / name
+        if not hook_path.exists():
+            continue
+
+        content = hook_path.read_text(encoding="utf-8")
+        if HOOK_SIGNATURE not in content:
+            print(f"  SKIP hook {name} (not ours — contains custom user content)")
+            continue
+
+        if dry_run:
+            print(f"  WOULD REMOVE hook: {hook_path}")
+        else:
+            hook_path.unlink()
+            print(f"  REMOVED hook: {hook_path}")
+        removed += 1
+
+    return removed
+
+
+def _clean_agent_schemas(dry_run: bool = False) -> int:
+    """Remove the LLM Wiki constraint block from agent schema files.
+    
+    If the file becomes empty after block removal, delete it entirely.
+    If user content remains, preserve it.
+    """
+    cleaned = 0
+
+    for filename in AGENT_SCHEMA_FILES:
+        schema_path = Path(filename)
+        if not schema_path.exists():
+            continue
+
+        content = read_md(schema_path)
+        if CONSTRAINT_START not in content:
+            continue
+
+        stripped = _strip_wiki_block(content)
+
+        if dry_run:
+            if stripped:
+                print(f"  WOULD CLEAN block from: {filename} (user content preserved)")
+            else:
+                print(f"  WOULD DELETE: {filename} (only contained wiki constraints)")
+        else:
+            if stripped:
+                write_md(schema_path, stripped)
+                print(f"  CLEANED block from: {filename} (user content preserved)")
+            else:
+                schema_path.unlink()
+                print(f"  DELETED: {filename} (only contained wiki constraints)")
+        cleaned += 1
+
+    return cleaned
+
+
+def _remove_wiki_dir(wiki_dir: Path, dry_run: bool = False) -> bool:
+    """Remove the wiki directory tree."""
+    if not wiki_dir.exists():
+        return False
+
+    if dry_run:
+        page_count = len(list(wiki_dir.rglob("*.md")))
+        print(f"  WOULD REMOVE: {wiki_dir}/ ({page_count} markdown files)")
+    else:
+        shutil.rmtree(wiki_dir)
+        print(f"  REMOVED: {wiki_dir}/")
+    return True
+
+
+def _remove_runtime_artifacts(dry_run: bool = False) -> int:
+    """Remove local runtime artifacts created by llm-wiki."""
+    removed = 0
+    for filepath in RUNTIME_ARTIFACTS:
+        p = Path(filepath)
+        if p.exists():
+            if dry_run:
+                print(f"  WOULD REMOVE: {filepath}")
+            else:
+                p.unlink()
+                print(f"  REMOVED: {filepath}")
+            removed += 1
+    return removed
+
+
+def run(args):
+    wiki_dir_arg = getattr(args, "wiki_dir", DEFAULT_WIKI_DIR)
+    validate_path(str(wiki_dir_arg), "--wiki-dir")
+    wiki_dir = Path(wiki_dir_arg)
+    remove_wiki = getattr(args, "remove_wiki", False)
+    dry_run = getattr(args, "dry_run", False)
+
+    if dry_run:
+        print("DRY RUN — no files will be modified:\n")
+
+    # ── 1. Preview what will be removed ──────────────────────────────
+    print("LLM Wiki Uninstall")
+    print("=" * 40)
+
+    # Hooks
+    print("\n1. Git Hooks:")
+    hooks_count = _remove_hooks(dry_run=True)
+    if hooks_count == 0:
+        print("  Nothing to remove.")
+
+    # Agent schemas
+    print("\n2. Agent Constraint Blocks:")
+    schema_count = 0
+    for filename in AGENT_SCHEMA_FILES:
+        p = Path(filename)
+        if p.exists() and CONSTRAINT_START in read_md(p):
+            stripped = _strip_wiki_block(read_md(p))
+            if stripped:
+                print(f"  {filename} — will strip wiki block (user content preserved)")
+            else:
+                print(f"  {filename} — will delete (only wiki constraints)")
+            schema_count += 1
+    if schema_count == 0:
+        print("  Nothing to remove.")
+
+    # Wiki dir
+    print("\n3. Wiki Directory:")
+    if remove_wiki and wiki_dir.exists():
+        page_count = len(list(wiki_dir.rglob("*.md")))
+        print(f"  {wiki_dir}/ — {page_count} markdown file(s)")
+    elif wiki_dir.exists():
+        print(f"  {wiki_dir}/ — KEPT (use --remove-wiki to delete)")
+    else:
+        print("  Not found.")
+
+    # Runtime artifacts
+    print("\n4. Runtime Artifacts:")
+    artifact_count = sum(1 for f in RUNTIME_ARTIFACTS if Path(f).exists())
+    if artifact_count:
+        for f in RUNTIME_ARTIFACTS:
+            if Path(f).exists():
+                print(f"  {f}")
+    else:
+        print("  Nothing to remove.")
+
+    wiki_targeted = remove_wiki and wiki_dir.exists()
+    total = hooks_count + schema_count + (1 if wiki_targeted else 0) + artifact_count
+    if total == 0:
+        print("\nNothing to uninstall. Project is clean.")
+        return
+
+    if dry_run:
+        print(f"\nDry run complete. {total} item(s) would be affected.")
+        return
+
+    # ── 2. Confirm and execute ────────────────────────────────────────
+    print(f"\n{total} item(s) will be affected.")
+    if not _confirm("Proceed with uninstall?"):
+        print("Aborted.")
+        return
+
+    print()
+    removed_total = 0
+
+    # Execute removals
+    r = _remove_hooks()
+    removed_total += r
+
+    r = _clean_agent_schemas()
+    removed_total += r
+
+    if remove_wiki and wiki_dir.exists():
+        _remove_wiki_dir(wiki_dir)
+        removed_total += 1
+
+    r = _remove_runtime_artifacts()
+    removed_total += r
+
+    print(f"\nUninstall complete. {removed_total} item(s) removed.")
+    print("To uninstall the CLI itself: pip uninstall agent-wiki-cli")

llm_wiki_cli/commands/upgrade_cmd.py

@@ -0,0 +1,196 @@
+"""llm-wiki upgrade — refresh all framework-managed artifacts in place.
+
+Replaces the uninstall → init → install-hook cycle with a single idempotent
+command that:
+1. Replaces the agent constraint block with the latest version
+2. Ensures wiki directory structure is complete
+3. Reinstalls git hooks
+4. Optionally switches agents
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+from ..config import AGENT_CHOICES, CLI_AGENTS, DEFAULT_WIKI_DIR, IDE_AGENTS, get_agent_config_path, read_config, validate_path, write_config
+from ..services.io import read_md, write_md
+from ..services.schema import (
+    ALL_SCHEMA_FILES,
+    CONSTRAINT_START,
+    SCHEMA_FILENAMES,
+    build_schema_content,
+    replace_schema_block,
+    strip_wiki_block,
+)
+
+# Re-use hook builders from hook_cmd to avoid duplication
+from .hook_cmd import _build_ide_post_commit, _build_post_commit, _install_hook
+
+
+def _read_agent_config(wiki_dir: str) -> str | None:
+    """Read the agent name persisted by `llm-wiki init`."""
+    config = read_config(wiki_dir)
+    agent = config.get("agent")
+    if agent and agent != "generic":
+        return agent
+    # Check if config file actually exists (defaults return "generic")
+    config_path = get_agent_config_path(wiki_dir)
+    if config_path.exists():
+        return agent
+    return None
+
+
+def _resolve_agent(args, wiki_dir: str) -> str:
+    """Resolve agent: CLI --agent flag > persisted config > error."""
+    agent = getattr(args, "agent", None)
+    if agent:
+        return agent
+
+    stored = _read_agent_config(wiki_dir)
+    if stored:
+        return stored
+
+    print(
+        "Error: Cannot determine agent.\n"
+        f"  No --agent flag provided and no config found at .git/.llm-wiki-agent\n\n"
+        "  Either run `llm-wiki init --agent <agent>` first,\n"
+        "  or pass --agent to this command:\n"
+        f"    llm-wiki upgrade --agent <{'|'.join(AGENT_CHOICES)}>",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+
+def _upgrade_schema(agent: str, wiki_dir: str, old_agent: str | None, *, quality_hints: bool = True) -> str:
+    """Replace or migrate the agent schema constraint block.
+
+    Returns a summary message.
+    """
+    new_content = build_schema_content(agent, wiki_dir, quality_hints=quality_hints)
+    new_filename = SCHEMA_FILENAMES.get(agent)
+
+    if old_agent and old_agent != agent:
+        # Switching agents — clean old schema file first
+        old_filename = SCHEMA_FILENAMES.get(old_agent)
+        if old_filename:
+            old_path = Path(old_filename)
+            if old_path.exists():
+                existing = read_md(old_path)
+                if CONSTRAINT_START in existing:
+                    stripped = strip_wiki_block(existing)
+                    if stripped:
+                        write_md(old_path, stripped)
+                        print(f"  Cleaned constraint block from: {old_filename}")
+                    else:
+                        old_path.unlink()
+                        print(f"  Removed: {old_filename} (only contained wiki constraints)")
+
+    # Write latest block to the target schema file
+    if new_filename:
+        schema_path = Path(new_filename)
+        replace_schema_block(schema_path, new_content)
+        return new_filename
+    return "(no schema file)"
+
+
+def _upgrade_dirs(wiki_dir: str) -> int:
+    """Ensure all standard wiki subdirectories exist. Returns count of newly created dirs."""
+    base = Path(wiki_dir)
+    subdirs = ["entities", "modules", "workflows", "infrastructure"]
+    created = 0
+    for name in ["."] + subdirs:
+        d = base if name == "." else base / name
+        if not d.exists():
+            d.mkdir(parents=True, exist_ok=True)
+            created += 1
+        gitkeep = d / ".gitkeep"
+        if not gitkeep.exists():
+            gitkeep.touch()
+    # Ensure core files exist
+    index_path = base / "index.md"
+    if not index_path.exists():
+        write_md(index_path,
+            "# LLM Wiki Index\n\nCatalog of project modules and entities.\n\n"
+            "## Entities\n\n## Modules\n\n## Workflows\n\n## Infrastructure\n"
+        )
+        created += 1
+    log_path = base / "log.md"
+    if not log_path.exists():
+        write_md(log_path, "# Architectural Log\n\nAppend-only chronological log.\n\n")
+        created += 1
+    return created
+
+
+def _upgrade_hooks(agent: str, wiki_dir: str, *, force: bool = False) -> None:
+    """Reinstall git hooks for the resolved agent."""
+    git_dir = Path(".git")
+    if not git_dir.exists():
+        print("  Skipped hooks (no .git directory)")
+        return
+
+    hooks_dir = git_dir / "hooks"
+    hooks_dir.mkdir(exist_ok=True)
+
+    if agent in IDE_AGENTS:
+        _install_hook(hooks_dir, "post-commit", _build_ide_post_commit(wiki_dir), force=force)
+        print(f"  Hooks: IDE prompt-generation mode ({agent})")
+    else:
+        _install_hook(hooks_dir, "post-commit", _build_post_commit(agent, wiki_dir), force=force)
+        print(f"  Hooks: CLI auto-sync mode ({agent})")
+
+
+def run(args):
+    wiki_dir = getattr(args, "wiki_dir", DEFAULT_WIKI_DIR)
+    validate_path(wiki_dir, "--wiki-dir")
+
+    agent = _resolve_agent(args, wiki_dir)
+    old_agent = _read_agent_config(wiki_dir)
+    switching = old_agent and old_agent != agent
+
+    # Resolve quality_hints: CLI flag > stored config > default (True)
+    cli_hints = getattr(args, "quality_hints", None)
+    if cli_hints is not None:
+        quality_hints = cli_hints
+    else:
+        stored = read_config(wiki_dir)
+        quality_hints = stored.get("quality_hints", True)
+
+    print("LLM Wiki Upgrade")
+    print("=" * 40)
+
+    if switching:
+        print(f"\n  Switching agent: {old_agent} → {agent}")
+    else:
+        print(f"\n  Agent: {agent}")
+
+    # 1. Schema constraint block
+    print("\n1. Agent Schema:")
+    schema_file = _upgrade_schema(agent, wiki_dir, old_agent, quality_hints=quality_hints)
+    print(f"  Updated: {schema_file}")
+
+    # 2. Wiki directories
+    print("\n2. Wiki Structure:")
+    new_dirs = _upgrade_dirs(wiki_dir)
+    if new_dirs:
+        print(f"  Created {new_dirs} new entries in {wiki_dir}/")
+    else:
+        print(f"  All directories present in {wiki_dir}/")
+
+    # 3. Git hooks
+    print("\n3. Git Hooks:")
+    _upgrade_hooks(agent, wiki_dir, force=getattr(args, "force", False))
+
+    # 4. Persist agent config
+    write_config(wiki_dir, {"agent": agent, "quality_hints": quality_hints})
+
+    # Warn if CLI agent executable missing
+    executable = CLI_AGENTS.get(agent)
+    if executable and not shutil.which(executable):
+        print(
+            f"\nWarning: '{executable}' not found on PATH.\n"
+            f"  Background auto-sync won't work until '{executable}' is installed."
+        )
+
+    print("\nUpgrade complete.")