workforest 0.1.0__py3-none-any.whl

workforest/__init__.py

@@ -0,0 +1,3 @@
+"""Workforest — git worktree forest management."""
+
+__version__ = "0.1.0"

workforest/__main__.py

@@ -0,0 +1,4 @@
+from workforest.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

workforest/cli.py

@@ -0,0 +1,254 @@
+"""argparse front-end: shortcut dispatch, error → exit-code mapping, and the
+sole writer to stdout (DESIGN §3.3/§5)."""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from workforest import __version__, commands, output
+from workforest.commands import CommandResult
+from workforest.errors import EXIT_CANCELLED, EXIT_OK, WorkforestError
+from workforest.launch import ShellAction
+
+SUBCOMMANDS = frozenset(
+    {
+        "create",
+        "open",
+        "list",
+        "delete",
+        "checkout",
+        "run",
+        "tui",
+        "init",
+        "config",
+        "shell-init",
+    }
+)
+
+
+def _claude_available() -> bool:
+    """Feature gate (DESIGN §3.7): the integration is invisible without
+    ~/.claude. Filesystem check only — core never imports the integration."""
+    return (Path.home() / ".claude").is_dir()
+
+
+def _known_subcommands() -> frozenset[str]:
+    if _claude_available():
+        return SUBCOMMANDS | {"claude"}
+    return SUBCOMMANDS
+
+
+def _emit(result: CommandResult) -> None:
+    match result:
+        case ShellAction(script=script):
+            print(script)
+        case str() as text if text:
+            print(text)
+        case _:
+            pass
+
+
+# --- handlers -----------------------------------------------------------
+
+
+def _handle_create(ns: argparse.Namespace) -> CommandResult:
+    ctx = commands.build_context()
+    return commands.cmd_create(
+        ctx,
+        ns.branch,
+        opener=ns.opener,
+        path_arg=ns.path,
+        no_hooks=ns.no_hooks,
+        no_open=ns.no_open,
+    )
+
+
+def _handle_open(ns: argparse.Namespace) -> CommandResult:
+    ctx = commands.build_context()
+    return commands.cmd_open(ctx, ns.name, opener=ns.opener, path_arg=ns.path)
+
+
+def _handle_list(ns: argparse.Namespace) -> CommandResult:
+    ctx = commands.build_context()
+    return commands.cmd_list(ctx, porcelain=ns.porcelain)
+
+
+def _handle_delete(ns: argparse.Namespace) -> CommandResult:
+    ctx = commands.build_context()
+    delete_branch: bool | None = None
+    if ns.delete_branch:
+        delete_branch = True
+    elif ns.keep_branch:
+        delete_branch = False
+    return commands.cmd_delete(ctx, ns.names, force=ns.force, delete_branch=delete_branch)
+
+
+def _handle_checkout(ns: argparse.Namespace) -> CommandResult:
+    ctx = commands.build_context()
+    return commands.cmd_checkout(ctx, ns.name, force=ns.force)
+
+
+def _handle_run(ns: argparse.Namespace) -> CommandResult:
+    ctx = commands.build_context()
+    return commands.cmd_run(ctx, ns.script, ns.args)
+
+
+def _handle_init(ns: argparse.Namespace) -> CommandResult:
+    ctx = commands.build_context()
+    return commands.cmd_init(ctx, local=ns.local)
+
+
+def _handle_config(ns: argparse.Namespace) -> CommandResult:
+    return commands.cmd_config_show(as_json=ns.json)
+
+
+def _handle_shell_init(ns: argparse.Namespace) -> CommandResult:
+    from workforest import shellinit
+
+    return shellinit.shell_init(ns.shell)
+
+
+def _handle_tui(ns: argparse.Namespace) -> CommandResult:
+    from workforest import tui
+
+    return tui.run(ns.mode)
+
+
+def _handle_claude(ns: argparse.Namespace) -> CommandResult:
+    from workforest.integrations import claude
+
+    claude.cmd_copy_session(ns.session_id)
+    return None
+
+
+# --- parser -------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="workforest",
+        description="Git worktree forest management",
+        epilog=(
+            "shortcut: `workforest OPENER [NAME] [-p PATH]` "
+            "is `workforest open [NAME] -o OPENER [-p PATH]`"
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"workforest {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def opener_args(p: argparse.ArgumentParser) -> None:
+        p.add_argument("-o", "--opener", help="opener name or command template")
+        p.add_argument("-p", "--path", help="path inside the worktree to open")
+
+    p = sub.add_parser("create", help="create (or reuse) a worktree for a branch and open it")
+    p.add_argument("branch", nargs="?", help="branch name (default: current branch)")
+    opener_args(p)
+    p.add_argument("--no-hooks", action="store_true", help="skip symlinks and setup scripts")
+    p.add_argument("--no-open", action="store_true", help="create only, do not open")
+    p.set_defaults(func=_handle_create)
+
+    p = sub.add_parser("open", help="open an existing worktree")
+    p.add_argument("name", nargs="?", help="worktree directory name")
+    opener_args(p)
+    p.set_defaults(func=_handle_open)
+
+    p = sub.add_parser("list", help="list managed worktrees")
+    p.add_argument("--porcelain", action="store_true", help="stable tab-separated output")
+    p.set_defaults(func=_handle_list)
+
+    p = sub.add_parser("delete", help="delete worktree(s)")
+    p.add_argument("names", nargs="+", metavar="NAME")
+    p.add_argument("--force", action="store_true", help="skip the dirty-worktree confirmation")
+    group = p.add_mutually_exclusive_group()
+    group.add_argument("--delete-branch", action="store_true", help="also delete the branch")
+    group.add_argument("--keep-branch", action="store_true", help="never delete the branch")
+    p.set_defaults(func=_handle_delete)
+
+    p = sub.add_parser("checkout", help="delete a worktree and check its branch out in main")
+    p.add_argument("name", metavar="NAME")
+    p.add_argument("--force", action="store_true", help="skip the dirty-worktree confirmation")
+    p.set_defaults(func=_handle_checkout)
+
+    p = sub.add_parser("run", help="run a named script from the merged config")
+    p.add_argument("script", metavar="SCRIPT")
+    p.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        metavar="ARGS",
+        help="appended (shell-quoted) to the script command",
+    )
+    p.set_defaults(func=_handle_run)
+
+    p = sub.add_parser("init", help="scaffold a .workforest.yaml project config")
+    p.add_argument(
+        "--local",
+        action="store_true",
+        help="place it in .vscode/ or .idea/ (untracked per-developer override)",
+    )
+    p.set_defaults(func=_handle_init)
+
+    p = sub.add_parser("config", help="show the merged configuration and its sources")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=_handle_config)
+
+    p = sub.add_parser("shell-init", help="print the wf shell wrapper (eval in your shell rc)")
+    p.add_argument("shell", nargs="?", choices=("bash", "zsh"), help="default: from $SHELL")
+    p.set_defaults(func=_handle_shell_init)
+
+    p = sub.add_parser("tui", help="interactive mode (requires fzf)")
+    p.add_argument("mode", nargs="?", help="initial mode (create/open/checkout/delete)")
+    p.set_defaults(func=_handle_tui)
+
+    if _claude_available():
+        p = sub.add_parser("claude", help="Claude Code integration")
+        claude_sub = p.add_subparsers(dest="claude_command", required=True)
+        cp = claude_sub.add_parser(
+            "copy-session", help="copy a session from the main worktree into this one"
+        )
+        cp.add_argument("session_id", metavar="SESSION_ID")
+        cp.set_defaults(func=_handle_claude)
+
+    return parser
+
+
+def _preprocess(argv: list[str]) -> list[str]:
+    """No args → TUI; unknown first word → opener shortcut for `open`."""
+    if not argv:
+        return ["tui"]
+    first = argv[0]
+    if first.startswith("-") or first in _known_subcommands():
+        return argv
+    return ["open", *argv[1:], "-o", first]
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _preprocess(list(sys.argv[1:] if argv is None else argv))
+
+    if args and args[0] == "--complete":
+        from workforest import completions
+
+        topic = args[1] if len(args) > 1 else ""
+        for line in completions.complete(topic):
+            print(line)
+        return EXIT_OK
+
+    parser = build_parser()
+    try:
+        ns = parser.parse_args(args)
+    except SystemExit as exc:  # argparse exits for --help/--version/usage errors
+        return int(exc.code) if isinstance(exc.code, int) else EXIT_OK
+
+    try:
+        handler: Any = ns.func
+        _emit(handler(ns))
+        return EXIT_OK
+    except WorkforestError as exc:
+        if os.environ.get("WORKFOREST_DEBUG"):
+            raise
+        output.error(str(exc))
+        return exc.exit_code
+    except KeyboardInterrupt:
+        output.info("")
+        return EXIT_CANCELLED

