agentquad 0.3.2 → 0.4.1

package/src/cursor-hook-installer.js

@@ -0,0 +1,296 @@
+/**
+ * Cursor Agent CLI hooks 安装器：
+ *   - 把 hook entry 合并写入 `~/.cursor/hooks.json`，不破坏用户现有 hook
+ *   - 写 `"version": 1` 协议头（Cursor 1.7+ 要求）
+ *
+ * Cursor 事件：stop（turn end）/ beforeSubmitPrompt（等用户）/ sessionEnd
+ *
+ * 合并策略：
+ *   - 已有 hooks.<event> 数组 → append；不删除已有 entry
+ *   - AgentQuad 加的 entry 用 `_agentquadManaged: true` 标记
+ *   - hooks.json 不存在 → 创建（带 version:1）
+ *   - hooks.json 损坏 → warn-skip
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { DEFAULT_ROOT_DIR } from './config.js'
+
+const MANAGED_KEY = '_agentquadManaged'
+const HOOK_EVENTS = ['stop', 'beforeSubmitPrompt', 'sessionEnd']
+const HOOK_VERSION_RE = /quadtodo-hook-version:\s*(\d+)/
+const SCHEMA_VERSION = 1
+
+function defaultHookScriptPath() {
+  return join(DEFAULT_ROOT_DIR, 'cursor-hooks', 'notify.js')
+}
+
+function defaultHooksJsonPath() {
+  return join(homedir(), '.cursor', 'hooks.json')
+}
+
+function defaultTemplatePath() {
+  return fileURLToPath(new URL('./templates/cursor-hooks/notify.js', import.meta.url))
+}
+
+function defaultUninstallMarkerPath() {
+  return join(DEFAULT_ROOT_DIR, 'cursor-hooks', '.uninstalled')
+}
+
+function parseHookVersion(content) {
+  if (!content) return null
+  const m = content.match(HOOK_VERSION_RE)
+  return m ? Number(m[1]) : 0
+}
+
+function eventToArg(event) {
+  if (event === 'beforeSubmitPrompt') return 'notification'
+  if (event === 'sessionEnd') return 'session-end'
+  return 'stop'
+}
+
+function buildHookEntry(event, hookScriptPath) {
+  // Cursor 的 hook entry 是扁平的 object（不像 Claude 的 matcher+hooks 嵌套）
+  return {
+    type: 'command',
+    command: `node ${hookScriptPath} ${eventToArg(event)}`,
+    timeout: 30,
+    [MANAGED_KEY]: true,
+  }
+}
+
+function loadHooksJson(path) {
+  if (!existsSync(path)) return { version: SCHEMA_VERSION }
+  const raw = readFileSync(path, 'utf8')
+  try {
+    return JSON.parse(raw)
+  } catch (e) {
+    const err = new Error(`cursor hooks.json malformed: ${e.message}`)
+    err.code = 'malformed_hooks_json'
+    err.path = path
+    throw err
+  }
+}
+
+function saveHooksJson(path, data) {
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n')
+}
+
+function backupFile(path) {
+  if (!existsSync(path)) return null
+  const bak = `${path}.bak.${Date.now()}`
+  copyFileSync(path, bak)
+  return bak
+}
+
+export function installHooks({
+  hooksPath = defaultHooksJsonPath(),
+  hookScriptPath = defaultHookScriptPath(),
+  events = HOOK_EVENTS,
+  uninstallMarkerPath = defaultUninstallMarkerPath(),
+  clearUninstallMarker = true,
+} = {}) {
+  if (!existsSync(hookScriptPath)) {
+    const err = new Error(`hook script not found: ${hookScriptPath}`)
+    err.code = 'hook_script_missing'
+    throw err
+  }
+
+  const data = loadHooksJson(hooksPath)
+  const backup = backupFile(hooksPath)
+  if (!data.version) data.version = SCHEMA_VERSION
+  if (!data.hooks || typeof data.hooks !== 'object') data.hooks = {}
+
+  const added = []
+  for (const event of events) {
+    if (!Array.isArray(data.hooks[event])) data.hooks[event] = []
+    data.hooks[event] = data.hooks[event].filter((entry) => !entry?.[MANAGED_KEY])
+    data.hooks[event].push(buildHookEntry(event, hookScriptPath))
+    added.push(event)
+  }
+
+  saveHooksJson(hooksPath, data)
+  let markerCleared = false
+  if (clearUninstallMarker && existsSync(uninstallMarkerPath)) {
+    try { unlinkSync(uninstallMarkerPath); markerCleared = true } catch { /* ignore */ }
+  }
+  return { hooksPath, backup, added, skipped: [], markerCleared }
+}
+
+export function uninstallHooks({
+  hooksPath = defaultHooksJsonPath(),
+  uninstallMarkerPath = defaultUninstallMarkerPath(),
+  writeUninstallMarker = true,
+} = {}) {
+  let markerWritten = false
+  const writeMarker = () => {
+    if (!writeUninstallMarker) return
+    try {
+      const dir = dirname(uninstallMarkerPath)
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+      writeFileSync(uninstallMarkerPath, `${new Date().toISOString()}\n`)
+      markerWritten = true
+    } catch { /* ignore */ }
+  }
+
+  if (!existsSync(hooksPath)) {
+    writeMarker()
+    return { hooksPath, removed: [], backup: null, markerWritten }
+  }
+
+  const data = loadHooksJson(hooksPath)
+  const backup = backupFile(hooksPath)
+  const removed = []
+
+  if (data.hooks && typeof data.hooks === 'object') {
+    for (const event of Object.keys(data.hooks)) {
+      if (!Array.isArray(data.hooks[event])) continue
+      const before = data.hooks[event].length
+      data.hooks[event] = data.hooks[event].filter((entry) => !entry?.[MANAGED_KEY])
+      if (data.hooks[event].length !== before) {
+        removed.push({ event, removedCount: before - data.hooks[event].length })
+      }
+      if (data.hooks[event].length === 0) delete data.hooks[event]
+    }
+    if (Object.keys(data.hooks).length === 0) delete data.hooks
+  }
+
+  saveHooksJson(hooksPath, data)
+  writeMarker()
+  return { hooksPath, removed, backup, markerWritten }
+}
+
+export function inspectHooks({
+  hooksPath = defaultHooksJsonPath(),
+  hookScriptPath = defaultHookScriptPath(),
+} = {}) {
+  const scriptExists = existsSync(hookScriptPath)
+  if (!existsSync(hooksPath)) {
+    return { installed: false, eventsInstalled: [], hooksPath, hookScriptPath, scriptExists }
+  }
+  let data
+  try {
+    data = loadHooksJson(hooksPath)
+  } catch (e) {
+    return { installed: false, eventsInstalled: [], hooksPath, hookScriptPath, scriptExists, error: e.code }
+  }
+  const eventsInstalled = []
+  for (const event of HOOK_EVENTS) {
+    const arr = data?.hooks?.[event]
+    if (!Array.isArray(arr)) continue
+    if (arr.some((entry) => entry?.[MANAGED_KEY])) eventsInstalled.push(event)
+  }
+  return {
+    installed: eventsInstalled.length === HOOK_EVENTS.length,
+    eventsInstalled,
+    hooksPath,
+    hookScriptPath,
+    scriptExists,
+  }
+}
+
+export function deployHookScript({
+  scriptPath = defaultHookScriptPath(),
+  templatePath = defaultTemplatePath(),
+} = {}) {
+  if (!existsSync(templatePath)) {
+    const err = new Error(`hook template not found: ${templatePath}`)
+    err.code = 'hook_template_missing'
+    throw err
+  }
+  const templateContent = readFileSync(templatePath, 'utf8')
+  const templateVersion = parseHookVersion(templateContent)
+
+  const dir = dirname(scriptPath)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+
+  const previousVersion = existsSync(scriptPath)
+    ? parseHookVersion(readFileSync(scriptPath, 'utf8'))
+    : null
+
+  if (previousVersion !== null && previousVersion === templateVersion) {
+    return { action: 'unchanged', version: templateVersion, previousVersion, scriptPath, backup: null }
+  }
+
+  let backup = null
+  if (previousVersion !== null) {
+    backup = `${scriptPath}.bak.${Date.now()}`
+    copyFileSync(scriptPath, backup)
+  }
+  writeFileSync(scriptPath, templateContent)
+  return {
+    action: previousVersion === null ? 'installed' : 'upgraded',
+    version: templateVersion,
+    previousVersion,
+    scriptPath,
+    backup,
+  }
+}
+
+export function bootstrapCursorHooks({
+  hooksPath = defaultHooksJsonPath(),
+  scriptPath = defaultHookScriptPath(),
+  templatePath = defaultTemplatePath(),
+  uninstallMarkerPath = defaultUninstallMarkerPath(),
+  respectUninstallMarker = true,
+} = {}) {
+  if (respectUninstallMarker && existsSync(uninstallMarkerPath)) {
+    return { skipped: true, reason: 'uninstall_marker', uninstallMarkerPath }
+  }
+
+  let markerCleared = false
+  if (!respectUninstallMarker && existsSync(uninstallMarkerPath)) {
+    try { unlinkSync(uninstallMarkerPath); markerCleared = true } catch { /* ignore */ }
+  }
+
+  const scriptResult = deployHookScript({ scriptPath, templatePath })
+
+  const inspect = inspectHooks({ hooksPath, hookScriptPath: scriptPath })
+  if (inspect.error === 'malformed_hooks_json') {
+    return {
+      skipped: true,
+      reason: 'malformed_hooks_json',
+      hooksPath,
+      scriptResult,
+      markerCleared,
+    }
+  }
+
+  if (inspect.installed) {
+    return {
+      skipped: false,
+      alreadyInstalled: true,
+      scriptResult,
+      hookResult: null,
+      markerCleared,
+    }
+  }
+
+  const hookResult = installHooks({
+    hooksPath,
+    hookScriptPath: scriptPath,
+    uninstallMarkerPath,
+    clearUninstallMarker: false,
+  })
+  return {
+    skipped: false,
+    alreadyInstalled: false,
+    scriptResult,
+    hookResult,
+    markerCleared,
+  }
+}
+
+export const __test__ = {
+  buildHookEntry,
+  MANAGED_KEY,
+  HOOK_EVENTS,
+  SCHEMA_VERSION,
+  parseHookVersion,
+  eventToArg,
+  defaultTemplatePath,
+  defaultUninstallMarkerPath,
+}

