@ngxtm/devkit 2.1.0 → 3.0.0

package/templates/base/hooks/lib/context-tracker.cjs

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Context Window Tracker - Self-healing context reset detection
+ *
+ * Fixes #177: Race condition from shared global state file
+ * Fixes #178: Consolidates temp files to /tmp/ck/ namespace
+ *
+ * Architecture:
+ * - NO global state file (was causing race conditions in concurrent sessions)
+ * - All state embedded in session-specific marker files
+ * - Each session is completely isolated (no shared state)
+ *
+ * Detection layers:
+ * - Layer 1: Hook markers (explicit reset signal from PreCompact/SessionStart)
+ * - Layer 2: Token drop detection (50% threshold fallback for hook failures)
+ *
+ * Removed:
+ * - Old Layer 1 (session ID change detection) - was the BUG source
+ * - Global STATE_FILE - caused race conditions in concurrent sessions
+ *
+ * Marker schema:
+ * {
+ *   sessionId: string,
+ *   trigger: string,           // 'session_start_clear', 'manual', 'auto', 'new_session', 'token_drop'
+ *   baselineRecorded: boolean,
+ *   baseline: number,          // Token count at baseline
+ *   lastTokenTotal: number,    // For token drop detection (replaces global state)
+ *   timestamp: number
+ * }
+ *
+ * @module context-tracker
+ */
+
+const fs = require('fs');
+const {
+  MARKERS_DIR,
+  CALIBRATION_PATH,
+  ensureDir,
+  getMarkerPath
+} = require('./ck-paths.cjs');
+
+// Token drop threshold for Layer 2 detection (50%)
+// Rationale: /compact typically reduces tokens by 60-80%, so 50% catches
+// context resets while avoiding false positives from normal token accumulation.
+// Exclusive: drops below (<) 50% trigger reset
+const TOKEN_DROP_THRESHOLD = 0.5;
+
+/**
+ * Get smart default compact threshold based on context window size
+ * Research-based defaults:
+ * - 200k window: ~77.5% (155k) - confirmed from GitHub issues
+ * - 1M window: ~33% (330k) - derived from user observations
+ *
+ * @param {number} contextWindowSize - Model's context window size
+ * @returns {number} Estimated compact threshold in tokens
+ */
+function getDefaultCompactThreshold(contextWindowSize) {
+  const KNOWN_THRESHOLDS = {
+    200000: 155000,   // 77.5% - confirmed via /context showing 45k buffer
+    1000000: 330000,  // 33% - 1M beta window
+  };
+
+  if (KNOWN_THRESHOLDS[contextWindowSize]) {
+    return KNOWN_THRESHOLDS[contextWindowSize];
+  }
+
+  // Tiered defaults based on window size
+  if (contextWindowSize >= 1000000) {
+    return Math.floor(contextWindowSize * 0.33);
+  }
+  return Math.floor(contextWindowSize * 0.775);
+}
+
+/**
+ * Read calibration data from file (recorded by PreCompact hook)
+ * @returns {Object} Calibration data keyed by context window size
+ */
+function readCalibration() {
+  try {
+    if (fs.existsSync(CALIBRATION_PATH)) {
+      return JSON.parse(fs.readFileSync(CALIBRATION_PATH, 'utf8'));
+    }
+  } catch (err) {
+    // Silent fail - use defaults
+  }
+  return {};
+}
+
+/**
+ * Get compact threshold, preferring calibrated value over default
+ * @param {number} contextWindowSize - Model's context window size
+ * @returns {number} Compact threshold in tokens
+ */
+function getCompactThreshold(contextWindowSize) {
+  const calibration = readCalibration();
+  const key = String(contextWindowSize);
+
+  if (calibration[key] && calibration[key].threshold > 0) {
+    return calibration[key].threshold;
+  }
+  return getDefaultCompactThreshold(contextWindowSize);
+}
+
+/**
+ * Read marker file for a session
+ * Defensive: handles missing/empty/corrupt files gracefully
+ * @param {string} sessionId - Session ID
+ * @returns {Object|null} Marker data or null
+ */
+function readMarker(sessionId) {
+  try {
+    const markerPath = getMarkerPath(sessionId);
+    if (!fs.existsSync(markerPath)) return null;
+    const data = fs.readFileSync(markerPath, 'utf8');
+    if (!data.trim()) return null; // Catch empty/corrupt files
+    const marker = JSON.parse(data);
+    // Basic schema validation
+    if (!marker || typeof marker.sessionId !== 'string') {
+      return null;
+    }
+    return marker;
+  } catch (err) {
+    // Silent fail - corrupt JSON or read error
+  }
+  return null;
+}
+
+/**
+ * Write marker file for a session
+ * @param {string} sessionId - Session ID
+ * @param {Object} marker - Marker data
+ */
+function writeMarker(sessionId, marker) {
+  try {
+    ensureDir(MARKERS_DIR);
+    const markerPath = getMarkerPath(sessionId);
+    fs.writeFileSync(markerPath, JSON.stringify(marker));
+  } catch (err) {
+    // Silent fail
+  }
+}
+
+/**
+ * Delete marker file for a session
+ * @param {string} sessionId - Session ID
+ */
+function deleteMarker(sessionId) {
+  try {
+    const markerPath = getMarkerPath(sessionId);
+    if (fs.existsSync(markerPath)) {
+      fs.unlinkSync(markerPath);
+    }
+  } catch (err) {
+    // Silent fail
+  }
+}
+
+/**
+ * Layer 2: Detect significant token drop (50%+ reduction)
+ * Uses session-specific lastTokenTotal from marker (no global state)
+ * @param {number} currentTotal - Current cumulative token total
+ * @param {Object|null} marker - Session marker with lastTokenTotal
+ * @returns {boolean} True if token drop detected
+ */
+function detectTokenDrop(currentTotal, marker) {
+  if (!marker || !marker.lastTokenTotal || marker.lastTokenTotal <= 0 || currentTotal <= 0) {
+    return false;
+  }
+
+  // Token total dropped by more than 50%
+  const dropRatio = currentTotal / marker.lastTokenTotal;
+  return dropRatio < TOKEN_DROP_THRESHOLD;
+}
+
+/**
+ * Layer 1: Check for explicit reset marker from hooks
+ * @param {Object|null} marker - Session marker
+ * @returns {{ shouldReset: boolean, trigger: string|null }}
+ */
+function checkResetMarker(marker) {
+  if (!marker) {
+    return { shouldReset: false, trigger: null };
+  }
+
+  // Check if marker indicates a reset (clear/compact)
+  const resetTriggers = ['clear', 'session_start_clear'];
+  if (resetTriggers.includes(marker.trigger)) {
+    return { shouldReset: true, trigger: marker.trigger };
+  }
+
+  return { shouldReset: false, trigger: marker.trigger };
+}
+
+/**
+ * Main context tracking function with 2-layer self-healing detection
+ *
+ * Layer 1: Hook markers (explicit reset from PreCompact/SessionStart)
+ * Layer 2: Token drop detection (50% threshold fallback)
+ *
+ * NO global state - all state is session-specific in marker files
+ *
+ * @param {Object} params - Tracking parameters
+ * @param {string} params.sessionId - Current session ID
+ * @param {number} params.contextInput - Input tokens
+ * @param {number} params.contextOutput - Output tokens
+ * @param {number} params.contextWindowSize - Model's context window size
+ * @returns {Object} { percentage, baseline, showCompactIndicator, resetLayer }
+ */
+function trackContext({ sessionId, contextInput, contextOutput, contextWindowSize }) {
+  const currentTotal = contextInput + contextOutput;
+  const compactThreshold = getCompactThreshold(contextWindowSize);
+  const effectiveSessionId = sessionId || 'default';
+
+  // Read session-specific marker (no global state!)
+  let marker = readMarker(effectiveSessionId);
+
+  // Track which layer triggered reset (for debugging)
+  let resetLayer = null;
+  let baseline = 0;
+  let showCompactIndicator = false;
+
+  // --- Layer 1: Hook marker system ---
+  // Markers from PreCompact/SessionStart hooks are explicit signals
+  const { shouldReset, trigger } = checkResetMarker(marker);
+  if (shouldReset) {
+    resetLayer = `marker_${trigger}`;
+    baseline = currentTotal;
+    // Clear the reset trigger after processing
+    marker = null; // Force fresh marker creation below
+  }
+
+  // --- Layer 2: Token drop detection (fallback for hook failures) ---
+  if (!resetLayer && detectTokenDrop(currentTotal, marker)) {
+    resetLayer = 'token_drop';
+    baseline = currentTotal;
+    marker = null; // Force fresh marker creation below
+  }
+
+  // --- No reset triggered - use existing marker/baseline ---
+  if (!resetLayer && marker) {
+    if (!marker.baselineRecorded) {
+      // Marker exists but baseline not recorded yet (from PreCompact)
+      marker.baselineRecorded = true;
+      marker.baseline = currentTotal;
+      marker.lastTokenTotal = currentTotal;
+      writeMarker(effectiveSessionId, marker);
+      baseline = currentTotal;
+      // PreCompact triggers: "manual" (from /compact) or "auto" (from auto-compact)
+      showCompactIndicator = ['compact', 'manual', 'auto'].includes(marker.trigger);
+    } else {
+      // Use stored baseline
+      baseline = marker.baseline || 0;
+    }
+  }
+
+  // --- Create fresh marker if needed ---
+  if (!marker || resetLayer) {
+    const newMarker = {
+      sessionId: effectiveSessionId,
+      trigger: resetLayer || 'new_session',
+      baselineRecorded: true,
+      baseline: currentTotal,
+      lastTokenTotal: currentTotal,
+      timestamp: Date.now()
+    };
+    writeMarker(effectiveSessionId, newMarker);
+    if (!resetLayer) {
+      baseline = currentTotal;
+    }
+  } else {
+    // Update lastTokenTotal for next token drop detection
+    marker.lastTokenTotal = currentTotal;
+    writeMarker(effectiveSessionId, marker);
+  }
+
+  // Calculate effective tokens (since baseline)
+  let effectiveTotal = baseline > 0 ? currentTotal - baseline : currentTotal;
+  if (effectiveTotal < 0) effectiveTotal = 0;
+
+  // Calculate percentage against compact threshold (not model limit)
+  const percentage = Math.min(100, Math.floor(effectiveTotal * 100 / compactThreshold));
+
+  return {
+    percentage,
+    baseline,
+    effectiveTotal,
+    compactThreshold,
+    showCompactIndicator,
+    resetLayer
+  };
+}
+
+/**
+ * Write reset marker for session (called by SessionStart hook on /clear)
+ * @param {string} sessionId - Session ID
+ * @param {string} trigger - Reset trigger ('clear', 'compact', etc.)
+ */
+function writeResetMarker(sessionId, trigger = 'clear') {
+  const effectiveSessionId = sessionId || 'default';
+  ensureDir(MARKERS_DIR);
+  writeMarker(effectiveSessionId, {
+    sessionId: effectiveSessionId,
+    trigger: `session_start_${trigger}`,
+    baselineRecorded: false,
+    baseline: 0,
+    lastTokenTotal: 0,
+    timestamp: Date.now()
+  });
+}
+
+/**
+ * Clear all markers (for testing/cleanup)
+ * Uses new /tmp/ck/ namespace
+ */
+function clearAllState() {
+  const { cleanAll } = require('./ck-paths.cjs');
+  cleanAll();
+}
+
+module.exports = {
+  trackContext,
+  writeResetMarker,
+  clearAllState,
+  getCompactThreshold,
+  // Export for testing
+  detectTokenDrop,
+  checkResetMarker,
+  readMarker,
+  writeMarker,
+  deleteMarker,
+  TOKEN_DROP_THRESHOLD,
+  MARKERS_DIR
+};

