Skip to content

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: rename CLI to o2b, add init and doctor commands (#3)

Sol Aitken2166f850e9c8
diff --git a/README.md b/README.md
index 83e2b487..5593f037 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,7 @@ open-second-brain/
agent-event-log/
SKILL.md
scripts/
- asb
+ o2b
vault-log
plugins/
hermes/
@@ -63,9 +63,9 @@ Open Second Brain is plugin-first, but not plugin-only.
Run the local CLI without installing the package:
```bash
-scripts/asb status
-scripts/asb append-event --vault /path/to/vault --as agent-name --date 2026.05.06 --time 10:15 "created first entry"
-scripts/asb export-config --config ~/.config/open-second-brain/config.yaml --output /tmp/open-second-brain-config.json
+scripts/o2b status
+scripts/o2b append-event --vault /path/to/vault --as agent-name --date 2026.05.06 --time 10:15 "created first entry"
+scripts/o2b export-config --config ~/.config/open-second-brain/config.yaml --output /tmp/open-second-brain-config.json
scripts/vault-log --vault /path/to/vault --as agent-name "compatibility event entry"
```
@@ -90,7 +90,7 @@ Run static syntax checks used by the initial PRs:
python3 -m json.tool .claude-plugin/plugin.json >/dev/null
python3 -m json.tool .codex-plugin/plugin.json >/dev/null
python3 -m py_compile plugins/hermes/__init__.py
-bash -n scripts/asb
+bash -n scripts/o2b
bash -n scripts/vault-log
```
diff --git a/docs/architecture.md b/docs/architecture.md
index 0dbe68b7..e18c8781 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -138,8 +138,8 @@ Open Second Brain should assume the vault is the primary portable backup unit.
Recommended behavior:
- vault-portable config is backed up with the vault;
-- machine-local config can be regenerated with `asb init --adopt-vault`;
-- `asb export-config` writes a redacted machine snapshot into the vault;
+- machine-local config can be regenerated with `o2b init --adopt-vault`;
+- `o2b export-config` writes a redacted machine snapshot into the vault;
- secrets are excluded and represented as `[REDACTED]` only when needed.
## Vault layout
diff --git a/docs/plans/2026-05-06-cli-foundation.md b/docs/plans/2026-05-06-cli-foundation.md
index 4b458e95..fd8525fd 100644
--- a/docs/plans/2026-05-06-cli-foundation.md
+++ b/docs/plans/2026-05-06-cli-foundation.md
@@ -4,7 +4,7 @@
**Goal:** Replace placeholder shell scripts with a tested Python CLI foundation for Open Second Brain.
-**Architecture:** The repository will expose a small Python package under `src/open_second_brain/`. The CLI entrypoint will be `open_second_brain.cli:main`, with the existing `scripts/asb` and `scripts/vault-log` shell wrappers delegating to Python modules. v0 keeps dependencies to the Python standard library.
+**Architecture:** The repository will expose a small Python package under `src/open_second_brain/`. The CLI entrypoint will be `open_second_brain.cli:main`, with the existing `scripts/o2b` and `scripts/vault-log` shell wrappers delegating to Python modules. v0 keeps dependencies to the Python standard library.
**Tech Stack:** Python 3.11+, argparse, unittest, pathlib, json, datetime, tempfile.
@@ -16,9 +16,9 @@
- Create `src/open_second_brain/__init__.py`: package version.
- Create `src/open_second_brain/config.py`: config path discovery and minimal redacted status model.
- Create `src/open_second_brain/event_log.py`: append-only daily Markdown event log backend.
-- Create `src/open_second_brain/cli.py`: `asb` CLI with `status`, `append-event`, and `export-config` commands.
+- Create `src/open_second_brain/cli.py`: `o2b` CLI with `status`, `init`, `doctor`, `append-event`, and `export-config` commands.
- Create `src/open_second_brain/vault_log.py`: compatibility CLI for `vault-log`.
-- Modify `scripts/asb`: shell wrapper that runs `python3 -m open_second_brain.cli` with local `src` on `PYTHONPATH`.
+- Modify `scripts/o2b`: shell wrapper that runs `python3 -m open_second_brain.cli` with local `src` on `PYTHONPATH`.
- Modify `scripts/vault-log`: shell wrapper that runs `python3 -m open_second_brain.vault_log` with local `src` on `PYTHONPATH`.
- Create `tests/test_config.py`: config path/status tests.
- Create `tests/test_event_log.py`: append-only daily Markdown backend tests.
@@ -53,7 +53,7 @@ keywords = ["second-brain", "obsidian", "agents", "skills", "event-log"]
dependencies = []
[project.scripts]
-asb = "open_second_brain.cli:main"
+o2b = "open_second_brain.cli:main"
vault-log = "open_second_brain.vault_log:main"
[tool.setuptools.packages.find]
@@ -290,13 +290,13 @@ git commit -m "feat: add daily markdown event log backend"
**Files:**
- Create: `src/open_second_brain/cli.py`
- Create: `src/open_second_brain/vault_log.py`
-- Modify: `scripts/asb`
+- Modify: `scripts/o2b`
- Modify: `scripts/vault-log`
- Create: `tests/test_cli.py`
- [ ] **Step 1: Write failing CLI tests**
-Test `asb status`, `asb append-event`, and `vault-log --as` using temporary vault directories.
+Test `o2b status`, `o2b init`, `o2b doctor`, `o2b append-event`, and `vault-log --as` using temporary vault directories.
- [ ] **Step 2: Run tests and verify failure**
@@ -335,7 +335,7 @@ Expected: OK.
- [ ] **Step 6: Commit**
```bash
-git add src/open_second_brain/cli.py src/open_second_brain/vault_log.py scripts/asb scripts/vault-log tests/test_cli.py
+git add src/open_second_brain/cli.py src/open_second_brain/vault_log.py scripts/o2b scripts/vault-log tests/test_cli.py
git commit -m "feat: add cli entrypoints"
```
@@ -358,7 +358,7 @@ PYTHONPATH=src python3 -m unittest discover -s tests -v
python3 -m json.tool .claude-plugin/plugin.json >/dev/null
python3 -m json.tool .codex-plugin/plugin.json >/dev/null
python3 -m py_compile plugins/hermes/__init__.py
-bash -n scripts/asb
+bash -n scripts/o2b
bash -n scripts/vault-log
```
@@ -394,4 +394,4 @@ Placeholder scan:
Type consistency:
- Config module names are consistent: `default_config_path`, `discover_config`, `redact_mapping`.
-- Event log command names are consistent: `asb append-event`, `vault-log --as`.
+- Event log command names are consistent: `o2b append-event`, `vault-log --as`.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 50425c7b..145c8228 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -18,34 +18,31 @@ Scope:
- no required MCP server;
- no automatic background writes.
-## v0.1: deterministic CLI
+## v0.1: deterministic CLI βœ…
-Implemented foundation:
+Implemented:
```text
-asb status
-asb export-config
-asb append-event
+o2b status
+o2b init
+o2b doctor
+o2b export-config
+o2b append-event
vault-log
```
-Current behavior:
+- `o2b status` β€” locate config and list known keys.
+- `o2b init` β€” bootstrap a vault profile with AI Wiki structure.
+- `o2b doctor` β€” run health checks on vault, config, and plugin manifests.
+- `o2b export-config` β€” write a redacted config snapshot.
+- `o2b append-event` β€” append an event to the daily Markdown backend.
+- `vault-log` β€” compatibility wrapper for existing vault-log users.
-- locate config through `OPEN_SECOND_BRAIN_CONFIG`, `XDG_CONFIG_HOME`, or the default user config path;
-- append event log entries to daily Markdown notes;
-- export redacted config snapshots;
-- keep the CLI dependency-free and testable with Python `unittest`.
+All commands are dependency-free and tested with Python `unittest` (34 tests).
-Still planned for this track:
+## v0.2: vault profile bootstrap βœ… (in-progress)
-```text
-asb init
-asb doctor
-```
-
-## v0.2: vault profile bootstrap
-
-Planned outputs:
+`o2b init` creates:
```text
AI Wiki/_OPEN_SECOND_BRAIN.md
@@ -57,6 +54,10 @@ AI Wiki/identity/user.md
AI Wiki/identity/agents.md
```
+Remaining v0.2 work:
+- vault-local operating manual (`_OPEN_SECOND_BRAIN.md`) to drive agent behavior;
+- query helpers for the wiki layer.
+
## v0.3: runtime polish
- Hermes plugin health checks;
diff --git a/pyproject.toml b/pyproject.toml
index 6ae408e4..15fa44d3 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -14,7 +14,7 @@ keywords = ["second-brain", "obsidian", "agents", "skills", "event-log"]
dependencies = []
[project.scripts]
-asb = "open_second_brain.cli:main"
+o2b = "open_second_brain.cli:main"
vault-log = "open_second_brain.vault_log:main"
[tool.setuptools.packages.find]
diff --git a/scripts/asb b/scripts/o2b
similarity index 100%
rename from scripts/asb
rename to scripts/o2b
diff --git a/skills/agent-event-log/SKILL.md b/skills/agent-event-log/SKILL.md
index cc7beab6..8579bf91 100644
--- a/skills/agent-event-log/SKILL.md
+++ b/skills/agent-event-log/SKILL.md
@@ -26,7 +26,7 @@ The compatibility command is `vault-log`.
Future Open Second Brain CLI commands may include:
```bash
-asb append-event --as <agent-name> "message"
+o2b append-event --as <agent-name> "message"
vault-log --as <agent-name> "message"
```
diff --git a/skills/open-second-brain/SKILL.md b/skills/open-second-brain/SKILL.md
index a572fb92..6565a3ab 100644
--- a/skills/open-second-brain/SKILL.md
+++ b/skills/open-second-brain/SKILL.md
@@ -24,7 +24,7 @@ In v0, Open Second Brain is expected to provide documentation, scripts, skills,
1. Check whether Open Second Brain is configured.
2. Read the machine-local config if available.
3. Read the vault-local operating manual if available.
-4. Use `vault-log` or `asb append-event` for event logging.
+4. Use `vault-log` or `o2b append-event` for event logging.
5. Use Markdown edits for durable synthesized knowledge only when the user asks or the configured policy allows it.
## Safety
diff --git a/src/open_second_brain/cli.py b/src/open_second_brain/cli.py
index 50f44ec1..6a72f6aa 100644
--- a/src/open_second_brain/cli.py
+++ b/src/open_second_brain/cli.py
@@ -3,19 +3,32 @@ from __future__ import annotations
import argparse
import json
import os
+import sys
from pathlib import Path
-from open_second_brain.config import discover_config, redact_mapping
+from open_second_brain.config import default_config_path, discover_config, redact_mapping
+from open_second_brain.doctor import doctor
from open_second_brain.event_log import append_event
+from open_second_brain.init import bootstrap_vault
def build_parser() -> argparse.ArgumentParser:
- parser = argparse.ArgumentParser(prog="asb", description="Open Second Brain CLI")
+ parser = argparse.ArgumentParser(prog="o2b", description="Open Second Brain CLI")
subcommands = parser.add_subparsers(dest="command", required=True)
status = subcommands.add_parser("status", help="Show Open Second Brain configuration status")
status.add_argument("--config", type=Path, default=None, help="Config file path")
+ init_cmd = subcommands.add_parser("init", help="Initialize a vault profile with required files")
+ init_cmd.add_argument("--vault", type=Path, required=True, help="Vault directory path")
+ init_cmd.add_argument("--name", default="Second Brain", help="Instance name (default: Second Brain)")
+ init_cmd.add_argument("--force", action="store_true", help="Overwrite existing files")
+
+ doctor_cmd = subcommands.add_parser("doctor", help="Run health checks on vault, config, and plugins")
+ doctor_cmd.add_argument("--vault", type=Path, default=None, help="Vault directory path")
+ doctor_cmd.add_argument("--config", type=Path, default=None, help="Config file path")
+ doctor_cmd.add_argument("--repo", type=Path, default=None, help="Repository root for plugin checks")
+
append = subcommands.add_parser("append-event", help="Append an event to the configured event log backend")
append.add_argument("message", help="Single-line event message")
append.add_argument("--vault", type=Path, default=None, help="Vault directory")
@@ -41,9 +54,49 @@ def command_status(args: argparse.Namespace) -> int:
return 0
+def command_init(args: argparse.Namespace) -> int:
+ vault = args.vault
+ try:
+ created = bootstrap_vault(vault, name=args.name, force=args.force)
+ except OSError as exc:
+ print(f"error: failed to initialize vault: {exc}", file=sys.stderr)
+ return 1
+ if not created:
+ print(f"vault already initialized: {vault}")
+ print("use --force to overwrite existing files")
+ return 0
+ print(f"initialized vault: {vault}")
+ for path in created:
+ print(f" created: {path}")
+ return 0
+
+
+def command_doctor(args: argparse.Namespace) -> int:
+ vault = args.vault or Path(os.environ.get("VAULT_DIR", "."))
+ config = args.config or default_config_path()
+ repo_root: Path | None = args.repo
+
+ try:
+ results = doctor(vault=vault, config=config, repo_root=repo_root)
+ except OSError as exc:
+ print(f"error: doctor failed: {exc}", file=sys.stderr)
+ return 1
+ all_ok = True
+ for r in results:
+ status = "OK" if r.ok else "FAIL"
+ print(f"[{status}] {r.name}: {r.message}")
+ if not r.ok:
+ all_ok = False
+ return 0 if all_ok else 1
+
+
def command_append_event(args: argparse.Namespace) -> int:
vault = args.vault or Path(os.environ.get("VAULT_DIR", "."))
- path = append_event(vault, args.agent, args.message, date=args.date, time=args.time)
+ try:
+ path = append_event(vault, args.agent, args.message, date=args.date, time=args.time)
+ except OSError as exc:
+ print(f"error: failed to append event: {exc}", file=sys.stderr)
+ return 1
print(f"appended: {path}")
return 0
@@ -55,8 +108,12 @@ def command_export_config(args: argparse.Namespace) -> int:
"config_exists": result.exists,
"config": redact_mapping(result.data),
}
- args.output.parent.mkdir(parents=True, exist_ok=True)
- args.output.write_text(json.dumps(snapshot, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ try:
+ args.output.parent.mkdir(parents=True, exist_ok=True)
+ args.output.write_text(json.dumps(snapshot, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ except OSError as exc:
+ print(f"error: failed to export config: {exc}", file=sys.stderr)
+ return 1
print(f"exported: {args.output}")
return 0
@@ -66,6 +123,10 @@ def main(argv: list[str] | None = None) -> int:
args = parser.parse_args(argv)
if args.command == "status":
return command_status(args)
+ if args.command == "init":
+ return command_init(args)
+ if args.command == "doctor":
+ return command_doctor(args)
if args.command == "append-event":
return command_append_event(args)
if args.command == "export-config":
diff --git a/src/open_second_brain/doctor.py b/src/open_second_brain/doctor.py
new file mode 100644
index 00000000..be94cd1d
--- /dev/null
+++ b/src/open_second_brain/doctor.py
@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class CheckResult:
+ name: str
+ ok: bool
+ message: str
+
+
+def check_vault_writeable(vault: Path) -> CheckResult:
+ if not vault.exists():
+ return CheckResult("vault_writeable", False, f"vault directory missing: {vault}")
+ test_path = vault / ".open-second-brain-doctor-test"
+ try:
+ test_path.touch()
+ test_path.unlink()
+ except OSError as exc:
+ return CheckResult("vault_writeable", False, f"cannot write to vault: {exc}")
+ return CheckResult("vault_writeable", True, f"vault exists and is writable: {vault}")
+
+
+def check_config_writeable(config: Path) -> CheckResult:
+ created_for_check = False
+ try:
+ config.parent.mkdir(parents=True, exist_ok=True)
+ if not config.exists():
+ created_for_check = True
+ with config.open("a", encoding="utf-8"):
+ pass
+ if created_for_check:
+ config.unlink()
+ except OSError as exc:
+ return CheckResult("config_writeable", False, f"cannot write config {config}: {exc}")
+ return CheckResult("config_writeable", True, f"config writable: {config}")
+
+
+def check_json_manifest(path: Path, description: str) -> CheckResult:
+ if not path.is_file():
+ return CheckResult(description, False, f"missing: {path}")
+ try:
+ json.loads(path.read_text(encoding="utf-8"))
+ except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+ return CheckResult(description, False, f"invalid JSON: {path} ({exc})")
+ return CheckResult(description, True, f"valid: {path}")
+
+
+def doctor(
+ *,
+ vault: Path,
+ config: Path | None = None,
+ repo_root: Path | None = None,
+) -> list[CheckResult]:
+ results: list[CheckResult] = []
+
+ # Vault checks
+ results.append(check_vault_writeable(vault))
+
+ # Config checks
+ if config is not None:
+ results.append(check_config_writeable(config))
+
+ # Plugin manifest checks (only if in repo context)
+ if repo_root is not None:
+ results.append(check_json_manifest(repo_root / ".claude-plugin" / "plugin.json", "claude_manifest"))
+ results.append(check_json_manifest(repo_root / ".codex-plugin" / "plugin.json", "codex_manifest"))
+
+ return results
diff --git a/src/open_second_brain/init.py b/src/open_second_brain/init.py
new file mode 100644
index 00000000..4e014293
--- /dev/null
+++ b/src/open_second_brain/init.py
@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+VAULT_FILES: list[Path] = [
+ Path("AI Wiki") / "_OPEN_SECOND_BRAIN.md",
+ Path("AI Wiki") / "_open-second-brain.yaml",
+ Path("AI Wiki") / "index.md",
+ Path("AI Wiki") / "hot.md",
+ Path("AI Wiki") / "log.md",
+ Path("AI Wiki") / "identity" / "user.md",
+ Path("AI Wiki") / "identity" / "agents.md",
+]
+
+TEMPLATES: dict[Path, str] = {
+ Path("AI Wiki") / "_OPEN_SECOND_BRAIN.md": (
+ "---\n"
+ "open_second_brain_version: 1\n"
+ "name: {name}\n"
+ "created: {created}\n"
+ "---\n\n"
+ "# {name}\n\n"
+ "This vault is managed by Open Second Brain.\n\n"
+ "## Rules\n\n"
+ "- Raw operational evidence goes into event log (Daily/).\n"
+ "- Synthesized knowledge goes into the wiki (AI Wiki/).\n"
+ "- Never write secrets, tokens, or credentials here.\n"
+ "- Read the identity files before acting on this vault.\n"
+ ),
+ Path("AI Wiki") / "_open-second-brain.yaml": (
+ "version: 1\n"
+ "name: {name}\n"
+ "created: {created}\n"
+ ),
+ Path("AI Wiki") / "index.md": (
+ "# {name}\n\n"
+ "Welcome to the {name} second brain.\n\n"
+ "## Key pages\n\n"
+ "- [[hot]] β€” short-term priority items.\n"
+ "- [[log]] β€” durable operation log.\n"
+ "- [[identity/user]] β€” owner profile.\n"
+ "- [[identity/agents]] β€” allowed agents and scopes.\n"
+ ),
+ Path("AI Wiki") / "hot.md": (
+ "# Hot\n\n"
+ "Short-term items, current focus, active decisions.\n\n"
+ "Items fade to cold over time.\n"
+ ),
+ Path("AI Wiki") / "log.md": (
+ "# Operation Log\n\n"
+ "Durable operations, major decisions, and infrastructure changes.\n\n"
+ "The event log (Daily/) is raw chronological evidence.\n"
+ "This page is synthesized operational knowledge.\n"
+ ),
+ Path("AI Wiki") / "identity" / "user.md": (
+ "# User Identity\n\n"
+ "Owner of this vault.\n\n"
+ "## Profile\n\n"
+ "- Name: (set your name)\n"
+ "- Timezone: (set your timezone)\n"
+ "- Contact: (set your primary contact)\n\n"
+ "## Preferences\n\n"
+ "(add durable preferences here so agents can read them)\n"
+ ),
+ Path("AI Wiki") / "identity" / "agents.md": (
+ "# Agent Identity\n\n"
+ "Allowed agents and their scopes.\n\n"
+ "## Registered agents\n\n"
+ "- (add your agents here, e.g., my-agent: operator on my-server)\n\n"
+ "## Scopes\n\n"
+ "- Write scope: AI Wiki/, Daily/\n"
+ "- Read scope: whole vault\n"
+ ),
+}
+
+
+def bootstrap_vault(
+ vault_dir: Path,
+ *,
+ name: str = "Second Brain",
+ force: bool = False,
+) -> list[Path]:
+ created: list[Path] = []
+ now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+ for rel_path in VAULT_FILES:
+ target = vault_dir / rel_path
+ target.parent.mkdir(parents=True, exist_ok=True)
+ if target.exists() and not force:
+ continue
+ template = TEMPLATES.get(rel_path, "")
+ content = template.format(name=name, created=now)
+ target.write_text(content, encoding="utf-8")
+ created.append(rel_path)
+
+ return created
diff --git a/tests/test_cli.py b/tests/test_cli.py
index ffa9935c..f39be85c 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -36,6 +36,73 @@ class CliTests(unittest.TestCase):
self.assertIn("config_exists: false", result.stdout)
self.assertIn(str(config), result.stdout)
+ def test_init_creates_vault_structure(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ result = run_cli("init", "--vault", str(vault), "--name", "Test")
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertIn("initialized vault:", result.stdout)
+ self.assertTrue((vault / "AI Wiki" / "_OPEN_SECOND_BRAIN.md").is_file())
+ self.assertTrue((vault / "AI Wiki" / "identity" / "agents.md").is_file())
+
+ def test_init_already_initialized_does_not_overwrite(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ run_cli("init", "--vault", str(vault), "--name", "First")
+ index = vault / "AI Wiki" / "index.md"
+ index.write_text("custom", encoding="utf-8")
+ result = run_cli("init", "--vault", str(vault), "--name", "Second")
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertIn("already initialized", result.stdout)
+ self.assertEqual(index.read_text(encoding="utf-8"), "custom")
+
+ def test_init_force_overwrites(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ run_cli("init", "--vault", str(vault), "--name", "First")
+ index = vault / "AI Wiki" / "index.md"
+ index.write_text("old", encoding="utf-8")
+ result = run_cli("init", "--vault", str(vault), "--name", "Second", "--force")
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertIn("initialized vault:", result.stdout)
+ self.assertNotEqual(index.read_text(encoding="utf-8"), "old")
+
+ def test_doctor_checks_valid_vault(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ result = run_cli(
+ "doctor",
+ "--vault",
+ str(vault),
+ env={
+ "OPEN_SECOND_BRAIN_CONFIG": "",
+ "XDG_CONFIG_HOME": "",
+ "VAULT_DIR": "",
+ },
+ )
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertIn("[OK]", result.stdout)
+ self.assertIn("vault", result.stdout.lower())
+
+ def test_doctor_reports_missing_vault(self):
+ result = run_cli("doctor", "--vault", "/nonexistent/path")
+ self.assertEqual(result.returncode, 1, result.stderr)
+ self.assertIn("[FAIL]", result.stdout)
+
+ def test_doctor_with_repo_checks_manifests(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp) / "vault"
+ vault.mkdir()
+ repo = Path(tmp) / "repo"
+ (repo / ".claude-plugin").mkdir(parents=True)
+ (repo / ".codex-plugin").mkdir(parents=True)
+ (repo / ".claude-plugin" / "plugin.json").write_text('{"name":"test"}', encoding="utf-8")
+ (repo / ".codex-plugin" / "plugin.json").write_text('{"name":"test"}', encoding="utf-8")
+ result = run_cli("doctor", "--vault", str(vault), "--repo", str(repo))
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertIn("claude_manifest", result.stdout)
+ self.assertIn("codex_manifest", result.stdout)
+
def test_append_event_writes_daily_note(self):
with tempfile.TemporaryDirectory() as tmp:
result = run_cli(
diff --git a/tests/test_doctor.py b/tests/test_doctor.py
new file mode 100644
index 00000000..cad4560d
--- /dev/null
+++ b/tests/test_doctor.py
@@ -0,0 +1,75 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from open_second_brain.doctor import (
+ CheckResult,
+ check_config_writeable,
+ check_json_manifest,
+ check_vault_writeable,
+ doctor,
+)
+
+
+class DoctorTests(unittest.TestCase):
+ def test_check_vault_writeable(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ result = check_vault_writeable(vault)
+ self.assertTrue(result.ok, result.message)
+ self.assertIn("writable", result.message.lower())
+
+ def test_check_vault_not_found(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ missing = Path(tmp) / "does_not_exist"
+ result = check_vault_writeable(missing)
+ self.assertFalse(result.ok)
+ self.assertIn("missing", result.message.lower())
+
+ def test_check_config_writeable_valid(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ config = Path(tmp) / "config.yaml"
+ config.write_text("vault_path: /tmp", encoding="utf-8")
+ result = check_config_writeable(config)
+ self.assertTrue(result.ok, result.message)
+
+ def test_check_config_writeable_missing_parent_is_ok(self):
+ # config can be missing; the check verifies we can write to the parent
+ with tempfile.TemporaryDirectory() as tmp:
+ config = Path(tmp) / "subdir" / "config.yaml"
+ result = check_config_writeable(config)
+ self.assertTrue(result.ok, f"should be ok: can create parent dirs and touch file: {result.message}")
+
+ def test_check_json_manifest_valid(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ manifest = Path(tmp) / "plugin.json"
+ manifest.write_text('{"name": "test", "version": "1.0.0"}', encoding="utf-8")
+ result = check_json_manifest(manifest, "Test manifest")
+ self.assertTrue(result.ok)
+
+ def test_check_json_manifest_invalid(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ manifest = Path(tmp) / "plugin.json"
+ manifest.write_text("{invalid json", encoding="utf-8")
+ result = check_json_manifest(manifest, "Test manifest")
+ self.assertFalse(result.ok)
+
+ def test_check_json_manifest_missing(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ missing = Path(tmp) / "does_not_exist.json"
+ result = check_json_manifest(missing, "Test")
+ self.assertFalse(result.ok)
+
+ def test_doctor_aggregates_results(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ config = Path(tmp) / "config.yaml"
+ config.write_text("vault_path: /tmp", encoding="utf-8")
+ results = doctor(vault=vault, config=config)
+ self.assertGreater(len(results), 0)
+ for r in results:
+ self.assertIsInstance(r, CheckResult)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_init.py b/tests/test_init.py
new file mode 100644
index 00000000..27c2fdc4
--- /dev/null
+++ b/tests/test_init.py
@@ -0,0 +1,59 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from open_second_brain.init import bootstrap_vault, VAULT_FILES
+
+
+class InitTests(unittest.TestCase):
+ def test_bootstrap_vault_creates_structure(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ created = bootstrap_vault(vault, name="Test Brain")
+ self.assertGreater(len(created), 0)
+ self.assertIn(Path("AI Wiki") / "_OPEN_SECOND_BRAIN.md", created)
+ self.assertIn(Path("AI Wiki") / "_open-second-brain.yaml", created)
+ self.assertIn(Path("AI Wiki") / "index.md", created)
+ self.assertIn(Path("AI Wiki") / "hot.md", created)
+ self.assertIn(Path("AI Wiki") / "log.md", created)
+ self.assertIn(Path("AI Wiki") / "identity" / "user.md", created)
+ self.assertIn(Path("AI Wiki") / "identity" / "agents.md", created)
+
+ # Verify all files exist
+ for rel_path in VAULT_FILES:
+ self.assertTrue((vault / rel_path).is_file(), f"Missing {rel_path}")
+
+ # Check content has the name
+ manual = (vault / "AI Wiki" / "_OPEN_SECOND_BRAIN.md").read_text(encoding="utf-8")
+ self.assertIn("Test Brain", manual)
+
+ def test_bootstrap_vault_does_not_overwrite_by_default(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ index_path = vault / "AI Wiki" / "index.md"
+ index_path.parent.mkdir(parents=True)
+ index_path.write_text("custom content", encoding="utf-8")
+
+ created = bootstrap_vault(vault, name="Test")
+ # index.md should NOT be in created (already exists)
+ self.assertNotIn(Path("AI Wiki") / "index.md", created)
+ # But other files should be created
+ self.assertIn(Path("AI Wiki") / "_OPEN_SECOND_BRAIN.md", created)
+ # Original content preserved
+ self.assertEqual(index_path.read_text(encoding="utf-8"), "custom content")
+
+ def test_bootstrap_vault_force_overwrites(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ index_path = vault / "AI Wiki" / "index.md"
+ index_path.parent.mkdir(parents=True)
+ index_path.write_text("old", encoding="utf-8")
+
+ created = bootstrap_vault(vault, name="Test", force=True)
+ self.assertIn(Path("AI Wiki") / "index.md", created)
+ # Content should be overwritten with template
+ self.assertNotEqual(index_path.read_text(encoding="utf-8"), "old")
+
+
+if __name__ == "__main__":
+ unittest.main()