@cxtms/cx-schema 1.1.1 → 1.2.1

package/.claude/skills/cx-workflow/SKILL.md

@@ -9,9 +9,9 @@ You are a CargoXplorer workflow YAML builder. You generate schema-valid YAML for
 **IMPORTANT — use `cx-cli` for all workflow operations:**
 - **Scaffold**: `npx cx-cli create workflow <name> --template <template>` — generates a schema-valid YAML file. ALWAYS run this first, then read the generated file, then customize. Do NOT write YAML from scratch or copy templates manually.
 - **Validate**: `npx cx-cli <file.yaml>` — run after every change
-- **Schema lookup**: `npx cx-cli schema <task>` — e.g., `cx-cli schema graphql`, `cx-cli schema foreach`
+- **Schema lookup**: `npx cx-cli schema <task>` — e.g., `cx-cli schema graphql`, `cx-cli schema foreach`, `cx-cli schema action-event`. Schema names use kebab-case file names. Case-insensitive: `ActionEvent` resolves to `action-event`.
 - **Examples**: `npx cx-cli example <task>` — show example YAML for a task
-- **List schemas**: `npx cx-cli list --type workflow`
+- **List schemas**: `npx cx-cli list --type workflow` — shows all available task schemas in the Tasks section
 - **Feature folder**: `npx cx-cli create workflow <name> --template <template> --feature <feature-name>`
 
 ## Generation Workflow

package/.claude/skills/cx-workflow/ref-utilities.md

@@ -91,6 +91,27 @@ Performs HTTP requests to external APIs.
 
 Response available at `ActivityName?.CallApi?.result?`.
 
+**Action events**: When an HTTP request operates on a specific entity (e.g., sending parcel info for an order), enable `actionEvents` in the inputs so the system can track and notify about the request. Include `eventDataExt` with the entity ID to link the event to the entity.
+
+```yaml
+- task: "Utilities/HttpRequest@1"
+  name: CallCarrierApi
+  inputs:
+    actionEvents:
+      enabled: true
+      eventName: "carrier.sendParcelInfo"
+      eventDataExt:
+        orderId: "{{ inputs.orderId }}"
+    url: "{{ carrierConfig?.baseUrl? }}/api/shipments"
+    method: POST
+    contentType: "application/json"
+    body:
+      trackingNumber: "{{ Data?.GetOrder?.order?.trackingNumber? }}"
+  outputs:
+    - name: result
+      mapping: "response?.body?"
+```
+
 ## Map@1
 
 Extracts/reshapes data from variables into new variables.

package/dist/cli.js

@@ -72,8 +72,9 @@ ${chalk_1.default.bold.yellow('COMMANDS:')}
   ${chalk_1.default.green('validate')}        Validate YAML file(s) ${chalk_1.default.gray('(default command)')}
   ${chalk_1.default.green('report')}          Generate validation report for multiple files
   ${chalk_1.default.green('init')}            Initialize a new CX project with app.yaml, README.md, AGENTS.md
-  ${chalk_1.default.green('create')}          Create a new module or workflow from template
+  ${chalk_1.default.green('create')}          Create a new module, workflow, or task-schema from template
   ${chalk_1.default.green('extract')}         Extract a component (and its routes) to another module
+  ${chalk_1.default.green('sync-schemas')}    Regenerate all.json from task schema directory
   ${chalk_1.default.green('schema')}          Show JSON schema for a component or task
   ${chalk_1.default.green('example')}         Show example YAML for a component or task
   ${chalk_1.default.green('list')}            List available schemas (modules, workflows, tasks)
@@ -92,6 +93,7 @@ ${chalk_1.default.bold.yellow('OPTIONS:')}
   ${chalk_1.default.green('--template <name>')}       Template variant for create command (e.g., ${chalk_1.default.cyan('basic')})
   ${chalk_1.default.green('--feature <name>')}        Place file under features/<name>/ instead of root
   ${chalk_1.default.green('--options <json>')}        JSON field definitions for create (inline or file path)
+  ${chalk_1.default.green('--tasks <list>')}         Comma-separated task enums for create task-schema
   ${chalk_1.default.green('--to <file>')}            Target file for extract command
 
 ${chalk_1.default.bold.yellow('VALIDATION EXAMPLES:')}
