# Local CI

This repo uses **local CI** via `./ci/run.sh` (which wraps `./scripts/verify.sh`).

> **Contract / Policy-as-code:** `./ci/run.sh` is the *only* supported CI entrypoint for this repo. Any release gate, merge gate, or automation must invoke `./ci/run.sh` (not `npm run build` directly). `./scripts/verify.sh` encodes enforced invariants (packaging + core purity + exports).  
> See also: `docs/progress/00-STATUS.md` for invariants and baseline tags.

## Quick Start

```bash
./ci/run.sh
```

## What It Checks

The CI runs `./scripts/verify.sh`, which performs:

1. **Environment Diagnostics** - Node.js, npm, Java, Swift, xcodebuild availability
2. **Dependencies** - npm install if needed
3. **Native Code Location** - Ensures no native code in `src/` directories
4. **TypeScript** - Lint, typecheck, unit tests
5. **Build** - `npm run build` must succeed
6. **Package** - `npm pack --dry-run` with forbidden files check
7. **Android** - Build check (if gradlew available)
8. **iOS** - Build and test check (if xcodebuild available)

## Platform-Specific Behavior

### Linux (CI/Development)

- ✅ TypeScript checks
- ✅ Build checks
- ✅ Package checks (forbidden files)
- ⚠️ Android builds: Skipped (requires gradlew)
- ⚠️ iOS builds: Skipped (requires xcodebuild)

### macOS (Full CI)

- ✅ All Linux checks
- ✅ iOS builds: Run if xcodebuild available
- ✅ iOS tests: Run if xcodebuild available

## Required Tooling

### Linux

- Node.js 18+
- npm
- Java 17+ (for Android builds, optional)
- TypeScript compiler

### macOS

- All Linux requirements
- Xcode (for iOS builds/tests)
- xcodebuild command-line tools

## Integration Points

### Release Gate

Add to your release process:

```bash
./ci/run.sh && npm publish
```

### Pre-Merge Gate

Run before merging PRs:

```bash
./ci/run.sh
```

### Git Hook (Recommended)

Install the pre-push hook to automatically run CI before pushing:

```bash
# One-time setup
git config core.hooksPath githooks
```

After setup, `githooks/pre-push` will automatically run `./ci/run.sh` before allowing pushes.

**To skip the hook (not recommended):**
```bash
git push --no-verify
```

### Makefile Target

```bash
# Run local CI
make ci
```

This is equivalent to `./ci/run.sh` and provides a convenient alias.

## Exit Codes

- `0` - All checks passed
- `1` - Verification failed

## Forbidden Files Check

The CI hard-fails if `npm pack --dry-run` contains:

- `xcuserdata/`
- `*.xcuserstate`
- `DerivedData/`
- `ios/App/`
- `.DS_Store`
- `*.swp`, `*.swo`
- `*.orig`, `*.rej`

This ensures the package is publish-safe.

## See Also

- `./scripts/verify.sh` - The actual verification script
- `docs/progress/00-STATUS.md` - Current status and packaging invariants
- `docs/_reference/github-actions-ci.yml` - Reference GitHub Actions template (not used)