claude-spotter 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 1.1.0
+
+**`spotter install` が tool-db を自動構築 + SessionStart hook がバックグラウンド refresh**。install 直後から audit 対象が揃うようになり、以降の session でも MCP / スキル / サブエージェントの追加・削除が自動追従する。
+
+### 背景
+
+v1.0.0 以前は `spotter install` が hook 登録だけで tool-db を作らず、別途 `spotter db refresh` を手動実行する必要があった。初回セッションで daemon が空 DB を掴むと Haiku に preamble が届かず audit が機能しない状態で起動してしまう。また、install 後に MCP や スキルを追加しても rebuild/refresh を手動で叩くまで視野に入らず、drift が常に発生していた。
+
+### 変更点
+
+- **編集 [src/cli/install.mjs](src/cli/install.mjs)**: settings.json 書き込み後に project-mode で `refresh({projectRoot})` を同期実行し tool-db を seed。失敗時は §0 準拠で throw (hook だけ登録されて DB が無い中途半端な状態を残さない)。`skipRefresh` オプションを新設 (既存テストが user 環境をスキャンしないように)。"next steps" メッセージから `spotter db refresh` の手動実行指示を削除
+- **編集 [src/hooks/session-start.mjs](src/hooks/session-start.mjs)**: daemon readiness 確立後に `spawnRefreshDetached({projectRoot})` を発火。hook 自体は即 return、refresh は detached child として bg 実行。**現セッションの daemon は起動時の tool-db で固定**のため反映は次セッション以降
+- **編集 [src/hooks/spawn-daemon.mjs](src/hooks/spawn-daemon.mjs)**: `spawnRefreshDetached` を追加 export。`node <spotterBin> db refresh` を `detached: true, stdio: 'ignore', unref()` で起動、hook を遅延させない
+- **テスト更新 [test/install.test.mjs](test/install.test.mjs)**: 全 6 件が `skipRefresh: true` を渡すよう更新
+
+### 設計判断
+
+- **rebuild ではなく refresh を採用**: 当初 user 指示は rebuild (local+global wipe + 全再スキャン) だったが、(1) 既適用プロジェクトの global キャッシュを毎 SessionStart で破壊するのは副作用が大きい、(2) 並列セッション (Project A rebuild 中に Project B SessionStart) で書き込み競合が発生する、の 2 点から refresh に変更。差分更新でも新規・削除の drift 追従は効く。description drift (同一名の description 更新) のみ取りこぼすが、これは `spotter db rebuild` の手動実行でカバー
+- **SessionStart の refresh は bg detached**: session-start hook の timeout は 5s で、MCP 全サーバー spawn + skills 181 件スキャンは秒単位かかるため同期実行は不可能。detached + unref で hook を遅延させない代わりに、反映は次セッション以降 (現セッションの daemon は既に古い tool-db をロード済みで、実行中の差し替えはしない)
+- **install 時の refresh 失敗は throw**: "hook 登録済みだが DB なし" という中途半端な状態を残すくらいなら install 自体を失敗扱いにするほうがクリーン。再試行は `spotter install` の再実行で、hook 登録は `nothing to change` で skip され refresh だけ走る
+
+### 破壊変更
+
+なし (skipRefresh オプションはデフォルト false で既存挙動より機能追加、CLI 利用者には透過)。
+
+### 影響範囲
+
+- 新規 `spotter install` 実行時は MCP/skills/agents の discover でセットアップ時間が数秒〜10 秒増える
+- 毎 SessionStart でバックグラウンド `spotter db refresh` プロセスが 1 つ発火 (bg unref なので UX 影響なし)
+- global tool-db への書き込みが session 起動ごとに発生 (atomic write なので corruption リスクなし、last-write-wins の並列 race は idempotent なので次 refresh で収束)
+
 ## 1.0.0
 
 **監査対象をユーザー追加分 (MCP / スキル / サブエージェント) に絞り込み**。Claude Code 本体が提供するツール (即時 + 遅延) は監査カタログから全面除外。設計転換の major bump。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-spotter",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Audit agent running alongside Claude Code that catches missed tool calls — 気づく役と実行する役の分離",
   "type": "module",
   "bin": {

package/src/cli/install.mjs

@@ -7,8 +7,9 @@
 // silently exit otherwise (prevents Throughline-style proliferation).
 //
 // v0.7.0: tool catalog (the old YAML) is replaced by tool-db.json (auto-discovered MCP
-// + hardcoded built-in deferred). Install no longer seeds a template — user runs
-// `spotter db refresh` after install to populate.
+// servers, skills, sub-agents — see docs/catalog-design.md for v1.0.0 scope).
+// Install seeds the DB automatically via `refresh` (project-mode only — user-mode
+// has no projectRoot so DB seeding is skipped there).
 
 import { mkdir, writeFile, readFile, access } from 'node:fs/promises';
 import { homedir } from 'node:os';
@@ -16,6 +17,8 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline/promises';
 import { version as SPOTTER_VERSION } from '../version.mjs';
+import { refresh } from '../tool-db/refresh.mjs';
+import { localDbPath, globalDbPath } from '../tool-db/loader.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(HERE, '..', '..');
@@ -33,7 +36,7 @@ const HOOK_EVENTS = [
   { event: 'SessionEnd', sub: 'session-end', timeout: 3 },
 ];
 
-export async function runInstall({ target = 'project', autoYes = false, cwd = process.cwd() } = {}) {
+export async function runInstall({ target = 'project', autoYes = false, cwd = process.cwd(), skipRefresh = false } = {}) {
   const settingsPath = target === 'user'
     ? join(homedir(), '.claude', 'settings.json')
     : join(cwd, '.claude', 'settings.json');
@@ -96,9 +99,21 @@ export async function runInstall({ target = 'project', autoYes = false, cwd = pr
   await mkdir(dirname(settingsPath), { recursive: true });
   await writeFile(settingsPath, JSON.stringify(updated, null, 2) + '\n', 'utf8');
   console.log(`wrote ${settingsPath}`);
+
+  // Seed the tool-db so the first session has something to audit against.
+  // Skipped for user-mode (deprecated — no projectRoot) and when caller opts out
+  // (tests set skipRefresh=true to avoid scanning the real user environment).
+  if (target === 'project' && !skipRefresh) {
+    console.log('\ndiscovering MCP servers, skills, and sub-agents...');
+    const log = (msg) => process.stderr.write(`  ${msg}\n`);
+    const resolved = await refresh({ projectRoot: cwd, logFn: log });
+    console.log(`  ${resolved.size} tool(s) resolved`);
+    console.log(`  local DB:  ${localDbPath(cwd)}`);
+    console.log(`  global DB: ${globalDbPath()}`);
+  }
+
   console.log('\nnext steps:');
-  console.log('  1. run `spotter db refresh` to discover available MCP/deferred tools');
-  console.log('  2. reload Claude Code (or open a new session) to activate Spotter');
+  console.log('  reload Claude Code (or open a new session) to activate Spotter');
 }
 
 async function exists(path) {

package/src/hooks/session-start.mjs

@@ -17,7 +17,7 @@
 // now heartbeat-based inside the daemon.
 
 import { readStdinJson, requireString, die, isChildCall, isSubagentCall, isOutsideSpotterProject, findSpotterMarker } from './lib.mjs';
-import { spawnDaemonAndWaitReady } from './spawn-daemon.mjs';
+import { spawnDaemonAndWaitReady, spawnRefreshDetached } from './spawn-daemon.mjs';
 
 export async function runSessionStart({ now = Date.now } = {}) {
   if (isChildCall()) return;
@@ -35,6 +35,7 @@ export async function runSessionStart({ now = Date.now } = {}) {
   }
 
   await spawnDaemonAndWaitReady({ sessionId, projectRoot, now });
+  spawnRefreshDetached({ projectRoot });
 }
 
 if (import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`) {

package/src/hooks/spawn-daemon.mjs

@@ -66,6 +66,27 @@ function spawnDaemon(sessionId, projectRoot) {
   child.unref();
 }
 
+// Fire-and-forget `spotter db refresh`. The daemon in THIS session already loaded the
+// pre-refresh tool-db, so any updates land in time for the NEXT session. Detached so
+// the hook doesn't wait for MCP/skill/agent discovery to finish.
+export function spawnRefreshDetached({ projectRoot }) {
+  const spotterBin = resolveSpotterBin();
+  const child = spawn(
+    process.execPath,
+    [spotterBin, 'db', 'refresh'],
+    {
+      cwd: projectRoot,
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    }
+  );
+  child.on('error', (err) => {
+    process.stderr.write(`spotter-hook: refresh spawn error: ${err.message}\n`);
+  });
+  child.unref();
+}
+
 function resolveSpotterBin() {
   const here = dirname(fileURLToPath(import.meta.url));
   return resolve(here, '..', '..', 'bin', 'spotter.mjs');