dotbrain 0.3.4__py3-none-any.whl

dotbrain/doctor.py

@@ -0,0 +1,279 @@
+"""Read-only health check for dotbrain: machine readiness, project wiring, beads drift.
+
+Self-contained diagnostic module. No filesystem mutations — pure inspections only.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from dotbrain import config, paths, resource_loader
+from dotbrain.adopter_repos import is_dotbrain_repo
+
+# Same shape as bootstrap.Runner; injected so tests can record without real subprocess calls.
+Runner = Callable[..., subprocess.CompletedProcess[str]]
+
+
+def _default_run(
+    argv: list[str], *, cwd: Path | None = None, check: bool = True, timeout: int | None = None
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        argv, cwd=cwd, check=check, capture_output=True, encoding="utf-8", timeout=timeout,
+    )
+
+
+@dataclass
+class Finding:
+    status: str       # "ok", "warn", "error"
+    message: str
+    suggestion: str = ""
+
+
+@dataclass
+class DoctorReport:
+    machine: list[Finding] = field(default_factory=list)
+    projects: dict[str, list[Finding]] = field(default_factory=dict)
+
+
+# --------------------------------------------------------------------------- machine readiness
+
+
+def _check_binary(name: str) -> Finding:
+    if shutil.which(name):
+        return Finding("ok", f"{name} available")
+    return Finding("error", f"{name} not found on PATH",
+                   f"install {name} or add it to PATH")
+
+
+def _check_dotbrain_config(root: Path) -> Finding:
+    try:
+        config.load_config(root)
+    except Exception as exc:
+        return Finding("error", f"config.yaml unreadable: {exc}",
+                       "check config.yaml syntax")
+    return Finding("ok", "config.yaml readable")
+
+
+def _check_global_skills_config(root: Path) -> Finding:
+    path = root / "skills" / "skills.yaml"
+    if path.is_file():
+        return Finding("ok", "operator skills config present")
+    return Finding("ok", "using packaged required-core skills only")
+
+
+def _check_templates(root: Path) -> Finding:
+    if resource_loader.resource("templates/brain/AGENTS.md").is_file():
+        return Finding("ok", "package templates/brain present")
+    return Finding("error", "package templates/brain missing",
+                   "installed package is missing bundled templates")
+
+
+def _check_machine(root: Path, home: Path) -> list[Finding]:
+    findings: list[Finding] = [
+        _check_binary("bd"),
+        _check_dotbrain_config(root),
+        _check_global_skills_config(root),
+        _check_templates(root),
+    ]
+    return findings
+
+
+# --------------------------------------------------------------------------- project wiring
+
+
+def _check_repo_file(brainspace: Path) -> tuple[Finding | None, Path | None]:
+    """Returns (finding_or_None, resolved_repo_path_or_None).
+
+    finding is None when the repo exists and is valid; the caller proceeds with wiring checks.
+    resolved_repo_path is None for brain-only projects or when the target is missing.
+    """
+    repo_file = brainspace / ".repo"
+    if not repo_file.is_file():
+        # Undeclared: the Brainspace names neither a repo nor brain-only. Both are
+        # resolvable, and only the operator knows which was intended, so name both.
+        return (Finding("error", f".repo file missing in {brainspace.name}",
+                        f"run 'dotbrain wire --repo <repo>' to wire a code repo, "
+                        f"or 'dotbrain wire --name {brainspace.name} --no-repo' "
+                        f"to declare it brain-only"),
+                None)
+    content = repo_file.read_text(encoding="utf-8").strip()
+    if content.startswith("(brain-only)"):
+        return (Finding("ok", "brain-only project (no code repo)"), None)
+    resolved = Path(content).expanduser().resolve() if content else None
+    if not resolved or not resolved.is_dir():
+        return (Finding("error", f".repo target not found: {content}",
+                        f"update {brainspace.name}/.repo or run 'dotbrain wire'"),
+                None)
+    return (None, resolved)  # repo exists; wiring checks follow
+
+
+def _check_brainspace_links(repo: Path, brainspace: Path) -> list[Finding]:
+    findings: list[Finding] = []
+    active_agents = config.load_project_agents(brainspace.parents[1], brainspace.name)
+    for agent in (agent for agent in ("claude", "codex") if agent in active_agents):
+        workspace = repo / f".{agent}"
+        if not workspace.is_dir() or workspace.is_symlink():
+            findings.append(Finding(
+                "warn",
+                f"{workspace} is not a materialized workspace",
+                f"run 'dotbrain refresh --name {brainspace.name}'",
+            ))
+    for name in paths.BRAINSPACE_LINKS:
+        link = repo / name
+        if not link.is_symlink():
+            findings.append(Finding("warn", f"{repo}/{name} not wired",
+                                     f"run 'dotbrain wire --repo {repo}'"))
+            continue
+        try:
+            link.resolve(strict=True)
+        except OSError:
+            findings.append(Finding("error", f"{repo}/{name} broken symlink",
+                                     f"run 'dotbrain wire --repo {repo}' to repair"))
+    return findings
+
+
+def _check_repo_excludes(repo: Path) -> list[Finding]:
+    findings: list[Finding] = []
+    present = paths.exclude_entries(repo)
+    for entry in paths.EXCLUDE_ENTRIES:
+        if entry not in present:
+            findings.append(Finding("warn",
+                                     f"{repo}/.git/info/exclude missing {entry}",
+                                     f"run 'dotbrain wire --repo {repo}' to repair"))
+    return findings
+
+
+# Wire's idempotency marker in append_pointer_to_file: ".brain/AGENTS.md" substring.
+# Doctor mirrors this so its "missing pointer" finding can actually be fixed by dotbrain wire.
+_WIRE_POINTER_MARKER = ".brain/AGENTS.md"
+
+
+def _check_agent_pointer(repo: Path) -> list[Finding]:
+    findings: list[Finding] = []
+    for name in ("AGENTS.md", "CLAUDE.md"):
+        file = repo / name
+        if not file.exists():
+            continue
+        try:
+            target = file.resolve(strict=True) if file.is_symlink() else file
+        except OSError:
+            continue
+        try:
+            if _WIRE_POINTER_MARKER not in target.read_text(encoding="utf-8"):
+                findings.append(Finding("warn",
+                                         f"{file} missing dotbrain pointer",
+                                         f"run 'dotbrain wire --repo {repo}' to repair"))
+        except OSError:
+            pass
+    return findings
+
+
+def _check_project_wiring(brainspace: Path, dotbrain_home: Path) -> list[Finding]:
+    findings: list[Finding] = []
+
+    repo_finding, resolved = _check_repo_file(brainspace)
+    if repo_finding is not None:
+        findings.append(repo_finding)
+        if repo_finding.status == "error":
+            return findings
+    if resolved is None:
+        return findings  # brain-only or repo target missing
+
+    # The dotbrain repo itself isn't an adopter — skip wiring checks on it.
+    if is_dotbrain_repo(resolved, dotbrain_home):
+        return [Finding("ok", "dotbrain repo (not an adopter)")]
+
+    findings += _check_brainspace_links(resolved, brainspace)
+    findings += _check_repo_excludes(resolved)
+    if paths.INJECT_ADOPTER_POINTER:
+        findings += _check_agent_pointer(resolved)
+    return findings
+
+
+# --------------------------------------------------------------------------- beads state
+
+
+def _check_beads_state(
+    brainspace: Path, name: str, dotbrain_home: Path, *, run: Runner = _default_run,
+) -> list[Finding]:
+    findings: list[Finding] = []
+    beads_cfg = config.load_project_config(dotbrain_home, name)
+
+    if beads_cfg.mode == "none":
+        return [Finding("ok", "beads disabled (mode: none)")]
+
+    beads_dir = brainspace / ".beads"
+    if not beads_dir.is_dir() or not (beads_dir / "metadata.json").is_file():
+        return [Finding("warn", ".beads not initialized",
+                        f"run 'dotbrain beads load --name {name}' or 'dotbrain wire --all'")]
+
+    if beads_cfg.mode == "server":
+        try:
+            run(["bd", "dolt", "test"], cwd=brainspace, check=True, timeout=15)
+            findings.append(Finding("ok", "beads server reachable"))
+        except subprocess.CalledProcessError as exc:
+            detail = (exc.stderr or exc.stdout or "").strip().splitlines()
+            msg = detail[-1] if detail else "bd dolt test failed"
+            findings.append(Finding("error", f"beads server unreachable: {msg}",
+                                     "check beads.server.host in dotbrain.yaml"))
+        except FileNotFoundError:
+            findings.append(Finding("error", "bd not found; skipping beads connectivity check",
+                                     "install bd to check beads server connectivity"))
+        except subprocess.TimeoutExpired:
+            findings.append(Finding("error", "beads server timed out",
+                                     "check connectivity to beads server"))
+    else:
+        findings.append(Finding("ok", f"beads mode: {beads_cfg.mode}"))
+
+    try:
+        result = run(["bd", "-C", str(brainspace), "ready"], cwd=brainspace, check=False, timeout=15)
+        if result.returncode != 0:
+            msg = (result.stderr or "").strip().splitlines()
+            snippet = msg[-1] if msg else "bd ready returned non-zero"
+            findings.append(Finding("warn", f"bd ready failed: {snippet}",
+                                     "beads tracker may need attention: bd doctor, bd dolt pull"))
+        else:
+            findings.append(Finding("ok", "bd ready responds"))
+    except FileNotFoundError:
+        findings.append(Finding("error", "bd not found; skipping beads check"))
+
+    return findings
+
+
+# --------------------------------------------------------------------------- orchestration
+
+
+def run_doctor(
+    dotbrain_home: Path, home: Path | None = None, *, run: Runner = _default_run,
+) -> DoctorReport:
+    home = Path(home) if home is not None else Path.home()
+    root = dotbrain_home.resolve()
+
+    report = DoctorReport(
+        machine=_check_machine(root, home),
+    )
+
+    brainspaces = paths.brainspaces(root)
+    if not brainspaces:
+        report.machine.append(Finding("warn", f"no Brainspaces in {paths.data_dir(root).name}/",
+                                       "create a project with 'dotbrain wire'"))
+        return report
+
+    for brainspace in brainspaces:
+        name = brainspace.name
+        findings: list[Finding] = []
+
+        wiring_findings = _check_project_wiring(brainspace, root)
+        findings += wiring_findings
+
+        if shutil.which("bd"):
+            findings += _check_beads_state(brainspace, name, root, run=run)
+
+        if findings:
+            report.projects[name] = findings
+
+    return report

dotbrain/hooks.py

@@ -0,0 +1,84 @@
+"""SessionStart hook: assemble a wired repo's Brain context.
+
+Pure Python by design. This ran as a packaged bash script until the Windows chain
+(PowerShell -> Python -> Git Bash) proved unreliable: locating a real ``bash`` behind
+Windows' ``System32`` WSL launcher depends on how Git was installed, and when the
+resolver picked the stub the script emitted nothing. Because the hook is fail-open,
+that surfaced as a session with no Brain context and no error at all.
+
+Only ``DOTBRAIN.md`` is injected. dotbrain owns that file, so its size is bounded and
+guarded by a test. The project's own ``.brain/AGENTS.md`` is deliberately left out: it
+grows with the project and would eventually cross the payload limit, at which point the
+runtime spills stdout to a file and the model receives none of it — including the
+convention. ``DOTBRAIN.md`` carries a rule telling the agent to read it instead.
+
+Output is assembled as bytes and written to ``stdout.buffer`` so the payload is exactly
+what ``cat`` produced: no newline translation on Windows, no re-encoding of Brain files.
+
+Beads context lives in project hooks (``bd prime --hook-json`` on Claude Code,
+``bd codex-hook SessionStart`` on Codex), so this hook does not set ``BEADS_DIR``.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import BinaryIO
+
+CONVENTION_HEADING = "## dotbrain convention"
+
+# Hook stdout over this many bytes is spilled to a file and never reaches the model.
+# Measured on Claude Code: 9,961 bytes delivered, 10,010 did not.
+PAYLOAD_LIMIT = 10_000
+
+
+def repo_root(cwd: Path | None = None) -> Path | None:
+    """Return the enclosing git repo root, or None outside one (and with no git)."""
+
+    try:
+        completed = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=cwd,
+            capture_output=True,
+            check=False,
+            encoding="utf-8",
+        )
+    except OSError:
+        return None
+    if completed.returncode != 0:
+        return None
+    top = (completed.stdout or "").strip()
+    return Path(top) if top else None
+
+
+def brain_context(cwd: Path | None = None) -> bytes:
+    """Build the SessionStart payload for a wired repo; empty bytes when there is no Brain."""
+
+    root = repo_root(cwd)
+    if root is None:
+        return b""
+    convention = root / ".brain" / "DOTBRAIN.md"
+    if not convention.is_file():
+        return b""
+
+    heading = (CONVENTION_HEADING + "\n\n").encode("utf-8")
+    return heading + convention.read_bytes() + b"\n\n"
+
+
+def emit_brain_context(stream: BinaryIO | None = None, cwd: Path | None = None) -> None:
+    """Write the payload to a binary stream. Fail-open: never raises, never exits nonzero."""
+
+    target = stream if stream is not None else sys.stdout.buffer
+    try:
+        payload = brain_context(cwd)
+    except OSError:
+        return
+    if not payload:
+        return
+    try:
+        target.write(payload)
+        target.flush()
+    except (OSError, ValueError):
+        # stdout closed or EPIPE at hook exit must not surface as a hook failure.
+        return

