gent-cli 6.0.1 → 8.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:
@@ -309,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 .
@@ -450,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
@@ -515,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,14 +1,16 @@
 {
   "name": "gent-cli",
-  "version": "6.0.1",
-  "description": "A modern, Git-like version control CLI with built-in cloud authentication and global user identity management.",
+  "version": "8.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": {
     "gent": "src/index.js"
   },
   "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/ai.js

@@ -0,0 +1,82 @@
+/**
+ * AI Command - Manage and verify AI integration.
+ *
+ *   gent ai status            → show key source, model, where it came from
+ *   gent ai test              → make a tiny live request to confirm it works
+ *   gent ai models            → list the model ids gent suggests
+ */
+
+const chalk = require('chalk');
+const ora = require('ora');
+const ai = require('../utils/ai-service');
+const userConfig = require('../utils/user-config');
+
+const SUGGESTED_MODELS = [
+    { id: 'claude-opus-4-7', tag: 'flagship', note: 'Highest quality' },
+    { id: 'claude-sonnet-4-6', tag: 'balanced', note: 'Strong, faster, cheaper' },
+    { id: 'claude-haiku-4-5', tag: 'fastest', note: 'Fastest & cheapest' },
+];
+
+async function aiCommand(subcommand) {
+    const sub = (subcommand || 'status').toLowerCase();
+    switch (sub) {
+        case 'status': return status();
+        case 'test': return test();
+        case 'models': return models();
+        default:
+            console.error(chalk.red(`Unknown subcommand '${sub}'`));
+            console.log(chalk.gray('Usage: gent ai <status|test|models>'));
+            process.exit(1);
+    }
+}
+
+async function status() {
+    const { value: key, source: keySource } = await ai.resolveKey();
+    const model = await ai.resolveModel();
+    const { source: modelSource } = await userConfig.getResolved('ai.model');
+
+    console.log(chalk.bold.cyan('\nGent AI status\n'));
+    if (key) {
+        console.log(`  ${chalk.green('●')} API key:   ${userConfig.maskSecret(key)}  ${chalk.gray(`[${keySource}]`)}`);
+    } else {
+        console.log(`  ${chalk.gray('○')} API key:   ${chalk.gray('not set')}`);
+        console.log(chalk.gray('             ↳ ' + ai.disabledHint()));
+    }
+    console.log(`  ${chalk.green('●')} Model:     ${model}  ${chalk.gray(`[${modelSource}]`)}`);
+    console.log(chalk.gray('\n  Run `gent ai test` to verify the key actually works.'));
+    console.log();
+}
+
+async function test() {
+    const { value: key } = await ai.resolveKey();
+    if (!key) {
+        console.error(chalk.red('No AI key configured.'));
+        console.log(chalk.yellow('Set one with `gent config set ai.api_key <key>`.'));
+        process.exit(1);
+    }
+
+    const model = await ai.resolveModel();
+    const spinner = ora(`Pinging Anthropic (${model})...`).start();
+    try {
+        const reply = await ai.complete({
+            prompt: 'Reply with the single word: pong',
+            maxTokens: 8,
+        });
+        spinner.succeed(chalk.green(`✓ Reachable. Reply: "${reply}"`));
+    } catch (err) {
+        spinner.fail(chalk.red(err.message));
+        process.exit(1);
+    }
+}
+
+async function models() {
+    const current = await ai.resolveModel();
+    console.log(chalk.bold.cyan('\nSuggested Claude models\n'));
+    for (const m of SUGGESTED_MODELS) {
+        const active = m.id === current ? chalk.green(' (current)') : '';
+        console.log(`  ${chalk.cyan(m.id.padEnd(22))} ${chalk.gray(m.tag.padEnd(10))} ${m.note}${active}`);
+    }
+    console.log(chalk.gray('\n  Switch with: gent config set ai.model <id>\n'));
+}
+
+module.exports = aiCommand;

package/src/commands/ask.js

@@ -0,0 +1,121 @@
+/**
+ * Ask Command - Plain-English Q&A about the current repo.
+ *
+ *   gent ask "what does this project do?"
+ *   gent ask "who has touched src/server.js recently?"
+ *   gent ask "what's pending on the current branch?"
+ *
+ * Builds a compact repo summary (README + last N commits + tree listing) and
+ * sends it as context. Falls back to a useful text dump if no AI key is set.
+ */
+
+const path = require('path');
+const chalk = require('chalk');
+const ora = require('ora');
+const { getGentPath, readJSON, pathExists } = require('../utils/fileSystem');
+const fs = require('fs').promises;
+const { COMMITS_FILE, CONFIG_FILE } = require('../utils/constants');
+const ai = require('../utils/ai-service');
+
+const MAX_CONTEXT_CHARS = 14000;
+const MAX_COMMITS = 25;
+
+async function ask(question, options = {}) {
+    try {
+        if (!question || !question.trim()) {
+            console.error(chalk.red('Usage: gent ask "<your question>"'));
+            process.exit(1);
+        }
+
+        const gentPath = await getGentPath();
+        const context = await buildRepoContext(gentPath);
+
+        if (!ai.isEnabled()) {
+            console.log(chalk.yellow(ai.disabledHint()));
+            console.log(chalk.gray('\nHere is the raw repo context you can pipe into another tool:\n'));
+            console.log(context);
+            return;
+        }
+
+        const spinner = ora(`Asking ${ai.getModel()}...`).start();
+        try {
+            const answer = await ai.complete({
+                system:
+                    'You are a senior engineer answering questions about a software repository. ' +
+                    'Be concrete and concise. If the answer is not in the context, say so. ' +
+                    'Reference filenames and short commit hashes when helpful.',
+                prompt: `Repository context:\n\n${context}\n\nQuestion: ${question}`,
+                maxTokens: 1024,
+            });
+            spinner.stop();
+            console.log('\n' + answer + '\n');
+        } catch (err) {
+            spinner.fail(chalk.red(err.message));
+            process.exit(1);
+        }
+    } catch (error) {
+        if (error.code === 'ENOENT' && error.message.includes('.gent')) {
+            console.error(chalk.red('Error: Not a gent repository'));
+            console.log(chalk.yellow('Run "gent init" to initialize a repository'));
+        } else {
+            console.error(chalk.red('Error:'), error.message);
+        }
+        process.exit(1);
+    }
+}
+
+async function buildRepoContext(gentPath) {
+    const cwd = process.cwd();
+    const parts = [];
+
+    // Project name + description from config
+    try {
+        const config = await readJSON(path.join(gentPath, CONFIG_FILE));
+        const repo = config.repository || {};
+        parts.push(`# Project\nname: ${repo.name || '(unnamed)'}\ndescription: ${repo.description || ''}`);
+    } catch { /* missing config — fine */ }
+
+    // README if present (any case, common extensions)
+    const readme = await findReadme(cwd);
+    if (readme) {
+        const text = await fs.readFile(readme.path, 'utf-8').catch(() => '');
+        if (text) parts.push(`# README (${readme.rel})\n${text.slice(0, 4000)}`);
+    }
+
+    // Recent commits
+    try {
+        const repository = await readJSON(path.join(gentPath, COMMITS_FILE));
+        const commits = (repository.commits || []).slice(-MAX_COMMITS).reverse();
+        const branch = repository.currentBranch || 'main';
+        const lines = commits.map(c =>
+            `- ${(c.hash || '').slice(0, 7)} (${(c.author?.name || 'unknown')}): ${(c.message || '').split('\n')[0]}`
+        );
+        parts.push(`# Recent commits on '${branch}'\n${lines.join('\n')}`);
+    } catch { /* no commits yet — fine */ }
+
+    // Top-level layout
+    try {
+        const entries = await fs.readdir(cwd, { withFileTypes: true });
+        const layout = entries
+            .filter(e => !e.name.startsWith('.') && e.name !== 'node_modules')
+            .map(e => e.isDirectory() ? `${e.name}/` : e.name)
+            .slice(0, 60);
+        parts.push(`# Top-level layout\n${layout.join('\n')}`);
+    } catch { /* unreadable — fine */ }
+
+    const joined = parts.join('\n\n');
+    return joined.length > MAX_CONTEXT_CHARS
+        ? joined.slice(0, MAX_CONTEXT_CHARS) + '\n... (context truncated)'
+        : joined;
+}
+
+async function findReadme(cwd) {
+    const candidates = ['README.md', 'readme.md', 'README.txt', 'README', 'README.rst'];
+    for (const c of candidates) {
+        const p = path.join(cwd, c);
+        if (await pathExists(p)) return { path: p, rel: c };
+    }
+    return null;
+}
+
+module.exports = ask;

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;