NovelSynth Development & Build System

Comprehensive Build Pipeline, Development Workflow & Release Management

This document provides complete documentation for NovelSynth's build system, featuring beautiful CLI interfaces, cross-platform compatibility, and professional release management.

📋 Table of Contents

Build System Overview
Development Workflow
Build Pipeline Architecture
CLI Interface Design
Quality Assurance
Release Management
Cross-Platform Compatibility
Performance Monitoring
Commands Reference

🏗️ Build System Overview

NovelSynth's build system is designed for professional development with beautiful CLI interfaces, comprehensive testing, and automated release management across multiple browsers.

Core Design Principles

🎨 Beautiful CLI: Enhanced user experience with visual progress tracking
🔄 Automated Workflow: Minimal manual intervention required
🌐 Cross-Platform: Works seamlessly on Windows, macOS, and Linux
📦 Multi-Target: Generates optimized packages for Chrome, Firefox, and source distribution
✅ Quality Assurance: Comprehensive testing and validation at every step

Complete Build System Architecture

graph TD
    subgraph "🔄 Development Workflow"
        DEV[👨‍💻 Developer Workspace<br/>TypeScript + React Development]
        GIT[📚 Git Repository<br/>Version Control & Branching]
        IDE[🛠️ VS Code Integration<br/>IntelliSense + Debugging]
        LINT[✨ Code Quality<br/>ESLint + Prettier + TypeScript]
    end

    subgraph "🔧 Build Pipeline Core"
        META[📋 Metadata Sync<br/>package.json ↔ manifest.json]
        CLEAN[🧹 Clean Build<br/>Remove Previous Artifacts]
        COMPILE[⚙️ TypeScript Compilation<br/>Source → JavaScript]
        BUNDLE[📦 Webpack Bundling<br/>Modules → Optimized Bundles]
        ASSETS[🎨 Asset Processing<br/>Images + Icons + Styles]
    end

    subgraph "🎯 Target Generation"
        CHROME[🟢 Chrome Extension<br/>Manifest v3 + Service Worker]
        FIREFOX[🟠 Firefox Extension<br/>Manifest v2 + Background Script]
        SOURCE[📂 Source Package<br/>Development Archive]
        DOCS[📚 Documentation<br/>Auto-generated API Docs]
    end

    subgraph "✅ Quality Assurance"
        TEST[🧪 Automated Testing<br/>Unit + Integration Tests]
        VALIDATE[✔️ Manifest Validation<br/>Browser Compatibility Check]
        SECURITY[🔒 Security Scan<br/>Dependency Vulnerability Check]
        PERFORMANCE[⚡ Performance Analysis<br/>Bundle Size + Load Time]
    end

    subgraph "🚀 Release Management"
        VERSION[🏷️ Version Management<br/>Semantic Versioning]
        PACKAGE[📦 Package Creation<br/>Signed & Compressed Archives]
        RELEASE[🎉 Release Notes<br/>Auto-generated Changelog]
        DEPLOY[🌐 Deployment<br/>Store Submission Ready]
    end

    subgraph "📊 CLI Interface Layer"
        BANNER[🎨 Beautiful Banners<br/>System Info + Progress]
        PROGRESS[⏳ Progress Tracking<br/>Visual Progress Bars]
        LOGGING[📝 Enhanced Logging<br/>Colored Output + Timing]
        STATS[📈 Build Statistics<br/>Performance Metrics]
    end

    %% Development Flow
    DEV --> GIT
    GIT --> IDE
    IDE --> LINT
    LINT --> META

    %% Build Pipeline Flow
    META --> CLEAN
    CLEAN --> COMPILE
    COMPILE --> BUNDLE
    BUNDLE --> ASSETS

    %% Target Generation Flow
    ASSETS --> CHROME
    ASSETS --> FIREFOX
    ASSETS --> SOURCE
    ASSETS --> DOCS

    %% Quality Assurance Flow
    CHROME --> TEST
    FIREFOX --> TEST
    TEST --> VALIDATE
    VALIDATE --> SECURITY
    SECURITY --> PERFORMANCE

    %% Release Flow
    PERFORMANCE --> VERSION
    VERSION --> PACKAGE
    PACKAGE --> RELEASE
    RELEASE --> DEPLOY

    %% CLI Integration
    BANNER -.-> META
    PROGRESS -.-> COMPILE
    LOGGING -.-> BUNDLE
    STATS -.-> PACKAGE

    %% Styling
    style DEV fill:#e3f2fd,stroke:#0277bd,stroke-width:3px
    style META fill:#c8e6c9,stroke:#388e3c,stroke-width:3px
    style CHROME fill:#4caf50,color:#fff,stroke-width:2px
    style FIREFOX fill:#ff9800,color:#fff,stroke-width:2px
    style BANNER fill:#f3e5f5,stroke:#7b1fa2,stroke-width:3px
    style DEPLOY fill:#ffcdd2,stroke:#d32f2f,stroke-width:3px

