gent-cli 6.0.0 → 7.0.0

package/QUICKSTART.md

@@ -1,198 +1,229 @@
-# Quick Start Guide - Gent CLI
+# Gent CLI — Quick Start Guide
 
-## Installation & Setup
+## Requirements
+
+- Node.js **18 or newer**
+- npm
+
+## Installation
 
 ```bash
-# Navigate to the CLI directory
 cd apps/Cli
-
-# Install dependencies
 npm install
-
-# Test the CLI
 node src/index.js --help
 ```
 
-## Make it Globally Available (Optional)
+Make `gent` available globally:
 
 ```bash
-# Link the CLI globally
 npm link
-
-# Now you can use 'gent' from anywhere
 gent --help
 ```
 
+---
+
 ## Your First Repository
 
 ### 1. Initialize
+
 ```bash
-# Create a new directory
 mkdir my-project
 cd my-project
-
-# Initialize gent repository
 gent init
 ```
 
-You'll be prompted for:
-- Your name
-- Your email
-- Repository name
-- Repository description
+Skip the interactive prompts:
 
-Or skip prompts with `-y`:
 ```bash
 gent init -y
 ```
 
 ### 2. Add Files
+
 ```bash
-# Create some files
 echo "console.log('Hello');" > index.js
-
-# Add to staging area
 gent add index.js
-
-# Or add all files
+# or add everything
 gent add .
 ```
 
 ### 3. Check Status
+
 ```bash
 gent status
+gent status -s   # short format
 ```
 
-### 4. Commit Changes
+### 4. Commit
+
 ```bash
-# With message flag
 gent commit -m "Initial commit"
+```
+
+Let AI suggest a message from your staged diff (requires `ANTHROPIC_API_KEY`):
 
-# Or interactive
-gent commit
+```bash
+gent commit --ai
 ```
 
 ### 5. View History
+
 ```bash
-# See all commits
 gent log
-
-# Compact view
 gent log --oneline
-
-# Limit commits shown
 gent log -n 5
+gent log --graph   # ASCII commit graph with branches and merges
 ```
 
+---
+
 ## Working with Branches
 
-### Create a Branch
 ```bash
-gent branch feature-name
+gent branch feature-name       # create
+gent checkout feature-name     # switch
+gent checkout -b new-feature   # create and switch
+gent branch                    # list all
+gent branch -d old-feature     # delete (undoable)
 ```
 
-### Switch to Branch
-```bash
-gent checkout feature-name
-```
+---
+
+## Merging
 
-### Create and Switch
 ```bash
-gent checkout -b new-feature
+gent checkout main
+gent merge feature-login
 ```
 
-### List Branches
+If the merge is clean it commits automatically. If there are conflicts:
+
 ```bash
-gent branch
+gent resolve        # walk each conflict hunk interactively → Ours / Theirs / Both / Edit / Ask AI
+gent push
 ```
 
-### Delete Branch
+Or resolve markers by hand then:
+
 ```bash
-gent branch -d old-feature
+gent add .
+gent commit -m "Resolve merge"
 ```
 
+---
+
 ## Common Workflows
 
-### Feature Development
+### Feature development
+
 ```bash
-# Start a new feature
 gent checkout -b feature-login
 
-# Make changes
 echo "// Login code" > login.js
 gent add login.js
 gent commit -m "Add login feature"
 
-# View your work
-gent log
-
-# Switch back to main
 gent checkout main
+gent merge feature-login
+gent log --graph
 ```
 
-### Quick Commit All
+### Made a mistake? Undo it.
+
 ```bash
-# Stage and commit all changes
-gent add .
-gent commit -m "Update all files"
+gent undo              # reverse the last commit / merge / reset / checkout
+gent undo --list       # see what can be undone
+gent redo              # re-apply the last undone operation
 ```
 
