@cocorograph/hub-agent 0.6.87 → 0.6.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocorograph/hub-agent",
-  "version": "0.6.87",
+  "version": "0.6.89",
   "description": "Hub Hosted Cockpit のローカル常駐 agent。Hub と outbound WSS で接続し、ローカルの tmux/pty を中継する。",
   "type": "module",
   "license": "UNLICENSED",

package/src/claude-md-sync.mjs

@@ -0,0 +1,361 @@
+/**
+ * Hub 正本 (Project.claude_md) と workspace ローカル CLAUDE.md の双方向同期。
+ *
+ * 方針: 双方向 last-write-wins + 履歴。
+ * - Hub 側更新 → 端末 pull（ローカルを `.bak.<ts>` 退避してから全文上書き）
+ * - 端末側更新 → Hub に PUT（Hub 側は履歴に直前版を積む。directly handled by backend）
+ * - 両方変化（衝突）→ 端末側を勝者にして Hub に PUT、Hub の取り込み内容は
+ *   `.bak.conflict.<ts>` に退避（後で人手マージできるよう保存）
+ * - どちらも変化なし → no-op
+ *
+ * 初回（メタファイル無し）:
+ * - ローカル CLAUDE.md が空 → pull（Hub の正本をそのまま受け取り）
+ * - ローカル非空 + Hub 非空 → 衝突扱い（端末側勝者）
+ * - ローカル非空 + Hub 空 → no-op（Hub に空を上書きしない、Stage 3 で初期化検討）
+ *
+ * 失敗時のポリシー: ローカル CLAUDE.md は触らない（warn ログ + skip）。
+ * session 起動を止めない（ensureClaudeMd と同じく best-effort）。
+ *
+ * 関連: backend Stage 1 / 1.5
+ *   GET /api/admin/project/claude-md-by-dir/?dir_name=...
+ *   PUT /api/admin/project/claude-md-by-dir/?dir_name=...  body: { claude_md }
+ */
+import fs from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import crypto from "node:crypto"
+
+const DEFAULT_HUB_API = "https://api.hub.cocorograph.com"
+const TOKEN_PATH = path.join(os.homedir(), ".claude", ".hub_token.json")
+const META_DIR = ".cockpit-sync"
+const META_FILE = "claude-md.json"
+const BAK_KEEP = 3 // 通常 .bak と衝突 .bak それぞれ直近 3 件まで保持
+
+async function readJsonOrNull(p) {
+  try {
+    const text = await fs.readFile(p, "utf-8")
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}
+
+async function loadAccessToken() {
+  const data = await readJsonOrNull(TOKEN_PATH)
+  return (data && typeof data.access === "string" && data.access) || null
+}
+
+function sha256(s) {
+  return crypto.createHash("sha256").update(s || "", "utf-8").digest("hex")
+}
+
+function nowIso() {
+  return new Date().toISOString()
+}
+
+function makeBakName(prefix) {
+  // ファイル名に使えるよう : を - に置換し、ミリ秒精度を保つ。
+  const ts = nowIso().replace(/[:.]/g, "-")
+  return `${prefix}.${ts}.bak`
+}
+
+/**
+ * Hub から claude-md-by-dir で正本を取得する。
+ *
+ * - 404 = 該当 Project 無し（Domain 型・local_dir 型 workspace）→ null
+ * - その他のエラー → null（warn ログ）
+ *
+ * @returns {Promise<null | {project_id, claude_md, claude_md_hash, claude_md_updated_at}>}
+ */
+async function fetchHubClaudeMd({ hubUrl, accessToken, dirName, fetchImpl, logger }) {
+  const f = fetchImpl || globalThis.fetch
+  if (!f) return null
+  const url =
+    `${hubUrl.replace(/\/+$/, "")}/api/admin/project/claude-md-by-dir/` +
+    `?dir_name=${encodeURIComponent(dirName)}`
+  try {
+    const res = await f(url, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    })
+    if (res.status === 404) return null
+    if (!res.ok) {
+      logger?.warn?.(
+        { dirName, status: res.status },
+        "fetchHubClaudeMd: non-OK response",
+      )
+      return null
+    }
+    return await res.json()
+  } catch (err) {
+    logger?.warn?.(
+      { dirName, err: err?.message || String(err) },
+      "fetchHubClaudeMd: request failed",
+    )
+    return null
+  }
+}
+
+/**
+ * Hub に PUT で本文を上書きする。Hub 側は履歴を積んでから保存する。
+ *
+ * @returns {Promise<boolean>} 成功なら true
+ */
+async function putHubClaudeMd({ hubUrl, accessToken, dirName, body, fetchImpl, logger }) {
+  const f = fetchImpl || globalThis.fetch
+  if (!f) return false
+  const url =
+    `${hubUrl.replace(/\/+$/, "")}/api/admin/project/claude-md-by-dir/` +
+    `?dir_name=${encodeURIComponent(dirName)}`
+  try {
+    const res = await f(url, {
+      method: "PUT",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ claude_md: body }),
+    })
+    if (!res.ok) {
+      logger?.warn?.(
+        { dirName, status: res.status },
+        "putHubClaudeMd: non-OK response",
+      )
+      return false
+    }
+    return true
+  } catch (err) {
+    logger?.warn?.(
+      { dirName, err: err?.message || String(err) },
+      "putHubClaudeMd: request failed",
+    )
+    return false
+  }
+}
+
+async function readLocalClaudeMd(targetDir) {
+  try {
+    return await fs.readFile(path.join(targetDir, "CLAUDE.md"), "utf-8")
+  } catch (err) {
+    if (err?.code === "ENOENT") return null
+    throw err
+  }
+}
+
+async function writeLocalClaudeMd(targetDir, body) {
+  await fs.writeFile(path.join(targetDir, "CLAUDE.md"), body, "utf-8")
+}
+
+async function readMeta(targetDir) {
+  const metaPath = path.join(targetDir, META_DIR, META_FILE)
+  return await readJsonOrNull(metaPath)
+}
+
+async function writeMeta(targetDir, meta) {
+  const metaDir = path.join(targetDir, META_DIR)
+  await fs.mkdir(metaDir, { recursive: true })
+  await fs.writeFile(
+    path.join(metaDir, META_FILE),
+    JSON.stringify(meta, null, 2),
+    "utf-8",
+  )
+}
+
+/**
+ * 既存ローカル CLAUDE.md を .cockpit-sync/CLAUDE.md.<prefix>.<ts>.bak に退避する。
+ * 同 prefix の .bak は新しい順に BAK_KEEP 件保持し、古いものから FIFO 削除する。
+ *
+ * @param {'normal'|'conflict'} kind バックアップ種別（命名 prefix）
+ */
+async function backupLocalClaudeMd(targetDir, body, kind) {
+  if (body == null) return
+  const metaDir = path.join(targetDir, META_DIR)
+  await fs.mkdir(metaDir, { recursive: true })
+  const prefix = kind === "conflict" ? "CLAUDE.md.conflict" : "CLAUDE.md"
+  const bakName = makeBakName(prefix)
+  await fs.writeFile(path.join(metaDir, bakName), body, "utf-8")
+  // 同 prefix の .bak を新しい順に BAK_KEEP 件まで残す。
+  const entries = await fs.readdir(metaDir).catch(() => [])
+  const sameKind = entries
+    .filter((n) => n.startsWith(`${prefix}.`) && n.endsWith(".bak"))
+    .sort() // 名前にタイムスタンプを含むので辞書順 ≒ 時系列順
+    .reverse() // 新しい順
+  const obsolete = sameKind.slice(BAK_KEEP)
+  await Promise.all(
+    obsolete.map((n) =>
+      fs.unlink(path.join(metaDir, n)).catch(() => {}),
+    ),
+  )
+}
+
+/**
+ * `<targetDir>` の CLAUDE.md を Hub 正本と同期する（双方向 last-write-wins）。
+ *
+ * @param {object} args
+ * @param {string} args.targetDir       絶対パス
+ * @param {string} args.dirName         workspace ディレクトリ名（Dxxxxx_... / Pxxxxx）
+ * @param {string} [args.hubUrl]        Hub API base
+ * @param {string} [args.accessToken]   省略時は ~/.claude/.hub_token.json から
+ * @param {object} [args.logger]
+ * @param {Function} [args.fetchImpl]   テスト注入用
+ * @returns {Promise<{ action: 'pull'|'push'|'conflict'|'noop'|'skipped', reason?: string }>}
+ */
+export async function syncClaudeMdWithHub({
+  targetDir,
+  dirName,
+  hubUrl,
+  accessToken,
+  logger,
+  fetchImpl,
+} = {}) {
+  if (!targetDir) throw new Error("syncClaudeMdWithHub requires targetDir")
+  if (!dirName) throw new Error("syncClaudeMdWithHub requires dirName")
+
+  const token =
+    accessToken === undefined ? await loadAccessToken() : accessToken || null
+  if (!token) {
+    logger?.info?.({ dirName }, "syncClaudeMdWithHub: no access token, skip")
+    return { action: "skipped", reason: "no-token" }
+  }
+  const url = hubUrl || DEFAULT_HUB_API
+
+  // 1) Hub の正本を取得
+  const hub = await fetchHubClaudeMd({
+    hubUrl: url,
+    accessToken: token,
+    dirName,
+    fetchImpl,
+    logger,
+  })
+  if (!hub) {
+    return { action: "skipped", reason: "hub-not-resolvable" }
+  }
+  const hubBody = hub.claude_md || ""
+  const hubHash = hub.claude_md_hash || "" // 空文字なら Project.save 未実行 = 空本文
+  const hubUpdatedAt = hub.claude_md_updated_at || null
+
+  // 2) ローカル CLAUDE.md を読み、現在 hash を計算
+  const localBody = await readLocalClaudeMd(targetDir)
+  const localCurrentHash = localBody == null ? null : sha256(localBody)
+
+  // 3) メタファイルを読み、前回 sync の状態を取得
+  const meta = await readMeta(targetDir)
+
+  // Hub が一度も保存されていない（空本文 + updated_at が null）プロジェクトは
+  // 「Hub UI で意図的に未設定にしている」運用（テナント標準 CLAUDE.md に任せる等）の
+  // 可能性がある。端末側に何か書いてあっても push せず noop に倒す。
+  // ユーザー確定方針: 「Hub の claude_md が空のプロジェクトは何もしない」。
+  const hubInitialized = !!hubUpdatedAt
+  if (!hubInitialized) {
+    return { action: "noop", reason: "hub-uninitialized" }
+  }
+
+  // 判定: hubChanged / localChanged を計算する。
+  // - hubChanged: Hub.updated_at が前回 sync 時より進んだ
+  //   updated_at が null（Project.save 未実行で初期空）の場合は変化なし扱い。
+  // - localChanged: 現在の localHash が前回 sync 時の hash と異なる（=端末で編集）
+  //   meta が無くてローカル非空なら、初回参加時のローカル変更扱い（衝突候補）。
+  let hubChanged, localChanged
+  if (!meta) {
+    // 初回 sync。
+    hubChanged = !!hubBody
+    if (localBody == null) {
+      localChanged = false
+    } else {
+      localChanged = !!localBody // 非空なら端末側に何かある＝衝突候補
+    }
+  } else {
+    hubChanged = !!hubUpdatedAt && hubUpdatedAt !== meta.lastSyncedHubUpdatedAt
+    localChanged =
+      localCurrentHash != null && localCurrentHash !== meta.lastSyncedHash
+  }
+
+  // 同じ内容で書き込まれている（hash 一致）なら衝突扱いせず noop に降格。
+  if (hubChanged && localChanged && hubHash && hubHash === localCurrentHash) {
+    hubChanged = false
+    localChanged = false
+  }
+
+  // 4) アクション決定
+  if (!hubChanged && !localChanged) {
+    return { action: "noop" }
+  }
+
+  if (hubChanged && !localChanged) {
+    // pull: ローカルを .bak 退避 → Hub の本文で上書き
+    await backupLocalClaudeMd(targetDir, localBody, "normal")
+    await writeLocalClaudeMd(targetDir, hubBody)
+    await writeMeta(targetDir, {
+      lastSyncedHubUpdatedAt: hubUpdatedAt,
+      lastSyncedHash: hubHash || sha256(hubBody),
+      lastSyncedAt: nowIso(),
+    })
+    logger?.info?.({ dirName }, "syncClaudeMdWithHub: pull")
+    return { action: "pull" }
+  }
+
+  if (!hubChanged && localChanged) {
+    // push: Hub に PUT。成功時にメタ更新。
+    const ok = await putHubClaudeMd({
+      hubUrl: url,
+      accessToken: token,
+      dirName,
+      body: localBody || "",
+      fetchImpl,
+      logger,
+    })
+    if (!ok) {
+      return { action: "skipped", reason: "hub-put-failed" }
+    }
+    await writeMeta(targetDir, {
+      // PUT 後の Hub.updated_at は再度 GET しないと厳密には取れないため、
+      // 「ローカル hash と Hub.updated_at は別途次回 sync で再同期」する設計。
+      // ここでは「今 push したぶんは Hub に反映済み」として、現在のローカル
+      // hash と「今の時刻」をメタに記録する（次回 sync 時に再判定可能）。
+      lastSyncedHubUpdatedAt: nowIso(),
+      lastSyncedHash: localCurrentHash,
+      lastSyncedAt: nowIso(),
+    })
+    logger?.info?.({ dirName }, "syncClaudeMdWithHub: push")
+    return { action: "push" }
+  }
+
+  // hubChanged && localChanged → 衝突。端末側を勝者にして Hub に PUT。
+  // Hub の取り込み内容は .bak.conflict に退避（後で人手マージできるよう）。
+  await backupLocalClaudeMd(targetDir, hubBody, "conflict")
+  const ok = await putHubClaudeMd({
+    hubUrl: url,
+    accessToken: token,
+    dirName,
+    body: localBody || "",
+    fetchImpl,
+    logger,
+  })
+  if (!ok) {
+    // PUT 失敗時はメタを更新しない（次回再試行）。ローカルは無傷。
+    return { action: "skipped", reason: "hub-put-failed-in-conflict" }
+  }
+  await writeMeta(targetDir, {
+    lastSyncedHubUpdatedAt: nowIso(),
+    lastSyncedHash: localCurrentHash,
+    lastSyncedAt: nowIso(),
+  })
+  logger?.warn?.(
+    { dirName },
+    "syncClaudeMdWithHub: conflict (terminal wins); hub body saved to .bak.conflict",
+  )
+  return { action: "conflict" }
+}
+
+// メタ操作・ハッシュ計算は ensureClaudeMd 側 (Hub pull 初回配信) でも使うため
+// named export する。同じファイルパス・同じスキーマで管理することで、初回配信と
+// 以降の sync で食い違いを起こさない。
+export { sha256, readMeta, writeMeta, nowIso }
+
+// 内部テスト用エクスポート
+export const _internals = {
+  sha256,
+  readMeta,
+  writeMeta,
+  backupLocalClaudeMd,
+  BAK_KEEP,
+}