🛠️ Development Workflow

Complete Development Process

flowchart TD
    DEV[👨‍💻 Developer] --> CODE[💻 Write Code]
    CODE --> TEST[🧪 Local Testing]
    TEST --> COMMIT[📝 Git Commit]
    COMMIT --> SYNC[🔄 Run Metadata Sync]

    SYNC --> BUILD{🏗️ Build Type?}
    BUILD -->|Development| DEV_BUILD[📦 npm run build:dev]
    BUILD -->|Production| PROD_BUILD[🚀 npm run build:full]
    BUILD -->|Watch Mode| WATCH[👀 npm run watch]

    DEV_BUILD --> DEV_TEST[🧪 Browser Testing]
    WATCH --> DEV_TEST
    DEV_TEST --> CODE

    PROD_BUILD --> PACKAGES[📦 Generate Packages]
    PACKAGES --> VALIDATE[✅ Package Validation]
    VALIDATE --> RELEASE[🚀 Create Release]

    subgraph "📦 Generated Packages"
        CHROME_PKG[🟢 Chrome ZIP<br/>Store Ready]
        FIREFOX_PKG[🟠 Firefox XPI<br/>AMO Ready]
        SOURCE_PKG[📂 Source ZIP<br/>Review Package]
    end

    PACKAGES --> CHROME_PKG
    PACKAGES --> FIREFOX_PKG
    PACKAGES --> SOURCE_PKG

    style DEV fill:#e8f5e8,stroke:#2e7d32
    style CODE fill:#e3f2fd,stroke:#1976d2
    style RELEASE fill:#f3e5f5,stroke:#7b1fa2

Development Commands

# Initial setup
npm install
npm run sync-metadata

# Development workflow
npm run dev              # Watch mode with hot reload
npm run build:dev        # Development build with source maps
npm run build:full       # Production build with optimization

# Testing
npm run test             # Run test suite
npm run test:watch       # Tests in watch mode
npm run type-check       # TypeScript validation

# Quality assurance
npm run lint             # ESLint checking
npm run format           # Prettier formatting
npm run validate         # Full validation pipeline

# Package generation
npm run package          # Generate all packages
npm run package:chrome   # Chrome-specific package
npm run package:firefox  # Firefox-specific package

🔧 Build Pipeline Architecture

Metadata Synchronization

The build system automatically synchronizes metadata between package.json and manifest.json:

graph LR
    subgraph "📋 Source Files"
        PKG[📦 package.json<br/>• Version<br/>• Name<br/>• Description<br/>• Author]
        MAN[📄 manifest.json<br/>• Extension metadata<br/>• Permissions<br/>• Content scripts]
    end

    subgraph "🔄 Sync Process"
        SYNC[⚙️ Metadata Sync<br/>• Version alignment<br/>• Field validation<br/>• Browser compatibility]
        BACKUP[💾 Backup Creation<br/>• Original preservation<br/>• Rollback capability]
    end

    subgraph "🎯 Output"
        MAN_CHROME[📄 manifest.json<br/>Chrome Manifest v3]
        MAN_FIREFOX[📄 manifest.json<br/>Firefox Manifest v2]
    end

    PKG --> SYNC
    MAN --> SYNC
    SYNC --> BACKUP
    SYNC --> MAN_CHROME
    SYNC --> MAN_FIREFOX

    style SYNC fill:#e3f2fd,stroke:#0277bd
    style BACKUP fill:#e8f5e8,stroke:#388e3c