dotbrain/migrate.py

@@ -0,0 +1,304 @@
+"""Migrate a project's beads tracker from embedded Dolt to a remote sql-server.
+
+dotbrain adopters start local-by-default: ``dotbrain wire`` initialises beads with an embedded
+Dolt engine. Moving an already-wired brain onto a shared sql-server has to preserve the full
+Dolt commit graph, so this uses ``bd backup`` (Dolt-native, history-preserving) rather than the
+``bd export`` JSONL path, which drops branches/history.
+
+Per-project sequence (all ``bd`` calls run with ``cwd=<brainspace>`` and ``_beads_env(brainspace)``):
+
+1. ``bd stats --json``                     -> capture ``summary.total_issues`` (pre_count)
+2. ``bd backup init <backup-dir>``
+3. ``bd backup sync``                       -> full Dolt backup of the embedded db
+4. ``bd init --server --external ... --reinit-local --destroy-token DESTROY-<prefix>``
+                                            -> repoint .beads at the server (fresh empty db)
+5. ``bd backup restore --force <backup-dir>`` -> load full history into the server db
+6. ``bd dolt test``                         -> connection sanity
+7. ``bd stats --json``                      -> post_count; assert it matches pre_count
+
+The embedded ``.beads/embeddeddolt`` and the backup dir are kept by default as the rollback path;
+cleanup stays manual until a migration's history depth is verified on the server.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from dotbrain import config, paths
+from dotbrain.beads import (
+    Runner,
+    _bd_init_args,
+    _beads_env,
+    _default_run,
+    _hide_root_beads,
+    _restore_root_beads,
+    normalize_server_beads_metadata,
+)
+
+
+# --------------------------------------------------------------------------- pure helpers
+
+
+def destroy_token(project: str) -> str:
+    """The non-interactive ``bd init`` confirmation token for re-initialising over local data."""
+    return f"DESTROY-{project}"
+
+
+def backup_dir_for(brainspace: Path) -> Path:
+    """Backup destination, kept outside tracked project Brainspaces."""
+    brainspace = Path(brainspace)
+    return brainspace.parent.parent / "backups" / "beads" / brainspace.name
+
+
+def parse_total_issues(stdout: str) -> int | None:
+    """Pull ``summary.total_issues`` out of ``bd stats --json``; None when it can't be parsed."""
+    try:
+        return int(json.loads(stdout)["summary"]["total_issues"])
+    except (ValueError, KeyError, TypeError):
+        return None
+
+
+def beads_mode(brainspace: Path) -> str:
+    """Classify a Brainspace's beads backend: ``embedded`` | ``server`` | ``none`` | ``unknown``.
+
+    Reads ``.beads/metadata.json`` directly (the same file bootstrap inspects); avoids shelling out.
+    """
+    metadata = Path(brainspace) / ".beads" / "metadata.json"
+    if not (Path(brainspace) / ".beads").is_dir():
+        return "none"
+    if not metadata.is_file():
+        return "unknown"
+    try:
+        data = json.loads(metadata.read_text(encoding="utf-8"))
+    except (ValueError, OSError):
+        return "unknown"
+    mode = str(data.get("dolt_mode", "")).strip()
+    if mode == "embedded":
+        return "embedded"
+    if mode in {"server", "external"}:
+        return "server"
+    return "unknown"
+
+
+# --------------------------------------------------------------------------- result type
+
+
+@dataclass
+class MigrationResult:
+    project: str = ""
+    brainspace: Path | None = None
+    status: str = ""  # migrated|migrated-unverified|skipped-server|skipped-no-beads|skipped-unknown|aborted-count-mismatch|dry-run|failed
+    pre_count: int | None = None
+    post_count: int | None = None
+    logs: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    planned_commands: list[list[str]] = field(default_factory=list)
+
+
+# --------------------------------------------------------------------------- orchestration
+
+
+def _migration_argv(
+    project: str, database: str, host: str, port: str, user: str, backup: Path
+) -> list[list[str]]:
+    """The ordered bd command sequence for one embedded -> server migration."""
+    return [
+        ["bd", "stats", "--json"],
+        ["bd", "backup", "init", str(backup)],
+        ["bd", "backup", "sync"],
+        *_backup_server_copy_argv(host, backup),
+        _bd_init_args(
+            project, "", host, port, user, database or project,
+            reinit_local=True, destroy_token=destroy_token(project),
+        ),
+        ["bd", "backup", "restore", "--force", str(backup)],
+        ["bd", "dolt", "test"],
+        ["bd", "stats", "--json"],
+    ]
+
+
+# Non-interactive SSH for the backup copy: the migration runs with no TTY, so a
+# first-connect host-key prompt or an unreachable server would hang it forever.
+# BatchMode disables prompts and ConnectTimeout bounds the wait, turning either
+# case into a fast, surfaced error instead of a silent stall.
+_SSH_OPTS = ["-o", "BatchMode=yes", "-o", "ConnectTimeout=10"]
+_RSYNC_SSH = "ssh " + " ".join(_SSH_OPTS)
+
+
+def _host_is_local(host: str) -> bool:
+    return host in {"", "localhost", "127.0.0.1", "::1"}
+
+
+def _backup_server_copy_argv(host: str, backup: Path) -> list[list[str]]:
+    """Make a local file:// backup visible to a remote external Dolt server."""
+    if _host_is_local(host):
+        return []
+    return [
+        ["ssh", *_SSH_OPTS, host, "mkdir", "-p", str(backup.parent)],
+        ["rsync", "-a", "--delete", "-e", _RSYNC_SSH, f"{backup}/", f"{host}:{backup}/"],
+    ]
+
+
+def migrate_project(
+    *,
+    dotbrain_home: Path,
+    project: str,
+    server_host: str,
+    server_port: str = "3307",
+    server_user: str = "beads",
+    database: str = "",
+    dry_run: bool = False,
+    run: Runner = _default_run,
+) -> MigrationResult:
+    dotbrain_home = Path(dotbrain_home)
+    brainspace = paths.brainspace(dotbrain_home, project)
+    result = MigrationResult(project=project, brainspace=brainspace)
+
+    mode = beads_mode(brainspace)
+    if mode == "server":
+        result.status = "skipped-server"
+        result.logs.append(f"{project}: already on a Dolt server; nothing to migrate")
+        return result
+    if mode == "none":
+        result.status = "skipped-no-beads"
+        result.logs.append(f"{project}: no .beads to migrate")
+        return result
+    if mode == "unknown":
+        result.status = "skipped-unknown"
+        result.warnings.append(
+            f"{project}: could not determine beads mode from metadata.json; skipping to avoid a "
+            "destructive re-init"
+        )
+        return result
+
+    database = database or project
+    backup = backup_dir_for(brainspace)
+    commands = _migration_argv(
+        project, database, server_host, server_port, server_user, backup
+    )
+    backup_copy_commands = _backup_server_copy_argv(server_host, backup)
+    init_args = commands[3 + len(backup_copy_commands)]
+
+    if dry_run:
+        result.status = "dry-run"
+        result.planned_commands = commands
+        result.logs.append(f"{project}: dry-run; {len(commands)} bd commands planned")
+        return result
+
+    env = _beads_env(brainspace)
+    hidden = _hide_root_beads(brainspace, dotbrain_home)
+    try:
+        stats_pre = run(["bd", "stats", "--json"], cwd=brainspace, env=env, check=True)
+        result.pre_count = parse_total_issues(stats_pre.stdout or "")
+
+        backup.parent.mkdir(parents=True, exist_ok=True)
+        run(["bd", "backup", "init", str(backup)], cwd=brainspace, env=env, check=True)
+        run(["bd", "backup", "sync"], cwd=brainspace, env=env, check=True)
+        for argv in backup_copy_commands:
+            run(argv, cwd=brainspace, env=env, check=True)
+        run(init_args, cwd=brainspace, env=env, check=True)  # bd init --server ... --reinit-local
+        run(["bd", "backup", "restore", "--force", str(backup)], cwd=brainspace, env=env, check=True)
+        run(["bd", "dolt", "test"], cwd=brainspace, env=env, check=True)
+        # bd writes the legacy dolt_server_port into metadata.json; make the port file primary.
+        normalize_server_beads_metadata(brainspace / ".beads", server_port)
+
+        stats_post = run(["bd", "stats", "--json"], cwd=brainspace, env=env, check=True)
+        result.post_count = parse_total_issues(stats_post.stdout or "")
+    finally:
+        _restore_root_beads(hidden, dotbrain_home)
+
+    if result.pre_count is None or result.post_count is None:
+        result.status = "migrated-unverified"
+        result.warnings.append(
+            f"{project}: migrated, but could not verify issue count from bd stats; verify history "
+            "depth on the server before removing embedded data"
+        )
+        _record_migrated_backend(dotbrain_home, project, database, result)
+        return result
+    if result.post_count != result.pre_count:
+        result.status = "aborted-count-mismatch"
+        result.warnings.append(
+            f"{project}: post-restore count {result.post_count} != pre-migration "
+            f"{result.pre_count}; embedded data and backup left intact for rollback"
+        )
+        return result
+
+    result.status = "migrated"
+    result.logs.append(
+        f"{project}: migrated to {server_host}:{server_port}/{database} "
+        f"({result.post_count} issues); embedded data + backup kept for rollback"
+    )
+    _record_migrated_backend(dotbrain_home, project, database, result)
+    return result
+
+
+def _record_migrated_backend(
+    dotbrain_home: Path, project: str, database: str, result: MigrationResult
+) -> None:
+    """The project is on the server now; its dotbrain.yaml entry must say so."""
+    if database != project:
+        log = config.record_project_beads(
+            dotbrain_home, project, config.ProjectBeads(mode="server", database=database)
+        )
+    else:
+        log = config.remove_project_beads(dotbrain_home, project)
+    if log:
+        result.logs.append(log)
+
+
+def _looks_like_ssh_failure(exc: Exception) -> bool:
+    """True when the failed command was the ssh/rsync backup copy (a likely host-key issue)."""
+    cmd = getattr(exc, "cmd", None)
+    return bool(cmd) and cmd[0] in {"ssh", "rsync"}
+
+
+def safe_migrate_project(**kwargs) -> MigrationResult:
+    """``migrate_project`` that turns any subprocess failure into a ``failed`` result.
+
+    Both the single-project CLI path and the ``--all`` sweep use this so a failed migration
+    reports a clean status and an actionable hint instead of crashing with a traceback. Accepts
+    the same keyword arguments as ``migrate_project``.
+    """
+    project = kwargs.get("project", "")
+    try:
+        return migrate_project(**kwargs)
+    except Exception as exc:
+        brainspace = paths.brainspace(Path(kwargs["dotbrain_home"]), project) if project else None
+        detail = str(exc)
+        stderr = (getattr(exc, "stderr", "") or "").strip()
+        if stderr:
+            detail = f"{detail}: {stderr}"
+        warnings = [f"{project}: migration failed: {detail}"]
+        if _looks_like_ssh_failure(exc):
+            warnings.append(
+                f"{project}: the Dolt server's SSH host key may be untrusted; trust it first "
+                "(e.g. `ssh-keyscan <host> >> ~/.ssh/known_hosts`) and retry"
+            )
+        return MigrationResult(project=project, brainspace=brainspace, status="failed", warnings=warnings)
+
+
+def migrate_all(
+    *,
+    dotbrain_home: Path,
+    server_host: str,
+    server_port: str = "3307",
+    server_user: str = "beads",
+    dry_run: bool = False,
+    run: Runner = _default_run,
+) -> list[MigrationResult]:
+    """Migrate every embedded Brainspace; skip server/none ones; never abort the whole sweep."""
+    dotbrain_home = Path(dotbrain_home)
+    return [
+        safe_migrate_project(
+            dotbrain_home=dotbrain_home,
+            project=brainspace.name,
+            server_host=server_host,
+            server_port=server_port,
+            server_user=server_user,
+            dry_run=dry_run,
+            run=run,
+        )
+        for brainspace in paths.brainspaces(dotbrain_home)
+    ]