Development Workflow and Build System

Relevant source files

• .github/workflows/docker.yml
• .github/workflows/release.yml
• .github/workflows/test.yml
• docs/archives/116-desktop-packaging-optimization/README.md
• docs/testing/README.md
• docs/testing/vcr-usage-guide.md
• docs/workspace/architecture-migration-analysis.md
• docs/workspace/testing-redesign/architecture.md
• docs/workspace/testing-redesign/findings.md
• docs/workspace/testing-redesign/progress.md
• docs/workspace/testing-redesign/task_plan.md
• package.json
• packages/core/package.json
• packages/desktop/package.json
• packages/extension/package.json
• packages/extension/public/manifest.json
• packages/mcp-server/package.json
• packages/ui/package.json
• packages/web/package.json
• pnpm-lock.yaml

Purpose and Scope

This document describes the development environment setup, build pipeline, testing strategies, and contribution workflows for the Prompt Optimizer monorepo. It covers tooling configuration, script execution order, and best practices for local development and continuous integration.

For deployment configurations and environment variables, see Environment Configuration and API Keys. For platform-specific build artifacts and distribution, see Desktop Distribution.

---

Prerequisites and Environment Setup

Node.js Version Requirements

The project enforces strict Node.js version compatibility through engine constraints defined in package.json6-10:

Requirement	Specification
Node.js	^18.0.0 || ^20.0.0 || ^22.0.0
Package Manager	pnpm 10.6.1+ (enforced)
npm/yarn	Blocked with error messages

The project uses packageManager field to enforce pnpm usage. Attempting to use npm or yarn will result in Chinese error messages directing developers to use pnpm.

Initial Setup

Sources: package.json1-10 package.json44

---

Monorepo Architecture and Workspace Configuration

pnpm Workspace Structure

The monorepo uses pnpm workspaces to manage six packages with internal dependencies:

Build Order Dependencies

Packages must be built in dependency order to satisfy workspace protocol links:

Phase 1: Foundation

• @prompt-optimizer/core - Business logic, no internal dependencies

Phase 2: UI Layer

• @prompt-optimizer/ui - Depends on core

Phase 3: Applications

• @prompt-optimizer/web - Depends on UI
• @prompt-optimizer/extension - Depends on UI
• @prompt-optimizer/desktop - Depends on core (uses web build artifacts)
• @prompt-optimizer/mcp-server - Depends on core

Sources: pnpm-lock.yaml10-456 packages/ui/package.json39 packages/web/package.json16

---

Build Pipeline by Package

Diagram: Complete Build Pipeline

Sources: package.json11-52 packages/core/package.json17 packages/desktop/package.json11-13

---

Core Package Build Configuration

The core package uses tsup to compile TypeScript into multiple module formats:

Output	Format	Purpose
dist/index.js	ESM	Modern module bundlers, Node.js with type: "module"
dist/index.cjs	CommonJS	Legacy Node.js compatibility, Electron main process
dist/index.d.ts	TypeScript definitions	Type checking for consumers

Build Command:

Development Mode:

The --watch flag enables hot-reload by regenerating outputs when source files change.

Sources: packages/core/package.json17-18 packages/core/package.json1-15

---

UI Package Build Configuration

The UI package uses vite to build a reusable component library with CSS:

Outputs:

• dist/index.js - ESM entry point
• dist/index.cjs - CommonJS entry point
• dist/index.d.ts - TypeScript definitions (via vite-plugin-dts)
• dist/style.css - Component styles

Vite Configuration Features:

• Component library mode (not SPA)
• CSS extraction and bundling
• Type generation with vite-plugin-dts
• External dependencies (Vue, Naive UI) marked for peer dependencies

Build Command:

Development Mode (Watch):

Sources: packages/ui/package.json26-27 packages/ui/package.json10-19

---

Web Package Build Configuration

The web package uses vite to build a single-page application:

Normal Build:

Electron Build Mode:

The ELECTRON_BUILD environment variable triggers special handling:

• Sets base path to ./ for relative asset loading in Electron
• Outputs to packages/web/dist as usual
• Desktop package copies this to packages/desktop/web-dist

Development Server:

The --force flag clears vite cache to ensure fresh builds after core/UI changes.

Sources: packages/web/package.json6-9 packages/desktop/package.json12

---

Extension Package Build Configuration

The extension package uses vite with special manifest processing:

Build Process:

1. Vite bundles Vue application code
2. Copies public/manifest.json to dist
3. Copies locales and icons to dist

Manifest Structure:

The extension uses Manifest V3 with a service worker background script.

Build Command:

Sources: packages/extension/package.json8 packages/extension/public/manifest.json1-34

---

Desktop Package Build Configuration

The desktop build is a two-phase process:

Phase 1: Web Build Copy

This command:

1. Builds the web application with Electron-specific settings
2. Copies packages/web/dist to packages/desktop/web-dist
3. Ensures the desktop app has current UI assets

Phase 2: Electron Builder

electron-builder Configuration from packages/desktop/package.json32-90:

Platform	Targets	Artifacts
Windows	NSIS installer, ZIP	PromptOptimizer-{version}-win-{arch}.exe PromptOptimizer-{version}-win-{arch}.zip
macOS	DMG, ZIP (x64 + arm64)	PromptOptimizer-{version}-mac-{arch}.dmg PromptOptimizer-{version}-mac-{arch}.zip
Linux	AppImage, ZIP	PromptOptimizer-{version}-linux-{arch}.AppImage PromptOptimizer-{version}-linux-{arch}.zip

Auto-Update Configuration:

The desktop app checks GitHub releases for updates using electron-updater.

Sources: packages/desktop/package.json11-13 packages/desktop/package.json32-90

---

MCP Server Build Configuration

The MCP server uses tsup to create a standalone CLI binary:

Build Command:

Outputs:

• dist/index.js / dist/index.cjs - Server implementation
• dist/start.js / dist/start.cjs - CLI entry point (marked as bin in package.json)
• dist/index.d.ts - Type definitions

Binary Configuration:

After installation, the server can be invoked as prompt-optimizer-mcp.

Sources: packages/mcp-server/package.json12 packages/mcp-server/package.json8-10

---

Development Workflows

Diagram: Development Script Execution Flow

Sources: package.json20-26 package.json11-19

---

Standard Development Workflow (Web)

This script executes:

1. pnpm run kill:dev - Kills any running dev processes (Node.js port conflicts)
2. pnpm run clean - Removes all dist folders and vite cache
3. pnpm install - Ensures dependencies are installed
4. pnpm run dev - Starts parallel development mode

What dev does:

The UI package rebuilds on file changes, and the web dev server serves the application at http://localhost:5173 (default vite port).

Sources: package.json20-22 package.json41-43

---

Desktop Development Workflow

This executes:

1. pnpm run kill:dev - Kill existing processes
2. pnpm run clean - Clean build artifacts
3. pnpm install - Install dependencies
4. pnpm run dev:desktop:parallel - Start desktop + web in parallel

Parallel Execution:

This starts:

• WEB process: Vite dev server on port 5173
• DESKTOP process: Electron loads http://localhost:5173

Electron Development Mode:

In development mode packages/desktop/package.json14 the Electron main process loads from the dev server instead of web-dist files.

Sources: package.json24-26 packages/desktop/package.json14

---

Process Management

Kill Development Processes:

This script package.json59 runs a Node.js script that forcefully terminates:

• All Node.js processes on development ports (5173, 3000, 8080)
• Electron processes
• Vite processes

Useful when processes hang or ports are in use.

Clean Build Artifacts:

Sources: package.json41-43 package.json59

---

Workspace-Scoped Commands

pnpm provides -F (filter) flag to target specific packages:

Recursive Commands:

The -r flag executes commands in topological order based on workspace dependencies.

