@solaqua/gji 0.8.0 → 0.9.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
@@ -178,13 +165,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
@@ -243,6 +231,7 @@ path=$(gji root --print)
 |---|---|
 | `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 pr open [branch|#N] [--select]` | open the current worktree PR, or choose a linked worktree with `--select` |
 | `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 |
@@ -254,7 +243,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 +265,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 +467,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 +479,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/clean.js

@@ -3,7 +3,7 @@ import { loadEffectiveConfig } from "./config.js";
 import { isBranchMergedInto, readWorktreeHealth, resolveRemoteDefaultBranch, runGit, } from "./git.js";
 import { isHeadless } from "./headless.js";
 import { formatLastCommit, formatUpstreamState, readWorktreeInfos, serializeWorktreeInfo, } from "./worktree-info.js";
-import { deleteBranch, forceDeleteBranch, forceRemoveWorktree, isBranchUnmergedError, isWorktreeDirtyError, loadLinkedWorktrees, removeWorktree, } from "./worktree-management.js";
+import { deleteBranch, forceDeleteBranch, forceRemoveWorktree, isBranchUnmergedError, isWorktreeDeletionError, isWorktreeForceRemovalError, loadLinkedWorktrees, removeWorktree, } from "./worktree-management.js";
 import { buildWorktreePromptEntries, promptForMultipleWorktrees, } from "./worktree-picker.js";
 import { defaultConfirmForceDeleteBranch, defaultConfirmForceRemoveWorktree, } from "./worktree-prompts.js";
 export function createCleanCommand(dependencies = {}) {
@@ -77,8 +77,8 @@ export function createCleanCommand(dependencies = {}) {
             }
             return 0;
         }
-        const removedPaths = [];
         const removedWorktrees = [];
+        const failures = [];
         for (const worktree of selectedWorktrees) {
             if (options.stale &&
                 !(await isStaleCleanupCandidate(repository.repoRoot, worktree, staleBaseRef))) {
@@ -89,31 +89,39 @@ export function createCleanCommand(dependencies = {}) {
                 await removeWorktree(repository.repoRoot, worktree.path);
             }
             catch (error) {
-                if (!isWorktreeDirtyError(error)) {
-                    throw error;
+                if (!isWorktreeForceRemovalError(error)) {
+                    failures.push({
+                        branch: worktree.branch,
+                        message: toMessage(error),
+                        path: worktree.path,
+                    });
+                    continue;
                 }
-                if (options.stale) {
+                if (options.stale && !isWorktreeDeletionError(error)) {
                     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");
-                    return 1;
+                    failures.push({
+                        branch: worktree.branch,
+                        message: "force removal declined",
+                        path: worktree.path,
+                    });
+                    continue;
                 }
                 try {
                     await forceRemoveWorktree(repository.repoRoot, worktree.path);
                 }
                 catch (forceError) {
-                    if (!options.json) {
-                        reportRemovedPaths(removedPaths, options.stderr);
-                    }
-                    emitError(options, `Failed to remove worktree at ${worktree.path}: ${toMessage(forceError)}`);
-                    return 1;
+                    failures.push({
+                        branch: worktree.branch,
+                        message: toMessage(forceError),
+                        path: worktree.path,
+                    });
+                    continue;
                 }
             }
-            removedPaths.push(worktree.path);
             removedWorktrees.push(worktree);
             if (worktree.branch) {
                 try {
@@ -145,12 +153,16 @@ export function createCleanCommand(dependencies = {}) {
                     ? { branch: worktree.branch, path: worktree.path }
                     : serializeWorktreeInfo(info);
             });
-            options.stdout(`${JSON.stringify({ removed }, null, 2)}\n`);
+            const payload = failures.length === 0 ? { removed } : { removed, failed: failures };
+            options.stdout(`${JSON.stringify(payload, null, 2)}\n`);
+        }
+        else if (failures.length > 0) {
+            reportCleanFailures(failures, options.stderr);
         }
         else {
             options.stdout(`${repository.repoRoot}\n`);
         }
-        return 0;
+        return failures.length === 0 ? 0 : 1;
     };
 }
 export const runCleanCommand = createCleanCommand();
@@ -216,9 +228,12 @@ function resolveSelectedWorktrees(worktrees, selections) {
     }
     return selectedWorktrees;
 }
-function reportRemovedPaths(paths, stderr) {
-    if (paths.length > 0) {
-        stderr(`Already removed: ${paths.join(", ")}\n`);
+function reportCleanFailures(failures, stderr) {
+    const noun = failures.length === 1 ? "worktree" : "worktrees";
+    stderr(`Failed to clean ${failures.length} ${noun}:\n`);
+    for (const failure of failures) {
+        const branch = failure.branch === null ? "detached" : failure.branch;
+        stderr(`- ${failure.path} (${branch}): ${failure.message}\n`);
     }
 }
 function formatCleanInfo(info) {

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 };
     }
@@ -118,19 +127,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")
@@ -267,6 +290,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 +300,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 +342,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) => {

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>;