@solaqua/gji 0.4.1 → 0.6.0

package/dist/repo-registry.js

@@ -0,0 +1,52 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { GLOBAL_CONFIG_DIRECTORY } from './config.js';
+const REGISTRY_FILE_NAME = 'repos.json';
+const MAX_REGISTRY_ENTRIES = 100;
+export function REGISTRY_FILE_PATH(home = homedir()) {
+    const configDir = process.env.GJI_CONFIG_DIR;
+    if (configDir) {
+        return join(resolve(configDir), REGISTRY_FILE_NAME);
+    }
+    return join(home, GLOBAL_CONFIG_DIRECTORY, REGISTRY_FILE_NAME);
+}
+export async function loadRegistry(home = homedir()) {
+    const path = REGISTRY_FILE_PATH(home);
+    try {
+        const raw = await readFile(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter(isRegistryEntry);
+    }
+    catch {
+        return [];
+    }
+}
+export async function registerRepo(repoPath, home = homedir()) {
+    const registryPath = REGISTRY_FILE_PATH(home);
+    const existing = await loadRegistry(home);
+    // Skip write if this repo is already the most-recently-used entry (common case).
+    if (existing.length > 0 && existing[0].path === repoPath)
+        return;
+    const entry = {
+        lastUsed: Date.now(),
+        name: basename(repoPath),
+        path: repoPath,
+    };
+    const filtered = existing.filter((e) => e.path !== repoPath);
+    const next = [entry, ...filtered].slice(0, MAX_REGISTRY_ENTRIES);
+    await mkdir(dirname(registryPath), { recursive: true });
+    await writeFile(registryPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+}
+function isRegistryEntry(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'path' in value &&
+        typeof value.path === 'string' &&
+        'name' in value &&
+        typeof value.name === 'string' &&
+        'lastUsed' in value &&
+        typeof value.lastUsed === 'number');
+}

package/dist/warp.d.ts

@@ -0,0 +1,20 @@
+export interface WarpCommandOptions {
+    branch?: string;
+    cwd: string;
+    json?: boolean;
+    newWorktree?: boolean;
+    stderr: (chunk: string) => void;
+    stdout: (chunk: string) => void;
+}
+export declare function runWarpCommand(options: WarpCommandOptions): Promise<number>;
+export interface WarpTarget {
+    branch: string | null;
+    path: string;
+}
+export declare function resolveWarpTarget(options: {
+    branch?: string;
+    commandName?: string;
+    cwd: string;
+    json?: boolean;
+    stderr: (chunk: string) => void;
+}): Promise<WarpTarget | null>;

package/dist/warp.js

@@ -0,0 +1,196 @@
+import { isCancel, select } from '@clack/prompts';
+import { readWorktreeHealth } from './git.js';
+import { isHeadless } from './headless.js';
+import { appendHistory } from './history.js';
+import { runNewCommand } from './new.js';
+import { loadRegistry } from './repo-registry.js';
+import { listWorktrees } from './repo.js';
+import { writeShellOutput } from './shell-handoff.js';
+const WARP_OUTPUT_FILE_ENV = 'GJI_WARP_OUTPUT_FILE';
+export async function runWarpCommand(options) {
+    if (options.newWorktree) {
+        const registry = await loadRegistry();
+        if (registry.length === 0) {
+            options.stderr('gji warp: no repos registered yet.\n' +
+                'Use any gji command in a repository to register it automatically.\n');
+            return 1;
+        }
+        return runWarpNew(options, registry);
+    }
+    return runWarpNavigate(options);
+}
+async function runWarpNavigate(options) {
+    if ((isHeadless() || options.json) && !options.branch) {
+        const message = 'branch argument is required';
+        if (options.json) {
+            options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
+        }
+        else {
+            options.stderr('gji warp: branch argument is required in non-interactive mode (GJI_NO_TUI=1)\n');
+        }
+        return 1;
+    }
+    const target = await resolveWarpTarget({ ...options, commandName: 'gji warp', json: options.json });
+    if (!target)
+        return 1;
+    if (options.json) {
+        // json callers use the output programmatically; skip history and shell handoff.
+        options.stdout(`${JSON.stringify({ branch: target.branch, path: target.path }, null, 2)}\n`);
+        return 0;
+    }
+    appendHistory(target.path, target.branch).catch(() => undefined);
+    await writeShellOutput(WARP_OUTPUT_FILE_ENV, target.path, options.stdout);
+    return 0;
+}
+async function runWarpNew(options, registry) {
+    let targetRepoRoot;
+    if (registry.length === 1) {
+        targetRepoRoot = registry[0].path;
+    }
+    else {
+        if (isHeadless()) {
+            options.stderr('gji warp: repo argument is required in non-interactive mode (GJI_NO_TUI=1)\n');
+            return 1;
+        }
+        const choice = await select({
+            message: 'Create worktree in which repo?',
+            options: registry.map((entry) => ({
+                value: entry.path,
+                label: entry.name,
+                hint: entry.path,
+            })),
+        });
+        if (isCancel(choice)) {
+            options.stderr('Aborted\n');
+            return 1;
+        }
+        targetRepoRoot = choice;
+    }
+    if (options.json) {
+        return runNewCommand({
+            branch: options.branch,
+            cwd: targetRepoRoot,
+            json: true,
+            stderr: options.stderr,
+            stdout: options.stdout,
+        });
+    }
+    // runNewCommand writes the created path to options.stdout via writeShellOutput.
+    // Since GJI_NEW_OUTPUT_FILE is not set in the warp shell context, it falls
+    // through to our captured stdout, giving us the path to hand off.
+    let capturedPath = '';
+    const captureStdout = (chunk) => {
+        capturedPath = chunk.trim();
+    };
+    const exitCode = await runNewCommand({
+        branch: options.branch,
+        cwd: targetRepoRoot,
+        stderr: options.stderr,
+        stdout: captureStdout,
+    });
+    if (exitCode !== 0) {
+        return exitCode;
+    }
+    if (!capturedPath) {
+        options.stderr('gji warp: could not determine new worktree path\n');
+        return 1;
+    }
+    await writeShellOutput(WARP_OUTPUT_FILE_ENV, capturedPath, options.stdout);
+    return 0;
+}
+function findByQuery(items, query) {
+    const slashIdx = query.indexOf('/');
+    if (slashIdx !== -1) {
+        const repoQuery = query.slice(0, slashIdx);
+        const branchQuery = query.slice(slashIdx + 1);
+        const match = items.find((item) => item.repoName === repoQuery && item.worktree.branch === branchQuery);
+        if (match)
+            return match;
+    }
+    return items.find((item) => item.worktree.branch === query) ?? null;
+}
+export async function resolveWarpTarget(options) {
+    const cmd = options.commandName ?? 'gji';
+    const emitError = (message, hint) => {
+        if (options.json) {
+            options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
+        }
+        else {
+            options.stderr(`${cmd}: ${message}\n`);
+            if (hint)
+                options.stderr(hint);
+        }
+    };
+    const registry = await loadRegistry();
+    if (registry.length === 0) {
+        emitError('not in a git repository and no repos registered yet.', 'Use any gji command inside a repository to register it.\n');
+        return null;
+    }
+    const results = await Promise.allSettled(registry.map(async (entry) => {
+        const worktrees = await listWorktrees(entry.path);
+        return { repoName: entry.name, worktrees };
+    }));
+    const allItems = [];
+    for (const result of results) {
+        if (result.status === 'rejected')
+            continue;
+        const { repoName, worktrees } = result.value;
+        for (const worktree of worktrees) {
+            allItems.push({ repoName, worktree });
+        }
+    }
+    if (allItems.length === 0) {
+        emitError('no accessible worktrees found in any registered repo.');
+        return null;
+    }
+    if (options.branch) {
+        const match = findByQuery(allItems, options.branch);
+        if (!match) {
+            emitError(`no worktree found matching: ${options.branch}`);
+            return null;
+        }
+        return { branch: match.worktree.branch, path: match.worktree.path };
+    }
+    const path = await promptForWarpTarget(allItems);
+    if (!path) {
+        options.stderr('Aborted\n');
+        return null;
+    }
+    const chosen = allItems.find((item) => item.worktree.path === path);
+    return { branch: chosen?.worktree.branch ?? null, path };
+}
+async function promptForWarpTarget(items) {
+    const healthResults = await Promise.allSettled(items.map((item) => readWorktreeHealth(item.worktree.path)));
+    const choice = await select({
+        message: 'Warp to a worktree',
+        options: items.map((item, i) => {
+            const health = healthResults[i].status === 'fulfilled' ? healthResults[i].value : null;
+            const upstream = health ? formatHint(item.worktree.branch, health) : null;
+            const label = `${item.repoName} › ${item.worktree.branch ?? '(detached)'}`;
+            const pathHint = item.worktree.isCurrent
+                ? `${item.worktree.path} (current)`
+                : item.worktree.path;
+            const hint = upstream ? `${upstream} · ${pathHint}` : pathHint;
+            return { hint, label, value: item.worktree.path };
+        }),
+    });
+    if (isCancel(choice)) {
+        return null;
+    }
+    return choice;
+}
+function formatHint(branch, health) {
+    if (branch === null)
+        return null;
+    if (!health.hasUpstream)
+        return 'no upstream';
+    if (health.upstreamGone)
+        return 'upstream gone';
+    if (health.ahead === 0 && health.behind === 0)
+        return 'up to date';
+    if (health.ahead === 0)
+        return `behind ${health.behind}`;
+    if (health.behind === 0)
+        return `ahead ${health.ahead}`;
+    return `ahead ${health.ahead}, behind ${health.behind}`;
+}

package/man/man1/gji-back.1

@@ -0,0 +1,13 @@
+.TH GJI\-BACK 1 "May 2026" "gji 0.6.0" "User Commands"
+.SH NAME
+gji\-back \- navigate to the previously visited worktree, optionally N steps back
+.SH SYNOPSIS
+.B gji back [\fIoptions\fR] [options] [n]
+.SH DESCRIPTION
+navigate to the previously visited worktree, optionally N steps back
+.SH OPTIONS
+.TP
+.B \-\-print
+print the resolved worktree path explicitly
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-clean.1

@@ -1,4 +1,4 @@
-.TH GJI\-CLEAN 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI\-CLEAN 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji\-clean \- interactively prune linked worktrees
 .SH SYNOPSIS

package/man/man1/gji-completion.1

@@ -1,4 +1,4 @@
-.TH GJI\-COMPLETION 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI\-COMPLETION 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji\-completion \- print shell completion definitions
 .SH SYNOPSIS

package/man/man1/gji-config.1

@@ -1,4 +1,4 @@
-.TH GJI\-CONFIG 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI\-CONFIG 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji\-config \- manage global config defaults
 .SH SYNOPSIS

package/man/man1/gji-go.1

@@ -1,4 +1,4 @@
-.TH GJI\-GO 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI\-GO 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji\-go \- print or select a worktree path
 .SH SYNOPSIS

package/man/man1/gji-history.1

@@ -0,0 +1,13 @@
+.TH GJI\-HISTORY 1 "May 2026" "gji 0.6.0" "User Commands"
+.SH NAME
+gji\-history \- show navigation history
+.SH SYNOPSIS
+.B gji history [\fIoptions\fR] [options]
+.SH DESCRIPTION
+show navigation history
+.SH OPTIONS
+.TP
+.B \-\-json
+print history as JSON
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-init.1

@@ -1,4 +1,4 @@
-.TH GJI\-INIT 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI\-INIT 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji\-init \- print or install shell integration
 .SH SYNOPSIS

package/man/man1/gji-ls.1

@@ -1,4 +1,4 @@
-.TH GJI\-LS 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI\-LS 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji\-ls \- list active worktrees
 .SH SYNOPSIS

package/man/man1/gji-new.1

@@ -1,4 +1,4 @@
-.TH GJI\-NEW 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI\-NEW 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji\-new \- create a new branch or detached linked worktree
 .SH SYNOPSIS
@@ -13,6 +13,12 @@ remove and recreate the worktree if the target path already exists
 .B \-\-detached
 create a detached worktree without a branch
 .TP
+.B \-\-open
+open the new worktree in an editor after creation
+.TP
+.B \-\-editor <cli>
+editor CLI to use with \-\-open (code, cursor, zed, …)
+.TP
 .B \-\-dry\-run
 show what would be created without executing any git commands or writing files
 .TP

package/man/man1/gji-open.1

@@ -0,0 +1,19 @@
+.TH GJI\-OPEN 1 "May 2026" "gji 0.6.0" "User Commands"
+.SH NAME
+gji\-open \- open the worktree in an editor
+.SH SYNOPSIS
+.B gji open [\fIoptions\fR] [options] [branch]
+.SH DESCRIPTION
+open the worktree in an editor
+.SH OPTIONS
+.TP
+.B \-\-editor <cli>
+editor CLI to use (code, cursor, zed, windsurf, subl, …)
+.TP
+.B \-\-save
+save the chosen editor to global config
+.TP
+.B \-\-workspace
+generate a .code\-workspace file before opening (VS Code / Cursor / Windsurf)
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-pr.1

@@ -1,4 +1,4 @@
-.TH GJI\-PR 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI\-PR 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji\-pr \- fetch a pull request by number, #number, or URL into a linked worktree
 .SH SYNOPSIS

package/man/man1/gji-remove.1

@@ -1,4 +1,4 @@
-.TH GJI\-REMOVE 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI\-REMOVE 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji\-remove \- remove a linked worktree and delete its branch when present
 .SH SYNOPSIS

package/man/man1/gji-root.1

@@ -1,4 +1,4 @@
-.TH GJI\-ROOT 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI\-ROOT 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji\-root \- print the main repository root path
 .SH SYNOPSIS

package/man/man1/gji-status.1

@@ -1,4 +1,4 @@
-.TH GJI\-STATUS 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI\-STATUS 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji\-status \- summarize repository and worktree health
 .SH SYNOPSIS

package/man/man1/gji-sync.1

@@ -1,4 +1,4 @@
-.TH GJI\-SYNC 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI\-SYNC 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji\-sync \- fetch and update one or all worktrees
 .SH SYNOPSIS

package/man/man1/gji-trigger-hook.1

@@ -1,4 +1,4 @@
-.TH GJI\-TRIGGER\-HOOK 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI\-TRIGGER\-HOOK 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji\-trigger\-hook \- run a named hook (afterCreate, afterEnter, beforeRemove) in the current worktree
 .SH SYNOPSIS

package/man/man1/gji-warp.1

@@ -0,0 +1,19 @@
+.TH GJI\-WARP 1 "May 2026" "gji 0.6.0" "User Commands"
+.SH NAME
+gji\-warp \- jump to any worktree across all known repos
+.SH SYNOPSIS
+.B gji warp [\fIoptions\fR] [options] [branch]
+.SH DESCRIPTION
+jump to any worktree across all known repos
+.SH OPTIONS
+.TP
+.B \-n, \-\-new [branch]
+create a new worktree in a registered repo
+.TP
+.B \-\-print
+print the resolved worktree path without changing directory
+.TP
+.B \-\-json
+emit JSON on success or error instead of human\-readable output
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji.1

@@ -1,4 +1,4 @@
-.TH GJI 1 "May 2026" "gji 0.4.1" "User Commands"
+.TH GJI 1 "May 2026" "gji 0.6.0" "User Commands"
 .SH NAME
 gji \- Context switching without the mess.
 .SH SYNOPSIS
@@ -23,8 +23,19 @@ print shell completion definitions
 .B pr [options] <ref>
 fetch a pull request by number, #number, or URL into a linked worktree
 .TP
+.B back [options] [n]
+navigate to the previously visited worktree, optionally N steps back
+.TP
+.B history [options]
+show navigation history
+.TP
+.B open [options] [branch]
+open the worktree in an editor
+.TP
 .B go [options] [branch]
 print or select a worktree path
+.br
+Alias: \fBjump\fR
 .TP
 .B root [options]
 print the main repository root path
@@ -49,6 +60,9 @@ Alias: \fBrm\fR
 .B trigger\-hook [options] <hook>
 run a named hook (afterCreate, afterEnter, beforeRemove) in the current worktree
 .TP
+.B warp [options] [branch]
+jump to any worktree across all known repos
+.TP
 .B config [options] [command]
 manage global config defaults
 .SH OPTIONS
@@ -60,6 +74,9 @@ output the version number
 .BR gji\-init (1),
 .BR gji\-completion (1),
 .BR gji\-pr (1),
+.BR gji\-back (1),
+.BR gji\-history (1),
+.BR gji\-open (1),
 .BR gji\-go (1),
 .BR gji\-root (1),
 .BR gji\-status (1),
@@ -68,4 +85,5 @@ output the version number
 .BR gji\-clean (1),
 .BR gji\-remove (1),
 .BR gji\-trigger\-hook (1),
+.BR gji\-warp (1),
 .BR gji\-config (1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solaqua/gji",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Git worktree CLI for fast context switching.",
   "license": "MIT",
   "author": "sjquant",
@@ -64,6 +64,8 @@
     "vitest": "^3.2.4"
   },
   "pnpm": {
-    "onlyBuiltDependencies": ["esbuild"]
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }