@aifabrix/builder 2.53.1 → 2.55.0

package/lib/channels/channel-install-envelope.js

@@ -0,0 +1,358 @@
+/**
+ * ChannelInstallEnvelope for CLI --json and MCP (not default HTTP).
+ *
+ * @fileoverview remainingSpec + verdicts → typed envelope
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { CHANNEL_TARGETS } = require('./channel-targets');
+const { remainingSpec, CHATGPT_REMAINING_STEPS, SLACK_APPS_URL } = require('./channel-add-remaining');
+const { buildChatGptFormValues, CHATGPT_APPS_CREATE_URL } = require('./chatgpt-setup-values');
+const {
+  buildClaudeFormValues,
+  CLAUDE_CONNECTORS_URL
+} = require('./claude-setup-values');
+const { CLAUDE_REMAINING_STEPS } = require('./claude-runtime-contract');
+const { DEVELOPER_PORTAL_APPS_URL } = require('./approval-guides/microsoft-copilot');
+const {
+  userAction,
+  openUrlAction,
+  copyValueAction,
+  remainingStepAction
+} = require('./channel-install-envelope-actions');
+const {
+  copilotVaultMissing,
+  microsoftLoginWaiting,
+  microsoftExtraActions,
+  teamsBotWaiting
+} = require('./channel-install-envelope-microsoft');
+
+/**
+ * @param {string} systemKey
+ * @param {string} artifactId
+ * @returns {string}
+ */
+function channelArtifactHref(systemKey, artifactId) {
+  return `/api/v1/builder/systems/${systemKey}/channels/artifacts/${artifactId}`;
+}
+
+/**
+ * @param {Object} params
+ * @returns {Object|null}
+ */
+function retryLoginAction(params) {
+  if (params.channelTarget === 'slack' && params.ctx && params.ctx.slackConnected === true) {
+    return null;
+  }
+  if (params.channelTarget === 'teams-bot' && !teamsBotWaiting(params)) {
+    return null;
+  }
+  return userAction({
+    id: 'retry-login',
+    kind: 'retryLogin',
+    label: microsoftLoginWaiting(params) ? 'Get a new code' : 'Refresh login',
+    required: false
+  });
+}
+
+/**
+ * @param {Object} params
+ * @param {Object[]} actions
+ * @param {boolean} runtimeOk
+ * @returns {Object[]}
+ */
+function withRetryLogin(params, actions, runtimeOk) {
+  if (!runtimeOk) {
+    return actions;
+  }
+  const retry = retryLoginAction(params);
+  return retry ? [...actions, retry] : actions;
+}
+
+/**
+ * @param {Object} spec
+ * @returns {Object[]}
+ */
+function actionsFromRemainingSpec(spec) {
+  const actions = [];
+  const required = spec.handoffRequired;
+  if (typeof spec.downloadHref === 'string' && spec.downloadHref.trim()) {
+    actions.push(userAction({
+      id: 'download-app-package',
+      kind: 'downloadArtifact',
+      label: spec.downloadHeading || 'Download app package',
+      required,
+      extra: { href: spec.downloadHref.trim() }
+    }));
+  }
+  const open = openUrlAction(spec.openUrl, spec.openHeading || 'Open', 'open-vendor', required);
+  if (open) {
+    actions.push(open);
+  }
+  const activate = openUrlAction(
+    spec.activateUrl,
+    spec.activateHeading || 'Activate',
+    'activate',
+    required
+  );
+  if (activate) {
+    actions.push(activate);
+  }
+  const admin = openUrlAction(spec.adminUrl, spec.adminHeading || 'Open admin', 'open-admin', required);
+  if (admin) {
+    actions.push(admin);
+  }
+  const auth = openUrlAction(spec.authUrl, spec.authHeading || 'Authentication', 'open-auth');
+  if (auth) {
+    actions.push(auth);
+  }
+  return actions;
+}
+
+function remainingStepActions(steps) {
+  if (!Array.isArray(steps)) {
+    return [];
+  }
+  return steps
+    .filter((step) => typeof step === 'string' && step.trim())
+    .map((step, index) => remainingStepAction(step.trim(), `remaining-${index + 1}`));
+}
+
+function chatgptCopyActions(runtimeValues) {
+  const values = buildChatGptFormValues({ runtimeValues: runtimeValues || {} });
+  return [
+    copyValueAction('Name', values.name, 'copy-name'),
+    copyValueAction('Description', values.description, 'copy-description'),
+    copyValueAction('Server URL', values.serverUrl, 'copy-server-url'),
+    copyValueAction('Authentication', values.authentication, 'copy-authentication')
+  ].filter(Boolean);
+}
+
+function claudeCopyActions(runtimeValues) {
+  const values = buildClaudeFormValues({ runtimeValues: runtimeValues || {} });
+  return [
+    copyValueAction('Name', values.name, 'copy-name'),
+    copyValueAction('Server URL', values.serverUrl, 'copy-server-url'),
+    copyValueAction('Authentication', values.authentication, 'copy-authentication')
+  ].filter(Boolean);
+}
+
+function copilotArtifacts(systemKey) {
+  return [
+    {
+      id: 'appPackage',
+      kind: 'zip',
+      fileName: 'appPackage.zip',
+      contentType: 'application/zip',
+      href: channelArtifactHref(systemKey, 'appPackage')
+    }
+  ];
+}
+
+/**
+ * @param {Object} params
+ * @returns {Object}
+ */
+function chatgptEnvelopeParts(params) {
+  const runtimeOk = resolveVerdicts(params).runtime.ok === true;
+  const values = buildChatGptFormValues({ runtimeValues: params.runtimeValues || {} });
+  const userActions = [
+    openUrlAction(CHATGPT_APPS_CREATE_URL, 'Open ChatGPT Apps', 'open-chatgpt-apps'),
+    ...chatgptCopyActions(params.runtimeValues)
+  ].filter(Boolean);
+  return {
+    artifacts: [],
+    userActions: runtimeOk ? withRetryLogin(params, userActions, true) : [],
+    remainingSteps: runtimeOk ? [...CHATGPT_REMAINING_STEPS] : [],
+    useValues: runtimeOk
+      ? {
+        Name: values.name,
+        Description: values.description,
+        'Server URL': values.serverUrl,
+        Authentication: values.authentication
+      }
+      : {}
+  };
+}
+
+/**
+ * @param {Object} params
+ * @returns {Object}
+ */
+function claudeEnvelopeParts(params) {
+  const runtimeOk = resolveVerdicts(params).runtime.ok === true;
+  const values = buildClaudeFormValues({ runtimeValues: params.runtimeValues || {} });
+  const userActions = [
+    openUrlAction(CLAUDE_CONNECTORS_URL, 'Open Claude connectors', 'open-claude-connectors'),
+    ...claudeCopyActions(params.runtimeValues)
+  ].filter(Boolean);
+  return {
+    artifacts: [],
+    userActions: runtimeOk ? withRetryLogin(params, userActions, true) : [],
+    remainingSteps: runtimeOk ? [...CLAUDE_REMAINING_STEPS] : [],
+    useValues: runtimeOk
+      ? {
+        Name: values.name,
+        'Server URL': values.serverUrl,
+        Authentication: values.authentication
+      }
+      : {}
+  };
+}
+
+/**
+ * @param {Object} params
+ * @returns {Object}
+ */
+function runCommandAction(command) {
+  if (typeof command !== 'string' || !command.trim()) {
+    return null;
+  }
+  return userAction({
+    id: 'run-command',
+    kind: 'runCommand',
+    label: 'Run this command',
+    extra: { command: command.trim() }
+  });
+}
+
+/**
+ * @param {Object} params
+ * @returns {Object}
+ */
+function slackTokenSubmitAction(params) {
+  if (params.channelTarget !== 'slack') {
+    return null;
+  }
+  if (params.ctx && params.ctx.slackConnected === true) {
+    return null;
+  }
+  return userAction({
+    id: 'submit-session-token',
+    kind: 'submitInput',
+    label: 'Paste the challenge code from Slack',
+    extra: { field: 'token' }
+  });
+}
+
+/**
+ * @param {Object} params
+ * @returns {Object}
+ */
+function defaultEnvelopeParts(params) {
+  const spec = remainingSpec(params.channelTarget, params.ctx || {}, params.runtimeValues);
+  const userActions = actionsFromRemainingSpec(spec);
+  const runCommand = runCommandAction(spec.slackSlashCommand);
+  if (runCommand) {
+    userActions.unshift(runCommand);
+  }
+  const tokenAction = slackTokenSubmitAction(params);
+  if (tokenAction) {
+    userActions.push(tokenAction);
+  }
+  userActions.push(...microsoftExtraActions(params));
+  const waitingCopilot =
+    params.channelTarget === 'microsoft-copilot' && copilotVaultMissing(params.runtimeValues);
+  const waitingTeams = teamsBotWaiting(params);
+  if (!waitingCopilot && !waitingTeams) {
+    userActions.push(...remainingStepActions(spec.steps));
+  }
+  const runtimeOk = resolveVerdicts(params).runtime.ok === true;
+  return {
+    artifacts: params.channelTarget === 'microsoft-copilot'
+      ? copilotArtifacts((params.ctx && params.ctx.instanceSystemKey) || params.channelTarget)
+      : [],
+    userActions: withRetryLogin(params, userActions, runtimeOk),
+    remainingSteps: Array.isArray(spec.steps) ? spec.steps.filter(Boolean) : [],
+    useValues: Object.fromEntries(
+      (spec.useLines || [])
+        .map((line) => String(line).split(/:\s(.*)/).filter(Boolean))
+        .filter((parts) => parts.length === 2 && !String(parts[1]).startsWith('/'))
+    )
+  };
+}
+
+/**
+ * @param {Object} params
+ * @returns {Object}
+ */
+function resolveVerdicts(params) {
+  const provided = params.verdicts && typeof params.verdicts === 'object' ? params.verdicts : {};
+  const runtimeOk = provided.runtime ? provided.runtime.ok !== false : true;
+  return {
+    runtime: provided.runtime || { ok: runtimeOk, label: runtimeOk ? 'Deployed' : 'Unavailable' },
+    oauth: provided.oauth || { ok: true, label: 'Connected' },
+    vendorSession: provided.vendorSession || { ok: false, label: 'Approval required' }
+  };
+}
+
+/**
+ * @param {Object} verdicts
+ * @param {Object[]} userActions
+ * @returns {string}
+ */
+function resolvePhase(verdicts, userActions) {
+  if (!verdicts.runtime || verdicts.runtime.ok !== true) {
+    return 'failed';
+  }
+  const required = (userActions || []).filter((action) => action.required === true);
+  const handoff = required.filter((action) => action.kind !== 'remainingVendorStep');
+  if (handoff.length > 0) {
+    return 'waitingForUser';
+  }
+  return 'ready';
+}
+
+function envelopePartsForTarget(channelTarget, params) {
+  if (channelTarget === 'chatgpt') {
+    return chatgptEnvelopeParts(params);
+  }
+  if (channelTarget === 'claude') {
+    return claudeEnvelopeParts(params);
+  }
+  return defaultEnvelopeParts(params);
+}
+
+/**
+ * @param {Object} params
+ * @param {string} params.channelTarget
+ * @param {string} [params.displayName]
+ * @param {Object|null} [params.ctx]
+ * @param {Object|null} [params.runtimeValues]
+ * @param {Object} [params.verdicts]
+ * @param {string} [params.requestId]
+ * @returns {Object}
+ */
+function toChannelInstallEnvelope(params) {
+  const channelTarget = params.channelTarget;
+  const target = CHANNEL_TARGETS[channelTarget] || { displayLabel: channelTarget, key: channelTarget };
+  const displayName = params.displayName || (params.runtimeValues && params.runtimeValues.appName) || channelTarget;
+  const verdicts = resolveVerdicts(params);
+  const parts = envelopePartsForTarget(channelTarget, params);
+  const userActions = parts.userActions;
+  return {
+    channelTarget,
+    displayLabel: target.displayLabel || channelTarget,
+    displayName,
+    phase: resolvePhase(verdicts, userActions),
+    verdicts,
+    artifacts: parts.artifacts,
+    userActions,
+    remainingSteps: parts.remainingSteps,
+    useValues: parts.useValues,
+    fix: verdicts.runtime.ok === true ? null : { detail: 'Fix the Runtime connection, then retry install.' },
+    requestId: params.requestId || undefined
+  };
+}
+
+module.exports = {
+  channelArtifactHref,
+  toChannelInstallEnvelope,
+  SLACK_APPS_URL,
+  DEVELOPER_PORTAL_APPS_URL,
+  CHATGPT_APPS_CREATE_URL,
+  CLAUDE_CONNECTORS_URL
+};

