Metadata-Version: 2.4
Name: itcpr
Version: 2.0.4
Summary: CLI tool for syncing GitHub repositories from ITCPR Cloud
Home-page: https://github.com/ITCPR/itcpr
Author: ITCPR
Author-email: ITCPR <info@itcpr.org>
License: MIT
Keywords: itcpr,github,git,sync,cli,repository
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: keyring>=23.0.0
Requires-Dist: tomli-w>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# ITCPR CLI

A production-ready CLI tool for syncing GitHub repositories from ITCPR Cloud to your local machine.

## Features

- 🔐 Device-based authentication with cloud.itcpr.org
- 📦 Automatic repository synchronization
- 🔄 Manual or continuous sync modes
- 💾 Local SQLite database for metadata tracking
- 🔒 Secure token storage using OS keyring
- 🛡️ Safe git operations with conflict detection

## Installation

### From PyPI (Recommended)

```bash
pip install itcpr
# OR
pip3 install itcpr
# OR
python3 -m pip install itcpr
```

### From Source

If you want to install from source or contribute:

```bash
git clone <repository-url>
cd cloud-cli
pip install -e .
# OR
pip3 install -e .
# OR
python3 -m pip install -e .
```

### Uninstall

To remove the CLI tool:

```bash
pip uninstall itcpr
```

**Note:** This will remove the CLI tool but will **not** delete:
- Configuration files (`~/.itcpr/config.toml`)
- Local repository database (`~/.itcpr/repos.db`)
- Stored device tokens (in OS keyring)

To completely remove all data:

```bash
# Uninstall the package
pip uninstall itcpr
# OR
pip3 uninstall itcpr
# OR
python3 -m pip uninstall itcpr

# Remove configuration and data
rm -rf ~/.itcpr

# Remove stored tokens (OS keyring)
# On macOS: Use Keychain Access app to remove "itcpr" entries
# On Linux: Use your keyring manager (e.g., seahorse, kwallet)
# On Windows: Use Credential Manager
```

### Requirements

- Python 3.10+
- Git (system installation)
- Access to cloud.itcpr.org

## Quick Start

### 1. Login

Authenticate your device with ITCPR Cloud:

```bash
itcpr login
```

This will:
- Open your browser to the device login page
- Display a device code
- Wait for approval
- Store credentials securely

### 2. Check Status

View your assigned repositories:

```bash
itcpr status
```

### 3. List Repositories

See all repositories assigned to your device:

```bash
itcpr repos
```

### 4. Clone a Repository

Clone a repository to your local machine:

```bash
itcpr clone paperport-itcpr
```

Or specify a custom path:

```bash
itcpr clone paperport-itcpr --path ~/projects/paperport
```

### 5. Sync Repositories

Sync all cloned repositories:

```bash
itcpr sync
```

Run continuous sync (watches for changes):

```bash
itcpr sync --watch
```

With custom interval:

```bash
itcpr sync --watch --interval 120  # Sync every 2 minutes
```

### 6. Logout

Clear stored credentials:

```bash
itcpr logout
```

## Commands

### `itcpr login`

Starts device authentication flow. Opens browser to `cloud.itcpr.org/device` and polls for approval.

### `itcpr logout`

Revokes device token and clears local metadata.

### `itcpr status`

Shows:
- Logged-in user information
- Device ID
- Assigned repositories
- Local repositories with sync status

### `itcpr repos`

Lists all repositories assigned to this device with their clone status.

### `itcpr clone <repo>`

Clones a repository from GitHub using short-lived installation tokens.

Options:
- `--path, -p`: Custom local path for the repository

### `itcpr sync`

One-shot synchronization of all cloned repositories.

Options:
- `--watch, -w`: Run continuous sync loop
- `--interval, -i`: Sync interval in seconds (watch mode only, default: 60)

## How It Works

### Authentication

1. Device requests authentication code from backend
2. User approves device in browser at `cloud.itcpr.org/device`
3. Device token is stored securely in OS keyring
4. Token is used for all API requests

### Repository Sync

1. Fetches latest changes from remote
2. Detects uncommitted local changes
3. Commits local changes if any
4. Pulls remote changes with rebase
5. Pushes local commits if permitted
6. Aborts on merge conflicts (requires manual resolution)

### Security

- **No Personal Access Tokens**: Only uses backend-issued short-lived GitHub installation tokens
- **Device Tokens**: Revocable device authentication
- **OS Keyring**: Credentials stored securely using system keyring
- **Safe Git Operations**: Never force-pushes, detects conflicts

## Configuration

Configuration is stored in `~/.itcpr/config.toml`.

Repository metadata is stored in `~/.itcpr/repos.db` (SQLite).

## Troubleshooting

### "Not logged in" error

Run `itcpr login` to authenticate your device.

### "Repository not assigned" error

The repository must be assigned to your device in ITCPR Cloud. Contact an administrator.

### Merge conflicts

If a merge conflict is detected during sync:
1. Resolve conflicts manually in the repository
2. Commit the resolution
3. Run `itcpr sync` again

### Git command not found

Ensure Git is installed and available in your PATH:
```bash
git --version
```

### Token storage issues

On Linux, you may need to install a keyring backend:
```bash
# For GNOME
sudo apt-get install python3-keyring

# For KDE
sudo apt-get install python3-keyring kdewallet
```

## Development

### Project Structure

```
cloud-cli/
├── itcpr/
│   ├── __init__.py      # Package initialization
│   ├── cli.py           # CLI commands
│   ├── auth.py          # Authentication
│   ├── api.py           # API client
│   ├── gitops.py        # Git operations
│   ├── sync.py          # Sync logic
│   ├── config.py        # Configuration
│   ├── storage.py       # SQLite storage
│   └── utils.py         # Utilities
├── setup.py             # Setup script
├── pyproject.toml       # Project metadata
└── README.md            # This file
```

### Running Tests

```bash
# Install in development mode
pip install -e .
# OR
pip3 install -e .
# OR
python3 -m pip install -e .

# Run CLI
itcpr --help
```

## API Endpoints

The CLI communicates with these backend endpoints:

- `POST /api/device/start` - Start device authentication
- `GET /api/device/poll` - Poll for authentication approval
- `POST /api/device/revoke` - Revoke device token
- `GET /api/agent/me` - Get device/user information
- `GET /api/agent/repos` - Get assigned repositories
- `POST /api/agent/token` - Get GitHub installation token

## License

MIT License

## Support

For issues and questions, contact ITCPR support or open an issue on GitHub.

