mxcli-olc-setup 1.0.0

package/README.md

@@ -0,0 +1,46 @@
+# mxcli-olc-setup
+
+Automates [mxcli](https://github.com/mendixlabs/mxcli) setup for Mendix projects. Downloads the correct mxcli binary for your platform, initializes it, adds AI-agent skills, and configures your project's `.gitignore`.
+
+## Quick Start
+
+Run from your **Mendix project root**:
+
+```bash
+npx mxcli-olc-setup
+```
+
+Or with an explicit path:
+
+```bash
+npx mxcli-olc-setup /path/to/mendix-project
+```
+
+## What It Does
+
+1. **Downloads mxcli** — fetches the latest release binary for your OS/architecture
+2. **Runs `mxcli init`** — initializes mxcli with Claude and OpenCode tool support
+3. **Adds Mendix Developer Skill** — copies the AI skill file to `.ai-context/skills/`
+4. **Updates `.gitignore`** — appends entries for AI/mxcli generated files
+5. **Creates knowledge base** — generates a `project-knowledge-base.md` template for AI agents
+
+## Global Install
+
+```bash
+npm install -g mxcli-olc-setup
+mxcli-olc-setup
+```
+
+## Prerequisites
+
+- **Node.js** >= 14
+- **Internet access** (downloads mxcli from GitHub releases)
+- Run from a **Mendix project directory**
+
+## Supported Platforms
+
+| OS | Architecture |
+|----|-------------|
+| Windows | x64, arm64 |
+| macOS | x64 (Intel), arm64 (Apple Silicon) |
+| Linux | x64, arm64 |

package/assets/mendix-developer-skill.md

@@ -0,0 +1,177 @@
+# Mendix Developer Skill
+
+This file is used for AI agent to carry out development or analysis task in Mendix project. Everytime any task to be executed in the Mendix project, please refer to this file. 
+
+## Mendix Model Inspection Guardrail
+
+When analyzing Mendix pages, never rely only on rendered HTML or text search. Decode the `.mpr` Unit contents and recursively inspect page/snippet widgets, especially nested DataGrid 2 `CustomWidgets$CustomWidget` properties, to find actual actions and target microflows/pages.
+
+## Project Search Workflow
+
+Always inspect the `.mpr` model, not only project files.
+
+Plain text search with `rg` often misses Mendix pages, captions, widget actions, and microflows because they are stored inside the `.mpr` database. Search both:
+
+1. Normal files with `rg`.
+2. The `.mpr` SQLite `Unit` table by decoding `Contents`.
+
+Search by exact phrase first, then variants. For requirement text like `Reference Documents Review`, search:
+
+```text
+Reference Documents Review
+Reference Document Approval
+ReferenceDocuments
+ReferenceDocumentApproval
+ApprovalOverview
+```
+
+## Map Labels To Mendix Artifacts
+
+When a user-facing label is found, identify:
+
+1. Module name.
+2. Page or snippet name.
+3. Menu/navigation entry.
+4. Data source microflow.
+5. Action microflow or page target.
+6. Related entity.
+
+Example output:
+
+```text
+Reference Document Approval menu opens OMS.ReferenceDocuments_ApprovalOverview, whose header is Reference Documents Review.
+```
+
+For requirement matching, keep a known-alias mapping table as analysis proceeds:
+
+| User label | Technical artifact |
+| --- | --- |
+| OMS Tasks | `OMSHomepage.Home_OMS` / `SNP_OMSHome_OMSTask` |
+| Notification Centre | `OMSHomepage.Home_OMS` / `notificationcenterdatagrid` |
+| Reference Documents Review | `OMS.ReferenceDocuments_ApprovalOverview` |
+| Activity Forms Table View | `ActivityFormManagement.ActivityForm_Overview` |
+| Daily Morning Meeting Table View | `MeetingManagement.MeetingRecords_Overview_DailyRecords` |
+
+## Page And Action Tracing
+
+For page/action analysis, trace clickable widgets. Do not stop at DOM or page name. For each relevant page/grid, inspect:
+
+1. `Forms$ActionButton`
+2. `Forms$MicroflowAction`
+3. `Forms$FormAction`
+4. `OnClickAction`
+5. `OnDoubleClickAction`
+6. Widget `DefaultAction`
+7. Nested widgets inside DataGrid 2 custom widgets
+
+For DataGrid 2, inspect nested widget properties. Mendix DataGrid 2 appears as `CustomWidgets$CustomWidget`, and buttons are often nested deep inside `Object.Properties[*].Value.Objects[*]...Widgets`. Recursively scan nested widgets for `Forms$ActionButton`.
+
+Distinguish row actions from button/link actions. Report clearly whether the action is:
+
+1. Row double-click/default action.
+2. Hyperlink/action button inside a column.
+3. Toolbar button.
+4. Bulk selection button.
+
+This matters because a requirement may say "double-click line" while the implementation only has a link or button.
+
+## Microflow Trace Requirements
+
+Trace called microflows until the final page. If a button calls a microflow, inspect the microflow for:
+
+1. Retrieve source.
+2. XPath constraints.
+3. Selected object.
+4. Empty checks.
+5. `ShowFormAction`.
+6. Final page opened.
+7. Parameter mappings.
+
+Flag unsafe retrieve patterns as risks:
+
+1. `SingleObject = true` without sort.
+2. Retrieving by non-unique fields like `LotNo + ProductionLine`.
+3. No empty check before using a retrieved object.
+4. Assuming child records share the same parent/order.
+5. Unused parameters.
+6. Opening the first matching Record Sheet instead of the exact linked one.
+
+Prefer association-based retrieval over string matching whenever possible.
+
+Example:
+
+```text
+Instead of finding Record Sheet by LotNo + StringProductionLine, prefer a direct association to ProductionOrder, Batch, OMSRecordSheet, or OMSRSUnitProcess.
+```
+
+## Navigation Review Trace Format
+
+When reviewing navigation requirements, build a small trace:
+
+```text
+User label:
+Menu item:
+Page:
+Grid/snippet:
+Clickable widget:
+Action:
+Microflow logic:
+Final opened page:
+Risk:
+Recommendation:
+```
+
+## Generated Analysis Reports
+
+Keep generated analysis reports for repetitive scanning. Prefer CSV or Markdown reports listing:
+
+1. Page.
+2. Grid name.
+3. Entity/data source.
+4. Buttons.
+5. Button caption.
+6. Action type.
+7. Target page/microflow.
+8. Whether it opens Record Sheet.
+
+## UI/UX and SCSS Guardrails
+
+When making UI/UX or CSS styling changes in Mendix, especially in `.scss` files, do not target generated Mendix element names directly for new styles.
+
+Avoid hardcoding selectors such as:
+
+```scss
+.mx-name-dropDown5 { ... }
+.mx-name-textBox4 { ... }
+.mx-name-comboBox9 { ... }
+```
+
+Instead, create a semantic CSS class name and apply that class to the relevant Mendix widget or container in Studio Pro.
+
+Preferred pattern:
+
+```scss
+.oms-decision-dropdown {
+  // styles here
+}
+```
+
+When adding a new style, document:
+
+1. The CSS class name.
+2. The widget or element where the class should be applied.
+3. The purpose of the class.
+
+Example:
+
+```text
+Class name: oms-decision-dropdown
+Apply to: the Dynamic Yes/No decision dropdown widget
+Purpose: align decision dropdown spacing and sizing in the record sheet action row
+```
+
+Existing legacy styles that already target `.mx-name-*` selectors should not be expanded unless the task is specifically to clean up or migrate them.
+
+## Git ignore
+
+Whenever AI or mxcli generated any files in the project directory, make sure the files to be included in git ignore file of the Mendix project.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "mxcli-olc-setup",
+  "version": "1.0.0",
+  "description": "Automates mxcli setup for Mendix projects — downloads mxcli binary, runs init, adds custom skills, and configures gitignore",
+  "bin": {
+    "mxcli-olc-setup": "./setup.js"
+  },
+  "files": [
+    "setup.js",
+    "assets/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "keywords": ["mendix", "mxcli", "ai", "low-code", "cli", "setup"],
+  "license": "UNLICENSED"
+}

package/setup.js

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+'use strict';
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const GITIGNORE_ENTRIES = [
+  '.ai-context',
+  '.claude',
+  '.devcontainer',
+  '.playwright',
+  'AGENTS.md',
+  'CLAUDE.md',
+  '.playwright-mcp',
+  '.mxcli',
+  '.mxcli-logs',
+  '.mxcli-plugins',
+  '.mxcli-plugins-lock.json',
+  '.mxcli-plugins-lock.json.bak',
+  '/outputs/',
+  '*.mdl',
+  'project-knowledge-base.md',
+  '/.tools/',
+];
+
+const PLATFORM_MAP = {
+  'win32-x64':   { assetPattern: /mxcli-windows-amd64\.exe$/,   binaryName: 'mxcli.exe' },
+  'win32-arm64': { assetPattern: /mxcli-windows-arm64\.exe$/,   binaryName: 'mxcli.exe' },
+  'darwin-x64':  { assetPattern: /mxcli-darwin-amd64$/,         binaryName: 'mxcli' },
+  'darwin-arm64':{ assetPattern: /mxcli-darwin-arm64$/,         binaryName: 'mxcli' },
+  'linux-x64':   { assetPattern: /mxcli-linux-amd64$/,          binaryName: 'mxcli' },
+  'linux-arm64': { assetPattern: /mxcli-linux-arm64$/,          binaryName: 'mxcli' },
+};
+
+function log(msg) {
+  console.log(`[mxcli-olc-setup] ${msg}`);
+}
+
+function warn(msg) {
+  console.warn(`[mxcli-olc-setup] WARNING: ${msg}`);
+}
+
+function fail(msg) {
+  console.error(`[mxcli-olc-setup] ERROR: ${msg}`);
+  process.exit(1);
+}
+
+function printHelp() {
+  const pkg = require('./package.json');
+  console.log(`
+  ${pkg.name} v${pkg.version}
+
+  Automates mxcli setup for Mendix projects.
+
+  Usage:
+    npx mxcli-olc-setup [project-path]
+    mxcli-olc-setup [project-path]
+
+  Arguments:
+    project-path    Path to the Mendix project root (default: current directory)
+
+  Options:
+    --help, -h      Show this help message
+    --version, -v   Show version number
+
+  What it does:
+    1. Downloads the latest mxcli binary for your platform
+    2. Runs mxcli init with Claude and OpenCode tools
+    3. Adds the Mendix Developer Skill to .ai-context/skills/
+    4. Appends AI/mxcli entries to .gitignore
+    5. Creates a project-knowledge-base.md template
+`);
+}
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  for (const arg of args) {
+    if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    }
+    if (arg === '--version' || arg === '-v') {
+      const pkg = require('./package.json');
+      console.log(pkg.version);
+      process.exit(0);
+    }
+  }
+  return args.find(a => !a.startsWith('-')) || null;
+}
+
+function getProjectRoot() {
+  const cliPath = parseArgs();
+  if (cliPath) return path.resolve(cliPath);
+  return process.env.INIT_CWD || process.cwd();
+}
+
+function getPlatformKey() {
+  const platform = os.platform();
+  const arch = os.arch();
+  const key = `${platform}-${arch}`;
+  if (!PLATFORM_MAP[key]) {
+    fail(`Unsupported platform: ${key}. Supported: ${Object.keys(PLATFORM_MAP).join(', ')}`);
+  }
+  return key;
+}
+
+function httpsGetJson(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, { headers: { 'User-Agent': 'mxcli-olc-setup' } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        httpsGetJson(res.headers.location).then(resolve).catch(reject);
+        return;
+      }
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode} from ${url}`));
+        return;
+      }
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try { resolve(JSON.parse(data)); } catch (e) { reject(e); }
+      });
+    }).on('error', reject);
+  });
+}
+
+function downloadFile(url, destPath) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(destPath);
+    let settled = false;
+
+    function finish(err) {
+      if (settled) return;
+      settled = true;
+      if (err) {
+        file.close(() => {
+          try { fs.unlinkSync(destPath); } catch (_) {}
+          reject(err);
+        });
+      } else {
+        process.stdout.write('\n');
+        file.close(resolve);
+      }
+    }
+
+    file.on('error', finish);
+
+    function doDownload(dlUrl, redirects) {
+      if (redirects > 10) { finish(new Error('Too many redirects')); return; }
+      const proto = dlUrl.startsWith('https') ? https : require('http');
+      const req = proto.get(dlUrl, { headers: { 'User-Agent': 'mxcli-olc-setup' } }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          doDownload(res.headers.location, redirects + 1);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          finish(new Error(`HTTP ${res.statusCode} downloading ${dlUrl}`));
+          return;
+        }
+        const total = parseInt(res.headers['content-length'], 10);
+        let downloaded = 0;
+        res.on('data', chunk => {
+          downloaded += chunk.length;
+          if (total) {
+            const pct = Math.round((downloaded / total) * 100);
+            process.stdout.write(`\r[mxcli-olc-setup] Downloading mxcli... ${pct}%`);
+          }
+        });
+        res.pipe(file);
+        file.on('finish', () => finish(null));
+      });
+      req.on('error', finish);
+    }
+    doDownload(url, 0);
+  });
+}
+
+async function getLatestRelease() {
+  log('Fetching latest mxcli release info...');
+  const release = await httpsGetJson('https://api.github.com/repos/mendixlabs/mxcli/releases/latest');
+  return release;
+}
+
+function findAsset(release, platformKey) {
+  const { assetPattern } = PLATFORM_MAP[platformKey];
+  const asset = release.assets.find(a => assetPattern.test(a.name));
+  if (!asset) {
+    fail(`No mxcli release asset found for ${platformKey}. Available: ${release.assets.map(a => a.name).join(', ')}`);
+  }
+  return asset;
+}
+
+async function downloadMxcli(projectRoot, release, platformKey) {
+  const { binaryName } = PLATFORM_MAP[platformKey];
+  const installDir = path.join(projectRoot, '.tools', 'mxcli');
+  const binaryPath = path.join(installDir, binaryName);
+
+  if (fs.existsSync(binaryPath)) {
+    log(`mxcli binary already exists at ${binaryPath}`);
+    try {
+      const result = execSync(`"${binaryPath}" --version`, { encoding: 'utf8', stdio: 'pipe' });
+      log(`Existing mxcli version: ${result.trim()}`);
+      return binaryPath;
+    } catch (e) {
+      warn('Existing binary failed --version check, will re-download');
+    }
+  }
+
+  fs.mkdirSync(installDir, { recursive: true });
+
+  const asset = findAsset(release, platformKey);
+  log(`Downloading mxcli ${release.tag_name}: ${asset.name} (${(asset.size / 1024 / 1024).toFixed(1)} MB)...`);
+
+  const tmpPath = path.join(os.tmpdir(), asset.name);
+  await downloadFile(asset.browser_download_url, tmpPath);
+
+  fs.copyFileSync(tmpPath, binaryPath);
+  try { fs.unlinkSync(tmpPath); } catch (_) {}
+
+  if (os.platform() !== 'win32') {
+    fs.chmodSync(binaryPath, 0o755);
+  }
+
+  log(`mxcli installed to ${binaryPath}`);
+  return binaryPath;
+}
+
+function runMxcliInit(binaryPath, projectRoot) {
+  log('Running mxcli init...');
+  try {
+    const result = execSync(
+      `"${binaryPath}" init --tool claude --tool opencode "${projectRoot}"`,
+      { encoding: 'utf8', stdio: 'pipe', cwd: projectRoot }
+    );
+    log('mxcli init completed successfully');
+    if (result.trim()) console.log(result.trim());
+  } catch (e) {
+    warn(`mxcli init had issues (may already be initialized): ${e.message}`);
+    if (e.stdout) console.log(e.stdout);
+    if (e.stderr) console.error(e.stderr);
+  }
+}
+
+function addCustomSkill(projectRoot) {
+  const skillSrc = path.join(__dirname, 'assets', 'mendix-developer-skill.md');
+  const skillDir = path.join(projectRoot, '.ai-context', 'skills');
+  const skillDest = path.join(skillDir, 'mendix-developer-skill.md');
+
+  if (!fs.existsSync(skillSrc)) {
+    warn(`Custom skill file not found at ${skillSrc}, skipping`);
+    return;
+  }
+
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.copyFileSync(skillSrc, skillDest);
+  log('Custom Mendix Developer Skill added to .ai-context/skills/');
+}
+
+function updateGitignore(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  let existingContent = '';
+
+  if (fs.existsSync(gitignorePath)) {
+    existingContent = fs.readFileSync(gitignorePath, 'utf8');
+  }
+
+  const existingLines = existingContent.split(/\r?\n/).map(l => l.trim());
+
+  const missing = GITIGNORE_ENTRIES.filter(entry => {
+    return !existingLines.some(line => line === entry || line === entry.replace(/^\//, ''));
+  });
+
+  if (missing.length === 0) {
+    log('All .gitignore entries already present, nothing to add');
+    return;
+  }
+
+  let append = '';
+  if (existingContent && !existingContent.endsWith('\n')) append += '\n';
+  append += '\n# mxcli-olc-setup auto-generated\n';
+  append += missing.join('\n') + '\n';
+
+  fs.appendFileSync(gitignorePath, append, 'utf8');
+  log(`Added ${missing.length} entries to .gitignore: ${missing.join(', ')}`);
+}
+
+function createKnowledgeBase(projectRoot) {
+  const kbPath = path.join(projectRoot, 'project-knowledge-base.md');
+
+  if (fs.existsSync(kbPath)) {
+    log('project-knowledge-base.md already exists, skipping');
+    return;
+  }
+
+  const header = `# Mendix Project Knowledge Base
+
+> This file is maintained by AI agents working on this project.
+> Every time an AI agent makes observations or discovers important context about the project, it should update this file for future reference.
+
+## Project Overview
+
+<!-- Add project description, purpose, and key stakeholders -->
+
+## Architecture Notes
+
+<!-- Document architectural decisions, patterns, and constraints -->
+
+## Module Map
+
+<!-- List modules and their responsibilities -->
+
+## Key Entities
+
+<!-- Document important domain entities and their relationships -->
+
+## Important Microflows
+
+<!-- List critical microflows and what they do -->
+
+## Known Issues / Gotchas
+
+<!-- Document pitfalls, edge cases, and things to watch out for -->
+
+## Change Log
+
+<!-- Agents: add dated entries when you discover or change something important -->
+`;
+
+  fs.writeFileSync(kbPath, header, 'utf8');
+  log('Created project-knowledge-base.md');
+}
+
+async function main() {
+  const projectRoot = getProjectRoot();
+  log(`Project root: ${projectRoot}`);
+  log(`Platform: ${os.platform()} ${os.arch()}`);
+
+  const platformKey = getPlatformKey();
+
+  let release;
+  try {
+    release = await getLatestRelease();
+    log(`Latest mxcli release: ${release.tag_name}`);
+  } catch (e) {
+    fail(`Failed to fetch mxcli release info: ${e.message}`);
+  }
+
+  const binaryPath = await downloadMxcli(projectRoot, release, platformKey);
+
+  runMxcliInit(binaryPath, projectRoot);
+
+  addCustomSkill(projectRoot);
+
+  updateGitignore(projectRoot);
+
+  createKnowledgeBase(projectRoot);
+
+  log('Setup complete!');
+}
+
+main().catch(e => {
+  console.error(`[mxcli-olc-setup] FATAL: ${e.message}`);
+  process.exit(1);
+});