@solaqua/gji 0.8.1 → 0.10.0

package/README.md

@@ -9,6 +9,7 @@ That matters even more in AI-assisted workflows, where one repository often has
 ```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
 ```
@@ -69,36 +70,18 @@ That makes Git worktrees more important, because a single shared checkout become
 npm install -g @solaqua/gji
 ```
 
-Then add shell integration so `gji go`, `gji new`, and `gji remove` can change your directory:
+Then run the guided setup in an interactive terminal:
 
 ```sh
-# zsh
-echo 'eval "$(gji init zsh)"' >> ~/.zshrc
-
-# bash
-echo 'eval "$(gji init bash)"' >> ~/.bashrc
-
-# fish
-gji init fish --write
-source ~/.config/fish/config.fish
+gji init
+# restart your shell, or source the rc file shown by the wizard
+gji doctor
 ```
 
-Install completions as separate files:
+The wizard installs shell integration, completions, and an available editor. In a non-interactive environment, use the existing explicit shell command instead:
 
 ```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
+gji init zsh --write
 ```
 
 ## Quick start
@@ -112,6 +95,10 @@ 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
@@ -120,8 +107,9 @@ gji status
 gji go feature/dark-mode
 gji go main
 
-# open any worktree in an editor (interactive picker)
+# 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
@@ -140,6 +128,7 @@ Set `worktreePath` in your config to use a different base (e.g. `"~/worktrees"`
 
 ```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
@@ -178,13 +167,14 @@ See the full comparison in [website/docs/comparison.mdx](./website/docs/comparis
 
 ## 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:
+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:
 
 ```sh
-gji init zsh   # prints the shell function, review it if you like
+gji init
+gji doctor
 ```
 
-Install the wrapper once:
+`gji init` is interactive. For dotfiles or CI, the explicit shell commands remain available and preserve their existing output:
 
 ```sh
 # zsh
@@ -241,9 +231,10 @@ path=$(gji root --print)
 
 | Command | Description |
 |---|---|
-| `gji new [branch] [--detached] [--open] [--editor <cli>] [--json]` | create branch + worktree, cd in (validates branch name against Git rules) |
+| `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 open [branch] [--editor <cli>] [--save] [--workspace]` | open a worktree in an editor |
+| `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 |
@@ -254,7 +245,8 @@ path=$(gji root --print)
 | `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 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
@@ -275,7 +267,7 @@ No setup required. Optional config lives in:
 | `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 once during `gji init --write` |
+| `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) |
 
@@ -477,7 +469,10 @@ 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 `--force`. `--json` implies the same behaviour.
+`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`.
 
@@ -486,6 +481,7 @@ Update notifications are also suppressed automatically in non-interactive and `-
 - 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
 
 ## License
 

package/dist/browser.d.ts

@@ -0,0 +1,7 @@
+export type BrowserCommandRunner = (command: string, args: string[]) => Promise<void>;
+export interface BrowserOpenerDependencies {
+    platform?: NodeJS.Platform;
+    runCommand?: BrowserCommandRunner;
+}
+export declare function createBrowserOpener(dependencies?: BrowserOpenerDependencies): (url: string) => Promise<void>;
+export declare const openBrowser: (url: string) => Promise<void>;

package/dist/browser.js

@@ -0,0 +1,37 @@
+import { execFile } from "node:child_process";
+import { platform } from "node:process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export function createBrowserOpener(dependencies = {}) {
+    const currentPlatform = dependencies.platform ?? platform;
+    const runCommand = dependencies.runCommand ?? defaultRunCommand;
+    return async function openBrowser(url) {
+        validateBrowserUrl(url);
+        const command = browserCommand(currentPlatform, url);
+        await runCommand(command.command, command.args);
+    };
+}
+export const openBrowser = createBrowserOpener();
+function browserCommand(currentPlatform, url) {
+    if (currentPlatform === "darwin")
+        return { args: [url], command: "open" };
+    if (currentPlatform === "win32") {
+        return { args: [url], command: "explorer.exe" };
+    }
+    return { args: [url], command: "xdg-open" };
+}
+function validateBrowserUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error("browser URL is invalid");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("browser URL must use http or https");
+    }
+}
+async function defaultRunCommand(command, args) {
+    await execFileAsync(command, args, { timeout: 10_000 });
+}

package/dist/cli.d.ts

@@ -1,6 +1,8 @@
 import { Command } from "commander";
+import { type PrOpenCommandDependencies } from "./pr-open.js";
 export interface RunCliOptions {
     cwd?: string;
+    prOpenDependencies?: Partial<PrOpenCommandDependencies>;
     stderr?: (chunk: string) => void;
     stdout?: (chunk: string) => void;
 }

package/dist/cli.js

@@ -5,6 +5,7 @@ import { runBackCommand } from "./back.js";
 import { runCleanCommand } from "./clean.js";
 import { runCompletionCommand } from "./completion.js";
 import { runConfigCommand } from "./config-command.js";
+import { runDoctorCommand } from "./doctor.js";
 import { runGoCommand } from "./go.js";
 import { isHeadless } from "./headless.js";
 import { runHistoryCommand } from "./history-command.js";
@@ -13,6 +14,7 @@ import { runLsCommand } from "./ls.js";
 import { runNewCommand } from "./new.js";
 import { runOpenCommand } from "./open.js";
 import { runPrCommand } from "./pr.js";
+import { createPrOpenCommand, } from "./pr-open.js";
 import { runRemoveCommand } from "./remove.js";
 import { detectRepository } from "./repo.js";
 import { registerRepo } from "./repo-registry.js";
@@ -44,7 +46,9 @@ function readPackageMetadata() {
 }
 export async function runCli(argv, options = {}) {
     await maybeNotifyForUpdates(argv);
-    maybeRegisterCurrentRepo(options.cwd ?? process.cwd());
+    if (argv[0] !== "doctor") {
+        maybeRegisterCurrentRepo(options.cwd ?? process.cwd());
+    }
     const program = createProgram();
     const cwd = options.cwd ?? process.cwd();
     const stdout = options.stdout ?? (() => undefined);
@@ -59,7 +63,12 @@ export async function runCli(argv, options = {}) {
         return { exitCode: 0 };
     }
     try {
-        attachCommandActions(program, { cwd, stderr, stdout });
+        attachCommandActions(program, {
+            cwd,
+            prOpenDependencies: options.prOpenDependencies,
+            stderr,
+            stdout,
+        });
         await program.parseAsync(["node", "gji", ...argv], { from: "node" });
         return { exitCode: 0 };
     }
@@ -111,6 +120,7 @@ function registerCommands(program) {
         .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("--from-current", "base the new branch on the current worktree instead of the main worktree (cannot be combined with --detached)")
         .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")
@@ -118,19 +128,33 @@ function registerCommands(program) {
         .action(notImplemented("new"));
     program
         .command("init [shell]")
-        .description("print or install shell integration")
+        .description("set up shell integration interactively or print a shell wrapper")
         .option("--write", "write the integration to the shell config file")
+        .option("--json", "emit a JSON error in non-interactive mode")
         .action(notImplemented("init"));
+    program
+        .command("doctor")
+        .description("check gji installation and configuration health")
+        .option("--fix", "apply safe automatic fixes after showing the plan")
+        .option("--yes", "apply --fix without prompting")
+        .option("--json", "emit diagnostic checks as JSON")
+        .action(notImplemented("doctor"));
     program
         .command("completion [shell]")
         .description("print shell completion definitions")
         .action(notImplemented("completion"));
-    program
+    const prCommand = program
         .command("pr <ref>")
+        .usage("[options] <ref>")
         .description("fetch a pull request by number, #number, or URL into a linked worktree")
         .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"));
+    prCommand
+        .command("open [target]")
+        .description("open an existing pull request in the default browser")
+        .option("--select", "choose a pull request from any linked worktree")
+        .action(notImplemented("pr open"));
     program
         .command("back [n]")
         .description("navigate to the previously visited worktree, optionally N steps back")
@@ -144,6 +168,7 @@ function registerCommands(program) {
     program
         .command("open [branch]")
         .description("open the worktree in an editor")
+        .option("--select", "choose a worktree with the interactive selector")
         .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)")
@@ -254,6 +279,7 @@ function attachCommandActions(program, options) {
             detached: commandOptions.detached,
             dryRun: commandOptions.dryRun,
             editor: commandOptions.editor,
+            fromCurrent: commandOptions.fromCurrent,
             force: commandOptions.force,
             json: commandOptions.json,
             open: commandOptions.open,
@@ -267,6 +293,7 @@ function attachCommandActions(program, options) {
         ?.action(async (shell, commandOptions) => {
         const exitCode = await runInitCommand({
             cwd: options.cwd,
+            json: commandOptions.json,
             shell,
             stderr: options.stderr,
             stdout: options.stdout,
@@ -276,6 +303,21 @@ function attachCommandActions(program, options) {
             throw commanderExit(exitCode);
         }
     });
+    program.commands
+        .find((command) => command.name() === "doctor")
+        ?.action(async (commandOptions) => {
+        const exitCode = await runDoctorCommand({
+            cwd: options.cwd,
+            fix: commandOptions.fix,
+            json: commandOptions.json,
+            stderr: options.stderr,
+            stdout: options.stdout,
+            yes: commandOptions.yes,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
     program.commands
         .find((command) => command.name() === "completion")
         ?.action(async (shell) => {
@@ -303,6 +345,22 @@ function attachCommandActions(program, options) {
             throw commanderExit(exitCode);
         }
     });
+    const prOpenCommand = program.commands
+        .find((command) => command.name() === "pr")
+        ?.commands.find((command) => command.name() === "open");
+    const runPrOpenCommand = createPrOpenCommand(options.prOpenDependencies);
+    prOpenCommand?.action(async (target, commandOptions) => {
+        const exitCode = await runPrOpenCommand({
+            cwd: options.cwd,
+            stderr: options.stderr,
+            stdout: options.stdout,
+            select: commandOptions.select,
+            target,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
     program.commands
         .find((command) => command.name() === "back")
         ?.action(async (n, commandOptions) => {
@@ -342,6 +400,7 @@ function attachCommandActions(program, options) {
             cwd: options.cwd,
             editor: commandOptions.editor,
             save: commandOptions.save,
+            select: commandOptions.select,
             stderr: options.stderr,
             stdout: options.stdout,
             workspace: commandOptions.workspace,

package/dist/doctor.d.ts

@@ -0,0 +1,28 @@
+export type DoctorCheckStatus = "fail" | "ok" | "skip";
+export interface DoctorCheck {
+    hint?: string;
+    id: string;
+    message: string;
+    status: DoctorCheckStatus;
+}
+export type DoctorFixStatus = "applied" | "declined" | "failed" | "pending" | "skipped";
+export interface DoctorFix {
+    hint?: string;
+    id: string;
+    message: string;
+    paths?: string[];
+    status: DoctorFixStatus;
+}
+export interface DoctorCommandOptions {
+    cwd: string;
+    home?: string;
+    fix?: boolean;
+    json?: boolean;
+    interactive?: boolean;
+    confirmFixes?: (fixes: DoctorFix[]) => Promise<boolean>;
+    shell?: string;
+    yes?: boolean;
+    stderr?: (chunk: string) => void;
+    stdout: (chunk: string) => void;
+}
+export declare function runDoctorCommand(options: DoctorCommandOptions): Promise<number>;