claude-spotter 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.0 (Unreleased)
+
+Initial release.
+
+### Features
+
+- Session-scoped daemon that audits tool usage alongside Claude Code (Bell)
+- 5 hooks wired: SessionStart / UserPromptSubmit / PreToolUse / Stop / SessionEnd
+- YAML tool catalog with 2-stage context (purpose/when_to_use first, usage/examples after)
+- Structured JSON I/O with Claude Haiku 4.5
+- Cross-platform socket transport (Unix domain socket / Windows Named Pipe via Node `net`)
+- `spotter install / uninstall / catalog edit / catalog lint / status / doctor` CLI
+
+### Dependencies
+
+- `js-yaml` (4.x) — required for catalog parsing. Node has no built-in YAML support, and hand-rolling a parser adds subtle bugs that violate §14.2 "no shim code" discipline. This is the single exception to the zero-dependency goal (§15.2).
+
+### Design
+
+All non-negotiable design decisions — including transparency vs invisibility, JSON I/O, socket abstraction, message envelope, SessionStart readiness — are documented in [docs/spotter-plan.md](docs/spotter-plan.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kitepon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# Spotter
+
+**気づく役と実行する役を分離する。** Spotter は Claude Code の横で静かに並走し、Bell (主役の Claude) が**ツールを呼び忘れたとき**に指摘する監査役です。
+
+> Claude には「使えるツールがあるのに、使うべきタイミングで使わない」という構造的な弱点があります。現在時刻を推測で答える、web_search を呼ばずに古い情報で応答する、read_file を使わずにファイルの中身を推測する — 「分からないと自覚できない」から、ツールを取りに行けない。
+
+Spotter は、ツールカタログを完全に把握した別エージェント (Claude Haiku 4.5) をセッション毎にプロセスとして常駐させ、Bell の発話予定と応答を並走監査します。見落としを検出すると、透明化された指摘として Bell に届け、補正応答を促します。
+
+## インストール
+
+```bash
+npm install -g claude-spotter
+spotter install     # .claude/settings.json に hook を登録 (diff を見せて確認)
+```
+
+次回 Claude Code セッションから自動で有効になります。
+
+## 動作要件
+
+- Node.js **22.5 以上**
+- Claude Code **2.0 以上**
+- Claude **Max プラン** (`claude -p` で Haiku を起動するため)
+
+## コンセプト
+
+```
+User 発話
+  ↓
+UserPromptSubmit hook → Spotter がカタログと発話を見て一次判定
+  ↓
+Bell Thinking (Spotter の推奨を additionalContext で受け取る)
+  ↓
+Bell 最終応答
+  ↓
+Stop hook → Spotter が応答と使用済みツールを見て最終チェック
+  ↓
+見落としあれば差し戻し (max 1 回、Claude Code の stop_hook_active で自動担保)
+```
+
+`~/.spotter/tool-catalog/tools.yaml` に監査対象のツール用途を記述します。`current_time` / `web_search` / `read_file` / `list_directory` / `run_command` の雛形付き。
+
+## Throughline との関係
+
+[Throughline](https://github.com/kitepon-rgb/Throughline) と Spotter は同じ作者が作った、**哲学を共有する別プロダクト**です。
+
+|  | Throughline | Spotter |
+|---|---|---|
+| 思想 | 引き算 (要らないものを退避) | 足し算 (足りない動作に気づかせる) |
+| 対象 | コンテキスト肥大化 | ツール取りこぼし |
+| 仕組み | hook で記憶退避 | hook でサブエージェント並走 |
+
+両者に共通するのは **「主体 (Bell) に頼らない仕組み」**。併用できます。
+
+## よく使うコマンド
+
+```bash
+spotter catalog edit     # ツールカタログを $EDITOR で開く
+spotter catalog lint     # YAML 検証 + test_cases を Haiku 実呼びで検証
+spotter status           # 稼働中の daemon 一覧
+spotter doctor           # 環境診断 (Node / claude CLI / カタログ整合性)
+spotter uninstall        # hook 登録を解除 (~/.spotter は残す)
+```
+
+## 設計ドキュメント
+
+全ての設計判断 — 透明化 vs 不可視化、JSON I/O、socket 抽象、メッセージ契約、SessionStart の readiness 戦略、§0 実装規範 — は [docs/spotter-plan.md](docs/spotter-plan.md) に記載しています。**実装を変更する前に必ず参照してください。**
+
+## 既知の制約
+
+- Stop hook は Bell の最初の応答が**出力された後**に発火するため、Spotter が Stop で差し戻した場合、ユーザーは「最初の応答 + 補正応答」の 2 連続を見ます (Claude Code の hook 仕様による制約)。UserPromptSubmit 段階での先回り検出を精度の軸にしています
+- v0.1 は JSON スキーマ違反時にリトライせず即 throw します (§14.1 silent fallback 禁止の帰結)。遵守率が下振れた場合は v0.2 でリトライ戦略を追加します
+
+## ライセンス
+
+MIT — see [LICENSE](LICENSE).

package/bin/spotter.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// spotter — CLI entry point.
+// dispatches to src/cli/* and src/hooks/*.
+
+import { runInstall } from '../src/cli/install.mjs';
+import { runUninstall } from '../src/cli/uninstall.mjs';
+import { runDoctor } from '../src/cli/doctor.mjs';
+import { runStatus } from '../src/cli/status.mjs';
+import { runCatalogEdit, runCatalogLint } from '../src/cli/catalog.mjs';
+import { runDaemonStart } from '../src/cli/daemon-cmd.mjs';
+import { runSessionStart } from '../src/hooks/session-start.mjs';
+import { runUserPrompt } from '../src/hooks/user-prompt.mjs';
+import { runPreToolUse } from '../src/hooks/pre-tool-use.mjs';
+import { runStop } from '../src/hooks/stop.mjs';
+import { runSessionEnd } from '../src/hooks/session-end.mjs';
+
+const USAGE = `spotter — Claude Code tool-call auditor
+
+Usage:
+  spotter install [--user] [-y]         register hooks in .claude/settings.json
+  spotter uninstall [--user] [-y]       remove spotter hooks
+  spotter catalog edit                  open tool catalog in $EDITOR
+  spotter catalog lint                  validate catalog + run test_cases (Haiku live call)
+  spotter status                        show running daemons
+  spotter doctor                        environment diagnostic
+  spotter daemon start --session-id ID  (internal) run session daemon
+  spotter hook <event>                  (internal) hook dispatch
+                                        events: session-start | user-prompt |
+                                                pre-tool-use | stop | session-end
+  spotter --help | -h                   this message
+  spotter --version | -v                version
+`;
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (argv[0] === '--version' || argv[0] === '-v') {
+    const { version } = await import('../src/version.mjs');
+    process.stdout.write(`spotter ${version}\n`);
+    return;
+  }
+
+  const [cmd, ...rest] = argv;
+  switch (cmd) {
+    case 'install': {
+      const target = rest.includes('--user') ? 'user' : 'project';
+      const autoYes = rest.includes('-y') || rest.includes('--yes');
+      await runInstall({ target, autoYes });
+      return;
+    }
+    case 'uninstall': {
+      const target = rest.includes('--user') ? 'user' : 'project';
+      const autoYes = rest.includes('-y') || rest.includes('--yes');
+      await runUninstall({ target, autoYes });
+      return;
+    }
+    case 'catalog': {
+      const sub = rest[0];
+      if (sub === 'edit') { await runCatalogEdit(); return; }
+      if (sub === 'lint') { await runCatalogLint(); return; }
+      process.stderr.write(`unknown catalog subcommand: ${sub}\n${USAGE}`);
+      process.exit(2);
+      return;
+    }
+    case 'status':
+      await runStatus();
+      return;
+    case 'doctor':
+      await runDoctor();
+      return;
+    case 'daemon': {
+      const sub = rest[0];
+      if (sub === 'start') { await runDaemonStart({ argv: rest.slice(1) }); return; }
+      process.stderr.write(`unknown daemon subcommand: ${sub}\n${USAGE}`);
+      process.exit(2);
+      return;
+    }
+    case 'hook': {
+      const event = rest[0];
+      switch (event) {
+        case 'session-start': await runSessionStart(); return;
+        case 'user-prompt': await runUserPrompt(); return;
+        case 'pre-tool-use': await runPreToolUse(); return;
+        case 'stop': await runStop(); return;
+        case 'session-end': await runSessionEnd(); return;
+        default:
+          process.stderr.write(`unknown hook event: ${event}\n${USAGE}`);
+          process.exit(2);
+      }
+      return;
+    }
+    default:
+      process.stderr.write(`unknown command: ${cmd}\n${USAGE}`);
+      process.exit(2);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`spotter: ${err.stack || err.message || err}\n`);
+  process.exit(err.exitCode ?? 2);
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "claude-spotter",
+  "version": "0.1.0",
+  "description": "Audit agent running alongside Claude Code that catches missed tool calls — 気づく役と実行する役の分離",
+  "type": "module",
+  "bin": {
+    "spotter": "./bin/spotter.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "hooks",
+    "agent",
+    "tool-use",
+    "audit",
+    "spotter"
+  ],
+  "author": "kitepon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kitepon-rgb/Spotter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kitepon-rgb/Spotter/issues"
+  },
+  "homepage": "https://github.com/kitepon-rgb/Spotter#readme",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ]
+}

