workforest 0.5.2__tar.gz → 0.6.0__tar.gz

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

@@ -0,0 +1,68 @@
+# 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.
+- The editor plugins ship the CLI they drive: `packaging/binary/build.sh`
+  freezes the wheel into one self-contained executable (PyInstaller) per
+  platform, which `make vscode-build`/`make idea-build` (this machine's
+  platform) and CI (all four) put in `editors/vscode/bin/workforest` (one per
+  platform-specific `.vsix`) and `editors/idea/bin/<os>-<arch>/workforest`
+  (all of them in one plugin zip). Both trees build fine without it, and
+  both run the bundled copy when there is one — it was built with the
+  client, so the two always match; only where the package carries none do
+  they fall back to `PATH` and the usual install directories. Neither
+  client offers a setting for the path, and neither may add a second way to
+  obtain the CLI — no downloading, no installing on the user's behalf.
+- `editors/vscode/` (the VS Code extension) is a thin client: it only ever
+  spawns `workforest` — never git — and reads its machine output
+  (`list --json`, `config --json`, `--complete` lines). Terminal prompts are
+  replaced by VS Code dialogs plus `--force`/`--keep-branch`/`--delete-branch`.
+  Parsing lives in `forest.ts`, which never imports `vscode` and is
+  unit-tested with `node:test`; `cli.ts` is the only module that spawns.
+  Verify with `npm run check` there (compile, tests, `vsce package`).
+- README.md is the project reference; there is no separate design document.
+  The man pages under `man/` (`workforest.1`, `workforest.5`) are its
+  installed counterpart: any change to commands, options, config keys,
+  environment variables, or exit codes updates both README.md and the
+  affected page in the same change. `tests/test_man.py` catches drift from
+  `cli.py`, not from prose — keep the wording in sync by hand.
+- Script groups (`hooks.py`): a `bulk`/`pipeline` runs under a forked
+  supervisor that leads the process group and takes the tty exactly like a
+  command, so records, `wf stop`, `exclusive`, `cleanup`, and `-b` need no
+  group-specific code. Bulk members must never take the tty (only one
+  group can own it); they run in the supervisor's process group so a
+  signal to the group reaches them all, write to a pty when stderr is a
+  terminal (so their programs keep colors) and to a pipe otherwise, and
+  the supervisor relays their lines prefixed. A bulk always waits for
+  every member. An outcome of `-SIGINT` or exit 130 is an interruption
+  (warning, `wf` dies by SIGINT), never a failure. Forked-child bodies are
+  `# pragma: no cover`; the logic lives in tested pure helpers
+  (`_Prefixer`, `_pump`, `_bulk_outcome`, `_run_step`).
+- `editors/idea/` (the JetBrains plugin) is a thin client like the VS Code
+  one: it only ever spawns `workforest` — never git — and reads its machine
+  output (`list --json`, `--complete` lines, the last stderr line as the
+  error). Terminal prompts are replaced by IDE dialogs plus
+  `--force`/`--keep-branch`/`--delete-branch`. Parsing lives in
+  `Protocol.kt`, which is pure and unit-tested; `WorkforestCli.kt` is the
+  only file that spawns. `terminal/` is loaded only with the bundled
+  Terminal plugin (optional dependency). Verify with `./gradlew build
+  buildPlugin` there (JDK 21).
+- Logo assets are generated, never hand-edited: `assets/src/logo.svg`
+  (full size) and `assets/src/logo-icon.svg` (adapted for small formats,
+  the source of every icon) are the only files touched by hand.
+  `assets/generate` writes `assets/logo*.svg` plus the icons vendored into
+  `editors/vscode/media/` and `editors/idea/.../resources/`; each carries a
+  "do not edit" header. Adding a place that ships the logo means adding a
+  target there, not another copy. `.github/workflows/assets.yml` re-runs the
+  script on pull requests and commits any difference.

workforest-0.6.0/.github/workflows/assets.yml