package/src/claude-md.mjs

@@ -2,17 +2,28 @@
  * 新規 workspace ディレクトリ初期化時の CLAUDE.md 生成。
  *
  * ~/hub/bin/generate-claude-md (Python) と同等の仕様を Node 側に持つ。
- * - `<dirName>/_director` slug で Hub director を引き当て、見つかれば
- *   frontmatter (client / domain / industry / service / tech_stack /
- *   google_drive) を反映した構造化 CLAUDE.md を書き出す
- * - 認証トークン (`~/.claude/.hub_token.json`) が無い / API 失敗 / director
- *   未登録ならプレースホルダ CLAUDE.md を書き出す
  *
- * CLAUDE.md が既存ならそのまま (上書きしない)。
+ * 優先順 (新規生成時のみ。既存 CLAUDE.md は触らない):
+ * 1. **Hub の Project.claude_md 正本** (Stage 3 初回配信) — 非空ならそれを書く。
+ *    同期メタ (.cockpit-sync/claude-md.json) も初期化する。以降は
+ *    syncClaudeMdWithHub が双方向同期する。
+ * 2. **Hub director frontmatter** — claude_md が空でも director があれば
+ *    client/domain/industry/service/tech_stack/google_drive で構造化版を書く。
+ * 3. **placeholder** — token なし / API 失敗 / director 未登録なら最小プレースホルダ。
+ *
+ * 1 を最優先にしたのは、新規メンバーが workspace に入ったとき、組織で固まった
+ * CLAUDE.md（Stage 1/2 で正本化したもの）が即座に引かれて作業に取り掛かれる
+ * ようにするため。動的生成は「Hub に正本がまだ無いプロジェクト」の救済として
+ * のみ機能する。
  */
 import fs from "node:fs/promises"
 import os from "node:os"
 import path from "node:path"
