agentworks-cli 0.2.1__py3-none-any.whl

agentworks/vms/templates.py

@@ -0,0 +1,152 @@
+"""VM 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 workspace
+templates.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from agentworks.config import Config, VMTemplate
+
+
+@dataclass
+class ResolvedVMTemplate:
+    """A fully resolved VM template with all inheritance applied."""
+
+    name: str
+    # Provisioning
+    cpus: int = 4
+    memory: int = 8
+    disk: int = 50
+    azure_vm_size: str = "Standard_B2s"
+    swap: int = 4
+    # System-wide init
+    apt: list[str] = field(default_factory=list)
+    apt_packages: list[str] = field(default_factory=list)
+    snap: list[str] = field(default_factory=list)
+    system_install_commands: list[str] = field(default_factory=list)
+    # Nerf tools
+    nerf_build_claude_plugin: bool = False
+    skip_nerf_defaults: bool = False
+    nerf_addl_manifests: list[Path] = field(default_factory=list)
+    nerf_home_dir: str = "/opt/agentworks/nerf"
+
+
+def resolve_from_dict(
+    templates: dict[str, VMTemplate],
+    template_name: str | None = None,
+) -> ResolvedVMTemplate:
+    """Resolve a VM template from a templates dict (no Config required).
+
+    Used during config loading to resolve the default template eagerly.
+    """
+    if template_name is not None and template_name != "default":
+        if template_name not in templates:
+            msg = f"Unknown VM template: {template_name}"
+            raise ValueError(msg)
+        return _resolve_from_dict(templates, template_name)
+
+    if "default" in templates:
+        return _resolve_from_dict(templates, "default")
+
+    return ResolvedVMTemplate(name="default")
+
+
+def _resolve_from_dict(templates: dict[str, VMTemplate], name: str) -> ResolvedVMTemplate:
+    """Depth-first resolution using a templates dict."""
+    if name not in templates:
+        # Implicit default: return built-in defaults
+        return ResolvedVMTemplate(name=name)
+
+    tmpl = templates[name]
+    result = ResolvedVMTemplate(name=name)
+
+    for parent_name in tmpl.inherits:
+        parent = _resolve_from_dict(templates, parent_name)
+        _merge(result, parent)
+
+    _merge_template(result, tmpl)
+    result.name = name
+    return result
+
+
+def resolve_template(config: Config, template_name: str | None = None) -> ResolvedVMTemplate:
+    """Resolve a VM template by name, applying inheritance.
+
+    Selection order:
+    1. Explicit template_name
+    2. "default" template if it exists
+    3. Built-in default template
+    """
+    return resolve_from_dict(config.vm_templates, template_name)
+
+
+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: ResolvedVMTemplate, source: ResolvedVMTemplate) -> None:
+    """Merge source into target. Scalars: source wins. Lists: append with dedupe."""
+    target.cpus = source.cpus
+    target.memory = source.memory
+    target.disk = source.disk
+    target.azure_vm_size = source.azure_vm_size
+    target.swap = source.swap
+    target.apt = _append_dedupe(target.apt, source.apt)
+    target.apt_packages = _append_dedupe(target.apt_packages, source.apt_packages)
+    target.snap = _append_dedupe(target.snap, source.snap)
+    target.system_install_commands = _append_dedupe(target.system_install_commands, source.system_install_commands)
+    target.nerf_build_claude_plugin = source.nerf_build_claude_plugin
+    target.skip_nerf_defaults = source.skip_nerf_defaults
+    target.nerf_addl_manifests = list(source.nerf_addl_manifests)
+    target.nerf_home_dir = source.nerf_home_dir
+
+
+def _merge_template(target: ResolvedVMTemplate, tmpl: VMTemplate) -> None:
+    """Merge a raw VMTemplate into a ResolvedVMTemplate. None = not set, skip.
+    Scalars: child overrides. Lists: append with dedupe."""
+    if tmpl.cpus is not None:
+        target.cpus = tmpl.cpus
+    if tmpl.memory is not None:
+        target.memory = tmpl.memory
+    if tmpl.disk is not None:
+        target.disk = tmpl.disk
+    if tmpl.azure_vm_size is not None:
+        target.azure_vm_size = tmpl.azure_vm_size
+    if tmpl.swap is not None:
+        target.swap = tmpl.swap
+    if tmpl.apt is not None:
+        target.apt = _append_dedupe(target.apt, tmpl.apt)
+    if tmpl.apt_packages is not None:
+        target.apt_packages = _append_dedupe(target.apt_packages, tmpl.apt_packages)
+    if tmpl.snap is not None:
+        target.snap = _append_dedupe(target.snap, tmpl.snap)
+    if tmpl.system_install_commands is not None:
+        target.system_install_commands = _append_dedupe(target.system_install_commands, tmpl.system_install_commands)
+    if tmpl.nerf_build_claude_plugin is not None:
+        target.nerf_build_claude_plugin = tmpl.nerf_build_claude_plugin
+    if tmpl.skip_nerf_defaults is not None:
+        target.skip_nerf_defaults = tmpl.skip_nerf_defaults
+    if tmpl.nerf_addl_manifests is not None:
+        target.nerf_addl_manifests = list(tmpl.nerf_addl_manifests)
+    if tmpl.nerf_home_dir is not None:
+        target.nerf_home_dir = tmpl.nerf_home_dir

agentworks/workspaces/backends/local.py

@@ -0,0 +1,119 @@
+"""Local workspace backend -- operations directly on the host filesystem."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from agentworks import output
+from agentworks.workspaces.tmuxinator import generate_config
+
+if TYPE_CHECKING:
+    from agentworks.config import Config
+    from agentworks.workspaces.templates import ResolvedTemplate
+
+
+def create_local_workspace(
+    config: Config,
+    ws_name: str,
+    template: ResolvedTemplate,
+) -> str:
+    """Create a local workspace. Returns the workspace path.
+
+    Errors if the workspace directory already exists.
+    """
+    workspace_dir = config.paths.local_workspaces / ws_name
+    workspace_path = str(workspace_dir)
+
+    if workspace_dir.exists():
+        raise output.WorkspaceError(
+            f"directory {workspace_path} already exists.\nRemove it manually or choose a different name."
+        )
+
+    # Git clone or just create directory
+    if template.repo:
+        output.info(f"Cloning {template.repo}...")
+        try:
+            result = subprocess.run(
+                ["git", "clone", template.repo, workspace_path],
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=300,
+            )
+        except subprocess.TimeoutExpired:
+            raise output.WorkspaceError("git clone timed out after 5 minutes") from None
+        if result.returncode != 0:
+            hint = ""
+            if template.repo.startswith("https://"):
+                hint = (
+                    "\nHint: HTTPS repo URLs require credentials. "
+                    "For private repos, use an SSH URL (git@...) so "
+                    "your SSH key provides authentication."
+                )
+            raise output.WorkspaceError(f"git clone failed: {result.stderr.strip()}{hint}")
+    else:
+        workspace_dir.mkdir(parents=True)
+
+    # Tmuxinator config (no agents on local workspaces)
+    if template.tmuxinator:
+        tmux_config = generate_config(ws_name, workspace_path)
+        tmux_file = workspace_dir / ".tmuxinator.yml"
+        tmux_file.write_text(tmux_config)
+
+        # Symlink for tmuxinator to find it by console session name
+        from agentworks.workspaces.tmuxinator import console_session_name
+
+        session = console_session_name(ws_name)
+        tmux_config_dir = Path.home() / ".config" / "tmuxinator"
+        tmux_config_dir.mkdir(parents=True, exist_ok=True)
+        link = tmux_config_dir / f"{session}.yml"
+        link.unlink(missing_ok=True)
+        link.symlink_to(tmux_file)
+
+    return workspace_path
+
+
+def shell_local_workspace(
+    workspace_path: str,
+) -> None:
+    """Open a plain shell into a local workspace."""
+    shell = os.environ.get("SHELL", "/bin/sh")
+    os.chdir(workspace_path)
+    os.execlp(shell, shell, "-l")
+
+
+def console_local_workspace(
+    ws_name: str,
+    *,
+    recreate: bool = False,
+) -> None:
+    """Open the workspace console (tmuxinator) for a local workspace."""
+    import subprocess
+
+    from agentworks.workspaces.tmuxinator import console_session_name
+
+    session = console_session_name(ws_name)
+
+    if recreate:
+        subprocess.run(["tmux", "kill-session", "-t", session], capture_output=True)  # noqa: S603, S607
+
+    os.execlp("tmuxinator", "tmuxinator", "start", session)
+
+
+def delete_local_workspace(ws_name: str, workspace_path: str) -> None:
+    """Delete a local workspace directory."""
+    ws_dir = Path(workspace_path)
+    if ws_dir.exists():
+        shutil.rmtree(ws_dir)
+
+    # Remove tmuxinator symlink
+    from agentworks.workspaces.tmuxinator import console_session_name
+
+    session = console_session_name(ws_name)
+    link = Path.home() / ".config" / "tmuxinator" / f"{session}.yml"
+    link.unlink(missing_ok=True)