TypeScript Compilation & Bundling

graph TB
    subgraph "📁 Source Code"
        TS[📝 TypeScript Files<br/>src/]
        RX[⚛️ React Components<br/>popup/]
        CSS[🎨 Stylesheets<br/>styles/]
    end

    subgraph "🔧 Compilation Process"
        TSC[⚙️ TypeScript Compiler<br/>Type checking & transpilation]
        WEBPACK[📦 Webpack<br/>Module bundling & optimization]
        BABEL[🔄 Babel<br/>JavaScript transformation]
    end

    subgraph "📦 Output Bundles"
        BG[🎯 background.js<br/>Service worker bundle]
        CONTENT[📄 content.js<br/>Content script bundle]
        POPUP[⚙️ popup.js<br/>Popup interface bundle]
    end

    TS --> TSC
    RX --> WEBPACK
    CSS --> WEBPACK
    TSC --> WEBPACK
    WEBPACK --> BABEL
    BABEL --> BG
    BABEL --> CONTENT
    BABEL --> POPUP

    style TSC fill:#3178c6,color:#fff
    style WEBPACK fill:#8dd6f9,color:#000
    style BABEL fill:#f5da55,color:#000

Asset Processing Pipeline

flowchart TD
    ASSETS[🎨 Asset Sources] --> ICONS[🔷 Icon Processing]
    ASSETS --> STYLES[🎨 Style Processing]
    ASSETS --> IMAGES[🖼️ Image Optimization]

    ICONS --> ICON_RESIZE[📏 Multi-Size Generation]
    ICONS --> ICON_OPTIMIZE[⚡ PNG Optimization]

    STYLES --> CSS_COMPILE[⚙️ SCSS Compilation]
    STYLES --> CSS_MINIFY[📦 CSS Minification]
    STYLES --> CSS_PREFIX[🔧 Autoprefixer]

    IMAGES --> IMG_COMPRESS[📦 Image Compression]
    IMAGES --> IMG_FORMAT[🔄 Format Conversion]

    ICON_RESIZE --> DIST_ICONS[📁 dist/icons/]
    ICON_OPTIMIZE --> DIST_ICONS
    CSS_COMPILE --> DIST_STYLES[📁 dist/styles/]
    CSS_MINIFY --> DIST_STYLES
    CSS_PREFIX --> DIST_STYLES
    IMG_COMPRESS --> DIST_IMAGES[📁 dist/images/]
    IMG_FORMAT --> DIST_IMAGES

    style ICONS fill:#4caf50,color:#fff
    style STYLES fill:#2196f3,color:#fff
    style IMAGES fill:#ff9800,color:#fff

🎨 CLI Interface Design

Beautiful System Banner

The build system features a comprehensive information banner:

╔══════════════════════════════════════════════════════════════════════════════╗
║                            🚀 NovelSynth Build System                         ║
╠══════════════════════════════════════════════════════════════════════════════╣
║  📋 Project Information                                                        ║
║  ├─ Name: NovelSynth                    │  ├─ Version: 1.0.0                 ║
║  ├─ Description: AI-powered content     │  ├─ License: MIT                   ║
║  │   enhancement extension              │  └─ Author: Your Name              ║
║                                                                                ║
║  💻 System Information                                                         ║
║  ├─ Platform: Windows 11                │  ├─ Memory: 16.0 GB               ║
║  ├─ Node.js: v18.17.0                   │  ├─ CPU: Intel i7-12700K          ║
║  ├─ npm: 9.6.7                          │  └─ Architecture: x64              ║
║                                                                                ║
║  🎯 Build Configuration                                                        ║
║  ├─ Target: Production                  │  ├─ Mode: Release                  ║
║  ├─ Environment: Cross-browser          │  ├─ Optimization: Enabled         ║
║  ├─ Working Directory: NovelSynth/      │  └─ Timestamp: 2024-12-07 15:30   ║
╚══════════════════════════════════════════════════════════════════════════════╝