package/lib/channels/channel-install-help-md.js

@@ -0,0 +1,172 @@
+/**
+ * Default HTTP help markdown from ChannelInstallEnvelope.
+ *
+ * @fileoverview Same remaining-step content as Canonical TTY / INSTALL.md
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { assertNoSecretsInArtifact } = require('./channel-artifact-generator');
+
+/**
+ * @param {Object} envelope
+ * @returns {boolean}
+ */
+function isRuntimeReady(envelope) {
+  return Boolean(envelope && envelope.verdicts && envelope.verdicts.runtime && envelope.verdicts.runtime.ok);
+}
+
+/**
+ * @param {Object} envelope
+ * @returns {string[]}
+ */
+function statusLines(envelope) {
+  const ready = isRuntimeReady(envelope);
+  const lines = [`# ${envelope.displayName} — ${envelope.displayLabel}`, '', `Status: ${ready ? 'Ready' : 'Not ready'}`];
+  if (!ready) {
+    const label =
+      (envelope.verdicts && envelope.verdicts.runtime && envelope.verdicts.runtime.label) || 'Unavailable';
+    lines.push('', `Runtime: ${label}`);
+    if (envelope.fix && envelope.fix.detail) {
+      lines.push('', envelope.fix.detail);
+    }
+    return lines;
+  }
+  lines.push('', 'Runtime: Deployed');
+  if (envelope.verdicts && envelope.verdicts.oauth && envelope.verdicts.oauth.ok) {
+    lines.push('OAuth: Connected.');
+  }
+  return lines;
+}
+
+/**
+ * @param {Object} action
+ * @returns {string|null}
+ */
+function renderOpenUrl(action) {
+  if (action.kind !== 'openUrl' || !action.href) {
+    return null;
+  }
+  const label = String(action.label || 'Open').trim();
+  if (/^(open|sign in|import|publish|approve|download)\b/i.test(label)) {
+    return `[${label}](${action.href}).`;
+  }
+  return `Open [${label}](${action.href}).`;
+}
+
+/**
+ * @param {Object} action
+ * @returns {string|null}
+ */
+function renderDownload(action) {
+  if (action.kind !== 'downloadArtifact') {
+    return null;
+  }
+  const href = action.href || '';
+  if (!href) {
+    return null;
+  }
+  return `[${action.label}](${href})`;
+}
+
+/**
+ * @param {Object} action
+ * @returns {string|null}
+ */
+function renderRunCommand(action) {
+  if (action.kind !== 'runCommand' || !action.command) {
+    return null;
+  }
+  return ['Run:', '', '```', action.command, '```'].join('\n');
+}
+
+/**
+ * @param {Object} envelope
+ * @returns {string[]}
+ */
+function useValueLines(envelope) {
+  const fromActions = (envelope.userActions || [])
+    .filter((action) => action.kind === 'copyValue' && action.value)
+    .map((action) => `- ${action.label}: ${action.value}`);
+  if (fromActions.length > 0) {
+    return ['Use:', '', ...fromActions];
+  }
+  const entries = Object.entries(envelope.useValues || {}).filter(([, value]) => String(value || '').trim());
+  if (entries.length === 0) {
+    return [];
+  }
+  return ['Use:', '', ...entries.map(([label, value]) => `- ${label}: ${value}`)];
+}
+
+/**
+ * @param {Object} envelope
+ * @returns {string[]}
+ */
+function remainingLines(envelope) {
+  const steps = Array.isArray(envelope.remainingSteps)
+    ? envelope.remainingSteps.filter((step) => typeof step === 'string' && step.trim())
+    : [];
+  if (steps.length === 0 || !isRuntimeReady(envelope)) {
+    return [];
+  }
+  const label = envelope.displayLabel || 'vendor';
+  return [`Remaining ${label} steps:`, '', ...steps.map((step) => `- ${step}`)];
+}
+
+/**
+ * @param {Object} envelope
+ * @returns {string}
+ */
+function toChannelHelpMarkdown(envelope) {
+  const lines = [...statusLines(envelope)];
+  if (isRuntimeReady(envelope)) {
+    const opens = (envelope.userActions || []).map(renderOpenUrl).filter(Boolean);
+    const downloads = (envelope.userActions || []).map(renderDownload).filter(Boolean);
+    const commands = (envelope.userActions || []).map(renderRunCommand).filter(Boolean);
+    if (opens.length) {
+      lines.push('', ...opens);
+    }
+    const useLines = useValueLines(envelope);
+    if (useLines.length) {
+      lines.push('', ...useLines);
+    }
+    if (downloads.length) {
+      lines.push('', ...downloads);
+    }
+    if (commands.length) {
+      lines.push('', ...commands);
+    }
+    const remaining = remainingLines(envelope);
+    if (remaining.length) {
+      lines.push('', ...remaining);
+    }
+  }
+  const markdown = `${lines.join('\n').trim()}\n`;
+  assertNoSecretsInArtifact(markdown);
+  return markdown;
+}
+
+/**
+ * Help-only fields. Default HTTP also includes phase + userActions via toChannelInstallHttpPayload.
+ * @param {Object} envelope
+ * @returns {{ helpMarkdown: string, helpMarkdownContentType: string, refreshHintSeconds?: number }}
+ */
+function toChannelHelpHttpPayload(envelope) {
+  const helpMarkdown = toChannelHelpMarkdown(envelope);
+  const payload = {
+    helpMarkdown,
+    helpMarkdownContentType: 'text/markdown'
+  };
+  if (envelope.phase === 'waitingForUser') {
+    payload.refreshHintSeconds = 15;
+  }
+  return payload;
+}
+
+module.exports = {
+  toChannelHelpMarkdown,
+  toChannelHelpHttpPayload,
+  isRuntimeReady
+};

