@aifabrix/builder 2.44.4 → 2.44.6

package/.cursor/rules/cli-layout.mdc

@@ -50,7 +50,7 @@ Markdown headings in `layout.md` may use emoji for doc navigation; **user-facing
 
 - **Canonical helpers:** `lib/utils/cli-test-layout-chalk.js` (see symbol → helper table in [layout.md](./layout.md) § “Implementation map”).
 - **Preferred import alias:** `lib/utils/cli-layout-chalk.js` re-exports the same API when the path should not contain `test`.
-- **Prefer** `formatSuccessLine`, `formatSuccessParagraph`, `formatBlockingError`, `failureGlyph`, `successGlyph`, and other exported section helpers over ad hoc `` chalk.green(`✔ …`) `` for one-off success/error lines.
+- **Prefer** `formatSuccessLine`, `formatSuccessParagraph`, `formatWarningLine`, `formatBlockingError`, `failureGlyph`, `successGlyph`, and other exported section helpers over ad hoc `` chalk.green(`✔ …`) `` for one-off success/error lines.
 - **Composite / indented lines** (e.g. `successGlyph()` + `chalk.white(…)`, or `  ✔ …` in validate-style output) may stay raw chalk **only** when a single helper would not match the spec; keep glyphs canonical.
 - **Tests:** extend or add tests under `tests/lib/utils/cli-test-layout-chalk.test.js` (and command tests) when behavior or snapshots encode layout.
 

package/.cursor/rules/project-rules.mdc

@@ -28,7 +28,7 @@ When adding or changing CLI commands, subcommands, flags, help text, or terminal
 
 - **Rule**: `.cursor/rules/cli-layout.mdc`
 - **Visual/layout spec**: `.cursor/rules/layout.md`
-- **Per-command output profiles**: `.cursor/rules/cli-output-command-matrix.md` (update for every new leaf command)
+- **Per-command output profiles**: `.cursor/rules/cli-output-command-matrix.md` (update for every new leaf command; see matrix **Layout compliance** for `cli-test-layout-chalk` adoption status)
 
 ## Architecture Patterns
 

package/.npmrc.token

@@ -1 +1 @@
-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
+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

package/README.md

@@ -42,33 +42,25 @@ npm install -g @aifabrix/builder
 
 Get the platform running locally so you can try it.
 
-1. **Start local infrastructure** (Postgres, Redis, optional Traefik):
+**One-shot install:**
 
-   ```bash
-   aifabrix up-infra
-   ```
-
-   First-time run creates required infra secrets automatically. Use `aifabrix up-infra --adminPassword <password>` to set a custom admin password for Postgres, pgAdmin, and Redis Commander.
-
-2. **Start the platform** (Keycloak, Miso Controller, Dataplane) from community images:
-
-   ```bash
-   aifabrix up-platform
-   ```
+```bash
+aifabrix setup
+```
 
