gent-cli 1.0.0

package/README.md

@@ -0,0 +1,316 @@
+# Gent CLI - A Git-like Version Control System
+
+🚀 **Gent** is a lightweight, Git-inspired version control CLI tool built with Node.js. It provides essential version control features with an intuitive command-line interface.
+
+## Features
+
+- **Repository Initialization** - Set up new Gent repositories with custom configuration
+- **File Staging** - Add files to staging area before committing
+- **Commit Management** - Record changes with descriptive messages
+- **Branch Operations** - Create, switch, and manage branches
+- **Status Tracking** - View working tree status and changes
+- **Commit History** - Browse commit logs with detailed information
+
+## Installation
+
+```bash
+# Navigate to the CLI directory
+cd apps/Cli
+
+# Install dependencies
+npm install
+
+# Link globally (optional)
+npm link
+```
+
+## Usage
+
+### Initialize a Repository
+
+Create a new Gent repository in the current directory:
+
+```bash
+gent init
+```
+
+With default configuration (skip prompts):
+
+```bash
+gent init -y
+```
+
+### Check Status
+
+View the current state of your working tree:
+
+```bash
+gent status
+```
+
+Short format:
+
+```bash
+gent status -s
+```
+
+### Stage Files
+
+Add files to the staging area:
+
+```bash
+# Add specific files
+gent add file1.js file2.js
+
+# Add all files
+gent add --all
+gent add .
+```
+
+### Commit Changes
+
+Record changes to the repository:
+
+```bash
+# With inline message
+gent commit -m "Your commit message"
+
+# Interactive (will prompt for message)
+gent commit
+```
+
+Auto-stage all modified files:
+
+```bash
+gent commit -a -m "Commit all changes"
+```
+
+### View Commit History
+
+Display commit logs:
+
+```bash
+# Show last 10 commits (default)
+gent log
+
+# Show specific number of commits
+gent log -n 5
+
+# Compact oneline format
+gent log --oneline
+```
+
+### Branch Management
+
+List all branches:
+
+```bash
+gent branch
+```
+
+Create a new branch:
+
+```bash
+gent branch feature-name
+```
+
+Delete a branch:
+
+```bash
+gent branch -d branch-name
+```
+
+### Switch Branches
+
+Switch to an existing branch:
+
+```bash
+gent checkout branch-name
+```
+
+Create and switch to a new branch:
+
+```bash
+gent checkout -b new-branch
+```
+
+## Project Structure
+
+```
+apps/Cli/
+├── src/
+│   ├── index.js              # Main entry point
+│   ├── commands/             # Command implementations
+│   │   ├── init.js          # Initialize repository
+│   │   ├── status.js        # Show status
+│   │   ├── add.js           # Stage files
+│   │   ├── commit.js        # Create commits
+│   │   ├── log.js           # View history
+│   │   ├── branch.js        # Manage branches
+│   │   └── checkout.js      # Switch branches
+│   └── utils/               # Utility modules
+│       ├── constants.js     # Application constants
+│       ├── fileSystem.js    # File operations
+│       └── helpers.js       # Helper functions
+├── package.json             # Dependencies and scripts
+└── README.md               # Documentation
+```
+
+## Repository Structure
+
+When you initialize a Gent repository, it creates a `.gent` directory:
+
+```
+.gent/
+├── config.json              # Repository configuration
+├── staging.json             # Staged files
+├── commits.json            # Commit history
+├── HEAD                    # Current branch reference
+├── objects/                # File objects (future use)
+└── refs/                   # Branch references
+    ├── heads/             # Branch pointers
+    └── tags/              # Tag references
+```
+
+## Configuration
+
+Gent stores configuration in `.gent/config.json`:
+
+```json
+{
+  "user": {
+    "name": "Your Name",
+    "email": "your.email@example.com"
+  },
+  "repository": {
+    "name": "project-name",
+    "description": "Project description",
+    "created": "2025-11-06T00:00:00.000Z"
+  }
+}
+```
+
+## Ignore Patterns
+
+Create a `.gentignore` file to exclude files from tracking:
+
+```
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+build/
+
+# Environment files
+.env
+.env.local
+
+# Logs
+*.log
+
+# OS files
+.DS_Store
+```
+
+## Command Reference
+
+| Command | Description | Options |
+|---------|-------------|---------|
+| `gent init` | Initialize repository | `-y, --yes` Skip prompts |
+| `gent status` | Show working tree status | `-s, --short` Short format |
+| `gent add <files>` | Stage files | `-A, --all` Stage all files |
+| `gent commit` | Record changes | `-m <msg>` Message, `-a` Stage all |
+| `gent log` | Show commit history | `-n <num>` Limit, `--oneline` Compact |
+| `gent branch [name]` | Manage branches | `-d <name>` Delete, `-a` List all |
+| `gent checkout <branch>` | Switch branches | `-b` Create new |
+| `gent help [command]` | Show help | |
+
+## Dependencies
+
+- **commander** - CLI framework
+- **chalk** - Terminal styling
+- **inquirer** - Interactive prompts
+- **ora** - Elegant terminal spinners
+- **boxen** - Create boxes in terminal
+- **date-fns** - Date formatting utilities
+
+## Development
+
+```bash
+# Run locally
+npm start
+
+# Run specific command
+node src/index.js init
+node src/index.js status
+```
+
+## Examples
+
+### Complete Workflow
+
+```bash
+# Initialize repository
+gent init
+
+# Add some files
+echo "console.log('Hello');" > app.js
+gent add app.js
+
+# Commit changes
+gent commit -m "Initial commit"
+
+# Create a feature branch
+gent branch feature-login
+gent checkout feature-login
+
+# Make changes and commit
+echo "// Login logic" >> app.js
+gent add app.js
+gent commit -m "Add login feature"
+
+# View history
+gent log
+
+# Switch back to main
+gent checkout main
+```
+
+## Error Handling
+
+Gent provides clear error messages:
+
+- **Not a gent repository** - Run `gent init` first
+- **No changes to commit** - Stage files with `gent add`
+- **Branch not found** - Check available branches with `gent branch`
+
+## Best Practices
+
+1. **Commit Often** - Make small, focused commits
+2. **Write Clear Messages** - Describe what and why
+3. **Use Branches** - Isolate features and experiments
+4. **Check Status** - Review changes before committing
+5. **Update .gentignore** - Exclude unnecessary files
+
+## Future Enhancements
+
+- [ ] Diff visualization
+- [ ] Remote repository support
+- [ ] Merge functionality
+- [ ] Tag management
+- [ ] Stash implementation
+- [ ] File restoration
+- [ ] Conflict resolution
+
+## License
+
+ISC
+
+## Author
+
+Built with ❤️ using Node.js
+
+---
+
+**Note**: Gent is a learning project and educational tool. For production use, consider established version control systems like Git.

