@solaqua/gji 0.10.0 → 0.11.0

package/README.md

@@ -11,7 +11,7 @@ gji new feature/payment-refactor   # new branch + worktree, cd in
 gji pr 1234                        # review PR in isolation, cd in
 gji pr open                         # open the PR for the current worktree
 gji go main                        # jump back, shell changes directory
-gji remove feature/payment-refactor
+gji done feature/payment-refactor
 ```
 
 ## Before / After
@@ -112,8 +112,8 @@ gji open
 gji open --select                # choose another worktree interactively
 gji open feature/dark-mode --editor code
 
-# clean up when done
-gji remove feature/dark-mode
+# finish a worktree when done
+gji done feature/dark-mode
 ```
 
 Worktrees land at a deterministic path so your editor bookmarks and scripts always know where to look:
@@ -135,7 +135,15 @@ gji pr 1234                       # checkout PR locally
 gji pr https://github.com/org/repo/pull/1234  # or paste the URL
 
 gji go feature/auth-refactor      # jump to a worktree
+gji go teammate-branch            # open an existing local or remote branch
+gji go -                          # return to the previous worktree
+gji go --root                     # return to the main repository checkout
 gji root                          # jump to repo root
+gji warp repo-a/main              # compatibility spelling for cross-repo navigation
+gji back                          # return through navigation history
+gji history                       # inspect recent navigation
+
+# with no branch, the chooser starts in the current repo; press Tab for all repos
 
 gji status                        # health overview + ahead/behind counts
 gji ls                            # list with status/upstream/last commit
@@ -146,7 +154,7 @@ gji sync --all                    # rebase every worktree
 
 gji clean                         # interactive bulk cleanup
 gji clean --stale                 # only target safe stale cleanup candidates
