workforest 0.1.0__py3-none-any.whl

workforest/config.py

@@ -0,0 +1,188 @@
+"""Configuration: schema, layered loading, merging, template resolution.
+
+Layers (low → high, DESIGN §4.1): built-in defaults → system → user →
+project-shared (main worktree root) → project-local (.vscode/ then .idea/) →
+environment → CLI flags (applied by commands, not here).
+"""
+
+import json
+import os
+import string
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from workforest.errors import ConfigError
+
+SYSTEM_CONFIG_DIR = Path("/etc/workforest")
+GLOBAL_BASENAMES = ("config.yaml", "config.yml", "config.json")
+PROJECT_BASENAMES = (".workforest.yaml", ".workforest.yml", ".workforest.json")
+PROJECT_LOCAL_DIRS = (".vscode", ".idea")
+
+# key -> (kind, default). Kinds: "str", "list", "map" (str -> str, where a
+# null value deletes the inherited entry during merge).
+_SCHEMA: dict[str, tuple[str, Any]] = {
+    "worktrees_dir": ("str", "$WF_MAIN/../worktrees/$WF_NAME"),
+    "opener": ("str", ""),
+    "openers": ("map", {}),
+    "window_command": ("str", ""),
+    "symlinks": ("list", []),
+    "setup_scripts": ("list", []),
+    "scripts": ("map", {}),
+}
+
+
+@dataclass(slots=True)
+class Config:
+    worktrees_dir: str = "$WF_MAIN/../worktrees/$WF_NAME"
+    opener: str = ""
+    openers: dict[str, str] = field(default_factory=dict)
+    window_command: str = ""
+    symlinks: list[str] = field(default_factory=list)
+    setup_scripts: list[str] = field(default_factory=list)
+    scripts: dict[str, str] = field(default_factory=dict)
+    sources: list[tuple[str, Path]] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "worktrees_dir": self.worktrees_dir,
+            "opener": self.opener,
+            "openers": self.openers,
+            "window_command": self.window_command,
+            "symlinks": self.symlinks,
+            "setup_scripts": self.setup_scripts,
+            "scripts": self.scripts,
+        }
+
+
+def _parse_file(path: Path) -> dict[str, Any]:
+    text = path.read_text()
+    if path.suffix == ".json":
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise ConfigError(f"{path}: invalid JSON: {exc}") from exc
+    else:
+        try:
+            data = yaml.safe_load(text)
+        except yaml.YAMLError as exc:
+            raise ConfigError(f"{path}: invalid YAML: {exc}") from exc
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path}: top level must be a mapping, got {type(data).__name__}")
+    return data
+
+
+def _validate(data: dict[str, Any], path: Path) -> None:
+    for key, value in data.items():
+        if key not in _SCHEMA:
+            known = ", ".join(sorted(_SCHEMA))
+            raise ConfigError(f"{path}: unknown key {key!r} (known keys: {known})")
+        kind, _ = _SCHEMA[key]
+        match kind:
+            case "str":
+                if not isinstance(value, str):
+                    raise ConfigError(
+                        f"{path}: {key!r} must be a string, got {type(value).__name__}"
+                    )
+            case "list":
+                if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+                    raise ConfigError(f"{path}: {key!r} must be a list of strings")
+            case "map":
+                if not isinstance(value, dict) or not all(
+                    isinstance(k, str) and (v is None or isinstance(v, str))
+                    for k, v in value.items()
+                ):
+                    raise ConfigError(
+                        f"{path}: {key!r} must be a mapping of string to string (or null)"
+                    )
+
+
+def _merge(base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]:
+    """Scalars/lists replace; mappings merge per key with null deleting."""
+    merged = dict(base)
+    for key, value in overlay.items():
+        kind, _ = _SCHEMA[key]
+        if kind == "map":
+            combined: dict[str, str] = dict(merged.get(key, {}))
+            for name, entry in value.items():
+                if entry is None:
+                    combined.pop(name, None)
+                else:
+                    combined[name] = entry
+            merged[key] = combined
+        else:
+            merged[key] = value
+    return merged
+
+
+def _first_existing(directory: Path, basenames: tuple[str, ...]) -> Path | None:
+    for basename in basenames:
+        candidate = directory / basename
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _layer_files(main_worktree: Path | None) -> list[tuple[str, Path]]:
+    layers: list[tuple[str, Path]] = []
+    if found := _first_existing(SYSTEM_CONFIG_DIR, GLOBAL_BASENAMES):
+        layers.append(("system", found))
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    user_dir = (Path(xdg) if xdg else Path.home() / ".config") / "workforest"
+    if found := _first_existing(user_dir, GLOBAL_BASENAMES):
+        layers.append(("user", found))
+    if main_worktree is not None:
+        if found := _first_existing(main_worktree, PROJECT_BASENAMES):
+            layers.append(("project", found))
+        for local_dir in PROJECT_LOCAL_DIRS:
+            if found := _first_existing(main_worktree / local_dir, PROJECT_BASENAMES):
+                layers.append(("project-local", found))
+                break
+    return layers
+
+
+def load_config(main_worktree: Path | None = None) -> Config:
+    """Load and merge all layers; main_worktree=None skips project layers."""
+    merged = {key: default for key, (_, default) in _SCHEMA.items()}
+    sources: list[tuple[str, Path]] = []
+    for layer, path in _layer_files(main_worktree):
+        data = _parse_file(path)
+        _validate(data, path)
+        merged = _merge(merged, data)
+        sources.append((layer, path))
+
+    # Set-but-empty is meaningful: WORKFOREST_WINDOW_COMMAND="" forces the
+    # current-shell mode in sessions where the configured window_command
+    # doesn't apply (ssh, plain tty); likewise an empty WORKFOREST_OPENER
+    # resets to the $VISUAL/$EDITOR chain.
+    if (opener := os.environ.get("WORKFOREST_OPENER")) is not None:
+        merged["opener"] = opener
+    if (window := os.environ.get("WORKFOREST_WINDOW_COMMAND")) is not None:
+        merged["window_command"] = window
+
+    return Config(**merged, sources=sources)
+
+
+def template_vars(main_worktree: Path) -> dict[str, str]:
+    """The WF_* family as template variables (DESIGN §3.5/§3.6)."""
+    return {
+        "WF_MAIN": str(main_worktree),
+        "WF_NAME": main_worktree.name,
+    }
+
+
+def resolve_worktrees_dir(config: Config, main_worktree: Path) -> Path:
+    """Expand $WF_* and environment variables, then normalize the path."""
+    mapping = {**os.environ, **template_vars(main_worktree)}
+    try:
+        expanded = string.Template(config.worktrees_dir).substitute(mapping)
+    except (KeyError, ValueError) as exc:
+        raise ConfigError(f"worktrees_dir {config.worktrees_dir!r}: {exc}") from exc
+    path = Path(expanded).expanduser()
+    if not path.is_absolute():
+        path = main_worktree / path
+    return Path(os.path.normpath(path))