package/src/catalog/lint.mjs

@@ -0,0 +1,56 @@
+// `spotter catalog lint` — schema validation + test_cases execution against live Haiku.
+// §11: v0.1 completion metric = this command passes. No mocks (§14.1 silent-fallback discipline).
+
+import { loadCatalog } from './loader.mjs';
+import { buildFirstStagePrompt, parseHaikuResponse } from '../daemon/haiku-caller.mjs';
+
+export async function runLint({ catalogPath, haikuCaller, writeLine }) {
+  writeLine(`lint: loading ${catalogPath}`);
+  const catalog = await loadCatalog(catalogPath);
+  writeLine(`lint: loaded ${catalog.tools.length} tools, validating test_cases...`);
+
+  const totalCases = catalog.tools.reduce(
+    (sum, t) => sum + (Array.isArray(t.test_cases) ? t.test_cases.length : 0),
+    0
+  );
+  if (totalCases === 0) {
+    writeLine('lint: no test_cases present — schema validation only, passed');
+    return { passed: 0, failed: 0, total: 0 };
+  }
+
+  let passed = 0;
+  const failures = [];
+
+  for (const tool of catalog.tools) {
+    if (!Array.isArray(tool.test_cases)) continue;
+    for (const tc of tool.test_cases) {
+      const prompt = buildFirstStagePrompt({
+        catalog,
+        userInput: tc.user_input,
+      });
+      const rawResponse = await haikuCaller(prompt);
+      const parsed = parseHaikuResponse(rawResponse);
+      const detectedNames = parsed.missing_tools.map((m) => m.name);
+      const hit = detectedNames.includes(tc.expected_tool);
+      if (hit) {
+        passed += 1;
+        writeLine(`  PASS  ${tool.name} :: "${tc.user_input}" → ${tc.expected_tool}`);
+      } else {
+        failures.push({
+          tool: tool.name,
+          user_input: tc.user_input,
+          expected: tc.expected_tool,
+          detected: detectedNames,
+        });
+        writeLine(
+          `  FAIL  ${tool.name} :: "${tc.user_input}" → expected ${tc.expected_tool}, detected [${detectedNames.join(', ') || '-'}]`
+        );
+      }
+    }
+  }
+
+  const failed = failures.length;
+  writeLine('');
+  writeLine(`lint summary: ${passed}/${totalCases} passed, ${failed} failed`);
+  return { passed, failed, total: totalCases, failures };
+}

