@aifabrix/builder 2.54.1 → 2.55.2

package/lib/programmatic/openapi-apply-result-schemas.js

@@ -21,6 +21,14 @@ const OPENAPI_APPLY_RESULT_SCHEMAS = {
     },
     ['deployed']
   ),
+  DownloadResultData: frozenObject(
+    {
+      downloaded: { type: 'boolean' },
+      dryRun: { type: 'boolean' },
+      systemKey: schemaRef('SystemKey')
+    },
+    ['downloaded', 'dryRun', 'systemKey']
+  ),
   ProtectionUploadData: frozenObject(
     {
       datasourceKey: schemaRef('DatasourceKey'),

package/lib/programmatic/openapi-channel-install-schemas.js

@@ -90,6 +90,7 @@ const OPENAPI_CHANNEL_INSTALL_RESULT_SCHEMAS = {
     provisioning: schemaRef('ChannelProvisioning'),
     runtimeTarget: schemaRef('ChannelRuntimeTarget'),
     experimental: { type: 'boolean' },
+    status: { type: 'string', enum: ['visible', 'hide', 'coming-soon'] },
     maxInstances: { type: 'integer', minimum: 1 },
     profiles: { type: 'array', items: schemaRef('ChannelTargetProfile') }
   }),
@@ -108,7 +109,8 @@ const OPENAPI_CHANNEL_INSTALL_RESULT_SCHEMAS = {
       maxInstances: { type: 'integer', minimum: 1 },
       installationCount: { type: 'integer', minimum: 0 },
       canInstall: { type: 'boolean' },
-      blockedReason: { type: 'string' }
+      blockedReason: { type: 'string' },
+      status: { type: 'string', enum: ['visible', 'hide', 'coming-soon'] }
     },
     ['key', 'displayName', 'channel', 'installations']
   ),
