gent-cli 6.0.1 → 8.0.0

package/src/commands/doctor.js

@@ -0,0 +1,169 @@
+/**
+ * Doctor Command - Health check for the gent CLI.
+ *
+ *   gent doctor              → run all checks
+ *   gent doctor --ai         → also ping Anthropic with a 1-token request
+ *
+ * Each row prints PASS / WARN / FAIL plus a hint on how to fix the issue.
+ */
+
+const path = require('path');
+const fs = require('fs').promises;
+const chalk = require('chalk');
+const axios = require('axios');
+const packageJson = require('../../package.json');
+const { GENT_DIR } = require('../utils/constants');
+const userConfig = require('../utils/user-config');
+const apiClient = require('../utils/api-client');
+const authStorage = require('../utils/auth-storage');
+const ai = require('../utils/ai-service');
+
+const MIN_NODE_MAJOR = 18;
+
+async function doctor(options = {}) {
+    console.log(chalk.bold.cyan('\nGent CLI health check\n'));
+
+    const checks = [];
+
+    checks.push(await checkNodeVersion());
+    checks.push(await checkCliVersion());
+    checks.push(await checkRepo());
+    checks.push(await checkAuth());
+    checks.push(await checkApi());
+    checks.push(await checkAiKey(!!options.ai));
+
+    for (const c of checks) {
+        printCheck(c);
+    }
+
+    const failed = checks.filter(c => c.status === 'fail').length;
+    const warned = checks.filter(c => c.status === 'warn').length;
+    const passed = checks.filter(c => c.status === 'pass').length;
+
+    console.log();
+    console.log(
+        chalk.green(`  ${passed} pass`) + '  ' +
+        chalk.yellow(`${warned} warn`) + '  ' +
+        chalk.red(`${failed} fail`)
+    );
+
+    if (failed > 0) process.exit(1);
+}
+
+function printCheck(c) {
+    const badge = c.status === 'pass' ? chalk.green('✓ PASS')
+        : c.status === 'warn' ? chalk.yellow('! WARN')
+        : chalk.red('✗ FAIL');
+    console.log(`  ${badge}  ${chalk.bold(c.name)} ${chalk.gray(`— ${c.detail}`)}`);
+    if (c.hint) console.log(chalk.gray(`           hint: ${c.hint}`));
+}
+
+async function checkNodeVersion() {
+    const v = process.versions.node;
+    const major = parseInt(v.split('.')[0], 10);
+    if (major >= MIN_NODE_MAJOR) {
+        return { name: 'Node version', status: 'pass', detail: `v${v}` };
+    }
+    return {
+        name: 'Node version',
+        status: 'fail',
+        detail: `v${v} (need ≥${MIN_NODE_MAJOR})`,
+        hint: `Install Node ${MIN_NODE_MAJOR}+ — e.g. via nvm.`,
+    };
+}
+
+async function checkCliVersion() {
+    return {
+        name: 'Gent CLI',
+        status: 'pass',
+        detail: `v${packageJson.version}`,
+    };
+}
+
+async function checkRepo() {
+    const gentPath = path.join(process.cwd(), GENT_DIR);
+    try {
+        const stat = await fs.stat(gentPath);
+        if (!stat.isDirectory()) throw new Error('not a directory');
+        return { name: 'Repository (.gent)', status: 'pass', detail: gentPath };
+    } catch {
+        return {
+            name: 'Repository (.gent)',
+            status: 'warn',
+            detail: 'not a gent repo (this directory)',
+            hint: 'Run `gent init` to start a repo here, or cd into one.',
+        };
+    }
+}
+
+async function checkAuth() {
+    const isAuth = await authStorage.isAuthenticated();
+    if (!isAuth) {
+        return {
+            name: 'Authentication',
+            status: 'warn',
+            detail: 'not logged in',
+            hint: 'Run `gent login` or `gent register`.',
+        };
+    }
+    const user = await authStorage.getUser();
+    const who = user ? `${user.email}` : 'unknown user';
+    return { name: 'Authentication', status: 'pass', detail: who };
+}
+
+async function checkApi() {
+    const { value: baseUrl, source } = await userConfig.getResolved('api.base_url');
+    try {
+        await axios.get(baseUrl, { timeout: 8000, validateStatus: () => true });
+        return {
+            name: 'Backend reachable',
+            status: 'pass',
+            detail: `${baseUrl}  [${source}]`,
+        };
+    } catch (err) {
+        return {
+            name: 'Backend reachable',
+            status: 'fail',
+            detail: `${baseUrl} → ${err.code || err.message}`,
+            hint: 'If running a local server: `gent config set api.base_url http://localhost:8000`.',
+        };
+    }
+}
+
+async function checkAiKey(probe) {
+    const { value: key, source } = await ai.resolveKey();
+    if (!key) {
+        return {
+            name: 'AI key',
+            status: 'warn',
+            detail: 'not configured (AI features will be skipped, not failed)',
+            hint: 'Run `gent config set ai.api_key <key>` or set ANTHROPIC_API_KEY.',
+        };
+    }
+
+    if (!probe) {
+        return {
+            name: 'AI key',
+            status: 'pass',
+            detail: `present [${source}], model: ${await ai.resolveModel()} (use --ai to live-test)`,
+        };
+    }
+
+    try {
+        await ai.complete({ prompt: 'ping', maxTokens: 4 });
+        return {
+            name: 'AI key',
+            status: 'pass',
+            detail: `verified — model ${await ai.resolveModel()} responded`,
+        };
+    } catch (err) {
+        return {
+            name: 'AI key',
+            status: 'fail',
+            detail: err.message,
+            hint: 'Re-check the key (`gent config set ai.api_key`) or model (`gent config set ai.model`).',
+        };
+    }
+}
+
+module.exports = doctor;

