@mcptoolshop/claude-sfx 0.1.0

package/dist/config.js

@@ -0,0 +1,104 @@
+/**
+ * Global configuration — persisted to ~/.claude-sfx/config.json.
+ * Controls profile, volume, quiet hours, mute state, per-verb toggles,
+ * and per-repo profile overrides.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+// --- Config directory ---
+const CONFIG_DIR = join(homedir(), ".claude-sfx");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+function ensureConfigDir() {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+}
+const DEFAULT_CONFIG = {
+    profile: "minimal",
+    volume: 80,
+    muted: false,
+    quietHours: null,
+    disabledVerbs: [],
+    repoProfiles: {},
+};
+// --- Read/Write ---
+export function loadConfig() {
+    if (!existsSync(CONFIG_FILE)) {
+        return { ...DEFAULT_CONFIG };
+    }
+    try {
+        const raw = readFileSync(CONFIG_FILE, "utf-8");
+        const parsed = JSON.parse(raw);
+        // Merge with defaults so new fields are always present
+        return { ...DEFAULT_CONFIG, ...parsed };
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+}
+export function saveConfig(config) {
+    ensureConfigDir();
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n");
+}
+// --- Convenience setters ---
+export function setMuted(muted) {
+    const cfg = loadConfig();
+    cfg.muted = muted;
+    saveConfig(cfg);
+    return cfg;
+}
+export function setVolume(volume) {
+    const cfg = loadConfig();
+    cfg.volume = Math.max(0, Math.min(100, Math.round(volume)));
+    saveConfig(cfg);
+    return cfg;
+}
+export function setProfile(profile) {
+    const cfg = loadConfig();
+    cfg.profile = profile;
+    saveConfig(cfg);
+    return cfg;
+}
+export function setQuietHours(start, end) {
+    const cfg = loadConfig();
+    cfg.quietHours = { start, end };
+    saveConfig(cfg);
+    return cfg;
+}
+export function clearQuietHours() {
+    const cfg = loadConfig();
+    cfg.quietHours = null;
+    saveConfig(cfg);
+    return cfg;
+}
+// --- Quiet hours check ---
+function parseTime(hhmm) {
+    const [h, m] = hhmm.split(":").map(Number);
+    return h * 60 + m;
+}
+export function isQuietTime(config) {
+    if (!config.quietHours)
+        return false;
+    const now = new Date();
+    const currentMinutes = now.getHours() * 60 + now.getMinutes();
+    const start = parseTime(config.quietHours.start);
+    const end = parseTime(config.quietHours.end);
+    // Handle overnight ranges (e.g., 22:00 → 07:00)
+    if (start > end) {
+        return currentMinutes >= start || currentMinutes < end;
+    }
+    return currentMinutes >= start && currentMinutes < end;
+}
+/** Resolve the effective profile name for the current working directory. */
+export function resolveProfileName(config, cwd) {
+    if (cwd && config.repoProfiles[cwd]) {
+        return config.repoProfiles[cwd];
+    }
+    return config.profile;
+}
+/** Convert volume (0–100) to gain (0.0–1.0). */
+export function volumeToGain(volume) {
+    return Math.max(0, Math.min(1, volume / 100));
+}
+export { CONFIG_DIR, CONFIG_FILE };

