@solaqua/gji 0.4.0 → 0.4.1

package/README.md

@@ -1,9 +1,11 @@
 # gji — Git worktrees without the hassle
 
-> Jump between tasks instantly. No stash. No reinstall. No mess.
+> Jump between tasks instantly. No stash. No branch juggling. No mess.
 
 `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.
 
+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.
+
 ```sh
 gji new feature/payment-refactor   # new branch + worktree, cd in
 gji pr 1234                        # review PR in isolation, cd in
@@ -11,6 +13,23 @@ 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.**
@@ -23,13 +42,26 @@ 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
+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` and it is just `gji pr 1234`.**
+**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
 
@@ -41,10 +73,32 @@ Then add shell integration so `gji go`, `gji new`, and `gji remove` can change y
 
 ```sh
 # zsh
-echo 'eval "$(gji init zsh)"' >> ~/.zshrc && source ~/.zshrc
+echo 'eval "$(gji init zsh)"' >> ~/.zshrc
 
 # bash
-echo 'eval "$(gji init bash)"' >> ~/.bashrc && source ~/.bashrc
+echo 'eval "$(gji init bash)"' >> ~/.bashrc
+
+# fish
+gji init fish --write
+source ~/.config/fish/config.fish
+```
+
+Install completions as separate files:
+
+```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
 ```
 
 ## Quick start
@@ -88,17 +142,33 @@ gji go feature/auth-refactor      # jump to a worktree
 gji root                          # jump to repo root
 
 gji status                        # health overview + ahead/behind counts
-gji ls                            # compact list
+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
 ```
 
+## 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 repositories; `gji` organizes active branches and PRs within one repository
+
+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
 
 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:
@@ -107,7 +177,7 @@ Without shell integration `gji` prints paths and exits — which is fine for scr
 gji init zsh   # prints the shell function, review it if you like
 ```
 
-To install automatically:
+Install the wrapper once:
 
 ```sh
 # zsh
@@ -115,12 +185,42 @@ 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, re-source to pick up changes:
+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`:
@@ -139,13 +239,14 @@ path=$(gji root --print)
 | `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 ls [--compact] [--json]` | list active worktrees |
 | `gji sync [--all]` | fetch and rebase worktrees onto default branch |
-| `gji clean [--force] [--json]` | interactively prune stale 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]` | print or install shell integration |
+| `gji completion [shell]` | print shell completion definitions |
 
 ## Configuration
 
@@ -283,6 +384,10 @@ gji new --json feature/dark-mode
 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 }
@@ -291,10 +396,16 @@ gji remove --json --force feature/dark-mode
 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 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.
@@ -309,11 +420,13 @@ GJI_NO_TUI=1 gji clean --force
 
 `GJI_NO_TUI=1` disables all prompts. Commands that need confirmation require `--force`. `--json` implies the same behaviour.
 
