# Development Environment Setup Guide

## Prerequisites

- Windows, macOS, or Linux
- Git
- Docker Desktop
- Visual Studio Code with Remote - Containers extension
- GitHub CLI

## Initial Setup

1. **Clone the Repository**
   ```bash
   git clone https://github.com/acedanger/finance.git
   cd finance
   ```

2. **Create Environment Files**
   ```bash
   cp .devcontainer/.env.example .devcontainer/.env
   cp .env.example .env
   ```

## GitHub Personal Access Token (PAT)

1. **Create a new PAT:**
   - Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
   - Click "Generate new token (classic)"
   - Name: `finance-dev-token`
   - Set expiration: 90 days (recommended)
   - Required scopes:
     - `repo` (Full control of private repositories)
     - `read:packages` (Download container images)
     - `write:packages` (Upload container images)
     - `delete:packages` (Optional: manage container versions)
     - `workflow` (GitHub Actions integration)

2. **Configure the PAT:**
   - Open `.devcontainer/.env`
   - Set `GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here`

## Building the Development Container

### Using VS Code (Recommended)
1. Open the project in VS Code
2. When prompted, click "Reopen in Container"
   - Or press F1 and run "Dev Containers: Rebuild and Reopen in Container"

### Using Command Line
1. Install the devcontainer CLI:
   ```bash
   npm install -g @devcontainers/cli
   ```

2. Build the container:
   ```bash
   devcontainer build .
   ```

3. Start the container:
   ```bash
   # With post-create command
   devcontainer up --workspace-folder .

   # Skip post-create command
   devcontainer up --workspace-folder . --skip-post-create
   ```

## Building and Pushing the Container Image

1. Ensure you're in the `.devcontainer` directory

2. Choose your preferred script:

   **Using PowerShell:**
   ```powershell
   .\build-and-push.ps1 your_github_username
   ```

   **Using Git Bash/Unix Shell:**
   ```bash
   chmod +x build-and-push.sh
   ./build-and-push.sh your_github_username
   ```

Both scripts perform the same functions:
- Validate prerequisites (Docker, GitHub CLI)
- Load GitHub PAT from `.env` file
- Build the container image
- Push to GitHub Container Registry
- Provide next steps for using the image

## Git Hooks

This project uses Git hooks via Husky to enforce code quality:

1. **Pre-commit Hook:**
   - Automatically runs Biome checks before each commit
   - Prevents committing code with linting or formatting errors
   - See [HOOKS.md](./HOOKS.md) for more details and usage instructions

## Pre-commit Hooks

The project uses Git hooks to enforce code quality standards automatically when committing changes.

### Setup

Husky is used to manage Git hooks and is automatically installed and configured when you run `npm install`. No manual setup is required.

### Available Hooks

1. **pre-commit**: Runs before each commit to ensure code quality
   - Runs Biome.js to check and auto-fix formatting and path alias usage
   - Runs TypeScript type checking
   - Auto-stages files fixed by Biome.js

### Bypassing Hooks

In rare cases, you may need to bypass the pre-commit hooks:

```bash
git commit --no-verify -m "Your commit message"
```

⚠️ Note: Only bypass hooks when absolutely necessary and ensure code quality manually.

### Troubleshooting

If the pre-commit hook fails:

1. Review the error messages in the console
2. Fix the reported issues
3. Stage your changes again
4. Retry the commit

For hook execution issues:
```bash
# Reinstall husky hooks
npm run prepare
```

## Environment Files

The project uses two separate environment files:

1. `.devcontainer/.env`:
   - Container-specific configuration
   - GitHub PAT
   - PostgreSQL settings
   - pgAdmin settings

2. `.env`:
   - Application-specific configuration
   - Development server port
   - API base URL
   - Node environment

## Troubleshooting

### Container Build Issues
- Ensure Docker Desktop is running
- Check that your PAT has the correct permissions
- Try rebuilding without cache: `devcontainer build . --no-cache`

### GitHub Authentication Issues
- Verify your PAT in `.devcontainer/.env`
- Try logging in manually: `gh auth login`
- Check GitHub CLI status: `gh auth status`

### Network Issues
- If DNS resolution fails, try using different DNS servers in `devcontainer.json`
- Check if GitHub Container Registry (ghcr.io) is accessible
- Verify Docker network settings

### VS Code Issues
- Install/update the Remote - Containers extension
- Clear VS Code's container cache
- Check VS Code's "Dev Containers" output panel for detailed logs

## Common Operations

### Rebuilding the Container
```bash
# Using VS Code
F1 -> "Dev Containers: Rebuild Container"

# Using CLI
devcontainer build . --no-cache
```

### Updating the Container Image
1. Make changes to `Dockerfile` or `devcontainer.json`
2. Run the build script:
   ```bash
   ./build-and-push.sh your_github_username
   ```
3. Update image reference in `devcontainer.json`
4. Rebuild container in VS Code

### Starting Development Server
```bash
npm run dev
```