@girardmedia/bootspring 1.1.0

package/core/telemetry.js

@@ -0,0 +1,247 @@
+/**
+ * Bootspring Telemetry
+ * Lightweight JSONL event emitter for product instrumentation.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const MAX_EVENTS_LIMIT = 10000;
+
+function getTelemetryDir(projectRoot = process.cwd()) {
+  return path.join(projectRoot, '.bootspring', 'telemetry');
+}
+
+function getTelemetryFile(projectRoot = process.cwd()) {
+  return path.join(getTelemetryDir(projectRoot), 'events.jsonl');
+}
+
+function ensureTelemetryDir(projectRoot = process.cwd()) {
+  const dir = getTelemetryDir(projectRoot);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function emitEvent(event, payload = {}, options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  ensureTelemetryDir(projectRoot);
+  const file = getTelemetryFile(projectRoot);
+  const record = {
+    timestamp: new Date().toISOString(),
+    event: String(event || '').trim(),
+    payload: payload || {}
+  };
+  fs.appendFileSync(file, `${JSON.stringify(record)}\n`, 'utf-8');
+  return record;
+}
+
+function parseEventLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+function listEvents(options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const file = getTelemetryFile(projectRoot);
+  if (!fs.existsSync(file)) return [];
+
+  const eventFilter = String(options.event || '').trim();
+  const from = options.from ? new Date(options.from).getTime() : null;
+  const to = options.to ? new Date(options.to).getTime() : null;
+  const limit = Number(options.limit);
+
+  const lines = fs.readFileSync(file, 'utf-8').split('\n').filter(Boolean);
+  let records = lines
+    .map(parseEventLine)
+    .filter(Boolean)
+    .filter(record => {
+      if (eventFilter && record.event !== eventFilter) return false;
+      const ts = new Date(record.timestamp).getTime();
+      if (Number.isFinite(from) && ts < from) return false;
+      if (Number.isFinite(to) && ts > to) return false;
+      return true;
+    });
+
+  const effectiveLimit = Number.isFinite(limit) && limit > 0
+    ? Math.min(limit, MAX_EVENTS_LIMIT)
+    : MAX_EVENTS_LIMIT;
+  records = records.slice(-effectiveLimit);
+  return records;
+}
+
+function clearEvents(options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const file = getTelemetryFile(projectRoot);
+  const records = listEvents({ projectRoot });
+  if (fs.existsSync(file)) {
+    fs.writeFileSync(file, '', 'utf-8');
+  }
+  return {
+    cleared: records.length,
+    file
+  };
+}
+
+function getStatus(options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const file = getTelemetryFile(projectRoot);
+  const records = listEvents({ projectRoot });
+  return {
+    file,
+    exists: fs.existsSync(file),
+    count: records.length,
+    lastEventAt: records.length > 0 ? records[records.length - 1].timestamp : null
+  };
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function chunkArray(items, size) {
+  const chunks = [];
+  for (let i = 0; i < items.length; i += size) {
+    chunks.push(items.slice(i, i + size));
+  }
+  return chunks;
+}
+
+async function postBatchWithRetry(endpoint, body, headers, options = {}) {
+  const maxRetries = Number(options.maxRetries);
+  const retryDelayMs = Number(options.retryDelayMs);
+  const retries = Number.isFinite(maxRetries) && maxRetries >= 0 ? maxRetries : 2;
+  const delayBase = Number.isFinite(retryDelayMs) && retryDelayMs > 0 ? retryDelayMs : 300;
+
+  let attempt = 0;
+  while (true) {
+    try {
+      const response = await fetch(endpoint, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+      return { success: true, attempts: attempt + 1 };
+    } catch (error) {
+      if (attempt >= retries) {
+        return {
+          success: false,
+          attempts: attempt + 1,
+          error: error.message || String(error)
+        };
+      }
+      attempt += 1;
+      const delay = delayBase * (2 ** (attempt - 1));
+      await sleep(delay);
+    }
+  }
+}
+
+async function uploadEvents(options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const endpoint = options.endpoint || process.env.BOOTSPRING_TELEMETRY_ENDPOINT;
+  if (!endpoint) {
+    throw new Error('Missing telemetry endpoint. Set BOOTSPRING_TELEMETRY_ENDPOINT or pass endpoint.');
+  }
+
+  const token = options.token || process.env.BOOTSPRING_TELEMETRY_TOKEN;
+  const event = options.event;
+  const limit = Number(options.limit) || undefined;
+  const batchSizeOption = Number(options.batchSize || process.env.BOOTSPRING_TELEMETRY_BATCH_SIZE);
+  const batchSize = Number.isFinite(batchSizeOption) && batchSizeOption > 0 ? batchSizeOption : 100;
+  const clearOnSuccess = options.clearOnSuccess === true;
+  const records = listEvents({ projectRoot, event, limit });
+
+  if (records.length === 0) {
+    return {
+      uploaded: 0,
+      remaining: 0,
+      endpoint
+    };
+  }
+
+  const headers = {
+    'content-type': 'application/json',
+    accept: 'application/json'
+  };
+  if (token) {
+    headers.authorization = `Bearer ${token}`;
+  }
+
+  const batches = chunkArray(records, batchSize);
+  let uploaded = 0;
+  let totalAttempts = 0;
+  const failedBatches = [];
+
+  for (let i = 0; i < batches.length; i++) {
+    const events = batches[i];
+    const batchId = crypto.createHash('sha1')
+      .update(JSON.stringify(events))
+      .digest('hex');
+    const result = await postBatchWithRetry(
+      endpoint,
+      {
+        source: 'bootspring',
+        batch: {
+          index: i,
+          total: batches.length,
+          id: batchId
+        },
+        events
+      },
+      {
+        ...headers,
+        'x-bootspring-batch-id': batchId
+      },
+      options
+    );
+
+    totalAttempts += result.attempts || 1;
+    if (!result.success) {
+      failedBatches.push({
+        index: i,
+        count: events.length,
+        error: result.error || 'upload_failed'
+      });
+      continue;
+    }
+    uploaded += events.length;
+  }
+
+  if (failedBatches.length > 0) {
+    throw new Error(`Telemetry upload failed for ${failedBatches.length}/${batches.length} batches`);
+  }
+
+  if (clearOnSuccess) {
+    clearEvents({ projectRoot });
+  }
+
+  const remaining = clearOnSuccess ? 0 : listEvents({ projectRoot }).length;
+  return {
+    uploaded,
+    attempted: records.length,
+    batches: batches.length,
+    attempts: totalAttempts,
+    remaining,
+    endpoint,
+    failedBatches
+  };
+}
+
+module.exports = {
+  MAX_EVENTS_LIMIT,
+  getTelemetryDir,
+  getTelemetryFile,
+  ensureTelemetryDir,
+  emitEvent,
+  listEvents,
+  clearEvents,
+  getStatus,
+  uploadEvents
+};

package/core/utils.js

@@ -0,0 +1,380 @@
+/**
+ * Bootspring Utilities
+ * Shared utility functions
+ *
+ * @package bootspring
+ * @module core/utils
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ANSI color codes
+const COLORS = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  italic: '\x1b[3m',
+  underline: '\x1b[4m',
+
+  // Foreground
+  black: '\x1b[30m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+
+  // Background
+  bgBlack: '\x1b[40m',
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+  bgBlue: '\x1b[44m',
+  bgMagenta: '\x1b[45m',
+  bgCyan: '\x1b[46m',
+  bgWhite: '\x1b[47m'
+};
+
+/**
+ * Styled console output
+ */
+const print = {
+  info: (msg) => console.log(`${COLORS.cyan}ℹ${COLORS.reset} ${msg}`),
+  success: (msg) => console.log(`${COLORS.green}✓${COLORS.reset} ${msg}`),
+  warning: (msg) => console.log(`${COLORS.yellow}⚠${COLORS.reset} ${msg}`),
+  error: (msg) => console.log(`${COLORS.red}✗${COLORS.reset} ${msg}`),
+  debug: (msg) => process.env.DEBUG && console.log(`${COLORS.dim}⋯ ${msg}${COLORS.reset}`),
+  header: (msg) => console.log(`\n${COLORS.bold}${COLORS.cyan}${msg}${COLORS.reset}\n`),
+  dim: (msg) => console.log(`${COLORS.dim}${msg}${COLORS.reset}`),
+  brand: (msg) => console.log(`${COLORS.cyan}⚡${COLORS.reset} ${msg}`)
+};
+
+/**
+ * Create a spinner for async operations
+ * @param {string} message - Spinner message
+ * @returns {object} Spinner controller
+ */
+function createSpinner(message) {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let frameIndex = 0;
+  let interval = null;
+  const isTTY = process.stdout.isTTY;
+
+  // Helper to clear line safely
+  const clearLine = () => {
+    if (isTTY && process.stdout.clearLine) {
+      process.stdout.clearLine(0);
+      process.stdout.cursorTo(0);
+    }
+  };
+
+  return {
+    start() {
+      if (isTTY) {
+        process.stdout.write(`${COLORS.cyan}${frames[0]}${COLORS.reset} ${message}`);
+        interval = setInterval(() => {
+          frameIndex = (frameIndex + 1) % frames.length;
+          clearLine();
+          process.stdout.write(`${COLORS.cyan}${frames[frameIndex]}${COLORS.reset} ${message}`);
+        }, 80);
+      }
+      return this;
+    },
+
+    succeed(text = message) {
+      if (interval) clearInterval(interval);
+      clearLine();
+      console.log(`${COLORS.green}✓${COLORS.reset} ${text}`);
+      return this;
+    },
+
+    fail(text = message) {
+      if (interval) clearInterval(interval);
+      clearLine();
+      console.log(`${COLORS.red}✗${COLORS.reset} ${text}`);
+      return this;
+    },
+
+    warn(text = message) {
+      if (interval) clearInterval(interval);
+      clearLine();
+      console.log(`${COLORS.yellow}⚠${COLORS.reset} ${text}`);
+      return this;
+    },
+
+    info(text = message) {
+      if (interval) clearInterval(interval);
+      clearLine();
+      console.log(`${COLORS.cyan}ℹ${COLORS.reset} ${text}`);
+      return this;
+    },
+
+    stop() {
+      if (interval) clearInterval(interval);
+      clearLine();
+      return this;
+    }
+  };
+}
+
+/**
+ * Ensure directory exists
+ * @param {string} dirPath - Directory path
+ * @returns {boolean} Success status
+ */
+function ensureDir(dirPath) {
+  try {
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Read file safely
+ * @param {string} filepath - File path
+ * @param {string} [defaultValue=null] - Default value if file doesn't exist
+ * @returns {string|null} File contents or default value (null if not found)
+ */
+function readFile(filepath, defaultValue = null) {
+  try {
+    return fs.readFileSync(filepath, 'utf-8');
+  } catch (error) {
+    return defaultValue;
+  }
+}
+
+/**
+ * Write file safely
+ * @param {string} filepath - File path
+ * @param {string} content - File content
+ * @returns {boolean} Success status
+ */
+function writeFile(filepath, content) {
+  try {
+    const dir = path.dirname(filepath);
+    ensureDir(dir);
+    fs.writeFileSync(filepath, content, 'utf-8');
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Check if file exists
+ * @param {string} filepath - File path
+ * @returns {boolean} Exists status
+ */
+function fileExists(filepath) {
+  try {
+    return fs.existsSync(filepath);
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Get file modification time
+ * @param {string} filepath - File path
+ * @returns {Date|null} Modification date or null
+ */
+function getFileTime(filepath) {
+  try {
+    const stats = fs.statSync(filepath);
+    return stats.mtime;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Format date as ISO string without time
+ * @param {Date} date - Date object
+ * @returns {string} Formatted date
+ */
+function formatDate(date = new Date()) {
+  return date.toISOString().split('T')[0];
+}
+
+/**
+ * Format date as relative time
+ * @param {Date} date - Date object
+ * @returns {string} Relative time string
+ */
+function formatRelativeTime(date) {
+  const now = new Date();
+  const diff = now - date;
+  const seconds = Math.floor(diff / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) return `${days} day${days > 1 ? 's' : ''} ago`;
+  if (hours > 0) return `${hours} hour${hours > 1 ? 's' : ''} ago`;
+  if (minutes > 0) return `${minutes} minute${minutes > 1 ? 's' : ''} ago`;
+  return 'just now';
+}
+
+/**
+ * Slugify a string
+ * @param {string} str - Input string
+ * @returns {string} Slugified string
+ */
+function slugify(str) {
+  return str
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Truncate string with ellipsis
+ * @param {string} str - Input string
+ * @param {number} length - Max length
+ * @returns {string} Truncated string
+ */
+function truncate(str, length = 50) {
+  if (str.length <= length) return str;
+  return str.slice(0, length - 3) + '...';
+}
+
+/**
+ * Parse command line arguments
+ * @param {string[]} args - Argument array
+ * @returns {object} Parsed arguments { _: positional, ...flags }
+ */
+function parseArgs(args) {
+  const result = { _: [] };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const nextArg = args[i + 1];
+
+      if (key.includes('=')) {
+        const [k, v] = key.split('=');
+        result[k] = v;
+      } else if (nextArg && !nextArg.startsWith('-')) {
+        result[key] = nextArg;
+        i++;
+      } else {
+        result[key] = true;
+      }
+    } else if (arg.startsWith('-') && arg.length === 2) {
+      // Short flag (e.g., -v, -n)
+      const key = arg.slice(1);
+      const nextArg = args[i + 1];
+
+      // Check if next argument is a value (not another flag)
+      if (nextArg && !nextArg.startsWith('-')) {
+        result[key] = nextArg;
+        i++;
+      } else {
+        result[key] = true;
+      }
+    } else if (arg.startsWith('-')) {
+      // Combined short flags (e.g., -abc) - treat each as boolean
+      const keys = arg.slice(1).split('');
+      for (const key of keys) {
+        result[key] = true;
+      }
+    } else {
+      result._.push(arg);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Create a simple table for console output
+ * @param {string[]} headers - Table headers
+ * @param {string[][]} rows - Table rows
+ * @returns {string} Formatted table
+ */
+function createTable(headers, rows) {
+  const widths = headers.map((h, i) => {
+    const colValues = [h, ...rows.map(r => String(r[i] || ''))];
+    return Math.max(...colValues.map(v => v.length));
+  });
+
+  const separator = widths.map(w => '─'.repeat(w + 2)).join('┼');
+  const formatRow = (row) => row.map((cell, i) => ` ${String(cell).padEnd(widths[i])} `).join('│');
+
+  const lines = [
+    formatRow(headers),
+    separator,
+    ...rows.map(formatRow)
+  ];
+
+  return lines.join('\n');
+}
+
+/**
+ * Deep clone an object
+ * @param {object} obj - Object to clone
+ * @returns {object} Cloned object
+ */
+function deepClone(obj) {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+/**
+ * Check if running in CI environment
+ * @returns {boolean} CI status
+ */
+function isCI() {
+  return !!(
+    process.env.CI ||
+    process.env.CONTINUOUS_INTEGRATION ||
+    process.env.GITHUB_ACTIONS ||
+    process.env.GITLAB_CI ||
+    process.env.CIRCLECI ||
+    process.env.TRAVIS
+  );
+}
+
+/**
+ * Get package.json from project
+ * @param {string} projectRoot - Project root path
+ * @returns {object|null} Package.json contents or null
+ */
+function getPackageJson(projectRoot) {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  try {
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch (error) {
+    return null;
+  }
+}
+
+module.exports = {
+  COLORS,
+  print,
+  createSpinner,
+  ensureDir,
+  readFile,
+  writeFile,
+  fileExists,
+  getFileTime,
+  formatDate,
+  formatRelativeTime,
+  slugify,
+  truncate,
+  parseArgs,
+  createTable,
+  deepClone,
+  isCI,
+  getPackageJson
+};