chore: add SQLite database handling and event tracking scripts

This commit introduces a new SQLite database setup for tracking tool usage events. It includes the following changes:
- Added `db.ts` for database initialization and schema creation.
- Implemented `trackEvent` function in `events.ts` to log events with relevant metadata.
- Created test files for both database operations and event tracking to ensure functionality and reliability.
- Added a CLI script (`tool-usage-collection.ts`) for collecting tool usage data via command-line arguments.

Additionally, updated `package.json` and `yarn.lock` to include necessary dependencies for SQLite and TypeScript support.

CHANGELOG entry: Added SQLite database handling for tool usage tracking.

Author: NicolasMassart

.cursor/agents/axi-tooling-reviewer.md

@@ -0,0 +1,71 @@
+---
+name: axi-tooling-reviewer
+description: Reviews CLI scripts and MCP tool definitions for AXI compliance (agent-ergonomic design). Use proactively when writing or modifying any script in scripts/tooling/, or when designing MCP tool responses, CLI output formats, or agent-facing interfaces. Checks against the 10 AXI principles from https://axi.md.
+---
+
+You are an expert in agent-ergonomic interface design, specialising in the AXI (Agent eXperience Interface) principles from https://axi.md.
+
+When invoked, you review scripts, MCP tool definitions, and CLI output formats to ensure they are token-efficient, robust, and discoverable for AI agents.
+
+## Your workflow
+
+1. Read the file(s) being reviewed using the Read tool
+2. Identify which AXI principles are violated or missing
+3. Provide concrete, actionable fixes with code examples
+4. Prioritise by impact (token cost > reliability > discoverability)
+
+## The 10 AXI principles to check against
+
+### Efficiency
+
+- **P1 — Token-efficient output**: Use TOON format instead of JSON for agent-readable output. Omit braces, quotes, and commas. Example: `events[3]{tool_name,event_type,created_at}:` followed by plain rows.
+- **P2 — Minimal default schemas**: Return 3–4 fields by default; offer `--fields` or `--full` to expand.
+- **P3 — Content truncation**: Truncate long strings with a size hint like `(truncated, 847 chars — use --full to see more)`.
+
+### Robustness
+
+- **P4 — Pre-computed aggregates**: Always include `totalCount`, success rates, abandonment rates. Never make the agent round-trip for summaries.
+- **P5 — Definitive empty states**: Always print an explicit zero-result message. Never return empty output — agents cannot distinguish empty from failure.
+- **P6 — Structured errors & exit codes**: Mutations must be idempotent. Errors to stdout (structured), debug to stderr. Exit 0 on success, 1 on error. Never prompt interactively.
+
+### Discoverability
+
+- **P7 — Ambient context**: Self-install into session hooks. Output a compact dashboard so agents see current state before acting.
+- **P8 — Content first**: Running with no args should show live data, not help text. Include the current executable path and a one-sentence description.
+- **P9 — Contextual disclosure**: After every output, append `hint[]` lines with concrete next-step command templates. Carry forward fixed flags; leave runtime values as `<placeholder>`.
+- **P10 — Consistent `--help`**: Every subcommand must have a concise `--help` flag as fallback.
+
+## Project context
+
+This project's tooling scripts live in `scripts/tooling/`:
+
+- `db.ts` — SQLite open/init (write only, AXI P6 applies to error handling)
+- `events.ts` — `trackEvent()` write function (P6: structured errors, idempotent)
+- `tool-usage-collection.ts` — CLI write wrapper called by hooks (P6: exit codes, P9: optional hint on success)
+- `tooling-mcp-server.ts` (Phase 2) — MCP write endpoint (P6: structured response with event_id)
+- `report.ts` (Phase 3) — Human + agent-facing inspect/report CLI (P1, P4, P5, P8, P9 all apply)
+- `check-skill-reporting-compliance.sh` (Phase 4) — Compliance checker (P5: always print count, P6: exit codes)
+
+## Output format for your reviews
+
+For each file, produce:
+
+```
+## <filename>
+
+violations[N]:
+  P<n> — <principle name>: <what is missing>
+    fix: <concrete code or command change>
+
+suggestions[M]:
+  P<n> — <principle name>: <nice-to-have improvement>
+    example: <code snippet>
+```
+
+If a file is fully compliant, output: `compliant: true — no AXI violations found`.
+
+## Key trade-offs for this project
+
+- `tool-usage-collection.ts` is intentionally **silent by default** (called from yarn hooks that must not pollute stdout). Suggest P9 hints only behind an opt-in `--verbose` flag.
+- `report.ts` is primarily **human-facing** (@clack/prompts UI), but should support `--agent` flag for TOON output (future MVP agent query interface).
+- The MCP `track_event` tool **must return a structured response** — even a minimal `{event_id, created_at}` confirmation — so the calling agent can verify the write succeeded.

