@aifabrix/builder 2.55.0 → 2.56.0

package/lib/utils/error-formatters/error-parser.js

@@ -177,6 +177,21 @@ function handleGenericError(errorData, statusCode) {
   return createErrorResult('generic', errorData.message || errorData.error || 'Unknown error', formatGenericError(errorData, statusCode), errorData);
 }
 
+function unwrapNestedErrorData(errorData) {
+  if (!errorData || !errorData.data || typeof errorData.data !== 'object') {
+    return errorData;
+  }
+  const nested = errorData.data;
+  return {
+    ...nested,
+    cliPermissionService: errorData.cliPermissionService || nested.cliPermissionService,
+    requiredPermissions: errorData.requiredPermissions || nested.requiredPermissions,
+    method: errorData.method || nested.method,
+    url: nested.instance || nested.url || errorData.url,
+    instance: nested.instance || errorData.instance
+  };
+}
+
 /**
  * Parses error response and determines error type
  * @param {string|Object} errorResponse - Error response (string or parsed JSON)
@@ -200,7 +215,7 @@ function parseErrorResponse(errorResponse, statusCode, isNetworkError) {
 
   // Handle nested response structure (some APIs wrap errors in data field)
   if (errorData.data && typeof errorData.data === 'object') {
-    errorData = errorData.data;
+    errorData = unwrapNestedErrorData(errorData);
   }
 
   // Handle network errors

package/lib/utils/error-formatters/permission-errors.js

@@ -42,6 +42,9 @@ function extractRequiredPermissions(errorData) {
   if (errorData.requiredPermissions && Array.isArray(errorData.requiredPermissions)) {
     return errorData.requiredPermissions;
   }
+  if (typeof errorData.requiredPermission === 'string' && errorData.requiredPermission.trim()) {
+    return [errorData.requiredPermission.trim()];
+  }
   if (errorData.required && errorData.required.permissions && Array.isArray(errorData.required.permissions)) {
     return errorData.required.permissions;
   }
@@ -97,6 +100,19 @@ function getPermissionDetailLines(errorData) {
   return lines;
 }
 
+function appendPermissionAssignHint(lines, errorData) {
+  const service = errorData.cliPermissionService;
+  if (service) {
+    lines.push(chalk.gray(`Required on: ${service}`));
+  }
+  lines.push(chalk.gray(
+    service
+      ? `Assign this permission on the ${service} for this environment (roles and groups).`
+      : 'Assign the required permission on the Controller or Dataplane for this environment (roles and groups).'
+  ));
+  lines.push('');
+}
+
 /**
  * Formats permission error with missing and required permissions
  * @param {Object} errorData - Error response data
@@ -111,11 +127,9 @@ function formatPermissionError(errorData) {
     lines.push('');
   }
 
-  const missingPerms = extractMissingPermissions(errorData);
-  addPermissionList(lines, missingPerms, 'Missing permissions');
-
-  const requiredPerms = extractRequiredPermissions(errorData);
-  addPermissionList(lines, requiredPerms, 'Required permissions');
+  addPermissionList(lines, extractMissingPermissions(errorData), 'Missing permissions');
+  addPermissionList(lines, extractRequiredPermissions(errorData), 'Required permissions');
+  appendPermissionAssignHint(lines, errorData);
 
   const requestUrl = errorData.instance || errorData.url;
   const method = errorData.method || 'POST';

package/lib/utils/keycloak-realm-ready.js

@@ -82,15 +82,18 @@ async function waitForKeycloakRealmReady(opts = {}) {
   const directUrl = directBase ? buildRealmWellKnownUrl(directBase) : null;
   const deadline = Date.now() + timeoutSeconds * 1000;
 
-  while (Date.now() < deadline) {
+  do {
     if (await probeRealmWellKnown(url)) {
       return;
     }
     if (directUrl && (await probeRealmWellKnown(directUrl))) {
       return;
     }
+    if (Date.now() >= deadline) {
+      break;
+    }
     await new Promise((resolve) => setTimeout(resolve, intervalMs));
-  }
+  } while (Date.now() < deadline);
 
   throw new Error(
     `Keycloak realm "aifabrix" was not ready within ${timeoutSeconds}s (checked ${url}${directUrl ? ` and ${directUrl}` : ''}). ` +

package/lib/utils/logger.js

@@ -83,4 +83,5 @@ const logger = {
 };
 
 module.exports = logger;
+module.exports.sanitizeValue = sanitizeValue;
 

package/lib/utils/paths.js

@@ -957,6 +957,24 @@ async function ensureShippedBuilderAppTemplate(appName) {
   return true;
 }
 
+/**
+ * Finds an existing local app workspace without copying shipped templates.
+ *
+ * @param {string} appName - Application name
+ * @param {Object} [options] - Detection options (reserved; options.type is ignored)
+ * @returns {{isExternal: boolean, appPath: string, appType: string, baseDir?: string}|null}
+ */
+function findExistingAppType(appName, options = {}) {
+  if (!appName || typeof appName !== 'string') {
+    return null;
+  }
+  const externalResult = checkExternalWorkspaceFolder(appName, options);
+  if (externalResult) {
+    return externalResult;
+  }
+  return checkBuilderFolder(appName);
+}
+
 /**
  * Detects if an app is external type by checking application config.
  * Resolution order: integration/ first, then builder/; if neither exists, throws.
@@ -971,13 +989,15 @@ async function detectAppType(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
-  const externalResult = checkExternalWorkspaceFolder(appName, options);
-  if (externalResult) return externalResult;
-  const builderResult = checkBuilderFolder(appName);
-  if (builderResult) return builderResult;
+  const existing = findExistingAppType(appName, options);
+  if (existing) {
+    return existing;
+  }
   await ensureShippedBuilderAppTemplate(appName);
   const builderAfterTemplate = checkBuilderFolder(appName);
-  if (builderAfterTemplate) return builderAfterTemplate;
+  if (builderAfterTemplate) {
+    return builderAfterTemplate;
+  }
   throw new Error(
     `App '${appName}' not found in integration/${appName}, enterprise-knowledge/${appName}, role-assistant/${appName}, or builder/${appName}`
   );
@@ -1121,6 +1141,7 @@ module.exports = {
   resolveApplicationConfigPath,
   resolveRbacPath,
   ensureShippedBuilderAppTemplate,
+  findExistingAppType,
   detectAppType,
   getResolveAppPath,
   resolveIntegrationAppKeyFromCwd,

package/lib/utils/qualification-poll-ui.js

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview TTY ora spinner + throttled non-TTY lines for qualification job polling.
+ * Mirrors host-ops-poll-ui.js's presentation pattern (plan 191.0 task 1).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+
+const SILENT_POLL_HANDLERS = {
+  onPollProgress: () => {},
+  onTransientError: () => {},
+  finish: () => {}
+};
+
+const NON_TTY_THROTTLE_MS = 5000;
+
+const HUMAN_STEP_LABELS = Object.freeze({
+  stageCandidate: 'Uploading configuration',
+  gateOperations: 'Checking operations',
+  gateTrust: 'Checking trust',
+  gateGovernance: 'Checking governance',
+  sealCertificate: 'Finalizing upload'
+});
+
+function shouldUseQualificationPollSpinner() {
+  return Boolean(process && process.stdout && process.stdout.isTTY);
+}
+
+/**
+ * @param {Object} job - PublishJobStatusResponse-shaped data ({ state, steps })
+ * @returns {string}
+ */
+function currentQualificationStepLabel(job, options = {}) {
+  if (!job || !Array.isArray(job.steps) || job.steps.length === 0) {
+    return 'Preparing upload';
+  }
+  const running = job.steps.find((step) => step.status === 'running');
+  if (running) return qualificationStepLabel(running, 'running', options);
+  const failed = job.steps.find((step) => step.status === 'failed');
+  if (failed) return qualificationStepLabel(failed, 'failed', options);
+  const pending = job.steps.find((step) => step.status === 'pending');
+  if (pending) return qualificationStepLabel(pending, 'pending', options);
+  return 'Upload complete';
+}
+
+function qualificationStepLabel(step, _status, _options) {
+  return HUMAN_STEP_LABELS[step.key] || 'Processing upload';
+}
+
+/**
+ * @param {string} jobId
+ * @param {Object|null} job
+ * @param {number} elapsedMs
+ * @param {string} [transientNote]
+ * @returns {string}
+ */
+function buildQualificationPollLine(jobId, job, elapsedMs, transientNote, options = {}) {
+  const seconds = Math.max(0, Math.round(elapsedMs / 1000));
+  const note = transientNote ? ` — ${transientNote}` : '';
+  if (options.verbose === true) {
+    return `Upload (job ${jobId}): ${currentQualificationStepLabel(job, options)} — ${seconds}s elapsed${note}`;
+  }
+  return `${currentQualificationStepLabel(job, options)} — ${seconds}s elapsed${note}`;
+}
+
+function createSpinnerQualificationPollHandlers(jobId, startedAt, options) {
+  const ora = require('ora');
+  const spinner = ora({
+    text: buildQualificationPollLine(jobId, null, 0, undefined, options),
+    spinner: 'dots'
+  }).start();
+  return {
+    onPollProgress: (job) => {
+      spinner.text = buildQualificationPollLine(jobId, job, Date.now() - startedAt, undefined, options);
+    },
+    onTransientError: (status, elapsedMs) => {
+      spinner.text = buildQualificationPollLine(
+        jobId,
+        null,
+        elapsedMs,
+        'service temporarily unavailable, retrying',
+        options
+      );
+    },
+    finish: () => spinner.stop()
+  };
+}
+
+function createNonTtyQualificationPollHandlers(jobId, startedAt, options) {
+  let lastLogAt = 0;
+  return {
+    onPollProgress: (job) => {
+      const now = Date.now();
+      if (now - lastLogAt < NON_TTY_THROTTLE_MS) {
+        return;
+      }
+      lastLogAt = now;
+      logger.log(chalk.gray(`  ${buildQualificationPollLine(jobId, job, now - startedAt, undefined, options)}`));
+    },
+    onTransientError: (status, elapsedMs) => {
+      logger.log(
+        chalk.gray(
+          `  ${buildQualificationPollLine(jobId, null, elapsedMs, 'service temporarily unavailable, retrying', options)}`
+        )
+      );
+    },
+    finish: () => {}
+  };
+}
+
+/**
+ * @param {string} jobId
+ * @param {{ startedAt?: number, silent?: boolean, verbose?: boolean }} [options]
+ * @returns {{ onPollProgress: Function, onTransientError: Function, finish: () => void }}
+ */
+function createQualificationPollHandlers(jobId, options = {}) {
+  if (options.silent === true) {
+    return SILENT_POLL_HANDLERS;
+  }
+  const startedAt = options.startedAt || Date.now();
+  if (shouldUseQualificationPollSpinner()) {
+    return createSpinnerQualificationPollHandlers(jobId, startedAt, options);
+  }
+  return createNonTtyQualificationPollHandlers(jobId, startedAt, options);
+}
+
+module.exports = {
+  currentQualificationStepLabel,
+  buildQualificationPollLine,
+  createQualificationPollHandlers,
+  shouldUseQualificationPollSpinner
+};

