workforest 0.2.3__tar.gz → 0.4.0__tar.gz

workforest-0.4.0/.claude/rules/architecture.md

@@ -0,0 +1,16 @@
+# Architecture invariants
+
+- `gitutil.py` is the only module that spawns git. Consumers get typed
+  results; worktree data comes from `--porcelain -z` output, never from
+  parsing the human-readable form.
+- `cli.py` is the sole stdout writer. Commands return
+  `ShellAction | str | None`; stdout carries the shell-wrapper cd protocol,
+  so nothing else may print there (hook/script stdout is diverted to stderr).
+- `tui.py`: everything except the fzf subprocess is pure and unit-tested;
+  fzf is the only sanctioned external tool there.
+- `completions.py` must never break the shell: any error yields an empty
+  candidate list, and output stays plain `NAME<TAB>ANNOTATION` lines.
+- `integrations/claude.py` is experimental: it reads Claude Code's private
+  on-disk state. Session lines are rewritten by JSON parsing, never by
+  string substitution.
+- README.md is the project reference; there is no separate design document.

workforest-0.4.0/.claude/rules/conventions.md

@@ -0,0 +1,12 @@
+# Code conventions
+
+- Python 3.14, uv-managed. Verify changes with `make check` (ruff lint +
+  format check, mypy, pytest with a 90% coverage floor). Run
+  `uv run ruff format .` rather than hand-formatting.
+- When a return value or constant bundles fields whose positions carry
+  meaning, use a small named dataclass — `@dataclass(slots=True,
+  frozen=True)` — not an anonymous tuple or nested dict. Plain dicts are for
+  genuine key→value lookups only (env maps, branch→remotes).
+- Pre-1.0 with zero users: on breaking changes keep the clean design and
+  state what to re-run (e.g. re-eval shell-init). Never add
+  backward-compatibility shims.

workforest-0.4.0/.claude/rules/tests.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "tests/**/*.py"
+---
+
+# Test conventions
+
+- Isolation contract (see `tests/conftest.py`): no test may read or write
+  the real environment. The autouse `isolated_env` fixture redirects HOME,
+  XDG_CONFIG_HOME, and git config, and pins SHELL=/bin/sh, EDITOR, and
+  NO_COLOR — rely on it instead of patching these per test.
+- Build repos through the `repo` / `make_repo` fixtures and the `Repo`
+  helper methods (`add_branch`, `add_remote`, `write_project_config`,
+  `make_dirty`) rather than raw git calls.
+- Coverage floor is 90% (`--cov-fail-under=90` in pyproject.toml); pure
+  helpers are expected to be unit-tested, subprocess/terminal glue may be
+  `# pragma: no cover`.

