@solaqua/gji 0.2.4 → 0.3.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);
         }

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,29 @@
 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',
+    '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 +37,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 +121,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 +135,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 +190,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solaqua/gji",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Git worktree CLI for fast context switching.",
   "license": "MIT",
   "author": "sjquant",