@cxtms/cx-schema 1.6.1 → 1.6.4

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

@@ -6,6 +6,91 @@ argument-hint: <entity name or question about fields>
 
 Shared domain reference for CargoXplorer entities. Used by `cx-workflow` and `cx-module` skills for entity field names, types, navigation properties, enums, and customValues extension patterns.
 
+## CX Server Authentication & Management
+
+The CLI can authenticate against CX environments and manage server resources. Auth is required for push, delete, execute, logs, publish, and org commands.
+
+### Authentication
+
+```bash
+# Login to a CX environment (OAuth2 + PKCE — opens browser)
+npx cx-cli login https://tms-v3-dev.usatrt.com
+
+# Logout from current session
+npx cx-cli logout
+```
+
+The session is stored at `~/.cxtms/<project-dir>/.session.json`, scoped by project directory name. Each project gets its own server session. The CLI auto-refreshes expired tokens.
+
+### PAT Tokens (alternative to OAuth)
+
+For CI/CD or headless environments, use Personal Access Tokens instead of interactive OAuth:
+
+```bash
+# Check PAT status and setup instructions
+npx cx-cli pat setup
+
+# Create a new PAT token (requires OAuth login first)
+npx cx-cli pat create "my-ci-token"
+
+# List active PAT tokens
+npx cx-cli pat list
+
+# Revoke a PAT token
+npx cx-cli pat revoke <tokenId>
+```
+
+After creating a PAT, add to `.env` in your project root:
+```
+CXTMS_AUTH=pat_xxxxx...
+CXTMS_SERVER=https://tms-v3-dev.usatrt.com
+```
+
+When `CXTMS_AUTH` is set, the CLI skips OAuth and uses the PAT token directly. `CXTMS_SERVER` provides the server URL (or set `server` in `app.yaml`).
+
+### Organization Management
+
+```bash
+# List organizations on the server
+npx cx-cli orgs list
+
+# Select an organization interactively
+npx cx-cli orgs select
+
+# Set active organization by ID
+npx cx-cli orgs use <orgId>
+
+# Show current context (server, org, app)
+npx cx-cli orgs use
+```
+
+The active org is cached in the session file and used by all server commands. Override with `--org <id>`.
+
+### Session Resolution
+
+Server commands resolve the target session in this order:
+1. `CXTMS_AUTH` env var → PAT token auth (with `CXTMS_SERVER` or `app.yaml` server field)
+2. `~/.cxtms/<project-dir>/.session.json` → project-scoped OAuth session
+3. Not logged in → error
+
+### Publish
+
+```bash
+# Publish all modules and workflows from current project
+npx cx-cli publish
+
+# Publish only a specific feature directory
+npx cx-cli publish --feature billing
+npx cx-cli publish billing
+
+# Publish with explicit org ID
+npx cx-cli publish --org 42
+```
+
+Validates all YAML files first, then pushes modules and workflows to the server. Skips files with validation errors and reports results.
+
+---
+
 ## Feature File Layout
 
 All modules and workflows are organized under feature directories:

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

@@ -15,6 +15,9 @@ You are a CargoXplorer module YAML builder. You generate schema-valid YAML for C
 - **List schemas**: `npx cx-cli list`
 - **Extract**: `npx cx-cli extract <source> <component> --to <target>` — move components between modules
 - **Feature folder**: `npx cx-cli create module <name> --template <template> --feature <feature-name>`
+- **Push to server**: `npx cx-cli appmodule push <file.yaml>` — creates or updates module on the CX server
+- **Delete from server**: `npx cx-cli appmodule delete <appModuleId>` — removes a module by UUID
+- **Publish all**: `npx cx-cli publish [--feature <name>]` — push all modules and workflows to the server
 
 ## Generation Workflow
 
@@ -384,6 +387,29 @@ Reusable select components (e.g., `Countries/Select`, `Ports/Select`) follow thi
 
 ---
 
