@manthank/mgit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mgit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# mgit 🌆
+
+**A friendly, animated terminal UI that teaches beginners git & GitHub.**
+
+`mgit` wraps every common git command in a colourful, guided interface built with
+[Ink](https://github.com/vadimdemedes/ink). Every action shows the **real command
+it runs** and a plain-English explanation, so you *learn git while you use it*.
+Dangerous actions are highlighted and ask for confirmation.
+
+```
+   █▀▄▀█ █▀▀ █ ▀█▀
+   █ ▀ █ █▄█ █  █
+```
+
+## Features
+
+- 🎬 **Animated UI** — shimmering gradient wordmark, travelling pulses, animated pointers.
+- 🎨 **6 themes + customisation** — Neon, Ocean, Sunset, Forest, Monochrome, Candy Pop.
+  Toggle animations, danger-confirmations and hints. Preferences persist in `~/.mgit/config.json`.
+- 📊 **Chart-style visualisations**
+  - **Status dashboard** — colour-coded staged / changed / untracked files.
+  - **Branch map** — every branch as a node, current one marked with ★.
+  - **Commit graph** — commits across all branches with branch/tag badges.
+  - **Contributions chart** — a bar chart of commits per author.
+- 🧭 **Everything explained** — a beginner hint for every one of the ~50 actions.
+- 🍳 **Guided recipes** — multi-step workflows (publish to GitHub, feature branch, sync main)
+  walked through one command at a time.
+- ⌨️ **Keyboard driven** — arrows, Enter, Esc, plus quick shortcuts (`t` theme, `s` settings, `?` help).
+
+## Covered commands
+
+All 35 topic areas from the classic git cheat-sheet are covered, grouped into:
+
+| Menu | Includes |
+|------|----------|
+| 🚀 Get Started | setup wizard (name/email/default branch), config list, `init`, `clone` |
+| 🔎 See What Changed | `status`, `diff`, `diff --staged`, `diff --name-only`, `show`, `blame`, `grep` |
+| 📈 History & Graph | commit graph, contributions chart, `log --oneline`, `reflog`, `shortlog` |
+| 📦 Stage & Commit | `add .`, `add <file>`, `add -u`, `commit -m`, `commit -am` |
+| 🌿 Branches | branch map, create/switch/merge/delete (safe & force) |
+| 🛰️ Remotes, Push & Pull | `remote -v/add/set-url/remove`, `push -u`, `push`, `pull`, `fetch`, force push |
+| ⏪ Undo & Recover | `restore`, unstage, `reset` (soft/mixed/hard), `revert`, `clean` |
+| 🧰 Stash | save, list, pop, apply, drop, clear |
+| 🏷️ Files & Tags | `rm`, `mv`, `.gitignore` generator, `ls-files`, tags |
+| 🧪 Advanced | `cherry-pick`, `rebase`, `rev-parse HEAD` |
+| 🍳 Guided Recipes | GitHub first-push, feature-branch flow, sync main |
+
+## Install & run
+
+### As a global CLI tool (npm)
+
+```bash
+npm install -g mgit
+mgit             # launch from any folder
+```
+
+Or run without installing:
+
+```bash
+npx mgit
+```
+
+### From source (development)
+
+```bash
+git clone <repo-url> && cd mgit
+npm install      # installs deps and builds to dist/
+npm link         # makes the `mgit` command available everywhere
+mgit             # launch from any folder
+```
+
+During development:
+
+```bash
+npm run dev      # build + run
+npm run build    # compile source/ -> dist/ with Babel
+```
+
+## How it works
+
+- `source/` is written in JSX and compiled to `dist/` by Babel (`@babel/preset-react`).
+- `source/git.js` is a thin, never-throwing wrapper around the `git` binary (via `execa`)
+  plus parsers that turn raw output into the data the visual components render.
+- `source/catalog.js` is a data-driven list of every action (label, beginner hint,
+  the git args to run, and safety flags) — the single source of truth for the menus.
+- `source/app.jsx` owns navigation (a simple screen stack), theming and global shortcuts.
+
+## Requirements
+
+- Node.js ≥ 18
+- git installed and on your PATH
+- An interactive terminal (TTY)
+
+## License
+
+MIT

package/dist/app.js

@@ -0,0 +1,468 @@
+// mgit root component: owns navigation, theme/config, and renders the active screen.
+import React, { useState, useEffect, useCallback } from 'react';
+import { Box, Text, useApp, useInput } from 'ink';
+import Header from './components/Header.js';
+import Footer from './components/Footer.js';
+import Menu from './components/Menu.js';
+import { categories } from './catalog.js';
+import { getTheme, themeOrder } from './themes.js';
+import { saveConfig } from './config.js';
+import { isGitRepo } from './git.js';
+import StatusView from './views/StatusView.js';
+import BranchView from './views/BranchView.js';
+import LogGraphView from './views/LogGraphView.js';
+import ContribView from './views/ContribView.js';
+import ConfigView from './views/ConfigView.js';
+import SetupWizard from './views/SetupWizard.js';
+import GitignoreView from './views/GitignoreView.js';
+import ActionRunner from './views/ActionRunner.js';
+import RecipeView from './views/RecipeView.js';
+import SettingsView from './views/SettingsView.js';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const HOME = {
+  type: 'home'
+};
+
+// Screens that are pure menus/read-only (safe to attach letter shortcuts to,
+// because they never mount a TextInput or single-key confirm).
+const MENU_TYPES = new Set(['home', 'category', 'settings', 'help', 'readview']);
+export default function App({
+  initialConfig
+}) {
+  const {
+    exit
+  } = useApp();
+  const [config, setConfig] = useState(initialConfig);
+  const [stack, setStack] = useState([HOME]);
+  const [repo, setRepo] = useState(false);
+  const theme = getTheme(config.theme);
+  const screen = stack[stack.length - 1];
+  const updateConfig = useCallback(next => {
+    setConfig(next);
+    saveConfig(next);
+  }, []);
+  const push = useCallback(s => setStack(st => [...st, s]), []);
+  const back = useCallback(() => setStack(st => st.length > 1 ? st.slice(0, -1) : st), []);
+
+  // Refresh "is this a repo?" whenever we land back on a menu screen.
+  useEffect(() => {
+    if (MENU_TYPES.has(screen.type)) {
+      isGitRepo().then(setRepo);
+    }
+  }, [stack.length, screen.type]);
+
+  // Global navigation. Esc always goes back (TextInput ignores Esc, so this is safe).
+  // Letter shortcuts only on menu-type screens so they don't hijack text entry.
+  useInput((input, key) => {
+    if (key.escape) {
+      if (stack.length > 1) back();else exit();
+      return;
+    }
+    if (!MENU_TYPES.has(screen.type)) return;
+    if (input === 'q') exit();else if (input === 't') cycleTheme();else if (input === 's') push({
+      type: 'settings'
+    });else if (input === '?') push({
+      type: 'help'
+    });else if (input === 'h') setStack([HOME]);else if (key.leftArrow && stack.length > 1) back();
+  });
+  function cycleTheme() {
+    const i = themeOrder.indexOf(config.theme);
+    updateConfig({
+      ...config,
+      theme: themeOrder[(i + 1) % themeOrder.length]
+    });
+  }
+  function openAction(action) {
+    if (action.needsRepo !== false && !repo && action.view !== 'setup' && action.view !== 'config') {
+      push({
+        type: 'norepo',
+        action
+      });
+      return;
+    }
+    switch (action.view) {
+      case 'status':
+      case 'branches':
+      case 'log':
+      case 'contrib':
+      case 'config':
+        push({
+          type: 'readview',
+          view: action.view,
+          action
+        });
+        break;
+      case 'setup':
+        push({
+          type: 'setup',
+          action
+        });
+        break;
+      case 'gitignore':
+        push({
+          type: 'gitignore',
+          action
+        });
+        break;
+      case 'recipe':
+        push({
+          type: 'recipe',
+          recipe: action.recipe,
+          action
+        });
+        break;
+      default:
+        push({
+          type: 'action',
+          action
+        });
+    }
+  }
+  const hints = buildHints(screen, stack.length);
+  return /*#__PURE__*/_jsxs(Box, {
+    flexDirection: "column",
+    paddingX: 1,
+    children: [/*#__PURE__*/_jsx(Header, {
+      theme: theme,
+      animations: config.animations,
+      subtitle: titleFor(screen)
+    }), /*#__PURE__*/_jsx(Breadcrumb, {
+      theme: theme,
+      stack: stack
+    }), /*#__PURE__*/_jsx(Box, {
+      flexDirection: "column",
+      marginTop: 1,
+      minHeight: 3,
+      children: renderScreen({
+        screen,
+        theme,
+        config,
+        repo,
+        push,
+        openAction,
+        updateConfig,
+        cycleTheme
+      })
+    }), /*#__PURE__*/_jsx(Footer, {
+      theme: theme,
+      hints: hints,
+      repo: repo
+    })]
+  });
+}
+function renderScreen(ctx) {
+  const {
+    screen,
+    theme,
+    config,
+    repo,
+    openAction,
+    updateConfig
+  } = ctx;
+  switch (screen.type) {
+    case 'home':
+      return /*#__PURE__*/_jsx(HomeMenu, {
+        theme: theme,
+        config: config,
+        onSelect: openAction,
+        ctx: ctx
+      });
+    case 'category':
+      return /*#__PURE__*/_jsx(CategoryMenu, {
+        theme: theme,
+        config: config,
+        categoryId: screen.categoryId,
+        onSelect: openAction
+      });
+    case 'readview':
+      if (screen.view === 'status') return /*#__PURE__*/_jsx(StatusView, {
+        theme: theme
+      });
+      if (screen.view === 'branches') return /*#__PURE__*/_jsx(BranchView, {
+        theme: theme,
+        animations: config.animations
+      });
+      if (screen.view === 'log') return /*#__PURE__*/_jsx(LogGraphView, {
+        theme: theme,
+        animations: config.animations
+      });
+      if (screen.view === 'contrib') return /*#__PURE__*/_jsx(ContribView, {
+        theme: theme,
+        animations: config.animations
+      });
+      if (screen.view === 'config') return /*#__PURE__*/_jsx(ConfigView, {
+        theme: theme
+      });
+      return null;
+    case 'setup':
+      return /*#__PURE__*/_jsx(SetupWizard, {
+        theme: theme
+      });
+    case 'gitignore':
+      return /*#__PURE__*/_jsx(GitignoreView, {
+        theme: theme
+      });
+    case 'action':
+      return /*#__PURE__*/_jsx(ActionRunner, {
+        action: screen.action,
+        theme: theme,
+        config: config
+      });
+    case 'recipe':
+      return /*#__PURE__*/_jsx(RecipeView, {
+        recipeId: screen.recipe,
+        theme: theme,
+        config: config
+      });
+    case 'settings':
+      return /*#__PURE__*/_jsx(SettingsView, {
+        theme: theme,
+        config: config,
+        onChange: updateConfig
+      });
+    case 'help':
+      return /*#__PURE__*/_jsx(HelpView, {
+        theme: theme
+      });
+    case 'norepo':
+      return /*#__PURE__*/_jsx(NoRepo, {
+        theme: theme,
+        action: screen.action
+      });
+    default:
+      return null;
+  }
+}
+function HomeMenu({
+  theme,
+  config,
+  onSelect,
+  ctx
+}) {
+  const items = [...categories.map(c => ({
+    label: `${c.emoji}  ${c.label.padEnd(22)} ${c.blurb}`,
+    value: 'cat:' + c.id
+  })), {
+    label: '⚙️   Settings & Themes',
+    value: 'nav:settings'
+  }, {
+    label: '❓  Help & shortcuts',
+    value: 'nav:help'
+  }, {
+    label: '🚪  Quit',
+    value: 'nav:quit'
+  }];
+  function handle({
+    value
+  }) {
+    const [kind, id] = value.split(':');
+    if (kind === 'cat') ctx.push({
+      type: 'category',
+      categoryId: id
+    });else if (id === 'settings') ctx.push({
+      type: 'settings'
+    });else if (id === 'help') ctx.push({
+      type: 'help'
+    });else if (id === 'quit') process.exit(0);
+  }
+  return /*#__PURE__*/_jsxs(Box, {
+    flexDirection: "column",
+    children: [/*#__PURE__*/_jsx(Text, {
+      color: theme.muted,
+      children: "What would you like to do? Use \u2191 \u2193 and Enter."
+    }), /*#__PURE__*/_jsx(Box, {
+      marginTop: 1,
+      children: /*#__PURE__*/_jsx(Menu, {
+        items: items,
+        onSelect: handle,
+        theme: theme,
+        animations: config.animations,
+        limit: 14
+      })
+    })]
+  });
+}
+function CategoryMenu({
+  theme,
+  config,
+  categoryId,
+  onSelect
+}) {
+  const cat = categories.find(c => c.id === categoryId);
+  if (!cat) return /*#__PURE__*/_jsx(Text, {
+    color: theme.danger,
+    children: "Unknown category."
+  });
+  const items = cat.actions.map(a => ({
+    label: `${a.danger ? '⚠ ' : ''}${a.label}`,
+    value: a.id
+  }));
+  const [hi, setHi] = useState(cat.actions[0]);
+  return /*#__PURE__*/_jsxs(Box, {
+    flexDirection: "column",
+    children: [/*#__PURE__*/_jsxs(Text, {
+      color: theme.secondary,
+      children: [cat.emoji, " ", cat.blurb]
+    }), /*#__PURE__*/_jsx(Box, {
+      marginTop: 1,
+      children: /*#__PURE__*/_jsx(Menu, {
+        items: items,
+        theme: theme,
+        animations: config.animations,
+        limit: 14,
+        onHighlight: item => setHi(cat.actions.find(a => a.id === item.value)),
+        onSelect: item => onSelect(cat.actions.find(a => a.id === item.value))
+      })
+    }), config.showHints && hi && /*#__PURE__*/_jsx(Box, {
+      marginTop: 1,
+      borderStyle: "round",
+      borderColor: theme.muted,
+      paddingX: 1,
+      children: /*#__PURE__*/_jsxs(Text, {
+        color: theme.muted,
+        children: ["\uD83D\uDCA1 ", hi.hint]
+      })
+    })]
+  });
+}
+function HelpView({
+  theme
+}) {
+  const rows = [['↑ ↓', 'Move through menus'], ['Enter', 'Select / run'], ['Esc', 'Go back (or quit from home)'], ['t', 'Cycle theme instantly'], ['s', 'Open Settings & Themes'], ['h', 'Jump home'], ['?', 'This help screen'], ['q', 'Quit mgit'], ['Y', 'Confirm a dangerous action']];
+  return /*#__PURE__*/_jsxs(Box, {
+    flexDirection: "column",
+    children: [/*#__PURE__*/_jsx(Text, {
+      color: theme.accent,
+      bold: true,
+      children: "Keyboard shortcuts"
+    }), /*#__PURE__*/_jsx(Box, {
+      marginTop: 1,
+      flexDirection: "column",
+      children: rows.map(([k, d]) => /*#__PURE__*/_jsxs(Text, {
+        children: [/*#__PURE__*/_jsx(Text, {
+          color: theme.accent,
+          bold: true,
+          children: k.padEnd(8)
+        }), /*#__PURE__*/_jsx(Text, {
+          color: "white",
+          children: d
+        })]
+      }, k))
+    }), /*#__PURE__*/_jsxs(Box, {
+      marginTop: 1,
+      flexDirection: "column",
+      children: [/*#__PURE__*/_jsx(Text, {
+        color: theme.secondary,
+        bold: true,
+        children: "About"
+      }), /*#__PURE__*/_jsx(Text, {
+        color: theme.muted,
+        children: "mgit is a guided, colourful front-end for git. Every action shows the real command it runs, so you learn git while you use it. Dangerous actions are highlighted and ask for confirmation."
+      })]
+    })]
+  });
+}
+function NoRepo({
+  theme,
+  action
+}) {
+  return /*#__PURE__*/_jsxs(Box, {
+    flexDirection: "column",
+    children: [/*#__PURE__*/_jsx(Text, {
+      color: theme.warn,
+      bold: true,
+      children: "This folder isn't a git repository yet."
+    }), /*#__PURE__*/_jsxs(Text, {
+      color: theme.muted,
+      children: ["\"", action.label, "\" needs a repo. Go to \uD83D\uDE80 Get Started \u2192 \"Initialize a repo here\", or open a folder that already contains one."]
+    }), /*#__PURE__*/_jsx(Box, {
+      marginTop: 1,
+      children: /*#__PURE__*/_jsxs(Text, {
+        color: theme.muted,
+        children: ["Current folder: ", process.cwd()]
+      })
+    }), /*#__PURE__*/_jsx(Box, {
+      marginTop: 1,
+      children: /*#__PURE__*/_jsx(Text, {
+        color: theme.accent,
+        children: "Press Esc / \u2190 to go back."
+      })
+    })]
+  });
+}
+function Breadcrumb({
+  theme,
+  stack
+}) {
+  const trail = stack.map(s => titleFor(s)).filter(Boolean);
+  return /*#__PURE__*/_jsx(Box, {
+    children: /*#__PURE__*/_jsx(Text, {
+      color: theme.muted,
+      children: trail.map((t, i) => /*#__PURE__*/_jsxs(Text, {
+        children: [i > 0 && /*#__PURE__*/_jsx(Text, {
+          color: theme.muted,
+          children: " \u203A "
+        }), /*#__PURE__*/_jsx(Text, {
+          color: i === trail.length - 1 ? theme.accent : theme.muted,
+          children: t
+        })]
+      }, i))
+    })
+  });
+}
+function titleFor(screen) {
+  switch (screen.type) {
+    case 'home':
+      return 'Home';
+    case 'category':
+      {
+        const c = categories.find(x => x.id === screen.categoryId);
+        return c ? c.label : 'Category';
+      }
+    case 'readview':
+      return screen.action ? screen.action.label : 'View';
+    case 'setup':
+      return 'Setup wizard';
+    case 'gitignore':
+      return '.gitignore';
+    case 'action':
+      return screen.action ? screen.action.label : 'Run';
+    case 'recipe':
+      return screen.action ? screen.action.label : 'Recipe';
+    case 'settings':
+      return 'Settings';
+    case 'help':
+      return 'Help';
+    case 'norepo':
+      return 'No repo';
+    default:
+      return '';
+  }
+}
+function buildHints(screen, depth) {
+  if (MENU_TYPES.has(screen.type)) {
+    return [{
+      key: '↑↓',
+      label: 'move'
+    }, {
+      key: '⏎',
+      label: 'select'
+    }, {
+      key: 't',
+      label: 'theme'
+    }, {
+      key: 'esc',
+      label: depth > 1 ? 'back' : 'quit'
+    }, {
+      key: 'q',
+      label: 'quit'
+    }];
+  }
+  return [{
+    key: '⏎',
+    label: 'confirm'
+  }, {
+    key: 'esc',
+    label: 'back'
+  }];
+}