workforest/errors.py

@@ -0,0 +1,34 @@
+"""Error hierarchy. cli.py maps these to messages and exit codes (DESIGN §5)."""
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+EXIT_CANCELLED = 3
+EXIT_CONFIG = 4
+
+
+class WorkforestError(Exception):
+    """Operational error; the message is shown to the user."""
+
+    exit_code = EXIT_ERROR
+
+
+class UsageError(WorkforestError):
+    exit_code = EXIT_USAGE
+
+
+class CancelledError(WorkforestError):
+    exit_code = EXIT_CANCELLED
+
+
+class ConfigError(WorkforestError):
+    exit_code = EXIT_CONFIG
+
+
+class GitError(WorkforestError):
+    pass
+
+
+class NotARepoError(GitError):
+    def __init__(self) -> None:
+        super().__init__("Not inside a git repository")

workforest/examples/config.yaml

@@ -0,0 +1,117 @@
+# Workforest — global configuration example
+#
+# Locations (first existing basename wins: config.yaml → config.yml → config.json):
+#   system layer:  /etc/workforest/config.yaml
+#   user layer:    $XDG_CONFIG_HOME/workforest/config.yaml   (~/.config/workforest/config.yaml)
+#
+# Layer precedence (low → high):
+#   built-in defaults → system → user → project shared (repo root)
+#   → project local (.vscode/ or .idea/) → env vars → CLI flags
+#
+# Merge semantics:
+#   scalars and lists REPLACE the lower layer;
+#   mappings (`openers`, `scripts`) MERGE per key, a key set to `null` removes
+#   the inherited entry.
+#
+# Every key is optional. The values shown at the top of each section are the
+# built-in defaults — a missing key and an explicitly-default key behave the
+# same. The global layers are the natural home for ENVIRONMENT concerns
+# (terminal, editor, personal helper scripts); repo concerns belong in the
+# project config (see examples/.workforest.yaml).
+
+# ---------------------------------------------------------------------------
+# Where managed worktrees live — a path template expanded with the WF_*
+# variables (the same family your scripts receive) plus ordinary environment
+# variables, then path-normalized:
+#   $WF_MAIN   absolute path of the main worktree
+#   $WF_NAME   repo name (the main checkout's directory name)
+#
+# Default: a `worktrees/` folder next to the main checkout, namespaced per
+# repo, so ~/src/api → ~/src/worktrees/api/<branch-short-name>.
+# ---------------------------------------------------------------------------
+worktrees_dir: "$WF_MAIN/../worktrees/$WF_NAME"
+
+# Alternatives:
+# worktrees_dir: "$HOME/worktrees/$WF_NAME"     # all forests in one place
+# worktrees_dir: "$WF_MAIN/../worktrees"        # bash-MVP flat layout
+
+# ---------------------------------------------------------------------------
+# Default opener — what runs when you `wf create`/`wf open` without -o.
+#
+# Value is either a name from the `openers` mapping below, or a command
+# template used verbatim.
+#
+# Default: "" — falls back to $VISUAL, then $EDITOR, then errors out asking
+# you to set one. Workforest never assumes a specific editor.
+# ---------------------------------------------------------------------------
+opener: ""
+
+# opener: edit          # a name defined in `openers`
+# opener: "$EDITOR {path}"   # or an inline template
+
+# ---------------------------------------------------------------------------
+# Named openers — command templates for -o NAME, the shortcut form
+# (`wf NAME <worktree>`), and the TUI opener carousel.
+#
+# Template rules:
+#   * environment variables are expanded ($EDITOR, $SHELL, …)
+#   * {path} is replaced with the shell-quoted target path
+#   * a template WITHOUT {path} simply runs with the target directory as its
+#     working directory
+#
+# Default: {} — the TUI then falls back to two derived entries:
+# the default opener and $SHELL.
+# ---------------------------------------------------------------------------
+openers: {}
+
+# openers:
+#   edit: "$EDITOR {path}"       # editors usually want the path argument
+#   shell: "$SHELL"              # just a shell in the worktree
+#   git: "lazygit"               # runs with cwd = worktree, no argument
+#   ide: "xdg-open {path}"       # hand off to the desktop default handler
+#   agent: "claude"
+
+# ---------------------------------------------------------------------------
+# Window command — WHERE the opener runs.
+#
+# Default: "" — the opener runs in your current shell via the `wf` wrapper
+# (`cd <worktree> && <opener>`).
+#
+# Set a template to spawn a new terminal window / multiplexer pane instead.
+# Placeholders: {title}    "repo: worktree", shell-quoted
+#               {path}     target directory
+#               {command}  the resolved opener command
+# The process is spawned fully detached.
+#
+# This key is the environment-specific bit par excellence — it belongs in
+# your USER config, never in a project config.
+# ---------------------------------------------------------------------------
+window_command: ""
+
+# window_command: "kitty --title {title} --directory {path} {command}"
+# window_command: "foot --title={title} --working-directory={path} {command}"
+# window_command: "alacritty --title {title} --working-directory {path} -e {command}"
+# window_command: "tmux new-window -c {path} -n {title} {command}"
+
+# ---------------------------------------------------------------------------
+# Personal named scripts — available via `workforest run NAME` in every repo.
+# Merged per key with project `scripts` (project wins on conflict).
+#
+# Scripts run from the current worktree root via $SHELL -c with:
+#   WF_MAIN, WF_WORKTREE, WF_WORKTREES_DIR, WF_BRANCH
+#
+# Default: {}
+# ---------------------------------------------------------------------------
+scripts: {}
+
+# scripts:
+#   sync: "git fetch --all --prune && git status -sb"
+#   diff-main: "git diff $(git -C \"$WF_MAIN\" branch --show-current)..."
+
+# ---------------------------------------------------------------------------
+# `symlinks` and `setup_scripts` are valid here too (any key is valid at any
+# layer), but they are repo concerns — you almost always want them in the
+# project config instead. Defaults: [] and [].
+# ---------------------------------------------------------------------------
+# symlinks: []
+# setup_scripts: []