package/dist/guard.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Sound guard — debounce, rate limiting, mute, quiet hours.
+ * All "should this sound play?" logic lives here.
+ *
+ * State is tracked via a lightweight temp file (no daemon needed).
+ * Each play call reads/writes a small JSON ledger.
+ */
+import { type SfxConfig } from "./config.js";
+export interface GuardResult {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * Check whether a sound should play, and record it in the ledger if allowed.
+ * This is the single entry point for all anti-annoyance logic.
+ */
+export declare function guardPlay(verb: string, config: SfxConfig): GuardResult;
+/** Reset the ledger (for testing or after mute toggle). */
+export declare function resetLedger(): void;

package/dist/guard.js

@@ -0,0 +1,87 @@
+/**
+ * Sound guard — debounce, rate limiting, mute, quiet hours.
+ * All "should this sound play?" logic lives here.
+ *
+ * State is tracked via a lightweight temp file (no daemon needed).
+ * Each play call reads/writes a small JSON ledger.
+ */
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { isQuietTime } from "./config.js";
+// --- Constants ---
+/** Debounce window: same verb within this window → skip. */
+const DEBOUNCE_MS = 200;
+/** Rate limit: max sounds in the sliding window. */
+const RATE_LIMIT_MAX = 8;
+/** Rate limit sliding window duration. */
+const RATE_LIMIT_WINDOW_MS = 10_000;
+/** Ledger file — tiny JSON tracking recent plays. */
+const LEDGER_FILE = join(tmpdir(), "claude-sfx-ledger.json");
+function readLedger() {
+    if (!existsSync(LEDGER_FILE)) {
+        return { entries: [] };
+    }
+    try {
+        const raw = readFileSync(LEDGER_FILE, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { entries: [] };
+    }
+}
+function writeLedger(ledger) {
+    writeFileSync(LEDGER_FILE, JSON.stringify(ledger));
+}
+/** Prune entries older than the rate limit window. */
+function pruneEntries(entries, now) {
+    const cutoff = now - RATE_LIMIT_WINDOW_MS;
+    return entries.filter((e) => e.timestamp > cutoff);
+}
+/**
+ * Check whether a sound should play, and record it in the ledger if allowed.
+ * This is the single entry point for all anti-annoyance logic.
+ */
+export function guardPlay(verb, config) {
+    // 1. Muted?
+    if (config.muted) {
+        return { allowed: false, reason: "muted" };
+    }
+    // 2. Quiet hours?
+    if (isQuietTime(config)) {
+        return { allowed: false, reason: "quiet hours" };
+    }
+    // 3. Verb disabled?
+    if (config.disabledVerbs.includes(verb)) {
+        return { allowed: false, reason: `verb "${verb}" disabled` };
+    }
+    // 4. Volume zero?
+    if (config.volume <= 0) {
+        return { allowed: false, reason: "volume is 0" };
+    }
+    const now = Date.now();
+    const ledger = readLedger();
+    const entries = pruneEntries(ledger.entries, now);
+    // 5. Debounce — same verb within the window?
+    const lastSameVerb = entries.filter((e) => e.verb === verb);
+    if (lastSameVerb.length > 0) {
+        const mostRecent = lastSameVerb[lastSameVerb.length - 1];
+        if (now - mostRecent.timestamp < DEBOUNCE_MS) {
+            writeLedger({ entries }); // still prune stale entries
+            return { allowed: false, reason: "debounced" };
+        }
+    }
+    // 6. Rate limit — too many sounds in the window?
+    if (entries.length >= RATE_LIMIT_MAX) {
+        writeLedger({ entries });
+        return { allowed: false, reason: "rate limited" };
+    }
+    // All checks passed — record and allow
+    entries.push({ verb, timestamp: now });
+    writeLedger({ entries });
+    return { allowed: true };
+}
+/** Reset the ledger (for testing or after mute toggle). */
+export function resetLedger() {
+    writeLedger({ entries: [] });
+}

package/dist/hook-handler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Hook handler — the bridge between Claude Code hooks and claude-sfx.
+ *
+ * All hooks route here. Reads JSON from stdin, determines the verb + modifiers,
+ * and dispatches to `generateVerb → playSync`. Runs in-process (no child spawn)
+ * for minimal latency.
+ *
+ * Usage (called by Claude Code hooks, not directly by users):
+ *   echo '{"tool_name":"Read",...}' | claude-sfx hook-handler PostToolUse
+ *   echo '{"session_id":"..."}' | claude-sfx hook-handler SessionStart
+ */
+import { type Verb, type PlayOptions } from "./verbs.js";
+export interface VerbMapping {
+    verb: Verb;
+    options?: PlayOptions;
+}
+/** Map a PostToolUse tool_name to a verb + options. */
+export declare function mapToolToVerb(toolName: string, input: StdinPayload): VerbMapping | null;
+/** Map Bash tool usage to a verb, detecting git commands and exit codes. */
+export declare function mapBashVerb(input: StdinPayload): VerbMapping;
+export interface StdinPayload {
+    session_id?: string;
+    cwd?: string;
+    hook_event_name?: string;
+    tool_name?: string;
+    tool_input?: unknown;
+    tool_output?: unknown;
+    exit_code?: number;
+    error_message?: string;
+    source?: string;
+    reason?: string;
+    [key: string]: unknown;
+}
+export declare function handleHook(eventName: string): Promise<void>;

package/dist/hook-handler.js

@@ -0,0 +1,200 @@
+/**
+ * Hook handler — the bridge between Claude Code hooks and claude-sfx.
+ *
+ * All hooks route here. Reads JSON from stdin, determines the verb + modifiers,
+ * and dispatches to `generateVerb → playSync`. Runs in-process (no child spawn)
+ * for minimal latency.
+ *
+ * Usage (called by Claude Code hooks, not directly by users):
+ *   echo '{"tool_name":"Read",...}' | claude-sfx hook-handler PostToolUse
+ *   echo '{"session_id":"..."}' | claude-sfx hook-handler SessionStart
+ */
+import { generateVerb, generateSessionStart, generateSessionEnd, } from "./verbs.js";
+import { applyVolume } from "./synth.js";
+import { playSync } from "./player.js";
+import { resolveProfile } from "./profiles.js";
+import { loadConfig, resolveProfileName, volumeToGain } from "./config.js";
+import { guardPlay } from "./guard.js";
+import { resolveAmbient, isAmbientRunning } from "./ambient.js";
+/** Map a PostToolUse tool_name to a verb + options. */
+export function mapToolToVerb(toolName, input) {
+    // Exact matches first
+    switch (toolName) {
+        case "Read":
+            return { verb: "intake" };
+        case "Edit":
+            return { verb: "transform" };
+        case "Write":
+        case "NotebookEdit":
+            return { verb: "commit" };
+        case "Grep":
+        case "Glob":
+            return { verb: "navigate" };
+        case "WebFetch":
+        case "WebSearch":
+            return { verb: "intake", options: { scope: "remote" } };
+        case "TodoWrite":
+            return { verb: "commit" };
+    }
+    // Bash — detect git commands and exit code
+    if (toolName === "Bash") {
+        return mapBashVerb(input);
+    }
+    // Task (subagent return) — treat as remote commit
+    if (toolName === "Task") {
+        return { verb: "commit", options: { scope: "remote" } };
+    }
+    // MCP tools — treat as remote intake
+    if (toolName.startsWith("mcp__")) {
+        return { verb: "intake", options: { scope: "remote" } };
+    }
+    // Unknown tool — skip
+    return null;
+}
+/** Map Bash tool usage to a verb, detecting git commands and exit codes. */
+export function mapBashVerb(input) {
+    const toolInput = typeof input.tool_input === "object"
+        ? JSON.stringify(input.tool_input)
+        : String(input.tool_input ?? "");
+    const exitCode = input.exit_code ?? 0;
+    const status = exitCode === 0 ? "ok" : "err";
+    // Git push/pull → sync with direction
+    if (/git\s+push/i.test(toolInput)) {
+        return { verb: "sync", options: { direction: "up", status } };
+    }
+    if (/git\s+(pull|fetch)/i.test(toolInput)) {
+        return { verb: "sync", options: { direction: "down", status } };
+    }
+    // Git commit → commit verb
+    if (/git\s+commit/i.test(toolInput)) {
+        return { verb: "commit", options: { status } };
+    }
+    // npm/yarn/pnpm install → intake (bringing deps in)
+    if (/(?:npm|yarn|pnpm|bun)\s+install/i.test(toolInput)) {
+        return { verb: "intake", options: { scope: "remote", status } };
+    }
+    // Test commands → execute with status
+    if (/(?:npm\s+test|pytest|jest|vitest|cargo\s+test|dotnet\s+test)/i.test(toolInput)) {
+        return { verb: "execute", options: { status } };
+    }
+    // Build commands → execute with status
+    if (/(?:npm\s+run\s+build|tsc|cargo\s+build|dotnet\s+build|make\b)/i.test(toolInput)) {
+        return { verb: "execute", options: { status } };
+    }
+    // mv/cp/rename → move
+    if (/\b(?:mv|cp|rename|move)\b/i.test(toolInput)) {
+        return { verb: "move" };
+    }
+    // rm/del → move with err-ish tone (destructive)
+    if (/\b(?:rm|del|rmdir)\b/i.test(toolInput)) {
+        return { verb: "move", options: { status: "warn" } };
+    }
+    // Default bash → execute
+    return { verb: "execute", options: { status } };
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => { data += chunk; });
+        process.stdin.on("end", () => resolve(data));
+        // If stdin is a TTY (no pipe), resolve immediately with empty
+        if (process.stdin.isTTY) {
+            resolve("");
+        }
+    });
+}
+// --- Play helper ---
+function playVerb(verb, options = {}) {
+    const config = loadConfig();
+    // Guard check
+    const guard = guardPlay(verb, config);
+    if (!guard.allowed)
+        return;
+    const profileName = resolveProfileName(config);
+    const profile = resolveProfile(profileName);
+    let buffer = generateVerb(profile, verb, options);
+    const gain = volumeToGain(config.volume);
+    if (gain < 1) {
+        buffer = applyVolume(buffer, gain);
+    }
+    playSync(buffer);
+}
+function playSession(type) {
+    const config = loadConfig();
+    if (config.muted)
+        return;
+    const profileName = resolveProfileName(config);
+    const profile = resolveProfile(profileName);
+    const gen = type === "start" ? generateSessionStart : generateSessionEnd;
+    let buffer = gen(profile);
+    const gain = volumeToGain(config.volume);
+    if (gain < 1) {
+        buffer = applyVolume(buffer, gain);
+    }
+    playSync(buffer);
+}
+// --- Main handler ---
+export async function handleHook(eventName) {
+    const raw = await readStdin();
+    let payload = {};
+    try {
+        if (raw.trim()) {
+            payload = JSON.parse(raw);
+        }
+    }
+    catch {
+        // Malformed stdin — not an error, just skip
+        return;
+    }
+    switch (eventName) {
+        case "SessionStart":
+            playSession("start");
+            break;
+        case "Stop":
+            // Stop any ambient drone on session end
+            if (isAmbientRunning()) {
+                const config = loadConfig();
+                const profile = resolveProfile(resolveProfileName(config));
+                resolveAmbient(profile);
+            }
+            playSession("end");
+            break;
+        case "PostToolUse": {
+            const toolName = payload.tool_name;
+            if (!toolName)
+                return;
+            const mapping = mapToolToVerb(toolName, payload);
+            if (!mapping)
+                return;
+            playVerb(mapping.verb, mapping.options ?? {});
+            break;
+        }
+        case "PostToolUseFailure": {
+            // Tool failed — play the verb with error status
+            const toolName = payload.tool_name;
+            if (!toolName)
+                return;
+            const mapping = mapToolToVerb(toolName, payload);
+            if (!mapping)
+                return;
+            const opts = { ...mapping.options, status: "err" };
+            playVerb(mapping.verb, opts);
+            break;
+        }
+        case "SubagentStart":
+            playVerb("move", { scope: "remote" });
+            break;
+        case "SubagentStop": {
+            const exitCode = payload.exit_code ?? 0;
+            playVerb("commit", {
+                scope: "remote",
+                status: exitCode === 0 ? "ok" : "err",
+            });
+            break;
+        }
+        default:
+            // Unknown event — ignore
+            break;
+    }
+}

