@solaqua/gji 0.10.0 → 0.12.0

package/README.md

@@ -1,487 +1,144 @@
-# gji — Git worktrees without the hassle
+# gji — Switch Git contexts without stashing
 
-> Jump between tasks instantly. No stash. No branch juggling. No mess.
+> Start, review, and switch between Git tasks without disturbing the work already open.
 
-`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.
+`gji` makes Git worktrees feel like normal shell navigation. Each task gets its
+own directory, dependencies, editor context, and terminal — so moving to a
+pull request or experiment does not require stashing, checking out, or
+reinstalling.
 
-That matters even more in AI-assisted workflows, where one repository often has several active tasks in parallel: your main feature, a PR review, a scratch experiment, or an agent-driven refactor. `gji` keeps each one isolated and easy to enter.
+## Start your next task
 
-```sh
-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
-```
-
-## Before / After
-
-<table>
-  <tr>
-    <td width="50%" valign="top">
-      <strong>Before</strong><br />
-      <img src=".github/assets/readme-before.gif" alt="Traditional branch review flow with git stash, branch switching, reinstalling dependencies, and a merge conflict on stash pop." />
-    </td>
-    <td width="50%" valign="top">
-      <strong>After</strong><br />
-      <img src=".github/assets/readme-after.gif" alt="gji creating an isolated pull request worktree from the terminal in a few commands." />
-    </td>
-  </tr>
-</table>
-
-Maintainer note: `pnpm generate:readme-demos` currently expects macOS, `zsh`, Google Chrome, `asciinema`, and `ffmpeg`.
-
----
-
-**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.**
-
----
-
-## 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 `npm install` to finish
-4. review
-5. checkout back
-6. pop your stash
-7. realize something is broken
-
-**Or you use `gji`, run `gji pr 1234`, and let the fresh worktree boot itself.**
-
-## Why it matters more now
-
-AI increases the amount of parallel work around a codebase.
-
-It is increasingly normal to have:
-
-1. your own branch open
-2. another branch for review
-3. a scratch space for testing an AI-generated change
-4. a separate worktree for validating a risky migration or refactor
-
-That makes Git worktrees more important, because a single shared checkout becomes the bottleneck. `gji` turns worktrees into a daily workflow instead of a Git power-user feature.
-
-## Install
+Run `gji new` and let the interactive flow guide you into a fresh worktree:
 
 ```sh
-npm install -g @solaqua/gji
+gji new
 ```
 
-Then run the guided setup in an interactive terminal:
+Choose a task name and setup options, then continue working in the new
+directory. For repeatable workflows, you can still provide a branch directly:
 
 ```sh
-gji init
-# restart your shell, or source the rc file shown by the wizard
-gji doctor
+gji new feature/payment-refactor
 ```
 
-The wizard installs shell integration, completions, and an available editor. In a non-interactive environment, use the existing explicit shell command instead:
+## The problem
 
-```sh
-gji init zsh --write
+You are halfway through a feature when someone asks you to review a pull
+request. Without worktrees, a quick review often becomes:
+
+```text
+stash → checkout → reinstall → review → checkout back → stash pop
 ```
 
-## Quick start
+With `gji`, the review gets its own workspace and your current task stays
+untouched:
 
 ```sh
-# start a new task
-gji new feature/dark-mode
-
-# start a task and open it straight in your editor
-gji new feature/dark-mode --open --editor cursor
-
-# review a pull request
 gji pr 1234
-gji pr open                         # open the PR for the current worktree
-gji pr open --select                # choose a PR from any linked worktree
-gji pr open feature/auth-refactor   # open the PR for a branch
-gji pr open '#1234'                 # open an open PR directly
-
-# see what's open
-gji status
-
-# jump between worktrees
-gji go feature/dark-mode
-gji go main
-
-# open the current worktree in an editor
-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
-```
-
-Worktrees land at a deterministic path so your editor bookmarks and scripts always know where to look:
-
-```
-../worktrees/<repo>/<branch>
 ```
 
-Set `worktreePath` in your config to use a different base (e.g. `"~/worktrees"` → `~/worktrees/<branch>`).
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <strong>Before</strong><br />
+      <img src=".github/assets/readme-before.gif" alt="Traditional branch switching with stash and reinstall steps" />
+    </td>
+    <td width="50%" valign="top">
+      <strong>After</strong><br />
+      <img src=".github/assets/readme-after.gif" alt="Creating an isolated pull request worktree with gji" />
+    </td>
+  </tr>
+</table>
 
