@cniska/agent-worktree 0.1.0 → 0.3.0

package/README.md

@@ -6,23 +6,53 @@
 
 agent-worktree never works out what a checkout needs: `agent-worktree install` writes the setup and teardown commands and the port count the project gives it into hooks, and agent-worktree runs those.
 
-- `agent-worktree create <name>` makes a git worktree outside the repository, on a new branch cut from `origin`'s default branch as `origin` has it now, runs the project's setup hook in it, and prints its path.
-- `agent-worktree remove <name>` runs the project's teardown hook, removes the worktree, and once its remote's default branch has the branch, deletes it locally and, when it was pushed with an upstream, on that remote. When the upstream holds a commit the branch lacks, it keeps both copies.
+- `agent-worktree create <name>` makes a git worktree outside the repository, on a new branch cut from `origin`'s default branch as `origin` has it now, runs the project's setup hook in it, and prints its path in its result.
+- `agent-worktree remove <name>` runs the project's teardown hook, removes the worktree, and once its remote's default branch has the branch, deletes it locally and on that remote: its upstream or, with none, the branch of the same name on `origin`, other than `origin`'s default branch. When the remote branch holds a commit the branch lacks, it keeps both copies.
 - The `cniska-worktree` Claude Code plugin sends Claude Code's own worktrees through the same commands.
 
 ## Install
 
