@aifabrix/builder 2.54.1 → 2.55.0

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 ?? '—'})`

package/lib/role-assistant/package-validate.js

@@ -0,0 +1,175 @@
+/**
+ * Role Assistant package folder validation (settings, tests, evidence, knowledge).
+ * @fileoverview Walk ra-* governed files. Ignore leftover Connected System artifacts.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { validateExternalFile, parseJsonFileContent } = require('../validation/validate-external-file');
+const { listTestCaseFiles } = require('./test-cases');
+const { validateTestCaseFile } = require('./test-case-validate');
+
+const SETTINGS_TYPE = 'role-assistant-settings';
+const EMPTY_TESTS_SKIP = 'tests/: skipped (no test cases)';
+
+function fileRow(filePath, type, result) {
+  return {
+    file: path.basename(filePath),
+    type,
+    valid: result.valid,
+    path: filePath,
+    errors: result.errors || [],
+    warnings: result.warnings || []
+  };
+}
+
+function listFilesByExt(dirPath, ext, acc) {
+  if (!fs.existsSync(dirPath)) {
+    return acc;
+  }
+  for (const name of fs.readdirSync(dirPath)) {
+    if (String(name).startsWith('.')) {
+      continue;
+    }
+    const full = path.join(dirPath, name);
+    const st = fs.statSync(full);
+    if (st.isDirectory()) {
+      listFilesByExt(full, ext, acc);
+    } else if (String(name).toLowerCase().endsWith(ext)) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+function evidenceRows(parsed) {
+  if (Array.isArray(parsed)) {
+    return parsed;
+  }
+  if (parsed && typeof parsed === 'object') {
+    return [parsed];
+  }
+  return null;
+}
+
+function validateEvidenceJsonFile(filePath) {
+  const parseResult = parseJsonFileContent(filePath);
+  if (parseResult.error) {
+    return { ...parseResult.error, file: filePath, type: 'evidence' };
+  }
+  const rows = evidenceRows(parseResult.parsed);
+  const errors = [];
+  if (!rows) {
+    errors.push(`${filePath}: Evidence JSON must be an object or array of objects`);
+  } else {
+    rows.forEach((row, index) => {
+      const key = row && typeof row === 'object' && !Array.isArray(row) ? String(row.key || '').trim() : '';
+      if (!key) {
+        errors.push(`${filePath}: item ${index} is missing key`);
+      }
+    });
+  }
+  return { valid: errors.length === 0, errors, warnings: [], file: filePath, type: 'evidence' };
+}
+
+function validateKnowledgeMarkdown(filePath) {
+  const text = fs.readFileSync(filePath, 'utf8');
+  if (!String(text).trim()) {
+    return {
+      valid: false,
+      errors: [`${filePath}: knowledge markdown must not be empty`],
+      warnings: [],
+      file: filePath,
+      type: 'knowledge'
+    };
+  }
+  return { valid: true, errors: [], warnings: [], file: filePath, type: 'knowledge' };
+}
+
+async function validateSettingsFile(appPath) {
+  const yamlPath = path.join(appPath, 'role-assistant.yaml');
+  try {
+    const result = await validateExternalFile(yamlPath, SETTINGS_TYPE);
+    return fileRow(yamlPath, SETTINGS_TYPE, result);
+  } catch (error) {
+    return fileRow(yamlPath, SETTINGS_TYPE, {
+      valid: false,
+      errors: [error.message],
+      warnings: []
+    });
+  }
+}
+
+function collectDuplicateCaseIdErrors(caseFiles) {
+  const seen = new Map();
+  const errors = [];
+  for (const row of caseFiles) {
+    const parseResult = parseJsonFileContent(row.path);
+    const caseId = parseResult.parsed && String(parseResult.parsed.caseId || '').trim();
+    if (!caseId) {
+      continue;
+    }
+    if (seen.has(caseId)) {
+      errors.push(`${row.path}: duplicate caseId "${caseId}" (also ${seen.get(caseId)})`);
+    } else {
+      seen.set(caseId, row.path);
+    }
+  }
+  return errors;
+}
+
+function validateTestFiles(appPath) {
+  const testsDir = path.join(appPath, 'tests');
+  const yamlFiles = listTestCaseFiles(testsDir);
+  if (yamlFiles.length === 0) {
+    return { files: [], errors: [], warnings: [EMPTY_TESTS_SKIP] };
+  }
+  const files = yamlFiles.map((filePath) => fileRow(filePath, 'role-assistant-test-case', validateTestCaseFile(filePath)));
+  const errors = files.flatMap((row) => row.errors);
+  errors.push(...collectDuplicateCaseIdErrors(files));
+  return { files, errors, warnings: [] };
+}
+
+function validateEvidenceFiles(appPath) {
+  const jsonFiles = listFilesByExt(path.join(appPath, 'evidence'), '.json', []);
+  const files = jsonFiles.map((filePath) => fileRow(filePath, 'evidence', validateEvidenceJsonFile(filePath)));
+  return { files, errors: files.flatMap((row) => row.errors), warnings: [] };
+}
+
+function validateKnowledgeFiles(appPath) {
+  const mdFiles = listFilesByExt(path.join(appPath, 'knowledge'), '.md', []).filter((filePath) => {
+    return path.dirname(filePath) === path.join(appPath, 'knowledge');
+  });
+  const files = mdFiles.map((filePath) => fileRow(filePath, 'knowledge', validateKnowledgeMarkdown(filePath)));
+  return { files, errors: files.flatMap((row) => row.errors), warnings: [] };
+}
+
+async function validateRoleAssistantPackage(appPath) {
+  const settings = await validateSettingsFile(appPath);
+  const tests = validateTestFiles(appPath);
+  const evidence = validateEvidenceFiles(appPath);
+  const knowledge = validateKnowledgeFiles(appPath);
+  const files = [settings, ...tests.files, ...evidence.files, ...knowledge.files];
+  const errors = [
+    ...settings.errors,
+    ...tests.errors,
+    ...evidence.errors,
+    ...knowledge.errors
+  ];
+  const warnings = [...settings.warnings, ...tests.warnings, ...evidence.warnings, ...knowledge.warnings];
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    files
+  };
+}
+
+module.exports = {
+  EMPTY_TESTS_SKIP,
+  validateRoleAssistantPackage,
+  validateEvidenceJsonFile,
+  validateKnowledgeMarkdown
+};

package/lib/role-assistant/test-case-assertion-row.js

@@ -0,0 +1,36 @@
+/**
+ * Shared assertion row helpers (pass/fail/warn/notes/skip).
+ * @fileoverview Kind flags for Role Assistant test result rows
+ */
+
+'use strict';
+
+function skipRow(id, message) {
+  return { id, passed: true, skip: true, kind: 'skip', message };
+}
+
+function notesRow(id, message) {
+  return { id, passed: true, notes: true, kind: 'notes', message };
+}
+
+function withKind(row) {
+  if (!row || row.kind) {
+    return row;
+  }
+  if (row.notes === true) {
+    return { ...row, kind: 'notes' };
+  }
+  if (row.skip === true) {
+    return { ...row, kind: 'skip' };
+  }
+  if (row.warn === true) {
+    return { ...row, kind: 'warn' };
+  }
+  return { ...row, kind: row.passed ? 'pass' : 'fail' };
+}
+
+module.exports = {
+  skipRow,
+  notesRow,
+  withKind
+};