@scheduler-systems/gal 0.1.1-beta

package/scripts/postinstall.cjs

@@ -0,0 +1,694 @@
+#!/usr/bin/env node
+/**
+ * GAL CLI Postinstall Script
+ *
+ * Automatically installs Claude Code integrations when GAL CLI is installed:
+ * 1. SessionStart hook → ~/.claude/hooks/gal-sync-reminder.js
+ * 2. Status line script → ~/.claude/status_lines/gal-sync-status.py
+ * 3. GAL CLI rules → ~/.claude/rules/gal-cli.md
+ *
+ * These are CLI-level configs (not org-specific).
+ * Org-specific configs are handled by `gal sync --pull`.
+ *
+ * Key behaviors:
+ * - Idempotent: Safe to run multiple times
+ * - Version-aware: Updates outdated scripts
+ * - Self-cleaning: Scripts remove themselves if GAL CLI is uninstalled
+ * - Non-destructive: Won't overwrite user's custom configs
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Get current CLI version from package.json
+const cliPackageJson = require('../package.json');
+const CLI_VERSION = cliPackageJson.version;
+
+// Version markers for idempotency
+const HOOK_VERSION = '2.1.0'; // SessionStart version (2.1.0: Added telemetry tracking)
+const STATUS_LINE_VERSION = '1.0.0';
+const RULES_VERSION = '1.0.0';
+
+// =============================================================================
+// GAL CLI Rules Content
+// =============================================================================
+// This is injected into ~/.claude/rules/gal-cli.md
+// Provides persistent GAL CLI awareness without running on every prompt
+// =============================================================================
+
+const GAL_CLI_RULES_CONTENT = `# GAL CLI
+
+<!-- GAL_RULES_VERSION = "${RULES_VERSION}" -->
+
+The \`gal\` CLI is available for managing org-approved AI agent configurations.
+
+## Available Commands
+- \`gal sync --pull\` - Download latest approved config from your organization
+- \`gal auth login\` - Authenticate with GitHub
+- \`gal --help\` - See all available commands
+
+## Behavior Rules
+- **Confirmation Required**: Always ask the user before running any \`gal\` command
+- **Self-Discovery**: If unsure about syntax, run \`gal --help\` or \`gal <command> --help\` first
+- **Sync Notifications**: When you see a GAL sync notification, ask: "Do you want me to sync gal now?"
+`;
+
+// =============================================================================
+// SessionStart Hook Content
+// =============================================================================
+// Shows sync status at session start (appears at top of chat, stays there).
+// Periodic reminders are handled by the status line.
+// =============================================================================
+
+const HOOK_CONTENT = `#!/usr/bin/env node
+/**
+ * GAL Config Sync Hook for Claude Code (SessionStart)
+ * Version: ${HOOK_VERSION}
+ *
+ * Shows sync status at session start:
+ * - Not authenticated → prompt to login
+ * - Token expired → prompt to re-login
+ * - Not synced → prompt to sync
+ * - Config outdated → prompt to sync
+ * - All good → show synced status
+ *
+ * Self-cleaning: removes itself if GAL CLI is uninstalled.
+ */
+
+// GAL_HOOK_VERSION = "${HOOK_VERSION}"
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const os = require('os');
+
+const GAL_DIR = '.gal';
+const SYNC_STATE_FILE = 'sync-state.json';
+const GAL_CONFIG_FILE = path.join(os.homedir(), '.gal', 'config.json');
+
+function showMessage(message, status) {
+  // Queue telemetry event before showing message
+  queueTelemetryEvent(status);
+  console.log(JSON.stringify({ systemMessage: message }));
+  process.exit(0);
+}
+
+// =============================================================================
+// Telemetry: Queue events for CLI to send on next run (GAL-114)
+// =============================================================================
+
+function queueTelemetryEvent(status) {
+  const pendingEventsPath = path.join(os.homedir(), '.gal', 'telemetry-pending-events.json');
+  const galDir = path.join(os.homedir(), '.gal');
+
+  let pending = [];
+  try {
+    if (fs.existsSync(pendingEventsPath)) {
+      pending = JSON.parse(fs.readFileSync(pendingEventsPath, 'utf-8'));
+    }
+  } catch {}
+
+  // Add session start hook event
+  pending.push({
+    id: require('crypto').randomUUID(),
+    eventType: 'hook_triggered',
+    timestamp: new Date().toISOString(),
+    payload: {
+      notificationType: 'session_start',
+      hookVersion: '${HOOK_VERSION}',
+      status: status,
+      cwd: process.cwd(),
+      platform: process.platform,
+      nodeVersion: process.version,
+    },
+    queuedAt: Date.now(),
+  });
+
+  try {
+    if (!fs.existsSync(galDir)) {
+      fs.mkdirSync(galDir, { recursive: true });
+    }
+    fs.writeFileSync(pendingEventsPath, JSON.stringify(pending), 'utf-8');
+  } catch {
+    // Ignore errors - telemetry is optional
+  }
+}
+
+// =============================================================================
+// Self-cleaning: Remove hook if GAL CLI is uninstalled
+// =============================================================================
+
+function isGalInstalled() {
+  try {
+    execSync('which gal', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function selfClean() {
+  const hookPath = __filename;
+  const claudeDir = path.join(os.homedir(), '.claude');
+  const settingsPath = path.join(claudeDir, 'settings.json');
+  const rulesPath = path.join(claudeDir, 'rules', 'gal-cli.md');
+
+  // Remove hook file
+  try { fs.unlinkSync(hookPath); } catch {}
+
+  // Remove rules file
+  try { fs.unlinkSync(rulesPath); } catch {}
+
+  // Remove hook entries from settings.json
+  try {
+    if (fs.existsSync(settingsPath)) {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+      const hookEvents = ['SessionStart', 'UserPromptSubmit'];
+
+      for (const event of hookEvents) {
+        if (settings.hooks?.[event]) {
+          settings.hooks[event] = settings.hooks[event].filter(entry => {
+            if (!entry.hooks) return true;
+            entry.hooks = entry.hooks.filter(h => !h.command?.includes('gal-'));
+            return entry.hooks.length > 0;
+          });
+          if (settings.hooks[event].length === 0) delete settings.hooks[event];
+        }
+      }
+
+      if (Object.keys(settings.hooks || {}).length === 0) delete settings.hooks;
+      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    }
+  } catch {}
+}
+
+// Check if GAL is installed, self-clean if not
+if (!isGalInstalled()) {
+  selfClean();
+  process.exit(0);
+}
+
+// Read GAL CLI config (auth token, default org)
+function readGalConfig() {
+  if (!fs.existsSync(GAL_CONFIG_FILE)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(GAL_CONFIG_FILE, 'utf-8'));
+  } catch { return null; }
+}
+
+// Decode JWT without verification (just to check expiration)
+function decodeJwt(token) {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString('utf-8'));
+    return payload;
+  } catch { return null; }
+}
+
+// Check authentication status
+const galConfig = readGalConfig();
+
+// Check 1: Not authenticated
+if (!galConfig || !galConfig.authToken) {
+  showMessage("🔐 GAL: Authentication required.\\nRun: gal auth login", 'auth_required');
+}
+
+// Check 2: Token expired
+const tokenPayload = decodeJwt(galConfig.authToken);
+if (tokenPayload && tokenPayload.exp) {
+  const expiresAt = tokenPayload.exp * 1000;
+  if (Date.now() > expiresAt) {
+    showMessage("🔐 GAL: Session expired.\\nRun: gal auth login", 'token_expired');
+  }
+}
+
+// Check 3: Project not synced
+function readSyncState() {
+  const statePath = path.join(process.cwd(), GAL_DIR, SYNC_STATE_FILE);
+  if (!fs.existsSync(statePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+  } catch { return null; }
+}
+
+const state = readSyncState();
+
+if (!state) {
+  const orgName = galConfig.defaultOrg || 'your organization';
+  showMessage(\`📥 GAL: Not synced with \${orgName}'s approved config.\\nRun: gal sync --pull\`, 'not_synced');
+}
+
+// Check 4: Config outdated
+if (state.lastSyncHash !== state.approvedConfigHash) {
+  const days = Math.floor((Date.now() - new Date(state.lastSyncTimestamp).getTime()) / (24 * 60 * 60 * 1000));
+  showMessage(\`⚠️ GAL: Config is \${days} day(s) behind \${state.organization}'s approved version.\\nRun: gal sync --pull\`, 'config_outdated');
+}
+
+// Check 5: Missing synced files
+if (state.syncedFiles && state.syncedFiles.length > 0) {
+  const missingFiles = state.syncedFiles.filter(f => {
+    const fullPath = path.join(process.cwd(), f);
+    return !fs.existsSync(fullPath);
+  });
+
+  if (missingFiles.length > 0) {
+    showMessage(\`⚠️ GAL: Missing synced file(s): \${missingFiles.join(', ')}.\\nRun: gal sync --pull\`, 'missing_files');
+  }
+}
+
+// All good - show synced status
+showMessage(\`✅ GAL: Synced with \${state.organization}'s approved config (v\${state.version || 'latest'})\`, 'synced');
+`;
+
+// =============================================================================
+// Status Line Script Content
+// =============================================================================
+// Shows sync warnings in Claude Code's status bar (always when not synced).
+// Silent when synced (no green tick spam).
+// =============================================================================
+
+const STATUS_LINE_CONTENT = `#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "python-dotenv",
+# ]
+# ///
+"""
+GAL Sync Status Line for Claude Code
+Generated by GAL CLI
+
+Version: ${STATUS_LINE_VERSION}
+
+Behavior:
+- NOT synced: Always show warning
+- Synced: Silent (no output)
+"""
+
+# GAL_STATUS_LINE_VERSION = "${STATUS_LINE_VERSION}"
+
+import json
+import os
+import sys
+import subprocess
+from pathlib import Path
+
+# =============================================================================
+# CONFIGURATION
+# =============================================================================
+GAL_DIR = '.gal'
+SYNC_STATE_FILE = 'sync-state.json'
+GAL_CONFIG_FILE = Path.home() / '.gal' / 'config.json'
+
+
+def is_gal_installed() -> bool:
+    """Check if GAL CLI is installed."""
+    try:
+        subprocess.run(['which', 'gal'], capture_output=True, check=True)
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+
+def self_clean():
+    """Remove this status line if GAL CLI is uninstalled."""
+    script_path = Path(__file__).resolve()
+    settings_path = Path.home() / '.claude' / 'settings.json'
+
+    # Remove script file
+    try:
+        script_path.unlink()
+    except (OSError, IOError):
+        pass
+
+    # Remove from settings.json
+    try:
+        if settings_path.exists():
+            settings = json.loads(settings_path.read_text())
+            status_line_cmd = settings.get('statusLine', {}).get('command', '')
+            if 'gal-sync-status' in status_line_cmd:
+                del settings['statusLine']
+                settings_path.write_text(json.dumps(settings, indent=2))
+    except (json.JSONDecodeError, IOError):
+        pass
+
+
+def read_gal_config():
+    """Read GAL CLI config (auth token, default org)."""
+    if not GAL_CONFIG_FILE.exists():
+        return None
+    try:
+        return json.loads(GAL_CONFIG_FILE.read_text())
+    except (json.JSONDecodeError, IOError):
+        return None
+
+
+def read_sync_state():
+    """Read sync state from .gal/sync-state.json in current directory."""
+    state_path = Path.cwd() / GAL_DIR / SYNC_STATE_FILE
+    if not state_path.exists():
+        return None
+    try:
+        return json.loads(state_path.read_text())
+    except (json.JSONDecodeError, IOError):
+        return None
+
+
+def generate_status_line(input_data):
+    """Generate the GAL sync status line.
+
+    Behavior:
+    - NOT synced: Always show warning (no throttle)
+    - Synced: Silent (no message)
+    """
+
+    # Self-clean if GAL is uninstalled
+    if not is_gal_installed():
+        self_clean()
+        return ""
+
+    # Read GAL config
+    gal_config = read_gal_config()
+
+    # Check 1: Not authenticated - always show
+    if not gal_config or not gal_config.get('authToken'):
+        return "\\033[33m🔐 GAL: login\\033[0m"
+
+    # Check 2: Project not synced - always show
+    state = read_sync_state()
+
+    if not state:
+        return "\\033[33m📥 GAL: sync\\033[0m"
+
+    # Check 3: Config outdated (hash mismatch) - always show
+    if state.get('lastSyncHash') != state.get('approvedConfigHash'):
+        return "\\033[33m⚠️ GAL: outdated\\033[0m"
+
+    # Check 4: Missing synced files - always show
+    synced_files = state.get('syncedFiles', [])
+    if synced_files:
+        missing = [f for f in synced_files if not (Path.cwd() / f).exists()]
+        if missing:
+            return "\\033[33m⚠️ GAL: missing files\\033[0m"
+
+    # Synced - stay silent
+    return ""
+
+
+def main():
+    try:
+        # Read JSON input from stdin (Claude Code passes context)
+        input_data = json.loads(sys.stdin.read())
+
+        # Generate status line
+        status_line = generate_status_line(input_data)
+
+        # Only output if there's something to show
+        if status_line:
+            print(status_line)
+
+        sys.exit(0)
+
+    except json.JSONDecodeError:
+        # Handle JSON decode errors gracefully - stay silent
+        sys.exit(0)
+    except Exception:
+        # Handle any other errors gracefully - stay silent
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()
+`;
+
+// =============================================================================
+// Installation Functions
+// =============================================================================
+
+/**
+ * Install the SessionStart hook to ~/.claude/hooks/
+ *
+ * Key behaviors:
+ * - Idempotent: Checks version before writing
+ * - Cleans up old UserPromptSubmit hooks
+ * - Registers in settings.json
+ */
+function installHook() {
+  const claudeDir = path.join(os.homedir(), '.claude');
+  const hooksDir = path.join(claudeDir, 'hooks');
+  const hookPath = path.join(hooksDir, 'gal-sync-reminder.js');
+  const settingsPath = path.join(claudeDir, 'settings.json');
+
+  try {
+    // Create directories if needed
+    if (!fs.existsSync(hooksDir)) {
+      fs.mkdirSync(hooksDir, { recursive: true });
+    }
+
+    // Check if hook already exists with current version
+    let needsUpdate = true;
+    if (fs.existsSync(hookPath)) {
+      const existingContent = fs.readFileSync(hookPath, 'utf-8');
+      const versionMatch = existingContent.match(/GAL_HOOK_VERSION = "([^"]+)"/);
+      if (versionMatch && versionMatch[1] === HOOK_VERSION) {
+        needsUpdate = false;
+      }
+    }
+
+    // Write the hook file if needed
+    if (needsUpdate) {
+      fs.writeFileSync(hookPath, HOOK_CONTENT, 'utf-8');
+      fs.chmodSync(hookPath, '755');
+    }
+
+    // Update settings.json
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+      try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+      } catch {
+        settings = {};
+      }
+    }
+
+    // CLEANUP: Remove old UserPromptSubmit hooks (we now use SessionStart)
+    if (settings.hooks?.UserPromptSubmit) {
+      settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(entry => {
+        if (!entry.hooks) return true;
+        entry.hooks = entry.hooks.filter(h =>
+          !h.command?.includes('gal-') && !h.command?.includes('/gal/')
+        );
+        return entry.hooks.length > 0;
+      });
+      if (settings.hooks.UserPromptSubmit.length === 0) {
+        delete settings.hooks.UserPromptSubmit;
+      }
+    }
+
+    // Register SessionStart hook if not already registered
+    const hookCommand = `node ${hookPath}`;
+    if (!settings.hooks) settings.hooks = {};
+    if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+
+    const alreadyRegistered = settings.hooks.SessionStart.some(entry =>
+      entry.hooks?.some(h => h.command?.includes('gal-sync-reminder'))
+    );
+
+    if (!alreadyRegistered) {
+      settings.hooks.SessionStart.push({
+        hooks: [{ type: 'command', command: hookCommand }]
+      });
+    }
+
+    // Write settings
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
+
+    if (needsUpdate) {
+      console.log('✓ GAL SessionStart hook installed');
+    }
+    return true;
+  } catch (error) {
+    // Silent fail - hook is optional enhancement
+    return false;
+  }
+}
+
+/**
+ * Install GAL CLI rules to ~/.claude/rules/
+ *
+ * Key behaviors:
+ * - Idempotent: Checks version before writing
+ * - Provides persistent GAL CLI awareness
+ * - No longer runs on every prompt (unlike hooks)
+ */
+function installRules() {
+  const claudeDir = path.join(os.homedir(), '.claude');
+  const rulesDir = path.join(claudeDir, 'rules');
+  const rulesPath = path.join(rulesDir, 'gal-cli.md');
+
+  try {
+    // Create rules directory if needed
+    if (!fs.existsSync(rulesDir)) {
+      fs.mkdirSync(rulesDir, { recursive: true });
+    }
+
+    // Check if rules file already exists with current version
+    let needsUpdate = true;
+    if (fs.existsSync(rulesPath)) {
+      const existingContent = fs.readFileSync(rulesPath, 'utf-8');
+      const versionMatch = existingContent.match(/GAL_RULES_VERSION = "([^"]+)"/);
+      if (versionMatch && versionMatch[1] === RULES_VERSION) {
+        needsUpdate = false;
+      }
+    }
+
+    // Write the rules file if needed
+    if (needsUpdate) {
+      fs.writeFileSync(rulesPath, GAL_CLI_RULES_CONTENT, 'utf-8');
+      console.log('✓ GAL CLI rules installed');
+    }
+
+    return true;
+  } catch (error) {
+    // Silent fail - rules are optional enhancement
+    return false;
+  }
+}
+
+/**
+ * Queue a telemetry event for the next CLI run (GAL-114)
+ * Since postinstall is CommonJS and telemetry module is ESM,
+ * we write events to a pending file that the CLI picks up on startup
+ */
+function queueTelemetryEvent() {
+  const pendingEventsPath = path.join(os.homedir(), '.gal', 'telemetry-pending-events.json');
+  const galDir = path.join(os.homedir(), '.gal');
+
+  let pending = [];
+  try {
+    if (fs.existsSync(pendingEventsPath)) {
+      pending = JSON.parse(fs.readFileSync(pendingEventsPath, 'utf-8'));
+    }
+  } catch {}
+
+  // Add postinstall hook event
+  pending.push({
+    id: require('crypto').randomUUID(),
+    eventType: 'hook_triggered',
+    timestamp: new Date().toISOString(),
+    payload: {
+      notificationType: 'postinstall',
+      cliVersion: CLI_VERSION,
+      platform: process.platform,
+      nodeVersion: process.version,
+    },
+    queuedAt: Date.now(),
+  });
+
+  try {
+    if (!fs.existsSync(galDir)) {
+      fs.mkdirSync(galDir, { recursive: true });
+    }
+    fs.writeFileSync(pendingEventsPath, JSON.stringify(pending), 'utf-8');
+  } catch {
+    // Ignore errors - telemetry is optional
+  }
+}
+
+/**
+ * Install the status line script to ~/.claude/status_lines/
+ *
+ * Key behaviors:
+ * - Idempotent: Checks version before writing
+ * - Won't overwrite user's custom statusLine
+ * - Registers in settings.json
+ */
+function installStatusLine() {
+  const claudeDir = path.join(os.homedir(), '.claude');
+  const statusLinesDir = path.join(claudeDir, 'status_lines');
+  const scriptPath = path.join(statusLinesDir, 'gal-sync-status.py');
+  const settingsPath = path.join(claudeDir, 'settings.json');
+
+  try {
+    // Check existing settings for custom statusLine
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+      try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+      } catch {
+        settings = {};
+      }
+    }
+
+    // Don't overwrite user's custom statusLine
+    if (settings.statusLine?.command && !settings.statusLine.command.includes('gal-sync-status')) {
+      console.log('ℹ Custom statusLine detected, skipping GAL status line');
+      return false;
+    }
+
+    // Create directories if needed
+    if (!fs.existsSync(statusLinesDir)) {
+      fs.mkdirSync(statusLinesDir, { recursive: true });
+    }
+
+    // Check if script already exists with current version
+    let needsUpdate = true;
+    if (fs.existsSync(scriptPath)) {
+      const existingContent = fs.readFileSync(scriptPath, 'utf-8');
+      const versionMatch = existingContent.match(/GAL_STATUS_LINE_VERSION = "([^"]+)"/);
+      if (versionMatch && versionMatch[1] === STATUS_LINE_VERSION) {
+        // Also check if it's registered in settings
+        if (settings.statusLine?.command?.includes('gal-sync-status')) {
+          needsUpdate = false;
+        }
+      }
+    }
+
+    // Write the script file if needed
+    if (needsUpdate) {
+      fs.writeFileSync(scriptPath, STATUS_LINE_CONTENT, 'utf-8');
+      fs.chmodSync(scriptPath, '755');
+
+      // Register in settings.json
+      settings.statusLine = {
+        type: 'command',
+        command: scriptPath
+      };
+
+      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
+      console.log('✓ GAL status line installed');
+    }
+
+    return true;
+  } catch (error) {
+    // Silent fail - status line is optional enhancement
+    return false;
+  }
+}
+
+// =============================================================================
+// Main
+// =============================================================================
+
+function main() {
+  const hookInstalled = installHook();
+  const rulesInstalled = installRules();
+  const statusLineInstalled = installStatusLine();
+
+  // Queue telemetry event (GAL-114)
+  queueTelemetryEvent();
+
+  if (hookInstalled || rulesInstalled || statusLineInstalled) {
+    console.log('');
+    console.log('Restart Claude Code/Cursor for changes to take effect.');
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. gal auth login     - Authenticate with GitHub');
+    console.log('  2. gal sync --pull    - Download org-approved config');
+    console.log('');
+  }
+}
+
+main();