{workforest-0.2.3 → workforest-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: workforest
-Version: 0.2.3
+Version: 0.4.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>
@@ -20,6 +20,14 @@ Description-Content-Type: text/markdown
 
 # Workforest
 
+## Elevator pitch
+
+Your repo has one working directory; your AI agents want five. Workforest
+gives every feature — and every agent — its own disposable git worktree, so
+parallel work on the same repo never collides.
+
+## About
+
 Git worktree forest management: one main checkout plus any number of
 disposable, per-branch worktrees in a predictable location — created, set up,
 opened, and cleaned up with one command.
@@ -36,8 +44,8 @@ opened, and cleaned up with one command.
 - **Create** a worktree for any branch (local, remote, or brand new) and have
   it set up automatically: symlinks for untracked assets (`node_modules`,
   `.env`, …) and project-defined setup scripts.
-- **Open** it in your editor — in the current shell, or in a new terminal
-  window via a configurable command template.
+- **Open** it in your editor — in your terminal, in a new terminal window or
+  multiplexer pane, or in a GUI app, all from a small shell-command config.
 - **Run** named project scripts with well-known `WF_*` environment variables.
 - **Delete** worktrees safely, or **checkout**: collapse one back into the
   main checkout.
@@ -98,27 +106,77 @@ Layered, YAML or JSON; later layers override earlier ones:
 | project (shared) | `.workforest.yaml` in the repo root | repo policy, committed |
 | project (local) | `.vscode/` or `.idea/` `.workforest.yaml` | personal overrides, untracked |
 
-Scalars and lists replace; the `scripts`/`openers` mappings merge per key
-(`null` removes an entry). `workforest config` shows the merged result and
-where each layer came from; `workforest init` scaffolds a project file
-(`--local` for a personal one).
+Scalars and lists replace; the `openers`/`wrappers`/`scripts` mappings
+merge per key (`null` removes an entry). `workforest config` shows the
+merged result and where each layer came from; `workforest init` scaffolds a
+project file (`--local` for a personal one). Nothing in the environment
+changes the result — files and flags only.
 
 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 {target}"
-window_command: ""      # "" → current shell; or e.g.
-                        # "kitty --title {title} --directory {worktree} $WF_COMMAND"
+opener: ""              # default opener: an `openers` name or a shell command;
+                        #   "" → $VISUAL → $EDITOR
+openers: {}             # name -> what `-o NAME` runs, and where
+wrappers: {}            # name -> command that runs $WF_COMMAND elsewhere (window, pane, direnv)
 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 and `window_command` are command templates sharing one variable
-family, which the launched process (and every script) also receives as
-environment variables:
+### Openers
+
+An opener is a shell command that runs with the worktree root as working
+directory, either **in your terminal** (the default: the `wf` wrapper does
+`cd` there and runs it) or **in the background** (`background: true`:
+spawned detached, `wf` returns immediately — for GUI apps and commands that
+hand off to a daemon or multiplexer). Optionally it runs **through a
+wrapper**, a command that receives it as `$WF_COMMAND` and takes it
+somewhere else: a new terminal window, a tmux window, a `direnv exec`. With
+no config at all, `wf` runs `$VISUAL`/`$EDITOR` in your terminal.
+
+```yaml
+opener: win                 # what `wf create` / `wf open` run by default
+
+wrappers:                   # get the opener command as $WF_COMMAND
+  kitty:
+    command: kitty --title "$WF_TITLE" --directory "$WF_WORKTREE" $SHELL -c "$WF_COMMAND"
+    background: true
+  tmux:                     # the tmux server has its own environment: WF_ENV re-creates ours
+    command: tmux new-window -n "$WF_TITLE" -c "$WF_WORKTREE" "export $WF_ENV; $WF_COMMAND"
+    background: true
+
+openers:
+  edit: $EDITOR "$WF_TARGET"        # in your terminal
+  code:                             # GUI app: detached
+    command: code "$WF_WORKTREE"
+    background: true
+  kitty:                              # edit's command, in a new kitty window
+    from: edit
+    wrap: kitty
+  tmux:                              # edit's command, in a new tmux window
+    from: edit
+    wrap: tmux
+  git: lazygit
+```
+
+An entry is a shell command string, or a mapping with either `command` (a
+shell command, never a name) or `from` (another opener's command — one
+level: the target has a `command` of its own — inheriting its `background`
+unless the entry sets one), plus optionally `background: true` or
+`wrap: NAME`. `wrap` and `background` never sit on the same entry: the
+wrapper decides where the whole thing runs, via its own `background` flag.
+`-o VALUE` (and `opener:`) is an `openers` name, else a shell command;
+`-w NAME` on `create`/`open` overrides the opener's wrapper (`-w ''` for
+none). Wrappers are environment-specific, so they belong in the per-machine
+user config — a host without your terminal emulator simply has none.
+`from` and `wrap` names are checked when the config loads, so `wf config`
+reports a misspelled one.
+
+All of them are plain shell commands, run via `$SHELL -c` with one variable
+family in the environment — the same family the launched process and every
+script receive:
 
 | Variable | Value |
 |---|---|