-## Daily workflow
+## Remember four commands
 
 ```sh
-gji new feature/auth-refactor     # new branch + worktree
-gji new feature/auth-tests --from-current  # branch from the current worktree
-gji new --detached                # scratch space, auto-named
-
-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 root                          # jump to repo root
-
-gji status                        # health overview + ahead/behind counts
-gji ls                            # list with status/upstream/last commit
-gji ls --compact                  # branch/path only
-
-gji sync                          # rebase current worktree onto default branch
-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 trigger-hook afterCreate      # re-run setup in the current worktree
+gji new                            # interactively start a task
+gji pr 1234                        # open a pull request in isolation
+gji go main                        # jump to another worktree
+gji done feature/payment-refactor  # finish and clean up a task
 ```
 
-## Comparison
-
-`gji` sits between raw Git primitives and larger Git or repository tools:
-
-- **vs raw `git worktree`**: same underlying capability, but with branch-first commands, shell handoff, PR checkout, hooks, sync, and cleanup built into the workflow
-- **vs `lazygit`**: `lazygit` is a broad Git UI; `gji` is narrower and faster for opening, jumping between, and removing isolated branch directories
-- **vs `ghq`**: `ghq` organizes where repositories live; `gji` organizes which branch, PR, or worktree you should be in once you are inside one
-
-Use `gji` when your bottleneck is repeated context switching between features, reviews, and maintenance work without disturbing what is already open.
-
-It is especially useful when those contexts are happening in parallel across both human and AI-assisted work.
-
-See the full comparison in [website/docs/comparison.mdx](./website/docs/comparison.mdx).
-
-## Shell setup
+With shell integration enabled, each command moves your shell into the
+selected worktree automatically.
 
