@cxtms/cx-schema 1.9.1 → 1.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxtms/cx-schema",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "description": "Schema validation package for CargoXplorer YAML modules",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/postinstall.js

@@ -111,6 +111,97 @@ main().catch(error => {
   }
 }
 
+const CX_CLAUDE_MARKER = '<!-- cx-schema-instructions -->';
+
+function generateClaudeMdContent() {
+  return `${CX_CLAUDE_MARKER}
+## CargoXplorer Project
+
+This is a CargoXplorer (CX) application. Modules and workflows are defined as YAML files validated against JSON schemas provided by \`@cxtms/cx-schema\`.
+
+### Project Structure
+
+\`\`\`
+app.yaml              # Application manifest (name, version, description)
+modules/              # UI module YAML files
+workflows/            # Workflow YAML files
+features/             # Feature-scoped modules and workflows
+  <feature>/
+    modules/
+    workflows/
+\`\`\`
+
+### CLI — \`cxtms\`
+
+**Always scaffold via CLI, never write YAML from scratch.**
+
+| Command | Description |
+|---------|-------------|
+| \`npx cxtms create module <name>\` | Scaffold a UI module |
+| \`npx cxtms create workflow <name>\` | Scaffold a workflow |
+| \`npx cxtms create module <name> --template <t>\` | Use a specific template |
+| \`npx cxtms create workflow <name> --template <t>\` | Use a specific template |
+| \`npx cxtms create module <name> --feature <f>\` | Place under features/<f>/modules/ |
+| \`npx cxtms <file.yaml>\` | Validate a YAML file |
+| \`npx cxtms <file.yaml> --verbose\` | Validate with detailed errors |
+| \`npx cxtms schema <name>\` | Show JSON schema for a component or task |
+| \`npx cxtms example <name>\` | Show example YAML |
+| \`npx cxtms list\` | List all available schemas |
+| \`npx cxtms extract <src> <comp> --to <tgt>\` | Move component between modules |
+
+**Module templates:** \`default\`, \`form\`, \`grid\`, \`select\`, \`configuration\`
+**Workflow templates:** \`basic\`, \`entity-trigger\`, \`document\`, \`scheduled\`, \`utility\`, \`webhook\`, \`public-api\`, \`mcp-tool\`, \`ftp-tracking\`, \`ftp-edi\`, \`api-tracking\`
+
+### Skills (slash commands)
+
+| Skill | Purpose |
+|-------|---------|
+| \`/cxtms-module-builder <description>\` | Generate a UI module (forms, grids, screens) |
+| \`/cxtms-workflow-builder <description>\` | Generate a workflow (automation, triggers, integrations) |
+| \`/cxtms-developer <entity or question>\` | Look up entity fields, enums, and domain reference |
+
+### Workflow: Scaffold → Customize → Validate
+
+1. **Scaffold** — \`npx cxtms create module|workflow <name> --template <t>\`
+2. **Read** the generated file
+3. **Customize** for the use case
+4. **Validate** — \`npx cxtms <file.yaml>\` — run after every change, fix all errors
+${CX_CLAUDE_MARKER}`;
+}
+
+function setupClaudeMd(projectRoot) {
+  const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+  const cxContent = generateClaudeMdContent();
+
+  if (fs.existsSync(claudeMdPath)) {
+    const existing = fs.readFileSync(claudeMdPath, 'utf-8');
+
+    if (existing.includes(CX_CLAUDE_MARKER)) {
+      // Replace existing CX section
+      const markerRegex = new RegExp(
+        CX_CLAUDE_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') +
+        '[\\s\\S]*?' +
+        CX_CLAUDE_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      );
+      const updated = existing.replace(markerRegex, cxContent);
+      if (updated !== existing) {
+        fs.writeFileSync(claudeMdPath, updated, 'utf-8');
+        console.log('Updated CX instructions in CLAUDE.md');
+      } else {
+        console.log('CLAUDE.md CX instructions already up to date');
+      }
+    } else {
+      // Append to existing file
+      const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+      fs.writeFileSync(claudeMdPath, existing + separator + cxContent + '\n', 'utf-8');
+      console.log('Appended CX instructions to CLAUDE.md');
+    }
+  } else {
+    fs.writeFileSync(claudeMdPath, `# Project Instructions\n\n${cxContent}\n`, 'utf-8');
+    console.log('Created CLAUDE.md with CX instructions');
+  }
+}
+
 function main() {
   console.log('CX Schema Validator: Running postinstall...');
 
@@ -183,6 +274,9 @@ function main() {
     }
   }
 
