Web Application Deployment Pipeline

Relevant source files

• Windsurf/Tools Wave 11.txt

Purpose and Scope

This document describes Windsurf Cascade's web application deployment pipeline, which enables automated deployment of JavaScript web applications to hosting providers like Netlify. The pipeline consists of three primary tools that handle configuration validation, deployment execution, and status monitoring.

For information about Windsurf's browser preview capabilities for local development servers, see Browser Preview and Page Interaction. For memory management across deployments, see Memory and Context Management.

Deployment Pipeline Overview

Windsurf Cascade provides a three-stage deployment workflow that validates project configuration, executes the deployment, and monitors completion status. The system handles source-only deployments without requiring pre-built artifacts, and supports both new site creation and updates to existing deployments.

Pipeline Architecture Diagram

Sources: Windsurf/Tools Wave 11.txt195-201 Windsurf/Tools Wave 11.txt88-100 Windsurf/Tools Wave 11.txt27-33

Tool Ecosystem

The deployment pipeline consists of three distinct tools that must be invoked in sequence:

Tool Name	Purpose	Input Requirements	Output
read_deployment_config	Validate project readiness	ProjectPath (absolute path)	Configuration status, missing files
deploy_web_app	Execute deployment	Framework, ProjectPath, ProjectId, Subdomain	WindsurfDeploymentId
check_deploy_status	Monitor deployment	WindsurfDeploymentId	Build status, claim status

Sources: Windsurf/Tools Wave 11.txt195-201 Windsurf/Tools Wave 11.txt88-100 Windsurf/Tools Wave 11.txt27-33

Configuration Validation Tool

read_deployment_config

The read_deployment_config tool performs pre-deployment validation by analyzing the project structure and determining if all required files exist for successful deployment.

Tool Signature

Parameters

• ProjectPath: The full absolute project path of the web application. Must point to the root directory containing the application source code.
• toolSummary: Brief 2-5 word summary of the action (e.g., "validating deployment config")

Workflow Integration

This tool must be executed first before any deployment attempt. It analyzes the project structure and returns information about:

• Whether the application is ready for deployment
• Missing configuration files that must be created
• Existing deployment configuration (if any)

If the tool identifies missing files, Cascade must create them before proceeding with deployment.

Sources: Windsurf/Tools Wave 11.txt195-201

Deployment Execution Tool

deploy_web_app

The deploy_web_app tool executes the actual deployment to hosting providers like Netlify. It handles both new site creation and updates to existing deployments.

Tool Signature

Parameter Specifications

Framework (required)

• Specifies the JavaScript framework used by the application
• Must be one of 18 supported frameworks (see Framework Support section below)
• Determines build configuration and deployment strategy

ProjectPath (required)

• Full absolute path to the project root directory
• Must match the path used in read_deployment_config
• Must contain all source files (build not required)

ProjectId (conditional)

• For existing sites: Exact project ID from deployment configuration file
• For new sites or renames: Leave EMPTY
• Critical for re-deployments to maintain site identity

Subdomain (conditional)

• For new sites: Unique subdomain or project name for the URL
• For existing sites (using ProjectId): Leave EMPTY
• Should be relevant to the project purpose

Sources: Windsurf/Tools Wave 11.txt88-100

Deployment Decision Logic

Sources: Windsurf/Tools Wave 11.txt92-97

Framework Support Matrix

The deployment pipeline supports 18 JavaScript frameworks, each with framework-specific build and deployment configurations:

Supported Frameworks

Framework	Type	Primary Use Case
nextjs	React Meta-framework	Full-stack React applications
nuxtjs	Vue Meta-framework	Full-stack Vue applications
sveltekit	Svelte Meta-framework	Full-stack Svelte applications
remix	React Meta-framework	Full-stack React with enhanced data loading
astro	Multi-framework	Static sites with partial hydration
gatsby	React Static Generator	Static React sites with GraphQL
hugo	Go Static Generator	Ultra-fast static sites
jekyll	Ruby Static Generator	Blog-focused static sites
eleventy	JavaScript Static Generator	Flexible static site generation
create-react-app	React SPA	Client-side React applications
angular	TypeScript Framework	Enterprise Angular applications
svelte	Component Framework	Lightweight reactive applications
hydrogen	Shopify Framework	E-commerce storefronts
gridsome	Vue Static Generator	Static Vue sites with GraphQL
hexo	Node.js Static Generator	Blog-focused static generation
middleman	Ruby Static Generator	Ruby-based static sites
mkdocs	Python Documentation	Documentation sites
grunt	Task Runner	Legacy JavaScript build systems