-gji remove feature/auth-refactor  # remove one worktree and its branch
+gji done feature/auth-refactor    # finish one worktree and its branch
 
 gji trigger-hook afterCreate      # re-run setup in the current worktree
 ```
@@ -231,24 +239,38 @@ path=$(gji root --print)
 
 | Command | Description |
 |---|---|
-| `gji new [branch] [--from-current] [--detached] [--open] [--editor <cli>] [--json]` | create branch + worktree, optionally based on the current worktree |
+| `gji new [branch] [--from-current] [--detached] [--no-fetch] [--take] [--copy] [--force] [--open] [--editor <cli>] [--dry-run] [--json]` | create branch + worktree from a refreshed remote base by default; `--no-fetch` opts out |
+| `gji done [branch] [--force] [--keep-branch] [--json]` | safely finish a linked worktree and return |
+| `gji undo [id] [--list] [--json]` | restore a journaled cleanup without overwriting work |
 | `gji pr <ref> [--json]` | fetch PR ref, create worktree, cd in |
 | `gji pr open [branch|#N] [--select]` | open the current worktree PR, or choose a linked worktree with `--select` |
+| `gji back [n] [--print]` | return to a previous worktree from navigation history |
+| `gji history [--json]` | show navigation history |
+| `gji warp [branch] [--print] [--json]` | compatibility spelling for cross-repository navigation |
 | `gji open [branch] [--select] [--editor <cli>] [--save] [--workspace]` | open the current or selected worktree in an editor |
-| `gji go [branch] [--print]` | jump to a worktree |
+| `gji go [branch] [--root] [--print] [--json]` | resolve and jump to a worktree, branch, remote, or PR |
 | `gji root [--print]` | jump to the main repo root |
 | `gji status [--json]` | repo overview, worktree health, ahead/behind |
 | `gji ls [--compact] [--json]` | list active worktrees |
 | `gji sync [--all]` | fetch and rebase worktrees onto default branch |
 | `gji sync-files [list\|add\|remove] [paths...]` | manage local files copied into new worktrees |
-| `gji clean [--stale] [--force] [--json]` | interactively prune linked worktrees |
-| `gji remove [branch] [--force] [--json]` | remove a worktree and its branch |
+| `gji clean [--stale] [--force] [--dry-run] [--json]` | interactively prune linked worktrees |
+| `gji remove [branch] [--force] [--dry-run] [--json]` (`rm`) | **deprecated**; use `gji done` for one worktree or `gji clean` for bulk cleanup |
 | `gji trigger-hook <hook>` | run a hook in the current worktree |
 | `gji config [get\|set\|unset] [key] [value]` | manage global defaults |
 | `gji init [shell]` | interactively set up onboarding, or print/install a shell wrapper |
 | `gji doctor [--json] [--fix] [--yes]` | check installation and configuration health; optionally remove stale repository entries |
 | `gji completion [shell]` | print shell completion definitions |
 
+The repository registry records projects that gji has visited so `go`, `warp`,
+and the chooser can resolve worktrees across repositories. It is advisory
+metadata: missing paths are skipped and `gji doctor --fix` can remove stale
+entries.
+
+`gji remove` and its `rm` alias remain available during the deprecation window,
+but print a migration warning in human-readable mode. Use `gji done <branch>`
+to finish one linked worktree or `gji clean` to prune several worktrees.
+
 ## Configuration
 
 No setup required. Optional config lives in:
@@ -266,8 +288,11 @@ No setup required. Optional config lives in:
 | `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; use global per-repo config for private files |
+| `syncDirs` | arbitrary directories to clone with filesystem copy-on-write before sync files |
+| `dependencyBootstrap` | dependency/build-state policy: `off`, `cow-then-repair`, or `install-only` |
+| `dependencyBuildCommand` | optional Cargo repair command used by `dependencyBootstrap` (default: `cargo check`) |
 | `skipInstallPrompt` | `true` to disable the auto-install prompt permanently |
-| `installSaveTarget` | `"local"` or `"global"` — where **Always**/**Never** choices are persisted (default: `"local"`); set during `gji init <shell> --write` |
+| `installSaveTarget` | `"local"` or `"global"` — where dependency policy and legacy **Always**/**Never** choices are persisted (default: `"local"`); set during `gji init <shell> --write` |
 | `hooks` | lifecycle scripts (see [Hooks](#hooks)) |
 | `repos` | per-repo overrides inside the global config (see below) |
 
@@ -276,7 +301,9 @@ No setup required. Optional config lives in:
   "branchPrefix": "feature/",
   "syncRemote": "upstream",
   "syncDefaultBranch": "main",
-  "syncFiles": [".env.example", ".nvmrc"]
+  "syncFiles": [".env.example", ".nvmrc"],
+  "syncDirs": [".next"],
+  "dependencyBootstrap": "cow-then-repair"
 }
 ```
 
@@ -304,6 +331,42 @@ This stores:
 }
 ```
 
+### Instant directory bootstrap
+
+Use `syncDirs` for advanced, arbitrary directories that should be available immediately in each new worktree. Dependency adapters discover their own project-local targets, so you do not need to list `node_modules`, `.venv`, or `target` here:
+
+```json
+{
+  "syncDirs": [".next", ".cache"]
+}
+```
+
+`gji new` clones these directories with APFS copy-on-write on macOS or mandatory reflinks on Linux, before `syncFiles`. It never falls back to a slow ordinary copy. Unsupported filesystems, external symlink targets, missing sources, and existing destinations are skipped safely; failed CoW attempts are cached in `~/.config/gji/state.json` so repeated worktree creation does not keep waiting on the same unsupported filesystem. `syncDirs` is generic: it does not know or special-case package managers.
+
+Paths are relative to the repository root. Absolute paths, `..` segments, and `.git` paths are rejected in all three config layers.
+
+The human output includes clone timing; dry-run can provide source-size estimates:
+
+```text
+⚡ cloned .next (size unavailable → 1.2s)
+```
+
+Use `dependencyBootstrap` when a package manager or build cache needs a reusable seed followed by authoritative repair:
+
+```json
+{
+  "dependencyBootstrap": "cow-then-repair"
+}
+```
+
+`cow-then-repair` supports pnpm (`node_modules` + `pnpm install --frozen-lockfile`), Yarn (`node_modules` + `yarn install --immutable`), uv (`.venv` + `uv sync --locked`), Cargo (`target` + the configured `dependencyBuildCommand`, or `cargo check`), and Bundler (`vendor/bundle` + `BUNDLE_PATH=vendor/bundle bundle install`). npm is install-only (`npm ci`) because it can delete an existing dependency tree; it never seeds `node_modules`. Only project-local targets are eligible, so global Ruby gems and package-manager caches are never cloned. CoW failure never triggers ordinary copying: repair runs from an empty target instead. The lifecycle is `CoW seed → syncFiles → repair/install → after-create`; a sync-file failure stops repair, install prompts, and hooks. A successful dependency seed is reported as `reused and repaired`, not as an install skip.
+
+When a supported lockfile is detected and no `dependencyBootstrap` policy is configured, interactive `gji new` and `gji pr` ask which policy to persist: **Reuse and repair (recommended)**, **Install fresh each time**, or **Skip dependency setup**. The prompt explains the detected tool—for example, pnpm reuses local `node_modules` through CoW and then runs `pnpm install --frozen-lockfile`. The choice is saved locally or in the per-repo global config according to `installSaveTarget`. Headless, JSON, and dry-run commands never prompt and retain the safe `off` default.
+
+Ecosystems dominated by global caches, such as Gradle, Maven, and Go, are not seeded until a safe project-local target and deterministic repair rule are available. Future adapters can add Composer, Poetry/PDM, Mix, Dart/Flutter, or .NET without changing `syncDirs`.
+
+Use `gji new --dry-run` to see the directories and estimated sizes without creating anything. `gji new --json` adds a `cloned` array and structured `dependencyBootstrap` events, including machine-readable reasons for skips and failures. If bootstrap fails, the JSON error includes the created worktree path; text mode prints the same path and a cleanup hint. The benchmark target for a 2 GB dependency tree on supported APFS/Btrfs or XFS filesystems is under 5 seconds; benchmark your repository locally because filesystem and storage behavior determine the result.
+
 ### Per-repo overrides in global config
 
 If you work across many repositories, you can scope config to a specific repo inside `~/.config/gji/config.json` without adding a `.gji.json` to that repo:
@@ -351,7 +414,7 @@ Run scripts automatically at key lifecycle moments:
 |---|---|
 | `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 |