+  // TODO: Enable once CLAUDE.md content is finalized
+  // setupClaudeMd(projectRoot);
+
   console.log('✓ CX Schema Validator installed successfully!');
   console.log('\nUsage:');
   console.log('  npx cxtms modules/your-module.yaml');

package/skills/cxtms-developer/SKILL.md

@@ -3,6 +3,7 @@ name: cxtms-developer
 description: >
   Shared CargoXplorer domain reference — entity fields, enums, customValues, GraphQL queries, and CLI auth.
   Use when the user asks about CX entity fields, enums, customValues, entity relationships, or needs domain reference for Orders, Contacts, Commodities, Jobs, Charges, or other CX entities.
+  Also use when the user wants to look up, check, or query specific orders, parcel shipments, commodities, tracking events, workflow logs, or any CX data.
 argument-hint: <entity name or question about fields>
 ---
 

package/skills/cxtms-developer/ref-graphql-query.md

@@ -290,17 +290,6 @@ npx cxtms gql type EntityAuditHistoryLightResult
 npx cxtms gql type CreateOrderInput
 ```
 
-### TMS MCP: `graphql_schema` / `graphql_type` — equivalent MCP tools
-
-When TMS MCP is available, the same discovery is available via MCP tools:
-
-```
-graphql_schema(section: "queries", filter: "order")
-graphql_schema(section: "types", filter: "audit")
-graphql_type(typeName: "OrderGqlDto")
-graphql_execute(query: "{ orders(organizationId: 1, take: 1) { items { orderId } } }")
-```
-
 ### Workflow: discover → query
 
 1. **Find the type** — `cxtms gql types --filter order` to find type names

package/skills/cxtms-workflow-builder/SKILL.md

@@ -43,7 +43,6 @@ npx cxtms create workflow <name> --template <template>
 | `ftp-tracking` | Import tracking events from FTP |
 | `ftp-edi` | Import orders from FTP via EDI |
 | `api-tracking` | Fetch tracking from carrier API |
-| `mcp-tool` | Expose workflow as MCP tool |
 | `webhook` | HTTP endpoint for external callers |
 | `public-api` | REST API endpoint with OpenAPI docs |
 
@@ -67,8 +66,6 @@ npx cxtms create workflow <name> --template <template>
 
 **`api-tracking`** — update `apiConfig` configName with carrier API credentials (`baseUrl`, `apiKey`, `carrierId`). Update the GraphQL filter to select orders needing tracking. Map the carrier's API response structure in ParseTrackingResponse (foreach path, field names for `eventDate`, `location`, `statusCode`). Configure `trackingEventMatchByFields` and `matchByEventDefinition` custom value keys.
 
-**`mcp-tool`** — write a clear `agentInstruction` describing when to use the tool, expected inputs, and return values. Keep `executionMode: Sync` so the agent gets results immediately. Define typed `inputs` with descriptive `props` (the AI reads these). Return structured data via `outputs`. The `mcp-tool` tag is required — it's what makes the workflow discoverable via `list_custom_tools` in the MCP server. Validate inputs with `Utilities/Error@1` conditions.
-
 **`webhook`** — endpoint: `POST /api/v2/orgs/{organizationId}/webhooks/{workflowId}`. The endpoint is anonymous (`[AllowAnonymous]`) and rate-limited (10/sec, 100/min per IP). Two inputs are auto-injected by the controller: `payload` (parsed JSON body or raw string) and `request` (object with `headers`, `body`, `remoteIpAddress`). Control the HTTP response via `response` and `statusCode` outputs. Update `webhookSecret` configName to your app config path. Customize the `ValidateWebhook` step for your auth method (header secret, HMAC signature, etc.). Use `executionMode: Sync` when the caller needs a response; use `Async` for fire-and-forget (returns immediately). Keep `runAs: "system"` since the endpoint is anonymous. Add `additionalProperties.cors.allowedOrigins` to restrict CORS if needed.
 
 **`public-api`** — requires a top-level `api` section defining the REST endpoint. Set `api.path` with route params (e.g., `/orders/{orderId}`), `api.method` (GET/POST/PUT/PATCH/DELETE), `api.authentication` (`none`, `bearer`, `apiKey`), `api.document` (swagger doc name, default `"public"`), and `api.category` (swagger tag). Configure `api.rateLimit` with `perSecond`/`perMinute`. Each input uses `props.in` (`path`, `query`, `header`, `body`) to specify where the parameter comes from, and `props.format` for OpenAPI type hints (e.g., `uuid`, `date-time`). Outputs use `props.type`, `props.description`, and `props.schema` to describe the response for OpenAPI docs. Must use `executionMode: Sync`. Control HTTP response via `response` and `statusCode` outputs.