package/src/commands/explain.js

@@ -0,0 +1,145 @@
+/**
+ * ============================================================================
+ * Explain Command - Plain-language summary of a commit or pending changes
+ * ============================================================================
+ *
+ * PURPOSE:
+ *   Turn a diff into a human explanation. With an API key set this uses Claude;
+ *   without one it still prints the unified diff plus a hint, so the command is
+ *   useful either way.
+ *
+ * USAGE:
+ *   gent explain            → explain the latest commit (HEAD)
+ *   gent explain <ref>      → explain a specific commit (full or short hash)
+ *   gent explain --staged   → explain the currently staged changes
+ *
+ * ============================================================================
+ */
+
+const path = require('path');
+const chalk = require('chalk');
+const ora = require('ora');
+const { getGentPath, readJSON } = require('../utils/fileSystem');
+const { COMMITS_FILE, STAGING_FILE } = require('../utils/constants');
+const { readBlobAsString, treeToMap } = require('../utils/hash-engine');
+const { formatUnifiedDiff } = require('../utils/diff-engine');
+const ai = require('../utils/ai-service');
+
+const MAX_DIFF_CHARS = 12000;
+
+function treeEntriesOf(commit) {
+    if (!commit) return [];
+    if (Array.isArray(commit.tree)) return commit.tree;
+    return (commit.files || []).map(f => ({ name: f.path || f.name, hash: f.hash }));
+}
+
+/**
+ * Build a unified-diff text between two trees (old → new).
+ */
+async function diffTrees(gentPath, oldEntries, newEntries) {
+    const oldMap = treeToMap(oldEntries);
+    const newMap = treeToMap(newEntries);
+    const files = new Set([...oldMap.keys(), ...newMap.keys()]);
+
+    const parts = [];
+    for (const file of files) {
+        const oh = oldMap.get(file);
+        const nh = newMap.get(file);
+        if (oh === nh) continue;
+        let oldText = '', newText = '';
+        try { if (oh) oldText = await readBlobAsString(gentPath, oh); } catch { /* binary/legacy */ }
+        try { if (nh) newText = await readBlobAsString(gentPath, nh); } catch { /* binary/legacy */ }
+        const d = formatUnifiedDiff(file, oldText, newText);
+        if (d) parts.push(d);
+    }
+    return parts.join('\n\n');
+}
+
+async function explain(ref, options = {}) {
+    try {
+        const gentPath = await getGentPath();
+        const repository = await readJSON(path.join(gentPath, COMMITS_FILE));
+        const commits = repository.commits || [];
+        const commitMap = new Map(commits.map(c => [c.hash, c]));
+
+        let title;
+        let diffText;
+
+        if (options.staged) {
+            const staging = await readJSON(path.join(gentPath, STAGING_FILE));
+            const entries = staging.entries || [];
+            if (entries.length === 0) {
+                console.log(chalk.yellow('No staged changes to explain'));
+                return;
+            }
+            const headHash = repository.branches[repository.currentBranch];
+            const headTree = treeEntriesOf(commitMap.get(headHash));
+            const stagedTree = entries
+                .filter(e => e.status !== 'deleted')
+                .map(e => ({ name: e.path, hash: e.hash }));
+            // Overlay staged entries on the HEAD tree
+            const overlay = new Map(headTree.map(e => [e.name, e.hash]));
+            for (const e of entries) {
+                if (e.status === 'deleted') overlay.delete(e.path);
+                else overlay.set(e.path, e.hash);
+            }
+            title = 'Staged changes';
+            diffText = await diffTrees(
+                gentPath,
+                headTree,
+                [...overlay].map(([name, hash]) => ({ name, hash }))
+            );
+            void stagedTree;
+        } else {
+            const targetHash = ref
+                ? (commits.find(c => c.hash === ref || c.hash.startsWith(ref)) || {}).hash
+                : repository.branches[repository.currentBranch];
+            const commit = targetHash ? commitMap.get(targetHash) : null;
+            if (!commit) {
+                console.log(chalk.yellow(ref ? `Commit '${ref}' not found` : 'No commits yet'));
+                return;
+            }
+            const parent = commit.parent ? commitMap.get(commit.parent) : null;
+            title = `Commit ${commit.hash.substring(0, 7)} — ${commit.message}`;
+            diffText = await diffTrees(gentPath, treeEntriesOf(parent), treeEntriesOf(commit));
+        }
+
+        if (!diffText) {
+            console.log(chalk.gray('No textual changes to explain.'));
+            return;
+        }
+
+        const trimmed = diffText.length > MAX_DIFF_CHARS
+            ? diffText.slice(0, MAX_DIFF_CHARS) + '\n... (diff truncated)'
+            : diffText;
+
+        console.log(chalk.bold.cyan(`\n${title}\n`));
+
+        if (!ai.isEnabled()) {
+            console.log(trimmed);
+            console.log(chalk.gray(`\n${ai.disabledHint()}`));
+            return;
+        }
+
+        const spinner = ora(`Asking ${ai.getModel()} to explain...`).start();
+        try {
+            const explanation = await ai.explainChanges(trimmed);
+            spinner.stop();
+            console.log(explanation);
+        } catch (err) {
+            spinner.fail(chalk.yellow('AI request failed — showing the raw diff instead'));
+            console.log(chalk.gray(`(${err.message})\n`));
+            console.log(trimmed);
+        }
+    } catch (error) {
+        if (error.code === 'ENOENT' && error.message.includes('.gent')) {
+            console.error(chalk.red('Error: Not a gent repository'));
+            console.log(chalk.yellow('\nRun "gent init" to initialize a repository'));
+        } else {
+            console.error(chalk.red('Error:'), error.message);
+        }
+        process.exit(1);
+    }
+}
+
+module.exports = explain;