package/commands-reference.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+/**
+ * Gent CLI - Command Summary
+ * Quick reference for all available commands
+ */
+
+const chalk = require('chalk');
+const boxen = require('boxen');
+
+const commands = [
+    {
+        name: 'init',
+        description: 'Initialize a new gent repository',
+        usage: 'gent init [options]',
+        options: ['-y, --yes  Skip prompts and use defaults'],
+        examples: ['gent init', 'gent init -y']
+    },
+    {
+        name: 'status',
+        description: 'Show the working tree status',
+        usage: 'gent status [options]',
+        options: ['-s, --short  Give output in short format'],
+        examples: ['gent status', 'gent status -s']
+    },
+    {
+        name: 'add',
+        description: 'Add file contents to the staging area',
+        usage: 'gent add <files...> [options]',
+        options: ['-A, --all  Add all files'],
+        examples: ['gent add file.js', 'gent add .', 'gent add --all']
+    },
+    {
+        name: 'commit',
+        description: 'Record changes to the repository',
+        usage: 'gent commit [options]',
+        options: [
+            '-m, --message <message>  Commit message',
+            '-a, --all               Auto stage modified files'
+        ],
+        examples: ['gent commit -m "Fix bug"', 'gent commit', 'gent commit -a -m "Update all"']
+    },
+    {
+        name: 'log',
+        description: 'Show commit logs',
+        usage: 'gent log [options]',
+        options: [
+            '-n, --number <count>  Limit commits (default: 10)',
+            '--oneline             Show each commit on one line'
+        ],
+        examples: ['gent log', 'gent log -n 5', 'gent log --oneline']
+    },
+    {
+        name: 'branch',
+        description: 'List, create, or delete branches',
+        usage: 'gent branch [name] [options]',
+        options: [
+            '-d, --delete <name>  Delete a branch',
+            '-a, --all            List all branches'
+        ],
+        examples: ['gent branch', 'gent branch feature-x', 'gent branch -d old-feature']
+    },
+    {
+        name: 'checkout',
+        description: 'Switch branches',
+        usage: 'gent checkout <branch> [options]',
+        options: ['-b, --create  Create a new branch'],
+        examples: ['gent checkout main', 'gent checkout -b new-feature']
+    }
+];
+
+console.log(chalk.bold.cyan('\n🚀 Gent CLI - Command Reference\n'));
+
+commands.forEach((cmd, index) => {
+    console.log(chalk.yellow.bold(`${index + 1}. ${cmd.name.toUpperCase()}`));
+    console.log(chalk.white(`   ${cmd.description}`));
+    console.log(chalk.gray(`   Usage: ${cmd.usage}`));
+
+    if (cmd.options.length > 0) {
+        console.log(chalk.gray('   Options:'));
+        cmd.options.forEach(opt => {
+            console.log(chalk.gray(`     ${opt}`));
+        });
+    }
+
+    console.log(chalk.cyan('   Examples:'));
+    cmd.examples.forEach(ex => {
+        console.log(chalk.green(`     $ ${ex}`));
+    });
+
+    console.log();
+});
+
+const tips = `
+${chalk.bold('💡 Quick Tips:')}
+
+${chalk.cyan('•')} Always run ${chalk.yellow('gent init')} first in a new project
+${chalk.cyan('•')} Use ${chalk.yellow('gent status')} to see what changed
+${chalk.cyan('•')} Stage files with ${chalk.yellow('gent add')} before committing
+${chalk.cyan('•')} Create branches for new features
+${chalk.cyan('•')} Check ${chalk.yellow('gent log')} to view history
+
+${chalk.bold('📚 Documentation:')}
+${chalk.gray('• README.md     - Complete documentation')}
+${chalk.gray('• QUICKSTART.md - Quick start guide')}
+${chalk.gray('• demo.sh       - Interactive demo')}
+`;
+
+console.log(boxen(tips, {
+    padding: 1,
+    margin: 1,
+    borderStyle: 'round',
+    borderColor: 'cyan'
+}));
+
+console.log(chalk.gray('Run'), chalk.yellow('gent --help'), chalk.gray('for more information\n'));

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "gent-cli",
+  "version": "1.0.0",
+  "description": "A Git-like version control CLI tool",
+  "main": "src/index.js",
+  "bin": {
+    "gent": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "demo": "bash demo.sh",
+    "link": "npm link",
+    "unlink": "npm unlink"
+  },
+  "keywords": [
+    "cli",
+    "version-control",
+    "git-like",
+    "gent"
+  ],
+  "author": "Abdalrahman Kanawati <kanawatiabdalrahman@gmail.com>",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SaadShaya7/gent.git"
+  },
+  "homepage": "https://github.com/SaadShaya7/gent#readme",
+  "bugs": {
+    "url": "https://github.com/SaadShaya7/gent/issues"
+  },
+  "dependencies": {
+    "commander": "^11.1.0",
+    "chalk": "^4.1.2",
+    "inquirer": "^8.2.5",
+    "ora": "^5.4.1",
+    "boxen": "^5.1.2",
+    "date-fns": "^2.30.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,88 @@
+/**
+ * Add Command - Add file contents to the staging area
+ * Stages files for the next commit
+ */
+
+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');
+
+/**
+ * Add files to staging area
+ * @param {Array} files - Files to add
+ * @param {Object} options - Command options
+ */
+async function add(files, options) {
+    const spinner = ora('Adding files to staging area...').start();
+
+    try {
+        const gentPath = await getGentPath();
+        const cwd = process.cwd();
+        const stagingPath = path.join(gentPath, STAGING_FILE);
+
+        // Read current staging area
+        const staging = await readJSON(stagingPath);
+        const stagedFiles = new Set(staging.files || []);
+
+        let filesToAdd = [];
+
+        // Handle --all option
+        if (options.all || files.includes('.') || files.includes('*')) {
+            spinner.text = 'Scanning for all files...';
+            const ignorePatterns = await getIgnorePatterns(cwd);
+            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);
+            }
+        }
+
+        // Add files to staging
+        let addedCount = 0;
+        for (const file of filesToAdd) {
+            if (!stagedFiles.has(file)) {
+                stagedFiles.add(file);
+                addedCount++;
+            }
+        }
+
+        // Save staging area
+        staging.files = Array.from(stagedFiles);
+        await writeJSON(stagingPath, staging);
+
+        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'));
+        }
+
+    } 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'));
+        } else {
+            console.error(chalk.red('\nError:'), error.message);
+        }
+        process.exit(1);
+    }
+}
+
+module.exports = add;

