@amiable-dev/docusaurus-plugin-stentorosaur 0.16.4 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amiable-dev/docusaurus-plugin-stentorosaur",
-  "version": "0.16.4",
+  "version": "0.18.0",
   "description": "A Docusaurus plugin for displaying status monitoring dashboard powered by GitHub Issues and Actions, similar to Upptime",
   "main": "lib/index.js",
   "types": "src/plugin-status.d.ts",
@@ -10,8 +10,17 @@
     "stentorosaur-notify": "scripts/notify.js",
     "stentorosaur-setup-status-branch": "scripts/setup-status-branch.js",
     "stentorosaur-migrate-to-status-branch": "scripts/migrate-to-status-branch.js",
-    "stentorosaur-cleanup-status-branch": "scripts/cleanup-status-branch.js"
+    "stentorosaur-cleanup-status-branch": "scripts/cleanup-status-branch.js",
+    "stentorosaur-bootstrap-summary": "scripts/bootstrap-summary.js",
+    "stentorosaur-init": "scripts/init.js",
+    "stentorosaur-config": "scripts/config.js"
   },
+  "files": [
+    "lib",
+    "scripts",
+    "templates",
+    "src/plugin-status.d.ts"
+  ],
   "keywords": [
     "docusaurus",
     "plugin",

package/scripts/bootstrap-summary.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+
+/**
+ * Bootstrap script to generate initial daily-summary.json from existing archives
+ *
+ * This script is typically run once when upgrading to a version that supports
+ * historical data aggregation (ADR-002). It reads all existing archive files
+ * and generates the initial daily-summary.json.
+ *
+ * Usage:
+ *   node scripts/bootstrap-summary.js --output-dir status-data
+ *   node scripts/bootstrap-summary.js --output-dir status-data --window 90
+ *
+ * Options:
+ *   --output-dir <path>  Output directory containing archives/ (default: status-data)
+ *   --window <days>      Number of days to aggregate (default: 90)
+ *   --verbose            Enable verbose logging
+ */
+
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const options = {
+  outputDir: 'status-data',
+  windowDays: 90,
+  verbose: false,
+};
+
+for (let i = 0; i < args.length; i++) {
+  switch (args[i]) {
+    case '--output-dir':
+      options.outputDir = args[++i];
+      break;
+    case '--window':
+      options.windowDays = parseInt(args[++i]);
+      break;
+    case '--verbose':
+      options.verbose = true;
+      break;
+  }
+}
+
+function log(...msg) {
+  console.log('[bootstrap-summary]', ...msg);
+}
+
+function verbose(...msg) {
+  if (options.verbose) {
+    console.log('[bootstrap-summary:verbose]', ...msg);
+  }
+}
+
+/**
+ * Calculate p95 latency from an array of latency values
+ */
+function calculateP95(latencies) {
+  if (latencies.length === 0) return null;
+  const sorted = [...latencies].sort((a, b) => a - b);
+  const index = Math.ceil(sorted.length * 0.95) - 1;
+  return sorted[Math.max(0, index)];
+}
+
+/**
+ * Aggregate readings for a specific day into a DailySummaryEntry
+ */
+function aggregateDayReadings(date, readings) {
+  const checksTotal = readings.length;
+  const checksPassed = readings.filter(r => r.state === 'up' || r.state === 'maintenance').length;
+  const uptimePct = checksTotal > 0 ? checksPassed / checksTotal : 0;
+
+  const latencies = readings
+    .filter(r => r.state === 'up')
+    .map(r => r.lat);
+
+  const avgLatencyMs = latencies.length > 0
+    ? Math.round(latencies.reduce((sum, lat) => sum + lat, 0) / latencies.length)
+    : null;
+
+  const p95LatencyMs = calculateP95(latencies);
+
+  // Count incidents (transitions from up to down)
+  let incidentCount = 0;
+  for (let i = 1; i < readings.length; i++) {
+    if (readings[i - 1].state === 'up' && readings[i].state === 'down') {
+      incidentCount++;
+    }
+  }
+
+  return {
+    date,
+    uptimePct,
+    avgLatencyMs,
+    p95LatencyMs,
+    checksTotal,
+    checksPassed,
+    incidentCount,
+  };
+}
+
+/**
+ * Generate daily-summary.json from existing archives
+ */
+function generateDailySummary(archivesDir, outputDir, windowDays) {
+  const now = new Date();
+
+  // Group all readings by service and date
+  const serviceReadings = new Map();
+
+  // Collect from last N days
+  for (let d = 0; d < windowDays; d++) {
+    const date = new Date(now.getTime() - d * 24 * 60 * 60 * 1000);
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    const dateKey = `${year}-${month}-${day}`;
+
+    const dir = path.join(archivesDir, String(year), month);
+    const plainFile = path.join(dir, `history-${year}-${month}-${day}.jsonl`);
+    const gzFile = path.join(dir, `history-${year}-${month}-${day}.jsonl.gz`);
+
+    let content = null;
+
+    // Try plain file first
+    if (fs.existsSync(plainFile)) {
+      try {
+        content = fs.readFileSync(plainFile, 'utf8');
+        verbose(`Read ${plainFile}`);
+      } catch (err) {
+        verbose(`Failed to read ${plainFile}:`, err.message);
+      }
+    }
+    // Try gzipped file
+    else if (fs.existsSync(gzFile)) {
+      try {
+        const compressed = fs.readFileSync(gzFile);
+        content = zlib.gunzipSync(compressed).toString('utf8');
+        verbose(`Read ${gzFile}`);
+      } catch (err) {
+        verbose(`Failed to decompress ${gzFile}:`, err.message);
+      }
+    }
+
+    // Parse and group by service
+    if (content) {
+      const lines = content.trim().split('\n').filter(line => line.trim());
+
+      for (const line of lines) {
+        try {
+          const obj = JSON.parse(line);
+          const svc = obj.svc;
+
+          if (!serviceReadings.has(svc)) {
+            serviceReadings.set(svc, new Map());
+          }
+
+          const svcMap = serviceReadings.get(svc);
+          if (!svcMap.has(dateKey)) {
+            svcMap.set(dateKey, []);
+          }
+          svcMap.get(dateKey).push(obj);
+        } catch (err) {
+          verbose('Failed to parse line:', line);
+        }
+      }
+    }
+  }
+
+  // Aggregate each service's daily data
+  const services = {};
+  let totalDays = 0;
+
+  for (const [svc, dateMap] of serviceReadings.entries()) {
+    const entries = [];
+
+    // Sort dates in reverse chronological order (most recent first)
+    const sortedDates = [...dateMap.keys()].sort().reverse();
+    totalDays = Math.max(totalDays, sortedDates.length);
+
+    for (const dateKey of sortedDates) {
+      const readings = dateMap.get(dateKey);
+      // Sort readings by timestamp for accurate incident counting
+      readings.sort((a, b) => a.t - b.t);
+
+      const entry = aggregateDayReadings(dateKey, readings);
+      entries.push(entry);
+    }
+
+    services[svc] = entries;
+  }
+
+  // Build the daily summary file (ADR-002 schema v1)
+  const summary = {
+    version: 1,
+    lastUpdated: now.toISOString(),
+    windowDays,
+    services,
+  };
+
+  // Atomic write: temp file → rename
+  const summaryPath = path.join(outputDir, 'daily-summary.json');
+  const tempPath = path.join(outputDir, 'daily-summary.tmp');
+
+  fs.writeFileSync(tempPath, JSON.stringify(summary, null, 2));
+  fs.renameSync(tempPath, summaryPath);
+
+  return { summary, totalDays };
+}
+
+// Main execution
+function main() {
+  try {
+    const archivesDir = path.join(options.outputDir, 'archives');
+
+    if (!fs.existsSync(archivesDir)) {
+      console.error(`Error: Archives directory not found: ${archivesDir}`);
+      console.error('Make sure --output-dir points to the correct status data directory.');
+      process.exit(1);
+    }
+
+    log(`Generating daily-summary.json from ${archivesDir}...`);
+    log(`Window: ${options.windowDays} days`);
+
+    const { summary, totalDays } = generateDailySummary(
+      archivesDir,
+      options.outputDir,
+      options.windowDays
+    );
+
+    const serviceCount = Object.keys(summary.services).length;
+    log(`\nGenerated daily-summary.json:`);
+    log(`  Services: ${serviceCount}`);
+    log(`  Days with data: ${totalDays}`);
+    log(`  Window: ${options.windowDays} days`);
+    log(`  Output: ${path.join(options.outputDir, 'daily-summary.json')}`);
+
+    if (serviceCount === 0) {
+      log('\nWarning: No data found. Make sure archives contain JSONL files.');
+    }
+
+  } catch (error) {
+    console.error('Error:', error.message);
+    if (options.verbose) {
+      console.error(error);
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/config.js

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+
+/**
+ * Stentorosaur configuration management CLI
+ * Manages .monitorrc.json and docusaurus.config plugin options
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+const CONFIG_FILE = '.monitorrc.json';
+const ENTITIES_FILE = '.stentorosaur-entities.json';
+
+// Parse command line arguments
+function parseArgs(args) {
+  const result = { command: args[0], options: {} };
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith('--')) {
+        result.options[key] = nextArg;
+        i++;
+      } else {
+        result.options[key] = true;
+      }
+    }
+  }
+
+  return result;
+}
+
+// Load monitor config
+async function loadConfig() {
+  const configPath = path.join(process.cwd(), CONFIG_FILE);
+
+  if (!await fs.pathExists(configPath)) {
+    return {
+      "$schema": "https://json-schema.org/draft-07/schema#",
+      "description": "Configuration file for status monitoring script",
+      "systems": []
+    };
+  }
+
+  return await fs.readJson(configPath);
+}
+
+// Save monitor config
+async function saveConfig(config) {
+  const configPath = path.join(process.cwd(), CONFIG_FILE);
+  await fs.writeJson(configPath, config, { spaces: 2 });
+}
+
+// Load entities config (for processes and additional metadata)
+async function loadEntities() {
+  const entitiesPath = path.join(process.cwd(), ENTITIES_FILE);
+
+  if (!await fs.pathExists(entitiesPath)) {
+    return { systems: [], processes: [] };
+  }
+
+  return await fs.readJson(entitiesPath);
+}
+
+// Save entities config
+async function saveEntities(entities) {
+  const entitiesPath = path.join(process.cwd(), ENTITIES_FILE);
+  await fs.writeJson(entitiesPath, entities, { spaces: 2 });
+}
+
+// Add a system to monitor
+async function addSystem(options) {
+  const name = options.name;
+  const url = options.url;
+  const method = options.method || 'GET';
+  const timeout = options.timeout || '10000';
+  const expectedCodes = options['expected-codes'] || '200';
+
+  if (!name || !url) {
+    console.error('\x1b[31mError:\x1b[0m Both --name and --url are required');
+    console.log('\nUsage: stentorosaur-config add-system --name api --url https://api.example.com/health');
+    process.exit(1);
+  }
+
+  const config = await loadConfig();
+
+  // Check if system already exists
+  const existingIndex = config.systems.findIndex(s => s.system === name);
+
+  const newSystem = {
+    system: name,
+    url: url,
+    method: method.toUpperCase(),
+    timeout: parseInt(timeout, 10),
+    expectedCodes: expectedCodes.split(',').map(c => parseInt(c.trim(), 10)),
+    maxResponseTime: 30000
+  };
+
+  if (existingIndex >= 0) {
+    config.systems[existingIndex] = newSystem;
+    console.log(`\x1b[33mUpdated:\x1b[0m System '${name}' configuration updated`);
+  } else {
+    config.systems.push(newSystem);
+    console.log(`\x1b[32mAdded:\x1b[0m System '${name}' added to ${CONFIG_FILE}`);
+  }
+
+  await saveConfig(config);
+
+  // Also add to entities for docusaurus config reference
+  const entities = await loadEntities();
+  if (!entities.systems.find(s => s.name === name)) {
+    entities.systems.push({ name, type: 'system', url });
+    await saveEntities(entities);
+  }
+
+  console.log(`\n  URL: ${url}`);
+  console.log(`  Method: ${method.toUpperCase()}`);
+  console.log(`  Timeout: ${timeout}ms`);
+  console.log(`  Expected codes: ${expectedCodes}`);
+}
+
+// Add a business process
+async function addProcess(options) {
+  const name = options.name;
+  const description = options.description || '';
+
+  if (!name) {
+    console.error('\x1b[31mError:\x1b[0m --name is required');
+    console.log('\nUsage: stentorosaur-config add-process --name deployments --description "Deployment pipeline"');
+    process.exit(1);
+  }
+
+  const entities = await loadEntities();
+
+  // Check if process already exists
+  const existingIndex = entities.processes.findIndex(p => p.name === name);
+
+  const newProcess = {
+    name,
+    type: 'process',
+    description: description || `${name} process tracking`
+  };
+
+  if (existingIndex >= 0) {
+    entities.processes[existingIndex] = newProcess;
+    console.log(`\x1b[33mUpdated:\x1b[0m Process '${name}' configuration updated`);
+  } else {
+    entities.processes.push(newProcess);
+    console.log(`\x1b[32mAdded:\x1b[0m Process '${name}' added to ${ENTITIES_FILE}`);
+  }
+
+  await saveEntities(entities);
+
+  console.log(`\n  Description: ${newProcess.description}`);
+  console.log(`\n\x1b[33mNote:\x1b[0m Add 'process:${name}' label to GitHub Issues to track this process.`);
+}
+
+// Remove a system
+async function removeSystem(options) {
+  const name = options.name;
+
+  if (!name) {
+    console.error('\x1b[31mError:\x1b[0m --name is required');
+    console.log('\nUsage: stentorosaur-config remove-system --name api');
+    process.exit(1);
+  }
+
+  const config = await loadConfig();
+  const originalLength = config.systems.length;
+  config.systems = config.systems.filter(s => s.system !== name);
+
+  if (config.systems.length === originalLength) {
+    console.log(`\x1b[33mWarning:\x1b[0m System '${name}' not found in ${CONFIG_FILE}`);
+  } else {
+    await saveConfig(config);
+    console.log(`\x1b[32mRemoved:\x1b[0m System '${name}' from ${CONFIG_FILE}`);
+  }
+
+  // Also remove from entities
+  const entities = await loadEntities();
+  entities.systems = entities.systems.filter(s => s.name !== name);
+  await saveEntities(entities);
+}
+
+// List all configured systems and processes
+async function list() {
+  const config = await loadConfig();
+  const entities = await loadEntities();
+
+  console.log('\n\x1b[32mMonitored Systems:\x1b[0m');
+  console.log('─'.repeat(60));
+
+  if (config.systems.length === 0) {
+    console.log('  No systems configured');
+    console.log('  Run: make status-add-system name=api url=https://...');
+  } else {
+    for (const system of config.systems) {
+      console.log(`\n  \x1b[36m${system.system}\x1b[0m`);
+      console.log(`    URL: ${system.url}`);
+      console.log(`    Method: ${system.method}`);
+      console.log(`    Timeout: ${system.timeout}ms`);
+      console.log(`    Expected: ${system.expectedCodes.join(', ')}`);
+    }
+  }
+
+  console.log('\n\n\x1b[32mBusiness Processes:\x1b[0m');
+  console.log('─'.repeat(60));
+
+  if (!entities.processes || entities.processes.length === 0) {
+    console.log('  No processes configured');
+    console.log('  Run: make status-add-process name=deployments');
+  } else {
+    for (const process of entities.processes) {
+      console.log(`\n  \x1b[36m${process.name}\x1b[0m`);
+      console.log(`    Label: process:${process.name}`);
+      if (process.description) {
+        console.log(`    Description: ${process.description}`);
+      }
+    }
+  }
+
+  console.log('\n');
+}
+
+// Validate configuration
+async function validate() {
+  const configPath = path.join(process.cwd(), CONFIG_FILE);
+
+  if (!await fs.pathExists(configPath)) {
+    console.error(`\x1b[31mError:\x1b[0m ${CONFIG_FILE} not found`);
+    console.log('Run: make status-init');
+    process.exit(1);
+  }
+
+  try {
+    const config = await fs.readJson(configPath);
+
+    const errors = [];
+    const warnings = [];
+
+    if (!config.systems || !Array.isArray(config.systems)) {
+      errors.push('Missing or invalid "systems" array');
+    } else {
+      for (let i = 0; i < config.systems.length; i++) {
+        const system = config.systems[i];
+
+        if (!system.system) {
+          errors.push(`System ${i + 1}: Missing "system" name`);
+        }
+        if (!system.url) {
+          errors.push(`System ${i + 1}: Missing "url"`);
+        } else {
+          try {
+            new URL(system.url);
+          } catch {
+            errors.push(`System ${i + 1}: Invalid URL "${system.url}"`);
+          }
+        }
+        if (system.timeout && (typeof system.timeout !== 'number' || system.timeout < 0)) {
+          warnings.push(`System ${i + 1}: Invalid timeout value`);
+        }
+      }
+    }
+
+    if (errors.length > 0) {
+      console.log('\x1b[31mValidation failed:\x1b[0m\n');
+      errors.forEach(e => console.log(`  - ${e}`));
+      process.exit(1);
+    }
+
+    if (warnings.length > 0) {
+      console.log('\x1b[33mWarnings:\x1b[0m\n');
+      warnings.forEach(w => console.log(`  - ${w}`));
+    }
+
+    console.log(`\x1b[32mConfiguration valid!\x1b[0m`);
+    console.log(`  ${config.systems.length} system(s) configured`);
+
+  } catch (err) {
+    console.error(`\x1b[31mError:\x1b[0m Failed to parse ${CONFIG_FILE}`);
+    console.error(err.message);
+    process.exit(1);
+  }
+}
+
+// Generate docusaurus config snippet
+async function generateConfig() {
+  const entities = await loadEntities();
+
+  const allEntities = [
+    ...entities.systems.map(s => ({ name: s.name, type: 'system' })),
+    ...entities.processes.map(p => ({ name: p.name, type: 'process' }))
+  ];
+
+  console.log('\n\x1b[32mDocusaurus Config Snippet:\x1b[0m');
+  console.log('─'.repeat(60));
+  console.log(`
+// Add to docusaurus.config.js plugins array:
+[
+  '@amiable-dev/docusaurus-plugin-stentorosaur',
+  {
+    owner: 'your-org',
+    repo: 'your-repo',
+    entities: ${JSON.stringify(allEntities, null, 6).replace(/\n/g, '\n    ')},
+  },
+],
+`);
+}
+
+// Main CLI
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.log('Stentorosaur Configuration Manager\n');
+    console.log('Commands:');
+    console.log('  add-system     Add a system to monitor');
+    console.log('  add-process    Add a business process');
+    console.log('  remove-system  Remove a system');
+    console.log('  list           List all configured systems and processes');
+    console.log('  validate       Validate configuration files');
+    console.log('  generate       Generate docusaurus.config.js snippet');
+    console.log('\nRun with --help for more info');
+    process.exit(0);
+  }
+
+  const { command, options } = parseArgs(args);
+
+  switch (command) {
+    case 'add-system':
+      await addSystem(options);
+      break;
+    case 'add-process':
+      await addProcess(options);
+      break;
+    case 'remove-system':
+      await removeSystem(options);
+      break;
+    case 'list':
+      await list();
+      break;
+    case 'validate':
+      await validate();
+      break;
+    case 'generate':
+      await generateConfig();
+      break;
+    default:
+      console.error(`\x1b[31mError:\x1b[0m Unknown command '${command}'`);
+      process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error('\x1b[31mError:\x1b[0m', err.message);
+  process.exit(1);
+});

package/scripts/init.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+/**
+ * Initialize Stentorosaur status monitoring in a consuming project
+ * Creates .monitorrc.json and status-data directory
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+const CONFIG_FILE = '.monitorrc.json';
+const STATUS_DATA_DIR = 'status-data';
+
+const DEFAULT_CONFIG = {
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "description": "Configuration file for status monitoring script",
+  "systems": []
+};
+
+async function init() {
+  const cwd = process.cwd();
+  const configPath = path.join(cwd, CONFIG_FILE);
+  const statusDataPath = path.join(cwd, STATUS_DATA_DIR);
+
+  console.log('Initializing Stentorosaur status monitoring...\n');
+
+  // Create .monitorrc.json if it doesn't exist
+  if (await fs.pathExists(configPath)) {
+    console.log(`\x1b[33mWarning:\x1b[0m ${CONFIG_FILE} already exists. Skipping...`);
+  } else {
+    await fs.writeJson(configPath, DEFAULT_CONFIG, { spaces: 2 });
+    console.log(`\x1b[32mCreated:\x1b[0m ${CONFIG_FILE}`);
+  }
+
+  // Create status-data directory
+  await fs.ensureDir(statusDataPath);
+  console.log(`\x1b[32mCreated:\x1b[0m ${STATUS_DATA_DIR}/`);
+
+  // Create .gitkeep in status-data
+  const gitkeepPath = path.join(statusDataPath, '.gitkeep');
+  if (!await fs.pathExists(gitkeepPath)) {
+    await fs.writeFile(gitkeepPath, '');
+  }
+
+  console.log('\n\x1b[32mStatus monitoring initialized!\x1b[0m\n');
+  console.log('Next steps:');
+  console.log('  1. Add systems to monitor:');
+  console.log('     make status-add-system name=api url=https://api.example.com/health\n');
+  console.log('  2. Copy GitHub Actions workflows:');
+  console.log('     make status-workflows\n');
+  console.log('  3. Test your configuration:');
+  console.log('     make status-test\n');
+}
+
+init().catch(err => {
+  console.error('\x1b[31mError:\x1b[0m', err.message);
+  process.exit(1);
+});