@errhythm/gitmux 1.6.6 → 1.6.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@errhythm/gitmux",
-  "version": "1.6.6",
+  "version": "1.6.12",
   "description": "Multi-repo Git & GitLab workflow CLI — switch branches, manage epics & issues, create MRs, all from the terminal",
   "type": "module",
   "bin": {
@@ -11,6 +11,10 @@
     "bin",
     "src"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/errhythm/gitmux.git"
+  },
   "engines": {
     "node": ">=22.13.0"
   },
@@ -30,14 +34,23 @@
   "license": "MIT",
   "main": "src/main.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"No tests specified yet\""
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
   },
   "dependencies": {
     "@inquirer/prompts": "^8.3.0",
+    "ansi-styles": "^6.2.3",
     "boxen": "^8.0.1",
     "chalk": "^5.6.2",
     "enquirer": "^2.4.1",
-    "figlet": "^1.10.0",
-    "listr2": "^10.2.1"
+    "figlet": "^1.11.0",
+    "get-east-asian-width": "^1.5.0",
+    "listr2": "^10.2.1",
+    "string-width": "^8.2.0",
+    "strip-ansi": "^7.2.0",
+    "wrap-ansi": "^10.0.0"
   }
 }

package/src/commands/portal.js

@@ -17,6 +17,7 @@ import {
   isGitLabRemote,
   detectGroupFromRepos,
   getProjectPath,
+  getDefaultBranch,
   slugify,
 } from "../gitlab/helpers.js";
 import { loadConfig, saveConfig } from "../config/index.js";
@@ -263,6 +264,11 @@ async function cmdIssueView(issue, glabRepos = [], portalConfig = {}) {
         name: p.purple("⊞  Create merge request"),
         description: p.muted("MR from ") + colorBranch(currentPrimary) + p.muted(" → default base branch"),
       }] : []),
