@chenguangyao/devflow-kit 0.1.43 → 0.1.44

package/src/client/workflow-adapter-client.js

@@ -0,0 +1,291 @@
+'use strict';
+
+const SUPPORTED_PROTOCOL = 'workflow-adapter-surface/v1';
+
+function ensureCompatibleSurface(surface) {
+  if (!surface || surface.type !== 'workflow_adapter_surface') {
+    throw new Error('expected workflow_adapter_surface JSON');
+  }
+  if (surface.protocolVersion !== SUPPORTED_PROTOCOL) {
+    throw new Error(`unsupported workflow adapter protocol: ${surface.protocolVersion || '<missing>'}`);
+  }
+  if (!surface.capabilities || surface.capabilities.mutationModel !== 'devflow-controlled') {
+    throw new Error('workflow adapter capabilities must use devflow-controlled mutations');
+  }
+  if (!surface.capabilities.supportsChatSelection) {
+    throw new Error('workflow adapter does not support chat selection payloads');
+  }
+  if (!surface.actions || !surface.actions.chatSelectionApi) {
+    throw new Error('workflow adapter missing actions.chatSelectionApi');
+  }
+  if (!surface.chatCard || !surface.chatCard.selection) {
+    throw new Error('workflow adapter missing chatCard.selection');
+  }
+  return surface;
+}
+
+function ensureCompatibleCatalog(catalog) {
+  if (!catalog || catalog.type !== 'workflow_adapter_catalog') {
+    throw new Error('expected workflow_adapter_catalog JSON');
+  }
+  if (catalog.protocolVersion !== SUPPORTED_PROTOCOL) {
+    throw new Error(`unsupported workflow adapter catalog protocol: ${catalog.protocolVersion || '<missing>'}`);
+  }
+  if (!catalog.defaults || catalog.defaults.mutationModel !== 'devflow-controlled') {
+    throw new Error('workflow adapter catalog defaults must use devflow-controlled mutations');
+  }
+  if (!Array.isArray(catalog.profiles) || !catalog.profiles.length) {
+    throw new Error('workflow adapter catalog missing profiles');
+  }
+  if (!Array.isArray(catalog.renderModes) || !catalog.renderModes.length) {
+    throw new Error('workflow adapter catalog missing renderModes');
+  }
+  return catalog;
+}
+
+function recommendAdapterProfile(catalog, host) {
+  ensureCompatibleCatalog(catalog);
+  const requestedHost = normalizeHostName(host || 'browser');
+  const aliasTarget = catalog.hostAliases && catalog.hostAliases[requestedHost];
+  const canonicalHost = aliasTarget || requestedHost;
+  const profiles = catalog.profiles || [];
+  const direct = profiles.find((profile) => profile.id === canonicalHost);
+  const recommended = direct || profiles.find((profile) => (profile.recommendedHosts || []).includes(requestedHost));
+  const fallbackId = catalog.defaults && catalog.defaults.customHostProfile || 'browser';
+  const fallback = profiles.find((profile) => profile.id === fallbackId) || profiles[0];
+  const profile = recommended || fallback;
+  const renderMode = profile.defaultRenderMode || (catalog.defaults && catalog.defaults.customHostRenderMode) || 'browser';
+  return {
+    host: requestedHost,
+    canonicalHost,
+    profile: profile.id,
+    renderMode,
+    reason: recommended
+      ? (direct ? 'host matches a built-in profile' : `host is recommended for ${profile.id}`)
+      : `custom host fallback to ${profile.id}`,
+    command: `devflow flow adapter --slug=<slug> --host=${requestedHost} --profile=${profile.id} --json`,
+  };
+}
+
+function buildSelectionPayload(surface, selectedStepIds) {
+  ensureCompatibleSurface(surface);
+  const selected = new Set(selectedStepIds || []);
+  const selection = surface.chatCard.selection;
+  return {
+    type: 'workflow_chat_selection',
+    layout: selection.layout || 'linear-checkboxes',
+    groups: (selection.groups || []).map((group) => ({
+      id: group.id,
+      label: group.label,
+      items: (group.items || []).map((item) => ({
+        ...item,
+        selected: item.locked === true || selected.has(item.step),
+      })),
+    })),
+  };
+}
+
+async function submitSelection(surface, selectedStepIds, options = {}) {
+  ensureCompatibleSurface(surface);
+  const payload = buildSelectionPayload(surface, selectedStepIds);
+  const url = surface.actions.chatSelectionApi;
+  if (options.dryRun) return { dryRun: true, url, payload };
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (typeof fetchImpl !== 'function') throw new Error('fetch is not available; use Node.js 20+ or pass a fetch implementation');
+  const response = await fetchImpl(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+  const text = await response.text();
+  const parsed = parseJsonOrRaw(text);
+  if (!response.ok) {
+    const detail = formatWorkflowHostError(parsed);
+    const err = new Error(`workflow selection submit failed: HTTP ${response.status}${detail}`);
+    err.response = parsed;
+    throw err;
+  }
+  return parsed;
+}
+
+function renderCatalogExample(catalog, options = {}) {
+  ensureCompatibleCatalog(catalog);
+  const host = normalizeHostName(options.host || 'browser');
+  const rec = recommendAdapterProfile(catalog, host);
+  return [
+    `# ${hostLabel(host)} workflow adapter discovery`,
+    '',
+    `- protocol: \`${catalog.protocolVersion}\``,
+    `- host: \`${rec.host}\``,
+    `- canonical host: \`${rec.canonicalHost}\``,
+    `- profile: \`${rec.profile}\``,
+    `- render mode: \`${rec.renderMode}\``,
+    `- reason: ${rec.reason}`,
+    '',
+    '## Recommended adapter command',
+    '',
+    '```bash',
+    rec.command,
+    '```',
+    '',
+    '## Supported profiles',
+    '',
+    ...(catalog.profiles || []).map((profile) => `- \`${profile.id}\` -> \`${profile.defaultRenderMode}\`: ${profile.description}`),
+    '',
+    '## Safety model',
+    '',
+    `- mutation model: \`${catalog.safety && catalog.safety.mutationModel || '<missing>'}\``,
+    `- arbitrary shell: \`${catalog.safety && catalog.safety.arbitraryShell === false ? 'false' : 'true'}\``,
+    `- mutation actions: \`${((catalog.safety && catalog.safety.mutationActions) || []).join(', ')}\``,
+  ].join('\n');
+}
+
+function renderHostExample(surface, options = {}) {
+  ensureCompatibleSurface(surface);
+  const host = normalizeHostName(options.host || surface.host || 'browser');
+  const selectedStepIds = collectDefaultSelectedSteps(surface);
+  const payload = buildSelectionPayload(surface, selectedStepIds);
+  return [
+    `# ${hostLabel(host)} workflow adapter example`,
+    '',
+    `- protocol: \`${surface.protocolVersion}\``,
+    `- render mode: \`${surface.renderMode}\``,
+    `- start UI: \`${surface.actions.startUi}\``,
+    `- open UI: ${surface.url}`,
+    `- submit selection: ${surface.actions.chatSelectionApi}`,
+    `- error schema: ${surface.capabilities.errorSchema || '<not advertised>'}`,
+    `- command result schema: ${surface.capabilities.commandResultSchema || '<not advertised>'}`,
+    '',
+    '## Host rendering',
+    '',
+    hostRenderingNotes(host),
+    '',
+    '## Markdown fallback',
+    '',
+    surface.chatCard.markdown || surface.fallbackMarkdown || '',
+    '',
+    '## POST selection payload',
+    '',
+    '```json',
+    JSON.stringify(payload, null, 2),
+    '```',
+    '',
+    '## Submit example',
+    '',
+    '```bash',
+    `curl -sS -X POST '${surface.actions.chatSelectionApi}' \\`,
+    "  -H 'content-type: application/json' \\",
+    "  --data @selection.json",
+    '```',
+  ].join('\n');
+}
+
+function renderSurfaceMarkdown(surface) {
+  if (!surface || typeof surface !== 'object') return '## Unknown surface\n\nNo structured surface was provided.';
+  if (surface.type === 'workflow_ui_error') {
+    return [
+      '## Workflow UI Error',
+      '',
+      `- code: \`${surface.code || 'unknown'}\``,
+      `- message: ${surface.message || '<empty>'}`,
+      surface.command ? `- command: \`${surface.command}\`` : null,
+    ].filter(Boolean).join('\n');
+  }
+  if (surface.type === 'workflow_policy_confirmation_surface') {
+    const cp = surface.checkpoint || {};
+    return [
+      '## 风险确认',
+      '',
+      `- change: \`${surface.slug || '-'}\``,
+      `- checkpoint: \`${cp.id || '-'}\``,
+      `- summary: ${cp.summary || '-'}`,
+      surface.actions && surface.actions.acceptRiskApi ? `- accept risk API: ${surface.actions.acceptRiskApi}` : null,
+      surface.actions && surface.actions.keepCommand ? `- keep command: \`${surface.actions.keepCommand}\`` : null,
+    ].filter(Boolean).join('\n');
+  }
+  if (surface.type === 'workflow_ui_command_result') {
+    return [
+      '## 命令结果',
+      '',
+      `- ok: \`${surface.ok === true ? 'true' : 'false'}\``,
+      `- slug: \`${surface.slug || '-'}\``,
+      '',
+      '```text',
+      surface.output || surface.error || '',
+      '```',
+    ].join('\n');
+  }
+  if (surface.type === 'workflow_selection_result_surface') {
+    return [
+      '## Workflow Selection Applied',
+      '',
+      `- slug: \`${surface.slug || '-'}\``,
+      `- next: \`${surface.nextAction || '-'}\``,
+    ].join('\n');
+  }
+  return `## ${surface.type || 'Unknown surface'}\n\n\`\`\`json\n${JSON.stringify(surface, null, 2)}\n\`\`\``;
+}
+
+function collectDefaultSelectedSteps(surface) {
+  const groups = surface.chatCard && surface.chatCard.selection && surface.chatCard.selection.groups;
+  const steps = [];
+  for (const group of groups || []) {
+    for (const item of group.items || []) {
+      if (item.selected === true || item.recommended === true || item.locked === true) steps.push(item.step);
+    }
+  }
+  return steps;
+}
+
+function hostLabel(host) {
+  if (host === 'codex') return 'Codex in-app browser';
+  if (host === 'cursor') return 'Cursor WebView';
+  if (host === 'cli') return 'CLI terminal';
+  if (host === 'browser') return 'Browser';
+  return host;
+}
+
+function hostRenderingNotes(host) {
+  if (host === 'codex') {
+    return 'Codex chat can show the Markdown fallback, then open the local URL in the Codex in-app browser for the interactive card.';
+  }
+  if (host === 'cursor') {
+    return 'Cursor can render the Markdown fallback in chat and embed the local URL in a WebView; without an extension, use the browser fallback.';
+  }
+  if (host === 'cli') {
+    return 'CLI hosts can print the Markdown fallback and ask the user to edit the JSON selection payload before POSTing it.';
+  }
+  return 'Browser hosts can open the local URL directly and call the listed API endpoints from the page.';
+}
+
+function formatWorkflowHostError(parsed) {
+  if (!parsed || typeof parsed !== 'object') return '';
+  const parts = [];
+  if (parsed.code) parts.push(String(parsed.code));
+  if (parsed.message) parts.push(String(parsed.message));
+  return parts.length ? `: ${parts.join(': ')}` : '';
+}
+
+function parseJsonOrRaw(text) {
+  try {
+    return text ? JSON.parse(text) : {};
+  } catch (_) {
+    return { raw: text };
+  }
+}
+
+function normalizeHostName(host) {
+  return String(host || 'browser').trim().toLowerCase();
+}
+
+module.exports = {
+  buildSelectionPayload,
+  collectDefaultSelectedSteps,
+  ensureCompatibleCatalog,
+  ensureCompatibleSurface,
+  recommendAdapterProfile,
+  renderCatalogExample,
+  renderHostExample,
+  renderSurfaceMarkdown,
+  submitSelection,
+};

package/src/core/workflow-actions.js

@@ -0,0 +1,25 @@
+'use strict';
+
+function workflowActions(slug) {
+  return {
+    picker: `devflow flow picker --slug=${slug} --json`,
+    applySelection: `devflow flow apply-selection --slug=${slug} --selection='<json>' --json`,
+    applySelectionFile: `devflow flow apply-selection --slug=${slug} --selection-file=<file> --json`,
+    card: `devflow flow card --slug=${slug} --json`,
+    check: `devflow flow check --slug=${slug} --json`,
+    confirm: `devflow flow confirm --slug=${slug}`,
+  };
+}
+
+function pickerActions(slug) {
+  return {
+    card: `devflow flow card --slug=${slug} --json`,
+    check: `devflow flow check --slug=${slug} --json`,
+    applySelection: `devflow flow apply-selection --slug=${slug} --selection=<json> --json`,
+    applySelectionFile: `devflow flow apply-selection --slug=${slug} --selection-file=<file> --json`,
+    confirm: `devflow flow confirm --slug=${slug}`,
+    suggest: `devflow flow suggest --slug=${slug} --apply-draft`,
+  };
+}
+
+module.exports = { workflowActions, pickerActions };

package/src/core/workflow-picker.js

@@ -2,6 +2,7 @@
 
 const workflow = require('./workflow.js');
 const workflowPolicy = require('./workflow-policy.js');
+const { pickerActions } = require('./workflow-actions.js');
 
 const GROUPS = [
   { id: 'core', label: '核心流程' },
@@ -48,6 +49,8 @@ function buildPicker(root, slug, st) {
       protected: false,
       source: 'builtin',
       status: 'available',
+      after: candidate.after || null,
+      before: candidate.before || null,
     }, {
       selected: false,
       recommended: riskReasons.has(candidate.id),
@@ -67,13 +70,7 @@ function buildPicker(root, slug, st) {
     status: wf.status || null,
     currentStep: wf.currentStep || null,
     groups,
-    actions: {
-      card: `devflow flow card --slug=${slug} --json`,
-      check: `devflow flow check --slug=${slug} --json`,
-      applySelection: `devflow flow apply-selection --slug=${slug} --selection=<json> --json`,
-      confirm: `devflow flow confirm --slug=${slug}`,
-      suggest: `devflow flow suggest --slug=${slug} --apply-draft`,
-    },
+    actions: pickerActions(slug),
   };
 }
 
@@ -94,6 +91,8 @@ function buildItem(root, slug, step, opts = {}) {
     locked,
     source: step.source || null,
     status: step.status || null,
+    after: step.after || null,
+    before: step.before || null,
     installed: workflow.installedSkillExists(root, step.skill),
     command: opts.command || commandForStep(slug, step, selected, locked),
   };
@@ -151,4 +150,13 @@ function itemOrder(item) {
   return idx === -1 ? order.length : idx;
 }
 
-module.exports = { buildPicker };
+function placementForCandidate(stepId) {
+  const candidate = QUALITY_CANDIDATES.find((item) => item.id === stepId || item.skill === stepId);
+  if (!candidate) return null;
+  return {
+    after: candidate.after || null,
+    before: candidate.before || null,
+  };
+}
+
+module.exports = { buildPicker, placementForCandidate };