@solaqua/gji 0.1.0-beta.9 → 0.2.0

package/README.md

@@ -1,222 +1,276 @@
-# gji
+# gji — Git worktrees without the hassle
 
-Context switching without the mess.
+> Jump between tasks instantly. No stash. No reinstall. No mess.
 
-`gji` is a Git worktree CLI for people who jump between tasks all day. It gives each branch or PR its own directory, so you stop doing `stash`, `pop`, reinstall cycles, and fragile branch juggling.
+`gji` wraps Git worktrees into a fast, ergonomic CLI. Each branch gets its own directory, its own `node_modules`, and its own terminal — so switching context is a single command instead of a ritual.
 
-## Why
+```sh
+gji new feature/payment-refactor   # new branch + worktree, cd in
+gji pr 1234                        # review PR in isolation, cd in
+gji go main                        # jump back, shell changes directory
+gji remove feature/payment-refactor
+```
 
-Standard branch switching gets annoying when you are:
+---
 
-- fixing one bug while reviewing another branch
-- hopping between feature work and PR checks
-- using multiple terminals, editors, or AI agents at the same time
+**If `gji` has saved you from a `git stash` spiral, a ⭐ on [GitHub](https://github.com/sjquant/gji) means a lot — it helps other developers find this tool.**
 
-`gji` keeps those contexts isolated in separate worktrees with deterministic paths.
+---
 
-## Install
+## The problem
+
+You are deep in a feature branch. A colleague asks for a quick review. You:
+
+1. stash your changes
+2. checkout their branch
+3. wait for `pnpm install` to finish
+4. review
+5. checkout back
+6. pop your stash
+7. realize something is broken
 
-Current source install:
+**Or you use `gji` and it is just `gji pr 1234`.**
+
+## Install
 
 ```sh
-git clone https://github.com/sjquant/gji.git
-cd gji
-pnpm build
-npm install -g .
+npm install -g @solaqua/gji
 ```
 
-Confirm the CLI is available:
+Then add shell integration so `gji go`, `gji new`, and `gji remove` can change your directory:
 
 ```sh
-gji --version
-gji --help
+# zsh
+echo 'eval "$(gji init zsh)"' >> ~/.zshrc && source ~/.zshrc
+
+# bash
+echo 'eval "$(gji init bash)"' >> ~/.bashrc && source ~/.bashrc
 ```
 
 ## Quick start
 
-Inside a Git repository:
-
 ```sh
-gji new feature/login-form
-gji status
-```
+# start a new task
+gji new feature/dark-mode
 
-That creates a linked worktree at a deterministic path:
+# review a pull request
+gji pr 1234
 
-```text
-../worktrees/<repo>/<branch>
-```
+# see what's open
+gji status
 
-## Shell setup
+# jump between worktrees
+gji go feature/dark-mode
+gji go main
 
-`gji new`, `gji go`, `gji root`, and `gji remove`/`gji rm` can only change your current directory when shell integration is installed. Without shell integration, the raw CLI prints the target path so it stays script-friendly.
+# clean up when done
+gji remove feature/dark-mode
+```
 
-For zsh:
+Worktrees land at a deterministic path so your editor bookmarks and scripts always know where to look:
 
-```sh
-echo 'eval "$(gji init zsh)"' >> ~/.zshrc
-source ~/.zshrc
+```
+../worktrees/<repo>/<branch>
 ```
 
-After that:
+## Daily workflow
 
 ```sh
-gji new feature/login-form
-gji go feature/login-form
-gji root
-gji rm feature/login-form
-```
+gji new feature/auth-refactor     # new branch + worktree
+gji new --detached                # scratch space, auto-named
 
-changes your shell directory directly.
+gji pr 1234                       # checkout PR locally
+gji pr https://github.com/org/repo/pull/1234  # or paste the URL
 
-If you reinstall or upgrade `gji`, refresh the shell function:
+gji go feature/auth-refactor      # jump to a worktree
+gji root                          # jump to repo root
 
-```sh
-eval "$(gji init zsh)"
-```
+gji status                        # health overview + ahead/behind counts
+gji ls                            # compact list
 
-For scripts or explicit piping:
+gji sync                          # rebase current worktree onto default branch
+gji sync --all                    # rebase every worktree
 
-```sh
-gji new feature/login-form
-gji go --print feature/login-form
-gji root --print
+gji clean                         # interactive bulk cleanup
+gji remove feature/auth-refactor  # remove one worktree and its branch
 ```
 
-`gji new` and `gji remove` print their destination paths in raw CLI mode, but in a shell-integrated session they change directory directly.
-
-## Daily workflow
+## Shell setup
 
-Start a task:
+Without shell integration `gji` prints paths and exits — which is fine for scripts but means it cannot `cd` you into a new worktree. Install the integration once:
 
 ```sh
-gji new feature/refactor-auth
+gji init zsh   # prints the shell function, review it if you like
 ```
 
-Start a detached scratch worktree:
+To install automatically:
 
 ```sh
-gji new --detached
+# zsh
+echo 'eval "$(gji init zsh)"' >> ~/.zshrc
+
+# bash
+echo 'eval "$(gji init bash)"' >> ~/.bashrc
 ```
 
-Check what is active:
+After a reinstall or upgrade, re-source to pick up changes:
 
 ```sh
-gji status
-gji ls
+eval "$(gji init zsh)"
 ```
 
-Pull a PR into its own worktree:
+For scripts that need the raw path, use `--print`:
 
 ```sh
-gji pr 123
-gji pr #123
-gji pr https://github.com/owner/repo/pull/123
+path=$(gji go --print feature/dark-mode)
+path=$(gji root --print)
 ```
 
-Sync the current worktree with the latest default branch:
+## Commands
 
-```sh
-gji sync
-```
+| Command | Description |
+|---|---|
+| `gji new [branch] [--detached] [--json]` | create branch + worktree, cd in |
+| `gji pr <ref> [--json]` | fetch PR ref, create worktree, cd in |
+| `gji go [branch] [--print]` | jump to a worktree |
+| `gji root [--print]` | jump to the main repo root |
+| `gji status [--json]` | repo overview, worktree health, ahead/behind |
+| `gji ls [--json]` | list active worktrees |
+| `gji sync [--all]` | fetch and rebase worktrees onto default branch |
+| `gji clean [--force] [--json]` | interactively prune stale worktrees |
+| `gji remove [branch] [--force] [--json]` | remove a worktree and its branch |
+| `gji config [get\|set\|unset] [key] [value]` | manage global defaults |
+| `gji init [shell]` | print or install shell integration |
 
-Sync every worktree in the repository:
+## Configuration
 
-```sh
-gji sync --all
-```
+No setup required. Optional config lives in:
 
-Clean up stale linked worktrees interactively:
+- `~/.config/gji/config.json` — global defaults
+- `.gji.json` — repo-local overrides (takes precedence)
 
-```sh
-gji clean
+### Available keys
+
+| Key | Description |
+|---|---|
+| `branchPrefix` | prefix added to new branch names (e.g. `"feature/"`) |
+| `syncRemote` | remote for `gji sync` (default: `origin`) |
+| `syncDefaultBranch` | branch to rebase onto (default: remote `HEAD`) |
+| `syncFiles` | files to copy from main worktree into each new worktree |
+| `skipInstallPrompt` | `true` to disable the auto-install prompt permanently |
+| `hooks` | lifecycle scripts (see [Hooks](#hooks)) |
+
+```json
+{
+  "branchPrefix": "feature/",
+  "syncRemote": "upstream",
+  "syncDefaultBranch": "main",
+  "syncFiles": [".env.example", ".nvmrc"]
+}
 ```
 
-Finish a single worktree explicitly:
+### Config commands
 
 ```sh
-gji remove feature/refactor-auth
-# or
-gji rm feature/refactor-auth
+gji config get
+gji config get branchPrefix
+gji config set branchPrefix feature/
+gji config unset branchPrefix
 ```
 
-After removal, the shell-integrated command returns you to the repository root.
+## Hooks
 
-## Commands
+Run scripts automatically at key lifecycle moments:
+
+```json
+{
+  "hooks": {
+    "afterCreate": "pnpm install",
+    "afterEnter": "echo 'switched to {{branch}}'",
+    "beforeRemove": "pnpm run cleanup"
+  }
+}
+```
 
-- `gji --version` prints the installed CLI version
-- `gji init [shell]` prints shell integration for `zsh`, `bash`, or `fish`
-- `gji new [branch] [--detached]` creates a branch and linked worktree; with shell integration it moves into the new worktree, and `--detached` creates a detached worktree instead
-- `gji pr <ref>` accepts `123`, `#123`, or a full PR/MR URL, extracts the numeric ID, then fetches `origin/pull/<number>/head` and creates a linked `pr/<number>` worktree
-- `gji go [branch] [--print]` jumps to an existing worktree when shell integration is installed, or prints the matching worktree path otherwise
-- `gji root [--print]` jumps to the main repository root when shell integration is installed, or prints it otherwise
-- `gji status [--json]` prints repository metadata, worktree health, and upstream divergence
-- `gji sync [--all]` fetches from the configured remote and rebases or fast-forwards worktrees onto the configured default branch
-- `gji ls [--json]` lists active worktrees in a table or JSON
-- `gji clean` interactively prunes one or more linked worktrees, including detached entries, while excluding the current worktree
-- `gji remove [branch]` and `gji rm [branch]` remove a linked worktree and delete its branch when present; with shell integration they return to the repository root
-- `gji config` reads or updates global defaults
+| Hook | When it runs |
+|---|---|
+| `afterCreate` | after `gji new` or `gji pr` creates a worktree |
+| `afterEnter` | after `gji go` switches to a worktree |
+| `beforeRemove` | before `gji remove` deletes a worktree |
 
-## Configuration
+Hooks receive `{{branch}}`, `{{path}}`, `{{repo}}` as template variables and `GJI_BRANCH`, `GJI_PATH`, `GJI_REPO` as environment variables. A failing hook emits a warning but never aborts the command.
 
-`gji` is usable without setup, but it supports defaults through:
+Global and repo-local hooks deep-merge per key:
 
-- global config at `~/.config/gji/config.json`
-- repo-local config at `.gji.json`
+```jsonc
+// ~/.config/gji/config.json
+{ "hooks": { "afterCreate": "nvm use", "afterEnter": "echo hi" } }
 
-Repo-local values override global defaults.
+// .gji.json
+{ "hooks": { "afterCreate": "pnpm install" } }
 
-Supported keys:
+// effective
+{ "hooks": { "afterCreate": "pnpm install", "afterEnter": "echo hi" } }
+```
 
-- `branchPrefix`
-- `syncRemote`
-- `syncDefaultBranch`
+## Install prompt
 
-Example:
+When `gji new` or `gji pr` creates a worktree, `gji` detects the project's package manager from its lockfile and offers to run the install command:
 
-```json
-{
-  "branchPrefix": "feature/",
-  "syncRemote": "upstream",
-  "syncDefaultBranch": "main"
-}
+```
+Run `pnpm install` in the new worktree?
+› Yes       run once
+  No        skip this time
+  Always    save as afterCreate hook
+  Never     disable this prompt for this repo
 ```
 
-Behavior:
-
-- if `syncRemote` is unset, `gji sync` defaults to `origin`
-- if `syncDefaultBranch` is unset, `gji sync` resolves the remote default branch from `HEAD`
+**Always** saves `hooks.afterCreate` to `.gji.json`; **Never** writes `skipInstallPrompt: true`. Both are local-only — global config is never modified.
 
 ## JSON output
 
-`gji ls --json` returns branch/path entries:
+Every mutating command supports `--json` for scripting and AI agent use. Success goes to stdout, errors go to stderr with exit code 1.
 
 ```sh
-gji ls --json
+# create
+gji new --json feature/dark-mode
+# → { "branch": "feature/dark-mode", "path": "/…/worktrees/repo/feature/dark-mode" }
+
+# fetch PR
+gji pr --json 1234
+# → { "branch": "pr/1234", "path": "/…/worktrees/repo/pr/1234" }
+
+# remove
+gji remove --json --force feature/dark-mode
+# → { "branch": "feature/dark-mode", "path": "/…", "deleted": true }
+
+# bulk clean
+gji clean --json --force
+# → { "removed": [{ "branch": "...", "path": "..." }, …] }
+
+# error shape (any command)
+# stderr → { "error": "branch argument is required" }
 ```
 
-`gji status --json` returns a top-level object with:
+`--json` suppresses all interactive prompts. `--force` is required for `remove` and `clean` in JSON mode. `branch` is `null` for detached worktrees.
+
+`gji ls --json` and `gji status --json` also produce structured output — see `gji status --json | jq` for the full schema.
 
-- `repoRoot`
-- `currentRoot`
-- `worktrees`
+## Non-interactive / CI mode
 
-Each worktree entry contains:
+```sh
+GJI_NO_TUI=1 gji new feature/ci-branch
+GJI_NO_TUI=1 gji remove --force feature/ci-branch
+GJI_NO_TUI=1 gji clean --force
+```
 
-- `branch`: branch name or `null` for detached worktrees
-- `current`
-- `path`
-- `status`: `clean` or `dirty`
-- `upstream`: one of
-  - `{ "kind": "detached" }`
-  - `{ "kind": "no-upstream" }`
-  - `{ "kind": "tracked", "ahead": number, "behind": number }`
+`GJI_NO_TUI=1` disables all prompts. Commands that need confirmation require `--force`. `--json` implies the same behaviour.
 
 ## Notes
 
-- `gji` works from either the main repository root or any linked worktree
-- the current worktree is never offered as a `gji clean` removal candidate
-- `gji pr` accepts GitHub, GitLab, and Bitbucket-style PR/MR links, but still fetches from `origin` using GitHub-style `refs/pull/<number>/head`
+- Works from either the main repo root or inside any linked worktree
+- The current worktree is never offered as a `gji clean` candidate
+- `gji pr` parses GitHub, GitLab, and Bitbucket URLs but always fetches via `refs/pull/<number>/head` from `origin`
 
 ## License
 

package/dist/clean.d.ts

@@ -1,10 +1,14 @@
 import type { WorktreeEntry } from './repo.js';
 export interface CleanCommandOptions {
     cwd: string;
+    force?: boolean;
+    json?: boolean;
     stderr: (chunk: string) => void;
     stdout: (chunk: string) => void;
 }
 export interface CleanCommandDependencies {
+    confirmForceDeleteBranch: (branch: string) => Promise<boolean>;
+    confirmForceRemoveWorktree: (worktreePath: string) => Promise<boolean>;
     confirmRemoval: (worktrees: WorktreeEntry[]) => Promise<boolean>;
     promptForWorktrees: (worktrees: WorktreeEntry[]) => Promise<string[] | null>;
 }

package/dist/clean.js

@@ -1,16 +1,33 @@
 import { confirm, isCancel, multiselect } from '@clack/prompts';
-import { deleteBranch, loadLinkedWorktrees, removeWorktree, } from './worktree-management.js';
+import { isHeadless } from './headless.js';
+import { deleteBranch, forceDeleteBranch, forceRemoveWorktree, isBranchUnmergedError, isWorktreeDirtyError, loadLinkedWorktrees, removeWorktree, } from './worktree-management.js';
+import { defaultConfirmForceDeleteBranch, defaultConfirmForceRemoveWorktree } from './worktree-prompts.js';
 export function createCleanCommand(dependencies = {}) {
     const promptForWorktrees = dependencies.promptForWorktrees ?? defaultPromptForWorktrees;
     const confirmRemoval = dependencies.confirmRemoval ?? defaultConfirmRemoval;
+    const confirmForceRemoveWorktree = dependencies.confirmForceRemoveWorktree ?? defaultConfirmForceRemoveWorktree;
+    const confirmForceDeleteBranch = dependencies.confirmForceDeleteBranch ?? defaultConfirmForceDeleteBranch;
     return async function runCleanCommand(options) {
         const { linkedWorktrees, repository } = await loadLinkedWorktrees(options.cwd);
         const cleanupCandidates = linkedWorktrees.filter((worktree) => worktree.path !== repository.currentRoot);
         if (cleanupCandidates.length === 0) {
-            options.stderr('No linked worktrees to clean\n');
+            emitError(options, 'No linked worktrees to clean');
             return 1;
         }
-        const selections = await promptForWorktrees(cleanupCandidates);
+        if (!options.force && (options.json || isHeadless())) {
+            const message = '--force is required';
+            if (options.json) {
+                emitError(options, message);
+            }
+            else {
+                options.stderr(`gji clean: ${message} in non-interactive mode (GJI_NO_TUI=1)\n`);
+            }
+            return 1;
+        }
+        // With --force, skip selection prompt and target all candidates.
+        const selections = options.force
+            ? cleanupCandidates.map((w) => w.path)
+            : await promptForWorktrees(cleanupCandidates);
         if (!selections || selections.length === 0) {
             options.stderr('Aborted\n');
             return 1;
@@ -20,17 +37,67 @@ export function createCleanCommand(dependencies = {}) {
             options.stderr('Selected worktree no longer exists\n');
             return 1;
         }
-        if (!(await confirmRemoval(selectedWorktrees))) {
+        if (!options.force && !(await confirmRemoval(selectedWorktrees))) {
             options.stderr('Aborted\n');
             return 1;
         }
+        const removedPaths = [];
+        const removedWorktrees = [];
         for (const worktree of selectedWorktrees) {
-            await removeWorktree(repository.repoRoot, worktree.path);
+            try {
+                await removeWorktree(repository.repoRoot, worktree.path);
+            }
+            catch (error) {
+                if (!isWorktreeDirtyError(error)) {
+                    throw error;
+                }
+                if (!options.force && !(await confirmForceRemoveWorktree(worktree.path))) {
+                    reportRemovedPaths(removedPaths, options.stderr);
+                    options.stderr('Aborted\n');
+                    return 1;
+                }
+                try {
+                    await forceRemoveWorktree(repository.repoRoot, worktree.path);
+                }
+                catch (forceError) {
+                    if (!options.json) {
+                        reportRemovedPaths(removedPaths, options.stderr);
+                    }
+                    emitError(options, `Failed to remove worktree at ${worktree.path}: ${toMessage(forceError)}`);
+                    return 1;
+                }
+            }
+            removedPaths.push(worktree.path);
+            removedWorktrees.push(worktree);
             if (worktree.branch) {
-                await deleteBranch(repository.repoRoot, worktree.branch);
+                try {
+                    await deleteBranch(repository.repoRoot, worktree.branch);
+                }
+                catch (error) {
+                    if (!isBranchUnmergedError(error)) {
+                        throw error;
+                    }
+                    if (options.force || (await confirmForceDeleteBranch(worktree.branch))) {
+                        try {
+                            await forceDeleteBranch(repository.repoRoot, worktree.branch);
+                        }
+                        catch (forceError) {
+                            options.stderr(`Failed to delete branch ${worktree.branch}: ${toMessage(forceError)}\n`);
+                        }
+                    }
+                    else {
+                        options.stderr(`Branch ${worktree.branch} was not deleted (has unmerged commits)\n`);
+                    }
+                }
             }
         }
-        options.stdout(`${repository.repoRoot}\n`);
+        if (options.json) {
+            const removed = removedWorktrees.map((w) => ({ branch: w.branch, path: w.path }));
+            options.stdout(`${JSON.stringify({ removed }, null, 2)}\n`);
+        }
+        else {
+            options.stdout(`${repository.repoRoot}\n`);
+        }
         return 0;
     };
 }
@@ -48,6 +115,22 @@ function resolveSelectedWorktrees(worktrees, selections) {
     }
     return selectedWorktrees;
 }
+function reportRemovedPaths(paths, stderr) {
+    if (paths.length > 0) {
+        stderr(`Already removed: ${paths.join(', ')}\n`);
+    }
+}
+function emitError(options, message) {
+    if (options.json) {
+        options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
+    }
+    else {
+        options.stderr(`${message}\n`);
+    }
+}
+function toMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 async function defaultPromptForWorktrees(worktrees) {
     const choice = await multiselect({
         message: 'Choose worktrees to clean',

package/dist/cli.js

@@ -59,6 +59,7 @@ function registerCommands(program) {
         .command('new [branch]')
         .description('create a new branch or detached linked worktree')
         .option('--detached', 'create a detached worktree without a branch')
+        .option('--json', 'emit JSON on success or error instead of human-readable output')
         .action(notImplemented('new'));
     program
         .command('init [shell]')
@@ -68,6 +69,7 @@ function registerCommands(program) {
     program
         .command('pr <number>')
         .description('fetch a pull request ref and create a linked worktree')
+        .option('--json', 'emit JSON on success or error instead of human-readable output')
         .action(notImplemented('pr'));
     program
         .command('go [branch]')
@@ -97,11 +99,15 @@ function registerCommands(program) {
     program
         .command('clean')
         .description('interactively prune linked worktrees')
+        .option('-f, --force', 'bypass prompts, force-remove dirty worktrees, and force-delete unmerged branches')
+        .option('--json', 'emit JSON on success or error instead of human-readable output')
         .action(notImplemented('clean'));
     program
         .command('remove [branch]')
         .alias('rm')
         .description('remove a linked worktree and delete its branch when present')
+        .option('-f, --force', 'bypass prompts, force-remove a dirty worktree, and force-delete an unmerged branch')
+        .option('--json', 'emit JSON on success or error instead of human-readable output')
         .action(notImplemented('remove'));
     const configCommand = program
         .command('config')
@@ -124,7 +130,7 @@ function attachCommandActions(program, options) {
     program.commands
         .find((command) => command.name() === 'new')
         ?.action(async (branch, commandOptions) => {
-        const exitCode = await runNewCommand({ ...options, branch, detached: commandOptions.detached });
+        const exitCode = await runNewCommand({ ...options, branch, detached: commandOptions.detached, json: commandOptions.json });
         if (exitCode !== 0) {
             throw commanderExit(exitCode);
         }
@@ -144,8 +150,8 @@ function attachCommandActions(program, options) {
     });
     program.commands
         .find((command) => command.name() === 'pr')
-        ?.action(async (number) => {
-        const exitCode = await runPrCommand({ cwd: options.cwd, number, stderr: options.stderr, stdout: options.stdout });
+        ?.action(async (number, commandOptions) => {
+        const exitCode = await runPrCommand({ cwd: options.cwd, json: commandOptions.json, number, stderr: options.stderr, stdout: options.stdout });
         if (exitCode !== 0) {
             throw commanderExit(exitCode);
         }
@@ -215,9 +221,11 @@ function attachCommandActions(program, options) {
     });
     program.commands
         .find((command) => command.name() === 'clean')
-        ?.action(async () => {
+        ?.action(async (commandOptions) => {
         const exitCode = await runCleanCommand({
             cwd: options.cwd,
+            force: commandOptions.force,
+            json: commandOptions.json,
             stderr: options.stderr,
             stdout: options.stdout,
         });
@@ -225,10 +233,12 @@ function attachCommandActions(program, options) {
             throw commanderExit(exitCode);
         }
     });
-    const runRemovalCommand = async (branch) => {
+    const runRemovalCommand = async (branch, commandOptions = {}) => {
         const exitCode = await runRemoveCommand({
             branch,
             cwd: options.cwd,
+            force: commandOptions.force,
+            json: commandOptions.json,
             stderr: options.stderr,
             stdout: options.stdout,
         });

package/dist/config.d.ts

@@ -11,6 +11,8 @@ export declare const DEFAULT_CONFIG: GjiConfig;
 export declare function loadConfig(root: string): Promise<LoadedConfig>;
 export declare function loadEffectiveConfig(root: string, home?: string): Promise<GjiConfig>;
 export declare function loadGlobalConfig(home?: string): Promise<LoadedConfig>;
+export declare function saveLocalConfig(root: string, config: GjiConfig): Promise<string>;
+export declare function updateLocalConfigKey(root: string, key: string, value: unknown): Promise<GjiConfig>;
 export declare function saveGlobalConfig(config: GjiConfig, home?: string): Promise<string>;
 export declare function unsetGlobalConfigKey(key: string, home?: string): Promise<GjiConfig>;
 export declare function updateGlobalConfigKey(key: string, value: unknown, home?: string): Promise<GjiConfig>;