+| `beforeRemove` | before `gji done` or `gji clean` deletes a worktree |
 
 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.
 
@@ -410,7 +473,9 @@ This is useful after cloning on a new machine, recovering a broken worktree, or
 
 ## Install prompt
 
-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:
+For supported lockfiles, the dependency policy prompt above is the primary setup choice. Keep `after-create` hooks for project-specific work such as `pnpm run generate`, code generation, local-service setup, or environment-specific commands; hooks are not a second dependency-bootstrap configuration.
+
+Projects without a supported dependency adapter can still use the legacy one-shot install prompt:
 
 ```
 Run `pnpm install` in the new worktree?
@@ -422,6 +487,8 @@ Run `pnpm install` in the new worktree?
 
 **Always** saves `hooks.afterCreate`; **Never** writes `skipInstallPrompt: true`. Where they are saved depends on `installSaveTarget` (see [Available keys](#available-keys)) — defaults to `.gji.json`.
 
+`syncDirs` remains generic and never suppresses installation or repair. To automate supported dependency/build setup, use `dependencyBootstrap`; the adapter always runs its lockfile/build repair after `syncFiles`. Explicit policies in global defaults, per-repo global config, or `.gji.json` always win over prompting.
+
 ## JSON output
 
 Every mutating command supports `--json` for scripting and AI agent use. Success goes to stdout, errors go to stderr with exit code 1.
@@ -429,18 +496,22 @@ Every mutating command supports `--json` for scripting and AI agent use. Success
 ```sh
 # create
 gji new --json feature/dark-mode
-# → { "branch": "feature/dark-mode", "path": "/…/worktrees/repo/feature/dark-mode" }
+# → { "branch": "feature/dark-mode", "path": "/…/worktrees/repo/feature/dark-mode", "repository": { "name": "repo", "root": "/…/repo" } }
 
 # fetch PR
 gji pr --json 1234
