workforest 0.1.2__tar.gz → 0.2.0__tar.gz

{workforest-0.1.2 → workforest-0.2.0}/.github/workflows/publish_aur.yml

@@ -72,6 +72,9 @@ jobs:
         run: |
           version="${GITHUB_REF_NAME#v}"
           cp packaging/AUR/PKGBUILD packaging/AUR/.SRCINFO /tmp/
+          # The workspace is created by the host runner under a different UID
+          # than the container's root, so git rejects it without this.
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
           # The workflow runs detached at the release tag; move to main to commit.
           # -f discards the in-place edits we just copied to /tmp; build
           # artifacts in packaging/AUR are untracked and never git-added.

{workforest-0.1.2 → workforest-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: workforest
-Version: 0.1.2
+Version: 0.2.0
 Summary: Git worktree forest management: create, open, and clean up per-branch worktrees with project-defined setup hooks
 Project-URL: Homepage, https://github.com/ArkadyBuryakov/workforest
 Author-email: Arkady Buryakov <arkady@buryakov.pro>
@@ -103,17 +103,35 @@ All keys, with defaults:
 ```yaml
 worktrees_dir: "$WF_MAIN/../worktrees/$WF_NAME"  # where the forest lives
 opener: ""              # default opener; "" → $VISUAL → $EDITOR
-openers: {}             # name -> command template, e.g. edit: "$EDITOR {path}"
+openers: {}             # name -> command template, e.g. edit: "$EDITOR {target}"
 window_command: ""      # "" → current shell; or e.g.
-                        # "kitty --title {title} --directory {path} {command}"
+                        # "kitty --title {title} --directory {worktree} $WF_COMMAND"
 symlinks: []            # untracked assets linked from main into new worktrees
 setup_scripts: []       # shell snippets run in a fresh worktree
 scripts: {}             # name -> snippet for `wf run NAME`
 ```
 
-Openers are command templates: `{path}` is replaced with the target path; a
-template without `{path}` just runs with the worktree as working directory.
-Environment variables expand in both openers and `window_command`.
+Openers and `window_command` are command templates sharing one variable
+family, which the launched process (and every script) also receives as
+environment variables:
+
+| Variable | Value |
+|---|---|
+| `WF_MAIN` | main worktree path, `/home/user/Projects/project_name` |
+| `WF_NAME` | repo name, `project_name` |
+| `WF_WORKTREES_DIR` | resolved worktrees directory |
+| `WF_WORKTREE` | this worktree's path |
+| `WF_BRANCH` | its branch (empty if detached) |
+| `WF_TARGET` | the `-p` argument, default `.` (launch-only) |
+| `WF_TITLE` | window label, `project_name: feat-x` (launch-only) |
+
+In templates, `$WF_X` (like any `$ENV` variable) inserts raw text that
+word-splits into multiple arguments, while `{x}` — `{worktree}`, `{target}`,
+`{title}`, … — inserts the shell-quoted value as exactly one argument.
+Openers run with the worktree root as working directory; in
+`window_command` the resolved opener command is additionally available as
+`$WF_COMMAND` (spliced into argv words) or `{command}` (one argument, for
+`$SHELL -c` wrappers).
 
 Fully commented reference configs:
 [`config.yaml`](src/workforest/examples/config.yaml) (user/system) and

{workforest-0.1.2 → workforest-0.2.0}/README.md

@@ -84,17 +84,35 @@ All keys, with defaults:
 ```yaml
 worktrees_dir: "$WF_MAIN/../worktrees/$WF_NAME"  # where the forest lives
 opener: ""              # default opener; "" → $VISUAL → $EDITOR
-openers: {}             # name -> command template, e.g. edit: "$EDITOR {path}"
+openers: {}             # name -> command template, e.g. edit: "$EDITOR {target}"
 window_command: ""      # "" → current shell; or e.g.
-                        # "kitty --title {title} --directory {path} {command}"
+                        # "kitty --title {title} --directory {worktree} $WF_COMMAND"
 symlinks: []            # untracked assets linked from main into new worktrees
 setup_scripts: []       # shell snippets run in a fresh worktree
 scripts: {}             # name -> snippet for `wf run NAME`
 ```
 
-Openers are command templates: `{path}` is replaced with the target path; a
-template without `{path}` just runs with the worktree as working directory.
-Environment variables expand in both openers and `window_command`.
+Openers and `window_command` are command templates sharing one variable
+family, which the launched process (and every script) also receives as
+environment variables:
+
+| Variable | Value |
+|---|---|
+| `WF_MAIN` | main worktree path, `/home/user/Projects/project_name` |
+| `WF_NAME` | repo name, `project_name` |
+| `WF_WORKTREES_DIR` | resolved worktrees directory |
+| `WF_WORKTREE` | this worktree's path |
+| `WF_BRANCH` | its branch (empty if detached) |
+| `WF_TARGET` | the `-p` argument, default `.` (launch-only) |
+| `WF_TITLE` | window label, `project_name: feat-x` (launch-only) |
+
+In templates, `$WF_X` (like any `$ENV` variable) inserts raw text that
+word-splits into multiple arguments, while `{x}` — `{worktree}`, `{target}`,
+`{title}`, … — inserts the shell-quoted value as exactly one argument.
+Openers run with the worktree root as working directory; in
+`window_command` the resolved opener command is additionally available as
+`$WF_COMMAND` (spliced into argv words) or `{command}` (one argument, for
+`$SHELL -c` wrappers).
 
 Fully commented reference configs:
 [`config.yaml`](src/workforest/examples/config.yaml) (user/system) and

{workforest-0.1.2 → workforest-0.2.0}/src/workforest/__init__.py

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

{workforest-0.1.2 → workforest-0.2.0}/src/workforest/cli.py

@@ -140,7 +140,9 @@ def build_parser() -> argparse.ArgumentParser:
 
     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.add_argument(
+            "-p", "--path", help="path inside the worktree, passed to the opener as {target}"
+        )
 
     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)")

