agent-wiki-cli 2.0.2__tar.gz → 2.1.0__tar.gz

{agent_wiki_cli-2.0.2 → agent_wiki_cli-2.1.0}/MANIFEST.in

@@ -3,4 +3,8 @@ include release_build_backend.py
 include src/llm_wiki_cli/schemas/llm-wiki-knowledge-v1.schema.json
 include src/llm_wiki_cli/extractors/ts_scripts/package-lock.json
 include docs/standalone-documentation.md
+include docs/wiki-guide.md
+include docs/cli-reference.md
+include docs/automation.md
+include docs/security-model.md
 prune reports

agent_wiki_cli-2.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: agent-wiki-cli
+Version: 2.1.0
+Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
+Author-email: Denis Sivagin <denissvgn@gmail.com>
+License-Expression: 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: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6
+Requires-Dist: tomli>=2; python_version < "3.11"
+Provides-Extra: tokens
+Requires-Dist: tokenizers<0.23,>=0.22; extra == "tokens"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: jsonschema>=4.18; extra == "dev"
+Requires-Dist: markdown-it-py<5,>=4.0; extra == "dev"
+Requires-Dist: setuptools==83.0.0; extra == "dev"
+Requires-Dist: tomli>=2; extra == "dev"
+Provides-Extra: typescript
+Provides-Extra: go
+Provides-Extra: rust
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.27; python_version >= "3.10" and extra == "mcp"
+Requires-Dist: pydantic-settings<2.15,>=2.5.2; python_version >= "3.10" and extra == "mcp"
+Dynamic: license-file
+
+# LLM Wiki CLI
+
+Build and maintain an architectural wiki for your codebase. LLM Wiki scans
+source into Markdown pages, keeps generated structure in sync, and supplies
+coding agents with searchable, bounded context. Agents add the explanations
+and guides that static analysis cannot provide.
+
+The PyPI package is `agent-wiki-cli`, the command is `llm-wiki`, and the Python
+import package is `llm_wiki_cli`.
+
+[Quick start](#quick-start) · [Command reference](docs/cli-reference.md) ·
+[Standalone documentation](docs/standalone-documentation.md)
+
+## Installation
+
+Requires Python 3.10 or later.
+
+```bash
+pip install agent-wiki-cli
+```
+
+For MCP support, install `pip install "agent-wiki-cli[mcp]"`.
+[Installation options](docs/wiki-guide.md#installation) cover source checkouts
+and optional dependencies. To remove the package, run
+`pip uninstall agent-wiki-cli`.
+
+## Quick Start
+
+Run these commands from your project root. Choose `generic` for an `AGENTS.md`
+instruction file, or select one of the [supported agents](#agent-support).
+
+```bash
+llm-wiki init --agent generic
+```
+
+For TypeScript/JavaScript, Go, Rust, or Haskell, first prepare the required
+helpers with `llm-wiki prepare-extractors --src-dir .`.
+[Helper setup](docs/cli-reference.md#prepare-extractors) is explicit and may
+download dependencies or compile a bundled helper. Python needs no helper.
+
+```bash
+llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki
+```
+
+Open `docs/llm_wiki/index.md` to browse the wiki. Use your coding agent to enrich
+semantic descriptions, guides, and behavior notes; generated diagrams, tables,
+and machine-readable artifacts are maintained by the CLI.
+
+After source changes, update and validate the wiki:
+
+```bash
+llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki --jobs 1
+llm-wiki lint --strict --src-dir . --wiki-dir docs/llm_wiki --jobs 1
+```
+
+For an isolated documentation workspace from source or an existing enriched
+wiki, follow the [standalone documentation guide](docs/standalone-documentation.md).
+
+## What It Creates
+
+The default `docs/llm_wiki/` contains an index, module and entity pages,
+workflows, user flows, guides, and a change log. Depending on the source and
+options, it also includes infrastructure, API contracts, dependency, and
+load-order pages. Generated structure and agent-authored prose share one
+canonical wiki.
+
+See the [wiki guide](docs/wiki-guide.md#what-it-creates) for the page taxonomy,
+content ownership, generated artifacts, and Python API. Export the same wiki
+for [Obsidian](docs/cli-reference.md#obsidian) or a
+[static site](docs/cli-reference.md#site).
+
+## Supported Inputs
+
+| Area | Implementation | Runtime requirement |
+|---|---|---|
+| Python | stdlib `ast` | Python 3.10+ |
+| TypeScript / JavaScript / TSX / JSX | `ts-morph` | prepared Node.js dependencies |
+| Go | `go/ast` | prepared helper binary |
+| Rust | `syn` | prepared helper binary |
+| Haskell | GHC parser, syntax-only inventory | prepared helper binary |
+| Docker / Compose | built-in parsers | none |
+| Runtime/config YAML | targeted built-in parsers | none |
+| OpenAPI 3.0/3.1 JSON / YAML | `json` / PyYAML safe loader | included with the package |
+
+Discovery honors `.gitignore`. Use a
+[source-selection profile](docs/wiki-guide.md#source-selection) to restrict the
+source boundary. See [input details](docs/wiki-guide.md#supported-inputs) for
+helper requirements and language-specific behavior.
+
+## Agent Support
+
+Choose `claude`, `aider`, `opencode`, `copilot`, `cursor`, or `generic` during
+initialization. Every agent can use explicit sync, lint, and reviewed prompts;
+LLM Wiki does not install Git hooks.
+
+[Agent setup](docs/wiki-guide.md#agent-support) explains instruction files and
+skill export. The [MCP server](docs/cli-reference.md#mcp) provides read-only wiki
+access, and [bundled skills](docs/cli-reference.md#skills) guide documentation
+and analysis workflows.
+
+## Common Workflows
+
+| Task | Example |
+|---|---|
+| [Search the wiki](docs/cli-reference.md#search) | `llm-wiki search "authentication" --limit 5` |
+| [Build agent context](docs/cli-reference.md#context) | `llm-wiki context --budget 8000 --format markdown` |
+| [Review changed code](docs/cli-reference.md#review) | `llm-wiki review --base main --head HEAD` |
+| [Compare OpenAPI exports](docs/cli-reference.md#api-diff) | `llm-wiki api-diff --baseline api/before.json --candidate api/after.json` |
+| [Find documentation work](docs/cli-reference.md#queue) | `llm-wiki queue --limit 30` |
+| [Diagnose helper setup and wiki health](docs/cli-reference.md#doctor) | `llm-wiki doctor --capabilities` |
+
+## Automation
+
+Install a read-only GitHub Actions integrity gate after creating your wiki.
+The [automation guide](docs/automation.md#install-the-full-integrity-gate)
+covers the immutable release reference, permissions, helper preparation, and
+advisory PR impact reports. It also covers optional health dashboards and
+manual agent triggers.
+
+## Command Reference
+
+The [command reference](docs/cli-reference.md) contains complete workflows,
+output formats, exit codes, migration guidance, and resource controls.
+Use `llm-wiki <command> --help` for available options.
+
+| Guide | Use it for |
+|---|---|
+| [Wiki guide](docs/wiki-guide.md) | Page structure, ownership, source selection, and agent setup |
+| [Standalone documentation](docs/standalone-documentation.md) | An isolated documentation workspace, agent handoffs, and export |
+| [Native knowledge](docs/native-knowledge.md) | Evidence, freshness, durable identity, and read APIs |
+| [Qualified context packets](docs/qualified-context-packets.md) | Validated context handoffs and packet contracts |
+| [Automation](docs/automation.md) | CI integrity, diagnostics, and explicit triggers |
+| [Changelog](CHANGELOG.md) | Release history and compatibility changes |
+
+## Security Model
+
+Built-in extraction reads source without importing the target application.
+Project plugins are trusted Python code, and manual agent triggers use the
+agent's own permissions. Review generated prompts before sharing sensitive
+source. See the [security model](docs/security-model.md) and
+[vulnerability reporting policy](SECURITY.md).
+
+## Contribution Policy
+
+This project does not maintain a formal contribution process. You are welcome to
+freely fork it, adapt it to your workflow, and publish your own changes under
+the [MIT license](LICENSE). Community interactions follow the
+[code of conduct](CODE_OF_CONDUCT.md).

agent_wiki_cli-2.1.0/README.md

@@ -0,0 +1,148 @@
+# LLM Wiki CLI
+
+Build and maintain an architectural wiki for your codebase. LLM Wiki scans
+source into Markdown pages, keeps generated structure in sync, and supplies
+coding agents with searchable, bounded context. Agents add the explanations
+and guides that static analysis cannot provide.
+
+The PyPI package is `agent-wiki-cli`, the command is `llm-wiki`, and the Python
+import package is `llm_wiki_cli`.
+
+[Quick start](#quick-start) · [Command reference](docs/cli-reference.md) ·
+[Standalone documentation](docs/standalone-documentation.md)
+
+## Installation
+
+Requires Python 3.10 or later.
+
+```bash
+pip install agent-wiki-cli
+```
+
+For MCP support, install `pip install "agent-wiki-cli[mcp]"`.
+[Installation options](docs/wiki-guide.md#installation) cover source checkouts
+and optional dependencies. To remove the package, run
+`pip uninstall agent-wiki-cli`.
+
+## Quick Start
+
+Run these commands from your project root. Choose `generic` for an `AGENTS.md`
+instruction file, or select one of the [supported agents](#agent-support).
+
+```bash
+llm-wiki init --agent generic
+```
+
+For TypeScript/JavaScript, Go, Rust, or Haskell, first prepare the required
+helpers with `llm-wiki prepare-extractors --src-dir .`.
+[Helper setup](docs/cli-reference.md#prepare-extractors) is explicit and may
+download dependencies or compile a bundled helper. Python needs no helper.
+
+```bash
+llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki
+```
+
+Open `docs/llm_wiki/index.md` to browse the wiki. Use your coding agent to enrich
+semantic descriptions, guides, and behavior notes; generated diagrams, tables,
+and machine-readable artifacts are maintained by the CLI.
+
+After source changes, update and validate the wiki:
+
+```bash
+llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki --jobs 1
+llm-wiki lint --strict --src-dir . --wiki-dir docs/llm_wiki --jobs 1
+```
+
+For an isolated documentation workspace from source or an existing enriched
+wiki, follow the [standalone documentation guide](docs/standalone-documentation.md).
+
+## What It Creates
+
+The default `docs/llm_wiki/` contains an index, module and entity pages,
+workflows, user flows, guides, and a change log. Depending on the source and
+options, it also includes infrastructure, API contracts, dependency, and
+load-order pages. Generated structure and agent-authored prose share one
+canonical wiki.
+
+See the [wiki guide](docs/wiki-guide.md#what-it-creates) for the page taxonomy,
+content ownership, generated artifacts, and Python API. Export the same wiki
+for [Obsidian](docs/cli-reference.md#obsidian) or a
+[static site](docs/cli-reference.md#site).
+
+## Supported Inputs
+
+| Area | Implementation | Runtime requirement |
+|---|---|---|
+| Python | stdlib `ast` | Python 3.10+ |
+| TypeScript / JavaScript / TSX / JSX | `ts-morph` | prepared Node.js dependencies |
+| Go | `go/ast` | prepared helper binary |
+| Rust | `syn` | prepared helper binary |
+| Haskell | GHC parser, syntax-only inventory | prepared helper binary |
+| Docker / Compose | built-in parsers | none |
+| Runtime/config YAML | targeted built-in parsers | none |
+| OpenAPI 3.0/3.1 JSON / YAML | `json` / PyYAML safe loader | included with the package |
+
+Discovery honors `.gitignore`. Use a
+[source-selection profile](docs/wiki-guide.md#source-selection) to restrict the
+source boundary. See [input details](docs/wiki-guide.md#supported-inputs) for
+helper requirements and language-specific behavior.
+
+## Agent Support
+
+Choose `claude`, `aider`, `opencode`, `copilot`, `cursor`, or `generic` during
+initialization. Every agent can use explicit sync, lint, and reviewed prompts;
+LLM Wiki does not install Git hooks.
+
+[Agent setup](docs/wiki-guide.md#agent-support) explains instruction files and
+skill export. The [MCP server](docs/cli-reference.md#mcp) provides read-only wiki
+access, and [bundled skills](docs/cli-reference.md#skills) guide documentation
+and analysis workflows.
+
+## Common Workflows
+
+| Task | Example |
+|---|---|
+| [Search the wiki](docs/cli-reference.md#search) | `llm-wiki search "authentication" --limit 5` |
+| [Build agent context](docs/cli-reference.md#context) | `llm-wiki context --budget 8000 --format markdown` |
+| [Review changed code](docs/cli-reference.md#review) | `llm-wiki review --base main --head HEAD` |
+| [Compare OpenAPI exports](docs/cli-reference.md#api-diff) | `llm-wiki api-diff --baseline api/before.json --candidate api/after.json` |
+| [Find documentation work](docs/cli-reference.md#queue) | `llm-wiki queue --limit 30` |
+| [Diagnose helper setup and wiki health](docs/cli-reference.md#doctor) | `llm-wiki doctor --capabilities` |
+
+## Automation
+
+Install a read-only GitHub Actions integrity gate after creating your wiki.
+The [automation guide](docs/automation.md#install-the-full-integrity-gate)
+covers the immutable release reference, permissions, helper preparation, and
+advisory PR impact reports. It also covers optional health dashboards and
+manual agent triggers.
+
+## Command Reference
+
+The [command reference](docs/cli-reference.md) contains complete workflows,
+output formats, exit codes, migration guidance, and resource controls.
+Use `llm-wiki <command> --help` for available options.
+
+| Guide | Use it for |
+|---|---|
+| [Wiki guide](docs/wiki-guide.md) | Page structure, ownership, source selection, and agent setup |
+| [Standalone documentation](docs/standalone-documentation.md) | An isolated documentation workspace, agent handoffs, and export |
+| [Native knowledge](docs/native-knowledge.md) | Evidence, freshness, durable identity, and read APIs |
+| [Qualified context packets](docs/qualified-context-packets.md) | Validated context handoffs and packet contracts |
+| [Automation](docs/automation.md) | CI integrity, diagnostics, and explicit triggers |
+| [Changelog](CHANGELOG.md) | Release history and compatibility changes |
+
+## Security Model
+
+Built-in extraction reads source without importing the target application.
+Project plugins are trusted Python code, and manual agent triggers use the
+agent's own permissions. Review generated prompts before sharing sensitive
+source. See the [security model](docs/security-model.md) and
+[vulnerability reporting policy](SECURITY.md).
+
+## Contribution Policy
+
+This project does not maintain a formal contribution process. You are welcome to
+freely fork it, adapt it to your workflow, and publish your own changes under
+the [MIT license](LICENSE). Community interactions follow the
+[code of conduct](CODE_OF_CONDUCT.md).

agent_wiki_cli-2.1.0/docs/automation.md

@@ -0,0 +1,188 @@
+# Automation
+
+[Back to README](../README.md) · [Command reference](cli-reference.md)
+
+Keep wiki maintenance explicit and use CI to check the committed result.
+Choose the [full integrity gate](#install-the-full-integrity-gate) for blocking
+validation or the [doctor dashboard](#strict-doctor-dashboard) for knowledge
+health diagnostics. [Manual agent triggers](#manual-agent-triggers) and
+[cleanup of retired hooks](#git-hook-retirement) are described separately.
+
+## Install the full integrity gate
+
+After `bootstrap` has created a managed wiki, install its dedicated workflow:
+
+```bash
+llm-wiki install-ci --action-ref "$RELEASE_COMMIT_SHA" --dry-run
+llm-wiki install-ci --action-ref "$RELEASE_COMMIT_SHA"
+```
+
+The command writes only
+`.github/workflows/llm-wiki-integrity.yml`. Rerunning it with the same inputs is
+an exact no-op, while an older unmodified workflow installed by this command is
+updated safely. An unmanaged or locally modified workflow is preserved and
+reported as a conflict unless `--force` is supplied; unrelated workflow files
+are never modified.
+
+The installed workflow checks out the project without persisted credentials
+and calls the release's reusable full-integrity action with read-only
+permissions. That action installs the CLI from its immutable action checkout,
+discovers helper languages through default source-selection discovery (using
+`.llm-wiki/source-selection.json` when present), installs their
+checksum-verified toolchains in runner-temporary storage, and prepares detected
+TypeScript/JavaScript, Go, Rust, and Haskell helpers. Python extraction is built
+in and needs no external helper. A pinned GitHub cache action restores only an
+exact helper-cache key covering the runner platform, release toolchain lock,
+selected helper sources and dependency locks, helper-cache contract, CLI
+version, and immutable action ref. Helper preparation still runs after every
+restore, so a miss or unusable entry rebuilds instead of reducing language
+coverage. Pull requests may restore the cache but only a successful push to the
+default branch may save a new entry.
+
+The action then runs the strict `ci-check` gate with advisory native-drift
+diagnostics, verifies that the project worktree stayed clean, and uploads a
+fixed, allowlisted set of validation, cache-measurement, and toolchain evidence
+even when validation fails.
+
+Installed pull-request workflows fetch full history and supply the fetched
+base and head commits to the same action for advisory change impact. The action
+adds a bounded job summary, up to 50 warning/notice annotations, and
+`llm-wiki-impact.json` / `llm-wiki-impact.md` artifacts. Reporting failures do
+not replace the integrity result. Callers of the action can opt in by setting
+both `impact-base` and `impact-head`.
+
+The portable gate disables project-local Python plugins so pull-request content
+is never imported or executed. A project that intentionally depends on trusted
+extractor, generation, or lint plugins must use a separately reviewed trusted
+workflow instead of this pull-request gate.
+
+Installation does not bootstrap or synchronize the wiki, change branch
+protection, install hooks, push commits, or add repository secrets. Those
+remain explicit maintainer actions.
+
+## Git hook retirement
+
+Git hook installation has been removed. After updating the package, run the
+workspace upgrade from each repository that used LLM Wiki:
+
+```bash
+pip install --upgrade agent-wiki-cli
+llm-wiki upgrade
+```
+
+`upgrade` automatically removes recognized, unmodified LLM Wiki `post-commit`,
+`pre-commit`, and `pre-push` hooks, including older background-agent and version
+bump hooks. Cleanup runs before agent instruction refresh and does not require
+an agent preference. If instruction refresh then needs configuration repair,
+the hook cleanup remains complete. Repeating the upgrade is safe.
+
+Cleanup covers the repository's Git hooks directory, the shared Git directory
+of a linked worktree, and a repository-local `core.hooksPath`. Customized hooks,
+unrelated hooks, and external/global hook directories remain user-managed.
+Unsafe or unreadable hook paths stop cleanup with an error; changed files are
+rechecked before removal. Package installation itself does not discover or
+modify arbitrary repositories. Read-only commands do not remove hooks.
+
+For a reviewed prompt, run `llm-wiki generate-prompt` explicitly. The retired
+`install-hook` command is no longer available.
+
+## Manual agent triggers
+
+For advanced trusted workflows, `trigger-agent` remains available as an explicit
+manual command:
+
+```bash
+llm-wiki trigger-agent --agent <agent>
+```
+
+The trigger command:
+
+- takes `git diff HEAD~1..HEAD`;
+- skips empty diffs and oversized diffs unless `--force` is used;
+- uses a lock file to prevent concurrent syncs;
+- opens a circuit breaker after repeated failures;
+- builds deep source inventory and call-graph context;
+- filters credential-like values from the generated prompt on a best-effort
+  basis, then writes `.git/llm-wiki-prompt.txt` with owner-only permissions
+  where supported;
+- invokes the selected agent with a prompt that asks it to update, lint, and
+  follow a repository-aware handoff. A Git-ignored or indeterminate wiki stays
+  local and is never force-added or committed.
+
+Useful trigger options:
+
+```bash
+llm-wiki trigger-agent --agent claude --timeout 600 --max-diff-lines 2000
+llm-wiki trigger-agent --agent claude --max-prompt-bytes 2000000
+llm-wiki trigger-agent --agent claude --force
+llm-wiki trigger-agent --reset-breaker
+```
+
+Failed trigger runs exit nonzero, including preparation and runner launch failures.
+Runner timeouts exit `124`; other positive child exit codes are preserved.
+Empty or oversized inputs, an occupied lock, and an open breaker remain successful
+skips. Each attempted run records its outcome for the circuit breaker and metrics.
+
+Set `LLM_WIKI_LOCK_WAIT` to a non-negative number of seconds when a trusted
+automation runner should wait briefly for another sync to release the lock.
+The circuit breaker permits one automatic recovery attempt after 3600 seconds
+by default; set `LLM_WIKI_BREAKER_TTL_SECONDS` to another non-negative duration,
+or to `0` to require `--reset-breaker`.
+
+## Strict doctor dashboard
+
+The context-health composite action publishes a diagnostic knowledge-health
+dashboard and applies a configurable failure threshold. It is intentionally
+separate from the blocking full-integrity gate: it does not replace general
+wiki checks, trusted plugin validation, or team-owned review policy.
+
+```yaml
+- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+- uses: Denissvgn/python-wiki-llm/integrations/github-action@<FULL_RELEASE_COMMIT_SHA>
+  with:
+    wiki-dir: docs/llm_wiki
+    src-dir: .
+    source-selection: .llm-wiki/source-selection.json
+    strict: "true"
+    fail-on: unhealthy
+    evidence-id: default
+```
+
+Use `fail-on: unhealthy` to allow degraded-but-usable knowledge while blocking
+mixed snapshots, invalid governance, confirmed stale concepts, and invalid
+verification receipts. Use `fail-on: degraded` when any degraded result must
+block the job. `strict: "true"` also classifies indeterminate or nonsemantic
+source drift as unhealthy. Replace `<FULL_RELEASE_COMMIT_SHA>` with the full
+40-character SHA of the immutable released commit; never use a branch or tag
+for a protected workflow.
+
+The action installs `agent-wiki-cli` from the same action checkout, so pinning
+the action reference also binds the CLI implementation. Through the same
+default source-selection discovery used by the CLI, it plans and prepares any
+detected TypeScript/JavaScript, Go, Rust, or Haskell extractor helper with the
+release's checksum-verified toolchains; Python extraction needs no helper. It
+then invokes `llm-wiki doctor --format json` and reads only the complete,
+versioned `llm-wiki-doctor/v1` object. The renderer rejects a report when its
+strictness or declared exit code does not match the captured request and
+process status, and it never scrapes human output. Within that schema major,
+required fields and documented state values remain strict while additive
+object fields are ignored. A wiki that has not been initialized is reported as
+`absent` and fails either threshold.
+
+The action reserves isolated runner-temporary cache, toolchain, and evidence
+paths and uploads only the JSON
+report, a hash-bound dashboard receipt, the extractor plan, and the preparation
+log. Human disclosure text is escaped and the job summary has fixed size and
+line bounds. This repository also provides a separately named, manually
+dispatched dashboard workflow; it has read-only permissions and no scheduled,
+pull-request, or push trigger. Branch protection should continue to require the
+exact `LLM Wiki integrity` context produced by the full gate, not this
+diagnostic dashboard.
+
+Omit `source-selection` to use default discovery. Set it to the same
+source-root-relative non-default profile used by local maintenance commands
+when a repository does not use `.llm-wiki/source-selection.json`.
+The default `evidence-id` is sufficient for one invocation in a job. Give each
+invocation a unique lowercase identifier when the same action is used more
+than once; unsafe identifiers and occupied runner paths fail closed before any
+artifact upload.