gsd-update-banner.js

#!/usr/bin/env node
// gsd-hook-version: {{GSD_VERSION}}
// SessionStart banner that surfaces GSD update availability when GSD's
// statusline isn't installed. Reads the cache that
// gsd-check-update-worker.js writes to ~/.cache/gsd/gsd-update-check.json.
//
// Opt-in by design: bin/install.js only registers this hook when the user
// declines to install (or replace) the GSD statusline. The presence of the
// SessionStart entry IS the opt-in — there is no separate runtime flag.
//
// See issue #2795 for the rationale.

'use strict';

const fs = require('fs');
const path = require('path');
const os = require('os');

// Suppress repeat parse-error banners for 24 hours so a genuinely broken
// cache file doesn't nag the user every session.
const RATE_LIMIT_SECONDS = 24 * 60 * 60;

/**
 * Build the SessionStart JSON envelope to emit, given parsed cache state.
 * Pure function — no I/O. Returns null when the hook should print nothing.
 *
 * @param {object} state
 * @param {object|null} state.cache                  Parsed cache, or null if missing/unreadable.
 * @param {boolean}     state.parseError             True iff cache file existed but JSON.parse failed.
…