@claudemini/shit-cli 1.7.0 → 1.8.0

package/README.md

@@ -124,6 +124,7 @@ shit summarize <session-id>    # Generate AI summary (requires API key)
 | `doctor` | Diagnose and fix issues |
 | `shadow` | List/inspect shadow branches |
 | `clean` | Clean old sessions |
+| `webhook` | Show/test webhook configuration |
 
 ## How It Works
 
@@ -248,6 +249,66 @@ if (history && history.length > 3) {
 }
 ```
 
+## Webhook
+
+shit-cli can send webhook notifications to external systems (Slack, Lark, CI, custom platforms) when key events occur.
+
+### Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `session.ended` | Session ends (hook `session-end` / `stop`) | `summary.json` content |
+| `review.completed` | `shit review` finishes | Review report |
+
+### Configuration
+
+Add a `webhooks` field to `.shit-logs/config.json`:
+
+```json
+{
+  "webhooks": {
+    "url": "https://example.com/hook",
+    "events": ["session.ended", "review.completed"],
+    "secret": "hmac-secret-key",
+    "headers": { "X-Custom": "value" },
+    "timeout_ms": 5000,
+    "retry": 1
+  }
+}
+```
+
+Or use environment variables (higher priority than config.json):
+
+```bash
+export SHIT_WEBHOOK_URL=https://example.com/hook
+export SHIT_WEBHOOK_SECRET=my-secret        # HMAC-SHA256 signing
+export SHIT_WEBHOOK_AUTH_TOKEN=bearer-token  # Bearer auth (alternative to secret)
+export SHIT_WEBHOOK_EVENTS=session.ended,review.completed
+```
+
+### Authentication
+
+- **HMAC-SHA256** — Set `secret` or `SHIT_WEBHOOK_SECRET`. Adds `X-Signature-256: sha256=<hex>` header (GitHub-compatible format).
+- **Bearer token** — Set `auth_token` or `SHIT_WEBHOOK_AUTH_TOKEN`. Adds `Authorization: Bearer <token>` header.
+- If neither is set, requests are sent without authentication.
+
+### Payload Format
+
+```json
+{
+  "event": "session.ended",
+  "timestamp": "2026-03-03T12:00:00.000Z",
+  "payload": { ... }
+}
+```
+
+### Commands
+
+```bash
+shit webhook              # Show current webhook configuration
+shit webhook --test       # Send a test ping to the configured URL
+```
+
 ## AI Summary
 
 Set one of these environment variables to enable AI-powered session summaries:
@@ -272,6 +333,10 @@ shit summarize <session-id>
 | `OPENAI_BASE_URL` | OpenAI-compatible base URL for summaries (default: `https://api.openai.com/v1`) |
 | `OPENAI_ENDPOINT` | Full OpenAI-compatible endpoint (overrides `OPENAI_BASE_URL`) |
 | `ANTHROPIC_API_KEY` | Enable AI summaries via Anthropic |
+| `SHIT_WEBHOOK_URL` | Webhook endpoint URL |
+| `SHIT_WEBHOOK_SECRET` | HMAC-SHA256 signing secret for webhooks |
+| `SHIT_WEBHOOK_AUTH_TOKEN` | Bearer token for webhook authentication |
+| `SHIT_WEBHOOK_EVENTS` | Comma-separated list of webhook events to subscribe to |
 
 ## Security
 

package/bin/shit.js

@@ -23,6 +23,7 @@ const commands = {
   doctor:      'Fix or clean stuck sessions',
   shadow:      'List shadow branches',
   clean:       'Clean old sessions',
+  webhook:     'Manage webhook configuration',
   help:        'Show help',
 };
 

package/lib/log.js

@@ -5,12 +5,13 @@
  * Reads stdin, parses event, delegates to session/extract/report modules.
  */
 
-import { appendFileSync, mkdirSync } from 'fs';
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { getProjectRoot, getLogDir } from './config.js';
 import { loadState, saveState, processEvent, updateIndex } from './session.js';
 import { extractIntent, extractChanges, classifySession } from './extract.js';
 import { generateReports } from './report.js';