agentworks/workspaces/backends/vm.py

@@ -0,0 +1,175 @@
+"""VM workspace backend -- operations via SSH to a VM."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TYPE_CHECKING
+
+from agentworks import output
+from agentworks.ssh import admin_exec_target
+from agentworks.workspaces.tmuxinator import console_session_name, generate_config
+
+if TYPE_CHECKING:
+    from agentworks.config import Config
+    from agentworks.db import VMRow
+    from agentworks.ssh import SSHLogger
+    from agentworks.workspaces.templates import ResolvedTemplate
+
+
+def create_vm_workspace(
+    vm: VMRow,
+    config: Config,
+    ws_name: str,
+    template: ResolvedTemplate,
+    *,
+    logger: SSHLogger | None = None,
+) -> str:
+    """Create a workspace on a VM. Returns the remote workspace path.
+
+    Errors if the workspace directory already exists on the VM.
+    """
+    assert vm.tailscale_host is not None
+    target = admin_exec_target(vm, config, logger=logger)
+
+    workspace_path = f"{config.paths.vm_workspaces}/{ws_name}"
+    ws_group = f"ws--{ws_name}"
+
+    # Refuse to create if directory already exists
+    exists = target.run(f"test -d {workspace_path}", check=False, timeout=10)
+    if exists.ok:
+        raise output.WorkspaceError(
+            f"directory {workspace_path} already exists on the VM. "
+            f"Remove it manually (ssh to the VM and 'sudo rm -rf {workspace_path}') "
+            "or choose a different name."
+        )
+
+    # Create workspace group (idempotent), add admin, and set up directory with setgid
+    target.run(f"sh -c 'getent group {ws_group} >/dev/null 2>&1 || /usr/sbin/groupadd {ws_group}'", sudo=True)
+    target.run(f"usermod -aG {ws_group} {vm.admin_username}", sudo=True)
+    target.run(f"mkdir -p {workspace_path}", sudo=True)
+    target.run(f"chown {vm.admin_username}:{ws_group} {workspace_path}", sudo=True)
+    target.run(f"chmod 2770 {workspace_path}", sudo=True)
+    # Set default ACLs so files created inside are group-writable
+    target.run(f"setfacl -d -m g::rwx -m m::rwx {workspace_path}", sudo=True)
+
+    # Git clone if repo is set
+    if template.repo:
+        output.info(f"Cloning {template.repo}...")
+        try:
+            target.run(f"git clone {template.repo} {workspace_path}", timeout=300)
+            # Ensure cloned files inherit the workspace group and subdirectories
+            # have SGID so new files (including atomic writes) get the right group
+            target.run(f"chgrp -R {ws_group} {workspace_path}", sudo=True)
+            import shlex
+
+            sgid_cmd = f"find {shlex.quote(workspace_path)} -type d -exec chmod g+s {{}} +"
+            target.run(sgid_cmd, sudo=True, timeout=120)
+        except Exception:
+            if template.repo.startswith("git@"):
+                output.warn(
+                    "Hint: SSH repo URLs are not supported. Use HTTPS URLs "
+                    "and configure git credentials with 'vm add-git-credential'."
+                )
+            else:
+                output.warn(
+                    "Hint: for private repos, ensure git credentials are "
+                    "configured on the VM (see 'vm add-git-credential')."
+                )
+            raise
+
+    # Tmuxinator config (no tasks yet at workspace creation time)
+    if template.tmuxinator:
+        tmux_config = generate_config(ws_name, workspace_path)
+        target.write_file(f"{workspace_path}/.tmuxinator.yml", tmux_config)
+        # Symlink so tmuxinator can find it by console session name
+        session = console_session_name(ws_name)
+        target.run("mkdir -p ~/.config/tmuxinator", timeout=10)
+        target.run(
+            f"ln -sf {workspace_path}/.tmuxinator.yml ~/.config/tmuxinator/{session}.yml",
+            timeout=10,
+        )
+
+    return workspace_path
+
+
+def shell_vm_workspace(
+    vm: VMRow,
+    config: Config,
+    workspace_path: str,
+) -> None:
+    """Open a plain shell into a VM workspace."""
+    from agentworks.ssh import admin_exec_target, interactive
+
+    target = admin_exec_target(vm, config)
+    sys.exit(interactive(target, f"cd {workspace_path} && exec $SHELL -l"))
+
+
+def console_vm_workspace(
+    vm: VMRow,
+    config: Config,
+    ws_name: str,
+    *,
+    recreate: bool = False,
+) -> None:
+    """Open the workspace console (tmuxinator) on a VM."""
+    from agentworks.ssh import admin_exec_target, interactive
+
+    session = console_session_name(ws_name)
+    target = admin_exec_target(vm, config)
+
+    if recreate:
+        target.run(f"tmux kill-session -t {session}", check=False, timeout=10)
+
+    sys.exit(interactive(target, f"tmuxinator start {session}"))
+
+
+def delete_vm_workspace(
+    vm: VMRow,
+    config: Config,
+    ws_name: str,
+    workspace_path: str,
+    *,
+    logger: SSHLogger | None = None,
+) -> None:
+    """Delete a workspace from a VM."""
+    from agentworks.ssh import SSHError
+
+    assert vm.tailscale_host is not None
+    target = admin_exec_target(vm, config, logger=logger)
+
+    try:
+        target.run(f"rm -rf {workspace_path}", sudo=True, timeout=30)
+        session = console_session_name(ws_name)
+        target.run(f"rm -f ~/.config/tmuxinator/{session}.yml", check=False, timeout=10)
+    except SSHError as e:
+        output.warn(f"remote cleanup failed: {e}")
+
+
+def generate_vscode_workspace(
+    vm: VMRow,
+    config: Config,
+    ws_name: str,
+    workspace_path: str,
+) -> str:
+    """Generate a .code-workspace file for VS Code SSH Remote."""
+    from agentworks.ssh_config import ssh_host_alias
+
+    # Use the SSH config alias so VS Code picks up the right host/user/key
+    ssh_host = ssh_host_alias(vm.name, config.operator.ssh_host_prefix)
+
+    ws_file = {
+        "folders": [
+            {
+                "uri": f"vscode-remote://ssh-remote+{ssh_host}{workspace_path}",
+            }
+        ],
+        "remoteAuthority": f"ssh-remote+{ssh_host}",
+    }
+
+    vscode_dir = config.paths.vscode_workspaces
+    vscode_dir.mkdir(parents=True, exist_ok=True)
+    vscode_path = vscode_dir / f"{ws_name}.code-workspace"
+    vscode_path.write_text(json.dumps(ws_file, indent=2) + "\n")
+
+    return str(vscode_path)