@girardmedia/bootspring 2.1.3 → 2.2.1

package/core/telemetry.d.ts

@@ -1,55 +0,0 @@
-/**
- * Bootspring Telemetry Types
- * @module core/telemetry
- */
-
-export interface TelemetryEvent {
-  event: string;
-  timestamp: number;
-  data?: Record<string, unknown>;
-  sessionId?: string;
-}
-
-export interface UploadResult {
-  success: boolean;
-  uploaded: number;
-  errors?: string[];
-}
-
-/** Maximum events to store locally */
-export const MAX_EVENTS_LIMIT: number;
-
-/**
- * Emit a telemetry event
- * @param event - Event name
- * @param data - Event data
- */
-export function emit(event: string, data?: Record<string, unknown>): void;
-
-/**
- * List stored telemetry events
- * @param limit - Maximum events to return
- * @returns Array of events
- */
-export function list(limit?: number): TelemetryEvent[];
-
-/**
- * Upload telemetry events to server
- * @param options - Upload options
- * @returns Upload result
- */
-export function upload(options?: {
-  batchSize?: number;
-  clearOnSuccess?: boolean;
-}): Promise<UploadResult>;
-
-/**
- * Clear stored telemetry events
- */
-export function clear(): void;
-
-/**
- * Get telemetry session ID
- * @returns Current session ID
- */
-export function getSessionId(): string;

package/core/telemetry.js

