@solaqua/gji 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# gji
+
+Context switching without the mess.
+
+`gji` is a Git worktree CLI for people who jump between tasks all day. It gives each branch or PR its own directory, so you stop doing `stash`, `pop`, reinstall cycles, and fragile branch juggling.
+
+## Why
+
+Standard branch switching gets annoying when you are:
+
+- fixing one bug while reviewing another branch
+- hopping between feature work and PR checks
+- using multiple terminals, editors, or AI agents at the same time
+
+`gji` keeps those contexts isolated in separate worktrees with deterministic paths.
+
+## Install
+
+Install from npm:
+
+```sh
+npm install -g @solaqua/gji
+```
+
+Confirm the CLI is available:
+
+```sh
+gji --help
+```
+
+The installed command is still:
+
+```sh
+gji
+```
+
+## Quick start
+
+Inside a Git repository:
+
+```sh
+gji new feature/login-form
+gji go feature/login-form
+gji status
+```
+
+That creates a linked worktree at a deterministic path:
+
+```text
+../worktrees/<repo>/<branch>
+```
+
+## Shell setup
+
+`gji go` can only change your current directory when shell integration is installed. Without shell integration, the raw CLI prints the target path so it stays script-friendly.
+
+For zsh:
+
+```sh
+echo 'eval "$(gji init zsh)"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+After that:
+
+```sh
+gji go feature/login-form
+```
+
+changes your shell directory directly.
+
+For scripts or explicit piping:
+
+```sh
+gji go --print feature/login-form
+```
+
+## Daily workflow
+
+Start a task:
+
+```sh
+gji new feature/refactor-auth
+gji go feature/refactor-auth
+```
+
+Check what is active:
+
+```sh
+gji status
+gji ls
+```
+
+Pull a PR into its own worktree:
+
+```sh
+gji pr 123
+```
+
+Sync the current worktree with the latest default branch:
+
+```sh
+gji sync
+```
+
+Sync every worktree in the repository:
+
+```sh
+gji sync --all
+```
+
+Clean up stale linked worktrees interactively:
+
+```sh
+gji clean
+```
+
+Finish a single worktree explicitly:
+
+```sh
+gji remove feature/refactor-auth
+```
+
+## Commands
+
+- `gji init [shell]` prints shell integration for `zsh`, `bash`, or `fish`
+- `gji new [branch]` creates a branch and linked worktree; when omitted, it prompts with a placeholder branch name
+- `gji pr <number>` fetches `origin/pull/<number>/head` and creates a linked `pr/<number>` worktree
+- `gji go [branch]` jumps to an existing worktree when shell integration is installed, or prints the matching worktree path otherwise
+- `gji root` prints the main repository root path from either the repo root or a linked worktree
+- `gji status [--json]` prints repository metadata, worktree health, and upstream divergence
+- `gji sync [--all]` fetches from the configured remote and rebases or fast-forwards worktrees onto the configured default branch
+- `gji ls [--json]` lists active worktrees in a table or JSON
+- `gji clean` interactively prunes one or more linked worktrees, including detached entries, while excluding the current worktree
+- `gji remove [branch]` removes a linked worktree and deletes its branch when present
+- `gji config` reads or updates global defaults
+
+## Configuration
+
+`gji` is usable without setup, but it supports defaults through:
+
+- global config at `~/.config/gji/config.json`
+- repo-local config at `.gji.json`
+
+Repo-local values override global defaults.
+
+Supported keys:
+
+- `branchPrefix`
+- `syncRemote`
+- `syncDefaultBranch`
+
+Example:
+
+```json
+{
+  "branchPrefix": "feature/",
+  "syncRemote": "upstream",
+  "syncDefaultBranch": "main"
+}
+```
+
+Behavior:
+
+- if `syncRemote` is unset, `gji sync` defaults to `origin`
+- if `syncDefaultBranch` is unset, `gji sync` resolves the remote default branch from `HEAD`
+
+## JSON output
+
+`gji ls --json` returns branch/path entries:
+
+```sh
+gji ls --json
+```
+
+`gji status --json` returns a top-level object with:
+
+- `repoRoot`
+- `currentRoot`
+- `worktrees`
+
+Each worktree entry contains:
+
+- `branch`: branch name or `null` for detached worktrees
+- `current`
+- `path`
+- `status`: `clean` or `dirty`
+- `upstream`: one of
+  - `{ "kind": "detached" }`
+  - `{ "kind": "no-upstream" }`
+  - `{ "kind": "tracked", "ahead": number, "behind": number }`
+
+## Notes
+
+- `gji` works from either the main repository root or any linked worktree
+- the current worktree is never offered as a `gji clean` removal candidate
+- `gji` currently uses GitHub-style PR refs for `gji pr`
+
+## License
+
+MIT

package/dist/clean.d.ts

@@ -0,0 +1,12 @@
+import type { WorktreeEntry } from './repo.js';
+export interface CleanCommandOptions {
+    cwd: string;
+    stderr: (chunk: string) => void;
+    stdout: (chunk: string) => void;
+}
+export interface CleanCommandDependencies {
+    confirmRemoval: (worktrees: WorktreeEntry[]) => Promise<boolean>;
+    promptForWorktrees: (worktrees: WorktreeEntry[]) => Promise<string[] | null>;
+}
+export declare function createCleanCommand(dependencies?: Partial<CleanCommandDependencies>): (options: CleanCommandOptions) => Promise<number>;
+export declare const runCleanCommand: (options: CleanCommandOptions) => Promise<number>;

package/dist/clean.js

@@ -0,0 +1,80 @@
+import { confirm, isCancel, multiselect } from '@clack/prompts';
+import { deleteBranch, loadLinkedWorktrees, removeWorktree, } from './worktree-management.js';
+export function createCleanCommand(dependencies = {}) {
+    const promptForWorktrees = dependencies.promptForWorktrees ?? defaultPromptForWorktrees;
+    const confirmRemoval = dependencies.confirmRemoval ?? defaultConfirmRemoval;
+    return async function runCleanCommand(options) {
+        const { linkedWorktrees, repository } = await loadLinkedWorktrees(options.cwd);
+        const cleanupCandidates = linkedWorktrees.filter((worktree) => worktree.path !== repository.currentRoot);
+        if (cleanupCandidates.length === 0) {
+            options.stderr('No linked worktrees to clean\n');
+            return 1;
+        }
+        const selections = await promptForWorktrees(cleanupCandidates);
+        if (!selections || selections.length === 0) {
+            options.stderr('Aborted\n');
+            return 1;
+        }
+        const selectedWorktrees = resolveSelectedWorktrees(cleanupCandidates, selections);
+        if (selectedWorktrees.length !== selections.length) {
+            options.stderr('Selected worktree no longer exists\n');
+            return 1;
+        }
+        if (!(await confirmRemoval(selectedWorktrees))) {
+            options.stderr('Aborted\n');
+            return 1;
+        }
+        for (const worktree of selectedWorktrees) {
+            await removeWorktree(repository.repoRoot, worktree.path);
+            if (worktree.branch) {
+                await deleteBranch(repository.repoRoot, worktree.branch);
+            }
+        }
+        options.stdout(`${repository.repoRoot}\n`);
+        return 0;
+    };
+}
+export const runCleanCommand = createCleanCommand();
+function resolveSelectedWorktrees(worktrees, selections) {
+    const selectedWorktrees = [];
+    const seenPaths = new Set();
+    for (const selection of selections) {
+        const worktree = worktrees.find((entry) => entry.path === selection || entry.branch === selection);
+        if (!worktree || seenPaths.has(worktree.path)) {
+            continue;
+        }
+        selectedWorktrees.push(worktree);
+        seenPaths.add(worktree.path);
+    }
+    return selectedWorktrees;
+}
+async function defaultPromptForWorktrees(worktrees) {
+    const choice = await multiselect({
+        message: 'Choose worktrees to clean',
+        options: worktrees.map((worktree) => ({
+            hint: worktree.path,
+            label: worktree.branch ?? '(detached)',
+            value: worktree.path,
+        })),
+        required: true,
+    });
+    return isCancel(choice) ? null : choice;
+}
+async function defaultConfirmRemoval(worktrees) {
+    const branchCount = worktrees.filter((worktree) => worktree.branch !== null).length;
+    const detachedCount = worktrees.length - branchCount;
+    const messageParts = [`Remove ${worktrees.length} linked worktree${worktrees.length === 1 ? '' : 's'}`];
+    if (branchCount > 0) {
+        messageParts.push(`delete ${branchCount} branch${branchCount === 1 ? '' : 'es'}`);
+    }
+    if (detachedCount > 0) {
+        messageParts.push(`remove ${detachedCount} detached worktree${detachedCount === 1 ? '' : 's'}`);
+    }
+    const choice = await confirm({
+        active: 'Yes',
+        inactive: 'No',
+        initialValue: true,
+        message: `${messageParts.join(', ')}?`,
+    });
+    return !isCancel(choice) && choice;
+}

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+import { Command } from 'commander';
+export interface RunCliOptions {
+    cwd?: string;
+    stderr?: (chunk: string) => void;
+    stdout?: (chunk: string) => void;
+}
+export interface RunCliResult {
+    exitCode: number;
+}
+export declare function createProgram(): Command;
+export declare function runCli(argv: string[], options?: RunCliOptions): Promise<RunCliResult>;

package/dist/cli.js

@@ -0,0 +1,294 @@
+import { Command } from 'commander';
+import { runCleanCommand } from './clean.js';
+import { runConfigCommand } from './config-command.js';
+import { runGoCommand } from './go.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 { runRootCommand } from './root.js';
+import { runStatusCommand } from './status.js';
+import { runSyncCommand } from './sync.js';
+export function createProgram() {
+    const program = new Command();
+    program
+        .name('gji')
+        .description('Context switching without the mess.')
+        .showHelpAfterError()
+        .showSuggestionAfterError();
+    registerCommands(program);
+    return program;
+}
+export async function runCli(argv, options = {}) {
+    const program = createProgram();
+    const cwd = options.cwd ?? process.cwd();
+    const stdout = options.stdout ?? (() => undefined);
+    const stderr = options.stderr ?? (() => undefined);
+    program.configureOutput({
+        writeErr: stderr,
+        writeOut: stdout,
+    });
+    program.exitOverride();
+    if (argv.length === 0) {
+        program.outputHelp();
+        return { exitCode: 0 };
+    }
+    try {
+        attachCommandActions(program, { cwd, stderr, stdout });
+        await program.parseAsync(['node', 'gji', ...argv], { from: 'node' });
+        return { exitCode: 0 };
+    }
+    catch (error) {
+        if (isCommanderExit(error)) {
+            return { exitCode: error.exitCode };
+        }
+        throw error;
+    }
+}
+function registerCommands(program) {
+    program
+        .command('new [branch]')
+        .description('create a new branch and linked worktree')
+        .action(notImplemented('new'));
+    program
+        .command('init [shell]')
+        .description('print or install shell integration')
+        .option('--write', 'write the integration to the shell config file')
+        .action(notImplemented('init'));
+    program
+        .command('pr <number>')
+        .description('fetch a pull request ref and create a linked worktree')
+        .action(notImplemented('pr'));
+    program
+        .command('go [branch]')
+        .description('print or select a worktree path')
+        .option('--print', 'print the resolved worktree path explicitly')
+        .action(notImplemented('go'));
+    program
+        .command('root')
+        .description('print the main repository root path')
+        .action(notImplemented('root'));
+    program
+        .command('status')
+        .description('summarize repository and worktree health')
+        .option('--json', 'print repository and worktree health as JSON')
+        .action(notImplemented('status'));
+    program
+        .command('sync')
+        .description('fetch and update one or all worktrees')
+        .option('--all', 'sync every worktree in the repository')
+        .action(notImplemented('sync'));
+    program
+        .command('ls')
+        .description('list active worktrees')
+        .option('--json', 'print active worktrees as JSON')
+        .action(notImplemented('ls'));
+    program
+        .command('clean')
+        .description('interactively prune linked worktrees')
+        .action(notImplemented('clean'));
+    program
+        .command('remove [branch]')
+        .description('remove a linked worktree and delete its branch when present')
+        .action(notImplemented('remove'));
+    const configCommand = program
+        .command('config')
+        .description('manage global config defaults')
+        .action(notImplemented('config'));
+    configCommand
+        .command('get [key]')
+        .description('print the global config or a single key')
+        .action(notImplemented('config get'));
+    configCommand
+        .command('set <key> <value>')
+        .description('set a global config value')
+        .action(notImplemented('config set'));
+    configCommand
+        .command('unset <key>')
+        .description('remove a global config value')
+        .action(notImplemented('config unset'));
+}
+function attachCommandActions(program, options) {
+    program.commands
+        .find((command) => command.name() === 'new')
+        ?.action(async (branch) => {
+        const exitCode = await runNewCommand({ ...options, branch });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    program.commands
+        .find((command) => command.name() === 'init')
+        ?.action(async (shell, commandOptions) => {
+        const exitCode = await runInitCommand({
+            cwd: options.cwd,
+            shell,
+            stdout: options.stdout,
+            write: commandOptions.write,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    program.commands
+        .find((command) => command.name() === 'pr')
+        ?.action(async (number) => {
+        const exitCode = await runPrCommand({ cwd: options.cwd, number, stdout: options.stdout });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    program.commands
+        .find((command) => command.name() === 'go')
+        ?.action(async (branch, commandOptions) => {
+        const exitCode = await runGoCommand({
+            branch,
+            cwd: options.cwd,
+            print: commandOptions.print,
+            stderr: options.stderr,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    program.commands
+        .find((command) => command.name() === 'root')
+        ?.action(async () => {
+        const exitCode = await runRootCommand({
+            cwd: options.cwd,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    program.commands
+        .find((command) => command.name() === 'status')
+        ?.action(async (commandOptions) => {
+        const exitCode = await runStatusCommand({
+            cwd: options.cwd,
+            json: commandOptions.json,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    program.commands
+        .find((command) => command.name() === 'sync')
+        ?.action(async (commandOptions) => {
+        const exitCode = await runSyncCommand({
+            all: commandOptions.all,
+            cwd: options.cwd,
+            stderr: options.stderr,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    program.commands
+        .find((command) => command.name() === 'ls')
+        ?.action(async (commandOptions) => {
+        const exitCode = await runLsCommand({
+            cwd: options.cwd,
+            json: commandOptions.json,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    program.commands
+        .find((command) => command.name() === 'clean')
+        ?.action(async () => {
+        const exitCode = await runCleanCommand({
+            cwd: options.cwd,
+            stderr: options.stderr,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    const runRemovalCommand = async (branch) => {
+        const exitCode = await runRemoveCommand({
+            branch,
+            cwd: options.cwd,
+            stderr: options.stderr,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    };
+    program.commands
+        .find((command) => command.name() === 'remove')
+        ?.action(runRemovalCommand);
+    const configCommand = program.commands.find((command) => command.name() === 'config');
+    configCommand?.action(async () => {
+        const exitCode = await runConfigCommand({
+            cwd: options.cwd,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    configCommand?.commands.find((command) => command.name() === 'get')?.action(async (key) => {
+        const exitCode = await runConfigCommand({
+            action: 'get',
+            cwd: options.cwd,
+            key,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    configCommand?.commands
+        .find((command) => command.name() === 'set')
+        ?.action(async (key, value) => {
+        const exitCode = await runConfigCommand({
+            action: 'set',
+            cwd: options.cwd,
+            key,
+            stdout: options.stdout,
+            value,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+    configCommand?.commands.find((command) => command.name() === 'unset')?.action(async (key) => {
+        const exitCode = await runConfigCommand({
+            action: 'unset',
+            cwd: options.cwd,
+            key,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
+}
+function notImplemented(commandName) {
+    return () => {
+        throw new Error(`'${commandName}' is not implemented yet.`);
+    };
+}
+function commanderExit(exitCode) {
+    const error = new Error(`Command exited with code ${exitCode}.`);
+    error.code = 'commander.executeSubCommandAsync';
+    error.exitCode = exitCode;
+    return error;
+}
+function isCommanderExit(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        'exitCode' in error &&
+        typeof error.code === 'string' &&
+        typeof error.exitCode === 'number');
+}

package/dist/config-command.d.ts

@@ -0,0 +1,8 @@
+export interface ConfigCommandOptions {
+    action?: string;
+    cwd: string;
+    key?: string;
+    stdout: (chunk: string) => void;
+    value?: string;
+}
+export declare function runConfigCommand(options: ConfigCommandOptions): Promise<number>;

package/dist/config-command.js

@@ -0,0 +1,31 @@
+import { loadGlobalConfig, parseConfigValue, unsetGlobalConfigKey, updateGlobalConfigKey, } from './config.js';
+export async function runConfigCommand(options) {
+    switch (options.action) {
+        case undefined: {
+            const loaded = await loadGlobalConfig();
+            writeJson(options.stdout, loaded.config);
+            return 0;
+        }
+        case 'get': {
+            const loaded = await loadGlobalConfig();
+            writeJson(options.stdout, options.key ? loaded.config[options.key] : loaded.config);
+            return 0;
+        }
+        case 'set':
+            if (options.key && options.value !== undefined) {
+                await updateGlobalConfigKey(options.key, parseConfigValue(options.value));
+                return 0;
+            }
+            break;
+        case 'unset':
+            if (options.key) {
+                await unsetGlobalConfigKey(options.key);
+                return 0;
+            }
+            break;
+    }
+    throw new Error(`Invalid config arguments: ${[options.action, options.key, options.value].filter(Boolean).join(' ')}`);
+}
+function writeJson(stdout, value) {
+    stdout(`${JSON.stringify(value, null, 2)}\n`);
+}

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+export declare const CONFIG_FILE_NAME = ".gji.json";
+export declare const GLOBAL_CONFIG_DIRECTORY = ".config/gji";
+export declare const GLOBAL_CONFIG_NAME = "config.json";
+export type GjiConfig = Record<string, unknown>;
+export interface LoadedConfig {
+    config: GjiConfig;
+    exists: boolean;
+    path: string;
+}
+export declare const DEFAULT_CONFIG: GjiConfig;
+export declare function loadConfig(root: string): Promise<LoadedConfig>;
+export declare function loadEffectiveConfig(root: string, home?: string): Promise<GjiConfig>;
+export declare function loadGlobalConfig(home?: string): Promise<LoadedConfig>;
+export declare function saveGlobalConfig(config: GjiConfig, home?: string): Promise<string>;
+export declare function unsetGlobalConfigKey(key: string, home?: string): Promise<GjiConfig>;
+export declare function updateGlobalConfigKey(key: string, value: unknown, home?: string): Promise<GjiConfig>;
+export declare function GLOBAL_CONFIG_FILE_PATH(home?: string): string;
+export declare function parseConfigValue(value: string): unknown;