@aifabrix/builder 2.50.0 → 2.51.1

package/lib/role-assistant/evidence-sync.js

@@ -0,0 +1,450 @@
+/**
+ * Role Assistant evidence import/export for dataplane evidence lifecycle.
+ *
+ * @fileoverview Sync local role-assistant evidence rows with dataplane evidence APIs
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const yaml = require('js-yaml');
+const logger = require('../utils/logger');
+const { formatSuccessLine, formatWarningLine, metadata } = require('../utils/cli-test-layout-chalk');
+const {
+  listEvidence,
+  loadEvidenceBulk,
+  validateEvidenceCandidate,
+  certifyEvidenceCandidate,
+  activateEvidenceCandidate
+} = require('../api/evidence.api');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
+const { SYSTEM_KIND_DIGITAL_WORKER } = require('./settings');
+
+const EVIDENCE_DIR_NAME = 'evidence';
+const EVIDENCE_EXPORT_FILE = 'evidence.json';
+const VALIDATION_FAILED = 'failed';
+const VALIDATION_PASSED = 'passed';
+
+const EVIDENCE_MUTABLE_KEYS = [
+  'key',
+  'resourceType',
+  'roleKey',
+  'kindKey',
+  'kindVersion',
+  'aspect',
+  'knowledgeType',
+  'originalLanguage',
+  'structuredContent',
+  'title',
+  'description',
+  'when',
+  'expectedBehavior',
+  'order',
+  'status',
+  'generationConfidence',
+  'suggestionExplanation',
+  'contributionOverrides',
+  'approval'
+];
+
+/** Read-only projections exported for Builder visibility (ignored on load). */
+const EVIDENCE_EXPORT_PROJECTION_KEYS = [
+  'valueProposal',
+  'contributionProjection',
+  'fingerprint',
+  'provenanceSummary',
+  'trustProjections'
+];
+
+function resolveSystemNode(input) {
+  if (!input || typeof input !== 'object') {
+    return null;
+  }
+  return input.system || input.application || null;
+}
+
+function isDigitalWorkerModel(input) {
+  const systemNode = resolveSystemNode(input);
+  if (!systemNode || typeof systemNode.systemKind !== 'string') {
+    return false;
+  }
+  return systemNode.systemKind.trim() === SYSTEM_KIND_DIGITAL_WORKER;
+}
+
+function isEvidenceFileName(fileName) {
+  const lower = String(fileName || '').toLowerCase();
+  return lower.endsWith('.json') || lower.endsWith('.yaml') || lower.endsWith('.yml');
+}
+
+function collectEvidenceFiles(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    return [];
+  }
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectEvidenceFiles(fullPath));
+      continue;
+    }
+    if (isEvidenceFileName(entry.name)) {
+      files.push(fullPath);
+    }
+  }
+  return files.sort();
+}
+
+function parseEvidenceFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  if (filePath.toLowerCase().endsWith('.json')) {
+    return JSON.parse(raw);
+  }
+  return yaml.load(raw);
+}
+
+function extractEvidenceRows(payload) {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+  if (!payload || typeof payload !== 'object') {
+    return [];
+  }
+  if (Array.isArray(payload.data)) {
+    return payload.data;
+  }
+  if (Array.isArray(payload.rows)) {
+    return payload.rows;
+  }
+  if (Array.isArray(payload.evidence)) {
+    return payload.evidence;
+  }
+  return [payload];
+}
+
+function sanitizeEvidenceRow(row, systemKey, options = {}) {
+  const includeProjections = options.includeProjections === true;
+  const out = {};
+  const keys = includeProjections
+    ? [...EVIDENCE_MUTABLE_KEYS, ...EVIDENCE_EXPORT_PROJECTION_KEYS]
+    : EVIDENCE_MUTABLE_KEYS;
+  for (const key of keys) {
+    if (typeof row[key] !== 'undefined') {
+      out[key] = row[key];
+    }
+  }
+  if (typeof out.roleKey !== 'string' || !out.roleKey.trim()) {
+    out.roleKey = systemKey;
+  }
+  // Import path: clients cannot load status=active; lifecycle activates after certify.
+  if (!includeProjections) {
+    out.status = 'candidate';
+  }
+  if (!out.title || !out.when || !out.expectedBehavior) {
+    return null;
+  }
+  return out;
+}
+
+function loadEvidenceRowsFromFolder(evidencePath, systemKey) {
+  const files = collectEvidenceFiles(evidencePath);
+  const rows = [];
+  for (const filePath of files) {
+    const parsed = parseEvidenceFile(filePath);
+    const extractedRows = extractEvidenceRows(parsed);
+    for (const row of extractedRows) {
+      if (!row || typeof row !== 'object' || Array.isArray(row)) {
+        continue;
+      }
+      const normalized = sanitizeEvidenceRow(row, systemKey);
+      if (!normalized) {
+        const shortName = path.relative(evidencePath, filePath);
+        throw new Error(
+          `Evidence row in ${shortName} is missing required fields title/when/expectedBehavior.`
+        );
+      }
+      rows.push(normalized);
+    }
+  }
+  return { files, rows };
+}
+
+function resolveEvidenceDirectory(systemKey, pathOptions = {}) {
+  const appPath = resolveExternalSystemPath(systemKey, pathOptions);
+  return path.join(appPath, EVIDENCE_DIR_NAME);
+}
+
+function normalizeEvidenceRef(row) {
+  if (!row || typeof row !== 'object') {
+    return '';
+  }
+  const candidates = [row.id, row.key];
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  return '';
+}
+
+function toMatchKey(row) {
+  return `${String(row.title || '').trim()}|${String(row.when || '').trim()}|${String(row.expectedBehavior || '').trim()}`;
+}
+
+function dedupeRefs(refs) {
+  const out = [];
+  const seen = new Set();
+  for (const ref of refs) {
+    if (!ref || seen.has(ref)) {
+      continue;
+    }
+    seen.add(ref);
+    out.push(ref);
+  }
+  return out;
+}
+
+function resolveRefsFromLoadedRows(rows) {
+  return dedupeRefs((rows || []).map((row) => normalizeEvidenceRef(row)).filter(Boolean));
+}
+
+function buildRoleEvidenceIndex(rows) {
+  const byKey = new Map();
+  for (const row of rows || []) {
+    if (!row || typeof row !== 'object') {
+      continue;
+    }
+    const ref = normalizeEvidenceRef(row);
+    if (!ref) {
+      continue;
+    }
+    const matchKey = toMatchKey(row);
+    if (matchKey !== '||' && !byKey.has(matchKey)) {
+      byKey.set(matchKey, ref);
+    }
+  }
+  return byKey;
+}
+
+async function resolveEvidenceLifecycleRefs(dataplaneUrl, authConfig, systemKey, loadedRows, preparedRows) {
+  const refs = resolveRefsFromLoadedRows(loadedRows);
+  if (refs.length >= preparedRows.length || preparedRows.length === 0) {
+    return refs;
+  }
+  const roleRows = await listEvidence(dataplaneUrl, authConfig, { roleKey: systemKey });
+  const roleByKey = buildRoleEvidenceIndex(roleRows);
+  for (const row of preparedRows) {
+    const matchRef = roleByKey.get(toMatchKey(row));
+    if (matchRef) {
+      refs.push(matchRef);
+    }
+  }
+  return dedupeRefs(refs);
+}
+
+function validationFailed(validationResponse) {
+  const status = String(validationResponse?.status || '').trim().toLowerCase();
+  return status === VALIDATION_FAILED;
+}
+
+function isActivatedEvidenceRow(row) {
+  const status = String(row?.status || '').trim().toLowerCase();
+  return !status || status === 'active';
+}
+
+async function runEvidenceLifecycleForRef(dataplaneUrl, authConfig, evidenceRef) {
+  const validation = await validateEvidenceCandidate(dataplaneUrl, authConfig, evidenceRef);
+  if (validationFailed(validation)) {
+    const issues = Array.isArray(validation?.issues) ? validation.issues.length : 0;
+    throw new Error(`Validation failed for evidence ${evidenceRef} (${issues} issue${issues === 1 ? '' : 's'}).`);
+  }
+  if (String(validation?.status || '').trim().toLowerCase() !== VALIDATION_PASSED) {
+    throw new Error(`Validation status for evidence ${evidenceRef} is "${validation?.status || 'unknown'}".`);
+  }
+  await certifyEvidenceCandidate(dataplaneUrl, authConfig, evidenceRef, {});
+  const activated = await activateEvidenceCandidate(dataplaneUrl, authConfig, evidenceRef);
+  if (!isActivatedEvidenceRow(activated)) {
+    throw new Error(`Evidence ${evidenceRef} did not become active after activation.`);
+  }
+}
+
+function buildFailureSummary(failures) {
+  const preview = failures.slice(0, 3).join('; ');
+  const more = failures.length > 3 ? ` (and ${failures.length - 3} more)` : '';
+  return `${preview}${more}`;
+}
+
+function buildEvidenceDryRunSummary(evidencePath, files, rows) {
+  return {
+    skipped: false,
+    dryRun: true,
+    evidencePath,
+    filesDiscovered: files.length,
+    discovered: rows.length
+  };
+}
+
+function buildEvidenceImportSummary(evidencePath, files, rows, loadResult) {
+  return {
+    skipped: false,
+    evidencePath,
+    filesDiscovered: files.length,
+    discovered: rows.length,
+    loaded: Number(loadResult.inserted || 0) + Number(loadResult.updated || 0),
+    validated: 0,
+    certified: 0,
+    productionReady: 0,
+    failed: 0
+  };
+}
+
+async function loadEvidenceAndResolveRefs(dataplaneUrl, authConfig, systemKey, rows) {
+  const loadResult = await loadEvidenceBulk(dataplaneUrl, authConfig, rows, {});
+  const refs = await resolveEvidenceLifecycleRefs(dataplaneUrl, authConfig, systemKey, loadResult.data, rows);
+  return { loadResult, refs };
+}
+
+async function runEvidenceLifecycleBatch(dataplaneUrl, authConfig, refs, summary) {
+  const failures = [];
+  for (const evidenceRef of refs) {
+    try {
+      await runEvidenceLifecycleForRef(dataplaneUrl, authConfig, evidenceRef);
+      summary.validated += 1;
+      summary.certified += 1;
+      summary.productionReady += 1;
+    } catch (error) {
+      summary.failed += 1;
+      failures.push(error.message || String(error));
+    }
+  }
+  return failures;
+}
+
+function appendUnresolvedEvidenceFailures(summary, failures, refCount, rowCount) {
+  if (refCount >= rowCount) {
+    return;
+  }
+  const unresolved = rowCount - refCount;
+  summary.failed += unresolved;
+  failures.push(`Could not resolve ${unresolved} evidence row(s) to dataplane ids after load.`);
+}
+
+function throwWhenEvidenceLifecycleFailed(summary, failures) {
+  if (summary.failed === 0) {
+    return;
+  }
+  const err = new Error(`Role assistant evidence lifecycle failed: ${buildFailureSummary(failures)}`);
+  err.evidenceSummary = summary;
+  throw err;
+}
+
+async function importRoleAssistantEvidence(params) {
+  const { systemKey, dataplaneUrl, authConfig, model, pathOptions = {}, dryRun = false } = params;
+  if (!isDigitalWorkerModel(model)) {
+    return { skipped: true, reason: 'not-role-assistant' };
+  }
+  const evidencePath = resolveEvidenceDirectory(systemKey, pathOptions);
+  const { files, rows } = loadEvidenceRowsFromFolder(evidencePath, systemKey);
+  if (rows.length === 0) {
+    return { skipped: true, reason: 'no-evidence-files', evidencePath };
+  }
+  if (dryRun) {
+    return buildEvidenceDryRunSummary(evidencePath, files, rows);
+  }
+  const { loadResult, refs } = await loadEvidenceAndResolveRefs(
+    dataplaneUrl,
+    authConfig,
+    systemKey,
+    rows
+  );
+  const summary = buildEvidenceImportSummary(evidencePath, files, rows, loadResult);
+  const failures = await runEvidenceLifecycleBatch(dataplaneUrl, authConfig, refs, summary);
+  appendUnresolvedEvidenceFailures(summary, failures, refs.length, rows.length);
+  throwWhenEvidenceLifecycleFailed(summary, failures);
+  return summary;
+}
+
+function sortEvidenceRows(rows) {
+  return [...rows].sort((left, right) => {
+    const titleCmp = String(left.title || '').localeCompare(String(right.title || ''));
+    if (titleCmp !== 0) {
+      return titleCmp;
+    }
+    return Number(left.order || 0) - Number(right.order || 0);
+  });
+}
+
+async function exportRoleAssistantEvidence(params) {
+  const { systemKey, dataplaneUrl, authConfig, manifest, pathOptions = {} } = params;
+  const model = { system: manifest?.application, dataSources: manifest?.dataSources || [] };
+  if (!isDigitalWorkerModel(model)) {
+    return { skipped: true, reason: 'not-role-assistant' };
+  }
+  const rows = await listEvidence(dataplaneUrl, authConfig, { roleKey: systemKey });
+  const normalized = sortEvidenceRows(
+    rows
+      .map((row) => sanitizeEvidenceRow(row, systemKey, { includeProjections: true }))
+      .filter(Boolean)
+  );
+  if (normalized.length === 0) {
+    return { skipped: true, reason: 'no-evidence-rows' };
+  }
+  const evidencePath = resolveEvidenceDirectory(systemKey, pathOptions);
+  fs.mkdirSync(evidencePath, { recursive: true });
+  const outPath = path.join(evidencePath, EVIDENCE_EXPORT_FILE);
+  fs.writeFileSync(outPath, `${JSON.stringify(normalized, null, 2)}\n`, 'utf8');
+  return {
+    skipped: false,
+    count: normalized.length,
+    evidencePath,
+    filePath: outPath
+  };
+}
+
+function logRoleAssistantEvidenceImportSummary(systemKey, result, options = {}) {
+  if (result.skipped) {
+    if (options.verbose === true) {
+      logger.log(metadata(`Role assistant evidence skipped (${systemKey}): ${result.reason}`));
+    }
+    return;
+  }
+  if (result.dryRun) {
+    logger.log(
+      formatWarningLine(
+        `Role assistant evidence dry-run: ${result.discovered} row(s) from ${result.filesDiscovered} file(s).`
+      )
+    );
+    return;
+  }
+  logger.log(
+    formatSuccessLine(
+      `Role assistant evidence applied: discovered ${result.discovered}, loaded ${result.loaded}, `
+        + `validated ${result.validated}, certified ${result.certified}, production-ready ${result.productionReady}.`
+    )
+  );
+}
+
+function logRoleAssistantEvidenceExportSummary(systemKey, result, options = {}) {
+  if (result.skipped) {
+    if (options.verbose === true) {
+      logger.log(metadata(`Role assistant evidence export skipped (${systemKey}): ${result.reason}`));
+    }
+    return;
+  }
+  logger.log(
+    formatSuccessLine(
+      `Role assistant evidence exported (${systemKey}): ${result.count} row(s) to ${result.filePath}.`
+    )
+  );
+}
+
+module.exports = {
+  isDigitalWorkerModel,
+  importRoleAssistantEvidence,
+  exportRoleAssistantEvidence,
+  logRoleAssistantEvidenceImportSummary,
+  logRoleAssistantEvidenceExportSummary
+};

