@aifabrix/builder 2.49.0 → 2.49.2

package/lib/commands/dev-host-ops.js

@@ -0,0 +1,239 @@
+/**
+ * @fileoverview Dev host-ops CLI handlers (platform-install, platform-update, etc.)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const readline = require('readline');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const { getRemoteDevAuth } = require('../utils/remote-dev-auth');
+const hostOpsApi = require('../api/host-ops.api');
+
+const REMOTE_NOT_CONFIGURED_MSG =
+  'Remote server is not configured. Set remote-server and run "aifabrix dev init" first.';
+
+const POLL_INTERVAL_MS = 3000;
+const POLL_TIMEOUT_MS = 3 * 60 * 60 * 1000;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Build job params from Commander options.
+ * @param {Object} options
+ * @param {string} [developerId]
+ * @returns {Object}
+ */
+function buildJobParams(options, developerId) {
+  const params = {};
+  const id = developerId || options.developerId || options['developer-id'];
+  if (id) params.developerId = String(id).trim();
+  if (options.include) params.include = options.include;
+  if (options.exclude) params.exclude = options.exclude;
+  if (options.builderVersion || options['builder-version']) {
+    params.builderVersion = options.builderVersion || options['builder-version'];
+  }
+  if (options.adminEmail || options['admin-email']) {
+    params.adminEmail = options.adminEmail || options['admin-email'];
+  }
+  if (options.adminPassword || options['admin-password']) {
+    params.adminPassword = options.adminPassword || options['admin-password'];
+  }
+  if (options.platform) params.platform = options.platform;
+  if (options.installation) params.installation = options.installation;
+  if (options.skipCert || options['skip-cert']) params.skipCert = true;
+  if (options.skipPlatform || options['skip-platform']) params.skipPlatform = true;
+  if (options.skipCli || options['skip-cli']) params.skipCli = true;
+  if (options.check) params.check = true;
+  if (options.failOnBlocked) params.failOnBlocked = true;
+  if (options.timeoutMinutes || options['timeout-minutes']) {
+    params.timeoutMinutes = parseInt(options.timeoutMinutes || options['timeout-minutes'], 10);
+  }
+  return params;
+}
+
+/**
+ * Poll host-ops job until terminal state.
+ * @param {Object} auth
+ * @param {string} jobId
+ * @param {Object} [opts]
+ * @param {boolean} [opts.wait=true]
+ * @param {boolean} [opts.json=false]
+ * @returns {Promise<Object>}
+ */
+async function waitForHostOpsJob(auth, jobId, opts = {}) {
+  const wait = opts.wait !== false;
+  const json = Boolean(opts.json);
+  if (!wait) {
+    return { jobId, status: 'pending' };
+  }
+  const started = Date.now();
+  while (Date.now() - started < POLL_TIMEOUT_MS) {
+    const job = await hostOpsApi.getHostOpsJob(
+      auth.serverUrl,
+      auth.clientCertPem,
+      jobId,
+      auth.serverCaPem || undefined
+    );
+    if (!json) {
+      logger.log(chalk.gray(`  host-ops job ${jobId}: ${job.status}`));
+    }
+    if (job.status === 'completed' || job.status === 'failed') {
+      if (job.status === 'failed') {
+        throw new Error(job.error || `Host-ops job ${jobId} failed`);
+      }
+      return job;
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new Error(`Timed out waiting for host-ops job ${jobId}`);
+}
+
+/**
+ * @param {string} question
+ * @returns {Promise<boolean>}
+ */
+function promptYesNo(question) {
+  if (!process.stdin.isTTY) {
+    return Promise.resolve(false);
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(String(answer || '').trim()));
+    });
+  });
+}
+
+function platformAlreadyInstalled(outcomes) {
+  if (!Array.isArray(outcomes)) return false;
+  return outcomes.some(
+    (row) =>
+      row &&
+      (row.overall === 'SKIP' || row.status === 'SKIP') &&
+      String(row.detail || '').toLowerCase().includes('installed')
+  );
+}
+
+/**
+ * Run a host-ops job and optionally wait.
+ * @param {string} type
+ * @param {Object} params
+ * @param {Object} options - Commander options (yes, wait, json)
+ * @returns {Promise<Object>}
+ */
+async function runHostOpsJob(type, params, options = {}) {
+  const auth = await getRemoteDevAuth();
+  if (!auth) throw new Error(REMOTE_NOT_CONFIGURED_MSG);
+  const { jobId } = await hostOpsApi.createHostOpsJob(
+    auth.serverUrl,
+    auth.clientCertPem,
+    { type, params },
+    auth.serverCaPem || undefined
+  );
+  if (options.json) {
+    const job = await waitForHostOpsJob(auth, jobId, { wait: options.wait !== false, json: true });
+    logger.log(JSON.stringify(job, null, 2));
+    return job;
+  }
+  const job = await waitForHostOpsJob(auth, jobId, { wait: options.wait !== false, json: false });
+  logger.log(formatSuccessLine(`Host-ops job ${jobId} completed (${type}).`));
+  return job;
+}
+
+async function handlePlatformInstallCli(developerId, options) {
+  const params = buildJobParams(options, developerId);
+  if (options.check) {
+    params.check = true;
+  } else if (!params.builderVersion) {
+    throw new Error('--builder-version is required unless --check is set');
+  }
+  await runHostOpsJob('install-builder-cli', params, options);
+}
+
+async function handlePlatformUpdate(developerId, options) {
+  const params = buildJobParams(options, developerId);
+  if (options.check) params.check = true;
+  await runHostOpsJob('update-dev-platform', params, options);
+}
+
+async function handlePlatformInstall(developerId, options) {
+  if (!developerId) {
+    throw new Error('Developer ID is required (positional argument).');
+  }
+  const params = buildJobParams(options, developerId);
+
+  if (options.check) {
+    params.check = true;
+    const auth = await getRemoteDevAuth();
+    if (!auth) throw new Error(REMOTE_NOT_CONFIGURED_MSG);
+    const { jobId } = await hostOpsApi.preflightHostOps(
+      auth.serverUrl,
+      auth.clientCertPem,
+      { type: 'install-dev-platform', params },
+      auth.serverCaPem || undefined
+    );
+    const job = await waitForHostOpsJob(auth, jobId, options);
+    if (options.json) {
+      logger.log(JSON.stringify(job, null, 2));
+    } else if (Array.isArray(job.outcomes)) {
+      job.outcomes.forEach((row) => {
+        logger.log(`  ${row.linuxUser || developerId}: ${row.overall || row.status}${row.detail ? ` — ${row.detail}` : ''}`);
+      });
+    }
+    return job;
+  }
+
+  if (!options.force && !options.yes) {
+    const auth = await getRemoteDevAuth();
+    if (!auth) throw new Error(REMOTE_NOT_CONFIGURED_MSG);
+    const { jobId } = await hostOpsApi.preflightHostOps(
+      auth.serverUrl,
+      auth.clientCertPem,
+      { type: 'install-dev-platform', params: { ...params, developerId } },
+      auth.serverCaPem || undefined
+    );
+    const preflight = await waitForHostOpsJob(auth, jobId, { ...options, json: false });
+    if (platformAlreadyInstalled(preflight.outcomes)) {
+      const ok = await promptYesNo(
+        `Platform already installed for dev${String(developerId).padStart(2, '0')}. Re-install?`
+      );
+      if (!ok) {
+        logger.log(chalk.gray('Cancelled.'));
+        return preflight;
+      }
+      await runHostOpsJob('reinstall-dev-platform', params, options);
+      return;
+    }
+  }
+
+  const jobType = options.force ? 'reinstall-dev-platform' : 'install-dev-platform';
+  await runHostOpsJob(jobType, params, options);
+}
+
+async function handleProvisionDevUser(developerId, options) {
+  const params = buildJobParams(options, developerId);
+  await runHostOpsJob('provision-dev-user', params, options);
+}
+
+async function handleRemoveDevUser(developerId, options) {
+  const params = buildJobParams(options, developerId);
+  if (!params.developerId) {
+    throw new Error('Developer ID is required.');
+  }
+  await runHostOpsJob('remove-dev-user', params, options);
+}
+
+module.exports = {
+  buildJobParams,
+  waitForHostOpsJob,
+  handlePlatformInstallCli,
+  handlePlatformUpdate,
+  handlePlatformInstall,
+  handleProvisionDevUser,
+  handleRemoveDevUser
+};

