@aifabrix/builder 2.50.0 → 2.51.1

package/lib/api/types/evidence.types.js

@@ -1,11 +1,11 @@
 /**
  * @fileoverview JSDoc types for Evidence Fabrix dataplane API.
  * @author AI Fabrix Team
- * @version 1.0.0
+ * @version 1.1.0
  */
 
 /**
- * @typedef {'active' | 'disabled'} EvidenceStatus
+ * @typedef {'candidate' | 'active' | 'disabled' | 'archived'} EvidenceStatus
  */
 
 /**
@@ -19,11 +19,44 @@
  * @property {string|null} [roleKey]
  */
 
+/**
+ * @typedef {Object} EvidenceContributionOverride
+ * @property {string} contributionKey
+ * @property {number} referenceValue
+ */
+
+/**
+ * @typedef {Object} EvidenceValueProposal
+ * @property {number|null} [primaryReferenceValue]
+ * @property {string|null} [primaryContributionKey]
+ * @property {string|null} [unit]
+ * @property {string|null} [rationale]
+ * @property {EvidenceContributionOverride[]} [overrides]
+ */
+
+/**
+ * @typedef {Object} EvidenceContributionProjectionItem
+ * @property {string} contributionKey
+ * @property {string|null} [typeRef]
+ * @property {string|null} [unit]
+ * @property {boolean} [primary]
+ * @property {number|null} [inheritedReferenceValue]
+ * @property {number|null} [effectiveReferenceValue]
+ * @property {boolean} [overridden]
+ * @property {string|null} [attributionKey]
+ * @property {string|null} [attributionBoundary]
+ * @property {string|null} [kindKey]
+ * @property {string|null} [kindVersion]
+ */
+
 /**
  * @typedef {Object} EvidenceRow
  * @property {string} id
- * @property {string} resourceType
+ * @property {string|null} [key]
+ * @property {string|null} [resourceType]
  * @property {string|null} [roleKey]
+ * @property {string|null} [kindKey]
+ * @property {string|null} [kindVersion]
  * @property {string} title
  * @property {string|null} [description]
  * @property {string} when
@@ -32,23 +65,34 @@
  * @property {EvidenceStatus} status
  * @property {number|null} [generationConfidence]
  * @property {string|null} [suggestionExplanation]
+ * @property {EvidenceContributionOverride[]|null} [contributionOverrides]
+ * @property {EvidenceValueProposal|null} [valueProposal]
+ * @property {EvidenceContributionProjectionItem[]|null} [contributionProjection]
+ * @property {string|null} [fingerprint]
+ * @property {Object|null} [provenanceSummary]
+ * @property {Object|null} [trustProjections]
  * @property {EvidenceApprovalPolicy} approval
- * @property {'human' | 'assistant'} createdByType
- * @property {string} createdById
- * @property {string} createdAt
- * @property {string} updatedAt
+ * @property {'human' | 'assistant'} [createdByType]
+ * @property {string|Object} [createdById]
+ * @property {string} [createdAt]
+ * @property {string} [updatedAt]
  */
 
 /**
  * @typedef {Object} EvidenceCreatePayload
- * @property {string} resourceType
+ * @property {string|null} [key]
+ * @property {string|null} [resourceType]
  * @property {string|null} [roleKey]
+ * @property {string|null} [kindKey]
+ * @property {string|null} [kindVersion]
  * @property {string} title
  * @property {string|null} [description]
  * @property {string} when
  * @property {string} expectedBehavior
  * @property {number|null} [order]
  * @property {EvidenceStatus} [status]
+ * @property {EvidenceContributionOverride[]} [contributionOverrides]
+ * @property {string|null} [suggestionExplanation]
  * @property {EvidenceApprovalPolicy} [approval]
  */
 
@@ -62,6 +106,110 @@
  * @property {string} [roleKey]
  * @property {boolean} [genericOnly]
  * @property {EvidenceStatus} [status]