+import {
+  sha256,
+  writeMeta,
+  nowIso,
+} from "./claude-md-sync.mjs"
 
 const DEFAULT_HUB_API = "https://api.hub.cocorograph.com"
 const TOKEN_PATH = path.join(os.homedir(), ".claude", ".hub_token.json")
@@ -31,6 +42,34 @@ async function loadAccessToken() {
   return (data && typeof data.access === "string" && data.access) || null
 }
 
+/**
+ * Hub の Project.claude_md 正本を取得する (Stage 3 初回配信用)。
+ *
+ * - 404 (該当 Project 無し) → null
+ * - その他のエラー → null
+ * - 取得成功時は { claude_md, claude_md_hash, claude_md_updated_at } を返す
+ *
+ * 同じエンドポイントは syncClaudeMdWithHub も使うが、ensureClaudeMd は
+ * 初回生成 (メタ無し) 経路でしか呼ばれず、PUT もしないため import せず
+ * 個別実装する。
+ */
+async function fetchHubClaudeMdProject({ hubUrl, accessToken, dirName, fetchImpl }) {
+  const f = fetchImpl || globalThis.fetch
+  if (!f) return null
+  const url =
+    `${hubUrl.replace(/\/+$/, "")}/api/admin/project/claude-md-by-dir/` +
+    `?dir_name=${encodeURIComponent(dirName)}`
+  try {
+    const res = await f(url, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    })
+    if (!res.ok) return null
+    return await res.json()
+  } catch {
+    return null
+  }
+}
+
 async function fetchDirector({ hubUrl, accessToken, dirName, fetchImpl }) {
   const f = fetchImpl || globalThis.fetch
   if (!f) return null
@@ -320,7 +359,35 @@ export async function ensureClaudeMd({
   const token =
     accessToken === undefined ? await loadAccessToken() : accessToken || null
   const url = hubUrl || DEFAULT_HUB_API
-  // director と repositories は独立して取れるので並列フェッチする。
+
+  // Stage 3: Hub に正本があればそれを最優先で書き込み、メタも初期化する
+  // （以降の syncClaudeMdWithHub が双方向同期の起点として使う）。
+  // Hub 側未保存 (claude_md_updated_at が null) なら従来パスへフォールバック。
+  if (token) {
+    const hub = await fetchHubClaudeMdProject({
+      hubUrl: url,
+      accessToken: token,
+      dirName,
+      fetchImpl,
+    })
+    const hubBody = hub?.claude_md || ""
+    const hubInitialized = !!hub?.claude_md_updated_at
+    if (hubInitialized && hubBody) {
+      await fs.writeFile(claudeMdPath, hubBody, "utf-8")
+      await writeMeta(targetDir, {
+        lastSyncedHubUpdatedAt: hub.claude_md_updated_at,
+        lastSyncedHash: hub.claude_md_hash || sha256(hubBody),
+        lastSyncedAt: nowIso(),
+      })
+      logger?.info?.(
+        { dirName, claudeMdPath },
+        "wrote CLAUDE.md from Hub project claude_md (initial sync)",
+      )
+      return { written: true, source: "hub" }
+    }
+  }
+
+  // 従来パス: director と repositories は独立して取れるので並列フェッチする。
   // どちらも失敗時は null / [] にフォールバックする (token なしの場合も同様)。
   const [director, repositories] = token
     ? await Promise.all([

package/src/tmux.mjs

@@ -20,6 +20,7 @@ import path from "node:path"
 import { promisify } from "node:util"
 
 import { ensureClaudeMd } from "./claude-md.mjs"
+import { syncClaudeMdWithHub } from "./claude-md-sync.mjs"
 import {
   capturePane,
   detectInputBoxText,
@@ -657,14 +658,22 @@ export async function createSession(name, cwd, opts = {}) {
       throw new Error(`cwd stat failed: ${err?.message || String(err)}`)
     }
   }
-  // HUB_PROJECTS_BASE 配下の workspace の場合は CLAUDE.md を必要なら生成する。
-  // Hub director があれば frontmatter 連動の構造化版、無ければ最小プレースホルダ。
-  // 既存 CLAUDE.md は触らない。失敗しても session 起動自体は止めない (warn のみ)。
+  // HUB_PROJECTS_BASE 配下の workspace の場合は CLAUDE.md を必要なら生成し、
+  // Hub の正本（Project.claude_md）と双方向同期する。
+  // - ensureClaudeMd: 既存 CLAUDE.md は触らない。無ければ director frontmatter
+  //   または placeholder を生成する。
+  // - syncClaudeMdWithHub: Hub 正本と双方向 last-write-wins 同期。Hub 側更新は
+  //   ローカルへ pull（.bak 退避してから上書き）、端末側更新は Hub へ push、
+  //   両方変化は端末側を勝者にして Hub へ push（Hub の取り込み内容は
+  //   .bak.conflict に退避）。Hub が一度も保存されていないプロジェクトでは
+  //   何もしない（テナント標準 CLAUDE.md の運用を尊重する）。
+  // どちらも失敗しても session 起動自体は止めない (warn のみ)。
   if (isUnderHubProjectsBase(resolvedCwd)) {
+    const dirName = path.basename(resolvedCwd)
     try {
       await ensureClaudeMd({
         targetDir: resolvedCwd,
-        dirName: path.basename(resolvedCwd),
+        dirName,
         hubUrl: opts.hubUrl,
         accessToken: opts.hubAccessToken,
         logger: opts.logger,
@@ -676,6 +685,25 @@ export async function createSession(name, cwd, opts = {}) {
         "ensureClaudeMd failed (workspace dir is usable, but no CLAUDE.md)",
       )
     }
+    try {
+      const syncResult = await syncClaudeMdWithHub({
+        targetDir: resolvedCwd,
+        dirName,
+        hubUrl: opts.hubUrl,
+        accessToken: opts.hubAccessToken,
+        logger: opts.logger,
+        fetchImpl: opts.fetchImpl,
+      })
+      opts.logger?.debug?.(
+        { session: name, dirName, sync: syncResult },
+        "syncClaudeMdWithHub completed",
+      )
+    } catch (err) {
+      opts.logger?.warn?.(
+        { session: name, cwd: resolvedCwd, err: err?.message || String(err) },
+        "syncClaudeMdWithHub failed (session starts anyway)",
+      )
+    }
   }
   // 既存チェック
   try {