-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, completions, and an editor once with:
+## Install
 
 ```sh
+npm install -g @solaqua/gji
 gji init
-gji doctor
-```
-
-`gji init` is interactive. For dotfiles or CI, the explicit shell commands remain available and preserve their existing output:
-
-```sh
-# zsh
-echo 'eval "$(gji init zsh)"' >> ~/.zshrc
-
-# bash
-echo 'eval "$(gji init bash)"' >> ~/.bashrc
-
-# fish
-gji init fish --write
-```
-
-Install completions separately so your shell rc stays small:
-
-```sh
-# zsh
-mkdir -p ~/.zsh/completions
-gji completion zsh > ~/.zsh/completions/_gji
-# add this before running compinit in ~/.zshrc
-fpath=(~/.zsh/completions $fpath)
-
-# bash
-mkdir -p ~/.local/share/bash-completion/completions
-gji completion bash > ~/.local/share/bash-completion/completions/gji
-
-# fish
-mkdir -p ~/.config/fish/completions
-gji completion fish > ~/.config/fish/completions/gji.fish
-```
-
-After a reinstall or upgrade, refresh both the wrapper and the completion file:
-
-```sh
-# zsh
-eval "$(gji init zsh)"
-gji completion zsh > ~/.zsh/completions/_gji
-# if zsh is already running, refresh completion discovery too
-autoload -Uz compinit && compinit
-
-# fish
-gji init fish --write
-gji completion fish > ~/.config/fish/completions/gji.fish
-source ~/.config/fish/config.fish
-```
-
-For scripts that need the raw path, use `--print`:
-
-```sh
-path=$(gji go --print feature/dark-mode)
-path=$(gji root --print)
-```
-
-## Commands
-
-| Command | Description |
-|---|---|
-| `gji new [branch] [--from-current] [--detached] [--open] [--editor <cli>] [--json]` | create branch + worktree, optionally based on the current worktree |
-| `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 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 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 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 |
-
-## Configuration
-
-No setup required. Optional config lives in:
-
-- `~/.config/gji/config.json` — global defaults
-- `.gji.json` — repo-local overrides (takes precedence)
-
-### Available keys
-
-| Key | Description |
-|---|---|
-| `branchPrefix` | prefix added to new branch names (e.g. `"feature/"`) |
-| `editor` | default editor CLI for `gji open` and `gji new --open` (e.g. `"cursor"`, `"code"`, `"zed"`); set automatically with `gji open --save` |
-| `worktreePath` | base directory for new worktrees (absolute or `~/…`); overrides the default `../worktrees/<repo>/` layout |
-| `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 |
-| `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` |
-| `hooks` | lifecycle scripts (see [Hooks](#hooks)) |
-| `repos` | per-repo overrides inside the global config (see below) |
-
-```json
-{
-  "branchPrefix": "feature/",
-  "syncRemote": "upstream",
-  "syncDefaultBranch": "main",
-  "syncFiles": [".env.example", ".nvmrc"]
-}
 ```
 
-### Syncing local files
-
-Use `syncFiles` for private, gitignored, or machine-local files that every new worktree needs, such as `.env.local` or `.npmrc`. `gji new` copies these files from the main worktree before install hooks run, skips missing source files, and does not overwrite files that already exist in the target worktree.
-
-For private files, prefer the `sync-files` command. It writes to your global per-repo config so secret filenames do not need to be committed to `.gji.json`:
+`gji init` interactively installs shell integration, completions, and an
+available editor. Restart your shell, or source the rc file shown by the
+wizard, then run:
 
 ```sh
-gji sync-files add .env.local .npmrc
-gji sync-files list
-gji sync-files remove .npmrc
-```
-
-This stores:
-
-```json
-{
-  "repos": {
-    "/home/me/code/my-repo": {
-      "syncFiles": [".env.local"]
-    }
-  }
-}
-```
-
-### 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:
-
-```json
-{
-  "branchPrefix": "feature/",
-  "repos": {
-    "/home/me/code/my-repo": {
-      "branchPrefix": "fix/",
-      "hooks": {
-        "afterCreate": "npm install"
-      }
-    }
-  }
-}
+gji doctor
 ```
 
-Precedence (lowest → highest): **global defaults → per-repo global → local `.gji.json`**. Hooks from all three layers are merged per key — different keys all apply, same key the higher-precedence layer wins.
+Without shell integration, commands still print paths for scripts and other
+non-interactive use. See the [installation guide](https://gji.solaqua.dev/docs/installation)
+for explicit shell setup.
 
-### Config commands
+## A typical day
 
 ```sh
-gji config get
-gji config get branchPrefix
-gji config set branchPrefix feature/
-gji config unset branchPrefix
-```
-
-## Hooks
-
-Run scripts automatically at key lifecycle moments:
-
-```json
-{
-  "hooks": {
-    "afterCreate": ["pnpm", "install"],
-    "afterEnter": ["printf", "switched to %s\n", "{{branch}}"],
-    "beforeRemove": "pnpm run cleanup"
-  }
-}
-```
+# Start feature work
+gji new
 
-| 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 |
+# Check what is active
+gji
 
-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.
+# Review a PR without changing the current task
+gji pr 1234
 
-Prefer argv-array hooks for simple commands:
+# Move between tasks
+gji go feature/payment-refactor
+gji back
 
-```json
-{
-  "hooks": {
-    "afterCreate": ["pnpm", "install"],
-    "afterEnter": ["printf", "switched to %s at %s\n", "{{branch}}", "{{path}}"]
-  }
-}
+# Keep worktrees current and remove finished work
+gji sync
+gji done feature/payment-refactor
 ```
 
-Array hooks run without a shell and pass each array item as exactly one argument. Use string hooks only when you need shell features like `&&`, pipes, redirects, shell functions, or `nvm use`.
-
-Template values are interpolated before the shell parses string hooks, so avoid putting `{{branch}}`, `{{path}}`, or `{{repo}}` directly into shell strings. For shell-string hooks, the safer pattern is to use the environment variables and double-quote each expansion:
+Worktrees use a predictable location by default:
 
-```json
-{
-  "hooks": {
-    "afterCreate": "pnpm install && printf 'ready: %s\n' \"$GJI_PATH\""
-  }
-}
+```text
+../worktrees/<repo>/<branch>
 ```
 
-Avoid unquoted template values in shell strings, such as `echo {{branch}}` or `cd {{path}}`.
+That keeps editor bookmarks, scripts, and terminal navigation stable.
 
-Hooks from all three config layers merge per key — different keys from different layers both apply, same key the higher-precedence layer wins:
+## More capabilities
 
-```jsonc
-// ~/.config/gji/config.json
-{ "hooks": { "afterCreate": "nvm use", "afterEnter": "echo hi" } }
+Use the documentation when you need to go beyond the core workflow:
 
-// per-repo entry in ~/.config/gji/config.json
-{ "repos": { "/my/repo": { "hooks": { "afterCreate": "npm install" } } } }
+- [Daily workflow](https://gji.solaqua.dev/docs/daily-workflow) — navigation, PRs, sync, and cleanup
+- [Commands](https://gji.solaqua.dev/docs/commands) — complete command reference
+- [Shell integration](https://gji.solaqua.dev/docs/shell-integration) — zsh, bash, and fish setup
+- [Configuration](https://gji.solaqua.dev/docs/configuration) — paths, defaults, and local files
+- [Hooks](https://gji.solaqua.dev/docs/hooks) — automate setup and cleanup
+- [Sync and cleanup](https://gji.solaqua.dev/docs/sync-and-cleanup) — maintain active worktrees
+- [Comparison](https://gji.solaqua.dev/docs/comparison) — `gji` vs `git worktree`, `lazygit`, and `ghq`
+- [FAQ and troubleshooting](https://gji.solaqua.dev/docs/faq) — common questions and fixes
 
-// .gji.json
-{ "hooks": { "beforeRemove": "echo bye" } }
-
-// effective
-{ "hooks": { "afterCreate": "npm install", "afterEnter": "echo hi", "beforeRemove": "echo bye" } }
-```
-
-### Triggering hooks manually
-
-Run any hook in the current worktree on demand:
+`gji` also supports JSON output for scripts and AI-assisted workflows:
 
 ```sh
-gji trigger-hook afterCreate   # re-run the setup script
-gji trigger-hook afterEnter    # re-run the enter script
-gji trigger-hook beforeRemove  # dry-run the cleanup script
-```
-
-This is useful after cloning on a new machine, recovering a broken worktree, or letting an AI agent bootstrap an already-existing worktree without needing interactive prompts.
-
-## 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:
-
-```
-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
-```
-
-**Always** saves `hooks.afterCreate`; **Never** writes `skipInstallPrompt: true`. Where they are saved depends on `installSaveTarget` (see [Available keys](#available-keys)) — defaults to `.gji.json`.
-
-## 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.
-
-```sh
-# create
+gji --json
 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" }
-
-# detailed list
-gji ls --json
-# → [{ "branch": "...", "status": "clean", "upstream": { "kind": "tracked", ... }, ... }]
-
-# remove
-gji remove --json --force feature/dark-mode
-# → { "branch": "feature/dark-mode", "path": "/…", "deleted": true }
-
-# bulk clean
-gji clean --json --force
-# → { "removed": [{ "branch": "...", "path": "..." }, …] }
-
-# stale-only clean
-gji clean --stale --json --force
-# → { "removed": [{ "branch": "...", "path": "..." }, …] }
-
-# error shape (any command)
-# stderr → { "error": "branch argument is required" }
+gji go --json feature/dark-mode
 ```
 
-`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.
-
-`gji ls --json` and `gji status --json` also produce structured output — see `gji status --json | jq` for the full schema.
+Read the [full documentation](https://gji.solaqua.dev) for configuration,
+dependency bootstrap, hooks, automation, and the complete CLI reference.
 
-## Non-interactive / CI mode
-
-```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
-```
-
-`GJI_NO_TUI=1` disables all prompts. Commands that need confirmation require their non-interactive approval flag (`--force` for cleanup commands, `--yes` for `doctor --fix`). `--json` implies the same behaviour.
-
-`gji pr open --select` requires an interactive terminal; plain `gji pr open` opens the PR for the current worktree without prompting.
-If the current worktree has no open PR or has multiple open PRs in headless mode, pass `gji pr open <branch|#N>` explicitly.
-
-Update notifications are also suppressed automatically in non-interactive and `--json` runs. Users can opt out explicitly with `NO_UPDATE_NOTIFIER=1` or `--no-update-notifier`.
-
-## Notes
+---
 
-- 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` fetches from `origin` using the first matching forge ref namespace: GitHub `refs/pull/<number>/head`, GitLab `refs/merge-requests/<number>/head`, then Bitbucket `refs/pull-requests/<number>/from`
-- `gji pr open` reads open PRs from the `origin` forge (GitHub, GitLab, or Bitbucket), preferring an installed authenticated provider CLI and falling back to its public API
+If `gji` has saved you from a `git stash` spiral, a ⭐ on
+[GitHub](https://github.com/sjquant/gji) helps other developers find it.
 
 ## License
 

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`;
+}