workforest/gitutil.py

@@ -0,0 +1,194 @@
+"""Typed subprocess wrappers around git plumbing.
+
+The only module that spawns git (DESIGN §5). Consumers get typed results;
+worktree data comes from `--porcelain -z` output, never from parsing the
+human-readable form.
+"""
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from workforest.errors import GitError, NotARepoError
+
+
+def run_git(
+    args: list[str],
+    *,
+    cwd: Path | None = None,
+    check: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    """Run git and return the completed process; raise GitError on failure."""
+    cmd = ["git", *args]
+    result = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, check=False)
+    if check and result.returncode != 0:
+        detail = result.stderr.strip() or result.stdout.strip() or "unknown error"
+        raise GitError(f"`{' '.join(cmd)}` failed: {detail}")
+    return result
+
+
+def git_output(args: list[str], *, cwd: Path | None = None) -> str:
+    return run_git(args, cwd=cwd).stdout.strip()
+
+
+def repo_root(cwd: Path | None = None) -> Path:
+    result = run_git(["rev-parse", "--show-toplevel"], cwd=cwd, check=False)
+    if result.returncode != 0:
+        raise NotARepoError()
+    return Path(result.stdout.strip())
+
+
+@dataclass(slots=True, frozen=True)
+class Worktree:
+    path: Path
+    head: str
+    branch: str | None  # short name; None when detached or bare
+    is_main: bool
+
+    @property
+    def name(self) -> str:
+        return self.path.name
+
+
+def parse_worktree_porcelain(data: str) -> list[Worktree]:
+    """Parse `git worktree list --porcelain -z` output.
+
+    Records are groups of NUL-terminated attribute lines separated by an
+    empty entry. Unknown attributes (locked, prunable, future ones) are
+    ignored. The first record is the main worktree — a git guarantee.
+    """
+    worktrees: list[Worktree] = []
+    record: dict[str, str] = {}
+    for token in data.split("\0"):
+        if token == "":
+            if record:
+                worktrees.append(_record_to_worktree(record, is_main=not worktrees))
+                record = {}
+            continue
+        key, _, value = token.partition(" ")
+        record[key] = value
+    if record:
+        worktrees.append(_record_to_worktree(record, is_main=not worktrees))
+    return worktrees
+
+
+def _record_to_worktree(record: dict[str, str], *, is_main: bool) -> Worktree:
+    branch = record.get("branch")
+    if branch is not None:
+        branch = branch.removeprefix("refs/heads/")
+    return Worktree(
+        path=Path(record["worktree"]),
+        head=record.get("HEAD", ""),
+        branch=branch,
+        is_main=is_main,
+    )
+
+
+def list_worktrees(cwd: Path | None = None) -> list[Worktree]:
+    result = run_git(["worktree", "list", "--porcelain", "-z"], cwd=cwd, check=False)
+    if result.returncode != 0:
+        raise NotARepoError()
+    return parse_worktree_porcelain(result.stdout)
+
+
+def main_worktree(cwd: Path | None = None) -> Path:
+    return list_worktrees(cwd)[0].path
+
+
+def current_branch(cwd: Path | None = None) -> str:
+    """Short branch name, or "HEAD" when detached."""
+    return git_output(["rev-parse", "--abbrev-ref", "HEAD"], cwd=cwd)
+
+
+def local_branches(cwd: Path | None = None) -> list[str]:
+    out = git_output(["for-each-ref", "--format=%(refname:short)", "refs/heads"], cwd=cwd)
+    return out.splitlines() if out else []
+
+
+def remote_branches(cwd: Path | None = None) -> list[str]:
+    """Remote branch names with the remote prefix stripped, deduplicated."""
+    out = git_output(["for-each-ref", "--format=%(refname:short)", "refs/remotes"], cwd=cwd)
+    seen: dict[str, None] = {}
+    for ref in out.splitlines():
+        _, _, name = ref.partition("/")
+        if name and name != "HEAD":
+            seen.setdefault(name)
+    return list(seen)
+
+
+def branch_exists(branch: str, cwd: Path | None = None) -> bool:
+    result = run_git(
+        ["show-ref", "--verify", "--quiet", f"refs/heads/{branch}"], cwd=cwd, check=False
+    )
+    return result.returncode == 0
+
+
+def remote_branch_exists(branch: str, cwd: Path | None = None) -> bool:
+    result = run_git(
+        ["show-ref", "--verify", "--quiet", f"refs/remotes/origin/{branch}"],
+        cwd=cwd,
+        check=False,
+    )
+    return result.returncode == 0
+
+
+def find_branch_worktree(branch: str, cwd: Path | None = None) -> Worktree | None:
+    for worktree in list_worktrees(cwd):
+        if worktree.branch == branch:
+            return worktree
+    return None
+
+
+def status_porcelain(path: Path) -> str:
+    """Empty string means clean."""
+    return run_git(["status", "--porcelain"], cwd=path).stdout.rstrip("\n")
+
+
+def worktree_add(repo: Path, path: Path, branch: str) -> None:
+    """Add a worktree, resolving the branch local → origin remote → new."""
+    if branch_exists(branch, repo) or remote_branch_exists(branch, repo):
+        # git checks out the local branch, or DWIMs a tracking branch from
+        # the remote one.
+        run_git(["worktree", "add", str(path), branch], cwd=repo)
+    else:
+        run_git(["worktree", "add", "-b", branch, str(path)], cwd=repo)
+
+
+def worktree_remove(repo: Path, path: Path, *, force: bool = False) -> None:
+    args = ["worktree", "remove"]
+    if force:
+        args.append("--force")
+    run_git([*args, str(path)], cwd=repo)
+
+
+def checkout(path: Path, branch: str) -> None:
+    run_git(["checkout", branch], cwd=path)
+
+
+def delete_branch(repo: Path, branch: str) -> None:
+    run_git(["branch", "-D", branch], cwd=repo)
+
+
+def git_dir(worktree: Path) -> Path:
+    """Per-worktree git dir (.git/worktrees/<name> for linked worktrees)."""
+    return Path(git_output(["rev-parse", "--absolute-git-dir"], cwd=worktree))
+
+
+def set_config(worktree: Path, key: str, value: str, *, per_worktree: bool = False) -> None:
+    args = ["config"]
+    if per_worktree:
+        args.append("--worktree")
+    run_git([*args, key, value], cwd=worktree)
+
+
+def global_excludes_file() -> Path | None:
+    """The user's global core.excludesFile, following git's own default."""
+    result = run_git(["config", "--global", "--get", "core.excludesFile"], check=False)
+    value = result.stdout.strip()
+    if value:
+        return Path(value).expanduser()
+    import os
+
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    return base / "git" / "ignore"

