agent-wiki-cli 2.3.1__tar.gz → 2.3.2__tar.gz

{agent_wiki_cli-2.3.1/src/agent_wiki_cli.egg-info → agent_wiki_cli-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 2.3.1
+Version: 2.3.2
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License-Expression: MIT
@@ -37,6 +37,10 @@ Dynamic: license-file
 
 # LLM Wiki CLI
 
+[![CI](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
 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
@@ -67,13 +71,17 @@ 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
+llm-wiki init --agent generic --prepare-extractors
 ```
 
-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.
+`--prepare-extractors` automatically prepares missing or stale helpers for the
+selected TypeScript/JavaScript, Go, Rust, or Haskell source files and reuses
+current helpers. Install the relevant toolchain first: Node.js with npm, Go,
+Cargo, or GHC. Python needs no helper.
+[Helper setup](docs/cli-reference.md#prepare-extractors) may download dependencies
+or compile a bundled helper. Omit the flag to scaffold without preparation;
+read-only commands never prepare helpers. You can rerun the setup command after
+a package upgrade or use `llm-wiki prepare-extractors --src-dir .` separately.
 
 ```bash
 llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki

{agent_wiki_cli-2.3.1 → agent_wiki_cli-2.3.2}/README.md

@@ -1,5 +1,9 @@
 # LLM Wiki CLI
 
+[![CI](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
 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
@@ -30,13 +34,17 @@ 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
+llm-wiki init --agent generic --prepare-extractors
 ```
 
-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.
+`--prepare-extractors` automatically prepares missing or stale helpers for the
+selected TypeScript/JavaScript, Go, Rust, or Haskell source files and reuses
+current helpers. Install the relevant toolchain first: Node.js with npm, Go,
+Cargo, or GHC. Python needs no helper.
+[Helper setup](docs/cli-reference.md#prepare-extractors) may download dependencies
+or compile a bundled helper. Omit the flag to scaffold without preparation;
+read-only commands never prepare helpers. You can rerun the setup command after
+a package upgrade or use `llm-wiki prepare-extractors --src-dir .` separately.
 
 ```bash
 llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki

{agent_wiki_cli-2.3.1 → agent_wiki_cli-2.3.2}/docs/automation.md

@@ -121,6 +121,131 @@ that exact commit. Routine pull-request health remains advisory. The release
 workflow retains `evidence-rd-10` with original maintenance inputs and
 `knowledge-maintenance-verification` with the separate verification result.
 
+For TypeScript/JavaScript wiki refreshes, use the locked Node/npm toolchain for
+the active extraction process as well as helper preparation. A helper prepared
+with the lock can still be executed by a different `node` on `PATH`; that records
+a different runtime identity and can prevent portable release-health comparison.
+On a source checkout, prepare and activate the ignored local toolchain before
+refreshing:
+
+```bash
+bash .github/scripts/setup-llm-wiki-ci-toolchains.sh --mode routine \
+  --install-root .git/llm-wiki-ci-toolchains \
+  --environment-file .git/llm-wiki-ci-toolchains.env --python .venv/bin/python
+source .git/llm-wiki-ci-toolchains.env
+.venv/bin/python -m llm_wiki_cli.cli sync --jobs 1 --src-dir . --wiki-dir docs/llm_wiki
+.venv/bin/python -m llm_wiki_cli.cli doctor --strict --comparison-policy analysis-v1 \
+  --src-dir . --wiki-dir docs/llm_wiki
+```
+
+### Qualification after merging
+
+Repository release automation is disabled by default in
+[`release/automation.json`](../release/automation.json). When enabled, successful
+main CI starts the coordinator. A stale policy binding receives a bounded,
+nonpromoting evaluation of the committed repository and standalone doctor
+parity. This evaluation can run between releases, including when the current
+version is already published.
+
+The coordinator authenticates the original hosted artifacts and creates a bot
+pull request containing only the activation update and its audit receipt.
+Independent proof verification, complete CI, and up-to-date branch checks must
+pass before automatic squash merging. The merge starts fresh CI and normal
+qualification for that exact main commit. Normal qualification waits when the
+version, release tag, or changelog is not ready; unavailable remote checks are
+reported as blocked. Source, health, and integrity failures remain blocking.
+
+Configure the following before setting `enabled` to `true`:
+
+- Enable repository auto-merge and protect main through pull requests, with no
+  bypass actors and with force pushes and deletion prohibited.
+- Require `CI complete` and `Release activation proof`, with up-to-date checks.
+  Retain the existing integrity requirement.
+- Set `trusted_bot.login` and `trusted_bot.id` to the bot account, and
+  `trusted_bot.check_app_id` to its independent check publisher's GitHub App ID.
+- For GitHub App authentication, configure the repository variable
+  `RELEASE_AUTOMATION_APP_CLIENT_ID` and secret
+  `RELEASE_AUTOMATION_APP_PRIVATE_KEY`. The pinned adapter creates and revokes a
+  repository-scoped installation token for each coordinator run. Grant Actions,
+  Contents, Pull requests, and Checks write permissions, and Administration read
+  permission to inspect branch rules. Do not grant protection bypass.
+- Alternatively, provide a suitable bot credential through the
+  `RELEASE_AUTOMATION_TOKEN` secret. It must authenticate as the configured bot
+  and check publisher; the coordinator never substitutes the ordinary job token.
+
+Missing credentials or protections produce `blocked_setup` without dispatching
+qualification or changing the repository. Configure and enable automation
+through a normal pull request, then use **Release qualification automation** in
+Actions to resume the current main candidate. The optional retry input creates
+a new request only when explicitly selected; duplicate completion events reuse
+existing work.
+
+Pinned candidate branches and candidate/run/attempt identities prevent main
+advancing during dispatch from changing the qualified source. Changed policy
+inputs supersede older renewal evidence. Audit receipts remain committed under
+`release/policy-activations/` after hosted artifact retention expires.
+
+Automation finishes with verified qualified artifacts and their links. PyPI
+publication and release tag creation remain separate explicit operations.
+
+## Manual policy approval and main releases
+
+Use **Renew policy approval** in Actions when the required policy binding is
+stale. This workflow works independently of whether the recurring release
+coordinator is enabled. It runs from `main` and offers a choice instead of
+requiring callers to find the policy-shadow switch among qualification options.
+
+1. Select `evaluate`. The workflow captures current main and dispatches a
+   nonpromoting policy proof through **Release qualification**. Its summary
+   links to qualification runs. Wait for the proof run to complete successfully.
+2. Run **Renew policy approval** again with `prepare`, that proof's run ID, and
+   its successful attempt number. The trusted verifier authenticates the
+   hosted artifacts, replays the evidence, and checks that the proof source is
+   in main history with unchanged policy implementation and configuration.
+3. Review the generated approval PR. With the configured GitHub App or
+   `RELEASE_AUTOMATION_TOKEN`, the workflow creates an activation-only PR from
+   `codex/manual-policy-activation/<implementation-digest>`. The credential
+   must belong to a repository maintainer or the configured trusted bot and
+   must trigger ordinary PR checks. The default job token is used for proof
+   dispatch and reading evidence, not for creating the approval PR.
+4. Without a PR credential, download `policy-approval-proposal`. Its generated
+   `release/knowledge-maintenance.json` and
+   `release/policy-activations/<implementation-digest>.json` are the two files
+   for a maintainer approval PR. Create the named branch from current main
+   without upstream tracking, commit those files, and push with an explicit
+   same-name refspec. If main advances, rerun `prepare` instead of carrying
+   other changes into that approval PR.
+   Retry an interrupted approval request with the same proof. The helper reuses
+   an existing branch only when its commit, tree, and main parent match the
+   generated proposal, then returns its matching open PR or creates the missing
+   PR. Unrelated, stale, or concurrently changed state is rejected for review;
+   existing branch state is never overwritten.
+5. Merge only after the independent **Release activation proof** and normal
+   required checks succeed and the approval is reviewed. The renewal workflow
+   never merges the PR, creates release tags, or publishes distributions.
+
+New activation records use `proof_source_sha`: the historical commit on which
+the reviewed policy proof was produced. Existing `candidate_sha` records remain
+readable; providing both names is rejected. Existing coordinator proof runs
+retain their pinned branch and correlation checks. Manual proofs are accepted
+from main only through the explicit manual verification route.
+
+The coordinator identifies automatic proofs through authenticated dispatch
+receipts before considering manual approvals. Automatic approval PRs can be
+rebased after main advances even when their proposed audit is not yet on main.
+A committed manual audit must match the proof source, run, attempt, and
+implementation before its original hosted evidence is replayed.
+
+An activation-only merge changes main's commit SHA without changing the policy
+implementation digest or evaluated configuration. Keep `proof_source_sha`
+pointing to the proof commit; use the new main SHA as `candidate-sha` for normal
+**Release qualification**. Run qualification from main with policy shadow off.
+After it succeeds, dry-run **Promote qualified artifacts to PyPI** from main
+using that qualification run, `refs/heads/main`, and the bundle's distribution
+hashes. Create the release tag at the qualified SHA before requesting actual
+publication with the same bundle. Further release-source changes require a
+new full qualification.
+
 ## Git hook retirement
 
 Git hook installation has been removed. After updating the package, run the

{agent_wiki_cli-2.3.1 → agent_wiki_cli-2.3.2}/docs/cli-reference.md

@@ -49,6 +49,8 @@ Scaffold the wiki structure and agent constraint file.
 
 ```bash
 llm-wiki init --agent claude
+llm-wiki init --agent claude --prepare-extractors
+llm-wiki init --prepare-extractors --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki init --agent copilot --wiki-dir .wiki
 llm-wiki init --agent cursor --no-quality-hints
 llm-wiki init --agent generic --issue-reporting
@@ -62,6 +64,29 @@ them when refreshing an existing initialization. On a refresh, omitting
 `--agent` reuses the stored agent; a project with no stored selection defaults
 to `generic`.
 
+Add `--prepare-extractors` to automatically prepare missing or stale extractor
+helpers before creating or refreshing the wiki scaffold. Setup detects helper
+languages from the selected source files, honoring `--source-selection` and
+the stored selection on subsequent runs. Current helpers are reused without
+requiring their build tools. Preparation may download dependencies or compile
+bundled helpers; the relevant Node.js/npm, Go, Cargo, or GHC toolchain must be
+available when a helper needs preparation. TypeScript/JavaScript analysis still
+requires Node.js to run its prepared helper.
+
+If preparation fails, setup exits unsuccessfully before changing the scaffold
+or agent configuration. Fix the reported problem and rerun the same command;
+helpers that were successfully prepared are reused. Repeat this setup after a
+package upgrade or a change in selected languages. The flag applies only to
+that invocation and does not enable preparation in read-only commands.
+
+`--helper-cache-dir PATH` requires `--prepare-extractors` and selects the same
+cache base as `prepare-extractors --cache-dir PATH`. Otherwise setup uses
+`LLM_WIKI_CACHE_DIR` or the repository's `.git/llm-wiki-extractors/`. Projects
+without Git need an explicit cache location only when selected languages need
+helpers. A custom cache location is not saved in the agent configuration:
+pass it to later commands with `--helper-cache-dir PATH`, or set
+`LLM_WIKI_CACHE_DIR` consistently for setup and analysis.
+
 ## `bootstrap`
 
 Generate the initial full wiki for an existing project.
@@ -424,6 +449,11 @@ JSON payload includes top-level `warnings` only when such diagnostics exist.
 Prepare TypeScript/JavaScript dependencies and cached Go/Rust/Haskell helper
 binaries outside the lint/extract hot path.
 
+For automatic preparation during project setup, use
+`llm-wiki init --prepare-extractors`. This reuses valid helpers and prepares only
+missing or stale ones. `prepare-extractors` also checks the current build
+toolchain when explicitly rebuilding or refreshing the cache.
+
 ```bash
 llm-wiki prepare-extractors --src-dir .
 llm-wiki prepare-extractors --src-dir . --plan --format json
@@ -448,6 +478,18 @@ Commands that consume prepared Go/Rust/Haskell helpers accept
 This is separate from inventory-command `--cache-dir PATH`, which only controls
 where `llm-wiki-inventory-cache.json` is read and written.
 
+Missing-helper errors include a preparation command for the failing language,
+source root, and resolved helper cache. Run that command as an authorized setup
+step, then retry the original analysis with the same options. Keep
+`--source-selection` on the analysis command; a language-specific preparation
+command uses `--language` and cannot also take `--source-selection`. If no Git
+cache is available, the remedy proposes a cache under the source root's
+`.llm-wiki/`; select that base on later reads with `--helper-cache-dir` where
+supported, or `LLM_WIKI_CACHE_DIR`. Preparation failures include toolchain and
+retry guidance. `llm-wiki doctor --capabilities` provides read-only diagnosis.
+After updating the package, `llm-wiki upgrade` refreshes managed agent
+instructions so agents follow the helper recovery procedure.
+
 ## `lint` and `ci-check`
 
 Validate wiki links, orphan pages, entities, modules, workflows,

{agent_wiki_cli-2.3.1 → agent_wiki_cli-2.3.2}/pyproject.toml

@@ -5,7 +5,7 @@ backend-path = ["."]
 
 [project]
 name = "agent-wiki-cli"
-version = "2.3.1"
+version = "2.3.2"
 description = "CLI tool to maintain hybrid LLM Wikis for multi-language projects."
 readme = "README.md"
 license = "MIT"

{agent_wiki_cli-2.3.1 → agent_wiki_cli-2.3.2/src/agent_wiki_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 2.3.1
+Version: 2.3.2
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License-Expression: MIT
@@ -37,6 +37,10 @@ Dynamic: license-file
 
 # LLM Wiki CLI
 
+[![CI](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
 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
@@ -67,13 +71,17 @@ 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
+llm-wiki init --agent generic --prepare-extractors
 ```
 
-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.
+`--prepare-extractors` automatically prepares missing or stale helpers for the
+selected TypeScript/JavaScript, Go, Rust, or Haskell source files and reuses
+current helpers. Install the relevant toolchain first: Node.js with npm, Go,
+Cargo, or GHC. Python needs no helper.
+[Helper setup](docs/cli-reference.md#prepare-extractors) may download dependencies
+or compile a bundled helper. Omit the flag to scaffold without preparation;
+read-only commands never prepare helpers. You can rerun the setup command after
+a package upgrade or use `llm-wiki prepare-extractors --src-dir .` separately.
 
 ```bash
 llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki

{agent_wiki_cli-2.3.1 → agent_wiki_cli-2.3.2}/src/agent_wiki_cli.egg-info/SOURCES.txt

@@ -152,6 +152,7 @@ src/llm_wiki_cli/services/health_contract.py
 src/llm_wiki_cli/services/health_details.py
 src/llm_wiki_cli/services/health_policy.py
 src/llm_wiki_cli/services/health_summary.py
+src/llm_wiki_cli/services/helper_preparation.py
 src/llm_wiki_cli/services/immutable.py
 src/llm_wiki_cli/services/impact.py
 src/llm_wiki_cli/services/imports.py
@@ -231,6 +232,9 @@ src/llm_wiki_cli/services/storage_sort.py
 src/llm_wiki_cli/services/storage_spool.py
 src/llm_wiki_cli/services/sync_analysis.py
 src/llm_wiki_cli/services/sync_manifest.py
+src/llm_wiki_cli/services/sync_retained_links.py
+src/llm_wiki_cli/services/sync_transition_execution.py
+src/llm_wiki_cli/services/sync_transitions.py
 src/llm_wiki_cli/services/task_context.py
 src/llm_wiki_cli/services/task_context_v2.py
 src/llm_wiki_cli/services/task_contract.py
@@ -413,6 +417,7 @@ tests/test_guarded_read_metadata.py
 tests/test_haskell_extract.py
 tests/test_health_details.py
 tests/test_helper_packaging_parity.py
+tests/test_helper_preparation.py
 tests/test_hook.py
 tests/test_hosted_evidence.py
 tests/test_impact.py
@@ -499,6 +504,9 @@ tests/test_packet_field_policy.py
 tests/test_paths.py
 tests/test_plugin_sample.py
 tests/test_plugins.py
+tests/test_policy_activation.py
+tests/test_policy_renewal.py
+tests/test_policy_source_freeze.py
 tests/test_progress.py
 tests/test_protected_artifacts.py
 tests/test_protocol_registry.py
@@ -513,6 +521,7 @@ tests/test_python_import_scopes.py
 tests/test_python_observation_cache.py
 tests/test_python_source_inventory.py
 tests/test_python_typed_dicts.py
+tests/test_qualification_automation.py
 tests/test_qualified_context_acceptance.py
 tests/test_quality_workflows.py
 tests/test_readonly_subprocess_stdin.py
@@ -520,6 +529,7 @@ tests/test_redaction.py
 tests/test_reference_skill_verifier.py
 tests/test_relationships.py
 tests/test_release.py
+tests/test_release_automation_workflow.py
 tests/test_release_build_backend.py
 tests/test_release_dogfood.py
 tests/test_release_qualification.py
@@ -553,10 +563,16 @@ tests/test_storage_locality.py
 tests/test_storage_performance.py
 tests/test_surface_initialization.py
 tests/test_sync.py
+tests/test_sync_analysis.py
 tests/test_sync_api_contracts.py
 tests/test_sync_manifest.py
+tests/test_sync_missing_pages.py
 tests/test_sync_no_plugins.py
+tests/test_sync_page_transitions.py
+tests/test_sync_retained_links.py
 tests/test_sync_runtime_regressions.py
+tests/test_sync_transition_execution.py
+tests/test_sync_transitions.py
 tests/test_task_context.py
 tests/test_task_context_v2.py
 tests/test_team.py

{agent_wiki_cli-2.3.1 → agent_wiki_cli-2.3.2}/src/llm_wiki_cli/api.py

@@ -831,7 +831,14 @@ def _raise_native_query_api_error(exc: Exception) -> NoReturn:
                 "Set allow_full_inventory=true to authorize a full-inventory query."
             )
         elif issubclass(leaf, WorkspaceStateError):
-            message = "A required documentation input or read capability is unavailable. Check access and prepared helpers."
+            message = (
+                "A required documentation input or read capability is unavailable. "
+                "Check access and prepared helpers. Run llm-wiki doctor --capabilities "
+                "with the same source root (--src-dir), source selection, and helper cache. "
+                "If a helper needs "
+                "preparation, use its recovery command in an authorized setup step, "
+                "then retry the original read."
+            )
         elif issubclass(leaf, ArtifactIntegrityError):
             message = "Documentation artifacts do not satisfy the supported integrity contract."
         else:

{agent_wiki_cli-2.3.1 → agent_wiki_cli-2.3.2}/src/llm_wiki_cli/cli.py

@@ -356,6 +356,15 @@ def _add_init_command(subparsers):
         default=None,
         help="Skip installing the wiki-reference skill into the agent's skills directory (.claude/skills for claude, .llm-wiki/skills otherwise)",
     )
+    init_parser.add_argument(
+        "--prepare-extractors",
+        action="store_true",
+        help=(
+            "Prepare missing or stale helpers for selected source languages during "
+            "setup; may download dependencies or compile bundled helpers"
+        ),
+    )
+    _add_helper_cache_argument(init_parser)
     init_issue_reporting = init_parser.add_mutually_exclusive_group()
     init_issue_reporting.add_argument(
         "--issue-reporting",

{agent_wiki_cli-2.3.1 → agent_wiki_cli-2.3.2}/src/llm_wiki_cli/commands/init_cmd.py

@@ -22,6 +22,8 @@ from ..services.filesystem_guard import (
     ensure_guarded_directory,
     unlink_guarded_bytes,
 )
+from ..services.helper_preparation import ensure_source_helpers
+from ..services.extractor_helpers import helper_preparation_failure_hint
 from ..services.rendering_lifecycle import (
     reference_recovery_command,
     select_render_profile,
@@ -93,6 +95,14 @@ def _managed_schema_agents() -> tuple[str, ...]:
 def run(args):
     wiki_dir = getattr(args, "wiki_dir", DEFAULT_WIKI_DIR)
     validate_path(wiki_dir, "--wiki-dir")
+    prepare_extractors = bool(getattr(args, "prepare_extractors", False))
+    helper_cache_dir = getattr(args, "helper_cache_dir", None)
+    if helper_cache_dir is not None and not prepare_extractors:
+        print(
+            "Error: --helper-cache-dir requires --prepare-extractors during init.",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
     try:
         require_safe_wiki_scaffold(wiki_dir)
         require_safe_config_path(wiki_dir)
@@ -302,6 +312,30 @@ def run(args):
             )
             raise SystemExit(2) from exc
 
+    if prepare_extractors:
+        print("Preparing selected extractor helpers...", flush=True)
+        try:
+            results = ensure_source_helpers(
+                ".", cache_dir=helper_cache_dir, source_selection=source_selection
+            )
+        except (ValueError, OSError) as exc:
+            print(f"Error preparing extractor helpers: {exc}", file=sys.stderr)
+            raise SystemExit(1) from exc
+        for result in results:
+            print(f"{result.language}: {result.status} - {result.message}")
+            if result.status == "failed":
+                print(f"Next step: {helper_preparation_failure_hint(result.language)}")
+        if any(result.status not in {"prepared", "already_current"} for result in results):
+            print(
+                "Error: extractor helper preparation did not complete. "
+                "Resolve the reported problem and rerun the same init command; "
+                "successfully prepared helpers will be reused.",
+                file=sys.stderr,
+            )
+            raise SystemExit(1)
+        if not results:
+            print("No extractor helpers required for the selected source files.")
+
     print(f"Initializing LLM Wiki with {agent} schema...")
 
     # Warn if the agent has a CLI executable that isn't installed.

{agent_wiki_cli-2.3.1 → agent_wiki_cli-2.3.2}/src/llm_wiki_cli/commands/prepare_extractors_cmd.py

@@ -8,11 +8,13 @@ from ..config import validate_source_root
 from ..services.extractor_helpers import (
     SUPPORTED_HELPERS,
     HelperPrepareResult,
+    helper_preparation_failure_hint,
     prepare_helper,
     resolve_helper_cache_root,
 )
 from ..services.source_snapshot import build_source_snapshot
 from ..services.source_selection import resolve_source_selection
+from ..services.helper_preparation import selected_helper_languages
 
 
 PREPARE_EXTRACTORS_PLAN_SCHEMA = "llm-wiki-prepare-extractors-plan/v1"
@@ -40,15 +42,7 @@ def _languages_from_snapshot(
     *,
     source_selection: str | Path | None = None,
 ) -> list[str]:
-    snapshot = build_source_snapshot(
-        src_dir,
-        source_selection=source_selection,
-    )
-    return [
-        language
-        for language in SUPPORTED_HELPERS
-        if snapshot.files_by_language.get(language)
-    ]
+    return selected_helper_languages(src_dir, source_selection=source_selection)
 
 
 def _print_plan(languages: list[str], output_format: str) -> None:
@@ -68,7 +62,10 @@ def _print_plan(languages: list[str], output_format: str) -> None:
 
 def _format_result(result: HelperPrepareResult) -> str:
     detail = f" ({result.path})" if result.path else ""
-    return f"{result.language}: {result.status} - {result.message}{detail}"
+    message = f"{result.language}: {result.status} - {result.message}{detail}"
+    if result.status == "failed":
+        message += f"\nNext step: {helper_preparation_failure_hint(result.language)}"
+    return message
 
 
 def run(args) -> None:
@@ -132,7 +129,13 @@ def run(args) -> None:
         return
 
     print(f"Preparing extractor helpers in: {Path(cache_root)}")
-    results = [prepare_helper(language, cache_root) for language in languages]
+    results = []
+    for language in languages:
+        try:
+            result = prepare_helper(language, cache_root)
+        except OSError as exc:
+            result = HelperPrepareResult(language, "failed", str(exc))
+        results.append(result)
     for result in results:
         print(_format_result(result))