workshell 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pullfrog, Inc.
+
+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.

package/README.md

@@ -0,0 +1,321 @@
+<p align="center">
+  <h1 align="center">🌲<br/><code>wsh</code></h1>
+  <p align="center">Human- and agent-friendly Git multitasking. Powered by worktrees.
+    <br/>
+    by <a href="https://x.com/colinhacks">@colinhacks</a>
+  </p>
+</p>
+<br/>
+
+<p align="center">
+<a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/github/license/colinhacks/workshell" alt="License"></a>
+<a href="https://www.npmjs.com/package/workshell" rel="nofollow"><img src="https://img.shields.io/npm/dw/workshell.svg" alt="npm"></a>
+<a href="https://github.com/colinhacks/workshell" rel="nofollow"><img src="https://img.shields.io/github/stars/colinhacks/workshell" alt="stars"></a>
+</p>
+
+<br/>
+<br/>
+<br/>
+
+## Install
+
+```bash
+$ npm i -g workshell
+```
+
+<br/>
+
+## How `wsh` works
+
+There have been many attempts to nail a DX for parallel work in the agentic coding era. Most are thin wrappers over `git worktree`. Instead `wsh` introduces a new paradigm: the *workshell*. 
+
+**A _workshell_ is an ephemeral worktree whose lifecycle is bound to a subshell.**
+
+Here's how it works (key points in **bold**).
+
+- You open a Git branch with `wsh open <branch>` or create a new one with `wsh new <branch>`.
+- An ephemeral worktree is created for this branch (in `.git/wsh/worktrees`) and **opened in a fresh subshell**.
+- You are now in an fresh checkout of your repo that is isolated on disk. Make changes with your agent/editor of choice and commit them.
+- You close the subshell with `wsh close`. **The associated worktree is auto-pruned**.
+- Your changes still exist on the associated branch, as Git commits/branches are shared among all worktrees. The worktree is destroyed—but your commits aren't.
+
+<!-- That's it. **Ephemeral worktrees whose lifecycle is bound to a subshell.** When the subshell exits, the worktree is destroyed—but your commits aren't. -->
+
+<!-- 
+## How does it work
+
+There have been many attempts to nail a DX for parallel work in the agentic coding era. Most are thin wrappers over `git worktree`. That's not what `wsh` is (though worktrees are used internally).
+
+Here's how it works (key points in **bold**).
+
+- **A fresh worktree is created** — The `wsh` utility a) creates a new worktree in `.git/wsh/worktrees` and b) opens it in a *subshell*.
+- **Make edits and commit** — From the worksh your preferred IDE/agent.
+- **Commit your changes** — Though your file system is isolated, Git commit history (including branches) is still shared among all worktrees. 
+- **Exit the subshell** — Run `wsh close` to exit the subshell. As with `git switch`, `wsh close` won't let you close the subshell if you have unstaged/uncommitted changes.
+- **The worktree is auto-pruned** — This is key. The lifecycle of the worktree is tied to the subshell. When the subshell is closed, the worktree is destroyed. But *the commits you made inside the subshell* still exist.
+- **Merge in your changes** — Merge/rebase your branch as you normally would, or push to GitHub to open a PR. -->
+
+<br/>
+
+## Features
+
+This approach has some nice properties.
+
+- 🖥️ **Tab-local workspaces** — Normally a `git checkout`/`git switch` changes your active branch for all terminals. With workshells, you can functionality open branches *in the current tab only*.
+- 🌳 **Full isolation** — Each workshell is isolated on disk, so the changes you make don't interfere anything else you're doing.
+- 🙅‍♂️ **Never stash again** — You can `wsh open` a branch even with uncommitted changes. When you exit the subshell, things will be exactly the same as they were. ☕️
+- 🪾 **Consistent with branch semantics** — As with regular `git switch`, `wsh close` won't let you close the subshell if you have unstaged/uncommitted changes. This is a feature, not a bug! Regular worktrees make it easy to lose your work in a forgotten corner of your file system.
+- 🤖 **Agent-ready** — Spin up parallel workshells so multiple agents can work simultaneously without conflicts.
+
+<br/>
+
+## Quickstart
+
+This section is entirely linear and self-contained. Try running all these commands in order to get a feel for how `wsh` works. First, install `wsh`.
+
+```bash
+$ npm i -g workshell
+```
+
+<br/>
+
+Then clone a repo (any repo works):
+
+```bash
+$ git clone git@github.com:colinhacks/zod.git
+$ cd zod
+```
+
+<br/>
+
+After cloning, the `main` branch is checked out. Let's say we want to start work on a new feature:
+
+```bash
+$ wsh new feat-1
+
+✓ feat-1 (from main)
+Opened branch in ephemeral subshell at .git/wsh/worktrees/zod@feat-1
+Type 'wsh close' to return.
+```
+
+<br/>
+
+You're now in a workshell. Check where you are:
+
+```bash
+$ pwd
+/Users/colinmcd94/Documents/repos/zod/.git/wsh/worktrees/zod@feat-1
+
+$ git branch --show-current
+feat-1
+```
+
+<br/>
+
+Now let's make some changes. (You can also open the repo in an IDE, start an agent run, etc.)
+
+```bash
+$ touch a.txt
+```
+
+<br/>
+
+Now let's try to close the workshell.
+
+```bash
+$ wsh close
+⚠ Uncommitted changes found. Commit, stash, or reset your changes first.
+  Or use --force/-f to discard changes
+    wsh close -f
+```
+
+<br/>
+
+We aren't able to close because we have uncommitted changes. Let's commit them.
+
+```bash
+$ git add -A && git commit -am "Add a.txt"
+```
+
+<br/>
+
+Now we can try closing again. Since our changes can be fast-forwarded from the base branch, `wsh` offers to auto-merge the changes.
+
+```bash
+$ wsh close
+✓ Back in main
+  Pruned worktree. Your changes are still in the 'feat-1' branch.
+  To merge your changes:
+    git merge feat-1
+
+  Auto-merge? (y/n/never) y
+
+✓ Merged 'feat-1' into 'main'
+```
+
+<br/> 
+
+## CLI
+
+```sh
+wsh v0.x.y - Human- and agent-friendly Git multitasking
+
+Usage: wsh <command> [options]
+
+Commands:
+  new [branch]    Create a branch and open it [--from <branch>]
+  open <branch>   Open a branch in a workshell
+  close           Exit current workshell
+  ls              List orphaned worktrees
+  status          Show current branch
+  rm <branch>     Remove a branch's worktree
+  config          Show or create config file
+
+Options:
+  --help, -h      Show help
+  --version, -v   Show version
+```
+
+<br />
+
+### List orphaned worktrees
+
+Normally the worktree will be auto-pruned when you close its associated workshell. If a worktree is left behind for some reason, you can list them with `wsh ls`.
+
+```sh
+$ wsh ls
+┌────────┬───────────┬───────────────┐
+│ branch │ status    │ created       │
+├────────┼───────────┼───────────────┤
+│ main * │ clean     │ -             │
+│ feat-1 │ 1 changed │ 5 minutes ago │
+└────────┴───────────┴───────────────┘
+```
+
+<br />
+
+
+### Open a branch in a workshell
+
+You can open any existing Git branch in a workshell. 
+
+```sh
+$ wsh open feat-1
+
+✓ feat-1 (existing worktree)
+Type 'wsh close' to return.
+```
+
+<br />
+
+### Show current branch status
+
+```sh
+$ wsh status
+branch:    main (root)
+worktree:  /path/to/zod
+status:    clean
+```
+
+<br />
+
+### Remove a worktree 
+
+Remove the worktree for a branch (the branch itself is kept):
+
+```sh
+$ wsh rm feat-1
+
+✓ Pruned worktree for feat-1
+```
+
+<br />
+
+### Closing a workshell
+
+This closes the current workshell and auto-prunes the associated worktree. Your changes survive in your branch commits. 
+
+```sh
+$ wsh close
+✓ Back in main
+  Pruned worktree. Your changes are still in the 'feat-1' branch.
+  To merge your changes:
+    git merge feat-1
+
+  Auto-merge? (y/n/never) y
+
+✓ Merged 'feat-1' into 'main'
+```
+
+If the branch hasn't been pushed to a remote, you'll be prompted to auto-merge:
+
+- `y` — merge into base branch
+- `n` — skip (branch is kept, merge manually later)
+- `never` — permanently disable auto-merge prompt
+
+That command will fail if you have unstaged/uncommited changes. Use the `--force`/`-f` flag to force close the workshell; **this will discard uncommitted changes**.
+
+```sh
+$ wsh close --force
+```
+
+<br />
+
+### Print or create a `wsh.toml`
+
+To print or create a config file:
+
+```sh
+$ wsh config
+
+✓ Config file: /path/to/repo/.git/wsh.toml
+
+────────────────────────────────────────────────────────────
+setup = "npm install"
+────────────────────────────────────────────────────────────
+```
+
+If no config exists, you'll be prompted to create one.
+
+```sh
+$ wsh config
+
+No config file found.
+
+Where would you like to create one?
+  1. .git/wsh.toml (local only, not committed)
+  2. wsh.toml (project root, can be committed)
+
+Choice (1/2): 1
+
+✓ Created /path/to/repo/.git/wsh.toml
+```
+
+<br />
+
+## `wsh.toml`
+
+You can configure `wsh` with a `wsh.toml` file. This is useful for running setup scripts when opening a workshell (e.g., `npm install`).
+
+`wsh` looks for config files in the following order:
+
+| Path | Description |
+|------|-------------|
+| `.git/wsh.toml` | Local only, not committed (highest precedence) |
+| `wsh.toml` | Project root, can be committed |
+
+<br />
+
+```toml
+# setup script executed in subshell after initialization
+setup = "npm install && cp {{ repo_path }}/.env {{ worktree_path }}/.env"
+```
+
+The following variable substitutions are supported in `setup`.
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{ branch }}` | Branch name | `feature/auth` |
+| `{{ repo_path }}` | Absolute path to main repo | `/path/to/repo` |
+| `{{ worktree_path }}` | Absolute path to worktree | `/path/to/repo/.git/wsh/worktrees/repo@feat` |
+