agentworks-cli 0.2.1__py3-none-any.whl

agentworks/agents/templates.py

@@ -0,0 +1,145 @@
+"""Agent template resolution and processing.
+
+Handles inheritance (depth-first, left-to-right), merge rules, and the
+built-in default template fallback. Follows the same pattern as VM and
+workspace templates.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentworks.config import AgentTemplate, Config
+
+
+@dataclass
+class ResolvedAgentTemplate:
+    """A fully resolved agent template with all inheritance applied."""
+
+    name: str
+    shell: str = "bash"
+    git_credentials: list[str] = field(default_factory=list)
+    user_install_commands: list[str] = field(default_factory=list)
+    dotfiles_source: str | None = None
+    dotfiles_destination: str = "~/.dotfiles"
+    dotfiles_install_cmd: str = "./install.sh"
+    mise_activate: bool = True
+    mise_packages: list[str] = field(default_factory=list)
+    mise_lockfile: str | None = None
+    mise_allow_unlocked: bool = False
+    mise_install_before: str = "7d"
+    mise_prune_on_reinit: bool = True
+    nerf_install_claude_plugin: bool = False
+    claude_marketplaces: list[str] = field(default_factory=list)
+    claude_plugins: list[str] = field(default_factory=list)
+
+
+def resolve_from_dict(
+    templates: dict[str, AgentTemplate],
+    template_name: str | None = None,
+) -> ResolvedAgentTemplate:
+    """Resolve an agent template from a templates dict (no Config required)."""
+    if template_name is not None and template_name != "default":
+        if template_name not in templates:
+            msg = f"Unknown agent template: {template_name}"
+            raise ValueError(msg)
+        return _resolve(templates, template_name)
+
+    if "default" in templates:
+        return _resolve(templates, "default")
+
+    return ResolvedAgentTemplate(name="default")
+
+
+def resolve_template(config: Config, template_name: str | None = None) -> ResolvedAgentTemplate:
+    """Resolve an agent template by name, applying inheritance."""
+    return resolve_from_dict(config.agent_templates, template_name)
+
+
+def _resolve(templates: dict[str, AgentTemplate], name: str) -> ResolvedAgentTemplate:
+    """Depth-first, left-to-right resolution."""
+    if name not in templates:
+        return ResolvedAgentTemplate(name=name)
+
+    tmpl = templates[name]
+    result = ResolvedAgentTemplate(name=name)
+
+    for parent_name in tmpl.inherits:
+        parent = _resolve(templates, parent_name)
+        _merge(result, parent)
+
+    _merge_template(result, tmpl)
+    result.name = name
+    return result
+
+
+def _append_dedupe(target: list[str], source: list[str]) -> list[str]:
+    """Append source items to target, skipping dupes. Preserves order."""
+    seen = set(target)
+    result = list(target)
+    for item in source:
+        if item not in seen:
+            seen.add(item)
+            result.append(item)
+    return result
+
+
+def _merge_map(target: dict[str, str], source: dict[str, str]) -> dict[str, str]:
+    """Merge source map into target. Source wins on key collision."""
+    return {**target, **source}
+
+
+def _merge(target: ResolvedAgentTemplate, source: ResolvedAgentTemplate) -> None:
+    """Merge source into target. Scalars: source wins. Lists: append with dedupe."""
+    target.shell = source.shell
+    target.git_credentials = _append_dedupe(target.git_credentials, source.git_credentials)
+    target.user_install_commands = _append_dedupe(target.user_install_commands, source.user_install_commands)
+    target.dotfiles_source = source.dotfiles_source
+    target.dotfiles_destination = source.dotfiles_destination
+    target.dotfiles_install_cmd = source.dotfiles_install_cmd
+    target.mise_activate = source.mise_activate
+    target.mise_packages = _append_dedupe(target.mise_packages, source.mise_packages)
+    target.mise_lockfile = source.mise_lockfile
+    target.mise_allow_unlocked = source.mise_allow_unlocked
+    target.mise_install_before = source.mise_install_before
+    target.mise_prune_on_reinit = source.mise_prune_on_reinit
+    target.nerf_install_claude_plugin = source.nerf_install_claude_plugin
+    target.claude_marketplaces = _append_dedupe(target.claude_marketplaces, source.claude_marketplaces)
+    target.claude_plugins = _append_dedupe(target.claude_plugins, source.claude_plugins)
+
+
+def _merge_template(target: ResolvedAgentTemplate, tmpl: AgentTemplate) -> None:
+    """Merge a raw AgentTemplate into a ResolvedAgentTemplate. None = not set, skip.
+    Scalars: child overrides. Lists: append with dedupe."""
+    if tmpl.shell is not None:
+        target.shell = tmpl.shell
+    if tmpl.git_credentials is not None:
+        target.git_credentials = _append_dedupe(target.git_credentials, tmpl.git_credentials)
+    if tmpl.user_install_commands is not None:
+        target.user_install_commands = _append_dedupe(target.user_install_commands, tmpl.user_install_commands)
+    if tmpl.dotfiles_source is not None:
+        target.dotfiles_source = tmpl.dotfiles_source
+    if tmpl.dotfiles_destination is not None:
+        target.dotfiles_destination = tmpl.dotfiles_destination
+    if tmpl.dotfiles_install_cmd is not None:
+        target.dotfiles_install_cmd = tmpl.dotfiles_install_cmd
+    if tmpl.mise_activate is not None:
+        target.mise_activate = tmpl.mise_activate
+    if tmpl.mise_packages is not None:
+        target.mise_packages = _append_dedupe(target.mise_packages, tmpl.mise_packages)
+    if tmpl.mise_lockfile is not None:
+        target.mise_lockfile = tmpl.mise_lockfile
+    if tmpl.mise_allow_unlocked is not None:
+        target.mise_allow_unlocked = tmpl.mise_allow_unlocked
+    if tmpl.mise_install_before is not None:
+        target.mise_install_before = tmpl.mise_install_before
+    if tmpl.mise_prune_on_reinit is not None:
+        target.mise_prune_on_reinit = tmpl.mise_prune_on_reinit
+    if tmpl.nerf_install_claude_plugin is not None:
+        target.nerf_install_claude_plugin = tmpl.nerf_install_claude_plugin
+    if tmpl.claude_marketplaces is not None:
+        target.claude_marketplaces = _append_dedupe(target.claude_marketplaces, tmpl.claude_marketplaces)
+    if tmpl.claude_plugins is not None:
+        target.claude_plugins = _append_dedupe(target.claude_plugins, tmpl.claude_plugins)

agentworks/catalog.py

@@ -0,0 +1,264 @@
+"""Built-in catalog loading, merging, and resolution.
+
+The catalog provides named entries for apt sources, apt packages, system
+install commands, and user install commands. A built-in catalog ships with
+the package; custom config entries override built-in entries on name collision.
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentworks.config import Config
+
+
+class CatalogError(Exception):
+    """Raised when the catalog is invalid."""
+
+
+# -- Data classes --------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class AptSourceEntry:
+    name: str
+    description: str
+    key_url: str
+    key_path: str
+    source: str
+    source_file: str
+    key_dearmor: bool = False
+
+
+@dataclass(frozen=True)
+class AptPackageEntry:
+    name: str
+    description: str
+    apt: list[str]
+    apt_sources: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class SystemInstallCommandEntry:
+    name: str
+    description: str
+    command: str
+    path: list[str] = field(default_factory=list)
+    test_exec: str | None = None
+    test_file: str | None = None
+    test_dir: str | None = None
+
+
+@dataclass(frozen=True)
+class UserInstallCommandEntry:
+    name: str
+    description: str
+    command: str
+    path: list[str] = field(default_factory=list)
+    test_exec: str | None = None
+    test_file: str | None = None
+    test_dir: str | None = None
+
+
+@dataclass(frozen=True)
+class ResolvedCatalog:
+    apt_sources: dict[str, AptSourceEntry]
+    apt_packages: dict[str, AptPackageEntry]
+    system_install_commands: dict[str, SystemInstallCommandEntry]
+    user_install_commands: dict[str, UserInstallCommandEntry]
+
+
+# -- Loading -------------------------------------------------------------------
+
+_BUILTIN_CATALOG_PATH = Path(__file__).parent / "catalog.toml"
+
+# source_file must be a simple filename (no slashes, no shell metacharacters)
+_SAFE_FILENAME_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._-]*$")
+
+
+def _require_field(data: dict[str, object], key: str, context: str) -> object:
+    if key not in data:
+        raise CatalogError(f"{context}.{key} is required")
+    return data[key]
+
+
+def _require_list(data: dict[str, object], key: str, context: str) -> list[str]:
+    val = data.get(key, [])
+    if not isinstance(val, list):
+        raise CatalogError(f"{context}.{key} must be a list")
+    return [str(item) for item in val]
+
+
+def _load_apt_sources(raw: dict[str, object]) -> dict[str, AptSourceEntry]:
+    entries: dict[str, AptSourceEntry] = {}
+    for name, data in raw.items():
+        if not isinstance(data, dict):
+            raise CatalogError(f"apt_sources.{name} must be a table")
+        ctx = f"apt_sources.{name}"
+        source_file = str(_require_field(data, "source_file", ctx))
+        if not _SAFE_FILENAME_RE.match(source_file):
+            raise CatalogError(f"{ctx}.source_file must be a simple filename, got: {source_file}")
+        entries[name] = AptSourceEntry(
+            name=name,
+            description=str(data.get("description", "")),
+            key_url=str(_require_field(data, "key_url", ctx)),
+            key_path=str(_require_field(data, "key_path", ctx)),
+            source=str(_require_field(data, "source", ctx)),
+            source_file=source_file,
+            key_dearmor=bool(data.get("key_dearmor", False)),
+        )
+    return entries
+
+
+def _load_apt_packages(raw: dict[str, object]) -> dict[str, AptPackageEntry]:
+    entries: dict[str, AptPackageEntry] = {}
+    for name, data in raw.items():
+        if not isinstance(data, dict):
+            raise CatalogError(f"apt_packages.{name} must be a table")
+        ctx = f"apt_packages.{name}"
+        entries[name] = AptPackageEntry(
+            name=name,
+            description=str(data.get("description", "")),
+            apt=_require_list(data, "apt", ctx),
+            apt_sources=_require_list(data, "apt_sources", ctx) if "apt_sources" in data else [],
+        )
+    return entries
+
+
+def _load_test_fields(data: dict[str, object], ctx: str) -> dict[str, str | None]:
+    """Load and validate test_exec/test_file/test_dir fields. At most one may be set."""
+    if "test" in data:
+        raise CatalogError(f"{ctx}: 'test' is not a valid field. Use 'test_exec', 'test_file', or 'test_dir'.")
+    fields: dict[str, str | None] = {}
+    for key in ("test_exec", "test_file", "test_dir"):
+        raw = str(data[key]).strip() if key in data else None
+        fields[key] = raw if raw else None
+    set_count = sum(1 for v in fields.values() if v is not None)
+    if set_count > 1:
+        raise CatalogError(f"{ctx}: at most one of test_exec, test_file, test_dir may be set")
+    return fields
+
+
+def _load_system_commands(raw: dict[str, object]) -> dict[str, SystemInstallCommandEntry]:
+    entries: dict[str, SystemInstallCommandEntry] = {}
+    for name, data in raw.items():
+        if not isinstance(data, dict):
+            raise CatalogError(f"system_install_commands.{name} must be a table")
+        ctx = f"system_install_commands.{name}"
+        tests = _load_test_fields(data, ctx)
+        entries[name] = SystemInstallCommandEntry(
+            name=name,
+            description=str(data.get("description", "")),
+            command=str(_require_field(data, "command", ctx)),
+            path=_require_list(data, "path", ctx) if "path" in data else [],
+            **tests,
+        )
+    return entries
+
+
+def _load_user_commands(raw: dict[str, object]) -> dict[str, UserInstallCommandEntry]:
+    entries: dict[str, UserInstallCommandEntry] = {}
+    for name, data in raw.items():
+        if not isinstance(data, dict):
+            raise CatalogError(f"user_install_commands.{name} must be a table")
+        ctx = f"user_install_commands.{name}"
+        tests = _load_test_fields(data, ctx)
+        entries[name] = UserInstallCommandEntry(
+            name=name,
+            description=str(data.get("description", "")),
+            command=str(_require_field(data, "command", ctx)),
+            path=_require_list(data, "path", ctx) if "path" in data else [],
+            **tests,
+        )
+    return entries
+
+
+def _load_toml(path: Path) -> dict[str, object]:
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def load_builtin_catalog() -> ResolvedCatalog:
+    """Load the built-in catalog bundled with the package."""
+    if not _BUILTIN_CATALOG_PATH.exists():
+        raise CatalogError(f"Built-in catalog not found: {_BUILTIN_CATALOG_PATH}")
+
+    data = _load_toml(_BUILTIN_CATALOG_PATH)
+    return _parse_catalog(data)
+
+
+def _get_section(data: dict[str, object], key: str) -> dict[str, object]:
+    """Extract a TOML table section, returning an empty dict if missing or wrong type."""
+    val = data.get(key, {})
+    if not isinstance(val, dict):
+        raise CatalogError(f"Catalog section '{key}' must be a table, got {type(val).__name__}")
+    return val
+
+
+def _parse_catalog(data: dict[str, object]) -> ResolvedCatalog:
+    return ResolvedCatalog(
+        apt_sources=_load_apt_sources(_get_section(data, "apt_sources")),
+        apt_packages=_load_apt_packages(_get_section(data, "apt_packages")),
+        system_install_commands=_load_system_commands(_get_section(data, "system_install_commands")),
+        user_install_commands=_load_user_commands(_get_section(data, "user_install_commands")),
+    )
+
+
+def load_catalog(config: Config) -> ResolvedCatalog:
+    """Load and merge built-in + custom catalog entries.
+
+    Custom entries override built-in entries with the same name.
+    Cross-references (apt_sources in apt_packages) are validated.
+    """
+    builtin = load_builtin_catalog()
+
+    # Parse custom entries (raw dicts from config) into typed entries
+    custom_apt_sources = _load_apt_sources(config.apt_sources)
+    custom_apt_packages = _load_apt_packages(config.apt_packages)
+    custom_system_cmds = _load_system_commands(config.system_install_commands)
+    custom_user_install_cmds = _load_user_commands(config.user_install_commands)
+
+    # Merge: custom wins on name collision
+    apt_sources = {**builtin.apt_sources, **custom_apt_sources}
+    apt_packages = {**builtin.apt_packages, **custom_apt_packages}
+    system_cmds = {**builtin.system_install_commands, **custom_system_cmds}
+    user_install_cmds = {**builtin.user_install_commands, **custom_user_install_cmds}
+
+    catalog = ResolvedCatalog(
+        apt_sources=apt_sources,
+        apt_packages=apt_packages,
+        system_install_commands=system_cmds,
+        user_install_commands=user_install_cmds,
+    )
+
+    _validate_references(catalog)
+    return catalog
+
+
+def _validate_references(catalog: ResolvedCatalog) -> None:
+    """Validate cross-references within the catalog."""
+    for name, pkg in catalog.apt_packages.items():
+        for src_name in pkg.apt_sources:
+            if src_name not in catalog.apt_sources:
+                raise CatalogError(f"apt_packages.{name} references unknown apt source: {src_name}")
+
+
+def validate_selections(config: Config, catalog: ResolvedCatalog) -> None:
+    """Validate that vm.config and agent.config selections resolve in the catalog."""
+    for ref in config.vm.apt_packages:
+        if ref not in catalog.apt_packages:
+            raise CatalogError(f"vm.config.apt_packages references unknown entry: {ref}")
+    for ref in config.vm.system_install_commands:
+        if ref not in catalog.system_install_commands:
+            raise CatalogError(f"vm.config.system_install_commands references unknown entry: {ref}")
+    for ref in config.admin.user_install_commands:
+        if ref not in catalog.user_install_commands:
+            raise CatalogError(f"admin.config.user_install_commands references unknown entry: {ref}")
+    for ref in config.agent.user_install_commands:
+        if ref not in catalog.user_install_commands:
+            raise CatalogError(f"agent.config.user_install_commands references unknown entry: {ref}")