package/lib/commands/teardown.js

@@ -120,17 +120,15 @@ function cleanAifabrixSystemDir() {
 }
 
 /**
- * Remove materialized `builder/` trees (aifabrix-work, aifabrix-home / config dir, cwd).
- * Complements {@link cleanAifabrixSystemDir} when `builder/` lives under `aifabrix-work` outside
- * the config directory.
+ * Remove materialized `builder/` trees under home/work and config dir only.
+ * Does not remove `cwd/builder` in product repos (e.g. aifabrix-dataplane/builder/dataplane).
  *
  * @returns {{ removed: string[], failed: string[] }}
  */
 function cleanMaterializedBuilderTrees() {
   const candidates = [
     pathsUtil.getBuilderRoot(),
-    path.join(pathsUtil.getAifabrixSystemDir(), 'builder'),
-    path.join(process.cwd(), 'builder')
+    path.join(pathsUtil.getAifabrixSystemDir(), 'builder')
   ];
   const seen = new Set();
   const removed = [];

package/lib/commands/up-common.js

@@ -242,26 +242,21 @@ function isUnderAllowedBuilderRoot(resolvedAppPath, allowedRoots) {
 }
 
 /**
- * Removes builder app directories for the given app names. Only removes paths under an allowed
- * builder root (project `builder/` or `~/.aifabrix/builder/`) to prevent path traversal.
- * Uses {@link pathsUtil.getBuilderPath} for each app (system apps may resolve under the config dir).
+ * Removes platform app directories under the home/work materialized `builder/` root only.
+ * Never deletes `cwd/builder` trees in product repos (e.g. aifabrix-miso/builder/miso-controller).
  *
  * @param {string[]} appNames - Application names (e.g. ['keycloak', 'miso-controller', 'dataplane'])
  * @returns {Promise<void>}
- * @throws {Error} If any path is outside allowed builder roots (path traversal attempt)
+ * @throws {Error} If any path is outside the home builder root (path traversal attempt)
  */
 async function cleanBuilderAppDirs(appNames, opts = {}) {
   const silent = Boolean(opts.silent);
   if (!Array.isArray(appNames) || appNames.length === 0) return;
-  const allowedRoots = uniqueResolvedRoots([
-    path.join(process.cwd(), 'builder'),
-    pathsUtil.getBuilderRoot(),
-    pathsUtil.getSystemBuilderRoot()
-  ]);
+  const allowedRoots = uniqueResolvedRoots([pathsUtil.getSystemBuilderRoot()]);
   const cleaned = [];
   for (const appName of appNames) {
     if (!appName || typeof appName !== 'string') continue;
-    const appPath = path.resolve(pathsUtil.getBuilderPath(appName));
+    const appPath = path.resolve(pathsUtil.getHomeBuilderAppPath(appName));
     if (!isUnderAllowedBuilderRoot(appPath, allowedRoots)) {
       throw new Error(
         `Path ${appPath} is outside allowed builder roots (${allowedRoots.join(', ')}); refusing to clean`
@@ -303,7 +298,9 @@ async function ensureAppFromTemplate(appName, opts = {}) {
   }
   const silent = Boolean(opts.silent);
 
-  const appPath = pathsUtil.getBuilderPath(appName);
+  const appPath = pathsUtil.isSystemBuilderAppName(appName)
+    ? pathsUtil.getHomeBuilderAppPath(appName)
+    : pathsUtil.getBuilderPath(appName);
   const primaryCopied = await ensureTemplateAtPath(appName, appPath);
   if (primaryCopied && !silent) {
     logger.log(chalk.blue(`Creating builder/${appName} from template...`));

package/lib/commands/up-dataplane.js

@@ -41,6 +41,17 @@ const {
 } = require('./up-dataplane-bootstrap');
 
 const CONTROLLER_HEALTH_PATH = '/health';
+/** Automation / af-server: wait for edge routing before dataplane (nginx + Traefik). */
+const CONTROLLER_HEALTH_RETRY_ATTEMPTS = 30;
+const CONTROLLER_HEALTH_RETRY_DELAY_MS = 2000;
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 
 /**
  * Check if controller is reachable (health endpoint).
@@ -76,19 +87,46 @@ function promptForControllerUrl(currentUrl) {
 }
 
 /**
- * Resolve controller URL and ensure it is healthy; if not, prompt once for new URL.
- * @returns {Promise<string>} Controller URL to use
- * @throws {Error} If controller unavailable and user aborts or new URL still unhealthy
+ * Poll controller /health until success or attempts exhausted.
+ * @param {string} baseUrl - Controller base URL (no trailing slash)
+ * @param {{ attempts?: number, delayMs?: number }} [opts]
+ * @returns {Promise<boolean>}
  */
-async function resolveControllerUrlWithHealthCheck() {
-  let controllerUrl = await resolveControllerUrl();
-  controllerUrl = controllerUrl.replace(/\/+$/, '');
-
-  let healthy = await isControllerHealthy(controllerUrl);
-  if (healthy) {
-    return controllerUrl;
+async function waitForControllerHealthy(baseUrl, opts = {}) {
+  const attempts = opts.attempts ?? CONTROLLER_HEALTH_RETRY_ATTEMPTS;
+  const delayMs = opts.delayMs ?? CONTROLLER_HEALTH_RETRY_DELAY_MS;
+  const normalized = baseUrl.replace(/\/+$/, '');
+  for (let i = 0; i < attempts; i += 1) {
+    if (await isControllerHealthy(normalized)) {
+      return true;
+    }
+    if (i < attempts - 1) {
+      await sleep(delayMs);
+    }
   }
+  return false;
+}
+
+/**
+ * @param {string} controllerUrl
+ * @returns {string}
+ */
+function buildControllerUnavailableMessage(controllerUrl) {
+  return (
+    `Controller at ${controllerUrl} is not responding after ${CONTROLLER_HEALTH_RETRY_ATTEMPTS} health checks ` +
+    `(~${Math.round((CONTROLLER_HEALTH_RETRY_ATTEMPTS * CONTROLLER_HEALTH_RETRY_DELAY_MS) / 1000)}s). ` +
+    'Miso may be up on localhost before nginx/Traefik routes are ready. ' +
+    'On the builder host run: sudo systemctl start aifabrix-sync-dev-traefik-nginx.service ' +
+    'then retry: aifabrix up-dataplane --force'
+  );
+}
 
+/**
+ * Prompt for a new controller URL and verify it responds to health checks.
+ * @param {string} controllerUrl - URL that failed the initial health check
+ * @returns {Promise<string>} Verified controller URL
+ */
+async function promptForHealthyControllerUrl(controllerUrl) {
   logger.log(chalk.yellow(`\nController at ${controllerUrl} is not responding (health check failed).\n`));
   const newUrl = await promptForControllerUrl(controllerUrl);
   if (!newUrl) {
@@ -103,7 +141,7 @@ async function resolveControllerUrlWithHealthCheck() {
 
   await setControllerUrl(newUrl);
   const normalizedNew = newUrl.trim().replace(/\/+$/, '');
-  healthy = await isControllerHealthy(normalizedNew);
+  const healthy = await isControllerHealthy(normalizedNew);
   if (!healthy) {
     throw new Error(`Controller at ${normalizedNew} is not responding. Ensure the controller is running and reachable, then run "aifabrix up-dataplane" again.`);
   }
@@ -112,6 +150,28 @@ async function resolveControllerUrlWithHealthCheck() {
   return normalizedNew;
 }
 
+/**
+ * Resolve controller URL and ensure it is healthy; if not, prompt once for new URL (TTY only).
+ * @returns {Promise<string>} Controller URL to use
+ * @throws {Error} If controller unavailable and user aborts or new URL still unhealthy
+ */
+async function resolveControllerUrlWithHealthCheck() {
+  let controllerUrl = await resolveControllerUrl();
+  controllerUrl = controllerUrl.replace(/\/+$/, '');
+
+  const healthy = await waitForControllerHealthy(controllerUrl);
+  if (healthy) {
+    return controllerUrl;
+  }
+
+  const isInteractive = Boolean(process.stdin && process.stdin.isTTY);
+  if (!isInteractive) {
+    throw new Error(buildControllerUnavailableMessage(controllerUrl));
+  }
+
+  return promptForHealthyControllerUrl(controllerUrl);
+}
+
 async function resolveUpDataplaneAuthContext(options, environmentKey) {
   if (options.skipInfraCheck !== true) {
     await assertDevInfraUp();
@@ -327,14 +387,22 @@ async function handleUpDataplane(options = {}) {
 
   const { runEnvKey, portOverride } = await computeDataplaneRunOverrides(options);
 
-  await app.runApp('dataplane', {
+  const runAppOpts = {
     skipEnvOutputPath: true,
     env: runEnvKey,
     port: portOverride,
     registry: options.registry || undefined,
     base: options.base !== false,
     skipManifestMetadataLine: true
-  });
+  };
+  if (options.platformInstall === true) {
+    if (typeof options.onPollText === 'function') {
+      runAppOpts.onPollText = options.onPollText;
+    } else {
+      runAppOpts.silentPoll = true;
+    }
+  }
+  await app.runApp('dataplane', runAppOpts);
 
   if (options.platformInstall !== true) {
     logger.log(formatSuccessParagraph('up-dataplane complete. Dataplane is registered, deployed in dev, and running locally.'));

package/lib/commands/up-miso.js

@@ -57,11 +57,15 @@ async function runMisoApps(options) {
     base: useBaseImage,
     skipManifestMetadataLine: true
   };
-  const keycloakRunOpts = { ...common };
+  const platformPollOpts =
+    options.platformInstall === true
+      ? { silentPoll: true }
+      : {};
+  const keycloakRunOpts = { ...common, ...platformPollOpts };
   if (imageMap.keycloak) {
     keycloakRunOpts.image = imageMap.keycloak;
   }
-  const misoRunOpts = { ...common };
+  const misoRunOpts = { ...common, ...platformPollOpts };
   if (imageMap['miso-controller']) {
     misoRunOpts.image = imageMap['miso-controller'];
   }

package/lib/schema/external-system.schema.json

@@ -212,7 +212,8 @@
                   "compileCom",
                   "generateEnterpriseDatasources",
                   "generateRestContracts",
-                  "generateMcpContracts"
+                  "generateMcpContracts",
+                  "runDigitalWorkerTask"
                ],
                "description": "Platform task type executed when the subscription fires."
             },
@@ -221,6 +222,104 @@
                "minimum": 1,
                "default": 1,
                "description": "Task definition version snapshot for audit."
+            },
+            "digitalWorkerKey": {
+               "type": "string",
+               "minLength": 1,
+               "description": "Target digital worker system key (runDigitalWorkerTask)."
+            },
+            "taskType": {
+               "type": "string",
+               "minLength": 1,
+               "description": "Worker task type label (runDigitalWorkerTask)."
+            },
+            "objectiveTemplate": {
+               "type": "string",
+               "description": "Objective template with {{recordId}} placeholders."
+            },
+            "requiresApproval": {
+               "type": "boolean",
+               "default": false
+            },
+            "owner": {
+               "$ref": "#/$defs/subscriptionTaskOwner"
+            }
+         },
+         "additionalProperties": false
+      },
+      "subscriptionCondition": {
+         "type": "object",
+         "required": [
+            "field",
+            "operator"
+         ],
+         "properties": {
+            "field": {
+               "type": "string",
+               "minLength": 1,
+               "description": "Path against afterSummary (default) or before.* prefix."
+            },
+            "operator": {
+               "type": "string",
+               "enum": [
+                  "equals",
+                  "notEquals",
+                  "in",
+                  "notIn",
+                  "exists",
+                  "missing",
+                  "changed",
+                  "greaterThan",
+                  "lessThan"
+               ]
+            },
+            "value": {}
+         },
+         "additionalProperties": false
+      },
+      "subscriptionTriggerPolicy": {
+         "type": "object",
+         "required": [
+            "mode"
+         ],
+         "properties": {
+            "mode": {
+               "type": "string",
+               "enum": [
+                  "immediate",
+                  "debounce",
+                  "scheduled"
+               ]
+            },
+            "windowSeconds": {
+               "type": "integer",
+               "minimum": 1,
+               "description": "Required when mode is debounce."
+            }
+         },
+         "additionalProperties": false
+      },
+      "subscriptionTaskOwner": {
+         "type": "object",
+         "required": [
+            "mode"
+         ],
+         "properties": {
+            "mode": {
+               "type": "string",
+               "enum": [
+                  "explicit",
+                  "recordField"
+               ]
+            },
+            "userId": {
+               "type": "string",
+               "minLength": 1
+            },
+            "field": {
+               "type": "string",
+               "minLength": 1,
+               "description": "Record summary field for recordField mode."
             }
          },
          "additionalProperties": false
@@ -251,11 +350,24 @@
             "event": {
                "type": "string",
                "minLength": 1,
-               "description": "V1 event namespace (platform.* or schedule.*)."
+               "description": "V1 event namespace (platform.*, schedule.*, or record.*)."
             },
             "filter": {
                "$ref": "#/$defs/subscriptionFilter"
             },
+            "conditions": {
+               "type": "array",
+               "items": {
+                  "$ref": "#/$defs/subscriptionCondition"
+               }
+            },
+            "triggerPolicy": {
+               "$ref": "#/$defs/subscriptionTriggerPolicy"
+            },
+            "deduplicationKeyTemplate": {
+               "type": "string",
+               "description": "Default: {{subscriptionId}}:{{resourceType}}:{{recordId}}:{{task.taskType}}"
+            },
             "task": {
                "$ref": "#/$defs/subscriptionTask"
             },