@sembix/cli 1.5.0 → 1.5.1

package/USAGE-EXAMPLES.md

@@ -869,4 +869,469 @@ sembix workflow run show --workflow-id wf_456 --run-id run_xyz789 --watch
 
 ---
 
-**Last Updated**: November 2024
+## Workflow Input Formats & Validation
+
+### Understanding Workflow Inputs
+
+When starting a workflow, you can provide inputs in three formats. The CLI validates all inputs before starting the workflow.
+
+### Format 1: Name-Based (Recommended)
+
+Use input variable names from the workflow template:
+
+```bash
+sembix workflow start \
+  --project-id proj_abc123 \
+  --workflow-id wf_deploy \
+  --inputs '{"environment": "production", "version": "1.2.3", "dryRun": false}'
+```
+
+**Advantages:**
+- Human-readable and self-documenting
+- CLI auto-resolves names to IDs
+- Validates required fields and data types
+- Fills optional fields with empty strings automatically
+
+**Example with required and optional fields:**
+```bash
+# Workflow has 4 inputs:
+# - environment (string, required)
+# - version (string, required)
+# - dryRun (boolean, optional)
+# - notes (string, optional)
+
+# Only provide required fields:
+sembix workflow start --project-id proj_123 --workflow-id wf_456 \
+  --inputs '{"environment": "production", "version": "1.2.3"}'
+
+# CLI automatically adds optional fields as empty strings:
+# Final payload sent to API:
+# {
+#   "environment": "production",
+#   "version": "1.2.3",
+#   "dryRun": "",
+#   "notes": ""
+# }
+```
+
+---
+
+### Format 2: ID-Based
+
+Use input variable IDs directly:
+
+```bash
+sembix workflow start \
+  --project-id proj_abc123 \
+  --workflow-id wf_deploy \
+  --inputs '[
+    {"id": "var_env_123", "instruction": "production"},
+    {"id": "var_ver_456", "instruction": "1.2.3"}
+  ]'
+```
+
+**When to use:**
+- You know the exact input variable IDs
+- Building dynamic inputs programmatically
+- Working with complex workflows
+
+---
+
+### Format 3: File-Based
+
+Store inputs in a JSON file:
+
+```bash
+# inputs.json (name-based)
+{
+  "environment": "production",
+  "version": "1.2.3",
+  "dryRun": false,
+  "notes": "Deploying hotfix"
+}
+
+# Or inputs.json (ID-based)
+[
+  {"id": "var_env_123", "instruction": "production"},
+  {"id": "var_ver_456", "instruction": "1.2.3"}
+]
+
+# Use with @ prefix:
+sembix workflow start \
+  --project-id proj_abc123 \
+  --workflow-id wf_deploy \
+  --inputs @inputs.json
+```
+
+**Advantages:**
+- Reusable input configurations
+- Version control your inputs
+- Easier to manage complex inputs
+- Good for CI/CD pipelines
+
+---
+
+### Input Validation Rules
+
+The CLI validates all inputs before starting workflows:
+
+#### 1. Required Fields Validation
+
+```bash
+# ✗ Missing required field
+$ sembix workflow start --project-id proj_123 --workflow-id wf_456 \
+    --inputs '{"version": "1.2.3"}'
+
+Error: Input validation failed:
+  - Required input "environment" is missing or empty
+
+# ✗ Empty required field
+$ sembix workflow start --project-id proj_123 --workflow-id wf_456 \
+    --inputs '{"environment": "", "version": "1.2.3"}'
+
+Error: Input validation failed:
+  - Required input "environment" is missing or empty
+
+# ✓ All required fields provided
+$ sembix workflow start --project-id proj_123 --workflow-id wf_456 \
+    --inputs '{"environment": "prod", "version": "1.2.3"}'
+```
+
+---
+
+#### 2. Boolean Field Validation
+
+Boolean fields must be `true`, `false`, or their string equivalents:
+
+```bash
+# ✓ Valid boolean values
+--inputs '{"dryRun": true}'
+--inputs '{"dryRun": false}'
+--inputs '{"dryRun": "true"}'
+--inputs '{"dryRun": "false"}'
+
+# ✗ Invalid boolean values
+--inputs '{"dryRun": "yes"}'
+# Error: Input "dryRun" must be true or false (got: yes)
+
+--inputs '{"dryRun": 1}'
+# Error: Input "dryRun" must be true or false (got: 1)
+
+--inputs '{"dryRun": "True"}'  # Case sensitive!
+# Error: Input "dryRun" must be true or false (got: True)
+```
+
+**Note:** The CLI converts boolean values to strings before sending to the API:
+- `true` → `"true"`
+- `false` → `"false"`
+
+---
+
+#### 3. Optional Field Handling
+
+Optional fields are **always included** in the final payload, even if not provided:
+
+```bash
+# Example: Workflow with 2 required + 2 optional fields
+
+# Input provided:
+--inputs '{"environment": "prod", "version": "1.2.3"}'
+
+# CLI validates and adds optional fields:
+{
+  "environment": "prod",
+  "version": "1.2.3",
+  "dryRun": "",      // Optional field added as empty string
+  "notes": ""        // Optional field added as empty string
+}
+```
+
+This ensures the API always receives a complete set of inputs.
+
+---
+
+### Real-World Examples
+
+#### Example 1: Simple Deployment
+
+```bash
+# Workflow: Deploy Application
+# Inputs:
+#   - environment (string, required)
+#   - version (string, required)
+#   - rollbackOnFailure (boolean, optional)
+
+sembix workflow start \
+  --project-id proj_abc123 \
+  --workflow-id wf_deploy \
+  --inputs '{
+    "environment": "production",
+    "version": "v2.3.1",
+    "rollbackOnFailure": true
+  }'
+```
+
+---
+
+#### Example 2: Database Migration
+
+```bash
+# Workflow: Run Database Migration
+# Inputs:
+#   - database (string, required)
+#   - migrationVersion (string, required)
+#   - dryRun (boolean, required)
+#   - backupFirst (boolean, optional)
+#   - notificationEmail (string, optional)
+
+# Interactive mode (recommended for one-off operations):
+sembix workflow start --project-id proj_123 --workflow-id wf_migrate
+
+# Non-interactive with file:
+cat > migration-inputs.json <<EOF
+{
+  "database": "production",
+  "migrationVersion": "20240115_001",
+  "dryRun": false,
+  "backupFirst": true,
+  "notificationEmail": "ops@company.com"
+}
+EOF
+
+sembix workflow start \
+  --project-id proj_123 \
+  --workflow-id wf_migrate \
+  --inputs @migration-inputs.json
+```
+
+---
+
+#### Example 3: CI/CD Pipeline
+
+```bash
+#!/bin/bash
+# deploy.sh - Automated deployment script
+
+PROJECT_ID="proj_abc123"
+WORKFLOW_ID="wf_deploy"
+VERSION="${GITHUB_SHA:0:7}"
+ENVIRONMENT="${DEPLOY_ENV:-staging}"
+
+# Build inputs JSON
+INPUTS=$(cat <<EOF
+{
+  "environment": "${ENVIRONMENT}",
+  "version": "${VERSION}",
+  "dryRun": false,
+  "gitCommit": "${GITHUB_SHA}",
+  "triggeredBy": "${GITHUB_ACTOR}"
+}
+EOF
+)
+
+# Start workflow
+sembix workflow start \
+  --project-id "${PROJECT_ID}" \
+  --workflow-id "${WORKFLOW_ID}" \
+  --inputs "${INPUTS}" \
+  --no-interactive
+```
+
+---
+
+#### Example 4: Handling Validation Errors
+
+```bash
+# Script with error handling
+#!/bin/bash
+
+PROJECT_ID="proj_abc123"
+WORKFLOW_ID="wf_456"
+
+# Attempt to start workflow
+if ! sembix workflow start \
+  --project-id "${PROJECT_ID}" \
+  --workflow-id "${WORKFLOW_ID}" \
+  --inputs '{"environment": "prod"}' 2>&1; then
+
+  echo "❌ Workflow start failed - checking for validation errors..."
+
+  # Try again with all required fields
+  echo "Retrying with complete inputs..."
+  sembix workflow start \
+    --project-id "${PROJECT_ID}" \
+    --workflow-id "${WORKFLOW_ID}" \
+    --inputs '{
+      "environment": "prod",
+      "version": "1.2.3",
+      "dryRun": false
+    }'
+fi
+```
+
+---
+
+### Interactive vs Non-Interactive Mode
+
+#### Interactive Mode (Default)
+
+When `--inputs` is not provided, CLI prompts for each input:
+
+```bash
+$ sembix workflow start --project-id proj_123 --workflow-id wf_456
+
+This workflow requires 4 input(s):
+
+environment
+  The deployment environment
+
+✔ environment (required): production
+
+version
+  The version to deploy
+
+✔ version (required): 1.2.3
+
+dryRun
+  Run in dry-run mode?
+
+✔ dryRun (optional): [y/n] n
+
+notes
+  Deployment notes
+
+✔ notes (optional):
+
+✓ Workflow started successfully!
+```
+
+**Interactive mode benefits:**
+- See all input descriptions
+- Validation happens as you type
+- Guided experience for complex workflows
+- Required vs optional clearly marked
+
+---
+
+#### Non-Interactive Mode
+
+Use `--no-interactive` to skip prompts (requires `--inputs`):
+
+```bash
+sembix workflow start \
+  --project-id proj_123 \
+  --workflow-id wf_456 \
+  --inputs '{"environment": "prod", "version": "1.2.3"}' \
+  --no-interactive
+```
+
+**Non-interactive benefits:**
+- Suitable for automation/CI/CD
+- Fast execution
+- Predictable behavior
+
+---
+
+### Best Practices
+
+#### ✅ DO
+
+- **Use name-based format** for readability
+  ```bash
+  --inputs '{"environment": "prod", "version": "1.2.3"}'
+  ```
+
+- **Store complex inputs in files**
+  ```bash
+  --inputs @production-config.json
+  ```
+
+- **Validate locally first** using interactive mode
+  ```bash
+  sembix workflow start  # Test interactively first
+  ```
+
+- **Handle validation errors** in scripts
+  ```bash
+  if ! sembix workflow start --inputs '{...}'; then
+    echo "Validation failed"
+    exit 1
+  fi
+  ```
+
+- **Use boolean true/false** (not strings)
+  ```bash
+  --inputs '{"dryRun": true}'  # ✓ Good
+  --inputs '{"dryRun": false}' # ✓ Good
+  ```
+
+---
+
+#### ❌ DON'T
+
+- **Don't use invalid boolean strings**
+  ```bash
+  --inputs '{"enabled": "yes"}'  # ✗ Error
+  --inputs '{"enabled": "True"}' # ✗ Case sensitive
+  ```
+
+- **Don't leave required fields empty**
+  ```bash
+  --inputs '{"environment": ""}'  # ✗ Validation error
+  ```
+
+- **Don't assume optional fields can be omitted from payload**
+  - CLI handles this automatically - optional fields are added as `""`
+
+- **Don't hard-code sensitive values**
+  ```bash
+  # ✗ Bad
+  --inputs '{"apiKey": "secret123"}'
+
+  # ✓ Good - use environment variables
+  --inputs "{\"apiKey\": \"${API_KEY}\"}"
+  ```
+
+---
+
+### Troubleshooting
+
+#### "Input validation failed" errors
+
+```bash
+Error: Input validation failed:
+  - Required input "environment" is missing or empty
+  - Required input "version" is missing or empty
+```
+
+**Solution:** Provide all required fields with non-empty values.
+
+---
+
+#### "must be true or false" errors
+
+```bash
+Error: Input validation failed:
+  - Input "dryRun" must be true or false (got: yes)
+```
+
+**Solution:** Use boolean `true`/`false` or strings `"true"`/`"false"`.
+
+---
+
+#### "Input variable name not found" errors
+
+```bash
+Error: Input variable name "environemnt" not found in workflow template.
+
+Available input variables:
+  - environment
+  - version
+  - dryRun
+```
+
+**Solution:** Fix the typo in the input name (check spelling and capitalization).
+
+---
+
+**Last Updated**: December 2024