@@ -0,0 +1,42 @@
+name: Assets
+
+# Every logo asset is derived from assets/src/ by assets/generate. Re-run it
+# whenever a pull request touches the sources or the script, and commit the
+# result — so a redrawn logo only ever has to be redrawn once. Pushes made
+# with GITHUB_TOKEN do not trigger workflows, so this cannot loop.
+
+on:
+  pull_request:
+    paths:
+      - assets/**
+      - .github/workflows/assets.yml
+
+permissions:
+  contents: write
+
+jobs:
+  generate:
+    # Forks cannot be pushed to with this token; leave their PRs alone.
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+
+      - name: Install rsvg-convert
+        run: sudo apt-get update && sudo apt-get install -y librsvg2-bin
+
+      - name: Regenerate assets
+        run: assets/generate
+
+      - name: Commit any difference
+        run: |
+          if git diff --quiet; then
+            echo "assets are up to date"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -am "Regenerate assets"
+          git push

workforest-0.6.0/.github/workflows/binaries.yml

@@ -0,0 +1,56 @@
+name: Binaries
+
+# The self-contained `workforest` executables the editor plugins ship, one
+# per platform (packaging/binary/build.sh). PyInstaller freezes for the
+# machine it runs on, so every target is built on a runner of its own.
+# Artifacts are named workforest-binary-<os>-<arch>, which is both the
+# `vsce package --target` identifier and the bin/<os>-<arch>/ directory the
+# JetBrains plugin looks under.
+#
+# Called by the publish workflows, dispatchable on its own, and run for a
+# pull request that touches the CLI these executables freeze — which is
+# where `make idea-build-full` gets the three platforms a single machine
+# cannot build. A pull request that leaves the CLI alone reuses whatever
+# run built it last: the binaries would be identical anyway.
+#
+# ci.yml builds linux-x64 of its own on every pull request, smoke-tests it,
+# and packages the editor clients around it; this is the full set, only
+# when it can differ.
+
+on:
+  workflow_call:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - src/**
+      - pyproject.toml
+      - uv.lock
+      - packaging/binary/**
+      - .github/workflows/binaries.yml
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - target: linux-x64
+            os: ubuntu-latest
+          - target: linux-arm64
+            os: ubuntu-24.04-arm
+          - target: darwin-x64
+            os: macos-26-intel # the standard x86_64 macOS runner
+          - target: darwin-arm64
+            os: macos-latest
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build the standalone executable
+        run: packaging/binary/build.sh
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: workforest-binary-${{ matrix.target }}
+          path: dist/binary/workforest

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

@@ -0,0 +1,162 @@
+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 groff
+
+      - 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 man-db
+
+      - 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
+          # man pages ride along in the wheel's share/man data, and shell-init
+          # puts that directory on $MANPATH for venv installs
+          MANPATH=/tmp/venv/share/man man -w workforest wf 5 workforest wf
+          /tmp/venv/bin/workforest shell-init bash | grep -q 'MANPATH=/tmp/venv/share/man'
+          # the init starter is package data too
+          git init -q /tmp/repo
+          (cd /tmp/repo && /tmp/venv/bin/workforest init)
+          test -s /tmp/repo/.workforest.yaml
+
+  binary:
+    # The self-contained executable the editor plugins ship
+    # (packaging/binary/build.sh). Only linux-x64 here, to keep PRs cheap:
+    # the other three platforms are built when publishing.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build the standalone executable
+        run: packaging/binary/build.sh
+
+      - name: Smoke test it (no Python, no venv, package data intact)
+        run: |
+          bin=$PWD/dist/binary/workforest
+          "$bin" --version
+          "$bin" shell-init bash | bash -n
+          git init -q /tmp/repo
+          cd /tmp/repo && "$bin" init && test -s .workforest.yaml
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: workforest-binary-linux-x64
+          path: dist/binary/workforest
+
+  vscode-extension:
+    # editors/vscode: compile, unit tests (node:test, no VS Code download),
+    # and the platform-specific .vsix that carries the CLI in bin/.
+    needs: binary
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: editors/vscode
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: editors/vscode/package-lock.json
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: workforest-binary-linux-x64
+          path: editors/vscode/bin
+
+      - name: Make the bundled CLI executable
+        run: chmod +x bin/workforest
+
+      - name: Install
+        run: npm ci
+
+      - name: Compile and test
+        run: npm test
+
+      - name: Package for linux-x64
+        run: npm run package -- --target linux-x64
+
+      - name: The .vsix carries the CLI
+        run: unzip -l workforest-linux-x64-*.vsix | grep -q 'extension/bin/workforest'
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: workforest-vscode
+          path: editors/vscode/*.vsix
+
+  plugin-idea:
+    # The JetBrains plugin under editors/idea: compile, unit tests, and the
+    # plugin zip, which carries one CLI per platform under bin/<os>-<arch>/
+    # (only linux-x64 here; a published build ships all four).
+    # verifyPlugin (downloads IDEs) is run by hand.
+    needs: binary
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: editors/idea
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+
+      - uses: gradle/actions/setup-gradle@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: workforest-binary-linux-x64
+          path: editors/idea/bin/linux-x64
+
+      - name: Make the bundled CLI executable
+        run: chmod +x bin/linux-x64/workforest
+
+      - name: Compile, test, package
+        run: ./gradlew --no-daemon build buildPlugin
+
+      - name: The plugin zip carries the CLI
+        run: unzip -l build/distributions/*.zip | grep -q 'bin/linux-x64/workforest'
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: workforest-idea
+          path: editors/idea/build/distributions/*.zip

workforest-0.6.0/.github/workflows/publish_idea.yml

@@ -0,0 +1,100 @@
+name: Publish JetBrains plugin
+
+# Publishes editors/idea to the JetBrains Marketplace when a release is
+# published, or on demand. One zip carrying the `workforest` executable for
+# every platform (packaging/binary/build.sh) under bin/<os>-<arch>/, so
+# installing the plugin is enough — no separate CLI install.
+#
+# The plugin has no version of its own: gradle.properties carries a
+# placeholder and the build is passed the CLI's __version__, so what the
+# Marketplace serves is always the release frozen inside it. A version
+# already on the Marketplace is skipped, which makes a re-run of an old
+# release a no-op. Needs the JB_PUBLISH_TOKEN secret (a
+# Marketplace permanent token, plugins.jetbrains.com/author/me/tokens);
+# without it the publish step is skipped. The environment variable it
+# becomes has to be PUBLISH_TOKEN — that name is the Gradle plugin's, the
+# secret's says which marketplace it opens.
+#
+# Only updates go through here: the Marketplace upload API updates an
+# existing plugin, it cannot create one. pro.buryakov.workforest (id 34090)
+# was uploaded by hand once and reviewed by the Marketplace team.
+#
+# The zip is published unsigned, which makes the IDE warn on install. To
+# sign it, add the CERTIFICATE_CHAIN, PRIVATE_KEY and PRIVATE_KEY_PASSWORD
+# secrets and pass them to the publish step as env — the Gradle plugin
+# reads exactly those names and runs signPlugin before publishPlugin. Set
+# them only once they exist: an empty value is still a value, and signing
+# with one fails.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  # The CLI the zip ships, one per platform.
+  binaries:
+    uses: ./.github/workflows/binaries.yml
+
+  publish:
+    needs: binaries
+    runs-on: ubuntu-latest
+    environment:
+      name: jetbrains-marketplace
+      url: https://plugins.jetbrains.com/plugin/34090-workforest
+    permissions:
+      contents: read
+    defaults:
+      run:
+        working-directory: editors/idea
+    env:
+      PUBLISH_TOKEN: ${{ secrets.JB_PUBLISH_TOKEN }}
+      # The Marketplace's own id for pro.buryakov.workforest; the updates
+      # API takes that, not the plugin's xml id.
+      PLUGIN_ID: "34090"
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+
+      - uses: gradle/actions/setup-gradle@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: workforest-binary-*
+          path: ${{ github.workspace }}/binaries
+
+      - name: Lay the executables out the way the plugin resolves them
+        run: |
+          for target in linux-x64 linux-arm64 darwin-x64 darwin-arm64; do
+            mkdir -p "bin/$target"
+            cp "$GITHUB_WORKSPACE/binaries/workforest-binary-$target/workforest" "bin/$target/workforest"
+            chmod +x "bin/$target/workforest"
+          done
+          ls -l bin/*
+
+      - name: Compile, test, package as the version of the CLI it ships
+        run: |
+          version=$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' "$GITHUB_WORKSPACE/src/workforest/__init__.py")
+          [ -n "$version" ] || { echo "cannot read __version__" >&2; exit 1; }
+          echo "PLUGIN_VERSION=$version" >> "$GITHUB_ENV"
+          ./gradlew --no-daemon -PpluginVersion="$version" build buildPlugin
+
+      - name: The zip carries every platform's CLI
+        run: |
+          for target in linux-x64 linux-arm64 darwin-x64 darwin-arm64; do
+            unzip -l build/distributions/*.zip | grep -q "bin/$target/workforest"
+          done
+
+      - name: Publish
+        if: env.PUBLISH_TOKEN != ''
+        run: |
+          if curl -fsS "https://plugins.jetbrains.com/api/plugins/$PLUGIN_ID/updates" \
+             | jq -e --arg v "$PLUGIN_VERSION" 'any(.[]; .version == $v)' > /dev/null; then
+            echo "workforest $PLUGIN_VERSION is already on the JetBrains Marketplace — nothing to publish."
+          else
+            ./gradlew --no-daemon -PpluginVersion="$PLUGIN_VERSION" publishPlugin
+          fi

workforest-0.6.0/.github/workflows/publish_vscode.yml

@@ -0,0 +1,96 @@
+name: Publish VS Code extension
+
+# Publishes editors/vscode to the Visual Studio Marketplace when a release
+# is published, or on demand. One .vsix per platform, each carrying the
+# `workforest` executable for it (packaging/binary/build.sh), so installing
+# the extension is enough — no separate CLI install. Linux and macOS only:
+# that is what workforest supports.
+#
+# The extension has no version of its own: package.json carries a
+# placeholder and the packaging step stamps it with the CLI's __version__,
+# so what the Marketplace serves is always the release frozen inside it. A
+# version already on the Marketplace is skipped, which makes a re-run of an
+# old release a no-op. Needs the VSCE_PAT secret (a
+# Marketplace personal access token for the publisher in package.json);
+# without it the publish step is skipped.
+#
+# That token is an Azure DevOps *global* PAT ("All accessible organizations",
+# scope Marketplace/Manage) — the Marketplace accepts nothing narrower, and
+# global PATs are decommissioned on 2026-12-01. Before then this job has to
+# move to Microsoft Entra (`vsce publish --azure-credential`, a user-assigned
+# managed identity added as a member of the publisher) or to trusted
+# publishing (`vsce publish --oidc`, no secret at all) once that ships — it is
+# in vsce's main branch but not in a release as of 3.9.2.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  # The CLI each .vsix ships, one per platform.
+  binaries:
+    uses: ./.github/workflows/binaries.yml
+
+  publish:
+    needs: binaries
+    runs-on: ubuntu-latest
+    environment:
+      name: vscode-marketplace
+      url: https://marketplace.visualstudio.com/items?itemName=ArkadyBuryakov.workforest
+    permissions:
+      contents: read
+    defaults:
+      run:
+        working-directory: editors/vscode
+    env:
+      VSCE_PAT: ${{ secrets.VSCE_PAT }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: editors/vscode/package-lock.json
+
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: workforest-binary-*
+          path: ${{ github.workspace }}/binaries
+
+      - name: Install
+        run: npm ci
+
+      - name: Compile and test
+        run: npm test
+
+      - name: Stamp the extension with the version of the CLI it ships
+        run: |
+          version=$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' "$GITHUB_WORKSPACE/src/workforest/__init__.py")
+          [ -n "$version" ] || { echo "cannot read __version__" >&2; exit 1; }
+          npm pkg set version="$version"
+          echo "packaging $version"
+
+      - name: Package one .vsix per platform, each with its own CLI
+        run: |
+          for target in linux-x64 linux-arm64 darwin-x64 darwin-arm64; do
+            rm -rf bin && mkdir bin
+            cp "$GITHUB_WORKSPACE/binaries/workforest-binary-$target/workforest" bin/workforest
+            chmod +x bin/workforest
+            npx vsce package --no-dependencies --target "$target"
+          done
+          ls -l ./*.vsix
+
+      - name: Publish
+        if: env.VSCE_PAT != ''
+        run: |
+          version=$(node -p "require('./package.json').version")
+          publisher=$(node -p "require('./package.json').publisher")
+          name=$(node -p "require('./package.json').name")
+          if npx vsce show "$publisher.$name" --json 2>/dev/null \
+             | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>process.exit(JSON.parse(d).versions.some(v=>v.version==='$version')?0:1))"; then
+            echo "$publisher.$name@$version is already on the Marketplace — nothing to publish."
+          else
+            npx vsce publish --no-dependencies --packagePath workforest-*.vsix
+          fi

{workforest-0.5.2 → workforest-0.6.0}/.gitignore

@@ -24,5 +24,15 @@ packaging/AUR/PKGBUILD
 packaging/AUR/.SRCINFO
 packaging/homebrew/workforest.rb
 
+# VS Code extension (editors/vscode)
+node_modules/
+editors/vscode/out/
+*.vsix
+
+# Bundled CLI binaries: built by packaging/binary/build.sh at package time
+editors/vscode/bin/
+editors/idea/bin/
+
 # Tooling config
 /.workforest.yaml
+/Makefile.local