@stella-studio/ck 1.0.0

package/.claude/hooks/notifications/lib/env-loader.cjs

@@ -0,0 +1,105 @@
+/**
+ * Environment loader with cascade: process.env > ~/.claude/.env > .claude/.env
+ * Zero dependencies - manual .env parsing
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Parse a .env file content into key-value pairs
+ * Supports: comments (#), quoted values, empty lines
+ * @param {string} content - File content
+ * @returns {Object} Parsed environment variables
+ */
+function parseEnvContent(content) {
+  const result = {};
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip empty lines and comments
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Find first = sign
+    const eqIndex = trimmed.indexOf('=');
+    if (eqIndex === -1) continue;
+
+    const key = trimmed.slice(0, eqIndex).trim();
+    let value = trimmed.slice(eqIndex + 1).trim();
+
+    // Handle quoted values (single or double quotes)
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    // Handle inline comments (only if not quoted)
+    if (!trimmed.slice(eqIndex + 1).trim().startsWith('"') &&
+        !trimmed.slice(eqIndex + 1).trim().startsWith("'")) {
+      const commentIndex = value.indexOf('#');
+      if (commentIndex !== -1) {
+        value = value.slice(0, commentIndex).trim();
+      }
+    }
+
+    if (key) {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Load .env file if it exists
+ * @param {string} filePath - Path to .env file
+ * @returns {Object} Parsed env or empty object
+ */
+function loadEnvFile(filePath) {
+  try {
+    if (fs.existsSync(filePath)) {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const parsed = parseEnvContent(content);
+      if (Object.keys(parsed).length > 0) {
+        console.error(`[env-loader] Loaded: ${filePath}`);
+      }
+      return parsed;
+    }
+  } catch (err) {
+    console.error(`[env-loader] Failed to read ${filePath}: ${err.message}`);
+  }
+  return {};
+}
+
+/**
+ * Load environment with cascade priority
+ * Priority: process.env > ~/.claude/.env > .claude/.env
+ * @param {string} [cwd] - Current working directory (defaults to process.cwd())
+ * @returns {Object} Merged environment variables
+ */
+function loadEnv(cwd = process.cwd()) {
+  const envFiles = [
+    // Lowest priority first (will be overwritten)
+    path.join(cwd, '.claude', '.env'),
+    path.join(os.homedir(), '.claude', '.env'),
+  ];
+
+  // Start with empty object, layer on each source
+  let merged = {};
+
+  for (const filePath of envFiles) {
+    const fileEnv = loadEnvFile(filePath);
+    merged = { ...merged, ...fileEnv };
+  }
+
+  // process.env has highest priority
+  merged = { ...merged, ...process.env };
+
+  return merged;
+}
+
+module.exports = { loadEnv, parseEnvContent };

package/.claude/hooks/notifications/lib/sender.cjs

@@ -0,0 +1,128 @@
+/**
+ * HTTP sender with smart throttling
+ * Uses native fetch (Node 18+) - zero dependencies
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const THROTTLE_FILE = path.join(os.tmpdir(), 'ck-noti-throttle.json');
+const THROTTLE_DURATION_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Load throttle state from temp file
+ * @returns {Object} Provider -> last error timestamp map
+ */
+function loadThrottleState() {
+  try {
+    if (fs.existsSync(THROTTLE_FILE)) {
+      const content = fs.readFileSync(THROTTLE_FILE, 'utf8');
+      return JSON.parse(content);
+    }
+  } catch (err) {
+    // Corrupted file - start fresh
+    console.error(`[sender] Throttle file corrupted, resetting: ${err.message}`);
+  }
+  return {};
+}
+
+/**
+ * Save throttle state to temp file
+ * @param {Object} state - Provider -> timestamp map
+ */
+function saveThrottleState(state) {
+  try {
+    fs.writeFileSync(THROTTLE_FILE, JSON.stringify(state, null, 2), 'utf8');
+  } catch (err) {
+    console.error(`[sender] Failed to save throttle state: ${err.message}`);
+  }
+}
+
+/**
+ * Check if provider is currently throttled
+ * @param {string} provider - Provider name
+ * @returns {boolean} True if throttled
+ */
+function isThrottled(provider) {
+  const state = loadThrottleState();
+  const lastError = state[provider];
+
+  if (!lastError) return false;
+
+  const elapsed = Date.now() - lastError;
+  return elapsed < THROTTLE_DURATION_MS;
+}
+
+/**
+ * Record an error for throttling
+ * @param {string} provider - Provider name
+ */
+function recordError(provider) {
+  const state = loadThrottleState();
+  state[provider] = Date.now();
+  saveThrottleState(state);
+}
+
+/**
+ * Clear throttle for a provider (on success)
+ * @param {string} provider - Provider name
+ */
+function clearThrottle(provider) {
+  const state = loadThrottleState();
+  if (state[provider]) {
+    delete state[provider];
+    saveThrottleState(state);
+  }
+}
+
+/**
+ * Send HTTP POST request with throttling
+ * @param {string} provider - Provider name for throttling
+ * @param {string} url - Target URL
+ * @param {Object} body - JSON body to send
+ * @param {Object} [headers] - Additional headers
+ * @returns {Promise<{success: boolean, error?: string, throttled?: boolean}>}
+ */
+async function send(provider, url, body, headers = {}) {
+  // Check throttle first
+  if (isThrottled(provider)) {
+    return { success: false, throttled: true };
+  }
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...headers,
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => 'Unknown error');
+      const errorMsg = `HTTP ${response.status}: ${errorText.slice(0, 100)}`;
+
+      // Record error for throttling
+      recordError(provider);
+      console.error(`[sender] ${provider} failed: ${errorMsg}`);
+
+      return { success: false, error: errorMsg };
+    }
+
+    // Success - clear any previous throttle
+    clearThrottle(provider);
+    return { success: true };
+
+  } catch (err) {
+    // Network error - record for throttling
+    recordError(provider);
+    console.error(`[sender] ${provider} network error: ${err.message}`);
+
+    return { success: false, error: err.message };
+  }
+}
+
+module.exports = { send, isThrottled };

