chore(release): prepare 1.4.0#517
Conversation
a fresh project's `vouch install-mcp claude-code` used to exit 0 with
"0 failed", create no .vouch/, and print no warning. every installed
hook then no-oped silently forever (they are all wired `|| true`), the
mcp server exited 2, and nothing anywhere told the user to run
`vouch init` — the only diagnostic that exists (`vouch status`) is
itself muffled by `|| true` in the sessionstart hook. reproduced on the
released pypi 1.3.0.
install-mcp now probes discover_root(target) before writing adapter
files: no kb found means it runs the same bootstrap as `vouch init`
(shared `_bootstrap_kb` helper, so the two paths cannot drift — same
starter seed through the normal approved path, same index rebuild, same
audit event), making install a one-command setup. `--no-init` opts out
and a loud stderr warning then names the remedy. a kb discovered above
the target is reported ("Using existing KB at …") instead of being
shadowed by a second one. unknown hosts keep the clean adapter error
and never plant a kb as a side effect.
hardening from review: staging-dir hosts opt out via a new manifest key
`kb_bootstrap: false` — claude-desktop sets it, because its target is a
paste-ready staging dir and a kb planted at an arbitrary cwd (often
$HOME for a user-global host) would become the ambient capture target
for every child project via upward discovery. the preflight passes
`respect_env=False` to discover_root so a shell-exported VOUCH_KB_PATH
neither suppresses a needed bootstrap nor fakes a "no kb" state (it is
surfaced as a stderr note instead), and a bootstrap failure exits as a
clean click error naming --no-init rather than a traceback.
docs follow the new story: the readme's step 1 is one command, the
adapter readme states the manual path's `vouch init` prerequisite,
install.sh's nudges and docs/INSTALL_FOR_AGENTS.md steps 2/4 teach the
one-command flow, and the redundant review-ui blocks in the readme's
step 4 are collapsed into one option list.
coderabbit review on #516: the new source comments now follow the lowercase-prose convention, and install.sh's next-steps line says "project hosts create .vouch/ if missing" since staging-dir hosts (claude-desktop) opt out via kb_bootstrap: false.
fix(cli): install-mcp bootstraps the kb when .vouch/ is missing
bump the version in all four sites (pyproject.toml, openclaw.plugin.json, package.json, src/vouch/__init__.py) and date the changelog section. headline: install-mcp is now a one-command setup — it bootstraps the kb when no .vouch/ is discoverable (#516) — plus the coderabbit merge-gate and pr-bot hardening that landed on test since 1.3.0.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
Walkthrough
ChangesInstall-MCP knowledge-base bootstrap
Estimated code review effort: 3 (Moderate) | ~25 minutes Sequence Diagram(s)sequenceDiagram
participant User
participant install_mcp
participant AdapterManifest
participant KBDiscovery
participant BootstrapKB
User->>install_mcp: Run install-mcp host
install_mcp->>AdapterManifest: Read kb_bootstrap policy
install_mcp->>KBDiscovery: Discover target or ancestor KB
install_mcp->>BootstrapKB: Initialize missing KB when enabled
BootstrapKB-->>install_mcp: Return initialized store and seed results
install_mcp-->>User: Complete wiring or report actionable error
Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
github-actions
Bot
added
docs
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
tests/test_install_adapter.py (1)
958-973: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winexercise failure after
.vouchhas been created.replacing
_bootstrap_kbthrows before any mutation, so this test cannot catch a half-created kb that makes the next invocation skip bootstrap. inject failure from seeding, index rebuilding, or audit logging and assert that no incomplete discoverable kb remains.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@tests/test_install_adapter.py` around lines 958 - 973, Update test_cli_install_mcp_bootstrap_failure_is_clean_error to inject the OSError from a post-creation bootstrap step such as seeding, index rebuilding, or audit logging rather than replacing _bootstrap_kb before mutation. After the failed install, assert that no incomplete discoverable .vouch knowledge base remains and that a subsequent invocation does not incorrectly skip bootstrap, while preserving the existing clean-error assertions.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/vouch/cli.py`:
- Around line 3993-3999: Update the warning message in the surrounding .vouch
discovery branch to state only that no project knowledge base was found, and
explain that installed hooks and the MCP server depend on whether the
VOUCH_KB_PATH environment override is exported. Remove the unconditional claim
that they will do nothing.
- Around line 198-205: Make KB bootstrap atomic around the initialization flow
in src/vouch/cli.py lines 198-205: stage or track newly created .vouch state,
and remove only that new bootstrap state if seed_starter_kb, template seeding,
health.rebuild_index, or audit_mod.log_event fails. Update
tests/test_install_adapter.py lines 958-973 to inject a failure after .vouch
creation and verify a retry performs complete bootstrap rather than reusing
partial state.
- Around line 200-203: Update the bootstrap flow in the CLI around
seed_starter_kb and template generation so all initial sources, claims, and
pages are submitted and written through proposals.approve() rather than direct
store.put_* calls. Reuse the existing approved-proposal path for both the
starter knowledge base and non-default template while preserving the current
approved_by identity.
---
Nitpick comments:
In `@tests/test_install_adapter.py`:
- Around line 958-973: Update
test_cli_install_mcp_bootstrap_failure_is_clean_error to inject the OSError from
a post-creation bootstrap step such as seeding, index rebuilding, or audit
logging rather than replacing _bootstrap_kb before mutation. After the failed
install, assert that no incomplete discoverable .vouch knowledge base remains
and that a subsequent invocation does not incorrectly skip bootstrap, while
preserving the existing clean-error assertions.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 7d313872-9b8d-49bc-a2d0-6442deb10b65
📒 Files selected for processing (14)
CHANGELOG.mdREADME.mdadapters/claude-code/README.mdadapters/claude-desktop/install.yamldocs/INSTALL_FOR_AGENTS.mdinstall.shopenclaw.plugin.jsonpackage.jsonpyproject.tomlsrc/vouch/__init__.pysrc/vouch/cli.pysrc/vouch/install_adapter.pysrc/vouch/storage.pytests/test_install_adapter.py
| seed = seed_starter_kb(store, approved_by=_whoami()) | ||
| template_result: SeedResult | None = None | ||
| if template != DEFAULT_TEMPLATE: | ||
| template_result = TEMPLATES[template](store, approved_by=_whoami()) |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
ast-grep outline src/vouch/onboarding.py \
--items all \
--match 'seed_starter_kb|_starter_source|_starter_claim|_starter_page|TEMPLATES' \
--view expanded
rg -n -C3 'proposals\.approve\s*\(' src/vouchRepository: vouchdev/vouch
Length of output: 2120
🏁 Script executed:
#!/bin/bash
sed -n '1,220p' src/vouch/onboarding.py
printf '\n---\n'
rg -n -C3 'approve\(|approve\s*\(' src/vouch/onboarding.py src/vouch/proposals.py src/vouch/lifecycle.pyRepository: vouchdev/vouch
Length of output: 10771
🏁 Script executed:
#!/bin/bash
grep -nE 'def seed_starter_kb|def _starter_source|def _starter_claim|def _starter_page|proposals\.approve|approve\(' -n src/vouch/onboarding.py
sed -n '70,160p' src/vouch/onboarding.pyRepository: vouchdev/vouch
Length of output: 3284
🏁 Script executed:
#!/bin/bash
sed -n '70,160p' src/vouch/onboarding.pyRepository: vouchdev/vouch
Length of output: 2973
🏁 Script executed:
#!/bin/bash
sed -n '1,260p' src/vouch/storage.py
printf '\n---\n'
rg -n -C2 'def put_source|def put_claim|def put_page|def approve\(' src/vouch/storage.py src/vouch/proposals.pyRepository: vouchdev/vouch
Length of output: 10630
🏁 Script executed:
#!/bin/bash
sed -n '340,620p' src/vouch/storage.pyRepository: vouchdev/vouch
Length of output: 12252
route bootstrap writes through proposals.approve()
src/vouch/cli.py:200-203 — seed_starter_kb() writes sources, claims, and pages directly via store.put_*(), so vouch init bypasses the review gate. keep bootstrap writes on the approved proposal path.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/vouch/cli.py` around lines 200 - 203, Update the bootstrap flow in the
CLI around seed_starter_kb and template generation so all initial sources,
claims, and pages are submitted and written through proposals.approve() rather
than direct store.put_* calls. Reuse the existing approved-proposal path for
both the starter knowledge base and non-default template while preserving the
current approved_by identity.
Sources: Coding guidelines, Path instructions
coderabbit review on #517. a failure after .vouch/ became discoverable (seed, index rebuild, audit) used to strand a half-created kb that made every rerun skip bootstrap — the original silent-no-op bug reborn. install-mcp now rmtrees the partial .vouch/ it just created before surfacing the error (safe: discover_root had just confirmed it did not exist), pinned by a test that fails the index rebuild and asserts the rerun bootstraps from scratch. the --no-init warning also stops overclaiming: with VOUCH_KB_PATH exported at runtime the hooks would use the override, so the wording now scopes the "will do nothing" claim to the no-override case.
|
@coderabbitai fixed in 3f5bb7a: install-mcp now removes the partial on the seeding finding: same position as on #516 — |
|
Tip For best results, initiate chat on the files or code changes.
Understood on starter seeding: it remains the existing, human-triggered 🐇 ✅ ✏️ Learnings added
If you found this review helpful, would you consider giving us a shout-out on X? Thank you for using CodeRabbit! |
1 participant
promotes
testtomainand prepares the 1.4.0 release: version bumped in all four sites (pyproject.toml, openclaw.plugin.json, package.json, src/vouch/init.py — the parity test ties them), changelog section dated 2026-07-17.headline change since 1.3.0:
vouch install-mcp <host>is a one-command setup — it bootstraps the kb when no.vouch/is discoverable (#516), with the staging-host exemption (kb_bootstrap: falsefor claude-desktop), env-override-proof preflight, and clean failure paths. also promotes the coderabbit merge-gate + pr-bot hardening (#508, #514) and the stop-hook answer capture that was in the tree but missing from the 1.3.0 wheel.after merge: tag
v1.4.0on main and release.yml publishes vouch-kb to pypi via trusted publishing; the github release gets the changelog section as its body.full gate green on this branch: pytest (excl. embeddings), mypy 99 files, ruff, and the openclaw manifest version-parity test;
vouch --versionself-reports 1.4.0 (the 1.2.0 regression class).🤖 Generated with Claude Code
Summary by CodeRabbit
vouch install-mcp <host>now bootstraps a missing knowledge base automatically; use--no-initto skip.