@@ -132,6 +134,12 @@ ${chalk_1.default.bold.yellow('PROJECT COMMANDS:')}
   ${chalk_1.default.gray('# Create module with custom fields')}
   ${chalk_1.default.cyan(`${PROGRAM_NAME} create module my-config --template configuration --options '[{"name":"host","type":"text"},{"name":"port","type":"number"}]'`)}
 
+  ${chalk_1.default.gray('# Create a task schema with pre-populated task enums')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} create task-schema filetransfer --tasks "FileTransfer/Connect@1,FileTransfer/Disconnect@1"`)}
+
+  ${chalk_1.default.gray('# Sync all.json after manually adding/removing task schemas')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} sync-schemas`)}
+
   ${chalk_1.default.gray('# Extract a component to a new module')}
   ${chalk_1.default.cyan(`${PROGRAM_NAME} extract modules/orders.yaml Orders/CreateItem --to modules/order-create.yaml`)}
 
@@ -194,9 +202,13 @@ ${chalk_1.default.bold.yellow('AVAILABLE SCHEMAS:')}
 
   ${chalk_1.default.bold('Workflow Tasks:')}
     foreach, switch, while, validation, graphql, httpRequest,
-    setVariable, map, log, error, csv, export, template,
-    order, contact, commodity, job, attachment,
-    email-send, document-render, charge, workflow-execute
+    setVariable, map, log, error, csv, export, template, import,
+    order, contact, contact-address, contact-payment-method,
+    commodity, job, attachment, charge, payment,
+    email-send, document-render, document-send, pdf-document,
+    accounting-transaction, number, workflow-execute,
+    filetransfer, caching, flow-transition, user, authentication,
+    edi, note, appmodule, action-event, inventory, movement
 
 ${chalk_1.default.bold.yellow('EXAMPLES:')}
   ${chalk_1.default.cyan(`${PROGRAM_NAME} schema form`)}
@@ -910,8 +922,13 @@ function runInit() {
     console.log('');
 }
 function runCreate(type, name, template, feature, createOptions) {
+    // Handle task-schema creation separately
+    if (type === 'task-schema') {
+        runCreateTaskSchema(name, createOptions);
+        return;
+    }
     if (!type || !['module', 'workflow'].includes(type)) {
-        console.error(chalk_1.default.red('Error: Invalid or missing type. Use: module or workflow'));
+        console.error(chalk_1.default.red('Error: Invalid or missing type. Use: module, workflow, or task-schema'));
         console.error(chalk_1.default.gray(`Example: ${PROGRAM_NAME} create module my-module`));
         process.exit(2);
     }
@@ -920,13 +937,13 @@ function runCreate(type, name, template, feature, createOptions) {
         console.error(chalk_1.default.gray(`Example: ${PROGRAM_NAME} create ${type} my-${type}`));
         process.exit(2);
     }
-    // Sanitize name
-    const safeName = name.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+    // Sanitize name: replace invalid chars with hyphen, collapse runs, trim edges
+    const safeName = name.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-{2,}/g, '-').replace(/^-|-$/g, '');
     // Determine output directory and file
     // workflows/ or features/<feature>/workflows/ (same for modules)
     const baseDir = type === 'module' ? 'modules' : 'workflows';
     const dir = feature
-        ? path.join('features', feature.toLowerCase().replace(/[^a-z0-9-]/g, '-'), baseDir)
+        ? path.join('features', feature.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-{2,}/g, '-').replace(/^-|-$/g, ''), baseDir)
         : baseDir;
     const fileName = `${safeName}.yaml`;
     const filePath = path.join(process.cwd(), dir, fileName);
@@ -960,6 +977,160 @@ function runCreate(type, name, template, feature, createOptions) {
     console.log('');
 }
 // ============================================================================