-### Check What Changed
-```bash
-# See status
-gent status
+Undo never deletes your working files. For hard-reset / fast-forward merges it
+also restores file content from the object store.
+
+### Understand what changed
 
-# Short format
-gent status -s
+```bash
+gent explain                  # explain the latest commit in plain language
+gent explain <commit_hash>    # explain a specific commit
+gent explain --staged         # explain what is currently staged
 ```
 
-## Tips & Tricks
+### Repository health
+
+```bash
+gent summary                  # branch counts, contributors, most-changed files, store size
+gent summary --ai             # + a short AI-written health narrative
+```
 
-1. **Use .gentignore** - Exclude files like `node_modules/`
-2. **Commit Often** - Small commits are easier to track
-3. **Descriptive Messages** - Write clear commit messages
-4. **Branch for Features** - Keep main branch stable
-5. **Check Status** - Always review before committing
+---
 
-## Running the Demo
+## Optional AI Features
 
-See the CLI in action:
+All AI features are off by default and have a non-AI fallback.
 
 ```bash
-chmod +x demo.sh
-./demo.sh
+export ANTHROPIC_API_KEY=sk-ant-...
+export GENT_AI_MODEL=claude-haiku-4-5   # optional; default is claude-opus-4-8
+
+gent commit --ai       # AI-suggested commit message
+gent explain           # plain-language diff summary
+gent resolve           # adds "Ask AI" option per conflict hunk
+gent summary --ai      # health narrative
 ```
 
+---
+
+## Tips & Tricks
+
+1. **Undo freely** — `gent undo` reverses history-changing commands without deleting files.
+2. **Use `gent resolve` for conflicts** — faster than editing conflict markers by hand.
+3. **Run `gent summary`** after a sprint to see who changed what and how big the repo has grown.
+4. **`gent log --graph`** gives you a visual picture of your branch and merge history.
+5. **Commit often** — small commits are easier to track and undo individually.
+6. **Use `.gentignore`** — exclude `node_modules/`, `.env`, build artifacts.
+7. **Descriptive messages** — `gent commit --ai` can help when you are stuck.
+8. **Branch for features** — keep `main` stable.
+
+---
+
 ## Troubleshooting
 
-**Not a gent repository error?**
+**Not a gent repository?**
 ```bash
-# Make sure you initialized
 gent init
 ```
 
-**No changes to commit?**
+**Nothing to commit?**
 ```bash
-# Add files first
 gent add <files>
+gent status
 ```
 
 **Command not found?**
 ```bash
-# Use node directly
+# Run without linking
 node src/index.js <command>
-
 # Or link globally
 npm link
 ```
 
-## Next Steps
+**Merge left conflict markers?**
+```bash
+gent resolve       # interactive resolver
+# or edit files, then:
+gent add .
+gent commit -m "Resolve conflicts"
+```
 
-- Read the full [README.md](README.md)
-- Explore the [source code](src/)
-- Try the [demo script](demo.sh)
-- Build your own commands!
+**Undo went too far?**
+```bash
+gent redo
+```
 
 ---
 
-**Happy coding with Gent! 🚀**
+## Next Steps
+
+- Full command reference: [docs/COMMANDS.md](docs/COMMANDS.md)
+- How the algorithms work: [docs/ALGORITHMS.md](docs/ALGORITHMS.md)
+- Architecture overview: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- Full workflow with remote sync: [README.md](README.md)

package/README.md

@@ -12,10 +12,23 @@ The CLI is configured in `src/utils/constants.js` to use that deployed API. Do n
 
 ## Requirements
 
-- Node.js 14 or newer
-- Internet access to `https://gent-api.onrender.com`
+- Node.js 18 or newer
+- Internet access to `https://gent-api.onrender.com` (only for remote/auth commands; local commands work offline)
 - A Gent account, created with `gent register`
 
+## What makes Gent "smart"
+
+Beyond a faithful git-like workflow, Gent adds:
+
+- **diff3 three-way merge** with language-aware auto-resolution (JSON key merge, import unioning) that resolves more conflicts correctly and never merges unsafely.
+- **`gent undo` / `gent redo`** — a one-command safety net over an operation journal (friendlier than `git reflog`).
+- **`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`.
+
+See [docs/COMMANDS.md](docs/COMMANDS.md) for the full reference and
+[docs/ALGORITHMS.md](docs/ALGORITHMS.md) for how the engines work.
+
 ## Install
 
 From npm:
@@ -137,6 +150,8 @@ Use the `/api/repos/<owner_id>/<repo_name>` path from the previous command:
 gent remote add origin /api/repos/2/my-project
 ```
 
+If the current folder is not initialized yet, `gent remote add` initializes `.gent` first, then adds the remote. You can still run `gent init` yourself before this step if you prefer the explicit flow.
+
 Check it:
 
 ```bash