@@ -140,6 +142,7 @@ const OPENAPI_CHANNEL_INSTALL_RESULT_SCHEMAS = {
       displayLabel: { type: 'string' },
       description: { type: 'string' },
       experimental: { type: 'boolean' },
+      status: { type: 'string', enum: ['visible', 'hide', 'coming-soon'] },
       provisioning: schemaRef('ChannelProvisioning'),
       runtimeTarget: schemaRef('ChannelRuntimeTarget'),
       installationSummary: schemaRef('ChannelInstallationSummary'),

package/lib/programmatic/openapi-component-schemas.js

@@ -40,6 +40,7 @@ const RESPONSE_ENVELOPES = [
   ['PreviewUploadResponse', 'PreviewUploadData'],
   ['UploadResultResponse', 'UploadResultData'],
   ['DeployResultResponse', 'DeployResultData'],
+  ['DownloadResultResponse', 'DownloadResultData'],
   ['ProtectionUploadResponse', 'ProtectionUploadData'],
   ['ProtectionCreateResponse', 'ProtectionCreateData'],
   ['TestResultResponse', 'TestResultData'],

package/lib/programmatic/openapi-descriptions.js

@@ -140,6 +140,12 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
       'Controller deploy for external systems (CLI aifabrix deploy parity). Optional body.gate matches CLI --gate (operations,trust,governance,full). Certificate seal is a platform side-effect of published Deploy — not a separate certificates issue call. Mutating; use Idempotency-Key.',
     tags: ['apply']
   },
+  runDownload: {
+    summary: 'Download system package into the workspace',
+    description:
+      'Fetch the published system from Dataplane into the workspace (CLI aifabrix download parity). Role Assistant packages also pull Evidence, Knowledge, and tests. Mutating; use Idempotency-Key.',
+    tags: ['workspace']
+  },
   runProtectionUpload: {
     summary: 'Upload protection manifest for a datasource',
     description:
@@ -269,13 +275,13 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
   listChannelTargets: {
     summary: 'List live channel definitions',
     description:
-      'List live Channel Definitions. Each row has key, displayLabel, description, experimental, provisioning, runtimeTarget, installationSummary, installationCount, and canInstall. Optional maxInstances and blockedReason when capped. Catalog is information-only; publishing uses POST install. Read-only.',
+      'List live Channel Definitions. Each row has key, displayLabel, description, experimental, status, provisioning, runtimeTarget, installationSummary, installationCount, and canInstall. Optional maxInstances and blockedReason when capped or coming-soon. hide definitions are omitted. Catalog is information-only; publishing uses POST install. Read-only.',
     tags: ['infra']
   },
   getChannelDefinitionDetail: {
     summary: 'Get a Channel Definition',
     description:
-      'Return a safe Channel Definition (identity, configuration, provisioning, runtimeTarget, profiles, optional maxInstances) plus installations projected from Dataplane Connected Systems. Includes canInstall. Unknown definition keys return 404. Known definitions with no instances return installations []. Read-only.',
+      'Return a safe Channel Definition (identity, configuration, provisioning, runtimeTarget, profiles, optional maxInstances, status) plus installations projected from Dataplane Connected Systems. Includes canInstall. Unknown or hide definition keys return 404. Known definitions with no instances return installations []. Read-only.',
     tags: ['infra']
   },
   getChannelInstallation: {
@@ -287,7 +293,7 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
   runChannelInstall: {
     summary: 'Install a channel',
     description:
-      'Scaffold, upload, and configure a channel from a Channel Definition. Path systemKey is the definition key. Body name is required; optional systemKey is the Connected System instance key; configuration is a generic propertyKey map. Returns help markdown plus phase, safe userActions, definitionKey, installationKey, and systemKey (the instance). Mutating.',
+      'Scaffold, upload, and configure a channel from a Channel Definition. Path systemKey is the definition key. Body name is required; optional systemKey is the Connected System instance key; configuration is a generic propertyKey map. hide and coming-soon definitions return 403; --force does not override. Returns help markdown plus phase, safe userActions, definitionKey, installationKey, and systemKey (the instance). Mutating.',
     tags: ['infra']
   },
   getChannelInstall: {

package/lib/programmatic/openapi-envelope-examples.js

@@ -141,6 +141,11 @@ const OPENAPI_ENVELOPE_DATA_EXAMPLES = {
     environment: 'dev',
     systemKey: SAMPLE_SYSTEM_KEY
   },
+  DownloadResultData: {
+    downloaded: true,
+    dryRun: false,
+    systemKey: SAMPLE_SYSTEM_KEY
+  },
   ProtectionUploadData: {
     datasourceKey: SAMPLE_DATASOURCE_KEY,
     uploaded: true,
@@ -282,6 +287,7 @@ const OPENAPI_ENVELOPE_DATA_EXAMPLES = {
         displayLabel: 'ChatGPT',
         description: 'ChatGPT channel',
         experimental: false,
+        status: 'visible',
         provisioning: { mode: 'guided' },
         runtimeTarget: { defaultSystemKey: 'runtime-orchestration', configurable: true },
         installationSummary: { count: 0, statusRollup: 'none' },
@@ -310,6 +316,7 @@ const OPENAPI_ENVELOPE_DATA_EXAMPLES = {
       provisioning: { mode: 'guided' },
       runtimeTarget: { defaultSystemKey: 'runtime-orchestration', configurable: true },
       experimental: false,
+      status: 'visible',
       profiles: []
     },
     installations: []

package/lib/programmatic/openapi-operation-bindings.js

@@ -233,6 +233,11 @@ const OPERATION_BINDINGS = Object.freeze({
     requestBody: jsonRequestBody('DeployRequest'),
     successResponse: 'DeployResultResponse'
   },
+  runDownload: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('DownloadRequest'),
+    successResponse: 'DownloadResultResponse'
+  },
   runProtectionUpload: {
     parameters: [SYSTEM_KEY_PARAM, DATASOURCE_KEY_PARAM],
     requestBody: jsonRequestBody('ProtectionUploadRequest'),

package/lib/programmatic/openapi-request-schemas.js

@@ -147,6 +147,11 @@ const OPENAPI_REQUEST_SCHEMAS = {
     sync: { type: 'boolean' },
     verbose: { type: 'boolean' }
   }),
+  DownloadRequest: frozenObject({
+    force: { type: 'boolean' },
+    dryRun: { type: 'boolean' },
+    format: { type: 'string', enum: ['json', 'yaml'] }
+  }),
   ProtectionUploadRequest: frozenObject({
     dryRun: { type: 'boolean' },
     sync: { type: 'boolean' },

package/lib/programmatic/openapi-schema-descriptions-channel.js

@@ -64,6 +64,7 @@ const CHANNEL_INSTALL_SCHEMA_DESCRIPTIONS = {
     provisioning: 'Provisioning mode for this definition.',
     runtimeTarget: 'Default runtime or MCP Connected System.',
     experimental: 'True when install requires allowExperimental.',
+    status: 'Catalog availability. Omit or visible: listed and installable. hide is omitted from this catalog. coming-soon: listed read-only; new install is refused.',
     maxInstances: 'Optional cap on Connected System instances for this definition. Omit for unbounded.',
     profiles: 'Optional generic install profiles (for example MCP client targets).'
   },
@@ -78,6 +79,7 @@ const CHANNEL_INSTALL_SCHEMA_DESCRIPTIONS = {
     displayLabel: 'Human-readable interface name.',
     description: 'Short catalog blurb for the portal table. Not remaining-step copy.',
     experimental: 'True when the target requires allowExperimental.',
+    status: 'visible: listed and installable. coming-soon: listed read-only. hide is omitted from the catalog.',
     provisioning: 'How Builder provisions this channel (automatic, guided, or cli).',
     runtimeTarget: 'Runtime or MCP Connected System. Not the channel instance key.',
     installationSummary: 'Count and status rollup of Connected System instances for this definition.',
@@ -88,12 +90,12 @@ const CHANNEL_INSTALL_SCHEMA_DESCRIPTIONS = {
     iconHref: 'Data URL for the definition icon.svg from the Builder channel template. Omitted when the template has no icon.',
     maxInstances: 'Optional instance cap from the Channel Definition. Omitted when unbounded.',
     installationCount: 'Number of Connected System instances currently projected for this definition.',
-    canInstall: 'False when installationCount is already at maxInstances. Omitted meaning is canInstall true when unbounded.',
-    blockedReason: 'Present when canInstall is false. Explains why a new install is refused.'
+    canInstall: 'False when coming-soon or when installationCount is already at maxInstances. Omitted meaning is canInstall true when unbounded.',
+    blockedReason: 'Present when canInstall is false. Explains why a new install is refused (coming soon or at cap).'
   },
   ListChannelTargetsData: {
     _schema: 'Catalog of live channel / interface targets.',
-    channels: 'Live targets the caller may install. Unimplemented keys are omitted.'
+    channels: 'Live targets. hide is omitted. coming-soon is included read-only (canInstall false). Unimplemented keys are omitted.'
   },
   ListChannelTargetsResponse: {
     _schema: '200 response envelope for listChannelTargets.',
@@ -116,8 +118,9 @@ const CHANNEL_INSTALL_SCHEMA_DESCRIPTIONS = {
     installations: 'Connected System instances for this definition. Empty array when none exist.',
     maxInstances: 'Optional instance cap from the Channel Definition. Omitted when unbounded.',
     installationCount: 'Number of Connected System instances currently projected for this definition.',
-    canInstall: 'False when installationCount is already at maxInstances.',
-    blockedReason: 'Present when canInstall is false.'
+    canInstall: 'False when coming-soon or when installationCount is already at maxInstances.',
+    blockedReason: 'Present when canInstall is false.',
+    status: 'visible or coming-soon. hide definitions return 404 instead of this payload.'
   },
   ChannelDefinitionDetailResponse: {
     _schema: '200 response envelope for getChannelDefinitionDetail.',

package/lib/programmatic/openapi-schema-descriptions-operations.js

@@ -124,6 +124,12 @@ const OPERATIONS_SCHEMA_DESCRIPTIONS = {
     sync: 'When true, force full datasource data sync after deploy.',
     verbose: 'When true, expand deploy summary output.'
   },
+  DownloadRequest: {
+    _schema: 'Optional flags for workspace download (CLI aifabrix download parity).',
+    force: 'When true, overwrite existing local package files.',
+    dryRun: 'When true, preview files that would be written without mutating the workspace.',
+    format: 'Package file format when downloading a Connected System (json or yaml).'
+  },
   ProtectionUploadRequest: {
     _schema: 'Optional flags for protection upload (CLI protection upload parity).',
     dryRun: 'When true, validate only; do not upload or sync.',
@@ -354,6 +360,19 @@ const OPERATIONS_SCHEMA_DESCRIPTIONS = {
     correlationId: 'UUID correlating logs for this request.',
     requestId: 'Optional per-request UUID when emitted by the server.'
   },
+  DownloadResultData: {
+    _schema: 'Workspace download outcome summary.',
+    downloaded: 'True when package files were written (false on dryRun).',
+    dryRun: 'True when validate-only dry run was requested.',
+    systemKey: 'Downloaded integration or Role Assistant system key.'
+  },
+  DownloadResultResponse: {
+    _schema: '200 response envelope for runDownload.',
+    success: 'Always true for successful builder-api JSON responses.',
+    data: 'Typed payload; see DownloadResultData.',
+    correlationId: 'UUID correlating logs for this request.',
+    requestId: 'Optional per-request UUID when emitted by the server.'
+  },
   ProtectionUploadData: {
     _schema: 'Protection upload outcome.',
     datasourceKey: 'Datasource key whose protection manifest was uploaded.',

package/lib/programmatic/openapi-spec.js

@@ -88,6 +88,7 @@ function applyOperationDurationHints(capability, operation) {
   const durationByHandler = {
     runUpload: Number(process.env.MAX_UPLOAD_TIMEOUT_MS || 300000),
     runDeploySystem: Number(process.env.MAX_DEPLOY_TIMEOUT_MS || 300000),
+    runDownload: Number(process.env.MAX_DOWNLOAD_TIMEOUT_MS || 300000),
     runTest: Number(process.env.MAX_TEST_E2E_TIMEOUT_MS || 120000),
     runCertifyPillar: Number(process.env.MAX_CERTIFY_TIMEOUT_MS || 120000)
   };

package/lib/programmatic/request-timeout.js

@@ -19,6 +19,9 @@ function getTimeoutMsForHandler(handlerId) {
   if (handlerId === 'runDeploySystem') {
     return Number(process.env.MAX_DEPLOY_TIMEOUT_MS || 300000);
   }
+  if (handlerId === 'runDownload') {
+    return Number(process.env.MAX_DOWNLOAD_TIMEOUT_MS || 300000);
+  }
   if (handlerId === 'runTest') {
     return Number(process.env.MAX_TEST_E2E_TIMEOUT_MS || 120000);
   }

package/lib/programmatic/route-handler-map.js

@@ -19,6 +19,7 @@ const { runRepair } = require('./run-repair');
 const { runValidate } = require('./run-validate');
 const { runPreviewUpload, runUpload } = require('./run-upload');
 const { runDeploySystem } = require('./run-deploy');
+const { runDownload } = require('./run-download');
 const { runProtectionUpload, runProtectionCreate } = require('./run-protection');
 const { runTest } = require('./run-test');
 const { runCertifyPillar } = require('./run-certify');
@@ -164,6 +165,12 @@ const HANDLER_MAP = {
       sync: body.sync === true,
       verbose: body.verbose === true
     }),
+  runDownload: (params, auth, body = {}) =>
+    runDownload(buildContext(auth, params.systemKey), {
+      force: body.force === true,
+      dryRun: body.dryRun === true,
+      format: body.format
+    }),
   runProtectionUpload: (params, auth, body) =>
     runProtectionUpload(buildContext(auth, params.systemKey), params.datasourceKey, {
       dryRun: body.dryRun === true,

package/lib/programmatic/run-channel-catalog.js

@@ -8,7 +8,7 @@
 
 'use strict';
 
-const { getChannelDefinition } = require('../channels/channel-definition-registry');
+const registry = require('../channels/channel-definition-registry');
 const { listLiveChannelTargetKeys, getChannelTarget } = require('../channels/channel-targets');
 const { profilesForCatalogRow } = require('../channels/channel-install-profiles');
 const { toSafeConfiguration, toPortalFields } = require('../channels/channel-configuration-map');
@@ -23,7 +23,14 @@ const {
 } = require('../channels/channel-install-inventory');
 const { listConnectedSystemsForInventory } = require('../channels/channel-inventory-fetch');
 const { cardinalityProjection } = require('../channels/channel-cardinality');
+const {
+  applyChannelStatusProjection,
+  normalizeChannelStatus
+} = require('../channels/channel-definition-status');
 const { httpError } = require('./channel-install-session');
+const { getExternalSystem } = require('../api/external-systems.api');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+const { isNotFoundError } = require('../channels/channel-instance-collision');
 
 /**
  * @param {Object} target
@@ -32,6 +39,7 @@ const { httpError } = require('./channel-install-session');
  */
 function toChannelCatalogRow(target, installations = []) {
   const summary = summarizeInstallations(installations);
+  const definition = registry.getChannelDefinition(target.key);
   const row = {
     key: target.key,
     displayLabel: target.displayLabel,
@@ -49,7 +57,10 @@ function toChannelCatalogRow(target, installations = []) {
   }
   return {
     ...row,
-    ...cardinalityProjection(getChannelDefinition(target.key), installations)
+    ...applyChannelStatusProjection(
+      normalizeChannelStatus(definition),
+      cardinalityProjection(definition, installations)
+    )
   };
 }
 
@@ -59,7 +70,7 @@ function toChannelCatalogRow(target, installations = []) {
  * @returns {Object}
  */
 function definitionListFields(definitionKey) {
-  const definition = getChannelDefinition(definitionKey);
+  const definition = registry.getChannelDefinition(definitionKey);
   if (!definition) {
     return {};
   }
@@ -99,8 +110,8 @@ async function listChannelTargets(query = {}, ctx = null, deps = {}) {
  * @returns {Object}
  */
 function requireChannelDefinition(definitionKey) {
-  const definition = getChannelDefinition(definitionKey);
-  if (!definition) {
+  const definition = registry.getChannelDefinition(definitionKey);
+  if (!definition || normalizeChannelStatus(definition) === 'hide') {
     throw httpError(`Unknown channel definition "${definitionKey}".`, 404);
   }
   return definition;
@@ -125,6 +136,7 @@ function toSafeDefinition(definition) {
       provisioning: channel.provisioning,
       runtimeTarget: channel.runtimeTarget,
       experimental: channel.experimental === true,
+      status: normalizeChannelStatus(definition),
       profiles: Array.isArray(channel.profiles) ? channel.profiles : []
     }
   };
@@ -153,11 +165,39 @@ async function getChannelDefinitionDetail(ctx, definitionKey, deps = {}) {
   const installations = installationsForDefinition(systems, definition.key);
   return {
     ...toSafeDefinition(definition),
-    ...cardinalityProjection(definition, installations),
+    ...applyChannelStatusProjection(
+      normalizeChannelStatus(definition),
+      cardinalityProjection(definition, installations)
+    ),
     installations
   };
 }
 
+/**
+ * @param {Object} ctx
+ * @param {string} definitionKey
+ * @param {string} systemKey
+ * @param {Object} [deps]
+ * @returns {Promise<Object>}
+ */
+async function installationFromDirectLookup(ctx, definitionKey, systemKey, deps) {
+  const getSystem = deps.getExternalSystem || getExternalSystem;
+  try {
+    const res = await getSystem(ctx.dataplaneUrl, systemKey, {
+      type: 'bearer',
+      token: ctx.bearerToken,
+      preserveBearer: true
+    });
+    const system = unwrapApiData(res);
+    return installationsForDefinition(system ? [system] : [], definitionKey)[0] || null;
+  } catch (err) {
+    if (isNotFoundError(err)) {
+      return null;
+    }
+    throw err;
+  }
+}
+
 /**
  * @param {Object} ctx
  * @param {string} definitionKey
@@ -168,8 +208,10 @@ async function getChannelDefinitionDetail(ctx, definitionKey, deps = {}) {
 async function getChannelInstallation(ctx, definitionKey, systemKey, deps = {}) {
   requireChannelDefinition(definitionKey);
   const systems = await listConnectedSystemsForInventory(ctx, deps);
-  const installations = installationsForDefinition(systems, definitionKey);
-  const found = installations.find((row) => row.key === systemKey);
+  const fromList = installationsForDefinition(systems, definitionKey).find(
+    (row) => row.key === systemKey
+  );
+  const found = fromList || (await installationFromDirectLookup(ctx, definitionKey, systemKey, deps));
   if (!found) {
     throw httpError(
       `Channel installation "${systemKey}" was not found for "${definitionKey}".`,

package/lib/programmatic/run-channel-install-options.js

@@ -56,9 +56,13 @@ function assertChannelInstallTarget(systemKey, body) {
   assertInstallProfile(systemKey, body || {});
   try {
     assertChannelTargetInstallable(systemKey, {
-      allowExperimental: body && body.allowExperimental === true
+      allowExperimental: body && body.allowExperimental === true,
+      continueInstall: body && body.continueInstall === true
     });
   } catch (err) {
+    if (err && err.statusCode === 403) {
+      throw httpError(err.message, 403);
+    }
     const live = listLiveChannelTargetKeys({
       allowExperimental: body && body.allowExperimental === true
     }).join(', ');

package/lib/programmatic/run-download.js

@@ -0,0 +1,41 @@
+/**
+ * Programmatic download wrapper — CLI download parity for builder-api.
+ *
+ * @fileoverview runDownload for POST /systems/:systemKey/download
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { downloadExternalSystem } = require('../external-system/download');
+const { runWithWorkspaceContext } = require('./workspace-context');
+const { mergeProgrammaticOptions } = require('./command-options');
+const { touchWorkspaceMeta } = require('./workspace-meta');
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [options]
+ * @param {boolean} [options.force]
+ * @param {boolean} [options.dryRun]
+ * @param {string} [options.format]
+ * @returns {Promise<Object>}
+ */
+async function runDownload(ctx, options = {}) {
+  const merged = mergeProgrammaticOptions(ctx, options);
+  return runWithWorkspaceContext(ctx, async() => {
+    await downloadExternalSystem(ctx.systemKey, merged);
+    if (!options.dryRun) {
+      touchWorkspaceMeta(ctx, { lastOperation: 'download' });
+    }
+    return {
+      downloaded: options.dryRun !== true,
+      dryRun: options.dryRun === true,
+      systemKey: ctx.systemKey
+    };
+  });
+}
+
+module.exports = {
+  runDownload
+};

package/lib/protection/auth-context.js

@@ -67,7 +67,9 @@ async function resolveCliProtectionDataplaneContext(options) {
     throw new Error('Authentication required. Run "aifabrix login" and try again.');
   }
 
-  const dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig);
+  const dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig, {
+    silent: options.json === true || options.silent === true
+  });
   return { environment, controllerUrl, dataplaneUrl, authConfig };
 }
 

package/lib/protection/protection-display.js

@@ -18,7 +18,7 @@ const {
   formatProgress,
   formatNextActions
 } = require('../utils/cli-test-layout-chalk');
-const { reportTaskRows } = require('./report-exit');
+const { reportTaskRows, isProtectionProblemResponse } = require('./report-exit');
 const { describeProtectionRoot } = require('./paths');
 const {
   appendTaskRows,
@@ -46,7 +46,8 @@ function formatProtectionValidateTTY(report, opts = {}) {
   const meta = report?.metadata || {};
   appendProtectionReportHeader(lines, meta);
   const summary = report?.summary || {};
-  const failCount = Number(summary.fail || 0);
+  const problem = isProtectionProblemResponse(report);
+  const failCount = problem ? Math.max(1, Number(summary.fail || 0)) : Number(summary.fail || 0);
   const warnCount = Number(summary.warn || 0);
   const aggregate = failCount > 0 ? 'fail' : warnCount > 0 ? 'warn' : 'ok';
   const glyph = aggregate === 'fail' ? '✖' : aggregate === 'warn' ? '⚠' : '✔';

package/lib/protection/report-exit.js

@@ -23,6 +23,51 @@ function reportTaskRows(report) {
   return [];
 }
 
+/**
+ * True when the payload is an RFC 7807 / API-client error, not a validate report.
+ * @param {*} report
+ * @returns {boolean}
+ */
+function isProtectionProblemResponse(report) {
+  if (!report || typeof report !== 'object') {
+    return false;
+  }
+  if (report.success === false) {
+    return true;
+  }
+  const status = Number(report.statusCode || report.status);
+  if (Number.isFinite(status) && status >= 400) {
+    return true;
+  }
+  const type = typeof report.type === 'string' ? report.type : '';
+  return type.includes('/Errors/') || type.includes('application/problem');
+}
+
+/**
+ * @param {*} uploaded
+ * @returns {string}
+ */
+function protectionUploadFailureMessage(uploaded) {
+  if (!uploaded || typeof uploaded !== 'object') {
+    return 'Protection upload returned empty response';
+  }
+  return (
+    uploaded.formattedError ||
+    uploaded.error ||
+    uploaded.detail ||
+    `Protection upload failed (HTTP ${uploaded.statusCode || uploaded.status || 0})`
+  );
+}
+
+/**
+ * @param {*} uploaded
+ */
+function assertProtectionUploadSucceeded(uploaded) {
+  if (!uploaded || typeof uploaded !== 'object' || isProtectionProblemResponse(uploaded)) {
+    throw new Error(protectionUploadFailureMessage(uploaded));
+  }
+}
+
 /**
  * @param {Object} report
  * @param {Object} [opts]
@@ -33,6 +78,9 @@ function exitCodeFromProtectionReport(report, opts = {}) {
   if (!report || typeof report !== 'object') {
     return 3;
   }
+  if (isProtectionProblemResponse(report)) {
+    return 1;
+  }
   const summary = report.summary || {};
   const failCount = Number(summary.fail || 0);
   const warnCount = Number(summary.warn || 0);
@@ -58,5 +106,7 @@ function exitCodeFromProtectionReport(report, opts = {}) {
 
 module.exports = {
   reportTaskRows,
+  isProtectionProblemResponse,
+  assertProtectionUploadSucceeded,
   exitCodeFromProtectionReport
 };

package/lib/protection/run-commands.js

@@ -18,6 +18,7 @@ const {
   deleteProtection,
   findProtectionKeyByDatasource
 } = require('../api/protection.api');
+const { assertProtectionUploadSucceeded } = require('./report-exit');
 const { preflightDatasourceReady } = require('./preflight-datasource-ready');
 const { runProtectionUploadDataSync } = require('./run-commands-upload-sync');
 const {
@@ -63,6 +64,7 @@ async function runProtectionUpload(datasourceKey, manifest, opts, logger) {
 
   logger.log(formatProgress('Uploading protection manifest...'));
   const uploaded = await uploadProtection(ctx.dataplaneUrl, ctx.authConfig, manifest);
+  assertProtectionUploadSucceeded(uploaded);
   logger.log(
     formatSuccessLine(
       `Protection for '${datasourceKey}' uploaded (deploymentId ${uploaded?.deploymentId || '—'}, revision ${uploaded?.revision ?? '—'})`