@aifabrix/builder 2.42.1 → 2.44.0

package/jest.config.integration.js

@@ -1,30 +1,33 @@
 /**
- * Jest Configuration for Integration Tests
- * Ensures tests run in correct order with proper error handling
+ * Jest configuration for integration tests under tests/integration/ only.
  *
- * @fileoverview Jest config specifically for integration tests
+ * IMPORTANT: Do not spread ./jest.config.js here — that config sets `projects` (default +
+ * isolated suites). Spreading it caused `test:integration` to run the entire multi-project
+ * suite in one process, leaking mocks/module state between projects and producing flaky
+ * failures. This file defines a single project matching docs/plans for npm run test:integration.
+ *
+ * @fileoverview Full integration Jest config: HubSpot fixtures, workflow shim, and
+ *   tests/integration/steps/* (real Docker: create, build, run, health).
+ *   For fixture-only tests without Docker, use jest.config.integration.fixtures.js
+ *   (npm run test:integration:fixtures).
  * @author AI Fabrix Team
  * @version 2.0.0
  */
 
-const baseConfig = require('./jest.config');
+const { sharedTransform } = require('./jest.projects');
 
 module.exports = {
-  ...baseConfig,
-  // Override testPathIgnorePatterns for integration tests
-  testPathIgnorePatterns: [
-    '/node_modules/',
-    '\\\\node_modules\\\\'
-  ],
-  // Use custom test sequencer for correct order
+  displayName: 'integration',
+  testEnvironment: 'node',
+  transform: sharedTransform,
+  testMatch: ['**/tests/integration/**/*.test.js'],
+  testPathIgnorePatterns: ['/node_modules/', '\\\\node_modules\\\\'],
   testSequencer: '<rootDir>/tests/integration/test-sequencer.js',
-  // Longer timeout for integration tests
-  testTimeout: 300000, // 5 minutes
-  // Run tests sequentially
+  testTimeout: 300000,
   maxWorkers: 1,
-  // Don't ignore integration tests
-  testMatch: [
-    '**/tests/integration/**/*.test.js'
+  setupFiles: ['<rootDir>/tests/capture-real-fs.js'],
+  setupFilesAfterEnv: [
+    '<rootDir>/tests/setup.js',
+    '<rootDir>/tests/integration/jest-restore-integration-timeout.js'
   ]
 };
-

package/jest.config.isolated.js

@@ -0,0 +1,10 @@
+/**
+ * Isolated test projects only. Used by test-wrapper pass 2 (fresh Node process).
+ * @fileoverview
+ */
+
+const { isolatedProjects } = require('./jest.projects');
+
+module.exports = {
+  projects: isolatedProjects
+};

package/jest.projects.js

@@ -0,0 +1,288 @@
+/**
+ * Shared Jest project definitions (default + isolated). Split configs run in separate processes
+ * so `jest.mock('fs')` in the default suite cannot leak into isolated workers.
+ * @fileoverview
+ */
+
+// Detect CI environment (GitHub Actions, CI simulation, etc.)
+const isCI = process.env.CI === 'true' || process.env.CI_SIMULATION === 'true';
+
+const sharedTransform = {
+  '^.+\\.js$': ['babel-jest', {
+    configFile: false,
+    babelrc: false,
+    presets: [['@babel/preset-env', { targets: { node: 'current' } }]],
+    plugins: ['@babel/plugin-syntax-optional-chaining']
+  }]
+};
+
+/**
+ * Single-file Jest project (fresh module graph when run in a separate process).
+ * @param {string} displayName - Jest project display name
+ * @param {string[]} testMatch - Glob patterns for test files
+ * @returns {object} Jest project configuration object
+ */
+function makeIsolatedProject(displayName, testMatch) {
+  return {
+    displayName,
+    testEnvironment: 'node',
+    transform: sharedTransform,
+    testMatch,
+    testPathIgnorePatterns: ['/node_modules/', '\\\\node_modules\\\\'],
+    setupFiles: ['<rootDir>/tests/capture-real-fs.js'],
+    setupFilesAfterEnv: ['<rootDir>/tests/setup.js'],
+    testTimeout: isCI ? 10000 : 5000,
+    maxWorkers: 1
+  };
+}
+
+const defaultProject = {
+  displayName: 'default',
+  testEnvironment: 'node',
+  transform: sharedTransform,
+  testMatch: [
+    '**/tests/**/*.test.js',
+    '**/tests/**/*.spec.js'
+  ],
+  testPathIgnorePatterns: (() => {
+    const patterns = [
+      '/node_modules/',
+      '\\\\node_modules\\\\',
+      '/tests/integration/',
+      '\\\\tests\\\\integration\\\\',
+      '/tests/manual/',
+      '\\\\tests\\\\manual\\\\',
+      'lib/utils/cli-utils.test.js',
+      'lib/utils/external-system-display.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/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\\\\datasource-validation-watch.test.js',
+      'lib/utils/dev-hosts-helper.test.js',
+      'lib/utils/declarative-url-matrix-d-reload.test.js',
+      'lib/utils/datasource-validation-watch.test.js',
+      'dev-hosts-helper\\.test\\.js',
+      'declarative-url-matrix-d-reload\\.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/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',
+      '/tests/lib/parameters/infra-platform-contract.test.js',
+      '\\\\tests\\\\lib\\\\parameters\\\\infra-platform-contract.test.js',
+      'lib/parameters/infra-platform-contract.test.js',
+      '/tests/lib/parameters/database-secret-values.test.js',
+      '\\\\tests\\\\lib\\\\parameters\\\\database-secret-values.test.js',
+      'lib/parameters/database-secret-values.test.js',
+      'database-secret-values\\.test\\.js',
+      '/tests/lib/parameters/infra-parameter-validate.test.js',
+      '\\\\tests\\\\lib\\\\parameters\\\\infra-parameter-validate.test.js',
+      'lib/parameters/infra-parameter-validate.test.js',
+      'infra-parameter-validate\\.test\\.js',
+      '/tests/lib/parameters/infra-parameter-catalog.test.js',
+      '\\\\tests\\\\lib\\\\parameters\\\\infra-parameter-catalog.test.js',
+      'lib/parameters/infra-parameter-catalog.test.js',
+      'infra-parameter-catalog\\.test\\.js',
+      '/tests/lib/utils/urls-local-registry.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\urls-local-registry.test.js',
+      'lib/utils/urls-local-registry.test.js',
+      'urls-local-registry\\.test\\.js',
+      '/tests/lib/utils/aifabrix-runtime-config-dir.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\aifabrix-runtime-config-dir.test.js',
+      'lib/utils/aifabrix-runtime-config-dir.test.js',
+      'aifabrix-runtime-config-dir\\.test\\.js',
+      '/tests/lib/parameters/platform-env-template-kv-catalog.test.js',
+      '\\\\tests\\\\lib\\\\parameters\\\\platform-env-template-kv-catalog.test.js',
+      'lib/parameters/platform-env-template-kv-catalog.test.js',
+      'platform-env-template-kv-catalog\\.test\\.js',
+      '/tests/lib/infrastructure/resolve-infra-state-paths.test.js',
+      '\\\\tests\\\\lib\\\\infrastructure\\\\resolve-infra-state-paths.test.js',
+      'lib/infrastructure/resolve-infra-state-paths.test.js',
+      'resolve-infra-state-paths\\.test\\.js',
+      '/tests/lib/utils/dev-ssh-config-helper.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\dev-ssh-config-helper.test.js',
+      'lib/utils/dev-ssh-config-helper.test.js',
+      'dev-ssh-config-helper\\.test\\.js',
+      '/tests/lib/utils/ssh-key-helper.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\ssh-key-helper.test.js',
+      'lib/utils/ssh-key-helper.test.js',
+      'ssh-key-helper\\.test\\.js',
+      '/tests/lib/core/secrets-ensure-catalog-fallback.test.js',
+      '\\\\tests\\\\lib\\\\core\\\\secrets-ensure-catalog-fallback.test.js',
+      'lib/core/secrets-ensure-catalog-fallback.test.js',
+      'secrets-ensure-catalog-fallback\\.test\\.js',
+      '/tests/lib/core/secrets-ensure.test.js',
+      '\\\\tests\\\\lib\\\\core\\\\secrets-ensure.test.js',
+      'lib/core/secrets-ensure.test.js',
+      'secrets-ensure\\.test\\.js',
+      '/tests/lib/utils/url-declarative-vdir-inactive-env.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\url-declarative-vdir-inactive-env.test.js',
+      'lib/utils/url-declarative-vdir-inactive-env.test.js',
+      'url-declarative-vdir-inactive-env\\.test\\.js',
+      '/tests/lib/utils/app-service-env-from-builder.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\app-service-env-from-builder.test.js',
+      'lib/utils/app-service-env-from-builder.test.js',
+      'app-service-env-from-builder\\.test\\.js',
+      '/tests/lib/parameters/infra-kv-discovery.test.js',
+      '\\\\tests\\\\lib\\\\parameters\\\\infra-kv-discovery.test.js',
+      'lib/parameters/infra-kv-discovery.test.js',
+      'infra-kv-discovery\\.test\\.js',
+      '/tests/lib/utils/infra-env-defaults.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\infra-env-defaults.test.js',
+      'lib/utils/infra-env-defaults.test.js',
+      'infra-env-defaults\\.test\\.js',
+      '/tests/lib/infrastructure/compose-traefik-template.test.js',
+      '\\\\tests\\\\lib\\\\infrastructure\\\\compose-traefik-template.test.js',
+      'lib/infrastructure/compose-traefik-template.test.js',
+      'compose-traefik-template\\.test\\.js',
+      '/tests/lib/utils/paths-app-listing.test.js',
+      '\\\\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/generator/generator-external-rbac.test.js',
+      '\\\\tests\\\\lib\\\\generator\\\\generator-external-rbac.test.js',
+      'lib/generator/generator-external-rbac.test.js',
+      'generator-external-rbac\\.test\\.js',
+      '/tests/lib/infrastructure/helpers-ensure-admin-secrets.test.js',
+      '\\\\tests\\\\lib\\\\infrastructure\\\\helpers-ensure-admin-secrets.test.js',
+      'lib/infrastructure/helpers-ensure-admin-secrets.test.js',
+      'helpers-ensure-admin-secrets\\.test\\.js',
+      '/tests/lib/utils/secrets-generator.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\secrets-generator.test.js',
+      'lib/utils/secrets-generator.test.js',
+      'secrets-generator\\.test\\.js',
+      '/tests/lib/app/app-uncovered-lines.test.js',
+      '\\\\tests\\\\lib\\\\app\\\\app-uncovered-lines.test.js',
+      'lib/app/app-uncovered-lines.test.js',
+      'app-uncovered-lines\\.test\\.js',
+      '/tests/lib/utils/ensure-dev-certs-for-remote-docker.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\ensure-dev-certs-for-remote-docker.test.js',
+      'lib/utils/ensure-dev-certs-for-remote-docker.test.js',
+      'ensure-dev-certs-for-remote-docker\\.test\\.js',
+      '/tests/lib/generator/generator-error-paths.test.js',
+      '\\\\tests\\\\lib\\\\generator\\\\generator-error-paths.test.js',
+      'lib/generator/generator-error-paths.test.js',
+      'generator-error-paths\\.test\\.js',
+      '/tests/lib/core/secrets-databaselog.test.js',
+      '\\\\tests\\\\lib\\\\core\\\\secrets-databaselog.test.js',
+      'lib/core/secrets-databaselog.test.js',
+      'secrets-databaselog\\.test\\.js',
+      '/tests/lib/validation/schema-241-alignment.test.js',
+      '\\\\tests\\\\lib\\\\validation\\\\schema-241-alignment.test.js',
+      'lib/validation/schema-241-alignment.test.js',
+      'schema-241-alignment\\.test\\.js',
+      '/tests/lib/app/app.test.js',
+      '\\\\tests\\\\lib\\\\app\\\\app.test.js',
+      'lib/app/app.test.js'
+    ];
+    if (process.env.INCLUDE_LOCAL_TESTS !== 'true') {
+      patterns.push('/tests/local/');
+      patterns.push('\\\\tests\\\\local\\\\');
+    }
+    return patterns;
+  })(),
+  setupFiles: ['<rootDir>/tests/capture-real-fs.js'],
+  setupFilesAfterEnv: ['<rootDir>/tests/setup.js'],
+  testTimeout: isCI ? 10000 : 5000,
+  detectOpenHandles: true,
+  maxWorkers: 1
+};
+
+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('paths-app-listing', ['**/tests/lib/utils/paths-app-listing.test.js']),
+  makeIsolatedProject('datasource-validation-watch', [
+    '**/tests/lib/utils/datasource-validation-watch.test.js'
+  ]),
+  makeIsolatedProject('datasource-test-run-schema-sync', [
+    '**/tests/lib/utils/datasource-test-run-schema-sync.test.js'
+  ]),
+  makeIsolatedProject('infra-platform-contract', [
+    '**/tests/lib/parameters/infra-platform-contract.test.js'
+  ]),
+  makeIsolatedProject('database-secret-values', [
+    '**/tests/lib/parameters/database-secret-values.test.js'
+  ]),
+  makeIsolatedProject('infra-parameter-validate', [
+    '**/tests/lib/parameters/infra-parameter-validate.test.js'
+  ]),
+  makeIsolatedProject('infra-parameter-catalog', [
+    '**/tests/lib/parameters/infra-parameter-catalog.test.js'
+  ]),
+  makeIsolatedProject('urls-local-registry', ['**/tests/lib/utils/urls-local-registry.test.js']),
+  makeIsolatedProject('aifabrix-runtime-config-dir', [
+    '**/tests/lib/utils/aifabrix-runtime-config-dir.test.js'
+  ]),
+  makeIsolatedProject('platform-env-template-kv-catalog', [
+    '**/tests/lib/parameters/platform-env-template-kv-catalog.test.js'
+  ]),
+  makeIsolatedProject('resolve-infra-state-paths', [
+    '**/tests/lib/infrastructure/resolve-infra-state-paths.test.js'
+  ]),
+  makeIsolatedProject('dev-ssh-config-helper', [
+    '**/tests/lib/utils/dev-ssh-config-helper.test.js'
+  ]),
+  makeIsolatedProject('ssh-key-helper', ['**/tests/lib/utils/ssh-key-helper.test.js']),
+  makeIsolatedProject('secrets-ensure-catalog-fallback', [
+    '**/tests/lib/core/secrets-ensure-catalog-fallback.test.js'
+  ]),
+  makeIsolatedProject('secrets-ensure', ['**/tests/lib/core/secrets-ensure.test.js']),
+  makeIsolatedProject('url-declarative-vdir-inactive-env', [
+    '**/tests/lib/utils/url-declarative-vdir-inactive-env.test.js'
+  ]),
+  makeIsolatedProject('app-service-env-from-builder', [
+    '**/tests/lib/utils/app-service-env-from-builder.test.js'
+  ]),
+  makeIsolatedProject('infra-kv-discovery', ['**/tests/lib/parameters/infra-kv-discovery.test.js']),
+  makeIsolatedProject('infra-env-defaults', ['**/tests/lib/utils/infra-env-defaults.test.js']),
+  makeIsolatedProject('compose-traefik-template', [
+    '**/tests/lib/infrastructure/compose-traefik-template.test.js'
+  ]),
+  makeIsolatedProject('generator-external-rbac', [
+    '**/tests/lib/generator/generator-external-rbac.test.js'
+  ]),
+  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', [
+    '**/tests/lib/utils/ensure-dev-certs-for-remote-docker.test.js'
+  ]),
+  makeIsolatedProject('generator-error-paths', ['**/tests/lib/generator/generator-error-paths.test.js']),
+  makeIsolatedProject('secrets-databaselog', ['**/tests/lib/core/secrets-databaselog.test.js']),
+  makeIsolatedProject('schema-241-alignment', ['**/tests/lib/validation/schema-241-alignment.test.js']),
+  makeIsolatedProject('app-module', ['**/tests/lib/app/app.test.js'])
+];
+
+const allProjects = [defaultProject, ...isolatedProjects];
+
+module.exports = {
+  isCI,
+  sharedTransform,
+  makeIsolatedProject,
+  defaultProject,
+  isolatedProjects,
+  allProjects
+};