+ * @property {string} [kindKey]
+ * @property {string} [aspect]
+ * @property {string} [search]
+ * @property {number} [limit]
+ * @property {number} [offset]
+ */
+
+/**
+ * @typedef {Object} EvidenceMetadataKind
+ * @property {string|null} key
+ * @property {string|null} version
+ * @property {string|null} [displayName]
+ * @property {string|null} [purpose]
+ */
+
+/**
+ * @typedef {Object} EvidenceMetadataResourceType
+ * @property {string|null} key
+ * @property {string|null} [displayName]
+ * @property {string|null} [category]
+ */
+
+/**
+ * @typedef {Object} EvidenceAuthoringMetadata
+ * @property {string} roleKey
+ * @property {EvidenceMetadataKind[]} evidenceKinds
+ * @property {string[]} aspects
+ * @property {EvidenceMetadataResourceType[]} resourceTypes
+ * @property {string[]} assistantCapabilities
+ * @property {string[]} writableFields
+ * @property {string[]} requiredFields
+ * @property {Object} constraints
+ * @property {Object} constraints.certification
+ * @property {string} constraints.certification.validationStatus
+ * @property {string} constraints.certification.candidateStatus
+ * @property {Object} constraints.activation
+ * @property {boolean} constraints.activation.requiresCertified
+ * @property {boolean} constraints.activation.requiresAuthority
+ */
+
+/**
+ * @typedef {EvidenceListParams & { roleKey: string }} EvidenceDownloadParams
+ */
+
+/**
+ * @typedef {Object} EvidenceDownloadResponse
+ * @property {string} roleKey
+ * @property {number} count
+ * @property {EvidenceRow[]} data
+ */
+
+/**
+ * @typedef {Object} EvidenceUploadRequest
+ * @property {string} roleKey
+ * @property {EvidenceCreatePayload[]} rows
+ * @property {string} [comment]
+ */
+
+/**
+ * @typedef {Object} EvidenceUploadAcceptedItem
+ * @property {number} index
+ * @property {string} evidenceRef
+ * @property {string} status
+ */
+
+/**
+ * @typedef {Object} EvidenceUploadRejectedItem
+ * @property {number} index
+ * @property {string} error
+ * @property {string} [evidenceRef]
+ * @property {Object[]} [issues]
+ */
+
+/**
+ * @typedef {Object} EvidenceUploadCertifiedItem
+ * @property {number} index
+ * @property {string} evidenceRef
+ * @property {string} status
+ * @property {Object} data
+ */
+
+/**
+ * @typedef {Object} EvidenceUploadResponse
+ * @property {string} roleKey
+ * @property {number} inserted
+ * @property {number} updated
+ * @property {EvidenceUploadAcceptedItem[]} accepted
+ * @property {EvidenceUploadRejectedItem[]} rejected
+ * @property {Object[]} warnings
+ * @property {EvidenceUploadCertifiedItem[]} certified
+ * @property {boolean} readyToActivate
+ */
+
+/**
+ * @typedef {Object} EvidenceActivateRequest
+ * @property {string[]} evidenceIds
+ */
+
+/**
+ * @typedef {Object} EvidenceActivateResponse
+ * @property {number} requested
+ * @property {Array<{ evidenceId: string, result: Object }>} activated
+ * @property {Array<{ evidenceId: string, error: string, status: number|null }>} failed
+ * @property {boolean} success
  */
 
 module.exports = {};

package/lib/api/types/roles.types.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Business role API type definitions (Controller /api/v1/roles)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * Create business role request body (API shape uses domainKey)
+ * @typedef {Object} CreateBusinessRoleRequest
+ * @property {string} key - Catalog key (lowercase, hyphens)
+ * @property {string} domainKey - Enterprise domain key
+ * @property {string} displayName - Human-readable name
+ * @property {string} [description] - Optional description
+ * @property {string} [purpose] - Role purpose
+ * @property {string} [businessOutcome] - Business outcome
+ * @property {boolean} [isActive] - Active flag
+ * @property {string} [source] - Provenance source
+ * @property {Object} [metadata] - Compiler fields and extensions
+ */
+
+/**
+ * Business role record
+ * @typedef {Object} BusinessRoleRecord
+ * @property {string} id - Controller id
+ * @property {string} key - Catalog key
+ * @property {string} domainKey - Enterprise domain key
+ * @property {string} displayName - Display name
+ * @property {string} [description] - Description
+ * @property {string} [purpose] - Purpose
+ * @property {string} [businessOutcome] - Business outcome
+ * @property {boolean} isActive - Active flag
+ * @property {string} [source] - Source
+ * @property {Object} [metadata] - Metadata
+ */
+
+module.exports = {};

package/lib/api/work.api.js

