gent-cli 2.1.0 → 5.0.1

package/README.md

@@ -1,17 +1,47 @@
 # Gent CLI
 
-> A modern, Git-like version control CLI with built-in cloud authentication and global user identity management.
-
-Gent is a lightweight version control system that feels exactly like Git but handles user identity automatically through the cloud. No more configuring `user.name` and `user.email` for every repository!
+![npm](https://img.shields.io/npm/v/gent-cli)
+![downloads](https://img.shields.io/npm/dw/gent-cli)
 
-## Features
+> A modern, Git-like version control CLI with built-in cloud authentication and global user identity management.
 
-- **Cloud Authentication**: Login once, work everywhere. Your identity follows you across projects.
-- **Git-like Experience**: Familiar commands (init, add, commit, status, log, branch, checkout).
-- **Cloud Synchronization**: Push and pull repositories to/from the cloud.
-- **Zero Configuration**: `gent init` is silent and auto-detects your authenticated user profile.
-- **Global Identity**: Commits are automatically authored with your cloud profile.
-- **Secure**: Tokens stored securely in your home directory.
+Gent is a lightweight version control system that feels like Git but handles user identity automatically through the cloud. No more configuring `user.name` and `user.email` for every repository.
+
+## Highlights
+
+- **Cloud Authentication** — Login once, work everywhere. JWT-based auth with automatic token refresh.
+- **Git-like Experience** — Familiar commands: `init`, `add`, `commit`, `status`, `log`, `branch`, `checkout`, `merge`, `push`, `pull`, `clone`, and more.
+- **Zero Configuration** — `gent init` auto-detects your authenticated user profile.
+- **Global Identity** — Commits are automatically authored with your cloud profile.
+- **Content-Addressable Storage** — SHA-256 object store with zlib compression and deduplication.
+- **Smart Diff & Merge** — Line-level LCS diff, three-way merge with conflict detection.
+- **Remote Sync** — Push, pull, and clone repositories from the cloud backend.
+- **Secure** — Tokens stored with AES encryption in `~/.gent/auth.json`.
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Authentication](#authentication)
+- [Commands](#commands)
+  - [Repository Setup](#repository-setup)
+  - [Staging & Working Tree](#staging--working-tree)
+  - [History](#history)
+  - [Branching & Merging](#branching--merging)
+  - [Remote & Sync](#remote--sync)
+  - [Authentication Commands](#authentication-commands)
+- [Usage Examples](#usage-examples)
+- [Repository Structure](#repository-structure)
+- [Configuration](#configuration)
+- [Docs](#docs)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Requirements
+
+- Node.js >= 14
 
 ## Installation
 
@@ -19,11 +49,33 @@ Gent is a lightweight version control system that feels exactly like Git but han
 npm install -g gent-cli
 ```
 
+Run locally without installing:
+
+```bash
+cd apps/Cli
+npm install
+node src/index.js --help
+```
+
+## Quickstart
+
+```bash
+# 1) Authenticate
+gent login
+
+# 2) Initialize a repo
+gent init
+
+# 3) Make a first commit
+gent add .
+gent commit -m "Initial commit"
+```
+
 ## Authentication
 
-Gent uses a global authentication system. You only need to login once.
+Gent uses a global authentication system. You only need to log in once.
 
-### Create an Account
+### Register a New Account
 
 ```bash
 gent register
@@ -33,11 +85,11 @@ gent register
 
 ```bash
 gent login
-# or
+# or with flags
 gent login -e user@example.com -p YourPassword
 ```
 
-### Check Status
+### Check Current User
 
 ```bash
 gent whoami
@@ -49,103 +101,201 @@ gent whoami
 gent logout
 ```
 
-## Local Usage
+## Commands
 
-### 1. Initialize a Repository
+### Repository Setup
+
+| Command | Description |
+|---|---|
+| `gent init [-y]` | Initialize a new Gent repository in the current directory. Use `-y` to skip prompts. |
+| `gent clone <url> [directory]` | Clone a remote repository from the cloud backend. |
+
+### Staging & Working Tree
+
+| Command | Description |
+|---|---|
+| `gent status [-s]` | Show the working tree status. Use `-s` for short format. |
+| `gent add <files...> [-A]` | Add files to the staging area. Use `-A` or `--all` to add all files. |
+| `gent rm <files...> [--cached]` | Remove files from the working tree and staging area. Use `--cached` to keep the file on disk. |
+| `gent reset [files...] [--hard <hash> \| --soft <hash>]` | Unstage files or reset HEAD to a specific commit. |
+| `gent diff [files...] [--staged] [--stat]` | Show changes between working tree, staging area, and commits. |
+
+### History
+
+| Command | Description |
+|---|---|
+| `gent commit [-m <message>] [-a]` | Record changes to the repository. Use `-a` to auto-stage all modified files. |
+| `gent log [-n <count>] [--oneline] [--stat]` | Show commit history. Default limit is 10 commits. |
+| `gent show [ref] [--no-patch]` | Show commit details and diff. |
+| `gent tag [name] [-m <message>] [-d <name>]` | Create, list, or delete tags. |
+
+### Branching & Merging
+
+| Command | Description |
+|---|---|
+| `gent branch [name] [-d <name>] [-a]` | List, create, or delete branches. |
+| `gent checkout <branch> [-b]` | Switch branches. Use `-b` to create and switch to a new branch. |
+| `gent merge <branch> [-m <message>]` | Merge a branch into the current branch using a three-way smart merge. |
+| `gent stash [pop \| list \| drop \| apply] [-m <message>] [-i <index>]` | Stash working tree changes. |
+
+### Remote & Sync
+
+| Command | Description |
+|---|---|
+| `gent remote [add \| remove \| set-url] [args...] [-v]` | Manage remote connections. |
+| `gent push [remote] [branch] [-f]` | Push local commits to the remote. Use `-f` to force push. |
+| `gent pull [remote] [branch]` | Pull and merge remote commits into the current branch. |
+
+### Authentication Commands
+
+| Command | Description |
+|---|---|
+| `gent register` | Create a new user account interactively. |
+| `gent login [-e <email>] [-p <password>]` | Log in to your account. |
+| `gent logout` | Log out and clear stored tokens. |
+| `gent whoami` | Display the currently logged-in user. |
+
+## Usage Examples
+
+### Initialize a Repository
 
 ```bash
 gent init
 # Output: Initialized empty Gent repository in /path/to/project
 ```
 
-### 2. Check Status
+### Stage and Commit
 
 ```bash
-gent status
+gent add .
+gent commit -m "Initial commit"
 ```
 
-### 3. Stage Files
+### Work with Branches
 
 ```bash
-gent add filename.js
-# or add all files
-gent add .
+# Create and switch to a new branch
+gent checkout -b feature-login
+
+# List branches
+gent branch
+
+# Switch back to main
+gent checkout main
+
+# Delete a branch
+gent branch -d feature-login
 ```
 
-### 4. Commit Changes
+### View History
 
 ```bash
-gent commit -m "Initial commit"
-# Output: [main a1b2c3d] Initial commit
-# Author: Your Name <your.email@example.com>
+gent log
+gent log --oneline
+gent log -n 5
 ```
 
-## Cloud Features
-
-### 1. Create a Cloud Repository
+### Remote Workflow
 
 ```bash
-# Create and link a local repo
-gent create my-repo --init-local
+# Add a remote
+gent remote add origin https://gent-api.onrender.com/api/repos/123/
+
+# Push to remote
+gent push origin main
 
-# Or initialize with cloud directly
-gent init --cloud
+# Pull from remote
+gent pull origin main
+
+# Clone a repository
+gent clone https://gent-api.onrender.com/api/repos/123/ my-project
 ```
 
-### 2. List Your Repositories
+## Repository Structure
 
-```bash
-gent list
-# or
-gent ls
+Gent creates a `.gent` directory in your project root:
+
+```
+.gent/
+├── config.json       # Project configuration, remotes, user info
+├── commits.json      # Full commit history, branches, and tags
+├── staging.json      # Current staging area
+├── stash.json        # Stashed changes (created on first stash)
+├── HEAD              # Current branch reference
+├── objects/          # Content-addressable blob and tree store
+│   ├── ab/           # First 2 characters of SHA-256 hash
+│   │   └── cdef...   # zlib-compressed object
+│   └── ...
+└── refs/
+    ├── heads/        # Branch references (reserved for future use)
+    └── tags/         # Tag references (reserved for future use)
 ```
 
-### 3. Clone a Repository
+Your authentication tokens are stored globally in `~/.gent/auth.json`.
+
+## Configuration
+
+### Ignore Files
+
+Create a `.gentignore` file in your repository root to exclude files from tracking:
 
-```bash
-gent clone <owner_id>/<repo_name>
-# Example: gent clone 1/my-repo
+```
+node_modules/
+dist/
+.env
+*.log
 ```
 
-### 4. Push Changes
+Default ignored patterns include: `.gent`, `node_modules`, `.git`, `.DS_Store`, `.env`, `dist`, `build`, `coverage`, `.vscode`, `.idea`, and `*.log`.
 
-```bash
-gent push
-# or commit and push in one go
-gent commit -m "Update README" --push
+### Remotes
+
+Remotes are stored in `.gent/config.json`:
+
+```json
+{
+  "remotes": {
+    "origin": {
+      "url": "https://gent-api.onrender.com/api/repos/123/"
+    }
+  }
+}
 ```
 
-### 5. Pull Changes
+## Troubleshooting
 
+**Command not found?**
+
+Make sure the CLI is linked globally:
 ```bash
-gent pull
+npm link
 ```
 
-### 6. Manage Remotes
-
+Or run it directly:
 ```bash
-gent remote add origin <owner_id>/<repo_name>
-gent remote -v
+node src/index.js <command>
 ```
 
-## Repository Structure
+**Not a Gent repository?**
 
-Gent creates a `.gent` directory in your project root:
+Run `gent init` in your project directory first.
 
-```
-.gent/
-├── config.json       # Project configuration
-├── objects/          # Stored file contents
-├── refs/             # Branch pointers
-├── remote.json       # Remote configuration
-└── HEAD             # Current branch reference
-```
+**No changes to commit?**
 
-Your authentication tokens are stored globally in `~/.gent/auth.json`.
+Stage files with `gent add <files>` before committing.
+
+**Authentication errors?**
+
+Run `gent login` to refresh your session. Tokens expire automatically and should refresh; if not, log in again.
+
+## Docs
+
+- [QUICKSTART.md](QUICKSTART.md)
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
 
 ## Contributing
 
-We welcome contributions! Please fork the repository and submit a Pull Request.
+Contributions are welcome! Please fork the repository and submit a Pull Request.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gent-cli",
-  "version": "2.1.0",
+  "version": "5.0.1",
   "description": "A modern, Git-like version control CLI with built-in cloud authentication and global user identity management.",
   "main": "src/index.js",
   "bin": {

package/src/commands/add.js

@@ -1,13 +1,16 @@
 /**
  * Add Command - Add file contents to the staging area
- * Stages files for the next commit
+ * Stages files with content snapshots (blobs) and diff stats
  */
 
+const fs = require('fs').promises;
 const path = require('path');
 const chalk = require('chalk');
 const ora = require('ora');
 const { getGentPath, readJSON, writeJSON, pathExists, getAllFiles, getIgnorePatterns } = require('../utils/fileSystem');
-const { STAGING_FILE } = require('../utils/constants');
+const { STAGING_FILE, COMMITS_FILE } = require('../utils/constants');
+const { storeBlob, hashBlob, isBinaryBuffer, snapshotFile } = require('../utils/hash-engine');
+const { diffText, formatUnifiedDiff } = require('../utils/diff-engine');
 
 /**
  * Add files to staging area
@@ -24,7 +27,19 @@ async function add(files, options) {
 
         // Read current staging area
         const staging = await readJSON(stagingPath);
-        const stagedFiles = new Set(staging.files || []);
+        const stagedEntries = staging.entries || [];
+        const stagedMap = new Map(stagedEntries.map(e => [e.path, e]));
+
+        // Get last commit tree for diff comparison
+        const repository = await readJSON(path.join(gentPath, COMMITS_FILE));
+        const lastCommitHash = repository.branches[repository.currentBranch] || null;
+        const lastCommit = lastCommitHash
+            ? (repository.commits || []).find(c => c.hash === lastCommitHash)
+            : null;
+        const lastTreeMap = new Map(
+            (lastCommit && lastCommit.tree ? lastCommit.tree : (lastCommit ? lastCommit.files : []))
+                .map(f => [f.path || f.name, f.hash])
+        );
 
         let filesToAdd = [];
 
@@ -35,49 +50,113 @@ async function add(files, options) {
             const allFiles = await getAllFiles(cwd, ignorePatterns);
             filesToAdd = allFiles.map(f => path.relative(cwd, f));
         } else {
-            // Add specified files
             for (const file of files) {
                 const filePath = path.resolve(cwd, file);
-
                 if (!await pathExists(filePath)) {
                     spinner.warn(chalk.yellow(`Warning: File not found: ${file}`));
                     continue;
                 }
-
-                const relativePath = path.relative(cwd, filePath);
-                filesToAdd.push(relativePath);
+                filesToAdd.push(path.relative(cwd, filePath));
             }
         }
 
-        // Add files to staging
+        // Snapshot each file → store blob, compute diff
         let addedCount = 0;
-        for (const file of filesToAdd) {
-            if (!stagedFiles.has(file)) {
-                stagedFiles.add(file);
+        let totalInsertions = 0;
+        let totalDeletions = 0;
+        const diffSummaries = [];
+
+        for (const relPath of filesToAdd) {
+            const fullPath = path.join(cwd, relPath);
+            const content = await fs.readFile(fullPath);
+
+            // Skip binary files for diff (still store blob)
+            const binary = isBinaryBuffer(content);
+            const blobHash = await storeBlob(gentPath, content);
+
+            // Check if changed vs last commit
+            const prevHash = lastTreeMap.get(relPath);
+            if (prevHash === blobHash && stagedMap.has(relPath)) {
+                continue; // unchanged, already staged
+            }
+
+            // Determine change status
+            let status = 'added';
+            let stats = { insertions: 0, deletions: 0 };
+
+            if (prevHash && prevHash !== blobHash && !binary) {
+                status = 'modified';
+                try {
+                    const { readBlobAsString } = require('../utils/hash-engine');
+                    const oldContent = await readBlobAsString(gentPath, prevHash);
+                    const diff = diffText(oldContent, content.toString('utf-8'));
+                    stats = { insertions: diff.stats.insertions, deletions: diff.stats.deletions };
+                } catch {
+                    // Old blob may not exist yet (first time adding objects)
+                }
+            } else if (!prevHash) {
+                status = 'added';
+                stats.insertions = content.toString('utf-8').split('\n').length;
+            }
+
+            totalInsertions += stats.insertions;
+            totalDeletions += stats.deletions;
+
+            // Update staging entry
+            stagedMap.set(relPath, {
+                path: relPath,
+                hash: blobHash,
+                status,
+                binary,
+                stats
+            });
+
+            diffSummaries.push({ path: relPath, status, stats, binary });
+            addedCount++;
+        }
+
+        // Detect deleted files (tracked in last commit but gone from disk)
+        for (const [trackedPath, trackedHash] of lastTreeMap) {
+            const fullPath = path.join(cwd, trackedPath);
+            if (!await pathExists(fullPath) && !stagedMap.has(trackedPath)) {
+                stagedMap.set(trackedPath, {
+                    path: trackedPath,
+                    hash: null,
+                    status: 'deleted',
+                    binary: false,
+                    stats: { insertions: 0, deletions: 0 }
+                });
+                diffSummaries.push({ path: trackedPath, status: 'deleted', stats: { insertions: 0, deletions: 0 }, binary: false });
                 addedCount++;
             }
         }
 
-        // Save staging area
-        staging.files = Array.from(stagedFiles);
+        // Save staging area (new format with entries)
+        staging.entries = Array.from(stagedMap.values());
+        staging.files = staging.entries.map(e => e.path); // backward compat
         await writeJSON(stagingPath, staging);
 
-        spinner.succeed(chalk.green(`✓ Added ${addedCount} file(s) to staging area`));
+        spinner.succeed(chalk.green(`Added ${addedCount} file(s) to staging area`));
 
-        if (addedCount > 0) {
-            console.log(chalk.gray('\nStaged files:'));
-            staging.files.forEach(file => {
-                console.log(chalk.green(`  ${file}`));
-            });
-            console.log(chalk.cyan('\nℹ Use "gent commit" to record your changes'));
+        if (diffSummaries.length > 0) {
+            console.log('');
+            for (const d of diffSummaries) {
+                const statusIcon = d.status === 'added' ? chalk.green('+ new')
+                    : d.status === 'deleted' ? chalk.red('- del')
+                        : chalk.yellow('~ mod');
+                const statsStr = d.binary ? chalk.gray('(binary)')
+                    : chalk.green(`+${d.stats.insertions}`) + ' ' + chalk.red(`-${d.stats.deletions}`);
+                console.log(`  ${statusIcon}  ${d.path}  ${statsStr}`);
+            }
+            console.log(chalk.gray(`\n  Total: `) + chalk.green(`+${totalInsertions}`) + ' ' + chalk.red(`-${totalDeletions}`));
+            console.log(chalk.cyan('\nUse "gent commit" to record your changes'));
         }
 
     } catch (error) {
         spinner.fail(chalk.red('Failed to add files'));
-
         if (error.code === 'ENOENT' && error.message.includes('.gent')) {
             console.error(chalk.red('\nError: Not a gent repository'));
-            console.log(chalk.yellow('ℹ Run "gent init" to initialize a repository'));
+            console.log(chalk.yellow('Run "gent init" to initialize a repository'));
         } else {
             console.error(chalk.red('\nError:'), error.message);
         }