herdr-worktreeinclude 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes are published in the [GitHub Releases](https://github.com/serhii-chernenko/herdr-worktreeinclude/releases) generated from version tags.
+
+## 0.1.0
+
+- Initial Herdr plugin: project-local worktrees, `.worktreeinclude` copying, and UI-first branch cleanup.

package/README.md

@@ -0,0 +1,91 @@
+# herdr-worktreeinclude
+
+A [Herdr](https://herdr.dev) plugin that keeps Herdr-created Git worktrees inside the project and restores selected ignored files into them.
+
+## What it does
+
+Use Herdr's normal **New worktree** UI. After creation, the plugin automatically:
+
+- moves the checkout from Herdr's global directory to `<project>/.herdr/worktrees/<branch>`;
+- copies files selected by `.worktreeinclude` from the primary checkout;
+- opens the relocated worktree as the active Herdr workspace.
+
+When you remove a plugin-managed worktree through Herdr's normal UI, an unchanged branch (one already contained in the primary checkout's `HEAD`) is removed silently. For a branch with unique commits, Herdr shows an in-terminal overlay: press `d` to safely delete the local branch or Enter to keep it.
+
+The plugin cannot change Herdr's built-in creation/removal dialogs. It uses lifecycle hooks immediately after those dialogs complete.
+
+## Requirements
+
+- Herdr with plugin support (currently the Preview channel)
+- Git
+- Node.js 20 or later
+- macOS or Linux
+
+## Install
+
+Once the repository is public and tagged with the GitHub topic `herdr-plugin`:
+
+```bash
+herdr plugin install serhii-chernenko/herdr-worktreeinclude
+```
+
+To install a specific release:
+
+```bash
+herdr plugin install serhii-chernenko/herdr-worktreeinclude --ref v0.1.0
+```
+
+For local development, link it into the current Herdr session:
+
+```bash
+herdr plugin link /path/to/herdr-worktreeinclude
+```
+
+Plugins are registered per Herdr session. For a named session, include its name:
+
+```bash
+herdr --session my-session plugin link /path/to/herdr-worktreeinclude
+```
+
+## Configure copied files
+
+Create `.worktreeinclude` at the project root. It uses `.gitignore` pattern syntax, but a file is copied only when it is both selected by `.worktreeinclude` and ignored by Git.
+
+```gitignore
+# .gitignore
+.env
+config/local/
+```
+
+```gitignore
+# .worktreeinclude
+.env
+config/local/
+```
+
+Tracked files are never copied. Existing destination files are not overwritten. Symlinks and file modes are preserved.
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+After changing the manifest or scripts, relink the plugin in the target Herdr session:
+
+```bash
+herdr plugin unlink serhii-chernenko.worktreeinclude
+herdr plugin link "$(pwd)"
+```
+
+## Releases
+
+The npm package and Herdr manifest share one version. Before publishing, update both `package.json` and `herdr-plugin.toml`, add release notes to `CHANGELOG.md`, then commit and push a matching tag:
+
+```bash
+git tag v0.1.1
+git push origin main v0.1.1
+```
+
+The tag workflow verifies the version, publishes to npm through npm Trusted Publishing, and creates GitHub Release notes automatically. After claiming the package name with an initial manual publish, configure npm's Trusted Publisher for GitHub repository `serhii-chernenko/herdr-worktreeinclude` and workflow filename `publish.yml`. Subsequent matching version tags publish without a stored npm token.

package/herdr-plugin.toml

@@ -0,0 +1,26 @@
+id = "serhii-chernenko.worktreeinclude"
+name = "Project-local Worktrees"
+version = "0.1.0"
+min_herdr_version = "0.7.0"
+description = "Creates project-local Git worktrees and restores ignored files selected by .worktreeinclude."
+platforms = ["macos", "linux"]
+
+[[events]]
+on = "worktree.created"
+command = ["bash", "scripts/on-worktree-created.sh"]
+
+[[events]]
+on = "worktree.removed"
+command = ["bash", "scripts/on-worktree-removed.sh"]
+
+[[panes]]
+id = "create"
+title = "Create project-local worktree"
+placement = "tab"
+command = ["bash", "scripts/create-worktree.sh"]
+
+[[panes]]
+id = "branch-cleanup"
+title = "Delete local branch?"
+placement = "overlay"
+command = ["bash", "scripts/branch-cleanup-pane.sh"]

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "herdr-worktreeinclude",
+  "version": "0.1.0",
+  "description": "Project-local Git worktrees and .worktreeinclude support for Herdr.",
+  "keywords": [
+    "herdr",
+    "herdr-plugin",
+    "git-worktree",
+    "worktreeinclude"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/serhii-chernenko/herdr-worktreeinclude.git"
+  },
+  "bugs": {
+    "url": "https://github.com/serhii-chernenko/herdr-worktreeinclude/issues"
+  },
+  "homepage": "https://github.com/serhii-chernenko/herdr-worktreeinclude#readme",
+  "files": [
+    "herdr-plugin.toml",
+    "scripts/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "bash tests/copy-worktreeinclude.sh && bash tests/create-worktree.sh",
+    "check": "bash -n scripts/*.sh tests/*.sh && node --check scripts/*.mjs && npm run test",
+    "release:check": "node scripts/assert-release-version.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/assert-release-version.mjs

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+
+const packageVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url))).version;
+const manifest = readFileSync(new URL("../herdr-plugin.toml", import.meta.url), "utf8");
+const manifestVersion = manifest.match(/^version\s*=\s*"([^"]+)"\s*$/m)?.[1];
+
+if (!manifestVersion || manifestVersion !== packageVersion) {
+  throw new Error(`Version mismatch: package.json=${packageVersion}, herdr-plugin.toml=${manifestVersion ?? "missing"}`);
+}
+
+const tag = process.env.GITHUB_REF_NAME;
+if (tag && tag !== `v${packageVersion}`) {
+  throw new Error(`Tag ${tag} does not match package version v${packageVersion}`);
+}
+
+console.log(`Release version ${packageVersion} is consistent.`);