package/lib/channels/channel-install-http-payload.js

@@ -0,0 +1,62 @@
+/**
+ * Default HTTP JSON for channel install GET/POST/continue.
+ *
+ * @fileoverview helpMarkdown + phase + safe userActions (not session SSOT)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { toChannelHelpHttpPayload } = require('./channel-install-help-md');
+
+const SECRETISH = /xox[baprs]-|sk-[a-zA-Z0-9]{8,}|Bearer\s+[A-Za-z0-9._-]{12,}/i;
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function looksSecret(value) {
+  return typeof value === 'string' && SECRETISH.test(value);
+}
+
+/**
+ * Strip secret-shaped fields from envelope actions for the default HTTP JSON.
+ * @param {Object[]} [actions]
+ * @returns {Object[]}
+ */
+function safeUserActions(actions) {
+  return (Array.isArray(actions) ? actions : []).map((action) => {
+    const copy = { ...action };
+    if (looksSecret(copy.value)) {
+      delete copy.value;
+    }
+    if (looksSecret(copy.command)) {
+      delete copy.command;
+    }
+    if (looksSecret(copy.text)) {
+      delete copy.text;
+    }
+    return copy;
+  });
+}
+
+/**
+ * Default machine wizard payload. verbose=true still returns the full envelope.
+ * @param {Object} envelope
+ * @returns {Object}
+ */
+function toChannelInstallHttpPayload(envelope) {
+  const help = toChannelHelpHttpPayload(envelope);
+  return {
+    ...help,
+    phase: envelope.phase,
+    userActions: safeUserActions(envelope.userActions),
+    verdicts: envelope.verdicts
+  };
+}
+
+module.exports = {
+  safeUserActions,
+  toChannelInstallHttpPayload
+};

