@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/cli/telemetry.ts

@@ -0,0 +1,172 @@
+/**
+ * Bootspring Telemetry Command
+ * Inspect and upload telemetry events.
+ *
+ * @package bootspring
+ * @module cli/telemetry
+ */
+
+import * as utils from '../core/utils';
+import * as telemetry from '../core/telemetry';
+import type { ListEventsOptions, UploadOptions } from '../core/telemetry';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * List command options
+ */
+interface ListOptions {
+  event?: string | undefined;
+  limit?: number | undefined;
+}
+
+/**
+ * Upload command options
+ */
+interface UploadCommandOptions {
+  endpoint?: string | undefined;
+  token?: string | undefined;
+  event?: string | undefined;
+  limit?: number | undefined;
+  clear?: boolean | undefined;
+}
+
+// =============================================================================
+// Command Functions
+// =============================================================================
+
+/**
+ * Show telemetry status
+ */
+function showStatus(): void {
+  const status = telemetry.getStatus();
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}Telemetry Status${utils.COLORS.reset}
+${utils.COLORS.dim}File: ${status.file}${utils.COLORS.reset}
+${utils.COLORS.dim}Events: ${status.count}${utils.COLORS.reset}
+${utils.COLORS.dim}Last event: ${status.lastEventAt ?? 'none'}${utils.COLORS.reset}
+`);
+}
+
+/**
+ * List telemetry events
+ */
+function listEvents(options: ListOptions = {}): void {
+  const listOptions: ListEventsOptions = {
+    event: options.event,
+    limit: options.limit
+  };
+
+  const records = telemetry.listEvents(listOptions);
+  if (records.length === 0) {
+    utils.print.warning('No telemetry events found');
+    return;
+  }
+
+  records.forEach(record => {
+    console.log(`${utils.COLORS.cyan}${record.timestamp}${utils.COLORS.reset} ${record.event}`);
+  });
+  console.log(`\n${utils.COLORS.dim}${records.length} event(s)${utils.COLORS.reset}`);
+}
+
+/**
+ * Upload telemetry events
+ */
+async function upload(options: UploadCommandOptions = {}): Promise<void> {
+  const spinner = utils.createSpinner('Uploading telemetry events').start();
+  try {
+    const uploadOptions: UploadOptions = {
+      endpoint: options.endpoint,
+      token: options.token,
+      event: options.event,
+      limit: options.limit,
+      clearOnSuccess: options.clear
+    };
+
+    const result = await telemetry.uploadEvents(uploadOptions);
+    spinner.succeed(`Uploaded ${result.uploaded} event(s)`);
+    utils.print.dim(`Endpoint: ${result.endpoint}`);
+    utils.print.dim(`Remaining local events: ${result.remaining}`);
+  } catch (error) {
+    spinner.fail(`Upload failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * Clear telemetry events
+ */
+function clear(): void {
+  const result = telemetry.clearEvents();
+  utils.print.success(`Cleared ${result.cleared} event(s)`);
+}
+
+/**
+ * Show help
+ */
+function help(): void {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}Bootspring Telemetry${utils.COLORS.reset}
+
+${utils.COLORS.cyan}Usage:${utils.COLORS.reset}
+  bootspring telemetry <command> [options]
+
+${utils.COLORS.cyan}Commands:${utils.COLORS.reset}
+  ${utils.COLORS.cyan}status${utils.COLORS.reset}                   Show telemetry status
+  ${utils.COLORS.cyan}list${utils.COLORS.reset}                     List telemetry events
+  ${utils.COLORS.cyan}upload${utils.COLORS.reset}                   Upload events to endpoint
+  ${utils.COLORS.cyan}clear${utils.COLORS.reset}                    Clear local event log
+
+${utils.COLORS.cyan}Options:${utils.COLORS.reset}
+  ${utils.COLORS.cyan}--event <name>${utils.COLORS.reset}           Filter by event name
+  ${utils.COLORS.cyan}--limit <n>${utils.COLORS.reset}              Limit listed/uploaded events
+  ${utils.COLORS.cyan}--endpoint <url>${utils.COLORS.reset}         Upload endpoint override
+  ${utils.COLORS.cyan}--token <value>${utils.COLORS.reset}          Upload bearer token
+  ${utils.COLORS.cyan}--clear${utils.COLORS.reset}                  Clear local events on successful upload
+`);
+}
+
+// =============================================================================
+// Main Entry Point
+// =============================================================================
+
+/**
+ * Run telemetry command
+ */
+export async function run(args: string[]): Promise<void> {
+  const parsed = utils.parseArgs(args);
+  const command = parsed._[0] ?? 'status';
+
+  switch (command) {
+    case 'status':
+      showStatus();
+      break;
+    case 'list':
+      listEvents({
+        event: parsed.event as string | undefined,
+        limit: parsed.limit ? Number(parsed.limit) : undefined
+      });
+      break;
+    case 'upload':
+      await upload({
+        endpoint: parsed.endpoint as string | undefined,
+        token: parsed.token as string | undefined,
+        event: parsed.event as string | undefined,
+        limit: parsed.limit ? Number(parsed.limit) : undefined,
+        clear: Boolean(parsed.clear)
+      });
+      break;
+    case 'clear':
+      clear();
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+      help();
+      break;
+    default:
+      utils.print.error(`Unknown telemetry command: ${command}`);
+      help();
+  }
+}