@solaqua/gji 0.2.4 → 0.4.0

package/README.md

@@ -73,6 +73,8 @@ Worktrees land at a deterministic path so your editor bookmarks and scripts alwa
 ../worktrees/<repo>/<branch>
 ```
 
+Set `worktreePath` in your config to use a different base (e.g. `"~/worktrees"` → `~/worktrees/<branch>`).
+
 ## Daily workflow
 
 ```sh
@@ -132,7 +134,7 @@ path=$(gji root --print)
 
 | Command | Description |
 |---|---|
-| `gji new [branch] [--detached] [--json]` | create branch + worktree, cd in |
+| `gji new [branch] [--detached] [--json]` | create branch + worktree, cd in (validates branch name against Git rules) |
 | `gji pr <ref> [--json]` | fetch PR ref, create worktree, cd in |
 | `gji go [branch] [--print]` | jump to a worktree |
 | `gji root [--print]` | jump to the main repo root |
@@ -157,6 +159,7 @@ No setup required. Optional config lives in:
 | Key | Description |
 |---|---|
 | `branchPrefix` | prefix added to new branch names (e.g. `"feature/"`) |
+| `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`) |
 | `syncFiles` | files to copy from main worktree into each new worktree |

package/dist/clean.js

@@ -1,4 +1,5 @@
 import { confirm, isCancel, multiselect } from '@clack/prompts';
+import { readWorktreeHealth } from './git.js';
 import { isHeadless } from './headless.js';
 import { deleteBranch, forceDeleteBranch, forceRemoveWorktree, isBranchUnmergedError, isWorktreeDirtyError, loadLinkedWorktrees, removeWorktree, } from './worktree-management.js';
 import { defaultConfirmForceDeleteBranch, defaultConfirmForceRemoveWorktree } from './worktree-prompts.js';
@@ -146,13 +147,18 @@ function toMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 async function defaultPromptForWorktrees(worktrees) {
+    const healthResults = await Promise.allSettled(worktrees.map((w) => readWorktreeHealth(w.path)));
     const choice = await multiselect({
         message: 'Choose worktrees to clean',
-        options: worktrees.map((worktree) => ({
-            hint: worktree.path,
-            label: worktree.branch ?? '(detached)',
-            value: worktree.path,
-        })),
+        options: worktrees.map((worktree, i) => {
+            const health = healthResults[i].status === 'fulfilled' ? healthResults[i].value : null;
+            const isStale = health?.upstreamGone === true;
+            return {
+                hint: isStale ? `${worktree.path} (upstream gone)` : worktree.path,
+                label: worktree.branch ?? '(detached)',
+                value: worktree.path,
+            };
+        }),
         required: true,
     });
     return isCancel(choice) ? null : choice;

package/dist/cli.js

@@ -59,6 +59,7 @@ 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('--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')
@@ -140,7 +141,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, json: commandOptions.json });
+        const exitCode = await runNewCommand({ ...options, branch, detached: commandOptions.detached, dryRun: commandOptions.dryRun, force: commandOptions.force, json: commandOptions.json });
         if (exitCode !== 0) {
             throw commanderExit(exitCode);
         }