package/lib/api/datasources-core.api.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Datasources Core API functions (Dataplane /api/v1/external/). All functions require Dataplane auth; scope per endpoint in dataplane OpenAPI (e.g. external-system:read, external-system:create).
+ * @fileoverview Datasources Core API functions (Dataplane /api/v1/external). All functions require Dataplane auth; scope per endpoint in dataplane OpenAPI (e.g. external-system:read, external-system:create).
  * @author AI Fabrix Team
  * @version 2.0.0
  */
@@ -9,12 +9,12 @@ const { ApiClient } = require('./index');
 /** @requiresPermission {Dataplane} external-system:read (datasource list) */
 async function listDatasources(dataplaneUrl, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
-  return await client.get('/api/v1/external/', { params: options });
+  return await client.get('/api/v1/external', { params: options });
 }
 /** @requiresPermission {Dataplane} external-system:create */
 async function createDatasource(dataplaneUrl, authConfig, datasourceData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
-  return await client.post('/api/v1/external/', { body: datasourceData });
+  return await client.post('/api/v1/external', { body: datasourceData });
 }
 /** @requiresPermission {Dataplane} external-system:read */
 async function getDatasource(dataplaneUrl, sourceIdOrKey, authConfig) {

package/lib/api/dev-mtls-request.js

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview HTTPS requests to Builder Server with TLS client certificate (mTLS).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const https = require('https');
+const { mergedCaForDevServer, DEFAULT_TIMEOUT_MS } = require('./dev-server-https');
+
+/**
+ * Build request options and TLS agent for mTLS request.
+ * @param {string} url - Full URL
+ * @param {Object} options - { method, headers, body }
+ * @param {string} certPem - PEM client certificate
+ * @param {string} keyPem - PEM client key
+ * @param {string} [serverCaPem] - Optional dev root CA
+ * @returns {{ urlObj: URL, method: string, headers: Object, body: string|undefined, agent: https.Agent, tlsOptions: Object }}
+ */
+function buildMtlsRequestOptions(url, options, certPem, keyPem, serverCaPem) {
+  const urlObj = new URL(url);
+  const method = (options.method || 'GET').toUpperCase();
+  const headers = { 'Content-Type': 'application/json', ...options.headers };
+  let body = options.body;
+  if (body !== undefined && typeof body !== 'string') {
+    body = JSON.stringify(body);
+  }
+  if (body) {
+    headers['Content-Length'] = Buffer.byteLength(body, 'utf8');
+  }
+  const merged = mergedCaForDevServer(serverCaPem);
+  const tlsOptions = { cert: certPem, key: keyPem, rejectUnauthorized: true };
+  if (merged) {
+    tlsOptions.ca = merged;
+  }
+  const agent = new https.Agent(tlsOptions);
+  return { urlObj, method, headers, body, agent, tlsOptions };
+}
+
+/**
+ * @param {import('http').IncomingMessage} res - HTTP response
+ * @param {Function} resolve - Promise resolve
+ * @param {Function} reject - Promise reject
+ */
+function handleMtlsResponse(res, resolve, reject) {
+  const chunks = [];
+  res.on('data', (c) => chunks.push(c));
+  res.on('end', () => {
+    const raw = Buffer.concat(chunks).toString('utf8');
+    let data;
+    try {
+      data = raw ? JSON.parse(raw) : {};
+    } catch {
+      data = raw;
+    }
+    if (res.statusCode < 200 || res.statusCode >= 300) {
+      const msg = (data && (data.message || data.error)) || res.statusMessage || `Request failed (${res.statusCode})`;
+      const err = new Error(msg);
+      err.status = res.statusCode;
+      err.errorData = data;
+      reject(err);
+    } else {
+      resolve(data);
+    }
+  });
+}
+
+/**
+ * mTLS JSON request (https only). Sends X-Client-Cert header from options if present.
+ * @param {string} url - Full https URL
+ * @param {Object} options - { method, headers, body }
+ * @param {string} certPem - Client certificate PEM
+ * @param {string} keyPem - Client key PEM
+ * @param {string} [serverCaPem] - Dev root CA PEM
+ * @returns {Promise<Object>}
+ */
+function requestWithClientCert(url, options, certPem, keyPem, serverCaPem) {
+  return new Promise((resolve, reject) => {
+    const urlObj = new URL(url);
+    if (urlObj.protocol !== 'https:') {
+      reject(new Error('mTLS request requires https URL'));
+      return;
+    }
+    const { method, headers, body, agent, tlsOptions } = buildMtlsRequestOptions(
+      url, options, certPem, keyPem, serverCaPem
+    );
+    const req = https.request(
+      {
+        hostname: urlObj.hostname,
+        port: urlObj.port || 443,
+        path: urlObj.pathname + urlObj.search,
+        method,
+        headers,
+        agent,
+        ...tlsOptions
+      },
+      (res) => handleMtlsResponse(res, resolve, reject)
+    );
+    req.on('error', reject);
+    req.setTimeout(DEFAULT_TIMEOUT_MS, () => {
+      req.destroy();
+      reject(new Error(`Request timed out after ${DEFAULT_TIMEOUT_MS}ms`));
+    });
+    if (body) {
+      req.write(body, 'utf8');
+    }
+    req.end();
+  });
+}
+
+module.exports = { requestWithClientCert };

package/lib/api/dev-server-https.js

@@ -0,0 +1,145 @@
+/**
+ * @fileoverview HTTPS JSON requests to Builder Server with dev root CA merged into Node TLS trust.
+ * Node does not use the Windows/macOS user trust store for fetch; OS CA install alone is insufficient.
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const https = require('https');
+const tls = require('tls');
+
+const DEFAULT_TIMEOUT_MS = 15000;
+
+/**
+ * Merge Mozilla roots (bundled in Node) with the dev Builder Server root CA.
+ * @param {string} serverCaPem - PEM-encoded root CA
+ * @returns {string[]|null} CA array for tls/https.Agent
+ */
+function mergedCaForDevServer(serverCaPem) {
+  const pem = typeof serverCaPem === 'string' ? serverCaPem.trim() : '';
+  if (!pem) return null;
+  return [...tls.rootCertificates, pem];
+}
+
+/**
+ * Collect response body, parse JSON, resolve or reject.
+ * @param {import('http').IncomingMessage} res - HTTP response
+ * @param {Function} resolve - Promise resolve
+ * @param {Function} reject - Promise reject
+ */
+function handleJsonHttpsResponse(res, resolve, reject) {
+  const chunks = [];
+  res.on('data', (c) => chunks.push(c));
+  res.on('end', () => {
+    const raw = Buffer.concat(chunks).toString('utf8');
+    let data;
+    try {
+      data = raw ? JSON.parse(raw) : {};
+    } catch {
+      data = raw;
+    }
+    if (res.statusCode < 200 || res.statusCode >= 300) {
+      const msg = (data && (data.message || data.error)) || res.statusMessage || `Request failed (${res.statusCode})`;
+      const err = new Error(msg);
+      err.status = res.statusCode;
+      err.errorData = data;
+      reject(err);
+    } else {
+      resolve(data);
+    }
+  });
+}
+
+/**
+ * @param {string} url
+ * @param {{ method?: string, headers?: Object, body?: * }} options
+ * @param {string} serverCaPem
+ * @returns {{ urlObj: URL, method: string, headers: Object, body: string|undefined, ca: string[] }}
+ */
+function prepareHttpsJsonRequest(url, options, serverCaPem) {
+  const urlObj = new URL(url);
+  if (urlObj.protocol !== 'https:') {
+    throw new Error('Builder Server requests require https URL');
+  }
+  const ca = mergedCaForDevServer(serverCaPem);
+  if (!ca) {
+    throw new Error('serverCaPem is required for httpsJsonRequest');
+  }
+  const method = (options.method || 'GET').toUpperCase();
+  const headers = { 'Content-Type': 'application/json', ...options.headers };
+  let body = options.body;
+  if (body !== undefined && typeof body !== 'string') {
+    body = JSON.stringify(body);
+  }
+  if (body) {
+    headers['Content-Length'] = Buffer.byteLength(body, 'utf8');
+  }
+  return { urlObj, method, headers, body, ca };
+}
+
+/**
+ * HTTPS JSON request with dev-server root CA (no client cert).
+ * @param {string} url - Full https URL
+ * @param {{ method?: string, headers?: Object, body?: * }} options - Request options
+ * @param {string} serverCaPem - Dev root CA PEM
+ * @returns {Promise<Object>} Parsed JSON body on success
+ */
+function httpsJsonRequest(url, options, serverCaPem) {
+  return new Promise((resolve, reject) => {
+    let parts;
+    try {
+      parts = prepareHttpsJsonRequest(url, options, serverCaPem);
+    } catch (e) {
+      reject(e);
+      return;
+    }
+    const { urlObj, method, headers, body, ca } = parts;
+    const agent = new https.Agent({ ca, rejectUnauthorized: true });
+    const req = https.request(
+      {
+        hostname: urlObj.hostname,
+        port: urlObj.port || 443,
+        path: urlObj.pathname + urlObj.search,
+        method,
+        headers,
+        agent,
+        ca,
+        rejectUnauthorized: true
+      },
+      (res) => handleJsonHttpsResponse(res, resolve, reject)
+    );
+    req.on('error', reject);
+    req.setTimeout(DEFAULT_TIMEOUT_MS, () => {
+      req.destroy();
+      reject(new Error(`Request timed out after ${DEFAULT_TIMEOUT_MS}ms`));
+    });
+    if (body) {
+      req.write(body, 'utf8');
+    }
+    req.end();
+  });
+}
+
+/**
+ * Use TLS client cert in the handshake only for https URLs (plain HTTP cannot carry mTLS).
+ * @param {string} fullUrl - Request URL
+ * @param {string} [clientKeyPem] - Client private key PEM
+ * @returns {boolean}
+ */
+function shouldUseMtlsForUrl(fullUrl, clientKeyPem) {
+  if (!clientKeyPem || typeof clientKeyPem !== 'string') {
+    return false;
+  }
+  try {
+    return new URL(fullUrl).protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  mergedCaForDevServer,
+  httpsJsonRequest,
+  DEFAULT_TIMEOUT_MS,
+  shouldUseMtlsForUrl
+};