@liquisio/git-cli/README.md

Intelligent GitHub connection tool for Wix Blocks - [re]connect local code to remote with smart conflict detection

# LQ CLI (`@liquisio/git-cli`)

**Intelligent GitHub connection tool for Wix Blocks** - Reconnect your local code to GitHub remote with smart conflict detection.

Perfect for reconnecting Wix Blocks projects after container resets or when git connection is lost.

**Commands:** `lq` or `lq-cli`

## Features

- **Smart File Analysis** - Compares local and remote files to suggest the right action
- **Simple Menu** - 6 clear options with detailed explanations
- **Automatic Backups** - Timestamped backups before any operation
- **Watch Mode** - Auto-pull changes from remote every 60 seconds
- **Restore from Backup** - Easy recovery if something goes wrong
- **Force Mode** - Skip warnings and confirmations with `-f` flag
- **GitHub Token Authentication** - Secure remote configuration
- **Web Terminal Compatible** - Number-based menus work everywhere

## Installation

### Option 1: Use with npx (Recommended)

No installation needed! Just run:

```bash
npx @liquisio/git-cli
```

### Option 2: Install Globally

```bash
npm install -g @liquisio/git-cli
lq
```

### Option 3: Install Locally

```bash
npm install @liquisio/git-cli
npx lq
```

### Option 4: Read-Only File Systems (Wix Blocks, Containers)

If you're working in a read-only environment where the npm cache directory is not writable:

```bash
# Install once with temporary cache
npm install @liquisio/git-cli --cache=/tmp/.npm

# Then run normally
npx lq
```

### Option 5: Install from Tarball (Offline/Restricted Environments)

If you can't access npm registry directly:

1. **Download the tarball** from another machine:
   ```bash
   npm pack @liquisio/git-cli
   ```

2. **Upload the tarball** to your target environment

3. **Install from the tarball:**
   ```bash
   npm install ./liquisio-git-cli-x.x.x.tgz --cache=/tmp/.npm
   ```

4. **Run the CLI:**
   ```bash
   npx lq
   ```

### Option 6: Install from npm Registry (via install script)

If using the install helper script in Wix Blocks:

```bash
./run npm    # Install from npm registry
./run cli    # Run the CLI
```

## Configuration

Create a `git-config.json` file in one of these locations:
- `./git-config.json` (project root)
- `./src/backend/git-config.json` (Wix Blocks backend directory)

```json
{
  "git": {
    "name": "Your Name",
    "email": "your.email@example.com"
  },
  "github": {
    "user": "your-github-username",
    "repo": "your-repo-name",
    "token": ""
  }
}
```

**Note:** The `src` field is optional - it's auto-detected from `./src` or `/user-code/src`.

### GitHub Personal Access Token

A GitHub token is required to connect to your repository securely.