@@ -307,7 +322,14 @@ gent merge feature-login
 gent push
 ```
 
-If there are conflicts, resolve the files, then:
+If there are conflicts, resolve them interactively (recommended):
+
+```bash
+gent resolve        # walk each conflict; it can finalize the merge commit for you
+gent push
+```
+
+Or resolve the markers by hand, then:
 
 ```bash
 gent add .
@@ -448,6 +470,42 @@ gent checkout <branch>
 gent checkout -b <branch>
 gent merge <branch>
 gent merge <branch> -m "Merge message"
+gent resolve                      # interactively resolve merge conflicts
+```
+
+### Safety Net (undo / redo)
+
+```bash
+gent undo                         # reverse the last commit/merge/reset/checkout
+gent undo --list                  # show the operation history
+gent redo                         # re-apply the last undone operation
+```
+
+Undo never deletes your working files; for content-discarding operations
+(`reset --hard`, fast-forward merge, pull) it restores them from the object store.
+
+### Insight
+
+```bash
+gent summary                      # repository health & statistics dashboard
+gent summary --ai                 # + a short AI-written assessment (needs a key)
+gent log --graph                  # ASCII commit graph with branches and merges
+gent explain                      # explain the latest commit in plain language
+gent explain <commit>             # explain a specific commit
+gent explain --staged             # explain currently staged changes
+```
+
+### Optional AI features
+
+AI is off by default and every feature has a non-AI fallback. Enable it with:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+export GENT_AI_MODEL=claude-haiku-4-5   # optional; default is claude-opus-4-8
+
+gent commit --ai                  # suggest a commit message from the staged diff
+gent explain                      # narrate a diff instead of just printing it
+gent resolve                      # adds an "Ask AI" choice per conflict hunk
 ```
 
 ### Tags
@@ -513,6 +571,7 @@ Inside each repo:
 ├── config.json
 ├── commits.json
 ├── staging.json
