agent-wiki-cli 0.5.1__tar.gz → 0.5.2__tar.gz

{agent_wiki_cli-0.5.1/src/agent_wiki_cli.egg-info → agent_wiki_cli-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 0.5.1
+Version: 0.5.2
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License: MIT
@@ -219,12 +219,16 @@ llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki bootstrap --overwrite
 llm-wiki bootstrap --depth shallow
 llm-wiki bootstrap --skip-workflows
+llm-wiki bootstrap --format json --source-adapter
 ```
 
 `bootstrap` writes entity, module, workflow, infrastructure, index, log, and
 manifest files. `--depth full` is the default and includes docstrings, imports,
 attributes, method signatures, and relationship data where extractors provide
-it.
+it. Use `--source-adapter` when callers need bootstrap to write only under
+`--wiki-dir`; this skips agent constraint-file updates outside the generated
+wiki directory. Use `--format json` to emit a machine-readable summary with
+created, updated, and skipped files plus source counts and the manifest path.
 
 ### `sync`
 
@@ -265,8 +269,15 @@ llm-wiki extract --src-dir . --deep
 llm-wiki extract --src-dir . --paths src/foo.py src/bar.ts
 llm-wiki extract --src-dir . --package llm_wiki_cli
 llm-wiki extract --src-dir . --include-empty
+llm-wiki extract --src-dir . --summary --output sources/code.json --read-only
+llm-wiki extract --src-dir /path/to/repo --allow-external-src --summary
 ```
 
+The JSON output includes `schema_version: "llm-wiki-extract/v1"` plus
+`inventory` and optional `docker` objects. Inventory keys are POSIX paths
+relative to `--src-dir`, never absolute paths. The v1 contract permits additive
+fields; incompatible shape changes require a new schema version.
+
 ### `prepare-extractors`
 
 Prepare TypeScript dependencies and cached Go/Rust helper binaries outside the
@@ -336,6 +347,7 @@ llm-wiki context --budget 8000 --src-dir . --format json
 llm-wiki context --budget 8000 --src-dir . --format markdown
 llm-wiki context --budget 8000 --focus changed
 llm-wiki context --budget 8000 --focus all
+llm-wiki context --budget 12000 --format json --focus all --output context.json --read-only
 ```
 
 `--focus changed` is the default. Changed files get full detail, one-hop import
@@ -362,6 +374,85 @@ Example request:
 }
 ```
 
+`--output PATH` writes the generated JSON or Markdown directly instead of
+printing it to stdout. `--read-only` documents source-adapter intent: the command
+does not write wiki files, hooks, manifests, local config, or helper/cache state,
+except for an explicit `--output` artifact.
+
+### Codebase source integration
+
+For research or indexing systems that need codebase evidence without adopting
+the maintained wiki format, prefer the read-only source-adapter commands:
+
+```bash
+llm-wiki extract --src-dir <repo> --summary --read-only
+llm-wiki context --src-dir <repo> --budget 12000 --format json --focus all --read-only
+llm-wiki bootstrap --src-dir <repo> --wiki-dir sources/code_wikis/<source_id> --format json --source-adapter
+```
+
+By default, `--src-dir` must resolve inside the current working directory. For a
+trusted source tree outside cwd, pass `--allow-external-src`; explicit
+`--paths` are still constrained to the chosen source root. Explicit output paths
+such as `--output` may be absolute or outside the project root because they are
+caller-selected artifacts.
+
+Example `extract --summary` payload:
+
+```json
+{
+  "schema_version": "llm-wiki-extract/v1",
+  "inventory": {
+    "models.py": {
+      "language": "python",
+      "package": "sample",
+      "classes": ["User"],
+      "functions": ["load_user"]
+    }
+  }
+}
+```
+
+Example `context --format json` payload:
+
+```json
+{
+  "budget": 12000,
+  "used": 320,
+  "truncated": false,
+  "omitted_files": [],
+  "downgraded_files": {},
+  "files": {
+    "models.py": {
+      "priority": "high",
+      "detail": "deep",
+      "classes": [{"name": "User"}],
+      "functions": []
+    }
+  }
+}
+```
+
+Example `bootstrap --format json --source-adapter` summary:
+
+```json
+{
+  "schema_version": "llm-wiki-bootstrap-summary/v1",
+  "src_dir": "/path/to/repo",
+  "generated_wiki_path": "sources/code_wikis/repo",
+  "depth": "full",
+  "source_files": 12,
+  "classes": 8,
+  "functions": 31,
+  "docker_files": 1,
+  "workflows": 2,
+  "cross_references": 14,
+  "created_files": ["sources/code_wikis/repo/index.md"],
+  "updated_files": [],
+  "skipped_files": [],
+  "manifest_path": "sources/code_wikis/repo/.llm-wiki-manifest.json"
+}
+```
+
 ### `generate-prompt`
 
 Build a sync prompt for IDE agents or for manual review.

{agent_wiki_cli-0.5.1 → agent_wiki_cli-0.5.2}/README.md

@@ -189,12 +189,16 @@ llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki bootstrap --overwrite
 llm-wiki bootstrap --depth shallow
 llm-wiki bootstrap --skip-workflows
+llm-wiki bootstrap --format json --source-adapter
 ```
 
 `bootstrap` writes entity, module, workflow, infrastructure, index, log, and
 manifest files. `--depth full` is the default and includes docstrings, imports,
 attributes, method signatures, and relationship data where extractors provide
-it.
+it. Use `--source-adapter` when callers need bootstrap to write only under
+`--wiki-dir`; this skips agent constraint-file updates outside the generated
+wiki directory. Use `--format json` to emit a machine-readable summary with
+created, updated, and skipped files plus source counts and the manifest path.
 
 ### `sync`
 
@@ -235,8 +239,15 @@ llm-wiki extract --src-dir . --deep
 llm-wiki extract --src-dir . --paths src/foo.py src/bar.ts
 llm-wiki extract --src-dir . --package llm_wiki_cli
 llm-wiki extract --src-dir . --include-empty
+llm-wiki extract --src-dir . --summary --output sources/code.json --read-only
+llm-wiki extract --src-dir /path/to/repo --allow-external-src --summary
 ```
 
+The JSON output includes `schema_version: "llm-wiki-extract/v1"` plus
+`inventory` and optional `docker` objects. Inventory keys are POSIX paths
+relative to `--src-dir`, never absolute paths. The v1 contract permits additive
+fields; incompatible shape changes require a new schema version.
+
 ### `prepare-extractors`
 
 Prepare TypeScript dependencies and cached Go/Rust helper binaries outside the
@@ -306,6 +317,7 @@ llm-wiki context --budget 8000 --src-dir . --format json
 llm-wiki context --budget 8000 --src-dir . --format markdown
 llm-wiki context --budget 8000 --focus changed
 llm-wiki context --budget 8000 --focus all
+llm-wiki context --budget 12000 --format json --focus all --output context.json --read-only
 ```
 
 `--focus changed` is the default. Changed files get full detail, one-hop import
@@ -332,6 +344,85 @@ Example request:
 }
 ```
 
+`--output PATH` writes the generated JSON or Markdown directly instead of
+printing it to stdout. `--read-only` documents source-adapter intent: the command
+does not write wiki files, hooks, manifests, local config, or helper/cache state,
+except for an explicit `--output` artifact.
+
+### Codebase source integration
+
+For research or indexing systems that need codebase evidence without adopting
+the maintained wiki format, prefer the read-only source-adapter commands:
+
+```bash
+llm-wiki extract --src-dir <repo> --summary --read-only
+llm-wiki context --src-dir <repo> --budget 12000 --format json --focus all --read-only
+llm-wiki bootstrap --src-dir <repo> --wiki-dir sources/code_wikis/<source_id> --format json --source-adapter
+```
+
+By default, `--src-dir` must resolve inside the current working directory. For a
+trusted source tree outside cwd, pass `--allow-external-src`; explicit
+`--paths` are still constrained to the chosen source root. Explicit output paths
+such as `--output` may be absolute or outside the project root because they are
+caller-selected artifacts.
+
+Example `extract --summary` payload:
+
+```json
+{
+  "schema_version": "llm-wiki-extract/v1",
+  "inventory": {
+    "models.py": {
+      "language": "python",
+      "package": "sample",
+      "classes": ["User"],
+      "functions": ["load_user"]
+    }
+  }
+}
+```
+
+Example `context --format json` payload:
+
+```json
+{
+  "budget": 12000,
+  "used": 320,
+  "truncated": false,
+  "omitted_files": [],
+  "downgraded_files": {},
+  "files": {
+    "models.py": {
+      "priority": "high",
+      "detail": "deep",
+      "classes": [{"name": "User"}],
+      "functions": []
+    }
+  }
+}
+```
+
+Example `bootstrap --format json --source-adapter` summary:
+
+```json
+{
+  "schema_version": "llm-wiki-bootstrap-summary/v1",
+  "src_dir": "/path/to/repo",
+  "generated_wiki_path": "sources/code_wikis/repo",
+  "depth": "full",
+  "source_files": 12,
+  "classes": 8,
+  "functions": 31,
+  "docker_files": 1,
+  "workflows": 2,
+  "cross_references": 14,
+  "created_files": ["sources/code_wikis/repo/index.md"],
+  "updated_files": [],
+  "skipped_files": [],
+  "manifest_path": "sources/code_wikis/repo/.llm-wiki-manifest.json"
+}
+```
+
 ### `generate-prompt`
 
 Build a sync prompt for IDE agents or for manual review.

{agent_wiki_cli-0.5.1 → agent_wiki_cli-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-wiki-cli"
-version = "0.5.1"
+version = "0.5.2"
 description = "CLI tool to maintain hybrid LLM Wikis for multi-language projects."
 readme = "README.md"
 license = {text = "MIT"}

{agent_wiki_cli-0.5.1 → agent_wiki_cli-0.5.2/src/agent_wiki_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 0.5.1
+Version: 0.5.2
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License: MIT
@@ -219,12 +219,16 @@ llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki
 llm-wiki bootstrap --overwrite
 llm-wiki bootstrap --depth shallow
 llm-wiki bootstrap --skip-workflows
+llm-wiki bootstrap --format json --source-adapter
 ```
 
 `bootstrap` writes entity, module, workflow, infrastructure, index, log, and
 manifest files. `--depth full` is the default and includes docstrings, imports,
 attributes, method signatures, and relationship data where extractors provide
-it.
+it. Use `--source-adapter` when callers need bootstrap to write only under
+`--wiki-dir`; this skips agent constraint-file updates outside the generated
+wiki directory. Use `--format json` to emit a machine-readable summary with
+created, updated, and skipped files plus source counts and the manifest path.
 
 ### `sync`
 
@@ -265,8 +269,15 @@ llm-wiki extract --src-dir . --deep
 llm-wiki extract --src-dir . --paths src/foo.py src/bar.ts
 llm-wiki extract --src-dir . --package llm_wiki_cli
 llm-wiki extract --src-dir . --include-empty
+llm-wiki extract --src-dir . --summary --output sources/code.json --read-only
+llm-wiki extract --src-dir /path/to/repo --allow-external-src --summary
 ```
 
+The JSON output includes `schema_version: "llm-wiki-extract/v1"` plus
+`inventory` and optional `docker` objects. Inventory keys are POSIX paths
+relative to `--src-dir`, never absolute paths. The v1 contract permits additive
+fields; incompatible shape changes require a new schema version.
+
 ### `prepare-extractors`
 
 Prepare TypeScript dependencies and cached Go/Rust helper binaries outside the
@@ -336,6 +347,7 @@ llm-wiki context --budget 8000 --src-dir . --format json
 llm-wiki context --budget 8000 --src-dir . --format markdown
 llm-wiki context --budget 8000 --focus changed
 llm-wiki context --budget 8000 --focus all
+llm-wiki context --budget 12000 --format json --focus all --output context.json --read-only
 ```
 
 `--focus changed` is the default. Changed files get full detail, one-hop import
@@ -362,6 +374,85 @@ Example request:
 }
 ```
 
+`--output PATH` writes the generated JSON or Markdown directly instead of
+printing it to stdout. `--read-only` documents source-adapter intent: the command
+does not write wiki files, hooks, manifests, local config, or helper/cache state,
+except for an explicit `--output` artifact.
+
+### Codebase source integration
+
+For research or indexing systems that need codebase evidence without adopting
+the maintained wiki format, prefer the read-only source-adapter commands:
+
+```bash
+llm-wiki extract --src-dir <repo> --summary --read-only
+llm-wiki context --src-dir <repo> --budget 12000 --format json --focus all --read-only
+llm-wiki bootstrap --src-dir <repo> --wiki-dir sources/code_wikis/<source_id> --format json --source-adapter
+```
+
+By default, `--src-dir` must resolve inside the current working directory. For a
+trusted source tree outside cwd, pass `--allow-external-src`; explicit
+`--paths` are still constrained to the chosen source root. Explicit output paths
+such as `--output` may be absolute or outside the project root because they are
+caller-selected artifacts.
+
+Example `extract --summary` payload:
+
+```json
+{
+  "schema_version": "llm-wiki-extract/v1",
+  "inventory": {
+    "models.py": {
+      "language": "python",
+      "package": "sample",
+      "classes": ["User"],
+      "functions": ["load_user"]
+    }
+  }
+}
+```
+
+Example `context --format json` payload:
+
+```json
+{
+  "budget": 12000,
+  "used": 320,
+  "truncated": false,
+  "omitted_files": [],
+  "downgraded_files": {},
+  "files": {
+    "models.py": {
+      "priority": "high",
+      "detail": "deep",
+      "classes": [{"name": "User"}],
+      "functions": []
+    }
+  }
+}
+```
+
+Example `bootstrap --format json --source-adapter` summary:
+
+```json
+{
+  "schema_version": "llm-wiki-bootstrap-summary/v1",
+  "src_dir": "/path/to/repo",
+  "generated_wiki_path": "sources/code_wikis/repo",
+  "depth": "full",
+  "source_files": 12,
+  "classes": 8,
+  "functions": 31,
+  "docker_files": 1,
+  "workflows": 2,
+  "cross_references": 14,
+  "created_files": ["sources/code_wikis/repo/index.md"],
+  "updated_files": [],
+  "skipped_files": [],
+  "manifest_path": "sources/code_wikis/repo/.llm-wiki-manifest.json"
+}
+```
+
 ### `generate-prompt`
 
 Build a sync prompt for IDE agents or for manual review.

{agent_wiki_cli-0.5.1 → agent_wiki_cli-0.5.2}/src/agent_wiki_cli.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ src/agent_wiki_cli.egg-info/entry_points.txt
 src/agent_wiki_cli.egg-info/requires.txt
 src/agent_wiki_cli.egg-info/top_level.txt
 src/llm_wiki_cli/__init__.py
+src/llm_wiki_cli/api.py
 src/llm_wiki_cli/cli.py
 src/llm_wiki_cli/config.py
 src/llm_wiki_cli/commands/__init__.py
@@ -50,6 +51,7 @@ src/llm_wiki_cli/extractors/ts_scripts/extract.js
 src/llm_wiki_cli/extractors/ts_scripts/package.json
 src/llm_wiki_cli/services/__init__.py
 src/llm_wiki_cli/services/circuit_breaker.py
+src/llm_wiki_cli/services/contracts.py
 src/llm_wiki_cli/services/extractor_helpers.py
 src/llm_wiki_cli/services/imports.py
 src/llm_wiki_cli/services/inventory_cache.py
@@ -66,6 +68,7 @@ src/llm_wiki_cli/services/secure_file.py
 src/llm_wiki_cli/services/source_snapshot.py
 src/llm_wiki_cli/services/team.py
 src/llm_wiki_cli/services/versioning.py
+tests/test_api.py
 tests/test_bootstrap.py
 tests/test_bump.py
 tests/test_ci_check.py

agent_wiki_cli-0.5.2/src/llm_wiki_cli/api.py

@@ -0,0 +1,130 @@
+"""Supported Python API for source-adapter extraction and context payloads."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .commands import context_cmd, extract_cmd
+from .config import PathValidationError
+from .services.contracts import (
+    BOOTSTRAP_SUMMARY_SCHEMA_VERSION,
+    EXTRACT_SCHEMA_VERSION,
+)
+
+
+class LlmWikiApiError(RuntimeError):
+    """Base exception raised by the supported Python API."""
+
+
+class PathPolicyError(LlmWikiApiError):
+    """Raised when a source path violates the configured path policy."""
+
+
+class ExtractionError(LlmWikiApiError):
+    """Raised when source extraction fails."""
+
+
+def extract_source(
+    src_dir: str = ".",
+    *,
+    changed: bool = False,
+    summary: bool = False,
+    deep: bool = False,
+    paths: list[str] | None = None,
+    package: str | None = None,
+    include_empty: bool = False,
+    allow_external_src: bool = False,
+    read_only: bool = True,
+) -> dict[str, Any]:
+    """Return the stable ``llm-wiki extract`` JSON payload as a dict."""
+    try:
+        result = extract_cmd.build_extract_payload(
+            src_dir,
+            changed=changed,
+            summary=summary,
+            deep=deep,
+            paths=paths,
+            package_filter=package,
+            include_empty=include_empty,
+            allow_external_src=allow_external_src,
+            read_only=read_only,
+        )
+    except PathValidationError as exc:
+        raise PathPolicyError(str(exc)) from exc
+    except extract_cmd.ExtractorFailureError as exc:
+        raise ExtractionError(str(exc)) from exc
+    except ValueError as exc:
+        raise LlmWikiApiError(str(exc)) from exc
+    return result.payload
+
+
+def build_context(
+    src_dir: str = ".",
+    *,
+    budget: int = 32000,
+    format: str = "json",
+    focus: str | list[str] = "changed",
+    filters: dict | None = None,
+    allow_external_src: bool = False,
+    read_only: bool = True,
+) -> dict[str, Any]:
+    """Return a supported context payload without depending on CLI internals."""
+    focus_values = _normalise_focus(focus)
+    request = {
+        "protocol": context_cmd.PROTOCOL_VERSION,
+        "budget_tokens": budget,
+        "focus": focus_values,
+        "format": format,
+        "filters": filters or {},
+    }
+    try:
+        validated = context_cmd._validate_protocol_request(request)
+        payload, warnings = context_cmd._build_context(
+            src_dir,
+            validated["budget_tokens"],
+            validated["format"],
+            validated["focus"],
+            validated["filters"],
+            emit_warnings=False,
+            allow_external_src=allow_external_src,
+            read_only=read_only,
+        )
+    except PathValidationError as exc:
+        raise PathPolicyError(str(exc)) from exc
+    except context_cmd.ProtocolRequestError as exc:
+        if exc.field == "src_dir":
+            raise ExtractionError(str(exc)) from exc
+        raise LlmWikiApiError(str(exc)) from exc
+
+    if validated["format"] == "markdown":
+        return {
+            "content": context_cmd._render_markdown(payload),
+            "payload": payload,
+            "warnings": warnings,
+        }
+
+    result = dict(payload)
+    if warnings:
+        result["warnings"] = warnings
+    return result
+
+
+def _normalise_focus(focus: str | list[str]) -> list[str]:
+    if isinstance(focus, str):
+        if focus == "all":
+            return ["all"]
+        if focus == "changed":
+            return ["changed", "neighbors"]
+        return [focus]
+    return list(focus)
+
+
+__all__ = [
+    "BOOTSTRAP_SUMMARY_SCHEMA_VERSION",
+    "EXTRACT_SCHEMA_VERSION",
+    "ExtractionError",
+    "LlmWikiApiError",
+    "PathPolicyError",
+    "build_context",
+    "extract_source",
+]

{agent_wiki_cli-0.5.1 → agent_wiki_cli-0.5.2}/src/llm_wiki_cli/cli.py

@@ -78,6 +78,12 @@ def main():
                                 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")
+    extract_parser.add_argument("--output", metavar="PATH",
+                                help="Write JSON output to a file instead of stdout")
+    extract_parser.add_argument("--read-only", action="store_true",
+                                help="Guarantee source-adapter mode writes no llm-wiki files except explicit --output")
+    extract_parser.add_argument("--allow-external-src", action="store_true",
+                                help="Allow --src-dir to point outside the current working directory")
 
     # lint command
     lint_parser = subparsers.add_parser("lint", help="Lint LLM Wiki for broken links, orphans, and AST drift")
@@ -203,6 +209,12 @@ def main():
                                   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")
+    bootstrap_parser.add_argument("--format", choices=["text", "json"], default="text",
+                                  help="Console output format (default: text)")
+    bootstrap_parser.add_argument("--source-adapter", action="store_true",
+                                  help="Write only under --wiki-dir and skip agent constraint updates")
+    bootstrap_parser.add_argument("--allow-external-src", action="store_true",
+                                  help="Allow --src-dir to point outside the current working directory")
 
     # bump command
     bump_parser = subparsers.add_parser("bump", help="Bump project version (patch or minor)")
@@ -393,6 +405,12 @@ def main():
                                 help="changed=prioritise git diff files, all=treat every file as high priority (default: changed)")
     context_parser.add_argument("--request", metavar="FILE|-",
                                 help="Read a Wiki-as-Context protocol JSON request from a file or stdin")
+    context_parser.add_argument("--output", metavar="PATH",
+                                help="Write generated context to a file instead of stdout")
+    context_parser.add_argument("--read-only", action="store_true",
+                                help="Guarantee source-adapter mode writes no llm-wiki files except explicit --output")
+    context_parser.add_argument("--allow-external-src", action="store_true",
+                                help="Allow --src-dir to point outside the current working directory")
 
     args = parser.parse_args()