workforest/commands.py

@@ -0,0 +1,284 @@
+"""Core commands. Each returns a ShellAction (stdout directive), a str
+(stdout text), or None — cli.py is the sole stdout writer (DESIGN §5)."""
+
+import importlib.resources
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from workforest import gitutil, hooks, launch, output
+from workforest.config import (
+    PROJECT_LOCAL_DIRS,
+    Config,
+    load_config,
+    resolve_worktrees_dir,
+)
+from workforest.errors import CancelledError, NotARepoError, UsageError, WorkforestError
+from workforest.launch import ShellAction
+
+type CommandResult = ShellAction | str | None
+
+
+@dataclass(slots=True)
+class Context:
+    cwd_root: Path  # repo root of the invocation directory
+    main: Path  # main worktree ($WF_MAIN)
+    config: Config
+    worktrees_dir: Path
+
+    @property
+    def repo_name(self) -> str:
+        return self.main.name
+
+
+def build_context(cwd: Path | None = None) -> Context:
+    cwd_root = gitutil.repo_root(cwd)
+    main = gitutil.main_worktree(cwd_root)
+    config = load_config(main)
+    worktrees_dir = resolve_worktrees_dir(config, main)
+    return Context(cwd_root=cwd_root, main=main, config=config, worktrees_dir=worktrees_dir)
+
+
+def managed_worktrees(ctx: Context) -> list[gitutil.Worktree]:
+    """Worktrees located directly inside the resolved worktrees dir
+    (DESIGN §3.5) — the only ones we list, complete, or delete."""
+    return [
+        worktree
+        for worktree in gitutil.list_worktrees(ctx.main)
+        if not worktree.is_main and worktree.path.parent == ctx.worktrees_dir
+    ]
+
+
+def find_managed(ctx: Context, name: str) -> gitutil.Worktree:
+    for worktree in managed_worktrees(ctx):
+        if worktree.name == name:
+            return worktree
+    raise WorkforestError(f"worktree {name!r} not found in {ctx.worktrees_dir}")
+
+
+def short_branch_name(branch: str) -> str:
+    return branch.rsplit("/", 1)[-1]
+
+
+def _script_env(ctx: Context, worktree: Path, branch: str | None) -> dict[str, str]:
+    return hooks.script_env(
+        main=ctx.main,
+        worktree=worktree,
+        worktrees_dir=ctx.worktrees_dir,
+        branch=branch,
+    )
+
+
+def cmd_create(
+    ctx: Context,
+    branch: str | None,
+    *,
+    opener: str | None = None,
+    path_arg: str | None = None,
+    no_hooks: bool = False,
+    no_open: bool = False,
+) -> CommandResult:
+    if not branch:
+        branch = gitutil.current_branch(ctx.cwd_root)
+        if branch == "HEAD":
+            raise WorkforestError("detached HEAD: specify a branch name")
+
+    existing = gitutil.find_branch_worktree(branch, ctx.main)
+    if existing is not None:
+        output.warn(f"branch {branch!r} already checked out at {existing.path}")
+        worktree_path = existing.path
+    else:
+        worktree_path = ctx.worktrees_dir / short_branch_name(branch)
+        registered = {w.path for w in gitutil.list_worktrees(ctx.main)}
+        if worktree_path in registered:
+            # Same directory name, different branch (feat/x vs fix/x): never
+            # silently reuse another branch's worktree.
+            raise WorkforestError(
+                f"{worktree_path} already holds a different branch; "
+                f"remove it first or use a different branch name"
+            )
+        if worktree_path.exists():
+            raise WorkforestError(f"directory exists but is not a worktree: {worktree_path}")
+        ctx.worktrees_dir.mkdir(parents=True, exist_ok=True)
+        gitutil.worktree_add(ctx.main, worktree_path, branch)
+        output.success(f"created worktree for {branch!r} at {worktree_path}")
+        if not no_hooks:
+            env = _script_env(ctx, worktree_path, branch)
+            hooks.create_symlinks(ctx.config, main=ctx.main, worktree=worktree_path)
+            failures = hooks.run_setup_scripts(ctx.config, worktree=worktree_path, env=env)
+            if failures:
+                output.warn(f"{failures} setup script(s) failed")
+
+    if no_open:
+        return None
+    return launch.launch(
+        ctx.config,
+        worktree=worktree_path,
+        repo_name=ctx.repo_name,
+        opener_arg=opener,
+        path_arg=path_arg,
+    )
+
+
+def cmd_open(
+    ctx: Context,
+    name: str | None,
+    *,
+    opener: str | None = None,
+    path_arg: str | None = None,
+) -> CommandResult:
+    if not name:
+        raise UsageError("worktree name required")
+    worktree = find_managed(ctx, name)
+    return launch.launch(
+        ctx.config,
+        worktree=worktree.path,
+        repo_name=ctx.repo_name,
+        opener_arg=opener,
+        path_arg=path_arg,
+    )
+
+
+def cmd_list(ctx: Context, *, porcelain: bool = False) -> CommandResult:
+    worktrees = managed_worktrees(ctx)
+    if porcelain:
+        lines = [
+            "\t".join(
+                (
+                    w.name,
+                    w.branch or "",
+                    str(w.path),
+                    "1" if gitutil.status_porcelain(w.path) else "0",
+                )
+            )
+            for w in worktrees
+        ]
+        return "\n".join(lines)
+    if not worktrees:
+        output.info(f"no worktrees in {ctx.worktrees_dir} (create one with: wf create BRANCH)")
+        return None
+    name_width = max(len(w.name) for w in worktrees)
+    branch_width = max(len(w.branch or "(detached)") for w in worktrees)
+    rows = [
+        f"{w.name:<{name_width}}  {w.branch or '(detached)':<{branch_width}}  "
+        f"{'dirty' if gitutil.status_porcelain(w.path) else 'clean'}  {w.path}"
+        for w in worktrees
+    ]
+    return "\n".join(rows)
+
+
+def _confirm_dirty(worktree: gitutil.Worktree, question: str, *, force: bool) -> None:
+    """Shared delete/checkout guard for uncommitted changes."""
+    if force:
+        return
+    changes = gitutil.status_porcelain(worktree.path)
+    if not changes:
+        return
+    lines = changes.splitlines()
+    output.warn(f"worktree {worktree.name!r} has uncommitted changes:")
+    for line in lines[:10]:
+        output.info(f"  {line}")
+    if len(lines) > 10:
+        output.info("  ...")
+    if not output.confirm(question):
+        raise CancelledError("cancelled") from None
+
+
+def cmd_delete(
+    ctx: Context,
+    names: list[str],
+    *,
+    force: bool = False,
+    delete_branch: bool | None = None,
+) -> CommandResult:
+    result: CommandResult = None
+    for name in names:
+        worktree = find_managed(ctx, name)
+        _confirm_dirty(worktree, "Delete anyway?", force=force)
+        branch = worktree.branch
+        gitutil.worktree_remove(ctx.main, worktree.path, force=True)
+        output.success(f"deleted worktree {name!r}")
+        if worktree.path == ctx.cwd_root:
+            # The shell is standing in the directory we just removed —
+            # move it back to the main checkout.
+            result = launch.cd_action(ctx.main)
+        if branch is None:
+            continue
+        decision = delete_branch
+        if decision is None and output.interactive():
+            decision = output.confirm(f"Also delete branch {branch!r}?")
+        if decision:
+            try:
+                gitutil.delete_branch(ctx.main, branch)
+                output.success(f"deleted branch {branch!r}")
+            except WorkforestError as exc:
+                output.warn(str(exc))
+    return result
+
+
+def cmd_checkout(ctx: Context, name: str, *, force: bool = False) -> CommandResult:
+    worktree = find_managed(ctx, name)
+    branch = worktree.branch
+    if branch is None:
+        raise WorkforestError(f"cannot determine branch for worktree {name!r} (detached HEAD)")
+    _confirm_dirty(
+        worktree,
+        "Delete worktree and checkout its branch in the main repo anyway?",
+        force=force,
+    )
+    gitutil.worktree_remove(ctx.main, worktree.path, force=True)
+    output.success(f"deleted worktree {name!r}")
+    gitutil.checkout(ctx.main, branch)
+    output.success(f"checked out {branch!r} in {ctx.main}")
+    return launch.cd_action(ctx.main)
+
+
+def cmd_run(ctx: Context, name: str, extra_args: list[str] | None = None) -> CommandResult:
+    branch = gitutil.current_branch(ctx.cwd_root)
+    env = _script_env(ctx, ctx.cwd_root, None if branch == "HEAD" else branch)
+    hooks.run_named_script(ctx.config, name, cwd=ctx.cwd_root, env=env, extra_args=extra_args)
+    return None
+
+
+def _scaffold_template() -> str:
+    resource = importlib.resources.files("workforest") / "examples" / ".workforest.yaml"
+    return resource.read_text()
+
+
+def cmd_init(ctx: Context, *, local: bool = False) -> CommandResult:
+    if local:
+        for candidate in PROJECT_LOCAL_DIRS:
+            directory = ctx.main / candidate
+            if directory.is_dir():
+                break
+        else:
+            dirs = " or ".join(f"{d}/" for d in PROJECT_LOCAL_DIRS)
+            raise WorkforestError(f"--local needs an IDE settings folder ({dirs}) in {ctx.main}")
+    else:
+        directory = ctx.main
+    target = directory / ".workforest.yaml"
+    if target.exists():
+        raise WorkforestError(f"{target} already exists")
+    target.write_text(_scaffold_template())
+    output.success(f"scaffolded {target}")
+    return None
+
+
+def cmd_config_show(*, as_json: bool = False) -> CommandResult:
+    try:
+        ctx = build_context()
+        config = ctx.config
+    except NotARepoError:
+        config = load_config(None)
+    sources = [(layer, str(path)) for layer, path in config.sources]
+    if as_json:
+        return json.dumps({"config": config.as_dict(), "sources": sources}, indent=2)
+    dump = yaml.safe_dump(config.as_dict(), sort_keys=False).rstrip("\n")
+    lines = [dump, "", "# sources (low -> high):"]
+    if sources:
+        lines.extend(f"#   {layer}: {path}" for layer, path in sources)
+    else:
+        lines.append("#   (built-in defaults only)")
+    return "\n".join(lines)