Sources: package.json28 package.json13-14

---

Testing Strategy and Quality Gates

Diagram: Complete Test Infrastructure

Sources: package.json27-40 packages/core/tests/utils/vcr.ts packages/ui/tests/utils/error-detection.ts tests/e2e/fixtures.ts

---

VCR System: LLM API Recording and Replay

The VCR (Video Cassette Recorder) system enables offline testing by recording real LLM API responses and replaying them in subsequent test runs. This eliminates API costs in CI and ensures deterministic test results.

Architecture:

Component	Purpose	Location
vcr.ts	VCR mode control and fixture management	packages/core/tests/utils/vcr.ts
llm-mock-service.ts	MSW handlers for LLM providers	packages/core/tests/utils/llm-mock-service.ts
stream-simulator.ts	Simulates streaming responses	packages/core/tests/utils/stream-simulator.ts
fixtures/	Stored API responses	packages/core/tests/fixtures/
setup.js	Global MSW integration	packages/core/tests/setup.js

VCR Modes:

Environment Variables:

Variable	Values	Purpose
VCR_MODE	auto, record, replay, off	Controls VCR behavior
ENABLE_REAL_LLM	true, false	Allows real API access (for record/off modes)
E2E_VCR_MODE	record, replay	E2E-specific VCR mode

Fixture Structure:

Fixtures are stored as JSON files organized by provider and scenario:

packages/core/tests/fixtures/
└── llm/
    ├── deepseek/
    │   ├── optimize-simple-prompt.json
    │   └── stream-response.json
    ├── openai/
    │   ├── chat-completion.json
    │   └── error-handling.json
    └── gemini/
        └── multi-turn-conversation.json

Each fixture contains:

• Request metadata (provider, model, messages)
• Response data (content, timestamps, tokens)
• Streaming chunks (if applicable)

Usage in Tests:

Sources: packages/core/tests/utils/vcr.ts packages/core/tests/utils/llm-mock-service.ts packages/core/tests/setup.js docs/testing/vcr-usage-guide.md

---

UI Error Detection Gates

The testing system automatically detects and fails tests on UI errors that would otherwise only be visible in browser console:

Vitest Environment (UI Package):

packages/ui/tests/utils/error-detection.ts implements global error handlers:

Integrated in packages/ui/tests/setup.ts to apply globally to all UI tests.

Playwright Environment (E2E Tests):

tests/e2e/fixtures.ts exports custom test and expect with error listeners:

All E2E tests import from ./fixtures instead of @playwright/test.

Ignored Errors:

Both systems support ignore patterns for legitimate warnings:

• Development-mode Vue warnings
• Third-party library notices
• Expected error scenarios in error-handling tests

Sources: packages/ui/tests/utils/error-detection.ts packages/ui/tests/setup.ts tests/e2e/fixtures.ts docs/workspace/testing-redesign/architecture.md

---

Test Gate Strategy

Test gates provide fast feedback loops while ensuring quality:

Fast Gate (Pre-commit):

Executes in < 1 minute package.json36:

• Core VCR unit tests (test:gate:core)
• UI component tests (test:gate:ui)
• Total: 240 tests (21 core + 219 UI)

Full Gate (CI):

Adds E2E regression suite package.json37:

• All fast gate tests
• Critical E2E paths (test:gate:e2e)
• Total: 257 tests (240 + 17 E2E)
• Execution time: < 10 minutes

E2E Gate:

Runs only critical E2E smoke tests package.json35:

• tests/e2e/regression.spec.ts - Basic functionality regression
• tests/e2e/workflows/p0-route-smoke.spec.ts - Core route accessibility

Pre-commit Hook:

.husky/pre-commit automatically runs fast gate:

Sources: package.json33-37 .husky/pre-commit docs/workspace/testing-redesign/progress.md

---

Test Execution Matrix