package/src/commands/branch.js

@@ -0,0 +1,115 @@
+/**
+ * Branch Command - List, create, or delete branches
+ * Manages repository branches
+ */
+
+const path = require('path');
+const chalk = require('chalk');
+const { getGentPath, readJSON, writeJSON } = require('../utils/fileSystem');
+const { COMMITS_FILE } = require('../utils/constants');
+
+/**
+ * Manage branches
+ * @param {String} name - Branch name (optional)
+ * @param {Object} options - Command options
+ */
+async function branch(name, options) {
+    try {
+        const gentPath = await getGentPath();
+        const repository = await readJSON(path.join(gentPath, COMMITS_FILE));
+
+        // Delete branch
+        if (options.delete) {
+            await deleteBranch(options.delete, repository, gentPath);
+            return;
+        }
+
+        // Create new branch
+        if (name) {
+            await createBranch(name, repository, gentPath);
+            return;
+        }
+
+        // List branches
+        listBranches(repository, options.all);
+
+    } catch (error) {
+        if (error.code === 'ENOENT' && error.message.includes('.gent')) {
+            console.error(chalk.red('Error: Not a gent repository'));
+            console.log(chalk.yellow('\nℹ Run "gent init" to initialize a repository'));
+        } else {
+            console.error(chalk.red('Error:'), error.message);
+        }
+        process.exit(1);
+    }
+}
+
+/**
+ * List all branches
+ */
+function listBranches(repository, showAll) {
+    const branches = repository.branches || {};
+    const currentBranch = repository.currentBranch || 'main';
+
+    console.log(chalk.bold.cyan('\nBranches:\n'));
+
+    for (const [branch, commitHash] of Object.entries(branches)) {
+        const isCurrent = branch === currentBranch;
+        const prefix = isCurrent ? chalk.green('* ') : '  ';
+        const branchName = isCurrent ? chalk.green.bold(branch) : chalk.white(branch);
+        const commitInfo = commitHash ? chalk.gray(` (${commitHash.substring(0, 7)})`) : chalk.gray(' (no commits)');
+
+        console.log(`${prefix}${branchName}${commitInfo}`);
+    }
+
+    console.log();
+}
+
+/**
+ * Create a new branch
+ */
+async function createBranch(name, repository, gentPath) {
+    const branches = repository.branches || {};
+
+    if (branches.hasOwnProperty(name)) {
+        console.error(chalk.red(`Error: Branch '${name}' already exists`));
+        process.exit(1);
+    }
+
+    // Create branch from current HEAD
+    const currentCommit = branches[repository.currentBranch] || null;
+    branches[name] = currentCommit;
+    repository.branches = branches;
+
+    await writeJSON(path.join(gentPath, COMMITS_FILE), repository);
+
+    console.log(chalk.green(`✓ Created branch '${name}'`));
+    console.log(chalk.gray(`Based on: ${repository.currentBranch}`));
+}
+
+/**
+ * Delete a branch
+ */
+async function deleteBranch(name, repository, gentPath) {
+    const branches = repository.branches || {};
+
+    if (!branches.hasOwnProperty(name)) {
+        console.error(chalk.red(`Error: Branch '${name}' not found`));
+        process.exit(1);
+    }
+
+    if (name === repository.currentBranch) {
+        console.error(chalk.red(`Error: Cannot delete current branch '${name}'`));
+        console.log(chalk.yellow('Switch to another branch first using "gent checkout <branch>"'));
+        process.exit(1);
+    }
+
+    delete branches[name];
+    repository.branches = branches;
+
+    await writeJSON(path.join(gentPath, COMMITS_FILE), repository);
+
+    console.log(chalk.green(`✓ Deleted branch '${name}'`));
+}
+
+module.exports = branch;