mx-empty-captions 1.0.0

package/README.md

@@ -0,0 +1,138 @@
+# mx-empty-captions
+
+CLI tool that scans a Mendix app for **Exclusive Split** (decision) activities with empty captions, then writes the results to a JSON file.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) v18 or later
+- A Mendix **Personal Access Token (PAT)**
+- Your Mendix **App ID** (Project ID)
+
+## Quick start
+
+### Run without installing
+
+```bash
+npx mx-empty-captions --help
+```
+
+### Install globally
+
+```bash
+npm install -g mx-empty-captions
+```
+
+### Set your PAT
+
+The Mendix Platform SDK reads your token from the `MENDIX_TOKEN` environment variable.
+
+**Linux / macOS:**
+
+```bash
+export MENDIX_TOKEN="your-pat-here"
+```
+
+**Windows (PowerShell):**
+
+```powershell
+$env:MENDIX_TOKEN = "your-pat-here"
+```
+
+**Windows (cmd):**
+
+```cmd
+set MENDIX_TOKEN=your-pat-here
+```
+
+Alternatively, pass `--token` on the command line (less secure in shared environments).
+
+### Create a PAT
+
+1. Open the [Mendix Developer Portal](https://sprintr.home.mendix.com/).
+2. Go to your profile → **Personal Access Tokens**.
+3. Create a token with access to the app you want to scan.
+
+Official guide: [Set up your PAT](https://docs.mendix.com/apidocs-mxsdk/mxsdk/setup-your-pat/)
+
+> **Warning:** Never commit a real PAT to Git or share it in scripts.
+
+### Find your App ID
+
+1. Open [Mendix Developer Portal](https://sprintr.home.mendix.com/).
+2. Open the app you want to scan.
+3. Copy the UUID from the app URL:
+
+```
+https://sprintr.home.mendix.com/link/myapps/<APP-ID-HERE>
+```
+
+Example: `81977b9a-2dfa-4f2d-b179-b72ea4b00e20`
+
+## Usage
+
+```bash
+mx-empty-captions --app-id 81977b9a-2dfa-4f2d-b179-b72ea4b00e20
+```
+
+```bash
+mx-empty-captions -a 81977b9a-2dfa-4f2d-b179-b72ea4b00e20 -b trunk -o results.json
+```
+
+### Options
+
+| Option      | Short | Required | Default                     | Description                             |
+| ----------- | ----- | -------- | --------------------------- | --------------------------------------- |
+| `--app-id`  | `-a`  | Yes      | —                           | Mendix app ID (Project ID)              |
+| `--branch`  | `-b`  | No       | `main`                      | Team Server branch for the working copy |
+| `--output`  | `-o`  | No       | `found_Empty_Captions.json` | Output JSON file path                   |
+| `--token`   | `-t`  | No       | —                           | PAT (overrides `MENDIX_TOKEN`)          |
+| `--help`    | `-h`  | No       | —                           | Show help                               |
+| `--version` | `-V`  | No       | —                           | Show version                            |
+
+## Output
+
+After a successful run, the tool creates a JSON file (default: `found_Empty_Captions.json` in the current directory).
+
+Example:
+
+```json
+[
+  {
+    "module": "MyFirstModule",
+    "microflows": [
+      {
+        "microflow": "MyFirstLogic",
+        "emptyCaptions": 1
+      }
+    ]
+  }
+]
+```
+
+Each module appears once. Under `microflows`, each entry lists a microflow and how many decision activities have an empty caption.
+
+## Troubleshooting
+
+| Error                           | Likely cause                                                                                |
+| ------------------------------- | ------------------------------------------------------------------------------------------- |
+| `No Mendix PAT found`           | Set `MENDIX_TOKEN` or pass `--token`                                                        |
+| `RS400` / branch does not exist | Wrong branch — try `trunk` instead of `main` with `-b trunk`                                |
+| Authentication failed           | PAT expired, revoked, or missing permissions for the app                                    |
+| App not found                   | Request failed, POST '/v1/temporary-working-copies/' message: Response code 403 (Forbidden) |
+
+## Development
+
+Clone the repo and install dependencies:
+
+```bash
+git clone <repo-url>
+cd MX_SDK_GetEmptyCaptionsOnDecisions
+npm install
+npm run build
+npm link
+mx-empty-captions --help
+```
+
+## License
+
+ISC

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import * as mendixPlatformSDK from "mendixplatformsdk";
+import { scanEmptyCaptions } from "./scan.js";
+function resolveToken(cliToken) {
+    return cliToken ?? process.env.MENDIX_TOKEN;
+}
+const program = new Command();
+program
+    .name("mx-empty-captions")
+    .description("Scan a Mendix app for decision activities (Exclusive Split) with empty captions")
+    .version("1.0.0")
+    .requiredOption("-a, --app-id <uuid>", "Mendix app ID (Project ID)")
+    .option("-b, --branch <name>", "Team Server branch", "main")
+    .option("-o, --output <path>", "Output JSON file path", "found_Empty_Captions.json")
+    .option("-t, --token <pat>", "Mendix Personal Access Token (defaults to MENDIX_TOKEN env var)")
+    .action(async (options) => {
+    const token = resolveToken(options.token);
+    if (!token) {
+        console.error("Error: No Mendix PAT found. Set MENDIX_TOKEN or pass --token.");
+        process.exit(1);
+    }
+    if (options.token) {
+        mendixPlatformSDK.setPlatformConfig({ mendixToken: token });
+    }
+    try {
+        const results = await scanEmptyCaptions({
+            appId: options.appId,
+            branch: options.branch,
+            outputPath: options.output,
+        });
+        console.log(`Wrote ${results.length} module(s) to ${options.output}`);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,iBAAiB,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,SAAS,YAAY,CAAC,QAA4B;IAChD,OAAO,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;AAC9C,CAAC;AAED,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,mBAAmB,CAAC;KACzB,WAAW,CACV,iFAAiF,CAClF;KACA,OAAO,CAAC,OAAO,CAAC;KAChB,cAAc,CAAC,qBAAqB,EAAE,4BAA4B,CAAC;KACnE,MAAM,CAAC,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,CAAC;KAC3D,MAAM,CACL,qBAAqB,EACrB,uBAAuB,EACvB,2BAA2B,CAC5B;KACA,MAAM,CACL,mBAAmB,EACnB,iEAAiE,CAClE;KACA,MAAM,CAAC,KAAK,EAAE,OAA0E,EAAE,EAAE;IAC3F,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAE1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CACX,+DAA+D,CAChE,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,iBAAiB,CAAC,iBAAiB,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC;YACtC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,UAAU,EAAE,OAAO,CAAC,MAAM;SAC3B,CAAC,CAAC;QAEH,OAAO,CAAC,GAAG,CACT,SAAS,OAAO,CAAC,MAAM,iBAAiB,OAAO,CAAC,MAAM,EAAE,CACzD,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACxE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/scan.d.ts

@@ -0,0 +1,15 @@
+export type MicroflowResult = {
+    microflow: string;
+    emptyCaptions: number;
+};
+export type ModuleResult = {
+    module: string;
+    microflows: MicroflowResult[];
+};
+export type ScanOptions = {
+    appId: string;
+    branch: string;
+    outputPath: string;
+};
+export declare function scanEmptyCaptions(options: ScanOptions): Promise<ModuleResult[]>;
+//# sourceMappingURL=scan.d.ts.map

package/dist/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,eAAe,EAAE,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,YAAY,EAAE,CAAC,CAyCzB"}

package/dist/scan.js

@@ -0,0 +1,35 @@
+import { MendixPlatformClient } from "mendixplatformsdk";
+import { microflows } from "mendixmodelsdk";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+export async function scanEmptyCaptions(options) {
+    const client = new MendixPlatformClient();
+    const app = await client.getApp(options.appId);
+    const workingCopy = await app.createTemporaryWorkingCopy(options.branch);
+    const model = await workingCopy.openModel();
+    const allMicroflows = model.allMicroflows();
+    const modulesByName = new Map();
+    for (const mc of allMicroflows) {
+        const loadedMc = await mc.load();
+        const emptyExclusiveSplits = loadedMc.objectCollection.objects.filter((activity) => activity instanceof microflows.ExclusiveSplit &&
+            activity.caption === "");
+        if (emptyExclusiveSplits.length === 0) {
+            continue;
+        }
+        const moduleName = loadedMc.containerAsModule.name;
+        let moduleEntry = modulesByName.get(moduleName);
+        if (!moduleEntry) {
+            moduleEntry = { module: moduleName, microflows: [] };
+            modulesByName.set(moduleName, moduleEntry);
+        }
+        moduleEntry.microflows.push({
+            microflow: loadedMc.name,
+            emptyCaptions: emptyExclusiveSplits.length,
+        });
+    }
+    const results = [...modulesByName.values()];
+    const outputPath = resolve(process.cwd(), options.outputPath);
+    await writeFile(outputPath, JSON.stringify(results, null, 2), "utf-8");
+    return results;
+}
+//# sourceMappingURL=scan.js.map

package/dist/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBpC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAoB;IAEpB,MAAM,MAAM,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC1C,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,MAAM,GAAG,CAAC,0BAA0B,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzE,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,SAAS,EAAE,CAAC;IAE5C,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,EAAE,CAAC;IAC5C,MAAM,aAAa,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEtD,KAAK,MAAM,EAAE,IAAI,aAAa,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,oBAAoB,GAAG,QAAQ,CAAC,gBAAgB,CAAC,OAAO,CAAC,MAAM,CACnE,CAAC,QAAoC,EAAE,EAAE,CACvC,QAAQ,YAAY,UAAU,CAAC,cAAc;YAC7C,QAAQ,CAAC,OAAO,KAAK,EAAE,CAC1B,CAAC;QAEF,IAAI,oBAAoB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtC,SAAS;QACX,CAAC;QAED,MAAM,UAAU,GAAG,QAAQ,CAAC,iBAAiB,CAAC,IAAI,CAAC;QACnD,IAAI,WAAW,GAAG,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAEhD,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,WAAW,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;YACrD,aAAa,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;QAC7C,CAAC;QAED,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC;YAC1B,SAAS,EAAE,QAAQ,CAAC,IAAI;YACxB,aAAa,EAAE,oBAAoB,CAAC,MAAM;SAC3C,CAAC,CAAC;IACL,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAE9D,MAAM,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAEvE,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "mx-empty-captions",
+  "version": "1.0.0",
+  "description": "Scan Mendix apps for decision activities with empty captions",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "mx-empty-captions": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mendix",
+    "mxsdk",
+    "microflow",
+    "cli"
+  ],
+  "author": "hasan <hasan-net2010@hotmail.com>",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hasan-droid/MX_SDK_EmptyCaptions.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Hasan-droid/MX_SDK_EmptyCaptions/issues"
+  },
+  "homepage": "https://github.com/Hasan-droid/MX_SDK_EmptyCaptions#readme",
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "mendixmodelsdk": "^4.114.0",
+    "mendixplatformsdk": "^5.2.0"
+  }
+}