package/src/templates/codex-hooks/notify.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// quadtodo-hook-version: 2
+/**
+ * AgentQuad Claude Code hook —— 把 PTY 内 Claude Code 的状态事件转推到微信。
+ *
+ * 调用约定：
+ *   - argv[2] = 事件名: stop | notification | session-end
+ *   - stdin = Claude Code 注入的 hook payload（JSON 文本，可空）
+ *   - env: QUADTODO_SESSION_ID  (空 = 非 AgentQuad 启动的 Claude Code，立刻 exit 0)
+ *          QUADTODO_TARGET_USER (微信 peer id)
+ *          QUADTODO_TODO_ID
+ *          QUADTODO_TODO_TITLE
+ *
+ * 故障策略：失败一律静默。这个脚本绝不能阻塞 Claude Code。
+ * - 没注 env → 仍然记日志（"no env"），exit 0
+ * - AgentQuad 没起 / 网络失败 → catch 后记日志，exit 0
+ * - JSON 解析失败 → 当作空 payload 继续
+ *
+ * Debug log: 写到 ~/.agentquad/claude-hooks/hook.log，记每次 fire。
+ * 这样能 100% 区分"hook 没 fire" vs "fire 了但 AgentQuad 没收到"。
+ *
+ * 这个文件是模板源；安装器会拷贝到 ~/.agentquad/claude-hooks/notify.js。
+ * 顶部 `quadtodo-hook-version` 行用于版本比对，升级 AgentQuad 时会自动覆盖旧脚本（带备份）。
+ * 注意：脚本独立运行（不能 import config.js）。LOG_PATH 用 import.meta.url 派生，
+ * 跟随脚本所在目录，自动适配 ~/.agentquad / ~/.quadtodo（legacy）。
+ */
+import { appendFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const LOG_PATH = join(dirname(fileURLToPath(import.meta.url)), 'hook.log')
+
+function logLine(obj) {
+  try {
+    appendFileSync(LOG_PATH, JSON.stringify({ ts: new Date().toISOString(), ...obj }) + '\n', 'utf8')
+  } catch { /* ignore — log 失败也不能阻塞 */ }
+}
+
+const event = (process.argv[2] || 'unknown').toLowerCase()
+const SESSION_ID = process.env.QUADTODO_SESSION_ID
+if (!SESSION_ID) {
+  logLine({ event, status: 'skipped_no_env', argv: process.argv.slice(2) })
+  process.exit(0)
+}
+
+const QUADTODO_URL = process.env.QUADTODO_URL || 'http://127.0.0.1:5677'
+const ENDPOINT = `${QUADTODO_URL}/api/openclaw/hook`
+logLine({ event, status: 'fired', sessionId: SESSION_ID, todoTitle: process.env.QUADTODO_TODO_TITLE })
+
+let raw = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (chunk) => {
+  raw += chunk
+  // 防止超大 payload 把这个进程占内存
+  if (raw.length > 64 * 1024) raw = raw.slice(0, 64 * 1024)
+})
+process.stdin.on('end', send)
+// 没有 stdin 也要发（例如 SessionEnd 可能不带 payload）
+setTimeout(() => { if (!sent) send() }, 1500).unref?.()
+
+let sent = false
+async function send() {
+  if (sent) return
+  sent = true
+
+  let hookPayload = null
+  if (raw.trim()) {
+    try { hookPayload = JSON.parse(raw) } catch { hookPayload = { _raw: raw.slice(0, 240) } }
+  }
+
+  const body = JSON.stringify({
+    event,
+    sessionId: SESSION_ID,
+    targetUserId: process.env.QUADTODO_TARGET_USER || null,
+    todoId: process.env.QUADTODO_TODO_ID || null,
+    todoTitle: process.env.QUADTODO_TODO_TITLE || null,
+    hookPayload,
+  })
+
+  try {
+    // 30s timeout：openclaw CLI shell-out 实测 4-6s，留足余量；
+    // Claude Code 默认等 hook 60s，所以 30s 安全。
+    const ctrl = new AbortController()
+    const timer = setTimeout(() => ctrl.abort(), 30_000)
+    timer.unref?.()
+    const res = await fetch(ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body,
+      signal: ctrl.signal,
+    })
+    clearTimeout(timer)
+    if (res.ok) {
+      const data = await res.json().catch(() => null)
+      logLine({ event, status: 'sent', sessionId: SESSION_ID, action: data?.action, reason: data?.reason })
+    } else {
+      const text = await res.text().catch(() => '')
+      logLine({ event, status: 'http_error', code: res.status, body: text.slice(0, 200) })
+    }
+  } catch (e) {
+    logLine({ event, status: 'fetch_error', error: e?.message || String(e) })
+  }
+}