+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` parses GitHub, GitLab, and Bitbucket URLs but always fetches via `refs/pull/<number>/head` from `origin`
+- `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`
 
 ## License
 

package/dist/clean.d.ts

@@ -4,6 +4,7 @@ export interface CleanCommandOptions {
     dryRun?: boolean;
     force?: boolean;
     json?: boolean;
+    stale?: boolean;
     stderr: (chunk: string) => void;
     stdout: (chunk: string) => void;
 }

package/dist/clean.js

@@ -1,6 +1,8 @@
 import { confirm, isCancel, multiselect } from '@clack/prompts';
-import { readWorktreeHealth } from './git.js';
+import { loadEffectiveConfig } from './config.js';
+import { isBranchMergedInto, readWorktreeHealth, resolveRemoteDefaultBranch, runGit } from './git.js';
 import { isHeadless } from './headless.js';
+import { formatLastCommit, formatUpstreamState, formatWorktreeHint, readWorktreeInfos, serializeWorktreeInfo, } from './worktree-info.js';
 import { deleteBranch, forceDeleteBranch, forceRemoveWorktree, isBranchUnmergedError, isWorktreeDirtyError, loadLinkedWorktrees, removeWorktree, } from './worktree-management.js';
 import { defaultConfirmForceDeleteBranch, defaultConfirmForceRemoveWorktree } from './worktree-prompts.js';
 export function createCleanCommand(dependencies = {}) {
@@ -10,8 +12,18 @@ export function createCleanCommand(dependencies = {}) {
     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);
+        const linkedCleanupCandidates = linkedWorktrees.filter((worktree) => worktree.path !== repository.currentRoot);
+        const staleBaseRef = options.stale
+            ? await resolveStaleBaseRef(repository.repoRoot, options.stderr)
+            : null;
+        const cleanupCandidates = options.stale
+            ? await filterStaleCleanupCandidates(repository.repoRoot, linkedCleanupCandidates, staleBaseRef)
+            : linkedCleanupCandidates;
         if (cleanupCandidates.length === 0) {
+            if (options.stale) {
+                emitNoStaleCandidates(options);
+                return 0;
+            }
             emitError(options, 'No linked worktrees to clean');
             return 1;
         }
@@ -25,8 +37,8 @@ export function createCleanCommand(dependencies = {}) {
             }
             return 1;
         }
-        // With --force, or dry-run in headless/json mode, skip selection prompt and target all candidates.
-        const shouldSelectAll = options.force || (options.dryRun && (options.json || isHeadless()));
+        // With --force, or non-interactive dry-runs, skip selection prompt and target all candidates.
+        const shouldSelectAll = options.force || (options.dryRun && (options.stale || options.json || isHeadless()));
         const selections = shouldSelectAll
             ? cleanupCandidates.map((w) => w.path)
             : await promptForWorktrees(cleanupCandidates);
@@ -39,19 +51,20 @@ export function createCleanCommand(dependencies = {}) {
             options.stderr('Selected worktree no longer exists\n');
             return 1;
         }
+        const selectedWorktreeInfos = await readWorktreeInfos(selectedWorktrees);
+        const selectedInfoByPath = new Map(selectedWorktreeInfos.map((info) => [info.path, info]));
         if (!options.dryRun && !options.force && !(await confirmRemoval(selectedWorktrees))) {
             options.stderr('Aborted\n');
             return 1;
         }
         if (options.dryRun) {
             if (options.json) {
-                const removed = selectedWorktrees.map((w) => ({ branch: w.branch, path: w.path }));
+                const removed = selectedWorktreeInfos.map((info) => serializeWorktreeInfo(info));
                 options.stdout(`${JSON.stringify({ removed, dryRun: true }, null, 2)}\n`);
             }
             else {
-                for (const w of selectedWorktrees) {
-                    const desc = w.branch ? `branch: ${w.branch}` : 'detached';
-                    options.stdout(`Would remove worktree at ${w.path} (${desc})\n`);
+                for (const info of selectedWorktreeInfos) {
+                    options.stdout(`Would remove worktree at ${info.path} (${formatCleanInfo(info)})\n`);
                 }
             }
             return 0;
@@ -59,6 +72,10 @@ export function createCleanCommand(dependencies = {}) {
         const removedPaths = [];
         const removedWorktrees = [];
         for (const worktree of selectedWorktrees) {
+            if (options.stale && !(await isStaleCleanupCandidate(repository.repoRoot, worktree, staleBaseRef))) {
+                options.stderr(`Skipped ${worktree.path}: no longer a safe stale cleanup candidate\n`);
+                continue;
+            }
             try {
                 await removeWorktree(repository.repoRoot, worktree.path);
             }
@@ -66,6 +83,10 @@ export function createCleanCommand(dependencies = {}) {
                 if (!isWorktreeDirtyError(error)) {
                     throw error;
                 }
+                if (options.stale) {
+                    options.stderr(`Skipped ${worktree.path}: no longer a safe stale cleanup candidate\n`);
+                    continue;
+                }
                 if (!options.force && !(await confirmForceRemoveWorktree(worktree.path))) {
                     reportRemovedPaths(removedPaths, options.stderr);
                     options.stderr('Aborted\n');
@@ -107,7 +128,12 @@ export function createCleanCommand(dependencies = {}) {
             }
         }
         if (options.json) {
-            const removed = removedWorktrees.map((w) => ({ branch: w.branch, path: w.path }));
+            const removed = removedWorktrees.map((worktree) => {
+                const info = selectedInfoByPath.get(worktree.path);
+                return info === undefined
+                    ? { branch: worktree.branch, path: worktree.path }
+                    : serializeWorktreeInfo(info);
+            });
             options.stdout(`${JSON.stringify({ removed }, null, 2)}\n`);
         }
         else {
@@ -117,6 +143,55 @@ export function createCleanCommand(dependencies = {}) {
     };
 }
 export const runCleanCommand = createCleanCommand();
+async function filterStaleCleanupCandidates(repoRoot, worktrees, baseBranch) {
+    if (baseBranch === null) {
+        return [];
+    }
+    const results = await Promise.all(worktrees.map((worktree) => isStaleCleanupCandidate(repoRoot, worktree, baseBranch)));
+    return worktrees.filter((_, index) => results[index]);
+}
+async function resolveStaleBaseRef(repoRoot, stderr) {
+    const config = await loadEffectiveConfig(repoRoot, undefined, stderr);
+    const remote = resolveConfiguredString(config.syncRemote) ?? 'origin';
+    const configuredDefaultBranch = resolveConfiguredString(config.syncDefaultBranch);
+    if (configuredDefaultBranch) {
+        return await resolveFetchedRemoteRef(repoRoot, remote, configuredDefaultBranch);
+    }
+    try {
+        const remoteDefaultBranch = await resolveRemoteDefaultBranch(repoRoot, remote);
+        return remoteDefaultBranch === null
+            ? null
+            : await resolveFetchedRemoteRef(repoRoot, remote, remoteDefaultBranch);
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveFetchedRemoteRef(repoRoot, remote, branch) {
+    try {
+        await runGit(repoRoot, ['fetch', '--prune', remote]);
+        return `${remote}/${branch}`;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveConfiguredString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+async function isStaleCleanupCandidate(repoRoot, worktree, baseBranch) {
+    if (baseBranch === null) {
+        return false;
+    }
+    if (worktree.branch === null) {
+        return false;
+    }
+    const health = await readWorktreeHealth(worktree.path);
+    if (health.status !== 'clean' || !health.upstreamGone) {
+        return false;
+    }
+    return isBranchMergedInto(repoRoot, worktree.branch, baseBranch);
+}
 function resolveSelectedWorktrees(worktrees, selections) {
     const selectedWorktrees = [];
     const seenPaths = new Set();
@@ -135,6 +210,13 @@ function reportRemovedPaths(paths, stderr) {
         stderr(`Already removed: ${paths.join(', ')}\n`);
     }
 }
+function formatCleanInfo(info) {
+    const branch = info.branch === null ? 'detached' : `branch: ${info.branch}`;
+    const status = `status: ${info.status}`;
+    const upstream = `upstream: ${formatUpstreamState(info.upstream)}`;
+    const last = `last: ${formatLastCommit(info.lastCommitTimestamp)}`;
+    return [branch, status, upstream, last].join(', ');
+}
 function emitError(options, message) {
     if (options.json) {
         options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
@@ -143,18 +225,26 @@ function emitError(options, message) {
         options.stderr(`${message}\n`);
     }
 }
+function emitNoStaleCandidates(options) {
+    if (options.json) {
+        const payload = options.dryRun
+            ? { removed: [], dryRun: true }
+            : { removed: [] };
+        options.stdout(`${JSON.stringify(payload, null, 2)}\n`);
+        return;
+    }
+    options.stdout('No stale linked worktrees to clean\n');
+}
 function toMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 async function defaultPromptForWorktrees(worktrees) {
-    const healthResults = await Promise.allSettled(worktrees.map((w) => readWorktreeHealth(w.path)));
+    const infos = await readWorktreeInfos(worktrees);
     const choice = await multiselect({
         message: 'Choose worktrees to clean',
         options: worktrees.map((worktree, i) => {
-            const health = healthResults[i].status === 'fulfilled' ? healthResults[i].value : null;
-            const isStale = health?.upstreamGone === true;
             return {
-                hint: isStale ? `${worktree.path} (upstream gone)` : worktree.path,
+                hint: formatWorktreeHint(infos[i]),
                 label: worktree.branch ?? '(detached)',
                 value: worktree.path,
             };

package/dist/cli.js

@@ -1,8 +1,11 @@
 import { createRequire } from 'node:module';
 import { Command } from 'commander';
+import updateNotifier from 'update-notifier';
 import { runCleanCommand } from './clean.js';
+import { runCompletionCommand } from './completion.js';
 import { runConfigCommand } from './config-command.js';
 import { runGoCommand } from './go.js';
+import { isHeadless } from './headless.js';
 import { runInitCommand } from './init.js';
 import { runLsCommand } from './ls.js';
 import { runNewCommand } from './new.js';
@@ -14,22 +17,26 @@ import { runSyncCommand } from './sync.js';
 import { runTriggerHookCommand } from './trigger-hook.js';
 export function createProgram() {
     const program = new Command();
-    const packageVersion = readPackageVersion();
+    const packageMetadata = readPackageMetadata();
     program
         .name('gji')
         .description('Context switching without the mess.')
-        .version(packageVersion)
+        .version(packageMetadata.version)
         .showHelpAfterError()
         .showSuggestionAfterError();
     registerCommands(program);
     return program;
 }
-function readPackageVersion() {
+function readPackageMetadata() {
     const require = createRequire(import.meta.url);
     const packageJson = require('../package.json');
-    return typeof packageJson.version === 'string' ? packageJson.version : '0.0.0';
+    return {
+        name: typeof packageJson.name === 'string' ? packageJson.name : 'gji',
+        version: typeof packageJson.version === 'string' ? packageJson.version : '0.0.0',
+    };
 }
 export async function runCli(argv, options = {}) {
+    await maybeNotifyForUpdates(argv);
     const program = createProgram();
     const cwd = options.cwd ?? process.cwd();
     const stdout = options.stdout ?? (() => undefined);
@@ -55,6 +62,36 @@ export async function runCli(argv, options = {}) {
         throw error;
     }
 }
+async function maybeNotifyForUpdates(argv) {
+    if (shouldSkipUpdateNotification(argv)) {
+        return;
+    }
+    try {
+        defaultNotifyForUpdates(readPackageMetadata());
+    }
+    catch {
+        // Ignore notifier failures so startup behaviour stays stable.
+    }
+}
+function shouldSkipUpdateNotification(argv) {
+    return (argv.length === 0
+        || argv.includes('--json')
+        || argv.some(isHelpOrVersionArgument)
+        || isHeadless()
+        || process.stdout.isTTY !== true
+        || process.stderr.isTTY !== true);
+}
+function isHelpOrVersionArgument(argument) {
+    return (argument === '--help'
+        || argument === '-h'
+        || argument === 'help'
+        || argument === '--version'
+        || argument === '-V');
+}
+function defaultNotifyForUpdates(pkg) {
+    const notifier = updateNotifier({ pkg });
+    notifier.notify();
+}
 function registerCommands(program) {
     program
         .command('new [branch]')
@@ -69,6 +106,10 @@ function registerCommands(program) {
         .description('print or install shell integration')
         .option('--write', 'write the integration to the shell config file')
         .action(notImplemented('init'));
+    program
+        .command('completion [shell]')
+        .description('print shell completion definitions')
+        .action(notImplemented('completion'));
     program
         .command('pr <ref>')
         .description('fetch a pull request by number, #number, or URL into a linked worktree')
@@ -99,12 +140,14 @@ function registerCommands(program) {
     program
         .command('ls')
         .description('list active worktrees')
+        .option('--compact', 'show only branch and path columns')
         .option('--json', 'print active worktrees as JSON')
         .action(notImplemented('ls'));
     program
         .command('clean')
         .description('interactively prune linked worktrees')
         .option('-f, --force', 'bypass prompts, force-remove dirty worktrees, and force-delete unmerged branches')
+        .option('--stale', 'only target clean worktrees whose upstream is gone and branch is merged into the default branch')
         .option('--dry-run', 'show what would be deleted without removing anything')
         .option('--json', 'emit JSON on success or error instead of human-readable output')
         .action(notImplemented('clean'));
@@ -160,6 +203,18 @@ function attachCommandActions(program, options) {
             throw commanderExit(exitCode);
         }
     });
+    program.commands
+        .find((command) => command.name() === 'completion')
+        ?.action(async (shell) => {
+        const exitCode = await runCompletionCommand({
+            shell,
+            stderr: options.stderr,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
     program.commands
         .find((command) => command.name() === 'pr')
         ?.action(async (number, commandOptions) => {
@@ -224,6 +279,7 @@ function attachCommandActions(program, options) {
         .find((command) => command.name() === 'ls')
         ?.action(async (commandOptions) => {
         const exitCode = await runLsCommand({
+            compact: commandOptions.compact,
             cwd: options.cwd,
             json: commandOptions.json,
             stdout: options.stdout,
@@ -240,6 +296,7 @@ function attachCommandActions(program, options) {
             dryRun: commandOptions.dryRun,
             force: commandOptions.force,
             json: commandOptions.json,
+            stale: commandOptions.stale,
             stderr: options.stderr,
             stdout: options.stdout,
         });

package/dist/completion.d.ts

@@ -0,0 +1,6 @@
+export interface CompletionCommandOptions {
+    shell?: string;
+    stderr?: (chunk: string) => void;
+    stdout: (chunk: string) => void;
+}
+export declare function runCompletionCommand(options: CompletionCommandOptions): Promise<number>;

package/dist/completion.js

@@ -0,0 +1,11 @@
+import { renderShellCompletion } from './shell-completion.js';
+import { resolveSupportedShell } from './shell.js';
+export async function runCompletionCommand(options) {
+    const shell = resolveSupportedShell(options.shell, process.env.SHELL);
+    if (!shell) {
+        options.stderr?.('Unable to detect a supported shell. Specify one explicitly: bash, fish, or zsh.\n');
+        return 1;
+    }
+    options.stdout(renderShellCompletion(shell));
+    return 0;
+}

package/dist/git.d.ts

@@ -8,3 +8,6 @@ export interface WorktreeHealth {
 export declare function runGit(cwd: string, args: string[]): Promise<string>;
 export declare function readWorktreeHealth(cwd: string): Promise<WorktreeHealth>;
 export declare function isDirtyWorktree(cwd: string): Promise<boolean>;
+export declare function isBranchMergedInto(cwd: string, branch: string, base?: string): Promise<boolean>;
+export declare function resolveRemoteDefaultBranch(cwd: string, remote: string): Promise<string | null>;
+export declare function readBranchLastCommitTimestamp(cwd: string, branch: string): Promise<number | null>;

package/dist/git.js

@@ -19,6 +19,39 @@ export async function isDirtyWorktree(cwd) {
     const health = await readWorktreeHealth(cwd);
     return health.status === 'dirty';
 }
+export async function isBranchMergedInto(cwd, branch, base = 'HEAD') {
+    try {
+        await execFileAsync('git', ['merge-base', '--is-ancestor', branch, base], { cwd });
+        return true;
+    }
+    catch (error) {
+        if (hasExitCode(error, 1)) {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function resolveRemoteDefaultBranch(cwd, remote) {
+    const { stdout } = await execFileAsync('git', ['ls-remote', '--symref', remote, 'HEAD'], { cwd });
+    const refLine = stdout
+        .split('\n')
+        .find((line) => line.startsWith('ref: refs/heads/'));
+    if (!refLine) {
+        return null;
+    }
+    const match = /^ref: refs\/heads\/(.+)\tHEAD$/.exec(refLine);
+    return match?.[1] ?? null;
+}
+export async function readBranchLastCommitTimestamp(cwd, branch) {
+    try {
+        const { stdout } = await execFileAsync('git', ['log', '-1', '--format=%ct', branch], { cwd });
+        const timestamp = Number(stdout.trim());
+        return Number.isFinite(timestamp) ? timestamp : null;
+    }
+    catch {
+        return null;
+    }
+}
 function parseWorktreeHealth(output) {
     let ahead = 0;
     let behind = 0;
@@ -52,3 +85,8 @@ function parseWorktreeHealth(output) {
         status: dirty ? 'dirty' : 'clean',
     };
 }
+function hasExitCode(error, code) {
+    return error instanceof Error
+        && 'code' in error
+        && error.code === code;
+}

package/dist/gji

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import('./gji-bundle.mjs').catch(err => {
+  process.stderr.write(err.message + '\n');
+  process.exit(1);
+});