Sources: Windsurf/Tools Wave 11.txt91

Status Monitoring Tool

check_deploy_status

The check_deploy_status tool monitors deployment progress and determines build completion and site claim status.

Tool Signature

Parameters

WindsurfDeploymentId (required)

• The deployment identifier returned by deploy_web_app
• NOT the same as ProjectId
• Used to query deployment provider for build status

Execution Constraints

• Must only be invoked after deploy_web_app has executed
• Should not be invoked unless explicitly requested by the user
• Polls the deployment provider for current status

Status Response Types

The tool returns information about:

1. Build Status: Whether the application build has succeeded or failed
2. Claim Status: Whether the deployment has been claimed by the user
3. Error Information: Build errors if the deployment failed

Sources: Windsurf/Tools Wave 11.txt27-33

Complete Deployment Workflow

Sequential Execution Pattern

Sources: Windsurf/Tools Wave 11.txt195-201 Windsurf/Tools Wave 11.txt88-100 Windsurf/Tools Wave 11.txt27-33

Deployment Configuration Management

Project Identity Preservation

The deployment pipeline maintains project identity through the ProjectId field, which serves as a persistent identifier for deployed sites:

New Deployment Pattern:

Re-deployment Pattern:

Site Rename Pattern:

Sources: Windsurf/Tools Wave 11.txt92-97

Configuration File Lookup

The read_deployment_config tool searches for deployment configuration in the project directory. When re-deploying, Cascade must:

1. Extract the exact ProjectId value from the configuration file
2. Use this ProjectId in deploy_web_app to maintain site continuity
3. Leave Subdomain empty to preserve existing URL

Sources: Windsurf/Tools Wave 11.txt195-201

Build and Deployment Constraints

Source-Only Deployment

The deployment pipeline accepts unbundled source files and handles the build process remotely:

• No Pre-build Required: Applications do not need to be built locally before deployment
• Source Files Sufficient: Only source code and configuration files are uploaded
• Remote Build Execution: The deployment provider executes framework-specific build commands
• Framework Detection: Build configuration is determined by the Framework parameter

File System Requirements

All deployment tools require absolute paths:

Sources: Windsurf/Tools Wave 11.txt94 Windsurf/Tools Wave 11.txt198

Error Handling and Recovery

Configuration Validation Failures

When read_deployment_config identifies missing files:

1. Cascade receives a list of required files that don't exist
2. Cascade creates the missing files with appropriate content
3. Cascade re-invokes read_deployment_config to confirm readiness
4. Only after validation passes does deployment proceed

Deployment Failures

When check_deploy_status reports build failures:

1. The tool returns error information from the build process
2. Cascade can analyze the error and fix source code issues
3. A new deploy_web_app invocation is required to retry
4. The same ProjectId should be used to update the existing site

Status Monitoring Pattern

The check_deploy_status tool should be polled periodically:

Sources: Windsurf/Tools Wave 11.txt27-33

Tool Invocation Guidelines

Mandatory Execution Order

The deployment tools must be invoked in strict sequence:

1. Always First: read_deployment_config - Validates project readiness
2. Only After Validation: deploy_web_app - Executes deployment
3. Only After Deployment: check_deploy_status - Monitors progress

User Approval Requirements

The deploy_web_app tool typically requires user approval before execution due to its side effects:

• Creates external resources (hosted sites)
• Consumes deployment provider resources
• May incur hosting costs
• Cannot be marked as SafeToAutoRun

The check_deploy_status tool should not run unless explicitly requested by the user, as noted in the tool description.

Sources: Windsurf/Tools Wave 11.txt27-28

Integration with Other Windsurf Tools

Browser Preview Integration

During local development before deployment:

• Use browser_preview tool to test the application locally (see Browser Preview and Page Interaction)
• Verify functionality with capture_browser_console_logs and capture_browser_screenshot
• Only deploy after local validation

Command Execution Integration

Deployment may require preparatory commands:

• Use run_command to install dependencies before deployment (see Command Execution and Background Processes)
• Execute build tests locally with run_command
• Check for configuration issues with terminal commands

Memory Persistence

Deployment information can be stored in Cascade's memory system:

• Use create_memory to save ProjectId values (see Memory and Context Management)
• Store deployment URLs and configuration details
• Tag memories with deployment and project-specific tags

Sources: Windsurf/Tools Wave 11.txt1-9 Windsurf/Tools Wave 11.txt262-283 Windsurf/Tools Wave 11.txt57-86