agent-notes 2.0.4__py3-none-any.whl

agent_notes/data/templates/frontmatter/opencode.py

@@ -0,0 +1,104 @@
+"""OpenCode frontmatter generator template."""
+
+from typing import Dict, Any
+
+
+_COLOR_TO_HEX = {
+    'red':    '#ef4444',
+    'blue':   '#3b82f6',
+    'green':  '#22c55e',
+    'yellow': '#eab308',
+    'purple': '#a855f7',
+    'orange': '#f97316',
+    'pink':   '#ec4899',
+    'cyan':   '#06b6d4',
+    'iris':   '#6366f1',
+    'violet': '#8b5cf6',
+    'ruby':   '#e11d48',
+    'gold':   '#d97706',
+    'gray':   '#6b7280',
+    'jade':   '#10b981',
+    'lime':   '#84cc16',
+    'mint':   '#14b8a6',
+}
+
+
+def render(ctx: dict) -> str:
+    """Render YAML frontmatter for an OpenCode agent.
+    
+    ctx keys:
+      agent_name:  str
+      agent_config: dict (from agents.yaml entry)
+      model_str:   str (resolved model string)
+      backend_name: str
+      backend:     CLIBackend object or None
+    """
+    agent_config = ctx['agent_config']
+    model_str = ctx['model_str']
+    
+    frontmatter = ['---']
+    frontmatter.append(f'description: {agent_config["description"]}')
+    frontmatter.append(f'mode: {agent_config["mode"]}')
+    frontmatter.append(f'model: {model_str}')
+    
+    # Handle permissions
+    opencode_config = agent_config.get('opencode', {})
+    permission = opencode_config.get('permission', {})
+    
+    if permission:
+        frontmatter.append('permission:')
+        
+        # Handle simple permissions
+        if 'edit' in permission:
+            frontmatter.append(f'  edit: {permission["edit"]}')
+        
+        # Handle bash permissions (can be string or dict)
+        if 'bash' in permission:
+            bash_perm = permission['bash']
+            if isinstance(bash_perm, str):
+                frontmatter.append(f'  bash: {bash_perm}')
+            elif isinstance(bash_perm, dict):
+                frontmatter.append('  bash:')
+                for key, value in bash_perm.items():
+                    # Properly quote keys with special characters
+                    if '*' in key or ' ' in key:
+                        frontmatter.append(f'    "{key}": {value}')
+                    else:
+                        frontmatter.append(f'    {key}: {value}')
+    
+    if 'color' in agent_config:
+        color = _COLOR_TO_HEX.get(agent_config['color'], agent_config['color'])
+        frontmatter.append(f"color: '{color}'")
+    
+    frontmatter.append('---')
+    
+    return '\n'.join(frontmatter)
+
+
+def post_process(prompt: str, ctx: dict) -> str:
+    """Strip ## Memory section from prompt for OpenCode (doesn't support agent memory)."""
+    return _strip_memory_section(prompt)
+
+
+def _strip_memory_section(content: str) -> str:
+    """Strip ## Memory section from content for OpenCode format."""
+    lines = content.split('\n')
+    result_lines = []
+    in_memory_section = False
+    
+    for line in lines:
+        if line.startswith('## Memory'):
+            in_memory_section = True
+            continue
+        elif line.startswith('## ') and in_memory_section:
+            # New section after Memory, include this line and continue
+            in_memory_section = False
+            result_lines.append(line)
+        elif not in_memory_section:
+            result_lines.append(line)
+    
+    # Remove trailing empty lines
+    while result_lines and result_lines[-1].strip() == '':
+        result_lines.pop()
+    
+    return '\n'.join(result_lines)

agent_notes/doctor_checks.py