package/lib/utils/secrets-helpers.js

@@ -47,7 +47,8 @@ const { resolveBashKvFromProcessEnv } = require('./secrets-bash-kv');
 const EMPTY_ALLOWED_KV_FALLBACK = new Set([
   'redis-passwordKeyVault',
   'azure-openaiapi-urlKeyVault',
-  'secrets-azureOpenaiApiKeyVault'
+  'secrets-azureOpenaiApiKeyVault',
+  'miso-controller-secrets-apiKeyVault'
 ]);
 
 /**
@@ -486,4 +487,3 @@ module.exports = {
   rewriteInfraEndpoints,
   getEnvHosts
 };
-

package/lib/utils/write-stream-and-wait.js

@@ -0,0 +1,63 @@
+/**
+ * Flush a writable stream chunk without hanging on Jest write mocks.
+ *
+ * @fileoverview Shared stdout/stderr write + wait for CLI exits.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {unknown} writeFn - Stream write implementation
+ * @returns {boolean}
+ */
+function isJestMockWrite(writeFn) {
+  return typeof jest !== 'undefined'
+    && typeof jest.isMockFunction === 'function'
+    && jest.isMockFunction(writeFn);
+}
+
+/**
+ * Write `chunk` and resolve after the stream flushes.
+ *
+ * Piped stdout/stderr on Linux is asynchronous; exiting before the write
+ * callback can truncate output. Jest spies that ignore the callback, and
+ * native writes inside a Jest worker, must not hang the test.
+ *
+ * @param {NodeJS.WritableStream} stream - stdout or stderr
+ * @param {string} chunk - Bytes to write
+ * @returns {Promise<void>}
+ */
+function writeStreamAndWait(stream, chunk) {
+  return new Promise(resolve => {
+    let settled = false;
+    const finish = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve();
+    };
+    if (!stream || typeof stream.write !== 'function') {
+      finish();
+      return;
+    }
+    const writeFn = stream.write;
+    try {
+      writeFn.call(stream, chunk, finish);
+    } catch {
+      finish();
+      return;
+    }
+    if (isJestMockWrite(writeFn) && writeFn.length < 2) {
+      finish();
+      return;
+    }
+    if (!isJestMockWrite(writeFn) && process.env.JEST_WORKER_ID) {
+      setImmediate(finish);
+    }
+  });
+}
+
+module.exports = { writeStreamAndWait };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.55.0",
+  "version": "2.56.0",
   "description": "AI Fabrix Builder — CLI and developer scripts (pnpm + af)",
   "main": "lib/index.js",
   "bin": {
@@ -21,6 +21,7 @@
     "dev-reload": "node scripts/pnpm/dev-reload.mjs",
     "dev-build": "node scripts/pnpm/af.mjs dev-build",
     "dev-promote": "node scripts/pnpm/af.mjs dev-promote",
+    "dev-deploy": "node scripts/pnpm/dev-deploy.mjs",
     "af": "node scripts/pnpm/af.mjs",
     "check-quiet": "node scripts/pnpm/check-quiet.mjs",
     "check": "npm run lint && npm run test",
@@ -86,32 +87,46 @@
   "overrides": {
     "@babel/core": "^7.29.7",
     "@babel/plugin-transform-modules-systemjs": "^7.29.7",
-    "fast-uri": "^4.1.0",
+    "baseline-browser-mapping": "^2.11.21",
+    "brace-expansion@5": "5.0.9",
+    "browserslist": "^4.28.9",
+    "fast-uri": "^4.1.4",
     "flatted": "^3.4.2",
     "follow-redirects": "^1.16.0",
     "form-data": "^4.0.6",
+    "js-yaml@3": "3.15.2",
+    "js-yaml@5": "5.4.1",
     "lodash": "^4.18.1",
     "minimatch": "^10.2.5",
+    "multer": "^2.3.0",
     "picomatch": "^4.0.5",
-    "qs": "^6.15.3"
+    "qs": "^6.16.0",
+    "smol-toml": "^1.8.0"
   },
   "pnpm": {
     "overrides": {
       "@bcoe/v8-coverage": "^1.0.2",
       "@babel/core": "^7.29.7",
       "@babel/plugin-transform-modules-systemjs": "^7.29.7",
-      "fast-uri": "^4.1.0",
+      "baseline-browser-mapping": "^2.11.21",
+      "brace-expansion@5": "5.0.9",
+      "browserslist": "^4.28.9",
+      "fast-uri": "^4.1.4",
       "flatted": "^3.4.2",
       "follow-redirects": "^1.16.0",
       "form-data": "^4.0.6",
+      "js-yaml@3": "3.15.2",
+      "js-yaml@5": "5.4.1",
       "lodash": "^4.18.1",
       "minimatch": "^10.2.5",
+      "multer": "^2.3.0",
       "picomatch": "^4.0.5",
-      "qs": "^6.15.3"
+      "qs": "^6.16.0",
+      "smol-toml": "^1.8.0"
     }
   },
   "dependencies": {
-    "@aifabrix/miso-client": "^4.19.0",
+    "@aifabrix/miso-client": "4.22.4",
     "adm-zip": "^0.6.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
@@ -121,7 +136,7 @@
     "handlebars": "^4.7.9",
     "inquirer": "^8.2.5",
     "inquirer-autocomplete-prompt": "^2.0.0",
-    "js-yaml": "^4.3.0",
+    "js-yaml": "^4.3.2",
     "ora": "^5.4.1",
     "yaml": "^2.9.0"
   },

package/templates/agent-kit/agent-kit.yaml

@@ -1,5 +1,5 @@
 schemaVersion: "1"
-kitVersion: "1.1.1"
+kitVersion: "1.1.2"
 minimumBuilderVersion: "2.54.2"
 skills:
   - aifabrix-plan

package/templates/agent-kit/instructions/AGENTKIT.md

@@ -34,7 +34,7 @@ New workspace instead of an existing repo: `aifabrix agent-kit init <workspaceNa
 Install the coding app, then sign in. How to **run** it locally or over SSH is in `.agents/skills/shared/hosts.md` (linked from every Agent Kit skill).
 {{#if autoApprove}}
 
-On TTY, install **asks** to auto-approve tool permissions **in this workspace**. Claude Code also allows `Bash(aifabrix *)` (delivery CLI) and `Read(~/**)` (home Read). Silent (`--yes` / non-TTY) writes them; `--skip-approve-all` skips.
+On TTY, install **asks** which hosts to support (omit `--host`) and which tools to auto-approve. `--approve-all claude` or `--approve-all codex` writes only that host's config. Claude Code also allows `Bash(aifabrix *)` (delivery CLI) and `Read(~/**)` (home Read). Silent (`--yes` / non-TTY) writes them; `--skip-approve-all` skips.
 {{#if claude}}
 - Claude Code writes `.claude/settings.local.json` (gitignored).
 {{/if}}
@@ -57,22 +57,43 @@ curl -fsSL https://claude.ai/install.sh | bash
 claude auth login
 ```
 
-Skills: same `/aifabrix-*` names. First `claude` must run inside this workspace, not your home directory.
+**Run in tmux** from this workspace so closing the terminal does not kill Claude. `--remote-control` is the **same** session on this PC, [claude.ai/code](https://claude.ai/code), and the Claude mobile app (Code). That is not `claude --cloud` (a separate cloud VM). Claude `--tmux` is for worktrees only.
+
+```bash
+aifabrix agent-kit start claude --remote-control --approve-all --yes
+```
+
+tmux session name defaults to this folder. Remote Control name is `hostname-user-folder` (for example `builder01-dev03-aifabrix-docs`). Override the folder with `--name`. Detach: `Ctrl-b` then `d`. Reattach: `tmux attach -t <folder>`. Several workspaces can run at once. Same account on phone and PC (`claude auth login`, Pro/Max/Team — not an API key). On the phone: Claude app → **Code**. Skills: `/aifabrix-plan` (and the other `/aifabrix-*` names). First `claude` must run inside this workspace, not your home directory. Full notes: `.agents/skills/shared/hosts.md`.
 {{/if}}
 {{#if codex}}
 
 ### Codex
 
-Install the Codex CLI, then sign in with your Codex account. Skills: `$aifabrix-plan` (and the other `$aifabrix-*` names). Codex reads `AGENTS.md`.
+Install the Codex CLI (`@openai/codex`, not the unrelated `codex` package), then sign in with ChatGPT (Plus, Pro, Business, Edu, or Enterprise):
+
+```bash
+npm install -g @openai/codex
+codex login
+```
+
+**Run in tmux** from this workspace so the session stays if you close the terminal:
+
+```bash
+aifabrix agent-kit start codex --approve-all --yes
+```
+
+Detach: `Ctrl-b` then `d`. Reattach: `tmux attach -t <folder>`, or `aifabrix agent-kit start codex` from this workspace. Default session name is this folder. Skills: `$aifabrix-plan` (and the other `$aifabrix-*` names). Codex reads `AGENTS.md`. Full notes: `.agents/skills/shared/hosts.md`.
 {{/if}}
 
 ## Auth for delivery CLI
 
+Do not tell the user to open a terminal for Builder login. Follow `.agents/skills/shared/login.md`.
+
 ```bash
 aifabrix auth status
 ```
 
-If still unauthenticated, run `aifabrix login` (the agent cannot log in for you).
+If that is not authenticated, ask for the Miso Controller URL, run device login, and paste the printed authenticate URL into chat.
 
 ## How to start
 

package/templates/agent-kit/instructions/root.AGENTS.md

@@ -28,7 +28,7 @@ Do not collapse these into a generic success boolean. Do not start the next life
 ## Coding hosts
 
 Cursor, Claude Code, and Codex — local machine or SSH (tmux, Claude Remote Control): `.agents/skills/shared/hosts.md`.
-Install and sign-in: `AGENTKIT.md`.
+Install and sign-in: `AGENTKIT.md`. Builder CLI login from chat: `.agents/skills/shared/login.md`.
 
 ## Docs
 

package/templates/agent-kit/skills/aifabrix-connected-system/SKILL.md

@@ -24,6 +24,7 @@ Stop at the phase gate. Do not run the next phase without `next-yes`
 
 Read current CLI help before composing commands. You own orchestration, not CLI implementation.
 Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
+CLI login from chat: [login.md](../shared/login.md).
 
 ## Always
 
@@ -31,7 +32,7 @@ Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
 aifabrix auth status
 ```
 
-Refresh first. User runs `aifabrix login` only if still unauthenticated. Re-run on 401, then retry once.
+Refresh first. If still unauthenticated, follow [login.md](../shared/login.md). Re-run on 401, then retry once.
 
 System key: argument → active plan → sole `integration/` folder → ask once. Never invent. Reject `ra-` / `ek-` ([scripts/reserved-system-key.js](scripts/reserved-system-key.js)).
 

package/templates/agent-kit/skills/aifabrix-connected-system/references/delivery-gates.md

@@ -41,7 +41,7 @@ Never mark live E2E pass when it did not run.
 
 ## Identity and protection order
 
-1. `aifabrix auth status`
+1. `aifabrix auth status` — if unauthenticated, [login.md](../../shared/login.md)
 2. Catalog roles + fixtures + `identity apply` / `identity sync` / `role set-groups`
 3. Load partitioned fixtures
 4. `aifabrix protection upload <sourceStorageDs> --sync` (storage DS, not the view)

package/templates/agent-kit/skills/aifabrix-plan/SKILL.md

@@ -15,6 +15,7 @@ Output: one delivery plan from [plan-template.md](references/plan-template.md).
 Score completeness with [challenge-checklist.md](references/challenge-checklist.md).
 Next-step interaction: [interaction.md](references/interaction.md).
 Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
+CLI login from chat: [login.md](../shared/login.md).
 
 ## Sequence
 
@@ -44,7 +45,7 @@ aifabrix auth status
 aifabrix role list --page-size 1000
 ```
 
-If still unauthenticated after refresh, draft the plan; catalog-role rows stay MISSING until the user runs `aifabrix login`.
+If unauthenticated after refresh, follow [login.md](../shared/login.md) before listing catalog roles.
 
 ## Trigger examples
 

package/templates/agent-kit/skills/aifabrix-prove/SKILL.md

@@ -19,6 +19,7 @@ Evidence rules: [evidence-lifecycle.md](references/evidence-lifecycle.md).
 Demo shape: [demo-template.md](references/demo-template.md).
 Next-step: [interaction.md](../aifabrix-plan/references/interaction.md).
 Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
+CLI login from chat: [login.md](../shared/login.md).
 
 ## Keys
 

package/templates/agent-kit/skills/aifabrix-role-assistant/SKILL.md

@@ -10,6 +10,7 @@ description: >
 
 See [package-boundary.md](references/package-boundary.md) and nested `role-assistant/AGENTS.md`.
 Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
+CLI login from chat: [login.md](../shared/login.md).
 
 ## Preconditions