package/dist/commands/workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../src/commands/workflow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../src/commands/workflow.ts"],"names":[],"mappings":"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"}

package/dist/commands/workflow.js

@@ -216,10 +216,50 @@ export async function workflowStartCommand(options) {
             else {
                 inputsJson = options.inputs;
             }
-            // Auto-detect format and parse
+            // Detect if name-based format (needs template)
+            let template;
+            try {
+                const parsed = JSON.parse(inputsJson);
+                // Check if simple object (name-based)
+                const isNameBased = !Array.isArray(parsed) &&
+                    typeof parsed === 'object' &&
+                    parsed !== null &&
+                    !('initialInstructions' in parsed) &&
+                    !('workspaceMetadata' in parsed);
+                if (isNameBased) {
+                    // Fetch template for name resolution
+                    const spinner = ui.spinner('Fetching workflow template for input name resolution...');
+                    spinner.start();
+                    const workflowTemplate = await apiClient.getWorkflowTemplateForWorkflow(projectId, workflowId);
+                    spinner.stop();
+                    if (!workflowTemplate) {
+                        throw new Error('Cannot use name-based inputs: workflow has no template.\n\n' +
+                            'Use ID-based format instead:\n' +
+                            '  --inputs \'[{"id": "var_123", "instruction": "value"}]\'\n\n' +
+                            'To find available input IDs, run:\n' +
+                            '  sembix workflow template show --project-id ' + projectId + ' --workflow-id ' + workflowId);
+                    }
+                    // Extract template instructions (try Start step first, then root level)
+                    const startStep = workflowTemplate.steps?.find(step => step.name === 'Start');
+                    template = startStep?.initialInstructions ||
+                        workflowTemplate.inputVariables ||
+                        workflowTemplate.initialInstructions;
+                }
+            }
+            catch (parseError) {
+                // Re-throw non-JSON parsing errors (like template fetch failures)
+                if (parseError instanceof SyntaxError) {
+                    // JSON parsing error - let parseWorkflowInputs handle it
+                }
+                else {
+                    // Other errors (e.g., template fetch failures) should be re-thrown
+                    throw parseError;
+                }
+            }
+            // Parse inputs with template if needed
             try {
                 const { parseWorkflowInputs } = await import('../utils/input-parser.js');
-                const parsedConfig = parseWorkflowInputs(inputsJson);
+                const parsedConfig = parseWorkflowInputs({ inputsJson, template, validate: true });
                 Object.assign(startConfiguration, parsedConfig);
             }
             catch (error) {