@@ -129,16 +187,21 @@ environment variables:
 | `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). Spawned windows shed activation state inherited from
-the invoking shell (Python venv, conda, nvm, rvm) so the new session starts
-clean instead of carrying an environment it cannot deactivate.
+| `WF_ENV` | all of the above as shell-quoted `NAME=value` assignments (launch-only) |
+| `WF_COMMAND` | in a wrapper: the opener command, unexpanded |
+
+Standard shell rules apply — there is no workforest template syntax:
+`"$WF_X"` is exactly one argument, bare `$WF_X` word-splits, and `$$`,
+braces, pipes, and `&&` mean whatever your shell says they mean (a
+misspelled `$WF_VAR` expands to empty, as in any shell). `$WF_COMMAND`
+reaches the wrapper unexpanded, so run it through a shell of its own for its
+`$WF_*` references to resolve: `$SHELL -c "$WF_COMMAND"`. When that shell
+runs somewhere this environment is not inherited — a tmux server, an ssh
+host — hand the family over as text: `"export $WF_ENV; $WF_COMMAND"` is
+re-parsed on the far side, quoting intact. Background
+processes shed activation state inherited from the invoking shell (Python
+venv, conda, nvm, rvm) so a new window starts clean instead of carrying an
+environment it cannot deactivate.
 
 Fully commented reference configs:
 [`config.yaml`](src/workforest/examples/config.yaml) (user/system) and
@@ -177,8 +240,8 @@ scripts:
 ## Commands
 
 ```
-workforest create [BRANCH] [-o OPENER] [-p PATH] [--no-hooks] [--no-open]
-workforest open   [NAME]   [-o OPENER] [-p PATH]
+workforest create [BRANCH] [-o OPENER] [-w WRAPPER] [-p PATH] [--no-hooks] [--no-open]
+workforest open   [NAME]   [-o OPENER] [-w WRAPPER] [-p PATH]
 workforest list   [--porcelain]
 workforest delete NAME...  [--force] [--delete-branch | --keep-branch]
 workforest checkout NAME   [--force]
@@ -187,8 +250,23 @@ workforest tui    [MODE]
 workforest init   [--local]
 workforest config [--json]
 workforest shell-init [bash|zsh]