-# → { "branch": "pr/1234", "path": "/…/worktrees/repo/pr/1234" }
+# → { "branch": "pr/1234", "path": "/…/worktrees/repo/pr/1234", "repository": { "name": "repo", "root": "/…/repo" } }
+
+# resolve an existing destination without changing directories
+gji go --json feature/auth-refactor
+# → { "branch": "feature/auth-refactor", "path": "/…/worktrees/repo/feature/auth-refactor", "repository": { "name": "repo", "root": "/…/repo" } }
 
 # detailed list
 gji ls --json
 # → [{ "branch": "...", "status": "clean", "upstream": { "kind": "tracked", ... }, ... }]
 
-# remove
-gji remove --json --force feature/dark-mode
+# finish one worktree
+gji done --json --force feature/dark-mode
 # → { "branch": "feature/dark-mode", "path": "/…", "deleted": true }
 
 # bulk clean
@@ -457,7 +528,7 @@ gji clean --stale --json --force
 
 `gji clean --stale` limits cleanup to clean branch worktrees whose upstream is gone and whose branch is already merged into the configured or remote default branch.
 
-`--json` suppresses all interactive prompts. `--force` is required for `remove` and `clean` in JSON mode. `branch` is `null` for detached worktrees.
+`--json` suppresses all interactive prompts. Navigation results include a `repository` object with the stable repository `root` and display `name`. `--force` is required for `done` 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.
 
@@ -465,7 +536,7 @@ gji clean --stale --json --force
 
 ```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 done --force feature/ci-branch
 GJI_NO_TUI=1 gji clean --force
 ```
 

package/dist/back.d.ts

@@ -3,7 +3,10 @@ export declare const BACK_OUTPUT_FILE_ENV = "GJI_BACK_OUTPUT_FILE";
 export interface BackCommandOptions {
     cwd: string;
     home?: string;
+    json?: boolean;
     n?: number;
+    commandName?: string;
+    outputEnv?: string;
     print?: boolean;
     stderr: (chunk: string) => void;
     stdout: (chunk: string) => void;

package/dist/back.js

@@ -3,6 +3,7 @@ import { basename } from "node:path";
 import { loadEffectiveConfig } from "./config.js";
 import { appendHistory, loadHistory } from "./history.js";
 import { extractHooks, runHook } from "./hooks.js";
+import { createNavigationRepository, createNavigationTarget, } from "./navigation-output.js";
 import { detectRepository } from "./repo.js";
 import { writeShellOutput } from "./shell-handoff.js";
 export const BACK_OUTPUT_FILE_ENV = "GJI_BACK_OUTPUT_FILE";
@@ -31,10 +32,23 @@ export async function runBackCommand(options) {
         }
     }
     if (!target) {
-        options.stderr("gji back: no previous worktree in history\n");
-        options.stderr("Hint: Use 'gji go', 'gji new', or 'gji pr' to navigate between worktrees\n");
+        const commandName = options.commandName ?? "gji back";
+        if (options.json) {
+            options.stderr(`${JSON.stringify({ error: "no previous worktree in history" }, null, 2)}\n`);
+        }
+        else {
+            options.stderr(`${commandName}: no previous worktree in history\n`);
+        }
+        if (!options.json) {
+            options.stderr("Hint: Use 'gji go', 'gji new', or 'gji pr' to navigate between worktrees\n");
+        }
         return 1;
     }
