@cxtms/cx-schema 1.0.0 → 1.1.0

package/schemas/workflows/workflow.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "CargoXplorer Workflow",
-  "description": "Schema for CargoXplorer workflow YAML files",
+  "description": "Schema for CargoXplorer workflow YAML files. Supports standard task-based workflows and Flow (state machine) workflows.",
   "type": "object",
   "properties": {
     "workflow": {
@@ -50,11 +50,13 @@
         },
         "enableActionEvents": {
           "type": "boolean",
-          "description": "Enable action events"
+          "description": "Enable action events (deprecated)"
         },
         "priority": {
-          "type": "number",
-          "description": "Workflow priority (higher = higher priority)"
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Workflow priority (0-100, higher = higher priority, default: 50)"
         },
         "tags": {
           "type": "array",
@@ -65,30 +67,44 @@
         },
         "workflowType": {
           "type": "string",
-          "enum": ["Document", "Quote", "EmailTemplate"],
-          "description": "Workflow type classification"
+          "enum": ["Document", "Quote", "Flow", "Webhook", "PublicApi"],
+          "description": "Workflow type: Document (PDF/Excel generation), Quote, Flow (declarative state machine), Webhook (HTTP endpoint), or PublicApi (REST API endpoint). Omit for standard process workflows."
         },
         "runAs": {
           "type": "string",
-          "description": "User context for workflow execution"
+          "description": "Username or user ID for workflow execution context"
         },
         "concurrency": {
           "type": "object",
           "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Whether concurrency control is active"
+            },
             "group": {
               "type": "string",
               "description": "Concurrency group identifier"
             },
             "waitTime": {
               "type": "number",
-              "description": "Seconds to wait for lock"
+              "default": 15,
+              "description": "Seconds to wait for lock (default: 15)"
             }
           },
           "additionalProperties": true
         },
+        "filePath": {
+          "type": "string",
+          "description": "Repository file path under workflows/ or features/{name}/workflows/"
+        },
+        "agentInstruction": {
+          "type": "string",
+          "description": "AI agent instruction describing how to use this workflow, expected inputs, and returned outputs"
+        },
         "fileName": {
           "type": "string",
-          "description": "Path to the workflow YAML file"
+          "description": "Path to the workflow YAML file (deprecated, use filePath)"
         },
         "actionEvent": {
           "type": "object",
@@ -127,7 +143,7 @@
     },
     "activities": {
       "type": "array",
-      "description": "Workflow activities containing steps",
+      "description": "Workflow activities containing steps (required for standard workflows, not used in Flow workflows)",
       "items": {
         "$ref": "activity.json"
       },
@@ -148,25 +164,167 @@
       }
     },
     "events": {
+      "oneOf": [
+        {
+          "type": "object",
+          "description": "Workflow-level event handlers as object",
+          "properties": {
+            "onWorkflowStarted": {
+              "type": "array",
+              "description": "Steps to execute when workflow starts"
+            },
+            "onWorkflowExecuted": {
+              "type": "array",
+              "description": "Steps to execute when workflow completes"
+            },
+            "onWorkflowFailed": {
+              "type": "array",
+              "description": "Steps to execute when workflow fails"
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "array",
+          "description": "Workflow-level event handlers as array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "description": "Event type"
+              },
+              "steps": {
+                "type": "array",
+                "description": "Steps to execute for this event"
+              }
+            },
+            "additionalProperties": true
+          }
+        }
+      ]
+    },
+    "api": {
       "type": "object",
-      "description": "Workflow-level event handlers",
+      "description": "Public API endpoint configuration (required for PublicApi workflows)",
       "properties": {
-        "onWorkflowStarted": {
-          "type": "array",
-          "description": "Steps to execute when workflow starts"
+        "path": {
+          "type": "string",
+          "description": "API route path with parameter placeholders (e.g., '/orders/{orderId}')"
         },
-        "onWorkflowExecuted": {
-          "type": "array",
-          "description": "Steps to execute when workflow completes"
+        "method": {
+          "type": "string",
+          "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"],
+          "description": "HTTP method"
         },
-        "onWorkflowFailed": {
-          "type": "array",
-          "description": "Steps to execute when workflow fails"
+        "summary": {
+          "type": "string",
+          "description": "Short summary for Swagger/OpenAPI documentation"
+        },
+        "description": {
+          "type": "string",
+          "description": "Detailed description for Swagger/OpenAPI documentation"
+        },
+        "operationId": {
+          "type": "string",
+          "description": "Unique operation ID for OpenAPI (auto-generated if omitted)"
+        },
+        "document": {
+          "type": "string",
+          "description": "Swagger document name (default: 'public')"
+        },
+        "category": {
+          "type": "string",
+          "description": "Swagger tag/group for organizing endpoints"
+        },
+        "authentication": {
+          "type": "string",
+          "enum": ["none", "bearer", "apiKey"],
+          "description": "Authentication method: none (anonymous), bearer (JWT token), or apiKey"
+        },
+        "rateLimit": {
+          "type": "object",
+          "description": "Rate limiting configuration",
+          "properties": {
+            "perSecond": {
+              "type": "integer",
+              "description": "Maximum requests per second"
+            },
+            "perMinute": {
+              "type": "integer",
+              "description": "Maximum requests per minute"
+            }
+          },
+          "additionalProperties": false
         }
       },
+      "required": ["path", "method"],
       "additionalProperties": true
+    },
+    "entity": {
+      "$ref": "flow/entity.json",
+      "description": "Entity configuration for Flow workflows"
+    },
+    "states": {
+      "type": "array",
+      "description": "State definitions for Flow workflows",
+      "items": {
+        "$ref": "flow/state.json"
+      }
+    },
+    "transitions": {
+      "type": "array",
+      "description": "Transition definitions for Flow workflows",
+      "items": {
+        "$ref": "flow/transition.json"
+      }
+    },
+    "aggregations": {
+      "type": "array",
+      "description": "Aggregation definitions for Flow workflows",
+      "items": {
+        "$ref": "flow/aggregation.json"
+      }
     }
   },
-  "required": ["workflow", "activities"],
+  "required": ["workflow"],
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "workflow": {
+            "properties": {
+              "workflowType": { "const": "Flow" }
+            },
+            "required": ["workflowType"]
+          }
+        }
+      },
+      "then": {
+        "required": ["workflow", "entity"],
+        "properties": {
+          "activities": false
+        }
+      },
+      "else": {
+        "required": ["workflow", "activities"]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "workflow": {
+            "properties": {
+              "workflowType": { "const": "PublicApi" }
+            },
+            "required": ["workflowType"]
+          }
+        }
+      },
+      "then": {
+        "required": ["workflow", "activities", "api"]
+      }
+    }
+  ],
   "additionalProperties": true
 }

