@chenguangyao/devflow-kit 0.1.43 → 0.1.44

package/src/core/workflow-ui-adapter.js

@@ -0,0 +1,467 @@
+'use strict';
+
+const adapterSurfaceSchema = require('../../schemas/workflow-adapter-surface.schema.json');
+const adapterCatalogSchema = require('../../schemas/workflow-adapter-catalog.schema.json');
+
+const SUPPORTED_PROFILES = new Set(['codex', 'cursor', 'browser', 'cli']);
+const SUPPORTED_RENDER_MODES = new Set(['in_app_browser', 'webview_or_browser', 'browser', 'terminal_markdown']);
+const PROTOCOL_VERSION = 'workflow-adapter-surface/v1';
+const ADAPTER_SURFACE_SCHEMA = 'https://devflow.dev/schemas/workflow-adapter-surface.schema.json';
+const ADAPTER_CATALOG_SCHEMA = 'https://devflow.dev/schemas/workflow-adapter-catalog.schema.json';
+const WORKFLOW_SELECTION_SCHEMA = 'https://devflow.dev/schemas/workflow-selection.schema.json';
+const WORKFLOW_UI_ERROR_SCHEMA = 'https://devflow.dev/schemas/workflow-ui-error.schema.json';
+const WORKFLOW_UI_COMMAND_RESULT_SCHEMA = 'https://devflow.dev/schemas/workflow-ui-command-result.schema.json';
+const ADAPTER_FEATURES = [
+  'catalog-discovery',
+  'chat-card',
+  'chat-selection',
+  'embedded-ui',
+  'read-only-diff',
+  'read-only-explain',
+  'checkpoint-resolve',
+  'controlled-confirm',
+];
+
+const HOST_ALIASES = {
+  'codex-app': 'codex',
+  vscode: 'browser',
+  web: 'browser',
+  terminal: 'cli',
+  shell: 'cli',
+};
+
+const PROFILE_CATALOG = [
+  {
+    id: 'codex',
+    label: 'Codex App',
+    defaultRenderMode: 'in_app_browser',
+    description: 'Use the Codex in-app browser for the interactive workflow UI and Markdown for chat fallback.',
+    recommendedHosts: ['codex', 'codex-app'],
+  },
+  {
+    id: 'cursor',
+    label: 'WebView host',
+    defaultRenderMode: 'webview_or_browser',
+    description: 'Use an IDE WebView when available, with the same local browser UI as fallback.',
+    recommendedHosts: ['cursor', 'windsurf'],
+  },
+  {
+    id: 'browser',
+    label: 'Browser host',
+    defaultRenderMode: 'browser',
+    description: 'Use the system browser or any generic tool that can open the local workflow UI URL.',
+    recommendedHosts: ['browser', 'jetbrains', 'zed'],
+  },
+  {
+    id: 'cli',
+    label: 'Terminal or Markdown host',
+    defaultRenderMode: 'terminal_markdown',
+    description: 'Print the Markdown chat card and submit edited workflow_chat_selection JSON through the local API.',
+    recommendedHosts: ['cli', 'terminal', 'shell'],
+  },
+];
+
+const RENDER_MODE_CATALOG = [
+  {
+    id: 'in_app_browser',
+    label: 'In-app browser',
+    supportsEmbeddedUi: true,
+    description: 'A host-owned browser surface can open the local workflow UI directly.',
+  },
+  {
+    id: 'webview_or_browser',
+    label: 'WebView or browser',
+    supportsEmbeddedUi: true,
+    description: 'An IDE extension may embed the local UI in a WebView and fall back to the system browser.',
+  },
+  {
+    id: 'browser',
+    label: 'Browser',
+    supportsEmbeddedUi: false,
+    description: 'Open the local workflow UI in an external browser.',
+  },
+  {
+    id: 'terminal_markdown',
+    label: 'Terminal Markdown',
+    supportsEmbeddedUi: false,
+    description: 'Render the Markdown fallback and call the listed local API endpoints for explicit user actions.',
+  },
+];
+
+function buildWorkflowAdapterSurface(options = {}) {
+  const slug = options.slug;
+  if (!slug) throw new Error('buildWorkflowAdapterSurface requires slug');
+  const host = normalizeAdapterHost(options.host || 'browser');
+  const profile = normalizeAdapterProfile(options.profile || profileForHost(host));
+  const renderMode = normalizeRenderMode(options.renderMode || options['render-mode'] || renderModeFor(profile));
+  const uiHost = options.uiHost || options.hostname || '127.0.0.1';
+  const port = options.port === undefined || options.port === null ? 8787 : Number(options.port);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`invalid adapter port: ${options.port}`);
+  const url = `http://${uiHost}:${port}/`;
+  const actions = {
+    startUi: `devflow flow ui --slug=${slug} --port=${port}`,
+    startUiJson: `devflow flow ui --slug=${slug} --port=${port} --json`,
+    statusApi: `${url}api/status`,
+    pickerApi: `${url}api/picker`,
+    diffApi: `${url}api/diff`,
+    explainApi: `${url}api/explain`,
+    applySelectionApi: `${url}api/apply-selection`,
+    chatSelectionApi: `${url}api/adapter/apply-selection`,
+    cardApi: `${url}api/card`,
+    checkpointResolveApi: `${url}api/checkpoint/resolve`,
+    confirmApi: `${url}api/confirm`,
+  };
+  const chatCard = buildChatCard({ host, profile, renderMode, slug, url, actions, pickerSurface: options.pickerSurface || null });
+  return {
+    type: 'workflow_adapter_surface',
+    protocolVersion: PROTOCOL_VERSION,
+    host,
+    profile,
+    slug,
+    renderMode,
+    url,
+    features: [...ADAPTER_FEATURES],
+    capabilities: capabilitiesFor(host, profile, renderMode),
+    actions,
+    chatCard,
+    instructions: instructionsFor(host, profile, renderMode, url, actions),
+    fallbackMarkdown: chatCard.markdown,
+  };
+}
+
+function buildWorkflowAdapterCatalog() {
+  return {
+    type: 'workflow_adapter_catalog',
+    protocolVersion: PROTOCOL_VERSION,
+    schema: ADAPTER_CATALOG_SCHEMA,
+    features: [...ADAPTER_FEATURES],
+    defaults: {
+      customHostProfile: 'browser',
+      customHostRenderMode: 'browser',
+      mutationModel: 'devflow-controlled',
+    },
+    profiles: PROFILE_CATALOG.map((profile) => ({ ...profile })),
+    renderModes: RENDER_MODE_CATALOG.map((mode) => ({ ...mode })),
+    hostAliases: { ...HOST_ALIASES },
+    examples: [
+      {
+        host: 'codex',
+        profile: 'codex',
+        renderMode: 'in_app_browser',
+        command: 'devflow flow adapter --slug=<slug> --host=codex --json',
+      },
+      {
+        host: 'windsurf',
+        profile: 'cursor',
+        renderMode: 'webview_or_browser',
+        command: 'devflow flow adapter --slug=<slug> --host=windsurf --profile=cursor --json',
+      },
+      {
+        host: 'jetbrains',
+        profile: 'browser',
+        renderMode: 'browser',
+        command: 'devflow flow adapter --slug=<slug> --host=jetbrains --render-mode=browser --json',
+      },
+      {
+        host: 'zed',
+        profile: 'cli',
+        renderMode: 'terminal_markdown',
+        command: 'devflow flow adapter --slug=<slug> --host=zed --profile=cli --json',
+      },
+    ],
+    safety: {
+      arbitraryShell: false,
+      mutationModel: 'devflow-controlled',
+      readOnlyActions: ['statusApi', 'pickerApi', 'diffApi', 'explainApi', 'cardApi'],
+      mutationActions: ['applySelectionApi', 'chatSelectionApi', 'checkpointResolveApi', 'confirmApi'],
+    },
+  };
+}
+
+function normalizeAdapterHost(host) {
+  const normalized = String(host || 'browser').trim().toLowerCase();
+  if (HOST_ALIASES[normalized]) return HOST_ALIASES[normalized];
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(normalized)) throw new Error(`invalid workflow adapter host: ${host}`);
+  return normalized;
+}
+
+function normalizeAdapterProfile(profile) {
+  const normalized = String(profile || 'browser').trim().toLowerCase();
+  if (normalized === 'codex-app') return 'codex';
+  if (normalized === 'vscode' || normalized === 'web') return 'browser';
+  if (normalized === 'webview') return 'cursor';
+  if (normalized === 'terminal' || normalized === 'shell' || normalized === 'markdown') return 'cli';
+  if (!SUPPORTED_PROFILES.has(normalized)) {
+    throw new Error(`unsupported workflow adapter profile: ${profile}. supported: codex, cursor, browser, cli`);
+  }
+  return normalized;
+}
+
+function profileForHost(host) {
+  if (SUPPORTED_PROFILES.has(host)) return host;
+  return 'browser';
+}
+
+function normalizeRenderMode(renderMode) {
+  const normalized = String(renderMode || 'browser').trim().toLowerCase().replace(/-/g, '_');
+  if (!SUPPORTED_RENDER_MODES.has(normalized)) {
+    throw new Error(`unsupported workflow adapter render mode: ${renderMode}. supported: in_app_browser, webview_or_browser, browser, terminal_markdown`);
+  }
+  return normalized;
+}
+
+function renderModeFor(profile) {
+  if (profile === 'codex') return 'in_app_browser';
+  if (profile === 'cursor') return 'webview_or_browser';
+  if (profile === 'cli') return 'terminal_markdown';
+  return 'browser';
+}
+
+function capabilitiesFor(host, profile, renderMode) {
+  return {
+    schema: ADAPTER_SURFACE_SCHEMA,
+    selectionSchema: WORKFLOW_SELECTION_SCHEMA,
+    errorSchema: WORKFLOW_UI_ERROR_SCHEMA,
+    commandResultSchema: WORKFLOW_UI_COMMAND_RESULT_SCHEMA,
+    host,
+    profile,
+    renderMode,
+    features: [...ADAPTER_FEATURES],
+    supportsChatCard: true,
+    supportsChatSelection: true,
+    supportsNativeCheckboxes: false,
+    supportsEmbeddedUi: renderMode === 'in_app_browser' || renderMode === 'webview_or_browser',
+    supportsReadOnlyDiff: true,
+    supportsReadOnlyExplain: true,
+    supportsApplySelection: true,
+    supportsCheckpointResolve: true,
+    supportsConfirm: true,
+    mutationModel: 'devflow-controlled',
+  };
+}
+
+function validateWorkflowAdapterSurface(surface) {
+  return validateAgainstSchema(surface, adapterSurfaceSchema, adapterSurfaceSchema, '');
+}
+
+function assertWorkflowAdapterSurface(surface) {
+  const errors = validateWorkflowAdapterSurface(surface);
+  if (errors.length) {
+    throw new Error(`workflow adapter surface contract violation:\n- ${errors.join('\n- ')}`);
+  }
+}
+
+function validateWorkflowAdapterCatalog(catalog) {
+  return validateAgainstSchema(catalog, adapterCatalogSchema, adapterCatalogSchema, '');
+}
+
+function assertWorkflowAdapterCatalog(catalog) {
+  const errors = validateWorkflowAdapterCatalog(catalog);
+  if (errors.length) {
+    throw new Error(`workflow adapter catalog contract violation:\n- ${errors.join('\n- ')}`);
+  }
+}
+
+function validateAgainstSchema(value, schema, rootSchema, path) {
+  const errors = [];
+  if (!schema) return errors;
+  if (schema.$ref) {
+    return validateAgainstSchema(value, resolveRef(rootSchema, schema.$ref), rootSchema, path);
+  }
+  if (Object.prototype.hasOwnProperty.call(schema, 'const') && value !== schema.const) {
+    errors.push(`${formatPath(path)} must equal ${JSON.stringify(schema.const)}`);
+  }
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push(`${formatPath(path)} must be one of ${schema.enum.map((item) => JSON.stringify(item)).join(', ')}`);
+  }
+  if (schema.type && !matchesType(value, schema.type)) {
+    errors.push(`${formatPath(path)} must be ${Array.isArray(schema.type) ? schema.type.join(' or ') : schema.type}`);
+    return errors;
+  }
+  if (schema.required && isPlainObject(value)) {
+    for (const key of schema.required) {
+      if (!Object.prototype.hasOwnProperty.call(value, key) || value[key] === undefined) {
+        errors.push(`${formatPath(joinPath(path, key))} is required`);
+      }
+    }
+  }
+  if (schema.properties && isPlainObject(value)) {
+    for (const [key, childSchema] of Object.entries(schema.properties)) {
+      if (Object.prototype.hasOwnProperty.call(value, key) && value[key] !== undefined) {
+        errors.push(...validateAgainstSchema(value[key], childSchema, rootSchema, joinPath(path, key)));
+      }
+    }
+  }
+  if (schema.items && Array.isArray(value)) {
+    value.forEach((item, index) => {
+      errors.push(...validateAgainstSchema(item, schema.items, rootSchema, `${path}[${index}]`));
+    });
+  }
+  return errors;
+}
+
+function resolveRef(rootSchema, ref) {
+  if (!ref.startsWith('#/')) throw new Error(`unsupported schema ref: ${ref}`);
+  return ref.slice(2).split('/').reduce((node, part) => node && node[part], rootSchema);
+}
+
+function matchesType(value, type) {
+  if (Array.isArray(type)) return type.some((entry) => matchesType(value, entry));
+  if (type === 'array') return Array.isArray(value);
+  if (type === 'object') return isPlainObject(value);
+  if (type === 'null') return value === null;
+  return typeof value === type;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function joinPath(base, key) {
+  return base ? `${base}.${key}` : key;
+}
+
+function formatPath(path) {
+  return path || '<root>';
+}
+
+function buildChatCard({ host, profile, renderMode, slug, url, actions, pickerSurface }) {
+  const hostLine = chatHostLine(host, profile, renderMode);
+  const selection = buildChatSelection(pickerSurface);
+  const skillLines = renderSkillSelection(selection);
+  return {
+    type: 'workflow_chat_card',
+    format: 'markdown',
+    title: 'Workflow 编排',
+    selection,
+    markdown: [
+      '## Workflow 编排',
+      '',
+      `- change: \`${slug}\``,
+      `- host: \`${host}\``,
+      `- profile: \`${profile}\``,
+      `- render mode: \`${renderMode}\``,
+      `- surface: ${hostLine}`,
+      '',
+      `[打开可交互编排卡片](${url})`,
+      '',
+      '**可用操作**',
+      `- 启动 UI：\`${actions.startUi}\``,
+      `- 状态接口：\`${actions.statusApi}\``,
+      `- diff/explain：\`${actions.diffApi}\` / \`${actions.explainApi}\``,
+      `- 应用选择：\`${actions.chatSelectionApi}\``,
+      `- 确认 workflow：\`${actions.confirmApi}\``,
+      ...skillLines,
+      '',
+      '提示：聊天卡片只负责展示；状态变更仍由 devflow CLI / local UI API 执行。',
+    ].join('\n'),
+  };
+}
+
+function buildChatSelection(pickerSurface) {
+  const groups = Array.isArray(pickerSurface && pickerSurface.groups) ? pickerSurface.groups : [];
+  return {
+    type: 'workflow_chat_selection',
+    layout: 'linear-checkboxes',
+    groups: groups.map((group) => ({
+      id: group.id,
+      label: group.label,
+      items: (group.items || []).map((item) => ({
+        step: item.step,
+        skill: item.skill,
+        label: item.label || item.step,
+        selected: item.selected === true,
+        recommended: item.recommended === true,
+        locked: item.locked === true,
+        required: item.required === true,
+        installed: item.installed === true,
+        reason: item.reason || null,
+        command: item.command || null,
+      })),
+    })),
+  };
+}
+
+function renderSkillSelection(selection) {
+  if (!selection.groups.length) return [];
+  const lines = ['', '**Skill 选择**'];
+  for (const group of selection.groups) {
+    lines.push('', `### ${group.label || group.id}`);
+    for (const item of group.items) {
+      const checked = item.selected ? 'x' : ' ';
+      const badges = [];
+      if (item.locked) badges.push('锁定');
+      if (item.required) badges.push('required');
+      if (item.recommended) badges.push('推荐');
+      if (item.installed === false) badges.push('未安装');
+      const suffix = badges.length ? ` (${badges.join(', ')})` : '';
+      lines.push(`- [${checked}] \`${item.step}\` -> \`${item.skill}\`${suffix}`);
+      if (item.reason) lines.push(`  - 原因：${item.reason}`);
+      if (item.command) lines.push(`  - 命令：\`${item.command}\``);
+    }
+  }
+  return lines;
+}
+
+function chatHostLine(host, profile, renderMode) {
+  if (profile === 'codex') return 'Codex in-app browser';
+  if (profile === 'cursor') return host === 'cursor' ? 'Cursor WebView 或浏览器' : `${host} WebView 或浏览器`;
+  if (profile === 'cli') return 'CLI terminal';
+  if (renderMode === 'terminal_markdown') return 'CLI terminal';
+  if (renderMode === 'webview_or_browser') return `${host} WebView 或浏览器`;
+  if (renderMode === 'in_app_browser') return `${host} in-app browser`;
+  return 'browser';
+}
+
+function instructionsFor(host, profile, renderMode, url, actions) {
+  if (profile === 'codex') {
+    return [
+      `Codex App adapter: start the local UI with \`${actions.startUi}\`, then open ${url} in the Codex in-app browser.`,
+      'Codex chat can show the fallback Markdown link, but interactive cards should run in the in-app browser surface.',
+      'Use diff/explain endpoints for read-only workflow insight, and checkpoint resolve only for explicit confirmation buttons.',
+      'All mutations still go through devflow CLI JSON APIs; the adapter does not edit state directly.',
+    ];
+  }
+  if (profile === 'cursor') {
+    const label = adapterLabel(host);
+    return [
+      `${label} adapter: start the local UI with \`${actions.startUi}\`, then open ${url} in a WebView or the system browser.`,
+      `${label} extensions can embed this URL in a WebView and call the listed local API endpoints from that WebView.`,
+      'Use diff/explain endpoints for read-only cards; apply selection, confirm, and checkpoint resolve are the only mutation APIs.',
+      'Without an extension, keep the terminal process running and use the browser fallback; workflow state remains CLI-owned.',
+    ];
+  }
+  if (profile === 'cli' || renderMode === 'terminal_markdown') {
+    const label = adapterLabel(host);
+    return [
+      `${label} adapter: start the local UI with \`${actions.startUi}\`, or use this Markdown card directly in a terminal/chat surface.`,
+      'CLI hosts should print the fallback Markdown and submit edited workflow_chat_selection JSON to the listed chatSelectionApi.',
+      'Use diff/explain endpoints for read-only inspection; apply selection, confirm, and checkpoint resolve remain devflow-controlled.',
+      'Do not execute arbitrary shell from the card; present commands and API endpoints for explicit user action.',
+    ];
+  }
+  return [
+    `${adapterLabel(host)} adapter: start the local UI with \`${actions.startUi}\`, then open ${url}.`,
+    'Use the listed local API endpoints if another host wants to render its own UI.',
+  ];
+}
+
+function adapterLabel(host) {
+  if (host === 'codex') return 'Codex App';
+  if (host === 'cursor') return 'Cursor';
+  if (host === 'browser') return 'Browser';
+  if (host === 'cli') return 'CLI';
+  return host;
+}
+
+module.exports = {
+  assertWorkflowAdapterCatalog,
+  assertWorkflowAdapterSurface,
+  buildWorkflowAdapterCatalog,
+  buildWorkflowAdapterSurface,
+  normalizeAdapterHost,
+  normalizeAdapterProfile,
+  normalizeRenderMode,
+  validateWorkflowAdapterCatalog,
+  validateWorkflowAdapterSurface,
+};