package/src/commands/log.js

@@ -60,7 +60,9 @@ async function log(options) {
             cur = c.parent;
         }
 
-        if (options.oneline) {
+        if (options.graph) {
+            displayGraphLog(commits, headHash, repository.branches || {}, limit);
+        } else if (options.oneline) {
             displayOnelineLog(ordered, headHash);
         } else {
             displayDetailedLog(ordered, headHash, currentBranch, options);
@@ -118,6 +120,54 @@ function displayDetailedLog(commits, currentCommitHash, currentBranch, options)
     });
 }
 
+/**
+ * Display a commit graph reachable from HEAD (parent + mergeParent edges),
+ * ordered newest-first, with branch/HEAD decorations and merge annotations.
+ * A simplified single-rail graph: merges are annotated rather than drawn as
+ * separate lanes, which keeps the output readable in a terminal.
+ */
+function displayGraphLog(allCommits, headHash, branches, limit) {
+    const map = new Map(allCommits.map(c => [c.hash, c]));
+
+    // Reachable set from HEAD via both edges.
+    const reachable = [];
+    const seen = new Set();
+    const stack = [headHash];
+    while (stack.length) {
+        const h = stack.pop();
+        if (!h || seen.has(h)) continue;
+        const c = map.get(h);
+        if (!c) continue;
+        seen.add(h);
+        reachable.push(c);
+        if (c.parent) stack.push(c.parent);
+        if (c.mergeParent) stack.push(c.mergeParent);
+    }
+    reachable.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
+    const limited = reachable.slice(0, limit);
+
+    // Branch labels by commit hash.
+    const refs = new Map();
+    for (const [name, hash] of Object.entries(branches)) {
+        if (!hash) continue;
+        if (!refs.has(hash)) refs.set(hash, []);
+        refs.get(hash).push(name);
+    }
+
+    console.log(chalk.bold.cyan('\nCommit graph:\n'));
+    limited.forEach((c, i) => {
+        const headLabel = c.hash === headHash ? chalk.yellow.bold(' (HEAD)') : '';
+        const refLabel = refs.has(c.hash) ? chalk.green(` (${refs.get(c.hash).join(', ')})`) : '';
+        const time = chalk.gray(`(${formatDistanceToNow(new Date(c.timestamp), { addSuffix: true })})`);
+        console.log(`${chalk.yellow('*')} ${chalk.yellow(c.hash.substring(0, 7))}${headLabel}${refLabel} ${c.message} ${time}`);
+        if (c.mergeParent) {
+            console.log(chalk.gray(`|\\  merge: ${(c.parent || '').substring(0, 7)} + ${c.mergeParent.substring(0, 7)}`));
+        }
+        if (i < limited.length - 1) console.log(chalk.gray('|'));
+    });
+    console.log();
+}
+
 /**
  * Display oneline commit log
  */

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 journal = require('../utils/journal');
 
 /**
  * Merge a branch into the current branch
@@ -66,6 +67,7 @@ async function merge(sourceBranch, options) {
         // Fast-forward: current branch is merge base → just move pointer
         if (baseHash === oursHash) {
             spinner.text = 'Fast-forward merge...';
+            await journal.recordOp(gentPath, 'merge', `fast-forward '${sourceBranch}' into ${currentBranch}`, { restoreTree: true });
             repository.branches[currentBranch] = theirsHash;
             await writeJSON(path.join(gentPath, COMMITS_FILE), repository);
 
@@ -165,6 +167,8 @@ async function merge(sourceBranch, options) {
                 }
             };
 
+            await journal.recordOp(gentPath, 'merge', `merge '${sourceBranch}' into ${currentBranch}`);
+
             repository.commits.push(mergeCommit);
             repository.branches[currentBranch] = mergeCommit.hash;
             await writeJSON(path.join(gentPath, COMMITS_FILE), repository);

package/src/commands/pull.js

@@ -30,7 +30,7 @@ const { getGentPath, readJSON, writeJSON } = require('../utils/fileSystem');
 const { COMMITS_FILE, CONFIG_FILE, API_ENDPOINTS, buildRepoUrl, parseRemoteUrl } = require('../utils/constants');
 const apiClient = require('../utils/api-client');
 const authStorage = require('../utils/auth-storage');
-const { storeBlob, objectExists, readBlobAsString, decodeRemoteBlobContent } = require('../utils/hash-engine');
+const { storeBlob, objectExists, readBlob, readBlobAsString, decodeRemoteBlobContent } = require('../utils/hash-engine');
 const { findMergeBase, mergeTreeEntries } = require('../utils/merge-engine');
 const { generateCommitHash } = require('../utils/helpers');
 
@@ -311,10 +311,11 @@ async function checkoutTree(gentPath, cwd, previousTree, nextTree) {
         const relPath = entry.name || entry.path;
         if (!relPath || !entry.hash) continue;
 
-        const content = await readBlobAsString(gentPath, entry.hash);
+        // Write the raw Buffer so binary blobs round-trip byte-exact.
+        const buf = await readBlob(gentPath, entry.hash);
         const fullPath = path.join(cwd, relPath);
         await fs.mkdir(path.dirname(fullPath), { recursive: true });
-        await fs.writeFile(fullPath, content, 'utf-8');
+        await fs.writeFile(fullPath, buf);
     }
 }
 

package/src/commands/reset.js

@@ -30,6 +30,7 @@ const ora = require('ora');
 const { getGentPath, readJSON, writeJSON, pathExists } = require('../utils/fileSystem');
 const { STAGING_FILE, COMMITS_FILE } = require('../utils/constants');
 const { readBlobAsString } = require('../utils/hash-engine');
+const journal = require('../utils/journal');
 
 /**
  * Reset staging or HEAD
@@ -112,6 +113,15 @@ async function resetHead(gentPath, cwd, args, options) {
 
     const spinner = ora(`Resetting to ${target.hash.substring(0, 7)}...`).start();
 
+    // Journal pre-state. A hard reset discards working-tree content, so flag it
+    // for working-tree restore on undo.
+    await journal.recordOp(
+        gentPath,
+        'reset',
+        `${options.hard ? 'hard' : 'soft'} reset to ${target.hash.substring(0, 7)}`,
+        { restoreTree: !!options.hard }
+    );
+
     // Move branch pointer
     repository.branches[currentBranch] = target.hash;
     await writeJSON(path.join(gentPath, COMMITS_FILE), repository);