package/.claude/hooks/notifications/notify.cjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * Notification Router - Main entry point for hook notifications
+ * Reads stdin JSON, routes to enabled providers
+ *
+ * Usage: echo '{"hook_event_name":"Stop"}' | node notify.cjs
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { loadEnv } = require('./lib/env-loader.cjs');
+
+// Provider prefixes to check for enablement
+const PROVIDER_PREFIXES = ['TELEGRAM', 'DISCORD', 'SLACK'];
+
+/**
+ * Read JSON from stdin
+ * @returns {Promise<Object>} Parsed JSON input
+ */
+async function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+
+    // Handle no stdin (empty pipe)
+    if (process.stdin.isTTY) {
+      resolve({});
+      return;
+    }
+
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { data += chunk; });
+    process.stdin.on('end', () => {
+      if (!data.trim()) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(data));
+      } catch (err) {
+        console.error(`[notify] Invalid JSON input: ${err.message}`);
+        resolve({});
+      }
+    });
+    process.stdin.on('error', err => {
+      console.error(`[notify] Stdin error: ${err.message}`);
+      resolve({});
+    });
+
+    // Timeout after 5 seconds (safety)
+    setTimeout(() => {
+      console.error('[notify] Stdin timeout');
+      resolve({});
+    }, 5000);
+  });
+}
+
+/**
+ * Check if a provider has any env vars set
+ * @param {string} prefix - Provider prefix (e.g., 'TELEGRAM')
+ * @param {Object} env - Environment variables
+ * @returns {boolean}
+ */
+function hasProviderEnv(prefix, env) {
+  return Object.keys(env).some(key => key.startsWith(prefix + '_'));
+}
+
+/**
+ * Load provider module if it exists
+ * @param {string} providerName - Provider name (lowercase)
+ * @returns {Object|null} Provider module or null
+ */
+function loadProvider(providerName) {
+  const providerPath = path.join(__dirname, 'providers', `${providerName}.cjs`);
+
+  try {
+    if (fs.existsSync(providerPath)) {
+      return require(providerPath);
+    }
+  } catch (err) {
+    console.error(`[notify] Failed to load provider ${providerName}: ${err.message}`);
+  }
+  return null;
+}
+
+/**
+ * Main notification router
+ */
+async function main() {
+  try {
+    // Read input from stdin
+    const input = await readStdin();
+
+    // Load environment with cascade
+    const cwd = input.cwd || process.cwd();
+    const env = loadEnv(cwd);
+
+    // Find and call enabled providers
+    const results = [];
+
+    for (const prefix of PROVIDER_PREFIXES) {
+      if (!hasProviderEnv(prefix, env)) continue;
+
+      const providerName = prefix.toLowerCase();
+      const provider = loadProvider(providerName);
+
+      if (!provider) {
+        console.error(`[notify] Provider ${providerName} not found`);
+        continue;
+      }
+
+      // Check if provider considers itself enabled
+      if (typeof provider.isEnabled === 'function' && !provider.isEnabled(env)) {
+        continue;
+      }
+
+      // Call provider
+      try {
+        const result = await provider.send(input, env);
+        results.push({
+          provider: provider.name || providerName,
+          ...result,
+        });
+
+        if (result.success) {
+          console.error(`[notify] ${providerName}: sent`);
+        } else if (result.throttled) {
+          console.error(`[notify] ${providerName}: throttled`);
+        } else {
+          console.error(`[notify] ${providerName}: failed - ${result.error}`);
+        }
+      } catch (err) {
+        console.error(`[notify] ${providerName} error: ${err.message}`);
+        results.push({
+          provider: provider.name || providerName,
+          success: false,
+          error: err.message,
+        });
+      }
+    }
+
+    // Log summary if any providers ran
+    if (results.length > 0) {
+      const successful = results.filter(r => r.success).length;
+      console.error(`[notify] Summary: ${successful}/${results.length} succeeded`);
+    }
+
+  } catch (err) {
+    console.error(`[notify] Fatal error: ${err.message}`);
+  }
+
+  // Always exit 0 - never block Claude
+  process.exit(0);
+}
+
+main();