package.json

@@ -562,6 +562,7 @@
     "@testing-library/react": "14.0.0",
     "@testing-library/react-hooks": "^8.0.1",
     "@testing-library/react-native": "^13.2.0",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/bnjs4": "npm:@types/bn.js@^4.11.6",
     "@types/bnjs5": "npm:@types/bn.js@^5.2.0",
     "@types/enzyme": "^3.10.12",
@@ -609,6 +610,7 @@
     "babel-plugin-transform-inline-environment-variables": "^0.4.4",
     "babel-plugin-transform-remove-console": "6.9.4",
     "base64-js": "^1.5.1",
+    "better-sqlite3": "^12.8.0",
     "chalk": "^4.1.2",
     "chromedriver": "^123.0.1",
     "depcheck": "^1.4.7",
@@ -670,6 +672,7 @@
     "simple-git": "^3.25.0",
     "tailwindcss": "^3.4.0",
     "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
     "typescript": "~5.4.5",
     "webdriverio": "^9.27.0",
     "webextension-polyfill": "^0.12.0",
@@ -781,6 +784,11 @@
       "eslint-import-resolver-typescript>unrs-resolver": false
     }
   },
+  "dependenciesMeta": {
+    "better-sqlite3": {
+      "built": true
+    }
+  },
   "packageManager": "yarn@4.10.3",
   "foundryup": {
     "binaries": [

scripts/tooling/db.test.ts

@@ -0,0 +1,133 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { openDb, DEFAULT_DB_PATH, DEFAULT_DB_DIR } from './db';
+
+describe('DEFAULT_DB_PATH', () => {
+  it('points inside the home directory', () => {
+    expect(DEFAULT_DB_PATH).toContain(os.homedir());
+    expect(DEFAULT_DB_PATH).toContain('events.db');
+    expect(DEFAULT_DB_DIR).toContain('.tool-usage-collection');
+  });
+});
+
+describe('openDb', () => {
+  it('creates the events table with all required columns', () => {
+    const db = openDb(':memory:');
+
+    const columns = db.prepare('PRAGMA table_info(events)').all() as {
+      name: string;
+    }[];
+    const names = columns.map((c) => c.name);
+
+    expect(names).toEqual([
+      'event_id',
+      'tool_name',
+      'tool_type',
+      'event_type',
+      'repo',
+      'agent_vendor',
+      'success',
+      'duration_ms',
+      'metadata',
+      'created_at',
+    ]);
+
+    db.close();
+  });
+
+  it('is idempotent — calling openDb twice on the same DB does not throw', () => {
+    const tmpPath = path.join(
+      os.tmpdir(),
+      `tool-usage-idempotent-${Date.now()}.db`,
+    );
+    const db1 = openDb(tmpPath);
+    db1.close();
+
+    // A second open should apply CREATE TABLE IF NOT EXISTS without error
+    const db2 = openDb(tmpPath);
+    db2.close();
+
+    fs.unlinkSync(tmpPath);
+  });
+
+  it('enforces the event_type CHECK constraint', () => {
+    const db = openDb(':memory:');
+
+    expect(() => {
+      db
+        .prepare(
+          `INSERT INTO events
+            (event_id, tool_name, tool_type, event_type, created_at)
+           VALUES (?, ?, ?, ?, ?)`,
+        )
+        .run('id-1', 'my-tool', 'skill', 'invalid', new Date().toISOString());
+    }).toThrow();
+
+    db.close();
+  });
+
+  it('accepts valid event rows', () => {
+    const db = openDb(':memory:');
+
+    const event = {
+      event_id: 'abc-123',
+      tool_name: 'worktree-create',
+      tool_type: 'skill',
+      event_type: 'start',
+      repo: 'MetaMask/metamask-mobile',
+      agent_vendor: 'cursor',
+      success: null,
+      duration_ms: null,
+      metadata: null,
+      created_at: '2026-04-09T10:00:00.000Z',
+    };
+
+    db.prepare(`
+      INSERT INTO events
+        (event_id, tool_name, tool_type, event_type, repo, agent_vendor, success, duration_ms, metadata, created_at)
+      VALUES
+        (@event_id, @tool_name, @tool_type, @event_type, @repo, @agent_vendor, @success, @duration_ms, @metadata, @created_at)
+    `).run(event);
+
+    const row = db
+      .prepare('SELECT * FROM events WHERE event_id = ?')
+      .get('abc-123') as typeof event;
+
+    expect(row).toMatchObject(event);
+
+    db.close();
+  });
+
+  it('enforces PRIMARY KEY uniqueness', () => {
+    const db = openDb(':memory:');
+
+    const insert = db.prepare(
+      `INSERT INTO events (event_id, tool_name, tool_type, event_type, created_at) VALUES (?, ?, ?, ?, ?)`,
+    );
+    insert.run('dup-id', 'tool', 'skill', 'start', new Date().toISOString());
+
+    expect(() => {
+      insert.run('dup-id', 'tool', 'skill', 'start', new Date().toISOString());
+    }).toThrow();
+
+    db.close();
+  });
+
+  it('creates the db directory when it does not exist', () => {
+    const tmpDir = path.join(
+      os.tmpdir(),
+      `tool-usage-newdir-${Date.now()}`,
+      'nested',
+    );
+    const tmpDb = path.join(tmpDir, 'events.db');
+
+    expect(fs.existsSync(tmpDir)).toBe(false);
+
+    const db = openDb(tmpDb);
+    expect(fs.existsSync(tmpDb)).toBe(true);
+    db.close();
+
+    fs.rmSync(path.dirname(tmpDir), { recursive: true });
+  });
+});

scripts/tooling/db.ts

@@ -0,0 +1,48 @@
+import Database from 'better-sqlite3';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+export const DEFAULT_DB_DIR = path.join(os.homedir(), '.tool-usage-collection');
+export const DEFAULT_DB_PATH = path.join(DEFAULT_DB_DIR, 'events.db');
+
+/**
+ * Opens (or creates) the tool-usage SQLite database, initialises the schema,
+ * and enables WAL mode for safe concurrent writes from multiple processes.
+ *
+ * Pass ':memory:' during tests to avoid touching the filesystem.
+ */
+export function openDb(dbPath = DEFAULT_DB_PATH): Database.Database {
+  // WAL journal mode requires a real file; skip dir creation and pragma for memory DBs
+  const isMemory = dbPath === ':memory:';
+
+  if (!isMemory) {
+    const dir = path.dirname(dbPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  const db = new Database(dbPath);
+
+  if (!isMemory) {
+    db.pragma('journal_mode = WAL');
+  }
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS events (
+      event_id     TEXT PRIMARY KEY,
+      tool_name    TEXT NOT NULL,
+      tool_type    TEXT NOT NULL,
+      event_type   TEXT NOT NULL CHECK(event_type IN ('start', 'end')),
+      repo         TEXT,
+      agent_vendor TEXT,
+      success      INTEGER,
+      duration_ms  INTEGER,
+      metadata     TEXT,
+      created_at   TEXT NOT NULL
+    )
+  `);
+
+  return db;
+}