package/src/catalog/loader.mjs

@@ -0,0 +1,36 @@
+import { readFile } from 'node:fs/promises';
+import yaml from 'js-yaml';
+import { validateCatalog, CatalogSchemaError } from './schema.mjs';
+
+export class CatalogLoadError extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.name = 'CatalogLoadError';
+    if (cause) this.cause = cause;
+  }
+}
+
+export async function loadCatalog(path) {
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new CatalogLoadError(`catalog not found: ${path}`, err);
+    }
+    throw new CatalogLoadError(`cannot read catalog: ${path}`, err);
+  }
+
+  let parsed;
+  try {
+    parsed = yaml.load(raw);
+  } catch (err) {
+    throw new CatalogLoadError(`yaml parse failed in ${path}: ${err.message}`, err);
+  }
+
+  // schema errors propagate as CatalogSchemaError — the caller can distinguish them
+  validateCatalog(parsed);
+  return parsed;
+}
+
+export { CatalogSchemaError };

package/src/catalog/schema.mjs

@@ -0,0 +1,109 @@
+// Tool catalog schema validation.
+// §0 rule: catalog shape violations throw. No silent coercion, no defaults-that-hide-bugs.
+
+const REQUIRED_TOOL_FIELDS = ['name', 'purpose', 'when_to_use'];
+const REQUIRED_TEST_CASE_FIELDS = ['user_input', 'expected_tool'];
+
+export class CatalogSchemaError extends Error {
+  constructor(message, path) {
+    super(`catalog schema violation at ${path}: ${message}`);
+    this.name = 'CatalogSchemaError';
+    this.path = path;
+  }
+}
+
+export function validateCatalog(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new CatalogSchemaError('root must be an object', '$');
+  }
+  if (raw.version !== 1) {
+    throw new CatalogSchemaError(`version must be 1, got ${JSON.stringify(raw.version)}`, '$.version');
+  }
+  if (!Array.isArray(raw.tools)) {
+    throw new CatalogSchemaError('tools must be an array', '$.tools');
+  }
+  if (raw.tools.length === 0) {
+    throw new CatalogSchemaError('tools must contain at least one entry', '$.tools');
+  }
+
+  const seen = new Set();
+  raw.tools.forEach((tool, i) => validateTool(tool, `$.tools[${i}]`, seen));
+
+  return raw;
+}
+
+function validateTool(tool, path, seen) {
+  if (tool === null || typeof tool !== 'object' || Array.isArray(tool)) {
+    throw new CatalogSchemaError('tool entry must be an object', path);
+  }
+  for (const field of REQUIRED_TOOL_FIELDS) {
+    if (!(field in tool)) {
+      throw new CatalogSchemaError(`missing required field "${field}"`, path);
+    }
+  }
+  if (typeof tool.name !== 'string' || tool.name.length === 0) {
+    throw new CatalogSchemaError('name must be a non-empty string', `${path}.name`);
+  }
+  if (seen.has(tool.name)) {
+    throw new CatalogSchemaError(`duplicate tool name "${tool.name}"`, `${path}.name`);
+  }
+  seen.add(tool.name);
+
+  if (typeof tool.purpose !== 'string' || tool.purpose.trim().length === 0) {
+    throw new CatalogSchemaError('purpose must be a non-empty string', `${path}.purpose`);
+  }
+  if (!Array.isArray(tool.when_to_use) || tool.when_to_use.length === 0) {
+    throw new CatalogSchemaError('when_to_use must be a non-empty array', `${path}.when_to_use`);
+  }
+  tool.when_to_use.forEach((entry, i) => {
+    if (typeof entry !== 'string' || entry.length === 0) {
+      throw new CatalogSchemaError('when_to_use entries must be non-empty strings', `${path}.when_to_use[${i}]`);
+    }
+  });
+
+  if ('test_cases' in tool) {
+    if (!Array.isArray(tool.test_cases)) {
+      throw new CatalogSchemaError('test_cases must be an array', `${path}.test_cases`);
+    }
+    tool.test_cases.forEach((tc, i) => validateTestCase(tc, `${path}.test_cases[${i}]`));
+  }
+}
+
+function validateTestCase(tc, path) {
+  if (tc === null || typeof tc !== 'object' || Array.isArray(tc)) {
+    throw new CatalogSchemaError('test case must be an object', path);
+  }
+  for (const field of REQUIRED_TEST_CASE_FIELDS) {
+    if (!(field in tc)) {
+      throw new CatalogSchemaError(`missing required field "${field}"`, path);
+    }
+  }
+  if (typeof tc.user_input !== 'string' || tc.user_input.length === 0) {
+    throw new CatalogSchemaError('user_input must be a non-empty string', `${path}.user_input`);
+  }
+  if (typeof tc.expected_tool !== 'string' || tc.expected_tool.length === 0) {
+    throw new CatalogSchemaError('expected_tool must be a non-empty string', `${path}.expected_tool`);
+  }
+}
+
+// Projection for Haiku first-stage judgement (§6.3).
+export function projectForFirstStage(catalog) {
+  return catalog.tools.map((tool) => ({
+    name: tool.name,
+    purpose: tool.purpose,
+    when_to_use: tool.when_to_use,
+  }));
+}
+
+// Projection for Haiku final-stage judgement — adds usage/examples when name matches.
+export function projectForFinalStage(catalog, candidateNames) {
+  return catalog.tools
+    .filter((tool) => candidateNames.includes(tool.name))
+    .map((tool) => ({
+      name: tool.name,
+      purpose: tool.purpose,
+      when_to_use: tool.when_to_use,
+      usage: tool.usage ?? null,
+      examples: tool.examples ?? [],
+    }));
+}

