@scheduler-systems/gal-run 0.0.197

package/scripts/postinstall.cjs

@@ -0,0 +1,891 @@
+#!/usr/bin/env node
+/**
+ * GAL CLI Postinstall Script
+ *
+ * Automatically installs Claude Code integrations when GAL CLI is installed via pnpm.
+ * This script runs as a pnpm lifecycle hook after package installation completes.
+ *
+ * What it installs:
+ * 1. SessionStart hook → ~/.claude/hooks/gal-sync-reminder.js
+ *    - Shows sync status at the start of each Claude session
+ *    - Prompts user to login/sync if needed
+ * 2. Status line script → ~/.claude/status_lines/gal-sync-status.py
+ *    - Displays sync warnings in Claude's status bar (when not synced)
+ * 3. GAL CLI rules → ~/.claude/rules/gal-cli.md
+ *    - Provides persistent GAL CLI awareness to Claude Code
+ *
+ * Scope:
+ * - These are CLI-level integrations (user-wide, not project-specific)
+ * - Org-specific configs are handled by `gal sync --pull`
+ *
+ * Key behaviors:
+ * - Idempotent: Safe to run multiple times, only updates when versions change
+ * - Version-aware: Checks version markers before overwriting files
+ * - Self-cleaning: Installed scripts remove themselves if GAL CLI is uninstalled
+ * - Non-destructive: Won't overwrite user's custom configs (e.g., custom statusLine)
+ * - Telemetry: Queues installation event for next CLI run (GAL-114)
+ *
+ * When it runs:
+ * - Automatically during `pnpm add -g @scheduler-systems/gal-run`
+ * - Can be manually triggered via `pnpm run postinstall` in the CLI package directory
+ *
+ * Prerequisites:
+ * - Node.js 18+ (CommonJS module)
+ * - Writable ~/.claude directory
+ *
+ * Related files:
+ * - apps/cli/scripts/preuninstall.cjs - Cleanup script (runs before uninstall)
+ * - apps/cli/package.json - pnpm lifecycle hooks configuration
+ *
+ * @see specs/gal-cli/installation.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// =============================================================================
+// Version Configuration
+// =============================================================================
+// Version markers control when files get updated.
+// Bump these when file contents change to trigger reinstallation.
+
+// Get current CLI version from package.json
+const cliPackageJson = require('../package.json');
+const CLI_VERSION = cliPackageJson.version;
+
+// Version markers for idempotency checks
+// Bump these to force updates to installed files
+const HOOK_VERSION = '4.0.0'; // SessionStart hook (4.0.0: Background cache refresh + sync)
+const STATUS_LINE_VERSION = '1.0.0'; // Status line script
+const RULES_VERSION = '1.0.0'; // GAL CLI rules
+
+// =============================================================================
+// GAL CLI Rules Content
+// =============================================================================
+// Injected into ~/.claude/rules/gal-cli.md
+// Provides persistent GAL CLI awareness to Claude without hook overhead.
+// Claude automatically loads rules from ~/.claude/rules/ at session start.
+// =============================================================================
+
+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 notification at Claude session start.
+// Appears once at the top of the chat window and stays visible.
+// For continuous status updates, see the status line script below.
+// =============================================================================
+
+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, spawn } = 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)
+// =============================================================================
+// Hook runs in Claude context (no network access), so we queue telemetry events
+// in a JSON file that the CLI reads and flushes on next run. This allows us to
+// track hook executions without blocking the user or requiring network calls.
+// =============================================================================
+
+/**
+ * Queue a telemetry event for the next CLI run.
+ *
+ * Since hooks run synchronously in Claude's context, we can't send telemetry
+ * directly. Instead, we write events to a pending queue file that the CLI
+ * reads and flushes on its next execution.
+ *
+ * @param {string} status - Sync status from the hook (auth_required, synced, etc.)
+ */
+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; }
+}
+
+// =============================================================================
+// Auto-update check: run gal update if a newer version is cached
+// =============================================================================
+function checkAndAutoUpdate() {
+  const updateCachePath = path.join(os.homedir(), '.gal', 'update-cache.json');
+  if (!fs.existsSync(updateCachePath)) return null;
+  try {
+    const cache = JSON.parse(fs.readFileSync(updateCachePath, 'utf-8'));
+    if (!cache.latestVersion) return null;
+    let currentVersion;
+    try {
+      currentVersion = execSync('gal --version', { stdio: 'pipe', timeout: 5000 }).toString().trim();
+    } catch { return null; }
+    const cv = currentVersion.replace(/^v/, '').split('.').map(Number);
+    const lv = cache.latestVersion.replace(/^v/, '').split('.').map(Number);
+    let needsUpdate = false;
+    for (let i = 0; i < 3; i++) {
+      if ((cv[i] || 0) < (lv[i] || 0)) { needsUpdate = true; break; }
+      if ((cv[i] || 0) > (lv[i] || 0)) break;
+    }
+    if (!needsUpdate) return null;
+    if (process.env.GAL_NO_AUTO_UPDATE === '1' || process.env.CI) return null;
+    try {
+      execSync('gal update', { stdio: 'pipe', timeout: 30000 });
+      return cache.latestVersion;
+    } catch { return null; }
+  } catch { return null; }
+}
+
+// Refresh update cache in background if stale (>24h)
+function refreshUpdateCacheIfStale() {
+  try {
+    const updateCachePath = path.join(os.homedir(), '.gal', 'update-cache.json');
+    let needsRefresh = true;
+    if (fs.existsSync(updateCachePath)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(updateCachePath, 'utf-8'));
+        if (cache.lastCheck && (Date.now() - cache.lastCheck) < 24 * 60 * 60 * 1000) {
+          needsRefresh = false;
+        }
+      } catch {}
+    }
+    if (needsRefresh) {
+      const child = spawn('gal', ['update', '--check'], {
+        stdio: 'ignore',
+        detached: true,
+      });
+      child.unref();
+    }
+  } catch {}
+}
+
+const updatedVersion = checkAndAutoUpdate();
+refreshUpdateCacheIfStale();
+
+// 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; }
+}
+
+let state = readSyncState();
+
+if (!state) {
+  // Attempt auto-sync
+  try {
+    execSync('gal sync --pull --auto', { stdio: 'pipe', timeout: 30000 });
+    state = readSyncState();
+  } catch {}
+
+  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 && state.lastSyncHash !== state.approvedConfigHash) {
+  // Attempt auto-sync for outdated configs
+  try {
+    execSync('gal sync --pull --auto', { stdio: 'pipe', timeout: 30000 });
+    state = readSyncState();
+  } catch {}
+
+  if (state && 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 && 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 - build synced status message with optional dispatch rules
+if (!state) {
+  showMessage("✅ GAL: Ready", 'synced');
+}
+
+let syncMessage = \`✅ GAL: Synced with \${state.organization}'s approved config (v\${state.version || 'latest'})\`;
+
+if (updatedVersion) {
+  syncMessage = \`🔄 GAL: Updated to v\${updatedVersion}. \` + syncMessage;
+}
+
+// Inject dispatch rules summary if available
+try {
+  const dispatchPath = path.join(process.cwd(), '.gal', 'dispatch-rules.json');
+  if (fs.existsSync(dispatchPath)) {
+    const rules = JSON.parse(fs.readFileSync(dispatchPath, 'utf-8'));
+    if (rules.enabled && rules.categories) {
+      const eligible = rules.categories.filter(c => c.enabled).map(c => c.name);
+      const local = rules.categories.filter(c => !c.enabled).map(c => c.name);
+      if (eligible.length > 0) {
+        syncMessage += \`\\n📋 Background dispatch: \${eligible.join(', ')} → use \\\`gal dispatch\\\`. \${local.length > 0 ? local.join(', ') + ' → keep local.' : ''}\`;
+      }
+    }
+  }
+} catch {
+  // Dispatch rules are optional - ignore errors
+}
+
+showMessage(syncMessage, 'synced');
+`;
+
+// =============================================================================
+// Status Line Script Content
+// =============================================================================
+// Python script that runs continuously in Claude's status bar.
+// Shows warnings when not synced, silent when synced (avoids status bar spam).
+// Uses uv's inline script runner for dependency management.
+// =============================================================================
+
+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
+// =============================================================================
+
+// =============================================================================
+// Installation Functions - SessionStart Hook
+// =============================================================================
+
+/**
+ * Install the SessionStart hook to ~/.claude/hooks/gal-sync-reminder.js
+ *
+ * The hook shows sync status at the start of each Claude session, prompting
+ * users to login or sync if needed. It checks:
+ * 1. Authentication status (GAL CLI login)
+ * 2. Project sync state (gal sync --pull)
+ * 3. Config staleness (hash mismatch)
+ * 4. Missing synced files
+ *
+ * Key behaviors:
+ * - Idempotent: Checks HOOK_VERSION marker before writing
+ * - Migration: Cleans up old UserPromptSubmit hooks (v1.x used those)
+ * - Registration: Adds hook to ~/.claude/settings.json
+ * - Self-cleaning: Hook removes itself if GAL CLI is uninstalled
+ *
+ * @returns {boolean} True if hook was installed or updated, false on error
+ */
+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 (v1.x migration)
+    // GAL CLI v1.x used UserPromptSubmit hooks, but they caused performance issues
+    // by running on every user message. v2.x uses SessionStart hooks instead.
+    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;
+  }
+}
+
+// =============================================================================
+// Installation Functions - GAL CLI Rules
+// =============================================================================
+
+/**
+ * Install GAL CLI rules to ~/.claude/rules/gal-cli.md
+ *
+ * Rules provide persistent awareness of GAL CLI commands without hook overhead.
+ * Claude automatically loads rules from ~/.claude/rules/ at session start,
+ * so the AI knows about `gal` commands and can suggest their usage.
+ *
+ * Key behaviors:
+ * - Idempotent: Checks RULES_VERSION marker before writing
+ * - Lightweight: No runtime overhead (unlike hooks that execute on events)
+ * - Persistent: Remains loaded for entire Claude session
+ *
+ * @returns {boolean} True if rules were installed or updated, false on error
+ */
+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;
+  }
+}
+
+// =============================================================================
+// Installation Functions - Telemetry Queue
+// =============================================================================
+
+/**
+ * Queue a telemetry event for the next CLI run (GAL-114)
+ *
+ * This postinstall script is CommonJS, but the telemetry module is ESM,
+ * so we can't import it directly. Instead, we write events to a pending
+ * file (~/.gal/telemetry-pending-events.json) that the CLI picks up and
+ * flushes on its next execution.
+ *
+ * Events are structured as:
+ * - id: Unique event identifier (UUID)
+ * - eventType: 'hook_triggered' for installation
+ * - timestamp: ISO 8601 timestamp
+ * - payload: Event-specific data (cliVersion, platform, nodeVersion)
+ * - queuedAt: Unix timestamp when event was queued
+ *
+ * @returns {void}
+ */
+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
+  }
+}
+
+// =============================================================================
+// Installation Functions - Status Line Script
+// =============================================================================
+
+/**
+ * Install the status line script to ~/.claude/status_lines/gal-sync-status.py
+ *
+ * The status line script runs continuously in Claude's status bar, showing
+ * sync warnings when the project is not synced with the org's approved config.
+ * Silent when synced (avoids status bar spam).
+ *
+ * Key behaviors:
+ * - Idempotent: Checks STATUS_LINE_VERSION marker before writing
+ * - Respectful: Won't overwrite user's existing custom statusLine
+ * - Registration: Adds to ~/.claude/settings.json statusLine field
+ * - Self-cleaning: Script removes itself if GAL CLI is uninstalled
+ *
+ * @returns {boolean} True if status line was installed or updated, false on error
+ */
+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 (respect user's existing config)
+    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();