@solaqua/gji 0.3.0 → 0.4.1

package/dist/shell.js

@@ -0,0 +1,21 @@
+export function resolveSupportedShell(requestedShell, detectedShell) {
+    const requested = normalizeShell(requestedShell);
+    if (requested) {
+        return requested;
+    }
+    return normalizeShell(detectedShell);
+}
+function normalizeShell(value) {
+    if (!value) {
+        return null;
+    }
+    const candidate = value.split('/').at(-1)?.toLowerCase();
+    switch (candidate) {
+        case 'bash':
+        case 'fish':
+        case 'zsh':
+            return candidate;
+        default:
+            return null;
+    }
+}

package/dist/sync.js

@@ -1,5 +1,5 @@
 import { loadEffectiveConfig } from './config.js';
-import { isDirtyWorktree, runGit } from './git.js';
+import { isDirtyWorktree, resolveRemoteDefaultBranch, runGit } from './git.js';
 import { comparePaths } from './paths.js';
 import { detectRepository, listWorktrees } from './repo.js';
 export async function runSyncCommand(options) {
@@ -10,7 +10,7 @@ export async function runSyncCommand(options) {
     let defaultBranch;
     try {
         defaultBranch = resolveConfiguredString(config.syncDefaultBranch)
-            ?? await resolveDefaultBranch(repository.repoRoot, remote);
+            ?? await resolveRemoteDefaultBranch(repository.repoRoot, remote);
     }
     catch {
         emitError(options, `Unable to reach remote '${remote}'`);
@@ -89,17 +89,6 @@ function selectTargetWorktrees(worktrees, currentRoot, all) {
     }
     return [currentWorktree];
 }
-async function resolveDefaultBranch(repoRoot, remote) {
-    const stdout = await runGit(repoRoot, ['ls-remote', '--symref', remote, 'HEAD']);
-    const refLine = stdout
-        .split('\n')
-        .find((line) => line.startsWith('ref: refs/heads/'));
-    if (!refLine) {
-        return null;
-    }
-    const match = /^ref: refs\/heads\/(.+)\tHEAD$/.exec(refLine);
-    return match?.[1] ?? null;
-}
 function resolveConfiguredString(value) {
     return typeof value === 'string' && value.length > 0 ? value : null;
 }

package/dist/worktree-info.d.ts

@@ -0,0 +1,33 @@
+import { type WorktreeHealth } from './git.js';
+import type { WorktreeEntry } from './repo.js';
+export interface WorktreeInfo extends WorktreeEntry {
+    lastCommitTimestamp: number | null;
+    status: WorktreeHealth['status'] | 'unknown';
+    upstream: UpstreamState;
+}
+export interface SerializedWorktreeInfo {
+    branch: string | null;
+    lastCommitTimestamp: number | null;
+    path: string;
+    status: WorktreeInfo['status'];
+    upstream: UpstreamState;
+}
+export type UpstreamState = {
+    kind: 'detached';
+} | {
+    kind: 'no-upstream';
+} | {
+    kind: 'stale';
+} | {
+    kind: 'tracked';
+    ahead: number;
+    behind: number;
+} | {
+    kind: 'unknown';
+};
+export declare function readWorktreeInfos(worktrees: WorktreeEntry[]): Promise<WorktreeInfo[]>;
+export declare function serializeWorktreeInfo(info: WorktreeInfo): SerializedWorktreeInfo;
+export declare function formatWorktreeHint(info: WorktreeInfo): string;
+export declare function formatUpstreamState(upstream: UpstreamState): string;
+export declare function formatLastCommit(timestampSeconds: number | null): string;
+export declare function formatRelativeAge(timestampSeconds: number): string;

package/dist/worktree-info.js

@@ -0,0 +1,105 @@
+import { readBranchLastCommitTimestamp, readWorktreeHealth } from './git.js';
+export async function readWorktreeInfos(worktrees) {
+    return Promise.all(worktrees.map((worktree) => readWorktreeInfo(worktree)));
+}
+async function readWorktreeInfo(worktree) {
+    const [healthResult, lastCommitResult] = await Promise.allSettled([
+        readWorktreeHealth(worktree.path),
+        worktree.branch === null ? null : readBranchLastCommitTimestamp(worktree.path, worktree.branch),
+    ]);
+    const health = healthResult.status === 'fulfilled' ? healthResult.value : null;
+    const lastCommitTimestamp = lastCommitResult.status === 'fulfilled'
+        ? lastCommitResult.value
+        : null;
+    return {
+        ...worktree,
+        lastCommitTimestamp,
+        status: health?.status ?? 'unknown',
+        upstream: buildUpstreamState(worktree.branch, health),
+    };
+}
+function buildUpstreamState(branch, health) {
+    if (branch === null) {
+        return { kind: 'detached' };
+    }
+    if (health === null) {
+        return { kind: 'unknown' };
+    }
+    if (!health.hasUpstream) {
+        return { kind: 'no-upstream' };
+    }
+    if (health.upstreamGone) {
+        return { kind: 'stale' };
+    }
+    return {
+        ahead: health.ahead,
+        behind: health.behind,
+        kind: 'tracked',
+    };
+}
+export function serializeWorktreeInfo(info) {
+    return {
+        branch: info.branch,
+        lastCommitTimestamp: info.lastCommitTimestamp,
+        path: info.path,
+        status: info.status,
+        upstream: info.upstream,
+    };
+}
+export function formatWorktreeHint(info) {
+    const details = [
+        `status: ${info.status}`,
+        `upstream: ${formatUpstreamState(info.upstream)}`,
+    ];
+    if (info.lastCommitTimestamp !== null) {
+        details.push(`last: ${formatRelativeAge(info.lastCommitTimestamp)}`);
+    }
+    return `${info.path} (${details.join(', ')})`;
+}
+export function formatUpstreamState(upstream) {
+    if (upstream.kind === 'detached') {
+        return 'n/a';
+    }
+    if (upstream.kind === 'no-upstream') {
+        return 'no-upstream';
+    }
+    if (upstream.kind === 'stale') {
+        return 'gone';
+    }
+    if (upstream.kind === 'unknown') {
+        return 'unknown';
+    }
+    return formatAheadBehind(upstream.ahead, upstream.behind);
+}
+function formatAheadBehind(ahead, behind) {
+    if (ahead === 0 && behind === 0) {
+        return 'up to date';
+    }
+    if (ahead === 0) {
+        return `behind ${behind}`;
+    }
+    if (behind === 0) {
+        return `ahead ${ahead}`;
+    }
+    return `ahead ${ahead}, behind ${behind}`;
+}
+export function formatLastCommit(timestampSeconds) {
+    return timestampSeconds === null ? 'n/a' : formatRelativeAge(timestampSeconds);
+}
+export function formatRelativeAge(timestampSeconds) {
+    const ageSeconds = Math.max(0, Math.floor(Date.now() / 1000) - timestampSeconds);
+    const units = [
+        { label: 'y', seconds: 365 * 24 * 60 * 60 },
+        { label: 'mo', seconds: 30 * 24 * 60 * 60 },
+        { label: 'd', seconds: 24 * 60 * 60 },
+        { label: 'h', seconds: 60 * 60 },
+        { label: 'm', seconds: 60 },
+    ];
+    for (const unit of units) {
+        const value = Math.floor(ageSeconds / unit.seconds);
+        if (value > 0) {
+            return `${value}${unit.label} ago`;
+        }
+    }
+    return 'just now';
+}

package/man/man1/gji-clean.1

@@ -0,0 +1,22 @@
+.TH GJI\-CLEAN 1 "May 2026" "gji 0.4.1" "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 \-\-stale
+only target clean worktrees whose upstream is gone and branch is merged into the default 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-completion.1

@@ -0,0 +1,9 @@
+.TH GJI\-COMPLETION 1 "May 2026" "gji 0.4.1" "User Commands"
+.SH NAME
+gji\-completion \- print shell completion definitions
+.SH SYNOPSIS
+.B gji completion [options] [shell]
+.SH DESCRIPTION
+print shell completion definitions
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-config.1

@@ -0,0 +1,19 @@
+.TH GJI\-CONFIG 1 "May 2026" "gji 0.4.1" "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 "May 2026" "gji 0.4.1" "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 "May 2026" "gji 0.4.1" "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,16 @@
+.TH GJI\-LS 1 "May 2026" "gji 0.4.1" "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 \-\-compact
+show only branch and path columns
+.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 "May 2026" "gji 0.4.1" "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 "May 2026" "gji 0.4.1" "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 "May 2026" "gji 0.4.1" "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 "May 2026" "gji 0.4.1" "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 "May 2026" "gji 0.4.1" "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 "May 2026" "gji 0.4.1" "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 "May 2026" "gji 0.4.1" "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,71 @@
+.TH GJI 1 "May 2026" "gji 0.4.1" "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 completion [options] [shell]
+print shell completion definitions
+.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\-completion (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.1",
   "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,18 +42,28 @@
   },
   "scripts": {
     "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
-    "prepublishOnly": "pnpm test && pnpm build",
+    "generate:readme-demos": "node scripts/generate-readme-demos.mjs",
+    "bundle": "node scripts/bundle.mjs",
+    "generate-man": "node scripts/generate-man.mjs",
+    "docs:build": "pnpm --dir website build",
+    "docs:start": "pnpm --dir website start",
+    "prepublishOnly": "pnpm test && pnpm build && pnpm generate-man",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest"
   },
   "dependencies": {
     "@clack/core": "0.5.0",
     "@clack/prompts": "^0.11.0",
-    "commander": "^14.0.1"
+    "commander": "^14.0.1",
+    "update-notifier": "^7.3.1"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",
+    "esbuild": "^0.27.0",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild"]
   }
 }