@aifabrix/builder 2.49.0 → 2.49.2

package/.cursor/process/README.md

@@ -0,0 +1,9 @@
+# Process documentation
+
+Canonical process descriptions for aifabrix-builder automation and release workflows.
+
+| Process | Description |
+| ------- | ----------- |
+| [deployment.md](./deployment.md) | NPM release: preflight, release branch CI, PR to `main`, publish and GitHub release |
+
+Command specs (agent-executable) live under [`.cursor/commands/`](../commands/).

package/.cursor/skills/README.md

@@ -0,0 +1,14 @@
+# aifabrix-builder Cursor skills
+
+| Skill | Command | Purpose |
+| ----- | ------- | ------- |
+| [builder-push-github](builder-push-github/SKILL.md) | `/push-github` | Release branch CI + optional NPM deploy PR |
+| [builder-repair-release](builder-repair-release/SKILL.md) | `/repair-release` | Version bump + CHANGELOG |
+| [builder-validate-tests](builder-validate-tests/SKILL.md) | `/validate-tests` | Lint + Jest fix loop |
+| [builder-validate-tests-ci](builder-validate-tests-ci/SKILL.md) | `/validate-tests.ci` | `build:ci` / GitHub parity |
+| [builder-validate-code](builder-validate-code/SKILL.md) | `/validate-code` | Code analysis → improvement plans |
+| [builder-validate-plan](builder-validate-plan/SKILL.md) | `/validate-plan` | Pre-implementation plan validation |
+| [builder-validate-implementation](builder-validate-implementation/SKILL.md) | `/validate-implementation` | Post-implementation plan validation |
+| [builder-validate-knowledgebase](builder-validate-knowledgebase/SKILL.md) | `/validate-knowledgebase` | `docs/` + schema validation |
+
+Commands live in `.cursor/commands/`.

package/lib/api/dev.api.js

