@cxtms/cx-schema 1.7.12 → 1.7.13

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

@@ -12,6 +12,10 @@ Shared domain reference for CargoXplorer entities. Used by `cx-workflow` and `cx
 
 For CLI authentication, PAT tokens, org management, and publishing: see [ref-cli-auth.md](ref-cli-auth.md)
 
+## GraphQL Querying & Audit History
+
+For running GraphQL queries via CLI, filter syntax (Lucene), pagination, audit change history, and field discovery: see [ref-graphql-query.md](ref-graphql-query.md)
+
 ## Feature File Layout
 
 All modules and workflows are organized under feature directories:

package/.claude/skills/cx-core/ref-graphql-query.md

@@ -0,0 +1,320 @@
+# GraphQL Query Reference
+
+## CLI Query Command
+
+```bash
+npx cxtms query '<graphql-query>'              # Inline query
+npx cxtms query my-query.graphql               # From file
+npx cxtms query '<query>' --vars '{"key":"v"}' # With variables
+```
+
+Requires active login (`npx cxtms login`). Uses the active organization.
+
+## Query Arguments
+
+All root entity queries follow this pattern:
+
+```graphql
+orders(
+  organizationId: Int!    # Required — active org ID
+  filter: String          # Lucene query syntax (see below)
+  search: String          # Full-text search across key fields
+  orderBy: String         # Comma-separated sort fields
+  take: Int               # Page size (alias: limit)
+  skip: Int               # Offset (alias: offset)
+)
+```
+
+Entity-specific extras:
+- `orders` — `includeDraft: Boolean` (default false)
+
+Available root queries: `orders`, `contacts`, `commodities`, `accountingTransactions`, `jobs`, and others.
+
+## Filter Syntax (Lucene Query)
+
+Filters use **Lucene Query syntax** (not OData, not NCalc).
+
+### Basic field matching
+```
+filter: "orderId:196596"
+filter: "orderType:ParcelShipment"
+filter: "status:Active"
+```
+
+### Wildcards
+```
+filter: "name:*pending*"        # Contains
+filter: "code:ABC*"             # Starts with
+filter: "status:*Active"        # Ends with
+```
+
+### Logical operators
+```
+filter: "countryCode:US AND name:Test"
+filter: "status:Active OR status:Pending"
+filter: "NOT customValues.po:123"
+filter: "orderType:ParcelShipment AND (status:Active OR status:Pending)"
+```
+
+### Nested paths (dot notation)
+```
+filter: "orderEntities.entityType:Consignee"
+filter: "orderEntities.contactId:7128"
+filter: "jobs.orders.orderNumber:16*"
+```
+
+### Range queries
+```
+filter: "lastModified:[\"2026-01-01\" TO \"2026-03-15\"]"
+filter: "lastModified:[\"2026-01-01\" TO *]"    # >= date
+filter: "amount:[100 TO 500]"
+```
+
+### NULL checks
+```
+filter: "customValues.po:NULL"
+```
+
+### CustomValues (JSONB fields)
+```
+filter: "customValues.fieldName:value"
+filter: "customValues.fieldName:\"exact match\""
+filter: "customValues.fieldName:NULL"
+```
+
+### Filtered collections (bracket notation)
+```
+filter: "children[category:CatA].name:test"
+```
+
+## OrderBy Syntax
+
+```
+orderBy: "orderNumber"                # Ascending
+orderBy: "-orderNumber"               # Descending
+orderBy: "-created,orderNumber"       # Multi-field
+orderBy: "customValues.fieldName"     # Custom field sort
+orderBy: "orderNumber~ToInt32"        # Type conversion during sort
+```
+
+## Pagination
+
+```graphql
+{
+  orders(organizationId: 1, take: 50, skip: 0) {
+    items { orderId orderNumber }
+    totalCount
+    pageInfo { hasNextPage hasPreviousPage }
+  }
+}
+```
+
+## Audit Change History
+
+### Entity-level: `changeHistory` computed field
+
+Available on: **Order**, **Contact**, **Commodity**, **AccountingTransaction**
+
+```graphql
+{
+  orders(organizationId: 1, filter: "orderId:196596", take: 1) {
+    items {
+      orderId
+      changeHistory(maxResults: 20) {
+        entityName
+        hasMoreRecords
+        continuationToken
+        changes {
+          state         # "Added" | "Modified" | "Deleted"
+          userId
+          timestamp
+          user {
+            fullName
+            email
+          }
+          changedFields {
+            fieldName
+            originalValue
+            currentValue
+            fieldType
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Arguments: `startDate: DateTime`, `endDate: DateTime`, `maxResults: Int` (default 10)
+
+### Root-level: `auditChanges` query
+
+Query audit changes directly without fetching the entity first:
+
+```graphql
+{
+  auditChanges(
+    organizationId: 1
+    filter: "entityName:Order AND primaryKey:196596"
+    take: 20
+  ) {
+    items {
+      state
+      userId
+      timestamp
+      user { fullName email }
+      changedFields {
+        fieldName
+        originalValue
+        currentValue
+        fieldType
+      }
+    }
+  }
+}
+```
+
+Arguments: `organizationId: Int!`, `filter: String`, `search: String`, `take: Int`, `skip: Int`, `orderBy: String`
+
+Filter fields: `entityName`, `primaryKey`, `userId`, `state`
+
+### Root-level: `auditChangeSummaries` query
+
+High-level summary of changes (grouped by change event):
+
+```graphql
+{
+  auditChangeSummaries(
+    organizationId: 1
+    startDate: "2026-03-01T00:00:00Z"
+    endDate: "2026-03-15T23:59:59Z"
+    maxResults: 50
+  ) {
+    items {
+      changeId
+      userId
+      timestamp
+      changePaths
+      organizationId
+    }
+    continuationToken
+    hasMoreRecords
+  }
+}
+```
+
+### Root-level: `auditChange` — single change detail
+
+```graphql
+{
+  auditChange(filePath: "<s3-file-path>") {
+    entityName
+    state
+    primaryKey
+    userId
+    timestamp
+    originalValues
+    currentValues
+    fields {
+      fieldName
+      originalValue
+      currentValue
+      fieldType
+    }
+  }
+}
+```
+
+## GraphQL Type Reference
+
+### EntityAuditHistoryLightResult
+| Field | Type |
+|-------|------|
+| `entityName` | `String` |
+| `primaryKey` | `String` |
+| `organizationId` | `Int` |
+| `changes` | `[AuditChangeEntry!]!` |
+| `continuationToken` | `String` |
+| `hasMoreRecords` | `Boolean!` |
+
+### AuditChangeEntry
+| Field | Type | Notes |
+|-------|------|-------|
+| `state` | `String` | "Added", "Modified", "Deleted" |
+| `userId` | `String` | |
+| `timestamp` | `DateTime!` | |
+| `user` | `AuditUser` | Lazy-loaded resolver |
+| `changedFields` | `[AuditChangeField!]!` | Lazy-loaded resolver |
+
+### AuditChangeField
+| Field | Type |
+|-------|------|
+| `fieldName` | `String!` |
+| `originalValue` | `Any` |
+| `currentValue` | `Any` |
+| `fieldType` | `String!` |
+
+### AuditUser
+| Field | Type |
+|-------|------|
+| `id` | `String` |
+| `firstName` | `String` |
+| `lastName` | `String` |
+| `fullName` | `String` |
+| `userName` | `String` |
+| `email` | `String` |
+
+## Discovering Fields
+
+**Always discover field names before building a query.** Do not guess field names — use the tools below.
+
+### CLI: `cxtms gql` — schema exploration commands
+
+```bash
+# List all query root fields (what you can query)
+npx cxtms gql queries
+npx cxtms gql queries --filter order
+
+# List all mutation root fields
+npx cxtms gql mutations
+npx cxtms gql mutations --filter order
+
+# List all types (filter by name)
+npx cxtms gql types --filter audit
+npx cxtms gql types --filter order
+
+# Inspect a specific type — shows fields, arguments, input fields, enum values
+npx cxtms gql type OrderGqlDto
+npx cxtms gql type AuditChangeEntry
+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
+2. **Inspect the type** — `cxtms gql type OrderGqlDto` to see all fields and their types
+3. **Check query args** — `cxtms gql queries --filter order` to see arguments
+4. **Build and run** — `cxtms query '<graphql-query>'`
+
+### Fallback: error-driven discovery
+
+GraphQL error messages reveal valid field/type names:
+- "The field `foo` does not exist on the type `BarType`" — tells you the type name
+- "The argument `bar` does not exist" — tells you valid argument patterns
+
+### Other sources
+
+- `npx cxtms schema <name>` — shows workflow/module JSON schema fields (not GraphQL)
+- Entity reference files (`ref-entity-*.md`) — document common fields, computed properties, and enums

package/dist/cli.js

@@ -119,6 +119,7 @@ ${chalk_1.default.bold.yellow('COMMANDS:')}
   ${chalk_1.default.green('publish')}         Publish all modules and workflows to a CX server
   ${chalk_1.default.green('app')}             Manage app manifests (install/upgrade from git, publish to git, list)
   ${chalk_1.default.green('query')}           Run a GraphQL query against the CX server
+  ${chalk_1.default.green('gql')}             Explore GraphQL schema (types, queries, mutations)
   ${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)
@@ -336,6 +337,20 @@ ${chalk_1.default.bold.yellow('QUERY COMMANDS:')}
   ${chalk_1.default.gray('# Pass variables as JSON')}
   ${chalk_1.default.cyan(`${PROGRAM_NAME} query my-query.graphql --vars '{"id": 42}'`)}
 
+${chalk_1.default.bold.yellow('GRAPHQL SCHEMA EXPLORATION:')}
+  ${chalk_1.default.gray('# List all queries, mutations, and types')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} gql queries`)}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} gql mutations`)}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} gql types`)}
+
+  ${chalk_1.default.gray('# Filter by name')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} gql types --filter audit`)}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} gql queries --filter order`)}
+
+  ${chalk_1.default.gray('# Inspect a specific type')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} gql type OrderGqlDto`)}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} gql type AuditChangeEntry`)}
+
 ${chalk_1.default.bold.yellow('VALIDATION TYPES:')}
   ${chalk_1.default.bold('module')}     - CargoXplorer UI module definitions (components, routes, entities)
   ${chalk_1.default.bold('workflow')}   - CargoXplorer workflow definitions (activities, tasks, triggers)
