gent-cli 12.0.0 → 14.0.0

package/README.md

@@ -25,6 +25,7 @@ Beyond a faithful git-like workflow, Gent adds:
 - **`gent resolve`** — an interactive conflict resolver (ours / theirs / both / edit / AI).
 - **`gent summary`** — a repository health dashboard, plus **`gent log --graph`**.
 - **Optional AI** (`gent commit --ai`, `gent explain`, `gent summary --ai`, AI option in `gent resolve`) — off by default, enabled with `ANTHROPIC_API_KEY`.
+- **Genti, your terminal mascot** — a chunky pixel bot that *acts out* your workflow: it carries a file crate to the cloud on `gent push`, walks one home on `gent pull`, and reconciles two branches on `gent merge`. It plays once (in place, no scrollback spam) after a successful command. Meet it directly with `gent pet` (add `--loop` to keep it running; try `gent pet push|pull|merge|auth`). Set `GENT_NO_PET=1` (or run in CI / a non-interactive shell) to turn the celebrations off.
 
 See [docs/COMMANDS.md](docs/COMMANDS.md) for the full reference and
 [docs/ALGORITHMS.md](docs/ALGORITHMS.md) for how the engines work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gent-cli",
-  "version": "12.0.0",
+  "version": "14.0.0",
   "description": "A modern, Git-like version control CLI with cloud sync, AI-powered superpowers (ask/review/docs/changelog), and zero-friction setup (gent setup/doctor/config).",
   "main": "src/index.js",
   "bin": {

package/src/commands/login.js

@@ -8,12 +8,14 @@ const inquirer = require('inquirer');
 const ora = require('ora');
 const boxen = require('boxen');
 const authService = require('../services/auth-service');
+const pet = require('./pet');
 
 /**
  * Login user
  * @param {Object} options - Command options
  */
 async function login(options) {
+    pet.banner('Knock knock — let\'s sign you in.', 'Enter your details below.');
     console.log(chalk.cyan('\n🔐 Login to your Gent account\n'));
 
     try {
@@ -75,6 +77,8 @@ ${chalk.bold('Commands:')}
             borderColor: 'cyan'
         }));
 
