cxtms 1.9.13

package/scripts/postinstall.js

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script to create .cx-schema folder in the project root
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function findProjectRoot() {
+  let currentDir = process.cwd();
+
+  // Walk up the directory tree to find package.json
+  while (currentDir !== path.dirname(currentDir)) {
+    const packageJsonPath = path.join(currentDir, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      // Check if this is not the cx-schema-validator package itself
+      try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        if (packageJson.name !== '@cxtms/cx-schema') {
+          return currentDir;
+        }
+      } catch (error) {
+        // Continue searching
+      }
+    }
+    currentDir = path.dirname(currentDir);
+  }
+
+  return null;
+}
+
+function copyDirectory(src, dest) {
+  // Create destination directory if it doesn't exist
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  // Read directory contents
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirectory(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function createValidationScript(projectRoot) {
+  const scriptContent = `#!/usr/bin/env node
+
+/**
+ * Local validation script
+ * This script uses the schemas in .cx-schema to validate modules
+ */
+
+const { ModuleValidator } = require('@cxtms/cx-schema');
+const path = require('path');
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error('Usage: node .cx-schema/validate.js <module-file>');
+    process.exit(1);
+  }
+
+  const schemasPath = path.join(__dirname);
+  const validator = new ModuleValidator({ schemasPath });
+
+  for (const file of args) {
+    const result = await validator.validateModule(file);
+
+    console.log(\`\\nValidation result for \${file}:\`);
+    console.log(\`  Status: \${result.summary.status}\`);
+    console.log(\`  Errors: \${result.summary.errorCount}\`);
+    console.log(\`  Warnings: \${result.summary.warningCount}\`);
+
+    if (!result.isValid) {
+      console.log('\\nErrors:');
+      result.errors.forEach((error, index) => {
+        console.log(\`  [\${index + 1}] \${error.type}: \${error.message}\`);
+        console.log(\`      Path: \${error.path}\`);
+      });
+      process.exit(1);
+    }
+  }
+
+  console.log('\\nAll validations passed!');
+}
+
+main().catch(error => {
+  console.error('Error:', error);
+  process.exit(1);
+});
+`;
+
+  const scriptPath = path.join(projectRoot, '.cx-schema', 'validate.js');
+  fs.writeFileSync(scriptPath, scriptContent, 'utf-8');
+
+  // Make it executable on Unix-like systems
+  try {
+    fs.chmodSync(scriptPath, '755');
+  } catch (error) {
+    // Ignore chmod errors on Windows
+  }
+}
+
+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...');
+
+  // Find project root
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.log('Warning: Could not find project root. Skipping .cx-schema creation.');
+    return;
+  }
+
+  console.log(`Project root: ${projectRoot}`);
+
+  // Create .cx-schema directory
+  const cxSchemaDir = path.join(projectRoot, '.cx-schema');
+
+  if (fs.existsSync(cxSchemaDir)) {
+    console.log('.cx-schema directory already exists. Updating schemas...');
+  } else {
+    console.log('Creating .cx-schema directory...');
+    fs.mkdirSync(cxSchemaDir, { recursive: true });
+  }
+
+  // Copy schemas
+  const schemasSource = path.join(__dirname, '..', 'schemas');
+  console.log(`Copying schemas from ${schemasSource}...`);
+
+  try {
+    copyDirectory(schemasSource, cxSchemaDir);
+    console.log('Schemas copied successfully!');
+  } catch (error) {
+    console.error('Error copying schemas:', error.message);
+    process.exit(1);
+  }
+
+  // Create validation script
+  console.log('Creating validation script...');
+  createValidationScript(projectRoot);
+
+  // Copy Claude Code skills (clean existing first to remove stale files)
+  const skillNames = ['cxtms-developer', 'cxtms-module-builder', 'cxtms-workflow-builder'];
+  for (const skillName of skillNames) {
+    const skillSource = path.join(__dirname, '..', 'skills', skillName);
+    if (fs.existsSync(skillSource)) {
+      const skillDest = path.join(projectRoot, '.claude', 'skills', skillName);
+      console.log(`Installing ${skillName} skill...`);
+      try {
+        // Remove existing skill directory to clean up stale files
+        if (fs.existsSync(skillDest)) {
+          fs.rmSync(skillDest, { recursive: true });
+        }
+        copyDirectory(skillSource, skillDest);
+        console.log(`${skillName} skill installed successfully!`);
+      } catch (error) {
+        console.warn(`Warning: Could not install ${skillName} skill:`, error.message);
+      }
+    }
+  }
+
+  // Remove deprecated skills
+  const deprecatedSkills = ['cx-build', 'cx-core', 'cx-module', 'cx-workflow'];
+  for (const oldSkill of deprecatedSkills) {
+    const oldSkillDest = path.join(projectRoot, '.claude', 'skills', oldSkill);
+    if (fs.existsSync(oldSkillDest)) {
+      try {
+        fs.rmSync(oldSkillDest, { recursive: true });
+        console.log(`Removed deprecated ${oldSkill} skill.`);
+      } catch (error) {
+        // Ignore cleanup errors
+      }
+    }
+  }
+
+  // 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');
+  console.log('  node .cx-schema/validate.js modules/your-module.yaml');
+  console.log('  /cxtms-module-builder <description>   (Claude Code skill - UI modules)');
+  console.log('  /cxtms-workflow-builder <description>  (Claude Code skill - workflows)');
+}
+
+// Only run if this is not being installed as a dependency of cx-schema-validator itself
+if (!process.env.npm_package_name || process.env.npm_package_name !== '@cxtms/cx-schema') {
+  main();
+}