Command	Tests Run	Time	Environment	Use Case
pnpm test	All unit + integration (auto VCR)	~2-3 min	Local dev	Quick validation
pnpm test:gate	Fast gate (240 tests)	< 1 min	Pre-commit	Blocking quality gate
pnpm test:gate:full	Fast gate + E2E (257 tests)	< 10 min	CI	Merge requirement
pnpm test:replay	All tests (strict VCR)	~3-4 min	CI	Offline CI runs
pnpm test:record	All tests (real API)	~10-15 min	Manual	Update fixtures
pnpm test:e2e	All E2E tests	~2-3 min	Local/CI	Full browser coverage
pnpm test:e2e:smart	Affected E2E subset	~30-60 sec	CI optimization	Changed files only

Smart E2E Testing:

scripts/smart-e2e.js analyzes git diff to run only affected E2E tests:

1. Detects changed files in git diff
2. Maps changes to test files (e.g., core changes → all tests, UI changes → specific workspace tests)
3. Runs subset or full suite based on impact scope
4. Falls back to full suite for extensive changes

Sources: package.json27-40 scripts/smart-e2e.js docs/testing/README.md

---

Unit and Integration Testing

Core Package Tests:

Located in packages/core/tests/:

• Unit tests: tests/unit/**/*.spec.ts (71 files)
• Integration tests: tests/integration/**/*.spec.ts (19 files)
• Test runner: Vitest with Node.js environment
• API mocking: MSW (Mock Service Worker)

Run core tests:

UI Package Tests:

Located in packages/ui/tests/:

• Unit tests: tests/unit/**/*.spec.ts (18 files)
• Integration tests: tests/integration/**/*.spec.ts (2 files)
• E2E tests: tests/e2e/**/*.spec.ts (1 file)
• Test runner: Vitest with jsdom environment
• Component testing: @vue/test-utils

Run UI tests:

Key Testing Utilities:

Utility	Purpose	Location
withVCR()	VCR wrapper for LLM tests	packages/core/tests/utils/vcr.ts
createTestPinia()	Pinia store testing helper	packages/ui/tests/utils/pinia-test-helpers.ts
withMockPiniaServices()	Auto-cleanup test wrapper	packages/ui/tests/utils/pinia-test-helpers.ts
real-llm helpers	Real LLM API integration	packages/core/tests/helpers/

Sources: packages/core/package.json19-24 packages/ui/package.json28 packages/core/tests/ packages/ui/tests/

---

E2E Testing with Playwright

Configuration:

playwright.config.ts defines:

• Browser: Chromium only (fast CI)
• Dev server: Port 15555 (web package)
• Timeout: 30 seconds per test
• Retries: 2 in CI, 0 locally
• Parallel: Up to 4 workers

Test Organization:

Located in tests/e2e/:

• regression.spec.ts - Basic functionality smoke tests
• workflows/ - Multi-step user workflows
• fixtures.ts - Custom Playwright fixtures with error gates

Run E2E tests:

VCR Mode in E2E:

Sources: playwright.config.ts tests/e2e/ package.json29-32

---

Code Quality and Standards

Linting

The project uses ESLint with TypeScript support:

Configuration: packages/ui/.eslintrc.json

Linting rules are defined in .eslintrc.json and enforce:

• TypeScript type safety with @typescript-eslint/eslint-plugin
• Vue.js best practices with eslint-plugin-vue
• Custom project-specific rules

ESLint Scope:

• Primary linting: UI package packages/ui/package.json30-31
• Root-level commands proxy to UI package package.json54-55

Sources: package.json54-55 packages/ui/package.json30-31

---

Type Checking

TypeScript type checking is performed separately from builds:

Type Check Command:

The --noEmit flag checks types without generating output files (build handles output).

tsconfig Configuration:

• Each package has its own tsconfig.json
• Extends @vue/tsconfig for Vue projects
• Strict mode enabled for type safety

Sources: packages/ui/package.json29 packages/mcp-server/package.json17

---

