# Development Scripts

This directory contains scripts to help with development environment setup and Augment thread initialization.

## Scripts

### `ensure-native-shell.js`
**Purpose**: Prevent accidental WSL usage in local Windows development
**Usage**: `pnpm env:guard` or `pnpm env:guard:bash`

- Fails when the current process is running inside WSL.
- Fails when the repo path is under a WSL drive mount such as `/mnt/c/...`.
- On Windows, warns when bare `bash` resolves to `C:\Windows\System32\bash.exe`.
- With `pnpm env:guard:bash`, fails when native Git Bash is required but bare `bash` resolves to WSL.
- Reports the native Git for Windows Bash path when it can find one.
- Runs before install, dev, lint, typecheck, test, rclone bootstrap/check, and Augment startup scripts.

### `dev-startup.js`
**Purpose**: Automatically check and start development services
**Usage**: `pnpm dev:check` or `pnpm dev:full`

- Checks if Next.js app is running on port 3000.
- Checks if rclone service is running on port 3001.
- On Windows, verifies that `fly-rclone/rclone.exe` exists and matches the pinned Dockerfile version before trying to start the rclone service.
- Automatically starts any missing services.
- Runs services in detached mode (background).

### `start-local-dev.ps1`
**Purpose**: Open the local development stack in four PowerShell terminals
**Usage**: `.\scripts\start-local-dev.ps1` or `pnpm dev:terminals`

- Starts `pnpm dev` in the repo root for the Next.js app.
- Starts `pnpm dev` in `fly-rclone` for the local rclone service.
- Starts `.\scripts\local-cron.ps1` in the repo root.
- Starts `stripe listen --forward-to http://localhost:3000/api/webhooks/stripe`.
- Supports PowerShell `-WhatIf` for previewing the terminals without opening them.

### `augment-init.js`
**Purpose**: Initialize development environment for Augment threads
**Usage**: `pnpm augment:init`

- Checks service availability.
- On Windows, checks the pinned local `rclone.exe` prerequisite before suggesting the rclone service startup command.
- Provides launch-process commands for Augment.
- Designed for use at the beginning of Augment threads.
- Does not start services automatically (provides commands instead).

### `ensure-local-rclone.mjs`
**Purpose**: Bootstrap and verify the pinned local Windows `rclone.exe`
**Usage**: `pnpm rclone:bootstrap` or `pnpm rclone:check`

- Reads the pinned `RCLONE_VERSION` from `fly-rclone/Dockerfile`.
- Downloads the matching upstream Windows archive and installs `fly-rclone/rclone.exe`.
- Verifies that `fly-rclone/src/utils/rclonePath.js` resolves to the pinned repo-local binary.
- Warns when `RCLONE_PATH` or `FLY_RCLONE_PATH` bypass the deterministic local path.

## Package.json Scripts

```json
{
  "scripts": {
    "env:guard": "node scripts/ensure-native-shell.js --verbose",
    "env:guard:bash": "node scripts/ensure-native-shell.js --require-native-bash",
    "dev:check": "node scripts/ensure-native-shell.js && node scripts/dev-startup.js",
    "dev:full": "node scripts/ensure-native-shell.js && node scripts/dev-startup.js && pnpm dev",
    "dev:terminals": "node scripts/ensure-native-shell.js && powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/start-local-dev.ps1",
    "rclone:bootstrap": "node scripts/ensure-native-shell.js && node scripts/ensure-local-rclone.mjs --bootstrap",
    "rclone:check": "node scripts/ensure-native-shell.js && node scripts/ensure-local-rclone.mjs --check",
    "augment:init": "node scripts/ensure-native-shell.js && node scripts/augment-init.js"
  }
}
```

## Usage in Augment Threads

At the beginning of each new Augment thread, run:

```powershell
pnpm env:guard
```

If the guard reports `C:\Windows\System32\bash.exe`, do not use bare `bash` for shell workflows; launch native Git Bash with the explicit Git for Windows path it reports.

Then run:

```bash
pnpm augment:init
```

This will check service status and provide launch-process commands if services need to be started.

## Service Ports

