gent-cli 5.0.0 → 5.0.3

package/README.md

@@ -1,16 +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).
-- **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
 
@@ -18,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
@@ -32,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
@@ -48,58 +101,77 @@ gent whoami
 gent logout
 ```
 
-## Usage
+## Commands
 
-### 1. Initialize a Repository
+### Repository Setup
 
-Just like Git, gent init is silent and sets up a new repository in your current directory. It automatically uses your logged-in identity for configuration.
+| 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. |
 
-```bash
-gent init
-# Output: Initialized empty Gent repository in /path/to/project
-```
+### Staging & Working Tree
 
-### 2. Check Status
+| 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. |
 
-See which files are modified or untracked.
+### History
 
-```bash
-gent status
-```
+| 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. |
 
-### 3. Stage Files
+### Branching & Merging
 
-Add files to the staging area.
+| 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. |
 
-```bash
-gent add filename.js
-# or add all files
-gent add .
-```
+### Remote & Sync
 
-### 4. Commit Changes
+| 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. |
 
-Create a commit. Gent automatically fetches your name and email from your global login session.
+### Authentication Commands
 
-```bash
-gent commit -m "Initial commit"
-# Output: [main a1b2c3d] Initial commit
-# Author: Your Name <your.email@example.com>
-```
+| 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. |
 
-### 5. View History
+## Usage Examples
 
-See your commit history.
+### Initialize a Repository
 
 ```bash
-gent log
-# or compact view
-gent log --oneline
+gent init
+# Output: Initialized empty Gent repository in /path/to/project
 ```
 
-## Branching
+### Stage and Commit
 
-Manage branches just like you're used to.
+```bash
+gent add .
+gent commit -m "Initial commit"
+```
+
+### Work with Branches
 
 ```bash
 # Create and switch to a new branch
@@ -115,23 +187,115 @@ gent checkout main
 gent branch -d feature-login
 ```
 
+### View History
+
+```bash
+gent log
+gent log --oneline
+gent log -n 5
+```
+
+### Remote Workflow
+
+```bash
+# Add a remote
+gent remote add origin https://gent-api.onrender.com/api/repos/123/
+
+# Push to remote
+gent push origin main
+
+# Pull from remote
+gent pull origin main
+
+# Clone a repository
+gent clone https://gent-api.onrender.com/api/repos/123/ my-project
+```
+
 ## Repository Structure
 
-Gent creates a .gent directory in your project root:
+Gent creates a `.gent` directory in your project root:
 
 ```
 .gent/
-├── config.json       # Project configuration
-├── objects/          # Stored file contents
-├── refs/             # Branch pointers
-└── HEAD             # Current branch reference
+├── 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)
+```
+
+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:
+
 ```
+node_modules/
+dist/
+.env
+*.log
+```
+
+Default ignored patterns include: `.gent`, `node_modules`, `.git`, `.DS_Store`, `.env`, `dist`, `build`, `coverage`, `.vscode`, `.idea`, and `*.log`.
+
+### Remotes
+
+Remotes are stored in `.gent/config.json`:
+
+```json
+{
+  "remotes": {
+    "origin": {
+      "url": "https://gent-api.onrender.com/api/repos/123/"
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+**Command not found?**
+
+Make sure the CLI is linked globally:
+```bash
+npm link
+```
+
+Or run it directly:
+```bash
+node src/index.js <command>
+```
+
+**Not a Gent repository?**
+
+Run `gent init` in your project directory first.
+
+**No changes to commit?**
+
+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
 
-Your authentication tokens are stored globally in ~/.gent/auth.json.
+- [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": "5.0.0",
+  "version": "5.0.3",
   "description": "A modern, Git-like version control CLI with built-in cloud authentication and global user identity management.",
   "main": "src/index.js",
   "bin": {