gent-cli 6.0.0 → 7.0.0

package/src/commands/summary.js

@@ -0,0 +1,176 @@
+/**
+ * ============================================================================
+ * Summary Command - Repository health & statistics dashboard
+ * ============================================================================
+ *
+ * PURPOSE:
+ *   A one-glance overview of the repository — commits, branches, tags,
+ *   contributors, tracked files, object-store size, most-changed files, last
+ *   activity, and how far ahead of the remote the current branch is. Something
+ *   plain git doesn't offer in a single command.
+ *
+ * USAGE:
+ *   gent summary           → print the dashboard
+ *   gent summary --ai      → also include a short AI-written health narrative
+ *
+ * ============================================================================
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const chalk = require('chalk');
+const boxen = require('boxen');
+const { formatDistanceToNow } = require('date-fns');
+const { getGentPath, readJSON, pathExists } = require('../utils/fileSystem');
+const { COMMITS_FILE, CONFIG_FILE } = require('../utils/constants');
+const { readBlobAsString } = require('../utils/hash-engine');
+const { formatBytes } = require('../utils/helpers');
+const ai = require('../utils/ai-service');
+
+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 }));
+}
+
+/** Recursively sum the byte size of the object store. */
+async function objectStoreSize(gentPath) {
+    const root = path.join(gentPath, 'objects');
+    let total = 0;
+    async function walk(dir) {
+        let entries;
+        try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return; }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) await walk(full);
+            else { try { total += (await fs.stat(full)).size; } catch { /* ignore */ } }
+        }
+    }
+    await walk(root);
+    return total;
+}
+
+/** Count change frequency per file across history (hash-only tree diff). */
+function mostChangedFiles(commits, commitMap, limit = 5) {
+    const counts = new Map();
+    for (const c of commits) {
+        const cur = new Map(treeEntriesOf(c).map(e => [e.name, e.hash]));
+        const parent = c.parent ? commitMap.get(c.parent) : null;
+        const prev = new Map(treeEntriesOf(parent).map(e => [e.name, e.hash]));
+        const names = new Set([...cur.keys(), ...prev.keys()]);
+        for (const name of names) {
+            if (cur.get(name) !== prev.get(name)) counts.set(name, (counts.get(name) || 0) + 1);
+        }
+    }
+    return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit);
+}
+
+/** Count commits reachable from `head` not yet known to the remote ref. */
+function aheadCount(commitMap, head, remoteRef) {
+    if (!head) return 0;
+    let cur = head, n = 0;
+    const guard = new Set();
+    while (cur && cur !== remoteRef && !guard.has(cur)) {
+        guard.add(cur);
+        const c = commitMap.get(cur);
+        if (!c) break;
+        n++;
+        cur = c.parent;
+    }
+    return n;
+}
+
+async function summary(options = {}) {
+    try {
+        const gentPath = await getGentPath();
+        const repository = await readJSON(path.join(gentPath, COMMITS_FILE));
+        const configPath = path.join(gentPath, CONFIG_FILE);
+        const config = (await pathExists(configPath)) ? await readJSON(configPath) : {};
+
+        const commits = repository.commits || [];
+        const commitMap = new Map(commits.map(c => [c.hash, c]));
+        const branches = repository.branches || {};
+        const currentBranch = repository.currentBranch || 'main';
+        const tags = repository.tags || {};
+
+        // Contributors
+        const authors = new Map();
+        for (const c of commits) {
+            const key = `${c.author?.name || 'Unknown'} <${c.author?.email || 'unknown'}>`;
+            authors.set(key, (authors.get(key) || 0) + 1);
+        }
+        const topAuthors = [...authors.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+
+        // Tracked files + lines of code (text blobs only)
+        const headHash = branches[currentBranch];
+        const headTree = treeEntriesOf(commitMap.get(headHash));
+        let loc = 0;
+        for (const e of headTree) {
+            try { loc += (await readBlobAsString(gentPath, e.hash)).split('\n').length; } catch { /* binary */ }
+        }
+
+        const storeSize = await objectStoreSize(gentPath);
+        const topChanged = mostChangedFiles(commits, commitMap);
+
+        // Last activity
+        const last = commits.reduce((acc, c) =>
+            (!acc || new Date(c.timestamp) > new Date(acc.timestamp)) ? c : acc, null);
+
+        // Ahead of remote (if known)
+        const remoteRef = (config.remoteRefs || {})[`origin/${currentBranch}`];
+        const ahead = remoteRef ? aheadCount(commitMap, headHash, remoteRef) : null;
+
+        // ── Render ──
+        const lines = [];
+        lines.push(chalk.bold.cyan(config.repository?.name || path.basename(process.cwd())));
+        if (config.repository?.description) lines.push(chalk.gray(config.repository.description));
+        lines.push('');
+        lines.push(`${chalk.bold('Branch:')}      ${chalk.green(currentBranch)}  ${chalk.gray(`(${Object.keys(branches).length} total)`)}`);
+        lines.push(`${chalk.bold('Commits:')}     ${commits.length}`);
+        lines.push(`${chalk.bold('Tags:')}        ${Object.keys(tags).length}`);
+        lines.push(`${chalk.bold('Tracked:')}     ${headTree.length} file(s), ~${loc} lines`);
+        lines.push(`${chalk.bold('Objects:')}     ${formatBytes(storeSize)}`);
+        if (ahead !== null) lines.push(`${chalk.bold('Remote:')}      ${ahead === 0 ? chalk.green('up to date') : chalk.yellow(`${ahead} commit(s) ahead of origin/${currentBranch}`)}`);
+        if (last) lines.push(`${chalk.bold('Last commit:')} ${formatDistanceToNow(new Date(last.timestamp), { addSuffix: true })}`);
+
+        if (topAuthors.length) {
+            lines.push('');
+            lines.push(chalk.bold('Top contributors:'));
+            for (const [name, n] of topAuthors) lines.push(`  ${chalk.green(String(n).padStart(4))}  ${name}`);
+        }
+
+        if (topChanged.length) {
+            lines.push('');
+            lines.push(chalk.bold('Most-changed files:'));
+            for (const [name, n] of topChanged) lines.push(`  ${chalk.yellow(String(n).padStart(4))}  ${name}`);
+        }
+
+        console.log(boxen(lines.join('\n'), {
+            padding: 1, margin: 1, borderStyle: 'round', borderColor: 'cyan', title: 'gent summary', titleAlignment: 'center'
+        }));
+
+        if (options.ai) {
+            if (!ai.isEnabled()) {
+                console.log(chalk.gray(ai.disabledHint()));
+            } else {
+                try {
+                    const facts = lines.join('\n').replace(/\[[0-9;]*m/g, ''); // strip colors
+                    const narrative = await ai.explainChanges(`Repository stats:\n${facts}\n\nGive a 2-3 sentence health assessment.`);
+                    console.log(chalk.cyan(narrative));
+                } catch (err) {
+                    console.log(chalk.yellow(`AI summary failed: ${err.message}`));
+                }
+            }
+        }
+    } 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 = summary;

package/src/commands/undo.js

@@ -0,0 +1,115 @@
+/**
+ * ============================================================================
+ * Undo / Redo Commands - One-command safety net over the operation journal
+ * ============================================================================
+ *
+ * PURPOSE:
+ *   Reverse (or re-apply) the last history-changing operation without having to
+ *   reason about reflogs and commit hashes.
+ *
+ * USAGE:
+ *   gent undo            → Reverse the last operation
+ *   gent undo --list     → Show the operation history (most recent first)
+ *   gent redo            → Re-apply the last undone operation
+ *
+ * See src/utils/journal.js for the recorded state and exact undo semantics
+ * (working files are never deleted).
+ *
+ * ============================================================================
+ */
+
+const chalk = require('chalk');
+const { formatDistanceToNow } = require('date-fns');
+const { getGentPath } = require('../utils/fileSystem');
+const journal = require('../utils/journal');
+
+function shortHash(h) {
+    return h ? h.substring(0, 7) : '(none)';
+}
+
+function notARepo(error) {
+    return error.code === 'ENOENT' && error.message.includes('.gent');
+}
+
+/**
+ * `gent undo` — reverse the last operation, or list history with --list.
+ * @param {Object} options
+ */
+async function undo(options = {}) {
+    try {
+        const gentPath = await getGentPath();
+        const cwd = process.cwd();
+
+        if (options.list) {
+            await printHistory(gentPath);
+            return;
+        }
+
+        const result = await journal.applyUndo(gentPath, cwd);
+        if (!result.ok) {
+            console.log(chalk.yellow('Nothing to undo'));
+            console.log(chalk.gray('History-changing operations (commit, merge, reset, checkout) can be undone.'));
+            return;
+        }
+
+        const { entry } = result;
+        console.log(chalk.green(`✓ Undid ${chalk.bold(entry.op)}: ${entry.description}`));
+        console.log(chalk.gray(`  Now on '${result.branch}' at ${shortHash(result.head)}`));
+        console.log(chalk.cyan('  Run "gent redo" to re-apply.'));
+    } catch (error) {
+        if (notARepo(error)) {
+            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);
+    }
+}
+
+/**
+ * `gent redo` — re-apply the last undone operation.
+ */
+async function redo() {
+    try {
+        const gentPath = await getGentPath();
+        const cwd = process.cwd();
+
+        const result = await journal.applyRedo(gentPath, cwd);
+        if (!result.ok) {
+            console.log(chalk.yellow('Nothing to redo'));
+            return;
+        }
+
+        const { entry } = result;
+        console.log(chalk.green(`✓ Redid ${chalk.bold(entry.op)}: ${entry.description}`));
+        console.log(chalk.gray(`  Now on '${result.branch}' at ${shortHash(result.head)}`));
+    } catch (error) {
+        if (notARepo(error)) {
+            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);
+    }
+}
+
+async function printHistory(gentPath) {
+    const entries = await journal.listEntries(gentPath);
+    if (entries.length === 0) {
+        console.log(chalk.yellow('No operations recorded yet'));
+        return;
+    }
+
+    console.log(chalk.bold.cyan('\nOperation history (most recent first):\n'));
+    entries.forEach((e, i) => {
+        const when = chalk.gray(`(${formatDistanceToNow(new Date(e.timestamp), { addSuffix: true })})`);
+        const marker = i === 0 ? chalk.yellow('● ') : chalk.gray('○ ');
+        console.log(`${marker}${chalk.bold(e.op.padEnd(14))} ${e.description} ${when}`);
+    });
+    console.log(chalk.gray('\n"gent undo" reverses the most recent (●).'));
+}
+
+module.exports = undo;
+module.exports.redo = redo;

package/src/index.js

@@ -9,13 +9,15 @@
  * COMMANDS:
  *   Repository:  init, clone
  *   Staging:     add, rm, reset, status, diff
- *   History:     commit, log, show, tag
- *   Branching:   branch, checkout, merge, stash
+ *   History:     commit, log, show, tag, explain
+ *   Branching:   branch, checkout, merge, resolve, stash
+ *   Safety:      undo, redo
+ *   Insight:     summary
  *   Remote:      remote, push, pull
  *   Auth:        register, login, logout, whoami
  *
  * @author Abdalrahman Kanawati
- * @version 2.0.0
+ * @version 7.0.0
  */
 
 const { program } = require('commander');
@@ -42,6 +44,10 @@ const remoteCommand = require('./commands/remote');
 const pushCommand = require('./commands/push');
 const pullCommand = require('./commands/pull');
 const reposCommand = require('./commands/repos');
+const undoCommand = require('./commands/undo');
+const resolveCommand = require('./commands/resolve');
+const summaryCommand = require('./commands/summary');
+const explainCommand = require('./commands/explain');
 
 // Import auth commands
 const registerCommand = require('./commands/register');
@@ -110,6 +116,7 @@ program
     .description('Record changes to the repository')
     .option('-m, --message <message>', 'Commit message')
     .option('-a, --all', 'Automatically stage all modified files')
+    .option('--ai', 'Suggest a commit message with AI (needs ANTHROPIC_API_KEY)')
     .action(commitCommand);
 
 program
@@ -117,6 +124,7 @@ program
     .description('Show commit logs')
     .option('-n, --number <count>', 'Limit the number of commits to show', '10')
     .option('--oneline', 'Show each commit on a single line')
+    .option('--graph', 'Show an ASCII commit graph with branches and merges')
     .option('--stat', 'Show file change statistics')
     .action(logCommand);
 
@@ -133,6 +141,18 @@ program
     .option('-d, --delete <name>', 'Delete a tag')
     .action(tagCommand);
 
+program
+    .command('explain [ref]')
+    .description('Explain a commit or staged changes in plain language')
+    .option('--staged', 'Explain staged changes instead of a commit')
+    .action(explainCommand);
+
+program
+    .command('summary')
+    .description('Show a repository health & statistics dashboard')
+    .option('--ai', 'Add an AI-written health narrative (needs ANTHROPIC_API_KEY)')
+    .action(summaryCommand);
+
 // ─── Branching & Merging ────────────────────────────────
 
 program
@@ -155,6 +175,11 @@ program
     .option('-m, --message <message>', 'Merge commit message')
     .action(mergeCommand);
 
+program
+    .command('resolve')
+    .description('Interactively resolve merge conflicts left by "gent merge"')
+    .action(resolveCommand);
+
 program
     .command('stash [subcommand]')
     .description('Stash working tree changes (pop|list|drop|apply)')
@@ -162,6 +187,17 @@ program
     .option('-i, --index <index>', 'Stash index for pop/apply/drop')
     .action(stashCommand);
 
+program
+    .command('undo')
+    .description('Reverse the last history-changing operation (safety net)')
+    .option('-l, --list', 'Show the operation history')
+    .action(undoCommand);
+
+program
+    .command('redo')
+    .description('Re-apply the last undone operation')
+    .action(undoCommand.redo);
+
 // ─── Remote & Sync ──────────────────────────────────────
 
 program

package/src/utils/ai-service.js

@@ -0,0 +1,156 @@
+/**
+ * ============================================================================
+ * AI Service - Optional, key-gated Claude integration (hybrid layer)
+ * ============================================================================
+ *
+ * PURPOSE:
+ *   Power Gent's *optional* "smart" features (commit-message suggestions, diff
+ *   explanations, AI-assisted conflict resolution). Every feature has a
+ *   reliable algorithmic path; this layer only activates when the user has set
+ *   an API key, and degrades gracefully (never throws into a command) when it
+ *   is absent or the request fails.
+ *
+ * ENABLEMENT:
+ *   Set ANTHROPIC_API_KEY in the environment to enable. Optionally set
+ *   GENT_AI_MODEL to pick a model (default: claude-opus-4-8). For a cheaper /
+ *   faster option set GENT_AI_MODEL=claude-haiku-4-5.
+ *
+ * IMPLEMENTATION NOTE:
+ *   Calls the Anthropic Messages API (POST /v1/messages) directly over the
+ *   project's existing `axios` dependency, to honour Gent's "no new runtime
+ *   dependencies" constraint. A production app would normally use the official
+ *   `@anthropic-ai/sdk`; raw HTTP is a deliberate trade-off here because the AI
+ *   layer is optional and self-contained.
+ *
+ * ============================================================================
+ */
+
+const axios = require('axios');
+
+const API_URL = 'https://api.anthropic.com/v1/messages';
+const API_VERSION = '2023-06-01';
+const DEFAULT_MODEL = 'claude-opus-4-8';
+
+/**
+ * Resolve the API key (env only — keeps secrets out of the repo).
+ * @returns {String|null}
+ */
+function getApiKey() {
+    return process.env.ANTHROPIC_API_KEY || null;
+}
+
+/**
+ * @returns {Boolean} whether AI features are enabled.
+ */
+function isEnabled() {
+    return !!getApiKey();
+}
+
+/**
+ * @returns {String} the model id to use.
+ */
+function getModel() {
+    return process.env.GENT_AI_MODEL || DEFAULT_MODEL;
+}
+
+/**
+ * One-line hint shown by commands when AI is requested but no key is set.
+ * @returns {String}
+ */
+function disabledHint() {
+    return 'AI features are off — set ANTHROPIC_API_KEY to enable (optional: GENT_AI_MODEL).';
+}
+
+/**
+ * Low-level single-shot completion. Returns the assistant's text.
+ * @param {Object} opts
+ * @param {String} opts.prompt - user content
+ * @param {String} [opts.system] - system prompt
+ * @param {Number} [opts.maxTokens]
+ * @returns {Promise<String>}
+ */
+async function complete({ prompt, system, maxTokens = 1024 }) {
+    const apiKey = getApiKey();
+    if (!apiKey) throw new Error('AI not enabled');
+
+    const body = {
+        model: getModel(),
+        max_tokens: maxTokens,
+        messages: [{ role: 'user', content: prompt }]
+    };
+    if (system) body.system = system;
+
+    const res = await axios.post(API_URL, body, {
+        headers: {
+            'x-api-key': apiKey,
+            'anthropic-version': API_VERSION,
+            'content-type': 'application/json'
+        },
+        timeout: 60000
+    });
+
+    const blocks = (res.data && res.data.content) || [];
+    return blocks
+        .filter(b => b.type === 'text')
+        .map(b => b.text)
+        .join('')
+        .trim();
+}
+
+// ─── High-level helpers ─────────────────────────────────
+
+/**
+ * Suggest a concise commit message from a staged diff / summary.
+ * @param {String} diffSummary
+ * @returns {Promise<String>}
+ */
+async function suggestCommitMessage(diffSummary) {
+    const system =
+        'You write clear, conventional git commit messages. Reply with ONLY the commit ' +
+        'message: a concise imperative subject line (<=72 chars), optionally followed by ' +
+        'a blank line and short body. No quotes, no preamble, no markdown fences.';
+    const prompt = `Write a commit message for these staged changes:\n\n${diffSummary}`;
+    return complete({ system, prompt, maxTokens: 512 });
+}
+
+/**
+ * Explain a commit or diff in plain language.
+ * @param {String} content - diff or commit details
+ * @returns {Promise<String>}
+ */
+async function explainChanges(content) {
+    const system =
+        'You are a senior engineer explaining a code change to a teammate. Summarize what ' +
+        'changed and why it matters in a few short bullet points. Be specific and concise.';
+    const prompt = `Explain these changes:\n\n${content}`;
+    return complete({ system, prompt, maxTokens: 1024 });
+}
+
+/**
+ * Propose a resolution for a single merge-conflict hunk.
+ * @param {Object} hunk - { base?, ours, theirs, fileName? }
+ * @returns {Promise<String>} the suggested merged text (no conflict markers)
+ */
+async function resolveConflictHunk({ base, ours, theirs, fileName }) {
+    const system =
+        'You resolve git merge conflicts. Combine the intent of BOTH sides into a single ' +
+        'correct version. Reply with ONLY the resolved file section — no conflict markers, ' +
+        'no explanation, no markdown fences.';
+    const prompt =
+        `File: ${fileName || 'unknown'}\n\n` +
+        `<<<<<<< BASE (common ancestor)\n${base || '(none)'}\n` +
+        `======= OURS\n${ours}\n` +
+        `======= THEIRS\n${theirs}\n>>>>>>>\n\n` +
+        'Return the merged result for this section.';
+    return complete({ system, prompt, maxTokens: 2048 });
+}
+
+module.exports = {
+    isEnabled,
+    getModel,
+    disabledHint,
+    complete,
+    suggestCommitMessage,
+    explainChanges,
+    resolveConflictHunk
+};

package/src/utils/diff-engine.js

@@ -22,6 +22,14 @@
  *   - Move up (i-1) → DELETE (line only in old version)
  *   - Move left (j-1) → INSERT (line only in new version)
  *
+ * COMMON PREFIX/SUFFIX TRIMMING (optimization):
+ *   Before building the O(M×N) matrix, identical leading and trailing lines are
+ *   stripped. Only the differing "middle" is run through LCS; the trimmed lines
+ *   are re-attached as `equal` ops with their original 1-based positions. For
+ *   the common case of a localized edit in a large file this turns an O(M×N)
+ *   matrix into something proportional to the size of the change — a large
+ *   memory and time win — while producing byte-identical output.
+ *
  * HUNK GENERATION:
  *   Groups adjacent changes with N context lines (default 3) into hunks.
  *   Changes within 2*N+1 lines of each other merge into one hunk.
@@ -63,12 +71,14 @@ function buildLcsMatrix(a, b) {
 }
 
 /**
- * Backtrack LCS matrix → line operations.
+ * Backtrack the LCS matrix of two line arrays → line operations with
+ * 1-based positions local to the given arrays. Pure O(M×N) core; callers
+ * normally use buildLineOperations, which trims common prefix/suffix first.
  * @param {String[]} oldLines
  * @param {String[]} newLines
  * @returns {Array<{type: 'equal'|'insert'|'delete', oldLine: number, newLine: number, content: String}>}
  */
-function buildLineOperations(oldLines, newLines) {
+function lcsOperations(oldLines, newLines) {
     const matrix = buildLcsMatrix(oldLines, newLines);
     const ops = [];
     let i = oldLines.length;
@@ -90,6 +100,61 @@ function buildLineOperations(oldLines, newLines) {
     return ops.reverse();
 }
 
+/**
+ * Diff two line arrays into operations, trimming common prefix/suffix before
+ * running LCS on the differing middle. Output is identical to running LCS on
+ * the full arrays, with `oldLine`/`newLine` as absolute 1-based positions.
+ * @param {String[]} oldLines
+ * @param {String[]} newLines
+ * @returns {Array<{type: 'equal'|'insert'|'delete', oldLine: number, newLine: number, content: String}>}
+ */
+function buildLineOperations(oldLines, newLines) {
+    const oldLen = oldLines.length;
+    const newLen = newLines.length;
+    const minLen = Math.min(oldLen, newLen);
+
+    // Common leading lines.
+    let prefix = 0;
+    while (prefix < minLen && oldLines[prefix] === newLines[prefix]) prefix++;
+
+    // Common trailing lines (not overlapping the prefix).
+    let suffix = 0;
+    while (
+        suffix < minLen - prefix &&
+        oldLines[oldLen - 1 - suffix] === newLines[newLen - 1 - suffix]
+    ) suffix++;
+
+    const ops = [];
+
+    // Prefix → equal ops at their original positions.
+    for (let k = 0; k < prefix; k++) {
+        ops.push({ type: 'equal', oldLine: k + 1, newLine: k + 1, content: oldLines[k] });
+    }
+
+    // Middle → LCS, shifted back into absolute coordinates by `prefix`.
+    const oldMid = oldLines.slice(prefix, oldLen - suffix);
+    const newMid = newLines.slice(prefix, newLen - suffix);
+    if (oldMid.length || newMid.length) {
+        for (const op of lcsOperations(oldMid, newMid)) {
+            ops.push({
+                type: op.type,
+                oldLine: op.oldLine + prefix,
+                newLine: op.newLine + prefix,
+                content: op.content
+            });
+        }
+    }
+
+    // Suffix → equal ops at their original positions.
+    for (let k = 0; k < suffix; k++) {
+        const oldIdx = oldLen - suffix + k;
+        const newIdx = newLen - suffix + k;
+        ops.push({ type: 'equal', oldLine: oldIdx + 1, newLine: newIdx + 1, content: oldLines[oldIdx] });
+    }
+
+    return ops;
+}
+
 /**
  * Diff two texts → operations + stats.
  * @param {String} oldText
@@ -229,6 +294,7 @@ module.exports = {
     diffText,
     summarizeOperations,
     buildLcsMatrix,
+    lcsOperations,
     buildLineOperations,
     generateHunks,
     formatUnifiedDiff,