package/.claude/hooks/notifications/providers/discord.cjs

@@ -0,0 +1,197 @@
+/**
+ * Discord notification provider
+ * Sends rich embed messages to Discord webhooks
+ */
+'use strict';
+
+const path = require('path');
+const { send } = require('../lib/sender.cjs');
+
+// Discord embed colors
+const COLORS = {
+  Stop: 5763719,         // Green
+  SubagentStop: 3447003, // Blue
+  AskUserPrompt: 15844367, // Yellow
+  default: 10070709,     // Gray
+};
+
+/**
+ * Get project name from cwd path
+ * @param {string} cwd - Working directory path
+ * @returns {string} Project name
+ */
+function getProjectName(cwd) {
+  if (!cwd) return 'Unknown';
+  return path.basename(cwd) || 'Unknown';
+}
+
+/**
+ * Format timestamp for display
+ * @returns {string} Formatted timestamp
+ */
+function formatTimestamp() {
+  const now = new Date();
+  return now.toLocaleTimeString('en-US', {
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+  });
+}
+
+/**
+ * Truncate session ID for display
+ * @param {string} sessionId - Full session ID
+ * @returns {string} Truncated session ID
+ */
+function truncateSessionId(sessionId) {
+  if (!sessionId) return 'N/A';
+  return sessionId.length > 8 ? `${sessionId.slice(0, 8)}...` : sessionId;
+}
+
+/**
+ * Build embed for Stop event
+ * @param {Object} input - Hook input
+ * @returns {Object} Discord embed
+ */
+function buildStopEmbed(input) {
+  const cwd = input.cwd || '';
+  const sessionId = input.session_id || '';
+  const projectName = getProjectName(cwd);
+
+  return {
+    title: 'Claude Code Session Complete',
+    description: 'Session completed successfully',
+    color: COLORS.Stop,
+    timestamp: new Date().toISOString(),
+    footer: { text: `Project • ${projectName}` },
+    fields: [
+      { name: '⏰ Time', value: formatTimestamp(), inline: true },
+      { name: '🆔 Session', value: `\`${truncateSessionId(sessionId)}\``, inline: true },
+      { name: '📍 Location', value: `\`${cwd || 'Unknown'}\``, inline: false },
+    ],
+  };
+}
+
+/**
+ * Build embed for SubagentStop event
+ * @param {Object} input - Hook input
+ * @returns {Object} Discord embed
+ */
+function buildSubagentStopEmbed(input) {
+  const cwd = input.cwd || '';
+  const sessionId = input.session_id || '';
+  const agentType = input.agent_type || 'unknown';
+  const projectName = getProjectName(cwd);
+
+  return {
+    title: 'Claude Code Subagent Complete',
+    description: 'Specialized agent completed its task',
+    color: COLORS.SubagentStop,
+    timestamp: new Date().toISOString(),
+    footer: { text: `Project • ${projectName}` },
+    fields: [
+      { name: '⏰ Time', value: formatTimestamp(), inline: true },
+      { name: '🔧 Agent Type', value: agentType, inline: true },
+      { name: '🆔 Session', value: `\`${truncateSessionId(sessionId)}\``, inline: true },
+      { name: '📍 Location', value: `\`${cwd || 'Unknown'}\``, inline: false },
+    ],
+  };
+}
+
+/**
+ * Build embed for AskUserPrompt event
+ * @param {Object} input - Hook input
+ * @returns {Object} Discord embed
+ */
+function buildAskUserPromptEmbed(input) {
+  const cwd = input.cwd || '';
+  const sessionId = input.session_id || '';
+  const projectName = getProjectName(cwd);
+
+  return {
+    title: 'Claude Code Needs Input',
+    description: 'Claude is waiting for user input',
+    color: COLORS.AskUserPrompt,
+    timestamp: new Date().toISOString(),
+    footer: { text: `Project • ${projectName}` },
+    fields: [
+      { name: '⏰ Time', value: formatTimestamp(), inline: true },
+      { name: '🆔 Session', value: `\`${truncateSessionId(sessionId)}\``, inline: true },
+      { name: '📍 Location', value: `\`${cwd || 'Unknown'}\``, inline: false },
+    ],
+  };
+}
+
+/**
+ * Build embed for generic/unknown events
+ * @param {Object} input - Hook input
+ * @returns {Object} Discord embed
+ */
+function buildDefaultEmbed(input) {
+  const hookType = input.hook_event_name || 'unknown';
+  const cwd = input.cwd || '';
+  const sessionId = input.session_id || '';
+  const projectName = getProjectName(cwd);
+
+  return {
+    title: 'Claude Code Event',
+    description: 'Claude Code event triggered',
+    color: COLORS.default,
+    timestamp: new Date().toISOString(),
+    footer: { text: `Project • ${projectName}` },
+    fields: [
+      { name: '⏰ Time', value: formatTimestamp(), inline: true },
+      { name: '📋 Event', value: hookType, inline: true },
+      { name: '🆔 Session', value: `\`${truncateSessionId(sessionId)}\``, inline: true },
+      { name: '📍 Location', value: `\`${cwd || 'Unknown'}\``, inline: false },
+    ],
+  };
+}
+
+/**
+ * Format embed based on hook event type
+ * @param {Object} input - Hook input with snake_case fields
+ * @returns {Object} Discord embed object
+ */
+function formatEmbed(input) {
+  // Use CORRECT snake_case field names (fixed from bash script's camelCase bug)
+  const hookType = input.hook_event_name || 'unknown';
+
+  switch (hookType) {
+    case 'Stop':
+      return buildStopEmbed(input);
+    case 'SubagentStop':
+      return buildSubagentStopEmbed(input);
+    case 'AskUserPrompt':
+      return buildAskUserPromptEmbed(input);
+    default:
+      return buildDefaultEmbed(input);
+  }
+}
+
+module.exports = {
+  name: 'discord',
+
+  /**
+   * Check if Discord provider is enabled
+   * @param {Object} env - Environment variables
+   * @returns {boolean} True if DISCORD_WEBHOOK_URL is set
+   */
+  isEnabled: (env) => !!env.DISCORD_WEBHOOK_URL,
+
+  /**
+   * Send notification to Discord
+   * @param {Object} input - Hook input (snake_case fields)
+   * @param {Object} env - Environment variables
+   * @returns {Promise<{success: boolean, error?: string}>}
+   */
+  send: async (input, env) => {
+    if (!env.DISCORD_WEBHOOK_URL) {
+      return { success: false, error: 'DISCORD_WEBHOOK_URL not configured' };
+    }
+
+    const embed = formatEmbed(input);
+    return send('discord', env.DISCORD_WEBHOOK_URL, { embeds: [embed] });
+  },
+};

