@solaqua/gji 0.3.0 → 0.4.0

package/dist/cli.js

@@ -152,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.js

@@ -8,6 +8,7 @@ export const KNOWN_CONFIG_KEYS = new Set([
     'branchPrefix',
     'hooks',
     'installSaveTarget',
+    'shellIntegration',
     'skipInstallPrompt',
     'syncDefaultBranch',
     'syncFiles',

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/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.3.0",
+  "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"
   },