Progress Tracking System

graph LR
    subgraph "⏳ Progress Components"
        BAR[📊 Progress Bar<br/>Visual progress indicator]
        STATUS[📋 Status Messages<br/>Current operation description]
        TIMER[⏱️ Elapsed Time<br/>Operation timing]
        ETA[🔮 Estimated Time<br/>Completion prediction]
    end

    subgraph "🎨 Visual Elements"
        SPINNER[🌀 Loading Spinner<br/>Activity indicator]
        COLORS[🎨 Color Coding<br/>Status-based coloring]
        ICONS[🔷 Status Icons<br/>Visual status indicators]
    end

    BAR --> COLORS
    STATUS --> ICONS
    TIMER --> ETA
    SPINNER --> COLORS

    style BAR fill:#e3f2fd,stroke:#1976d2
    style STATUS fill:#e8f5e8,stroke:#388e3c
    style TIMER fill:#fff3e0,stroke:#f57c00

Enhanced Logging System

[15:30:42] 🔄 Starting metadata synchronization...
[15:30:42] ✅ package.json → manifest.json sync complete
[15:30:43] 🧹 Cleaning previous build artifacts...
[15:30:43] ⚙️ Compiling TypeScript sources...
[15:30:45] 📦 Bundling with Webpack...
[15:30:47] 🎨 Processing assets and icons...
[15:30:48] ✅ Chrome extension build complete (2.1 MB)
[15:30:48] ✅ Firefox extension build complete (2.0 MB)
[15:30:49] 📊 Build Statistics:
           ├─ Build time: 7.2 seconds
           ├─ Bundle size: 2.1 MB (Chrome), 2.0 MB (Firefox)
           ├─ Type errors: 0
           └─ Lint warnings: 0

✅ Quality Assurance

Automated Testing Framework

graph TD
    subgraph "🧪 Test Suite Architecture"
        UNIT[🔬 Unit Tests<br/>Individual Component Testing]
        INTEGRATION[🔗 Integration Tests<br/>Component Interaction Testing]
        E2E[🌐 End-to-End Tests<br/>Full Workflow Testing]
        PERFORMANCE[⚡ Performance Tests<br/>Bundle Size + Load Time]
    end

    subgraph "🔍 Test Categories"
        AI_TESTS[🤖 AI Service Tests<br/>Provider Integration]
        UI_TESTS[🖥️ UI Component Tests<br/>React Component Testing]
        STORAGE_TESTS[💾 Storage Tests<br/>Data Persistence]
        SECURITY_TESTS[🔒 Security Tests<br/>Vulnerability Scanning]
    end

    subgraph "📊 Test Reporting"
        COVERAGE[📈 Coverage Reports<br/>Code Coverage Analysis]
        RESULTS[📋 Test Results<br/>Pass/Fail Statistics]
        METRICS[📊 Performance Metrics<br/>Bundle Analysis]
        REPORT[📄 HTML Reports<br/>Detailed Test Documentation]
    end

    UNIT --> AI_TESTS
    UNIT --> UI_TESTS
    INTEGRATION --> STORAGE_TESTS
    INTEGRATION --> SECURITY_TESTS
    E2E --> PERFORMANCE

    AI_TESTS --> COVERAGE
    UI_TESTS --> RESULTS
    STORAGE_TESTS --> METRICS
    SECURITY_TESTS --> REPORT

    style UNIT fill:#e8f5e8,stroke:#4caf50
    style INTEGRATION fill:#e3f2fd,stroke:#2196f3
    style E2E fill:#f3e5f5,stroke:#9c27b0
    style PERFORMANCE fill:#fff3e0,stroke:#ff9800

Manifest Validation & Compatibility