**How to generate a token:**
1. Visit: [https://github.com/settings/personal-access-tokens](https://github.com/settings/personal-access-tokens)
2. Click "Generate new token"
3. Give it a name (e.g., "LQ CLI" or "Wix Blocks")
4. Repository access: Select **only** the repository you need
5. Permissions: **Repository permissions → Contents: Read and write**
6. Generate and copy the token
7. Add it to your `git-config.json` file

**Security:**
- Token is automatically ignored by git (`**/git-config.json` in `.gitignore`)
- Never commit your config file to version control
- Give token access to specific repos only

## Usage

### Interactive Menu

Run without arguments to see the interactive menu:

```bash
lq
```

This shows:
1. File comparison (local vs GitHub)
2. Smart analysis suggesting which version is newer
3. Menu with 5 options

### Direct Commands

Skip the menu with direct commands:

```bash
lq push      # Push local code to GitHub (preserves history)
lq pull      # Pull GitHub code to local
lq watch     # Pull + auto-sync on changes
lq restore   # Restore files from latest backup
```

### Command Line Options

```bash
lq --help       # Show help message
lq --version    # Show version number
lq --logs       # Show debug output
lq -f, --force  # Skip warnings and confirmations
```

### Force Mode

Use `-f` or `--force` to skip all warnings and confirmation prompts:

```bash
lq push -f      # Force push (no warnings, default commit message)
lq pull -f      # Force pull (no warnings)
```

This is useful for scripting or when you're confident about the action.

## Menu Options

```
? What would you like to do?

  1) Push to GitHub      - Backup → Fetch history → Add local files → Push
  2) Pull from GitHub    - Backup → Reset to remote → Keep local-only files
  3) Watch mode          - Pull now, then auto-pull every 60s
  4) View file details   - List all compared files
  5) Restore backup      - Copy files from latest backup
  6) Exit
```

### Push to GitHub

- Creates backup of local files
- Fetches remote history (preserves commit history)
- Copies your local files on top
- Commits and pushes to GitHub

### Pull from GitHub

- Creates backup of local files
- Resets to remote HEAD
- Preserves local-only files (files not on GitHub)

### Watch Mode

- Pulls latest from GitHub
- Watches for remote changes every 60 seconds
- Auto-pulls when changes detected

**Watch Mode Controls:**
- **p** - Pull from remote immediately
- **ESC** - Quit watch mode

### View File Details

Shows detailed breakdown of all compared files:
- Identical files
- Conflicting files (different content)
- New in local (only exists locally)
- New on GitHub (only exists on remote)

### Restore Backup

- Restores files from the latest backup
- Preserves `site/` folder (Wix auto-generated)

## Smart Analysis

LQ CLI analyzes your files and suggests the right action:

```
📊 File Comparison:

   ✓ 10 file(s) identical
   ✗ 2 file(s) conflicting
   + 3 file(s) new in local
   - 1 file(s) new on GitHub

💡 Analysis: Local appears to have newer changes
   (2 conflicting, 3 new local files)
```

### Risk Warnings

If you choose an action that might lose data, you'll see a warning:

```
⚠️  Warning: Local appears to have newer changes!
   Pulling will OVERWRITE your local modifications.

Continue anyway? (y/N)
```

## Safety Features

- **Automatic Backups:** Creates timestamped backup before any operation
- **Token Security:** Stored in gitignored config file
- **Clear Warnings:** Explains risks before potentially destructive operations
- **Confirmation Prompts:** Requires explicit confirmation for risky actions
- **Backup Restore:** Easy recovery with `lq restore`
- **Site Folder Preserved:** Wix auto-generated `site/` folder is never touched

## File Structure

```
@liquisio/git-cli/
├── dist/
│   └── index.js              # Bundled CLI (published to npm)
├── src/
│   ├── index.js              # Main CLI orchestration
│   └── utils/
│       ├── backup.js         # Timestamped backup creation
│       ├── config.js         # JSON configuration loader
│       ├── git-ops.js        # Core git operations
│       ├── prompt-helper.js  # Number-based prompts (web terminal compatible)
│       ├── repo-state.js     # Repository state analysis & file comparison
│       ├── watch-mode.js     # Watch mode with auto-pull
│       └── welcome.js        # First-time setup flow
├── scripts/
│   └── install.sh            # Install helper for Wix Blocks
├── git-config.example.json   # Example configuration
├── package.json
└── README.md
```

## Development

### Local Development

```bash
# Install dependencies
npm install

# Run from source
npm run dev

# Run with arguments
npm run dev -- push
npm run dev -- --logs
```

### Build & Test

```bash
# Build bundle
npm run build

# Test bundle
node dist/index.js

# Create tarball
npm pack
```

### Testing in Wix Blocks

1. Build and pack:
   ```bash
   npm run build && npm pack
   ```

2. Copy tarball to Wix Blocks project

3. Install:
   ```bash
   npm install ./liquisio-git-cli-x.x.x.tgz --cache=/tmp/.npm
   ```

4. Run:
   ```bash
   npx lq
   ```

## Publishing

```bash
# Version bump
npm version patch  # 1.0.0 → 1.0.1

# Publish (runs build automatically)
npm publish
```

## Requirements

- Node.js >= 18
- Git installed on system

## License

MIT

## Contributing

Contributions welcome! Please open an issue or submit a pull request.

## Author

Varun Dev <hello@liquis.io>