@@ -0,0 +1,189 @@
+"""Scoped health checks for agent-notes — only touches files we own."""
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Optional
+
+from .registries.cli_registry import CLIRegistry
+from .domain.cli_backend import CLIBackend
+from .services import installer
+from .state import State, ScopeState, sha256_of
+from .config import BIN_HOME, AGENTS_HOME, DIST_SCRIPTS_DIR, DIST_SKILLS_DIR
+
+
+def expected_paths_for_install(
+    registry: CLIRegistry, scope: str
+) -> list[tuple[Path, Path, str, str]]:
+    """Return list of (source_file, target_file, backend_name, component) tuples
+    that SHOULD be installed given the current dist/ tree and registry.
+    
+    Does NOT read state.json — this is "what would be installed if user ran install now".
+    """
+    expected: list[tuple[Path, Path, str, str]] = []
+    
+    for backend in registry.all():
+        for component in installer.COMPONENT_TYPES:
+            src = installer.dist_source_for(backend, component)
+            dst = installer.target_dir_for(backend, component, scope)
+            if src is None or dst is None:
+                continue
+            
+            if component == "config":
+                fn = installer.config_filename_for(backend)
+                if not fn:
+                    continue
+                src_file = src / fn
+                if src_file.exists():
+                    expected.append((src_file, dst / fn, backend.name, component))
+            elif component == "skills":
+                # Each top-level dir in src is a skill
+                for skill_dir in sorted(src.iterdir()):
+                    if skill_dir.is_dir():
+                        expected.append((skill_dir, dst / skill_dir.name, backend.name, component))
+            else:
+                # agents, rules, commands: flat *.md files
+                for f in sorted(src.glob("*.md")):
+                    expected.append((f, dst / f.name, backend.name, component))
+    
+    # Scripts (global only)
+    if scope == "global" and DIST_SCRIPTS_DIR.exists():
+        for script in sorted(DIST_SCRIPTS_DIR.iterdir()):
+            if script.is_file():
+                expected.append((script, BIN_HOME / script.name, "scripts", "scripts"))
+    
+    # Universal skills mirror (global only)
+    if scope == "global" and DIST_SKILLS_DIR.exists():
+        any_backend_has_skills = any(b.supports("skills") for b in registry.all())
+        if any_backend_has_skills:
+            for skill_dir in sorted(DIST_SKILLS_DIR.iterdir()):
+                if skill_dir.is_dir():
+                    expected.append((skill_dir, AGENTS_HOME / "skills" / skill_dir.name, "universal", "skills"))
+    
+    return expected
+
+
+def check_missing(scope, registry, issues, fix_actions, scope_state: Optional[ScopeState] = None):
+    """Files that exist in dist/ but are not installed.
+
+    If ``scope_state`` is provided, only flag missing files for backends the
+    user actually installed — backends absent from state were opted-out of
+    and legitimately have no files on disk. When ``scope_state`` is None,
+    fall back to expecting every registry backend (legacy behavior).
+    """
+    from .doctor import Issue, FixAction  # reuse existing classes
+    installed_backends: Optional[set[str]] = None
+    if scope_state is not None:
+        installed_backends = set(scope_state.clis.keys())
+
+    for src, dst, backend_name, component in expected_paths_for_install(registry, scope):
+        # "scripts" / "universal" are shared (not per-CLI-backend); always expected.
+        if (installed_backends is not None
+                and backend_name not in ("scripts", "universal")
+                and backend_name not in installed_backends):
+            continue
+        if not dst.exists() and not dst.is_symlink():
+            issues.append(Issue("missing", str(dst), "Source exists but not installed"))
+            fix_actions.append(FixAction("INSTALL", str(dst), f"install {component}"))
+
+
+def check_broken(scope, registry, issues, fix_actions, scope_state: Optional[ScopeState] = None):
+    """Expected files that are broken symlinks."""
+    from .doctor import Issue, FixAction
+    paths_to_check: set[tuple[Path, Path]] = set()
+    
+    # Expected paths from current dist
+    for src, dst, _, _ in expected_paths_for_install(registry, scope):
+        paths_to_check.add((src, dst))
+    
+    # Plus state.json paths (may differ from expected if dist changed)
+    if scope_state is not None:
+        for backend_name, bs in scope_state.clis.items():
+            for component_type, items in bs.installed.items():
+                for _name, item in items.items():
+                    paths_to_check.add((Path("?"), Path(item.target)))
+    
+    for _src, path in paths_to_check:
+        if path.is_symlink():
+            target = path.readlink()
+            if not target.is_absolute():
+                target = path.parent / target
+            if not target.exists():
+                issues.append(Issue("broken", str(path), "Symlink target does not exist"))
+                # Try to recover the source — if it's in our dist, relink; else delete
+                fix_actions.append(FixAction("RELINK", str(path), "reinstall"))
+
+
+def check_drift(scope, registry, issues, fix_actions, scope_state: Optional[ScopeState] = None):
+    """Content drift: regular file (not symlink) whose content differs from source.
+    
+    Only meaningful when install mode was 'copy'. Limit to state.json paths if available.
+    """
+    from .doctor import Issue, FixAction
+    if scope_state is None:
+        return  # without state.json, we don't know if drift is expected (no manifest)
+    
+    if scope_state.mode != "copy":
+        return  # symlinks can't drift
+    
+    for backend_name, bs in scope_state.clis.items():
+        for component_type, items in bs.installed.items():
+            for name, item in items.items():
+                p = Path(item.target)
+                if not p.exists() or p.is_symlink():
+                    continue
+                # File exists as regular file; compare sha
+                try:
+                    current_sha = sha256_of(p) if p.is_file() else None
+                    # For directories (skills), we'd need deeper compare — skip for now
+                    if current_sha and current_sha != item.sha:
+                        issues.append(Issue("drift", str(p),
+                            "Content differs from source. Local changes will be lost on update."))
+                except OSError:
+                    pass
+
+
+def check_stale(scope, scope_state, registry, issues, fix_actions):
+    """State-based check: files listed in state.json whose dist source is gone."""
+    from .doctor import Issue, FixAction
+    if scope_state is None:
+        return
+    
+    # Build lookup of what currently exists in dist for each backend
+    for backend_name, bs in scope_state.clis.items():
+        try:
+            backend = registry.get(backend_name)
+        except KeyError:
+            # Backend was removed entirely — everything is stale
+            for component_type, items in bs.installed.items():
+                for name, item in items.items():
+                    issues.append(Issue("stale", str(item.target),
+                        f"Backend '{backend_name}' no longer exists in agent-notes"))
+                    fix_actions.append(FixAction("DELETE", str(item.target), "stale"))
+            continue
+        
+        for component_type, items in bs.installed.items():
+            src_dir = installer.dist_source_for(backend, component_type)
+            if src_dir is None:
+                continue
+            for name, item in items.items():
+                # Check if this specific item's source still exists
+                if component_type == "config":
+                    config_fn = installer.config_filename_for(backend)
+                    if config_fn and (src_dir / config_fn).exists():
+                        continue  # Still exists
+                    issues.append(Issue("stale", str(item.target),
+                        f"Config file no longer built for {backend_name}"))
+                    fix_actions.append(FixAction("DELETE", str(item.target), "stale config"))
+                elif component_type == "skills":
+                    if (src_dir / name).is_dir():
+                        continue  # Still exists
+                    issues.append(Issue("stale", str(item.target),
+                        f"Skill '{name}' no longer exists in agent-notes"))
+                    fix_actions.append(FixAction("DELETE", str(item.target), "stale skill"))
+                else:
+                    # agents, rules, commands: files
+                    if (src_dir / name).exists():
+                        continue  # Still exists
+                    issues.append(Issue("stale", str(item.target),
+                        f"{component_type.title()} '{name}' no longer exists in agent-notes"))
+                    fix_actions.append(FixAction("DELETE", str(item.target), f"stale {component_type}"))