class ManifestValidator {
  validateChromeManifest(manifest: any): ValidationResult {
    const errors: string[] = [];

    // Validate manifest version
    if (manifest.manifest_version !== 3) {
      errors.push('Chrome manifest must use version 3');
    }

    // Validate service worker
    if (!manifest.background?.service_worker) {
      errors.push('Chrome manifest must specify service worker');
    }

    // Validate host permissions
    if (!manifest.host_permissions) {
      errors.push('Chrome manifest must specify host permissions');
    }

    return { valid: errors.length === 0, errors };
  }

  validateFirefoxManifest(manifest: any): ValidationResult {
    const errors: string[] = [];

    // Validate manifest version
    if (manifest.manifest_version !== 2) {
      errors.push('Firefox manifest must use version 2');
    }

    // Validate background scripts
    if (!manifest.background?.scripts) {
      errors.push('Firefox manifest must specify background scripts');
    }

    return { valid: errors.length === 0, errors };
  }
}

Security Scanning

# Dependency vulnerability check
npm audit --audit-level high

# SAST (Static Application Security Testing)
npm run security:scan

# License compliance check
npm run license:check

# Bundle analysis for security
npm run analyze:security

🚀 Release Management

Semantic Versioning Automation

graph TB
    subgraph "🏷️ Version Management"
        CURRENT[📌 Current Version<br/>v1.2.3]
        COMMITS[📝 Analyze Commits<br/>Conventional Commits]
        BUMP[⬆️ Version Bump<br/>patch/minor/major]
    end

    subgraph "📝 Changelog Generation"
        FEATURES[🎉 New Features<br/>feat: commits]
        FIXES[🐛 Bug Fixes<br/>fix: commits]
        BREAKING[💥 Breaking Changes<br/>BREAKING CHANGE: commits]
        NOTES[📋 Release Notes<br/>Auto-generated]
    end

    subgraph "🎯 Release Artifacts"
        TAG[🏷️ Git Tag<br/>Semantic version tag]
        CHROME_REL[🟢 Chrome Package<br/>Store-ready ZIP]
        FIREFOX_REL[🟠 Firefox Package<br/>AMO-ready XPI]
        SOURCE_REL[📂 Source Package<br/>Review-ready ZIP]
    end

    CURRENT --> COMMITS
    COMMITS --> BUMP
    BUMP --> FEATURES
    BUMP --> FIXES
    BUMP --> BREAKING
    FEATURES --> NOTES
    FIXES --> NOTES
    BREAKING --> NOTES
    NOTES --> TAG
    NOTES --> CHROME_REL
    NOTES --> FIREFOX_REL
    NOTES --> SOURCE_REL

    style CURRENT fill:#e3f2fd,stroke:#1976d2
    style NOTES fill:#e8f5e8,stroke:#388e3c
    style TAG fill:#fff3e0,stroke:#f57c00

Package Creation & Signing

flowchart TD
    BUILD[🏗️ Built Extensions] --> VALIDATE[✅ Validation Check]
    VALIDATE --> CHROME_PKG[📦 Chrome Package Creation]
    VALIDATE --> FIREFOX_PKG[📦 Firefox Package Creation]
    VALIDATE --> SOURCE_PKG[📂 Source Package Creation]

    CHROME_PKG --> CHROME_ZIP[🗜️ Chrome ZIP Archive]
    FIREFOX_PKG --> FIREFOX_ZIP[🗜️ Firefox ZIP Archive]
    SOURCE_PKG --> SOURCE_ZIP[🗜️ Source ZIP Archive]

    CHROME_ZIP --> SIGN[🔏 Digital Signing]
    FIREFOX_ZIP --> SIGN
    SOURCE_ZIP --> SIGN

    SIGN --> VERIFY[✔️ Signature Verification]
    VERIFY --> UPLOAD[📤 Upload Ready Packages]

    style BUILD fill:#e3f2fd,stroke:#0277bd
    style VALIDATE fill:#e8f5e8,stroke:#388e3c
    style SIGN fill:#f3e5f5,stroke:#7b1fa2
    style UPLOAD fill:#fff3e0,stroke:#f57c00

Automated Release Notes