+workforest claude copy-session SESSION_ID   # experimental
 ```
 
+`open` (and the opener shortcut, e.g. `wf edit`) without NAME opens the
+worktree you are standing in.
+
+`create` resolves BRANCH in order: existing local branch, then a branch on
+exactly one remote (checked out tracking it), then a brand-new branch.
+`REMOTE/BRANCH` picks the remote explicitly — needed when several remotes
+carry the same branch name; if that local name is already taken, `create`
+prompts for a different one.
+
+`workforest claude` (shown only when `~/.claude` exists) copies a Claude
+Code session from the main worktree into the current one. It is
+**experimental**: it manipulates Claude Code's private on-disk state,
+which is not a stable interface, so any Claude Code update may break it.
+
 Exit codes: `0` ok · `1` error · `2` usage · `3` cancelled · `4` config error.
 Human messages go to stderr; stdout carries only machine output (`cd`
 directives for the `wf` wrapper, `--porcelain` listings, dumps).

{workforest-0.2.3 → workforest-0.4.0}/README.md

@@ -1,5 +1,13 @@
 # Workforest
 
+## Elevator pitch
+
+Your repo has one working directory; your AI agents want five. Workforest
+gives every feature — and every agent — its own disposable git worktree, so
+parallel work on the same repo never collides.
+
+## About
+
 Git worktree forest management: one main checkout plus any number of
 disposable, per-branch worktrees in a predictable location — created, set up,
 opened, and cleaned up with one command.
@@ -16,8 +24,8 @@ opened, and cleaned up with one command.
 - **Create** a worktree for any branch (local, remote, or brand new) and have
   it set up automatically: symlinks for untracked assets (`node_modules`,
   `.env`, …) and project-defined setup scripts.
-- **Open** it in your editor — in the current shell, or in a new terminal
-  window via a configurable command template.
+- **Open** it in your editor — in your terminal, in a new terminal window or
+  multiplexer pane, or in a GUI app, all from a small shell-command config.
 - **Run** named project scripts with well-known `WF_*` environment variables.
 - **Delete** worktrees safely, or **checkout**: collapse one back into the
   main checkout.
@@ -78,27 +86,77 @@ Layered, YAML or JSON; later layers override earlier ones:
 | project (shared) | `.workforest.yaml` in the repo root | repo policy, committed |
 | project (local) | `.vscode/` or `.idea/` `.workforest.yaml` | personal overrides, untracked |
 
-Scalars and lists replace; the `scripts`/`openers` mappings merge per key
-(`null` removes an entry). `workforest config` shows the merged result and
-where each layer came from; `workforest init` scaffolds a project file
-(`--local` for a personal one).
+Scalars and lists replace; the `openers`/`wrappers`/`scripts` mappings
+merge per key (`null` removes an entry). `workforest config` shows the
+merged result and where each layer came from; `workforest init` scaffolds a
+project file (`--local` for a personal one). Nothing in the environment
+changes the result — files and flags only.
 
 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 {target}"
-window_command: ""      # "" → current shell; or e.g.
-                        # "kitty --title {title} --directory {worktree} $WF_COMMAND"
+opener: ""              # default opener: an `openers` name or a shell command;
+                        #   "" → $VISUAL → $EDITOR
+openers: {}             # name -> what `-o NAME` runs, and where
+wrappers: {}            # name -> command that runs $WF_COMMAND elsewhere (window, pane, direnv)
 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 and `window_command` are command templates sharing one variable
-family, which the launched process (and every script) also receives as
-environment variables:
+### Openers
+
+An opener is a shell command that runs with the worktree root as working
+directory, either **in your terminal** (the default: the `wf` wrapper does
+`cd` there and runs it) or **in the background** (`background: true`:
+spawned detached, `wf` returns immediately — for GUI apps and commands that
+hand off to a daemon or multiplexer). Optionally it runs **through a
+wrapper**, a command that receives it as `$WF_COMMAND` and takes it
+somewhere else: a new terminal window, a tmux window, a `direnv exec`. With
+no config at all, `wf` runs `$VISUAL`/`$EDITOR` in your terminal.
+
+```yaml
+opener: win                 # what `wf create` / `wf open` run by default
+
+wrappers:                   # get the opener command as $WF_COMMAND
+  kitty:
+    command: kitty --title "$WF_TITLE" --directory "$WF_WORKTREE" $SHELL -c "$WF_COMMAND"
+    background: true
+  tmux:                     # the tmux server has its own environment: WF_ENV re-creates ours
+    command: tmux new-window -n "$WF_TITLE" -c "$WF_WORKTREE" "export $WF_ENV; $WF_COMMAND"
+    background: true
+
+openers:
+  edit: $EDITOR "$WF_TARGET"        # in your terminal
+  code:                             # GUI app: detached
+    command: code "$WF_WORKTREE"
+    background: true
+  kitty:                              # edit's command, in a new kitty window
+    from: edit
+    wrap: kitty
+  tmux:                              # edit's command, in a new tmux window
+    from: edit
+    wrap: tmux
+  git: lazygit
+```
+
+An entry is a shell command string, or a mapping with either `command` (a
+shell command, never a name) or `from` (another opener's command — one
+level: the target has a `command` of its own — inheriting its `background`
+unless the entry sets one), plus optionally `background: true` or
+`wrap: NAME`. `wrap` and `background` never sit on the same entry: the
+wrapper decides where the whole thing runs, via its own `background` flag.
+`-o VALUE` (and `opener:`) is an `openers` name, else a shell command;
+`-w NAME` on `create`/`open` overrides the opener's wrapper (`-w ''` for
+none). Wrappers are environment-specific, so they belong in the per-machine
+user config — a host without your terminal emulator simply has none.
+`from` and `wrap` names are checked when the config loads, so `wf config`
+reports a misspelled one.
+
+All of them are plain shell commands, run via `$SHELL -c` with one variable
+family in the environment — the same family the launched process and every
+script receive:
 
 | Variable | Value |
 |---|---|
@@ -109,16 +167,21 @@ environment variables:
 | `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). Spawned windows shed activation state inherited from
-the invoking shell (Python venv, conda, nvm, rvm) so the new session starts
-clean instead of carrying an environment it cannot deactivate.
+| `WF_ENV` | all of the above as shell-quoted `NAME=value` assignments (launch-only) |
+| `WF_COMMAND` | in a wrapper: the opener command, unexpanded |
+
+Standard shell rules apply — there is no workforest template syntax:
+`"$WF_X"` is exactly one argument, bare `$WF_X` word-splits, and `$$`,
+braces, pipes, and `&&` mean whatever your shell says they mean (a
+misspelled `$WF_VAR` expands to empty, as in any shell). `$WF_COMMAND`
+reaches the wrapper unexpanded, so run it through a shell of its own for its
+`$WF_*` references to resolve: `$SHELL -c "$WF_COMMAND"`. When that shell
+runs somewhere this environment is not inherited — a tmux server, an ssh
+host — hand the family over as text: `"export $WF_ENV; $WF_COMMAND"` is
+re-parsed on the far side, quoting intact. Background
+processes shed activation state inherited from the invoking shell (Python
+venv, conda, nvm, rvm) so a new window starts clean instead of carrying an
+environment it cannot deactivate.
 
 Fully commented reference configs:
 [`config.yaml`](src/workforest/examples/config.yaml) (user/system) and