agentworks/catalog.toml

@@ -0,0 +1,131 @@
+# Built-in catalog of apt sources, apt packages, system install commands, and
+# user install commands. This file is read-only at runtime and ships with the
+# agentworks package. Users can override entries by defining entries with the
+# same name in their config.toml.
+
+# -- Apt sources ---------------------------------------------------------------
+# Third-party apt repositories. The {arch} placeholder is resolved at install
+# time via `dpkg --print-architecture` (amd64 or arm64).
+
+[apt_sources.github-cli]
+description = "GitHub CLI official apt repository"
+key_url = "https://cli.github.com/packages/githubcli-archive-keyring.gpg"
+key_path = "/etc/apt/keyrings/githubcli-archive-keyring.gpg"
+source = "deb [arch={arch} signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main"
+source_file = "github-cli.list"
+
+[apt_sources.hashicorp]
+description = "HashiCorp official apt repository"
+key_url = "https://apt.releases.hashicorp.com/gpg"
+key_path = "/etc/apt/keyrings/hashicorp-archive-keyring.gpg"
+key_dearmor = true
+source = "deb [arch={arch} signed-by=/etc/apt/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com bookworm main"
+source_file = "hashicorp.list"
+
+[apt_sources.nodesource-v22]
+description = "NodeSource Node.js 22.x apt repository"
+key_url = "https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key"
+key_path = "/etc/apt/keyrings/nodesource.gpg"
+key_dearmor = true
+source = "deb [arch={arch} signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main"
+source_file = "nodesource.list"
+
+[apt_sources.tofuutils-tenv]
+description = "tofuutils tenv apt repository (Cloudsmith)"
+key_url = "https://dl.cloudsmith.io/public/tofuutils/tenv/gpg.8ACD4386ADD982F6.key"
+key_path = "/etc/apt/keyrings/tofuutils-tenv-archive-keyring.gpg"
+key_dearmor = true
+source = "deb [signed-by=/etc/apt/keyrings/tofuutils-tenv-archive-keyring.gpg] https://dl.cloudsmith.io/public/tofuutils/tenv/deb/debian bookworm main"
+source_file = "tofuutils-tenv.list"
+
+# -- Apt packages --------------------------------------------------------------
+# Named sets of apt packages with optional apt source dependencies.
+
+[apt_packages.gh]
+description = "GitHub CLI"
+apt_sources = ["github-cli"]
+apt = ["gh"]
+
+[apt_packages.terraform]
+description = "HashiCorp Terraform"
+apt_sources = ["hashicorp"]
+apt = ["terraform"]
+
+[apt_packages.nodejs]
+description = "Node.js 22.x via NodeSource"
+apt_sources = ["nodesource-v22"]
+apt = ["nodejs"]
+
+[apt_packages.tenv]
+description = "tenv (Terraform/OpenTofu/Terragrunt version manager)"
+apt_sources = ["tofuutils-tenv"]
+apt = ["tenv"]
+
+# -- System install commands ---------------------------------------------------
+# Shell commands that install system-wide tooling (run once per VM).
+#
+# These may be re-run (e.g. during reinit) so they really should be idempotent.
+#
+# Optional checks can be defined to short-circuit installation if the tool is already present.
+# Installed-check fields (at most one per entry):
+#   test_exec: skip if this command is on PATH (uses `command -v`)
+#   test_file: skip if this file exists
+#   test_dir:  skip if this directory exists
+
+[system_install_commands.az-cli]
+description = "Azure CLI"
+command = "curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash"
+test_exec = "az"
+
+# -- User install commands -----------------------------------------------------
+# Shell commands that install per-user tooling (run for each user).
+#
+# These may be re-run (e.g. during reinit) so they really should be idempotent.
+#
+# Optional checks can be defined to short-circuit installation if the tool is already present.
+# Installed-check fields (at most one per entry):
+#   test_exec: skip if this command is on PATH (uses `command -v`)
+#   test_file: skip if this file exists (~ resolves to the user's home)
+#   test_dir:  skip if this directory exists (~ resolves to the user's home)
+#
+# path: optional list of directories to add to the user's PATH. This is only necessary if the install
+# command doesn't modify shell files to update the PATH automatically.
+
+# -- User install commands -----------------------------------------------------
+
+[user_install_commands.oh-my-zsh]
+description = "Oh My Zsh"
+command = "sh -c \"$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)\" -- --unattended"
+test_dir = "~/.oh-my-zsh"
+
+[user_install_commands.bun]
+description = "Bun JavaScript runtime"
+command = "curl -fsSL https://bun.sh/install | bash"
+test_exec = "bun"
+
+[user_install_commands.fnm]
+description = "Fast Node Manager"
+command = "curl -fsSL https://fnm.vercel.app/install | bash"
+test_exec = "fnm"
+
+[user_install_commands.nvm]
+description = "Node Version Manager"
+command = "curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash"
+test_file = "~/.nvm/nvm.sh"
+
+[user_install_commands.claude]
+description = "Claude Code CLI"
+command = "curl -fsSL https://claude.ai/install.sh | bash"
+path = ["~/.local/bin"]
+test_exec = "claude"
+
+[user_install_commands.starship]
+description = "Starship cross-shell prompt"
+command = "curl -sS https://starship.rs/install.sh | sh -s -- -y -b ~/.local/bin"
+path = ["~/.local/bin"]
+test_exec = "starship"
+
+[user_install_commands.uv]
+description = "uv Python version manager"
+command = "curl -LsSf https://astral.sh/uv/install.sh | sh"
+test_exec = "uv"