package/src/templates/cursor-hooks/notify.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// quadtodo-hook-version: 2
+/**
+ * AgentQuad Claude Code hook —— 把 PTY 内 Claude Code 的状态事件转推到微信。
+ *
+ * 调用约定：
+ *   - argv[2] = 事件名: stop | notification | session-end
+ *   - stdin = Claude Code 注入的 hook payload（JSON 文本，可空）
+ *   - env: QUADTODO_SESSION_ID  (空 = 非 AgentQuad 启动的 Claude Code，立刻 exit 0)
+ *          QUADTODO_TARGET_USER (微信 peer id)
+ *          QUADTODO_TODO_ID
+ *          QUADTODO_TODO_TITLE
+ *
+ * 故障策略：失败一律静默。这个脚本绝不能阻塞 Claude Code。
+ * - 没注 env → 仍然记日志（"no env"），exit 0
+ * - AgentQuad 没起 / 网络失败 → catch 后记日志，exit 0
+ * - JSON 解析失败 → 当作空 payload 继续
+ *
+ * Debug log: 写到 ~/.agentquad/claude-hooks/hook.log，记每次 fire。
+ * 这样能 100% 区分"hook 没 fire" vs "fire 了但 AgentQuad 没收到"。
+ *
+ * 这个文件是模板源；安装器会拷贝到 ~/.agentquad/claude-hooks/notify.js。
+ * 顶部 `quadtodo-hook-version` 行用于版本比对，升级 AgentQuad 时会自动覆盖旧脚本（带备份）。
+ * 注意：脚本独立运行（不能 import config.js）。LOG_PATH 用 import.meta.url 派生，
+ * 跟随脚本所在目录，自动适配 ~/.agentquad / ~/.quadtodo（legacy）。
+ */
+import { appendFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const LOG_PATH = join(dirname(fileURLToPath(import.meta.url)), 'hook.log')
+
+function logLine(obj) {
+  try {
+    appendFileSync(LOG_PATH, JSON.stringify({ ts: new Date().toISOString(), ...obj }) + '\n', 'utf8')
+  } catch { /* ignore — log 失败也不能阻塞 */ }
+}
+
+const event = (process.argv[2] || 'unknown').toLowerCase()
+const SESSION_ID = process.env.QUADTODO_SESSION_ID
+if (!SESSION_ID) {
+  logLine({ event, status: 'skipped_no_env', argv: process.argv.slice(2) })
+  process.exit(0)
+}
+
+const QUADTODO_URL = process.env.QUADTODO_URL || 'http://127.0.0.1:5677'
+const ENDPOINT = `${QUADTODO_URL}/api/openclaw/hook`
+logLine({ event, status: 'fired', sessionId: SESSION_ID, todoTitle: process.env.QUADTODO_TODO_TITLE })
+
+let raw = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (chunk) => {
+  raw += chunk
+  // 防止超大 payload 把这个进程占内存
+  if (raw.length > 64 * 1024) raw = raw.slice(0, 64 * 1024)
+})
+process.stdin.on('end', send)
+// 没有 stdin 也要发（例如 SessionEnd 可能不带 payload）
+setTimeout(() => { if (!sent) send() }, 1500).unref?.()
+
+let sent = false
+async function send() {
+  if (sent) return
+  sent = true
+
+  let hookPayload = null
+  if (raw.trim()) {
+    try { hookPayload = JSON.parse(raw) } catch { hookPayload = { _raw: raw.slice(0, 240) } }
+  }
+
+  const body = JSON.stringify({
+    event,
+    sessionId: SESSION_ID,
+    targetUserId: process.env.QUADTODO_TARGET_USER || null,
+    todoId: process.env.QUADTODO_TODO_ID || null,
+    todoTitle: process.env.QUADTODO_TODO_TITLE || null,
+    hookPayload,
+  })
+
+  try {
+    // 30s timeout：openclaw CLI shell-out 实测 4-6s，留足余量；
+    // Claude Code 默认等 hook 60s，所以 30s 安全。
+    const ctrl = new AbortController()
+    const timer = setTimeout(() => ctrl.abort(), 30_000)
+    timer.unref?.()
+    const res = await fetch(ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body,
+      signal: ctrl.signal,
+    })
+    clearTimeout(timer)
+    if (res.ok) {
+      const data = await res.json().catch(() => null)
+      logLine({ event, status: 'sent', sessionId: SESSION_ID, action: data?.action, reason: data?.reason })
+    } else {
+      const text = await res.text().catch(() => '')
+      logLine({ event, status: 'http_error', code: res.status, body: text.slice(0, 200) })
+    }
+  } catch (e) {
+    logLine({ event, status: 'fetch_error', error: e?.message || String(e) })
+  }
+}