claude-spotter 0.1.0

package/src/daemon/transport.mjs

@@ -0,0 +1,142 @@
+// hook ⇄ daemon transport (§5.6 socket abstraction, §5.7 envelope).
+// Cross-platform: Unix domain socket on macOS/Linux, Named Pipe on Windows.
+// Wire format: newline-delimited JSON, one request or response per line.
+
+import net from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const RUNTIME_DIR = join(homedir(), '.spotter', 'runtime');
+
+export function socketPath(sessionId) {
+  if (!sessionId || typeof sessionId !== 'string') {
+    throw new TypeError('sessionId must be a non-empty string');
+  }
+  if (process.platform === 'win32') {
+    return `\\\\.\\pipe\\spotter-${sessionId}`;
+  }
+  return join(RUNTIME_DIR, `session-${sessionId}.sock`);
+}
+
+export async function ensureRuntimeDir() {
+  await mkdir(RUNTIME_DIR, { recursive: true });
+  return RUNTIME_DIR;
+}
+
+// Request/response over a single connection. Used by hooks.
+export function sendRequest({ sessionId, event, payload, timeoutMs }) {
+  if (typeof timeoutMs !== 'number' || timeoutMs <= 0) {
+    throw new TypeError('timeoutMs must be a positive number');
+  }
+  const envelope = {
+    id: randomUUID(),
+    event,
+    session_id: sessionId,
+    payload: payload ?? {},
+  };
+
+  return new Promise((resolve, reject) => {
+    const path = socketPath(sessionId);
+    const sock = net.createConnection(path);
+    let buf = '';
+    let settled = false;
+
+    const settle = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      sock.destroy();
+      fn(value);
+    };
+
+    const timer = setTimeout(() => {
+      settle(reject, new TransportError('E_TIMEOUT', `daemon did not respond within ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    sock.on('connect', () => {
+      sock.write(JSON.stringify(envelope) + '\n');
+    });
+
+    sock.on('data', (chunk) => {
+      buf += chunk.toString('utf8');
+      const newlineIdx = buf.indexOf('\n');
+      if (newlineIdx === -1) return;
+      const line = buf.slice(0, newlineIdx);
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch (err) {
+        settle(reject, new TransportError('E_INTERNAL', `invalid JSON from daemon: ${err.message}`));
+        return;
+      }
+      if (parsed.id !== envelope.id) {
+        settle(reject, new TransportError('E_INTERNAL', `id mismatch: sent ${envelope.id}, got ${parsed.id}`));
+        return;
+      }
+      settle(resolve, parsed);
+    });
+
+    sock.on('error', (err) => {
+      if (err.code === 'ENOENT' || err.code === 'ECONNREFUSED') {
+        settle(reject, new TransportError('E_UNREACHABLE', `daemon unreachable at ${path}: ${err.code}`));
+      } else {
+        settle(reject, new TransportError('E_INTERNAL', `socket error: ${err.message}`));
+      }
+    });
+  });
+}
+
+export class TransportError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'TransportError';
+    this.code = code;
+  }
+}
+
+// Daemon side: listen on socket, dispatch envelopes through a handler.
+// handler: async (envelope) => result — result is put into { ok: true, result } or
+// on throw packed into { ok: false, error: { code, message } }.
+export function createServer({ sessionId, handler, onError }) {
+  const path = socketPath(sessionId);
+  const server = net.createServer((conn) => {
+    let buf = '';
+    conn.on('data', async (chunk) => {
+      buf += chunk.toString('utf8');
+      let newlineIdx;
+      while ((newlineIdx = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, newlineIdx);
+        buf = buf.slice(newlineIdx + 1);
+        if (line.length === 0) continue;
+        let envelope;
+        try {
+          envelope = JSON.parse(line);
+        } catch (err) {
+          // Malformed client input — write minimal error response with null id.
+          conn.write(JSON.stringify({
+            id: null,
+            ok: false,
+            error: { code: 'E_INTERNAL', message: `invalid JSON: ${err.message}` },
+          }) + '\n');
+          continue;
+        }
+        try {
+          const result = await handler(envelope);
+          conn.write(JSON.stringify({ id: envelope.id, ok: true, result }) + '\n');
+        } catch (err) {
+          const code = err.code && typeof err.code === 'string' ? err.code : 'E_INTERNAL';
+          const message = err.message ?? String(err);
+          conn.write(JSON.stringify({ id: envelope.id, ok: false, error: { code, message } }) + '\n');
+          if (onError) onError(err, envelope);
+        }
+      }
+    });
+    conn.on('error', (err) => {
+      if (onError) onError(err, null);
+    });
+  });
+
+  return { server, path };
+}

package/src/hooks/lib.mjs

@@ -0,0 +1,88 @@
+// Shared hook plumbing — stdin read, error → exit-code mapping per §14.3 / §14.4.
+//
+// Exit code contract (§14.3 / §14.4):
+//   0 = success (normal flow)
+//   1 = expected abnormal (daemon unreachable; user should restart daemon)
+//   2 = unexpected (propagate to Claude Code transcript)
+//
+// Silent fallback (exit 0 with missing behaviour) is forbidden. See §14.1.
+
+export async function readStdinJson() {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    raw += chunk;
+  }
+  if (raw.length === 0) {
+    const err = new Error('hook received empty stdin — Claude Code is expected to provide a JSON envelope');
+    err.exitCode = 2;
+    throw err;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (cause) {
+    const err = new Error(`hook stdin is not valid JSON: ${cause.message}`);
+    err.exitCode = 2;
+    err.cause = cause;
+    throw err;
+  }
+}
+
+export function requireString(input, key) {
+  const value = input[key];
+  if (typeof value !== 'string' || value.length === 0) {
+    const err = new Error(`hook input missing required string "${key}"`);
+    err.exitCode = 2;
+    throw err;
+  }
+  return value;
+}
+
+export function optionalString(input, key) {
+  const value = input[key];
+  if (value === undefined || value === null) return null;
+  if (typeof value !== 'string') {
+    const err = new Error(`hook input "${key}" must be a string if present`);
+    err.exitCode = 2;
+    throw err;
+  }
+  return value;
+}
+
+// Map a TransportError / HaikuError into an exit code.
+export function exitCodeFor(err) {
+  if (err && typeof err.code === 'string') {
+    if (err.code === 'E_UNREACHABLE') return 1;
+    return 2;
+  }
+  return 2;
+}
+
+export function die(message, exitCode = 2) {
+  process.stderr.write(`spotter-hook: ${message}\n`);
+  process.exit(exitCode);
+}
+
+export function formatTransparentContext(missingTools) {
+  // §12.2: transparent phrasing — Bell should reference Spotter explicitly.
+  const lines = missingTools.map((m) => `- \`${m.name}\`: ${m.reason}`);
+  return [
+    '[Spotter からの推奨ツール]',
+    'このプロンプトに応答する前に、以下のツールを使うべきか検討してください。',
+    ...lines,
+    '',
+    '使う場合は「Spotter の推奨に従い〜」のように監査役の指摘を明示してください。',
+  ].join('\n');
+}
+
+export function formatTransparentBlockReason(missingTools) {
+  // §12.3: transparent phrasing for Stop hook block.
+  const lines = missingTools.map((m) => `- \`${m.name}\`: ${m.reason}`);
+  return [
+    '[Spotter からの指摘]',
+    '上記応答ではツールが不足している可能性があります。以下を検討し、必要なら呼び出した上で応答を補正してください。',
+    ...lines,
+    '',
+    '応答には「Spotter からの指摘を受けて〜」のように監査役の介入を明示してください。',
+  ].join('\n');
+}

package/src/hooks/pre-tool-use.mjs

@@ -0,0 +1,30 @@
+// PreToolUse hook — record tool usage in daemon (lightweight, no Haiku call). §9.1 v0.1.
+
+import { readStdinJson, requireString, exitCodeFor, die } from './lib.mjs';
+import { sendRequest } from '../daemon/transport.mjs';
+
+const TIMEOUT_MS = 1_000;
+
+export async function runPreToolUse() {
+  const input = await readStdinJson();
+  const sessionId = requireString(input, 'session_id');
+  const toolName = requireString(input, 'tool_name');
+
+  try {
+    const response = await sendRequest({
+      sessionId,
+      event: 'tool_used',
+      payload: { tool_name: toolName },
+      timeoutMs: TIMEOUT_MS,
+    });
+    if (response.ok !== true) {
+      die(`daemon error on tool_used: ${response.error?.code ?? '?'}: ${response.error?.message ?? ''}`, 2);
+    }
+  } catch (err) {
+    die(`pre-tool-use transport failure: ${err.code ?? '?'}: ${err.message}`, exitCodeFor(err));
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`) {
+  runPreToolUse().catch((err) => die(err.message, err.exitCode ?? 2));
+}

package/src/hooks/session-end.mjs

@@ -0,0 +1,30 @@
+// SessionEnd hook — best-effort shutdown notice. §14.1 exception: cleanup failures warn only.
+
+import { readStdinJson, requireString } from './lib.mjs';
+import { sendRequest } from '../daemon/transport.mjs';
+
+const TIMEOUT_MS = 2_000;
+
+export async function runSessionEnd() {
+  const input = await readStdinJson();
+  const sessionId = requireString(input, 'session_id');
+
+  try {
+    await sendRequest({
+      sessionId,
+      event: 'shutdown',
+      timeoutMs: TIMEOUT_MS,
+    });
+  } catch (err) {
+    // §14.1 exception — don't fail the Claude Code session just because cleanup failed.
+    process.stderr.write(`spotter-hook: session-end shutdown warning: ${err.code ?? '?'}: ${err.message}\n`);
+    process.exit(0);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`) {
+  runSessionEnd().catch((err) => {
+    process.stderr.write(`spotter-hook: session-end unexpected error: ${err.message}\n`);
+    process.exit(0); // still don't block session end (§14.1 exception)
+  });
+}

package/src/hooks/session-start.mjs

@@ -0,0 +1,69 @@
+// SessionStart hook — spawn daemon detached, wait up to 3s for readiness (§9.1).
+//
+// §14.3 classifies readiness failure as unexpected (exit 2). §14.1 forbids silent fallback.
+
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { readStdinJson, requireString, die } from './lib.mjs';
+import { sendRequest, TransportError } from '../daemon/transport.mjs';
+
+const READINESS_TIMEOUT_MS = 3_000;
+const POLL_INTERVAL_MS = 100;
+
+export async function runSessionStart({ argv = process.argv, now = Date.now } = {}) {
+  const input = await readStdinJson();
+  const sessionId = requireString(input, 'session_id');
+
+  spawnDaemon(sessionId, argv);
+
+  const deadline = now() + READINESS_TIMEOUT_MS;
+  while (now() < deadline) {
+    try {
+      const resp = await sendRequest({
+        sessionId,
+        event: 'readiness',
+        timeoutMs: 500,
+      });
+      if (resp.ok === true && resp.result && resp.result.ready === true) {
+        return; // success — exit 0 implicitly
+      }
+    } catch (err) {
+      if (!(err instanceof TransportError) || err.code !== 'E_UNREACHABLE') {
+        // E_TIMEOUT or internal errors while daemon is booting — keep polling.
+        // E_UNREACHABLE means the socket file/pipe doesn't exist yet — also retryable.
+      }
+    }
+    await delay(POLL_INTERVAL_MS);
+  }
+
+  die(`daemon did not reach readiness within ${READINESS_TIMEOUT_MS}ms for session ${sessionId}`, 2);
+}
+
+function spawnDaemon(sessionId, argv) {
+  // Invoke `node <spotter-bin> daemon start --session-id ...` detached.
+  const spotterBin = resolveSpotterBin(argv);
+  const child = spawn(process.execPath, [spotterBin, 'daemon', 'start', '--session-id', sessionId], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+  });
+  child.on('error', (err) => {
+    // best effort: the polling below will fail if the spawn actually didn't work
+    process.stderr.write(`spotter-hook: daemon spawn error: ${err.message}\n`);
+  });
+  child.unref();
+}
+
+function resolveSpotterBin(argv) {
+  // argv[1] is the path to the currently running script (bin/spotter.mjs when invoked via CLI,
+  // or src/hooks/session-start.mjs in tests). Walk up to the package root.
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, '..', '..', 'bin', 'spotter.mjs');
+}
+
+// Direct-execution entry — used when called as `node session-start.mjs`.
+if (import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`) {
+  runSessionStart().catch((err) => die(err.message, err.exitCode ?? 2));
+}

package/src/hooks/stop.mjs

@@ -0,0 +1,56 @@
+// Stop hook — send turn_end, return decision:"block" on miss (§12.3 transparent).
+// `stop_hook_active: true` → daemon returns pass automatically (§7.5 max-1-loop).
+
+import {
+  readStdinJson,
+  requireString,
+  optionalString,
+  exitCodeFor,
+  die,
+  formatTransparentBlockReason,
+} from './lib.mjs';
+import { sendRequest } from '../daemon/transport.mjs';
+
+const TIMEOUT_MS = 15_000;
+
+export async function runStop() {
+  const input = await readStdinJson();
+  const sessionId = requireString(input, 'session_id');
+  const stopHookActive = input.stop_hook_active === true;
+  // Claude Code passes the transcript path; the final response is read from there or provided inline.
+  const finalResponse = optionalString(input, 'final_response') ?? '(no final response provided)';
+
+  let response;
+  try {
+    response = await sendRequest({
+      sessionId,
+      event: 'turn_end',
+      payload: {
+        final_response: finalResponse,
+        stop_hook_active: stopHookActive,
+      },
+      timeoutMs: TIMEOUT_MS,
+    });
+  } catch (err) {
+    die(`stop transport failure: ${err.code ?? '?'}: ${err.message}`, exitCodeFor(err));
+    return;
+  }
+
+  if (response.ok !== true) {
+    die(`daemon error on turn_end: ${response.error?.code ?? '?'}: ${response.error?.message ?? ''}`, 2);
+    return;
+  }
+
+  const result = response.result;
+  if (result.pass === true) {
+    return; // no block
+  }
+
+  const reason = formatTransparentBlockReason(result.missing_tools);
+  const output = { decision: 'block', reason };
+  process.stdout.write(JSON.stringify(output));
+}
+
+if (import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`) {
+  runStop().catch((err) => die(err.message, err.exitCode ?? 2));
+}

package/src/hooks/user-prompt.mjs

@@ -0,0 +1,48 @@
+// UserPromptSubmit hook — send user_input to daemon, inject additionalContext (§12.2 transparent).
+
+import { readStdinJson, requireString, exitCodeFor, die, formatTransparentContext } from './lib.mjs';
+import { sendRequest } from '../daemon/transport.mjs';
+
+const TIMEOUT_MS = 30_000;
+
+export async function runUserPrompt() {
+  const input = await readStdinJson();
+  const sessionId = requireString(input, 'session_id');
+  const prompt = requireString(input, 'prompt');
+
+  let response;
+  try {
+    response = await sendRequest({
+      sessionId,
+      event: 'user_input',
+      payload: { user_input: prompt },
+      timeoutMs: TIMEOUT_MS,
+    });
+  } catch (err) {
+    die(`user-prompt transport failure: ${err.code ?? '?'}: ${err.message}`, exitCodeFor(err));
+    return;
+  }
+
+  if (response.ok !== true) {
+    die(`daemon error on user_input: ${response.error?.code ?? '?'}: ${response.error?.message ?? ''}`, 2);
+    return;
+  }
+
+  const result = response.result;
+  if (result.pass === true) {
+    return; // no additionalContext to inject
+  }
+
+  const additionalContext = formatTransparentContext(result.missing_tools);
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext,
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+}
+
+if (import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`) {
+  runUserPrompt().catch((err) => die(err.message, err.exitCode ?? 2));
+}

package/src/index.mjs

@@ -0,0 +1,19 @@
+// Public entry for programmatic use (e.g. `import { startDaemon } from 'claude-spotter'`).
+
+export { startDaemon } from './daemon/daemon.mjs';
+export {
+  sendRequest,
+  TransportError,
+  socketPath,
+} from './daemon/transport.mjs';
+export {
+  buildFirstStagePrompt,
+  buildFinalStagePrompt,
+  parseHaikuResponse,
+  createHaikuCaller,
+  HaikuError,
+} from './daemon/haiku-caller.mjs';
+export { loadCatalog, CatalogLoadError, CatalogSchemaError } from './catalog/loader.mjs';
+export { validateCatalog } from './catalog/schema.mjs';
+export { runLint } from './catalog/lint.mjs';
+export { version } from './version.mjs';

package/src/version.mjs

@@ -0,0 +1 @@
+export const version = '0.1.0';

package/templates/tools.yaml

@@ -0,0 +1,111 @@
+version: 1
+tools:
+  - name: current_time
+    category: time
+    purpose: >
+      現在の日時を正確に取得する。LLM は会話の流れから時刻を合成する癖があるが
+      不正確。時刻に言及する発話を出す前に必ず呼ぶ。
+    when_to_use:
+      - 「今何時」「今日は何日」等の時刻直接質問
+      - 「もう深夜だね」等の時刻言及を伴う発話
+      - 営業時間・締切・祝日など時間依存の判断
+    usage: current_time [timezone]
+    examples:
+      - input: もう夜遅いね
+        call: current_time Asia/Tokyo
+      - input: 今何時?
+        call: current_time
+    keywords: [今, 現在, 時刻, 日付, 何時, 今日, now, today, time]
+    test_cases:
+      - user_input: 今何時?
+        expected_tool: current_time
+      - user_input: 今日は何月何日?
+        expected_tool: current_time
+
+  - name: web_search
+    category: information
+    purpose: >
+      最新情報を Web から取得する。LLM の訓練データは特定時点までなので、
+      それ以降の出来事・価格・バージョン・ニュースは自力で答えない。
+    when_to_use:
+      - 最新ニュース・イベント・トレンドの質問
+      - 製品バージョン・リリース情報
+      - 価格・在庫・営業情報の問い合わせ
+      - 訓練データ以降に発生した事象の確認
+    usage: web_search <query>
+    examples:
+      - input: Claude の最新モデルは?
+        call: web_search "latest Claude model release"
+      - input: 今日の東京の天気
+        call: web_search "Tokyo weather today"
+    keywords: [最新, ニュース, 今, 現在, トレンド, 調べて, 検索, latest, news, search]
+    test_cases:
+      - user_input: React の最新バージョンは?
+        expected_tool: web_search
+      - user_input: 昨日のニュース教えて
+        expected_tool: web_search
+
+  - name: read_file
+    category: filesystem
+    purpose: >
+      ローカルファイルの内容を正確に読み取る。記憶から内容を再構成せず、
+      必ず最新の内容を取得する。
+    when_to_use:
+      - ユーザーがファイル名・パスを明示した質問
+      - コードのレビューや修正の依頼
+      - 設定ファイル・ログファイルの確認依頼
+    usage: read_file <path>
+    examples:
+      - input: package.json 見せて
+        call: read_file package.json
+      - input: src/index.js にバグある?
+        call: read_file src/index.js
+    keywords: [ファイル, 読ん, 開い, 見せて, 確認, read, file, open]
+    test_cases:
+      - user_input: README.md の内容は?
+        expected_tool: read_file
+      - user_input: この src/app.ts にバグがあるか確認して
+        expected_tool: read_file
+
+  - name: list_directory
+    category: filesystem
+    purpose: >
+      ディレクトリのファイル一覧を取得する。何があるか分からない状態で
+      推測せず、実際の一覧を確認する。
+    when_to_use:
+      - 「どんなファイルがある?」等のディレクトリ内容質問
+      - プロジェクト構造の把握
+      - 特定パターンのファイル存在確認
+    usage: list_directory <path>
+    examples:
+      - input: src/ 以下のファイル一覧
+        call: list_directory src/
+      - input: このプロジェクトの構造を教えて
+        call: list_directory .
+    keywords: [一覧, リスト, 構造, どんな, どこに, ls, list]
+    test_cases:
+      - user_input: test/ にどんなファイルある?
+        expected_tool: list_directory
+
+  - name: run_command
+    category: shell
+    purpose: >
+      シェルコマンドを実行する。ビルド・テスト・git 操作・環境確認など、
+      実行結果を知る必要がある場合に使う。実行結果を推測で答えない。
+    when_to_use:
+      - ビルド・テスト・リント実行の依頼
+      - git 操作 (status, log, diff)
+      - 環境確認 (node -v, which, 等)
+      - パッケージのインストール・更新
+    usage: run_command <command>
+    examples:
+      - input: テスト通る?
+        call: run_command "npm test"
+      - input: git の状態
+        call: run_command "git status"
+    keywords: [実行, 走ら, ビルド, テスト, npm, git, run, build, test]
+    test_cases:
+      - user_input: node のバージョン確認して
+        expected_tool: run_command
+      - user_input: npm test 通るか見て
+        expected_tool: run_command