@@ -391,6 +391,7 @@ async function deleteSecret(serverUrl, clientCertPem, key, serverCaPem, secretsE
 }
 
 module.exports = {
+  request,
   issueCert,
   getHealth,
   getSettings,

package/lib/api/host-ops.api.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Builder Server host-ops API
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const devApi = require('./dev.api');
+
+/**
+ * Create host-ops job. POST /api/dev/host-ops/jobs
+ * @param {string} serverUrl
+ * @param {string} clientCertPem
+ * @param {Object} body - { type, params }
+ * @param {string} [serverCaPem]
+ * @returns {Promise<{ jobId: string, status: string }>}
+ */
+async function createHostOpsJob(serverUrl, clientCertPem, body, serverCaPem) {
+  const base = devApi.normalizeBaseUrl(serverUrl);
+  return devApi.request(devApi.buildUrl(base, '/api/dev/host-ops/jobs'), {
+    method: 'POST',
+    headers: { 'X-Client-Cert': devApi.encodeCertForHeader(clientCertPem) },
+    body,
+    serverCaPem
+  });
+}
+
+/**
+ * Get host-ops job. GET /api/dev/host-ops/jobs/:jobId
+ * @param {string} serverUrl
+ * @param {string} clientCertPem
+ * @param {string} jobId
+ * @param {string} [serverCaPem]
+ * @returns {Promise<Object>}
+ */
+async function getHostOpsJob(serverUrl, clientCertPem, jobId, serverCaPem) {
+  const base = devApi.normalizeBaseUrl(serverUrl);
+  return devApi.request(
+    devApi.buildUrl(base, `/api/dev/host-ops/jobs/${encodeURIComponent(jobId)}`),
+    {
+      method: 'GET',
+      headers: { 'X-Client-Cert': devApi.encodeCertForHeader(clientCertPem) },
+      serverCaPem
+    }
+  );
+}
+
+/**
+ * Queue preflight (check-only job). POST /api/dev/host-ops/preflight
+ * @param {string} serverUrl
+ * @param {string} clientCertPem
+ * @param {Object} body - { type, params }
+ * @param {string} [serverCaPem]
+ * @returns {Promise<{ jobId: string, status: string }>}
+ */
+async function preflightHostOps(serverUrl, clientCertPem, body, serverCaPem) {
+  const base = devApi.normalizeBaseUrl(serverUrl);
+  return devApi.request(devApi.buildUrl(base, '/api/dev/host-ops/preflight'), {
+    method: 'POST',
+    headers: { 'X-Client-Cert': devApi.encodeCertForHeader(clientCertPem) },
+    body,
+    serverCaPem
+  });
+}
+
+module.exports = {
+  createHostOpsJob,
+  getHostOpsJob,
+  preflightHostOps
+};

package/lib/cli/infra-guided-auth.js

@@ -123,10 +123,14 @@ async function runGuidedDataplaneWithAuthRecovery(
   ui = {}
 ) {
   const onSpinnerText = typeof ui.onSpinnerText === 'function' ? ui.onSpinnerText : null;
+  const dataplaneOpts = {
+    ...options,
+    platformInstall: true,
+    skipInfraCheck: true,
+    ...(onSpinnerText ? { onPollText: onSpinnerText } : {})
+  };
   try {
-    await withMutedLogger(() =>
-      handleUpDataplane({ ...options, platformInstall: true, skipInfraCheck: true })
-    );
+    await withMutedLogger(() => handleUpDataplane(dataplaneOpts));
   } catch (error) {
     if (!isAuthenticationError(error)) {
       throw error;
@@ -154,9 +158,7 @@ async function runGuidedDataplaneWithAuthRecovery(
     if (onSpinnerText) {
       onSpinnerText('Validating Dataplane...');
     }
-    await withMutedLogger(() =>
-      handleUpDataplane({ ...options, platformInstall: true, skipInfraCheck: true })
-    );
+    await withMutedLogger(() => handleUpDataplane(dataplaneOpts));
   }
 }
 

package/lib/cli/infra-guided.js

@@ -104,6 +104,9 @@ async function waitForAppReady(appName, opts = {}) {
   if (userCfg && userCfg.traefik === true) {
     healthRunOpts.traefikEnabled = true;
   }
+  if (typeof opts.onPollText === 'function') {
+    healthRunOpts.onPollText = opts.onPollText;
+  }
   await healthCheck.waitForHealthCheck(appName, timeoutSeconds, hostPort, appConfig, false, healthRunOpts);
 }
 
@@ -180,7 +183,10 @@ async function runGuidedUpMiso(options, handleUpMiso) {
   stopSpinnerSuccess(kcSpin, 'Keycloak ready');
   logger.log('');
   const mcSpin = startSpinner('Starting Miso Controller...');
-  await waitForAppReady('miso-controller', { timeoutSeconds: 120 });
+  await waitForAppReady('miso-controller', {
+    timeoutSeconds: 120,
+    onPollText: createSpinnerTextUpdater(mcSpin)
+  });
   stopSpinnerSuccess(mcSpin, 'Miso Controller ready');
   await logMisoReadyFooter();
   await validateAppErrorLogs(['miso-controller']);
@@ -242,7 +248,10 @@ async function runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso) {
   logger.log('');
   emitSystemBuilderAppManifestLineIfTTY(logger, 'miso-controller');
   const mcSpin = startSpinner('Starting Miso Controller...');
-  await waitForAppReady('miso-controller', { timeoutSeconds: 120 });
+  await waitForAppReady('miso-controller', {
+    timeoutSeconds: 120,
+    onPollText: createSpinnerTextUpdater(mcSpin)
+  });
   stopSpinnerSuccess(mcSpin, 'Miso Controller ready');
   logger.log('');
 }

package/lib/cli/setup-dev-path-commands.js

@@ -44,6 +44,29 @@ async function runShellEnvRegistration() {
   }
 }
 
+function addSetEnvConfigCommand(dev) {
+  dev
+    .command('set-env-config <path>')
+    .description('Set or clear aifabrix-env-config path in ~/.aifabrix/config.yaml')
+    .action(async(envConfigPath) => {
+      try {
+        const trimmed = (envConfigPath || '').trim();
+        await config.setAifabrixEnvConfigPath(trimmed);
+        logger.log(
+          trimmed === ''
+            ? formatSuccessLine('Env config path cleared')
+            : formatSuccessLine(`Env config path set to ${trimmed}`)
+        );
+        const devId = await config.getDeveloperId();
+        const { displayDevConfig } = require('../commands/dev-show-display');
+        await displayDevConfig(devId);
+      } catch (error) {
+        handleCommandError(error, 'dev set-env-config');
+        process.exit(1);
+      }
+    });
+}
+
 function addSetHomeCommand(dev) {
   dev
     .command('set-home <path>')
@@ -162,6 +185,7 @@ function addSetFormatCommand(dev, handleSetFormat) {
  * @returns {void}
  */
 function setupDevPathAndFormatCommands(dev, handleSetFormat) {
+  addSetEnvConfigCommand(dev);
   addSetHomeCommand(dev);
   addSetWorkCommand(dev);
   addPrintHomeWorkCommands(dev);

package/lib/cli/setup-dev.js

@@ -21,6 +21,11 @@ const {
   handleDevPin,
   handleDevDelete
 } = require('../commands/dev-cli-handlers');
+const {
+  handlePlatformInstallCli,
+  handlePlatformUpdate,
+  handlePlatformInstall
+} = require('../commands/dev-host-ops');
 
 /** Appended to `dev update --help` (examples + partial-update behaviour). */
 const DEV_UPDATE_HELP_AFTER = `
@@ -49,7 +54,7 @@ const DEV_GROUP_HELP_AFTER = `
 Categories:
   Local config   show, set-id, set-scoped-resources, set-env-config, set-home, set-work, set-format, print-home, print-work
   Onboarding     init (PIN onboarding), refresh (sync settings / renew cert)
-  Remote admin   list, add, update, pin, delete  (need remote-server + client cert in ~/.aifabrix)
+  Remote admin   list, add, update, pin, delete, platform-install, platform-update, platform-install-cli  (need remote-server + client cert in ~/.aifabrix)
   Sync / stop    down  (Mutagen; optional --apps for containers)
 
 Use: aifabrix dev <command> --help
@@ -85,10 +90,31 @@ when their config already has remote-server + developer-id.
 
 /** Appended to `dev delete --help`. */
 const DEV_DELETE_HELP_AFTER = `
-Example:
+Examples:
   $ aifabrix dev delete 02
+  $ aifabrix dev delete 02 -y
+  $ aifabrix dev delete 02 --db-only
+
+Default removes the developer from the host (OS user, containers) and server database. Use --db-only for database-only removal.
 `;
 
+/** Shared host-ops flags for platform commands and dev add provision. */
+function addHostOpsSharedOptions(cmd) {
+  return cmd
+    .option('--check', 'Preflight only (no changes)')
+    .option('-y, --yes', 'Non-interactive (skip prompts)')
+    .option('--wait', 'Poll until job completes', true)
+    .option('--no-wait', 'Return after job is queued')
+    .option('--json', 'JSON output (includes job result when --wait)')
+    .option('--include <ids>', 'Comma-separated developer ids (batch)')
+    .option('--exclude <ids>', 'Comma-separated developer ids to skip')
+    .option('--builder-version <ver>', 'Builder CLI / platform bundle version')
+    .option('--admin-email <email>', 'Platform admin email (install / provision)')
+    .option('--admin-password <password>', 'Platform admin password (never logged)')
+    .option('--platform <mode>', 'Platform mode (e.g. single-traefik)')
+    .option('--installation <profile>', 'Installation profile (e.g. dev)');
+}
+
 /** Appended to `dev down --help`. */
 const DEV_DOWN_HELP_AFTER = `
 Examples:
@@ -276,6 +302,15 @@ function setupDevListAddCommands(dev) {
     .requiredOption('--name <name>', 'Display name')
     .requiredOption('--email <email>', 'Email address')
     .option('--groups <items>', 'Comma-separated roles: admin, secret-manager, secret-reader, developer, docker', 'developer')
+    .option('--no-provision', 'Create user in database only (skip host provision job)')
+    .option('--builder-version <ver>', 'Builder CLI version for provision job')
+    .option('--admin-email <email>', 'Platform admin email for provision job')
+    .option('--admin-password <password>', 'Platform admin password for provision job')
+    .option('--platform <mode>', 'Platform mode for provision job')
+    .option('--installation <profile>', 'Installation profile for provision job')
+    .option('--skip-cert', 'Skip certificate step in provision job')
+    .option('--skip-platform', 'Skip platform install in provision job')
+    .option('--skip-cli', 'Skip Builder CLI install in provision job')
     .addHelpText('after', DEV_ADD_HELP_AFTER)
     .action(async(options) => {
       try {
@@ -287,6 +322,27 @@ function setupDevListAddCommands(dev) {
     });
 }
 
+/**
+ * Register dev down command.
+ * @param {Command} dev - dev subcommand group
+ */
+function setupDevDownCommand(dev) {
+  dev
+    .command('down')
+    .description('Stop Mutagen sync; --apps also stops app containers')
+    .addHelpText('after', DEV_DOWN_HELP_AFTER)
+    .option('--apps', 'Also stop running app containers for this developer')
+    .action(async(options) => {
+      try {
+        const { handleDevDown } = require('../commands/dev-down');
+        await handleDevDown(options);
+      } catch (error) {
+        handleCommandError(error, 'dev down');
+        process.exit(1);
+      }
+    });
+}
+
 /**
  * Register dev update/pin/delete commands (remote only).
  * @param {Command} dev - dev subcommand group
@@ -325,31 +381,68 @@ function setupDevUpdatePinDeleteCommands(dev) {
 
   dev
     .command('delete <developerId>')
-    .description('Remove developer from server (admin)')
+    .description('Remove developer from host and server (admin)')
+    .option('--db-only', 'Remove from server database only (legacy behaviour)')
+    .option('-y, --yes', 'Skip confirmation prompt')
     .addHelpText('after', DEV_DELETE_HELP_AFTER)
-    .action(async(developerId) => {
+    .action(async(developerId, options) => {
       try {
-        await handleDevDelete(developerId);
+        await handleDevDelete(developerId, options);
       } catch (error) {
         handleCommandError(error, 'dev delete');
         process.exit(1);
       }
     });
 
-  dev
-    .command('down')
-    .description('Stop Mutagen sync; --apps also stops app containers')
-    .addHelpText('after', DEV_DOWN_HELP_AFTER)
-    .option('--apps', 'Also stop running app containers for this developer')
-    .action(async(options) => {
+  setupDevDownCommand(dev);
+}
+
+/**
+ * Register platform lifecycle commands (host-ops).
+ * @param {Command} dev - dev subcommand group
+ */
+function setupDevPlatformCommands(dev) {
+  addHostOpsSharedOptions(
+    dev
+      .command('platform-install-cli [developerId]')
+      .description('Install or upgrade Builder CLI on dev host(s) (admin)')
+  )
+    .option('--force', 'Reinstall even when CLI is present')
+    .action(async(developerId, options) => {
       try {
-        const { handleDevDown } = require('../commands/dev-down');
-        await handleDevDown(options);
+        await handlePlatformInstallCli(developerId, options);
       } catch (error) {
-        handleCommandError(error, 'dev down');
+        handleCommandError(error, 'dev platform-install-cli');
         process.exit(1);
       }
     });
+
+  addHostOpsSharedOptions(
+    dev
+      .command('platform-update [developerId]')
+      .description('Refresh dev platform images (admin)')
+  ).action(async(developerId, options) => {
+    try {
+      await handlePlatformUpdate(developerId, options);
+    } catch (error) {
+      handleCommandError(error, 'dev platform-update');
+      process.exit(1);
+    }
+  });
+
+  addHostOpsSharedOptions(
+    dev
+      .command('platform-install <developerId>')
+      .description('Install dev platform for one developer (admin)')
+      .option('--force', 'Remove existing platform then reinstall')
+  ).action(async(developerId, options) => {
+    try {
+      await handlePlatformInstall(developerId, options);
+    } catch (error) {
+      handleCommandError(error, 'dev platform-install');
+      process.exit(1);
+    }
+  });
 }
 
 /**
@@ -359,6 +452,7 @@ function setupDevUpdatePinDeleteCommands(dev) {
 function setupDevUserCommands(dev) {
   setupDevListAddCommands(dev);
   setupDevUpdatePinDeleteCommands(dev);
+  setupDevPlatformCommands(dev);
 }
 
 /**

package/lib/commands/dev-cli-handlers.js

@@ -16,6 +16,7 @@ const {
   validateDevGroups,
   augmentDevUserGroupsServerError
 } = require('../utils/dev-user-groups');
+const { handleProvisionDevUser, handleRemoveDevUser } = require('./dev-host-ops');
 
 const REMOTE_NOT_CONFIGURED_MSG = 'Remote server is not configured. Set remote-server and run "aifabrix dev init" first.';
 
@@ -26,6 +27,19 @@ const CERT_WIDTH = 10;
 const UNTIL_WIDTH = 22; // 2026-03-20T17:31:14
 const TABLE_SEPARATOR_LENGTH = 130;
 
+/**
+ * Normalize numeric developer id for comparison (e.g. 3 → 03).
+ * @param {string} id - Developer ID
+ * @returns {string}
+ */
+function normalizeDeveloperIdForCompare(id) {
+  const trimmed = String(id ?? '').trim();
+  if (!/^\d+$/.test(trimmed)) {
+    return trimmed;
+  }
+  return String(parseInt(trimmed, 10)).padStart(2, '0');
+}
+
 /**
  * Format certificate validity end for display (e.g. 2026-03-20T17:31:14.000Z -> 2026-03-20T17:31:14).
  * @param {string} iso - ISO 8601 date string
@@ -91,6 +105,10 @@ async function handleDevAdd(options) {
       groups
     }, auth.serverCaPem || undefined);
     logger.log(formatSuccessLine(`Developer ${user.id} created. Use "aifabrix dev pin ${user.id}" to create a PIN for onboarding.`));
+    const noProvision = options.noProvision || options['no-provision'];
+    if (!noProvision) {
+      await handleProvisionDevUser(user.id, options);
+    }
   } catch (err) {
     augmentDevUserGroupsServerError(err, groups);
     throw err;
@@ -222,18 +240,61 @@ async function handleDevPin(developerId, options = {}) {
   });
 }
 
+/**
+ * @param {string} question
+ * @returns {Promise<boolean>}
+ */
+async function promptYesNo(question) {
+  if (!process.stdin.isTTY) {
+    return false;
+  }
+  const readline = require('readline');
+  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()));
+    });
+  });
+}
+
 /**
  * Handle dev delete – remove developer (remote only).
+ * Default: full host removal via host-ops. Use --db-only for API-only delete.
  * @param {string} developerId - Developer ID
+ * @param {Object} [options] - Commander options
  * @returns {Promise<void>}
  */
-async function handleDevDelete(developerId) {
+async function handleDevDelete(developerId, options = {}) {
   const auth = await getRemoteDevAuth();
   if (!auth) throw new Error(REMOTE_NOT_CONFIGURED_MSG);
   const id = developerId;
   if (!id) throw new Error('Developer ID is required (positional argument or --developer-id).');
-  await devApi.deleteUser(auth.serverUrl, auth.clientCertPem, id, auth.serverCaPem || undefined);
-  logger.log(formatSuccessLine(`Developer ${id} removed.`));
+  const actorId = await config.getDeveloperId();
+  if (
+    actorId &&
+    normalizeDeveloperIdForCompare(actorId) === normalizeDeveloperIdForCompare(id)
+  ) {
+    throw new Error('You cannot delete your own developer account.');
+  }
+  const dbOnly = options.dbOnly || options['db-only'];
+  if (dbOnly) {
+    await devApi.deleteUser(auth.serverUrl, auth.clientCertPem, id, auth.serverCaPem || undefined);
+    logger.log(formatSuccessLine(`Developer ${id} removed from server database.`));
+    return;
+  }
+  const assumeYes = options.yes || options.y;
+  if (!assumeYes) {
+    const ok = await promptYesNo(
+      `Remove developer ${id} from host and server (containers, OS user, database)?`
+    );
+    if (!ok) {
+      logger.log(chalk.gray('Cancelled.'));
+      return;
+    }
+  }
+  await handleRemoveDevUser(id, { ...options, developerId: id });
+  logger.log(formatSuccessLine(`Developer ${id} removal queued and completed.`));
 }
 
 module.exports = {