package/scripts/branch-cleanup-pane.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Herdr overlay pane shown after a worktree checkout has been removed.
+set -euo pipefail
+
+source_root=${HERDR_WORKTREEINCLUDE_SOURCE:?Missing source repository}
+branch=${HERDR_WORKTREEINCLUDE_BRANCH:?Missing branch name}
+
+clear
+printf '\n  Worktree checkout removed\n\n'
+printf '  Delete the local branch "%s" too?\n\n' "$branch"
+printf '  [d] Delete branch    [Enter] Keep branch\n\n'
+read -r -n 1 choice || true
+printf '\n'
+
+if [[ "$choice" == "d" || "$choice" == "D" ]]; then
+  git -C "$source_root" branch -d -- "$branch" >&2 || true
+fi
+
+herdr_bin=${HERDR_BIN_PATH:-herdr}
+"$herdr_bin" plugin pane close "${HERDR_PANE_ID:?Missing Herdr pane id}" || true

package/scripts/copy-worktreeinclude.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Copy source files which are both Git-ignored and selected by .worktreeinclude.
+set -euo pipefail
+
+usage() {
+  echo "usage: $0 SOURCE_WORKTREE DESTINATION_WORKTREE" >&2
+  exit 64
+}
+
+[[ $# -eq 2 ]] || usage
+source_root=$(git -C "$1" rev-parse --show-toplevel)
+destination_root=$(git -C "$2" rev-parse --show-toplevel)
+include_file="$source_root/.worktreeinclude"
+
+if [[ ! -f "$include_file" ]]; then
+  echo "No .worktreeinclude in $source_root; nothing to copy."
+  exit 0
+fi
+
+# A project-local worktree is physically nested below the primary checkout.
+# Do not treat another checkout's ignored files as source files to copy.
+linked_worktrees=$(git -C "$source_root" worktree list --porcelain | awk '/^worktree / { print substr($0, 10) }')
+
+is_other_worktree_path() {
+  local candidate=$1 worktree
+  while IFS= read -r worktree; do
+    [[ -n "$worktree" && "$worktree" != "$source_root" ]] || continue
+    case "$candidate" in
+      "$worktree"|"$worktree"/*) return 0 ;;
+    esac
+  done <<<"$linked_worktrees"
+  return 1
+}
+
+matches=$(mktemp "${TMPDIR:-/tmp}/herdr-worktreeinclude.XXXXXX")
+pattern_root=$(mktemp -d "${TMPDIR:-/tmp}/herdr-worktreeinclude-patterns.XXXXXX")
+trap 'rm -f "$matches"; rm -rf "$pattern_root"' EXIT
+
+# Evaluate selection patterns in an otherwise empty Git repository. Evaluating
+# them inside the source repository would also apply its .gitignore, whose
+# higher precedence could defeat a .worktreeinclude negation (for example
+# `config/` followed by `!config/example.json`).
+git -C "$pattern_root" init -q
+cp "$include_file" "$pattern_root/.gitignore"
+
+# git ls-files supplies only ignored, untracked paths. check-ignore then applies
+# .worktreeinclude with Git's own .gitignore-compatible pattern engine.
+git -C "$source_root" ls-files --others --ignored --exclude-standard -z \
+  | git -C "$pattern_root" check-ignore --no-index --stdin -z >"$matches" || true
+
+copied=0
+skipped=0
+while IFS= read -r -d '' relative_path; do
+  # Reject paths which could escape either worktree. Git normally cannot emit
+  # these, but the guard makes copying safe even with unusual filenames.
+  [[ "$relative_path" != /* && "$relative_path" != ../* && "$relative_path" != */../* ]] || continue
+
+  source_path="$source_root/$relative_path"
+  destination_path="$destination_root/$relative_path"
+  [[ -e "$source_path" || -L "$source_path" ]] || continue
+  is_other_worktree_path "$source_path" && continue
+
+  # Never overwrite a file Git checked out in the destination.
+  if git -C "$destination_root" ls-files --error-unmatch -- "$relative_path" >/dev/null 2>&1; then
+    echo "Skipping tracked destination path: $relative_path" >&2
+    ((skipped += 1))
+    continue
+  fi
+  if [[ -e "$destination_path" || -L "$destination_path" ]]; then
+    echo "Skipping existing destination path: $relative_path" >&2
+    ((skipped += 1))
+    continue
+  fi
+
+  mkdir -p "$(dirname "$destination_path")"
+  # -P preserves symlinks, -R copies recursively if Git reports a directory,
+  # and -p retains the source mode and timestamps.
+  cp -pPR "$source_path" "$destination_path"
+  ((copied += 1))
+done <"$matches"
+
+echo "Copied $copied .worktreeinclude file(s); skipped $skipped."

package/scripts/create-worktree.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Interactive Herdr pane entrypoint. The pane starts in the source workspace.
+set -euo pipefail
+
+plugin_root=${HERDR_PLUGIN_ROOT:-"$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"}
+source_root=$(git rev-parse --show-toplevel)
+
+read -r -p "Branch name: " branch
+[[ -n "$branch" ]] || { echo "A branch name is required." >&2; exit 64; }
+read -r -p "Base ref [HEAD]: " base
+base=${base:-HEAD}
+
+# Keep branches separate without allowing a branch name to traverse directories.
+slug=$(printf '%s' "$branch" | tr '/[:space:]' '--' | tr -cd '[:alnum:]._-')
+[[ -n "$slug" ]] || { echo "Branch name contains no usable path characters." >&2; exit 64; }
+worktree_path="$source_root/.herdr/worktrees/$slug"
+
+if [[ -e "$worktree_path" ]]; then
+  echo "Destination already exists: $worktree_path" >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "$worktree_path")"
+if git show-ref --verify --quiet "refs/heads/$branch"; then
+  git worktree add "$worktree_path" "$branch"
+else
+  git worktree add -b "$branch" "$worktree_path" "$base"
+fi
+
+"$plugin_root/scripts/copy-worktreeinclude.sh" "$source_root" "$worktree_path"
+
+herdr_bin=${HERDR_BIN_PATH:-herdr}
+"$herdr_bin" worktree open --cwd "$source_root" --path "$worktree_path" --focus
+echo "Opened $worktree_path in Herdr."

package/scripts/event-worktree-path.mjs

@@ -0,0 +1,8 @@
+const event = JSON.parse(process.env.HERDR_PLUGIN_EVENT_JSON ?? "{}");
+
+for (const candidate of [event?.worktree?.path, event?.data?.worktree?.path, event?.payload?.worktree?.path]) {
+  if (typeof candidate === "string" && candidate.startsWith("/")) {
+    process.stdout.write(candidate);
+    break;
+  }
+}

package/scripts/on-worktree-created.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Make Herdr's native worktree dialog project-local, then restore selected
+# ignored files. Herdr v1 emits this hook after it has created the checkout,
+# so relocation necessarily happens immediately after the dialog completes.
+set -euo pipefail
+
+plugin_root=${HERDR_PLUGIN_ROOT:-"$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"}
+target=$(node "$plugin_root/scripts/event-worktree-path.mjs")
+[[ -n "$target" ]] || { echo "Could not find worktree path in Herdr event payload." >&2; exit 0; }
+
+# The primary worktree provides the shared repository's local ignored files.
+source=$(git -C "$target" worktree list --porcelain | awk '/^worktree / { print substr($0, 10); exit }')
+[[ -n "$source" ]] || exit 0
+branch=$(git -C "$target" branch --show-current)
+[[ -n "$branch" ]] || { echo "Skipping detached worktree: $target" >&2; exit 0; }
+slug=$(printf '%s' "$branch" | tr '[:space:]/' '--' | tr -cd '[:alnum:]._-')
+[[ -n "$slug" ]] || { echo "Could not make a safe path from branch: $branch" >&2; exit 1; }
+destination="$source/.herdr/worktrees/$slug"
+
+# A plugin-created project-local worktree already has the right path.
+if [[ "$target" != "$destination" ]]; then
+  if [[ -e "$destination" ]]; then
+    echo "Project-local worktree path already exists; leaving Herdr worktree at $target" >&2
+    exit 1
+  fi
+
+  herdr_bin=${HERDR_BIN_PATH:-herdr}
+  # Capture the workspace while Herdr still recognizes the original path.
+  workspace_id=$("$herdr_bin" worktree list --cwd "$source" --json \
+    | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const r=JSON.parse(s).result;const w=(r.worktrees||[]).find(x=>x.path===process.argv[1]);if(w?.open_workspace_id)process.stdout.write(w.open_workspace_id)})' "$target")
+  "$plugin_root/scripts/copy-worktreeinclude.sh" "$source" "$target"
+  mkdir -p "$(dirname "$destination")"
+  git -C "$source" worktree move "$target" "$destination"
+
+  # Herdr's workspace is still attached to the old path. Close it, then open
+  # the relocated checkout as the replacement workspace.
+  [[ -z "$workspace_id" ]] || "$herdr_bin" workspace close "$workspace_id"
+  "$herdr_bin" worktree open --cwd "$source" --path "$destination" --focus
+  echo "Relocated worktree to $destination"
+else
+  "$plugin_root/scripts/copy-worktreeinclude.sh" "$source" "$target"
+fi
+
+# Store the final checkout path. The removal event occurs after Git has
+# deleted that checkout, so this is how the cleanup pane knows its branch and
+# source repository.
+managed_path=${destination:-$target}
+state_dir=${HERDR_PLUGIN_STATE_DIR:-"$plugin_root/.state"}
+state_file="$state_dir/managed-worktrees.tsv"
+mkdir -p "$state_dir"
+state_tmp=$(mktemp "$state_dir/managed-worktrees.XXXXXX")
+if [[ -f "$state_file" ]]; then
+  awk -F '\t' -v path="$managed_path" '$1 != path' "$state_file" >"$state_tmp"
+fi
+printf '%s\t%s\t%s\n' "$managed_path" "$source" "$branch" >>"$state_tmp"
+mv "$state_tmp" "$state_file"

package/scripts/on-worktree-removed.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Open an in-Herdr branch-cleanup overlay after a plugin-managed checkout is
+# removed. This hook deliberately does not use macOS dialogs.
+set -euo pipefail
+
+plugin_root=${HERDR_PLUGIN_ROOT:-"$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"}
+target=$(node "$plugin_root/scripts/event-worktree-path.mjs")
+[[ -n "$target" ]] || exit 0
+
+state_dir=${HERDR_PLUGIN_STATE_DIR:-"$plugin_root/.state"}
+state_file="$state_dir/managed-worktrees.tsv"
+[[ -f "$state_file" ]] || exit 0
+record=$(awk -F '\t' -v path="$target" '$1 == path { print; exit }' "$state_file")
+[[ -n "$record" ]] || exit 0
+IFS=$'\t' read -r _ source branch <<<"$record"
+
+state_tmp=$(mktemp "$state_dir/managed-worktrees.XXXXXX")
+awk -F '\t' -v path="$target" '$1 != path' "$state_file" >"$state_tmp"
+mv "$state_tmp" "$state_file"
+
+herdr_bin=${HERDR_BIN_PATH:-herdr}
+
+# If the branch tip is already contained in the source checkout's HEAD, no
+# work remains unique to the worktree. Delete it without interrupting the UI.
+if git -C "$source" merge-base --is-ancestor "$branch" HEAD; then
+  git -C "$source" branch -d -- "$branch" >&2 || true
+  exit 0
+fi
+
+"$herdr_bin" plugin pane open \
+  --plugin "${HERDR_PLUGIN_ID:-serhii-chernenko.worktreeinclude}" \
+  --entrypoint branch-cleanup \
+  --placement overlay \
+  --env "HERDR_WORKTREEINCLUDE_SOURCE=$source" \
+  --env "HERDR_WORKTREEINCLUDE_BRANCH=$branch" \
+  --focus