@solaqua/gji 0.4.0 → 0.5.0

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-back.1

@@ -0,0 +1,13 @@
+.TH GJI\-BACK 1 "May 2026" "gji 0.5.0" "User Commands"
+.SH NAME
+gji\-back \- navigate to the previously visited worktree, optionally N steps back
+.SH SYNOPSIS
+.B gji back [\fIoptions\fR] [options] [n]
+.SH DESCRIPTION
+navigate to the previously visited worktree, optionally N steps back
+.SH OPTIONS
+.TP
+.B \-\-print
+print the resolved worktree path explicitly
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-clean.1

@@ -1,4 +1,4 @@
-.TH GJI\-CLEAN 1 "April 2026" "gji 0.4.0" "User Commands"
+.TH GJI\-CLEAN 1 "May 2026" "gji 0.5.0" "User Commands"
 .SH NAME
 gji\-clean \- interactively prune linked worktrees
 .SH SYNOPSIS
@@ -10,6 +10,9 @@ interactively prune linked worktrees
 .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

package/man/man1/gji-completion.1

@@ -0,0 +1,9 @@
+.TH GJI\-COMPLETION 1 "May 2026" "gji 0.5.0" "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

@@ -1,4 +1,4 @@
-.TH GJI\-CONFIG 1 "April 2026" "gji 0.4.0" "User Commands"
+.TH GJI\-CONFIG 1 "May 2026" "gji 0.5.0" "User Commands"
 .SH NAME
 gji\-config \- manage global config defaults
 .SH SYNOPSIS

package/man/man1/gji-go.1

@@ -1,4 +1,4 @@
-.TH GJI\-GO 1 "April 2026" "gji 0.4.0" "User Commands"
+.TH GJI\-GO 1 "May 2026" "gji 0.5.0" "User Commands"
 .SH NAME
 gji\-go \- print or select a worktree path
 .SH SYNOPSIS

package/man/man1/gji-history.1

@@ -0,0 +1,13 @@
+.TH GJI\-HISTORY 1 "May 2026" "gji 0.5.0" "User Commands"
+.SH NAME
+gji\-history \- show navigation history
+.SH SYNOPSIS
+.B gji history [\fIoptions\fR] [options]
+.SH DESCRIPTION
+show navigation history
+.SH OPTIONS
+.TP
+.B \-\-json
+print history as JSON
+.SH "SEE ALSO"
+.BR gji (1)

package/man/man1/gji-init.1

@@ -1,4 +1,4 @@
-.TH GJI\-INIT 1 "April 2026" "gji 0.4.0" "User Commands"
+.TH GJI\-INIT 1 "May 2026" "gji 0.5.0" "User Commands"
 .SH NAME
 gji\-init \- print or install shell integration
 .SH SYNOPSIS

package/man/man1/gji-ls.1

@@ -1,4 +1,4 @@
-.TH GJI\-LS 1 "April 2026" "gji 0.4.0" "User Commands"
+.TH GJI\-LS 1 "May 2026" "gji 0.5.0" "User Commands"
 .SH NAME
 gji\-ls \- list active worktrees
 .SH SYNOPSIS
@@ -7,6 +7,9 @@ gji\-ls \- list active worktrees
 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"

package/man/man1/gji-new.1

@@ -1,4 +1,4 @@
-.TH GJI\-NEW 1 "April 2026" "gji 0.4.0" "User Commands"
+.TH GJI\-NEW 1 "May 2026" "gji 0.5.0" "User Commands"
 .SH NAME
 gji\-new \- create a new branch or detached linked worktree
 .SH SYNOPSIS

package/man/man1/gji-pr.1

@@ -1,4 +1,4 @@
-.TH GJI\-PR 1 "April 2026" "gji 0.4.0" "User Commands"
+.TH GJI\-PR 1 "May 2026" "gji 0.5.0" "User Commands"
 .SH NAME
 gji\-pr \- fetch a pull request by number, #number, or URL into a linked worktree
 .SH SYNOPSIS

package/man/man1/gji-remove.1

@@ -1,4 +1,4 @@
-.TH GJI\-REMOVE 1 "April 2026" "gji 0.4.0" "User Commands"
+.TH GJI\-REMOVE 1 "May 2026" "gji 0.5.0" "User Commands"
 .SH NAME
 gji\-remove \- remove a linked worktree and delete its branch when present
 .SH SYNOPSIS

package/man/man1/gji-root.1

@@ -1,4 +1,4 @@
-.TH GJI\-ROOT 1 "April 2026" "gji 0.4.0" "User Commands"
+.TH GJI\-ROOT 1 "May 2026" "gji 0.5.0" "User Commands"
 .SH NAME
 gji\-root \- print the main repository root path
 .SH SYNOPSIS

package/man/man1/gji-status.1

@@ -1,4 +1,4 @@
-.TH GJI\-STATUS 1 "April 2026" "gji 0.4.0" "User Commands"
+.TH GJI\-STATUS 1 "May 2026" "gji 0.5.0" "User Commands"
 .SH NAME
 gji\-status \- summarize repository and worktree health
 .SH SYNOPSIS

package/man/man1/gji-sync.1

@@ -1,4 +1,4 @@
-.TH GJI\-SYNC 1 "April 2026" "gji 0.4.0" "User Commands"
+.TH GJI\-SYNC 1 "May 2026" "gji 0.5.0" "User Commands"
 .SH NAME
 gji\-sync \- fetch and update one or all worktrees
 .SH SYNOPSIS

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

@@ -1,4 +1,4 @@
-.TH GJI\-TRIGGER\-HOOK 1 "April 2026" "gji 0.4.0" "User Commands"
+.TH GJI\-TRIGGER\-HOOK 1 "May 2026" "gji 0.5.0" "User Commands"
 .SH NAME
 gji\-trigger\-hook \- run a named hook (afterCreate, afterEnter, beforeRemove) in the current worktree
 .SH SYNOPSIS

package/man/man1/gji.1

@@ -1,4 +1,4 @@
-.TH GJI 1 "April 2026" "gji 0.4.0" "User Commands"
+.TH GJI 1 "May 2026" "gji 0.5.0" "User Commands"
 .SH NAME
 gji \- Context switching without the mess.
 .SH SYNOPSIS
@@ -17,9 +17,18 @@ create a new branch or detached linked worktree
 .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 back [options] [n]
+navigate to the previously visited worktree, optionally N steps back
+.TP
+.B history [options]
+show navigation history
+.TP
 .B go [options] [branch]
 print or select a worktree path
 .TP
@@ -55,7 +64,10 @@ 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\-back (1),
+.BR gji\-history (1),
 .BR gji\-go (1),
 .BR gji\-root (1),
 .BR gji\-status (1),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solaqua/gji",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Git worktree CLI for fast context switching.",
   "license": "MIT",
   "author": "sjquant",
@@ -42,7 +42,11 @@
   },
   "scripts": {
     "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
+    "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"
@@ -50,11 +54,16 @@
   "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"]
   }
 }