@cxtms/cx-schema 1.7.6 → 1.7.8

package/.claude/skills/cx-core/ref-cli-auth.md

@@ -61,7 +61,7 @@ npx cxtms orgs use <orgId>
 npx cxtms orgs use
 ```
 
-The active org is cached in the session file and used by all server commands. Override with `--org <id>`.
+The active org is cached in the session file and used by all server commands. **Always pass `--org <id>` on deploy/undeploy/publish/execute/logs commands** to avoid the interactive org picker blocking automation.
 
 ## Session Resolution
 
@@ -85,3 +85,39 @@ 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, publish 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
+
+# Publish server changes to git (creates a PR)
+npx cxtms app publish
+
+# Publish with a custom commit message
+npx cxtms app publish --message "Add new shipping module"
+
+# Force publish all modules and workflows (not just changed ones)
+npx cxtms app publish --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 publish`** takes the current server state and publishes it to git by creating a PR. The server increments the version, creates a publish 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.

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

@@ -18,9 +18,9 @@ You are a CargoXplorer module YAML builder. You generate schema-valid YAML for C
 - **List schemas**: `npx cxtms list`
 - **Extract**: `npx cxtms extract <source> <component> --to <target>` — move components between modules
 - **Feature folder**: `npx cxtms create module <name> --template <template> --feature <feature-name>`
-- **Deploy to server**: `npx cxtms appmodule deploy <file.yaml>` — creates or updates module on the CX server
-- **Undeploy from server**: `npx cxtms appmodule undeploy <appModuleId>` — removes a module by UUID
-- **Publish all**: `npx cxtms publish [--feature <name>]` — push all modules and workflows to the server
+- **Deploy to server**: `npx cxtms appmodule deploy <file.yaml> --org <id>` — creates or updates module on the CX server
+- **Undeploy from server**: `npx cxtms appmodule undeploy <appModuleId> --org <id>` — removes a module by UUID
+- **Publish all**: `npx cxtms publish [--feature <name>] --org <id>` — push all modules and workflows to the server
 
 ## Generation Workflow
 

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

@@ -16,12 +16,12 @@ You are a CargoXplorer workflow YAML builder. You generate schema-valid YAML for
 - **Examples**: `npx cxtms example <task>` — show example YAML for a task
 - **List schemas**: `npx cxtms list --type workflow` — shows all available task schemas in the Tasks section
 - **Feature folder**: `npx cxtms create workflow <name> --template <template> --feature <feature-name>`
-- **Deploy to server**: `npx cxtms workflow deploy <file.yaml>` — creates or updates workflow on the CX server
-- **Undeploy from server**: `npx cxtms workflow undeploy <workflowId>` — removes a workflow by UUID
-- **Execute**: `npx cxtms workflow execute <workflowId|file.yaml> [--vars '<json>']` — trigger a workflow execution
-- **List logs**: `npx cxtms workflow logs <workflowId|file.yaml> [--from YYYY-MM-DD] [--to YYYY-MM-DD]` — list executions with log availability
-- **Download log**: `npx cxtms workflow log <executionId> [--json] [--console] [--output <file>]` — download execution log
-- **Publish all**: `npx cxtms publish [--feature <name>]` — push all modules and workflows to the server
+- **Deploy to server**: `npx cxtms workflow deploy <file.yaml> --org <id>` — creates or updates workflow on the CX server
+- **Undeploy from server**: `npx cxtms workflow undeploy <workflowId> --org <id>` — removes a workflow by UUID
+- **Execute**: `npx cxtms workflow execute <workflowId|file.yaml> --org <id> [--vars '<json>']` — trigger a workflow execution
+- **List logs**: `npx cxtms workflow logs <workflowId|file.yaml> --org <id> [--from YYYY-MM-DD] [--to YYYY-MM-DD]` — list executions with log availability
+- **Download log**: `npx cxtms workflow log <executionId> --org <id> [--json] [--console] [--output <file>]` — download execution log
+- **Publish all**: `npx cxtms publish [--feature <name>] --org <id>` — push all modules and workflows to the server
 
 ## Generation Workflow
 

package/dist/cli.js

@@ -117,6 +117,7 @@ ${chalk_1.default.bold.yellow('COMMANDS:')}
   ${chalk_1.default.green('appmodule')}       Manage app modules on a CX server (deploy, undeploy)
   ${chalk_1.default.green('workflow')}        Manage workflows on a CX server (deploy, undeploy, execute, logs, log)
   ${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('schema')}          Show JSON schema for a component or task
   ${chalk_1.default.green('example')}         Show example YAML for a component or task
