@gong-ym/ai-spec-auto 0.2.3

package/internal/visual-hooks/inbox-consumer.js

@@ -0,0 +1,469 @@
+/**
+ * Visual Inbox Consumer
+ *
+ * 在 CLI 命令边界（protocol-step / -advance / -update / -status）以同步、超时短的方式
+ * 扫描 .ai-spec/inbox/ 下的控制指令文件并应用到本地 runtime-state，再把结果
+ * 通过 receipt-pusher 反向回报给 visual。
+ *
+ * 设计约束（见 plan）：
+ * - 仅使用 Node 内置模块（fs / path / crypto / os），零 npm 依赖
+ * - 所有失败必须静默降级，永不抛出阻断主流程
+ * - 超时硬限（默认 ≤ 50ms），保证不影响命令启动时延
+ * - 处理过的文件移入 .ai-spec/inbox/.processed/，带结果后缀
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const INBOX_DIR_REL = '.ai-spec/inbox';
+const PROCESSED_SUBDIR = '.processed';
+const APPLIED_SUBDIR = '.applied';
+const FAILED_SUBDIR = '.failed';
+
+const SUPPORTED_COMMANDS = new Set([
+  'approve_gate',
+  'reject_gate',
+  'resume_run',
+  'cancel_run',
+]);
+
+function safeReadJson(filePath) {
+  try {
+    const text = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(text);
+  } catch (_err) {
+    return null;
+  }
+}
+
+function ensureDir(dir) {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (_err) {
+    // noop
+  }
+}
+
+function loadBridgeConfig(targetDir) {
+  const candidates = [
+    path.join(targetDir, '.ai-spec/visual-bridge.json'),
+    path.join(targetDir, '.ai-spec/visual-config.json'),
+  ];
+  for (const file of candidates) {
+    const data = safeReadJson(file);
+    if (data && typeof data === 'object') {
+      return { source: file, data };
+    }
+  }
+  return null;
+}
+
+function verifySignature(message, signature, secret) {
+  if (!secret) {
+    return true; // 未配置 token 视为本地受信任环境，跳过校验
+  }
+  if (!signature || typeof signature !== 'string') {
+    return false;
+  }
+  try {
+    const expected = crypto
+      .createHmac('sha256', String(secret))
+      .update(typeof message === 'string' ? message : JSON.stringify(message))
+      .digest('hex');
+    if (expected.length !== signature.length) {
+      return false;
+    }
+    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
+  } catch (_err) {
+    return false;
+  }
+}
+
+function loadRuntimeState(targetDir) {
+  try {
+    const runtimeState = require('../../bin/runtime-state');
+    return runtimeState;
+  } catch (_err) {
+    return null;
+  }
+}
+
+/**
+ * 切面式写入：当 Visual 侧审批被成功应用后，往项目根 .ai-spec/next-step.md
+ * 追加一条人类可读的提示，供 IDE 里的 AI / 用户感知"已批准、请继续"。
+ *
+ * 设计原则：
+ * - 纯 additive，失败 silent 吞，绝不影响主 apply 链路
+ * - 只追加，不清空；保留审批历史
+ * - 通过结构化 marker 方便 AGENTS.md / Cursor slash 读取
+ */
+function appendNextStepHint(targetDir, command, payload, snapshot) {
+  try {
+    const file = path.join(targetDir, '.ai-spec', 'next-step.md');
+    ensureDir(path.dirname(file));
+    const ts = new Date().toISOString();
+    const gate = payload?.gate || snapshot?.pending_gate || 'unknown';
+    const runId = payload?.run_id || snapshot?.run_id || 'unknown';
+    const nextRole = snapshot?.current_role || payload?.next_role || 'unknown';
+    const recommend =
+      command === 'approve_gate' || command === 'resume_run'
+        ? '请在 IDE (Cursor / Claude Code) 执行 `/spec-continue` 继续下一步开发。'
+        : command === 'request_changes'
+          ? '请补齐资产后重新提交审批。'
+          : '请查看 visual 审批结果并在 IDE 按提示操作。';
+    const block = [
+      '',
+      `## [${ts}] ${command} applied`,
+      '',
+      `- run_id: \`${runId}\``,
+      `- gate: \`${gate}\``,
+      `- next_role: \`${nextRole}\``,
+      `- action: ${recommend}`,
+      '',
+      '<!-- visual-next-step:end -->',
+      '',
+    ].join('\n');
+
+    const header = fs.existsSync(file)
+      ? ''
+      : [
+          '# Visual 审批 → 下一步提示',
+          '',
+          '> 本文件由 `br-ai-spec` 的 visual-hooks 自动追加写入。',
+          '> 每当 visual 侧审批（approve_gate / resume_run）被成功应用到本地',
+          '> runtime-state 后，会在下方 append 一条记录。IDE 中的 AI 可读取',
+          '> 该文件作为"继续开发"的信号。本地手动推进或清理可直接删除此文件。',
+          '',
+        ].join('\n');
+
+    fs.appendFileSync(file, `${header}${block}`, 'utf-8');
+  } catch (_err) {
+    // silent — 这条提示是增值能力，失败绝不影响主链路
+  }
+}
+
+/**
+ * 切面式写入 gate-signal.json：为 IDE 侧 AI 轮询提供"审批已到达"的结构化信号。
+ * 所有失败静默吞掉，绝不影响 apply 主链路。
+ */
+function emitGateSignal(targetDir, command, payload, snapshot) {
+  try {
+    const normalizedDecision = String(payload?.decision || '').trim().toLowerCase();
+    const decision =
+      command === 'approve_gate'
+        ? 'approved'
+        : command === 'resume_run'
+          ? 'resumed'
+          : command === 'reject_gate'
+            ? normalizedDecision === 'request_changes' || normalizedDecision === 'request-changes'
+              ? 'request_changes'
+              : 'rejected'
+            : null;
+    if (!decision) return;
+    const { writeGateSignal } = require('./gate-signal');
+    writeGateSignal({
+      targetDir,
+      runId: payload?.run_id || snapshot?.run_id || null,
+      gate: payload?.gate || snapshot?.pending_gate || 'unknown',
+      decision,
+      reason: payload?.reason || payload?.decision || null,
+      actorId: payload?.requested_by || payload?.actor_id || null,
+    });
+  } catch (_err) {
+    // silent — 切面能力，任何异常都不允许冒泡影响 receipt 结果
+  }
+}
+
+function applyControl(targetDir, command, payload) {
+  const runtimeState = loadRuntimeState(targetDir);
+  if (!runtimeState) {
+    return { result: 'rejected', reason: 'runtime-state module unavailable' };
+  }
+
+  try {
+    if (command === 'approve_gate') {
+      const result = runtimeState.approveRunState({
+        target: targetDir,
+        gate: payload?.gate || null,
+        runId: payload?.run_id || null,
+        nextRole: payload?.next_role || null,
+        status: payload?.status || 'running',
+      });
+      const snapshot = {
+        status: result?.state?.status,
+        current_role: result?.state?.current_role,
+        run_id: result?.state?.run_id,
+      };
+      appendNextStepHint(targetDir, 'approve_gate', payload, snapshot);
+      emitGateSignal(targetDir, 'approve_gate', payload, snapshot);
+      return { result: 'applied', snapshot };
+    }
+
+    if (command === 'reject_gate') {
+      const state = safeReadJson(path.join(targetDir, '.ai-spec', 'current-run.json'));
+      if (!state?.run_id) {
+        return { result: 'conflict', reason: 'current run-state unavailable' };
+      }
+      const activeGate = state.pending_gate || null;
+      const requestedGate = payload?.gate || activeGate;
+      if (!activeGate) {
+        return { result: 'conflict', reason: 'No pending approval gate found' };
+      }
+      if (requestedGate && activeGate !== requestedGate) {
+        return {
+          result: 'conflict',
+          reason: `Pending gate mismatch: current is "${activeGate}", requested "${requestedGate}"`,
+        };
+      }
+      const decision = String(payload?.decision || '').trim().toLowerCase();
+      const isRequestChanges =
+        decision === 'request_changes' || decision === 'request-changes';
+      const reason = payload?.reason || payload?.decision || 'rejected by visual gate';
+      const result = runtimeState.gateBlockedRunState({
+        target: targetDir,
+        runId: payload?.run_id || state.run_id,
+        gate: activeGate,
+        pendingGate: activeGate,
+        status: 'waiting-approval',
+        fromRole: state.current_role || null,
+        toRole: state.current_role || null,
+        blockedByRole: state.current_role || state.gate_context?.blocked_by_role || null,
+        resumeToRole: state.gate_context?.resume_to_role || null,
+        requiredUserAction: isRequestChanges
+          ? `请先补齐资产或说明后重新提交审批。${reason ? ` 当前要求：${reason}` : ''}`.trim()
+          : state.gate_context?.required_user_action || '当前门禁已被拒绝，请修正后重新请求审批。',
+        blockedReason: isRequestChanges
+          ? `gate request_changes: ${reason}`
+          : `gate rejected: ${reason}`,
+        message: isRequestChanges
+          ? `gate request_changes: ${reason}`
+          : `gate rejected: ${reason}`,
+        eventType: isRequestChanges ? 'gate-request-changes' : 'gate-rejected',
+      });
+      const rejectSnapshot = {
+        status: result?.state?.status,
+        current_role: result?.state?.current_role,
+        pending_gate: result?.state?.pending_gate,
+        run_id: result?.state?.run_id,
+      };
+      if (isRequestChanges) {
+        appendNextStepHint(targetDir, 'request_changes', payload, rejectSnapshot);
+      }
+      emitGateSignal(targetDir, 'reject_gate', payload, rejectSnapshot);
+      return {
+        result: 'rejected',
+        reason,
+        snapshot: rejectSnapshot,
+      };
+    }
+
+    if (command === 'resume_run') {
+      const result = runtimeState.approveRunState({
+        target: targetDir,
+        gate: payload?.gate || null,
+        runId: payload?.run_id || null,
+        nextRole: payload?.next_role || payload?.resume_to_role || null,
+        status: 'running',
+      });
+      const snapshot = {
+        status: result?.state?.status,
+        current_role: result?.state?.current_role,
+        run_id: result?.state?.run_id,
+      };
+      appendNextStepHint(targetDir, 'resume_run', payload, snapshot);
+      emitGateSignal(targetDir, 'resume_run', payload, snapshot);
+      return { result: 'applied', snapshot };
+    }
+
+    if (command === 'cancel_run') {
+      // cancel_run 走轻量路径：只生成回执，不强制改写状态以避免与协议推进竞争。
+      return {
+        result: 'applied',
+        snapshot: { decision: 'cancel_requested', reason: payload?.reason || null },
+      };
+    }
+
+    return { result: 'rejected', reason: `unsupported command: ${command}` };
+  } catch (err) {
+    const msg = String(err?.message || err);
+    if (/No pending approval gate/.test(msg) || /Pending gate mismatch/.test(msg)) {
+      return { result: 'conflict', reason: msg };
+    }
+    return { result: 'rejected', reason: msg };
+  }
+}
+
+function moveFile(srcPath, destDir) {
+  ensureDir(destDir);
+  const base = path.basename(srcPath);
+  const dest = path.join(destDir, `${Date.now()}_${base}`);
+  try {
+    fs.renameSync(srcPath, dest);
+    return dest;
+  } catch (_err) {
+    try {
+      fs.copyFileSync(srcPath, dest);
+      fs.unlinkSync(srcPath);
+      return dest;
+    } catch (_err2) {
+      return null;
+    }
+  }
+}
+
+function listInboxFiles(inboxDir) {
+  if (!fs.existsSync(inboxDir)) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(inboxDir, { withFileTypes: true });
+  } catch (_err) {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isFile() && /^control-.*\.json$/.test(entry.name))
+    .map((entry) => path.join(inboxDir, entry.name))
+    .sort();
+}
+
+/**
+ * 消费 inbox 控制指令并产生 receipt 列表
+ *
+ * 完整生命周期（按顺序，每步都是 best-effort 静默失败）：
+ *   1. 可选 HTTP pull：从 visual 拉 pending 控制指令落盘到 inbox
+ *   2. 扫描 inbox 文件并应用到本地 runtime-state
+ *   3. 可选 HTTP push：把 receipts 回灌给 visual
+ *
+ * @param {{ targetDir: string, timeoutMs?: number, secret?: string, skipPull?: boolean, skipPush?: boolean }} opts
+ * @returns {Promise<{ processed: number, receipts: Array<object>, pulled?: number }>}
+ */
+async function consumeInbox(opts = {}) {
+  const targetDir = opts.targetDir || process.cwd();
+  const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 50;
+  const startedAt = Date.now();
+
+  const bridge = loadBridgeConfig(targetDir);
+  const secret =
+    opts.secret ||
+    bridge?.data?.control_secret ||
+    bridge?.data?.controlSecret ||
+    null;
+
+  let pulled = 0;
+  if (!opts.skipPull && bridge?.data?.enabled !== false) {
+    try {
+      const { pullPendingControls } = require('./control-puller');
+      const pullResult = await pullPendingControls({
+        targetDir,
+        timeoutMs: Math.max(50, Math.floor(timeoutMs * 4)),
+      });
+      pulled = pullResult?.written || 0;
+    } catch (_err) {
+      // pull 阶段失败不影响后续 inbox 消费
+    }
+  }
+
+  const inboxDir = path.join(targetDir, INBOX_DIR_REL);
+  if (!fs.existsSync(inboxDir)) {
+    return { processed: 0, receipts: [], pulled };
+  }
+
+  const files = listInboxFiles(inboxDir);
+  if (files.length === 0) {
+    return { processed: 0, receipts: [] };
+  }
+
+  const receipts = [];
+  let processed = 0;
+  const seenOutboxIds = new Set();
+
+  for (const file of files) {
+    if (Date.now() - startedAt > timeoutMs) {
+      break; // 超时优雅退出，剩余文件留待下一次命令边界处理
+    }
+
+    const envelope = safeReadJson(file);
+    if (!envelope || typeof envelope !== 'object') {
+      moveFile(file, path.join(inboxDir, FAILED_SUBDIR));
+      continue;
+    }
+
+    const {
+      outbox_id: outboxId,
+      command,
+      payload,
+      signature,
+    } = envelope;
+    const receiptKey = outboxId || path.basename(file);
+
+    if (seenOutboxIds.has(receiptKey)) {
+      moveFile(file, path.join(inboxDir, PROCESSED_SUBDIR));
+      continue;
+    }
+    seenOutboxIds.add(receiptKey);
+
+    let receipt = {
+      eventType: 'control.receipt',
+      outbox_id: receiptKey,
+      command: command || null,
+      result: 'rejected',
+      reason: null,
+      applied_state_snapshot: null,
+      received_at: new Date().toISOString(),
+    };
+
+    if (!command || !SUPPORTED_COMMANDS.has(command)) {
+      receipt.reason = `unsupported command: ${command}`;
+      moveFile(file, path.join(inboxDir, FAILED_SUBDIR));
+      receipts.push(receipt);
+      processed += 1;
+      continue;
+    }
+
+    const signed = verifySignature(
+      { outbox_id: outboxId, command, payload },
+      signature,
+      secret,
+    );
+    if (!signed) {
+      receipt.reason = 'signature verification failed';
+      moveFile(file, path.join(inboxDir, FAILED_SUBDIR));
+      receipts.push(receipt);
+      processed += 1;
+      continue;
+    }
+
+    const applyResult = applyControl(targetDir, command, payload || {});
+    receipt.result = applyResult.result;
+    receipt.reason = applyResult.reason || null;
+    receipt.applied_state_snapshot = applyResult.snapshot || null;
+
+    const destDir = applyResult.result === 'applied'
+      ? path.join(inboxDir, APPLIED_SUBDIR)
+      : path.join(inboxDir, PROCESSED_SUBDIR);
+    moveFile(file, destDir);
+
+    receipts.push(receipt);
+    processed += 1;
+  }
+
+  if (!opts.skipPush && receipts.length > 0 && bridge?.data?.enabled !== false) {
+    try {
+      const { pushReceipts } = require('./receipt-pusher');
+      await pushReceipts({
+        targetDir,
+        receipts,
+        timeoutMs: Math.max(200, Math.floor(timeoutMs * 8)),
+      });
+    } catch (_err) {
+      // 推送失败不影响本地 inbox 已正常处理的事实
+    }
+  }
+
+  return { processed, receipts, pulled };
+}
+
+module.exports = {
+  consumeInbox,
+  INBOX_DIR_REL,
+};