package/scripts/setup-vscode.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+/**
+ * VS Code integration setup script
+ * Creates .vscode/settings.json with YAML schema associations
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function setupVSCode(projectRoot) {
+  const vscodeDir = path.join(projectRoot, '.vscode');
+  const settingsPath = path.join(vscodeDir, 'settings.json');
+
+  // Create .vscode directory if it doesn't exist
+  if (!fs.existsSync(vscodeDir)) {
+    fs.mkdirSync(vscodeDir, { recursive: true });
+    console.log('Created .vscode directory');
+  }
+
+  // Read existing settings or create new
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      const content = fs.readFileSync(settingsPath, 'utf-8');
+      settings = JSON.parse(content);
+      console.log('Loaded existing VS Code settings');
+    } catch (error) {
+      console.warn('Could not parse existing settings.json, creating new one');
+    }
+  }
+
+  // Add or update YAML schema associations
+  if (!settings['yaml.schemas']) {
+    settings['yaml.schemas'] = {};
+  }
+
+  // Add schema mapping for module files
+  const schemaPath = path.join(projectRoot, '.cx-schema', 'schemas.json');
+  settings['yaml.schemas'][schemaPath] = [
+    'modules/*-module.yaml',
+    'modules/**/*-module.yaml'
+  ];
+
+  // Write updated settings
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
+  console.log('Updated .vscode/settings.json with schema associations');
+
+  return true;
+}
+
+function main() {
+  const projectRoot = process.cwd();
+
+  console.log('Setting up VS Code integration...');
+  console.log(`Project root: ${projectRoot}`);
+
+  if (!fs.existsSync(path.join(projectRoot, '.cx-schema'))) {
+    console.error('Error: .cx-schema directory not found.');
+    console.error('Please run npm install first to create the schema directory.');
+    process.exit(1);
+  }
+
+  try {
+    setupVSCode(projectRoot);
+    console.log('\n✓ VS Code integration setup complete!');
+    console.log('\nYour YAML module files will now have schema validation and autocomplete in VS Code.');
+    console.log('Restart VS Code for changes to take effect.');
+  } catch (error) {
+    console.error('Error setting up VS Code integration:', error.message);
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = { setupVSCode };

package/skills/cxtms-developer/SKILL.md

@@ -0,0 +1,118 @@
+---
+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>
+---
+
+Shared domain reference for CargoXplorer entities. Used by `cxtms-workflow-builder` and `cxtms-module-builder` skills for entity field names, types, navigation properties, enums, and customValues extension patterns.
+
+## Feature File Layout
+
+All modules and workflows are organized under feature directories:
+
+```
+features/
+  <feature_name>/
+    modules/          # UI module YAML files
+    workflows/        # Workflow YAML files
+```
+
+When creating new modules or workflows, always place them under the correct feature directory:
+- `features/<feature_name>/modules/<name>-module.yaml`
+- `features/<feature_name>/workflows/<name>.yaml`
+
+Use `--feature <feature_name>` with `cx-cli create` to automatically place files in the correct location.
+
+## Entity Field Reference
+
+### Primary Entities
+
+!cat skills/cxtms-developer/ref-entity-order.md
+!cat skills/cxtms-developer/ref-entity-contact.md
+!cat skills/cxtms-developer/ref-entity-commodity.md
+!cat skills/cxtms-developer/ref-entity-accounting.md
+
+### Order Sub-Entities & Related
+
+!cat skills/cxtms-developer/ref-entity-order-sub.md
+!cat skills/cxtms-developer/ref-entity-job.md
+
+### Pricing & Accounting Lookups
+
+!cat skills/cxtms-developer/ref-entity-rate.md
+
+### Shared & Lookup Entities
+
+!cat skills/cxtms-developer/ref-entity-shared.md
+!cat skills/cxtms-developer/ref-entity-geography.md
+
+### Warehouse & Inventory
+
+!cat skills/cxtms-developer/ref-entity-warehouse.md
+
+### Notifications
+
+!cat skills/cxtms-developer/ref-entity-notification.md
+
+| Category | Entities | Reference |
+|----------|----------|-----------|
+| **Primary** | Order, Contact, Commodity, AccountingTransaction | ref-entity-order/contact/commodity/accounting.md |
+| **Order sub** | OrderEntity, TrackingEvent, EventDefinition, LinkedOrder, OrderDocument | ref-entity-order-sub.md |
+| **Job** | Job, JobOrder, JobStatus | ref-entity-job.md |
+| **Pricing** | Rate, Lane, Discount, AccountingItem, AccountingAccount, PaymentTerm | ref-entity-rate.md |
+| **Shared** | Tag, Attachment, Division, EquipmentType, PackageType, Note/NoteThread | ref-entity-shared.md |
+| **Geography** | Country, State, City, Port, Vessel, CustomCode, ModeOfTransportation | ref-entity-geography.md |
+| **Warehouse** | InventoryItem, WarehouseLocation, CargoMovement (Order variant) | ref-entity-warehouse.md |
+| **Notification** | Notification, UserNotification | ref-entity-notification.md |
+
+## CustomValues Pattern
+
+Most entities have `customValues` — a `Dictionary<string, object?>` stored as PostgreSQL `jsonb`:
+
+- **Access (workflow)**: `{{ entity.customValues.fieldName }}` or `{{ entity.customValues['field-name'] }}`
+- **Access (module)**: `customValues.fieldName` in GraphQL sort/filter paths
+- **Update (workflow)**: `CustomValues.fieldName: "value"` (dot notation) or `customValues: { field: "value" }` (bulk merge)
+- **Merge semantics**: upserts keys — does **not** replace entire dictionary
+- **Full-text searchable**: included in PostgreSQL `tsvector` via `jsonb_to_tsvector`
+- **GraphQL sort/filter**: use `CustomValues.fieldName` path — translates to `jsonb_extract_path_text`
+
+### Entities with customValues
+
+**Primary entities**: Order, Contact, Commodity, AccountingTransaction, Charge, Payment
+
+**Sub-entities**: OrderEntity, OrderCommodity, ContactAddress, ContactPaymentMethod, CommodityType, CommodityTag, OrderTag, LinkedOrder, InventoryItemTag
+
+**Lookup entities**: Job, JobStatus, Tag, Attachment, EventDefinition, Rate, Lane, Discount, AccountingItem, Port, Country, State, City, ModeOfTransportation
+
+**Without customValues**: Division, EquipmentType, PackageType, Vessel, CustomCode, AccountingAccount, PaymentTerm, WarehouseLocation, JobOrder
+
+### Audit Fields (AuditableEntity)
+
+Most entities inherit these fields:
+
+| Field | Type |
+|-------|------|
+| `created` | `DateTime` |
+| `createdBy` | `string` (user ID) |
+| `lastModified` | `DateTime` |
+| `lastModifiedBy` | `string` (user ID) |
+| `createdUser` | `User` navigation |
+| `updatedUser` | `User` navigation |
+
+### Entity Kind Mapping
+
+Used in module `entityKind` and Flow workflow `entity.name`:
+
+| EntityKind | Entities |
+|------------|----------|
+| `Order` | Order (all types: Brokerage, ParcelShipment, Quote, WarehouseReceipt, etc.) |
+| `Contact` | Contact (all types: Customer, Carrier, Vendor, Driver, Employee, etc.) |
+| `OrderEntity` | OrderEntity (Shipper, Consignee, Carrier roles on an order) |
+| `AccountingTransaction` | Invoice, Bill, CreditMemo |
+| `Commodity` | Commodity |
+| `Calendar` | CalendarEntity |
+| `CalendarEvent` | CalendarEvent |
+| `Other` | Any custom entity |

package/skills/cxtms-developer/ref-cli-auth.md

@@ -0,0 +1,120 @@
+# CX Server Authentication & Management
+
+## Contents
+- Authentication (OAuth2 login/logout)
+- PAT Tokens (CI/CD alternative to OAuth)
+- Organization Management
+- Session Resolution
+- Publish (push modules and workflows to server)
+
+## Authentication
+
+```bash
+# Login to a CX environment (OAuth2 + PKCE — opens browser)
+npx cxtms login https://tms-v3-dev.usatrt.com
+
+# Logout from current session
+npx cxtms 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 cxtms pat setup
+
+# Create a new PAT token (requires OAuth login first)
+npx cxtms pat create "my-ci-token"
+
+# List active PAT tokens
+npx cxtms pat list
+
+# Revoke a PAT token
+npx cxtms 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 cxtms orgs list
+
+# Select an organization interactively
+npx cxtms orgs select
+
+# Set active organization by ID
+npx cxtms orgs use <orgId>
+
+# Show current context (server, org, app)
+npx cxtms orgs use
+```
+
+The active org is cached in the session file and used by all server commands. **Always pass `--org <id>` on deploy/undeploy/release/execute/logs commands** to avoid the interactive org picker blocking automation.
+
+## 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 cxtms publish
+
+# Publish only a specific feature directory
+npx cxtms publish --feature billing
+npx cxtms publish billing
+
+# Publish with explicit org ID
+npx cxtms publish --org 42
+```
+
+Validates all YAML files first, then pushes modules and workflows to the server. Skips files with validation errors and reports results.
+
+## App Manifest Management
+
+Server-side app manifest operations — install from git, release changes to git, and list installed apps.
+
+```bash
+# Install/refresh app from its git repository into the CX server
+npx cxtms app install
+
+# Force reinstall even if same version is already installed
+npx cxtms app install --force
+
+# Install from a specific branch
+npx cxtms app install --branch develop
+
+# Install but skip modules that have unpublished local changes
+npx cxtms app install --skip-changed
+
+# Release server changes to git (creates a PR) — message is required
+npx cxtms app release -m "Add new shipping module"
+
+# Force release all modules and workflows (not just changed ones)
+npx cxtms app release -m "Full republish" --force
+
+# List installed app manifests on the server
+npx cxtms app list
+```
+
+**`app install`** reads `repository` and `branch` from `app.yaml`, downloads the repo on the server side, and installs/updates all modules and workflows. Use `--force` to reinstall even if the version hasn't changed. Use `--skip-changed` to preserve modules with unpublished changes.
+
+**`app release`** takes the current server state and releases it to git by creating a PR. Requires a `-m` message describing the changes (like a git commit message). The server increments the version, creates a release branch, commits all module/workflow YAML files, and opens a pull request to the target branch.
+
+**`app list`** shows all installed app manifests with their version, status flags (disabled, unpublished changes, update available), and repository info.