-agent-worktree runs on [Bun](https://bun.sh), which [mise](https://mise.jdx.dev) installs for it. With mise installed:
+Install the `agent-worktree` command for macOS on Apple silicon or Linux on x64 through one of these channels.
+
+With the release's installer:
+
+```bash
+curl -fsSL https://github.com/cniska/agent-worktree/releases/latest/download/install.sh | sh
+```
+
+With Homebrew:
+
+```bash
+brew install cniska/tap/agent-worktree
+```
+
+With npm:
+
+```bash
+npm install -g @cniska/agent-worktree
+```
+
+With Bun:
 
 ```bash
-git clone https://github.com/cniska/agent-worktree.git
-cd agent-worktree
-mise trust && mise install
+bun add -g @cniska/agent-worktree
 ```
 
-`mise install` installs Bun and the dependencies. In the clone, never in a worktree, it puts `agent-worktree` in `~/.bun/bin` with `bun link`, so removing a worktree never leaves the command pointing at a deleted checkout. Add that directory to your `PATH` if it is not there yet.
+The curl line installs `~/.local/bin/agent-worktree` and, when that directory is not on your `PATH`, adds it to `~/.zshrc` for zsh or to an existing `~/.bashrc` or `~/.bash_profile` for bash, and otherwise asks you to add it. Each channel updates the way it installed: `brew upgrade agent-worktree`, `npm update -g @cniska/agent-worktree`, `bun update -g @cniska/agent-worktree`, or the curl line run again.
+
+### Updates
+
+Once a day, an installed `agent-worktree` asks the channel it came from for the latest release, giving up after a second. While a newer one is out, every command prints one line on stderr before anything else, with its stdout and exit code unchanged:
+
+```text
+agent-worktree 0.3.1 is out (running 0.3.0): run brew upgrade agent-worktree; if you cannot, tell the user.
+```
 
-Then install the Claude Code plugin:
+The line names the upgrade for the channel it was installed through. The check runs only for an install it can place: one Homebrew, npm or Bun installed, or the curl line's `~/.local/bin/agent-worktree`. It records when it last asked in `${XDG_STATE_HOME:-~/.local/state}/agent-worktree/update-check.json`. Set `AGENT_WORKTREE_NO_UPDATE_CHECK=1` to turn it off; it is also off when `CI` is set, and under the plugin's `agent-worktree hook`.
+
+### Claude Code plugin
+
+Install the Claude Code plugin:
 
 ```bash
 claude plugin install cniska-worktree@cniska
@@ -42,10 +72,11 @@ Claude Code makes worktrees of its own, for EnterWorktree and for subagents, wit
 | `agent-worktree create [--from <ref>] <name>` | Create the worktree, run setup, print the path |
 | `agent-worktree remove [--force] <name>` | Run teardown, remove the worktree and settle its branch |
 | `agent-worktree prune` | Tear down gone worktrees and remove those whose branch landed |
-| `agent-worktree ls` | One line per worktree |
+| `agent-worktree ls [--full]` | Count the worktrees in each state and list them; also what `agent-worktree` alone prints |
 | `agent-worktree path <name>` | Print the worktree's path |
+| `agent-worktree doctor [--full]` | Report what agent-worktree, its plugin and the project need, each check with its fix |
 
-[Commands](docs/commands.md) lists every command, where `create` cuts a branch and how `remove` settles one.
+Each command prints its result, or its error, as one [TOON](https://toonformat.dev) document. [Commands](docs/commands.md) lists every command and its output, where `create` cuts a branch, how `remove` settles one and what `doctor` checks.
 
 ## Docs
 
@@ -54,3 +85,11 @@ Claude Code makes worktrees of its own, for EnterWorktree and for subagents, wit
 - [Claude Code plugin](docs/plugin.md): what the plugin does and what it needs.
 - [Development](docs/development.md): setup, checks, layout and rules, for working on this repo.
 - [Releasing](docs/releasing.md): the release workflow, the owner's one-time setup and each release's steps.
+
+## Related
+
+agent-worktree works on its own in any agent workflow, and is one of the optional add-ons to [agent-skills](https://github.com/cniska/agent-skills), engineering skills for coding agents. The other add-ons:
+
+- [agent-task](https://github.com/cniska/agent-task): task tracking for coding agents, the tasks running, in review and waiting to run
+- [agent-record](https://github.com/cniska/agent-record): a session record for coding agents, every past session queryable and joined to its commits
+- [agent-gates](https://github.com/cniska/agent-gates): commit gates for coding agents, git hooks and CI checks that refuse a bad commit

package/bin/agent-worktree

@@ -5,8 +5,13 @@ builds='darwin-arm64 linux-x64'
 name=agent-worktree
 scope=@cniska
 
+quoted() {
+  printf '"%s"' "$(printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+}
+
 refuse() {
-  printf '%s: %s\n  %s\n' "$name" "$1" "$2" >&2
+  printf 'command: %s\nok: false\nerror:\n  kind: refusal\n  code: %s\n  message: %s\n  meta:\n  resolve: %s\n' \
+    "$name" "$1" "$(quoted "$2")" "$(quoted "$3")" >&2
   exit 1
 }
 
@@ -34,9 +39,9 @@ target=$os-$cpu
 
 case " $builds " in
   *" $target "*) ;;
-  *) refuse \
+  *) refuse no_build_for_platform \
     "$name ships no build for $target, only $(printf '%s' "$builds" | sed 's/ / and /g')" \
-    "build $name from source with Bun, as its README says" ;;
+    "build $name from source with Bun, as its docs/development.md says" ;;
 esac
 
 package=$scope/$name-$target
@@ -47,9 +52,9 @@ for dir in "$bin/../node_modules/$package" "$bin/../../$name-$target"; do
     break
   fi
 done
-[ -n "$binary" ] || refuse \
+[ -n "$binary" ] || refuse platform_package_missing \
   "$package is not installed beside $scope/$name" \
   "reinstall $scope/$name with optional dependencies enabled"
-[ -x "$binary" ] || refuse "$binary is not executable" "reinstall $scope/$name"
+[ -x "$binary" ] || refuse binary_not_executable "$binary is not executable" "reinstall $scope/$name"
 
 exec "$binary" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cniska/agent-worktree",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Task worktrees for coding agents: one checkout per task, set up and torn down by the project's own commands.",
   "license": "MIT",
   "homepage": "https://github.com/cniska/agent-worktree",
@@ -25,7 +25,7 @@
     "bin/agent-worktree"
   ],
   "optionalDependencies": {
-    "@cniska/agent-worktree-darwin-arm64": "0.1.0",
-    "@cniska/agent-worktree-linux-x64": "0.1.0"
+    "@cniska/agent-worktree-darwin-arm64": "0.3.0",
+    "@cniska/agent-worktree-linux-x64": "0.3.0"
   }
 }