@aifabrix/builder 2.53.1 → 2.55.0

package/lib/channels/teams-bot-channel-add.js

@@ -0,0 +1,94 @@
+/**
+ * Teams Bot channel-add provisioning hook.
+ *
+ * @fileoverview Keep add-channel.js free of Teams Developer CLI argv
+ */
+
+'use strict';
+
+const { provisionTeamsBot, TEAMS_CLI_MISSING_REMAINING } = require('./microsoft-provisioning/teams-bot-provision');
+const { redactTeamsSecrets } = require('./microsoft-provisioning/errors');
+
+const FAIL_CLOSED_CODES = new Set(['WRONG_TENANT', 'TEAMS_MANAGED', 'SECRET', 'SCAFFOLD']);
+
+/**
+ * @param {Error} error
+ * @returns {string[]}
+ */
+function remainingFromError(error) {
+  const code = error && error.code;
+  if (code === 'TEAMS_CLI_MISSING') {
+    return TEAMS_CLI_MISSING_REMAINING;
+  }
+  if (code === 'MISSING_AZURE') {
+    return [
+      'Azure subscription and resource group were not found on the controller environment',
+      'Deploy the environment, then re-run aifabrix channel add teams-bot'
+    ];
+  }
+  if (code === 'ENDPOINT') {
+    return ['Use a public HTTPS dataplane URL for the Teams Bot messaging endpoint'];
+  }
+  const detail = redactTeamsSecrets(
+    (error && error.message) || 'Teams Bot provisioning failed'
+  );
+  return [detail];
+}
+
+/**
+ * @param {Error} error
+ * @returns {boolean}
+ */
+function shouldFailClosed(error) {
+  return FAIL_CLOSED_CODES.has(error && error.code);
+}
+
+/**
+ * @param {Error} error
+ * @returns {Object}
+ */
+function recoveryFromError(error) {
+  return {
+    connected: false,
+    skipped: true,
+    remaining: remainingFromError(error)
+  };
+}
+
+/**
+ * @param {Object} params
+ * @returns {Promise<Object|null>}
+ */
+async function maybeProvisionTeamsBotChannel(params) {
+  if (!params || params.channelTarget !== 'teams-bot') {
+    return null;
+  }
+  if (params.options && params.options.dryRun === true) {
+    return null;
+  }
+  const ctx = params.ctx || {};
+  const options = params.options || {};
+  const deps = options.teamsBotProvisioningDeps || {};
+  try {
+    return await provisionTeamsBot(
+      {
+        projectRoot: options.projectRoot || process.cwd(),
+        runtimeValues: params.runtimeValues,
+        ctx,
+        environment: ctx.environment,
+        options
+      },
+      deps
+    );
+  } catch (error) {
+    if (shouldFailClosed(error)) {
+      throw error;
+    }
+    return recoveryFromError(error);
+  }
+}
+
+module.exports = {
+  maybeProvisionTeamsBotChannel,
+  remainingFromError
+};

package/lib/channels/vendor-dataplane-url.js

