workforest 0.1.0__tar.gz

workforest-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    container: archlinux:latest
+    steps:
+      - name: Install system dependencies
+        run: pacman -Syu --noconfirm git python uv make zsh
+
+      - uses: actions/checkout@v4
+
+      - name: Sync dev environment
+        run: uv sync
+
+      - name: Lint, type-check, test
+        run: make check
+
+  package-smoke:
+    # Builds the wheel the AUR package would build and installs it into a
+    # clean venv — catches missing package data and broken entry points.
+    # The full `makepkg -si` + namcap check runs in the release workflow,
+    # where a source tarball exists.
+    runs-on: ubuntu-latest
+    container: archlinux:latest
+    steps:
+      - name: Install system dependencies
+        run: pacman -Syu --noconfirm git python python-build python-installer python-wheel python-hatchling
+
+      - uses: actions/checkout@v4
+
+      - name: Build wheel (no isolation, like the PKGBUILD)
+        run: python -m build --wheel --no-isolation
+
+      - name: Install into a clean venv and smoke test
+        run: |
+          python -m venv /tmp/venv
+          /tmp/venv/bin/pip install dist/*.whl
+          /tmp/venv/bin/workforest --version
+          /tmp/venv/bin/wf --version
+          /tmp/venv/bin/workforest shell-init bash | bash -n
+          /tmp/venv/bin/workforest shell-init zsh | head -1 | grep -q Workforest

workforest-0.1.0/.github/workflows/publish_pypi.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC for PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

workforest-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Read package version
+        id: version
+        run: |
+          version=$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' src/workforest/__init__.py)
+          if [ -z "$version" ]; then
+            echo "Could not parse __version__ from src/workforest/__init__.py" >&2
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Create tag and release if missing
+        env:
+          # Must be a PAT, not github.token: releases created with the default
+          # token do not trigger the release-published publisher workflows.
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          tag="v${{ steps.version.outputs.version }}"
+          if git ls-remote --exit-code --tags origin "refs/tags/$tag" > /dev/null; then
+            echo "Tag $tag already exists — nothing to release."
+          else
+            gh release create "$tag" --target "$GITHUB_SHA" --generate-notes
+          fi

workforest-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Packaging artifacts
+*.pkg.tar.zst
+pkg/
+
+# Tooling config
+.workforest.yaml

workforest-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arkady Buryakov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

workforest-0.1.0/Makefile

@@ -0,0 +1,33 @@
+# Dev targets wrap `uv run`; `uv sync` is the only setup step.
+
+.PHONY: check test lint type cov sync install uninstall
+
+sync:
+	uv sync
+
+test:
+	uv run pytest
+
+lint:
+	uv run ruff check .
+	uv run ruff format --check .
+
+type:
+	uv run mypy
+
+check: lint type test
+
+cov:
+	uv run pytest --cov-report=html
+	@echo "open htmlcov/index.html"
+
+# Install the current checkout as a uv tool (~/.local/bin/workforest).
+# --reinstall so re-running picks up changes even without a version bump.
+install:
+	uv tool install --reinstall .
+	@echo
+	@echo 'workforest installed. Make sure your shell rc has:'
+	@echo '  eval "$$(workforest shell-init)"'
+
+uninstall:
+	uv tool uninstall workforest

workforest-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: workforest
+Version: 0.1.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/arkadyb/workforest
+Author-email: Arkady Buryakov <arkady@buryakov.pro>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,developer-tools,git,worktree
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.14
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# Workforest
+
+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.
+
+```
+~/dev/
+├── api/                  # main checkout
+└── worktrees/
+    └── api/
+        ├── feature-x/    # wf create feature-x
+        └── fix-y/
+```
+
+- **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.
+- **Run** named project scripts with well-known `WF_*` environment variables.
+- **Delete** worktrees safely, or **checkout**: collapse one back into the
+  main checkout.
+- Drive everything from an interactive fzf **TUI** (`wf` with no arguments).
+
+## Install
+
+```sh
+# Arch Linux
+yay -S workforest        # AUR
+
+# anywhere else
+uv tool install workforest   # or: pipx install workforest
+```
+
+This installs two commands: `workforest` and its alias `wf`. Then add one
+line to your `~/.bashrc` / `~/.zshrc`:
+
+```sh
+eval "$(workforest shell-init)"
+```
+
+This upgrades `wf` to a shell function (needed so `wf open` can change your
+shell's directory — a plain binary cannot) and registers completions. Without
+it everything still works, but "open in current shell" prints the `cd`
+command instead of performing it.
+
+Requirements: Linux, git ≥ 2.36, Python ≥ 3.14. Optional: `fzf` for the TUI.
+
+## Quick start
+
+```sh
+wf create feature/login     # create worktree + run hooks + open in $EDITOR
+wf list                     # what's in the forest
+wf open login -o 'lazygit'  # open with any command instead
+wf run test                 # run a named script from config
+wf run make check -j2       # extra args are appended to the script command
+wf checkout login           # fold the branch back into the main checkout
+wf delete fix-y             # remove a worktree (asks about dirty changes)
+wf                          # interactive TUI (fzf)
+```
+
+Any unknown first word is an opener shortcut: `wf edit api` ≡
+`wf open api -o edit`.
+
+## Configuration
+
+Layered, YAML or JSON; later layers override earlier ones:
+
+| Layer | Location | Typical content |
+|---|---|---|
+| system | `/etc/workforest/config.yaml` | org-wide defaults |
+| user | `~/.config/workforest/config.yaml` | your terminal/editor setup |
+| 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).
+
+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}"
+window_command: ""      # "" → current shell; or e.g.
+                        # "kitty --title {title} --directory {path} {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`.
+
+Fully commented reference configs:
+[`config.yaml`](src/workforest/examples/config.yaml) (user/system) and
+[`.workforest.yaml`](src/workforest/examples/.workforest.yaml) (project) —
+installed to `/usr/share/doc/workforest/examples/` by the Arch package.
+
+### Script environment
+
+`setup_scripts`, `scripts`, and hooks run via `$SHELL -c` with:
+
+| Variable | Value |
+|---|---|
+| `WF_MAIN` | main worktree path |
+| `WF_NAME` | repo name (main checkout directory name) |
+| `WF_WORKTREE` | current/new worktree path |
+| `WF_WORKTREES_DIR` | resolved worktrees directory |
+| `WF_BRANCH` | branch of the current/new worktree |
+
+`worktrees_dir` is a template using the same naming pattern: `$WF_MAIN` and
+`$WF_NAME` (plus regular environment variables like `$HOME`) expand there —
+the per-worktree variables don't, since no worktree exists yet when the base
+directory is resolved.
+
+### Example project config
+
+```yaml
+# .workforest.yaml — committed to the repo
+symlinks: [node_modules, .env]
+setup_scripts:
+  - npm install --prefer-offline
+scripts:
+  test: npm test
+  migrate: npm run db:migrate
+```
+
+## Commands
+
+```
+workforest create [BRANCH] [-o OPENER] [-p PATH] [--no-hooks] [--no-open]
+workforest open   [NAME]   [-o OPENER] [-p PATH]
+workforest list   [--porcelain]
+workforest delete NAME...  [--force] [--delete-branch | --keep-branch]
+workforest checkout NAME   [--force]
+workforest run    SCRIPT [ARGS...]
+workforest tui    [MODE]
+workforest init   [--local]
+workforest config [--json]
+workforest shell-init [bash|zsh]
+```
+
+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).
+
+## Development
+
+```sh
+uv sync           # venv + dev dependencies (uv.lock)
+make check        # ruff + mypy --strict + pytest (coverage gate ≥ 90%)
+make install      # install this checkout as a uv tool (~/.local/bin/workforest)
+make uninstall    # remove it again
+```
+
+Packaging recipes live under
+`packaging/` (one directory per package manager; currently `packaging/AUR/`).
+Release: bump `__version__`, tag, update `sha256sums` in
+`packaging/AUR/PKGBUILD`, regenerate `.SRCINFO`
+(`makepkg --printsrcinfo > .SRCINFO` inside `packaging/AUR/`), push to AUR.
+
+## License
+
+[MIT](./LICENSE)

workforest-0.1.0/README.md

@@ -0,0 +1,169 @@
+# Workforest
+
+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.
+
+```
+~/dev/
+├── api/                  # main checkout
+└── worktrees/
+    └── api/
+        ├── feature-x/    # wf create feature-x
+        └── fix-y/
+```
+
+- **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.
+- **Run** named project scripts with well-known `WF_*` environment variables.
+- **Delete** worktrees safely, or **checkout**: collapse one back into the
+  main checkout.
+- Drive everything from an interactive fzf **TUI** (`wf` with no arguments).
+
+## Install
+
+```sh
+# Arch Linux
+yay -S workforest        # AUR
+
+# anywhere else
+uv tool install workforest   # or: pipx install workforest
+```
+
+This installs two commands: `workforest` and its alias `wf`. Then add one
+line to your `~/.bashrc` / `~/.zshrc`:
+
+```sh
+eval "$(workforest shell-init)"
+```
+
+This upgrades `wf` to a shell function (needed so `wf open` can change your
+shell's directory — a plain binary cannot) and registers completions. Without
+it everything still works, but "open in current shell" prints the `cd`
+command instead of performing it.
+
+Requirements: Linux, git ≥ 2.36, Python ≥ 3.14. Optional: `fzf` for the TUI.
+
+## Quick start
+
+```sh
+wf create feature/login     # create worktree + run hooks + open in $EDITOR
+wf list                     # what's in the forest
+wf open login -o 'lazygit'  # open with any command instead
+wf run test                 # run a named script from config
+wf run make check -j2       # extra args are appended to the script command
+wf checkout login           # fold the branch back into the main checkout
+wf delete fix-y             # remove a worktree (asks about dirty changes)
+wf                          # interactive TUI (fzf)
+```
+
+Any unknown first word is an opener shortcut: `wf edit api` ≡
+`wf open api -o edit`.
+
+## Configuration
+
+Layered, YAML or JSON; later layers override earlier ones:
+
+| Layer | Location | Typical content |
+|---|---|---|
+| system | `/etc/workforest/config.yaml` | org-wide defaults |
+| user | `~/.config/workforest/config.yaml` | your terminal/editor setup |
+| 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).
+
+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}"
+window_command: ""      # "" → current shell; or e.g.
+                        # "kitty --title {title} --directory {path} {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`.
+
+Fully commented reference configs:
+[`config.yaml`](src/workforest/examples/config.yaml) (user/system) and
+[`.workforest.yaml`](src/workforest/examples/.workforest.yaml) (project) —
+installed to `/usr/share/doc/workforest/examples/` by the Arch package.
+
+### Script environment
+
+`setup_scripts`, `scripts`, and hooks run via `$SHELL -c` with:
+
+| Variable | Value |
+|---|---|
+| `WF_MAIN` | main worktree path |
+| `WF_NAME` | repo name (main checkout directory name) |
+| `WF_WORKTREE` | current/new worktree path |
+| `WF_WORKTREES_DIR` | resolved worktrees directory |
+| `WF_BRANCH` | branch of the current/new worktree |
+
+`worktrees_dir` is a template using the same naming pattern: `$WF_MAIN` and
+`$WF_NAME` (plus regular environment variables like `$HOME`) expand there —
+the per-worktree variables don't, since no worktree exists yet when the base
+directory is resolved.
+
+### Example project config
+
+```yaml
+# .workforest.yaml — committed to the repo
+symlinks: [node_modules, .env]
+setup_scripts:
+  - npm install --prefer-offline
+scripts:
+  test: npm test
+  migrate: npm run db:migrate
+```
+
+## Commands
+
+```
+workforest create [BRANCH] [-o OPENER] [-p PATH] [--no-hooks] [--no-open]
+workforest open   [NAME]   [-o OPENER] [-p PATH]
+workforest list   [--porcelain]
+workforest delete NAME...  [--force] [--delete-branch | --keep-branch]
+workforest checkout NAME   [--force]
+workforest run    SCRIPT [ARGS...]
+workforest tui    [MODE]
+workforest init   [--local]
+workforest config [--json]
+workforest shell-init [bash|zsh]
+```
+
+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).
+
+## Development
+
+```sh
+uv sync           # venv + dev dependencies (uv.lock)
+make check        # ruff + mypy --strict + pytest (coverage gate ≥ 90%)
+make install      # install this checkout as a uv tool (~/.local/bin/workforest)
+make uninstall    # remove it again
+```
+
+Packaging recipes live under
+`packaging/` (one directory per package manager; currently `packaging/AUR/`).
+Release: bump `__version__`, tag, update `sha256sums` in
+`packaging/AUR/PKGBUILD`, regenerate `.SRCINFO`
+(`makepkg --printsrcinfo > .SRCINFO` inside `packaging/AUR/`), push to AUR.
+
+## License
+
+[MIT](./LICENSE)

workforest-0.1.0/completions/_workforest

@@ -0,0 +1,23 @@
+#compdef workforest wf
+# zsh completion for workforest / wf — installed to zsh site-functions.
+# Dynamic candidates are delegated to `workforest --complete TOPIC`.
+
+local topic cmd
+local -a items
+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)"})
+    (( ${#items} )) && compadd -a items
+fi

workforest-0.1.0/packaging/AUR/.SRCINFO

@@ -0,0 +1,19 @@
+pkgbase = workforest
+	pkgdesc = Git worktree forest management: per-branch worktrees with project-defined setup hooks
+	pkgver = 0.1.0
+	pkgrel = 1
+	url = https://github.com/arkadyb/workforest
+	arch = any
+	license = MIT
+	makedepends = python-build
+	makedepends = python-installer
+	makedepends = python-wheel
+	makedepends = python-hatchling
+	depends = python
+	depends = python-yaml
+	depends = git
+	optdepends = fzf: interactive TUI (workforest tui)
+	source = workforest-0.1.0.tar.gz::https://github.com/arkadyb/workforest/archive/v0.1.0.tar.gz
+	sha256sums = SKIP
+
+pkgname = workforest

workforest-0.1.0/packaging/AUR/PKGBUILD

@@ -0,0 +1,37 @@
+# Maintainer: Arkady Buryakov <arkady@buryakov.pro>
+pkgname=workforest
+pkgver=0.1.0
+pkgrel=1
+pkgdesc="Git worktree forest management: per-branch worktrees with project-defined setup hooks"
+arch=(any)
+url="https://github.com/arkadyb/workforest"
+license=(MIT)
+depends=(python python-yaml git)
+makedepends=(python-build python-installer python-wheel python-hatchling)
+optdepends=('fzf: interactive TUI (workforest tui)')
+source=("$pkgname-$pkgver.tar.gz::$url/archive/v$pkgver.tar.gz")
+sha256sums=('SKIP') # set the real checksum when cutting a release
+
+build() {
+  cd "$pkgname-$pkgver"
+  python -m build --wheel --no-isolation
+}
+
+package() {
+  cd "$pkgname-$pkgver"
+  python -m installer --destdir="$pkgdir" dist/*.whl
+
+  install -Dm644 LICENSE "$pkgdir/usr/share/licenses/$pkgname/LICENSE"
+
+  # Shell completions (the wf function itself comes from `workforest shell-init`)
+  install -Dm644 src/workforest/shell/completion.bash \
+    "$pkgdir/usr/share/bash-completion/completions/workforest"
+  install -Dm644 completions/_workforest \
+    "$pkgdir/usr/share/zsh/site-functions/_workforest"
+
+  # Reference configs (DESIGN §4.3)
+  install -Dm644 src/workforest/examples/config.yaml \
+    "$pkgdir/usr/share/doc/$pkgname/examples/config.yaml"
+  install -Dm644 src/workforest/examples/.workforest.yaml \
+    "$pkgdir/usr/share/doc/$pkgname/examples/workforest.project.yaml"
+}