@@ -0,0 +1,283 @@
+/**
+ * @fileoverview Dataplane work runtime API client for role-assistant test flows.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+/** Work Hub plan create runs LLM planning; 30s default is too short under load/reload. */
+const WORK_PLAN_TIMEOUT_MS = 120000;
+/** Task poll / result fetch can wait on Celery + CIP. */
+const WORK_TASK_TIMEOUT_MS = 60000;
+
+/**
+ * Some dataplane work routes return `{ data: { … } }` while ApiClient already
+ * wraps once — peel a nested `data` envelope when top-level identity is missing.
+ */
+function unwrapWorkPayload(res) {
+  const cur = unwrapApiData(res);
+  if (!cur || typeof cur !== 'object' || Array.isArray(cur)) {
+    return cur;
+  }
+  if (cur.planId || cur.taskId || cur.processExecutionId || cur.status || cur.schemaVersion) {
+    return cur;
+  }
+  if (cur.data && typeof cur.data === 'object' && !Array.isArray(cur.data)) {
+    return cur.data;
+  }
+  return cur;
+}
+
+function extractApiErrorMessage(res, fallbackMessage) {
+  return (
+    (res &&
+      res.error &&
+      (res.error.formattedError || res.error.error || res.error.message || res.error.detail)) ||
+    (res && (res.formattedError || res.error || res.message)) ||
+    fallbackMessage
+  );
+}
+
+function assertObjectShape(value, fallbackMessage) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(fallbackMessage);
+  }
+}
+
+/**
+ * POST /api/v1/work/start
+ * @requiresPermission {Dataplane} worker-task:create
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {Object} body
+ * @returns {Promise<Object>}
+ */
+async function startWorkIntent(dataplaneUrl, authConfig, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.post('/api/v1/work/start', { body });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.start request failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.start returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * GET /api/v1/work/executions/{processExecutionId}
+ * @requiresPermission {Dataplane} worker-task:read
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} processExecutionId
+ * @returns {Promise<Object>}
+ */
+async function getWorkExecutionStatus(dataplaneUrl, authConfig, processExecutionId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(processExecutionId));
+  const res = await client.get(`/api/v1/work/executions/${encodedId}`, {
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.status request failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.status returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/work/executions/{processExecutionId}/respond
+ * @requiresPermission {Dataplane} worker-task:update
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} processExecutionId
+ * @param {Object} body
+ * @returns {Promise<Object>}
+ */
+async function respondWorkExecution(dataplaneUrl, authConfig, processExecutionId, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(processExecutionId));
+  const res = await client.post(`/api/v1/work/executions/${encodedId}/respond`, {
+    body,
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.respond request failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.respond returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/work/executions/{processExecutionId}/continue
+ * @requiresPermission {Dataplane} worker-task:update
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} processExecutionId
+ * @param {Object} [body]
+ * @returns {Promise<Object>}
+ */
+async function continueWorkExecution(dataplaneUrl, authConfig, processExecutionId, body = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(processExecutionId));
+  const res = await client.post(`/api/v1/work/executions/${encodedId}/continue`, {
+    body,
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.continue request failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.continue returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * GET /api/v1/work/executions/{processExecutionId}/result
+ * @requiresPermission {Dataplane} worker-task:read
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} processExecutionId
+ * @param {Object} [query]
+ * @returns {Promise<Object>}
+ */
+async function getWorkExecutionResult(dataplaneUrl, authConfig, processExecutionId, query = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(processExecutionId));
+  const params = {};
+  if (query && typeof query === 'object') {
+    if (query.requestedDepth) {
+      params.requestedDepth = String(query.requestedDepth);
+    }
+    if (query.format) {
+      params.format = String(query.format);
+    }
+    if (query.projection) {
+      params.projection = String(query.projection);
+    }
+  }
+  const res = await client.get(`/api/v1/work/executions/${encodedId}/result`, {
+    params,
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.result request failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.result returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/work/tasks/plan — Work Hub plan (objective → Role Assistant).
+ * @requiresPermission {Dataplane} worker-task:create
+ */
+async function createWorkTaskPlan(dataplaneUrl, authConfig, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.post('/api/v1/work/tasks/plan', {
+    body,
+    timeoutMs: WORK_PLAN_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.tasks.plan request failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.tasks.plan returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/work/tasks/plan/{planId}/activate-assistant
+ * @requiresPermission {Dataplane} worker-task:update
+ */
+async function activateWorkPlanAssistant(dataplaneUrl, authConfig, planId, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(planId));
+  const res = await client.post(`/api/v1/work/tasks/plan/${encodedId}/activate-assistant`, {
+    body,
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.tasks.plan.activate-assistant failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'activate-assistant returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/work/tasks/plan/{planId}/accept
+ * @requiresPermission {Dataplane} worker-task:update
+ */
+async function acceptWorkTaskPlan(dataplaneUrl, authConfig, planId, body = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(planId));
+  const res = await client.post(`/api/v1/work/tasks/plan/${encodedId}/accept`, {
+    body: { planId, ...body },
+    timeoutMs: WORK_PLAN_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.tasks.plan.accept failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.tasks.plan.accept returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * GET /api/v1/work/tasks/{taskId}
+ * @requiresPermission {Dataplane} worker-task:read
+ */
+async function getWorkTask(dataplaneUrl, authConfig, taskId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(taskId));
+  const res = await client.get(`/api/v1/work/tasks/${encodedId}`, {
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.tasks.get failed'));
+  }
+  const unwrapped = unwrapWorkPayload(res);
+  assertObjectShape(unwrapped, 'work.tasks.get returned an unexpected response shape');
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/work/tasks/{taskId}/approve
+ * @requiresPermission {Dataplane} worker-task:update
+ */
+async function approveWorkTask(dataplaneUrl, authConfig, taskId, body = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const encodedId = encodeURIComponent(String(taskId));
+  const res = await client.post(`/api/v1/work/tasks/${encodedId}/approve`, {
+    body: { taskId, ...body },
+    timeoutMs: WORK_TASK_TIMEOUT_MS
+  });
+  if (res && res.success === false) {
+    throw new Error(extractApiErrorMessage(res, 'work.tasks.approve failed'));
+  }
+  return unwrapWorkPayload(res);
+}
+
+module.exports = {
+  startWorkIntent,
+  getWorkExecutionStatus,
+  respondWorkExecution,
+  continueWorkExecution,
+  getWorkExecutionResult,
+  createWorkTaskPlan,
+  activateWorkPlanAssistant,
+  acceptWorkTaskPlan,
+  getWorkTask,
+  approveWorkTask
+};

package/lib/app/certification-verify-rows.js

@@ -16,7 +16,7 @@ const { getActiveIntegrationCertificate, verifyIntegrationCertificate } = requir
 function certificateIdString(id) {
   if (id === undefined || id === null) return null;
   if (typeof id === 'string') return id.trim() || null;
-  if (typeof id === 'object' && id !== null && typeof id.id === 'string') return id.id.trim() || null;
+  if (typeof id === 'object' && typeof id.id === 'string') return id.id.trim() || null;
   return null;
 }
 

package/lib/app/run-deploy-job.js

@@ -0,0 +1,108 @@
+/**
+ * Optional build.deployJob — one-shot before long-running aifabrix run start.
+ *
+ * @fileoverview Run deployJob once per aifabrix run
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const config = require('../core/config');
+const logger = require('../utils/logger');
+const {
+  infoLine,
+  formatSuccessLine,
+  formatBlockingError
+} = require('../utils/cli-test-layout-chalk');
+const { runDockerRunEphemeral } = require('../utils/docker-run-ephemeral');
+const { getInfraBridgeNetworkName } = require('../infrastructure/orphan-infra-docker-teardown');
+
+/**
+ * Resolve trimmed deployJob from app config, or null if unset.
+ * @param {Object} appConfig - Application configuration
+ * @returns {string|null}
+ */
+function resolveDeployJobCommand(appConfig) {
+  const raw = appConfig?.build?.deployJob;
+  if (typeof raw !== 'string') {
+    return null;
+  }
+  const trimmed = raw.trim();
+  return trimmed ? trimmed : null;
+}
+
+/**
+ * Developer infra bridge so ephemeral jobs resolve compose DNS (e.g. postgres).
+ * @returns {Promise<string>}
+ */
+async function resolveDeployJobNetwork() {
+  const developerId = await config.getDeveloperId();
+  return getInfraBridgeNetworkName(developerId);
+}
+
+/**
+ * If build.deployJob is set, run it once in an ephemeral container (same image + env).
+ * Fail-closed on non-zero exit. No-op when unset.
+ *
+ * When `devMountPath` is set (aifabrix run --reload), bind-mount that path at `/app`
+ * so migrate/deploy sees the same tree as the long-running reload container.
+ *
+ * @async
+ * @param {Object} params
+ * @param {Object} params.appConfig - Application configuration
+ * @param {string} params.fullImage - Image:tag used for the run
+ * @param {string|null} [params.runEnvPath] - Ephemeral .env.run path for --env-file
+ * @param {string|null} [params.devMountPath] - Host path mounted at /app for --reload
+ * @param {boolean} [params.debug]
+ * @returns {Promise<void>}
+ * @throws {Error} If deployJob exits non-zero
+ */
+async function runDeployJobIfConfigured({
+  appConfig,
+  fullImage,
+  runEnvPath = null,
+  devMountPath = null,
+  debug = false
+}) {
+  const cmd = resolveDeployJobCommand(appConfig);
+  if (!cmd) {
+    return;
+  }
+  if (!fullImage || typeof fullImage !== 'string') {
+    throw new Error('build.deployJob requires a resolved container image');
+  }
+  const network = await resolveDeployJobNetwork();
+  const volumeMounts = _deployJobVolumeMounts(devMountPath);
+  logger.log(infoLine(`Running build.deployJob once before start (${fullImage})…`));
+  if (debug) {
+    logger.log(infoLine(`deployJob: ${cmd}`));
+    logger.log(infoLine(`deployJob network: ${network}`));
+    if (volumeMounts.length) {
+      logger.log(infoLine(`deployJob mount: ${volumeMounts[0].host} -> /app`));
+    }
+  }
+  const code = await runDockerRunEphemeral(fullImage, cmd, runEnvPath, {
+    network,
+    volumeMounts
+  });
+  if (code !== 0) {
+    logger.log(formatBlockingError(`build.deployJob failed with exit code ${code}`));
+    throw new Error(`build.deployJob failed with exit code ${code}`);
+  }
+  logger.log(formatSuccessLine('build.deployJob completed'));
+}
+
+/**
+ * @param {string|null|undefined} devMountPath
+ * @returns {Array<{ host: string, container: string }>}
+ */
+function _deployJobVolumeMounts(devMountPath) {
+  if (typeof devMountPath !== 'string' || !devMountPath.trim()) {
+    return [];
+  }
+  return [{ host: devMountPath.trim(), container: '/app' }];
+}
+
+module.exports = {
+  resolveDeployJobCommand,
+  runDeployJobIfConfigured
+};

package/lib/app/run-helpers.js

@@ -34,7 +34,12 @@ const runEnvCompose = require('./run-env-compose');
 const { getAppInfraRequirements } = require('./run-infra-requirements');
 const { resolveRunImage } = require('./run-resolve-image');
 const { startContainer } = require('./run-container-start');
-const { resolveEnvOutputPath, writeEnvOutputForReload, writeEnvOutputForLocal } = require('../utils/env-copy');
+const {
+  resolveEnvOutputPath,
+  resolveEnvLocalOutputPath,
+  writeEnvOutputForReload,
+  writeEnvOutputForLocal
+} = require('../utils/env-copy');
 const { resolveVersionForApp } = require('../utils/image-version');
 const healthCheckUtil = require('../utils/health-check');
 const { computeTraefikPublicAppUrl } = require('../utils/health-check-url');
@@ -303,8 +308,8 @@ async function generateComposeFile(appName, appConfig, composeOptions, devDir, l
 
 /**
  * Writes `build.envOutputPath` after each `aifabrix run`: **local**-flavored env for the host/IDE
- * when not using `--reload`; with **`--reload`**, merges container `.env.run` into the existing file
- * (preserves resolve comments) without appending run-only keys missing from the template.
+ * when not using `--reload`; with **`--reload`**, merges container `.env.run` into `.env` and also
+ * writes a sibling **`.env.local`** with localhost / published-port URLs for host CLI and manual tests.
  *
  * @async
  * @param {string} appName - Application name
@@ -326,6 +331,8 @@ async function writeEnvOutputIfConfigured(appName, appConfig, runEnvPath, option
   }
   if (options && options.reload === true) {
     await writeEnvOutputForReload(outputPath, runEnvPath, appName);
+    const localOutputPath = resolveEnvLocalOutputPath(outputPath);
+    await writeEnvOutputForLocal(appName, localOutputPath);
   } else {
     await writeEnvOutputForLocal(appName, outputPath);
   }

package/lib/app/run.js

@@ -404,6 +404,14 @@ async function runApp(appName, options = {}) {
       logger.log(chalk.gray(`[DEBUG] Compose file generated: ${prepared.tempComposePath}`));
     }
     logReloadDevSummary(Boolean(prepared.mergedRunOptions.reload), prepared.mergedRunOptions.reloadSyncSummary);
+    const { runDeployJobIfConfigured } = require('./run-deploy-job');
+    await runDeployJobIfConfigured({
+      appConfig: prepared.appConfig,
+      fullImage: prepared.mergedRunOptions.image,
+      runEnvPath: prepared.runEnvPath,
+      devMountPath: prepared.devMountPath || null,
+      debug
+    });
     await startAppContainer(appName, prepared.tempComposePath, prepared.hostPort, prepared.appConfig, {
       debug,
       runEnvPath: prepared.runEnvPath,