@@ -3188,6 +3203,169 @@ async function runQuery(queryArg, variables) {
     console.log(JSON.stringify(data, null, 2));
 }
 // ============================================================================
+// GQL Schema Exploration Command
+// ============================================================================
+async function runGql(sub, filter) {
+    if (!sub) {
+        console.error(chalk_1.default.red('Error: subcommand required'));
+        console.error(chalk_1.default.gray(`Usage: ${PROGRAM_NAME} gql <queries|mutations|types|type> [name] [--filter <text>]`));
+        process.exit(2);
+    }
+    const session = resolveSession();
+    if (sub === 'type') {
+        if (!filter) {
+            console.error(chalk_1.default.red('Error: type name required'));
+            console.error(chalk_1.default.gray(`Usage: ${PROGRAM_NAME} gql type <TypeName>`));
+            process.exit(2);
+        }
+        await runGqlType(session, filter);
+    }
+    else if (sub === 'queries') {
+        await runGqlRootFields(session, 'queryType', filter);
+    }
+    else if (sub === 'mutations') {
+        await runGqlRootFields(session, 'mutationType', filter);
+    }
+    else if (sub === 'types') {
+        await runGqlTypes(session, filter);
+    }
+    else {
+        console.error(chalk_1.default.red(`Unknown gql subcommand: ${sub}`));
+        console.error(chalk_1.default.gray(`Usage: ${PROGRAM_NAME} gql <queries|mutations|types|type> [--filter <text>]`));
+        process.exit(2);
+    }
+}
+function formatGqlType(t) {
+    if (!t)
+        return 'unknown';
+    if (t.kind === 'NON_NULL')
+        return `${formatGqlType(t.ofType)}!`;
+    if (t.kind === 'LIST')
+        return `[${formatGqlType(t.ofType)}]`;
+    return t.name || 'unknown';
+}
+async function runGqlType(session, typeName) {
+    const query = `{
+    __type(name: "${typeName}") {
+      name kind description
+      fields { name description type { name kind ofType { name kind ofType { name kind ofType { name kind } } } } args { name type { name kind ofType { name kind ofType { name kind } } } defaultValue } }
+      inputFields { name type { name kind ofType { name kind ofType { name kind } } } defaultValue }
+      enumValues { name description }
+    }
+  }`;
+    const data = await graphqlRequest(session.domain, session.access_token, query, {});
+    const type = data.__type;
+    if (!type) {
+        console.error(chalk_1.default.red(`Type "${typeName}" not found`));
+        process.exit(1);
+    }
+    console.log(chalk_1.default.bold.cyan(`${type.name}`) + chalk_1.default.gray(` (${type.kind})`));
+    if (type.description)
+        console.log(chalk_1.default.gray(type.description));
+    console.log('');
+    if (type.fields && type.fields.length > 0) {
+        console.log(chalk_1.default.bold.yellow('Fields:'));
+        for (const f of type.fields) {
+            const typeStr = formatGqlType(f.type);
+            let line = `  ${chalk_1.default.green(f.name)}: ${chalk_1.default.cyan(typeStr)}`;
+            if (f.args && f.args.length > 0) {
+                const argsStr = f.args.map((a) => {
+                    const argType = formatGqlType(a.type);
+                    return a.defaultValue ? `${a.name}: ${argType} = ${a.defaultValue}` : `${a.name}: ${argType}`;
+                }).join(', ');
+                line += chalk_1.default.gray(` (${argsStr})`);
+            }
+            if (f.description)
+                line += chalk_1.default.gray(` — ${f.description}`);
+            console.log(line);
+        }
+    }
+    if (type.inputFields && type.inputFields.length > 0) {
+        console.log(chalk_1.default.bold.yellow('Input Fields:'));
+        for (const f of type.inputFields) {
+            const typeStr = formatGqlType(f.type);
+            let line = `  ${chalk_1.default.green(f.name)}: ${chalk_1.default.cyan(typeStr)}`;
+            if (f.defaultValue)
+                line += chalk_1.default.gray(` = ${f.defaultValue}`);
+            console.log(line);
+        }
+    }
+    if (type.enumValues && type.enumValues.length > 0) {
+        console.log(chalk_1.default.bold.yellow('Enum Values:'));
+        for (const v of type.enumValues) {
+            let line = `  ${chalk_1.default.green(v.name)}`;
+            if (v.description)
+                line += chalk_1.default.gray(` — ${v.description}`);
+            console.log(line);
+        }
+    }
+}
+async function runGqlRootFields(session, rootType, filter) {
+    const query = `{
+    __schema {
+      ${rootType} {
+        fields { name description args { name type { name kind ofType { name kind ofType { name kind } } } defaultValue } type { name kind ofType { name kind ofType { name kind } } } }
+      }
+    }
+  }`;
+    const data = await graphqlRequest(session.domain, session.access_token, query, {});
+    const fields = data.__schema?.[rootType]?.fields || [];
+    const filtered = filter
+        ? fields.filter((f) => f.name.toLowerCase().includes(filter.toLowerCase()))
+        : fields;
+    const label = rootType === 'queryType' ? 'Queries' : 'Mutations';
+    console.log(chalk_1.default.bold.yellow(`${label}${filter ? ` (filter: "${filter}")` : ''}:`));
+    console.log('');
+    for (const f of filtered) {
+        const returnType = formatGqlType(f.type);
+        console.log(`  ${chalk_1.default.green(f.name)}: ${chalk_1.default.cyan(returnType)}`);
+        if (f.description)
+            console.log(`    ${chalk_1.default.gray(f.description)}`);
+        if (f.args && f.args.length > 0) {
+            for (const a of f.args) {
+                const argType = formatGqlType(a.type);
+                const def = a.defaultValue ? chalk_1.default.gray(` = ${a.defaultValue}`) : '';
+                console.log(`    ${chalk_1.default.white(a.name)}: ${chalk_1.default.cyan(argType)}${def}`);
+            }
+        }
+        console.log('');
+    }
+    console.log(chalk_1.default.gray(`${filtered.length} ${label.toLowerCase()} found`));
+}
+async function runGqlTypes(session, filter) {
+    const query = `{
+    __schema {
+      types { name kind description }
+    }
+  }`;
+    const data = await graphqlRequest(session.domain, session.access_token, query, {});
+    const types = (data.__schema?.types || [])
+        .filter((t) => !t.name.startsWith('__'))
+        .filter((t) => !filter || t.name.toLowerCase().includes(filter.toLowerCase()));
+    const grouped = {};
+    for (const t of types) {
+        const kind = t.kind || 'OTHER';
+        if (!grouped[kind])
+            grouped[kind] = [];
+        grouped[kind].push(t);
+    }
+    const kindOrder = ['OBJECT', 'INPUT_OBJECT', 'ENUM', 'INTERFACE', 'UNION', 'SCALAR'];
+    for (const kind of kindOrder) {
+        const items = grouped[kind];
+        if (!items || items.length === 0)
+            continue;
+        console.log(chalk_1.default.bold.yellow(`${kind} (${items.length}):`));
+        for (const t of items.sort((a, b) => a.name.localeCompare(b.name))) {
+            let line = `  ${chalk_1.default.green(t.name)}`;
+            if (t.description)
+                line += chalk_1.default.gray(` — ${t.description}`);
+            console.log(line);
+        }
+        console.log('');
+    }
+    console.log(chalk_1.default.gray(`${types.length} types found${filter ? ` matching "${filter}"` : ''}`));
+}
+// ============================================================================
 // Extract Command
 // ============================================================================
 function runExtract(sourceFile, componentName, targetFile, copy) {
@@ -3398,7 +3576,7 @@ function parseArgs(args) {
         reportFormat: 'json'
     };
     // Check for commands
-    const commands = ['validate', 'schema', 'example', 'list', 'help', 'version', 'report', 'init', 'create', 'extract', 'sync-schemas', 'install-skills', 'update', 'setup-claude', 'login', 'logout', 'pat', 'appmodule', 'orgs', 'workflow', 'publish', 'query', 'app'];
+    const commands = ['validate', 'schema', 'example', 'list', 'help', 'version', 'report', 'init', 'create', 'extract', 'sync-schemas', 'install-skills', 'update', 'setup-claude', 'login', 'logout', 'pat', 'appmodule', 'orgs', 'workflow', 'publish', 'query', 'gql', 'app'];
     if (args.length > 0 && commands.includes(args[0])) {
         command = args[0];
         args = args.slice(1);
@@ -3509,6 +3687,9 @@ function parseArgs(args) {
                 options.file = [];
             options.file.push(args[++i]);
         }
+        else if (arg === '--filter') {
+            options.filter = args[++i];
+        }
         else if (arg === '--force') {
             options.force = true;
         }
@@ -4435,6 +4616,14 @@ async function main() {
         }
         process.exit(0);
     }
+    // Handle gql command (no schemas needed)
+    if (command === 'gql') {
+        const sub = files[0];
+        // For 'gql type <name>', the type name is in files[1] — use it as filter
+        const filterArg = sub === 'type' ? (files[1] || options.filter) : options.filter;
+        await runGql(sub, filterArg);
+        process.exit(0);
+    }
     // Handle query command (no schemas needed)
     if (command === 'query') {
         await runQuery(files[0], options.vars);