+      {
+        value: "createBranch",
+        name: p.green("+  Create branch"),
+        description: p.muted("create a new branch for this issue"),
+      },
       {
         value: "open",
         name: p.teal("⊕  View in GitLab"),
@@ -286,6 +292,63 @@ async function cmdIssueView(issue, glabRepos = [], portalConfig = {}) {
     return;
   }
 
+  // Create a new branch for this issue
+  if (issueAction === "createBranch") {
+    const localRepo = findLocalRepo(glabRepos, projectPath);
+    const projectDefaultBranch = localRepo ? getDefaultBranch(localRepo.repo) : null;
+    const defaultBranchName = `feature/${localIid}-${slugify(issue.title)}`;
+
+    const { branchName } = await enquirer.prompt({
+      type: "input",
+      name: "branchName",
+      message: p.white("Branch name:"),
+      initial: defaultBranchName,
+      validate: (v) => v.trim() !== "" || "Branch name cannot be empty",
+    });
+
+    const { baseBranchName } = await enquirer.prompt({
+      type: "input",
+      name: "baseBranchName",
+      message: p.white("Base branch:"),
+      initial: projectDefaultBranch || portalConfig.defaultBaseBranch || "develop",
+      validate: (v) => v.trim() !== "" || "Base branch cannot be empty",
+    });
+
+    const enc = encodeURIComponent(projectPath);
+    process.stdout.write("  " + p.muted("Creating branch…\r"));
+    try {
+      await glabApi(`projects/${enc}/repository/branches`, {
+        method: "POST",
+        fields: { branch: branchName.trim(), ref: baseBranchName.trim() },
+      });
+      process.stdout.write(" ".repeat(40) + "\r");
+      console.log(
+        boxen(
+          chalk.bold(p.green("✔  Branch created")) + "  " + colorBranch(branchName.trim()),
+          { padding: { top: 0, bottom: 0, left: 2, right: 2 }, borderStyle: "round", borderColor: "#4ade80" },
+        ),
+      );
+      // Auto-set as primary if none is set yet
+      const cfgNow = loadConfig();
+      const pb = cfgNow.portal?.primaryBranches ?? {};
+      if (!pb[configKey]) {
+        pb[configKey] = branchName.trim();
+        saveConfig({ ...cfgNow, portal: { ...cfgNow.portal, primaryBranches: pb } });
+        console.log("  " + p.teal("★") + "  " + p.muted("Set as primary branch"));
+      }
+    } catch (e) {
+      process.stdout.write(" ".repeat(40) + "\r");
+      console.log(
+        boxen(
+          chalk.bold(p.red("Branch creation failed")) + "\n\n" + p.muted(e.message.slice(0, 80)),
+          { padding: { top: 0, bottom: 0, left: 2, right: 2 }, borderStyle: "round", borderColor: "#f87171" },
+        ),
+      );
+    }
+    console.log();
+    return;
+  }
+
   // Set primary branch
   const primaryChoice = await search({
     message: p.white("Set primary branch:"),
@@ -477,62 +540,62 @@ async function cmdEpicMr(epicIssues, glabRepos, portalConfig, { autoConfirm = fa
       console.log();
     }
   } else {
-  // Multi-select: all ready repos pre-selected, space to toggle, Esc to go back
-  const choices = ready.map((c) => ({
-    name: c.localRepo.name,
-    value: c.localRepo.name,
-    message: chalk.bold(p.white(c.localRepo.name)) + "  " + colorBranch(c.primary),
-    hint: "",
-    enabled: true,  // pre-select all
-  }));
-
-  const selectedNames = await enquirer.autocomplete({
-    name: "repos",
-    message: "Select repos to create MRs for:",
-    multiple: true,
-    initial: 0,
-    limit: 12,
-    choices,
-    symbols: { indicator: { on: "◉", off: "◯" } },
-    footer() { return p.muted("space to toggle · type to filter · enter to confirm · esc to go back"); },
-    suggest(input = "", allChoices = []) {
-      const term = (input ?? "").toLowerCase().trim();
-      const selected = allChoices.filter((c) => c.enabled);
-      const unselected = allChoices.filter((c) => !c.enabled);
-      const filtered = term ? unselected.filter((c) => c.value.toLowerCase().includes(term)) : unselected;
-      return [...selected, ...filtered];
-    },
-  }).catch(() => "__back__");
+    // Multi-select: all ready repos pre-selected, space to toggle, Esc to go back
+    const choices = ready.map((c) => ({
+      name: c.localRepo.name,
+      value: c.localRepo.name,
+      message: chalk.bold(p.white(c.localRepo.name)) + "  " + colorBranch(c.primary),
+      hint: "",
+      enabled: true,  // pre-select all
+    }));
+
+    const selectedNames = await enquirer.autocomplete({
+      name: "repos",
+      message: "Select repos to create MRs for:",
+      multiple: true,
+      initial: 0,
+      limit: 12,
+      choices,
+      symbols: { indicator: { on: "◉", off: "◯" } },
+      footer() { return p.muted("space to toggle · type to filter · enter to confirm · esc to go back"); },
+      suggest(input = "", allChoices = []) {
+        const term = (input ?? "").toLowerCase().trim();
+        const selected = allChoices.filter((c) => c.enabled);
+        const unselected = allChoices.filter((c) => !c.enabled);
+        const filtered = term ? unselected.filter((c) => c.value.toLowerCase().includes(term)) : unselected;
+        return [...selected, ...filtered];
+      },
+    }).catch(() => "__back__");
 
-  console.log();
-  if (selectedNames === "__back__" || !Array.isArray(selectedNames) || selectedNames.length === 0) {
-    if (selectedNames !== "__back__") console.log("  " + p.muted("Nothing selected.\n"));
-    return;
-  }
+    console.log();
+    if (selectedNames === "__back__" || !Array.isArray(selectedNames) || selectedNames.length === 0) {
+      if (selectedNames !== "__back__") console.log("  " + p.muted("Nothing selected.\n"));
+      return;
+    }
 
-  selectedReady = selectedNames
-    .map((name) => ready.find((c) => c.localRepo.name === name))
-    .filter(Boolean);
+    selectedReady = selectedNames
+      .map((name) => ready.find((c) => c.localRepo.name === name))
+      .filter(Boolean);
   } // end autoConfirm / interactive split
 
   // Shared options — prompt once for all (skip prompts when auto-confirming)
   const targetBranch = autoConfirm
     ? (portalConfig.defaultBaseBranch ?? "develop")
     : (await enquirer.prompt({
-        type: "input",
-        name: "targetBranch",
-        message: p.white("Target branch") + p.muted(" (for all):"),
-        initial: portalConfig.defaultBaseBranch ?? "develop",
-        validate: (v) => v.trim() !== "" || "Required",
-      })).targetBranch;
+      type: "input",
+      name: "targetBranch",
+      message: p.white("Target branch") + p.muted(" (for all):"),
+      initial: portalConfig.defaultBaseBranch ?? "develop",
+      validate: (v) => v.trim() !== "" || "Required",
+    })).targetBranch;
 
   const labels = autoConfirm
     ? (portalConfig.defaultLabels ?? "")
     : await input({
-        message: p.white("Labels") + p.muted(" (optional, applied to all):"),
-        default: portalConfig.defaultLabels ?? "",
-        theme: { ...THEME, style: { ...THEME.style, answer: (s) => p.purple(s) } },
-      });
+      message: p.white("Labels") + p.muted(" (optional, applied to all):"),
+      default: portalConfig.defaultLabels ?? "",
+      theme: { ...THEME, style: { ...THEME.style, answer: (s) => p.purple(s) } },
+    });
 
   const isDraft = autoConfirm
     ? false