+    if (options.json) {
+        const repository = await detectRepository(target.path);
+        options.stdout(`${JSON.stringify(createNavigationTarget(createNavigationRepository(repository.repoName, repository.repoRoot), target.path, target.branch), null, 2)}\n`);
+        return 0;
+    }
     try {
         const repository = await detectRepository(target.path);
         const config = await loadEffectiveConfig(repository.repoRoot, options.home, options.stderr);
@@ -49,21 +63,19 @@ export async function runBackCommand(options) {
         // Not in a git repo or hooks unavailable — proceed without hook
     }
     await appendHistory(target.path, target.branch, options.home);
-    await writeShellOutput(BACK_OUTPUT_FILE_ENV, target.path, options.stdout);
+    await writeShellOutput(options.outputEnv ?? BACK_OUTPUT_FILE_ENV, target.path, options.stdout);
     return 0;
 }
 export function formatHistoryList(history, cwd) {
     const branchWidth = Math.max("BRANCH".length, ...history.map((e) => (e.branch ?? "(detached)").length));
-    const lines = [
-        "  " + "BRANCH".padEnd(branchWidth) + " WHEN       PATH",
-    ];
+    const lines = [`  ${"BRANCH".padEnd(branchWidth)} WHEN       PATH`];
     for (const entry of history) {
         const isCurrent = entry.path === cwd;
         const branch = (entry.branch ?? "(detached)").padEnd(branchWidth);
         const when = formatAge(entry.timestamp).padEnd(10);
         lines.push(`${isCurrent ? "*" : " "} ${branch} ${when} ${entry.path}`);
     }
-    return lines.join("\n") + "\n";
+    return `${lines.join("\n")}\n`;
 }
 export function formatAge(timestamp) {
     const seconds = Math.floor((Date.now() - timestamp) / 1000);

package/dist/bootstrap-output.d.ts

@@ -0,0 +1,3 @@
+import type { DependencyBootstrapReporter } from "./dependency-bootstrap.js";
+import type { SyncDirectoryReporter } from "./sync-directories.js";
+export declare function createBootstrapReporter(write: (chunk: string) => void, json: boolean, measureCloneSize?: boolean): SyncDirectoryReporter & DependencyBootstrapReporter;

package/dist/bootstrap-output.js

@@ -0,0 +1,27 @@
+import { formatBytes } from "./format-bytes.js";
+export function createBootstrapReporter(write, json, measureCloneSize = false) {
+    return {
+        emitCachedFailureWarnings: !json,
+        measureCloneSize: measureCloneSize && !json,
+        write,
+        cloned: (directory) => {
+            if (json)
+                return;
+            write(`⚡ cloned ${directory.dir} (${formatBytes(directory.bytes)} → ${formatDuration(directory.ms)})\n`);
+        },
+        skipped: (directory) => {
+            if (json)
+                return;
+            write(`gji: skipped ${directory.dir} — ${directory.reason}\n`);
+        },
+        dependency: (event) => {
+            if (json)
+                return;
+            const target = event.target ? ` ${event.target}` : "";
+            write(`gji: ${event.state}${target} — ${event.message}\n`);
+        },
+    };
+}
+function formatDuration(ms) {
+    return `${(ms / 1000).toFixed(1)}s`;
+}

package/dist/bootstrap-preview.d.ts

@@ -0,0 +1,10 @@
+import type { DependencyBootstrapMode } from "./config.js";
+import { type BootstrapTarget, type DependencyBootstrapPreview } from "./dependency-bootstrap.js";
+export declare function createDependencyBootstrapPreview(mode: DependencyBootstrapMode, context: {
+    repoRoot: string;
+    currentRoot?: string;
+    worktreePath: string;
+    cargoBuildCommand?: string;
+    checkUvRuntime?: (target: BootstrapTarget) => Promise<boolean>;
+}): Promise<DependencyBootstrapPreview>;
+export declare function formatDependencyBootstrapPreview(preview: DependencyBootstrapPreview | undefined): string;

package/dist/bootstrap-preview.js

@@ -0,0 +1,21 @@
+import { prepareDependencyBootstrap, previewDependencyBootstrap, } from "./dependency-bootstrap.js";
+export async function createDependencyBootstrapPreview(mode, context) {
+    return previewDependencyBootstrap(await prepareDependencyBootstrap(mode, context));
+}
+export function formatDependencyBootstrapPreview(preview) {
+    if (!preview)
+        return "";
+    return preview.targets
+        .map(({ adapter, target, strategy }) => `Would ${formatBootstrapStrategy(strategy)} ${target} with ${adapter}\n`)
+        .join("");
+}
+function formatBootstrapStrategy(strategy) {
+    switch (strategy) {
+        case "cow-then-repair":
+            return "seed and repair";
+        case "repair-only":
+            return "repair";
+        case "install-only":
+            return "install";
+    }
+}

package/dist/clean.js

@@ -2,8 +2,9 @@ import { confirm, isCancel } from "@clack/prompts";
 import { loadEffectiveConfig } from "./config.js";
 import { isBranchMergedInto, readWorktreeHealth, resolveRemoteDefaultBranch, runGit, } from "./git.js";
 import { isHeadless } from "./headless.js";
+import { finalizeUndoOperation, recordUndoOperation } from "./undo.js";
 import { formatLastCommit, formatUpstreamState, readWorktreeInfos, serializeWorktreeInfo, } from "./worktree-info.js";
-import { deleteBranch, forceDeleteBranch, forceRemoveWorktree, isBranchUnmergedError, isWorktreeDeletionError, isWorktreeForceRemovalError, loadLinkedWorktrees, removeWorktree, } from "./worktree-management.js";
+import { deleteBranch, forceDeleteBranch, forceRemoveWorktree, isBranchUnmergedError, isSubmoduleWorktreeRemovalError, isWorktreeDeletionError, isWorktreeForceRemovalError, loadLinkedWorktrees, removeWorktree, } from "./worktree-management.js";
 import { buildWorktreePromptEntries, promptForMultipleWorktrees, } from "./worktree-picker.js";
 import { defaultConfirmForceDeleteBranch, defaultConfirmForceRemoveWorktree, } from "./worktree-prompts.js";
 export function createCleanCommand(dependencies = {}) {
@@ -79,6 +80,18 @@ export function createCleanCommand(dependencies = {}) {
         }
         const removedWorktrees = [];
         const failures = [];
+        let journal;
+        try {
+            journal = await recordUndoOperation("clean", repository.repoRoot, selectedWorktrees);
+        }
+        catch (error) {
+            emitError(options, `could not write undo journal; no worktrees were removed: ${toMessage(error)}`);
+            return 1;
+        }
+        if (!journal) {
+            emitError(options, "could not capture undo state; no worktrees were removed");
+            return 1;
+        }
         for (const worktree of selectedWorktrees) {
             if (options.stale &&
                 !(await isStaleCleanupCandidate(repository.repoRoot, worktree, staleBaseRef))) {
@@ -97,7 +110,9 @@ export function createCleanCommand(dependencies = {}) {
                     });
                     continue;
                 }
-                if (options.stale && !isWorktreeDeletionError(error)) {
+                if (options.stale &&
+                    !isWorktreeDeletionError(error) &&
+                    !isSubmoduleWorktreeRemovalError(error)) {
                     options.stderr(`Skipped ${worktree.path}: no longer a safe stale cleanup candidate\n`);
                     continue;
                 }
@@ -129,7 +144,12 @@ export function createCleanCommand(dependencies = {}) {
                 }
                 catch (error) {
                     if (!isBranchUnmergedError(error)) {
-                        throw error;
+                        failures.push({
+                            branch: worktree.branch,
+                            message: toMessage(error),
+                            path: worktree.path,
+                        });
+                        continue;
                     }
                     if (options.force ||
                         (await confirmForceDeleteBranch(worktree.branch))) {
@@ -146,6 +166,7 @@ export function createCleanCommand(dependencies = {}) {
                 }
             }
         }
+        await finalizeUndoOperation(journal, removedWorktrees);
         if (options.json) {
             const removed = removedWorktrees.map((worktree) => {
                 const info = selectedInfoByPath.get(worktree.path);
@@ -160,6 +181,7 @@ export function createCleanCommand(dependencies = {}) {
             reportCleanFailures(failures, options.stderr);
         }
         else {
+            options.stderr("undo: gji undo\n");
             options.stdout(`${repository.repoRoot}\n`);
         }
         return failures.length === 0 ? 0 : 1;