@aifabrix/builder 2.55.0 → 2.56.0

package/lib/agent-kit/host-approve.js

@@ -10,9 +10,50 @@ const fs = require('../internal/fs-real-sync');
 
 const CLAUDE_REL = '.claude/settings.local.json';
 const CODEX_REL = '.codex/config.toml';
+const APPROVE_HOSTS = ['claude', 'codex'];
 const IGNORE_COMMENT = '# Host auto-approve (machine-local; aifabrix agent-kit)';
 const IGNORE_LINES = [CLAUDE_REL, CODEX_REL];
 
+/**
+ * --approve-all [host]: true/'all' = every selected host; claude|codex = one tool.
+ * @param {unknown} value
+ * @returns {{ requested: boolean, target: string|null }}
+ */
+function parseApproveAll(value) {
+  if (value === undefined || value === false || value === '') {
+    return { requested: false, target: null };
+  }
+  if (value === true || value === 'all') {
+    return { requested: true, target: 'all' };
+  }
+  const target = String(value);
+  if (APPROVE_HOSTS.includes(target)) {
+    return { requested: true, target };
+  }
+  throw new Error('Invalid --approve-all. Use all, claude, or codex.');
+}
+
+/**
+ * Subset of managed hosts that receive auto-approve files.
+ * @param {string[]} [managedHosts]
+ * @param {unknown} approveAll
+ * @returns {string[]}
+ */
+function resolveApproveHosts(managedHosts, approveAll) {
+  const parsed = parseApproveAll(approveAll);
+  if (!parsed.requested) {
+    return [];
+  }
+  const eligible = (managedHosts || []).filter((h) => APPROVE_HOSTS.includes(h));
+  if (parsed.target === 'all') {
+    return eligible;
+  }
+  if (!eligible.includes(parsed.target)) {
+    throw new Error(`--approve-all ${parsed.target} requires --host ${parsed.target} or --host all.`);
+  }
+  return [parsed.target];
+}
+
 /**
  * This workspace for writes. Read(~/**) is home-anchored. Bash(aifabrix *)
  * allows the delivery CLI without granting every shell command.
@@ -101,15 +142,13 @@ function listApproveWrites(options) {
  * @returns {{ requested: boolean, files: { path: string, action: string }[] }}
  */
 function writeApproveAllFiles(options) {
-  if (!options.approveAll) {
+  const parsed = parseApproveAll(options.approveAll);
+  if (!parsed.requested) {
     return { requested: false, files: [] };
   }
+  const hosts = resolveApproveHosts(options.hosts, options.approveAll);
   const fsApi = options.fs || fs;
-  const ctx = {
-    repoRoot: options.repoRoot,
-    hosts: options.hosts || [],
-    fsApi
-  };
+  const ctx = { repoRoot: options.repoRoot, hosts, fsApi };
   const dryRun = Boolean(options.dryRun);
   const force = Boolean(options.force);
   const files = listApproveWrites(ctx).map((row) =>
@@ -124,6 +163,9 @@ function writeApproveAllFiles(options) {
 module.exports = {
   CLAUDE_REL,
   CODEX_REL,
+  APPROVE_HOSTS,
+  parseApproveAll,
+  resolveApproveHosts,
   buildClaudeSettings,
   buildCodexConfig,
   writeApproveAllFiles

package/lib/agent-kit/init.js

@@ -152,7 +152,7 @@ function runInit(options) {
     dryRun,
     targetAbs,
     host: options.host || 'all',
-    approveAll: Boolean(options.approveAll),
+    approveAll: options.approveAll,
     force: Boolean(options.force),
     gitResult,
     phases
@@ -195,7 +195,7 @@ function installKitPhase(p) {
   const kit = runInstall({
     cwd: p.targetAbs,
     host: p.host,
-    approveAll: Boolean(p.approveAll),
+    approveAll: p.approveAll,
     force: Boolean(p.force)
   });
   p.phases.push({ phase: 'agent-kit', state: kit.state });

package/lib/agent-kit/remote-prompts.js

@@ -7,6 +7,7 @@
 
 const { execFileSync } = require('child_process');
 const { ALL_HOSTS, HOST_LABELS, normalizeHosts } = require('./hosts');
+const { APPROVE_HOSTS, parseApproveAll } = require('./host-approve');
 
 /**
  * @param {{ execFileSync?: Function }} [options]
@@ -198,18 +199,57 @@ async function enrichInitRemoteOptions(options, deps = {}) {
 }
 
 /**
- * TTY asks; --approve-all / --yes / non-TTY auto-approve; --skip-approve-all skips.
+ * @param {object} inquirer
+ * @param {string[]} eligible
+ * @returns {Promise<true|false|string>}
+ */
+async function askApproveAllChoice(inquirer, eligible) {
+  if (eligible.length === 1) {
+    const host = eligible[0];
+    const { approveAll } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'approveAll',
+        message: `Auto-approve ${HOST_LABELS[host] || host} tool permissions in this workspace?`,
+        default: true
+      }
+    ]);
+    return Boolean(approveAll);
+  }
+  const { approveAll } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'approveAll',
+      message: 'Which coding host should auto-approve tools in this workspace?',
+      default: 'all',
+      choices: [
+        { name: 'Both Claude Code and Codex', value: 'all' },
+        { name: 'Claude Code only', value: 'claude' },
+        { name: 'Codex only', value: 'codex' },
+        { name: 'Skip (the coding app will ask each time)', value: 'skip' }
+      ]
+    }
+  ]);
+  return approveAll === 'skip' ? false : approveAll;
+}
+
+/**
+ * TTY asks; --approve-all [host] / --yes / non-TTY auto-approve; --skip-approve-all skips.
  * @param {object} options
  * @param {{ interactive?: boolean, inquirer?: object, ask?: boolean }} [deps]
  * @returns {Promise<object>}
  */
 async function enrichApproveAllOptions(options, deps = {}) {
   const hosts = normalizeHosts(options.host);
-  const needsHost = hosts.includes('claude') || hosts.includes('codex');
-  if (!needsHost || options.skipApproveAll) {
+  const eligible = hosts.filter((h) => APPROVE_HOSTS.includes(h));
+  if (!eligible.length || options.skipApproveAll) {
     return { ...options, approveAll: false };
   }
-  if (options.approveAll || options.yes) {
+  if (options.approveAll) {
+    parseApproveAll(options.approveAll);
+    return options;
+  }
+  if (options.yes) {
     return { ...options, approveAll: true };
   }
   if (deps.ask === false) {
@@ -219,15 +259,8 @@ async function enrichApproveAllOptions(options, deps = {}) {
     return { ...options, approveAll: true };
   }
   const inquirer = deps.inquirer || require('inquirer');
-  const { approveAll } = await inquirer.prompt([
-    {
-      type: 'confirm',
-      name: 'approveAll',
-      message: 'Auto-approve all Claude Code and Codex tool permissions in this workspace?',
-      default: true
-    }
-  ]);
-  return { ...options, approveAll: Boolean(approveAll) };
+  const approveAll = await askApproveAllChoice(inquirer, eligible);
+  return { ...options, approveAll };
 }
 
 module.exports = {

package/lib/agent-kit/run.js

@@ -46,7 +46,7 @@ function runManagedCommand(options, mode) {
   const approvals = writeApproveAllFiles({
     repoRoot,
     hosts,
-    approveAll: Boolean(options.approveAll),
+    approveAll: options.approveAll,
     dryRun: Boolean(options.dryRun),
     force: Boolean(options.force)
   });

package/lib/agent-kit/start.js

@@ -0,0 +1,310 @@
+/**
+ * Start Claude Code or Codex in a named tmux session.
+ * @fileoverview Does not install Agent Kit skills
+ */
+
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { execFileSync, spawnSync } = require('child_process');
+const logger = require('../utils/logger');
+const { resolveGitRoot } = require('./repo-guard');
+const { writeApproveAllFiles } = require('./host-approve');
+
+const START_APPS = {
+  claude: { bin: 'claude' },
+  codex: { bin: 'codex' }
+};
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function normalizeStartApp(value) {
+  const app = String(value || '').trim();
+  if (!START_APPS[app]) {
+    throw new Error('Invalid app. Use claude or codex.');
+  }
+  return app;
+}
+
+/**
+ * Session names may not contain colons or periods.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function sanitizeSessionName(value) {
+  const name = String(value || '')
+    .trim()
+    .replace(/[.:\s]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  if (!name) {
+    throw new Error(
+      'Invalid --name. Use the last folder of this git workspace, for example aifabrix-docs.'
+    );
+  }
+  return name;
+}
+
+/**
+ * Default display name is the last folder of the git workspace.
+ * @param {unknown} explicit
+ * @param {string} cwd
+ * @returns {string}
+ */
+function resolveSessionName(explicit, cwd) {
+  const raw = explicit === undefined || explicit === null || explicit === ''
+    ? path.basename(cwd)
+    : explicit;
+  return sanitizeSessionName(raw);
+}
+
+/**
+ * @param {object} options
+ * @returns {string}
+ */
+function currentUsername(options) {
+  if (options && options.username) {
+    return String(options.username);
+  }
+  try {
+    return os.userInfo().username;
+  } catch {
+    return process.env.USER || process.env.LOGNAME || 'user';
+  }
+}
+
+/**
+ * Hostname + login, e.g. builder01-dev03.
+ * @param {object} [options]
+ * @returns {string}
+ */
+function hostUserPrefix(options) {
+  const hostRaw = options && options.hostname ? options.hostname : os.hostname();
+  const host = String(hostRaw).split('.')[0];
+  return sanitizeSessionName(`${host}-${currentUsername(options || {})}`);
+}
+
+/**
+ * Remote Control session: builder01-dev03-aifabrix-docs.
+ * @param {string} prefix
+ * @param {string} session
+ * @returns {string}
+ */
+function resolveRemoteControlName(prefix, session) {
+  return sanitizeSessionName(`${prefix}-${session}`);
+}
+
+/**
+ * @param {string} bin
+ * @param {Function} exec
+ * @returns {boolean}
+ */
+function hasOnPath(bin, exec) {
+  try {
+    exec('which', [bin], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {object} options
+ * @returns {void}
+ */
+function validateStartOptions(options) {
+  const app = String(options.app || '').trim();
+  if (options.remoteControl && app !== 'claude') {
+    throw new Error('--remote-control is only valid with claude.');
+  }
+}
+
+/**
+ * Claude argv after the binary (Remote Control names, not Claude --tmux).
+ * @param {object} p
+ * @returns {string[]}
+ */
+function claudeInnerArgs(p) {
+  const args = ['--name', p.session];
+  if (!p.remoteControl) {
+    return args;
+  }
+  return args.concat([
+    '--remote-control',
+    p.remoteControlName,
+    '--remote-control-session-name-prefix',
+    p.remoteControlPrefix
+  ]);
+}
+
+/**
+ * @param {object} p
+ * @returns {object}
+ */
+function buildTmuxSpec(p) {
+  const spec = START_APPS[p.app];
+  const extra = p.app === 'claude' ? claudeInnerArgs(p) : [];
+  const mode = p.detach
+    ? ['new-session', '-d', '-s', p.session, '-c', p.cwd]
+    : ['new-session', '-A', '-s', p.session, '-c', p.cwd];
+  const remote = p.app === 'claude' && p.remoteControl;
+  return {
+    bin: 'tmux',
+    args: [...mode, spec.bin, ...extra],
+    session: p.session,
+    appBin: spec.bin,
+    needTmux: true,
+    remoteControlName: remote ? p.remoteControlName : undefined,
+    remoteControlPrefix: remote ? p.remoteControlPrefix : undefined
+  };
+}
+
+/**
+ * @param {object} p
+ * @returns {object}
+ */
+function buildLaunchSpec(p) {
+  return buildTmuxSpec(p);
+}
+
+/**
+ * @param {{ appBin: string, needTmux?: boolean }} spec
+ * @param {Function} exec
+ * @returns {void}
+ */
+function requireBinaries(spec, exec) {
+  if (spec.needTmux && !hasOnPath('tmux', exec)) {
+    throw new Error('tmux is not on PATH. Install tmux, then retry.');
+  }
+  if (hasOnPath(spec.appBin, exec)) {
+    return;
+  }
+  if (spec.appBin === 'claude') {
+    throw new Error(
+      'claude is not on PATH. Install with: curl -fsSL https://claude.ai/install.sh | bash'
+    );
+  }
+  throw new Error('codex is not on PATH. Install with: npm install -g @openai/codex');
+}
+
+/**
+ * @param {object} options
+ * @returns {boolean}
+ */
+function shouldExecute(options) {
+  if (options.dryRun || options.json) {
+    return false;
+  }
+  if (options.detach) {
+    return true;
+  }
+  if (!process.stdout.isTTY) {
+    throw new Error('agent-kit start needs a TTY to attach. Pass --detach or --dry-run.');
+  }
+  return true;
+}
+
+/**
+ * @param {object} options
+ * @param {{ bin: string, args: string[], cwd: string }} spec
+ * @returns {unknown}
+ */
+function spawnLaunch(options, spec) {
+  const spawn = options.spawnSync || spawnSync;
+  const result = spawn(spec.bin, spec.args, { stdio: 'inherit', cwd: spec.cwd });
+  const status = result && typeof result.status === 'number' ? result.status : 0;
+  if (status !== 0) {
+    throw new Error(`${spec.bin} exited with status ${status}`);
+  }
+  return status;
+}
+
+/**
+ * @param {object} spec
+ * @param {object} extra
+ * @returns {object}
+ */
+function toStartResult(spec, extra) {
+  const launch = [spec.bin, ...spec.args];
+  return {
+    command: 'start',
+    app: extra.app,
+    session: spec.session,
+    remoteControlName: spec.remoteControlName,
+    remoteControlPrefix: spec.remoteControlPrefix,
+    path: extra.cwd,
+    launch,
+    tmux: spec.needTmux ? launch : undefined,
+    approvals: extra.approvals,
+    dryRun: extra.dryRun,
+    detach: extra.detach,
+    executed: extra.executed
+  };
+}
+
+/**
+ * @param {object} options
+ * @returns {object}
+ */
+function runStart(options) {
+  validateStartOptions(options);
+  const app = normalizeStartApp(options.app);
+  const cwd = resolveGitRoot(options.cwd || process.cwd());
+  const session = resolveSessionName(options.name, cwd);
+  const remoteControlPrefix = hostUserPrefix(options);
+  const remoteControlName = resolveRemoteControlName(remoteControlPrefix, session);
+  const exec = options.execFileSync || execFileSync;
+  const spec = buildLaunchSpec({
+    app,
+    cwd,
+    session,
+    remoteControlPrefix,
+    remoteControlName,
+    detach: Boolean(options.detach),
+    remoteControl: Boolean(options.remoteControl)
+  });
+  spec.cwd = cwd;
+  const approveAll = !options.skipApproveAll && Boolean(options.approveAll || options.yes);
+  const approvals = writeApproveAllFiles({
+    repoRoot: cwd,
+    hosts: [app],
+    approveAll,
+    dryRun: Boolean(options.dryRun)
+  });
+  if (!options.dryRun) {
+    requireBinaries(spec, exec);
+  }
+  const execute = shouldExecute(options);
+  if (execute && !options.json) {
+    logger.log(`Starting ${app} session ${spec.session}`);
+  }
+  if (execute) {
+    spawnLaunch(options, spec);
+  }
+  return toStartResult(spec, {
+    app,
+    cwd,
+    approvals,
+    dryRun: Boolean(options.dryRun),
+    detach: Boolean(options.detach),
+    executed: execute
+  });
+}
+
+module.exports = {
+  START_APPS,
+  normalizeStartApp,
+  sanitizeSessionName,
+  resolveSessionName,
+  hostUserPrefix,
+  resolveRemoteControlName,
+  claudeInnerArgs,
+  buildTmuxSpec,
+  runStart
+};

package/lib/api/pipeline.api.js

@@ -278,7 +278,10 @@ function resolvePipelineUploadTimeoutMs(raw) {
  * @param {Object} authConfig
  * @param {Object} payload
  * @param {Object} [options]
- * @param {number|string} [options.timeoutMs] - HTTP + dataplane publish budget (default 300000)
+ * @param {number|string} [options.timeoutMs] - HTTP + dataplane publish budget (default 300000); ignored when options.async is true.
+ * @param {boolean} [options.async=false] - When true, durably accept the upload for qualification (202 jobId/candidateFingerprint) instead of blocking for the ladder (plan 191.0 task 1).
+ * @param {string} [options.gate] - Optional comma-separated checks: operations, trust, governance, full.
+ * @param {string} [options.subjectEmail] - Optional comma-separated governance subject emails.
  */
 async function uploadApplicationViaPipeline(
   dataplaneUrl,
@@ -287,8 +290,17 @@ async function uploadApplicationViaPipeline(
   options = {}
 ) {
   const body = { ...payload, status: payload.status ?? 'draft' };
-  const timeoutMs = resolvePipelineUploadTimeoutMs(options.timeoutMs);
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  if (options.async === true) {
+    const params = { async: 'true' };
+    if (options.gate) params.gate = options.gate;
+    if (options.subjectEmail) params.subjectEmail = options.subjectEmail;
+    return await client.post('/api/v1/pipeline/upload', {
+      body,
+      params
+    });
+  }
+  const timeoutMs = resolvePipelineUploadTimeoutMs(options.timeoutMs);
   return await client.post('/api/v1/pipeline/upload', {
     body,
     timeoutMs,
@@ -297,6 +309,23 @@ async function uploadApplicationViaPipeline(
   });
 }
 
+/**
+ * Get durable publish/qualification job status.
+ * GET /api/v1/publish-jobs/{jobId}
+ * @requiresPermission {Dataplane} external-system:publish or external-system:read
+ * @async
+ * @function getPublishJobStatus
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} jobId - Publish/qualification job id returned by uploadApplicationViaPipeline({ async: true })
+ * @returns {Promise<Object>} API envelope `{ success, data }` where `data` is `{ jobId, state, targetType, targetKey, steps, error, result }`
+ * @throws {Error} If request fails
+ */
+async function getPublishJobStatus(dataplaneUrl, authConfig, jobId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  return await client.get(`/api/v1/publish-jobs/${encodeURIComponent(jobId)}`);
+}
+
 module.exports = {
   validatePipeline,
   deployPipeline,
@@ -307,7 +336,7 @@ module.exports = {
   testSystemViaPipeline,
   testDatasourceViaPipeline,
   uploadApplicationViaPipeline,
+  getPublishJobStatus,
   resolvePipelineUploadTimeoutMs,
   PIPELINE_UPLOAD_TIMEOUT_MS
 };
-

package/lib/app/deploy.js

@@ -23,6 +23,7 @@ const pushUtils = require('../deployment/push');
 const SEP = chalk.gray('────────────────────────────────────────');
 const logger = require('../utils/logger');
 const { detectAppType, getBuilderPath, getIntegrationPath } = require('../utils/paths');
+const { offerCreateFromTemplateIfMissing } = require('./offer-create-from-template');
 const { checkApplicationExists } = require('../utils/app-existence');
 const { loadDeploymentConfig } = require('./deploy-config');
 const { logOfflinePathWhenType } = require('../utils/cli-utils');
@@ -307,10 +308,12 @@ function validateImageIsPullable(imageRef, appName) {
  */
 function throwIfDeploymentFailed(status, statusObj) {
   if (status !== 'failed' && status !== 'cancelled') return;
-  const msg =
-    statusObj.message ||
-    statusObj.error ||
-    (status === 'cancelled' ? 'Deployment cancelled' : 'Deployment failed');
+  const reportedErrors = Array.isArray(statusObj.errors) ? statusObj.errors.filter(Boolean).join('; ') : '';
+  // A failed deployment can retain its last progress message (for example
+  // "Database-only mode"). Prefer the terminal error so the CLI reports the cause.
+  const msg = status === 'failed'
+    ? statusObj.error || reportedErrors || statusObj.message || 'Deployment failed'
+    : statusObj.message || statusObj.error || reportedErrors || 'Deployment cancelled';
   const err = new Error(`Deployment ${status}: ${msg}`);
   err.formatted = `Deployment ${status}.\n\n${msg}`;
   err.deploymentStatus = statusObj;
@@ -462,7 +465,7 @@ async function executeDeployPipeline(appName, options) {
  * @param {boolean} [options.poll] - Poll for deployment status
  * @param {number} [options.pollInterval] - Polling interval in milliseconds
  * @param {number} [options.pollMaxAttempts] - Max polling attempts
- * @returns {Promise<{ result: Object, usedExternalDeploy: boolean }>} Deployment result and whether external deploy was used
+ * @returns {Promise<{ result: Object, usedExternalDeploy: boolean, appKey: string }>} Deployment result and whether external deploy was used
  * @throws {Error} If deployment fails
  *
  * Controller and environment come from config.yaml (set via aifabrix login or aifabrix auth config).
@@ -473,16 +476,18 @@ async function executeDeployPipeline(appName, options) {
 async function deployApp(appName, options = {}) {
   let controllerUrl = null;
   let usedExternalDeploy = false;
+  let resolvedName = appName;
 
   try {
     assertDeployNotProtectionScope(appName);
     validateAppName(appName);
-    const pipeline = await executeDeployPipeline(appName, options);
+    resolvedName = await offerCreateFromTemplateIfMissing(appName, options);
+    const pipeline = await executeDeployPipeline(resolvedName, options);
     controllerUrl = pipeline.controllerUrl ?? null;
     usedExternalDeploy = pipeline.usedExternalDeploy;
-    return { result: pipeline.result, usedExternalDeploy };
+    return { result: pipeline.result, usedExternalDeploy, appKey: resolvedName };
   } catch (error) {
-    await handleDeploymentError(error, appName, controllerUrl, usedExternalDeploy);
+    await handleDeploymentError(error, resolvedName, controllerUrl, usedExternalDeploy);
   }
 }
 
@@ -492,4 +497,3 @@ module.exports = {
   validateAppName,
   validateImageIsPullable
 };
-