dotbrain 0.3.4__py3-none-any.whl

dotbrain/bootstrap.py

@@ -0,0 +1,199 @@
+"""Machine-readiness bootstrap.
+
+This module owns machine-global setup: data-root seeding and global runtime links.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+from dotbrain import adopter_repos, resource_loader, skills, subagents
+
+Runner = Callable[..., "subprocess.CompletedProcess[str]"]
+
+
+def _default_run(
+    argv: Sequence[str], *, cwd: Path | None = None, check: bool = True
+) -> "subprocess.CompletedProcess[str]":
+    return subprocess.run(
+        list(argv), cwd=cwd, check=check,
+        capture_output=True, encoding="utf-8", stdin=subprocess.DEVNULL,
+    )
+
+
+# --------------------------------------------------------------------------- data-root seeding
+
+
+@dataclass
+class DataRootResult:
+    """What happened during data-root seeding (idempotent)."""
+
+    created: bool = False
+    config_seeded: bool = False
+    skills_seeded: bool = False
+    agents_seeded: bool = False
+    git_initialized: bool = False
+    logs: list[str] = field(default_factory=list)
+
+
+def ensure_root_gitignore(dotbrain_home: Path) -> bool:
+    """Ensure the data-root gitignore matches the packaged template."""
+
+    path = Path(dotbrain_home) / ".gitignore"
+    desired = resource_loader.resource("templates/gitignore").read_text(encoding="utf-8")
+    if path.is_file() and path.read_text(encoding="utf-8") == desired:
+        return False
+    path.write_text(desired, encoding="utf-8", newline="\n")
+    return True
+
+
+def ensure_data_root(dotbrain_home: Path, *, run: Runner = _default_run) -> DataRootResult:
+    """Create the data root and seed ``config.yaml`` from the packaged template.
+
+    Idempotent — if ``config.yaml`` already exists it is left untouched.
+    """
+    root = Path(dotbrain_home)
+    result = DataRootResult()
+
+    if not root.exists():
+        root.mkdir(parents=True)
+        result.created = True
+        result.logs.append(f"created data root: {root}")
+
+    # wire/refresh/unwire all require the data root to be a git checkout — Brain and
+    # execution state are versioned there. Seeding the files without initializing the
+    # repo left every fresh install failing on the first 'dotbrain wire'.
+    if not (root / ".git").exists():
+        try:
+            run(["git", "init", "--quiet"], cwd=root)
+        except FileNotFoundError as exc:
+            raise RuntimeError(
+                f"git is required to initialize the dotbrain data root at {root}; install git"
+            ) from exc
+        except subprocess.CalledProcessError as exc:
+            detail = (exc.stderr or exc.stdout or "").strip() or "git init failed"
+            raise RuntimeError(f"could not initialize {root} as a git checkout: {detail}") from exc
+        result.git_initialized = True
+        result.logs.append(f"initialized git checkout: {root}")
+
+    if ensure_root_gitignore(root):
+        result.logs.append(f"seeded .gitignore into {root}")
+
+    config_dest = root / "config.yaml"
+    if not config_dest.exists():
+        src = resource_loader.resource("config.yaml")
+        if src.is_file():
+            config_dest.write_text(
+                src.read_text(encoding="utf-8"),
+                encoding="utf-8",
+                newline="\n",
+            )
+            result.config_seeded = True
+            result.logs.append(f"seeded config.yaml into {root}")
+
+    # Seed the operator skill-link config so there's a clear home to manage
+    # global skills. Rendered via the same function reconcile uses, so the
+    # seeded file is already normalized.
+    skills_dest = root / "skills" / "skills.yaml"
+    if not skills_dest.exists():
+        skills_dest.parent.mkdir(parents=True, exist_ok=True)
+        skills_dest.write_text(
+            skills.render_global_config(skills.DEFAULT_TARGETS, ()),
+            encoding="utf-8",
+            newline="\n",
+        )
+        result.skills_seeded = True
+        result.logs.append(f"seeded skills/skills.yaml into {root}")
+
+    agents_root = root / "agents"
+    for subdir, _ext in subagents.RUNTIME_SPEC.values():
+        (agents_root / subdir).mkdir(parents=True, exist_ok=True)
+    agents_dest = agents_root / "agents.yaml"
+    if not agents_dest.exists():
+        agents_dest.write_text(
+            subagents.render_global_subagents(),
+            encoding="utf-8",
+            newline="\n",
+        )
+        result.agents_seeded = True
+        result.logs.append(f"seeded agents/agents.yaml into {root}")
+    seeded_subagents = subagents.rehydrate_packaged_subagents(root)
+    if seeded_subagents:
+        result.agents_seeded = True
+        result.logs += [
+            f"rehydrated {path.relative_to(root).as_posix()} into {root}" for path in seeded_subagents
+        ]
+
+    return result
+
+
+@dataclass
+class GlobalSkillBootstrapResult:
+    logs: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def link_global_skills(
+    dotbrain_home: Path, target: str = "all", *, home: Path | None = None
+) -> GlobalSkillBootstrapResult:
+    root = Path(dotbrain_home)
+    h = Path(home) if home is not None else Path.home()
+    config_path = root / "skills" / "skills.yaml"
+    result = GlobalSkillBootstrapResult()
+    config = skills.reconcile_global_config(config_path)
+    skill_paths = config.global_extra
+    if target == "all":
+        keys = list(config.targets)
+    elif target in config.targets:
+        keys = [target]
+    else:
+        result.warnings.append(f"target '{target}' not configured; skipping")
+        return result
+
+    for key in keys:
+        dest = adopter_repos.expand_path(config.targets[key], home=h)
+        link_result = skills.link_into(root, dest, skill_paths, label=key, prune_owned_only=True)
+        result.warnings += [f"{warning} (global {key})" for warning in link_result.warnings]
+        result.logs += [f"stashed real path aside: {moved}" for moved in link_result.stashed]
+        result.logs += [f"pruned stale {pruned}" for pruned in link_result.pruned]
+        result.logs.append(f"global: linked {len(link_result.linked)} skill(s) into {dest}")
+    return result
+
+
+def link_global_subagents(
+    dotbrain_home: Path, target: str = "all", *, home: Path | None = None
+) -> GlobalSkillBootstrapResult:
+    root = Path(dotbrain_home)
+    h = Path(home) if home is not None else Path.home()
+    result = GlobalSkillBootstrapResult()
+    config = subagents.load_global_config(root)
+    names = config.global_names
+    resolved = {name: subagents._resolve_subagent_files(root, name) for name in names}
+    missing = [name for name, runtime_files in resolved.items() if not runtime_files]
+    result.warnings += [f"subagent not found: {name}" for name in missing]
+
+    if target == "all":
+        keys = list(config.targets)
+    elif target in config.targets:
+        keys = [target]
+    else:
+        result.warnings.append(f"target '{target}' not configured; skipping")
+        return result
+
+    for key in keys:
+        dest = adopter_repos.expand_path(config.targets[key], home=h)
+        files = [runtime_files[key] for name, runtime_files in resolved.items() if key in runtime_files]
+        link_result = subagents.link_files_into(
+            root,
+            dest,
+            files,
+            label=key,
+        )
+        result.logs += [f"stashed real path aside: {moved}" for moved in link_result.stashed]
+        result.logs += [f"pruned stale {pruned}" for pruned in link_result.pruned]
+        result.logs.append(f"global: linked {len(files)} subagent file(s) into {dest}")
+    return result

dotbrain/brainspaces.py

@@ -0,0 +1,238 @@
+"""Brainspace lifecycle: Brain seeding, agent-workspace preparation, and offboarding.
+
+A Brainspace is a project's private context store under ``brainspaces/<name>/``. This module owns
+its whole lifecycle except the adopter-repo links (``adopter_repos``) and beads setup
+(``wiring``/``beads``):
+
+- Brain skeleton seeding from packaged ``templates/brain/`` resources;
+- agent-workspace preparation for selected Claude/Codex assets;
+- offboarding: keep | archive | delete plus the byproduct cleanup that precedes git mv/rm.
+
+It depends only on ``paths``. It is intentionally not split into ``brain_seed.py`` /
+``agent_workspaces.py`` yet.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+from dotbrain import config, paths, resource_loader
+
+# A subprocess seam: same shape as ``subprocess.run`` but easy to fake in tests.
+Runner = Callable[..., "subprocess.CompletedProcess[str]"]
+
+def _default_run(
+    argv: Sequence[str], *, cwd: Path | None = None, check: bool = True
+) -> "subprocess.CompletedProcess[str]":
+    return subprocess.run(
+        list(argv), cwd=cwd, check=check, capture_output=True, encoding="utf-8"
+    )
+
+
+# --------------------------------------------------------------------------- pure helpers
+
+
+# --------------------------------------------------------------------------- brain & gitignore
+
+
+def seed_brain(brainspace: Path, dotbrain_home: Path) -> None:
+    """Seed a brain skeleton from packaged dotbrain resources.
+
+    ``DOTBRAIN.md`` and ``README.md`` files are dotbrain-owned and overwritten
+    so package template changes propagate. All other files, including
+    ``project.yaml``, are project-owned and are only written when missing.
+    """
+
+    brain = Path(brainspace) / ".brain"
+    brain.mkdir(parents=True, exist_ok=True)
+
+    if not resource_loader.resource("templates/brain/AGENTS.md").is_file():
+        raise FileNotFoundError("package resource templates/brain/AGENTS.md is missing")
+
+    for rel, src in resource_loader.iter_resource_files("templates/brain"):
+        dest = brain / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        if src.name not in ("DOTBRAIN.md", "README.md") and dest.exists():
+            continue
+        content = src.read_text(encoding="utf-8")
+        if dest.is_file() and dest.read_bytes() == content.encode("utf-8"):
+            continue
+        dest.write_text(
+            content,
+            encoding="utf-8",
+            newline="\n",
+        )
+
+    claude = brain / "CLAUDE.md"
+    if not claude.exists():
+        claude.symlink_to("AGENTS.md")
+
+
+# --------------------------------------------------------------------------- agent workspaces
+
+
+def _hook_command_present(entries: list, command: str) -> bool:
+    for entry in entries:
+        for hook in entry.get("hooks", []) if isinstance(entry, dict) else []:
+            if isinstance(hook, dict) and hook.get("command") == command:
+                return True
+    return False
+
+
+def ensure_json_hook(
+    file: Path,
+    event: str,
+    command: str,
+    matcher: str = "",
+    status_message: str = "",
+) -> None:
+    """Idempotently merge a hook entry into an agent JSON config (Python port of the jq logic).
+
+    Keyed on the command string anywhere under ``.hooks[event][].hooks[].command``.
+    """
+    file = Path(file)
+    file.parent.mkdir(parents=True, exist_ok=True)
+    text = file.read_text(encoding="utf-8") if file.is_file() else ""
+    data = json.loads(text) if text.strip() else {}
+    if not isinstance(data, dict):
+        data = {}
+
+    hooks = data.setdefault("hooks", {})
+    entries = hooks.setdefault(event, [])
+    if _hook_command_present(entries, command):
+        return
+
+    hook: dict = {"type": "command", "command": command}
+    if status_message:
+        hook["statusMessage"] = status_message
+    entry: dict = {"hooks": [hook]}
+    if matcher:
+        entry["matcher"] = matcher
+    entries.append(entry)
+    file.write_text(
+        json.dumps(data, indent=2) + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )
+
+
+_KNOWN_AGENT_WORKSPACES = frozenset({"claude", "codex"})
+
+
+def active_agent_workspaces(brainspace: Path, dotbrain_home: Path) -> tuple[str, ...]:
+    """Return the declared, known workspace directory names for a project."""
+    agents = config.load_project_agents(dotbrain_home, Path(brainspace).name)
+    return tuple(f".{agent}" for agent in agents if agent in _KNOWN_AGENT_WORKSPACES)
+
+
+def is_brain_only(brainspace: Path) -> bool:
+    """True when the Brainspace declares no adopter repo."""
+
+    repo_file = Path(brainspace) / ".repo"
+    return (
+        repo_file.is_file()
+        and repo_file.read_text(encoding="utf-8").strip() == "(brain-only)"
+    )
+
+
+def seed_agent_workspaces(brainspace: Path, dotbrain_home: Path, home: Path | None = None) -> list[str]:
+    """Create declared agent workspaces, but only for a brain-only Brainspace.
+
+    A repo-backed Brainspace has its workspaces materialized in the code repo, and skill and
+    subagent links point from there straight at the dotbrain home. Seeding one here too would
+    leave directories nothing reads. A brain-only Brainspace has no repo, so it is the only
+    place its links can live.
+
+    Undeclared agents still warn either way: a typo in ``project.yaml`` should not be silent.
+    """
+    brainspace = Path(brainspace)
+    warnings: list[str] = []
+    brain_only = is_brain_only(brainspace)
+
+    for agent in config.load_project_agents(dotbrain_home, brainspace.name):
+        if agent not in _KNOWN_AGENT_WORKSPACES:
+            warnings.append(f"ignored unknown agent workspace in {brainspace / '.brain' / 'project.yaml'}: {agent}")
+            continue
+        if brain_only:
+            (brainspace / f".{agent}").mkdir(parents=True, exist_ok=True)
+
+    return warnings
+
+
+# --------------------------------------------------------------------------- offboarding
+
+
+def _strip_brainspace_byproducts(dotbrain_home: Path, project: str, run: Runner) -> None:
+    """Remove the Brainspace's gitignored runtime/wiring litter (beads runtime state,
+    .claude/.codex skill symlinks). ``git rm``/``git mv`` only handle tracked files, so
+    without this an offboard strands these byproducts on disk. ``-X`` removes *only* ignored
+    files, so an uncommitted (untracked) brain is left intact; ``-ff`` clears nested git/dolt dirs."""
+    rel = paths.data_dir(dotbrain_home).name
+    run(["git", "-C", str(dotbrain_home), "clean", "-ffdXq", "--", f"{rel}/{project}"])
+
+
+def _is_tracked(dotbrain_home: Path, project: str, run: Runner) -> bool:
+    """True if the Brainspace has any git-tracked files (wire no longer commits, so a
+    freshly-wired root is untracked and git rm/mv would fail)."""
+    rel = paths.data_dir(dotbrain_home).name
+    out = run(["git", "-C", str(dotbrain_home), "ls-files", "--", f"{rel}/{project}"], check=False)
+    return bool((out.stdout or "").strip())
+
+
+def offboard_brainspace(
+    dotbrain_home: Path,
+    project: str,
+    mode: str,
+    *,
+    dry_run: bool = False,
+    run: Runner = _default_run,
+) -> list[str]:
+    """keep | archive | delete the Brainspace. Returns log lines."""
+    brainspace = paths.brainspace(dotbrain_home, project)
+    rel = paths.data_dir(dotbrain_home).name
+    if not brainspace.is_dir():
+        return [f"warning: Brainspace {brainspace} not found; nothing to offboard"]
+
+    if mode == "keep":
+        return [f"kept Brainspace: {brainspace} (disconnected; re-wire later with dotbrain wire)"]
+
+    if mode == "archive":
+        if dry_run:
+            return [f"would archive Brainspace {rel}/{project} -> {rel}/.archive/{project} "
+                    "(stripping runtime byproducts first)"]
+        _strip_brainspace_byproducts(dotbrain_home, project, run)
+        archive_dir = paths.data_dir(dotbrain_home) / ".archive"
+        archive_dir.mkdir(exist_ok=True)
+        dest = archive_dir / project
+        if _is_tracked(dotbrain_home, project, run):
+            run(["git", "-C", str(dotbrain_home), "mv",
+                 f"{rel}/{project}", f"{rel}/.archive/{project}"])
+            staged = " (staged)"
+        else:
+            shutil.move(str(brainspace), str(dest))
+            staged = " (uncommitted)"
+        return [
+            f"archived Brainspace -> {rel}/.archive/{project}{staged}",
+            f"suggested commit: chore(brain): archive {project} Brainspace",
+        ]
+
+    if mode == "delete":
+        if dry_run:
+            return [f"would remove Brainspace {rel}/{project} (tracked files + runtime byproducts)"]
+        _strip_brainspace_byproducts(dotbrain_home, project, run)
+        # -f: delete is a deliberate full removal, so force past locally-modified tracked files
+        # (e.g. beads backup-state). --ignore-unmatch: a freshly-wired root is untracked.
+        run(["git", "-C", str(dotbrain_home), "rm", "-r", "-q", "-f", "--ignore-unmatch",
+             f"{rel}/{project}"])
+        if brainspace.exists():
+            shutil.rmtree(brainspace)
+        return [
+            f"removed Brainspace {rel}/{project}",
+            f"suggested commit: chore(brain): remove {project} Brainspace",
+        ]
+
+    raise ValueError(f"unknown offboard mode: {mode!r}")