@@ -547,9 +610,9 @@ async function cmdEpicMr(epicIssues, glabRepos, portalConfig, { autoConfirm = fa
   const confirmed = autoConfirm
     ? true
     : await confirm({
-        message: p.white("Create ") + p.cyan(String(selectedReady.length)) + p.white(` MR${selectedReady.length !== 1 ? "s" : ""}?`),
-        default: true, theme: THEME,
-      });
+      message: p.white("Create ") + p.cyan(String(selectedReady.length)) + p.white(` MR${selectedReady.length !== 1 ? "s" : ""}?`),
+      default: true, theme: THEME,
+    });
   console.log();
   if (!confirmed) return;
 
@@ -753,10 +816,10 @@ async function cmdEpicCheckout(epicIssues, glabRepos, { autoConfirm = false } =
   const confirmed = autoConfirm
     ? true
     : await confirm({
-        message: p.white("Checkout ") + p.cyan(String(checkouts.length)) + p.white(" repo" + (checkouts.length !== 1 ? "s" : "") + "?"),
-        default: true,
-        theme: THEME,
-      });
+      message: p.white("Checkout ") + p.cyan(String(checkouts.length)) + p.white(" repo" + (checkouts.length !== 1 ? "s" : "") + "?"),
+      default: true,
+      theme: THEME,
+    });
   console.log();
   if (!confirmed) return;
 
