@panchr/tyr 0.1.0

package/src/db.ts

@@ -0,0 +1,229 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/** Current schema version. Bump when schema changes require migration. */
+export const CURRENT_SCHEMA_VERSION = 1;
+
+const DEFAULT_DB_DIR = join(homedir(), ".local", "share", "tyr");
+const DEFAULT_DB_FILE = join(DEFAULT_DB_DIR, "tyr.db");
+
+export function getDbPath(): string {
+	return process.env.TYR_DB_PATH ?? DEFAULT_DB_FILE;
+}
+
+let instance: Database | null = null;
+
+const SCHEMA_STATEMENTS = [
+	`CREATE TABLE IF NOT EXISTS _meta (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+)`,
+	`CREATE TABLE IF NOT EXISTS logs (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp   INTEGER NOT NULL,
+    session_id  TEXT    NOT NULL,
+    cwd         TEXT    NOT NULL,
+    tool_name   TEXT    NOT NULL,
+    tool_input  TEXT    NOT NULL,
+    input       TEXT    NOT NULL,
+    decision    TEXT    NOT NULL CHECK (decision IN ('allow','deny','abstain','error')),
+    provider    TEXT,
+    reason      TEXT,
+    duration_ms INTEGER NOT NULL,
+    cached      INTEGER NOT NULL DEFAULT 0,
+    mode        TEXT    CHECK (mode IN ('shadow','audit') OR mode IS NULL)
+)`,
+	"CREATE INDEX IF NOT EXISTS idx_logs_timestamp ON logs (timestamp)",
+	"CREATE INDEX IF NOT EXISTS idx_logs_session   ON logs (session_id)",
+	"CREATE INDEX IF NOT EXISTS idx_logs_suggest   ON logs (decision, mode, tool_input)",
+	`CREATE TABLE IF NOT EXISTS llm_logs (
+    id       INTEGER PRIMARY KEY AUTOINCREMENT,
+    log_id   INTEGER NOT NULL REFERENCES logs(id),
+    prompt   TEXT    NOT NULL,
+    model    TEXT    NOT NULL
+)`,
+	"CREATE INDEX IF NOT EXISTS idx_llm_logs_log_id ON llm_logs (log_id)",
+	`CREATE TABLE IF NOT EXISTS cache (
+    tool_name   TEXT    NOT NULL,
+    tool_input  TEXT    NOT NULL,
+    cwd         TEXT    NOT NULL,
+    decision    TEXT    NOT NULL CHECK (decision IN ('allow','deny')),
+    provider    TEXT    NOT NULL,
+    reason      TEXT,
+    config_hash TEXT    NOT NULL,
+    created_at  INTEGER NOT NULL,
+    PRIMARY KEY (tool_name, tool_input, cwd, config_hash)
+)`,
+];
+
+export function getSchemaVersion(db: Database): number | null {
+	const row = db
+		.query("SELECT value FROM _meta WHERE key = 'schema_version'")
+		.get() as { value: string } | null;
+	return row ? Number(row.value) : null;
+}
+
+function checkVersion(version: number): void {
+	if (version < CURRENT_SCHEMA_VERSION) {
+		throw new Error(
+			`[tyr] database schema is v${version} but tyr requires v${CURRENT_SCHEMA_VERSION}. Run 'tyr db migrate' to upgrade.`,
+		);
+	}
+	if (version > CURRENT_SCHEMA_VERSION) {
+		throw new Error(
+			`[tyr] database schema is v${version} but this tyr only supports up to v${CURRENT_SCHEMA_VERSION}. Upgrade tyr.`,
+		);
+	}
+}
+
+/**
+ * Sequential migration functions. Each entry migrates from version N to N+1.
+ * migrations[0] migrates v1 → v2, migrations[1] migrates v2 → v3, etc.
+ *
+ * Rules for writing migrations:
+ * - cache table is ephemeral: DROP + CREATE is fine
+ * - logs/llm_logs are historical: only ADD COLUMN, never drop data
+ * - For complex changes, use rename-copy-drop pattern
+ */
+export const migrations: ReadonlyArray<(db: Database) => void> = [
+	// Add new migration functions here when CURRENT_SCHEMA_VERSION is bumped.
+	// Example: (db) => { db.run("ALTER TABLE logs ADD COLUMN new_col TEXT"); }
+];
+
+export interface MigrationResult {
+	fromVersion: number;
+	toVersion: number;
+	applied: number;
+}
+
+/** Run pending migrations from current version up to CURRENT_SCHEMA_VERSION. */
+export function runMigrations(db: Database): MigrationResult {
+	if (!hasMetaTable(db)) {
+		throw new Error(
+			"[tyr] database has no _meta table. Cannot migrate an uninitialized database.",
+		);
+	}
+
+	const version = getSchemaVersion(db);
+	if (version === null) {
+		throw new Error(
+			"[tyr] database is missing schema_version. Cannot determine migration starting point.",
+		);
+	}
+
+	if (version > CURRENT_SCHEMA_VERSION) {
+		throw new Error(
+			`[tyr] database schema is v${version} but this tyr only supports up to v${CURRENT_SCHEMA_VERSION}. Upgrade tyr.`,
+		);
+	}
+
+	if (version === CURRENT_SCHEMA_VERSION) {
+		return { fromVersion: version, toVersion: version, applied: 0 };
+	}
+
+	const fromVersion = version;
+	db.transaction(() => {
+		for (let v = version; v < CURRENT_SCHEMA_VERSION; v++) {
+			const migrate = migrations[v - 1];
+			if (!migrate) {
+				throw new Error(
+					`[tyr] missing migration function for v${v} → v${v + 1}`,
+				);
+			}
+			migrate(db);
+		}
+		db.query("UPDATE _meta SET value = ? WHERE key = 'schema_version'").run(
+			String(CURRENT_SCHEMA_VERSION),
+		);
+	})();
+
+	return {
+		fromVersion,
+		toVersion: CURRENT_SCHEMA_VERSION,
+		applied: CURRENT_SCHEMA_VERSION - fromVersion,
+	};
+}
+
+export function hasMetaTable(db: Database): boolean {
+	const row = db
+		.query("SELECT 1 FROM sqlite_master WHERE type='table' AND name='_meta'")
+		.get();
+	return row !== null;
+}
+
+function setPragmas(db: Database): void {
+	const walResult = db.query("PRAGMA journal_mode = WAL").get() as {
+		journal_mode: string;
+	};
+	if (walResult.journal_mode !== "wal") {
+		throw new Error(
+			`[tyr] failed to enable WAL mode (got ${walResult.journal_mode})`,
+		);
+	}
+	db.run("PRAGMA busy_timeout = 5000");
+	db.run("PRAGMA foreign_keys = ON");
+}
+
+/** Open a raw Database connection with PRAGMAs set, bypassing version checks. */
+export function openRawDb(dbPath?: string): Database {
+	const p = dbPath ?? getDbPath();
+	mkdirSync(dirname(p), { recursive: true });
+	const db = new Database(p);
+	setPragmas(db);
+	return db;
+}
+
+function initDb(db: Database): void {
+	setPragmas(db);
+
+	// If _meta exists, this is an existing DB — check version before touching anything
+	if (hasMetaTable(db)) {
+		const version = getSchemaVersion(db);
+		if (version === null) {
+			throw new Error(
+				"[tyr] database is missing schema_version. Delete the DB or run 'tyr db migrate'.",
+			);
+		}
+		checkVersion(version);
+		return;
+	}
+
+	// First-time initialization — create all tables in a transaction
+	db.transaction(() => {
+		for (const stmt of SCHEMA_STATEMENTS) {
+			db.run(stmt);
+		}
+		db.query("INSERT INTO _meta (key, value) VALUES ('schema_version', ?)").run(
+			String(CURRENT_SCHEMA_VERSION),
+		);
+	})();
+}
+
+/** Get (or create) the singleton SQLite database connection. */
+export function getDb(): Database {
+	if (instance) return instance;
+
+	const dbPath = getDbPath();
+	mkdirSync(dirname(dbPath), { recursive: true });
+
+	const db = new Database(dbPath);
+	initDb(db);
+
+	instance = db;
+	return db;
+}
+
+/** Close the singleton connection. Safe to call multiple times. */
+export function closeDb(): void {
+	if (instance) {
+		instance.close();
+		instance = null;
+	}
+}
+
+/** Reset the singleton (for tests). Closes the connection first. */
+export function resetDbInstance(): void {
+	closeDb();
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+
+import { defineCommand, runMain } from "citty";
+import config from "./commands/config.ts";
+import db from "./commands/db.ts";
+import debug from "./commands/debug.ts";
+import install from "./commands/install.ts";
+import judge from "./commands/judge.ts";
+import log from "./commands/log.ts";
+import stats from "./commands/stats.ts";
+import suggest from "./commands/suggest.ts";
+import uninstall from "./commands/uninstall.ts";
+import version from "./commands/version.ts";
+import { VERSION } from "./version.ts";
+
+const main = defineCommand({
+	meta: {
+		name: "tyr",
+		version: VERSION,
+		description: "Intelligent permission management for Claude Code hooks",
+	},
+	subCommands: {
+		config,
+		db,
+		debug,
+		install,
+		judge,
+		log,
+		stats,
+		suggest,
+		uninstall,
+		version,
+	},
+});
+
+runMain(main);

package/src/install.ts

@@ -0,0 +1,116 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export type JudgeMode = "shadow" | "audit" | undefined;
+
+function tyrCommand(mode: JudgeMode): string {
+	if (mode) return `tyr judge --${mode}`;
+	return "tyr judge";
+}
+
+function tyrHookEntry(mode: JudgeMode) {
+	return {
+		matcher: "Bash",
+		hooks: [{ type: "command", command: tyrCommand(mode) }],
+	};
+}
+
+export function getSettingsPath(scope: "global" | "project"): string {
+	if (scope === "global") {
+		return join(homedir(), ".claude", "settings.json");
+	}
+	return join(process.cwd(), ".claude", "settings.json");
+}
+
+/** Read and parse a settings.json, returning {} if it doesn't exist. */
+export async function readSettings(
+	path: string,
+): Promise<Record<string, unknown>> {
+	try {
+		const text = await readFile(path, "utf-8");
+		return JSON.parse(text) as Record<string, unknown>;
+	} catch {
+		return {};
+	}
+}
+
+/** Check if tyr is already installed in the given settings. */
+export function isInstalled(settings: Record<string, unknown>): boolean {
+	const hooks = settings.hooks as Record<string, unknown> | undefined;
+	if (!hooks) return false;
+
+	const permReqs = hooks.PermissionRequest;
+	if (!Array.isArray(permReqs)) return false;
+
+	return permReqs.some((entry: Record<string, unknown>) => isTyrEntry(entry));
+}
+
+/** Merge the tyr hook into settings without clobbering existing hooks.
+ *  If a tyr entry already exists it is replaced so install is idempotent. */
+export function mergeHook(
+	settings: Record<string, unknown>,
+	mode?: JudgeMode,
+): Record<string, unknown> {
+	const result = { ...settings };
+	const hooks = (result.hooks ?? {}) as Record<string, unknown>;
+	const permReqs = Array.isArray(hooks.PermissionRequest)
+		? (hooks.PermissionRequest as Record<string, unknown>[]).filter(
+				(entry) => !isTyrEntry(entry),
+			)
+		: [];
+
+	permReqs.push(tyrHookEntry(mode));
+
+	result.hooks = { ...hooks, PermissionRequest: permReqs };
+	return result;
+}
+
+/** Check if a PermissionRequest entry belongs to tyr. */
+function isTyrEntry(entry: Record<string, unknown>): boolean {
+	const entryHooks = entry.hooks;
+	if (!Array.isArray(entryHooks)) return false;
+	return entryHooks.some(
+		(h: Record<string, unknown>) =>
+			h.type === "command" &&
+			typeof h.command === "string" &&
+			h.command.startsWith("tyr "),
+	);
+}
+
+/** Remove the tyr hook from settings, returning the cleaned settings.
+ *  Returns null if tyr was not installed. */
+export function removeHook(
+	settings: Record<string, unknown>,
+): Record<string, unknown> | null {
+	if (!isInstalled(settings)) return null;
+
+	const result = { ...settings };
+	const hooks = { ...(result.hooks as Record<string, unknown>) };
+	const permReqs = hooks.PermissionRequest as Record<string, unknown>[];
+	const filtered = permReqs.filter((entry) => !isTyrEntry(entry));
+
+	if (filtered.length > 0) {
+		hooks.PermissionRequest = filtered;
+	} else {
+		delete hooks.PermissionRequest;
+	}
+
+	// Clean up empty hooks object
+	if (Object.keys(hooks).length === 0) {
+		delete result.hooks;
+	} else {
+		result.hooks = hooks;
+	}
+
+	return result;
+}
+
+/** Write settings to disk, creating parent directories as needed. */
+export async function writeSettings(
+	path: string,
+	settings: Record<string, unknown>,
+): Promise<void> {
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+}

package/src/judge.ts

@@ -0,0 +1,19 @@
+import { type PermissionRequest, PermissionRequestSchema } from "./types.ts";
+
+/** Parse and validate a PermissionRequest from unknown input. */
+export function parsePermissionRequest(
+	data: unknown,
+): PermissionRequest | null {
+	const result = PermissionRequestSchema.safeParse(data);
+	if (!result.success) return null;
+	return result.data;
+}
+
+/** Read all of stdin as a string. */
+export async function readStdin(): Promise<string> {
+	const chunks: Uint8Array[] = [];
+	for await (const chunk of Bun.stdin.stream()) {
+		chunks.push(chunk);
+	}
+	return Buffer.concat(chunks).toString("utf-8");
+}

package/src/log.ts

@@ -0,0 +1,193 @@
+import { getDb } from "./db.ts";
+
+export interface LogEntry {
+	timestamp: number;
+	session_id: string;
+	cwd: string;
+	tool_name: string;
+	tool_input: string;
+	input: string;
+	decision: "allow" | "deny" | "abstain" | "error";
+	provider: string | null;
+	reason?: string | null;
+	duration_ms: number;
+	cached?: number;
+	mode?: "shadow" | "audit" | null;
+}
+
+export interface LlmLogEntry {
+	prompt: string;
+	model: string;
+}
+
+/** Extract a human-readable tool_input string from the raw PermissionRequest tool_input. */
+export function extractToolInput(
+	toolName: string,
+	toolInput: Record<string, unknown>,
+): string {
+	if (toolName === "Bash" && typeof toolInput.command === "string") {
+		return toolInput.command;
+	}
+	return JSON.stringify(toolInput);
+}
+
+export function appendLogEntry(entry: LogEntry, llm?: LlmLogEntry): void {
+	const db = getDb();
+	const result = db
+		.query(
+			`INSERT INTO logs (timestamp, session_id, cwd, tool_name, tool_input, input, decision, provider, reason, duration_ms, cached, mode)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		)
+		.run(
+			entry.timestamp,
+			entry.session_id,
+			entry.cwd,
+			entry.tool_name,
+			entry.tool_input,
+			entry.input,
+			entry.decision,
+			entry.provider,
+			entry.reason ?? null,
+			entry.duration_ms,
+			entry.cached ?? 0,
+			entry.mode ?? null,
+		);
+
+	if (llm) {
+		const logId = Number(result.lastInsertRowid);
+		db.query(
+			"INSERT INTO llm_logs (log_id, prompt, model) VALUES (?, ?, ?)",
+		).run(logId, llm.prompt, llm.model);
+	}
+}
+
+export interface LogRow {
+	id: number;
+	timestamp: number;
+	session_id: string;
+	cwd: string;
+	tool_name: string;
+	tool_input: string;
+	input: string;
+	decision: string;
+	provider: string | null;
+	reason: string | null;
+	duration_ms: number;
+	cached: number;
+	mode: string | null;
+}
+
+export interface LlmLogRow {
+	log_id: number;
+	prompt: string;
+	model: string;
+}
+
+/** Fetch LLM verbose logs for the given log entry IDs. */
+export function readLlmLogs(logIds: number[]): Map<number, LlmLogRow> {
+	if (logIds.length === 0) return new Map();
+	const db = getDb();
+	const placeholders = logIds.map(() => "?").join(",");
+	const rows = db
+		.query(
+			`SELECT log_id, prompt, model FROM llm_logs WHERE log_id IN (${placeholders})`,
+		)
+		.all(...logIds) as LlmLogRow[];
+	const map = new Map<number, LlmLogRow>();
+	for (const row of rows) {
+		map.set(row.log_id, row);
+	}
+	return map;
+}
+
+export interface ReadLogOptions {
+	last?: number;
+	since?: number;
+	until?: number;
+	decision?: string;
+	provider?: string;
+	cwd?: string;
+}
+
+/** Delete all log entries and associated LLM logs. Returns the number of rows deleted. */
+export function clearLogs(): number {
+	const db = getDb();
+	db.run("DELETE FROM llm_logs");
+	const result = db.query("DELETE FROM logs").run();
+	return result.changes;
+}
+
+/** Parse a retention duration string (e.g. "30d", "12h") into milliseconds.
+ *  Returns null for "0" (disabled) or invalid values. */
+export function parseRetention(value: string): number | null {
+	if (value === "0") return null;
+	const match = value.match(/^(\d+)([smhd])$/);
+	if (!match) return null;
+	const amount = Number(match[1]);
+	if (amount === 0) return null;
+	const unit = match[2];
+	const multipliers: Record<string, number> = {
+		s: 1000,
+		m: 60_000,
+		h: 3_600_000,
+		d: 86_400_000,
+	};
+	const ms = multipliers[unit as string];
+	if (ms === undefined) return null;
+	return amount * ms;
+}
+
+/** Delete log entries (and associated LLM logs) older than the given retention period.
+ *  Returns the number of log rows deleted. No-op if retention is "0" (disabled). */
+export function truncateOldLogs(retention: string): number {
+	const ms = parseRetention(retention);
+	if (ms === null) return 0;
+	const cutoff = Date.now() - ms;
+	const db = getDb();
+	db.run(
+		"DELETE FROM llm_logs WHERE log_id IN (SELECT id FROM logs WHERE timestamp < ?)",
+		[cutoff],
+	);
+	const result = db.query("DELETE FROM logs WHERE timestamp < ?").run(cutoff);
+	return result.changes;
+}
+
+export function readLogEntries(opts: ReadLogOptions = {}): LogRow[] {
+	const db = getDb();
+	const conditions: string[] = [];
+	const params: (string | number)[] = [];
+
+	if (opts.since !== undefined) {
+		conditions.push("timestamp >= ?");
+		params.push(opts.since);
+	}
+	if (opts.until !== undefined) {
+		conditions.push("timestamp <= ?");
+		params.push(opts.until);
+	}
+	if (opts.decision !== undefined) {
+		conditions.push("decision = ?");
+		params.push(opts.decision);
+	}
+	if (opts.provider !== undefined) {
+		conditions.push("provider = ?");
+		params.push(opts.provider);
+	}
+	if (opts.cwd !== undefined) {
+		const escapedCwd = opts.cwd.replace(/[%_]/g, "\\$&");
+		conditions.push("(cwd = ? OR cwd LIKE ? || '/%' ESCAPE '\\')");
+		params.push(opts.cwd, escapedCwd);
+	}
+
+	const where =
+		conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+	const limit =
+		opts.last !== undefined && opts.last > 0 ? `LIMIT ${opts.last}` : "";
+
+	// Use a subquery to get the last N rows (ordered by id DESC), then re-order ASC
+	const sql = limit
+		? `SELECT * FROM (SELECT * FROM logs ${where} ORDER BY id DESC ${limit}) ORDER BY id ASC`
+		: `SELECT * FROM logs ${where} ORDER BY id ASC`;
+
+	return db.query(sql).all(...params) as LogRow[];
+}

package/src/pipeline.ts

@@ -0,0 +1,32 @@
+import type { PermissionRequest, PermissionResult, Provider } from "./types.ts";
+
+/** Result from running the provider pipeline. */
+export interface PipelineResult {
+	decision: PermissionResult;
+	provider: string | null;
+	reason?: string;
+}
+
+/** Run providers in order until one returns a definitive result.
+ *  First `allow` or `deny` wins. If all abstain, returns `abstain`. */
+export async function runPipeline(
+	providers: Provider[],
+	req: PermissionRequest,
+): Promise<PipelineResult> {
+	for (const provider of providers) {
+		try {
+			const result = await provider.checkPermission(req);
+			if (result.decision === "allow" || result.decision === "deny") {
+				return {
+					decision: result.decision,
+					provider: provider.name,
+					reason: result.reason,
+				};
+			}
+		} catch {
+			// Provider errors are treated as abstain — fail-through
+		}
+	}
+
+	return { decision: "abstain", provider: null };
+}

package/src/prompts.ts

@@ -0,0 +1,83 @@
+import type { ClaudeAgent } from "./agents/claude.ts";
+import type { PermissionRequest } from "./types.ts";
+
+/** Expected shape of the LLM's JSON response. */
+export interface LlmDecision {
+	decision: "allow" | "deny";
+	reason: string;
+}
+
+/** Build the prompt that asks the LLM to evaluate a permission request. */
+export function buildPrompt(
+	req: PermissionRequest,
+	agent: ClaudeAgent,
+	canDeny: boolean,
+): string {
+	const info = agent.getDebugInfo();
+	const command =
+		typeof req.tool_input.command === "string" ? req.tool_input.command : "";
+
+	const rules = canDeny
+		? `- If the command is a variation of one of the ALLOWED patterns → allow.
+- If the command is a variation of one of the DENIED patterns → deny.
+- If the command is not clearly similar to either set of patterns → deny (fail-closed).
+- Only allow commands that are clearly within the spirit of an existing allowed pattern.`
+		: `- If the command is a variation of one of the ALLOWED patterns → allow.
+- If the command is NOT clearly similar to an allowed pattern → abstain.
+- Only allow commands that are clearly within the spirit of an existing allowed pattern.
+- You CANNOT deny commands. Your only options are allow or abstain.`;
+
+	const responseFormat = canDeny
+		? `{"decision": "allow", "reason": "brief explanation"}
+or
+{"decision": "deny", "reason": "brief explanation"}`
+		: `{"decision": "allow", "reason": "brief explanation"}
+or
+{"decision": "abstain", "reason": "brief explanation"}`;
+
+	return `You are a pattern-matching permission checker.
+
+A coding assistant is requesting permission to run a shell command. Your job is to decide whether this command is similar to an already-allowed pattern.
+
+## Context
+- Working directory: ${req.cwd}
+- Tool: ${req.tool_name}
+- Command: ${command}
+
+## Configured permission patterns
+- Allowed patterns: ${JSON.stringify(info.allow)}
+- Denied patterns: ${JSON.stringify(info.deny)}
+
+The command did not exactly match any pattern, so you must judge by similarity.
+
+## Rules
+${rules}
+
+Respond with ONLY a JSON object in this exact format, no other text:
+${responseFormat}`;
+}
+
+/** Parse the LLM's stdout into a decision. Returns null on invalid output. */
+export function parseLlmResponse(stdout: string): LlmDecision | null {
+	const trimmed = stdout.trim();
+	if (!trimmed) return null;
+
+	// The LLM might wrap JSON in markdown code fences
+	const jsonStr = trimmed
+		.replace(/^```(?:json)?\s*/i, "")
+		.replace(/\s*```$/i, "")
+		.trim();
+
+	try {
+		const parsed = JSON.parse(jsonStr) as Record<string, unknown>;
+		if (
+			(parsed.decision === "allow" || parsed.decision === "deny") &&
+			typeof parsed.reason === "string"
+		) {
+			return { decision: parsed.decision, reason: parsed.reason };
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}