agent_notes/domain/__init__.py

@@ -0,0 +1,17 @@
+"""Domain model layer — pure data classes, no I/O, no agent_notes deps."""
+from .cli_backend import CLIBackend
+from .model import Model
+from .role import Role
+from .agent import AgentSpec
+from .skill import Skill
+from .rule import Rule
+from .state import State, ScopeState, BackendState, InstalledItem
+from .diagnostics import Issue, FixAction, ValidationError, ValidationWarning
+from .diff import ComponentDiff, StateDiff
+
+__all__ = [
+    "CLIBackend", "Model", "Role", "AgentSpec", "Skill", "Rule",
+    "State", "ScopeState", "BackendState", "InstalledItem",
+    "Issue", "FixAction", "ValidationError", "ValidationWarning",
+    "ComponentDiff", "StateDiff",
+]

agent_notes/domain/agent.py

@@ -0,0 +1,34 @@
+"""Agent domain type for agent metadata."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    """Agent configuration from agents.yaml."""
+    name: str
+    description: str
+    role: str
+    mode: str  # primary, subagent
+    color: Optional[str] = None
+    effort: Optional[str] = None  # low, medium, high
+    backends: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+    # backends is keyed by CLI backend name (e.g. "claude", "opencode", "copilot", ...).
+    # Each value is the per-backend override dict as declared in agents.yaml.
+    # Example: {"claude": {"exclude": True}, "opencode": {"mode": "subagent"}}
+    
+    def backend_config(self, backend_name: str) -> Dict[str, Any]:
+        """Return per-backend config for backend_name, or {} if none declared."""
+        return self.backends.get(backend_name, {}) or {}
+
+    def excluded_from(self, backend_name: str) -> bool:
+        """Return True if the agent is excluded from this backend's build.
+
+        A backend is excluded when its config has exclude: true. For backward
+        compat, also treat the legacy top-level 'claude_exclude' key as meaning
+        excluded-from-claude — the loader maps this into backends["claude"]["exclude"].
+        """
+        cfg = self.backend_config(backend_name)
+        return bool(cfg.get("exclude", False))

agent_notes/domain/cli_backend.py

@@ -0,0 +1,40 @@
+"""CLI backend dataclass — pure data model for CLI backend descriptors."""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class CLIBackend:
+    """Represents a single CLI backend loaded from YAML descriptor."""
+    
+    name: str                      # "claude"
+    label: str                     # "Claude Code"
+    global_home: Path              # expanded ~/.claude (Path object)
+    local_dir: str                 # ".claude"
+    layout: dict[str, str]         # {"agents": "agents/", ...}
+    features: dict[str, object]    # {"agents": True, "frontmatter": "claude", ...}
+    global_template: Optional[str] # "global-claude.md" or None
+    exclude_flag: Optional[str] = None    # "claude_exclude" or None
+    strip_memory_section: bool = False
+    settings_template: Optional[str] = None
+    accepted_providers: tuple[str, ...] = ()   # new
+
+    def supports(self, feature: str) -> bool:
+        """Return True if the backend has that feature enabled."""
+        val = self.features.get(feature)
+        return bool(val)
+
+    def local_path(self) -> Path:
+        """Return Path(self.local_dir) relative to cwd — caller decides absolute."""
+        return Path(self.local_dir)
+
+    def first_alias_for(self, model_aliases: dict[str, str]) -> Optional[tuple[str, str]]:
+        """Given a model's aliases dict, return (provider, alias) for the first
+        of self.accepted_providers that has an alias. None if no compat."""
+        for provider in self.accepted_providers:
+            if provider in model_aliases:
+                return (provider, model_aliases[provider])
+        return None

agent_notes/domain/diagnostics.py

@@ -0,0 +1,29 @@
+"""Diagnostics dataclasses — pure data models for issues and validation."""
+
+from __future__ import annotations
+
+
+class Issue:
+    def __init__(self, issue_type: str, file: str, message: str):
+        self.type = issue_type
+        self.file = file
+        self.message = message
+
+
+class FixAction:
+    def __init__(self, action: str, file: str, details: str):
+        self.action = action
+        self.file = file
+        self.details = details
+
+
+class ValidationError:
+    def __init__(self, file_path: str, message: str):
+        self.file_path = file_path
+        self.message = message
+
+
+class ValidationWarning:
+    def __init__(self, file_path: str, message: str):
+        self.file_path = file_path
+        self.message = message

agent_notes/domain/diff.py

@@ -0,0 +1,44 @@
+"""Diff dataclasses — pure data models for state comparison."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class ComponentDiff:
+    """Diff for one component type (agents, skills, rules, commands, config) within one backend."""
+    backend: str
+    component: str                       # "agents" | "skills" | "rules" | "commands" | "config" | "settings"
+    added: list[str] = field(default_factory=list)      # names/keys present in new, absent in old
+    removed: list[str] = field(default_factory=list)    # present in old, absent in new
+    modified: list[str] = field(default_factory=list)   # present in both, sha differs
+    unchanged: list[str] = field(default_factory=list)  # present in both, sha identical
+
+    def has_changes(self) -> bool:
+        return bool(self.added or self.removed or self.modified)
+
+    def change_count(self) -> int:
+        return len(self.added) + len(self.removed) + len(self.modified)
+
+
+@dataclass
+class StateDiff:
+    """Full diff between two State snapshots."""
+    old_version: Optional[str]
+    new_version: str
+    old_commit: Optional[str]
+    new_commit: str
+    added_backends: list[str]            # present in new, absent in old
+    removed_backends: list[str]          # present in old, absent in new
+    components: list[ComponentDiff]      # one per (backend, component-type) that has at least one of {added, removed, modified, unchanged}
+
+    def has_changes(self) -> bool:
+        return (
+            bool(self.added_backends) or
+            bool(self.removed_backends) or
+            any(c.has_changes() for c in self.components)
+        )
+
+    def total_changes(self) -> int:
+        return sum(c.change_count() for c in self.components)