package/lib/role-assistant/github-workflow.js

@@ -0,0 +1,96 @@
+/**
+ * Role Assistant GitHub workflow scaffolding.
+ *
+ * @fileoverview Generates a promotion workflow for role-assistant packages
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fsSync = require('../internal/fs-real-sync');
+const path = require('path');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
+
+const WORKFLOW_FILE_NAME = 'role-assistant-promote.yml';
+
+function buildRoleAssistantWorkflowContent(systemKey) {
+  return `name: Role Assistant Promotion
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: "Target environment"
+        required: true
+        type: choice
+        options:
+          - dev
+          - tst
+          - pro
+        default: dev
+
+jobs:
+  promote:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install AI Fabrix Builder
+        run: npm install -g @aifabrix/builder
+
+      - name: Login to AI Fabrix
+        run: |
+          set -e
+          aifabrix login \\
+            --method credentials \\
+            --app ${systemKey} \\
+            --client-id \${{ secrets.AIFABRIX_CLIENT_ID }} \\
+            --client-secret \${{ secrets.AIFABRIX_CLIENT_SECRET }} \\
+            --controller \${{ secrets.AIFABRIX_CONTROLLER_URL }} \\
+            --environment \${{ inputs.environment }}
+
+      - name: Validate role assistant package
+        run: |
+          set -e
+          aifabrix validate ${systemKey}
+
+      - name: Upload role assistant package
+        run: |
+          set -e
+          aifabrix upload ${systemKey} --env \${{ inputs.environment }}
+
+      - name: Run role assistant lifecycle test
+        run: |
+          set -e
+          aifabrix role-assistant test ${systemKey} --env \${{ inputs.environment }} --json
+`;
+}
+
+function resolveRoleAssistantWorkflowPath(systemKey, options = {}) {
+  const rootDir = options.roleAssistantPath || resolveExternalSystemPath(systemKey, options.pathOptions || {});
+  return path.join(rootDir, '.github', 'workflows', WORKFLOW_FILE_NAME);
+}
+
+async function ensureRoleAssistantGithubWorkflow(systemKey, options = {}) {
+  const workflowPath = resolveRoleAssistantWorkflowPath(systemKey, options);
+  if (!options.force && fsSync.existsSync(workflowPath)) {
+    return { created: false, workflowPath, reason: 'already-exists' };
+  }
+  fsSync.mkdirSync(path.dirname(workflowPath), { recursive: true });
+  fsSync.writeFileSync(workflowPath, buildRoleAssistantWorkflowContent(systemKey), 'utf8');
+  return { created: true, workflowPath };
+}
+
+module.exports = {
+  WORKFLOW_FILE_NAME,
+  buildRoleAssistantWorkflowContent,
+  resolveRoleAssistantWorkflowPath,
+  ensureRoleAssistantGithubWorkflow
+};