{workforest-0.1.2 → workforest-0.2.0}/src/workforest/commands.py

@@ -115,8 +115,10 @@ def cmd_create(
         return None
     return launch.launch(
         ctx.config,
+        main=ctx.main,
         worktree=worktree_path,
-        repo_name=ctx.repo_name,
+        worktrees_dir=ctx.worktrees_dir,
+        branch=branch,
         opener_arg=opener,
         path_arg=path_arg,
     )
@@ -134,8 +136,10 @@ def cmd_open(
     worktree = find_managed(ctx, name)
     return launch.launch(
         ctx.config,
+        main=ctx.main,
         worktree=worktree.path,
-        repo_name=ctx.repo_name,
+        worktrees_dir=ctx.worktrees_dir,
+        branch=worktree.branch,
         opener_arg=opener,
         path_arg=path_arg,
     )

{workforest-0.1.2 → workforest-0.2.0}/src/workforest/examples/config.yaml

@@ -35,6 +35,32 @@ worktrees_dir: "$WF_MAIN/../worktrees/$WF_NAME"
 # worktrees_dir: "$HOME/worktrees/$WF_NAME"     # all forests in one place
 # worktrees_dir: "$WF_MAIN/../worktrees"        # bash-MVP flat layout
 
+# ---------------------------------------------------------------------------
+# The WF_* variable family — one set of variables, available everywhere.
+#
+#   $WF_MAIN            main worktree path        /home/user/Projects/project_name
+#   $WF_NAME            repo name                 project_name
+#   $WF_WORKTREES_DIR   resolved worktrees dir    /home/user/Projects/worktrees/project_name
+#   $WF_WORKTREE        this worktree's path      .../worktrees/project_name/feat-x
+#   $WF_BRANCH          its branch                feat/x   (empty if detached)
+#   $WF_TARGET          the -p argument           src/foo.py   (default ".")
+#   $WF_TITLE           window label              "project_name: feat-x"
+#
+# In `opener`/`openers`/`window_command` templates, workforest expands them
+# itself, in two forms:
+#   * $WF_X (and any $ENV var)  raw text — word-splits into multiple arguments
+#   * {x}   (e.g. {worktree})   the shell-quoted value of $WF_X — always
+#                               exactly ONE argument; use this unless you
+#                               specifically want splitting
+# The launched process (editor, terminal, scripts they spawn) also receives
+# the family as real environment variables.
+#
+# Exceptions to "everywhere":
+#   * `worktrees_dir` sees only $WF_MAIN/$WF_NAME (the rest don't exist yet)
+#   * scripts don't get WF_TARGET/WF_TITLE (launch-only concepts)
+#   * your interactive shell never gets them (they're scoped to the opener)
+# ---------------------------------------------------------------------------
+
 # ---------------------------------------------------------------------------
 # Default opener — what runs when you `wf create`/`wf open` without -o.
 #
@@ -47,17 +73,15 @@ worktrees_dir: "$WF_MAIN/../worktrees/$WF_NAME"
 opener: ""
 
 # opener: edit          # a name defined in `openers`
-# opener: "$EDITOR {path}"   # or an inline template
+# opener: "$EDITOR {target}"   # 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
+# Openers always run with the worktree root as working directory; {target}
+# ($WF_TARGET) is the -p argument, "." by default. A template without
+# {target} simply runs in the worktree.
 #
 # Default: {} — the TUI then falls back to two derived entries:
 # the default opener and $SHELL.
@@ -65,40 +89,40 @@ opener: ""
 openers: {}
 
 # openers:
-#   edit: "$EDITOR {path}"       # editors usually want the path argument
+#   edit: "$EDITOR {target}"     # 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
+#   ide: "xdg-open {target}"     # 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>`).
+# (`cd <worktree> && WF_*=... <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.
+# The process is spawned fully detached. Besides the WF_* family, the
+# resolved opener command is available here as:
+#   $WF_COMMAND   spliced into separate argv words (most terminals)
+#   {command}     ONE argument — what `$SHELL -c` wrappers want
 #
 # 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}"
+# window_command: "kitty --title {title} --directory {worktree} $WF_COMMAND"
+# window_command: "foot --title={title} --working-directory={worktree} $WF_COMMAND"
+# window_command: "alacritty --title {title} --working-directory {worktree} -e $SHELL -c {command}"
+# window_command: "tmux new-window -c {worktree} -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
+#   WF_MAIN, WF_NAME, WF_WORKTREE, WF_WORKTREES_DIR, WF_BRANCH
 #
 # Default: {}
 # ---------------------------------------------------------------------------

workforest-0.2.0/src/workforest/launch.py

@@ -0,0 +1,162 @@
+"""Opener/window template resolution and cd-protocol emission (DESIGN §3.4).
+
+No tool names appear here: what to run comes from config templates and the
+$VISUAL/$EDITOR contract; where to run it is the current shell (ShellAction)
+unless the user configured a window_command template.
+
+Templates and launched processes share one variable family, WF_*:
+
+* `$WF_X` (and any environment variable) is substituted as raw text at
+  template time, so it word-splits into multiple arguments;
+* `{x}` is the shell-quoted form of `$WF_X` — always exactly one argument;
+* the launched process receives the same family as environment variables
+  (Popen env in the window path, prefix assignments in the shell path).
+"""
+
+import os
+import re
+import shlex
+import string
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from workforest.config import Config
+from workforest.errors import WorkforestError
+
+_PLACEHOLDER = re.compile(r"\{([a-z_]+)\}")
+
+
+@dataclass(slots=True, frozen=True)
+class ShellAction:
+    """A directive for the wf shell wrapper; the only thing cli.py prints
+    to stdout for create/open/checkout."""
+
+    script: str
+
+
+def cd_action(path: Path) -> ShellAction:
+    return ShellAction(f"cd {shlex.quote(str(path))}")
+
+
+def resolve_opener_template(config: Config, opener_arg: str | None) -> str:
+    """-o NAME → `openers` lookup, else verbatim; default $VISUAL → $EDITOR."""
+    value = opener_arg or config.opener
+    if value:
+        return config.openers.get(value, value)
+    for var in ("VISUAL", "EDITOR"):
+        if os.environ.get(var):
+            return os.environ[var]
+    raise WorkforestError(
+        "no opener: pass -o, set `opener` in a config file, or export $VISUAL/$EDITOR"
+    )
+
+
+def launch_vars(
+    *,
+    main: Path,
+    worktree: Path,
+    worktrees_dir: Path,
+    branch: str | None,
+    target: str,
+) -> dict[str, str]:
+    """The full WF_* family for a launch (DESIGN §3.5/§3.6): the scripts'
+    structural five plus the launch-only WF_TARGET and WF_TITLE."""
+    return {
+        "WF_MAIN": str(main),
+        "WF_NAME": main.name,
+        "WF_WORKTREES_DIR": str(worktrees_dir),
+        "WF_WORKTREE": str(worktree),
+        "WF_BRANCH": branch or "",
+        "WF_TARGET": target,
+        "WF_TITLE": f"{main.name}: {worktree.name}",
+    }
+
+
+def expand_template(template: str, variables: dict[str, str]) -> str:
+    """`$WF_X`/`$ENV` insert raw text; `{x}` inserts $WF_X shell-quoted.
+
+    Raw substitution never touches the quoted insertions: the template is
+    split on `{x}` placeholders and only the literal segments go through
+    string.Template, so values containing `$` or braces are inert.
+    """
+    mapping = {**os.environ, **variables}
+    quoted = {name.removeprefix("WF_").lower(): value for name, value in variables.items()}
+    parts: list[str] = []
+    pos = 0
+    for match in _PLACEHOLDER.finditer(template):
+        parts.append(string.Template(template[pos : match.start()]).safe_substitute(mapping))
+        name = match.group(1)
+        if name not in quoted:
+            known = ", ".join("{" + key + "}" for key in sorted(quoted))
+            raise WorkforestError(f"unknown placeholder {{{name}}} (known: {known})")
+        parts.append(shlex.quote(quoted[name]))
+        pos = match.end()
+    parts.append(string.Template(template[pos:]).safe_substitute(mapping))
+    return "".join(parts)
+
+
+def launch(
+    config: Config,
+    *,
+    main: Path,
+    worktree: Path,
+    worktrees_dir: Path,
+    branch: str | None,
+    opener_arg: str | None = None,
+    path_arg: str | None = None,
+) -> ShellAction | None:
+    """Open a worktree: a ShellAction for the current shell, or a detached
+    window spawn (returning None) when window_command is configured.
+
+    The launch cwd is always the worktree root; -p only sets WF_TARGET,
+    the opener's argument.
+    """
+    template = resolve_opener_template(config, opener_arg)
+    target = path_arg if path_arg else "."
+    variables = launch_vars(
+        main=main,
+        worktree=worktree,
+        worktrees_dir=worktrees_dir,
+        branch=branch,
+        target=target,
+    )
+    command = expand_template(template, variables)
+    if config.window_command:
+        spawn_window(config.window_command, variables=variables, command=command, cwd=worktree)
+        return None
+    # Prefix assignments scope WF_* to the opener command alone — nothing
+    # leaks into (or goes stale in) the user's interactive shell.
+    assignments = " ".join(f"{name}={shlex.quote(value)}" for name, value in variables.items())
+    return ShellAction(f"cd {shlex.quote(str(worktree))} && {assignments} {command}")
+
+
+def spawn_window(
+    window_template: str,
+    *,
+    variables: dict[str, str],
+    command: str,
+    cwd: Path,
+) -> None:
+    """Spawn the user's window_command fully detached (DESIGN §3.4).
+
+    The resolved opener command joins the family as {command} (one argument,
+    e.g. for `$SHELL -c {command}`) / `$WF_COMMAND` (spliced into argv words);
+    it is template-only and not exported to the environment.
+    """
+    expanded = expand_template(window_template, {**variables, "WF_COMMAND": command})
+    argv = shlex.split(expanded)
+    if not argv:
+        raise WorkforestError("window_command expanded to an empty command")
+    try:
+        subprocess.Popen(
+            argv,
+            cwd=cwd,
+            env={**os.environ, **variables},
+            start_new_session=True,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except FileNotFoundError as exc:
+        raise WorkforestError(f"window_command program not found: {argv[0]!r}") from exc

{workforest-0.1.2 → workforest-0.2.0}/tests/conftest.py

@@ -149,7 +149,9 @@ class Recorder:
 def recorder(tmp_path: Path) -> Recorder:
     log = tmp_path / "recorder.log"
     script = tmp_path / "recorder"
-    script.write_text(f'#!/bin/sh\necho "argv=$* cwd=$PWD" >> {log}\n')
+    script.write_text(
+        f'#!/bin/sh\necho "argv=$* argc=$# cwd=$PWD wf_worktree=$WF_WORKTREE" >> {log}\n'
+    )
     script.chmod(script.stat().st_mode | stat.S_IXUSR)
     return Recorder(path=script, log=log)
 

{workforest-0.1.2 → workforest-0.2.0}/tests/test_cli.py

@@ -46,7 +46,8 @@ class TestStdoutContract:
         lines = result.out.splitlines()
         assert len(lines) == 1
         assert lines[0].startswith("cd ")
-        assert lines[0].endswith("&& stub-editor")
+        assert lines[0].endswith(" stub-editor")
+        assert "WF_MAIN=" in lines[0]  # WF_* rides along as prefix assignments
         assert "created worktree" in result.err  # human messages on stderr
 
     def test_no_open_emits_nothing(self, run_cli: Run, repo: Repo) -> None:
@@ -79,13 +80,13 @@ class TestShortcut:
         run_cli("create", "feat", "--no-open", cwd=repo.path)
         result = run_cli("mytool", "feat", cwd=repo.path)
         assert result.code == 0
-        assert result.out.strip().endswith("&& mytool")
+        assert result.out.strip().endswith(" mytool")
 
     def test_shortcut_passes_path(self, run_cli: Run, repo: Repo) -> None:
         run_cli("create", "feat", "--no-open", cwd=repo.path)
-        result = run_cli("mytool {path}", "feat", "-p", "README.md", cwd=repo.path)
+        result = run_cli("mytool {target}", "feat", "-p", "README.md", cwd=repo.path)
         assert result.code == 0
-        assert result.out.strip().endswith("&& mytool README.md")
+        assert result.out.strip().endswith(" mytool README.md")
 
 
 class TestExitCodes:

{workforest-0.1.2 → workforest-0.2.0}/tests/test_commands.py

@@ -49,7 +49,9 @@ class TestCreate:
         assert worktree_path.is_dir()
         assert gitutil.current_branch(worktree_path) == "feature/cool-thing"
         assert isinstance(action, ShellAction)
-        assert action.script == f"cd {worktree_path} && stub-editor"
+        assert action.script.startswith(f"cd {worktree_path} && WF_MAIN=")
+        assert action.script.endswith(" stub-editor")
+        assert "WF_BRANCH=feature/cool-thing" in action.script
 
     def test_existing_local_branch(self, repo: Repo) -> None:
         repo.add_branch("existing")
@@ -76,7 +78,8 @@ class TestCreate:
         ctx = ctx_for(repo)
         action = commands.cmd_create(ctx, None)
         assert isinstance(action, ShellAction)
-        assert action.script == f"cd {repo.path} && stub-editor"
+        assert action.script.startswith(f"cd {repo.path} && WF_MAIN=")
+        assert action.script.endswith(" stub-editor")
 
     def test_short_name_collision_errors(self, repo: Repo) -> None:
         ctx = ctx_for(repo)
@@ -120,22 +123,26 @@ class TestOpen:
         commands.cmd_create(ctx, "feat", no_open=True)
         action = commands.cmd_open(ctx, "feat")
         assert isinstance(action, ShellAction)
-        assert action.script == f"cd {ctx.worktrees_dir / 'feat'} && stub-editor"
+        assert action.script.startswith(f"cd {ctx.worktrees_dir / 'feat'} && WF_MAIN=")
+        assert action.script.endswith(" stub-editor")
 
-    def test_open_subdirectory(self, repo: Repo) -> None:
+    def test_open_subdirectory_stays_at_root(self, repo: Repo) -> None:
+        # -p never changes the launch cwd; it only sets WF_TARGET.
         ctx = ctx_for(repo)
         commands.cmd_create(ctx, "feat", no_open=True)
         (ctx.worktrees_dir / "feat" / "src").mkdir()
         action = commands.cmd_open(ctx, "feat", path_arg="src")
         assert isinstance(action, ShellAction)
-        assert action.script == f"cd {ctx.worktrees_dir / 'feat' / 'src'} && stub-editor"
+        assert action.script.startswith(f"cd {ctx.worktrees_dir / 'feat'} && ")
+        assert "WF_TARGET=src" in action.script
 
-    def test_open_file_with_path_template(self, repo: Repo) -> None:
+    def test_open_file_with_target_template(self, repo: Repo) -> None:
         ctx = ctx_for(repo)
         commands.cmd_create(ctx, "feat", no_open=True)
-        action = commands.cmd_open(ctx, "feat", opener="tool {path}", path_arg="README.md")
+        action = commands.cmd_open(ctx, "feat", opener="tool {target}", path_arg="README.md")
         assert isinstance(action, ShellAction)
-        assert action.script == f"cd {ctx.worktrees_dir / 'feat'} && tool README.md"
+        assert action.script.startswith(f"cd {ctx.worktrees_dir / 'feat'} && ")
+        assert action.script.endswith(" tool README.md")
 
     def test_open_unknown_errors(self, repo: Repo) -> None:
         with pytest.raises(WorkforestError, match="'nope' not found"):

{workforest-0.1.2 → workforest-0.2.0}/tests/test_config.py

@@ -129,10 +129,10 @@ class TestMergeSemantics:
         assert load_config(project).scripts == {}
 
     def test_openers_merge_like_scripts(self, tmp_path: Path) -> None:
-        write_system_config("openers:\n  edit: $EDITOR {path}\n")
+        write_system_config("openers:\n  edit: $EDITOR {target}\n")
         write_user_config("openers:\n  git: lazygit\n")
         cfg = load_config()
-        assert cfg.openers == {"edit": "$EDITOR {path}", "git": "lazygit"}
+        assert cfg.openers == {"edit": "$EDITOR {target}", "git": "lazygit"}
 
 
 class TestEnvOverrides:

workforest-0.2.0/tests/test_launch.py

@@ -0,0 +1,204 @@
+"""launch: opener/window template resolution and the cd protocol."""
+
+import shlex
+from pathlib import Path
+
+import pytest
+
+from workforest import launch
+from workforest.config import Config
+from workforest.errors import WorkforestError
+
+from .conftest import Recorder
+
+
+class TestOpenerResolution:
+    def test_named_opener_from_config(self) -> None:
+        cfg = Config(openers={"edit": "$EDITOR {target}"})
+        assert launch.resolve_opener_template(cfg, "edit") == "$EDITOR {target}"
+
+    def test_unknown_name_used_verbatim(self) -> None:
+        cfg = Config(openers={"edit": "$EDITOR {target}"})
+        assert launch.resolve_opener_template(cfg, "my-tool --flag") == "my-tool --flag"
+
+    def test_config_default_opener(self) -> None:
+        cfg = Config(opener="edit", openers={"edit": "$EDITOR {target}"})
+        assert launch.resolve_opener_template(cfg, None) == "$EDITOR {target}"
+
+    def test_visual_beats_editor(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("VISUAL", "visual-tool")
+        assert launch.resolve_opener_template(Config(), None) == "visual-tool"
+
+    def test_editor_fallback(self) -> None:
+        # EDITOR is pinned to stub-editor by the isolation fixture
+        assert launch.resolve_opener_template(Config(), None) == "stub-editor"
+
+    def test_no_opener_anywhere_errors(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("EDITOR")
+        with pytest.raises(WorkforestError, match="no opener"):
+            launch.resolve_opener_template(Config(), None)
+
+
+class TestLaunchVars:
+    def test_full_family(self, tmp_path: Path) -> None:
+        variables = launch.launch_vars(
+            main=tmp_path / "api",
+            worktree=tmp_path / "worktrees" / "api" / "feat",
+            worktrees_dir=tmp_path / "worktrees" / "api",
+            branch="feat/x",
+            target="src/foo.py",
+        )
+        assert variables == {
+            "WF_MAIN": str(tmp_path / "api"),
+            "WF_NAME": "api",
+            "WF_WORKTREES_DIR": str(tmp_path / "worktrees" / "api"),
+            "WF_WORKTREE": str(tmp_path / "worktrees" / "api" / "feat"),
+            "WF_BRANCH": "feat/x",
+            "WF_TARGET": "src/foo.py",
+            "WF_TITLE": "api: feat",
+        }
+
+    def test_detached_branch_is_empty(self, tmp_path: Path) -> None:
+        variables = launch.launch_vars(
+            main=tmp_path / "api",
+            worktree=tmp_path / "feat",
+            worktrees_dir=tmp_path,
+            branch=None,
+            target=".",
+        )
+        assert variables["WF_BRANCH"] == ""
+
+
+class TestTemplateExpansion:
+    def test_placeholder_is_one_quoted_argument(self) -> None:
+        result = launch.expand_template("tool {target}", {"WF_TARGET": "a file.txt"})
+        assert result == "tool 'a file.txt'"
+
+    def test_dollar_form_is_raw_and_word_splits(self) -> None:
+        result = launch.expand_template("tool $WF_TARGET", {"WF_TARGET": "--flag one"})
+        assert result == "tool --flag one"
+
+    def test_env_expansion(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("MYTOOL", "actual-tool")
+        assert launch.expand_template("$MYTOOL {target}", {"WF_TARGET": "."}) == "actual-tool ."
+
+    def test_unknown_env_left_alone(self) -> None:
+        assert launch.expand_template("tool $NO_SUCH_VAR", {}) == "tool $NO_SUCH_VAR"
+
+    def test_unknown_placeholder_errors_with_known_list(self) -> None:
+        with pytest.raises(WorkforestError, match=r"unknown placeholder \{path\}.*\{target\}"):
+            launch.expand_template("tool {path}", {"WF_TARGET": "."})
+
+    def test_values_are_inert(self) -> None:
+        # A substituted value must never be re-expanded, even if it looks
+        # like a template itself.
+        result = launch.expand_template("edit {target}", {"WF_TARGET": "$HOME/{title}"})
+        assert result == "edit '$HOME/{title}'"
+
+    def test_no_placeholder_left_alone(self) -> None:
+        assert launch.expand_template("plain-tool --flag", {"WF_TARGET": "."}) == (
+            "plain-tool --flag"
+        )
+
+
+def run_launch(
+    cfg: Config,
+    tmp_path: Path,
+    *,
+    branch: str | None = "feat",
+    opener_arg: str | None = None,
+    path_arg: str | None = None,
+) -> tuple[launch.ShellAction | None, Path]:
+    main = tmp_path / "api"
+    worktree = tmp_path / "worktrees" / "api" / "feat"
+    worktree.mkdir(parents=True, exist_ok=True)
+    action = launch.launch(
+        cfg,
+        main=main,
+        worktree=worktree,
+        worktrees_dir=worktree.parent,
+        branch=branch,
+        opener_arg=opener_arg,
+        path_arg=path_arg,
+    )
+    return action, worktree
+
+
+class TestLaunch:
+    def test_shell_action_by_default(self, tmp_path: Path) -> None:
+        action, worktree = run_launch(Config(), tmp_path)
+        assert action is not None
+        variables = launch.launch_vars(
+            main=tmp_path / "api",
+            worktree=worktree,
+            worktrees_dir=worktree.parent,
+            branch="feat",
+            target=".",
+        )
+        assignments = " ".join(f"{k}={shlex.quote(v)}" for k, v in variables.items())
+        assert action.script == f"cd {worktree} && {assignments} stub-editor"
+        # WF_* is scoped to the command via prefix assignments, not exported.
+        assert "export" not in action.script
+        assert "WF_TITLE='api: feat'" in action.script
+
+    def test_path_arg_is_target_not_cwd(self, tmp_path: Path) -> None:
+        (tmp_path / "worktrees" / "api" / "feat" / "src").mkdir(parents=True)
+        action, worktree = run_launch(
+            Config(), tmp_path, opener_arg="tool {target}", path_arg="src"
+        )
+        assert action is not None
+        # cwd stays the worktree root; -p only sets the opener argument.
+        assert action.script.startswith(f"cd {worktree} && ")
+        assert action.script.endswith(" tool src")
+        assert "WF_TARGET=src" in action.script
+
+    def test_window_command_spawns_detached(self, tmp_path: Path, recorder: Recorder) -> None:
+        cfg = Config(window_command=f"{recorder.path} --title {{title}} $WF_COMMAND")
+        action, worktree = run_launch(cfg, tmp_path, opener_arg="the-opener")
+        assert action is None  # nothing on stdout when a window is spawned
+        (line,) = recorder.wait_for_lines(1)
+        assert "--title" in line
+        assert "api: feat" in line
+        assert "the-opener" in line
+        assert f"cwd={worktree}" in line
+
+    def test_window_worktree_placeholder(self, tmp_path: Path, recorder: Recorder) -> None:
+        cfg = Config(window_command=f"{recorder.path} -d {{worktree}} $WF_COMMAND")
+        _, worktree = run_launch(cfg, tmp_path, opener_arg="x")
+        (line,) = recorder.wait_for_lines(1)
+        assert f"-d {worktree}" in line
+
+    def test_wf_command_splices_into_argv_words(self, tmp_path: Path, recorder: Recorder) -> None:
+        cfg = Config(window_command=f"{recorder.path} $WF_COMMAND")
+        run_launch(cfg, tmp_path, opener_arg="the-opener --flag")
+        (line,) = recorder.wait_for_lines(1)
+        assert "argv=the-opener --flag argc=2" in line
+
+    def test_command_placeholder_is_one_argument(self, tmp_path: Path, recorder: Recorder) -> None:
+        cfg = Config(window_command=f"{recorder.path} {{command}}")
+        run_launch(cfg, tmp_path, opener_arg="the-opener --flag")
+        (line,) = recorder.wait_for_lines(1)
+        assert "argv=the-opener --flag argc=1" in line
+
+    def test_window_process_inherits_wf_env(self, tmp_path: Path, recorder: Recorder) -> None:
+        cfg = Config(window_command=f"{recorder.path} $WF_COMMAND")
+        _, worktree = run_launch(cfg, tmp_path, opener_arg="x")
+        (line,) = recorder.wait_for_lines(1)
+        assert f"wf_worktree={worktree}" in line
+
+    def test_empty_window_command_after_expansion(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setenv("MY_TERM", "")
+        cfg = Config(window_command="$MY_TERM")
+        with pytest.raises(WorkforestError, match="empty"):
+            run_launch(cfg, tmp_path, opener_arg="x")
+
+    def test_missing_window_program(self, tmp_path: Path) -> None:
+        cfg = Config(window_command="no-such-terminal-xyz $WF_COMMAND")
+        with pytest.raises(WorkforestError, match="not found"):
+            run_launch(cfg, tmp_path, opener_arg="x")
+
+    def test_cd_action_quotes(self) -> None:
+        action = launch.cd_action(Path("/tmp/with space"))
+        assert action.script == "cd '/tmp/with space'"

{workforest-0.1.2 → workforest-0.2.0}/tests/test_shell.py

@@ -151,7 +151,7 @@ class TestCompleteBackend:
 
     def test_scripts_and_openers(self, repo: Repo, run_cli: Run) -> None:
         repo.write_project_config(
-            "scripts:\n  migrate: 'true'\n  test: 'true'\nopeners:\n  edit: '$EDITOR {path}'\n"
+            "scripts:\n  migrate: 'true'\n  test: 'true'\nopeners:\n  edit: '$EDITOR {target}'\n"
         )
         result = run_cli("--complete", "scripts", cwd=repo.path)
         assert result.out.splitlines() == ["migrate", "test"]

{workforest-0.1.2 → workforest-0.2.0}/tests/test_tui.py

@@ -49,7 +49,7 @@ class TestPureHelpers:
 class TestCarousel:
     def test_config_openers_win(self, repo: Repo) -> None:
         ctx = commands.build_context(repo.path)
-        ctx.config = Config(openers={"edit": "$EDITOR {path}", "git": "lazygit"})
+        ctx.config = Config(openers={"edit": "$EDITOR {target}", "git": "lazygit"})
         assert tui.opener_carousel(ctx) == [("edit", "edit"), ("git", "git")]
 
     def test_derived_fallback_pair(self, repo: Repo) -> None:

workforest-0.1.2/src/workforest/launch.py

@@ -1,107 +0,0 @@
-"""Opener/window template resolution and cd-protocol emission (DESIGN §3.4).
-
-No tool names appear here: what to run comes from config templates and the
-$VISUAL/$EDITOR contract; where to run it is the current shell (ShellAction)
-unless the user configured a window_command template.
-"""
-
-import os
-import shlex
-import string
-import subprocess
-from dataclasses import dataclass
-from pathlib import Path
-
-from workforest.config import Config
-from workforest.errors import WorkforestError
-
-
-@dataclass(slots=True, frozen=True)
-class ShellAction:
-    """A directive for the wf shell wrapper; the only thing cli.py prints
-    to stdout for create/open/checkout."""
-
-    script: str
-
-
-def cd_action(path: Path) -> ShellAction:
-    return ShellAction(f"cd {shlex.quote(str(path))}")
-
-
-def resolve_opener_template(config: Config, opener_arg: str | None) -> str:
-    """-o NAME → `openers` lookup, else verbatim; default $VISUAL → $EDITOR."""
-    value = opener_arg or config.opener
-    if value:
-        return config.openers.get(value, value)
-    for var in ("VISUAL", "EDITOR"):
-        if os.environ.get(var):
-            return os.environ[var]
-    raise WorkforestError(
-        "no opener: pass -o, set `opener` in a config file, or export $VISUAL/$EDITOR"
-    )
-
-
-def resolve_target(worktree: Path, path_arg: str | None) -> tuple[Path, str]:
-    """-p resolution: directories become cwd, files stay opener arguments."""
-    if path_arg in (None, "", "."):
-        return worktree, "."
-    assert path_arg is not None
-    target = worktree / path_arg
-    if target.is_dir():
-        return target, "."
-    return worktree, path_arg
-
-
-def _expand_env(template: str) -> str:
-    return string.Template(template).safe_substitute(os.environ)
-
-
-def build_opener_command(template: str, path_arg: str) -> str:
-    expanded = _expand_env(template)
-    if "{path}" in expanded:
-        return expanded.replace("{path}", shlex.quote(path_arg))
-    return expanded
-
-
-def launch(
-    config: Config,
-    *,
-    worktree: Path,
-    repo_name: str,
-    opener_arg: str | None = None,
-    path_arg: str | None = None,
-) -> ShellAction | None:
-    """Open a worktree: a ShellAction for the current shell, or a detached
-    window spawn (returning None) when window_command is configured."""
-    template = resolve_opener_template(config, opener_arg)
-    cwd, resolved_path = resolve_target(worktree, path_arg)
-    command = build_opener_command(template, resolved_path)
-    if config.window_command:
-        title = f"{repo_name}: {worktree.name}"
-        spawn_window(config.window_command, title=title, cwd=cwd, command=command)
-        return None
-    return ShellAction(f"cd {shlex.quote(str(cwd))} && {command}")
-
-
-def spawn_window(window_template: str, *, title: str, cwd: Path, command: str) -> None:
-    """Spawn the user's window_command fully detached (DESIGN §3.4)."""
-    expanded = (
-        _expand_env(window_template)
-        .replace("{title}", shlex.quote(title))
-        .replace("{path}", shlex.quote(str(cwd)))
-        .replace("{command}", command)
-    )
-    argv = shlex.split(expanded)
-    if not argv:
-        raise WorkforestError("window_command expanded to an empty command")
-    try:
-        subprocess.Popen(
-            argv,
-            cwd=cwd,
-            start_new_session=True,
-            stdin=subprocess.DEVNULL,
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-        )
-    except FileNotFoundError as exc:
-        raise WorkforestError(f"window_command program not found: {argv[0]!r}") from exc

workforest-0.1.2/tests/test_launch.py

@@ -1,113 +0,0 @@
-"""launch: opener/window template resolution and the cd protocol."""
-
-from pathlib import Path
-
-import pytest
-
-from workforest import launch
-from workforest.config import Config
-from workforest.errors import WorkforestError
-
-from .conftest import Recorder
-
-
-class TestOpenerResolution:
-    def test_named_opener_from_config(self) -> None:
-        cfg = Config(openers={"edit": "$EDITOR {path}"})
-        assert launch.resolve_opener_template(cfg, "edit") == "$EDITOR {path}"
-
-    def test_unknown_name_used_verbatim(self) -> None:
-        cfg = Config(openers={"edit": "$EDITOR {path}"})
-        assert launch.resolve_opener_template(cfg, "my-tool --flag") == "my-tool --flag"
-
-    def test_config_default_opener(self) -> None:
-        cfg = Config(opener="edit", openers={"edit": "$EDITOR {path}"})
-        assert launch.resolve_opener_template(cfg, None) == "$EDITOR {path}"
-
-    def test_visual_beats_editor(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        monkeypatch.setenv("VISUAL", "visual-tool")
-        assert launch.resolve_opener_template(Config(), None) == "visual-tool"
-
-    def test_editor_fallback(self) -> None:
-        # EDITOR is pinned to stub-editor by the isolation fixture
-        assert launch.resolve_opener_template(Config(), None) == "stub-editor"
-
-    def test_no_opener_anywhere_errors(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        monkeypatch.delenv("EDITOR")
-        with pytest.raises(WorkforestError, match="no opener"):
-            launch.resolve_opener_template(Config(), None)
-
-
-class TestTargetResolution:
-    def test_default_is_worktree_root(self, tmp_path: Path) -> None:
-        assert launch.resolve_target(tmp_path, None) == (tmp_path, ".")
-        assert launch.resolve_target(tmp_path, ".") == (tmp_path, ".")
-
-    def test_directory_becomes_cwd(self, tmp_path: Path) -> None:
-        (tmp_path / "src").mkdir()
-        assert launch.resolve_target(tmp_path, "src") == (tmp_path / "src", ".")
-
-    def test_file_stays_argument(self, tmp_path: Path) -> None:
-        (tmp_path / "README.md").write_text("x")
-        assert launch.resolve_target(tmp_path, "README.md") == (tmp_path, "README.md")
-
-    def test_missing_path_stays_argument(self, tmp_path: Path) -> None:
-        assert launch.resolve_target(tmp_path, "new-file.txt") == (tmp_path, "new-file.txt")
-
-
-class TestCommandBuilding:
-    def test_path_placeholder_substituted_and_quoted(self) -> None:
-        assert launch.build_opener_command("tool {path}", "a file.txt") == "tool 'a file.txt'"
-
-    def test_env_expansion(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        monkeypatch.setenv("MYTOOL", "actual-tool")
-        assert launch.build_opener_command("$MYTOOL {path}", ".") == "actual-tool ."
-
-    def test_no_placeholder_left_alone(self) -> None:
-        assert launch.build_opener_command("plain-tool --flag", ".") == "plain-tool --flag"
-
-
-class TestLaunch:
-    def test_shell_action_by_default(self, tmp_path: Path) -> None:
-        worktree = tmp_path / "feat"
-        worktree.mkdir()
-        action = launch.launch(Config(), worktree=worktree, repo_name="api")
-        assert action is not None
-        assert action.script == f"cd {worktree} && stub-editor"
-
-    def test_window_command_spawns_detached(self, tmp_path: Path, recorder: Recorder) -> None:
-        worktree = tmp_path / "feat"
-        worktree.mkdir()
-        cfg = Config(window_command=f"{recorder.path} --title {{title}} {{command}}")
-        action = launch.launch(cfg, worktree=worktree, repo_name="api", opener_arg="the-opener")
-        assert action is None  # nothing on stdout when a window is spawned
-        (line,) = recorder.wait_for_lines(1)
-        assert "--title" in line
-        assert "api: feat" in line
-        assert "the-opener" in line
-        assert f"cwd={worktree}" in line
-
-    def test_window_path_placeholder(self, tmp_path: Path, recorder: Recorder) -> None:
-        worktree = tmp_path / "feat"
-        worktree.mkdir()
-        cfg = Config(window_command=f"{recorder.path} -d {{path}} {{command}}")
-        launch.launch(cfg, worktree=worktree, repo_name="api", opener_arg="x")
-        (line,) = recorder.wait_for_lines(1)
-        assert f"-d {worktree}" in line
-
-    def test_empty_window_command_after_expansion(
-        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-    ) -> None:
-        monkeypatch.setenv("MY_TERM", "")
-        cfg = Config(window_command="$MY_TERM")
-        with pytest.raises(WorkforestError, match="empty"):
-            launch.launch(cfg, worktree=tmp_path, repo_name="api", opener_arg="x")
-
-    def test_missing_window_program(self, tmp_path: Path) -> None:
-        cfg = Config(window_command="no-such-terminal-xyz {command}")
-        with pytest.raises(WorkforestError, match="not found"):
-            launch.launch(cfg, worktree=tmp_path, repo_name="api", opener_arg="x")
-
-    def test_cd_action_quotes(self) -> None:
-        action = launch.cd_action(Path("/tmp/with space"))
-        assert action.script == "cd '/tmp/with space'"