@@ -0,0 +1,249 @@
+/**
+ * Vendor-facing dataplane and controller bases for channel webhooks and packages.
+ *
+ * @fileoverview Keep DATAPLANE_URL / MISO_CONTROLLER_URL internal for API calls
+ */
+
+'use strict';
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function trimBase(value) {
+  return String(value || '').trim().replace(/\/$/, '');
+}
+
+/**
+ * @param {string} host
+ * @returns {boolean}
+ */
+function isLoopbackHost(host) {
+  const hostname = String(host || '').toLowerCase();
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPublicHttpsUrl(value) {
+  const raw = trimBase(value);
+  if (!raw) {
+    return false;
+  }
+  try {
+    const parsed = new URL(raw);
+    if (parsed.protocol !== 'https:') {
+      return false;
+    }
+    const host = parsed.hostname.toLowerCase();
+    return Boolean(host) && !isLoopbackHost(host) && host.includes('.');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} internalUrl
+ * @returns {string}
+ */
+function pathVdir(internalUrl) {
+  try {
+    const pathName = new URL(internalUrl).pathname.replace(/\/$/, '');
+    return pathName && pathName !== '/' ? pathName : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * @param {string} origin
+ * @param {string} vdir
+ * @returns {string}
+ */
+function joinOriginAndVdir(origin, vdir) {
+  const base = trimBase(origin);
+  if (!base) {
+    return '';
+  }
+  if (!vdir) {
+    return base;
+  }
+  if (base.endsWith(vdir)) {
+    return base;
+  }
+  return `${base}${vdir.startsWith('/') ? vdir : `/${vdir}`}`;
+}
+
+/**
+ * Browser Origin / Referer that vendors can reach (portal host, not builder-api).
+ * @param {import('http').IncomingMessage|null|undefined} req
+ * @returns {string}
+ */
+function publicOriginFromRequest(req) {
+  const headers = (req && req.headers) || {};
+  const origin = trimBase(headers.origin);
+  if (isPublicHttpsUrl(origin)) {
+    return new URL(origin).origin;
+  }
+  try {
+    const referer = new URL(String(headers.referer || ''));
+    if (isPublicHttpsUrl(referer.origin)) {
+      return referer.origin;
+    }
+  } catch {
+    // ignore invalid Referer
+  }
+  return '';
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+function publicOriginFromAllowlist(env = process.env) {
+  for (const raw of String(env.ALLOWED_ORIGINS || '').split(',')) {
+    const candidate = trimBase(raw);
+    if (!candidate || candidate.includes('*')) {
+      continue;
+    }
+    try {
+      const parsed = new URL(candidate);
+      if (parsed.port && parsed.port !== '443') {
+        continue;
+      }
+      if (isPublicHttpsUrl(candidate)) {
+        return parsed.origin;
+      }
+    } catch {
+      // skip malformed allowlist entries
+    }
+  }
+  return '';
+}
+
+/**
+ * @param {string} [controllerUrl]
+ * @returns {string}
+ */
+function publicOriginFromController(controllerUrl) {
+  const raw = trimBase(controllerUrl);
+  if (!isPublicHttpsUrl(raw)) {
+    return '';
+  }
+  try {
+    return new URL(raw).origin;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * @param {string} [internalUrl]
+ * @param {string} envKey
+ * @param {NodeJS.ProcessEnv} env
+ * @param {{ publicOrigin?: string, siblingPublicUrl?: string, defaultVdir?: string }} extras
+ * @returns {string}
+ */
+function resolveVendorFacingBase(internalUrl, envKey, env, extras = {}) {
+  const internal = trimBase(internalUrl);
+  if (isPublicHttpsUrl(internal)) {
+    return internal;
+  }
+  const envUrl = trimBase(env[envKey]);
+  if (isPublicHttpsUrl(envUrl)) {
+    return envUrl;
+  }
+  const vdir = pathVdir(internal) || extras.defaultVdir || '';
+  const fromOrigin = joinOriginAndVdir(extras.publicOrigin, vdir);
+  if (isPublicHttpsUrl(fromOrigin)) {
+    return fromOrigin;
+  }
+  const fromAllow = joinOriginAndVdir(publicOriginFromAllowlist(env), vdir);
+  if (isPublicHttpsUrl(fromAllow)) {
+    return fromAllow;
+  }
+  const siblingOrigin = publicOriginFromController(extras.siblingPublicUrl);
+  const fromSibling = joinOriginAndVdir(siblingOrigin, vdir);
+  if (isPublicHttpsUrl(fromSibling)) {
+    return fromSibling;
+  }
+  return internal;
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string[]} keys
+ * @returns {string}
+ */
+function firstPublicEnvUrl(env, keys) {
+  for (const key of keys) {
+    const value = trimBase(env[key]);
+    if (isPublicHttpsUrl(value)) {
+      return value;
+    }
+  }
+  return '';
+}
+
+/**
+ * @param {string} [internalUrl]
+ * @param {{ publicOrigin?: string, env?: NodeJS.ProcessEnv, controllerUrl?: string }} [options]
+ * @returns {string}
+ */
+function resolveVendorFacingDataplaneUrl(internalUrl, options = {}) {
+  return resolveVendorFacingBase(internalUrl, 'DATAPLANE_PUBLIC_URL', options.env || process.env, {
+    publicOrigin: options.publicOrigin,
+    siblingPublicUrl: options.controllerUrl
+  });
+}
+
+/**
+ * @param {string} [internalUrl]
+ * @param {{ publicOrigin?: string, env?: NodeJS.ProcessEnv, dataplanePublicUrl?: string }} [options]
+ * @returns {string}
+ */
+function resolveVendorFacingControllerUrl(internalUrl, options = {}) {
+  const env = options.env || process.env;
+  const dedicated = firstPublicEnvUrl(env, [
+    'MISO_CONTROLLER_PUBLIC_URL',
+    'CONTROLLER_PUBLIC_URL'
+  ]);
+  if (dedicated) {
+    return dedicated;
+  }
+  return resolveVendorFacingBase(internalUrl, 'MISO_CONTROLLER_PUBLIC_URL', env, {
+    publicOrigin: options.publicOrigin,
+    siblingPublicUrl: options.dataplanePublicUrl
+  });
+}
+
+/**
+ * @param {Object|null|undefined} ctx
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ dataplaneBaseUrl: string, controllerUrl: string }}
+ */
+function vendorFacingUrlsFromCtx(ctx, env) {
+  const options = {
+    publicOrigin: ctx && ctx.publicOrigin,
+    controllerUrl: ctx && ctx.controllerUrl,
+    env: env || process.env
+  };
+  const dataplaneBaseUrl = resolveVendorFacingDataplaneUrl(ctx && ctx.dataplaneUrl, options);
+  const controllerUrl = resolveVendorFacingControllerUrl(ctx && ctx.controllerUrl, {
+    publicOrigin: options.publicOrigin,
+    env: options.env,
+    dataplanePublicUrl: dataplaneBaseUrl
+  });
+  return { dataplaneBaseUrl, controllerUrl };
+}
+
+module.exports = {
+  isPublicHttpsUrl,
+  publicOriginFromRequest,
+  publicOriginFromAllowlist,
+  resolveVendorFacingDataplaneUrl,
+  resolveVendorFacingControllerUrl,
+  vendorFacingUrlsFromCtx
+};

package/lib/cli/index.js

@@ -25,9 +25,11 @@ const { setupDimensionCommands } = require('../commands/dimension');
 const { setupResourceTypeCommands } = require('../commands/resource-type');
 const { setupRoleCommands } = require('../commands/role');
 const { setupRoleAssistantCommands } = require('../commands/role-assistant');
+const { setupSearchCommands } = require('../commands/search');
 const { setupEvidenceKindCommands } = require('../commands/evidence-kind');
 const { setupEnterpriseKnowledgeCommands } = require('../commands/enterprise-knowledge');
 const { setupIdentityCommands } = require('../commands/identity');
+const { setupAgentKitCommands } = require('../commands/agent-kit');
 const { setupProtectionCommands } = require('../commands/protection');
 const { setupEvidenceCommands } = require('../commands/evidence');
 const { setupCredentialDeploymentCommands } = require('./setup-credential-deployment');
@@ -80,9 +82,11 @@ function setupExtendedCliCommands(program) {
   setupResourceTypeCommands(program);
   setupRoleCommands(program);
   setupRoleAssistantCommands(program);
+  setupSearchCommands(program);
   setupEvidenceKindCommands(program);
   setupEnterpriseKnowledgeCommands(program);
   setupIdentityCommands(program);
+  setupAgentKitCommands(program);
   setupProtectionCommands(program);
   setupEvidenceCommands(program);
   setupUtilityCommands(program);

package/lib/cli/setup-certification-commands.js

@@ -20,7 +20,7 @@ function setupVerifyOperationsCommand(program) {
     .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
     .option('-v, --verbose', 'Readiness breakdown and verification step checklist')
     .option('-d, --debug', 'Write debug logs under integration/<systemKey>/logs/')
-    .option('--no-publish', 'Skip publishing local integration files before dataplane steps')
+    .option('--no-publish', 'Skip uploading local files (verify-operations does not upload by default)')
     .option(
       '--force',
       'With default sync, pass force to upload (same as aifabrix upload --force)'
@@ -39,7 +39,7 @@ function setupVerifyTrustCommand(program) {
     .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
     .option('-v, --verbose', 'Per-datasource breakdown')
     .option('-d, --debug', 'Write debug log under integration/<systemKey>/logs/')
-    .option('--no-publish', 'Skip publishing local integration files before validate')
+    .option('--no-publish', 'Skip uploading local files (verify-trust does not upload by default)')
     .option(
       '--force',
       'With default sync, pass force to upload (same as aifabrix upload --force)'

package/lib/cli/setup-certification.help.js

@@ -12,6 +12,8 @@ Examples:
 
 Notes:
   - Orchestrates validate → test → test-integration → test-e2e for the system.
+  - Does not upload. Upload is not publish; run aifabrix deploy to publish.
+  - Static custom packages (syncBridge disabled) skip live E2E (not FAILED).
   - Default output shows Operational Readiness % and OPERATIONS VERIFIED/FAILED only.
   - -v / --verbose adds readiness breakdown and verification step checklist at the end.
   - -v does not enable upload sidecar logs or inner E2E poll spinners (use aifabrix upload -v for upload detail).
@@ -28,7 +30,7 @@ Examples:
 Notes:
   - For one datasource: aifabrix datasource verify-trust <datasourceKey>
   - Does not call external vendor APIs (use verify-operations / test-e2e for connectivity).
-  - Local integration files are published before run unless --no-publish.
+  - Does not upload. Upload is not publish; run aifabrix deploy to publish.
 `;
 
 const VERIFY_GOVERNANCE_HELP_AFTER = `
@@ -78,6 +80,8 @@ Examples:
 
 Notes:
   - Expert path: pushes integration/<systemKey>/scenarios/*.yaml to the dataplane.
+  - Each file is stored on the datasource named by the filename (scenarios/<datasourceKey>.yaml).
+  - Search datasourceKeys in the YAML are what verification searches; they may differ for views (carrier storage datasource).
   - Packs must satisfy the 424.0 schema (spec.coverage, metadata.generationState). Use governance generate
     or verify-governance for dataplane-first packs.
 `;

package/lib/cli/setup-external-system-help.js

@@ -29,6 +29,7 @@ Notes:
   - --probe runs dataplane runtime checks after publish (slower).
   - --timeout sets publish budget in ms (HTTP client and dataplane); default 300000.
   - --env selects role-assistant.yaml section (dev|tst|pro) for digital workers; default dev.
+  - Role Assistant packages under role-assistant/ do not use application.yaml; upload applies settings and Evidence only.
   - test-e2e and test-integration publish local files first by default; use --no-publish on those commands to skip.
   - After dimension/FK edits on active datasources, use --force (or test-e2e / test-integration / datasource test-* with --sync --force).
   - For one datasource only: aifabrix datasource upload <datasourceKey>
@@ -45,6 +46,7 @@ Examples:
 
 Notes:
   - Requires login and a system that already exists on the dataplane.
+  - Omit --format to use the developer default from aifabrix dev set-format (else yaml).
   - Overwrite prompts apply when integration/<systemKey>/ already exists (--force for README).
 `;
 

package/lib/cli/setup-external-system.js

@@ -63,7 +63,7 @@ function setupDownloadCommand(program) {
   program.command('download <systemKey>')
     .description('Pull external system from dataplane into integration/<key>/')
     .addHelpText('after', DOWNLOAD_HELP_AFTER)
-    .option('--format <format>', 'Output format: json | yaml (default: yaml or config format)')
+    .option('--format <format>', 'Output format: json | yaml (default: aifabrix dev set-format, else yaml)')
     .option('--dry-run', 'Show what would be downloaded without actually downloading')
     .option('--force', 'Overwrite existing README.md without prompting')
     .option(

package/lib/commands/agent-kit-help.js

@@ -0,0 +1,79 @@
+/**
+ * Help text for `aifabrix agent-kit` leaves.
+ * @fileoverview Per-command examples so update -h is not install-centric
+ */
+
+'use strict';
+
+const GROUP_HELP = `
+Examples:
+  $ aifabrix agent-kit init cust-demo --host all --approve-all --yes
+  $ aifabrix agent-kit install --host all --approve-all --yes
+  $ aifabrix agent-kit update --host all --approve-all --yes
+  $ aifabrix agent-kit status
+  $ aifabrix agent-kit validate
+`;
+
+const INSTALL_HELP = `
+Examples:
+  $ aifabrix agent-kit install
+  $ aifabrix agent-kit install --host all --approve-all --yes
+  $ aifabrix agent-kit install --host claude --approve-all --yes
+  $ aifabrix agent-kit install --skip-approve-all
+  $ aifabrix agent-kit install --dry-run
+
+TTY asks to auto-approve Claude Code and Codex permissions (default yes). Silent: --approve-all --yes. Skip: --skip-approve-all.
+`;
+
+const STATUS_HELP = `
+Examples:
+  $ aifabrix agent-kit status
+  $ aifabrix agent-kit status --json
+`;
+
+const UPDATE_HELP = `
+Examples:
+  $ aifabrix agent-kit update
+  $ aifabrix agent-kit update --host all --approve-all --yes
+  $ aifabrix agent-kit update --host claude --force
+  $ aifabrix agent-kit update --dry-run
+
+Omit --host to keep the coding hosts already recorded. Pass --host when you add or switch Cursor, Claude Code, or Codex.
+`;
+
+const VALIDATE_HELP = `
+Examples:
+  $ aifabrix agent-kit validate
+  $ aifabrix agent-kit validate --json
+`;
+
+const INIT_HELP = `
+Examples:
+  $ aifabrix agent-kit init cust-demo
+  $ aifabrix agent-kit init cust-demo --host all --approve-all --yes
+  $ aifabrix agent-kit init cust-demo --host all --remote --org my-org --yes
+  $ aifabrix agent-kit init ./path/to/cust-demo --dry-run --json
+
+Interactive (TTY): omit --host / --yes to be prompted.
+Silent local: --host all --approve-all --yes
+Silent remote: --host all --remote --org <owner> --yes
+`;
+
+const REMOTE_HELP = `
+Examples:
+  $ cd cust-demo && aifabrix agent-kit remote create
+  $ aifabrix agent-kit remote create --org my-org --yes
+  $ aifabrix agent-kit remote create --org my-org --dry-run --json
+
+Interactive (TTY): omit flags to be prompted. Silent: --org <owner> --yes
+`;
+
+module.exports = {
+  GROUP_HELP,
+  INSTALL_HELP,
+  STATUS_HELP,
+  UPDATE_HELP,
+  VALIDATE_HELP,
+  INIT_HELP,
+  REMOTE_HELP
+};