-   Or run platform apps separately: `aifabrix up-miso` then `aifabrix up-dataplane`. Infra must be up first.
+`aifabrix setup` detects your local state and either runs a fresh-install wizard (admin email/password, optional AI tool keys) or shows a mode menu (re-install, wipe data, clean files, update images). It then runs `up-infra` and `up-platform` for you. Use `aifabrix teardown` to fully remove the local installation. See [Infrastructure commands](docs/commands/infrastructure.md#aifabrix-setup) for details and CI flags.
 
-3. **Configure secrets** – You need either **OpenAI** or **Azure OpenAI**:
+If you prefer to set the AI tool key outside the wizard, use one of:
 
-   - **OpenAI:** set your API key:
-     ```bash
-     aifabrix secret set secrets-openaiApiKeyVault <your-openai-secret-key>
-     ```
-   - **Azure OpenAI:** set endpoint and API key:
-     ```bash
-     aifabrix secret set azure-openaiapi-urlKeyVault <your-azure-openai-endpoint-url>
-     aifabrix secret set secrets-azureOpenaiApiKeyVault <your-azure-openai-secret-key>
-     ```
+- **OpenAI:** set your API key:
+  ```bash
+  aifabrix secret set secrets-openaiApiKeyVault <your-openai-secret-key>
+  ```
+- **Azure OpenAI:** set endpoint and API key:
+  ```bash
+  aifabrix secret set azure-openaiapi-urlKeyVault <your-azure-openai-endpoint-url>
+  aifabrix secret set secrets-azureOpenaiApiKeyVault <your-azure-openai-secret-key>
+  ```
 
 Secrets are stored in `~/.aifabrix/secrets.local.yaml` or the file from `aifabrix-secrets` in your config (e.g. `builder/secrets.local.yaml`).
 

package/integration/hubspot-test/README.md

@@ -150,6 +150,8 @@ If you see **"Invalid token or insufficient permissions"** or **"Failed to creat
 
 If the dataplane is configured to accept device tokens for the wizard API, ensure you are logged in with `aifabrix login` and that the controller URL and environment match (e.g. `dev`). No client credentials are needed.
 
+When this error appears, `pnpm test:hubspot-wizard` **skips** the live wizard cases (exit code 0) so optional CI/agents are not blocked; configure client credentials or dataplane auth to run those cases for real.
+
 ## Troubleshooting
 
 - **Validation errors**: Run `aifabrix validate hubspot-test --type external` to see schema and manifest errors.

package/integration/hubspot-test/test.js

@@ -796,8 +796,8 @@ async function testDownloadAndSplit(appName, context, options) {
 }
 
 /**
- * Returns a skip message only when the wizard failure is due to dataplane unreachable (no service).
- * Does not skip for auth/session errors when dataplane is up (so tests fail with the real error).
+ * Returns a skip message when the wizard cannot run due to environment (dataplane missing,
+ * or dataplane rejecting the CLI token for wizard session).
  * @param {string} errorOutput - Combined stdout + stderr from wizard command
  * @returns {string|null} Skip message or null
  */
@@ -1257,7 +1257,9 @@ async function createSystemForNegativeTest(appName, configName, context, options
   });
   const wizardResult = await runWizard(configPath, context, options);
   if (!wizardResult.success) {
-    throw new SkipTestError(`Wizard failed to create system: ${wizardResult.stderr}`);
+    const errorOutput = `${wizardResult.stdout}\n${wizardResult.stderr}`;
+    const skipMsg = getWizardEnvironmentSkipMessage(errorOutput);
+    throw new SkipTestError(skipMsg || `Wizard failed to create system: ${wizardResult.stderr}`);
   }
   await new Promise(resolve => setTimeout(resolve, 200));
   return path.join(process.cwd(), 'integration', appName);

package/jest.projects.js

