@gong-ym/ai-spec-auto 0.2.3

package/internal/visual-hooks/config-loader.js

@@ -0,0 +1,218 @@
+/**
+ * Visual Config Loader
+ * 
+ * 功能：加载 .ai-spec/visual-config.json 配置文件
+ * 优先级：
+ * 1. .ai-spec/visual-config.json（项目级）
+ * 2. ~/.ai-spec/visual-config.json（用户级）
+ * 3. 环境变量覆盖
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * 加载 visual 配置
+ *
+ * 历史背景：项目里同时存在两份 visual 相关 JSON
+ *   - .ai-spec/visual-bridge.json（由 br-ai-spec CLI sync/init 自动生成，字段名：server_url / enabled / workspace_id / connect_token）
+ *   - .ai-spec/visual-config.json（早期 internal/visual-hooks 设计的独立配置，字段名：visual_url / enabled / workspace_id）
+ * 为避免用户必须维护两份配置，本 loader 同时识别两种文件并做字段映射：
+ *   visual-bridge.json.server_url ⇄ visual-config.json.visual_url
+ * 加载优先级（越靠前越高）：
+ *   1. 项目级 .ai-spec/visual-config.json（显式配置，向后兼容）
+ *   2. 项目级 .ai-spec/visual-bridge.json（CLI 自动产物，零配置默认值）
+ *   3. 用户级 ~/.ai-spec/visual-config.json
+ *   4. 环境变量覆盖（最终）
+ *
+ * @returns {VisualConfig | null}
+ */
+function loadVisualConfig(options = {}) {
+  const cwd = path.resolve(options.targetDir || process.cwd());
+  let configSource = null;
+
+  // 优先级 1: 项目级 visual-config.json（用户显式配置）
+  let config = loadConfigFromFile(path.join(cwd, '.ai-spec/visual-config.json'));
+  if (config) configSource = path.join(cwd, '.ai-spec/visual-config.json');
+
+  // 优先级 2: 项目级 visual-bridge.json（CLI 自动产物，自动映射字段名）
+  if (!config) {
+    const bridgeRaw = loadConfigFromFile(path.join(cwd, '.ai-spec/visual-bridge.json'));
+    if (bridgeRaw) {
+      config = mapBridgeStateToVisualConfig(bridgeRaw);
+      configSource = path.join(cwd, '.ai-spec/visual-bridge.json');
+    }
+  }
+
+  // 优先级 3: 用户级配置
+  if (!config) {
+    const userConfigPath = path.join(os.homedir(), '.ai-spec/visual-config.json');
+    config = loadConfigFromFile(userConfigPath);
+    if (config) configSource = userConfigPath;
+  }
+
+  if (!config) {
+    return null;
+  }
+
+  // 优先级 4: 环境变量覆盖
+  config = applyEnvironmentOverrides({
+    ...config,
+    target_dir: cwd,
+    config_source: configSource,
+  });
+
+  // 校验必填字段
+  if (!validateConfig(config)) {
+    console.warn('[visual-hooks] config validation failed');
+    return null;
+  }
+
+  return config;
+}
+
+/**
+ * 把 visual-bridge.json 的 schema 映射成 visual-hooks 期待的 VisualConfig schema
+ *
+ * @param {object} bridgeState
+ * @returns {VisualConfig | null}
+ */
+function mapBridgeStateToVisualConfig(bridgeState) {
+  if (!bridgeState || typeof bridgeState !== 'object') {
+    return null;
+  }
+  // 桥接状态文件里 enabled=false / server_url=null 都是合法状态，
+  // 但对 hooks 而言这就等于"未配置"，让 validateConfig 决定。
+  return {
+    enabled: bridgeState.enabled === true,
+    visual_url: bridgeState.server_url || null,
+    workspace_id: bridgeState.workspace_id || null,
+    workspace_name: bridgeState.workspace_name || null,
+    push_mode: 'hook',
+    push_timeout_ms: bridgeState.push_timeout_ms || 3000,
+    retry_times: bridgeState.retry_times != null ? bridgeState.retry_times : 1,
+    collector_schedule: null,
+    // 透传一些 hooks 可能要消费的桥接字段
+    connect_token: bridgeState.connect_token || null,
+    agent_id: bridgeState.agent_id || 'ai-spec-auto',
+    fail_open: bridgeState.fail_open !== false,
+  };
+}
+
+/**
+ * 从文件加载配置
+ * @param {string} filePath
+ * @returns {VisualConfig | null}
+ */
+function loadConfigFromFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const config = JSON.parse(content);
+    console.warn(`[visual-hooks] config loaded from: ${filePath}`);
+    return config;
+  } catch (err) {
+    console.warn(`[visual-hooks] failed to load config from ${filePath}:`, err.message);
+    return null;
+  }
+}
+
+/**
+ * 应用环境变量覆盖
+ * @param {VisualConfig} config
+ * @returns {VisualConfig}
+ */
+function applyEnvironmentOverrides(config) {
+  const overrides = { ...config };
+
+  if (process.env.AI_SPEC_VISUAL_ENABLED !== undefined) {
+    overrides.enabled = process.env.AI_SPEC_VISUAL_ENABLED === 'true';
+  }
+
+  if (process.env.AI_SPEC_VISUAL_URL) {
+    overrides.visual_url = process.env.AI_SPEC_VISUAL_URL;
+  }
+
+  if (process.env.AI_SPEC_VISUAL_WORKSPACE_ID) {
+    overrides.workspace_id = process.env.AI_SPEC_VISUAL_WORKSPACE_ID;
+  }
+
+  if (process.env.AI_SPEC_VISUAL_PUSH_TIMEOUT_MS) {
+    overrides.push_timeout_ms = parseInt(process.env.AI_SPEC_VISUAL_PUSH_TIMEOUT_MS, 10);
+  }
+
+  return overrides;
+}
+
+/**
+ * 校验配置
+ * @param {VisualConfig} config
+ * @returns {boolean}
+ */
+function validateConfig(config) {
+  if (!config.visual_url) {
+    console.warn('[visual-hooks] config missing: visual_url');
+    return false;
+  }
+
+  if (!config.workspace_id) {
+    console.warn('[visual-hooks] config missing: workspace_id');
+    return false;
+  }
+
+  // 校验 visual_url 格式
+  try {
+    new URL(config.visual_url);
+  } catch (err) {
+    console.warn('[visual-hooks] invalid visual_url:', config.visual_url);
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * 创建默认配置示例文件
+ * @param {string} targetPath
+ */
+function createConfigExample(targetPath) {
+  const exampleConfig = {
+    $schema: 'https://schemas.br-ai-spec.internal/visual-config.schema.json',
+    enabled: false,
+    visual_url: 'http://localhost:3000',
+    workspace_id: 'my-project',
+    workspace_name: '项目显示名称',
+    push_mode: 'hook',
+    push_timeout_ms: 3000,
+    retry_times: 1,
+    collector_schedule: null
+  };
+
+  try {
+    const dir = path.dirname(targetPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(
+      targetPath,
+      JSON.stringify(exampleConfig, null, 2),
+      'utf-8'
+    );
+
+    console.warn(`[visual-hooks] config example created: ${targetPath}`);
+    return true;
+  } catch (err) {
+    console.warn(`[visual-hooks] failed to create config example:`, err.message);
+    return false;
+  }
+}
+
+module.exports = {
+  loadVisualConfig,
+  createConfigExample
+};

package/internal/visual-hooks/control-puller.js

@@ -0,0 +1,206 @@
+/**
+ * Visual Control Puller
+ *
+ * 可选 HTTP 拉取：在 inbox-consumer 之前，先从 visual 拉取 pending 控制指令，
+ * 把响应转写成 .ai-spec/inbox/control-*.json 文件，统一交给 inbox-consumer 消费。
+ *
+ * 设计约束：
+ * - 仅使用 Node 内置（http/https/fs/path），零依赖
+ * - 严格短超时（默认 ≤ 800ms），任何错误必须静默
+ * - 仅在 visual-bridge.json 存在 enabled=true 且 inbox_transport != 'file-only' 时启用
+ */
+
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const path = require('path');
+const { URL } = require('url');
+
+const INBOX_DIR_REL = '.ai-spec/inbox';
+
+function safeReadJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch (_err) {
+    return null;
+  }
+}
+
+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 data;
+    }
+  }
+  return null;
+}
+
+function ensureDir(dir) {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (_err) {
+    // noop
+  }
+}
+
+function getServerUrl(bridge) {
+  return bridge?.server_url || bridge?.serverUrl || bridge?.visual_url || null;
+}
+
+function getWorkspaceId(bridge) {
+  return bridge?.workspace_id || bridge?.workspaceId || null;
+}
+
+function httpRequest({ url, method = 'GET', headers = {}, timeoutMs = 800, body = null }) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    const protocol = parsed.protocol === 'https:' ? https : http;
+    const req = protocol.request(
+      parsed,
+      {
+        method,
+        headers: {
+          'Accept': 'application/json',
+          'User-Agent': 'ai-spec-auto-control-puller/1.0',
+          ...headers,
+        },
+      },
+      (res) => {
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => {
+          const text = Buffer.concat(chunks).toString('utf-8');
+          if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+            resolve({ statusCode: res.statusCode, body: text });
+          } else {
+            reject(new Error(`HTTP ${res.statusCode}: ${text.slice(0, 200)}`));
+          }
+        });
+      },
+    );
+
+    const timer = setTimeout(() => {
+      req.destroy(new Error(`request timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    req.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    req.on('close', () => clearTimeout(timer));
+
+    if (body) {
+      req.write(typeof body === 'string' ? body : JSON.stringify(body));
+    }
+    req.end();
+  });
+}
+
+/**
+ * 拉取 pending 控制指令并落盘为 inbox 文件
+ * @param {{ targetDir: string, timeoutMs?: number }} opts
+ * @returns {Promise<{ pulled: number, written: number, transport: string, error?: string }>}
+ */
+async function pullPendingControls(opts = {}) {
+  const targetDir = opts.targetDir || process.cwd();
+  const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 800;
+
+  const bridge = loadBridgeConfig(targetDir);
+  if (!bridge || bridge.enabled === false) {
+    return { pulled: 0, written: 0, transport: 'disabled' };
+  }
+
+  const transport = bridge.inbox_transport || bridge.inboxTransport || 'http-pull';
+  if (transport === 'file-only' || transport === 'file-inbox') {
+    return { pulled: 0, written: 0, transport };
+  }
+
+  const serverUrl = getServerUrl(bridge);
+  const workspaceId = getWorkspaceId(bridge);
+  if (!serverUrl || !workspaceId) {
+    return { pulled: 0, written: 0, transport, error: 'missing server_url/workspace_id' };
+  }
+
+  const sinceFile = path.join(targetDir, INBOX_DIR_REL, '.last-pull.json');
+  ensureDir(path.dirname(sinceFile));
+  const since = safeReadJson(sinceFile)?.cursor || '';
+
+  let endpoint;
+  try {
+    endpoint = new URL('/api/control/pending', serverUrl);
+    endpoint.searchParams.set('workspace_id', workspaceId);
+    if (since) endpoint.searchParams.set('since', since);
+  } catch (err) {
+    return { pulled: 0, written: 0, transport, error: err.message };
+  }
+
+  let response;
+  try {
+    response = await httpRequest({
+      url: endpoint.toString(),
+      method: 'GET',
+      headers: bridge.connect_token ? { 'X-Connect-Token': bridge.connect_token } : {},
+      timeoutMs,
+    });
+  } catch (err) {
+    return { pulled: 0, written: 0, transport, error: err.message };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(response.body);
+  } catch (err) {
+    return { pulled: 0, written: 0, transport, error: `invalid JSON response: ${err.message}` };
+  }
+
+  const items = Array.isArray(parsed?.items) ? parsed.items : [];
+  if (items.length === 0) {
+    return { pulled: 0, written: 0, transport };
+  }
+
+  const inboxDir = path.join(targetDir, INBOX_DIR_REL);
+  ensureDir(inboxDir);
+
+  let written = 0;
+  let cursor = since;
+  for (const item of items) {
+    if (!item || typeof item !== 'object') continue;
+    const outboxId = item.outbox_id || item.id || `pull_${Date.now()}_${written}`;
+    const fileName = `control-${String(outboxId).replace(/[^a-zA-Z0-9_-]/g, '_')}.json`;
+    const target = path.join(inboxDir, fileName);
+    try {
+      fs.writeFileSync(target, `${JSON.stringify(item, null, 2)}\n`, 'utf-8');
+      written += 1;
+      if (item.created_at && (!cursor || item.created_at > cursor)) {
+        cursor = item.created_at;
+      }
+    } catch (_err) {
+      // 单个文件落盘失败不影响其他
+    }
+  }
+
+  if (cursor && cursor !== since) {
+    try {
+      fs.writeFileSync(sinceFile, JSON.stringify({ cursor, updated_at: new Date().toISOString() }, null, 2), 'utf-8');
+    } catch (_err) {
+      // noop
+    }
+  }
+
+  return { pulled: items.length, written, transport };
+}
+
+module.exports = {
+  pullPendingControls,
+};

package/internal/visual-hooks/gate-signal.js

@@ -0,0 +1,150 @@
+/**
+ * Visual Gate Signal（切面能力，绝不影响主链路）
+ *
+ * 用途：当 Visual 侧审批指令在 inbox-consumer 里被成功应用后，额外写一个
+ *      轻量的 `.ai-spec/gate-signal.json`，供 IDE 中的 AI（Cursor / Claude Code）
+ *      通过规则 / skill 轮询该文件实现"审批后原对话自动继续"。
+ *
+ * 设计约束：
+ * - 纯 Node 内置模块（fs / path / os），零 npm 依赖
+ * - 所有 IO 失败必须静默降级，只写 .ai-spec/logs/gate-signal.log，绝不抛
+ * - 原子写：先写 .tmp，再 rename，避免读侧读到半写文件
+ * - 不与 runtime-state / inbox-consumer 的任何返回值耦合
+ *
+ * 文件契约（schema_version=1）：
+ * {
+ *   "schema_version": 1,
+ *   "run_id": "run_2026xxxx",
+ *   "gate": "before-implementation",
+ *   "decision": "approved" | "rejected" | "resumed" | "request_changes",
+ *   "reason": "...optional...",
+ *   "actor_id": "...optional...",
+ *   "ts_ms": 1714000000000,
+ *   "ts_iso": "2026-04-23T..."
+ * }
+ *
+ * AI 读侧判定：signal.run_id === currentRunId 且 signal.gate === currentGate
+ * 且 signal.ts_ms > waitStartedAt 时才视为命中。错配一律忽略，避免陈旧信号误触发。
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SIGNAL_REL = '.ai-spec/gate-signal.json';
+const LOG_REL = '.ai-spec/logs/gate-signal.log';
+const SCHEMA_VERSION = 1;
+
+function ensureDir(dir) {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (_err) {
+    // noop
+  }
+}
+
+function logError(targetDir, phase, err) {
+  try {
+    const logPath = path.join(targetDir, LOG_REL);
+    ensureDir(path.dirname(logPath));
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      phase,
+      message: String(err?.message || err),
+    });
+    fs.appendFileSync(logPath, `${line}\n`, 'utf-8');
+  } catch (_err) {
+    // 真正的最后一道防线失败也必须吞掉
+  }
+}
+
+/**
+ * 写入 gate-signal.json（原子）。任何失败只写日志，绝不抛。
+ *
+ * @param {object} opts
+ * @param {string} opts.targetDir 项目根
+ * @param {string} opts.runId
+ * @param {string} opts.gate
+ * @param {'approved'|'rejected'|'resumed'|'request_changes'} opts.decision
+ * @param {string} [opts.reason]
+ * @param {string} [opts.actorId]
+ * @returns {{ ok: boolean, path?: string }}
+ */
+function writeGateSignal(opts) {
+  const targetDir = opts && opts.targetDir;
+  if (!targetDir || typeof targetDir !== 'string') {
+    return { ok: false };
+  }
+  const runId = opts.runId;
+  const gate = opts.gate;
+  const decision = opts.decision;
+  if (!runId || !gate || !decision) {
+    logError(targetDir, 'write.validate', new Error('missing runId/gate/decision'));
+    return { ok: false };
+  }
+
+  const now = Date.now();
+  const payload = {
+    schema_version: SCHEMA_VERSION,
+    run_id: String(runId),
+    gate: String(gate),
+    decision: String(decision),
+    reason: opts.reason ? String(opts.reason) : null,
+    actor_id: opts.actorId ? String(opts.actorId) : null,
+    ts_ms: now,
+    ts_iso: new Date(now).toISOString(),
+  };
+
+  const target = path.join(targetDir, SIGNAL_REL);
+  const tmp = `${target}.tmp-${process.pid}-${now}`;
+  try {
+    ensureDir(path.dirname(target));
+    fs.writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+    try {
+      fs.renameSync(tmp, target);
+    } catch (renameErr) {
+      try {
+        fs.copyFileSync(tmp, target);
+        fs.unlinkSync(tmp);
+      } catch (copyErr) {
+        logError(targetDir, 'write.rename', renameErr);
+        logError(targetDir, 'write.copy', copyErr);
+        return { ok: false };
+      }
+    }
+    return { ok: true, path: target };
+  } catch (err) {
+    logError(targetDir, 'write.writeFile', err);
+    try {
+      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+    } catch (_cleanupErr) {
+      // ignore
+    }
+    return { ok: false };
+  }
+}
+
+/**
+ * 读取 gate-signal.json（供排障或 skill 端本地验证用）。
+ * 损坏 / 不存在 → 返回 null，不抛。
+ */
+function readGateSignal(targetDir) {
+  if (!targetDir) return null;
+  const target = path.join(targetDir, SIGNAL_REL);
+  try {
+    const text = fs.readFileSync(target, 'utf-8');
+    const data = JSON.parse(text);
+    if (data && typeof data === 'object' && data.schema_version === SCHEMA_VERSION) {
+      return data;
+    }
+    return null;
+  } catch (_err) {
+    return null;
+  }
+}
+
+module.exports = {
+  writeGateSignal,
+  readGateSignal,
+  SIGNAL_REL,
+  SCHEMA_VERSION,
+};