@solaqua/gji 0.4.1 → 0.6.0

package/README.md

@@ -107,6 +107,9 @@ gji completion fish > ~/.config/fish/completions/gji.fish
 # 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
 
@@ -117,6 +120,10 @@ gji status
 gji go feature/dark-mode
 gji go main
 
+# open any worktree in an editor (interactive picker)
+gji open
+gji open feature/dark-mode --editor code
+
 # clean up when done
 gji remove feature/dark-mode
 ```
@@ -234,8 +241,9 @@ path=$(gji root --print)
 
 | Command | Description |
 |---|---|
-| `gji new [branch] [--detached] [--json]` | create branch + worktree, cd in (validates branch name against Git rules) |
+| `gji new [branch] [--detached] [--open] [--editor <cli>] [--json]` | create branch + worktree, cd in (validates branch name against Git rules) |
 | `gji pr <ref> [--json]` | fetch PR ref, create worktree, cd in |
+| `gji open [branch] [--editor <cli>] [--save] [--workspace]` | open a 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 |
@@ -260,6 +268,7 @@ No setup required. Optional config lives in:
 | 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`) |
@@ -314,8 +323,8 @@ Run scripts automatically at key lifecycle moments:
 ```json
 {
   "hooks": {
-    "afterCreate": "pnpm install",
-    "afterEnter": "echo 'switched to {{branch}}'",
+    "afterCreate": ["pnpm", "install"],
+    "afterEnter": ["printf", "switched to %s\n", "{{branch}}"],
     "beforeRemove": "pnpm run cleanup"
   }
 }
@@ -329,6 +338,31 @@ Run scripts automatically at key lifecycle moments:
 
 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.
 
+Prefer argv-array hooks for simple commands:
+
+```json
+{
+  "hooks": {
+    "afterCreate": ["pnpm", "install"],
+    "afterEnter": ["printf", "switched to %s at %s\n", "{{branch}}", "{{path}}"]
+  }
+}
+```
+
+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:
+
+```json
+{
+  "hooks": {
+    "afterCreate": "pnpm install && printf 'ready: %s\n' \"$GJI_PATH\""
+  }
+}
+```
+
+Avoid unquoted template values in shell strings, such as `echo {{branch}}` or `cd {{path}}`.
+
 Hooks from all three config layers merge per key — different keys from different layers both apply, same key the higher-precedence layer wins:
 
 ```jsonc

package/dist/back.d.ts

@@ -0,0 +1,13 @@
+import { type HistoryEntry } from './history.js';
+export declare const BACK_OUTPUT_FILE_ENV = "GJI_BACK_OUTPUT_FILE";
+export interface BackCommandOptions {
+    cwd: string;
+    home?: string;
+    n?: number;
+    print?: boolean;
+    stderr: (chunk: string) => void;
+    stdout: (chunk: string) => void;
+}
+export declare function runBackCommand(options: BackCommandOptions): Promise<number>;
+export declare function formatHistoryList(history: HistoryEntry[], cwd: string): string;
+export declare function formatAge(timestamp: number): string;

package/dist/back.js

@@ -0,0 +1,74 @@
+import { access } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { loadEffectiveConfig } from './config.js';
+import { extractHooks, runHook } from './hooks.js';
+import { appendHistory, loadHistory } from './history.js';
+import { detectRepository } from './repo.js';
+import { writeShellOutput } from './shell-handoff.js';
+export const BACK_OUTPUT_FILE_ENV = 'GJI_BACK_OUTPUT_FILE';
+export async function runBackCommand(options) {
+    const history = await loadHistory(options.home);
+    const steps = options.n ?? 1;
+    if (steps < 1) {
+        options.stderr('gji back: step count must be at least 1\n');
+        return 1;
+    }
+    let found = 0;
+    let target;
+    for (const entry of history) {
+        if (entry.path === options.cwd)
+            continue;
+        try {
+            await access(entry.path);
+            found++;
+            if (found === steps) {
+                target = entry;
+                break;
+            }
+        }
+        catch {
+            // Path no longer exists — skip to the next entry
+        }
+    }
+    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");
+        return 1;
+    }
+    try {
+        const repository = await detectRepository(target.path);
+        const config = await loadEffectiveConfig(repository.repoRoot, options.home, options.stderr);
+        const hooks = extractHooks(config);
+        await runHook(hooks.afterEnter, target.path, { branch: target.branch ?? undefined, path: target.path, repo: basename(repository.repoRoot) }, options.stderr);
+    }
+    catch {
+        // 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);
+    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'];
+    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';
+}
+export function formatAge(timestamp) {
+    const seconds = Math.floor((Date.now() - timestamp) / 1000);
+    if (seconds < 60)
+        return 'just now';
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}