agent_notes/domain/model.py

@@ -0,0 +1,27 @@
+"""Model dataclass — pure data model for model descriptors."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class Model:
+    id: str                          # "claude-opus-4-7"
+    label: str                       # "Claude Opus 4.7"
+    family: str                      # "claude", "kimi", "gpt"
+    model_class: str                 # "opus" | "sonnet" | "haiku" | "flash" | "pro"
+    aliases: dict[str, str]          # {"anthropic": "claude-opus-4-7", ...}
+    pricing: dict[str, float] = field(default_factory=dict)
+    capabilities: dict[str, bool] = field(default_factory=dict)
+
+    def has_alias_for(self, provider: str) -> bool:
+        return provider in self.aliases
+
+    def resolve_for_providers(self, providers: list[str]) -> Optional[tuple[str, str]]:
+        """Given a CLI's ordered accepted_providers list, return (provider, resolved_id)
+        for the first provider that has an alias for this model. None if no compat."""
+        for provider in providers:
+            if provider in self.aliases:
+                return (provider, self.aliases[provider])
+        return None

agent_notes/domain/role.py

@@ -0,0 +1,13 @@
+"""Role dataclass — pure data model for role descriptors."""
+
+from __future__ import annotations
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Role:
+    name: str
+    label: str
+    description: str
+    typical_class: str
+    color: str = ""

agent_notes/domain/rule.py

@@ -0,0 +1,13 @@
+"""Rule domain type."""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Rule:
+    """Rule from data/rules/*.md."""
+    name: str     # filename stem
+    path: Path    # full path
+    title: str    # first # heading in the file, or name

agent_notes/domain/skill.py

@@ -0,0 +1,15 @@
+"""Skill domain type."""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class Skill:
+    """Skill from data/skills/<name>/."""
+    name: str              # directory name
+    path: Path             # full path to skill dir
+    description: str       # from SKILL.md frontmatter or first line
+    group: Optional[str] = None   # from SKILL.md frontmatter (if present)

agent_notes/domain/state.py

@@ -0,0 +1,46 @@
+"""State dataclasses — pure data models for installation state."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class MemoryConfig:
+    backend: str = "local"   # "obsidian" | "local" | "none"
+    path: str = ""           # vault root (obsidian) or memory dir (local). empty = use default
+
+
+@dataclass
+class InstalledItem:
+    sha: str
+    target: str
+    mode: str
+
+
+@dataclass
+class BackendState:
+    """Installation manifest for one CLI within one scope."""
+    role_models: dict[str, str] = field(default_factory=dict)   # role_name -> model_id
+    installed: dict[str, dict[str, InstalledItem]] = field(default_factory=dict)
+    # installed is a dict of component_type -> {filename/key -> InstalledItem}
+    # e.g. installed["agents"]["lead.md"] = InstalledItem(...)
+
+
+@dataclass
+class ScopeState:
+    """One install scope: either the single global install or one local-project install."""
+    installed_at: str = ""
+    updated_at: str = ""
+    mode: str = "symlink"
+    clis: dict[str, BackendState] = field(default_factory=dict)
+
+
+@dataclass
+class State:
+    """Full agent-notes state."""
+    source_path: str = ""
+    source_commit: str = ""
+    global_install: Optional[ScopeState] = None         # JSON key is "global"
+    local_installs: dict[str, ScopeState] = field(default_factory=dict)  # JSON key is "local"
+    memory: MemoryConfig = field(default_factory=MemoryConfig)

agent_notes/install_state.py

@@ -0,0 +1,11 @@
+"""Build and read State objects during install/uninstall flows."""
+
+# Re-export everything from services
+from .services.install_state_builder import build_install_state, git_head_short, _get_target_path
+from .services.state_store import record_install_state, load_current_state, remove_install_state, clear_state
+
+# Backward compatibility
+__all__ = [
+    'build_install_state', 'git_head_short', 'record_install_state', 
+    'load_current_state', 'remove_install_state', 'clear_state'
+]

agent_notes/registries/__init__.py

@@ -0,0 +1,16 @@
+"""Registries — load YAML/Markdown descriptors into typed in-memory indexes."""
+from .cli_registry import CLIRegistry, load_registry, default_registry
+from .model_registry import ModelRegistry, load_model_registry, default_model_registry
+from .role_registry import RoleRegistry, load_role_registry, default_role_registry
+from .agent_registry import AgentRegistry, load_agent_registry, default_agent_registry
+from .skill_registry import SkillRegistry, load_skill_registry, default_skill_registry
+from .rule_registry import RuleRegistry, load_rule_registry, default_rule_registry
+
+__all__ = [
+    "CLIRegistry", "load_registry", "default_registry",
+    "ModelRegistry", "load_model_registry", "default_model_registry",
+    "RoleRegistry", "load_role_registry", "default_role_registry",
+    "AgentRegistry", "load_agent_registry", "default_agent_registry",
+    "SkillRegistry", "load_skill_registry", "default_skill_registry",
+    "RuleRegistry", "load_rule_registry", "default_rule_registry",
+]

agent_notes/registries/_base.py

@@ -0,0 +1,46 @@
+"""Shared helpers used by all registries."""
+from __future__ import annotations
+from pathlib import Path
+from typing import Any
+import yaml
+
+
+def load_yaml_file(path: Path) -> dict[str, Any]:
+    """Load a single YAML file, wrapping errors with the filename."""
+    try:
+        return yaml.safe_load(path.read_text()) or {}
+    except yaml.YAMLError as e:
+        raise ValueError(f"Invalid YAML in {path}: {e}")
+    except Exception as e:
+        raise ValueError(f"Failed to read {path}: {e}")
+
+
+def require_fields(
+    data: dict,
+    required: list[str],
+    source: Path,
+    msg_template: str = "Missing required field '{field}' in {path}",
+) -> None:
+    """Validate that required top-level fields are present; raise ValueError on miss.
+
+    msg_template supports {field}, {filename} (basename), and {path} (full path).
+    """
+    for f in required:
+        if f not in data:
+            msg = msg_template.format(field=f, filename=source.name, path=source)
+            raise ValueError(msg)
+
+
+def load_yaml_dir(dir_path: Path, required_fields: list[str] | None = None) -> list[tuple[Path, dict]]:
+    """Load every *.yaml in dir_path (sorted). Returns list of (path, data) pairs.
+    Raises ValueError if dir missing or any YAML invalid.
+    """
+    if not dir_path.exists():
+        raise ValueError(f"Registry directory not found: {dir_path}")
+    items = []
+    for yaml_file in sorted(dir_path.glob("*.yaml")):
+        data = load_yaml_file(yaml_file)
+        if required_fields:
+            require_fields(data, required_fields, yaml_file)
+        items.append((yaml_file, data))
+    return items