+        await pet.celebrate('auth');
+
     } catch (error) {
         console.error(chalk.red('\n✗ Login failed'));
         console.error(chalk.red(`Error: ${error.message}\n`));

package/src/commands/merge.js

@@ -13,6 +13,7 @@ const { generateCommitHash } = require('../utils/helpers');
 const authStorage = require('../utils/auth-storage');
 const { findMergeBase, mergeTreeEntries, autoMerge } = require('../utils/merge-engine');
 const { storeTree, readBlobAsString, storeBlob } = require('../utils/hash-engine');
+const pet = require('./pet');
 const journal = require('../utils/journal');
 
 /**
@@ -78,6 +79,7 @@ async function merge(sourceBranch, options) {
             }
 
             spinner.succeed(chalk.green(`Fast-forward merge: ${currentBranch} → ${theirsHash.substring(0, 7)}`));
+            await pet.celebrate('merge');
             return;
         }
 
@@ -185,6 +187,7 @@ async function merge(sourceBranch, options) {
             console.log(chalk.gray(`\n  Base: ${baseHash ? baseHash.substring(0, 7) : 'none'}`));
             console.log(chalk.gray(`  Ours: ${oursHash.substring(0, 7)}  Theirs: ${theirsHash.substring(0, 7)}`));
             console.log(chalk.green(`  ${autoResolved} file(s) merged automatically`));
+            await pet.celebrate('merge');
         } else {
             // Stage the merge state for manual resolution
             const staging = await readJSON(path.join(gentPath, STAGING_FILE));

package/src/commands/pet.js

@@ -365,52 +365,116 @@ const TIPS = [
 ];
 
 // ── Scene registry ───────────────────────────────────────────────────────
+// `cycle` = ticks in one full loop; playing "once" runs exactly one cycle.
 const SCENES = {
-    idle:  { fn: (cv, t, st) => sceneIdle(cv, t, st.tip) },
-    push:  { fn: scenePush },
-    pull:  { fn: scenePull },
-    merge: { fn: sceneMerge },
-    auth:  { fn: (cv, t) => sceneAuth(cv, t) },
-    login: { fn: (cv, t) => sceneAuth(cv, t) },
+    idle:  { fn: (cv, t, st) => sceneIdle(cv, t, st.tip), cycle: 66 },
+    push:  { fn: scenePush,  cycle: 66 },
+    pull:  { fn: scenePull,  cycle: 64 },
+    merge: { fn: sceneMerge, cycle: 70 },
+    auth:  { fn: (cv, t) => sceneAuth(cv, t), cycle: 102 },
+    login: { fn: (cv, t) => sceneAuth(cv, t), cycle: 102 },
 };
 
 // ── ANSI helpers ─────────────────────────────────────────────────────────
-const HOME = '[H';
-const CLEAR = '[2J[H';
-const HIDE = '[?25l';
-const SHOW = '[?25h';
+const HIDE = '\x1b[?25l';
+const SHOW = '\x1b[?25h';
+const CLEAR_LINE = '\x1b[2K';
+const HOME = '\x1b[H';
+const ENTER_ALT = '\x1b[?1049h';   // switch to the alternate screen buffer
+const LEAVE_ALT = '\x1b[?1049l';   // …and restore the user's scrollback on exit
+const up = (n) => `\x1b[${n}A`;
 
-function play(sceneName, { once }) {
-    const scene = SCENES[sceneName] || SCENES.idle;
-    const cv = new Canvas(CV_W, CV_H);
-    const state = { count: 0, tip: TIPS[Math.floor(Math.random() * TIPS.length)] };
-    let t = 0;
-
-    process.stdout.write(HIDE + CLEAR);
-
-    const footer = () =>
-        chalk.gray('  scene: ') + C.body(sceneName) +
-        chalk.gray('   ·   try: ') + C.say('gent pet push|pull|merge') +
-        chalk.gray('   ·   Ctrl+C to leave');
-
-    const bye = () => {
-        process.stdout.write(SHOW + '\n');
-        console.log(C.body('  Genti waves. ') + chalk.gray('Come back with ') + C.say('gent pet') + chalk.gray('.'));
-    };
-
-    const timer = setInterval(() => {
-        cv.clear();
-        scene.fn(cv, t, state);
-        // rotate idle tip every ~6s
-        if (sceneName === 'idle' && t > 0 && t % 66 === 0) {
-            state.tip = TIPS[Math.floor(Math.random() * TIPS.length)];
-        }
-        process.stdout.write(HOME + cv.render() + '\n' + footer() + '\n');
-        t++;
-        if (once && t > 130) { clearInterval(timer); bye(); process.exit(0); }
-    }, FRAME_MS);
+/**
+ * Play a scene. Resolves when finished.
+ *
+ * Two redraw strategies:
+ *  - altScreen:true  → take over the whole screen (alternate buffer), redraw
+ *    from HOME each frame, restore on exit. Zero scrollback drift. Used by the
+ *    standalone `gent pet` command.
+ *  - altScreen:false → inline redraw below existing output via cursor-up, so a
+ *    command's own text stays visible above. Used by post-command celebrations.
+ *
+ * @param {string}  sceneName
+ * @param {object}  opts
+ * @param {boolean} opts.loop       keep looping until Ctrl+C (default: play once)
+ * @param {boolean} opts.footer     show the hint line under the stage
+ * @param {boolean} opts.goodbye    print a farewell line when done
+ * @param {boolean} opts.altScreen  use the alternate screen buffer
+ * @returns {Promise<void>}
+ */
+function play(sceneName, { loop = false, footer = true, goodbye = false, altScreen = false, maxTicks = Infinity } = {}) {
+    return new Promise((resolve) => {
+        const scene = SCENES[sceneName] || SCENES.idle;
+        const cv = new Canvas(CV_W, CV_H);
+        const state = { count: 0, tip: TIPS[Math.floor(Math.random() * TIPS.length)] };
+        const totalTicks = loop ? Infinity : Math.min(scene.cycle + 1, maxTicks); // one clean cycle, capped
+        let t = 0;
+        let printed = false;
+        let done = false;
+
+        const footerLine = () => footer
+            ? chalk.gray('  ') +
+              (loop ? chalk.gray('Ctrl+C to leave') : C.body('Genti')) +
+              chalk.gray('   ·   more scenes: ') + C.say('gent pet push|pull|merge')
+            : '';
+
+        const paint = () => {
+            cv.clear();
+            scene.fn(cv, t, state);
+            if (sceneName === 'idle' && loop && t > 0 && t % scene.cycle === 0) {
+                state.tip = TIPS[Math.floor(Math.random() * TIPS.length)];
+            }
+            const lines = cv.render().split('\n');
+            lines.push(footerLine());
+            const block = lines.map(l => CLEAR_LINE + l).join('\n');
+            if (altScreen) {
+                process.stdout.write(HOME + block);
+            } else {
+                if (printed) process.stdout.write(up(lines.length));
+                process.stdout.write(block + '\n');
+            }
+            printed = true;
+        };
+
+        const finish = () => {
+            if (done) return;
+            done = true;
+            clearInterval(timer);
+            process.removeListener('SIGINT', onSig);
+            process.stdout.write(SHOW + (altScreen ? LEAVE_ALT : ''));
+            if (goodbye) {
+                console.log(C.body('  Genti waves.') + chalk.gray(' Come back with ') + C.say('gent pet') + chalk.gray('.'));
+            }
+            resolve();
+        };
+
+        const onSig = () => finish();
+
+        process.stdout.write((altScreen ? ENTER_ALT + HOME : '') + HIDE);
+        paint();
+        const timer = setInterval(() => {
+            t++;
+            if (t >= totalTicks) { paint(); return finish(); }
+            paint();
+        }, FRAME_MS);
+        process.on('SIGINT', onSig);
+    });
+}
 
-    process.on('SIGINT', () => { clearInterval(timer); bye(); process.exit(0); });
+/**
+ * A compact STATIC Genti header — safe to print above an interactive prompt
+ * (inquirer, etc.) because it never animates or moves the cursor.
+ * @param {string} greeting  bold line beside the mascot
+ * @param {string} [sub]     dimmer line under the greeting
+ */
+function banner(greeting, sub) {
+    if (process.env.GENT_NO_PET || !process.stdout.isTTY) return;
+    const cv = new Canvas(52, 9);
+    cv.sprite(mascot({}), 1, 0);
+    cv.sprite(legs('stand'), 1, 7);
+    cv.text(18, 2, greeting, C.body);
+    if (sub) cv.text(18, 4, sub, C.say);
+    console.log('\n' + cv.render());
 }
 
 // Static single frame for non-TTY (piped) output.
@@ -419,10 +483,9 @@ function still(sceneName) {
     const state = { count: 1, tip: TIPS[Math.floor(Math.random() * TIPS.length)] };
     (SCENES[sceneName] || SCENES.idle).fn(cv, 12, state);
     console.log(cv.render());
-    console.log(chalk.gray('  (animated in a real terminal — run ') + C.say(`gent pet ${sceneName === 'idle' ? '' : sceneName}`.trim()) + chalk.gray(')'));
 }
 
-// ── Entry ────────────────────────────────────────────────────────────────
+// ── Public: standalone `gent pet` command ────────────────────────────────
 async function petCommand(scene, options = {}) {
     if (process.env.NO_COLOR || (options && options.color === false)) chalk.level = 0;
 
@@ -435,14 +498,36 @@ async function petCommand(scene, options = {}) {
         return;
     }
 
-    // Signed-out nudge: default idle → auth scene the first time.
-    if (name === 'idle' && !options.stay) {
+    // Signed-out nudge: bare `gent pet` greets you at the door.
+    if (name === 'idle') {
         const authed = await authStorage.isAuthenticated().catch(() => false);
         if (!authed) name = 'auth';
     }
 
     if (!process.stdout.isTTY) return still(name);
-    play(name, { once: !!options.once });
+    // Default: play once, on the alternate screen so nothing pollutes scrollback.
+    // `--loop` keeps it running until Ctrl+C.
+    await play(name, { loop: !!options.loop, footer: true, goodbye: true, altScreen: true });
+}
+
+/**
+ * Public: a one-shot celebration other commands fire after they succeed.
+ * Silent + safe in non-interactive contexts (CI, pipes, GENT_NO_PET=1).
+ * Never throws — a mascot must never break a real command.
+ */
+async function celebrate(scene) {
+    try {
+        if (!process.stdout.isTTY) return;
+        if (process.env.NO_COLOR) { /* still animate, just uncolored */ }
+        if (process.env.GENT_NO_PET || process.env.CI) return;
+        if (!SCENES[scene]) return;
+        console.log(); // one blank line between command output and Genti
+        // Auth flows just need a quick friendly wave; action scenes tell a fuller story.
+        const maxTicks = (scene === 'auth' || scene === 'login') ? 34 : Infinity;
+        await play(scene, { loop: false, footer: false, goodbye: false, maxTicks });
+    } catch (_) { /* ignore — decoration only */ }
 }
 
 module.exports = petCommand;
+module.exports.celebrate = celebrate;
+module.exports.banner = banner;

package/src/commands/pull.js

@@ -29,6 +29,7 @@ const apiClient = require('../utils/api-client');
 const authStorage = require('../utils/auth-storage');
 const { storeBlob, readBlob } = require('../utils/hash-engine');
 const { findMergeBase, mergeTreeEntries } = require('../utils/merge-engine');
+const pet = require('./pet');
 const { generateCommitHash } = require('../utils/helpers');
 
 /**
@@ -137,6 +138,7 @@ async function pull(remoteName, branchName, options) {
 
             spinner.succeed(chalk.green(`Fast-forward: ${newCount} new commit(s)`));
             console.log(chalk.gray(`  ${remote}/${branch} → ${remoteHead.substring(0, 7)}`));
+            await pet.celebrate('pull');
         } else {
             // Diverged — need 3-way merge
             spinner.text = 'Branches diverged, merging...';
@@ -192,6 +194,7 @@ async function pull(remoteName, branchName, options) {
             } else {
                 spinner.succeed(chalk.green(`Merged ${newCount} remote commit(s)`));
                 console.log(chalk.gray(`  Merge commit: ${mergeCommit.hash.substring(0, 7)}`));
+                await pet.celebrate('pull');
             }
         }
     } catch (error) {

package/src/commands/push.js

@@ -42,6 +42,7 @@ const { COMMITS_FILE, CONFIG_FILE, API_ENDPOINTS, buildRepoUrl, parseRemoteUrl }
 const apiClient = require('../utils/api-client');
 const authStorage = require('../utils/auth-storage');
 const { readBlob, readTree, objectExists, readBlobAsString } = require('../utils/hash-engine');
+const pet = require('./pet');
 
 /**
  * Push commits to remote
@@ -243,6 +244,8 @@ async function push(remoteName, branchName, options) {
         console.log(chalk.gray(`  ${localHead.substring(0, 7)} → ${remote}/${branch}`));
         console.log(chalk.gray(`  ${packBlobs.length} blob(s), ${packTrees.length} tree(s) transferred`));
 
+        await pet.celebrate('push');
+
     } catch (error) {
         spinner.fail(chalk.red('Push failed'));
 

package/src/commands/register.js

@@ -8,12 +8,14 @@ const inquirer = require('inquirer');
 const ora = require('ora');
 const boxen = require('boxen');
 const authService = require('../services/auth-service');
+const pet = require('./pet');
 
 /**
  * Register a new user
  * @param {Object} options - Command options
  */
 async function register(options) {
+    pet.banner('New here? Let\'s get you set up.', 'Create your account below.');
     console.log(chalk.cyan('\n🚀 Create your Gent account\n'));
 
     try {
@@ -120,6 +122,8 @@ ${chalk.bold('Next steps:')}
             borderColor: 'green'
         }));
 
+        await pet.celebrate('auth');
+
     } catch (error) {
         console.error(chalk.red('\n✗ Registration failed'));
         console.error(chalk.red(`Error: ${error.message}\n`));

package/src/index.js

@@ -437,8 +437,7 @@ program
 program
     .command('pet [scene]')
     .description('Meet Genti — an animated pixel mascot that acts out gent (push|pull|merge|auth)')
-    .option('--once', 'Play a few cycles, then exit (good for scripts / shell startup)')
-    .option('--stay', 'Stay on the idle scene even when signed out')
+    .option('--loop', 'Keep looping until Ctrl+C (default: play once)')
     .action(petCommand);
 
 // Help command