package/dist/cli.js

@@ -1,20 +1,26 @@
 import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import updateNotifier from 'update-notifier';
+import { runBackCommand } from './back.js';
 import { runCleanCommand } from './clean.js';
+import { runHistoryCommand } from './history-command.js';
 import { runCompletionCommand } from './completion.js';
 import { runConfigCommand } from './config-command.js';
 import { runGoCommand } from './go.js';
+import { runOpenCommand } from './open.js';
 import { isHeadless } from './headless.js';
 import { runInitCommand } from './init.js';
 import { runLsCommand } from './ls.js';
 import { runNewCommand } from './new.js';
 import { runPrCommand } from './pr.js';
 import { runRemoveCommand } from './remove.js';
+import { registerRepo } from './repo-registry.js';
+import { detectRepository } from './repo.js';
 import { runRootCommand } from './root.js';
 import { runStatusCommand } from './status.js';
 import { runSyncCommand } from './sync.js';
 import { runTriggerHookCommand } from './trigger-hook.js';
+import { runWarpCommand } from './warp.js';
 export function createProgram() {
     const program = new Command();
     const packageMetadata = readPackageMetadata();
@@ -37,6 +43,7 @@ function readPackageMetadata() {
 }
 export async function runCli(argv, options = {}) {
     await maybeNotifyForUpdates(argv);
+    maybeRegisterCurrentRepo(options.cwd ?? process.cwd());
     const program = createProgram();
     const cwd = options.cwd ?? process.cwd();
     const stdout = options.stdout ?? (() => undefined);
@@ -92,12 +99,19 @@ function defaultNotifyForUpdates(pkg) {
     const notifier = updateNotifier({ pkg });
     notifier.notify();
 }
+function maybeRegisterCurrentRepo(cwd) {
+    detectRepository(cwd)
+        .then(({ repoRoot }) => registerRepo(repoRoot))
+        .catch(() => undefined);
+}
 function registerCommands(program) {
     program
         .command('new [branch]')
         .description('create a new branch or detached linked worktree')
         .option('-f, --force', 'remove and recreate the worktree if the target path already exists')
         .option('--detached', 'create a detached worktree without a branch')
+        .option('--open', 'open the new worktree in an editor after creation')
+        .option('--editor <cli>', 'editor CLI to use with --open (code, cursor, zed, …)')
         .option('--dry-run', 'show what would be created without executing any git commands or writing files')
         .option('--json', 'emit JSON on success or error instead of human-readable output')
         .action(notImplemented('new'));
@@ -116,8 +130,26 @@ function registerCommands(program) {
         .option('--dry-run', 'show what would be created without executing any git commands or writing files')
         .option('--json', 'emit JSON on success or error instead of human-readable output')
         .action(notImplemented('pr'));
+    program
+        .command('back [n]')
+        .description('navigate to the previously visited worktree, optionally N steps back')
+        .option('--print', 'print the resolved worktree path explicitly')
+        .action(notImplemented('back'));
+    program
+        .command('history')
+        .description('show navigation history')
+        .option('--json', 'print history as JSON')
+        .action(notImplemented('history'));
+    program
+        .command('open [branch]')
+        .description('open the worktree in an editor')
+        .option('--editor <cli>', 'editor CLI to use (code, cursor, zed, windsurf, subl, …)')
+        .option('--save', 'save the chosen editor to global config')
+        .option('--workspace', 'generate a .code-workspace file before opening (VS Code / Cursor / Windsurf)')
+        .action(notImplemented('open'));
     program
         .command('go [branch]')
+        .alias('jump')
         .description('print or select a worktree path')
         .option('--print', 'print the resolved worktree path explicitly')
         .action(notImplemented('go'));
@@ -163,6 +195,15 @@ function registerCommands(program) {
         .command('trigger-hook <hook>')
         .description('run a named hook (afterCreate, afterEnter, beforeRemove) in the current worktree')
         .action(notImplemented('trigger-hook'));
+    program
+        .command('warp [branch]')
+        .description('jump to any worktree across all known repos')
+        .option('-n, --new [branch]', 'create a new worktree in a registered repo')
+        // --print is the shell-wrapper bypass signal (see SHELL_WRAPPED_COMMANDS in init.ts).
+        // The shell omits GJI_WARP_OUTPUT_FILE, so writeShellOutput falls through to stdout.
+        .option('--print', 'print the resolved worktree path without changing directory')
+        .option('--json', 'emit JSON on success or error instead of human-readable output')
+        .action(notImplemented('warp'));
     const configCommand = program
         .command('config')
         .description('manage global config defaults')
@@ -184,7 +225,7 @@ function attachCommandActions(program, options) {
     program.commands
         .find((command) => command.name() === 'new')
         ?.action(async (branch, commandOptions) => {
-        const exitCode = await runNewCommand({ ...options, branch, detached: commandOptions.detached, dryRun: commandOptions.dryRun, force: commandOptions.force, json: commandOptions.json });
+        const exitCode = await runNewCommand({ ...options, branch, detached: commandOptions.detached, dryRun: commandOptions.dryRun, editor: commandOptions.editor, force: commandOptions.force, json: commandOptions.json, open: commandOptions.open });
         if (exitCode !== 0) {
             throw commanderExit(exitCode);
         }
@@ -223,6 +264,53 @@ function attachCommandActions(program, options) {
             throw commanderExit(exitCode);
         }
     });
+    program.commands
+        .find((command) => command.name() === 'back')
+        ?.action(async (n, commandOptions) => {
+        if (n !== undefined && !/^\d+$/.test(n)) {
+            options.stderr(`gji back: invalid step count: ${n}\n`);
+            throw commanderExit(1);
+        }
+        const steps = n !== undefined ? parseInt(n, 10) : undefined;
+        const exitCode = await runBackCommand({
+            cwd: options.cwd,
+            n: steps,
+            print: commandOptions.print,
+            stderr: options.stderr,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    program.commands
+        .find((command) => command.name() === 'history')
+        ?.action(async (commandOptions) => {
+        const exitCode = await runHistoryCommand({
+            cwd: options.cwd,
+            json: commandOptions.json,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    program.commands
+        .find((command) => command.name() === 'open')
+        ?.action(async (branch, commandOptions) => {
+        const exitCode = await runOpenCommand({
+            branch,
+            cwd: options.cwd,
+            editor: commandOptions.editor,
+            save: commandOptions.save,
+            stderr: options.stderr,
+            stdout: options.stdout,
+            workspace: commandOptions.workspace,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
     program.commands
         .find((command) => command.name() === 'go')
         ?.action(async (branch, commandOptions) => {
@@ -333,6 +421,24 @@ function attachCommandActions(program, options) {
             throw commanderExit(exitCode);
         }
     });
+    program.commands
+        .find((command) => command.name() === 'warp')
+        ?.action(async (branch, commandOptions) => {
+        const newFlag = commandOptions.new;
+        const newWorktree = newFlag !== undefined && newFlag !== false;
+        const newBranch = typeof newFlag === 'string' ? newFlag : undefined;
+        const exitCode = await runWarpCommand({
+            branch: newWorktree ? (newBranch ?? branch) : branch,
+            cwd: options.cwd,
+            json: commandOptions.json,
+            newWorktree,
+            stderr: options.stderr,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
     const configCommand = program.commands.find((command) => command.name() === 'config');
     configCommand?.action(async () => {
         const exitCode = await runConfigCommand({

package/dist/config.js

@@ -6,6 +6,7 @@ export const GLOBAL_CONFIG_DIRECTORY = '.config/gji';
 export const GLOBAL_CONFIG_NAME = 'config.json';
 export const KNOWN_CONFIG_KEYS = new Set([
     'branchPrefix',
+    'editor',
     'hooks',
     'installSaveTarget',
     'shellIntegration',

package/dist/editor.d.ts

@@ -0,0 +1,8 @@
+export interface EditorDefinition {
+    cli: string;
+    name: string;
+    newWindowFlag?: string;
+    supportsWorkspace: boolean;
+}
+export declare const EDITORS: EditorDefinition[];
+export declare function defaultSpawnEditor(cli: string, args: string[]): Promise<void>;

package/dist/editor.js

@@ -0,0 +1,17 @@
+import { spawn } from 'node:child_process';
+// Ordered by likely popularity among the target audience.
+export const EDITORS = [
+    { cli: 'cursor', name: 'Cursor', newWindowFlag: '--new-window', supportsWorkspace: true },
+    { cli: 'code', name: 'VS Code', newWindowFlag: '--new-window', supportsWorkspace: true },
+    { cli: 'windsurf', name: 'Windsurf', newWindowFlag: '--new-window', supportsWorkspace: true },
+    { cli: 'zed', name: 'Zed', supportsWorkspace: false },
+    { cli: 'subl', name: 'Sublime Text', newWindowFlag: '--new-window', supportsWorkspace: false },
+];
+export async function defaultSpawnEditor(cli, args) {
+    const child = spawn(cli, args, { detached: true, stdio: 'ignore' });
+    await new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('spawn', resolve);
+    });
+    child.unref();
+}