@@ -157,8 +220,8 @@ scripts:
 ## Commands
 
 ```
-workforest create [BRANCH] [-o OPENER] [-p PATH] [--no-hooks] [--no-open]
-workforest open   [NAME]   [-o OPENER] [-p PATH]
+workforest create [BRANCH] [-o OPENER] [-w WRAPPER] [-p PATH] [--no-hooks] [--no-open]
+workforest open   [NAME]   [-o OPENER] [-w WRAPPER] [-p PATH]
 workforest list   [--porcelain]
 workforest delete NAME...  [--force] [--delete-branch | --keep-branch]
 workforest checkout NAME   [--force]
@@ -167,8 +230,23 @@ workforest tui    [MODE]
 workforest init   [--local]
 workforest config [--json]
 workforest shell-init [bash|zsh]
+workforest claude copy-session SESSION_ID   # experimental
 ```
 
+`open` (and the opener shortcut, e.g. `wf edit`) without NAME opens the
+worktree you are standing in.
+
+`create` resolves BRANCH in order: existing local branch, then a branch on
+exactly one remote (checked out tracking it), then a brand-new branch.
+`REMOTE/BRANCH` picks the remote explicitly — needed when several remotes
+carry the same branch name; if that local name is already taken, `create`
+prompts for a different one.
+
+`workforest claude` (shown only when `~/.claude` exists) copies a Claude
+Code session from the main worktree into the current one. It is
+**experimental**: it manipulates Claude Code's private on-disk state,
+which is not a stable interface, so any Claude Code update may break it.
+
 Exit codes: `0` ok · `1` error · `2` usage · `3` cancelled · `4` config error.
 Human messages go to stderr; stdout carries only machine output (`cd`
 directives for the `wf` wrapper, `--porcelain` listings, dumps).

workforest-0.4.0/completions/_workforest

@@ -0,0 +1,44 @@
+#compdef workforest wf
+# zsh completion for workforest / wf — installed to zsh site-functions.
+# Dynamic candidates are delegated to `workforest --complete TOPIC`.
+
+local topic cmd line name rest kind desc
+local -a items cmds
+cmd="${words[2]:-}"
+if (( CURRENT == 2 )); then
+    topic=commands
+else
+    case "$cmd" in
+        create) topic=branches ;;
+        open|delete|checkout) topic=worktrees ;;
+        run) topic=scripts ;;
+        claude) topic=claude-sessions ;;
+        tui|list|init|config|shell-init) topic=none ;;
+        *) topic=worktrees ;;
+    esac
+fi
+if [[ "$topic" != none ]]; then
+    items=(${(f)"$(workforest --complete "$topic" 2>/dev/null)"})
+    if [[ "$topic" == commands ]]; then
+        # NAME<TAB>KIND<TAB>DESCRIPTION → described candidates; one group
+        # (kind spelled out in the description) so list order, alignment,
+        # and the command/opener distinction survive fzf-tab's merging.
+        # Cyan for openers, but only under fzf-tab (fzf renders ANSI with
+        # --ansi; plain complist would print the escapes literally).
+        local pre="" post=""
+        if (( ${+functions[fzf-tab-complete]} )); then
+            pre=$'\e[36m' post=$'\e[0m'
+        fi
+        for line in "${items[@]}"; do
+            name="${line%%$'\t'*}"
+            rest="${line#*$'\t'}"
+            kind="${rest%%$'\t'*}"
+            desc="${rest#*$'\t'}"
+            [[ "$kind" == opener ]] && desc="${pre}opener: ${desc}${post}"
+            cmds+=("${name//:/\\:}:${desc}")
+        done
+        (( ${#cmds} )) && _describe -t commands 'workforest command' cmds
+    else
+        (( ${#items} )) && compadd -a items
+    fi
+fi

{workforest-0.2.3 → workforest-0.4.0}/src/workforest/__init__.py

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