@@ -151,6 +152,7 @@ function attachCommandActions(program, options) {
         const exitCode = await runInitCommand({
             cwd: options.cwd,
             shell,
+            stderr: options.stderr,
             stdout: options.stdout,
             write: commandOptions.write,
         });

package/dist/config.d.ts

@@ -1,6 +1,7 @@
 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 declare const KNOWN_CONFIG_KEYS: ReadonlySet<string>;
 export type GjiConfig = Record<string, unknown>;
 export interface LoadedConfig {
     config: GjiConfig;
@@ -9,7 +10,7 @@ export interface LoadedConfig {
 }
 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 loadEffectiveConfig(root: string, home?: string, onWarning?: (message: string) => void): Promise<GjiConfig>;
 export declare function loadGlobalConfig(home?: string): Promise<LoadedConfig>;
 export declare function saveLocalConfig(root: string, config: GjiConfig): Promise<string>;
 export declare function updateLocalConfigKey(root: string, key: string, value: unknown): Promise<GjiConfig>;
@@ -19,3 +20,4 @@ export declare function updateGlobalConfigKey(key: string, value: unknown, home?
 export declare function updateGlobalRepoConfigKey(repoRoot: string, 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;
+export declare function resolveConfigString(config: GjiConfig, key: string): string | undefined;

package/dist/config.js

@@ -1,15 +1,30 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 export const CONFIG_FILE_NAME = '.gji.json';
 export const GLOBAL_CONFIG_DIRECTORY = '.config/gji';
 export const GLOBAL_CONFIG_NAME = 'config.json';
+export const KNOWN_CONFIG_KEYS = new Set([
+    'branchPrefix',
+    'hooks',
+    'installSaveTarget',
+    'shellIntegration',
+    'skipInstallPrompt',
+    'syncDefaultBranch',
+    'syncFiles',
+    'syncRemote',
+    'worktreePath',
+]);
+const KNOWN_GLOBAL_CONFIG_KEYS = new Set([
+    ...KNOWN_CONFIG_KEYS,
+    'repos',
+]);
 export const DEFAULT_CONFIG = Object.freeze({});
 export async function loadConfig(root) {
     const path = join(root, CONFIG_FILE_NAME);
     return loadConfigFile(path);
 }
-export async function loadEffectiveConfig(root, home = homedir()) {
+export async function loadEffectiveConfig(root, home = homedir(), onWarning) {
     const [globalConfig, localConfig] = await Promise.all([
         loadGlobalConfig(home),
         loadConfig(root),
@@ -23,8 +38,28 @@ export async function loadEffectiveConfig(root, home = homedir()) {
     // Strip the internal `repos` registry from the global base before merging.
     const globalBase = { ...globalConfig.config };
     delete globalBase.repos;
+    if (onWarning) {
+        if (globalConfig.exists) {
+            warnUnknownKeys(globalBase, globalConfig.path, KNOWN_GLOBAL_CONFIG_KEYS, onWarning);
+            if (Object.keys(perRepoConfig).length > 0) {
+                warnUnknownKeys(perRepoConfig, globalConfig.path, KNOWN_CONFIG_KEYS, onWarning);
+            }
+        }
+        if (localConfig.exists) {
+            warnUnknownKeys(localConfig.config, localConfig.path, KNOWN_CONFIG_KEYS, onWarning);
+        }
+    }
     // Precedence (lowest → highest): global base → per-repo global → local.
     const merged = mergeConfig(globalBase, perRepoConfig, localConfig.config);
+    // Warn about relative worktreePath: it must be absolute or tilde-prefixed.
+    const worktreePathValue = merged.worktreePath;
+    if (onWarning &&
+        typeof worktreePathValue === 'string' &&
+        worktreePathValue.length > 0 &&
+        !worktreePathValue.startsWith('/') &&
+        !worktreePathValue.startsWith('~')) {
+        onWarning(`gji: "worktreePath" must be an absolute path or start with ~, got "${worktreePathValue}" — using default\n`);
+    }
     // Hooks are spread across all three layers so that different hook keys from
     // different layers both apply (e.g. global afterEnter + local afterCreate).
     // Within each key the higher-precedence layer wins (same spread order).
@@ -87,6 +122,10 @@ export async function updateGlobalRepoConfigKey(repoRoot, key, value, home = hom
     return nextConfig;
 }
 export function GLOBAL_CONFIG_FILE_PATH(home = homedir()) {
+    const configDir = process.env.GJI_CONFIG_DIR;
+    if (configDir) {
+        return join(resolve(configDir), GLOBAL_CONFIG_NAME);
+    }
     return join(home, GLOBAL_CONFIG_DIRECTORY, GLOBAL_CONFIG_NAME);
 }
 export function parseConfigValue(value) {
@@ -97,6 +136,10 @@ export function parseConfigValue(value) {
         return value;
     }
 }
+export function resolveConfigString(config, key) {
+    const value = config[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
 async function loadConfigFile(path) {
     try {
         const rawConfig = await readFile(path, 'utf8');
@@ -148,3 +191,38 @@ function isMissingFileError(error) {
         'code' in error &&
         error.code === 'ENOENT');
 }
+function warnUnknownKeys(config, filePath, knownKeys, onWarning) {
+    for (const key of Object.keys(config)) {
+        if (!knownKeys.has(key)) {
+            const suggestion = closestKey(key, knownKeys);
+            const hint = suggestion ? ` (did you mean "${suggestion}"?)` : '';
+            onWarning(`gji: unknown config key "${key}" in ${filePath}${hint}\n`);
+        }
+    }
+}
+function closestKey(unknown, knownKeys) {
+    let best = null;
+    let bestDist = Infinity;
+    for (const key of knownKeys) {
+        const dist = levenshtein(unknown, key);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = key;
+        }
+    }
+    return bestDist <= Math.max(2, Math.floor(unknown.length / 2)) ? best : null;
+}
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] =
+                a[i - 1] === b[j - 1]
+                    ? dp[i - 1][j - 1]
+                    : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}

package/dist/git.d.ts

@@ -2,6 +2,7 @@ export interface WorktreeHealth {
     ahead: number;
     behind: number;
     hasUpstream: boolean;
+    upstreamGone: boolean;
     status: 'clean' | 'dirty';
 }
 export declare function runGit(cwd: string, args: string[]): Promise<string>;

package/dist/git.js

@@ -23,6 +23,7 @@ function parseWorktreeHealth(output) {
     let ahead = 0;
     let behind = 0;
     let hasUpstream = false;
+    let hasAb = false;
     let dirty = false;
     for (const line of output.split('\n').filter(Boolean)) {
         if (line.startsWith('# branch.upstream ')) {
@@ -34,6 +35,7 @@ function parseWorktreeHealth(output) {
             if (!match) {
                 throw new Error(`Unexpected branch.ab output: '${line}'`);
             }
+            hasAb = true;
             ahead = Number(match[1]);
             behind = Number(match[2]);
             continue;
@@ -46,6 +48,7 @@ function parseWorktreeHealth(output) {
         ahead,
         behind,
         hasUpstream,
+        upstreamGone: hasUpstream && !hasAb,
         status: dirty ? 'dirty' : 'clean',
     };
 }

package/dist/go.d.ts

@@ -1,3 +1,4 @@
+import { type WorktreeHealth } from './git.js';
 import { type WorktreeEntry } from './repo.js';
 export interface GoCommandOptions {
     branch?: string;
@@ -11,3 +12,4 @@ export interface GoCommandDependencies {
 }
 export declare function createGoCommand(dependencies?: Partial<GoCommandDependencies>): (options: GoCommandOptions) => Promise<number>;
 export declare const runGoCommand: (options: GoCommandOptions) => Promise<number>;
+export declare function formatUpstreamHint(branch: string | null, health: WorktreeHealth): string | null;

package/dist/go.js

@@ -1,6 +1,7 @@
 import { basename } from 'node:path';
 import { isCancel, select } from '@clack/prompts';
 import { loadEffectiveConfig } from './config.js';
+import { readWorktreeHealth } from './git.js';
 import { isHeadless } from './headless.js';
 import { extractHooks, runHook } from './hooks.js';
 import { detectRepository, listWorktrees, sortByCurrentFirst } from './repo.js';
@@ -32,7 +33,7 @@ export function createGoCommand(dependencies = {}) {
             return 1;
         }
         const chosenWorktree = worktrees.find((w) => w.path === resolvedPath);
-        const config = await loadEffectiveConfig(repository.repoRoot);
+        const config = await loadEffectiveConfig(repository.repoRoot, undefined, options.stderr);
         const hooks = extractHooks(config);
         await runHook(hooks.afterEnter, resolvedPath, { branch: chosenWorktree?.branch ?? undefined, path: resolvedPath, repo: basename(repository.repoRoot) }, options.stderr);
         await writeShellOutput(GO_OUTPUT_FILE_ENV, resolvedPath, options.stdout);
@@ -41,16 +42,37 @@ export function createGoCommand(dependencies = {}) {
 }
 export const runGoCommand = createGoCommand();
 async function promptForWorktree(worktrees) {
+    const healthResults = await Promise.allSettled(worktrees.map((w) => readWorktreeHealth(w.path)));
     const choice = await select({
         message: 'Choose a worktree',
-        options: worktrees.map((worktree) => ({
-            value: worktree.path,
-            label: worktree.branch ?? '(detached)',
-            hint: worktree.isCurrent ? `${worktree.path} (current)` : worktree.path,
-        })),
+        options: worktrees.map((worktree, i) => {
+            const health = healthResults[i].status === 'fulfilled' ? healthResults[i].value : null;
+            const pathHint = worktree.isCurrent ? `${worktree.path} (current)` : worktree.path;
+            const upstream = health ? formatUpstreamHint(worktree.branch, health) : null;
+            return {
+                value: worktree.path,
+                label: worktree.branch ?? '(detached)',
+                hint: upstream ? `${upstream} · ${pathHint}` : pathHint,
+            };
+        }),
     });
     if (isCancel(choice)) {
         return null;
     }
     return choice;
 }
+export function formatUpstreamHint(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/dist/index.js

@@ -1,8 +1,19 @@
 #!/usr/bin/env node
+import { homedir } from 'node:os';
+import { loadGlobalConfig } from './config.js';
 import { runCli } from './cli.js';
 async function main() {
     try {
-        const result = await runCli(process.argv.slice(2), {
+        const argv = process.argv.slice(2);
+        // Warn once (until fixed) when shell integration hasn't been set up.
+        // Only shown in interactive terminals — suppressed in pipes and after gji init --write.
+        const isMetaArg = argv[0] === 'init'
+            || argv[0] === '--version' || argv[0] === '-V'
+            || argv[0] === '--help' || argv[0] === '-h';
+        if (process.stderr.isTTY === true && !isMetaArg) {
+            await warnIfMissingShellIntegration();
+        }
+        const result = await runCli(argv, {
             stderr: (chunk) => process.stderr.write(chunk),
             stdout: (chunk) => process.stdout.write(chunk),
         });
@@ -14,4 +25,17 @@ async function main() {
         process.exitCode = 1;
     }
 }
+async function warnIfMissingShellIntegration() {
+    try {
+        const { config } = await loadGlobalConfig(homedir());
+        if (!config.shellIntegration) {
+            const shellBin = (process.env.SHELL ?? '').split('/').at(-1);
+            const shellArg = shellBin && ['bash', 'zsh', 'fish'].includes(shellBin) ? ` ${shellBin}` : '';
+            process.stderr.write(`gji: shell integration not set up — run \`gji init${shellArg} --write\` to enable automatic cd.\n`);
+        }
+    }
+    catch {
+        // best-effort; never block the command
+    }
+}
 void main();

package/dist/init.d.ts

@@ -1,9 +1,19 @@
 export type SupportedShell = 'bash' | 'fish' | 'zsh';
 export type InstallSaveTarget = 'local' | 'global';
+export interface SetupWizardResult {
+    branchPrefix?: string;
+    hooks?: {
+        afterCreate?: string;
+        afterEnter?: string;
+        beforeRemove?: string;
+    };
+    installSaveTarget: InstallSaveTarget;
+    worktreePath?: string;
+}
 export interface InitCommandOptions {
     cwd: string;
     home?: string;
-    promptForInstallSaveTarget?: () => Promise<InstallSaveTarget | null>;
+    promptForSetup?: () => Promise<SetupWizardResult | null>;
     shell?: string;
     stderr?: (chunk: string) => void;
     stdout: (chunk: string) => void;

package/dist/init.js

@@ -1,8 +1,8 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { isCancel, select } from '@clack/prompts';
-import { loadGlobalConfig, updateGlobalConfigKey } from './config.js';
+import { intro, isCancel, outro, select, text } from '@clack/prompts';
+import { loadConfig, loadGlobalConfig, saveGlobalConfig, saveLocalConfig, updateGlobalConfigKey } from './config.js';
 const START_MARKER = '# >>> gji init >>>';
 const END_MARKER = '# <<< gji init <<<';
 const SHELL_WRAPPED_COMMANDS = [
@@ -60,19 +60,21 @@ export async function runInitCommand(options) {
     const next = upsertShellIntegration(current, script);
     await writeFile(rcPath, next, 'utf8');
     options.stdout(`${rcPath}\n`);
-    // After the shell integration is in place, ask once where to save hooks/prefs.
-    // Skip if already configured. When using the default interactive prompt, also
-    // require a real TTY so we don't block in piped/headless environments.
+    // Run the setup wizard on the first-ever init (not on subsequent re-runs).
     const { config: globalConfig } = await loadGlobalConfig(home);
-    const hasCustomPrompt = options.promptForInstallSaveTarget !== undefined;
+    const alreadyConfigured = 'shellIntegration' in globalConfig || 'installSaveTarget' in globalConfig;
+    const hasCustomPrompt = options.promptForSetup !== undefined;
     const canPrompt = hasCustomPrompt || process.stdout.isTTY === true;
-    if (!('installSaveTarget' in globalConfig) && canPrompt) {
-        const prompt = options.promptForInstallSaveTarget ?? defaultPromptForInstallSaveTarget;
-        const target = await prompt();
-        if (target) {
-            await updateGlobalConfigKey('installSaveTarget', target, home);
+    if (!alreadyConfigured && canPrompt) {
+        const prompt = options.promptForSetup ?? defaultPromptForSetup;
+        const result = await prompt();
+        if (result) {
+            await updateGlobalConfigKey('installSaveTarget', result.installSaveTarget, home);
+            await saveWizardConfig(result, options.cwd, home);
         }
     }
+    // Mark shell integration as installed so the first-run nudge is suppressed.
+    await updateGlobalConfigKey('shellIntegration', true, home);
     return 0;
 }
 export function renderShellIntegration(shell) {
@@ -111,6 +113,32 @@ export function upsertShellIntegration(existingConfig, script) {
     }
     return ensureTrailingNewline(`${prefix}\n\n${trimmedScript}`);
 }
+async function saveWizardConfig(result, cwd, home) {
+    const values = {};
+    if (result.branchPrefix)
+        values.branchPrefix = result.branchPrefix;
+    if (result.worktreePath)
+        values.worktreePath = result.worktreePath;
+    const hooks = {};
+    if (result.hooks?.afterCreate)
+        hooks.afterCreate = result.hooks.afterCreate;
+    if (result.hooks?.afterEnter)
+        hooks.afterEnter = result.hooks.afterEnter;
+    if (result.hooks?.beforeRemove)
+        hooks.beforeRemove = result.hooks.beforeRemove;
+    if (Object.keys(hooks).length > 0)
+        values.hooks = hooks;
+    if (Object.keys(values).length === 0)
+        return;
+    if (result.installSaveTarget === 'local') {
+        const loaded = await loadConfig(cwd);
+        await saveLocalConfig(cwd, { ...loaded.config, ...values });
+    }
+    else {
+        const { config: existing } = await loadGlobalConfig(home);
+        await saveGlobalConfig({ ...existing, ...values }, home);
+    }
+}
 function resolveShell(requestedShell, detectedShell) {
     const requested = normalizeShell(requestedShell);
     if (requested) {
@@ -211,16 +239,71 @@ function indentBlock(value, spaces) {
         .map((line) => line.length === 0 ? '' : `${prefix}${line}`)
         .join('\n');
 }
-async function defaultPromptForInstallSaveTarget() {
-    const choice = await select({
-        message: 'Where should saved hooks and preferences be stored by default?',
+async function defaultPromptForSetup() {
+    intro('gji setup');
+    const installSaveTarget = await select({
+        message: 'Where should preferences be saved?',
         options: [
-            { value: 'local', label: '.gji.json', hint: 'local — committed, shared with the team' },
-            { value: 'global', label: '~/.config/gji/config.json', hint: 'global — personal, never committed' },
+            { value: 'global', label: '~/.config/gji/config.json', hint: 'personal — never committed' },
+            { value: 'local', label: '.gji.json', hint: 'repo — committed with the project' },
         ],
     });
-    if (isCancel(choice)) {
+    if (isCancel(installSaveTarget)) {
+        outro('Setup skipped.');
+        return null;
+    }
+    const branchPrefix = await text({
+        message: 'Default branch prefix?',
+        placeholder: 'e.g. feat/ or fix/ — leave blank to skip',
+    });
+    if (isCancel(branchPrefix)) {
+        outro('Setup skipped.');
+        return null;
+    }
+    const worktreePath = await text({
+        message: 'Worktree base path?',
+        placeholder: 'leave blank to use the default path',
+    });
+    if (isCancel(worktreePath)) {
+        outro('Setup skipped.');
+        return null;
+    }
+    const afterCreate = await text({
+        message: 'afterCreate hook — run after creating a worktree?',
+        placeholder: 'e.g. pnpm install — leave blank to skip',
+    });
+    if (isCancel(afterCreate)) {
+        outro('Setup skipped.');
+        return null;
+    }
+    const afterEnter = await text({
+        message: 'afterEnter hook — run after entering a worktree?',
+        placeholder: 'e.g. nvm use — leave blank to skip',
+    });
+    if (isCancel(afterEnter)) {
+        outro('Setup skipped.');
+        return null;
+    }
+    const beforeRemove = await text({
+        message: 'beforeRemove hook — run before removing a worktree?',
+        placeholder: 'leave blank to skip',
+    });
+    if (isCancel(beforeRemove)) {
+        outro('Setup skipped.');
         return null;
     }
-    return choice;
+    outro('Setup complete!');
+    const hooks = {};
+    if (afterCreate)
+        hooks.afterCreate = afterCreate;
+    if (afterEnter)
+        hooks.afterEnter = afterEnter;
+    if (beforeRemove)
+        hooks.beforeRemove = beforeRemove;
+    return {
+        branchPrefix: branchPrefix || undefined,
+        hooks: Object.keys(hooks).length > 0 ? hooks : undefined,
+        installSaveTarget,
+        worktreePath: worktreePath || undefined,
+    };
 }

package/dist/new.d.ts

@@ -6,6 +6,7 @@ export interface NewCommandOptions {
     cwd: string;
     detached?: boolean;
     dryRun?: boolean;
+    force?: boolean;
     json?: boolean;
     stderr: (chunk: string) => void;
     stdout: (chunk: string) => void;

package/dist/new.js

@@ -3,13 +3,13 @@ import { basename, dirname } from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { isCancel, text } from '@clack/prompts';
-import { loadEffectiveConfig } from './config.js';
+import { loadEffectiveConfig, resolveConfigString } from './config.js';
 import { syncFiles } from './file-sync.js';
 import { extractHooks, runHook } from './hooks.js';
 import { isHeadless } from './headless.js';
 import { maybeRunInstallPrompt } from './install-prompt.js';
 import { pathExists, promptForPathConflict } from './conflict.js';
-import { detectRepository, resolveWorktreePath } from './repo.js';
+import { detectRepository, resolveWorktreePath, validateBranchName } from './repo.js';
 import { writeShellOutput } from './shell-handoff.js';
 const execFileAsync = promisify(execFile);
 const NEW_OUTPUT_FILE_ENV = 'GJI_NEW_OUTPUT_FILE';
@@ -19,7 +19,7 @@ export function createNewCommand(dependencies = {}) {
     const prompt = dependencies.promptForPathConflict ?? promptForPathConflict;
     return async function runNewCommand(options) {
         const repository = await detectRepository(options.cwd);
-        const config = await loadEffectiveConfig(repository.repoRoot);
+        const config = await loadEffectiveConfig(repository.repoRoot, undefined, options.stderr);
         const usesGeneratedDetachedName = options.detached && options.branch === undefined;
         if (!options.detached && !options.branch && (options.json || isHeadless())) {
             const message = 'branch argument is required';
@@ -43,14 +43,54 @@ export function createNewCommand(dependencies = {}) {
             }
             return 1;
         }
+        if (!options.detached) {
+            const branchError = validateBranchName(rawBranch);
+            if (branchError) {
+                if (options.json) {
+                    options.stderr(`${JSON.stringify({ error: branchError }, null, 2)}\n`);
+                }
+                else {
+                    options.stderr(`gji new: ${branchError}\n`);
+                }
+                return 1;
+            }
+        }
+        const rawBasePath = resolveConfigString(config, 'worktreePath');
+        const configuredBasePath = rawBasePath?.startsWith('/') || rawBasePath?.startsWith('~') ? rawBasePath : undefined;
         const worktreeName = options.detached
             ? rawBranch
             : applyConfiguredBranchPrefix(rawBranch, config.branchPrefix);
         const worktreePath = usesGeneratedDetachedName
-            ? await resolveUniqueDetachedWorktreePath(repository.repoRoot, worktreeName)
-            : resolveWorktreePath(repository.repoRoot, worktreeName);
+            ? await resolveUniqueDetachedWorktreePath(repository.repoRoot, worktreeName, configuredBasePath)
+            : resolveWorktreePath(repository.repoRoot, worktreeName, configuredBasePath);
         if (!usesGeneratedDetachedName && await pathExists(worktreePath)) {
-            if (options.json || isHeadless()) {
+            if (options.force) {
+                if (!options.dryRun) {
+                    try {
+                        await execFileAsync('git', ['worktree', 'remove', '--force', worktreePath], { cwd: repository.repoRoot });
+                    }
+                    catch (err) {
+                        if (!isNotRegisteredWorktreeError(err)) {
+                            const msg = `could not remove existing worktree at ${worktreePath}: ${toExecMessage(err)}`;
+                            if (options.json) {
+                                options.stderr(`${JSON.stringify({ warning: msg }, null, 2)}\n`);
+                            }
+                            else {
+                                options.stderr(`Warning: ${msg}\n`);
+                            }
+                        }
+                    }
+                    if (!options.detached) {
+                        try {
+                            await execFileAsync('git', ['branch', '-D', worktreeName], { cwd: repository.repoRoot });
+                        }
+                        catch {
+                            // Branch may not exist; proceed anyway.
+                        }
+                    }
+                }
+            }
+            else if (options.json || isHeadless()) {
                 const message = `target worktree path already exists: ${worktreePath}`;
                 if (options.json) {
                     options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
@@ -62,13 +102,15 @@ export function createNewCommand(dependencies = {}) {
                 }
                 return 1;
             }
-            const choice = await prompt(worktreePath);
-            if (choice === 'reuse') {
-                await writeOutput(worktreePath, options.stdout);
-                return 0;
+            else {
+                const choice = await prompt(worktreePath);
+                if (choice === 'reuse') {
+                    await writeOutput(worktreePath, options.stdout);
+                    return 0;
+                }
+                options.stderr(`Aborted because target worktree path already exists: ${worktreePath}\n`);
+                return 1;
             }
-            options.stderr(`Aborted because target worktree path already exists: ${worktreePath}\n`);
-            return 1;
         }
         if (options.dryRun) {
             if (options.json) {
@@ -162,11 +204,11 @@ function applyConfiguredBranchPrefix(branch, branchPrefix) {
     }
     return `${branchPrefix}${branch}`;
 }
-async function resolveUniqueDetachedWorktreePath(repoRoot, baseName) {
+async function resolveUniqueDetachedWorktreePath(repoRoot, baseName, basePath) {
     let attempt = 1;
     while (true) {
         const candidateName = attempt === 1 ? baseName : `${baseName}-${attempt}`;
-        const candidatePath = resolveWorktreePath(repoRoot, candidateName);
+        const candidatePath = resolveWorktreePath(repoRoot, candidateName, basePath);
         if (!await pathExists(candidatePath)) {
             return candidatePath;
         }
@@ -178,7 +220,10 @@ async function defaultPromptForBranch(placeholder) {
         defaultValue: placeholder,
         message: 'Name the new branch',
         placeholder,
-        validate: (value) => value.trim().length === 0 ? 'Branch name must not be empty.' : undefined,
+        validate: (value) => {
+            const trimmed = value.trim();
+            return validateBranchName(trimmed) ?? undefined;
+        },
     });
     if (isCancel(choice)) {
         return null;
@@ -201,3 +246,13 @@ async function localBranchExists(repoRoot, branchName) {
 async function writeOutput(worktreePath, stdout) {
     await writeShellOutput(NEW_OUTPUT_FILE_ENV, worktreePath, stdout);
 }
+function isNotRegisteredWorktreeError(error) {
+    const stderr = hasExecStderr(error) ? error.stderr : String(error);
+    return stderr.includes('is not a working tree') || stderr.includes('not a linked working tree');
+}
+function hasExecStderr(error) {
+    return error instanceof Error && 'stderr' in error && typeof error.stderr === 'string';
+}
+function toExecMessage(error) {
+    return hasExecStderr(error) ? error.stderr.trim() : String(error);
+}

package/dist/pr.js

@@ -2,7 +2,7 @@ import { mkdir } from 'node:fs/promises';
 import { basename, dirname } from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { loadEffectiveConfig } from './config.js';
+import { loadEffectiveConfig, resolveConfigString } from './config.js';
 import { syncFiles } from './file-sync.js';
 import { pathExists, promptForPathConflict } from './conflict.js';
 import { extractHooks, runHook } from './hooks.js';
@@ -38,10 +38,12 @@ export function createPrCommand(dependencies = {}) {
             return 1;
         }
         const repository = await detectRepository(options.cwd);
-        const config = await loadEffectiveConfig(repository.repoRoot);
+        const config = await loadEffectiveConfig(repository.repoRoot, undefined, options.stderr);
         const branchName = `pr/${prNumber}`;
         const remoteRef = `refs/remotes/origin/pull/${prNumber}/head`;
-        const worktreePath = resolveWorktreePath(repository.repoRoot, branchName);
+        const rawBasePath = resolveConfigString(config, 'worktreePath');
+        const configuredBasePath = rawBasePath?.startsWith('/') || rawBasePath?.startsWith('~') ? rawBasePath : undefined;
+        const worktreePath = resolveWorktreePath(repository.repoRoot, branchName, configuredBasePath);
         if (await pathExists(worktreePath)) {
             if (options.json || isHeadless()) {
                 const message = `target worktree path already exists: ${worktreePath}`;

package/dist/remove.js

@@ -63,7 +63,7 @@ export function createRemoveCommand(dependencies = {}) {
             }
             return 0;
         }
-        const config = await loadEffectiveConfig(repository.repoRoot);
+        const config = await loadEffectiveConfig(repository.repoRoot, undefined, options.stderr);
         const hooks = extractHooks(config);
         await runHook(hooks.beforeRemove, worktree.path, { branch: worktree.branch ?? undefined, path: worktree.path, repo: basename(repository.repoRoot) }, options.stderr);
         try {

package/dist/repo.d.ts

@@ -11,6 +11,7 @@ export interface WorktreeEntry {
     path: string;
 }
 export declare function detectRepository(cwd: string): Promise<RepositoryContext>;
-export declare function resolveWorktreePath(repoRoot: string, branch: string): string;
+export declare function resolveWorktreePath(repoRoot: string, branch: string, basePath?: string): string;
+export declare function validateBranchName(name: string): string | null;
 export declare function listWorktrees(cwd: string): Promise<WorktreeEntry[]>;
 export declare function sortByCurrentFirst(worktrees: WorktreeEntry[]): WorktreeEntry[];

package/dist/repo.js

@@ -1,4 +1,5 @@
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
 import { runGit } from './git.js';
 export async function detectRepository(cwd) {
     const currentRoot = await runGit(cwd, ['rev-parse', '--show-toplevel']);
@@ -15,7 +16,7 @@ export async function detectRepository(cwd) {
         repoRoot,
     };
 }
-export function resolveWorktreePath(repoRoot, branch) {
+export function resolveWorktreePath(repoRoot, branch, basePath) {
     const segments = branch.split('/').filter(Boolean);
     if (segments.length === 0) {
         throw new Error('Branch name must not be empty.');
@@ -23,7 +24,52 @@ export function resolveWorktreePath(repoRoot, branch) {
     if (segments.some((segment) => segment === '.' || segment === '..')) {
         throw new Error(`Branch name '${branch}' contains an invalid path segment.`);
     }
-    return join(dirname(repoRoot), 'worktrees', basename(repoRoot), ...segments);
+    const base = basePath
+        ? expandTildeInPath(basePath)
+        : join(dirname(repoRoot), 'worktrees', basename(repoRoot));
+    return join(base, ...segments);
+}
+export function validateBranchName(name) {
+    if (name.length === 0) {
+        return 'Branch name must not be empty.';
+    }
+    if (/[\x00-\x1f\x7f ~^:?*[\\\s]/.test(name)) {
+        return `Branch name '${name}' contains an invalid character.`;
+    }
+    if (name.startsWith('-')) {
+        return `Branch name '${name}' must not start with a dash.`;
+    }
+    if (name.startsWith('/') || name.endsWith('/') || name.includes('//')) {
+        return `Branch name '${name}' has invalid slash placement.`;
+    }
+    if (name.includes('..')) {
+        return `Branch name '${name}' must not contain '..'.`;
+    }
+    if (name.endsWith('.')) {
+        return `Branch name '${name}' must not end with '.'.`;
+    }
+    if (name.includes('@{')) {
+        return `Branch name '${name}' must not contain '@{'.`;
+    }
+    if (name === '@') {
+        return "Branch name cannot be '@'.";
+    }
+    for (const segment of name.split('/')) {
+        if (segment.startsWith('.')) {
+            return `Branch name '${name}' contains a path component starting with '.'.`;
+        }
+        if (segment.endsWith('.lock')) {
+            return `Branch name '${name}' contains a path component ending with '.lock'.`;
+        }
+    }
+    return null;
+}
+function expandTildeInPath(p) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/'))
+        return join(homedir(), p.slice(2));
+    return p;
 }
 export async function listWorktrees(cwd) {
     const [output, currentRoot] = await Promise.all([

package/dist/status.d.ts

@@ -14,6 +14,8 @@ type UpstreamState = {
     kind: 'detached';
 } | {
     kind: 'no-upstream';
+} | {
+    kind: 'stale';
 } | {
     kind: 'tracked';
     ahead: number;

package/dist/status.js

@@ -58,6 +58,9 @@ function buildUpstreamState(branch, health) {
     if (!health.hasUpstream) {
         return { kind: 'no-upstream' };
     }
+    if (health.upstreamGone) {
+        return { kind: 'stale' };
+    }
     return {
         ahead: health.ahead,
         behind: health.behind,
@@ -71,6 +74,9 @@ function formatUpstreamState(upstream) {
     if (upstream.kind === 'no-upstream') {
         return 'no-upstream';
     }
+    if (upstream.kind === 'stale') {
+        return 'gone';
+    }
     if (upstream.ahead === 0 && upstream.behind === 0) {
         return 'up to date';
     }

package/dist/sync.js

@@ -4,7 +4,7 @@ import { comparePaths } from './paths.js';
 import { detectRepository, listWorktrees } from './repo.js';
 export async function runSyncCommand(options) {
     const repository = await detectRepository(options.cwd);
-    const config = await loadEffectiveConfig(repository.repoRoot);
+    const config = await loadEffectiveConfig(repository.repoRoot, undefined, options.stderr);
     const worktrees = await listWorktrees(options.cwd);
     const remote = resolveConfiguredString(config.syncRemote) ?? 'origin';
     let defaultBranch;

package/dist/trigger-hook.js

@@ -12,7 +12,7 @@ export async function runTriggerHookCommand(options) {
     }
     const hookName = options.hook;
     const repository = await detectRepository(options.cwd);
-    const config = await loadEffectiveConfig(repository.repoRoot);
+    const config = await loadEffectiveConfig(repository.repoRoot, undefined, options.stderr);
     const hooks = extractHooks(config);
     // Find the branch for the current worktree (undefined for detached HEAD).
     const worktrees = await listWorktrees(options.cwd);

package/man/man1/gji-clean.1

@@ -0,0 +1,19 @@
+.TH GJI\-CLEAN 1 "April 2026" "gji 0.4.0" "User Commands"
+.SH NAME
+gji\-clean \- interactively prune linked worktrees
+.SH SYNOPSIS
+.B gji clean [\fIoptions\fR] [options]
+.SH DESCRIPTION
+interactively prune linked worktrees
+.SH OPTIONS
+.TP
+.B \-f, \-\-force
+bypass prompts, force\-remove dirty worktrees, and force\-delete unmerged branches
+.TP
+.B \-\-dry\-run
+show what would be deleted without removing anything
+.TP
+.B \-\-json
+emit JSON on success or error instead of human\-readable output
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-config.1

@@ -0,0 +1,19 @@
+.TH GJI\-CONFIG 1 "April 2026" "gji 0.4.0" "User Commands"
+.SH NAME
+gji\-config \- manage global config defaults
+.SH SYNOPSIS
+.B gji config [options] [command]
+.SH DESCRIPTION
+manage global config defaults
+.SH SUBCOMMANDS
+.TP
+.B get
+print the global config or a single key
+.TP
+.B set
+set a global config value
+.TP
+.B unset
+remove a global config value
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-go.1

@@ -0,0 +1,13 @@
+.TH GJI\-GO 1 "April 2026" "gji 0.4.0" "User Commands"
+.SH NAME
+gji\-go \- print or select a worktree path
+.SH SYNOPSIS
+.B gji go [\fIoptions\fR] [options] [branch]
+.SH DESCRIPTION
+print or select a worktree path
+.SH OPTIONS
+.TP
+.B \-\-print
+print the resolved worktree path explicitly
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-init.1

@@ -0,0 +1,13 @@
+.TH GJI\-INIT 1 "April 2026" "gji 0.4.0" "User Commands"
+.SH NAME
+gji\-init \- print or install shell integration
+.SH SYNOPSIS
+.B gji init [\fIoptions\fR] [options] [shell]
+.SH DESCRIPTION
+print or install shell integration
+.SH OPTIONS
+.TP
+.B \-\-write
+write the integration to the shell config file
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-ls.1

@@ -0,0 +1,13 @@
+.TH GJI\-LS 1 "April 2026" "gji 0.4.0" "User Commands"
+.SH NAME
+gji\-ls \- list active worktrees
+.SH SYNOPSIS
+.B gji ls [\fIoptions\fR] [options]
+.SH DESCRIPTION
+list active worktrees
+.SH OPTIONS
+.TP
+.B \-\-json
+print active worktrees as JSON
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-new.1

@@ -0,0 +1,22 @@
+.TH GJI\-NEW 1 "April 2026" "gji 0.4.0" "User Commands"
+.SH NAME
+gji\-new \- create a new branch or detached linked worktree
+.SH SYNOPSIS
+.B gji new [\fIoptions\fR] [options] [branch]
+.SH DESCRIPTION
+create a new branch or detached linked worktree
+.SH OPTIONS
+.TP
+.B \-f, \-\-force
+remove and recreate the worktree if the target path already exists
+.TP
+.B \-\-detached
+create a detached worktree without a branch
+.TP
+.B \-\-dry\-run
+show what would be created without executing any git commands or writing files
+.TP
+.B \-\-json
+emit JSON on success or error instead of human\-readable output
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-pr.1

@@ -0,0 +1,16 @@
+.TH GJI\-PR 1 "April 2026" "gji 0.4.0" "User Commands"
+.SH NAME
+gji\-pr \- fetch a pull request by number, #number, or URL into a linked worktree
+.SH SYNOPSIS
+.B gji pr [\fIoptions\fR] [options] <ref>
+.SH DESCRIPTION
+fetch a pull request by number, #number, or URL into a linked worktree
+.SH OPTIONS
+.TP
+.B \-\-dry\-run
+show what would be created without executing any git commands or writing files
+.TP
+.B \-\-json
+emit JSON on success or error instead of human\-readable output
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-remove.1

@@ -0,0 +1,19 @@
+.TH GJI\-REMOVE 1 "April 2026" "gji 0.4.0" "User Commands"
+.SH NAME
+gji\-remove \- remove a linked worktree and delete its branch when present
+.SH SYNOPSIS
+.B gji remove [\fIoptions\fR] [options] [branch]
+.SH DESCRIPTION
+remove a linked worktree and delete its branch when present
+.SH OPTIONS
+.TP
+.B \-f, \-\-force
+bypass prompts, force\-remove a dirty worktree, and force\-delete an unmerged branch
+.TP
+.B \-\-dry\-run
+show what would be deleted without removing anything
+.TP
+.B \-\-json
+emit JSON on success or error instead of human\-readable output
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-root.1

@@ -0,0 +1,13 @@
+.TH GJI\-ROOT 1 "April 2026" "gji 0.4.0" "User Commands"
+.SH NAME
+gji\-root \- print the main repository root path
+.SH SYNOPSIS
+.B gji root [\fIoptions\fR] [options]
+.SH DESCRIPTION
+print the main repository root path
+.SH OPTIONS
+.TP
+.B \-\-print
+print the resolved repository root path explicitly
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-status.1

@@ -0,0 +1,13 @@
+.TH GJI\-STATUS 1 "April 2026" "gji 0.4.0" "User Commands"
+.SH NAME
+gji\-status \- summarize repository and worktree health
+.SH SYNOPSIS
+.B gji status [\fIoptions\fR] [options]
+.SH DESCRIPTION
+summarize repository and worktree health
+.SH OPTIONS
+.TP
+.B \-\-json
+print repository and worktree health as JSON
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-sync.1

@@ -0,0 +1,16 @@
+.TH GJI\-SYNC 1 "April 2026" "gji 0.4.0" "User Commands"
+.SH NAME
+gji\-sync \- fetch and update one or all worktrees
+.SH SYNOPSIS
+.B gji sync [\fIoptions\fR] [options]
+.SH DESCRIPTION
+fetch and update one or all worktrees
+.SH OPTIONS
+.TP
+.B \-\-all
+sync every worktree in the repository
+.TP
+.B \-\-json
+emit JSON on success or error instead of human\-readable output
+.SH "SEE ALSO"
+.BR gji (1)

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

@@ -0,0 +1,9 @@
+.TH GJI\-TRIGGER\-HOOK 1 "April 2026" "gji 0.4.0" "User Commands"
+.SH NAME
+gji\-trigger\-hook \- run a named hook (afterCreate, afterEnter, beforeRemove) in the current worktree
+.SH SYNOPSIS
+.B gji trigger\-hook [options] <hook>
+.SH DESCRIPTION
+run a named hook (afterCreate, afterEnter, beforeRemove) in the current worktree
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji.1

@@ -0,0 +1,67 @@
+.TH GJI 1 "April 2026" "gji 0.4.0" "User Commands"
+.SH NAME
+gji \- Context switching without the mess.
+.SH SYNOPSIS
+.B gji
+[\fIoptions\fR] <\fIcommand\fR> [\fIargs\fR]
+.SH DESCRIPTION
+Context switching without the mess.
+.PP
+Each branch lives in its own worktree with its own node_modules and terminal,
+eliminating the need for \fBgit stash\fR when switching contexts.
+.SH COMMANDS
+.TP
+.B new [options] [branch]
+create a new branch or detached linked worktree
+.TP
+.B init [options] [shell]
+print or install shell integration
+.TP
+.B pr [options] <ref>
+fetch a pull request by number, #number, or URL into a linked worktree
+.TP
+.B go [options] [branch]
+print or select a worktree path
+.TP
+.B root [options]
+print the main repository root path
+.TP
+.B status [options]
+summarize repository and worktree health
+.TP
+.B sync [options]
+fetch and update one or all worktrees
+.TP
+.B ls [options]
+list active worktrees
+.TP
+.B clean [options]
+interactively prune linked worktrees
+.TP
+.B remove [options] [branch]
+remove a linked worktree and delete its branch when present
+.br
+Alias: \fBrm\fR
+.TP
+.B trigger\-hook [options] <hook>
+run a named hook (afterCreate, afterEnter, beforeRemove) in the current worktree
+.TP
+.B config [options] [command]
+manage global config defaults
+.SH OPTIONS
+.TP
+.B \-V, \-\-version
+output the version number
+.SH "SEE ALSO"
+.BR gji\-new (1),
+.BR gji\-init (1),
+.BR gji\-pr (1),
+.BR gji\-go (1),
+.BR gji\-root (1),
+.BR gji\-status (1),
+.BR gji\-sync (1),
+.BR gji\-ls (1),
+.BR gji\-clean (1),
+.BR gji\-remove (1),
+.BR gji\-trigger\-hook (1),
+.BR gji\-config (1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solaqua/gji",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "description": "Git worktree CLI for fast context switching.",
   "license": "MIT",
   "author": "sjquant",
@@ -24,9 +24,13 @@
   ],
   "files": [
     "dist",
+    "man",
     "README.md",
     "LICENSE"
   ],
+  "man": [
+    "man/man1/gji.1"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -38,7 +42,8 @@
   },
   "scripts": {
     "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
-    "prepublishOnly": "pnpm test && pnpm build",
+    "generate-man": "node scripts/generate-man.mjs",
+    "prepublishOnly": "pnpm test && pnpm build && pnpm generate-man",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest"
   },