package/scripts/postinstall.js

@@ -149,10 +149,39 @@ function main() {
   console.log('Creating validation script...');
   createValidationScript(projectRoot);
 
+  // Copy Claude Code skills
+  const skillNames = ['cx-module', 'cx-workflow'];
+  for (const skillName of skillNames) {
+    const skillSource = path.join(__dirname, '..', '.claude', 'skills', skillName);
+    if (fs.existsSync(skillSource)) {
+      const skillDest = path.join(projectRoot, '.claude', 'skills', skillName);
+      console.log(`Installing ${skillName} skill...`);
+      try {
+        copyDirectory(skillSource, skillDest);
+        console.log(`${skillName} skill installed successfully!`);
+      } catch (error) {
+        console.warn(`Warning: Could not install ${skillName} skill:`, error.message);
+      }
+    }
+  }
+
+  // Remove old cx-build skill if it exists
+  const oldSkillDest = path.join(projectRoot, '.claude', 'skills', 'cx-build');
+  if (fs.existsSync(oldSkillDest)) {
+    try {
+      fs.rmSync(oldSkillDest, { recursive: true });
+      console.log('Removed deprecated cx-build skill.');
+    } catch (error) {
+      // Ignore cleanup errors
+    }
+  }
+
   console.log('✓ CX Schema Validator installed successfully!');
   console.log('\nUsage:');
-  console.log('  npx cx-validate modules/your-module.yaml');
+  console.log('  npx cx-cli modules/your-module.yaml');
   console.log('  node .cx-schema/validate.js modules/your-module.yaml');
+  console.log('  /cx-module <description>   (Claude Code skill - UI modules)');
+  console.log('  /cx-workflow <description>  (Claude Code skill - workflows)');
 }
 
 // Only run if this is not being installed as a dependency of cx-schema-validator itself

package/templates/module-configuration.yaml

@@ -0,0 +1,110 @@
+# {{displayName}} Configuration Module
+# Generated by cx-cli create module --template configuration
+
+module:
+  name: "{{displayNameNoSpaces}}"
+  appModuleId: "{{uuid}}"
+  displayName:
+    en-US: "{{displayName}}"
+  description:
+    en-US: "{{displayName}} configuration module"
+  application: CargoXplorer
+  fileName: "{{fileName}}"
+
+components:
+  - name: {{displayNameNoSpaces}}/Configuration
+    displayName:
+      en-US: "{{displayName}}"
+    layout:
+      component: form
+      name: {{name}}Form
+      props:
+        title:
+          en-US: "{{displayName}}"
+        queries:
+          - name: getConfiguration
+            query:
+              command: |
+                query GetConfiguration($organizationId: Int!) {
+                  configuration(organizationId: $organizationId) {
+                    settingName
+                    maxRetries
+                    enableNotifications
+                  }
+                }
+              variables:
+                organizationId: "\{{organizationId}}"
+        initialValues:
+          fromQuery:
+            name: getConfiguration
+            path: configuration
+          append:
+            settingName: "Default Setting"
+            maxRetries: 3
+            enableNotifications: true
+        validationSchema:
+          settingName:
+            type: string
+            required: true
+          maxRetries:
+            type: number
+            required: true
+          enableNotifications:
+            type: boolean
+        onSubmit:
+          - type: mutation
+            props:
+              command: |
+                mutation SaveConfiguration($organizationId: Int!, $input: ConfigurationInput!) {
+                  saveConfiguration(organizationId: $organizationId, input: $input) {
+                    success
+                  }
+                }
+              variables:
+                organizationId: "\{{organizationId}}"
+                input: "\{{formValues}}"
+          - type: notification
+            props:
+              message:
+                en-US: "{{displayName}} saved successfully"
+              severity: success
+      children:
+        - component: field
+          name: settingName
+          props:
+            label:
+              en-US: "Setting Name"
+            type: text
+            required: true
+        - component: field
+          name: maxRetries
+          props:
+            label:
+              en-US: "Max Retries"
+            type: number
+        - component: field
+          name: enableNotifications
+          props:
+            label:
+              en-US: "Enable Notifications"
+            type: checkbox
+
+routes:
+  - name: configuration
+    path: /{{name}}
+    component: {{displayNameNoSpaces}}/Configuration
+    props:
+      title:
+        en-US: "{{displayName}}"
+
+permissions:
+  - name: "{{displayNameNoSpaces}}/View"
+    displayName:
+      en-US: "View {{displayName}}"
+    roles:
+      - Admin
+  - name: "{{displayNameNoSpaces}}/Edit"
+    displayName:
+      en-US: "Edit {{displayName}}"
+    roles:
+      - Admin

