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

llm_wiki_cli/cli.py

@@ -0,0 +1,231 @@
+import argparse
+import os
+import sys
+from .commands import init_cmd, extract_cmd, lint_cmd, hook_cmd, trigger_cmd, bootstrap_cmd, bump_cmd, uninstall_cmd, generate_prompt_cmd, status_cmd, release_cmd, upgrade_cmd, sync_cmd, context_cmd, migrate_cmd
+from .config import AGENT_CHOICES, DEFAULT_WIKI_DIR, PathValidationError
+from . import __version__
+
+
+def _positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed < 1:
+        raise argparse.ArgumentTypeError("must be greater than zero")
+    return parsed
+
+
+def main():
+    parser = argparse.ArgumentParser(description="LLM Wiki CLI")
+    parser.add_argument("--version", action="version", version=f"llm-wiki {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # init command
+    init_parser = subparsers.add_parser("init", help="Scaffold LLM Wiki structure and schema")
+    init_parser.add_argument("--agent", choices=AGENT_CHOICES, default="generic", help="Target agent format for rules/constraints")
+    init_parser.add_argument("--wiki-dir", default=DEFAULT_WIKI_DIR, help="Wiki directory to create (default: docs/llm_wiki)")
+    init_parser.add_argument("--no-quality-hints", action="store_true", default=False,
+                             help="Omit agent quality guidelines from the constraint block")
+
+    # extract command
+    # ... (skipping extract/lint)
+    extract_parser = subparsers.add_parser("extract", help="Extract project AST and structure into wiki")
+    extract_parser.add_argument("--src-dir", default=".", help="Source directory to scan")
+    extract_parser.add_argument("--changed", action="store_true",
+                                help="Only extract files changed in the last git commit")
+    extract_parser.add_argument("--summary", action="store_true",
+                                help="Compact output: file paths with class/function names only")
+    extract_parser.add_argument("--paths", nargs="+", metavar="FILE",
+                                help="Only extract specific file paths (relative to --src-dir)")
+    extract_parser.add_argument("--deep", action="store_true",
+                                help="Include docstrings, params, attributes, and imports")
+    extract_parser.add_argument("--package", default=None, metavar="NAME",
+                                help="Only include files belonging to the named package")
+    extract_parser.add_argument("--include-empty", action="store_true",
+                                help="Include all .py files even if they have no extractable components")
+
+    # lint command
+    lint_parser = subparsers.add_parser("lint", help="Lint LLM Wiki for broken links, orphans, and AST drift")
+    lint_parser.add_argument("--wiki-dir", default=DEFAULT_WIKI_DIR, help="Wiki directory to lint")
+    lint_parser.add_argument("--src-dir", default=".", help="Source directory to cross-reference against")
+
+    # hook command
+    hook_parser = subparsers.add_parser("install-hook", help="Install git hooks for wiki sync")
+    hook_parser.add_argument("--wiki-dir", default=DEFAULT_WIKI_DIR,
+                             help="Wiki directory to read agent config from (default: docs/llm_wiki)")
+    hook_parser.add_argument("--agent", choices=AGENT_CHOICES, default=None,
+                             help="Override the agent for the post-commit hook (default: read from wiki config)")
+    hook_parser.add_argument("--force", action="store_true",
+                             help="Replace an existing unrelated post-commit hook")
+
+    # trigger command
+    trigger_parser = subparsers.add_parser("trigger-agent", help="Trigger subagent to update wiki using diff")
+    trigger_parser.add_argument("--agent", choices=AGENT_CHOICES, default="claude", help="Agent executable to invoke for background sync")
+    trigger_parser.add_argument("--wiki-dir", default=DEFAULT_WIKI_DIR,
+                                help="Wiki directory to update (default: docs/llm_wiki)")
+    trigger_parser.add_argument("--reset-breaker", action="store_true",
+                                help="Reset the circuit breaker after consecutive failures and exit")
+    trigger_parser.add_argument("--timeout", type=int, default=300,
+                                help="Timeout in seconds for the subagent process (default: 300)")
+    trigger_parser.add_argument("--max-diff-lines", type=int, default=1000,
+                                help="Skip sync if diff exceeds this many lines (default: 1000)")
+    trigger_parser.add_argument("--max-prompt-bytes", type=_positive_int, default=None,
+                                help=f"Skip sync if generated prompt exceeds this many bytes (default: {trigger_cmd.DEFAULT_MAX_PROMPT_BYTES})")
+    trigger_parser.add_argument("--force", action="store_true",
+                                help="Bypass diff and prompt size guards (does not bypass lock or circuit breaker)")
+
+    # bootstrap command
+    bootstrap_parser = subparsers.add_parser("bootstrap", help="Generate initial wiki for an existing codebase")
+    bootstrap_parser.add_argument("--src-dir", default=".", help="Source directory to scan")
+    bootstrap_parser.add_argument("--wiki-dir", default=DEFAULT_WIKI_DIR, help="Wiki output directory")
+    bootstrap_parser.add_argument("--overwrite", action="store_true", help="Overwrite existing entity/module pages")
+    bootstrap_parser.add_argument("--depth", choices=["shallow", "full"], default="full",
+                                  help="shallow=names only, full=docstrings/attrs/methods/imports/relationships (default: full)")
+    bootstrap_parser.add_argument("--skip-workflows", action="store_true",
+                                  help="Skip automatic workflow page generation from call graph")
+
+    # bump command
+    bump_parser = subparsers.add_parser("bump", help="Bump project version (patch or minor)")
+    bump_group = bump_parser.add_mutually_exclusive_group(required=True)
+    bump_group.add_argument("--patch", dest="bump_type", action="store_const", const="patch",
+                            help="Bump patch version (0.1.5 -> 0.1.6)")
+    bump_group.add_argument("--minor", dest="bump_type", action="store_const", const="minor",
+                            help="Bump minor version (0.1.6 -> 0.2.0)")
+    bump_parser.add_argument("--stage", action="store_true",
+                             help="Git-add the version file after bumping (for use in hooks)")
+
+    # generate-prompt command
+    gp_parser = subparsers.add_parser("generate-prompt", help="Build a wiki sync prompt for IDE agents (Copilot, Cursor, etc.)")
+    gp_parser.add_argument("--wiki-dir", default=DEFAULT_WIKI_DIR, help="Wiki directory (default: docs/llm_wiki)")
+    gp_parser.add_argument("--src-dir", default=".", help="Source directory to scan (default: .)")
+    gp_parser.add_argument("--output", default=".git/llm-wiki-prompt.txt", help="Output file path (default: .git/llm-wiki-prompt.txt)")
+    gp_parser.add_argument("--print", dest="print_prompt", action="store_true", help="Print the prompt to stdout instead of writing to a file")
+
+    # uninstall command
+    uninstall_parser = subparsers.add_parser("uninstall", help="Remove all LLM Wiki artifacts from the project")
+    uninstall_parser.add_argument("--wiki-dir", default=DEFAULT_WIKI_DIR, help="Wiki directory path")
+    uninstall_parser.add_argument("--remove-wiki", action="store_true",
+                                  help="Also remove the wiki documentation directory")
+    uninstall_parser.add_argument("--dry-run", action="store_true",
+                                  help="Preview what would be removed without deleting anything")
+
+    # status command
+    status_parser = subparsers.add_parser("status", help="Show LLM Wiki status (agent, hooks, breaker, pages)")
+    status_parser.add_argument("--wiki-dir", default=DEFAULT_WIKI_DIR, help="Wiki directory path")
+
+    # release command
+    release_parser = subparsers.add_parser(
+        "release",
+        help="Stamp the [Unreleased] CHANGELOG section with the current version",
+    )
+    release_parser.add_argument(
+        "--changelog", default="CHANGELOG.md",
+        help="Path to the changelog file (default: CHANGELOG.md)",
+    )
+    release_parser.add_argument(
+        "--stage", action="store_true",
+        help="Git-add CHANGELOG.md after stamping (for use in hooks)",
+    )
+
+    # upgrade command
+    upgrade_parser = subparsers.add_parser(
+        "upgrade",
+        help="Refresh all framework-managed artifacts (schema, hooks, dirs) in place",
+    )
+    upgrade_parser.add_argument("--wiki-dir", default=DEFAULT_WIKI_DIR,
+                                help="Wiki directory path (default: docs/llm_wiki)")
+    upgrade_parser.add_argument("--agent", choices=AGENT_CHOICES, default=None,
+                                help="Switch to a different agent (default: keep current)")
+    upgrade_parser.add_argument("--force", action="store_true",
+                                help="Replace an existing unrelated post-commit hook")
+    upgrade_hints = upgrade_parser.add_mutually_exclusive_group()
+    upgrade_hints.add_argument("--quality-hints", dest="quality_hints", action="store_true", default=None,
+                               help="Include agent quality guidelines in the constraint block")
+    upgrade_hints.add_argument("--no-quality-hints", dest="quality_hints", action="store_false",
+                               help="Omit agent quality guidelines from the constraint block")
+
+    # sync command
+    sync_parser = subparsers.add_parser(
+        "sync",
+        help="Incrementally update wiki pages for files that changed since last bootstrap/sync",
+    )
+    sync_parser.add_argument("--src-dir", default=".", help="Source directory to scan (default: .)")
+    sync_parser.add_argument("--wiki-dir", default=DEFAULT_WIKI_DIR,
+                             help="Wiki directory (default: docs/llm_wiki)")
+
+    # migrate command
+    migrate_parser = subparsers.add_parser(
+        "migrate",
+        help="Reconcile legacy wiki pages with current canonical naming",
+    )
+    migrate_parser.add_argument("--src-dir", default=".", help="Source directory to scan (default: .)")
+    migrate_parser.add_argument("--wiki-dir", default=DEFAULT_WIKI_DIR,
+                                help="Wiki directory (default: docs/llm_wiki)")
+    migrate_parser.add_argument("--dry-run", action="store_true",
+                                help="Preview migration actions without modifying files")
+    migrate_parser.add_argument("--chunk-size", type=_positive_int, metavar="PAGES",
+                                help="Apply at most this many pending page operations in one migration chunk")
+    migrate_parser.add_argument("--chunk", type=_positive_int, metavar="N",
+                                help="Apply chunk N from the current --chunk-size plan (default: 1)")
+    migrate_parser.add_argument("--plan-chunks", action="store_true",
+                                help="Print the current chunk plan and exit without modifying files")
+
+    # context command
+    context_parser = subparsers.add_parser(
+        "context",
+        help="Return priority-ranked, token-budgeted codebase context for LLM agents",
+    )
+    context_parser.add_argument("--budget", type=_positive_int, required=True,
+                                help="Token budget for the context payload")
+    context_parser.add_argument("--src-dir", default=".",
+                                help="Source directory to scan (default: .)")
+    context_parser.add_argument("--format", choices=["json", "markdown"], default="json",
+                                help="Output format (default: json)")
+    context_parser.add_argument("--focus", choices=["changed", "all"], default="changed",
+                                help="changed=prioritise git diff files, all=treat every file as high priority (default: changed)")
+
+    args = parser.parse_args()
+
+    try:
+        if args.command == "init":
+            init_cmd.run(args)
+        elif args.command == "extract":
+            extract_cmd.run(args)
+        elif args.command == "lint":
+            lint_cmd.run(args)
+        elif args.command == "install-hook":
+            hook_cmd.run(args)
+        elif args.command == "trigger-agent":
+            trigger_cmd.run(args)
+        elif args.command == "bootstrap":
+            bootstrap_cmd.run(args)
+        elif args.command == "bump":
+            bump_cmd.run(args)
+        elif args.command == "generate-prompt":
+            generate_prompt_cmd.run(args)
+        elif args.command == "uninstall":
+            uninstall_cmd.run(args)
+        elif args.command == "status":
+            status_cmd.run(args)
+        elif args.command == "release":
+            release_cmd.run(args)
+        elif args.command == "upgrade":
+            upgrade_cmd.run(args)
+        elif args.command == "sync":
+            sync_cmd.run(args)
+        elif args.command == "migrate":
+            migrate_cmd.run(args)
+        elif args.command == "context":
+            context_cmd.run(args)
+    except KeyboardInterrupt:
+        print("\nAborted.")
+        sys.exit(130)
+    except PathValidationError as exc:
+        print(str(exc), file=sys.stderr)
+        sys.exit(1)
+    except Exception as exc:
+        if os.environ.get("LLM_WIKI_DEBUG"):
+            raise
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

llm_wiki_cli/commands/__init__.py

@@ -0,0 +1 @@
+from . import init_cmd, extract_cmd, lint_cmd, hook_cmd, trigger_cmd, generate_prompt_cmd, release_cmd, sync_cmd, migrate_cmd