@solaqua/gji 0.2.1 → 0.2.3

package/README.md

@@ -93,6 +93,8 @@ gji sync --all                    # rebase every worktree
 
 gji clean                         # interactive bulk cleanup
 gji remove feature/auth-refactor  # remove one worktree and its branch
+
+gji trigger-hook afterCreate      # re-run setup in the current worktree
 ```
 
 ## Shell setup
@@ -139,6 +141,7 @@ path=$(gji root --print)
 | `gji sync [--all]` | fetch and rebase worktrees onto default branch |
 | `gji clean [--force] [--json]` | interactively prune stale worktrees |
 | `gji remove [branch] [--force] [--json]` | remove a worktree and its branch |
+| `gji trigger-hook <hook>` | run a hook in the current worktree |
 | `gji config [get\|set\|unset] [key] [value]` | manage global defaults |
 | `gji init [shell]` | print or install shell integration |
 
@@ -158,7 +161,9 @@ No setup required. Optional config lives in:
 | `syncDefaultBranch` | branch to rebase onto (default: remote `HEAD`) |
 | `syncFiles` | files to copy from main worktree into each new worktree |
 | `skipInstallPrompt` | `true` to disable the auto-install prompt permanently |
+| `installSaveTarget` | `"local"` or `"global"` — where **Always**/**Never** choices are persisted (default: `"local"`); set once during `gji init --write` |
 | `hooks` | lifecycle scripts (see [Hooks](#hooks)) |
+| `repos` | per-repo overrides inside the global config (see below) |
 
 ```json
 {
@@ -169,6 +174,26 @@ No setup required. Optional config lives in:
 }
 ```
 
+### Per-repo overrides in global config
+
+If you work across many repositories, you can scope config to a specific repo inside `~/.config/gji/config.json` without adding a `.gji.json` to that repo:
+
+```json
+{
+  "branchPrefix": "feature/",
+  "repos": {
+    "/home/me/code/my-repo": {
+      "branchPrefix": "fix/",
+      "hooks": {
+        "afterCreate": "npm install"
+      }
+    }
+  }
+}
+```
+
+Precedence (lowest → highest): **global defaults → per-repo global → local `.gji.json`**. Hooks from all three layers are merged per key — different keys all apply, same key the higher-precedence layer wins.
+
 ### Config commands
 
 ```sh
@@ -200,19 +225,34 @@ Run scripts automatically at key lifecycle moments:
 
 Hooks receive `{{branch}}`, `{{path}}`, `{{repo}}` as template variables and `GJI_BRANCH`, `GJI_PATH`, `GJI_REPO` as environment variables. A failing hook emits a warning but never aborts the command.
 
-Global and repo-local hooks deep-merge per key:
+Hooks from all three config layers merge per key — different keys from different layers both apply, same key the higher-precedence layer wins:
 
 ```jsonc
 // ~/.config/gji/config.json
 { "hooks": { "afterCreate": "nvm use", "afterEnter": "echo hi" } }
 
+// per-repo entry in ~/.config/gji/config.json
+{ "repos": { "/my/repo": { "hooks": { "afterCreate": "npm install" } } } }
+
 // .gji.json
-{ "hooks": { "afterCreate": "pnpm install" } }
+{ "hooks": { "beforeRemove": "echo bye" } }
 
 // effective
-{ "hooks": { "afterCreate": "pnpm install", "afterEnter": "echo hi" } }
+{ "hooks": { "afterCreate": "npm install", "afterEnter": "echo hi", "beforeRemove": "echo bye" } }
 ```
 
+### Triggering hooks manually
+
+Run any hook in the current worktree on demand:
+
+```sh
+gji trigger-hook afterCreate   # re-run the setup script
+gji trigger-hook afterEnter    # re-run the enter script
+gji trigger-hook beforeRemove  # dry-run the cleanup script
+```
+
+This is useful after cloning on a new machine, recovering a broken worktree, or letting an AI agent bootstrap an already-existing worktree without needing interactive prompts.
+
 ## Install prompt
 
 When `gji new` or `gji pr` creates a worktree, `gji` detects the project's package manager from its lockfile and offers to run the install command:
@@ -225,7 +265,7 @@ Run `pnpm install` in the new worktree?
   Never     disable this prompt for this repo
 ```
 
-**Always** saves `hooks.afterCreate` to `.gji.json`; **Never** writes `skipInstallPrompt: true`. Both are local-only — global config is never modified.
+**Always** saves `hooks.afterCreate`; **Never** writes `skipInstallPrompt: true`. Where they are saved depends on `installSaveTarget` (see [Available keys](#available-keys)) — defaults to `.gji.json`.
 
 ## JSON output
 

package/dist/cli.js

@@ -11,6 +11,7 @@ import { runRemoveCommand } from './remove.js';
 import { runRootCommand } from './root.js';
 import { runStatusCommand } from './status.js';
 import { runSyncCommand } from './sync.js';
+import { runTriggerHookCommand } from './trigger-hook.js';
 export function createProgram() {
     const program = new Command();
     const packageVersion = readPackageVersion();
@@ -114,6 +115,10 @@ function registerCommands(program) {
         .option('--dry-run', 'show what would be deleted without removing anything')
         .option('--json', 'emit JSON on success or error instead of human-readable output')
         .action(notImplemented('remove'));
+    program
+        .command('trigger-hook <hook>')
+        .description('run a named hook (afterCreate, afterEnter, beforeRemove) in the current worktree')
+        .action(notImplemented('trigger-hook'));
     const configCommand = program
         .command('config')
         .description('manage global config defaults')
@@ -257,6 +262,18 @@ function attachCommandActions(program, options) {
     program.commands
         .find((command) => command.name() === 'remove')
         ?.action(runRemovalCommand);
+    program.commands
+        .find((command) => command.name() === 'trigger-hook')
+        ?.action(async (hook) => {
+        const exitCode = await runTriggerHookCommand({
+            cwd: options.cwd,
+            hook,
+            stderr: options.stderr,
+        });
+        if (exitCode !== 0) {
+            throw commanderExit(exitCode);
+        }
+    });
     const configCommand = program.commands.find((command) => command.name() === 'config');
     configCommand?.action(async () => {
         const exitCode = await runConfigCommand({

package/dist/config.d.ts

@@ -16,5 +16,6 @@ export declare function updateLocalConfigKey(root: string, key: string, value: u
 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 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;

package/dist/config.js

@@ -14,11 +14,27 @@ export async function loadEffectiveConfig(root, home = homedir()) {
         loadGlobalConfig(home),
         loadConfig(root),
     ]);
-    const merged = mergeConfig(globalConfig.config, localConfig.config);
-    const globalHooks = isPlainObject(globalConfig.config.hooks) ? globalConfig.config.hooks : {};
+    // Extract per-repo override keyed by the absolute repo path.
+    // Keys may use ~ as shorthand for the home directory (e.g. ~/code/my-repo).
+    const repos = globalConfig.config.repos;
+    const perRepoConfig = isPlainObject(repos)
+        ? findPerRepoConfig(repos, root, home)
+        : {};
+    // Strip the internal `repos` registry from the global base before merging.
+    const globalBase = { ...globalConfig.config };
+    delete globalBase.repos;
+    // Precedence (lowest → highest): global base → per-repo global → local.
+    const merged = mergeConfig(globalBase, perRepoConfig, localConfig.config);
+    // 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).
+    const globalHooks = isPlainObject(globalBase.hooks) ? globalBase.hooks : {};
+    const perRepoHooks = isPlainObject(perRepoConfig.hooks) ? perRepoConfig.hooks : {};
     const localHooks = isPlainObject(localConfig.config.hooks) ? localConfig.config.hooks : {};
-    if (Object.keys(globalHooks).length > 0 || Object.keys(localHooks).length > 0) {
-        merged.hooks = { ...globalHooks, ...localHooks };
+    if (Object.keys(globalHooks).length > 0 ||
+        Object.keys(perRepoHooks).length > 0 ||
+        Object.keys(localHooks).length > 0) {
+        merged.hooks = { ...globalHooks, ...perRepoHooks, ...localHooks };
     }
     return merged;
 }
@@ -61,6 +77,15 @@ export async function updateGlobalConfigKey(key, value, home = homedir()) {
     await saveGlobalConfig(nextConfig, home);
     return nextConfig;
 }
+export async function updateGlobalRepoConfigKey(repoRoot, key, value, home = homedir()) {
+    const loaded = await loadGlobalConfig(home);
+    const repos = isPlainObject(loaded.config.repos) ? { ...loaded.config.repos } : {};
+    const existing = isPlainObject(repos[repoRoot]) ? repos[repoRoot] : {};
+    repos[repoRoot] = { ...existing, [key]: value };
+    const nextConfig = { ...loaded.config, repos };
+    await saveGlobalConfig(nextConfig, home);
+    return nextConfig;
+}
 export function GLOBAL_CONFIG_FILE_PATH(home = homedir()) {
     return join(home, GLOBAL_CONFIG_DIRECTORY, GLOBAL_CONFIG_NAME);
 }
@@ -99,6 +124,22 @@ function mergeConfig(...values) {
         ...value,
     }), { ...DEFAULT_CONFIG });
 }
+function findPerRepoConfig(repos, repoRoot, home) {
+    for (const [key, value] of Object.entries(repos)) {
+        const expandedKey = expandTilde(key, home);
+        if (expandedKey === repoRoot && isPlainObject(value)) {
+            return value;
+        }
+    }
+    return {};
+}
+function expandTilde(value, home) {
+    if (value === '~')
+        return home;
+    if (value.startsWith('~/'))
+        return join(home, value.slice(2));
+    return value;
+}
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/dist/init.d.ts

@@ -1,6 +1,9 @@
 export type SupportedShell = 'bash' | 'fish' | 'zsh';
+export type InstallSaveTarget = 'local' | 'global';
 export interface InitCommandOptions {
     cwd: string;
+    home?: string;
+    promptForInstallSaveTarget?: () => Promise<InstallSaveTarget | null>;
     shell?: string;
     stderr?: (chunk: string) => void;
     stdout: (chunk: string) => void;

package/dist/init.js

@@ -1,6 +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';
 const START_MARKER = '# >>> gji init >>>';
 const END_MARKER = '# <<< gji init <<<';
 const SHELL_WRAPPED_COMMANDS = [
@@ -42,6 +44,7 @@ const SHELL_WRAPPED_COMMANDS = [
 ];
 export async function runInitCommand(options) {
     const shell = resolveShell(options.shell, process.env.SHELL);
+    const home = options.home ?? homedir();
     if (!shell) {
         options.stderr?.('Unable to detect a supported shell. Specify one explicitly: bash, fish, or zsh.\n');
         return 1;
@@ -51,12 +54,25 @@ export async function runInitCommand(options) {
         options.stdout(script);
         return 0;
     }
-    const rcPath = resolveShellConfigPath(shell, homedir());
+    const rcPath = resolveShellConfigPath(shell, home);
     await mkdir(dirname(rcPath), { recursive: true });
     const current = await readExistingConfig(rcPath);
     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.
+    const { config: globalConfig } = await loadGlobalConfig(home);
+    const hasCustomPrompt = options.promptForInstallSaveTarget !== 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);
+        }
+    }
     return 0;
 }
 export function renderShellIntegration(shell) {
@@ -195,3 +211,16 @@ 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?',
+        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' },
+        ],
+    });
+    if (isCancel(choice)) {
+        return null;
+    }
+    return choice;
+}

package/dist/install-prompt.d.ts

@@ -6,5 +6,6 @@ export interface InstallPromptDependencies {
     promptForInstallChoice?: (pm: PackageManager) => Promise<InstallChoice | null>;
     runInstallCommand?: (command: string, cwd: string, stderr: (chunk: string) => void) => Promise<void>;
     writeConfigKey?: (root: string, key: string, value: unknown) => Promise<void>;
+    writeGlobalRepoConfigKey?: (repoRoot: string, key: string, value: unknown) => Promise<void>;
 }
 export declare function maybeRunInstallPrompt(worktreePath: string, repoRoot: string, config: GjiConfig, stderr: (chunk: string) => void, dependencies?: InstallPromptDependencies, nonInteractive?: boolean): Promise<void>;

package/dist/install-prompt.js

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { isCancel, select } from '@clack/prompts';
-import { loadConfig, updateLocalConfigKey } from './config.js';
+import { loadConfig, loadGlobalConfig, updateGlobalRepoConfigKey, updateLocalConfigKey } from './config.js';
 import { isHeadless } from './headless.js';
 import { detectPackageManager } from './package-manager.js';
 export async function maybeRunInstallPrompt(worktreePath, repoRoot, config, stderr, dependencies = {}, nonInteractive = false) {
@@ -36,13 +36,22 @@ export async function maybeRunInstallPrompt(worktreePath, repoRoot, config, stde
             stderr(`gji: install command failed: ${error instanceof Error ? error.message : String(error)}\n`);
         }
     }
+    const saveGlobal = config.installSaveTarget === 'global';
     const writeKey = dependencies.writeConfigKey ?? defaultWriteConfigKey;
+    const writeGlobalKey = dependencies.writeGlobalRepoConfigKey ?? defaultWriteGlobalRepoConfigKey;
     if (choice === 'always') {
         try {
-            // Read local config hooks to deep-merge so other hook keys (e.g. afterEnter) are preserved.
-            const { config: localConfig } = await loadConfig(repoRoot);
-            const existingLocalHooks = isPlainObject(localConfig.hooks) ? localConfig.hooks : {};
-            await writeKey(repoRoot, 'hooks', { ...existingLocalHooks, afterCreate: pm.installCommand });
+            if (saveGlobal) {
+                // Deep-merge with any existing per-repo global hooks so other keys are preserved.
+                const existingHooks = await loadExistingGlobalRepoHooks(repoRoot);
+                await writeGlobalKey(repoRoot, 'hooks', { ...existingHooks, afterCreate: pm.installCommand });
+            }
+            else {
+                // Read local config hooks to deep-merge so other hook keys (e.g. afterEnter) are preserved.
+                const { config: localConfig } = await loadConfig(repoRoot);
+                const existingLocalHooks = isPlainObject(localConfig.hooks) ? localConfig.hooks : {};
+                await writeKey(repoRoot, 'hooks', { ...existingLocalHooks, afterCreate: pm.installCommand });
+            }
         }
         catch (error) {
             stderr(`gji: failed to save config: ${error instanceof Error ? error.message : String(error)}\n`);
@@ -50,7 +59,12 @@ export async function maybeRunInstallPrompt(worktreePath, repoRoot, config, stde
     }
     if (choice === 'never') {
         try {
-            await writeKey(repoRoot, 'skipInstallPrompt', true);
+            if (saveGlobal) {
+                await writeGlobalKey(repoRoot, 'skipInstallPrompt', true);
+            }
+            else {
+                await writeKey(repoRoot, 'skipInstallPrompt', true);
+            }
         }
         catch (error) {
             stderr(`gji: failed to save config: ${error instanceof Error ? error.message : String(error)}\n`);
@@ -79,6 +93,15 @@ async function defaultRunInstallCommand(command, cwd, stderr) {
 async function defaultWriteConfigKey(root, key, value) {
     await updateLocalConfigKey(root, key, value);
 }
+async function defaultWriteGlobalRepoConfigKey(repoRoot, key, value) {
+    await updateGlobalRepoConfigKey(repoRoot, key, value);
+}
+async function loadExistingGlobalRepoHooks(repoRoot) {
+    const { config: globalConfig } = await loadGlobalConfig();
+    const repos = isPlainObject(globalConfig.repos) ? globalConfig.repos : {};
+    const perRepo = isPlainObject(repos[repoRoot]) ? repos[repoRoot] : {};
+    return isPlainObject(perRepo.hooks) ? perRepo.hooks : {};
+}
 async function defaultPromptForInstallChoice(pm) {
     const choice = await select({
         message: `Run \`${pm.installCommand}\` in the new worktree?`,

