Local-first π§ memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly π΄ dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
feat: add lifecycle uninstall helper and update/remove docs (v0.4.1)
Sol Aitken5fb86c95b560
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex c4129654..467d20cf 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.4.0",+ "version": "0.4.1","description": "Plugin-first second brain package for AI agents and humans.","author": "Open Second Brain contributors","license": "MIT",@@ -50,6 +50,12 @@"command": "scripts/o2b","args": ["mcp"]},+ {+ "name": "uninstall",+ "description": "Print an uninstall plan; --apply-local removes only the machine-local config directory.",+ "command": "scripts/o2b",+ "args": ["uninstall"]+ },{"name": "vault-log","description": "Compatibility wrapper for appending event log entries.",diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.jsonindex 874d62ea..c7586d56 100644--- a/.codex-plugin/plugin.json+++ b/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.4.0",+ "version": "0.4.1","description": "Plugin-first second brain package for Codex, Hermes, Claude Code, and other agent runtimes.","skills": "./skills","keywords": ["second-brain", "obsidian", "agents", "skills", "event-log", "mcp"]diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3f08d74e..533a234d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+## [0.4.1] - 2026-05-06++### Added++- `o2b uninstall` CLI helper that prints a read-only uninstall plan, including+ the exact Hermes commands the user must run (`hermes mcp remove`,+ `hermes plugins remove`, `hermes gateway restart`) and the location of the+ machine-local config directory.+- `--apply-local` flag for `o2b uninstall` that may remove the machine-local+ config directory only (`~/.config/open-second-brain` or the parent of+ `$OPEN_SECOND_BRAIN_CONFIG`). Refuses to act on directories whose name is+ not a recognized Open Second Brain config dir, paths inside Hermes-owned+ trees, or directories that look like git repositories.+- `after-install.md` at the repository root so Hermes can show post-install+ guidance (init, MCP registration, update, uninstall) right after+ `hermes plugins install`.+- `uninstall` command entry in the Claude Code plugin manifest.+- README now documents an explicit Hermes CLI form for MCP registration+ (`hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault`)+ and adds dedicated **Updating** and **Uninstalling** sections that spell+ out the Hermes-owned vs. machine-local layers.+- `docs/mcp.md` now covers updating and removing the MCP registration, and+ warns against passing `--args` as a single quoted string.+- Dedicated `tests/test_uninstall.py` covering dry-run safety, vault and+ Hermes config preservation, the `--apply-local` allow-list, the+ `OPEN_SECOND_BRAIN_CONFIG` env override, and the help text invariants.++### Changed++- Bumped package, plugin, and Claude/Codex manifest versions to 0.4.1.++### Migration / Uninstall notes++- `o2b uninstall` is read-only by default. It **never** edits+ `~/.hermes/config.yaml`, removes the installed plugin directory, or+ touches the vault β including `Daily/`, `AI Wiki/`, or any Markdown.+- To deregister the MCP server and remove the plugin run the Hermes+ commands yourself (`hermes mcp remove open-second-brain`,+ `hermes plugins remove open-second-brain`, `hermes gateway restart`).+- `o2b uninstall --apply-local` only removes the machine-local+ Open Second Brain config directory; it refuses to delete anything else.+- Existing users do not need to re-register the MCP server after upgrading+ to 0.4.1; the plugin update flow keeps `~/.hermes/config.yaml` untouched.+## [0.4.0] - 2026-05-06### Added@@ -48,7 +92,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Sandbox vault and plugin manifest fixtures for tests.- GitHub release workflow for tag-based and manually dispatched releases.-[unreleased]: https://github.com/itechmeat/open-second-brain/compare/v0.4.0...HEAD+[unreleased]: https://github.com/itechmeat/open-second-brain/compare/v0.4.1...HEAD+[0.4.1]: https://github.com/itechmeat/open-second-brain/compare/v0.4.0...v0.4.1[0.4.0]: https://github.com/itechmeat/open-second-brain/compare/v0.3.1...v0.4.0[0.3.1]: https://github.com/itechmeat/open-second-brain/compare/v0.3.0...v0.3.1[0.3.0]: https://github.com/itechmeat/open-second-brain/releases/tag/v0.3.0diff --git a/README.md b/README.mdindex defadb37..faa4b250 100644--- a/README.md+++ b/README.md@@ -76,6 +76,7 @@ o2b append-event Append one daily event-log entryo2b index Rebuild the Markdown page indexo2b export-config Write a redacted config snapshoto2b mcp Run the optional MCP tool server (stdio)+o2b uninstall Print an uninstall plan; --apply-local removes only local configvault-log Compatibility wrapper around append-event```@@ -83,7 +84,13 @@ The local checkout can be used without installing the Python package. Run comman## Optional MCP tool server-OpenSecondBrain ships an optional Model Context Protocol server that exposes the same deterministic operations as MCP tools. Hermes Agent discovers it through `~/.hermes/config.yaml`:+OpenSecondBrain ships an optional Model Context Protocol server that exposes the same deterministic operations as MCP tools. Register it through Hermes from the CLI:++```bash+hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault+```++Or edit `~/.hermes/config.yaml` directly:```yamlmcp_servers:@@ -94,6 +101,56 @@ mcp_servers:Tools: `second_brain_status`, `second_brain_query`, `second_brain_capture`, `event_log_append`, `vault_health`. See `docs/mcp.md` for full setup, tool schemas, and Claude Code/Codex notes. The CLI remains the supported baseline; the MCP server is opt-in.+## Updating++OpenSecondBrain follows the standard Hermes plugin update flow.++```bash+hermes plugins update open-second-brain+hermes gateway restart+```++`hermes plugins update` runs `git pull` inside the installed plugin directory; it does not rewrite your `~/.hermes/config.yaml` MCP registration. After an update:++- The `o2b` CLI is upgraded automatically.+- The MCP entrypoint stays registered, so no `hermes mcp add` is needed for an in-place upgrade.+- Restart the gateway (or open a fresh Hermes session) so cached plugin metadata and the MCP subprocess are reloaded.+- Run `o2b doctor --vault /path/to/vault --repo .` to confirm the new manifest still validates.++The `version` field in `plugin.yaml` is informational β Hermes installs whatever the current `main` branch contains. Pin to a specific release by checking out a tag inside the plugin directory if you want stricter control.++## Uninstalling++OpenSecondBrain treats your vault as the source of truth and never removes Markdown notes, `Daily/`, or `AI Wiki/`. Uninstalling has three independent layers; do them in this order.++1. Print a plan and review the leftovers (read-only):++ ```bash+ o2b uninstall+ ```++ The plan tells you which Hermes commands to run yourself, where the machine-local config directory lives, and reminds you that the vault is untouched. The dry-run never modifies the filesystem.++2. Deregister the MCP server and remove the Hermes plugin (Hermes-owned state):++ ```bash+ hermes mcp remove open-second-brain+ hermes plugins remove open-second-brain+ hermes gateway restart+ ```++ `hermes mcp remove` deletes the MCP registration and any OAuth tokens. `hermes plugins remove` deletes only the installed plugin directory. OpenSecondBrain itself never edits `~/.hermes/config.yaml` β these commands are run by you against Hermes.++3. Optionally remove the machine-local config directory (typically `~/.config/open-second-brain` or `$OPEN_SECOND_BRAIN_CONFIG`'s parent):++ ```bash+ o2b uninstall --apply-local+ ```++ `--apply-local` only removes that one config directory. It refuses to act if the directory name is not a recognized Open Second Brain config dir, if it lives inside a Hermes-owned path, or if it looks like a git repository. It never touches the vault, Hermes config, or anything else.++To delete the vault you must do that yourself with normal filesystem tools β OpenSecondBrain will not do it for you, even with `--apply-local`.+## Safety model- Your notes stay as plain Markdown.diff --git a/after-install.md b/after-install.mdnew file mode 100644index 00000000..ac49d471--- /dev/null+++ b/after-install.md@@ -0,0 +1,79 @@+# Open Second Brain β after install++Thanks for installing Open Second Brain. The plugin is now on disk; finish+the setup with the steps below.++## 1. Initialise a vault++Pick (or create) the Obsidian-compatible folder you want as your second+brain, then bootstrap the agent-owned files:++```bash+o2b init --vault /path/to/vault --name "My Second Brain"+o2b doctor --vault /path/to/vault --repo .+```++`o2b doctor` should print `[OK]` for every check.++## 2. Register the MCP server (optional but recommended)++Open Second Brain ships an optional stdio MCP server. Register it with+Hermes so the deterministic tools are routable:++```bash+hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault+hermes gateway restart+```++`--args` is a single flag whose value is the remaining tokens on the line+(here: `mcp --vault /path/to/vault`). Hermes hands those tokens to the MCP+server's command line as-is β do not wrap them in one quoted string like+`--args 'mcp --vault /path/to/vault'`, and do not repeat `--args` per token.+Edit `~/.hermes/config.yaml` instead if you prefer YAML.++The CLI works on its own; the MCP server is opt-in. See `docs/mcp.md` for+tool schemas, per-tool arguments, and Claude Code / Codex notes.++## 3. Updating++```bash+hermes plugins update open-second-brain+hermes gateway restart+```++`hermes plugins update` runs `git pull` inside the plugin directory. Your+MCP registration in `~/.hermes/config.yaml` is preserved across updates.++## 4. Uninstalling++Run a dry-run first to see exactly what will happen and which Hermes+commands you need to run:++```bash+o2b uninstall+```++Then deregister the MCP server and remove the plugin (Hermes-owned state):++```bash+hermes mcp remove open-second-brain+hermes plugins remove open-second-brain+hermes gateway restart+```++Optional: remove the machine-local config directory only:++```bash+o2b uninstall --apply-local+```++`--apply-local` only touches `~/.config/open-second-brain` (or the parent+of `$OPEN_SECOND_BRAIN_CONFIG`). Your vault, `Daily/`, `AI Wiki/`, and+Markdown notes are never removed by Open Second Brain β delete them+yourself with normal filesystem tools if that is what you want.++## More++- `README.md` β full feature description and CLI reference.+- `docs/mcp.md` β MCP tool server, registration, update/remove flows.+- `docs/architecture.md` β config model, vault layout, security rules.diff --git a/docs/mcp.md b/docs/mcp.mdindex 9ac92686..cfc7b920 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -53,7 +53,21 @@ The server logs its banner to `stderr` and only writes JSON-RPC frames toHermes discovers MCP servers from `~/.hermes/config.yaml` under the`mcp_servers` key. After installing this plugin, register the MCP server on-the same machine that hosts the vault:+the same machine that hosts the vault.++The Hermes CLI accepts the registration directly:++```bash+hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault+```++`--args` is a single flag; everything after it on the line (here+`mcp --vault /path/to/vault`) is collected as the argument list and forwarded+to the MCP server's command line. Do not wrap those tokens in a single+quoted string like `--args 'mcp --vault /path'` (Hermes would treat the whole+thing as one argument), and do not repeat `--args` per token.++You can also edit `~/.hermes/config.yaml` by hand:```yamlmcp_servers:@@ -88,6 +102,53 @@ The Hermes plugin manifest (`plugin.yaml`) advertises this MCP entrypoint viathe `mcp_server` field so future Hermes releases can auto-register the server,but the official Hermes config flow is the source of truth today.+## Updating the MCP registration++Updating the plugin via `hermes plugins update open-second-brain` does not+rewrite `~/.hermes/config.yaml`. Your existing `mcp_servers.open-second-brain`+entry keeps working as long as the `command` and `args` you originally+registered still resolve.++After an update:++- Restart the gateway so the MCP subprocess is reloaded:++ ```bash+ hermes gateway restart+ ```++- If the new release adds a flag, re-add the registration with the updated+ `--args` list (or edit the YAML by hand):++ ```bash+ hermes mcp remove open-second-brain+ hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault+ ```++`scripts/o2b mcp --vault /path/to/vault` from the checkout can be used to+sanity-check the server before re-registering it.++## Removing the MCP registration++To remove just the MCP server without uninstalling the plugin, run:++```bash+hermes mcp remove open-second-brain+hermes gateway restart+```++`hermes mcp remove` deletes the registration entry. Open Second Brain runs+over stdio (JSON-RPC 2.0) and does not use OAuth, so there are no tokens for+this server specifically; the OAuth-token cleanup `hermes mcp remove` performs+only matters for transports that authenticate that way. The installed plugin+and its CLI commands stay in place, so `hermes plugins update` will continue+to track new releases.++To remove both the MCP server and the plugin itself, follow the+`Uninstalling` section in the project README. Open Second Brain never edits+`~/.hermes/config.yaml` on your behalf, and `o2b uninstall` is a read-only+helper that prints the exact Hermes commands to run.+## Claude Code and CodexThe Claude Code plugin manifest exposes `o2b mcp` as a regular command thatdiff --git a/plugin.yaml b/plugin.yamlindex a53e7c85..3d090152 100644--- a/plugin.yaml+++ b/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "0.4.0"+version: "0.4.1"description: "Hermes plugin entrypoint for OpenSecondBrain vault health checks and the optional MCP tool server."author: "OpenSecondBrain contributors"kind: standalonediff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yamlindex 5876479c..96e2afa2 100644--- a/plugins/hermes/plugin.yaml+++ b/plugins/hermes/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "0.4.0"+version: "0.4.1"description: "Hermes adapter for OpenSecondBrain vault health checks and optional MCP tool server."author: "OpenSecondBrain contributors"kind: standalonediff --git a/pyproject.toml b/pyproject.tomlindex 500b12cb..0081bcef 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"[project]name = "open-second-brain"-version = "0.4.0"+version = "0.4.1"description = "Hermes-first second brain package for Obsidian-compatible Markdown vaults."readme = "README.md"requires-python = ">=3.11"diff --git a/src/open_second_brain/__init__.py b/src/open_second_brain/__init__.pyindex 2c472b92..1023395c 100644--- a/src/open_second_brain/__init__.py+++ b/src/open_second_brain/__init__.py@@ -1,3 +1,3 @@"""Open Second Brain core package."""-__version__ = "0.4.0"+__version__ = "0.4.1"diff --git a/src/open_second_brain/cli.py b/src/open_second_brain/cli.pyindex 4fb8141f..ed6f8b47 100644--- a/src/open_second_brain/cli.py+++ b/src/open_second_brain/cli.py@@ -11,6 +11,7 @@ from open_second_brain.doctor import doctorfrom open_second_brain.event_log import append_eventfrom open_second_brain.init import bootstrap_vaultfrom open_second_brain.mcp import run_cli_command as run_mcp_server+from open_second_brain.uninstall import plan_uninstall, render_planfrom open_second_brain.vault import list_vault_pages, write_frontmatter@@ -57,6 +58,28 @@ def build_parser() -> argparse.ArgumentParser:mcp_cmd.add_argument("--config", type=Path, default=None, help="Config file path")mcp_cmd.add_argument("--repo", type=Path, default=None, help="Repository root for plugin checks")+ uninstall_cmd = subcommands.add_parser(+ "uninstall",+ help="Print an uninstall plan and (optionally) clean local config",+ description=(+ "Read-only by default. Prints the Hermes commands you must run yourself "+ "(this tool never touches ~/.hermes/config.yaml or the installed plugin). "+ "With --apply-local it may remove the machine-local Open Second Brain "+ "config directory only. Your vault, Daily/, AI Wiki/, and Markdown notes "+ "are never removed."+ ),+ )+ uninstall_cmd.add_argument("--config", type=Path, default=None, help="Config file path")+ uninstall_cmd.add_argument(+ "--apply-local",+ action="store_true",+ help=(+ "Remove the machine-local Open Second Brain config directory "+ "(typically ~/.config/open-second-brain). Hermes config and the vault "+ "are never touched."+ ),+ )+return parser@@ -179,6 +202,15 @@ def command_mcp(args: argparse.Namespace) -> int:return 0+def command_uninstall(args: argparse.Namespace) -> int:+ config = args.config or default_config_path()+ plan = plan_uninstall(config_path=config, apply_local=args.apply_local)+ sys.stdout.write(render_plan(plan))+ if plan.errors:+ return 1+ return 0++def main(argv: list[str] | None = None) -> int:parser = build_parser()args = parser.parse_args(argv)@@ -196,6 +228,8 @@ def main(argv: list[str] | None = None) -> int:return command_index(args)if args.command == "mcp":return command_mcp(args)+ if args.command == "uninstall":+ return command_uninstall(args)raise AssertionError(f"unhandled command: {args.command}")diff --git a/src/open_second_brain/mcp.py b/src/open_second_brain/mcp.pyindex ca94fe09..173b6422 100644--- a/src/open_second_brain/mcp.py+++ b/src/open_second_brain/mcp.py@@ -29,7 +29,7 @@ from open_second_brain.vault import list_vault_pages, parse_frontmatter, write_fPROTOCOL_VERSION = "2025-06-18"SERVER_NAME = "open-second-brain"-SERVER_VERSION = "0.4.0"+SERVER_VERSION = "0.4.1"JSONRPC_VERSION = "2.0"# JSON-RPC 2.0 error codes used by the MCP server.diff --git a/src/open_second_brain/uninstall.py b/src/open_second_brain/uninstall.pynew file mode 100644index 00000000..3a85e99a--- /dev/null+++ b/src/open_second_brain/uninstall.py@@ -0,0 +1,211 @@+"""Read-only uninstall planner for Open Second Brain.++The uninstall helper does NOT manage the Hermes plugin install or+MCP registration; those are owned by Hermes. It also never touches the+user's vault. By default it is a dry-run that prints the plan and the+exact Hermes commands the user should run themselves.++When invoked with ``--apply-local`` it may delete the machine-local+Open Second Brain config directory (typically ``~/.config/open-second-brain``).+Anything outside that single directory is left untouched.+"""++from __future__ import annotations++import shutil+from dataclasses import dataclass, field+from pathlib import Path+from typing import Iterable++from open_second_brain.config import discover_config++PLUGIN_NAME = "open-second-brain"++HERMES_COMMANDS: tuple[str, ...] = (+ f"hermes mcp remove {PLUGIN_NAME}",+ f"hermes plugins remove {PLUGIN_NAME}",+ "hermes gateway restart",+)++SAFE_CONFIG_DIR_NAMES: frozenset[str] = frozenset({"open-second-brain", "open_second_brain"})+++@dataclass(frozen=True)+class UninstallPlan:+ """Computed plan for an uninstall invocation."""++ config_path: Path+ config_exists: bool+ config_dir: Path+ config_dir_exists: bool+ config_dir_entries: tuple[Path, ...]+ vault_path: Path | None+ apply_local: bool+ hermes_commands: tuple[str, ...] = HERMES_COMMANDS+ removed_paths: tuple[Path, ...] = field(default_factory=tuple)+ skipped_paths: tuple[tuple[Path, str], ...] = field(default_factory=tuple)+ errors: tuple[tuple[Path, str], ...] = field(default_factory=tuple)+++def _is_safe_local_config_dir(target: Path) -> tuple[bool, str]:+ """Return ``(safe, reason)`` for ``target`` as a deletion candidate.++ Only a directory whose final name is one of the well-known Open Second+ Brain config dir names is eligible. The directory must also live outside+ any Hermes config tree to keep us strictly off Hermes-owned state.+ """++ if target.name not in SAFE_CONFIG_DIR_NAMES:+ return False, (+ f"directory name '{target.name}' is not a recognized Open Second Brain "+ "config directory; refusing to remove"+ )++ parts_lower = {part.lower() for part in target.parts}+ if ".hermes" in parts_lower or "hermes" in parts_lower:+ return False, "config directory is inside a Hermes-owned path; refusing to remove"++ if (target / ".git").exists():+ return False, "config directory looks like a git repository; refusing to remove"++ return True, ""+++def _vault_path_from_config(data: dict[str, str]) -> Path | None:+ for key in ("vault_path", "vault", "vault_dir", "path"):+ value = data.get(key)+ if value:+ return Path(value).expanduser()+ return None+++def _list_entries(directory: Path) -> tuple[Path, ...]:+ if not directory.is_dir():+ return ()+ try:+ return tuple(sorted(directory.iterdir()))+ except OSError:+ return ()+++def plan_uninstall(+ *,+ config_path: Path,+ apply_local: bool = False,+) -> UninstallPlan:+ """Compute (and optionally apply-local) an uninstall plan.++ The plan never modifies the Hermes config, the installed plugin+ directory, or the user's vault. With ``apply_local=True`` it may+ remove the machine-local config directory if and only if it passes+ :func:`_is_safe_local_config_dir`.+ """++ discovery = discover_config(config_path)+ cfg_dir = discovery.path.parent+ cfg_dir_exists = cfg_dir.is_dir()+ entries = _list_entries(cfg_dir)+ vault_path = _vault_path_from_config(discovery.data)++ removed: list[Path] = []+ skipped: list[tuple[Path, str]] = []+ errors: list[tuple[Path, str]] = []++ if apply_local:+ if not cfg_dir_exists:+ skipped.append((cfg_dir, "config directory does not exist"))+ else:+ safe, reason = _is_safe_local_config_dir(cfg_dir)+ if not safe:+ skipped.append((cfg_dir, reason))+ else:+ try:+ shutil.rmtree(cfg_dir)+ removed.append(cfg_dir)+ except OSError as exc:+ errors.append((cfg_dir, str(exc)))++ return UninstallPlan(+ config_path=discovery.path,+ config_exists=discovery.exists,+ config_dir=cfg_dir,+ config_dir_exists=cfg_dir_exists,+ config_dir_entries=entries,+ vault_path=vault_path,+ apply_local=apply_local,+ removed_paths=tuple(removed),+ skipped_paths=tuple(skipped),+ errors=tuple(errors),+ )+++def render_plan(plan: UninstallPlan) -> str:+ """Render an :class:`UninstallPlan` as plain text for the CLI."""++ lines: list[str] = []+ title = "Open Second Brain β Uninstall plan"+ lines.append(title)+ lines.append("=" * len(title))+ lines.append("")++ mode = "apply-local (machine-local config directory may be removed)" if plan.apply_local else "dry-run (read-only)"+ lines.append(f"Mode: {mode}")+ lines.append("")++ lines.append("Local config:")+ config_state = "exists" if plan.config_exists else "missing"+ lines.append(f" config file: {plan.config_path} ({config_state})")+ if plan.config_dir_exists:+ entry_count = len(plan.config_dir_entries)+ lines.append(f" config dir: {plan.config_dir} ({entry_count} entr{'y' if entry_count == 1 else 'ies'})")+ for entry in plan.config_dir_entries:+ suffix = "/" if entry.is_dir() else ""+ lines.append(f" - {entry.name}{suffix}")+ else:+ lines.append(f" config dir: {plan.config_dir} (missing)")+ lines.append("")++ lines.append("Hermes integration (run these yourself; this tool will not):")+ for cmd in plan.hermes_commands:+ lines.append(f" $ {cmd}")+ lines.append("")+ lines.append(" Hermes owns plugin installation and MCP registration. Open Second")+ lines.append(" Brain never edits ~/.hermes/config.yaml on your behalf.")+ lines.append("")++ lines.append("Vault (NEVER removed by this tool):")+ if plan.vault_path is not None:+ lines.append(f" {plan.vault_path}")+ else:+ lines.append(" (no vault path recorded in config; check your runtime settings)")+ lines.append(" Your Markdown notes, Daily/, and AI Wiki/ stay exactly as they are.")+ lines.append("")++ if plan.apply_local:+ lines.append("Apply-local results:")+ if plan.removed_paths:+ for path in plan.removed_paths:+ lines.append(f" removed: {path}")+ if plan.skipped_paths:+ for path, reason in plan.skipped_paths:+ lines.append(f" skipped: {path} β {reason}")+ if plan.errors:+ for path, reason in plan.errors:+ lines.append(f" error: {path} β {reason}")+ if not (plan.removed_paths or plan.skipped_paths or plan.errors):+ lines.append(" (nothing to do)")+ lines.append("")+ else:+ lines.append("Next steps:")+ lines.append(" 1. Run the Hermes commands above to deregister the MCP server and plugin.")+ lines.append(" 2. Re-run with --apply-local to remove the machine-local config directory.")+ lines.append(" 3. Delete the vault yourself if and only if you really want to lose your notes.")+ lines.append("")++ return "\n".join(lines).rstrip() + "\n"+++def iter_hermes_commands() -> Iterable[str]:+ """Public iterator over the Hermes commands the user should run."""++ return iter(HERMES_COMMANDS)diff --git a/tests/test_uninstall.py b/tests/test_uninstall.pynew file mode 100644index 00000000..ccd41b09--- /dev/null+++ b/tests/test_uninstall.py@@ -0,0 +1,328 @@+import os+import re+import sys+import tempfile+import textwrap+import unittest+from pathlib import Path++ROOT = Path(__file__).resolve().parents[1]+sys.path.insert(0, str(ROOT / "src"))++from open_second_brain.uninstall import (+ HERMES_COMMANDS,+ PLUGIN_NAME,+ SAFE_CONFIG_DIR_NAMES,+ plan_uninstall,+ render_plan,+)+from tests.test_cli import run_cli+++class HermesCommandsTests(unittest.TestCase):+ def test_hermes_commands_match_documented_form(self):+ self.assertEqual(+ HERMES_COMMANDS,+ (+ f"hermes mcp remove {PLUGIN_NAME}",+ f"hermes plugins remove {PLUGIN_NAME}",+ "hermes gateway restart",+ ),+ )++ def test_hermes_commands_do_not_use_quoted_args_blob(self):+ for cmd in HERMES_COMMANDS:+ self.assertNotIn("'", cmd)+ self.assertNotIn('"', cmd)+ self.assertNotIn("--args ", cmd)+++class PlanUninstallTests(unittest.TestCase):+ def test_dry_run_does_not_remove_config_directory(self):+ with tempfile.TemporaryDirectory() as tmp:+ config_dir = Path(tmp) / "open-second-brain"+ config_dir.mkdir()+ config = config_dir / "config.yaml"+ config.write_text("vault_path: /vault/example\n", encoding="utf-8")+ other = config_dir / "snapshot.json"+ other.write_text("{}", encoding="utf-8")++ plan = plan_uninstall(config_path=config, apply_local=False)++ self.assertFalse(plan.apply_local)+ self.assertTrue(config.exists())+ self.assertTrue(other.exists())+ self.assertTrue(config_dir.is_dir())+ self.assertEqual(plan.removed_paths, ())+ self.assertEqual(plan.skipped_paths, ())+ self.assertEqual(plan.config_dir, config_dir)+ self.assertTrue(plan.config_dir_exists)+ self.assertEqual(plan.vault_path, Path("/vault/example"))++ def test_dry_run_records_missing_config(self):+ with tempfile.TemporaryDirectory() as tmp:+ config = Path(tmp) / "open-second-brain" / "missing.yaml"++ plan = plan_uninstall(config_path=config, apply_local=False)++ self.assertFalse(plan.config_exists)+ self.assertFalse(plan.config_dir_exists)+ self.assertEqual(plan.removed_paths, ())++ def test_apply_local_removes_only_named_config_directory(self):+ with tempfile.TemporaryDirectory() as tmp:+ config_dir = Path(tmp) / "open-second-brain"+ config_dir.mkdir()+ (config_dir / "config.yaml").write_text("instance: x\n", encoding="utf-8")+ (config_dir / "snapshots").mkdir()+ (config_dir / "snapshots" / "old.json").write_text("{}", encoding="utf-8")++ plan = plan_uninstall(config_path=config_dir / "config.yaml", apply_local=True)++ self.assertTrue(plan.apply_local)+ self.assertFalse(config_dir.exists())+ self.assertEqual(plan.removed_paths, (config_dir,))+ self.assertEqual(plan.skipped_paths, ())+ self.assertEqual(plan.errors, ())++ def test_apply_local_refuses_unknown_directory_name(self):+ with tempfile.TemporaryDirectory() as tmp:+ config_dir = Path(tmp) / "etc"+ config_dir.mkdir()+ payload = config_dir / "important.yaml"+ payload.write_text("vault_path: /vault\n", encoding="utf-8")++ plan = plan_uninstall(config_path=payload, apply_local=True)++ self.assertTrue(config_dir.exists())+ self.assertTrue(payload.exists())+ self.assertEqual(plan.removed_paths, ())+ self.assertEqual(len(plan.skipped_paths), 1)+ skipped_path, reason = plan.skipped_paths[0]+ self.assertEqual(skipped_path, config_dir)+ self.assertIn("not a recognized", reason)++ def test_apply_local_refuses_paths_inside_hermes(self):+ with tempfile.TemporaryDirectory() as tmp:+ hermes_root = Path(tmp) / ".hermes"+ config_dir = hermes_root / "open-second-brain"+ config_dir.mkdir(parents=True)+ payload = config_dir / "config.yaml"+ payload.write_text("vault_path: /vault\n", encoding="utf-8")++ plan = plan_uninstall(config_path=payload, apply_local=True)++ self.assertTrue(config_dir.exists())+ self.assertTrue(payload.exists())+ self.assertEqual(plan.removed_paths, ())+ self.assertEqual(len(plan.skipped_paths), 1)+ _, reason = plan.skipped_paths[0]+ self.assertIn("Hermes", reason)++ def test_apply_local_refuses_git_repository(self):+ with tempfile.TemporaryDirectory() as tmp:+ config_dir = Path(tmp) / "open-second-brain"+ config_dir.mkdir()+ (config_dir / ".git").mkdir()+ payload = config_dir / "config.yaml"+ payload.write_text("instance: x\n", encoding="utf-8")++ plan = plan_uninstall(config_path=payload, apply_local=True)++ self.assertTrue(config_dir.exists())+ self.assertEqual(plan.removed_paths, ())+ self.assertEqual(len(plan.skipped_paths), 1)+ _, reason = plan.skipped_paths[0]+ self.assertIn("git", reason)++ def test_apply_local_skips_when_config_dir_missing(self):+ with tempfile.TemporaryDirectory() as tmp:+ payload = Path(tmp) / "open-second-brain" / "config.yaml"++ plan = plan_uninstall(config_path=payload, apply_local=True)++ self.assertEqual(plan.removed_paths, ())+ self.assertEqual(len(plan.skipped_paths), 1)+ _, reason = plan.skipped_paths[0]+ self.assertIn("does not exist", reason)+++class VaultSafetyTests(unittest.TestCase):+ def test_apply_local_never_touches_vault(self):+ with tempfile.TemporaryDirectory() as tmp:+ tmp_path = Path(tmp)+ vault = tmp_path / "vault"+ (vault / "AI Wiki").mkdir(parents=True)+ (vault / "Daily").mkdir(parents=True)+ (vault / "AI Wiki" / "page.md").write_text("# Page\n", encoding="utf-8")+ (vault / "Daily" / "2026.05.06.md").write_text("# Daily\n", encoding="utf-8")++ config_dir = tmp_path / "open-second-brain"+ config_dir.mkdir()+ config = config_dir / "config.yaml"+ config.write_text(f"vault_path: {vault}\n", encoding="utf-8")++ plan_uninstall(config_path=config, apply_local=True)++ self.assertTrue(vault.is_dir())+ self.assertTrue((vault / "AI Wiki" / "page.md").is_file())+ self.assertTrue((vault / "Daily" / "2026.05.06.md").is_file())++ def test_apply_local_never_touches_hermes_config_file(self):+ with tempfile.TemporaryDirectory() as tmp:+ tmp_path = Path(tmp)+ hermes_dir = tmp_path / ".hermes"+ hermes_dir.mkdir()+ hermes_config = hermes_dir / "config.yaml"+ hermes_payload = textwrap.dedent(+ """+ mcp_servers:+ open-second-brain:+ command: o2b+ args: ["mcp", "--vault", "/vault"]+ """+ ).strip() + "\n"+ hermes_config.write_text(hermes_payload, encoding="utf-8")++ config_dir = tmp_path / "open-second-brain"+ config_dir.mkdir()+ config = config_dir / "config.yaml"+ config.write_text("vault_path: /vault\n", encoding="utf-8")++ plan_uninstall(config_path=config, apply_local=True)++ self.assertTrue(hermes_config.is_file())+ self.assertEqual(hermes_config.read_text(encoding="utf-8"), hermes_payload)+++class RenderPlanTests(unittest.TestCase):+ def _basic_plan(self, *, apply_local: bool, tmp_path: Path) -> str:+ config_dir = tmp_path / "open-second-brain"+ config_dir.mkdir()+ config = config_dir / "config.yaml"+ config.write_text("vault_path: /vault/here\n", encoding="utf-8")++ plan = plan_uninstall(config_path=config, apply_local=apply_local)+ return render_plan(plan)++ def test_rendered_plan_includes_hermes_commands(self):+ with tempfile.TemporaryDirectory() as tmp:+ text = self._basic_plan(apply_local=False, tmp_path=Path(tmp))+ for cmd in HERMES_COMMANDS:+ self.assertIn(cmd, text)++ def test_rendered_plan_states_vault_is_preserved(self):+ with tempfile.TemporaryDirectory() as tmp:+ text = self._basic_plan(apply_local=False, tmp_path=Path(tmp))+ self.assertRegex(text, r"Vault \(NEVER removed by this tool\)")+ self.assertIn("Daily/", text)+ self.assertIn("AI Wiki/", text)++ def test_rendered_plan_states_hermes_config_is_not_edited(self):+ with tempfile.TemporaryDirectory() as tmp:+ text = self._basic_plan(apply_local=False, tmp_path=Path(tmp))+ self.assertIn("~/.hermes/config.yaml", text)+ self.assertIn("never edits", text)++ def test_rendered_plan_marks_dry_run(self):+ with tempfile.TemporaryDirectory() as tmp:+ text = self._basic_plan(apply_local=False, tmp_path=Path(tmp))+ self.assertIn("dry-run", text)++ def test_rendered_plan_marks_apply_local(self):+ with tempfile.TemporaryDirectory() as tmp:+ text = self._basic_plan(apply_local=True, tmp_path=Path(tmp))+ self.assertIn("apply-local", text)+++class CliUninstallTests(unittest.TestCase):+ def test_cli_dry_run_does_not_modify_filesystem(self):+ with tempfile.TemporaryDirectory() as tmp:+ tmp_path = Path(tmp)+ config_dir = tmp_path / "open-second-brain"+ config_dir.mkdir()+ config = config_dir / "config.yaml"+ config.write_text("vault_path: /vault\n", encoding="utf-8")++ result = run_cli("uninstall", "--config", str(config))++ self.assertEqual(result.returncode, 0, result.stderr)+ self.assertIn("Uninstall plan", result.stdout)+ self.assertIn("dry-run", result.stdout)+ self.assertIn("hermes mcp remove open-second-brain", result.stdout)+ self.assertIn("hermes plugins remove open-second-brain", result.stdout)+ self.assertIn("hermes gateway restart", result.stdout)+ self.assertIn("NEVER removed by this tool", result.stdout)+ self.assertTrue(config.exists())+ self.assertTrue(config_dir.is_dir())++ def test_cli_apply_local_removes_only_local_config_dir(self):+ with tempfile.TemporaryDirectory() as tmp:+ tmp_path = Path(tmp)+ vault = tmp_path / "vault"+ (vault / "Daily").mkdir(parents=True)+ (vault / "Daily" / "2026.05.06.md").write_text("vault content", encoding="utf-8")++ config_dir = tmp_path / "open-second-brain"+ config_dir.mkdir()+ config = config_dir / "config.yaml"+ config.write_text(f"vault_path: {vault}\n", encoding="utf-8")++ result = run_cli("uninstall", "--config", str(config), "--apply-local")++ self.assertEqual(result.returncode, 0, result.stderr)+ self.assertIn("apply-local", result.stdout)+ self.assertFalse(config_dir.exists())+ self.assertTrue(vault.is_dir())+ self.assertTrue((vault / "Daily" / "2026.05.06.md").is_file())++ def test_cli_apply_local_refuses_when_config_dir_name_unknown(self):+ with tempfile.TemporaryDirectory() as tmp:+ tmp_path = Path(tmp)+ config_dir = tmp_path / "etc"+ config_dir.mkdir()+ (config_dir / "very-important.yaml").write_text("keep-me\n", encoding="utf-8")+ config = config_dir / "config.yaml"+ config.write_text("vault_path: /vault\n", encoding="utf-8")++ result = run_cli("uninstall", "--config", str(config), "--apply-local")++ self.assertEqual(result.returncode, 0, result.stderr)+ self.assertIn("skipped", result.stdout)+ self.assertTrue(config_dir.is_dir())+ self.assertTrue((config_dir / "very-important.yaml").is_file())++ def test_cli_uses_open_second_brain_config_env(self):+ with tempfile.TemporaryDirectory() as tmp:+ tmp_path = Path(tmp)+ config_dir = tmp_path / "open-second-brain"+ config_dir.mkdir()+ config = config_dir / "config.yaml"+ config.write_text("vault_path: /env/vault\n", encoding="utf-8")++ result = run_cli(+ "uninstall",+ env={"OPEN_SECOND_BRAIN_CONFIG": str(config)},+ )++ self.assertEqual(result.returncode, 0, result.stderr)+ self.assertIn(str(config), result.stdout)+ self.assertIn("/env/vault", result.stdout)++ def test_cli_help_documents_safety_invariants(self):+ result = run_cli("uninstall", "--help")+ self.assertEqual(result.returncode, 0, result.stderr)+ self.assertIn("never touches", result.stdout)+ self.assertIn("vault", result.stdout.lower())+++class SafeNamesTests(unittest.TestCase):+ def test_safe_names_only_contain_canonical_open_second_brain_names(self):+ self.assertEqual(+ SAFE_CONFIG_DIR_NAMES,+ frozenset({"open-second-brain", "open_second_brain"}),+ )+++if __name__ == "__main__":+ unittest.main()