@@ -147,6 +148,10 @@ ${chalk_1.default.bold.yellow('OPTIONS:')}
   ${chalk_1.default.green('--output <file>')}        Save workflow log to file (or -o)
   ${chalk_1.default.green('--console')}              Print workflow log to stdout
   ${chalk_1.default.green('--json')}                 Download JSON log instead of text
+  ${chalk_1.default.green('-m, --message <msg>')}     Commit message for app publish
+  ${chalk_1.default.green('-b, --branch <branch>')}   Branch override for app install/publish
+  ${chalk_1.default.green('--force')}                Force install (even if same version) or publish all
+  ${chalk_1.default.green('--skip-changed')}         Skip modules with unpublished changes during install
 
 ${chalk_1.default.bold.yellow('VALIDATION EXAMPLES:')}
   ${chalk_1.default.gray('# Validate a module YAML file')}
@@ -288,6 +293,35 @@ ${chalk_1.default.bold.yellow('PUBLISH COMMANDS:')}
   ${chalk_1.default.gray('# Publish with explicit org ID')}
   ${chalk_1.default.cyan(`${PROGRAM_NAME} publish --org 42`)}
 
+${chalk_1.default.bold.yellow('APP COMMANDS:')}
+  ${chalk_1.default.gray('# Install/refresh app from git repository into the CX server')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} app install`)}
+
+  ${chalk_1.default.gray('# Force reinstall even if same version')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} app install --force`)}
+
+  ${chalk_1.default.gray('# Install from a specific branch')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} app install --branch develop`)}
+
+  ${chalk_1.default.gray('# Install but skip modules that have local changes')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} app install --skip-changed`)}
+
+  ${chalk_1.default.gray('# Upgrade app from git (alias for install)')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} app upgrade`)}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} app upgrade --force`)}
+
+  ${chalk_1.default.gray('# Publish server changes to git (creates a PR)')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} app publish`)}
+
+  ${chalk_1.default.gray('# Publish with a custom commit message')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} app publish --message "Add new shipping module"`)}
+
+  ${chalk_1.default.gray('# Force publish all modules and workflows')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} app publish --force`)}
+
+  ${chalk_1.default.gray('# List installed app manifests on the server')}
+  ${chalk_1.default.cyan(`${PROGRAM_NAME} app list`)}
+
 ${chalk_1.default.bold.yellow('QUERY COMMANDS:')}
   ${chalk_1.default.gray('# Run an inline GraphQL query')}
   ${chalk_1.default.cyan(`${PROGRAM_NAME} query '{ organizations(take: 5) { items { organizationId companyName } } }'`)}
@@ -840,6 +874,23 @@ function applyFieldsToForm(form, fields) {
         }
     }
 }
+function applyFieldsToConfiguration(layout, fields) {
+    // Configuration fields are stored under customValues, so prefix all field names
+    const configFields = fields.map(f => ({
+        component: 'field',
+        name: `customValues.${f.name}`,
+        props: {
+            type: f.type,
+            label: { 'en-US': f.label || fieldNameToLabel(f.name) },
+            ...(f.required ? { required: true } : {})
+        }
+    }));
+    if (!layout.children)
+        layout.children = [];
+    layout.children.push(...configFields);
+    // Update defaultValue in configurations if present
+    // (handled separately since configurations is a top-level key)
+}
 function findDataGridComponents(obj) {
     const grids = [];
     if (!obj || typeof obj !== 'object')
@@ -967,9 +1018,16 @@ function applyCreateOptions(content, optionsArg) {
     if (!doc)
         throw new Error('Failed to parse template YAML for --options processing');
     let applied = false;
+    const isConfiguration = Array.isArray(doc.configurations);
     if (doc.components && Array.isArray(doc.components)) {
         for (const comp of doc.components) {
-            // Apply to form components (configuration template)
+            // Apply to configuration templates (fields go directly into layout children)
+            if (isConfiguration && comp.layout) {
+                applyFieldsToConfiguration(comp.layout, fields);
+                applied = true;
+                continue;
+            }
+            // Apply to form components
             const forms = findFormComponents(comp);
             for (const form of forms) {
                 applyFieldsToForm(form, fields);
@@ -997,6 +1055,18 @@ function applyCreateOptions(content, optionsArg) {
         applyFieldsToEntities(doc, fields, opts.entityName);
         applied = true;
     }
+    // Apply defaults to configuration defaultValue
+    if (isConfiguration && doc.configurations) {
+        for (const config of doc.configurations) {
+            if (!config.defaultValue)
+                config.defaultValue = {};
+            for (const f of fields) {
+                if (f.default !== undefined) {
+                    config.defaultValue[f.name] = f.default;
+                }
+            }
+        }
+    }
     if (!applied) {
         console.warn(chalk_1.default.yellow('Warning: --options provided but no form or dataGrid component found in template'));
         return content;
@@ -2763,6 +2833,192 @@ async function runPublish(featureDir, orgOverride) {
     }
 }
 // ============================================================================
+// App Manifest Commands (install from git, publish to git, list)
+// ============================================================================
+function readAppYaml() {
+    const appYamlPath = path.join(process.cwd(), 'app.yaml');
+    if (!fs.existsSync(appYamlPath)) {
+        console.error(chalk_1.default.red('Error: app.yaml not found in current directory'));
+        process.exit(2);
+    }
+    return yaml_1.default.parse(fs.readFileSync(appYamlPath, 'utf-8'));
+}
+async function runAppInstall(orgOverride, branch, force, skipChanged) {
+    const session = resolveSession();
+    const domain = session.domain;
+    const token = session.access_token;
+    const orgId = await resolveOrgId(domain, token, orgOverride);
+    const appYaml = readAppYaml();
+    const repository = appYaml.repository;
+    if (!repository) {
+        console.error(chalk_1.default.red('Error: app.yaml must have a `repository` field'));
+        process.exit(2);
+    }
+    const repositoryBranch = branch || appYaml.branch || 'main';
+    console.log(chalk_1.default.bold.cyan('\n  App Install\n'));
+    console.log(chalk_1.default.gray(`  Server:     ${new URL(domain).hostname}`));
+    console.log(chalk_1.default.gray(`  Org:        ${orgId}`));
+    console.log(chalk_1.default.gray(`  Repository: ${repository}`));
+    console.log(chalk_1.default.gray(`  Branch:     ${repositoryBranch}`));
+    if (force)
+        console.log(chalk_1.default.gray(`  Force:      yes`));
+    if (skipChanged)
+        console.log(chalk_1.default.gray(`  Skip changed: yes`));
+    console.log('');
+    try {
+        const data = await graphqlRequest(domain, token, `
+      mutation ($input: InstallAppManifestInput!) {
+        installAppManifest(input: $input) {
+          appManifest {
+            appManifestId
+            name
+            currentVersion
+            isEnabled
+            hasUnpublishedChanges
+            isUpdateAvailable
+          }
+        }
+      }
+    `, {
+            input: {
+                organizationId: orgId,
+                values: {
+                    repository,
+                    repositoryBranch,
+                    force: force || false,
+                    skipModulesWithChanges: skipChanged || false,
+                }
+            }
+        });
+        const manifest = data?.installAppManifest?.appManifest;
+        if (manifest) {
+            console.log(chalk_1.default.green(`  ✓ Installed ${manifest.name} v${manifest.currentVersion}`));
+            if (manifest.hasUnpublishedChanges) {
+                console.log(chalk_1.default.yellow(`    Has unpublished changes`));
+            }
+        }
+        else {
+            console.log(chalk_1.default.green('  ✓ Install completed'));
+        }
+    }
+    catch (e) {
+        console.error(chalk_1.default.red(`  ✗ Install failed: ${e.message}`));
+        process.exit(1);
+    }
+    console.log('');
+}
+async function runAppPublish(orgOverride, message, branch, force) {
+    const session = resolveSession();
+    const domain = session.domain;
+    const token = session.access_token;
+    const orgId = await resolveOrgId(domain, token, orgOverride);
+    const appYaml = readAppYaml();
+    const appManifestId = appYaml.id;
+    if (!appManifestId) {
+        console.error(chalk_1.default.red('Error: app.yaml must have an `id` field'));
+        process.exit(2);
+    }
+    console.log(chalk_1.default.bold.cyan('\n  App Publish\n'));
+    console.log(chalk_1.default.gray(`  Server:  ${new URL(domain).hostname}`));
+    console.log(chalk_1.default.gray(`  Org:     ${orgId}`));
+    console.log(chalk_1.default.gray(`  App:     ${appYaml.name || appManifestId}`));
+    if (message)
+        console.log(chalk_1.default.gray(`  Message: ${message}`));
+    if (branch)
+        console.log(chalk_1.default.gray(`  Branch:  ${branch}`));
+    if (force)
+        console.log(chalk_1.default.gray(`  Force:   yes`));
+    console.log('');
+    try {
+        const data = await graphqlRequest(domain, token, `
+      mutation ($input: PublishAppManifestInput!) {
+        publishAppManifest(input: $input) {
+          appManifest {
+            appManifestId
+            name
+            currentVersion
+            hasUnpublishedChanges
+          }
+        }
+      }
+    `, {
+            input: {
+                organizationId: orgId,
+                appManifestId,
+                values: {
+                    message: message || undefined,
+                    branch: branch || undefined,
+                    force: force || false,
+                }
+            }
+        });
+        const manifest = data?.publishAppManifest?.appManifest;
+        if (manifest) {
+            console.log(chalk_1.default.green(`  ✓ Published ${manifest.name} v${manifest.currentVersion}`));
+        }
+        else {
+            console.log(chalk_1.default.green('  ✓ Publish completed'));
+        }
+    }
+    catch (e) {
+        console.error(chalk_1.default.red(`  ✗ Publish failed: ${e.message}`));
+        process.exit(1);
+    }
+    console.log('');
+}
+async function runAppList(orgOverride) {
+    const session = resolveSession();
+    const domain = session.domain;
+    const token = session.access_token;
+    const orgId = await resolveOrgId(domain, token, orgOverride);
+    console.log(chalk_1.default.bold.cyan('\n  App Manifests\n'));
+    console.log(chalk_1.default.gray(`  Server: ${new URL(domain).hostname}`));
+    console.log(chalk_1.default.gray(`  Org:    ${orgId}\n`));
+    try {
+        const data = await graphqlRequest(domain, token, `
+      query ($organizationId: Int!) {
+        appManifests(organizationId: $organizationId) {
+          items {
+            appManifestId
+            name
+            currentVersion
+            isEnabled
+            hasUnpublishedChanges
+            isUpdateAvailable
+            repository
+            repositoryBranch
+          }
+        }
+      }
+    `, { organizationId: orgId });
+        const items = data?.appManifests?.items || [];
+        if (items.length === 0) {
+            console.log(chalk_1.default.gray('  No app manifests installed\n'));
+            return;
+        }
+        for (const app of items) {
+            const flags = [];
+            if (!app.isEnabled)
+                flags.push(chalk_1.default.red('disabled'));
+            if (app.hasUnpublishedChanges)
+                flags.push(chalk_1.default.yellow('unpublished'));
+            if (app.isUpdateAvailable)
+                flags.push(chalk_1.default.cyan('update available'));
+            const flagStr = flags.length > 0 ? ` [${flags.join(', ')}]` : '';
+            console.log(`  ${chalk_1.default.bold(app.name)} ${chalk_1.default.gray(`v${app.currentVersion}`)}${flagStr}`);
+            console.log(chalk_1.default.gray(`    ID:   ${app.appManifestId}`));
+            if (app.repository) {
+                console.log(chalk_1.default.gray(`    Repo: ${app.repository} (${app.repositoryBranch || 'main'})`));
+            }
+        }
+        console.log('');
+    }
+    catch (e) {
+        console.error(chalk_1.default.red(`  ✗ Failed to list apps: ${e.message}`));
+        process.exit(1);
+    }
+}
+// ============================================================================
 // Query Command
 // ============================================================================
 async function runQuery(queryArg, variables) {
@@ -3008,7 +3264,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'];
+    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'];
     if (args.length > 0 && commands.includes(args[0])) {
         command = args[0];
         args = args.slice(1);
@@ -3108,6 +3364,18 @@ function parseArgs(args) {
         else if (arg === '--console') {
             options.console = true;
         }
+        else if (arg === '--message' || arg === '-m') {
+            options.message = args[++i];
+        }
+        else if (arg === '--branch' || arg === '-b') {
+            options.branch = args[++i];
+        }
+        else if (arg === '--force') {
+            options.force = true;
+        }
+        else if (arg === '--skip-changed') {
+            options.skipChanged = true;
+        }
         else if (!arg.startsWith('-')) {
             files.push(arg);
         }
@@ -4009,6 +4277,25 @@ async function main() {
         await runPublish(files[0] || options.feature, options.orgId);
         process.exit(0);
     }
+    // Handle app command (no schemas needed)
+    if (command === 'app') {
+        const sub = files[0];
+        if (sub === 'install' || sub === 'upgrade') {
+            await runAppInstall(options.orgId, options.branch, options.force, options.skipChanged);
+        }
+        else if (sub === 'publish') {
+            await runAppPublish(options.orgId, options.message, options.branch, options.force);
+        }
+        else if (sub === 'list' || !sub) {
+            await runAppList(options.orgId);
+        }
+        else {
+            console.error(chalk_1.default.red(`Unknown app subcommand: ${sub}`));
+            console.error(chalk_1.default.gray(`Usage: ${PROGRAM_NAME} app <install|upgrade|publish|list>`));
+            process.exit(2);
+        }
+        process.exit(0);
+    }
     // Handle query command (no schemas needed)
     if (command === 'query') {
         await runQuery(files[0], options.vars);