@@ -901,29 +964,29 @@ async function cmdEpicCrReview(epicIssues, glabRepos, portalConfig = {}) {
 // ── Main portal command ────────────────────────────────────────────────────────
 
 export async function cmdPortal(repos, {
-  settings    = false,
+  settings = false,
   // ── non-interactive opts ────────────────────────────────────────────────────────────
-  epic:             cliEpic      = null,  // --epic <iid>
-  checkout:         cliCheckout  = false, // --checkout
-  createMr:         cliCreateMr  = false, // --create-mr
-  createIssue:      cliCreateIssue = false, // --create-issue
-  review:           cliReview    = false, // --review
+  epic: cliEpic = null,  // --epic <iid>
+  checkout: cliCheckout = false, // --checkout
+  createMr: cliCreateMr = false, // --create-mr
+  createIssue: cliCreateIssue = false, // --create-issue
+  review: cliReview = false, // --review
   // shared
-  target:           cliTarget       = null, // --target
-  title:            cliTitle        = null, // --title (MR)
-  description:      cliDescription  = null,
-  labels:           cliLabels       = null,
-  draft:            cliDraft        = false,
-  noPush:           cliNoPush       = false,
+  target: cliTarget = null, // --target
+  title: cliTitle = null, // --title (MR)
+  description: cliDescription = null,
+  labels: cliLabels = null,
+  draft: cliDraft = false,
+  noPush: cliNoPush = false,
   // issue creation
-  issueProject:     cliIssueProject     = null,
-  issueTitle:       cliIssueTitle       = null,
+  issueProject: cliIssueProject = null,
+  issueTitle: cliIssueTitle = null,
   issueDescription: cliIssueDescription = null,
-  issueLabels:      cliIssueLabels      = null,
-  branchName:       cliBranchName       = null,
-  baseBranch:       cliBaseBranch       = null,
+  issueLabels: cliIssueLabels = null,
+  branchName: cliBranchName = null,
+  baseBranch: cliBaseBranch = null,
   // auto-confirm
-  yes:              autoConfirm         = false,
+  yes: autoConfirm = false,
 } = {}) {
   // Detect CodeRabbit CLI once up front
   const crAvailable = isCrAvailable();
@@ -933,28 +996,28 @@ export async function cmdPortal(repos, {
   try {
     execSync("glab version", { encoding: "utf8", stdio: "pipe" });
   } catch {
-    const isMac   = process.platform === "darwin";
-    const isWin   = process.platform === "win32";
+    const isMac = process.platform === "darwin";
+    const isWin = process.platform === "win32";
     const isLinux = process.platform === "linux";
 
     const platform = isMac ? "macOS" : isWin ? "Windows" : isLinux ? "Linux" : null;
 
     const installLines = isMac
       ? p.muted("  brew     ") + p.cyan("brew install glab") + "\n" +
-        p.muted("  MacPorts ") + p.cyan("sudo port install glab") + "\n" +
-        p.muted("  asdf     ") + p.cyan("asdf plugin add glab && asdf install glab latest")
+      p.muted("  MacPorts ") + p.cyan("sudo port install glab") + "\n" +
+      p.muted("  asdf     ") + p.cyan("asdf plugin add glab && asdf install glab latest")
       : isWin
-      ? p.muted("  winget   ") + p.cyan("winget install glab.glab") + "\n" +
+        ? p.muted("  winget   ") + p.cyan("winget install glab.glab") + "\n" +
         p.muted("  choco    ") + p.cyan("choco install glab") + "\n" +
         p.muted("  scoop    ") + p.cyan("scoop install glab") + "\n" +
         p.muted("  brew     ") + p.cyan("brew install glab") + p.muted("  (via WSL)")
-      : isLinux
-      ? p.muted("  brew     ") + p.cyan("brew install glab") + "\n" +
-        p.muted("  snap     ") + p.cyan("sudo snap install glab && sudo snap connect glab:ssh-keys") + "\n" +
-        p.muted("  apt      ") + p.cyan("sudo apt install glab") + p.muted("  (WakeMeOps repo)") + "\n" +
-        p.muted("  pacman   ") + p.cyan("pacman -S glab") + "\n" +
-        p.muted("  dnf      ") + p.cyan("dnf install glab")
-      : p.muted("  ") + p.cyan("https://gitlab.com/gitlab-org/cli#installation");
+        : isLinux
+          ? p.muted("  brew     ") + p.cyan("brew install glab") + "\n" +
+          p.muted("  snap     ") + p.cyan("sudo snap install glab && sudo snap connect glab:ssh-keys") + "\n" +
+          p.muted("  apt      ") + p.cyan("sudo apt install glab") + p.muted("  (WakeMeOps repo)") + "\n" +
+          p.muted("  pacman   ") + p.cyan("pacman -S glab") + "\n" +
+          p.muted("  dnf      ") + p.cyan("dnf install glab")
+          : p.muted("  ") + p.cyan("https://gitlab.com/gitlab-org/cli#installation");
 
     console.log(
       boxen(
@@ -1110,13 +1173,13 @@ export async function cmdPortal(repos, {
     // --create-mr via portal (non-interactive MR command)
     if (cliCreateMr && !cliEpic) {
       return await cmdMr(repos, {
-        target:      cliTarget,
-        title:       cliTitle,
+        target: cliTarget,
+        title: cliTitle,
         description: cliDescription,
-        labels:      cliLabels,
-        draft:       cliDraft,
-        noPush:      cliNoPush,
-        yes:         autoConfirm,
+        labels: cliLabels,
+        draft: cliDraft,
+        noPush: cliNoPush,
+        yes: autoConfirm,
       });
     }
 
@@ -1155,8 +1218,8 @@ export async function cmdPortal(repos, {
         // Bulk epic MR — override shared options in portalConfig for non-interactive
         const mergedPortalConfig = {
           ...portalConfig,
-          ...(cliTarget  ? { defaultBaseBranch: cliTarget } : {}),
-          ...(cliLabels  ? { defaultLabels: cliLabels }     : {}),
+          ...(cliTarget ? { defaultBaseBranch: cliTarget } : {}),
+          ...(cliLabels ? { defaultLabels: cliLabels } : {}),
         };
         return await cmdEpicMr(epicIssues, glabRepos, mergedPortalConfig, { autoConfirm });
       }
@@ -1297,13 +1360,13 @@ export async function cmdPortal(repos, {
 
     if (section === "mr") {
       const r = await cmdMr(repos, {
-        target:      cliTarget,
-        title:       cliTitle,
+        target: cliTarget,
+        title: cliTitle,
         description: cliDescription,
-        labels:      cliLabels,
-        draft:       cliDraft,
-        noPush:      cliNoPush,
-        yes:         autoConfirm,
+        labels: cliLabels,
+        draft: cliDraft,
+        noPush: cliNoPush,
+        yes: autoConfirm,
       });
       if (r !== "__back__") return r;
       continue portalHome;
@@ -1657,11 +1720,12 @@ export async function cmdPortal(repos, {
             validate: (v) => v.trim() !== "" || "Branch name cannot be empty",
           });
 
+          const projectDefaultBranch = getDefaultBranch(projectChoice.repo);
           const { baseBranchName } = await enquirer.prompt({
             type: "input",
             name: "baseBranchName",
             message: p.white("Base branch:"),
-            initial: portalConfig.defaultBaseBranch ?? "develop",
+            initial: projectDefaultBranch || portalConfig.defaultBaseBranch || "develop",
             validate: (v) => v.trim() !== "" || "Base branch cannot be empty",
           });
 

package/src/main.js

@@ -17,27 +17,32 @@ import { cmdSwitch } from "./commands/switch.js";
 import { cmdMr } from "./commands/mr.js";
 import { cmdPortal } from "./commands/portal.js";
 import { cmdSettings } from "./commands/settings.js";
+import { checkForUpdate, awaitUpdateCheck } from "./utils/update-check.js";
+
+// Kick off the update check in the background immediately so the network
+// request runs while the rest of startup happens.
+checkForUpdate();
 
 // ── Dependency checks ─────────────────────────────────────────────────────────
 
 function checkRequiredDeps() {
   // git — required by every command
   try { execSync("git --version", { stdio: "pipe" }); } catch {
-    const isMac   = process.platform === "darwin";
-    const isWin   = process.platform === "win32";
+    const isMac = process.platform === "darwin";
+    const isWin = process.platform === "win32";
     const isLinux = process.platform === "linux";
 
     const installLines = isMac
       ? p.muted("  brew   ") + p.cyan("brew install git") + "\n" +
-        p.muted("  direct ") + p.cyan("https://git-scm.com/download/mac")
+      p.muted("  direct ") + p.cyan("https://git-scm.com/download/mac")
       : isWin
-      ? p.muted("  winget ") + p.cyan("winget install --id Git.Git") + "\n" +
+        ? p.muted("  winget ") + p.cyan("winget install --id Git.Git") + "\n" +
         p.muted("  direct ") + p.cyan("https://git-scm.com/download/win")
-      : isLinux
-      ? p.muted("  apt    ") + p.cyan("sudo apt install git") + "\n" +
-        p.muted("  dnf    ") + p.cyan("sudo dnf install git") + "\n" +
-        p.muted("  pacman ") + p.cyan("sudo pacman -S git")
-      : p.muted("  ") + p.cyan("https://git-scm.com/downloads");
+        : isLinux
+          ? p.muted("  apt    ") + p.cyan("sudo apt install git") + "\n" +
+          p.muted("  dnf    ") + p.cyan("sudo dnf install git") + "\n" +
+          p.muted("  pacman ") + p.cyan("sudo pacman -S git")
+          : p.muted("  ") + p.cyan("https://git-scm.com/downloads");
 
     console.log(
       boxen(
@@ -45,10 +50,10 @@ function checkRequiredDeps() {
         p.white("gitmux requires git. Install it:\n\n") +
         installLines,
         {
-          padding:        { top: 1, bottom: 1, left: 3, right: 3 },
-          borderStyle:    "round",
-          borderColor:    "#f87171",
-          title:          p.red(" missing dependency: git "),
+          padding: { top: 1, bottom: 1, left: 3, right: 3 },
+          borderStyle: "round",
+          borderColor: "#f87171",
+          title: p.red(" missing dependency: git "),
           titleAlignment: "center",
         },
       ),
@@ -108,55 +113,55 @@ function parseArgs(rawArgs) {
     branch: isSubcmd ? (positional[1] ?? "") : first,
 
     // ── Switch flags ────────────────────────────────────────────────────────
-    pull:     flags.has("--pull")    || flags.has("-p"),
-    fuzzy:    flags.has("--fuzzy")   || flags.has("-f"),
-    create:   flags.has("--create")  || flags.has("-c"),
-    stash:    flags.has("--stash")   || flags.has("-s"),
-    fetch:    flags.has("--fetch"),
-    dryRun:   flags.has("--dry-run"),
+    pull: flags.has("--pull") || flags.has("-p"),
+    fuzzy: flags.has("--fuzzy") || flags.has("-f"),
+    create: flags.has("--create") || flags.has("-c"),
+    stash: flags.has("--stash") || flags.has("-s"),
+    fetch: flags.has("--fetch"),
+    dryRun: flags.has("--dry-run"),
 
     // ── Global ──────────────────────────────────────────────────────────────
-    version:  flags.has("--version") || flags.has("-v"),
-    help:     flags.has("--help")    || flags.has("-h"),
+    version: flags.has("--version") || flags.has("-v"),
+    help: flags.has("--help") || flags.has("-h"),
     settings: flags.has("--settings"),
-    debug:    flags.has("--debug"),
-    yes:      flags.has("--yes")     || flags.has("-y"),
-    depth:    parseInt(options.depth ?? String(DEFAULT_DEPTH), 10) || DEFAULT_DEPTH,
-    exclude:  options.exclude ?? null,
-    filter:   options.filter ?? null,
+    debug: flags.has("--debug"),
+    yes: flags.has("--yes") || flags.has("-y"),
+    depth: parseInt(options.depth ?? String(DEFAULT_DEPTH), 10) || DEFAULT_DEPTH,
+    exclude: options.exclude ?? null,
+    filter: options.filter ?? null,
 
     // ── MR flags ─────────────────────────────────────────────────────────────
     // --target / -t <branch>  — MR target branch
-    target:      options.target ?? options.t ?? null,
+    target: options.target ?? options.t ?? null,
     // --repo <name>  (repeatable) — restrict MR to these repos
-    mrRepos:     repos.length > 0 ? repos : null,
+    mrRepos: repos.length > 0 ? repos : null,
     // --title / --description / --labels — MR or issue metadata
-    title:       options.title       ?? null,
+    title: options.title ?? null,
     description: options.description ?? null,
-    labels:      options.labels      ?? null,
+    labels: options.labels ?? null,
     // --draft  — mark MR as draft
-    draft:       flags.has("--draft"),
+    draft: flags.has("--draft"),
     // --no-push  — skip git push before MR
-    noPush:      flags.has("--no-push"),
+    noPush: flags.has("--no-push"),
 
     // ── Portal flags ──────────────────────────────────────────────────────────
     // --epic <iid>  — select epic by IID non-interactively
-    epic:             options.epic             ?? null,
+    epic: options.epic ?? null,
     // --checkout  — run epic checkout without menus
-    checkout:         flags.has("--checkout"),
+    checkout: flags.has("--checkout"),
     // --create-mr  — create bulk MRs for epic without menus
-    createMr:         flags.has("--create-mr"),
+    createMr: flags.has("--create-mr"),
     // --create-issue  — go straight to issue creation
-    createIssue:      flags.has("--create-issue"),
+    createIssue: flags.has("--create-issue"),
     // --review  — run cr review on all primary branches of the epic
-    review:           flags.has("--review"),
+    review: flags.has("--review"),
     // Issue creation params
-    issueProject:     options.issueProject     ?? null,
-    issueTitle:       options.issueTitle       ?? null,
+    issueProject: options.issueProject ?? null,
+    issueTitle: options.issueTitle ?? null,
     issueDescription: options.issueDescription ?? null,
-    issueLabels:      options.issueLabels      ?? null,
-    branchName:       options.branchName       ?? null,
-    baseBranch:       options.baseBranch       ?? null,
+    issueLabels: options.issueLabels ?? null,
+    branchName: options.branchName ?? null,
+    baseBranch: options.baseBranch ?? null,
   };
 }
 
@@ -189,6 +194,27 @@ export async function main() {
   printLogo();
   checkRequiredDeps();
 
+  // Show update notice if available (result already fetched in background)
+  const updateInfo = await awaitUpdateCheck();
+  if (updateInfo) {
+    const notice =
+      chalk.green("◆") + "  " +
+      chalk.bold(p.white("update available")) + "  " +
+      p.muted("·") + "  " +
+      p.muted(updateInfo.current) + p.muted(" → ") + chalk.bold(p.green(updateInfo.latest)) + "  " +
+      p.muted("·") + "  " +
+      p.cyan(`npm i -g @errhythm/gitmux@${updateInfo.latest}`);
+
+    console.log(
+      boxen(notice, {
+        padding: { top: 0, bottom: 0, left: 2, right: 2 },
+        borderStyle: "round",
+        borderColor: "#22c55e",
+      }),
+    );
+    console.log();
+  }
+
   const cwd = process.cwd();
   let repos = findRepos(cwd, opts.depth);
 
@@ -246,38 +272,38 @@ export async function main() {
 
   if (opts.subcommand === "mr") {
     return await cmdMr(repos, {
-      target:      opts.target,
-      mrRepos:     opts.mrRepos,
-      title:       opts.title,
+      target: opts.target,
+      mrRepos: opts.mrRepos,
+      title: opts.title,
       description: opts.description,
-      labels:      opts.labels,
-      draft:       opts.draft,
-      noPush:      opts.noPush,
-      yes:         opts.yes,
+      labels: opts.labels,
+      draft: opts.draft,
+      noPush: opts.noPush,
+      yes: opts.yes,
     });
   }
 
   if (opts.subcommand === "portal") {
     return await cmdPortal(repos, {
-      settings:         opts.settings,
-      epic:             opts.epic,
-      checkout:         opts.checkout,
-      createMr:         opts.createMr,
-      createIssue:      opts.createIssue,
-      review:           opts.review,
-      target:           opts.target,
-      title:            opts.title,
-      description:      opts.description,
-      labels:           opts.labels,
-      draft:            opts.draft,
-      noPush:           opts.noPush,
-      issueProject:     opts.issueProject,
-      issueTitle:       opts.issueTitle,
+      settings: opts.settings,
+      epic: opts.epic,
+      checkout: opts.checkout,
+      createMr: opts.createMr,
+      createIssue: opts.createIssue,
+      review: opts.review,
+      target: opts.target,
+      title: opts.title,
+      description: opts.description,
+      labels: opts.labels,
+      draft: opts.draft,
+      noPush: opts.noPush,
+      issueProject: opts.issueProject,
+      issueTitle: opts.issueTitle,
       issueDescription: opts.issueDescription,
-      issueLabels:      opts.issueLabels,
-      branchName:       opts.branchName,
-      baseBranch:       opts.baseBranch,
-      yes:              opts.yes,
+      issueLabels: opts.issueLabels,
+      branchName: opts.branchName,
+      baseBranch: opts.baseBranch,
+      yes: opts.yes,
     });
   }
 
@@ -303,22 +329,31 @@ export async function main() {
       p.muted(` ${repos.length === 1 ? "repo" : "repos"} in scope\n`),
     );
 
-    // Mode selector — loop so "go back" from sub-commands returns here
+    // Helper to detect ESC / ExitPromptError from @inquirer/prompts
+    const isEsc = (e) => e?.name === "ExitPromptError";
+
+    // Mode selector — loop so ESC / "go back" from sub-commands returns here
     modeLoop: while (true) {
-      const mode = await select({
-        message: p.white("What do you want to do?"),
-        choices: [
-          {
-            value: "switch",
-            name: p.cyan("⇌  Switch branches") + p.muted("   checkout a branch across all repos"),
-          },
-          {
-            value: "portal",
-            name: chalk.hex("#FC6D26")("◈  GitLab") + p.muted("   development portal — epics, MRs & branches"),
-          },
-        ],
-        theme: THEME,
-      });
+      let mode;
+      try {
+        mode = await select({
+          message: p.white("What do you want to do?"),
+          choices: [
+            {
+              value: "switch",
+              name: p.cyan("⇌  Switch branches") + p.muted("   checkout a branch across all repos"),
+            },
+            {
+              value: "portal",
+              name: chalk.hex("#FC6D26")("◈  GitLab") + p.muted("   development portal — epics, MRs & branches"),
+            },
+          ],
+          theme: THEME,
+        });
+      } catch (e) {
+        if (isEsc(e)) { console.log("\n" + p.muted("  Exited.\n")); return 0; }
+        throw e;
+      }
 
       console.log();
 
@@ -328,47 +363,66 @@ export async function main() {
         continue;
       }
 
-      // ── Switch branch flow (with back support) ─────────────────────────────
+      // ── Switch branch flow ─────────────────────────────────────────────────
+      // ESC at any prompt navigates back one level; no explicit "← Go back" needed.
       const branchSuggestions = getSwitchBranchSuggestions(config);
 
       if (branchSuggestions.length > 0) {
-        const branchChoice = await select({
-          message: p.white("Suggested branch:"),
-          choices: [
-            { value: "__back__", name: p.yellow("← Go back"), description: p.muted("return to main menu") },
-            ...branchSuggestions.map((item) => ({
-              value: item.value,
-              name: colorBranch(item.value),
-              description: p.muted(item.template),
-            })),
-            {
-              value: "__custom__",
-              name: p.white("Custom branch..."),
-              description: p.muted("type any branch name or partial"),
-            },
-          ],
-          theme: THEME,
-        });
-
-        console.log();
-
-        if (branchChoice === "__back__") continue modeLoop;
-
-        if (branchChoice === "__custom__") {
+        // Inner loop so ESC on the custom-branch input returns to suggestions.
+        suggestionLoop: while (true) {
+          let branchChoice;
+          try {
+            branchChoice = await select({
+              message: p.white("Suggested branch:"),
+              choices: [
+                ...branchSuggestions.map((item) => ({
+                  value: item.value,
+                  name: colorBranch(item.value),
+                  description: p.muted(item.template),
+                })),
+                {
+                  value: "__custom__",
+                  name: p.white("Custom branch..."),
+                  description: p.muted("type any branch name or partial"),
+                },
+              ],
+              theme: THEME,
+            });
+          } catch (e) {
+            if (isEsc(e)) { console.log(); continue modeLoop; } // ESC → mode selector
+            throw e;
+          }
+
+          console.log();
+
+          if (branchChoice === "__custom__") {
+            try {
+              targetBranch = await input({
+                message: p.white("Branch name") + p.muted(" (or partial):"),
+                theme: THEME,
+                validate: (v) => v.trim() !== "" || "Branch name cannot be empty",
+              });
+            } catch (e) {
+              if (isEsc(e)) { console.log(); continue suggestionLoop; } // ESC → suggestions
+              throw e;
+            }
+          } else {
+            targetBranch = branchChoice;
+          }
+
+          break suggestionLoop;
+        }
+      } else {
+        try {
           targetBranch = await input({
             message: p.white("Branch name") + p.muted(" (or partial):"),
             theme: THEME,
             validate: (v) => v.trim() !== "" || "Branch name cannot be empty",
           });
-        } else {
-          targetBranch = branchChoice;
+        } catch (e) {
+          if (isEsc(e)) { console.log(); continue modeLoop; } // ESC → mode selector
+          throw e;
         }
-      } else {
-        targetBranch = await input({
-          message: p.white("Branch name") + p.muted(" (or partial):"),
-          theme: THEME,
-          validate: (v) => v.trim() !== "" || "Branch name cannot be empty",
-        });
       }
 
       break modeLoop; // branch was chosen — proceed to confirm prompts

package/src/utils/update-check.js

@@ -0,0 +1,105 @@
+/**
+ * Non-blocking npm update checker.
+ *
+ * - Checks the npm registry for a newer version of the package.
+ * - Throttled to at most once per day using a cache entry in the gitmux config.
+ * - Run checkForUpdate() early (don't await) to fetch in the background, then
+ *   call awaitUpdateCheck() before blocking on user input to show the notice.
+ */
+
+import { createRequire } from "module";
+import { loadConfig, saveConfig } from "../config/index.js";
+
+const require = createRequire(import.meta.url);
+
+// Read own package.json without dynamic import (avoids assertion syntax issues)
+let PKG_NAME = "@errhythm/gitmux";
+let PKG_VERSION = "0.0.0";
+try {
+    // Walk up from this file: src/utils/ → src/ → root
+    const pkg = require("../../package.json");
+    PKG_NAME = pkg.name;
+    PKG_VERSION = pkg.version;
+} catch { /* ignore */ }
+
+/** ms in one day */
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+
+/** Registry URL — use the unscoped form to avoid encoding issues */
+function registryUrl(name) {
+    return `https://registry.npmjs.org/${encodeURIComponent(name).replace("%40", "@")}`;
+}
+
+// Internal promise handle — resolved by checkForUpdate()
+let _resolve;
+let _updatePromise = new Promise((r) => { _resolve = r; });
+
+/**
+ * Kick off the update check in the background.
+ * Call this EARLY in startup (do NOT await).
+ */
+export function checkForUpdate() {
+    (async () => {
+        try {
+            const cfg = loadConfig();
+            const cache = cfg._updateCheck ?? {};
+            const now = Date.now();
+
+            // Only hit the network once per day
+            if (cache.lastChecked && (now - cache.lastChecked) < ONE_DAY_MS) {
+                _resolve({ latest: cache.latest ?? null, current: PKG_VERSION });
+                return;
+            }
+
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 4000);
+
+            let latest = null;
+            try {
+                const res = await fetch(registryUrl(PKG_NAME), { signal: controller.signal });
+                const data = await res.json();
+                latest = data["dist-tags"]?.latest ?? null;
+            } catch {
+                // Network error / timeout — silently skip
+            } finally {
+                clearTimeout(timeout);
+            }
+
+            // Persist the result so we don't hammer npm
+            if (latest) {
+                saveConfig({
+                    ...loadConfig(),
+                    _updateCheck: { lastChecked: now, latest },
+                });
+            }
+
+            _resolve({ latest, current: PKG_VERSION });
+        } catch {
+            _resolve({ latest: null, current: PKG_VERSION });
+        }
+    })();
+}
+
+/**
+ * Await the background check and return a boxen-ready notice string,
+ * or null if the user is already on the latest version.
+ */
+export async function awaitUpdateCheck() {
+    const { latest, current } = await _updatePromise;
+    if (!latest) return null;
+
+    // Simple semver comparison (major.minor.patch — no pre-release needed)
+    if (!isNewer(latest, current)) return null;
+
+    return { latest, current };
+}
+
+/** Returns true if `candidate` is strictly newer than `baseline`. */
+function isNewer(candidate, baseline) {
+    const toNum = (v) => v.split(".").map(Number);
+    const [ma, mi, pa] = toNum(candidate);
+    const [mb, mib, pb] = toNum(baseline);
+    if (ma !== mb) return ma > mb;
+    if (mi !== mib) return mi > mib;
+    return pa > pb;
+}