+// Create Task Schema Command
+// ============================================================================
+function runCreateTaskSchema(name, tasks) {
+    if (!name) {
+        console.error(chalk_1.default.red('Error: Missing name for task-schema'));
+        console.error(chalk_1.default.gray(`Example: ${PROGRAM_NAME} create task-schema filetransfer --tasks "FileTransfer/Connect@1,FileTransfer/Disconnect@1"`));
+        process.exit(2);
+    }
+    const safeName = name.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-{2,}/g, '-').replace(/^-|-$/g, '');
+    // Find schemas directory — prefer source schemas/ in dev, fall back to standard resolution
+    let schemasDir = path.join(process.cwd(), 'schemas');
+    if (!fs.existsSync(schemasDir)) {
+        const resolved = findSchemasPath();
+        if (!resolved) {
+            console.error(chalk_1.default.red('Error: Cannot find schemas directory'));
+            process.exit(2);
+        }
+        schemasDir = resolved;
+    }
+    const tasksDir = path.join(schemasDir, 'workflows', 'tasks');
+    if (!fs.existsSync(tasksDir)) {
+        fs.mkdirSync(tasksDir, { recursive: true });
+    }
+    const filePath = path.join(tasksDir, `${safeName}.json`);
+    if (fs.existsSync(filePath)) {
+        console.error(chalk_1.default.red(`Error: Schema file already exists: ${filePath}`));
+        process.exit(2);
+    }
+    // Parse --tasks flag (passed via --options)
+    const taskEnums = [];
+    if (tasks) {
+        for (const t of tasks.split(',')) {
+            const trimmed = t.trim();
+            if (trimmed)
+                taskEnums.push(trimmed);
+        }
+    }
+    // Derive a title from the name
+    const title = safeName
+        .split('-')
+        .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ') + ' Tasks';
+    // Build the schema JSON
+    const schema = {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        title,
+        description: `${title} operations`,
+        type: 'object',
+        properties: {
+            task: {
+                type: 'string',
+                ...(taskEnums.length > 0 ? { enum: taskEnums } : {}),
+                description: 'Task type identifier'
+            },
+            name: {
+                type: 'string',
+                description: 'Step name identifier'
+            },
+            description: {
+                type: 'string',
+                description: 'Step description'
+            },
+            conditions: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        expression: { type: 'string' }
+                    },
+                    required: ['expression']
+                }
+            },
+            continueOnError: {
+                type: 'boolean'
+            },
+            inputs: {
+                type: 'object',
+                description: `${title} inputs`,
+                additionalProperties: true
+            },
+            outputs: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string' },
+                        mapping: { type: 'string' }
+                    },
+                    required: ['name', 'mapping']
+                }
+            }
+        },
+        required: ['task'],
+        additionalProperties: true
+    };
+    fs.writeFileSync(filePath, JSON.stringify(schema, null, 2) + '\n', 'utf-8');
+    // Sync all.json
+    syncAllJson(tasksDir);
+    // Invalidate cache so new schema is immediately discoverable
+    _workflowTaskNamesCache = null;
+    console.log(chalk_1.default.green(`\n✓ Created task schema: ${path.relative(process.cwd(), filePath)}`));
+    console.log(chalk_1.default.gray(`\n  Next steps:`));
+    console.log(chalk_1.default.gray(`    1. Edit ${chalk_1.default.white(filePath)} to add typed input properties`));
+    console.log(chalk_1.default.gray(`    2. Verify: ${chalk_1.default.white(`${PROGRAM_NAME} schema ${safeName}`)}`));
+    console.log(chalk_1.default.gray(`    3. all.json has been auto-updated with the new reference`));
+    console.log('');
+}
+// ============================================================================
+// Sync all.json (auto-regenerate $ref entries from task schema directory)
+// ============================================================================
+function syncAllJson(tasksDir) {
+    const files = fs.readdirSync(tasksDir)
+        .filter(f => f.endsWith('.json') && f !== 'all.json' && f !== 'generic.json')
+        .sort();
+    const anyOfRefs = files.map(f => ({ $ref: f }));
+    // generic.json always last as fallback
+    if (fs.existsSync(path.join(tasksDir, 'generic.json'))) {
+        anyOfRefs.push({ $ref: 'generic.json' });
+    }
+    const allJson = {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        title: 'All Workflow Tasks',
+        description: 'Aggregator schema for all workflow task types. Uses anyOf to allow matching any known task type or falling back to generic task structure.',
+        type: 'object',
+        anyOf: anyOfRefs
+    };
+    fs.writeFileSync(path.join(tasksDir, 'all.json'), JSON.stringify(allJson, null, 2) + '\n', 'utf-8');
+}
+function runSyncSchemas() {
+    // Find schemas directory
+    let schemasDir = path.join(process.cwd(), 'schemas');
+    if (!fs.existsSync(schemasDir)) {
+        const resolved = findSchemasPath();
+        if (!resolved) {
+            console.error(chalk_1.default.red('Error: Cannot find schemas directory'));
+            process.exit(2);
+        }
+        schemasDir = resolved;
+    }
+    const tasksDir = path.join(schemasDir, 'workflows', 'tasks');
+    if (!fs.existsSync(tasksDir)) {
+        console.error(chalk_1.default.red('Error: Tasks directory not found'));
+        process.exit(2);
+    }
+    syncAllJson(tasksDir);
+    // Invalidate cache
+    _workflowTaskNamesCache = null;
+    const taskCount = fs.readdirSync(tasksDir)
+        .filter(f => f.endsWith('.json') && f !== 'all.json' && f !== 'generic.json')
+        .length;
+    console.log(chalk_1.default.green(`\n✓ Synced all.json with ${taskCount} task schemas (+ generic fallback)`));
+    console.log('');
+}
+// ============================================================================
 // Extract Command
 // ============================================================================
 function runExtract(sourceFile, componentName, targetFile) {
@@ -1090,7 +1261,7 @@ function parseArgs(args) {
         reportFormat: 'json'
     };
     // Check for commands
-    const commands = ['validate', 'schema', 'example', 'list', 'help', 'report', 'init', 'create', 'extract'];
+    const commands = ['validate', 'schema', 'example', 'list', 'help', 'report', 'init', 'create', 'extract', 'sync-schemas'];
     if (args.length > 0 && commands.includes(args[0])) {
         command = args[0];
         args = args.slice(1);
@@ -1157,6 +1328,9 @@ function parseArgs(args) {
         else if (arg === '--options') {
             options.createOptions = args[++i];
         }
+        else if (arg === '--tasks') {
+            options.createTasks = args[++i];
+        }
         else if (arg === '--to') {
             options.extractTo = args[++i];
         }
@@ -1244,47 +1418,81 @@ function detectFileType(filePath) {
 // ============================================================================
 // Schema Display
 // ============================================================================
+// Cache for dynamically discovered workflow task schema names
+let _workflowTaskNamesCache = null;
+function getWorkflowTaskNames(schemasPath) {
+    if (_workflowTaskNamesCache)
+        return _workflowTaskNamesCache;
+    const tasksDir = path.join(schemasPath, 'workflows', 'tasks');
+    _workflowTaskNamesCache = new Set();
+    if (fs.existsSync(tasksDir)) {
+        for (const file of fs.readdirSync(tasksDir)) {
+            if (file.endsWith('.json') && file !== 'all.json') {
+                _workflowTaskNamesCache.add(file.replace('.json', '').toLowerCase().replace(/[^a-z0-9-]/g, ''));
+            }
+        }
+    }
+    // Also include common definitions
+    const commonDir = path.join(schemasPath, 'workflows', 'common');
+    if (fs.existsSync(commonDir)) {
+        for (const file of fs.readdirSync(commonDir)) {
+            if (file.endsWith('.json')) {
+                _workflowTaskNamesCache.add(file.replace('.json', '').toLowerCase().replace(/[^a-z0-9-]/g, ''));
+            }
+        }
+    }
+    return _workflowTaskNamesCache;
+}
 function findSchemaFile(schemasPath, name, preferWorkflow = false) {
-    // Normalize name
+    // Normalize name: lowercase, strip non-alphanumeric except hyphens
     const normalizedName = name.toLowerCase().replace(/[^a-z0-9-]/g, '');
-    // Workflow schema names - these should match workflow schemas first
+    // Dynamically detect workflow schema names from directory contents
     const workflowCoreNames = ['workflow', 'activity', 'input', 'output', 'variable', 'trigger', 'schedule'];
-    const workflowTaskNames = [
-        'foreach', 'switch', 'while', 'validation', 'map', 'setvariable', 'httprequest',
-        'log', 'error', 'csv', 'export', 'template', 'graphql', 'order', 'contact',
-        'commodity', 'job', 'attachment', 'email-send', 'document-render', 'document-send',
-        'charge', 'accounting-transaction', 'payment', 'workflow-execute', 'condition',
-        'expression', 'mapping'
-    ];
+    const workflowTaskNames = getWorkflowTaskNames(schemasPath);
     const isWorkflowSchema = workflowCoreNames.includes(normalizedName) ||
-        workflowTaskNames.includes(normalizedName);
-    // Search patterns in order of priority
+        workflowTaskNames.has(normalizedName);
+    // Build search paths using normalized name for consistency
     const searchPaths = preferWorkflow || isWorkflowSchema
         ? [
             // Workflow schemas first for workflow-related names
-            path.join(schemasPath, 'workflows', `${name}.json`),
-            path.join(schemasPath, 'workflows', 'tasks', `${name}.json`),
-            path.join(schemasPath, 'workflows', 'common', `${name}.json`),
+            path.join(schemasPath, 'workflows', `${normalizedName}.json`),
+            path.join(schemasPath, 'workflows', 'tasks', `${normalizedName}.json`),
+            path.join(schemasPath, 'workflows', 'common', `${normalizedName}.json`),
             // Then module schemas
-            path.join(schemasPath, 'components', `${name}.json`),
-            path.join(schemasPath, 'fields', `${name}.json`),
-            path.join(schemasPath, 'actions', `${name}.json`)
+            path.join(schemasPath, 'components', `${normalizedName}.json`),
+            path.join(schemasPath, 'fields', `${normalizedName}.json`),
+            path.join(schemasPath, 'actions', `${normalizedName}.json`)
         ]
         : [
             // Module schemas first
-            path.join(schemasPath, 'components', `${name}.json`),
-            path.join(schemasPath, 'fields', `${name}.json`),
-            path.join(schemasPath, 'actions', `${name}.json`),
+            path.join(schemasPath, 'components', `${normalizedName}.json`),
+            path.join(schemasPath, 'fields', `${normalizedName}.json`),
+            path.join(schemasPath, 'actions', `${normalizedName}.json`),
             // Then workflow schemas
-            path.join(schemasPath, 'workflows', `${name}.json`),
-            path.join(schemasPath, 'workflows', 'tasks', `${name}.json`),
-            path.join(schemasPath, 'workflows', 'common', `${name}.json`)
+            path.join(schemasPath, 'workflows', `${normalizedName}.json`),
+            path.join(schemasPath, 'workflows', 'tasks', `${normalizedName}.json`),
+            path.join(schemasPath, 'workflows', 'common', `${normalizedName}.json`)
         ];
     for (const schemaPath of searchPaths) {
         if (fs.existsSync(schemaPath)) {
             return schemaPath;
         }
     }
+    // Also try with the original name (preserving case) for backwards compatibility
+    if (normalizedName !== name) {
+        const caseSensitivePaths = [
+            path.join(schemasPath, 'workflows', 'tasks', `${name}.json`),
+            path.join(schemasPath, 'workflows', `${name}.json`),
+            path.join(schemasPath, 'components', `${name}.json`),
+            path.join(schemasPath, 'fields', `${name}.json`),
+            path.join(schemasPath, 'actions', `${name}.json`)
+        ];
+        for (const schemaPath of caseSensitivePaths) {
+            if (fs.existsSync(schemaPath)) {
+                return schemaPath;
+            }
+        }
+    }
     // Try fuzzy matching
     const allSchemas = getAllSchemas(schemasPath);
     for (const schema of allSchemas) {
@@ -1940,7 +2148,18 @@ async function main() {
     }
     // Handle create command
     if (command === 'create') {
-        runCreate(files[0], files[1], options.template, options.feature, options.createOptions);
+        // For task-schema, pass --tasks (from options.createTasks) as the tasks argument
+        if (files[0] === 'task-schema') {
+            runCreate(files[0], files[1], options.template, options.feature, options.createTasks);
+        }
+        else {
+            runCreate(files[0], files[1], options.template, options.feature, options.createOptions);
+        }
+        process.exit(0);
+    }
+    // Handle sync-schemas command
+    if (command === 'sync-schemas') {
+        runSyncSchemas();
         process.exit(0);
     }
     // Handle extract command