dotbrain 0.3.4__py3-none-any.whl

dotbrain/resources/templates/brain/project.yaml

@@ -0,0 +1,27 @@
+# Per-project identity. Values below are active defaults; edit as needed.
+# The tool reads this file; dotbrain refresh may overwrite shared sections.
+
+execution-engine: beads
+
+agents:
+  - claude
+  - codex
+
+# Public-facing tracker for issue intake and contributor collaboration, never private work tracking.
+# One of: none, gh, linear.
+# Set public-tracker-id when activating a tracker (e.g. "owner/repo" for gh).
+public-tracker: none
+# public-tracker-id: ""
+
+# beads: deviations from global defaults only — uncomment the keys you need.
+#   mode: embedded     # one of: embedded, server, none
+#   remote: https://doltremoteapi.dolthub.com/owner/repo
+#   database: custom_name
+
+# Skills linked into this project's agent workspaces. Operator-owned.
+# skills:
+#   - some-collection/some-skill
+#
+# Project-scoped subagents only. The packaged four are always wired into active workspaces.
+# subagents:
+#   - some-project-only-subagent

dotbrain/resources/templates/gitignore

@@ -0,0 +1,17 @@
+# Generated cache state.
+/.cache/
+
+# Runtime state inside Brainspaces.
+brainspaces/*/.dolt/
+brainspaces/*/*.db
+brainspaces/*/.beads-credential-key
+brainspaces/*/.beads/proxieddb/
+brainspaces/*/.beads/metadata.json
+brainspaces/*/.beads/interactions.jsonl
+brainspaces/*/.beads/dolt-config.log
+brainspaces/*/.claude/settings.local.json
+brainspaces/*/.claude/skills/
+brainspaces/*/.codex/skills/
+brainspaces/*/.claude/agents/
+brainspaces/*/.codex/agents/
+brainspaces/*/.repo.local

dotbrain/skills.py

@@ -0,0 +1,264 @@
+"""Operator skill config and symlink linking."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable, Mapping, Sequence
+
+import yaml
+
+from dotbrain import paths
+
+DEFAULT_TARGETS: dict[str, str] = {
+    "claude-code": "~/.claude/skills",
+    "codex": "~/.codex/skills",
+}
+@dataclass
+class GlobalConfig:
+    """Operator-configurable skill-link settings."""
+
+    targets: dict[str, str] = field(default_factory=lambda: dict(DEFAULT_TARGETS))
+    global_extra: tuple[str, ...] = ()
+
+
+@dataclass
+class LinkResult:
+    """Result of creating/pruning skill links."""
+
+    linked: list[str] = field(default_factory=list)
+    pruned: list[str] = field(default_factory=list)
+    stashed: list[Path] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def _clean(values: object, *, exclude: Iterable[str] = ()) -> tuple[str, ...]:
+    if values is None:
+        return ()
+    if isinstance(values, str):
+        values = [values]
+    if not isinstance(values, (list, tuple)):
+        return ()
+
+    excluded = set(exclude)
+    out: list[str] = []
+    seen: set[str] = set()
+    for value in values:
+        if not isinstance(value, str):
+            continue
+        value = value.strip().strip("/")
+        if not value or value in excluded or value in seen:
+            continue
+        out.append(value)
+        seen.add(value)
+    return tuple(out)
+
+
+def discover_skills(skills_root: Path) -> list[str]:
+    """Return skill paths under a skills root."""
+
+    skills_root = Path(skills_root)
+    if not skills_root.is_dir():
+        return []
+
+    out: list[str] = []
+    for skill_md in skills_root.rglob("SKILL.md"):
+        if "node_modules" in skill_md.parts:
+            continue
+        out.append(skill_md.parent.relative_to(skills_root).as_posix())
+    return sorted(out)
+
+
+def _read_yaml_mapping(path: Path) -> dict[str, object]:
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    if not isinstance(data, dict):
+        raise ValueError(f"{path}: expected a YAML mapping")
+    return data
+
+
+def load_global_config(path: Path) -> GlobalConfig:
+    """Parse optional operator skill-link config."""
+
+    path = Path(path)
+    if not path.is_file():
+        return GlobalConfig()
+
+    data = _read_yaml_mapping(path)
+    targets = data.get("targets") or {}
+    if not isinstance(targets, dict) or not all(
+        isinstance(k, str) and isinstance(v, str) for k, v in targets.items()
+    ):
+        raise ValueError(f"{path}: targets must be a mapping of runtime -> destination")
+
+    merged_targets = dict(DEFAULT_TARGETS)
+    merged_targets.update(targets)
+    return GlobalConfig(
+        targets=merged_targets,
+        global_extra=_clean(data.get("global_extra", data.get("extra"))),
+    )
+
+
+def render_global_config(
+    targets: dict[str, str],
+    global_extra: Iterable[str],
+) -> str:
+    """Render the optional operator-owned skill-link config."""
+
+    lines = [
+        "version: 1",
+        "# Operator skill-link config — your global skills, linked into every agent",
+        "# session. List global skills under global_extra.",
+        "targets:",
+    ]
+    for key, value in targets.items():
+        lines.append(f"  {key}: {value}")
+    extra = _clean(global_extra)
+    if extra:
+        lines.append("global_extra:")
+        for skill in extra:
+            lines.append(f"  - {skill}")
+    else:
+        lines.append("global_extra: []")
+    return "\n".join(lines) + "\n"
+
+
+def reconcile_global_config(path: Path) -> GlobalConfig:
+    """Normalize optional operator config when present."""
+
+    path = Path(path)
+    config = load_global_config(path)
+    if path.is_file():
+        desired = render_global_config(
+            config.targets,
+            config.global_extra,
+        )
+        if path.read_text(encoding="utf-8") != desired:
+            path.write_text(desired, encoding="utf-8", newline="\n")
+    return config
+
+
+def project_link_set(extras: Iterable[str]) -> tuple[str, ...]:
+    """Return the operator's deduplicated per-project skill selection."""
+
+    return _clean(extras)
+
+
+def stash_collision(target: Path) -> Path:
+    tmp = target.parent / ".tmp"
+    tmp.mkdir(parents=True, exist_ok=True)
+    moved = tmp / f"{target.name}.{int(time.time())}"
+    target.rename(moved)
+    return moved
+
+
+def _points_into(link: Path, root: Path) -> bool:
+    try:
+        return link.resolve().is_relative_to(root.resolve())
+    except FileNotFoundError:
+        return False
+
+
+def _resolve_skill_source(dotbrain_home: Path, skill_path: str) -> Path | None:
+    private_src = dotbrain_home / "skills" / skill_path
+    return private_src if private_src.is_dir() else None
+
+
+def _remove_legacy_skill_cache(dotbrain_home: Path) -> None:
+    cache = Path(dotbrain_home) / ".cache" / "skills"
+    if cache.is_dir() and not cache.is_symlink():
+        shutil.rmtree(cache)
+    elif cache.exists() or cache.is_symlink():
+        cache.unlink()
+
+
+def link_into(
+    dotbrain_home: Path,
+    skills_dir: Path,
+    skill_paths: Sequence[str],
+    *,
+    label: str = "",
+    prune_owned_only: bool = False,
+    preserve_collisions: bool = False,
+) -> LinkResult:
+    """Link skill paths into an agent runtime skills directory."""
+
+    dotbrain_home = Path(dotbrain_home)
+    skills_dir = Path(skills_dir)
+    skills_dir.mkdir(parents=True, exist_ok=True)
+
+    prefix = f"{label}/" if label else ""
+    result = LinkResult()
+    wanted: set[str] = set()
+    _remove_legacy_skill_cache(dotbrain_home)
+    cache_root = (dotbrain_home / ".cache" / "skills").resolve()
+    private_root = (dotbrain_home / "skills").resolve()
+
+    for skill_path in skill_paths:
+        src = _resolve_skill_source(dotbrain_home, skill_path)
+        if src is None or not src.is_dir():
+            result.warnings.append(f"skill not found: {skill_path}")
+            continue
+
+        dest = skills_dir / Path(skill_path).name
+        wanted.add(dest.name)
+        owned = dest.is_symlink() and (
+            _points_into(dest, private_root) or _points_into(dest, cache_root)
+        )
+        if preserve_collisions and (dest.exists() or dest.is_symlink()) and not owned:
+            result.warnings.append(f"{dest} exists and was not created by dotbrain; skipping")
+            continue
+        if dest.exists() and not dest.is_symlink():
+            result.stashed.append(stash_collision(dest))
+        if dest.is_symlink() or dest.exists():
+            dest.unlink()
+        try:
+            dest.symlink_to(os.path.relpath(src, skills_dir), target_is_directory=True)
+        except OSError as exc:
+            message = paths.symlink_privilege_message(exc)
+            if message is None:
+                raise
+            raise RuntimeError(f"{dest}: {message}") from exc
+        result.linked.append(f"{prefix}{dest.name}")
+
+    for entry in sorted(skills_dir.iterdir()):
+        if not entry.is_symlink() or entry.name in wanted:
+            continue
+        if prune_owned_only and not (
+            _points_into(entry, private_root) or _points_into(entry, cache_root)
+        ):
+            continue
+        entry.unlink()
+        result.pruned.append(f"{prefix}{entry.name}")
+
+    return result
+
+
+def link_project(
+    dotbrain_home: Path,
+    brainspace: Path,
+    workspaces: Sequence[str],
+    skill_paths: Sequence[str],
+    *,
+    workspace_dirs: Mapping[str, Path] | None = None,
+) -> LinkResult:
+    brainspace = Path(brainspace)
+    result = LinkResult()
+    for workspace in workspaces:
+        workspace_dir = workspace_dirs.get(workspace) if workspace_dirs else None
+        skills_dir = (workspace_dir or brainspace / workspace) / "skills"
+        ws_result = link_into(
+            dotbrain_home,
+            skills_dir,
+            skill_paths,
+            label=f"{workspace}/skills",
+            prune_owned_only=True,
+            preserve_collisions=True,
+        )
+        result.linked += ws_result.linked
+        result.pruned += ws_result.pruned
+        result.stashed += ws_result.stashed
+        result.warnings += ws_result.warnings
+    return result

dotbrain/subagents.py

@@ -0,0 +1,252 @@
+"""Vendor-native subagent config and symlink linking."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Mapping, Sequence
+
+from dotbrain import resource_loader, skills
+
+AGENT_TARGETS: dict[str, str] = {
+    "claude-code": "~/.claude/agents",
+    "codex": "~/.codex/agents",
+}
+
+RUNTIME_SPEC: dict[str, tuple[str, str]] = {
+    "claude-code": ("claude", ".md"),
+    "codex": ("codex", ".toml"),
+}
+
+WORKSPACE_RUNTIME: dict[str, str] = {
+    ".claude": "claude-code",
+    ".codex": "codex",
+}
+
+
+def _required_core() -> tuple[str, ...]:
+    """Read the packaged project subagent core from core.yaml."""
+
+    import yaml
+
+    src = resource_loader.resource("core.yaml")
+    data = yaml.safe_load(src.read_text(encoding="utf-8")) or {}
+    if not isinstance(data, dict):
+        raise ValueError("packaged core.yaml: expected a YAML mapping")
+    subagents_data = data.get("subagents")
+    if not isinstance(subagents_data, dict):
+        raise ValueError("packaged core.yaml: expected a subagents mapping")
+    return skills._clean(subagents_data.get("project_required"))
+
+
+PROJECT_BASELINE = _required_core()
+
+
+@dataclass
+class GlobalConfig:
+    """Operator-configurable global subagent-link settings."""
+
+    targets: dict[str, str] = field(default_factory=lambda: dict(AGENT_TARGETS))
+    global_names: tuple[str, ...] = ()
+
+
+def render_global_subagents(names: Sequence[str] = ()) -> str:
+    lines = [
+        "# Global vendor-native subagents linked into personal agent homes.",
+        "# Remove entries to prune dotbrain-managed links on the next relink.",
+        "# Project-scoped extras belong in project.yaml; this file is for personal-home reach and extras.",
+        "# Optional target overrides (defaults shown):",
+        "# targets:",
+        "#   claude-code: ~/.claude/agents",
+        "#   codex: ~/.codex/agents",
+    ]
+    cleaned = skills._clean(names)
+    if not cleaned:
+        lines += ["# global:", "#   - some-shared-subagent"]
+        return "\n".join(lines) + "\n"
+    lines.append("global:")
+    lines.extend(f"  - {name}" for name in cleaned)
+    return "\n".join(lines) + "\n"
+
+
+def _copy_resource_file(resource_path: str, dest: Path) -> None:
+    if dest.exists() or dest.is_symlink():
+        if dest.is_dir() and not dest.is_symlink():
+            shutil.rmtree(dest)
+        else:
+            dest.unlink()
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(
+        resource_loader.resource(resource_path).read_text(encoding="utf-8"),
+        encoding="utf-8",
+        newline="\n",
+    )
+
+
+def rehydrate_packaged_subagents(dotbrain_home: Path) -> list[Path]:
+    root = Path(dotbrain_home)
+    cached: list[Path] = []
+    for rel, src in resource_loader.iter_resource_files("agents"):
+        dest = root / ".cache" / "agents" / rel
+        if dest.exists() or dest.is_symlink():
+            if dest.is_dir() and not dest.is_symlink():
+                shutil.rmtree(dest)
+            else:
+                dest.unlink()
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(
+            src.read_text(encoding="utf-8"),
+            encoding="utf-8",
+            newline="\n",
+        )
+        cached.append(dest)
+    return cached
+
+
+def seed_private_subagents(dotbrain_home: Path) -> list[Path]:
+    """Seed bundled examples into the private agents tree without overwriting overrides."""
+
+    root = Path(dotbrain_home)
+    seeded: list[Path] = []
+    for rel, src in resource_loader.iter_resource_files("agents"):
+        dest = root / "agents" / rel
+        if dest.exists() or dest.is_symlink():
+            continue
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(
+            src.read_text(encoding="utf-8"),
+            encoding="utf-8",
+            newline="\n",
+        )
+        seeded.append(dest)
+    return seeded
+
+
+def _resolve_subagent_files(dotbrain_home: Path, name: str) -> dict[str, Path]:
+    resolved: dict[str, Path] = {}
+    root = Path(dotbrain_home)
+    for runtime, (subdir, ext) in RUNTIME_SPEC.items():
+        private_src = root / "agents" / subdir / f"{name}{ext}"
+        if private_src.is_file():
+            resolved[runtime] = private_src
+            continue
+
+        resource_path = f"agents/{subdir}/{name}{ext}"
+        try:
+            resource = resource_loader.resource(resource_path)
+        except FileNotFoundError:
+            continue
+        if not resource.is_file():
+            continue
+
+        cached = root / ".cache" / "agents" / subdir / f"{name}{ext}"
+        _copy_resource_file(resource_path, cached)
+        resolved[runtime] = cached
+    return resolved
+
+
+def link_files_into(
+    dotbrain_home: Path,
+    target_dir: Path,
+    files: Sequence[Path],
+    *,
+    label: str,
+    preserve_collisions: bool = False,
+) -> skills.LinkResult:
+    target_dir = Path(target_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+    private_root = (Path(dotbrain_home) / "agents").resolve()
+    cache_root = (Path(dotbrain_home) / ".cache" / "agents").resolve()
+    result = skills.LinkResult()
+    wanted: set[str] = set()
+    prefix = f"{label}/" if label else ""
+
+    for src in files:
+        dest = target_dir / src.name
+        wanted.add(dest.name)
+        owned = dest.is_symlink() and (
+            skills._points_into(dest, private_root) or skills._points_into(dest, cache_root)
+        )
+        if preserve_collisions and (dest.exists() or dest.is_symlink()) and not owned:
+            result.warnings.append(f"{dest} exists and was not created by dotbrain; skipping")
+            continue
+        if dest.exists() and not dest.is_symlink():
+            result.stashed.append(skills.stash_collision(dest))
+        if dest.is_symlink() or dest.exists():
+            dest.unlink()
+        dest.symlink_to(os.path.relpath(src, target_dir))
+        result.linked.append(f"{prefix}{dest.name}")
+
+    for entry in sorted(target_dir.iterdir()):
+        if not entry.is_symlink() or entry.name in wanted:
+            continue
+        owned = skills._points_into(entry, private_root) or skills._points_into(entry, cache_root)
+        if not owned:
+            continue
+        entry.unlink()
+        result.pruned.append(f"{prefix}{entry.name}")
+
+    return result
+
+
+def load_global_config(dotbrain_home: Path) -> GlobalConfig:
+    path = Path(dotbrain_home) / "agents" / "agents.yaml"
+    if not path.is_file():
+        return GlobalConfig()
+    data = skills._read_yaml_mapping(path)
+    targets = data.get("targets") or {}
+    if not isinstance(targets, dict) or not all(
+        isinstance(k, str) and isinstance(v, str) for k, v in targets.items()
+    ):
+        raise ValueError(f"{path}: targets must be a mapping of runtime -> destination")
+    merged_targets = dict(AGENT_TARGETS)
+    merged_targets.update(targets)
+    return GlobalConfig(
+        targets=merged_targets,
+        global_names=skills._clean(data.get("global")),
+    )
+
+
+def load_global_subagents(dotbrain_home: Path) -> tuple[str, ...]:
+    return load_global_config(dotbrain_home).global_names
+
+
+def project_link_set(extras: Sequence[str]) -> tuple[str, ...]:
+    """Compose per-project link set: required core + operator extras."""
+
+    return PROJECT_BASELINE + skills._clean(extras, exclude=PROJECT_BASELINE)
+
+
+def link_project_subagents(
+    dotbrain_home: Path,
+    brainspace: Path,
+    workspaces: Sequence[str],
+    names: Sequence[str],
+    *,
+    workspace_dirs: Mapping[str, Path] | None = None,
+) -> skills.LinkResult:
+    root = Path(dotbrain_home)
+    resolved = {name: _resolve_subagent_files(root, name) for name in names}
+    result = skills.LinkResult()
+
+    result.warnings += [f"subagent not found: {name}" for name, files in resolved.items() if not files]
+
+    for workspace in workspaces:
+        runtime = WORKSPACE_RUNTIME.get(workspace)
+        if runtime is None:
+            continue
+        files = [resolved[name][runtime] for name in names if runtime in resolved[name]]
+        ws_result = link_files_into(
+            root,
+            ((workspace_dirs.get(workspace) if workspace_dirs else None) or Path(brainspace) / workspace) / "agents",
+            files,
+            label=f"{workspace}/agents",
+            preserve_collisions=True,
+        )
+        result.linked += ws_result.linked
+        result.pruned += ws_result.pruned
+        result.stashed += ws_result.stashed
+        result.warnings += ws_result.warnings
+    return result

dotbrain/updater.py

@@ -0,0 +1,105 @@
+"""Update released dotbrain CLI installations from PyPI."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from importlib import metadata
+from typing import Any, Callable
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+PACKAGE = "dotbrain"
+_PYPI_URL = f"https://pypi.org/pypi/{PACKAGE}/json"
+_VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+Fetch = Callable[[str], dict[str, Any]]
+Run = Callable[..., subprocess.CompletedProcess[str]]
+
+
+class UpdateError(RuntimeError):
+    """The CLI could not safely update itself."""
+
+
+def update_cli(current_version: str, *, fetch: Fetch | None = None,
+               run: Run = subprocess.run) -> str | None:
+    """Install the latest stable release, returning its version or ``None`` when current."""
+    if _is_editable_install():
+        raise UpdateError("editable installs are updated from their checkout; use git pull there")
+
+    fetch = fetch or _fetch_json
+    target_version = _latest_version(fetch(_PYPI_URL))
+    if _version_parts(target_version) <= _version_parts(current_version):
+        return None
+
+    command = ["uv", "tool", "install", "--force", f"{PACKAGE}=={target_version}"]
+    if _is_windows():
+        _defer_install(command)
+        return target_version
+    try:
+        result = run(command, check=False)
+    except FileNotFoundError as exc:
+        raise UpdateError("uv is not on PATH; install uv and retry") from exc
+    if result.returncode:
+        raise UpdateError(f"uv could not install {target_version}; the existing CLI was left unchanged")
+    return target_version
+
+
+def _is_windows() -> bool:
+    return os.name == "nt"
+
+
+def _defer_install(command: list[str]) -> None:
+    """Run after this Windows launcher releases its executable lock."""
+    subprocess.Popen(
+        ["cmd", "/c", f"ping -n 2 127.0.0.1 >NUL & {subprocess.list2cmdline(command)}"],
+    )
+
+
+def _is_editable_install() -> bool:
+    try:
+        distribution = metadata.distribution("dotbrain")
+    except metadata.PackageNotFoundError:
+        return False
+    raw = next(
+        (
+            distribution.locate_file(path).read_text(encoding="utf-8")
+            for path in distribution.files or ()
+            if path.name == "direct_url.json"
+        ),
+        None,
+    )
+    if not raw:
+        return False
+    try:
+        return bool(json.loads(raw).get("dir_info", {}).get("editable"))
+    except (ValueError, AttributeError):
+        return False
+
+
+def _fetch_json(url: str) -> dict[str, Any]:
+    request = Request(url, headers={"Accept": "application/json", "User-Agent": "dotbrain"})
+    try:
+        with urlopen(request, timeout=10) as response:  # noqa: S310 - fixed PyPI URL
+            data = json.load(response)
+    except (OSError, URLError, ValueError) as exc:
+        raise UpdateError("could not reach PyPI to check for updates") from exc
+    if not isinstance(data, dict):
+        raise UpdateError("PyPI returned an invalid update response")
+    return data
+
+
+def _latest_version(release: dict[str, Any]) -> str:
+    info = release.get("info", {}) if isinstance(release.get("info"), dict) else {}
+    version = str(info.get("version", ""))
+    if not _VERSION_RE.fullmatch(version):
+        raise UpdateError("PyPI did not return a stable dotbrain release")
+    return version
+
+
+def _version_parts(version: str) -> tuple[int, int, int]:
+    match = _VERSION_RE.fullmatch(version)
+    if not match:
+        raise UpdateError(f"unsupported installed version: {version}")
+    return tuple(int(part) for part in match.groups())