# PyMosaygent

A locally running Python API server that powers [Mosayic](https://mosayic.app) — a development companion for managing full-stack React Native and Python projects with integrated support for Firebase, Google Cloud, GitHub, Expo, and Supabase.

## Features

- **Environment Management** — Configure project directories, detect Python and React Native codebases, track git status
- **Expo Dev Server Control** — Start, stop, and monitor Metro bundler with live reload support
- **Firebase Integration** — Manage projects, configure Android/iOS/Web apps, deploy functions, handle secrets
- **GitHub Operations** — Clone templates, initialize repositories, manage Actions secrets
- **Supabase Local Dev** — Control local Supabase instance, run migrations, manage database
- **Google Cloud Run** — Deploy containerized services

## Requirements

- Python 3.10 - 3.12
- External CLI tools (depending on features used):
  - `firebase-cli` and `gcloud` for Firebase/GCP operations
  - `gh` for GitHub operations
  - `node`, `npm`, `expo`, and `eas` for Expo/React Native
  - `supabase` and `docker` for Supabase local development
  - `git` for version control

## Installation

```bash
uv add mosaygent
```

For development:

```bash
git clone https://github.com/yourusername/pymosaygent
cd pymosaygent
uv sync
```

## Project Structure

```
pymosaygent/
├── mosaygent/
│   ├── __init__.py           # App entry, service initialization
│   ├── command_runner.py     # Async subprocess execution
│   ├── logger.py             # Colored logging setup
│   ├── middleware.py         # Exception handling
│   ├── routes/               # API endpoints
│   │   ├── environment.py    # Project & codebase management
│   │   ├── expo.py           # Expo dev server control
│   │   ├── firebase.py       # Firebase CLI operations
│   │   ├── github.py         # GitHub & repo operations
│   │   └── supabase.py       # Supabase local dev
│   └── services/             # Business logic
│       ├── environment.py    # Project detection, git ops
│       ├── expo.py           # Expo process management
│       ├── github.py         # GitHub CLI wrapper
│       ├── cloudrun.py       # Cloud Run deployment
│       └── firebase/         # Firebase service modules
├── tests/                    # Test suite
├── pyproject.toml            # Project metadata
└── CLAUDE.md                 # Code standards
```

## API Endpoints

### Environment

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/environment/set-directory` | Set project root directory |
| GET | `/environment/status` | Check API & mobile codebase status |
| POST | `/environment/clone-api` | Initialize Python API from template |

### Expo

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/expo/start` | Start Metro bundler |
| POST | `/expo/stop` | Stop development server |
| GET | `/expo/status` | Get server status |
| POST | `/expo/reload` | Trigger live reload |
| GET | `/expo/logs` | Fetch captured output |
| GET | `/expo/connection` | Get Metro URL and port |

### Firebase

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/firebase/cli-installed` | Check Firebase & gcloud CLI |
| GET | `/firebase/auth-status` | Authentication state |
| GET | `/firebase/projects` | List accessible projects |
| POST | `/firebase/create-android-app` | Create Android app, get google-services.json |
| POST | `/firebase/fetch-firebase-configs` | Download platform configs |
| POST | `/firebase/deploy` | Deploy Firebase project |
| POST | `/firebase/deploy-cloud-run` | Deploy Cloud Run service |
| POST | `/firebase/set-secrets` | Create env files & upload secrets |

### GitHub

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/github/auth` | Check gh CLI auth status |
| GET | `/github/accounts` | List user & organizations |
| POST | `/github/init-repo` | Clone template, create GitHub repo |
| POST | `/github/set-secret` | Set GitHub Actions secret |

### Supabase

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/supabase/check-installation` | Verify Docker & Supabase CLI |
| GET | `/supabase/migrations` | List migrations |
| POST | `/supabase/migrations` | Create migration via db diff |
| POST | `/supabase/start` | Start local Supabase |
| POST | `/supabase/stop` | Stop Supabase |
| GET | `/supabase/status` | Get running services info |
| POST | `/supabase/reset-database` | Reset local database |

### Health

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Liveness check |

## Configuration

Project directory is persisted in `~/.mosayic/config.txt` and auto-loaded on startup.

**Codebase detection:**
- Python API: Looks for `pyproject.toml` in subdirectories
- React Native: Looks for `app.json` with Expo configuration

## Testing

```bash
pytest
pytest --cov  # with coverage
```

## License

MIT