package/src/cli/catalog.mjs

@@ -0,0 +1,37 @@
+// `spotter catalog edit|lint`
+//
+// edit: open the catalog in $EDITOR
+// lint: validate schema + run test_cases against live Haiku (v0.1 completion metric)
+
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { runLint } from '../catalog/lint.mjs';
+import { createHaikuCaller } from '../daemon/haiku-caller.mjs';
+
+const CATALOG_PATH = join(homedir(), '.spotter', 'tool-catalog', 'tools.yaml');
+
+export async function runCatalogEdit() {
+  const editor = process.env.EDITOR || process.env.VISUAL || defaultEditor();
+  await new Promise((resolve, reject) => {
+    const child = spawn(editor, [CATALOG_PATH], { stdio: 'inherit' });
+    child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`editor exited with ${code}`))));
+    child.on('error', reject);
+  });
+}
+
+function defaultEditor() {
+  return process.platform === 'win32' ? 'notepad' : 'vi';
+}
+
+export async function runCatalogLint({ catalogPath = CATALOG_PATH } = {}) {
+  const haikuCaller = createHaikuCaller({ timeoutMs: 30_000 });
+  const result = await runLint({
+    catalogPath,
+    haikuCaller,
+    writeLine: (s) => console.log(s),
+  });
+  if (result.failed > 0) {
+    process.exit(1);
+  }
+}