@@ -57,28 +57,36 @@ const defaultProject = {
       '/tests/lib/utils/cli-utils.test.js',
       '/tests/lib/utils/external-system-display.test.js',
       '/tests/lib/utils/dev-hosts-helper.test.js',
-      '/tests/lib/utils/declarative-url-matrix-d-reload.test.js',
+      '/tests/lib/utils/register-aifabrix-shell-env.test.js',
       '/tests/lib/utils/datasource-validation-watch.test.js',
       '\\\\tests\\\\lib\\\\utils\\\\cli-utils.test.js',
       '\\\\tests\\\\lib\\\\utils\\\\external-system-display.test.js',
       '\\\\tests\\\\lib\\\\utils\\\\dev-hosts-helper.test.js',
-      '\\\\tests\\\\lib\\\\utils\\\\declarative-url-matrix-d-reload.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\register-aifabrix-shell-env.test.js',
       '\\\\tests\\\\lib\\\\utils\\\\datasource-validation-watch.test.js',
       'lib/utils/dev-hosts-helper.test.js',
-      'lib/utils/declarative-url-matrix-d-reload.test.js',
+      'lib/utils/register-aifabrix-shell-env.test.js',
       'lib/utils/datasource-validation-watch.test.js',
       'dev-hosts-helper\\.test\\.js',
-      'declarative-url-matrix-d-reload\\.test\\.js',
+      'register-aifabrix-shell-env\\.test\\.js',
       '/tests/lib/datasource/log-viewer.test.js',
       '\\\\tests\\\\lib\\\\datasource\\\\log-viewer.test.js',
       'lib/datasource/log-viewer.test.js',
       '/tests/lib/datasource/log-viewer-structural.test.js',
+      '/tests/lib/datasource/log-viewer-run.test.js',
       '\\\\tests\\\\lib\\\\datasource\\\\log-viewer-structural.test.js',
+      '\\\\tests\\\\lib\\\\datasource\\\\log-viewer-run.test.js',
       'lib/datasource/log-viewer-structural.test.js',
+      'lib/datasource/log-viewer-run.test.js',
+      'log-viewer-run\\.test\\.js',
       '/tests/lib/commands/parameters-validate.test.js',
       '\\\\tests\\\\lib\\\\commands\\\\parameters-validate.test.js',
       'lib/commands/parameters-validate.test.js',
       'parameters-validate\\.test\\.js',
+      '/tests/lib/commands/repair-openapi-sync.test.js',
+      '\\\\tests\\\\lib\\\\commands\\\\repair-openapi-sync.test.js',
+      'lib/commands/repair-openapi-sync.test.js',
+      'repair-openapi-sync\\.test\\.js',
       '/tests/lib/utils/datasource-test-run-schema-sync.test.js',
       '\\\\tests\\\\lib\\\\utils\\\\datasource-test-run-schema-sync.test.js',
       'lib/utils/datasource-test-run-schema-sync.test.js',
@@ -153,10 +161,14 @@ const defaultProject = {
       '\\\\tests\\\\lib\\\\utils\\\\paths-app-listing.test.js',
       'lib/utils/paths-app-listing.test.js',
       'paths-app-listing\\.test\\.js',
-      '/tests/lib/utils/url-declarative-truth-table-124.test.js',
-      '\\\\tests\\\\lib\\\\utils\\\\url-declarative-truth-table-124.test.js',
-      'lib/utils/url-declarative-truth-table-124.test.js',
-      'url-declarative-truth-table-124\\.test\\.js',
+      '/tests/lib/utils/paths-system-builder-resolution.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\paths-system-builder-resolution.test.js',
+      'lib/utils/paths-system-builder-resolution.test.js',
+      'paths-system-builder-resolution\\.test\\.js',
+      '/tests/lib/utils/secrets-ancestor-paths.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\secrets-ancestor-paths.test.js',
+      'lib/utils/secrets-ancestor-paths.test.js',
+      'secrets-ancestor-paths\\.test\\.js',
       '/tests/lib/generator/generator-external-rbac.test.js',
       '\\\\tests\\\\lib\\\\generator\\\\generator-external-rbac.test.js',
       'lib/generator/generator-external-rbac.test.js',
@@ -200,9 +212,33 @@ const defaultProject = {
       '/tests/lib/app/app.test.js',
       '\\\\tests\\\\lib\\\\app\\\\app.test.js',
       'lib/app/app.test.js',
+      '/tests/lib/templates/application-frontdoor-paths.contract.test.js',
+      '\\\\tests\\\\lib\\\\templates\\\\application-frontdoor-paths.contract.test.js',
+      'lib/templates/application-frontdoor-paths.contract.test.js',
+      'application-frontdoor-paths\\.contract\\.test\\.js',
       '/tests/lib/core/admin-secrets.test.js',
       '\\\\tests\\\\lib\\\\core\\\\admin-secrets.test.js',
-      'lib/core/admin-secrets.test.js'
+      'lib/core/admin-secrets.test.js',
+      '/tests/lib/datasource/validate-datasource-parsed.test.js',
+      '\\\\tests\\\\lib\\\\datasource\\\\validate-datasource-parsed.test.js',
+      'lib/datasource/validate-datasource-parsed.test.js',
+      'validate-datasource-parsed\\.test\\.js',
+      '/tests/lib/datasource/run-capability-copy.test.js',
+      '\\\\tests\\\\lib\\\\datasource\\\\run-capability-copy.test.js',
+      'lib/datasource/run-capability-copy.test.js',
+      'run-capability-copy\\.test\\.js',
+      '/tests/lib/datasource/run-capability-diff.test.js',
+      '\\\\tests\\\\lib\\\\datasource\\\\run-capability-diff.test.js',
+      'lib/datasource/run-capability-diff.test.js',
+      'run-capability-diff\\.test\\.js',
+      '/tests/lib/datasource/run-capability-edit.test.js',
+      '\\\\tests\\\\lib\\\\datasource\\\\run-capability-edit.test.js',
+      'lib/datasource/run-capability-edit.test.js',
+      'run-capability-edit\\.test\\.js',
+      '/tests/lib/datasource/run-capability-remove.test.js',
+      '\\\\tests\\\\lib\\\\datasource\\\\run-capability-remove.test.js',
+      'lib/datasource/run-capability-remove.test.js',
+      'run-capability-remove\\.test\\.js'
     ];
     if (process.env.INCLUDE_LOCAL_TESTS !== 'true') {
       patterns.push('/tests/local/');
@@ -221,17 +257,23 @@ const isolatedProjects = [
   makeIsolatedProject('cli-utils', ['**/tests/lib/utils/cli-utils.test.js']),
   makeIsolatedProject('external-system-display', ['**/tests/lib/utils/external-system-display.test.js']),
   makeIsolatedProject('dev-hosts-helper', ['**/tests/lib/utils/dev-hosts-helper.test.js']),
-  makeIsolatedProject('declarative-url-matrix-d-reload', [
-    '**/tests/lib/utils/declarative-url-matrix-d-reload.test.js'
-  ]),
   makeIsolatedProject('parameters-validate', ['**/tests/lib/commands/parameters-validate.test.js']),
+  makeIsolatedProject('repair-openapi-sync', ['**/tests/lib/commands/repair-openapi-sync.test.js']),
   makeIsolatedProject('paths-app-listing', ['**/tests/lib/utils/paths-app-listing.test.js']),
+  makeIsolatedProject('paths-system-builder-resolution', [
+    '**/tests/lib/utils/paths-system-builder-resolution.test.js'
+  ]),
+  makeIsolatedProject('secrets-ancestor-paths', ['**/tests/lib/utils/secrets-ancestor-paths.test.js']),
   makeIsolatedProject('datasource-validation-watch', [
     '**/tests/lib/utils/datasource-validation-watch.test.js'
   ]),
   makeIsolatedProject('log-viewer', [
     '**/tests/lib/datasource/log-viewer.test.js',
-    '**/tests/lib/datasource/log-viewer-structural.test.js'
+    '**/tests/lib/datasource/log-viewer-structural.test.js',
+    '**/tests/lib/datasource/log-viewer-run.test.js'
+  ]),
+  makeIsolatedProject('register-aifabrix-shell-env', [
+    '**/tests/lib/utils/register-aifabrix-shell-env.test.js'
   ]),
   makeIsolatedProject('datasource-test-run-schema-sync', [
     '**/tests/lib/utils/datasource-test-run-schema-sync.test.js'
@@ -239,6 +281,9 @@ const isolatedProjects = [
   makeIsolatedProject('infra-platform-contract', [
     '**/tests/lib/parameters/infra-platform-contract.test.js'
   ]),
+  makeIsolatedProject('application-frontdoor-paths-contract', [
+    '**/tests/lib/templates/application-frontdoor-paths.contract.test.js'
+  ]),
   makeIsolatedProject('database-secret-values', [
     '**/tests/lib/parameters/database-secret-values.test.js'
   ]),
@@ -283,9 +328,6 @@ const isolatedProjects = [
   makeIsolatedProject('helpers-ensure-admin-secrets', [
     '**/tests/lib/infrastructure/helpers-ensure-admin-secrets.test.js'
   ]),
-  makeIsolatedProject('url-declarative-truth-table-124', [
-    '**/tests/lib/utils/url-declarative-truth-table-124.test.js'
-  ]),
   makeIsolatedProject('secrets-generator', ['**/tests/lib/utils/secrets-generator.test.js']),
   makeIsolatedProject('app-uncovered-lines', ['**/tests/lib/app/app-uncovered-lines.test.js']),
   makeIsolatedProject('ensure-dev-certs-for-remote-docker', [
@@ -297,7 +339,16 @@ const isolatedProjects = [
   makeIsolatedProject('schema-241-alignment', ['**/tests/lib/validation/schema-241-alignment.test.js']),
   makeIsolatedProject('schema-resolver-order', ['**/tests/lib/utils/schema-resolver-order.test.js']),
   makeIsolatedProject('app-module', ['**/tests/lib/app/app.test.js']),
-  makeIsolatedProject('admin-secrets', ['**/tests/lib/core/admin-secrets.test.js'])
+  makeIsolatedProject('admin-secrets', ['**/tests/lib/core/admin-secrets.test.js']),
+  makeIsolatedProject('validate-datasource-parsed', [
+    '**/tests/lib/datasource/validate-datasource-parsed.test.js'
+  ]),
+  makeIsolatedProject('capability-run-real-fs', [
+    '**/tests/lib/datasource/run-capability-copy.test.js',
+    '**/tests/lib/datasource/run-capability-diff.test.js',
+    '**/tests/lib/datasource/run-capability-edit.test.js',
+    '**/tests/lib/datasource/run-capability-remove.test.js'
+  ])
 ];
 
 const allProjects = [defaultProject, ...isolatedProjects];

package/lib/api/controller-health.api.js

@@ -0,0 +1,49 @@
+/**
+ * Controller health (public) — deployment mode for Builder polling tuning.
+ *
+ * GET /api/v1/health returns `{ data: { deploymentType, ... } }` (miso-controller).
+ *
+ * @fileoverview Read controller deployment type without authentication
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { ApiClient } = require('./index');
+
+/**
+ * Extract deploymentType from harmonized API JSON body.
+ * @param {Object} response - Result from ApiClient.get / makeApiCall shape `{ success, data }`
+ * @returns {string|undefined} Normalized lowercase deployment type or undefined
+ */
+function extractDeploymentTypeFromHealthResponse(response) {
+  if (!response || response.success === false || response.data === null) {
+    return undefined;
+  }
+  const body = response.data;
+  if (!body || typeof body !== 'object') {
+    return undefined;
+  }
+  const payload = body.data !== undefined ? body.data : body;
+  if (!payload || typeof payload !== 'object') {
+    return undefined;
+  }
+  const dt = payload.deploymentType;
+  return typeof dt === 'string' ? dt.trim().toLowerCase() : undefined;
+}
+
+/**
+ * Fetch controller DEPLOYMENT mode label (public endpoint, no auth).
+ * @async
+ * @param {string} controllerUrl - Controller base URL
+ * @returns {Promise<string|undefined>} e.g. 'database', 'local', 'azure', 'azure-mock'
+ */
+async function getControllerDeploymentType(controllerUrl) {
+  const client = new ApiClient(controllerUrl);
+  const response = await client.get('/api/v1/health');
+  return extractDeploymentTypeFromHealthResponse(response);
+}
+
+module.exports = {
+  getControllerDeploymentType,
+  extractDeploymentTypeFromHealthResponse
+};

package/lib/api/dimension-values.api.js

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Dimension values API (Controller)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+/**
+ * List dimension values for a dimension
+ * @requiresPermission {Controller} dimensions:read
+ * @async
+ * @function listDimensionValues
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} dimensionIdOrKey
+ * @param {Object} [options]
+ * @param {number} [options.page]
+ * @param {number} [options.pageSize]
+ * @param {string} [options.sort]
+ * @param {string} [options.filter]
+ * @param {string} [options.search]
+ * @returns {Promise<Object>}
+ */
+async function listDimensionValues(controllerUrl, authConfig, dimensionIdOrKey, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(`/api/v1/dimensions/${encodeURIComponent(dimensionIdOrKey)}/values`, {
+    params: options
+  });
+}
+
+/**
+ * Create a dimension value under a dimension
+ * @requiresPermission {Controller} dimensions:create
+ * @async
+ * @function createDimensionValue
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} dimensionIdOrKey
+ * @param {Object} body
+ * @param {string} body.value
+ * @param {string} [body.displayName]
+ * @param {string} [body.description]
+ * @returns {Promise<Object>}
+ */
+async function createDimensionValue(controllerUrl, authConfig, dimensionIdOrKey, body) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  const payload = { value: body.value };
+  if (body.displayName !== undefined && body.displayName !== null && body.displayName !== '') {
+    payload.displayName = body.displayName;
+  }
+  if (body.description !== undefined && body.description !== null && body.description !== '') {
+    payload.description = body.description;
+  }
+  return await client.post(`/api/v1/dimensions/${encodeURIComponent(dimensionIdOrKey)}/values`, {
+    body: payload
+  });
+}
+
+/**
+ * Delete a dimension value by id
+ * @requiresPermission {Controller} dimensions:delete
+ * @async
+ * @function deleteDimensionValue
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} dimensionValueId
+ * @returns {Promise<Object>}
+ */
+async function deleteDimensionValue(controllerUrl, authConfig, dimensionValueId) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.delete(`/api/v1/dimension-values/${encodeURIComponent(dimensionValueId)}`);
+}
+
+module.exports = {
+  listDimensionValues,
+  createDimensionValue,
+  deleteDimensionValue
+};
+

package/lib/api/dimensions.api.js

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Dimensions API (Controller /api/v1/dimensions)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const BASE = '/api/v1/dimensions';
+
+/**
+ * List dimensions (paginated)
+ * @requiresPermission {Controller} dimensions:read
+ * @async
+ * @function listDimensions
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {Object} [options]
+ * @param {number} [options.page]
+ * @param {number} [options.pageSize]
+ * @param {string} [options.sort]
+ * @param {string} [options.filter]
+ * @param {string} [options.search]
+ * @returns {Promise<Object>}
+ */
+async function listDimensions(controllerUrl, authConfig, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(BASE, { params: options });
+}
+
+/**
+ * Get a dimension by id or key
+ * @requiresPermission {Controller} dimensions:read
+ * @async
+ * @function getDimension
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} dimensionIdOrKey
+ * @param {Object} [options]
+ * @param {boolean} [options.includeValues]
+ * @returns {Promise<Object>}
+ */
+async function getDimension(controllerUrl, authConfig, dimensionIdOrKey, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  const params = {};
+  if (options.includeValues !== undefined && options.includeValues !== null) {
+    params.includeValues = options.includeValues;
+  }
+  return await client.get(`${BASE}/${encodeURIComponent(dimensionIdOrKey)}`, { params });
+}
+
+/**
+ * Create a dimension
+ * @requiresPermission {Controller} dimensions:create
+ * @async
+ * @function createDimension
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {Object} body
+ * @returns {Promise<Object>}
+ */
+async function createDimension(controllerUrl, authConfig, body) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  const payload = {
+    key: body.key,
+    displayName: body.displayName,
+    dataType: body.dataType
+  };
+  if (body.description !== undefined && body.description !== null && body.description !== '') {
+    payload.description = body.description;
+  }
+  if (body.isRequired !== undefined && body.isRequired !== null) {
+    payload.isRequired = Boolean(body.isRequired);
+  }
+  return await client.post(BASE, { body: payload });
+}
+
+/**
+ * Create-if-missing (idempotent by default): if a dimension already exists for the key, return it as success.
+ * @requiresPermission {Controller} dimensions:read + dimensions:create
+ * @async
+ * @function createDimensionIdempotent
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {Object} body
+ * @returns {Promise<{ created: boolean, response: Object }>}
+ */
+async function createDimensionIdempotent(controllerUrl, authConfig, body) {
+  const key = String(body?.key || '').trim();
+  if (!key) {
+    throw new Error('Dimension key is required');
+  }
+  const getRes = await getDimension(controllerUrl, authConfig, key);
+  if (getRes && getRes.success === true) {
+    return { created: false, response: getRes };
+  }
+  // Not found or other read failure; attempt create and let errors surface.
+  const createRes = await createDimension(controllerUrl, authConfig, body);
+  if (createRes && createRes.success === true) {
+    return { created: true, response: createRes };
+  }
+  const msg = createRes?.error || createRes?.formattedError || 'Failed to create dimension';
+  throw new Error(msg);
+}
+
+module.exports = {
+  listDimensions,
+  getDimension,
+  createDimension,
+  createDimensionIdempotent
+};
+

package/lib/api/external-systems.api.js

@@ -60,6 +60,7 @@ async function createExternalSystem(dataplaneUrl, authConfig, systemData) {
  * @param {Object} authConfig - Authentication configuration
  * @returns {Promise<Object>} External system details response. May include optional fields:
  *   - {string} [mcpServerUrl] - Full URL of external system MCP server when configured
+ *   - {string} [mcpDocsPageUrl] - Full URL of MCP OpenAPI docs page (builder may derive when absent)
  *   - {string} [apiDocumentUrl] - Full URL of API document (OpenAPI spec) when configured
  *   - {string} [openApiDocsPageUrl] - Full URL of dataplane API docs page when showOpenApiDocs is true
  * @throws {Error} If request fails