<!-- @template-name: .cursor/commands/build-distribution.md @version: 0.2.0 @release-date: 2025-11-03 -->
# Build Distribution

Build and compile the distribution package containing all files for customer publication to the public Roadcrew repository.

**Note:** This is an automated step that runs before publishing. Manual execution is rarely needed.

## What This Command Does

1. Compiles TypeScript source files to JavaScript
2. Copies compiled files to `dist/scripts/utils/`
3. Adds version headers to each compiled file
4. Verifies imports work correctly
5. Confirms distribution is ready for publishing

## Architecture

Roadcrew uses a simple architecture for distribution:

### Development (main/dev branches)
```
roadcrew-internal/
  ├── commands/          # Cursor commands
  ├── dist/              # Compiled output (generated)
  ├── templates/         # Document templates
  ├── rules/             # Cursor rules
  ├── scripts/           # TypeScript source
  │   └── utils/         # Utility modules
  ├── context/           # Internal docs
  └── memory-bank/       # Internal planning
```

### Distribution (Published to Public Repo)
```
roadcrew/ (public)
  ├── commands/          # Cursor commands (published)
  ├── dist/              # Compiled utilities (published)
  ├── templates/         # Document templates (published)
  ├── rules/             # Cursor rules (published)
  ├── install.cjs        # Installation script (published)
  ├── package.json       # Package config (published)
  ├── setup.sh           # Setup automation (published)
  ├── LICENSE            # License files (published)
  └── README.md          # Customer documentation (published)
```

## Usage

Run this command to manually build distribution (or it runs automatically before publishing):

```bash
# Manual build
/build-distribution

# Or directly via script
npm run build
./scripts/build-distribution.sh
```

## Process

### Step 1: Compile TypeScript

The build script compiles TypeScript sources to JavaScript:

```bash
npm run build
```

**Output:**
- `dist/scripts/` directory with compiled `.js` files
- Source maps (`.js.map`) for debugging
- Each file gets a version header comment

### Step 2: Verify Build

After compilation, the script verifies:
- ✅ All `.js` files compiled successfully
- ✅ Source maps generated
- ✅ Imports are correct
- ✅ File permissions preserved

## What Gets Built

**Included in distribution:**
- ✅ Compiled scripts in `dist/scripts/`
- ✅ Type definitions (`.d.ts`)
- ✅ Source maps (`.map` files)
- ✅ Version headers added to each file
- ✅ Commands (`commands/`)
- ✅ Templates (`templates/`)
- ✅ Rules (`rules/`)
- ✅ Installation script (`install.cjs`)
- ✅ Package config (`package.json`)
- ✅ Documentation (`README.md`, `LICENSE`, etc.)

**Excluded from distribution:**
- ❌ TypeScript source files (`scripts/` `.ts`)
- ❌ Development commands (`.cursor/commands/00-internal/`)
- ❌ Internal docs (`context/`, `memory-bank/`)
- ❌ Build scripts (`build-distribution.sh`)
- ❌ Test files
- ❌ Development dependencies

## Integration with Publishing

The build process is **automated** as part of publishing:

```bash
# Publish runs build automatically
npx tsx scripts/publish-distribution.ts --push

# Build runs first if needed
# Then publishes to public repo
```

**Manual build only needed if:**
- You need to inspect compiled output before publishing
- You're troubleshooting compilation issues
- You want to commit built files separately

## Troubleshooting

### Problem: "TypeScript compilation failed"

```bash
# Check for TypeScript errors
npm run lint:types

# Fix reported errors and rebuild
npm run build
```

### Problem: "Source maps missing"

```bash
# Verify tsconfig.json has sourceMap enabled
cat tsconfig.json | grep -A2 sourceMap

# Rebuild
npm run build
```

## Configuration

Build behavior is configured in `tsconfig.json`:

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ES2020",
    "outDir": "dist",
    "declaration": true,
    "sourceMap": true,
    "strict": true
  }
}
```

## Related Commands

- **`/publish-distribution`** - Publish compiled distribution to public repo
- **`npm run build`** - Direct command to build distribution

---

**Behavior:**
- Automatic: Runs before publishing if needed
- Safe: Non-destructive, only creates files
- Fast: Incremental compilation (only changed files)