---
roadcrew_template_name: "build-project.md"
roadcrew_template_type: "command"
execution_mode: "auto-execute"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
---

# Build Project

Build the roadcrew project by compiling TypeScript utilities and ensuring all dependencies are installed.

## What This Command Does

1. Checks if `node_modules` is installed
2. Installs dependencies if needed
3. Compiles TypeScript files from `scripts/utils/*.ts` to `dist/scripts/utils/*.js`
4. Validates the build was successful
5. Shows build summary

## Usage

Run this command when:
- Initial setup of roadcrew
- After pulling updates from git
- Before running any TypeScript utilities
- When `dist/` directory is missing
- After modifying TypeScript source files

## Process

### 1. Check Node.js Installation

Verify Node.js is installed and meets minimum version requirement:

```bash
node --version
```

Required: Node.js >= 18.0.0 (from package.json engines)

If not installed:
- **macOS**: `brew install node` or download from nodejs.org
- **Linux**: `sudo apt install nodejs npm` or use nvm
- **Windows**: Download from nodejs.org

### 2. Install Dependencies

Check if `node_modules` exists:
```bash
ls -la node_modules
```

If missing or after package.json changes, install:
```bash
npm install
```

**What gets installed:**
- **Production dependencies**: 
  - `fs-extra` - Enhanced file system operations
  - `glob` - File pattern matching
  - `googleapis` - Google Drive API integration
  - `yaml` - YAML file parsing
- **Dev dependencies**:
  - `typescript` - TypeScript compiler
  - `@types/*` - Type definitions
  - `eslint` - Code linting
  - `@typescript-eslint/*` - TypeScript linting rules

### 3. Compile TypeScript

Use the smart build helper (recommended):
```bash
npm run ensure-built
```

**What `ensure-built` does:**
- Checks if `dist/` directory exists
- Checks if TypeScript source files changed since last build
- Only compiles if needed (saves time)
- Shows clear status messages

**Or manually compile:**
```bash
npm run build
```

This runs `tsc` which compiles:
- Input: `scripts/utils/*.ts` (TypeScript source)
- Output: `dist/scripts/utils/*.js` (JavaScript)
- Also generates: `.d.ts` type definition files

**Compilation settings** (from `tsconfig.json`):
- Target: ES2022
- Module: ES modules
- Strict mode: enabled
- Source maps: generated
- Output directory: `dist/`

### 4. Verify Build Success

Check that compiled files exist:
```bash
ls -la dist/scripts/utils/
```

Expected output:
```
detect-deployment.js
detect-deployment.d.ts
detect-schema.js
detect-schema.d.ts
detect-cicd.js
detect-cicd.d.ts
[other utility files]
```

### 5. Run Type Checking (Optional but Recommended)

Check for TypeScript errors without emitting files:
```bash
npm run type-check
```

This validates:
- All types are correct
- No `any` types (strict mode)
- Return types are explicit
- Imports are valid

### 6. Run Linting (Optional)

Check code quality:
```bash
npm run lint
```

Auto-fix linting issues:
```bash
npm run lint:fix
```

### 7. Display Build Summary

Show what was built:

```
✅ Build successful!

📦 Dependencies: Installed (42 packages)
🔨 TypeScript: Compiled (5 files)
📁 Output: dist/scripts/utils/

Built files:
- detect-deployment.js (3.2 KB)
- detect-schema.js (4.1 KB)  
- detect-cicd.js (2.8 KB)

Ready to use:
- npm run process-feedback
- npm run validate-setup
- /analyze-repo command
```

## Troubleshooting

### Problem: "command not found: npm"

**Solution:**
```bash
# Install Node.js (includes npm)
# macOS
brew install node

# Ubuntu/Debian
sudo apt install nodejs npm

# Or use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
```

### Problem: "npm ERR! ENOENT"

**Solution:**
```bash
# Initialize package.json if missing
npm init -y

# Or restore from git
git checkout package.json
npm install
```

### Problem: TypeScript compilation errors

**Solution:**
```bash
# Check TypeScript is installed
npm list typescript

# Reinstall if missing
npm install --save-dev typescript

# Check for syntax errors in source files
npm run type-check

# Review and fix errors shown
```

### Problem: "Cannot find module './dist/...'"

**Cause:** Trying to import compiled files before building

**Solution:**
```bash
# Build first
npm run ensure-built

# Then run your script
npm run process-feedback
```

### Problem: "EACCES: permission denied"

**Solution:**
```bash
# Fix npm permissions (don't use sudo with npm)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

# Or reinstall Node with proper permissions
```

### Problem: Build succeeds but files missing

**Solution:**
```bash
# Check tsconfig.json outDir setting
cat tsconfig.json | grep outDir

# Should be: "outDir": "./dist"

# Check .gitignore doesn't exclude dist when building
# (dist/ should be gitignored but present after build)

# Force clean rebuild
rm -rf dist node_modules
npm install
npm run build
```

## Files Involved

**Source files (tracked in git):**
```
scripts/utils/
├── detect-deployment.ts
├── detect-schema.ts  
└── detect-cicd.ts
```

**Compiled output (gitignored):**
```
dist/scripts/utils/
├── detect-deployment.js
├── detect-deployment.d.ts
├── detect-schema.js
├── detect-schema.d.ts
├── detect-cicd.js
└── detect-cicd.d.ts
```

**Configuration files:**
```
tsconfig.json          # TypeScript compiler config
package.json           # Dependencies and scripts
eslint.config.js       # Linting rules
scripts/ensure-built.js  # Smart build helper
```

## Build Scripts Reference

| Script | Command | Purpose |
|--------|---------|---------|
| `npm run build` | `tsc` | Compile TypeScript files |
| `npm run ensure-built` | `node scripts/ensure-built.js` | Smart compile (only if needed) |
| `npm run type-check` | `tsc --noEmit` | Check types without building |
| `npm run lint` | `eslint . --ext .ts` | Check code quality |
| `npm run lint:fix` | `eslint . --ext .ts --fix` | Auto-fix linting issues |

## When to Rebuild

**Always rebuild after:**
- Pulling updates from git (upstream sync)
- Modifying any `.ts` file in `scripts/utils/`
- Updating TypeScript version in package.json
- Changing `tsconfig.json` settings
- Deleting `dist/` directory

**No rebuild needed after:**
- Modifying markdown files
- Changing config files (yaml, json, md)
- Updating non-TypeScript dependencies
- Working on roadmap documents

## CI/CD Integration

If you have CI/CD setup, ensure build step is included:

```yaml
# .github/workflows/test.yml
steps:
  - uses: actions/checkout@v3
  - uses: actions/setup-node@v3
    with:
      node-version: '18'
  - run: npm install
  - run: npm run build
  - run: npm run type-check
  - run: npm run lint
  - run: npm test
```

## Best Practices

1. **Always use `ensure-built`** instead of `build` for faster execution
2. **Run `type-check`** before committing to catch errors early
3. **Don't commit `dist/`** (it's gitignored for a reason)
4. **Keep dependencies updated** but test after updates
5. **Document custom utilities** if you add new TypeScript files

## Notes

- Build artifacts (`dist/`) are gitignored and not synced between template and instances
- Each instance must build independently after setup or sync
- Source files (`.ts`) are synced from template to instances
- Compiled files (`.js`) are generated locally on each machine
- This pattern works reliably in sandboxed/offline environments