package/internal/visual-hooks/index.js

@@ -0,0 +1,197 @@
+/**
+ * Visual Hooks - 切面式数据推送入口
+ * 
+ * 功能：在 ai-spec-auto 协议推进的关键节点推送数据到 visual 服务
+ * 设计原则：
+ * - 零侵入：不修改现有协议逻辑
+ * - 优雅降级：visual 不可用时自动降级，不影响主流程
+ * - 配置驱动：通过 .ai-spec/visual-config.json 控制启用与否
+ */
+
+const { loadVisualConfig } = require('./config-loader');
+const { createPushClient } = require('./push-client');
+
+let visualHooks = null;
+let initError = null;
+
+/**
+ * 初始化 visual hooks
+ * @returns {VisualHooks | null} hooks 对象，如果未启用则返回 null
+ */
+function initVisualHooks(options = {}) {
+  // 避免重复初始化
+  const targetDir = options.targetDir ? require('path').resolve(options.targetDir) : null;
+  if (visualHooks !== null && (!targetDir || visualHooks.config.target_dir === targetDir)) {
+    return visualHooks;
+  }
+
+  try {
+    const config = loadVisualConfig({ targetDir });
+    
+    if (!config?.enabled || !config?.visual_url) {
+      console.warn('[visual-hooks] disabled or not configured');
+      visualHooks = null;
+      return null;
+    }
+
+    console.warn('[visual-hooks] initializing with config:', {
+      visual_url: config.visual_url,
+      workspace_id: config.workspace_id,
+      push_mode: config.push_mode
+    });
+
+    const client = createPushClient(config);
+
+    visualHooks = {
+      /**
+       * Hook: run 启动时
+       * 触发点: protocol-step 命令入口
+       */
+      onRunStart: async (runId, workspaceId, input) => {
+        try {
+          await client.push({
+            eventType: 'run.started',
+            runId,
+            workspaceId,
+            payload: {
+              run_id: runId,
+              workspace_id: workspaceId,
+              input,
+              started_at: new Date().toISOString()
+            }
+          });
+          console.warn(`[visual-hooks] onRunStart pushed: ${runId}`);
+          return {
+            ok: true,
+            eventType: 'run.started',
+            runId,
+            workspaceId,
+          };
+        } catch (err) {
+          console.warn('[visual-hooks] onRunStart failed:', err.message);
+          return {
+            ok: false,
+            eventType: 'run.started',
+            runId,
+            workspaceId,
+            error: err.message,
+          };
+        }
+      },
+
+      /**
+       * Hook: run 状态变更时
+       * 触发点: expert-executor 执行完专家后
+       */
+      onRunStateChange: async (runState) => {
+        try {
+          await client.push({
+            eventType: 'run.state_changed',
+            runId: runState.run_id,
+            workspaceId: runState.workspace_id,
+            payload: runState
+          });
+          console.warn(`[visual-hooks] onRunStateChange pushed: ${runState.run_id}`);
+          return {
+            ok: true,
+            eventType: 'run.state_changed',
+            runId: runState.run_id,
+            workspaceId: runState.workspace_id,
+          };
+        } catch (err) {
+          console.warn('[visual-hooks] onRunStateChange failed:', err.message);
+          return {
+            ok: false,
+            eventType: 'run.state_changed',
+            runId: runState.run_id,
+            workspaceId: runState.workspace_id,
+            error: err.message,
+          };
+        }
+      },
+
+      /**
+       * Hook: 归档完成时
+       * 触发点: archive-change 完成归档后
+       */
+      onArchiveComplete: async (archiveResult) => {
+        try {
+          await client.push({
+            eventType: 'run.archived',
+            runId: archiveResult.run_id,
+            workspaceId: archiveResult.workspace_id,
+            payload: {
+              ...archiveResult,
+              archived_at: new Date().toISOString()
+            }
+          });
+          console.warn(`[visual-hooks] onArchiveComplete pushed: ${archiveResult.run_id}`);
+          return {
+            ok: true,
+            eventType: 'run.archived',
+            runId: archiveResult.run_id,
+            workspaceId: archiveResult.workspace_id,
+          };
+        } catch (err) {
+          console.warn('[visual-hooks] onArchiveComplete failed:', err.message);
+          return {
+            ok: false,
+            eventType: 'run.archived',
+            runId: archiveResult.run_id,
+            workspaceId: archiveResult.workspace_id,
+            error: err.message,
+          };
+        }
+      },
+
+      /**
+       * 配置信息（只读）
+       */
+      config: {
+        visual_url: config.visual_url,
+        workspace_id: config.workspace_id,
+        enabled: config.enabled,
+        target_dir: config.target_dir,
+        config_source: config.config_source || null,
+      }
+    };
+
+    return visualHooks;
+  } catch (err) {
+    console.warn('[visual-hooks] initialization failed:', err.message);
+    initError = err;
+    visualHooks = null;
+    return null;
+  }
+}
+
+/**
+ * 获取当前 hooks 实例（不触发初始化）
+ * @returns {VisualHooks | null}
+ */
+function getVisualHooks() {
+  return visualHooks;
+}
+
+/**
+ * 获取初始化错误（用于调试）
+ * @returns {Error | null}
+ */
+function getInitError() {
+  return initError;
+}
+
+/**
+ * 重置 hooks（用于测试）
+ */
+function resetVisualHooks() {
+  visualHooks = null;
+  initError = null;
+}
+
+module.exports = {
+  initVisualHooks,
+  getVisualHooks,
+  getInitError,
+  resetVisualHooks
+};