package/src/cli/daemon-cmd.mjs

@@ -0,0 +1,41 @@
+// `spotter daemon start|stop` — internal commands invoked by SessionStart/SessionEnd hooks.
+
+import { startDaemon } from '../daemon/daemon.mjs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { open } from 'node:fs/promises';
+
+function parseArgs(argv) {
+  const out = { sessionId: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--session-id') {
+      out.sessionId = argv[i + 1];
+      i += 1;
+    }
+  }
+  return out;
+}
+
+export async function runDaemonStart({ argv }) {
+  const { sessionId } = parseArgs(argv);
+  if (!sessionId) {
+    process.stderr.write('spotter daemon start: --session-id is required\n');
+    process.exit(2);
+  }
+
+  const logFile = await open(
+    join(homedir(), '.spotter', 'logs', `daemon-${sessionId}.log`),
+    'a'
+  );
+  const log = (msg) => {
+    const line = `[${new Date().toISOString()}] ${msg}\n`;
+    logFile.write(line).catch(() => {});
+  };
+
+  const running = await startDaemon({ sessionId, logFn: log });
+  log(`started on ${running.path}`);
+
+  // Keep process alive; SessionEnd → shutdown event triggers server.close() which resolves the await.
+  await new Promise((resolve) => running.server.on('close', resolve));
+  log('server closed, exiting');
+}

package/src/cli/doctor.mjs

@@ -0,0 +1,74 @@
+// `spotter doctor` — environment diagnostic.
+
+import { access, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { loadCatalog } from '../catalog/loader.mjs';
+
+const execFileP = promisify(execFile);
+
+export async function runDoctor() {
+  console.log('spotter doctor');
+  let warnings = 0;
+  let failures = 0;
+
+  // Node version
+  const nodeVersion = process.versions.node;
+  const major = parseInt(nodeVersion.split('.')[0], 10);
+  const minor = parseInt(nodeVersion.split('.')[1], 10);
+  const okNode = major > 22 || (major === 22 && minor >= 5);
+  mark(okNode, `Node.js ${nodeVersion}`, 'need >= 22.5');
+  if (!okNode) failures += 1;
+
+  // claude CLI — on Windows the entry is `claude.cmd`; route through cmd.exe /c
+  // rather than shell:true (DEP0190 on Node 24+).
+  try {
+    const opts = { timeout: 5_000, windowsHide: true };
+    const { stdout } = process.platform === 'win32'
+      ? await execFileP('cmd.exe', ['/c', 'claude', '--version'], opts)
+      : await execFileP('claude', ['--version'], opts);
+    mark(true, `claude CLI: ${stdout.trim()}`);
+  } catch (err) {
+    mark(false, 'claude CLI', `not found or failed: ${err.message}`);
+    failures += 1;
+  }
+
+  // ~/.spotter directories
+  const home = join(homedir(), '.spotter');
+  for (const sub of ['tool-catalog', 'runtime', 'workdir', 'logs']) {
+    const path = join(home, sub);
+    const ok = await exists(path);
+    mark(ok, `dir ${path}`);
+    if (!ok) warnings += 1;
+  }
+
+  // catalog
+  const catalogPath = join(home, 'tool-catalog', 'tools.yaml');
+  try {
+    const cat = await loadCatalog(catalogPath);
+    mark(true, `catalog: ${cat.tools.length} tools at ${catalogPath}`);
+  } catch (err) {
+    mark(false, 'catalog', err.message);
+    failures += 1;
+  }
+
+  console.log('');
+  if (failures > 0) {
+    console.log(`result: ${failures} failure(s), ${warnings} warning(s)`);
+    process.exit(1);
+  }
+  console.log(`result: OK (${warnings} warnings)`);
+}
+
+async function exists(path) {
+  try { await access(path); return true; }
+  catch { return false; }
+}
+
+function mark(ok, label, detail) {
+  const icon = ok ? 'OK ' : 'NG ';
+  const line = detail ? `${label} — ${detail}` : label;
+  console.log(`  ${icon} ${line}`);
+}