package/dist/hooks.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Hook config generator — creates Claude Code hooks entries for .claude/settings.json.
+ * Handles merging with existing settings non-destructively.
+ */
+interface HookEntry {
+    type: "command";
+    command: string;
+    timeout: number;
+}
+interface HookMatcher {
+    matcher?: string;
+    hooks: HookEntry[];
+}
+interface HooksConfig {
+    [eventName: string]: HookMatcher[];
+}
+/** Generate the full hooks config for claude-sfx. */
+export declare function generateHooksConfig(): HooksConfig;
+/**
+ * Install claude-sfx hooks into .claude/settings.json.
+ * Merges non-destructively — preserves existing hooks from other tools.
+ */
+export declare function installHooks(cwd: string): {
+    settingsPath: string;
+    eventsAdded: string[];
+};
+/**
+ * Remove all claude-sfx hooks from .claude/settings.json.
+ * Preserves hooks from other tools.
+ */
+export declare function uninstallHooks(cwd: string): {
+    settingsPath: string;
+    removed: boolean;
+};
+export {};

package/dist/hooks.js

@@ -0,0 +1,192 @@
+/**
+ * Hook config generator — creates Claude Code hooks entries for .claude/settings.json.
+ * Handles merging with existing settings non-destructively.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+// --- Marker to identify our hooks ---
+const SFX_MARKER = "claude-sfx";
+/** Resolve the path to the claude-sfx CLI (the installed binary or dist/cli.js). */
+function resolveSfxBin() {
+    // Try to find the globally/locally installed binary
+    try {
+        const which = process.platform === "win32"
+            ? execSync("where claude-sfx", { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }).trim().split("\n")[0]
+            : execSync("which claude-sfx", { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }).trim();
+        if (which)
+            return which;
+    }
+    catch {
+        // Not installed globally — use node + dist path
+    }
+    // Fallback: use node with the dist path relative to this package
+    const __filename = fileURLToPath(import.meta.url);
+    const cliPath = join(dirname(__filename), "cli.js");
+    return `node "${cliPath}"`;
+}
+function makeHookCommand(sfxBin, eventName) {
+    return `${sfxBin} hook-handler ${eventName}`;
+}
+/** Generate the full hooks config for claude-sfx. */
+export function generateHooksConfig() {
+    const sfxBin = resolveSfxBin();
+    return {
+        SessionStart: [
+            {
+                hooks: [
+                    {
+                        type: "command",
+                        command: makeHookCommand(sfxBin, "SessionStart"),
+                        timeout: 5,
+                    },
+                ],
+            },
+        ],
+        PostToolUse: [
+            {
+                // Match all tools — the handler does the mapping internally
+                matcher: ".*",
+                hooks: [
+                    {
+                        type: "command",
+                        command: makeHookCommand(sfxBin, "PostToolUse"),
+                        timeout: 5,
+                    },
+                ],
+            },
+        ],
+        PostToolUseFailure: [
+            {
+                matcher: ".*",
+                hooks: [
+                    {
+                        type: "command",
+                        command: makeHookCommand(sfxBin, "PostToolUseFailure"),
+                        timeout: 5,
+                    },
+                ],
+            },
+        ],
+        SubagentStart: [
+            {
+                hooks: [
+                    {
+                        type: "command",
+                        command: makeHookCommand(sfxBin, "SubagentStart"),
+                        timeout: 5,
+                    },
+                ],
+            },
+        ],
+        SubagentStop: [
+            {
+                hooks: [
+                    {
+                        type: "command",
+                        command: makeHookCommand(sfxBin, "SubagentStop"),
+                        timeout: 5,
+                    },
+                ],
+            },
+        ],
+        Stop: [
+            {
+                hooks: [
+                    {
+                        type: "command",
+                        command: makeHookCommand(sfxBin, "Stop"),
+                        timeout: 5,
+                    },
+                ],
+            },
+        ],
+    };
+}
+/** Check if a hook entry is one of ours. */
+function isSfxHook(entry) {
+    return entry.command.includes(SFX_MARKER);
+}
+/** Check if a matcher block contains any of our hooks. */
+function containsSfxHook(matcherBlock) {
+    return matcherBlock.hooks.some(isSfxHook);
+}
+// --- Init / Uninstall ---
+function getSettingsPath(cwd) {
+    return join(cwd, ".claude", "settings.json");
+}
+function readSettings(settingsPath) {
+    if (!existsSync(settingsPath))
+        return {};
+    try {
+        return JSON.parse(readFileSync(settingsPath, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeSettings(settingsPath, settings) {
+    const dir = dirname(settingsPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+}
+/**
+ * Install claude-sfx hooks into .claude/settings.json.
+ * Merges non-destructively — preserves existing hooks from other tools.
+ */
+export function installHooks(cwd) {
+    const settingsPath = getSettingsPath(cwd);
+    const settings = readSettings(settingsPath);
+    const sfxHooks = generateHooksConfig();
+    if (!settings.hooks) {
+        settings.hooks = {};
+    }
+    const eventsAdded = [];
+    for (const [eventName, sfxMatchers] of Object.entries(sfxHooks)) {
+        if (!settings.hooks[eventName]) {
+            settings.hooks[eventName] = [];
+        }
+        // Remove any existing SFX hooks (in case of re-init)
+        settings.hooks[eventName] = settings.hooks[eventName].filter((m) => !containsSfxHook(m));
+        // Add our hooks
+        settings.hooks[eventName].push(...sfxMatchers);
+        eventsAdded.push(eventName);
+    }
+    writeSettings(settingsPath, settings);
+    return { settingsPath, eventsAdded };
+}
+/**
+ * Remove all claude-sfx hooks from .claude/settings.json.
+ * Preserves hooks from other tools.
+ */
+export function uninstallHooks(cwd) {
+    const settingsPath = getSettingsPath(cwd);
+    if (!existsSync(settingsPath)) {
+        return { settingsPath, removed: false };
+    }
+    const settings = readSettings(settingsPath);
+    if (!settings.hooks) {
+        return { settingsPath, removed: false };
+    }
+    let removedAny = false;
+    for (const eventName of Object.keys(settings.hooks)) {
+        const before = settings.hooks[eventName].length;
+        settings.hooks[eventName] = settings.hooks[eventName].filter((m) => !containsSfxHook(m));
+        if (settings.hooks[eventName].length < before) {
+            removedAny = true;
+        }
+        // Clean up empty event arrays
+        if (settings.hooks[eventName].length === 0) {
+            delete settings.hooks[eventName];
+        }
+    }
+    // Clean up empty hooks object
+    if (Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+    }
+    writeSettings(settingsPath, settings);
+    return { settingsPath, removed: removedAny };
+}

package/dist/player.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Cross-platform audio playback.
+ * Writes a temp .wav file, plays it with the OS native player, cleans up.
+ * Zero dependencies.
+ */
+export interface PlayResult {
+    played: boolean;
+    method: string;
+    durationMs: number;
+}
+/** Play a PCM audio buffer through the system speakers. Blocks until done. */
+export declare function playSync(buffer: Float64Array): PlayResult;
+/** Play a PCM audio buffer asynchronously (fire and forget). */
+export declare function playAsync(buffer: Float64Array): void;
+/** Write a WAV file to disk (for export / debugging). */
+export declare function saveWav(buffer: Float64Array, outputPath: string): void;