workforest/completions.py

@@ -0,0 +1,76 @@
+"""`workforest --complete TOPIC` backend.
+
+Completion must never break the shell: any error yields an empty candidate
+list, and everything stays on stdout as bare lines.
+"""
+
+from workforest import commands, gitutil
+from workforest.config import Config, load_config
+from workforest.errors import WorkforestError
+
+TOPICS = ("commands", "branches", "worktrees", "scripts", "openers", "claude-sessions")
+
+
+def complete(topic: str) -> list[str]:
+    try:
+        return _complete(topic)
+    except WorkforestError, OSError:
+        return []
+
+
+def _complete(topic: str) -> list[str]:
+    match topic:
+        case "commands":
+            return _commands()
+        case "branches":
+            return _branches()
+        case "worktrees":
+            return _worktrees()
+        case "scripts":
+            return sorted(_config().scripts)
+        case "openers":
+            return sorted(_config().openers)
+        case "claude-sessions":
+            return _claude_sessions()
+        case _:
+            return []
+
+
+def _config() -> Config:
+    try:
+        return commands.build_context().config
+    except WorkforestError:
+        return load_config(None)
+
+
+def _commands() -> list[str]:
+    from workforest.cli import _known_subcommands
+
+    return sorted(_known_subcommands()) + sorted(_config().openers)
+
+
+def _branches() -> list[str]:
+    """Local then remote branches, minus those already checked out."""
+    root = gitutil.repo_root()
+    taken = {w.branch for w in gitutil.list_worktrees(root) if w.branch}
+    candidates: dict[str, None] = {}
+    for branch in (*gitutil.local_branches(root), *gitutil.remote_branches(root)):
+        if branch not in taken:
+            candidates.setdefault(branch)
+    return list(candidates)
+
+
+def _worktrees() -> list[str]:
+    ctx = commands.build_context()
+    return [w.name for w in commands.managed_worktrees(ctx)]
+
+
+def _claude_sessions() -> list[str]:
+    from workforest.integrations import claude
+
+    if not claude.available():
+        return []
+    ctx = commands.build_context()
+    if ctx.cwd_root == ctx.main:
+        return []
+    return [sid for sid, _ in claude.list_new_sessions(ctx.main, ctx.cwd_root)]