class ReleaseNotesGenerator {
  async generateReleaseNotes(version: string): Promise<string> {
    const commits = await this.getCommitsSinceLastRelease();
    const features = this.extractFeatures(commits);
    const bugfixes = this.extractBugfixes(commits);
    const improvements = this.extractImprovements(commits);

    const releaseNotes = `
# NovelSynth v${version} Release Notes

## 🎉 New Features
${features.map(f => `- ${f.description}`).join('\n')}

## 🐛 Bug Fixes
${bugfixes.map(b => `- ${b.description}`).join('\n')}

## ⚡ Improvements
${improvements.map(i => `- ${i.description}`).join('\n')}

## 📊 Statistics
- Total commits: ${commits.length}
- Features added: ${features.length}
- Bugs fixed: ${bugfixes.length}
- Performance improvements: ${improvements.length}

## 🔗 Downloads
- Chrome Web Store: [Extension Link]
- Firefox Add-ons: [Extension Link]
- Source Code: [GitHub Release]
`;

    await fs.writeFile(`releases/v${version}-notes.md`, releaseNotes);
    return releaseNotes;
  }
}

🌐 Cross-Platform Compatibility

Operating System Support

graph TD
    subgraph "💻 Operating Systems"
        WIN[🪟 Windows<br/>PowerShell Commands]
        MAC[🍎 macOS<br/>Unix Commands]
        LIN[🐧 Linux<br/>Unix Commands]
    end

    subgraph "📦 Packaging Methods"
        PS[⚡ PowerShell<br/>Compress-Archive]
        ZIP[🗜️ Native Zip<br/>zip -r command]
        NODE[📦 Node.js<br/>Cross-platform APIs]
    end

    subgraph "✅ Build Validation"
        PATH[📁 Path Resolution<br/>Cross-platform paths]
        PERM[🔐 Permissions<br/>File access rights]
        ENCODE[📝 Encoding<br/>UTF-8 consistency]
    end

    WIN --> PS
    MAC --> ZIP
    LIN --> ZIP

    PS --> NODE
    ZIP --> NODE

    NODE --> PATH
    NODE --> PERM
    NODE --> ENCODE

    style WIN fill:#0078d4,color:#fff
    style MAC fill:#000,color:#fff
    style LIN fill:#fcc624,color:#000
    style NODE fill:#68a063,color:#fff

Browser Compatibility Matrix

Feature	Chrome	Firefox	Edge	Safari
Manifest V3	✅	❌	✅	✅
Manifest V2	✅	✅	✅	✅
Service Workers	✅	❌	✅	✅
Background Scripts	✅	✅	✅	✅
Content Scripts	✅	✅	✅	✅
Storage API	✅	✅	✅	✅

📊 Performance Monitoring

Build Analytics & Metrics

graph LR
    subgraph "📈 Performance Metrics"
        TIME[⏱️ Build Time<br/>Compilation + Bundling]
        SIZE[📦 Bundle Size<br/>Gzipped + Uncompressed]
        MEMORY[🧠 Memory Usage<br/>Peak + Average]
        CPU[⚙️ CPU Usage<br/>Build process efficiency]
    end

    subgraph "📊 Quality Metrics"
        COVERAGE[🎯 Test Coverage<br/>Line + Branch coverage]
        COMPLEXITY[🔄 Code Complexity<br/>Cyclomatic complexity]
        DUPLICATION[👥 Code Duplication<br/>Duplicate code detection]
        MAINTAINABILITY[🛠️ Maintainability<br/>Code quality index]
    end

    subgraph "🎯 Optimization"
        TREESHAKE[🌳 Tree Shaking<br/>Dead code elimination]
        MINIFY[📦 Minification<br/>Code compression]
        COMPRESS[🗜️ Compression<br/>Asset optimization]
        CACHE[💾 Caching<br/>Build cache optimization]
    end

    TIME --> TREESHAKE
    SIZE --> MINIFY
    MEMORY --> CACHE
    COVERAGE --> MAINTAINABILITY
    COMPLEXITY --> TREESHAKE
    DUPLICATION --> MAINTAINABILITY

    style TIME fill:#e3f2fd,stroke:#1976d2
    style SIZE fill:#e8f5e8,stroke:#388e3c
    style COVERAGE fill:#f3e5f5,stroke:#7b1fa2
    style TREESHAKE fill:#fff3e0,stroke:#f57c00