workforest/hooks.py

@@ -0,0 +1,146 @@
+"""Creation hooks (symlinks, setup scripts) and named-script execution.
+
+Scripts get exactly one environment variable family, WF_* (DESIGN §3.6), and
+run via $SHELL -c (sh -c fallback). Their stdout is routed to our stderr so
+the cd protocol on stdout stays clean.
+"""
+
+import io
+import os
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+from workforest import gitutil, output
+from workforest.config import Config
+from workforest.errors import WorkforestError
+
+EXCLUDE_FILE_NAME = "workforest.exclude"
+
+
+def script_env(
+    *,
+    main: Path,
+    worktree: Path,
+    worktrees_dir: Path,
+    branch: str | None,
+) -> dict[str, str]:
+    env = os.environ.copy()
+    env.update(
+        {
+            "WF_MAIN": str(main),
+            "WF_NAME": main.name,
+            "WF_WORKTREE": str(worktree),
+            "WF_WORKTREES_DIR": str(worktrees_dir),
+            "WF_BRANCH": branch or "",
+        }
+    )
+    return env
+
+
+def _shell() -> str:
+    return os.environ.get("SHELL") or "sh"
+
+
+def run_snippet(snippet: str, *, cwd: Path, env: dict[str, str]) -> int:
+    """Run a config-defined shell snippet with stdout diverted to stderr."""
+    argv = [_shell(), "-c", snippet]
+    try:
+        stderr_fd: int | None = sys.stderr.fileno()
+    except io.UnsupportedOperation, AttributeError:
+        stderr_fd = None
+    if stderr_fd is not None:
+        result = subprocess.run(argv, cwd=cwd, env=env, stdout=stderr_fd, check=False)
+        return result.returncode
+    captured = subprocess.run(argv, cwd=cwd, env=env, capture_output=True, text=True, check=False)
+    if captured.stdout:
+        sys.stderr.write(captured.stdout)
+    if captured.stderr:
+        sys.stderr.write(captured.stderr)
+    return captured.returncode
+
+
+def create_symlinks(config: Config, *, main: Path, worktree: Path) -> list[str]:
+    """Symlink configured repo-root-relative paths from main into the
+    worktree; returns the created relative paths."""
+    created: list[str] = []
+    for rel in config.symlinks:
+        rel = rel.strip("/")
+        if not rel:
+            continue
+        src = main / rel
+        dst = worktree / rel
+        if not src.exists():
+            output.warn(f"symlink source does not exist, skipping: {src}")
+            continue
+        if dst.exists() and not dst.is_symlink():
+            output.warn(f"destination exists and is not a symlink, skipping: {dst}")
+            continue
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        if dst.is_symlink():
+            dst.unlink()
+        dst.symlink_to(src)
+        output.success(f"symlinked {rel} -> {src}")
+        created.append(rel)
+    if created:
+        exclude_from_git(worktree, created)
+    return created
+
+
+def exclude_from_git(worktree: Path, rel_paths: list[str]) -> None:
+    """Hide the given root-relative paths from git status in this worktree
+    only, via a per-worktree core.excludesFile seeded with the user's global
+    excludes (so overriding the file loses nothing)."""
+    git_dir = gitutil.git_dir(worktree)
+    exclude_file = git_dir / EXCLUDE_FILE_NAME
+
+    gitutil.set_config(worktree, "extensions.worktreeConfig", "true")
+    gitutil.set_config(worktree, "core.excludesFile", str(exclude_file), per_worktree=True)
+
+    lines = ["# Managed by workforest: symlinks from the `symlinks` config key"]
+    global_excludes = gitutil.global_excludes_file()
+    if global_excludes is not None and global_excludes.is_file():
+        lines.append(f"# --- inherited from global core.excludesFile: {global_excludes} ---")
+        lines.append(global_excludes.read_text().rstrip("\n"))
+        lines.append("# --- workforest symlinks ---")
+    lines.extend(f"/{rel}" for rel in rel_paths)
+    exclude_file.write_text("\n".join(lines) + "\n")
+    output.success(f"excluded {len(rel_paths)} symlink(s) from git in this worktree")
+
+
+def run_setup_scripts(config: Config, *, worktree: Path, env: dict[str, str]) -> int:
+    """Run setup_scripts in order; failures warn but do not abort. Returns
+    the number of failed scripts."""
+    failures = 0
+    for snippet in config.setup_scripts:
+        output.success(f"running setup script: {snippet}")
+        if run_snippet(snippet, cwd=worktree, env=env) != 0:
+            output.warn(f"setup script failed: {snippet}")
+            failures += 1
+    return failures
+
+
+def run_named_script(
+    config: Config,
+    name: str,
+    *,
+    cwd: Path,
+    env: dict[str, str],
+    extra_args: list[str] | None = None,
+) -> None:
+    """Run a `scripts` entry from the merged config; raise on failure.
+
+    extra_args are shell-quoted and appended to the snippet, so
+    `wf run make check` runs `make check` for a script defined as `make`.
+    """
+    snippet = config.scripts.get(name)
+    if snippet is None:
+        available = ", ".join(sorted(config.scripts)) or "none defined"
+        raise WorkforestError(f"no script named {name!r} (available: {available})")
+    if extra_args:
+        snippet = f"{snippet} {' '.join(shlex.quote(arg) for arg in extra_args)}"
+    output.success(f"running {name!r} in {cwd}: {snippet}")
+    code = run_snippet(snippet, cwd=cwd, env=env)
+    if code != 0:
+        raise WorkforestError(f"script {name!r} failed with exit code {code}")

workforest/integrations/__init__.py

@@ -0,0 +1,2 @@
+"""Optional integrations (DESIGN §3.7). Core never imports this subpackage;
+each integration is feature-gated on its own environment being present."""