package/dist/new.js

@@ -58,6 +58,7 @@ export function createNewCommand(dependencies = {}) {
                 else {
                     options.stderr(`gji new: ${message} in non-interactive mode (GJI_NO_TUI=1)\n`);
                     options.stderr(`Hint: Use 'gji remove ${worktreeName}' or 'gji clean' to remove the existing worktree\n`);
+                    options.stderr(`Hint: Use 'gji trigger-hook afterCreate' inside the worktree to re-run setup hooks\n`);
                 }
                 return 1;
             }

package/dist/trigger-hook.d.ts

@@ -0,0 +1,6 @@
+export interface TriggerHookCommandOptions {
+    cwd: string;
+    hook: string;
+    stderr: (chunk: string) => void;
+}
+export declare function runTriggerHookCommand(options: TriggerHookCommandOptions): Promise<number>;

package/dist/trigger-hook.js

@@ -0,0 +1,26 @@
+import { loadEffectiveConfig } from './config.js';
+import { extractHooks, runHook } from './hooks.js';
+import { detectRepository, listWorktrees } from './repo.js';
+const VALID_HOOKS = ['afterCreate', 'afterEnter', 'beforeRemove'];
+function isValidHook(hook) {
+    return VALID_HOOKS.includes(hook);
+}
+export async function runTriggerHookCommand(options) {
+    if (!isValidHook(options.hook)) {
+        options.stderr(`gji trigger-hook: unknown hook '${options.hook}'. Valid hooks: ${VALID_HOOKS.join(', ')}\n`);
+        return 1;
+    }
+    const hookName = options.hook;
+    const repository = await detectRepository(options.cwd);
+    const config = await loadEffectiveConfig(repository.repoRoot);
+    const hooks = extractHooks(config);
+    // Find the branch for the current worktree (undefined for detached HEAD).
+    const worktrees = await listWorktrees(options.cwd);
+    const currentWorktree = worktrees.find((w) => w.path === repository.currentRoot);
+    await runHook(hooks[hookName], repository.currentRoot, {
+        branch: currentWorktree?.branch ?? undefined,
+        path: repository.currentRoot,
+        repo: repository.repoName,
+    }, options.stderr);
+    return 0;
+}

package/package.json

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