+import { dispatchWebhook } from './webhook.js';
 
 export default async function log(args) {
   const hookType = args[0] || 'unknown';
@@ -50,8 +51,11 @@ export default async function log(args) {
   const classification = classifySession(intent, changes);
   generateReports(sessionDir, sessionId, state, intent, changes, classification);
 
-  // 4. On session end: checkpoint + update index
-  if (hookType === 'session-end' || hookType === 'stop') {
+  // 4. On session end: checkpoint + update index + webhook (idempotent — run once per session)
+  const isSessionEnd = ['session-end', 'SessionEnd', 'stop', 'session_end', 'end', 'onSessionEnd'].includes(hookType);
+  const endedSentinel = join(sessionDir, '.ended');
+  if (isSessionEnd && !existsSync(endedSentinel)) {
+    writeFileSync(endedSentinel, new Date().toISOString());
     try {
       const { commitCheckpoint } = await import('./checkpoint.js');
       await commitCheckpoint(projectRoot, sessionDir, sessionId);
@@ -60,6 +64,14 @@ export default async function log(args) {
     try {
       updateIndex(logDir, sessionId, intent, classification, changes, state);
     } catch { /* index is best-effort */ }
+
+    // Dispatch webhook for session end — must await before exit
+    try {
+      const { readFileSync } = await import('fs');
+      const summaryPath = join(sessionDir, 'summary.json');
+      const summary = JSON.parse(readFileSync(summaryPath, 'utf-8'));
+      await dispatchWebhook(projectRoot, 'session.ended', summary);
+    } catch { /* webhook is best-effort */ }
   }
 
   process.exit(0);

package/lib/review.js

@@ -12,6 +12,7 @@ import { join } from 'path';
 import { createHash } from 'crypto';
 import { getLogDir, getProjectRoot, SESSION_ID_REGEX } from './config.js';
 import { redactSecrets } from './redact.js';
+import { dispatchWebhook } from './webhook.js';
 
 const SEVERITY_SCORE = {
   info: 1,
@@ -708,6 +709,9 @@ export default async function review(args) {
 
     const report = buildReport(selectedSessions, options);
 
+    // Dispatch webhook for review completion
+    dispatchWebhook(projectRoot, 'review.completed', report).catch(() => {});
+
     if (options.format === 'json') {
       console.log(JSON.stringify(report, null, 2));
     } else if (options.format === 'markdown') {

package/lib/webhook.js

@@ -0,0 +1,211 @@
+/**
+ * Webhook support for shit-cli.
+ * Fire-and-forget notifications for session.ended and review.completed events.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { createHmac } from 'crypto';
+import { request as httpsRequest } from 'https';
+import { request as httpRequest } from 'http';
+
+/**
+ * Load webhook configuration from .shit-logs/config.json + environment variables.
+ * Env vars take precedence over config.json values.
+ */
+export function loadWebhookConfig(projectRoot) {
+  let fileConfig = {};
+  const configPath = join(projectRoot, '.shit-logs', 'config.json');
+  if (existsSync(configPath)) {
+    try {
+      const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+      fileConfig = raw.webhooks || {};
+    } catch { /* ignore malformed config */ }
+  }
+
+  const url = process.env.SHIT_WEBHOOK_URL || fileConfig.url;
+  if (!url) return null;
+
+  const envEvents = process.env.SHIT_WEBHOOK_EVENTS;
+  const events = envEvents
+    ? envEvents.split(',').map(e => e.trim()).filter(Boolean)
+    : (Array.isArray(fileConfig.events) ? fileConfig.events : []);
+
+  return {
+    url,
+    events,
+    secret: process.env.SHIT_WEBHOOK_SECRET || fileConfig.secret || '',
+    auth_token: process.env.SHIT_WEBHOOK_AUTH_TOKEN || fileConfig.auth_token || '',
+    headers: fileConfig.headers || {},
+    timeout_ms: fileConfig.timeout_ms || 5000,
+    retry: typeof fileConfig.retry === 'number' ? fileConfig.retry : 1,
+  };
+}
+
+/**
+ * Compute HMAC-SHA256 signature in GitHub-compatible format.
+ */
+function computeSignature(secret, body) {
+  const hmac = createHmac('sha256', secret);
+  hmac.update(body);
+  return `sha256=${hmac.digest('hex')}`;
+}
+
+/**
+ * Send a single HTTP POST request. Returns a promise that resolves/rejects.
+ */
+function httpPost(url, headers, body, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const isHttps = parsed.protocol === 'https:';
+    const reqFn = isHttps ? httpsRequest : httpRequest;
+
+    const options = {
+      hostname: parsed.hostname,
+      port: parsed.port || (isHttps ? 443 : 80),
+      path: parsed.pathname + parsed.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        ...headers,
+      },
+      timeout: timeoutMs,
+    };
+
+    const req = reqFn(options, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve({ status: res.statusCode, body: data });
+        } else {
+          reject(new Error(`HTTP ${res.statusCode}: ${data.slice(0, 200)}`));
+        }
+      });
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error(`Request timed out after ${timeoutMs}ms`));
+    });
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Send webhook for a single config entry. Supports retry.
+ */
+export async function sendWebhook(config, event, payload) {
+  const body = JSON.stringify({
+    event,
+    timestamp: new Date().toISOString(),
+    payload,
+  });
+
+  const headers = { ...config.headers };
+
+  // Auth: HMAC signature or Bearer token (mutually exclusive, HMAC preferred)
+  if (config.secret) {
+    headers['X-Signature-256'] = computeSignature(config.secret, body);
+  } else if (config.auth_token) {
+    headers['Authorization'] = `Bearer ${config.auth_token}`;
+  }
+
+  const maxAttempts = (config.retry || 0) + 1;
+  let lastError;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      await httpPost(config.url, headers, body, config.timeout_ms || 5000);
+      return; // success
+    } catch (err) {
+      lastError = err;
+      if (attempt < maxAttempts) {
+        // Brief delay before retry
+        await new Promise(r => setTimeout(r, 500 * attempt));
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Main entry point: load config, filter by event, dispatch webhook.
+ * Non-blocking — logs warnings to stderr, never throws.
+ */
+export async function dispatchWebhook(projectRoot, event, payload) {
+  try {
+    const config = loadWebhookConfig(projectRoot);
+    if (!config) return;
+
+    // If events list is configured, only fire for matching events
+    if (config.events.length > 0 && !config.events.includes(event)) return;
+
+    await sendWebhook(config, event, payload);
+  } catch (err) {
+    process.stderr.write(`[shit-cli] webhook warning: ${err.message}\n`);
+  }
+}
+
+/**
+ * CLI command: shit webhook
+ * Shows current webhook configuration status.
+ */
+export default async function webhook(args) {
+  const { getProjectRoot } = await import('./config.js');
+  const projectRoot = getProjectRoot();
+  const config = loadWebhookConfig(projectRoot);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log('Usage: shit webhook [options]');
+    console.log('');
+    console.log('Show current webhook configuration.');
+    console.log('');
+    console.log('Options:');
+    console.log('  --test    Send a test webhook ping');
+    console.log('  --help    Show this help');
+    console.log('');
+    console.log('Configuration:');
+    console.log('  Set webhooks in .shit-logs/config.json or via environment variables:');
+    console.log('    SHIT_WEBHOOK_URL        Webhook endpoint URL');
+    console.log('    SHIT_WEBHOOK_SECRET     HMAC-SHA256 signing secret');
+    console.log('    SHIT_WEBHOOK_AUTH_TOKEN  Bearer token');
+    console.log('    SHIT_WEBHOOK_EVENTS     Comma-separated event list');
+    return 0;
+  }
+
+  if (!config) {
+    console.log('No webhook configured.');
+    console.log('');
+    console.log('Set SHIT_WEBHOOK_URL or add "webhooks" to .shit-logs/config.json');
+    return 0;
+  }
+
+  console.log('Webhook configuration:');
+  console.log(`  URL:     ${config.url}`);
+  console.log(`  Events:  ${config.events.length > 0 ? config.events.join(', ') : '(all)'}`);
+  console.log(`  Auth:    ${config.secret ? 'HMAC-SHA256' : config.auth_token ? 'Bearer token' : 'none'}`);
+  console.log(`  Timeout: ${config.timeout_ms}ms`);
+  console.log(`  Retry:   ${config.retry}`);
+  if (Object.keys(config.headers).length > 0) {
+    console.log(`  Headers: ${Object.keys(config.headers).join(', ')}`);
+  }
+
+  if (args.includes('--test')) {
+    console.log('');
+    console.log('Sending test ping...');
+    try {
+      await sendWebhook(config, 'ping', { message: 'shit-cli webhook test' });
+      console.log('OK — webhook delivered successfully.');
+    } catch (err) {
+      console.error(`Failed: ${err.message}`);
+      return 1;
+    }
+  }
+
+  return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudemini/shit-cli",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Session-based Hook Intelligence Tracker - Zero-dependency memory system for human-AI coding sessions",
   "type": "module",
   "bin": {