package/templates/base/hooks/lib/privacy-checker.cjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+/**
+ * privacy-checker.cjs - Privacy pattern matching logic for sensitive file detection
+ *
+ * Extracted from privacy-block.cjs for reuse in both Claude hooks and OpenCode plugins.
+ * Pure logic module - no stdin/stdout, no exit codes.
+ *
+ * @module privacy-checker
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+const APPROVED_PREFIX = 'APPROVED:';
+
+// Safe file patterns - exempt from privacy checks (documentation/template files)
+const SAFE_PATTERNS = [
+  /\.example$/i,   // .env.example, config.example
+  /\.sample$/i,    // .env.sample
+  /\.template$/i,  // .env.template
+];
+
+// Privacy-sensitive patterns
+const PRIVACY_PATTERNS = [
+  /^\.env$/,              // .env
+  /^\.env\./,             // .env.local, .env.production, etc.
+  /\.env$/,               // path/to/.env
+  /\/\.env\./,            // path/to/.env.local
+  /credentials/i,         // credentials.json, etc.
+  /secrets?\.ya?ml$/i,    // secrets.yaml, secret.yml
+  /\.pem$/,               // Private keys
+  /\.key$/,               // Private keys
+  /id_rsa/,               // SSH keys
+  /id_ed25519/,           // SSH keys
+];
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if path is a safe file (example/sample/template)
+ * @param {string} testPath - Path to check
+ * @returns {boolean} true if file matches safe patterns
+ */
+function isSafeFile(testPath) {
+  if (!testPath) return false;
+  const basename = path.basename(testPath);
+  return SAFE_PATTERNS.some(p => p.test(basename));
+}
+
+/**
+ * Check if path has APPROVED: prefix
+ * @param {string} testPath - Path to check
+ * @returns {boolean} true if path starts with APPROVED:
+ */
+function hasApprovalPrefix(testPath) {
+  return testPath && testPath.startsWith(APPROVED_PREFIX);
+}
+
+/**
+ * Strip APPROVED: prefix from path
+ * @param {string} testPath - Path to process
+ * @returns {string} Path without APPROVED: prefix
+ */
+function stripApprovalPrefix(testPath) {
+  if (hasApprovalPrefix(testPath)) {
+    return testPath.slice(APPROVED_PREFIX.length);
+  }
+  return testPath;
+}
+
+/**
+ * Check if stripped path is suspicious (path traversal or absolute)
+ * @param {string} strippedPath - Path after stripping APPROVED: prefix
+ * @returns {boolean} true if path looks suspicious
+ */
+function isSuspiciousPath(strippedPath) {
+  return strippedPath.includes('..') || path.isAbsolute(strippedPath);
+}
+
+/**
+ * Check if path matches privacy patterns
+ * @param {string} testPath - Path to check
+ * @returns {boolean} true if path matches privacy-sensitive patterns
+ */
+function isPrivacySensitive(testPath) {
+  if (!testPath) return false;
+
+  // Strip prefix for pattern matching
+  const cleanPath = stripApprovalPrefix(testPath);
+  let normalized = cleanPath.replace(/\\/g, '/');
+
+  // Decode URI components to catch obfuscated paths (%2e = '.')
+  try {
+    normalized = decodeURIComponent(normalized);
+  } catch (e) {
+    // Invalid encoding, use as-is
+  }
+
+  // Check safe patterns first - exempt example/sample/template files
+  if (isSafeFile(normalized)) {
+    return false;
+  }
+
+  const basename = path.basename(normalized);
+
+  for (const pattern of PRIVACY_PATTERNS) {
+    if (pattern.test(basename) || pattern.test(normalized)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Extract paths from tool input
+ * @param {Object} toolInput - Tool input object with file_path, path, pattern, or command
+ * @returns {Array<{value: string, field: string}>} Array of extracted paths with field names
+ */
+function extractPaths(toolInput) {
+  const paths = [];
+  if (!toolInput) return paths;
+
+  if (toolInput.file_path) paths.push({ value: toolInput.file_path, field: 'file_path' });
+  if (toolInput.path) paths.push({ value: toolInput.path, field: 'path' });
+  if (toolInput.pattern) paths.push({ value: toolInput.pattern, field: 'pattern' });
+
+  // Check bash commands for file paths
+  if (toolInput.command) {
+    // Look for APPROVED:.env or .env patterns
+    const approvedMatch = toolInput.command.match(/APPROVED:[^\s]+/g) || [];
+    approvedMatch.forEach(p => paths.push({ value: p, field: 'command' }));
+
+    // Only look for .env if no APPROVED: version found
+    if (approvedMatch.length === 0) {
+      const envMatch = toolInput.command.match(/\.env[^\s]*/g) || [];
+      envMatch.forEach(p => paths.push({ value: p, field: 'command' }));
+
+      // Also check bash variable assignments (FILE=.env, ENV_FILE=.env.local)
+      const varAssignments = toolInput.command.match(/\w+=[^\s]*\.env[^\s]*/g) || [];
+      varAssignments.forEach(a => {
+        const value = a.split('=')[1];
+        if (value) paths.push({ value, field: 'command' });
+      });
+
+      // Check command substitution containing sensitive patterns - extract .env from inside
+      const cmdSubst = toolInput.command.match(/\$\([^)]*?(\.env[^\s)]*)[^)]*\)/g) || [];
+      for (const subst of cmdSubst) {
+        const inner = subst.match(/\.env[^\s)]*/);
+        if (inner) paths.push({ value: inner[0], field: 'command' });
+      }
+    }
+  }
+
+  return paths.filter(p => p.value);
+}
+
+/**
+ * Load .ck.json config to check if privacy block is disabled
+ * @param {string} [configDir] - Directory containing .ck.json (defaults to .claude in cwd)
+ * @returns {boolean} true if privacy block should be skipped
+ */
+function isPrivacyBlockDisabled(configDir) {
+  try {
+    const configPath = configDir
+      ? path.join(configDir, '.ck.json')
+      : path.join(process.cwd(), '.claude', '.ck.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return config.privacyBlock === false;
+  } catch {
+    return false; // Default to enabled on error (file not found or invalid JSON)
+  }
+}
+
+/**
+ * Build prompt data for AskUserQuestion tool
+ * @param {string} filePath - Blocked file path
+ * @returns {Object} Prompt data object
+ */
+function buildPromptData(filePath) {
+  const basename = path.basename(filePath);
+  return {
+    type: 'PRIVACY_PROMPT',
+    file: filePath,
+    basename: basename,
+    question: {
+      header: 'File Access',
+      text: `I need to read "${basename}" which may contain sensitive data (API keys, passwords, tokens). Do you approve?`,
+      options: [
+        { label: 'Yes, approve access', description: `Allow reading ${basename} this time` },
+        { label: 'No, skip this file', description: 'Continue without accessing this file' }
+      ]
+    }
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN ENTRY POINT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if a tool call accesses privacy-sensitive files
+ *
+ * @param {Object} params
+ * @param {string} params.toolName - Name of tool (Read, Write, Bash, etc.)
+ * @param {Object} params.toolInput - Tool input with file_path, path, command, etc.
+ * @param {Object} [params.options]
+ * @param {boolean} [params.options.disabled] - Skip checks if true
+ * @param {string} [params.options.configDir] - Directory for .ck.json config
+ * @param {boolean} [params.options.allowBash] - Allow Bash tool without blocking (default: true)
+ * @returns {{
+ *   blocked: boolean,
+ *   filePath?: string,
+ *   reason?: string,
+ *   approved?: boolean,
+ *   isBash?: boolean,
+ *   suspicious?: boolean,
+ *   promptData?: Object
+ * }}
+ */
+function checkPrivacy({ toolName, toolInput, options = {} }) {
+  const { disabled, configDir, allowBash = true } = options;
+
+  // Check if disabled via options or config
+  if (disabled || isPrivacyBlockDisabled(configDir)) {
+    return { blocked: false };
+  }
+
+  const isBashTool = toolName === 'Bash';
+  const paths = extractPaths(toolInput);
+
+  // Check each path
+  for (const { value: testPath } of paths) {
+    if (!isPrivacySensitive(testPath)) continue;
+
+    // Check for approval prefix
+    if (hasApprovalPrefix(testPath)) {
+      const strippedPath = stripApprovalPrefix(testPath);
+      return {
+        blocked: false,
+        approved: true,
+        filePath: strippedPath,
+        suspicious: isSuspiciousPath(strippedPath)
+      };
+    }
+
+    // For Bash: warn but don't block (allows "Yes → bash cat" flow)
+    if (isBashTool && allowBash) {
+      return {
+        blocked: false,
+        isBash: true,
+        filePath: testPath,
+        reason: `Bash command accesses sensitive file: ${testPath}`
+      };
+    }
+
+    // Block - sensitive file without approval
+    return {
+      blocked: true,
+      filePath: testPath,
+      reason: `Sensitive file access requires user approval`,
+      promptData: buildPromptData(testPath)
+    };
+  }
+
+  // No sensitive paths found
+  return { blocked: false };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  // Main entry point
+  checkPrivacy,
+
+  // Helper functions (for testing and direct use)
+  isSafeFile,
+  isPrivacySensitive,
+  hasApprovalPrefix,
+  stripApprovalPrefix,
+  isSuspiciousPath,
+  extractPaths,
+  isPrivacyBlockDisabled,
+  buildPromptData,
+
+  // Constants
+  APPROVED_PREFIX,
+  SAFE_PATTERNS,
+  PRIVACY_PATTERNS
+};