agent-wiki-cli 0.3.28__tar.gz

agent_wiki_cli-0.3.28/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Sivagin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_wiki_cli-0.3.28/PKG-INFO

@@ -0,0 +1,425 @@
+Metadata-Version: 2.4
+Name: agent-wiki-cli
+Version: 0.3.28
+Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
+Author-email: Denis Sivagin <denissvgn@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Denissvgn/python-wiki-llm
+Project-URL: Repository, https://github.com/Denissvgn/python-wiki-llm
+Project-URL: Issues, https://github.com/Denissvgn/python-wiki-llm/issues
+Keywords: llm,wiki,documentation,ai,agents,code-context
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Provides-Extra: typescript
+Provides-Extra: go
+Provides-Extra: rust
+Dynamic: license-file
+
+# LLM Wiki CLI
+
+## About
+
+LLM Wiki CLI helps coding agents keep project documentation accurate automatically. It builds and maintains a structured wiki from your source code, validates consistency with lint checks, and supports automated or prompt-driven sync workflows after each commit.
+
+It is designed for teams using AI-assisted development who want less context drift, better architectural memory, and a repo-level documentation process that scales across Python, TypeScript, Go, Rust, and Docker/Compose infrastructure.
+
+A companion CLI designed to help Native LLM Coding Agents (like Claude Code, OpenCode, Cursor, Copilot, or Aider) autonomously maintain a persistent architectural memory ("Wiki") of your projects.
+
+By providing constant, up-to-date documentation via a local wiki, your LLM agents will stop rediscovering project boundaries from scratch upon every interaction. Instead, the agent learns to consult the `docs/llm_wiki` first, and updates it gracefully whenever a commit alters the software architecture.
+
+Supports **Python, TypeScript, Go, and Rust** projects. Infrastructure documentation (Docker/Compose) included.
+
+> Inspired by Andrej Karpathy's post on [LLM-native development workflows](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
+
+> **Warning:** This tool grants **full unsupervised permissions** to background agents (e.g. `--dangerously-skip-permissions` for Claude Code). The post-commit hook runs headlessly with no human-in-the-loop confirmation. Use with caution — review your agent's capabilities and ensure you trust the execution environment before enabling automation.
+
+## How it Works
+
+This tool bridges the context gap using a **Hybrid Approach**:
+1. **Multi-Language Extraction**: The CLI uses language-specific AST processors (Python `ast`, TypeScript `ts-morph`, Go stdlib `ast`, Rust `syn`) to rapidly map classes, functions, types, imports, and relationships without forcing the LLM to waste context tokens loading megabytes of raw text.
+2. **Strict Schema Constraints**: The tool scaffolds specific prompt constraints (e.g., `CLAUDE.md` or `.github/copilot-instructions.md`) dictating that your agent *must* act as the overarching librarian for `docs/llm_wiki/`.
+3. **Post-Commit Wiki Sync**: A local `.git/hooks/post-commit` script is installed. The sync strategy depends on the agent type:
+   - **CLI agents** (`claude`, `aider`, `opencode`): every commit spawns a fully detached background process that captures the `git diff`, merges it with the structural AST, and invokes the agent headlessly to update the wiki automatically.
+   - **IDE agents** (`copilot`, `cursor`, `generic`): every commit generates a ready-to-paste sync prompt at `.git/llm-wiki-prompt.txt`. You paste it into your IDE chat to trigger the update.
+
+## Agent Support
+
+| Agent | Schema file | Auto-sync mode |
+|---|---|---|
+| `claude` | `CLAUDE.md` | Headless background process |
+| `aider` | `.aider.conf.yml` | Headless background process |
+| `opencode` | `.opencode/instructions.md` | Headless background process |
+| `copilot` | `.github/copilot-instructions.md` | IDE prompt (paste into chat) |
+| `cursor` | `.cursorrules` | IDE prompt (paste into chat) |
+| `generic` | `.agents.md` | IDE prompt (paste into chat) |
+
+## Multi-Language Support
+
+The tool supports multiple programming languages via a pluggable extractor architecture:
+
+| Language | Extractor | Requirements | Installation |
+|----------|-----------|--------------|--------------|
+| **Python** | AST (stdlib) | Python 3.9+ | Included |
+| **TypeScript/TSX** | ts-morph (Node.js) | Node.js, npm | Included; installs bundled npm deps on first use |
+| **Go** | stdlib `ast` | Go toolchain on PATH | Included; auto-detects from PATH |
+| **Rust** | syn + cargo | Rust toolchain on PATH | Included; builds bundled extractor on first use |
+
+All extractors share the same output format and are automatically invoked by `bootstrap`, `extract`, `lint`, and `sync` commands.
+
+Each language provides:
+- **Classes/Types** → Entity wiki pages with attributes, methods, relationships
+- **Functions/Methods** → Function tables in module pages
+- **Imports** → Cross-module relationship tracking
+- **Docstrings/Comments** → Included in entity documentation
+
+## Installation (with Multi-Language Support)
+
+Install the CLI:
+```bash
+pip install agent-wiki-cli
+```
+
+The package defines optional extras for language groups, but they do not install
+additional Python dependencies. Non-Python extractors depend on runtime
+toolchains instead:
+- TypeScript/TSX: `node` and `npm`; bundled npm dependencies install on first use.
+- Go: `go`; the bundled extractor runs via the Go toolchain.
+- Rust: `cargo`; the bundled extractor builds on first use using the packaged lockfile.
+
+Or from source:
+```bash
+git clone https://github.com/Denissvgn/python-wiki-llm.git
+cd python-wiki-llm
+pip install -e .
+```
+
+## Setup & Initialization
+
+Bootstrap the wiki and agent constraint schema inside the root of your project:
+
+```bash
+llm-wiki init --agent claude
+```
+
+Supported agents: `claude`, `aider`, `opencode`, `copilot`, `cursor`, `generic`.
+
+**What this does**:
+- Creates `docs/llm_wiki/index.md` (table of contents).
+- Creates `docs/llm_wiki/log.md` (append-only chronological ledger).
+- Scaffolds `entities/`, `modules/`, `workflows/`, and `infrastructure/` directories.
+- Writes the agent-specific instruction file (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`) so the agent knows the rules of the system.
+- Saves the chosen agent to `.git/.llm-wiki-agent` (local-only, not committed) so subsequent commands (like `install-hook`) pick it up automatically.
+
+> If you pass a CLI agent (`claude`, `aider`, `opencode`) that is not installed on your `PATH`, `init` will warn you but still create all files.
+
+Use `--wiki-dir` to change the default wiki location:
+
+```bash
+llm-wiki init --agent copilot --wiki-dir .wiki
+```
+
+Disable quality hints (agent constraints for surgical changes and careful editing):
+```bash
+llm-wiki init --agent copilot --no-quality-hints
+```
+
+## Bootstrap an Existing Codebase
+
+Generate a comprehensive wiki from an existing project in one command:
+
+```bash
+llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki
+```
+
+**What this does**:
+- Scans all project files via **multi-language AST extraction** (Python, TypeScript, Go, Rust).
+- For each language:
+  - Python: deep extraction (docstrings, attributes with types/defaults, method signatures, decorators, imports).
+  - TypeScript/Go/Rust: classes, interfaces, types, functions, methods, imports.
+- Creates **entity pages** (`entities/<ClassName>.md`) with full attribute tables, method signatures, and cross-module relationship links.
+- Creates **module pages** (`modules/<filename>.md`) with import tables, class summaries, and function signatures with decorators.
+- Discovers and documents **Docker/Compose files** as `infrastructure/<name>.md` with build stages, ports, environment variables, volumes, services, and cross-references to source code.
+- Rebuilds `index.md` and appends a summary to `log.md`.
+- Creates `<wiki-dir>/.llm-wiki-manifest.json` for incremental syncs (see `llm-wiki sync` below).
+- Cross-references imports to build `used_by` / `imported_by` relationship graphs between entities.
+
+**Flags**:
+- `--overwrite` — Regenerate existing pages instead of skipping them.
+- `--depth shallow|full` — `full` (default) extracts everything; `shallow` produces name-only stubs.
+- `--skip-workflows` — Skip automatic workflow page generation from the call graph.
+
+**Multi-language support:**
+- **Python**: Always available (stdlib `ast`)
+- **TypeScript/TSX** (`.ts`, `.tsx`): Requires Node.js and npm on PATH; bundled npm dependencies install on first use
+- **Go** (`.go`): Requires Go on PATH
+- **Rust** (`.rs`): Requires Cargo on PATH; compiles on first use
+
+## Automation Setup (Highly Recommended)
+
+Install the post-commit hook to keep the wiki in sync automatically:
+
+```bash
+llm-wiki install-hook
+```
+
+The agent is read automatically from `.git/.llm-wiki-agent` (written by `init` as a local-only, non-committed file). You can override it:
+
+```bash
+llm-wiki install-hook --agent aider
+llm-wiki install-hook --wiki-dir .wiki        # custom wiki dir
+```
+
+### CLI Agents (Claude, Aider, OpenCode)
+
+The post-commit hook spawns `llm-wiki trigger-agent` as a detached background process via `nohup`:
+
+1. Calculates `git diff HEAD~1..HEAD`.
+2. Extracts current multi-language AST context.
+3. Writes a temporary command payload to `.git/llm-wiki-prompt.txt`.
+4. Spawns the CLI agent (e.g., `claude -p --dangerously-skip-permissions`) and pipes the prompt in.
+5. The agent updates the configured wiki markdown files and commits the result.
+
+The prompt file includes the last commit diff and AST context. It is written with owner-only permissions where the platform supports it, but you should still treat it as sensitive if commits may contain secrets.
+
+Inspect the background log at any time:
+```bash
+cat .git/llm-wiki-sync.log
+```
+
+### IDE Agents (Copilot, Cursor, Generic)
+
+Because IDE agents run inside the editor and have no headless CLI interface, the post-commit hook generates a sync prompt instead:
+
+1. Writes a ready-to-paste prompt to `.git/llm-wiki-prompt.txt`.
+2. The prompt tells the IDE agent how to inspect the last diff, extract changed-file AST context, and run lint.
+3. Prints a reminder in the terminal.
+
+After every commit you'll see:
+```text
++--------------------------------------------------------------+
+|  LLM Wiki: paste the sync prompt into your IDE agent chat.  |
+|  File: .git/llm-wiki-prompt.txt                             |
++--------------------------------------------------------------+
+```
+
+Paste the file contents into your agent chat to trigger the wiki update.
+
+You can also generate the prompt manually at any time (without committing):
+```bash
+llm-wiki generate-prompt
+llm-wiki generate-prompt --print              # print to stdout
+llm-wiki generate-prompt --wiki-dir .wiki     # custom wiki dir
+```
+
+### Manual Version Bumping
+
+You can bump the project version manually at any time:
+
+```bash
+llm-wiki bump --patch          # 0.1.5 -> 0.1.6
+llm-wiki bump --minor          # 0.1.6 -> 0.2.0
+llm-wiki bump --patch --stage  # bump + git add (for hook use)
+```
+
+Supported version files: `pyproject.toml`, `setup.cfg`, `package.json`, `VERSION`.
+
+## Manual Commands
+
+You or your agent can manually invoke any part of the pipeline:
+
+### 1. Structural Extraction
+
+Extracts the project topology into a token-friendly JSON representation (all languages):
+```bash
+llm-wiki extract --src-dir .
+llm-wiki extract --src-dir . --changed        # only files changed in last commit
+llm-wiki extract --src-dir . --summary        # compact output (names only)
+llm-wiki extract --src-dir . --paths src/foo.py src/bar.py  # specific files
+```
+
+**Flags**:
+- `--changed` — Extract only files modified since the last commit (for large projects)
+- `--summary` — Compact format with class/function names only (no signatures, docstrings)
+- `--paths FILE...` — Extract specific files for drill-down detail
+- `--deep` — Deep mode (extract nested relationships)
+- `--package NAME` — Only include files belonging to a discovered package
+- `--include-empty` — Include Python files even if they have no extractable components
+
+### 2. Linting the Wiki
+
+Validates wiki consistency — checks for broken links, orphan pages, and cross-references all entity/module/infrastructure pages against the live AST to detect undocumented classes, stale pages, and missing modules:
+```bash
+llm-wiki lint --wiki-dir docs/llm_wiki --src-dir .
+```
+
+Returns exit code `1` on any issues, making it CI-compatible.
+
+### 3. Incremental Sync (Fast Updates)
+
+Update the wiki incrementally — only regenerates pages for files that changed since bootstrap/last sync:
+```bash
+llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki
+```
+
+This is much faster than `bootstrap` for large projects. It:
+- Uses `docs/llm_wiki/.llm-wiki-manifest.json` to track source file hashes
+- Regenerates entity and module pages only for changed/new files
+- Marks deleted files with a deprecation header in their wiki pages
+- Rebuilds the index automatically
+- Falls back gracefully for pre-manifest wikis (seeds baseline on first run)
+
+### 4. Context Budgeting (Large Projects)
+
+Build a token-budgeted snapshot of the codebase for feeding to agents when the full extract is too large:
+```bash
+llm-wiki context --budget 8000 --src-dir . --format markdown
+llm-wiki context --budget 8000 --src-dir . --format json
+llm-wiki context --budget 8000 --focus changed   # prioritise changed files
+llm-wiki context --budget 8000 --focus all       # treat all files equally
+```
+
+The token budget is an estimated maximum for the returned context payload.
+When full detail does not fit, files are downgraded to slimmer summaries; files
+that still do not fit are listed as omitted.
+
+**Flags**:
+- `--budget TOKENS` (required) — Estimated maximum token count for the context payload
+- `--format markdown|json` — Output format (default: json)
+- `--focus changed|all` — Priority classification (changed files get full detail; default: changed)
+
+### 5. Legacy Wiki Migration
+
+Reconcile pages generated by older llm-wiki versions with the current
+collision-aware naming rules without deleting prior content:
+```bash
+llm-wiki migrate --src-dir . --wiki-dir docs/llm_wiki
+llm-wiki migrate --dry-run                    # preview without writing
+llm-wiki migrate --chunk-size 200 --plan-chunks  # inspect chunk plan
+llm-wiki migrate --chunk-size 200             # apply next pending chunk
+```
+
+This regenerates active canonical pages, preserves previous page content under
+`## Legacy Notes`, archives old pages under `docs/llm_wiki/legacy/`, rebuilds
+`index.md`, refreshes the sync manifest, and rewrites known active links.
+Archived `legacy/` pages are ignored by `lint`, and migrate adds the archive
+directory to `.gitignore` so migration snapshots do not flood the repository.
+
+For large wikis, use `--chunk-size` to keep each working-tree change small.
+Run the same chunked command repeatedly, reviewing or committing between runs.
+The final chunk refreshes `index.md`, active links, and `.llm-wiki-manifest.json`.
+
+### 6. Generate Sync Prompt (IDE agents)
+
+Builds an IDE sync prompt and writes it to a file for pasting into your IDE agent chat:
+```bash
+llm-wiki generate-prompt
+llm-wiki generate-prompt --print              # print to stdout instead
+llm-wiki generate-prompt --output my.txt     # custom output path
+llm-wiki generate-prompt --src-dir . --wiki-dir docs/llm_wiki
+```
+
+### 7. Upgrade Framework
+
+Refresh all framework-managed artifacts in one command (idempotent, non-destructive):
+```bash
+llm-wiki upgrade
+llm-wiki upgrade --agent copilot              # switch agents
+llm-wiki upgrade --wiki-dir .wiki             # custom wiki dir
+llm-wiki upgrade --no-quality-hints           # disable quality hints
+```
+
+This updates:
+- Agent constraint blocks in schema files
+- Wiki directory structure (adds missing directories)
+- Git hooks (if previously installed)
+
+### 8. Release Changelog
+
+Stamp the current project version into the `[Unreleased]` section of the changelog. Empty `[Unreleased]` sections are left unchanged.
+```bash
+llm-wiki release
+llm-wiki release --changelog CHANGELOG.md
+llm-wiki release --stage
+```
+
+### 9. Project Status
+
+Display the current wiki setup and integration status:
+```bash
+llm-wiki status
+```
+
+Shows: wiki directory, configured agent, installed hooks, circuit breaker state, page counts.
+
+### 10. Version Bump
+
+Manually bump the project version:
+```bash
+llm-wiki bump --patch   # increment patch
+llm-wiki bump --minor   # increment minor, reset patch
+```
+
+## Wiki File Naming Conventions
+
+The wiki uses collision-aware naming to ensure every page has a unique filename:
+
+| Page Type | Pattern | Examples |
+|-----------|---------|----------|
+| **Entity** | `entities/<ClassName>.md` | `User.md`, `parser_Parser.md` (when collision) |
+| **Module** | `modules/<file_stem>.md` | `cli.md`, `pkg_a_cli.md` (when collision) |
+| **Workflow** | `workflows/<name>.md` | `user_auth_flow.md` |
+| **Infrastructure** | `infrastructure/<path_transformed>.md` | `Dockerfile.md`, `test_project_Dockerfile.md`, `docker-compose_yml.md` |
+
+**Collision-aware naming:**
+- When multiple classes share the same name across different files, the module page name is prepended (e.g., `pkg_a_cli_Parser.md` vs `pkg_b_cli_Parser.md`)
+- When multiple files share the same stem in different directories, parent directory components are progressively added (e.g., `pkg_a_cli.md` vs `pkg_b_cli.md`)
+- These rules are automatically enforced by `bootstrap`, `sync`, and validated by `lint`
+
+## Forking and Security
+
+This project does not maintain a formal contribution process. The source is
+published under the MIT License, so you may freely fork it, adapt it, and run
+your own version under the license terms.
+
+Public issues are still useful for reproducible bugs and project discussion.
+Participants are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md)
+in project spaces.
+
+Do not report security vulnerabilities in public issues. Follow
+[SECURITY.md](SECURITY.md), especially for issues involving headless agent
+execution, generated prompt files, path handling, or extractor subprocesses.
+
+## Uninstalling from a Project
+
+Remove LLM Wiki integration artifacts (hooks, agent constraint blocks, local runtime artifacts) while **preserving the wiki documentation**:
+
+```bash
+llm-wiki uninstall
+```
+
+To also delete the wiki documentation directory:
+```bash
+llm-wiki uninstall --remove-wiki
+```
+
+Preview what would be removed first:
+```bash
+llm-wiki uninstall --dry-run
+```
+
+**Safety guarantees:**
+- **Wiki docs**: kept by default. Pass `--remove-wiki` to opt-in to deletion.
+- **Agent schema files** (e.g. `CLAUDE.md`): only the `# --- LLM Wiki Maintainer Constraints ---` block is stripped. Any user-written content outside that block is preserved. The file is only deleted if it contained nothing else.
+- **Git hooks**: only removed if they contain the `LLM Wiki` signature. Custom user hooks are never touched.
+- The CLI itself is not uninstalled — run `pip uninstall agent-wiki-cli` separately if needed.