Documentation Standards

From .cursorrules19-36 the project maintains two documentation files:

experience.md - Long-term knowledge:

• Reusable component patterns
• Dependency versions and compatibility
• Model configurations
• Bug fixes and root causes
• Architecture decisions

scratchpad.md - Working memory:

• Current task tracking
• Step-by-step implementation plans
• Problem logs with solutions
• Milestone checklists

Documentation Update Requirements:

1. After fixing bugs: Add to experience.md with root cause analysis
2. During development: Track progress in scratchpad.md
3. After completing features: Update relevant documentation
4. Before merging: Ensure documentation is current

Sources: .cursorrules19-64

---

Code Review Checklist

From .cursorrules110-115 reviewers should verify:

1. Type Safety: All TypeScript types are explicit and correct
2. Error Handling: Try-catch blocks with proper error messages
3. Test Coverage: New code has corresponding tests
4. Code Style: Follows ESLint rules
5. Performance: No obvious performance regressions

Sources: .cursorrules110-115

---

Version Management

Version Management and Release Process

Version Synchronization:

scripts/sync-versions.js ensures all packages use the same version:

1. Reads version from root package.json (currently 2.5.4)
2. Updates version field in all workspace package.json files
3. Maintains consistency across monorepo

Local Release Workflow:

Automated Git Hook:

package.json46 defines a lifecycle script that runs after pnpm version:

This ensures version changes are automatically staged.

CI/CD Release Trigger:

Pushing a git tag triggers .github/workflows/release.yml:

1. Tag format: v*.*.* (e.g., v2.5.4)
2. Pre-release tags: v*.*.*-beta.1, v*.*.*-rc.2
3. Workflow dynamically extracts version from tag
4. Updates package.json in each platform build job
5. Publishes to GitHub Releases with installers

Version Constraints:

Constraint	Value	Purpose
Package Manager	[email protected]	Enforced consistency
Lockfile Version	9.0	pnpm lockfile format
Node.js Engines	^18.0.0 || ^20.0.0 || ^22.0.0	Supported Node versions
Dependency Override	[email protected]	Fixes electron-builder issue

Desktop Application Versioning:

The release workflow .github/workflows/release.yml44-115 modifies packages/desktop/package.json during build:

This ensures installer metadata matches the release tag.

Extension Manifest Versioning:

packages/extension/public/manifest.json5 must be manually updated before release:

Chrome Web Store requires exact version match with manifest.

Sources: package.json45-49 package.json3 package.json99-106 .github/workflows/release.yml44-115 packages/extension/public/manifest.json5

---

Common Development Tasks

Full Clean Rebuild

Sources: package.json41-43

---

Debugging Desktop Application

View Logs:

This opens the logs directory at %APPDATA%\PromptOptimizer\logs.

Clear Logs:

Log Locations by Platform:

• Windows: %APPDATA%\PromptOptimizer\logs
• macOS: ~/Library/Application Support/PromptOptimizer/logs
• Linux: ~/.config/PromptOptimizer/logs

Sources: packages/desktop/package.json15-16

---

MCP Server Development

Start MCP Server (HTTP Mode):

This runs packages/mcp-server/package.json13:

The -r ./preload-env.js flag loads environment variables from .env before execution.

Test MCP Server:

Production Start:

Uses the CommonJS build (dist/start.cjs) for better compatibility.

Sources: packages/mcp-server/package.json12-15

---

Building for Production

All Platforms:

This executes in order package.json12:

1. build:core - Core package (tsup)
2. build:ui - UI package (vite)
3. build:parallel - Web + Extension in parallel

Desktop Only:

Builds core, UI, web, then packages desktop application package.json19

Sources: package.json12-19

---

CI/CD Pipeline

Diagram: GitHub Actions Workflow Architecture

Sources: .github/workflows/test.yml .github/workflows/release.yml .github/workflows/docker.yml

---

Test Workflow (test.yml)

Trigger Conditions:

• Push to main or master branches
• Pull requests targeting main or master
• Manual dispatch via GitHub UI
• Called by other workflows (workflow_call)

Execution Steps:

.github/workflows/test.yml17-49 defines a single test job on ubuntu-latest:

1. Checkout code with actions/checkout@v6
2. Setup pnpm with pnpm/action-setup@v4
3. Setup Node.js 22 with cache enabled
4. Install dependencies: pnpm install
5. Run fast gate: pnpm test:gate (Core + UI tests, 240 tests)
6. Install Playwright: pnpm exec playwright install --with-deps chromium
7. Run E2E gate: pnpm test:gate:e2e (17 critical E2E tests)
   • Environment: E2E_VCR_MODE=replay (strict offline mode)

Total execution time: Typically 5-8 minutes

Key configurations:

• Node version: 22 (enforced consistency)
• Cache: pnpm store cached by actions/setup-node@v6
• Path ignore: **.md and docs/** (skip on doc-only changes)

Sources: .github/workflows/test.yml1-49

---

Release Workflow (release.yml)

Trigger Conditions:

• Git tags matching v*.*.* (e.g., v2.5.4)
• Git tags with pre-release suffixes: v*.*.*-* (e.g., v2.5.4-beta.1)
• Manual dispatch with version input

Multi-Stage Process:

Stage 1: Test Gate

.github/workflows/release.yml19-20 calls test.yml workflow first. Release only proceeds if all tests pass.

Stage 2: Platform Builds (Parallel)

Three parallel jobs build desktop applications:

Windows Build .github/workflows/release.yml23-154:

• Runner: windows-latest
• Dynamic package.json modification (PowerShell):

• Build command: pnpm build:desktop
• Artifacts: .exe installer + .zip portable + .yml auto-update manifest
• Upload with actions/upload-artifact@v6 (30-day retention)

macOS Build .github/workflows/release.yml156-280:

• Runner: macos-latest
• Dynamic package.json modification (bash + jq)
• Build command: pnpm build:desktop
• Artifacts:
  • .dmg installers (x64 + arm64)
  • .zip portable archives (x64 + arm64)
  • .yml auto-update manifests
• Note: Builds both Intel (x64) and Apple Silicon (arm64) binaries

Linux Build .github/workflows/release.yml282-406:

• Runner: ubuntu-latest
• Dynamic package.json modification (bash + jq)
• Build command: pnpm build:desktop
• Artifacts: .AppImage + .zip + .yml auto-update manifest

Artifact Verification:

Each build job includes verification .github/workflows/release.yml124-144:

Stage 3: Release Creation

.github/workflows/release.yml408-670 unifies artifacts and publishes:

1. Download artifacts from all platform builds
2. Remove debug files: Delete builder-debug.yml files
3. Generate release notes:
   • Extract commits since previous tag
   • Format commit messages with links
   • Detect version type (stable/prerelease/hotfix)
   • Generate download instructions per platform
   • Include macOS security tips (quarantine removal)
4. Create GitHub Release:
   • Uses softprops/action-gh-release@v2
   • Attaches all platform artifacts
   • Sets prerelease flag for beta/alpha/rc versions
   • Generates semantic release name (e.g., "Release v2.5.4" or "Preview v2.5.4-beta.1")

Version Detection Logic .github/workflows/release.yml438-458:

Pattern	Type	Prerelease Flag	Example
v*.*.*	Stable release	false	v2.5.4
v*.*.*-alpha	Alpha	true	v2.5.4-alpha.1
v*.*.*-beta	Beta	true	v2.5.4-beta.1
v*.*.*-rc	Release candidate	true	v2.5.4-rc.1
v*.*.*-hotfix	Hotfix	false	v2.5.4-hotfix.1

Auto-Update Integration:

The .yml manifest files enable Electron auto-updater:

Sources: .github/workflows/release.yml1-670 packages/desktop/package.json32-90

---

Docker Workflow (docker.yml)

Trigger Conditions:

• Automatic: After successful test.yml workflow on main/master
• Manual: workflow_dispatch

Conditional Execution:

Only runs if .github/workflows/docker.yml20:

• Triggered manually, OR
• test.yml succeeded AND push event on main/master

Multi-Architecture Build:

.github/workflows/docker.yml26-71 performs:

1. Version extraction from package.json .github/workflows/docker.yml32-37:

2. Registry login (dual-push):

   • Docker Hub: docker.io/linshen/prompt-optimizer
   • Aliyun Registry: registry.cn-guangzhou.aliyuncs.com/prompt-optimizer/prompt-optimizer

3. QEMU setup for cross-compilation .github/workflows/docker.yml52-53

4. Docker Buildx with platforms .github/workflows/docker.yml62:

5. Multi-tag push .github/workflows/docker.yml64-68:

   • linshen/prompt-optimizer:2.5.4
   • linshen/prompt-optimizer:latest
   • registry.cn-guangzhou.aliyuncs.com/.../prompt-optimizer:2.5.4
   • registry.cn-guangzhou.aliyuncs.com/.../prompt-optimizer:latest

6. Build cache optimization .github/workflows/docker.yml69-70:

Docker Image Contents:

From the Dockerfile (implied structure):

• Web application static files (packages/web/dist)
• MCP server (packages/mcp-server/dist)
• Nginx configuration (serves web on port 80, proxies MCP)

Sources: .github/workflows/docker.yml1-71

---

CI Optimization Strategies

Parallel Execution:

• Release workflow: Windows, macOS, and Linux builds run simultaneously
• Reduces total build time from ~45 minutes (serial) to ~15-20 minutes

Caching:

• pnpm store: Cached by setup-node action (reduces install time by 80%)
• Docker layers: GitHub Actions cache for multi-arch builds (saves 5-10 minutes)
• Playwright browsers: Only installed once per workflow run

Smart Test Execution:

• Fast gate (< 1 min) runs before slow E2E tests
• VCR replay mode eliminates network latency and API costs
• Smart E2E skips unaffected tests based on git diff

Path Filtering:

• test.yml ignores **.md and docs/** changes
• Prevents unnecessary CI runs on documentation updates

Conditional Workflows:

• Docker build only after successful tests
• Release workflow only on git tags
• E2E tests only after unit/integration tests pass

Sources: .github/workflows/test.yml5-8 .github/workflows/docker.yml20 .github/workflows/release.yml409

---

Contribution Workflow

Development Process

From .cursorrules93-109 the standard workflow is:

1. Feature Development:

2. Bug Fixes:

3. Pre-Commit:

Sources: .cursorrules93-109

---

Testing Requirements

From .cursorrules10-18 every code change must:

1. Execute npm run test (maps to pnpm run test)
2. Ensure all test cases pass
3. Include new tests for new functionality
4. Cover:
   • Unit tests for isolated logic
   • Integration tests for service interactions
   • Exception scenarios

Sources: .cursorrules10-18

---

Documentation Requirements

Before submitting a PR, update:

1. Code Comments: Complex logic must have inline explanations
2. experience.md: New patterns, bugs fixed, lessons learned
3. scratchpad.md: Clear task completion notes
4. README: If adding new features or changing setup

From .cursorrules119-125 required reading before contribution:

• fileNames.md - Project file map
• docs/prd.md - Product requirements
• docs/app-flow.md - Application flow diagrams
• docs/tech-stack.md - Technology stack overview
• docs/file-structure.md - Directory structure
• docs/frontend-guidelines.md - Frontend development standards

Sources: .cursorrules119-125 .cursorrules19-36

---

This comprehensive build and workflow system ensures consistent development across all platforms while maintaining high code quality through automated testing and standardized processes. The monorepo structure enables code sharing while the flexible build pipeline supports diverse deployment targets from web apps to desktop applications to MCP servers.