Success/Failure Banners

Success Banner:

╔══════════════════════════════════════════════════════════════════════════════╗
║                              ✅ BUILD SUCCESSFUL                              ║
╠══════════════════════════════════════════════════════════════════════════════╣
║  🎉 Packages Created:                                                          ║
║  ├─ 🟢 Chrome Extension: novelsynth-chrome-v1.0.0.zip (2.1 MB)              ║
║  ├─ 🟠 Firefox Extension: novelsynth-firefox-v1.0.0.xpi (2.0 MB)            ║
║  └─ 📂 Source Package: novelsynth-source-v1.0.0.zip (5.2 MB)                ║
║                                                                                ║
║  📊 Build Statistics:                                                          ║
║  ├─ ⏱️  Total Time: 12.4 seconds                                              ║
║  ├─ 🧪 Tests Passed: 127/127                                                  ║
║  ├─ 📈 Coverage: 94.2%                                                        ║
║  └─ ✨ No lint errors or warnings                                             ║
╚══════════════════════════════════════════════════════════════════════════════╝

Failure Banner:

╔══════════════════════════════════════════════════════════════════════════════╗
║                               ❌ BUILD FAILED                                 ║
╠══════════════════════════════════════════════════════════════════════════════╣
║  🚨 Error Details:                                                             ║
║  ├─ TypeScript compilation failed                                             ║
║  ├─ 3 type errors in src/services/AIManager.ts                               ║
║  └─ 1 lint error in src/components/MainPopup.tsx                             ║
║                                                                                ║
║  🔧 Suggested Actions:                                                         ║
║  ├─ Run `npm run type-check` to see detailed errors                          ║
║  ├─ Run `npm run lint --fix` to auto-fix lint issues                         ║
║  └─ Check the build log above for more details                               ║
╚══════════════════════════════════════════════════════════════════════════════╝

📚 Commands Reference

Primary Build Commands

# Core build commands
npm run build               # Production build for all targets
npm run build:dev           # Development build with source maps
npm run build:chrome        # Chrome-specific build
npm run build:firefox       # Firefox-specific build

# Development commands
npm run dev                 # Watch mode with hot reload
npm run watch               # File watcher for automatic builds
npm run serve               # Local development server

# Quality assurance
npm run test                # Run all tests
npm run test:unit           # Unit tests only
npm run test:integration    # Integration tests only
npm run test:e2e            # End-to-end tests
npm run test:coverage       # Generate coverage report

# Code quality
npm run lint                # ESLint checking
npm run lint:fix            # Auto-fix lint issues
npm run format              # Prettier formatting
npm run type-check          # TypeScript validation

# Utility commands
npm run clean               # Clean build artifacts
npm run sync-metadata       # Sync package.json ↔ manifest.json
npm run analyze             # Bundle size analysis
npm run validate            # Full validation pipeline

# Package management
npm run package             # Create all distribution packages
npm run package:chrome      # Chrome Web Store package
npm run package:firefox     # Firefox Add-ons package
npm run package:source      # Source code package

# Release management
npm run version:patch       # Bump patch version
npm run version:minor       # Bump minor version
npm run version:major       # Bump major version
npm run release             # Full release pipeline

Advanced Commands

# Performance analysis
npm run perf:build          # Build performance analysis
npm run perf:bundle         # Bundle size optimization analysis
npm run perf:memory         # Memory usage profiling

# Security
npm run security:audit      # Security vulnerability scan
npm run security:license    # License compliance check
npm run security:deps       # Dependency analysis

# Documentation
npm run docs:generate       # Generate API documentation
npm run docs:serve          # Serve documentation locally
npm run docs:deploy         # Deploy documentation

# Maintenance
npm run deps:update         # Update dependencies
npm run deps:check          # Check for outdated packages
npm run cache:clear         # Clear build cache

This comprehensive build system documentation ensures reliable, professional development and deployment of NovelSynth across all supported platforms and browsers.