@@ -1,617 +0,0 @@
-/**
- * Bootspring Telemetry
- * Lightweight JSONL event emitter for product instrumentation.
- */
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-const { redactErrorMessage, redactSensitiveData } = require('./redaction');
-
-const MAX_EVENTS_LIMIT = 10000;
-const ASSISTANTS = ['claude', 'codex', 'gemini'];
-const ASSISTANT_SETUP_EVENT = 'assistant_setup';
-const ASSISTANT_FIRST_SUCCESS_EVENT = 'assistant_first_success';
-const ASSISTANT_RETURN_EVENT = 'assistant_return';
-const BILLING_UPGRADE_STARTED_EVENT = 'billing_upgrade_started';
-const UPGRADE_PROMPT_EVENT = 'premium_prompted';
-const UPGRADE_COMPLETED_EVENT = 'premium_unlocked';
-const ASSISTANT_STATUS_ALLOWLIST = new Set(['installed', 'updated', 'skipped', 'failed', 'created', 'unchanged']);
-const ASSISTANT_SOURCE_ALLOWLIST = new Set(['mcp', 'cli', 'setup', 'dashboard', 'api', 'unknown']);
-
-function normalizeAssistantId(value) {
-  const normalized = String(value || '').trim().toLowerCase();
-  if (!normalized) return null;
-  const compact = normalized.replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
-  if (compact === 'claude' || compact === 'claude-code') return 'claude';
-  if (compact === 'codex' || compact === 'openai-codex') return 'codex';
-  if (compact === 'gemini' || compact === 'gemini-cli') return 'gemini';
-  return null;
-}
-
-function inferAssistantFromEnvironment(env = process.env) {
-  const explicit = normalizeAssistantId(env.BOOTSPRING_ASSISTANT);
-  if (explicit) return explicit;
-  if (env.CLAUDE_CODE || env.CLAUDECODE) return 'claude';
-  if (env.CODEX_SANDBOX || env.CODEX_ENV || env.OPENAI_CODEX) return 'codex';
-  if (env.GEMINI_CLI || env.GOOGLE_GEMINI_CLI) return 'gemini';
-  return null;
-}
-
-function normalizeCardinalityValue(value, fallback = 'unknown') {
-  const normalized = String(value || '')
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9_-]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-  return normalized || fallback;
-}
-
-function normalizeAssistantStatus(value) {
-  const normalized = normalizeCardinalityValue(value, 'updated');
-  return ASSISTANT_STATUS_ALLOWLIST.has(normalized) ? normalized : 'other';
-}
-
-function normalizeAssistantSource(value) {
-  const normalized = normalizeCardinalityValue(value, 'unknown');
-  return ASSISTANT_SOURCE_ALLOWLIST.has(normalized) ? normalized : 'other';
-}
-
-function getAssistantRecords(assistant, options = {}) {
-  const normalized = normalizeAssistantId(assistant);
-  if (!normalized) return [];
-  return listEvents({
-    projectRoot: options.projectRoot
-  }).filter(record => normalizeAssistantId(record?.payload?.assistant) === normalized);
-}
-
-function returnWindow(daysSinceFirst) {
-  if (daysSinceFirst >= 7) return 'd7_plus';
-  if (daysSinceFirst >= 2) return 'd2_6';
-  if (daysSinceFirst >= 1) return 'd1';
-  return 'd0';
-}
-
-function eventTimeMs(record) {
-  const occurredAt = String(record?.payload?.occurredAt || '').trim();
-  const source = occurredAt || String(record?.timestamp || '').trim();
-  const ts = new Date(source).getTime();
-  return Number.isFinite(ts) ? ts : null;
-}
-
-function eventTimeIso(record) {
-  const occurredAt = String(record?.payload?.occurredAt || '').trim();
-  if (occurredAt) return occurredAt;
-  const fallback = String(record?.timestamp || '').trim();
-  return fallback || null;
-}
-
-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 eventTime = options.now ? new Date(options.now) : new Date();
-  const record = {
-    timestamp: eventTime.toISOString(),
-    event: String(event || '').trim(),
-    payload: redactSensitiveData(payload || {})
-  };
-  fs.appendFileSync(file, `${JSON.stringify(record)}\n`, 'utf-8');
-  return record;
-}
-
-function trackAssistantSetup(assistant, payload = {}, options = {}) {
-  const normalized = normalizeAssistantId(assistant);
-  if (!normalized) {
-    return null;
-  }
-
-  return emitEvent(ASSISTANT_SETUP_EVENT, {
-    assistant: normalized,
-    status: normalizeAssistantStatus(payload.status)
-  }, options);
-}
-
-function trackAssistantUsageSuccess(assistant, payload = {}, options = {}) {
-  const normalized = normalizeAssistantId(assistant);
-  if (!normalized) {
-    return {
-      assistant: null,
-      firstSuccessTracked: false,
-      returnTracked: false,
-      daysSinceFirst: null
-    };
-  }
-
-  const projectRoot = options.projectRoot || process.cwd();
-  const now = options.now ? new Date(options.now) : new Date();
-  const records = getAssistantRecords(normalized, { projectRoot });
-  const firstSuccess = records.find(record => record.event === ASSISTANT_FIRST_SUCCESS_EVENT);
-
-  if (!firstSuccess) {
-    emitEvent(ASSISTANT_FIRST_SUCCESS_EVENT, {
-      assistant: normalized,
-      source: normalizeAssistantSource(payload.source || 'mcp')
-    }, { projectRoot, now });
-    return {
-      assistant: normalized,
-      firstSuccessTracked: true,
-      returnTracked: false,
-      daysSinceFirst: 0
-    };
-  }
-
-  const firstSuccessAt = eventTimeMs(firstSuccess);
-  const daysSinceFirst = Number.isFinite(firstSuccessAt)
-    ? Math.floor((now.getTime() - firstSuccessAt) / (24 * 60 * 60 * 1000))
-    : 0;
-
-  if (daysSinceFirst >= 1) {
-    const window = returnWindow(daysSinceFirst);
-    const alreadyTrackedWindow = records.some(record => {
-      if (record.event !== ASSISTANT_RETURN_EVENT) return false;
-      return String(record?.payload?.window || '') === window;
-    });
-
-    if (!alreadyTrackedWindow) {
-      emitEvent(ASSISTANT_RETURN_EVENT, {
-        assistant: normalized,
-        source: normalizeAssistantSource(payload.source || 'mcp'),
-        window
-      }, { projectRoot, now });
-      return {
-        assistant: normalized,
-        firstSuccessTracked: false,
-        returnTracked: true,
-        daysSinceFirst
-      };
-    }
-  }
-
-  return {
-    assistant: normalized,
-    firstSuccessTracked: false,
-    returnTracked: false,
-    daysSinceFirst
-  };
-}
-
-function dayDelta(fromIso, toIso) {
-  const from = new Date(String(fromIso || '')).getTime();
-  const to = new Date(String(toIso || '')).getTime();
-  if (!Number.isFinite(from) || !Number.isFinite(to)) {
-    return null;
-  }
-  return Math.floor((to - from) / (24 * 60 * 60 * 1000));
-}
-
-function summarizeAssistantFunnel(records, assistant) {
-  const filtered = records.filter(record => normalizeAssistantId(record?.payload?.assistant) === assistant);
-  const setupEvent = filtered.find(record => record.event === ASSISTANT_SETUP_EVENT);
-  const firstSuccessEvent = filtered.find(record => record.event === ASSISTANT_FIRST_SUCCESS_EVENT);
-  const returns = filtered.filter(record => record.event === ASSISTANT_RETURN_EVENT);
-
-  const d1 = firstSuccessEvent
-    ? returns.some(record => {
-      const delta = dayDelta(eventTimeIso(firstSuccessEvent), eventTimeIso(record));
-      return delta !== null && delta >= 1;
-    })
-    : false;
-  const d7 = firstSuccessEvent
-    ? returns.some(record => {
-      const delta = dayDelta(eventTimeIso(firstSuccessEvent), eventTimeIso(record));
-      return delta !== null && delta >= 7;
-    })
-    : false;
-
-  return {
-    setup: !!setupEvent,
-    firstSuccess: !!firstSuccessEvent,
-    returned: returns.length > 0,
-    d1,
-    d7,
-    setupAt: eventTimeIso(setupEvent),
-    firstSuccessAt: eventTimeIso(firstSuccessEvent),
-    lastReturnAt: returns.length > 0 ? eventTimeIso(returns[returns.length - 1]) : null
-  };
-}
-
-function getAssistantActivationFunnel(options = {}) {
-  const projectRoot = options.projectRoot || process.cwd();
-  const assistantFilter = normalizeAssistantId(options.assistant);
-  const records = listEvents({
-    projectRoot,
-    from: options.from,
-    to: options.to
-  });
-  const assistantIds = assistantFilter ? [assistantFilter] : ASSISTANTS;
-
-  const assistants = {};
-  for (const assistant of assistantIds) {
-    assistants[assistant] = summarizeAssistantFunnel(records, assistant);
-  }
-
-  const totals = Object.values(assistants).reduce((acc, entry) => {
-    if (entry.setup) acc.setup += 1;
-    if (entry.firstSuccess) acc.firstSuccess += 1;
-    if (entry.returned) acc.return += 1;
-    if (entry.d1) acc.d1 += 1;
-    if (entry.d7) acc.d7 += 1;
-    return acc;
-  }, { setup: 0, firstSuccess: 0, return: 0, d1: 0, d7: 0 });
-
-  return {
-    generatedAt: new Date().toISOString(),
-    query: {
-      assistant: assistantFilter,
-      from: options.from || null,
-      to: options.to || null
-    },
-    totals,
-    assistants
-  };
-}
-
-function safeRate(numerator, denominator) {
-  if (!denominator) return 0;
-  return Number((numerator / denominator).toFixed(4));
-}
-
-function normalizeDimension(value, fallback) {
-  const normalized = String(value || '')
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9_-]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-  return normalized || fallback;
-}
-
-function getUpgradeEventContext(payload = {}) {
-  const feature = payload.feature || payload.skillId || payload.workflow || payload.agent || 'unknown';
-  return {
-    capability: normalizeDimension(payload.capability, 'unknown'),
-    featureType: normalizeDimension(payload.featureType, 'general'),
-    feature: normalizeDimension(feature, 'unknown'),
-    placement: normalizeDimension(payload.placement, 'inline'),
-    variant: normalizeDimension(payload.variant, 'control')
-  };
-}
-
-/**
- * Summarize upgrade conversion funnel (prompt shown -> upgrade started -> premium unlocked).
- * @param {{ projectRoot?: string }} options
- * @returns {{ generatedAt: string, totals: { prompted: number, started: number, completed: number, converted: number, startRate: number, conversionRate: number }, capabilities: Record<string, object> }}
- */
-function getUpgradeConversionFunnel(options = {}) {
-  const projectRoot = options.projectRoot || process.cwd();
-  const records = listEvents({ projectRoot });
-  const capabilities = {};
-
-  for (const record of records) {
-    if (record.event !== UPGRADE_PROMPT_EVENT
-      && record.event !== BILLING_UPGRADE_STARTED_EVENT
-      && record.event !== UPGRADE_COMPLETED_EVENT) {
-      continue;
-    }
-
-    const context = getUpgradeEventContext(record.payload);
-    const key = `${context.capability}:${context.featureType}:${context.feature}`;
-    if (!capabilities[key]) {
-      capabilities[key] = {
-        capability: context.capability,
-        featureType: context.featureType,
-        feature: context.feature,
-        prompted: 0,
-        started: 0,
-        completed: 0,
-        converted: 0,
-        conversionRate: 0,
-        placements: {},
-        variants: {}
-      };
-    }
-
-    const bucket = capabilities[key];
-    if (!bucket) continue;
-
-    if (record.event === UPGRADE_PROMPT_EVENT) {
-      bucket.prompted += 1;
-      bucket.placements[context.placement] = (bucket.placements[context.placement] || 0) + 1;
-      bucket.variants[context.variant] = (bucket.variants[context.variant] || 0) + 1;
-      continue;
-    }
-
-    if (record.event === BILLING_UPGRADE_STARTED_EVENT) {
-      bucket.started += 1;
-      continue;
-    }
-
-    bucket.completed += 1;
-  }
-
-  const totals = Object.values(capabilities).reduce((acc, bucket) => {
-    bucket.converted = Math.min(bucket.prompted, bucket.completed);
-    bucket.conversionRate = safeRate(bucket.converted, bucket.prompted);
-
-    acc.prompted += bucket.prompted;
-    acc.started += bucket.started;
-    acc.completed += bucket.completed;
-    acc.converted += bucket.converted;
-    return acc;
-  }, {
-    prompted: 0,
-    started: 0,
-    completed: 0,
-    converted: 0
-  });
-
-  return {
-    generatedAt: new Date().toISOString(),
-    totals: {
-      ...totals,
-      startRate: safeRate(totals.started, totals.prompted),
-      conversionRate: safeRate(totals.converted, totals.prompted)
-    },
-    capabilities
-  };
-}
-
-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: redactErrorMessage(error)
-        };
-      }
-      attempt += 1;
-      const delay = delayBase * (2 ** (attempt - 1));
-      await sleep(delay);
-    }
-  }
-}
-
-async function uploadEvents(options = {}) {
-  const projectRoot = options.projectRoot || process.cwd();
-  const API_BASE = process.env.BOOTSPRING_API_URL || 'https://www.bootspring.com';
-  const defaultEndpoint = `${API_BASE}/api/v1/events/batch`;
-  const endpoint = options.endpoint || process.env.BOOTSPRING_TELEMETRY_ENDPOINT || defaultEndpoint;
-
-  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
-    };
-  }
-
-  // Try to get API key and project context from auth/session modules
-  let apiKey = null;
-  let projectId = null;
-  try {
-    const auth = require('./auth');
-    const session = require('./session');
-    apiKey = auth.getApiKey();
-    const project = session.getEffectiveProject();
-    projectId = project?.id || null;
-  } catch {
-    // Modules not available, continue without
-  }
-
-  const headers = {
-    'content-type': 'application/json',
-    accept: 'application/json',
-    'user-agent': `bootspring-cli/${require('../package.json').version}`
-  };
-
-  // Use API key if available, otherwise fall back to token
-  if (apiKey) {
-    headers['x-api-key'] = apiKey;
-  } else if (token) {
-    headers.authorization = `Bearer ${token}`;
-  }
-
-  // Add project context if available
-  if (projectId) {
-    headers['x-project-id'] = projectId;
-  }
-
-  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: redactErrorMessage(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,
-  ASSISTANTS,
-  ASSISTANT_SETUP_EVENT,
-  ASSISTANT_FIRST_SUCCESS_EVENT,
-  ASSISTANT_RETURN_EVENT,
-  BILLING_UPGRADE_STARTED_EVENT,
-  UPGRADE_PROMPT_EVENT,
-  UPGRADE_COMPLETED_EVENT,
-  getTelemetryDir,
-  getTelemetryFile,
-  ensureTelemetryDir,
-  emitEvent,
-  track: emitEvent, // Alias for compatibility
-  normalizeAssistantId,
-  inferAssistantFromEnvironment,
-  trackAssistantSetup,
-  trackAssistantUsageSuccess,
-  getAssistantActivationFunnel,
-  getUpgradeConversionFunnel,
-  listEvents,
-  clearEvents,
-  getStatus,
-  uploadEvents
-};