- **Next.js App**: http://localhost:3000.
- **rclone Service**: http://localhost:3001 (health: http://localhost:3001/health).

## Local rclone Workflow

Run this once after `pnpm install` on Windows:

```bash
pnpm rclone:bootstrap
pnpm rclone:check
```

That installs a pinned `fly-rclone/rclone.exe` which keeps local development aligned with the Fly image instead of relying on a global `rclone.exe` from `PATH`.

## Example Augment Workflow

1. Start new Augment thread
2. Run `pnpm augment:init` to check services
3. Use provided launch-process commands if needed
4. Monitor services using `list-processes` and `read-process`
5. Proceed with development tasks

## Benefits

- ✅ Consistent service startup across threads.
- ✅ Health checking before proceeding.
- ✅ Augment can monitor launched processes.
- ✅ Clear status reporting.
- ✅ Non-blocking service startup.

---

## Backup & Cron Job Scripts

### Investigation & Troubleshooting

#### `investigate-failed-backup.mjs`
**Purpose**: Comprehensive investigation of failed backup jobs
**Usage**: `node scripts/investigate-failed-backup.mjs`

- Queries database for failed backup jobs.
- Shows detailed error messages and stack traces.
- Displays job configuration and execution history.
- Provides recommendations for fixing issues.

#### `check-backup-jobs.mjs`
**Purpose**: Quick status check of all backup jobs
**Usage**: `node scripts/check-backup-jobs.mjs`

- Lists all backup jobs with their current status.
- Shows next scheduled run times.
- Identifies overdue or stuck jobs.

#### `get-job-details.mjs`
**Purpose**: Get detailed information about a specific backup job
**Usage**: `node scripts/get-job-details.mjs <job-id>`

- Shows complete job configuration.
- Displays execution history.
- Shows source and destination details.

### Verification & Testing

#### `test-execute-endpoint.ps1`
**Purpose**: Test the backup job execution endpoint locally with confirmation
**Usage**: `.\scripts\test-execute-endpoint.ps1 -JobId <job-id>`

- Tests `/api/jobs/[id]/execute` endpoint.
- Refuses non-local hosts.
- Reads `CRON_SECRET` from the environment or an explicit parameter and never
  embeds or prints it.

#### `test-cron-endpoint.ps1`
**Purpose**: Test the cron trigger endpoint
**Usage**: `.\scripts\test-cron-endpoint.ps1`

- Tests `/api/cron/execute-backups` endpoint.
- Verifies CRON_SECRET authentication.
- Checks for proper job scheduling.

### Job Management

#### `reset-job-status.mjs`
**Purpose**: Reset a failed job back to scheduled status
**Usage**: `node scripts/reset-job-status.mjs <job-id>`

- Resets job status from 'failed' to 'scheduled'.
- Clears error messages.
- Useful for retrying failed jobs.

#### `update-job-next-run.mjs`
**Purpose**: Update the next run time for a backup job
**Usage**: `node scripts/update-job-next-run.mjs <job-id> <new-time>`

- Updates nextRunAt timestamp.
- Useful for rescheduling jobs.
- Validates time format.

#### `update-job-next-run-future.mjs`
**Purpose**: Schedule a job to run in the near future (for testing)
**Usage**: `node scripts/update-job-next-run-future.mjs <job-id>`

- Sets nextRunAt to 2 minutes in the future.
- Useful for testing cron job execution.
- Automatically calculates UTC time.

### E2E Testing

#### `e2e-test-scheduled-backup.mjs`
**Purpose**: End-to-end test of scheduled backup functionality
**Usage**: `node scripts/e2e-test-scheduled-backup.mjs`

- Creates a test backup job.
- Schedules it for immediate execution.
- Monitors execution and verifies results.
- Cleans up test data.

## Related Documentation

- [Cron Job Deployment Guide](CRON_JOB_DEPLOYMENT.md).
- [Backup Feature Documentation](BACKUP_FEATURE.md).
- [Backup Troubleshooting](consolidation-history/BACKUP_FIXES_CONSOLIDATION_2025-10-25.md).
- [Vercel Deployment Protection Fix](consolidation-history/VERCEL_DEPLOYMENT_PROTECTION_FIX_2025-10-25.md).