package/.claude/hooks/notifications/providers/slack.cjs

@@ -0,0 +1,111 @@
+/**
+ * Slack notification provider using Block Kit format
+ * Uses incoming webhooks - zero dependencies
+ */
+'use strict';
+
+const path = require('path');
+const { send } = require('../lib/sender.cjs');
+
+/**
+ * Get title based on hook event type
+ * @param {string} hookType - Hook event name
+ * @returns {string} Human-readable title
+ */
+function getTitle(hookType) {
+  switch (hookType) {
+    case 'Stop':
+      return 'Claude Code Session Complete';
+    case 'SubagentStop':
+      return 'Claude Code Subagent Complete';
+    case 'AskUserPrompt':
+      return 'Claude Code Needs Input';
+    default:
+      return 'Claude Code Event';
+  }
+}
+
+/**
+ * Build Slack Block Kit blocks array
+ * @param {Object} input - Hook input with snake_case fields
+ * @param {string} hookType - Hook event name
+ * @param {string} projectName - Extracted project name
+ * @param {string} sessionId - Truncated session ID
+ * @returns {Array} Block Kit blocks
+ */
+function buildBlocks(input, hookType, projectName, sessionId) {
+  const timestamp = new Date().toLocaleString();
+  const cwd = input.cwd || 'Unknown';
+
+  const blocks = [
+    {
+      type: 'header',
+      text: { type: 'plain_text', text: getTitle(hookType) }
+    },
+    {
+      type: 'section',
+      fields: [
+        { type: 'mrkdwn', text: `*Project:*\n${projectName}` },
+        { type: 'mrkdwn', text: `*Time:*\n${timestamp}` },
+        { type: 'mrkdwn', text: `*Session:*\n\`${sessionId}...\`` },
+        { type: 'mrkdwn', text: `*Event:*\n${hookType}` }
+      ]
+    },
+    { type: 'divider' },
+    {
+      type: 'context',
+      elements: [
+        { type: 'mrkdwn', text: `📍 \`${cwd}\`` }
+      ]
+    }
+  ];
+
+  // Add agent_type for SubagentStop
+  if (hookType === 'SubagentStop' && input.agent_type) {
+    blocks.splice(2, 0, {
+      type: 'section',
+      text: { type: 'mrkdwn', text: `*Agent Type:* ${input.agent_type}` }
+    });
+  }
+
+  return blocks;
+}
+
+/**
+ * Format message for Slack webhook
+ * @param {Object} input - Hook input with snake_case fields
+ * @returns {Object} Slack payload with text fallback and blocks
+ */
+function formatMessage(input) {
+  const hookType = input.hook_event_name || 'unknown';
+  const projectDir = input.cwd || '';
+  const projectName = path.basename(projectDir) || 'Unknown';
+  const sessionId = (input.session_id || '').slice(0, 8);
+
+  return {
+    text: `Claude Code: ${hookType} in ${projectName}`, // Fallback required
+    blocks: buildBlocks(input, hookType, projectName, sessionId)
+  };
+}
+
+module.exports = {
+  name: 'slack',
+
+  /**
+   * Check if Slack provider is enabled
+   * @param {Object} env - Environment variables
+   * @returns {boolean} True if SLACK_WEBHOOK_URL is set
+   */
+  isEnabled: (env) => !!env.SLACK_WEBHOOK_URL,
+
+  /**
+   * Send notification to Slack
+   * @param {Object} input - Hook input with snake_case fields
+   * @param {Object} env - Environment variables
+   * @returns {Promise<{success: boolean, error?: string, throttled?: boolean}>}
+   */
+  send: async (input, env) => {
+    const payload = formatMessage(input);
+    return send('slack', env.SLACK_WEBHOOK_URL, payload);
+  }
+};