package/templates/module-form.yaml

@@ -0,0 +1,152 @@
+# {{displayName}} Form Module
+# Generated by cx-cli create module --template form
+
+module:
+  name: "{{displayNameNoSpaces}}"
+  appModuleId: "{{uuid}}"
+  displayName:
+    en-US: "{{displayName}}"
+  description:
+    en-US: "{{displayName}} module"
+  application: CargoXplorer
+  fileName: "{{fileName}}"
+
+components:
+  - name: {{displayNameNoSpaces}}/Detail
+    displayName:
+      en-US: "{{displayName}} Detail"
+    platforms:
+      - web
+    layout:
+      component: form
+      name: {{name}}Form
+      props:
+        title:
+          en-US: "{{displayName}}"
+        toolbar:
+          - component: button
+            name: saveBtn
+            props:
+              label:
+                en-US: "Save"
+              icon: check
+              options:
+                type: submit
+                variant: primary
+          - component: button
+            name: cancelBtn
+            props:
+              label:
+                en-US: "Cancel"
+              icon: x
+              options:
+                variant: secondary
+              onClick:
+                - navigateBack:
+                    fallback: "/{{name}}"
+        dirtyGuard:
+          enabled: true
+          title:
+            en-US: "Unsaved Changes"
+          message:
+            en-US: "You have unsaved changes. Are you sure you want to leave?"
+          confirmLabel:
+            en-US: "Leave"
+          cancelLabel:
+            en-US: "Stay"
+        queries:
+          - name: get{{displayNameNoSpaces}}
+            query:
+              command: |
+                query Get{{displayNameNoSpaces}}($organizationId: Int!, $id: Int!) {
+                  {{name}}(organizationId: $organizationId, id: $id) {
+                    id
+                    name
+                    description
+                  }
+                }
+              variables:
+                organizationId: '\{{number organizationId}}'
+                id: '\{{number id}}'
+        initialValues:
+          fromQuery:
+            name: get{{displayNameNoSpaces}}
+            path: {{name}}
+        validationSchema:
+          name:
+            type: string
+            required: true
+          description:
+            type: string
+        onSubmit:
+          - mutation:
+              command: |
+                mutation Save{{displayNameNoSpaces}}($organizationId: Int!, $input: {{displayNameNoSpaces}}Input!) {
+                  save{{displayNameNoSpaces}}(organizationId: $organizationId, input: $input) {
+                    id
+                  }
+                }
+              variables:
+                organizationId: '\{{number organizationId}}'
+                input: '\{{form}}'
+              onSuccess:
+                - notification:
+                    message:
+                      en-US: "{{displayName}} saved successfully"
+                    type: success
+                - navigateBack:
+                    fallback: "/{{name}}"
+              onError:
+                - notification:
+                    message:
+                      en-US: "Failed to save {{displayName}}"
+                    type: error
+      children:
+        - component: field
+          name: name
+          props:
+            label:
+              en-US: "Name"
+            type: text
+            required: true
+        - component: field
+          name: description
+          props:
+            label:
+              en-US: "Description"
+            type: textarea
+
+routes:
+  - name: detail
+    path: /{{name}}/:id
+    component: {{displayNameNoSpaces}}/Detail
+    props:
+      title:
+        en-US: "{{displayName}}"
+
+entities:
+  - name: {{displayNameNoSpaces}}
+    entityKind: Other
+    displayName:
+      en-US: "{{displayName}}"
+    fields:
+      - name: name
+        displayName:
+          en-US: "Name"
+        fieldType: text
+      - name: description
+        displayName:
+          en-US: "Description"
+        fieldType: text
+
+permissions:
+  - name: "{{displayNameNoSpaces}}/Read"
+    displayName:
+      en-US: "Read {{displayName}}"
+    roles:
+      - Admin
+  - name: "{{displayNameNoSpaces}}/Update"
+    displayName:
+      en-US: "Update {{displayName}}"
+    roles:
+      - Admin