+## Server Module Commands
+
+### Push / Delete
+
+```bash
+# Push a module YAML to the server (creates or updates)
+npx cx-cli appmodule push modules/my-module.yaml
+
+# Push with explicit org ID
+npx cx-cli appmodule push modules/my-module.yaml --org 42
+
+# Delete an app module by UUID
+npx cx-cli appmodule delete <appModuleId>
+
+# Publish all modules and workflows (validates first)
+npx cx-cli publish
+npx cx-cli publish --feature billing
+```
+
+Push reads `module.appModuleId` from the YAML, queries the server, and creates or updates accordingly. Requires an active session (`cx-cli login` or PAT token — see cx-core skill).
+
+---
+
 # Generation Rules
 
 1. **Always scaffold via `cx-cli create module` first** — never write YAML from scratch, never copy templates manually

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

@@ -13,6 +13,12 @@ You are a CargoXplorer workflow YAML builder. You generate schema-valid YAML for
 - **Examples**: `npx cx-cli example <task>` — show example YAML for a task
 - **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>`
+- **Push to server**: `npx cx-cli workflow push <file.yaml>` — creates or updates workflow on the CX server
+- **Delete from server**: `npx cx-cli workflow delete <workflowId>` — removes a workflow by UUID
+- **Execute**: `npx cx-cli workflow execute <workflowId|file.yaml> [--vars '<json>']` — trigger a workflow execution
+- **List logs**: `npx cx-cli workflow logs <workflowId|file.yaml> [--from YYYY-MM-DD] [--to YYYY-MM-DD]` — list executions with log availability
+- **Download log**: `npx cx-cli workflow log <executionId> [--json] [--console] [--output <file>]` — download execution log
+- **Publish all**: `npx cx-cli publish [--feature <name>]` — push all modules and workflows to the server
 
 ## Generation Workflow
 
@@ -307,14 +313,71 @@ Implicit variable: `iteration` (zero-based).
 
 ---
 
-## Debugging Workflow Executions
+## Server Workflow Commands
 
-When TMS MCP returns gzip file URLs for workflow execution logs, decompress with:
+### Push / Delete
 
 ```bash
-node -e "const https=require('https'),zlib=require('zlib'),fs=require('fs');https.get(process.argv[1],r=>r.pipe(zlib.createGunzip()).pipe(fs.createWriteStream(process.argv[2])))" "<url>" "<output-file>"
+# Push a workflow YAML to the server (creates or updates)
+npx cx-cli workflow push workflows/my-workflow.yaml
+
+# Delete a workflow by UUID
+npx cx-cli workflow delete <workflowId>
+
+# Publish all modules and workflows (validates first)
+npx cx-cli publish
+npx cx-cli publish --feature billing
+```
+
+Push reads `workflow.workflowId` from the YAML, queries the server, and creates or updates accordingly. Requires an active session (`cx-cli login` or PAT token — see cx-core skill).
+
+### Execute
+
+```bash
+# Execute a workflow by UUID or YAML file
+npx cx-cli workflow execute <workflowId>
+npx cx-cli workflow execute workflows/my-workflow.yaml
+
+# Pass input variables as JSON
+npx cx-cli workflow execute <workflowId> --vars '{"city": "London", "count": 5}'
+```
+
+Returns execution result including `executionId`, `isAsync`, `outputs` (for Sync workflows).
+
+### Execution Logs
+
+```bash
+# List executions with log availability (sorted desc by date)
+npx cx-cli workflow logs <workflowId|file.yaml>
+
+# Filter by date range
+npx cx-cli workflow logs <workflowId> --from 2026-01-01 --to 2026-01-31
+
+# Download a specific execution log (saves to temp dir by default)
+npx cx-cli workflow log <executionId>
+
+# Save to specific file
+npx cx-cli workflow log <executionId> --output mylog.txt
+
+# Print to stdout
+npx cx-cli workflow log <executionId> --console
+
+# Download JSON log (richer data: inputs, outputs, timing, metadata)
+npx cx-cli workflow log <executionId> --json
+
+# JSON log to stdout
+npx cx-cli workflow log <executionId> --json --console
 ```
 
+`workflow logs` shows a table with execution status, date, duration, user, and log availability indicators (filled/empty circle). `workflow log` downloads the actual log content from the server (gzip-compressed S3 URLs).
+
+### Debugging Tips
+
+- Use `--json` for detailed structured data (ExecutionId, Inputs, Outputs, Exception, timing)
+- Text logs show step-by-step execution trace with timestamps
+- Sync workflow executions may not appear in `workflow logs` — they return results inline
+- Use `workflow execute --vars` to test workflows with specific inputs
+
 ---
 
 ## Generation Rules