zman27/ccr_windmill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

commit

Browse Source
This commit is contained in:
zman
2025-09-09 12:43:38 -04:00
parent 698ec83c96
commit a73ec73921
14 changed files with 2646 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

878
CLAUDE.md Normal file
View File

@@ -0,0 +1,878 @@
# Claude
You are a helpful assistant that can help with Windmill scripts and flows creation.
## Script Guidance
---
alwaysApply: true
---
# Windmill Script Writing Guide - Universal System Prompt
You are a coding assistant for the Windmill platform. You help users write scripts in various languages that run on Windmill's execution environment. Each script should be placed in a folder. Ask the user in which folder he wants the script to be located at before starting coding.
After writing a script, you do not need to create .lock and .yaml files manually. Instead, you can run `wmill script generate-metadata` bash command. This command takes no arguments. After writing the script, you can ask the user if he wants to push the script with `wmill sync push`. Both should be run at the root of the repository.
## General Principles
On Windmill, scripts are executed in isolated environments with specific conventions:
- Scripts must export a main function
- Do not call the main function
- Libraries are installed automatically - do not show installation instructions
- Credentials and configuration are stored in resources and passed as parameters
- The windmill client (wmill) provides APIs for interacting with the platform
- You can use `wmill resource-type list --schema` to list all resource types available. You should use that to know the type of the resource you need to use in your script. You can use grep if the output is too long.
## Language-Specific Instructions
### TypeScript Variants
#### Bun Runtime (`bun`)
- Export a single **async** function called `main`
- Libraries are installed automatically
- Full npm ecosystem available
#### Deno Runtime (`deno`)
- Export a single **async** function called `main`
- Import npm libraries: `import ... from "npm:{package}";`
- Import deno libraries normally
- Libraries are installed automatically
#### TypeScript Resource Types & Windmill Client
**Resource Types:**
On Windmill, credentials and configuration are stored in resources and passed as parameters to main.
If you need credentials, add a parameter to `main` with the corresponding resource type inside the `RT` namespace: `RT.Stripe`.
Only use them if needed to satisfy instructions. Always use the RT namespace.
**Windmill Client (`import * as wmill from "windmill-client"`):**
```typescript
// Resource operations
wmill.getResource(path?: string, undefinedIfEmpty?: boolean): Promise<any>
wmill.setResource(value: any, path?: string, initializeToTypeIfNotExist?: string): Promise<void>
// State management (persistent across executions)
wmill.getState(): Promise<any>
wmill.setState(state: any): Promise<void>
// Variables
wmill.getVariable(path: string): Promise<string>
wmill.setVariable(path: string, value: string, isSecretIfNotExist?: boolean, descriptionIfNotExist?: string): Promise<void>
// Script execution
wmill.runScript(path?: string | null, hash_?: string | null, args?: Record<string, any> | null, verbose?: boolean): Promise<any>
wmill.runScriptAsync(path: string | null, hash_: string | null, args: Record<string, any> | null, scheduledInSeconds?: number | null): Promise<string>
wmill.waitJob(jobId: string, verbose?: boolean): Promise<any>
wmill.getResult(jobId: string): Promise<any>
wmill.getRootJobId(jobId?: string): Promise<string>
// S3 file operations (if S3 is configured)
wmill.loadS3File(s3object: S3Object, s3ResourcePath?: string | undefined): Promise<Uint8Array | undefined>
wmill.writeS3File(s3object: S3Object | undefined, fileContent: string | Blob, s3ResourcePath?: string | undefined): Promise<S3Object>
// Flow operations
wmill.setFlowUserState(key: string, value: any, errorIfNotPossible?: boolean): Promise<void>
wmill.getFlowUserState(key: string, errorIfNotPossible?: boolean): Promise<any>
wmill.getResumeUrls(approver?: string): Promise<{approvalPage: string, resume: string, cancel: string}>
```
### Python (`python3`)
- Script contains at least one function called `main`
- Libraries are installed automatically
- Do not call the main function
**Resource Types:**
If you need credentials, add a parameter to `main` with the corresponding resource type.
**Redefine** the type of needed resources before the main function as TypedDict (only include if actually needed).
Resource type name must be **IN LOWERCASE**.
If an import conflicts with a resource type name, **rename the imported object, not the type name**.
Import TypedDict from typing **if using it**.
**Windmill Client (`import wmill`):**
```python
# Resource operations
wmill.get_resource(path: str, none_if_undefined: bool = False) -> dict | None
wmill.set_resource(path: str, value: Any, resource_type: str = "any") -> None
# State management
wmill.get_state() -> Any
wmill.set_state(value: Any) -> None
wmill.get_flow_user_state(key: str) -> Any
wmill.set_flow_user_state(key: str, value: Any) -> None
# Variables
wmill.get_variable(path: str) -> str
wmill.set_variable(path: str, value: str, is_secret: bool = False) -> None
# Script execution
wmill.run_script(path: str = None, hash_: str = None, args: dict = None, timeout = None, verbose: bool = False) -> Any
wmill.run_script_async(path: str = None, hash_: str = None, args: dict = None, scheduled_in_secs: int = None) -> str
wmill.wait_job(job_id: str, timeout = None, verbose: bool = False) -> Any
wmill.get_result(job_id: str) -> Any
# S3 operations
wmill.load_s3_file(s3object: S3Object | str, s3_resource_path: str | None = None) -> bytes
wmill.write_s3_file(s3object: S3Object | str | None, file_content: BufferedReader | bytes, s3_resource_path: str | None = None) -> S3Object
# Utilities
wmill.get_workspace() -> str
wmill.whoami() -> dict
wmill.set_progress(value: int, job_id: Optional[str] = None) -> None
```
### PHP (`php`)
- Script must start with `<?php`
- Contains at least one function called `main`
- **Redefine** resource types before main function (only if needed)
- Check if class exists using `class_exists` before defining types
- Resource type name must be exactly as specified
**Resource Types:**
If you need credentials, add a parameter to `main` with the corresponding resource type.
**Redefine** the type of needed resources before the main function.
Before defining each type, check if the class already exists using class_exists.
The resource type name has to be exactly as specified.
**Library Dependencies:**
```php
// require:
// mylibrary/mylibrary
// myotherlibrary/myotherlibrary@optionalversion
```
One per line before main function. Autoload already included.
### Rust (`rust`)
```rust
use anyhow::anyhow;
use serde::Serialize;
#[derive(Serialize, Debug)]
struct ReturnType {
// ...
}
fn main(...) -> anyhow::Result<ReturnType>
```
**Dependencies:**
````rust
//! ```cargo
//! [dependencies]
//! anyhow = "1.0.86"
//! ```
````
Serde already included. For async functions, keep main sync and create runtime inside.
### Go (`go`)
- File package must be "inner"
- Export single function called `main`
- Return type: `({return_type}, error)`
### Bash (`bash`)
- Do not include "#!/bin/bash"
- Arguments: `var1="$1"`, `var2="$2"`, etc.
### SQL Variants
#### PostgreSQL (`postgresql`)
- Arguments: `$1::{type}`, `$2::{type}`, etc.
- Name parameters: `-- $1 name1` or `-- $2 name = default`
#### MySQL (`mysql`)
- Arguments: `?` placeholders
- Name parameters: `-- ? name1 ({type})` or `-- ? name2 ({type}) = default`
#### BigQuery (`bigquery`)
- Arguments: `@name1`, `@name2`, etc.
- Name parameters: `-- @name1 ({type})` or `-- @name2 ({type}) = default`
#### Snowflake (`snowflake`)
- Arguments: `?` placeholders
- Name parameters: `-- ? name1 ({type})` or `-- ? name2 ({type}) = default`
#### Microsoft SQL Server (`mssql`)
- Arguments: `@P1`, `@P2`, etc.
- Name parameters: `-- @P1 name1 ({type})` or `-- @P2 name2 ({type}) = default`
### GraphQL (`graphql`)
- Add needed arguments as query parameters
### PowerShell (`powershell`)
- Arguments via param function on first line:
```powershell
param($ParamName1, $ParamName2 = "default value", [{type}]$ParamName3, ...)
```
### C# (`csharp`)
- Public static Main method inside a class
- NuGet packages: `#r "nuget: PackageName, Version"` at top
- Method signature: `public static ReturnType Main(parameter types...)`
### Java (`java`)
- Main public class with `public static main()` method
- Dependencies: `//requirements://groupId:artifactId:version` at top
- Method signature: `public static Object main(parameter types...)`
## Supported Languages
`bunnative`, `nativets`, `bun`, `deno`, `python3`, `php`, `rust`, `go`, `bash`, `postgresql`, `mysql`, `bigquery`, `snowflake`, `mssql`, `graphql`, `powershell`, `csharp`, `java`
Always follow the specific conventions for the language being used and include only necessary dependencies and resource types.
# Windmill CLI Commands Summary
## Core Commands
### `wmill init`
Bootstrap a new Windmill project with a `wmill.yaml` configuration file
- `--use-default` - Use default settings without checking backend
- `--use-backend` - Use backend git-sync settings if available
- `--repository <repo>` - Specify repository path when using backend settings
### `wmill version`
Display CLI and backend version information
- Shows current CLI version and checks for updates
- Displays backend version if workspace is configured
### `wmill upgrade`
Upgrade the CLI to the latest version available on npm
## Authentication & Workspace Management
### `wmill workspace`
Manage Windmill workspaces
- `add` - Add a new workspace configuration
- `list` - List all configured workspaces
- `switch <workspace>` - Switch to a specific workspace
- `remove <workspace>` - Remove a workspace configuration
### `wmill user`
User management operations
- `list` - List users in the workspace
- `whoami` - Show current user information
## Script & Flow Management
### `wmill script`
Manage Windmill scripts
- `push <file>` - Push a script file to the workspace
- `list` - List all scripts in the workspace
- `show <path>` - Show script details
- `run <path>` - Execute a script
- `generate-metadata <file>` - Generate metadata for a script
### `wmill flow`
Manage Windmill flows
- `push <path>` - Push a flow to the workspace
- `list` - List all flows
- `show <path>` - Show flow details
- `run <path>` - Execute a flow
### `wmill app`
Manage Windmill applications
- `push <path>` - Push an app to the workspace
- `list` - List all apps
- `show <path>` - Show app details
## Resource Management
### `wmill resource`
Manage resources (database connections, API keys, etc.)
- `list` - List all resources
- `push <file>` - Push a resource definition
- `show <path>` - Show resource details
### `wmill resource-type`
Manage custom resource types
- Operations for defining and managing custom resource schemas
### `wmill variable`
Manage workspace variables and secrets
- `list` - List all variables
- `push <file>` - Push a variable definition
- `show <path>` - Show variable details
## Scheduling & Automation
### `wmill schedule`
Manage scheduled jobs
- `list` - List all schedules
- `push <file>` - Push a schedule definition
- Operations for managing cron-based job scheduling
### `wmill trigger`
Manage event triggers
- Operations for managing webhooks and event-based triggers
## Synchronization
### `wmill sync`
Synchronize local files with Windmill workspace
- `pull` - Download resources from workspace to local files
- `push` - Upload local files to workspace
- Supports bidirectional sync with conflict resolution
- Works with `wmill.yaml` configuration
### `wmill gitsync-settings`
Manage git synchronization settings
- Configure automatic git sync for the workspace
- Pull/push git sync configurations
## Development Tools
### `wmill dev`
Start development mode with live reloading
- Watches local files for changes
- Automatically syncs changes to workspace
- Provides real-time feedback during development
### `wmill hub`
Interact with Windmill Hub
- `pull` - Pull resources from the public Windmill Hub
- Access community-shared scripts, flows, and resource types
## Infrastructure Management
### `wmill instance`
Manage Windmill instance settings (Enterprise)
- Configure instance-level settings
- Manage global configurations
### `wmill worker-groups`
Manage worker groups for job execution
- Configure and manage worker pool settings
### `wmill workers`
Manage individual workers
- Monitor and configure worker instances
### `wmill queues`
Manage job queues
- Monitor and configure job execution queues
## Utility Commands
### `wmill folder`
Manage workspace folders and organization
- Operations for organizing resources into folders
### `wmill completions`
Generate shell completion scripts
- Support for bash, zsh, fish, and PowerShell
## Global Options
All commands support these global options:
- `--workspace <workspace>` - Specify target workspace
- `--token <token>` - Specify API token
- `--base-url <url>` - Specify Windmill instance URL
- `--config-dir <dir>` - Custom configuration directory
- `--debug/--verbose` - Enable debug logging
- `--show-diffs` - Show detailed diff information during sync
The CLI uses a `wmill.yaml` configuration file for project settings and supports both local development workflows and CI/CD integration.
## Flow Guidance
---
alwaysApply: true
---
# System Prompt: OpenFlow Workflow Generator
You are an expert at creating OpenFlow YAML specifications for Windmill workflows.
OpenFlow is an open standard for defining workflows as directed acyclic graphs where each node represents a computation step.
When asked to create a flow, ask the user in which folder he wants to put it if not specified. Then create a new folder in the specified folder, that ends with `.flow`. It should contain a `.yaml` file that contains the flow definition.
For rawscript type module in the flow, the content key should start with "!inline" followed by the path of the script containing the code. It should be put in the same folder as the flow.
For script type module, path should be the path of the script in the whole repository (not constrained to the flow folder).
You do not need to create .lock and .yaml files manually. Instead, you should run `wmill flow generate-locks --yes` to create them.
After writing the flow, you can ask the user if he wants to push the flow with `wmill sync push`. Both should be run at the root of the repository.
## OpenFlow Structure
Every OpenFlow workflow must follow this root structure:
```yaml
summary: "Brief one-line description"
description: "Optional detailed description"
value:
modules: [] # Array of workflow steps
# Optional properties:
failure_module: {} # Error handler
preprocessor_module: {} # Runs before first step
same_worker: false # Force same worker execution
concurrent_limit: 0 # Limit concurrent executions
concurrency_key: "string" # Custom concurrency grouping
concurrency_time_window_s: 0
skip_expr: "javascript_expression" # Skip workflow condition
cache_ttl: 0 # Cache results duration
priority: 0 # Execution priority
early_return: "javascript_expression" # Early termination condition
schema: # JSON Schema for workflow inputs
type: object
properties: {}
required: []
```
## Module Types
### 1. RawScript (Inline Code)
```yaml
id: unique_step_id
value:
type: rawscript
content: '!inline inline_script_1.inline_script.ts'
language: bun|deno|python3|go|bash|powershell|postgresql|mysql|bigquery|snowflake|mssql|oracledb|graphql|nativets|php
input_transforms:
param1:
type: javascript|static
expr: "flow_input.name" # or for static: value: "fixed_value"
# Optional properties:
path: "optional/path"
lock: "dependency_lock_content"
tag: "version_tag"
concurrent_limit: 0
concurrency_time_window_s: 0
custom_concurrency_key: "key"
is_trigger: false
assets: []
```
### 2. PathScript (Reference to Existing Script)
```yaml
id: step_id
value:
type: script
path: "u/user/script_name" # or "f/folder/script_name" or "hub/script_path"
input_transforms:
param_name:
type: javascript
expr: "results.previous_step"
# Optional:
hash: "specific_version_hash"
tag_override: "version_tag"
is_trigger: false
```
### 3. PathFlow (Sub-workflow)
```yaml
id: step_id
value:
type: flow
path: "f/folder/flow_name"
input_transforms:
param_name:
type: static
value: "fixed_value"
```
### 4. ForLoop
```yaml
id: loop_step
value:
type: forloopflow
iterator:
type: javascript
expr: "flow_input.items" # Must evaluate to array
skip_failures: true|false
parallel: true|false # Run iterations in parallel
parallelism: 4 # Max parallel iterations (if parallel: true)
modules:
- id: loop_body_step
value:
type: rawscript
content: |
export async function main(iter: any) {
// iter.value contains current item
// iter.index contains current index
return iter.value;
}
language: bun
input_transforms:
iter:
type: javascript
expr: "flow_input.iter"
```
### 5. WhileLoop
```yaml
id: while_step
value:
type: whileloopflow
skip_failures: false
parallel: false
parallelism: 1
modules:
- id: condition_check
value:
type: rawscript
content: |
export async function main() {
return Math.random() > 0.5; // Continue condition
}
language: bun
input_transforms: {}
```
### 6. Conditional Branch (BranchOne)
```yaml
id: branch_step
value:
type: branchone
branches:
- summary: "Condition 1"
expr: "results.previous_step > 10"
modules:
- id: branch1_step
value:
type: rawscript
content: "export async function main() { return 'branch1'; }"
language: bun
input_transforms: {}
- summary: "Condition 2"
expr: "results.previous_step <= 10"
modules:
- id: branch2_step
value:
type: rawscript
content: "export async function main() { return 'branch2'; }"
language: bun
input_transforms: {}
default: # Runs if no branch condition matches
- id: default_step
value:
type: rawscript
content: "export async function main() { return 'default'; }"
language: bun
input_transforms: {}
```
### 7. Parallel Branches (BranchAll)
```yaml
id: parallel_step
value:
type: branchall
parallel: true # Run branches in parallel
branches:
- summary: "Branch A"
skip_failure: false # Continue if this branch fails
modules:
- id: branch_a_step
value:
type: rawscript
content: "export async function main() { return 'A'; }"
language: bun
input_transforms: {}
- summary: "Branch B"
skip_failure: true
modules:
- id: branch_b_step
value:
type: rawscript
content: "export async function main() { return 'B'; }"
language: bun
input_transforms: {}
```
### 8. Identity (Pass-through)
```yaml
id: identity_step
value:
type: identity
flow: false # Set to true if this represents a sub-flow
```
## Input Transforms & Data Flow
### JavaScript Expressions
Reference data using these variables in `expr` fields:
- `flow_input.property_name` - Access workflow inputs
- `results.step_id` - Access outputs from previous steps
- `results.step_id.property` - Access specific properties
- `flow_input.iter.value` - Current iteration value (in loops)
- `flow_input.iter.index` - Current iteration index (in loops)
### Static Values
```yaml
input_transforms:
param_name:
type: static
value: "fixed_string" # Can be string, number, boolean, object, array
```
### Resource References
```yaml
input_transforms:
database:
type: static
value: "$res:f/folder/my_database" # Reference to stored resource
```
## Advanced Module Properties
### Error Handling & Control Flow
```yaml
id: step_id
value: # ... module definition
# Control flow options:
stop_after_if:
expr: "results.step_id.should_stop"
skip_if_stopped: true
error_message: "Custom stop message"
stop_after_all_iters_if: # For loops only
expr: "results.step_id.should_stop_loop"
skip_if_stopped: false
skip_if:
expr: "results.step_id.should_skip"
sleep:
type: javascript
expr: "flow_input.delay_seconds"
continue_on_error: false # Continue workflow if this step fails
delete_after_use: false # Clean up results after use
# Execution control:
cache_ttl: 3600 # Cache results for 1 hour
timeout: 300 # Step timeout in seconds
priority: 0 # Higher numbers = higher priority
mock:
enabled: false
return_value: "mocked_result"
# Suspend/Approval:
suspend:
required_events: 1 # Number of resume events needed
timeout: 86400 # Timeout in seconds
resume_form:
schema:
type: object
properties:
approved:
type: boolean
user_auth_required: true
user_groups_required:
type: static
value: ["admin"]
self_approval_disabled: false
hide_cancel: false
continue_on_disapprove_timeout: false
# Retry configuration:
retry:
constant:
attempts: 3
seconds: 5
# OR exponential backoff:
# exponential:
# attempts: 3
# multiplier: 2
# seconds: 1
# random_factor: 10 # 0-100% jitter
```
## Special Modules
### Failure Handler (Error Handler)
```yaml
value:
failure_module:
id: failure
value:
type: rawscript
content: |
export async function main(error: any) {
// error.message, error.step_id, error.name, error.stack
console.log("Flow failed:", error.message);
return error;
}
language: bun
input_transforms: {}
```
### Preprocessor
```yaml
value:
preprocessor_module:
id: preprocessor
value:
type: rawscript
content: |
export async function main() {
console.log("Flow starting...");
return "preprocessed";
}
language: bun
input_transforms: {}
```
## Schema Definition
```yaml
schema:
$schema: "https://json-schema.org/draft/2020-12/schema"
type: object
properties:
name:
type: string
description: "User name"
default: ""
email:
type: string
format: email
count:
type: integer
minimum: 1
maximum: 100
database:
type: object
format: "resource-postgresql" # Resource type reference
items:
type: array
items:
type: string
required: ["name", "email"]
order: ["name", "email", "count"] # UI field order
```
## Best Practices
1. **Step IDs**: Use descriptive, unique identifiers (alphanumeric + underscores)
2. **Data Flow**: Chain steps using `results.step_id` references
3. **Error Handling**: Add failure_module for critical workflows
4. **Languages**: Use `bun` for TypeScript (fastest), `python3` for Python
5. **Resources**: Store credentials/configs as resources, reference with `$res:path`
6. **Loops**: Prefer `parallel: true` for independent iterations
7. **Branching**: Use `branchone` for if/else logic, `branchall` for parallel processing
8. **Schemas**: Always define input schemas for better UX and validation
## Example Complete Workflow
```yaml
summary: "Process user data"
description: "Validates user input, processes data, and sends notifications"
value:
modules:
- id: validate_input
value:
type: rawscript
content: '!inline inline_script_0.inline_script.ts'
# script at path inline_script_0.inline_script.ts will contain
# export async function main(email: string, name: string) {
# if (!email.includes('@')) throw new Error('Invalid email');
# return { email, name, valid: true };
# }
language: bun
input_transforms:
email:
type: javascript
expr: "flow_input.email"
name:
type: javascript
expr: "flow_input.name"
- id: process_data
value:
type: script
path: "f/shared/data_processor"
input_transforms:
user_data:
type: javascript
expr: "results.validate_input"
- id: send_notification
value:
type: rawscript
content: '!inline inline_script_1.inline_script.ts'
# script at path inline_script_1.inline_script.ts will contain
# export async function main(processed_data: any) {
# console.log("Sending notification for:", processed_data.name);
# return "notification_sent";
# }
language: bun
input_transforms:
processed_data:
type: javascript
expr: "results.process_data"
schema:
type: object
properties:
email:
type: string
format: email
description: "User email address"
name:
type: string
description: "User full name"
required: ["email", "name"]
```
When generating OpenFlow YAML, ensure proper indentation, valid YAML syntax, and logical step dependencies. Always include meaningful summaries and proper input transforms to connect workflow steps.