package/lib/channels/channel-install-inventory.js

@@ -0,0 +1,115 @@
+/**
+ * Match Dataplane Connected Systems to a Channel Definition.
+ *
+ * @fileoverview Builder inventory projection — no second lifecycle store
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Object|null} system
+ * @returns {string|null}
+ */
+function readStamp(block) {
+  if (!block || typeof block !== 'object') {
+    return null;
+  }
+  const stamped =
+    (typeof block.definitionKey === 'string' && block.definitionKey) ||
+    (typeof block.definitionKey === 'string' && block.definitionKey);
+  return stamped || null;
+}
+
+function readDefinitionKeyFromSystem(system) {
+  if (!system || typeof system !== 'object') {
+    return null;
+  }
+  const fromChannel = readStamp(system.channel);
+  if (fromChannel) {
+    return fromChannel;
+  }
+  const fallback = system.config && system.config.extensions && system.config.extensions.channel;
+  const fromConfig = readStamp(fallback);
+  if (fromConfig) {
+    return fromConfig;
+  }
+  if (fallback && typeof fallback.type === 'string' && fallback.type) {
+    return null;
+  }
+  return null;
+}
+
+function isInstanceKeyForDefinition(systemKey, definitionKey) {
+  return (
+    typeof systemKey === 'string' &&
+    systemKey !== definitionKey &&
+    systemKey.startsWith(`${definitionKey}-`)
+  );
+}
+
+/**
+ * @param {Object} system
+ * @returns {Object}
+ */
+function toInstallationProjection(system) {
+  const runtime =
+    system.channel && system.channel.runtimeTarget && system.channel.runtimeTarget.defaultSystemKey
+      ? system.channel.runtimeTarget.defaultSystemKey
+      : 'runtime-orchestration';
+  return {
+    key: system.key,
+    displayName: system.displayName || system.key,
+    version: system.version || system.configVersion || null,
+    lifecycle: system.lifecycle || system.status || null,
+    availability: system.availability || null,
+    authenticationStatus: system.authenticationStatus || system.authStatus || null,
+    connectedSystemKey: system.key,
+    runtimeTarget: { systemKey: runtime }
+  };
+}
+
+/**
+ * @param {Object[]} systems
+ * @param {string} definitionKey
+ * @returns {Object[]}
+ */
+function installationsForDefinition(systems, definitionKey) {
+  return (Array.isArray(systems) ? systems : [])
+    .filter((system) => {
+      if (!system || typeof system !== 'object' || system.key === definitionKey) {
+        return false;
+      }
+      return (
+        readDefinitionKeyFromSystem(system) === definitionKey ||
+        isInstanceKeyForDefinition(system.key, definitionKey)
+      );
+    })
+    .map(toInstallationProjection);
+}
+
+/**
+ * @param {Object[]} installations
+ * @returns {{ count: number, statusRollup: string }}
+ */
+function summarizeInstallations(installations) {
+  const rows = Array.isArray(installations) ? installations : [];
+  if (rows.length === 0) {
+    return { count: 0, statusRollup: 'none' };
+  }
+  const statuses = rows.map((row) => row.lifecycle || row.availability || 'unknown');
+  const unique = [...new Set(statuses)];
+  return {
+    count: rows.length,
+    statusRollup: unique.length === 1 ? unique[0] : 'mixed'
+  };
+}
+
+module.exports = {
+  readDefinitionKeyFromSystem,
+  isInstanceKeyForDefinition,
+  toInstallationProjection,
+  installationsForDefinition,
+  summarizeInstallations
+};