+├── journal.json   # operation journal for undo/redo (created on first op)
 ├── HEAD
 ├── objects/
 └── refs/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gent-cli",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "description": "A modern, Git-like version control CLI with built-in cloud authentication and global user identity management.",
   "main": "src/index.js",
   "bin": {
@@ -8,7 +8,9 @@
   },
   "scripts": {
     "start": "node src/index.js",
-    "test": "node --check src/index.js && node --check tests/remote-e2e.js",
+    "test": "node --check src/index.js && node --test tests/diff.test.js tests/merge.test.js tests/hash.test.js tests/merge-base.test.js && node tests/offline-e2e.js",
+    "test:unit": "node --test tests/diff.test.js tests/merge.test.js tests/hash.test.js tests/merge-base.test.js",
+    "test:e2e": "node tests/offline-e2e.js",
     "test:remote:e2e": "node tests/remote-e2e.js",
     "demo": "bash demo.sh",
     "link": "npm link",
@@ -47,7 +49,7 @@
     "ora": "^5.4.1"
   },
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=18.0.0"
   },
   "files": [
     "src/",

package/src/commands/branch.js

@@ -10,6 +10,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 journal = require('../utils/journal');
 
 /**
  * Manage branches
@@ -110,6 +111,8 @@ async function deleteBranch(name, repository, gentPath) {
         process.exit(1);
     }
 
+    await journal.recordOp(gentPath, 'branch-delete', `delete branch '${name}'`);
+
     delete branches[name];
     repository.branches = branches;
 

package/src/commands/checkout.js

@@ -7,6 +7,7 @@ const path = require('path');
 const chalk = require('chalk');
 const { getGentPath, readJSON, writeJSON } = require('../utils/fileSystem');
 const { COMMITS_FILE } = require('../utils/constants');
+const journal = require('../utils/journal');
 
 /**
  * Switch to a different branch
@@ -28,6 +29,8 @@ async function checkout(branch, options) {
             }
 
             // Create and switch to new branch
+            await journal.recordOp(gentPath, 'checkout', `create branch '${branch}'`);
+
             const currentCommit = branches[repository.currentBranch] || null;
             branches[branch] = currentCommit;
             repository.branches = branches;
@@ -52,6 +55,8 @@ async function checkout(branch, options) {
             return;
         }
 
+        await journal.recordOp(gentPath, 'checkout', `switch to branch '${branch}'`);
+
         repository.currentBranch = branch;
         await writeJSON(path.join(gentPath, COMMITS_FILE), repository);
 

package/src/commands/commit.js

@@ -11,7 +11,10 @@ const { getGentPath, readJSON, writeJSON } = require('../utils/fileSystem');
 const authStorage = require('../utils/auth-storage');
 const { STAGING_FILE, COMMITS_FILE, CONFIG_FILE } = require('../utils/constants');
 const { generateCommitHash } = require('../utils/helpers');
-const { storeTree, snapshotFile } = require('../utils/hash-engine');
+const { storeTree, snapshotFile, readBlobAsString } = require('../utils/hash-engine');
+const { formatUnifiedDiff } = require('../utils/diff-engine');
+const journal = require('../utils/journal');
+const ai = require('../utils/ai-service');
 
 /**
  * Create a new commit
@@ -36,6 +39,25 @@ async function commit(options) {
         // Get commit message
         let message = options.message;
 
+        // Optional: AI-suggested commit message (`gent commit --ai`)
+        if (!message && options.ai) {
+            if (!ai.isEnabled()) {
+                console.log(chalk.yellow(ai.disabledHint()));
+            } else {
+                const suggested = await suggestMessage(gentPath, stagedEntries);
+                if (suggested) {
+                    const answer = await inquirer.prompt([{
+                        type: 'input',
+                        name: 'message',
+                        message: 'Commit message (AI-suggested, edit as needed):',
+                        default: suggested.split('\n')[0],
+                        validate: (input) => input.length > 0 || 'Commit message cannot be empty'
+                    }]);
+                    message = answer.message;
+                }
+            }
+        }
+
         if (!message) {
             const answer = await inquirer.prompt([
                 {
@@ -148,7 +170,9 @@ async function commit(options) {
             }
         };
 
-        // Save commit
+        // Save commit (journal pre-state first so "gent undo" can reverse it)
+        await journal.recordOp(gentPath, 'commit', `${message} [${repository.currentBranch}]`);
+
         repository.commits = repository.commits || [];
         repository.commits.push(commitObj);
         repository.branches[repository.currentBranch] = commitObj.hash;
@@ -181,4 +205,43 @@ async function commit(options) {
     }
 }
 
+/**
+ * Build a compact staged-diff summary and ask the AI for a commit message.
+ * Returns null on any failure (caller falls back to a manual prompt).
+ * @param {String} gentPath
+ * @param {Array} stagedEntries
+ * @returns {Promise<String|null>}
+ */
+async function suggestMessage(gentPath, stagedEntries) {
+    try {
+        const repository = await readJSON(path.join(gentPath, COMMITS_FILE));
+        const headHash = repository.branches[repository.currentBranch];
+        const headCommit = headHash ? (repository.commits || []).find(c => c.hash === headHash) : null;
+        const headMap = new Map(
+            ((headCommit && headCommit.tree) ? headCommit.tree : (headCommit ? headCommit.files : []) || [])
+                .map(f => [f.path || f.name, f.hash])
+        );
+
+        const parts = [];
+        for (const e of stagedEntries) {
+            if (e.status === 'deleted') { parts.push(`deleted: ${e.path}`); continue; }
+            let oldText = '';
+            const prev = headMap.get(e.path);
+            try { if (prev) oldText = await readBlobAsString(gentPath, prev); } catch { /* binary */ }
+            let newText = '';
+            try { newText = await readBlobAsString(gentPath, e.hash); } catch { /* binary */ }
+            const d = formatUnifiedDiff(e.path, oldText, newText);
+            parts.push(d || `${e.status}: ${e.path}`);
+        }
+
+        const summary = parts.join('\n\n').slice(0, 12000);
+        const spinner = ora(`Asking ${ai.getModel()} for a commit message...`).start();
+        const msg = await ai.suggestCommitMessage(summary);
+        spinner.stop();
+        return msg || null;
+    } catch {
+        return null;
+    }
+}
+
 module.exports = commit;