@springfield/ham-radio-utils 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.1.0](https://gitlab.com/springfield-ham-radio/app/ham-radio-utils/compare/v2.0.2...v2.1.0) (2025-06-21)
+
+
+### Features
+
+* add UI logger for command-level logging in UI environments ([c9f7545](https://gitlab.com/springfield-ham-radio/app/ham-radio-utils/commit/c9f754580119f4c8bfd1a42ebca089692fd4a62e))
+
+## [2.0.2](https://gitlab.com/springfield-ham-radio/app/ham-radio-utils/compare/v2.0.1...v2.0.2) (2025-06-20)
+
+
+### Bug Fixes
+
+* **deps:** update dependency loglayer to ^6.4.3 ([0e41dfa](https://gitlab.com/springfield-ham-radio/app/ham-radio-utils/commit/0e41dfa764d9b3b176efcea00a586c3e2cfef336))
+
 ## [2.0.1](https://gitlab.com/springfield-ham-radio/app/ham-radio-utils/compare/v2.0.0...v2.0.1) (2025-06-14)
 
 

package/dist/index.d.ts

@@ -8,4 +8,6 @@ export * from './utils/memory-channel-utils.js';
 export * from './utils/memory-data-utils.js';
 export * from './utils/number-to-bcd.js';
 export * from './utils/to-hex-words.js';
+export * from './utils/ui-logger.js';
+export * from './utils/ui-logger-factory.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAE7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,kDAAkD,CAAC;AAEjE,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAE7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,kDAAkD,CAAC;AAEjE,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC"}

package/dist/index.js

@@ -8,4 +8,6 @@ export * from './utils/memory-channel-utils.js';
 export * from './utils/memory-data-utils.js';
 export * from './utils/number-to-bcd.js';
 export * from './utils/to-hex-words.js';
+export * from './utils/ui-logger.js';
+export * from './utils/ui-logger-factory.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAE7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,kDAAkD,CAAC;AAEjE,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC","sourcesContent":["export * from './memory/segmented-memory.js';\n\nexport * from './test-utils/radio-channel-factory.js';\nexport * from './test-utils/radio-programmed-channel-factory.js';\n\nexport * from './utils/bcd-to-number.js';\nexport * from './utils/band-plan.js';\nexport * from './utils/frequency-display.js';\nexport * from './utils/memory-channel-utils.js';\nexport * from './utils/memory-data-utils.js';\nexport * from './utils/number-to-bcd.js';\nexport * from './utils/to-hex-words.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAE7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,kDAAkD,CAAC;AAEjE,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC","sourcesContent":["export * from './memory/segmented-memory.js';\n\nexport * from './test-utils/radio-channel-factory.js';\nexport * from './test-utils/radio-programmed-channel-factory.js';\n\nexport * from './utils/bcd-to-number.js';\nexport * from './utils/band-plan.js';\nexport * from './utils/frequency-display.js';\nexport * from './utils/memory-channel-utils.js';\nexport * from './utils/memory-data-utils.js';\nexport * from './utils/number-to-bcd.js';\nexport * from './utils/to-hex-words.js';\nexport * from './utils/ui-logger.js';\nexport * from './utils/ui-logger-factory.js';\n"]}

package/dist/utils/ui-logger-factory.d.ts

@@ -0,0 +1,8 @@
+import { UILogger } from './ui-logger.js';
+export interface UILoggerConfig {
+    enableConsoleDebug?: boolean;
+    customTransport?: any;
+}
+export declare function createUILogger(config?: UILoggerConfig): UILogger;
+export declare function createUILoggerWithCallback(callback: (logEntry: any) => void, config?: UILoggerConfig): UILogger;
+//# sourceMappingURL=ui-logger-factory.d.ts.map

package/dist/utils/ui-logger-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-logger-factory.d.ts","sourceRoot":"","sources":["../../src/utils/ui-logger-factory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AA2B1C,MAAM,WAAW,cAAc;IAC7B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,eAAe,CAAC,EAAE,GAAG,CAAC;CACvB;AAED,wBAAgB,cAAc,CAAC,MAAM,GAAE,cAAmB,GAAG,QAAQ,CAYpE;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,EAAE,MAAM,GAAE,cAAmB,GAAG,QAAQ,CAQnH"}

package/dist/utils/ui-logger-factory.js

@@ -0,0 +1,48 @@
+import { LogLayer } from 'loglayer';
+import { BaseTransport } from '@loglayer/transport';
+import { UILogger } from './ui-logger.js';
+/**
+ * Custom LogLayer transport for capturing UI log entries.
+ */
+class UILogTransport extends BaseTransport {
+    #callback;
+    constructor(callback) {
+        // Pass a dummy logger to BaseTransport
+        super({ logger: { log: () => { } }, id: 'ui-logger-transport', enabled: true });
+        this.#callback = callback;
+    }
+    shipToLogger(params) {
+        const logEntry = {
+            timestamp: new Date().toISOString(),
+            level: params.logLevel,
+            message: params.messages.join(' '),
+            data: params.data,
+            hasData: params.hasData,
+        };
+        this.#callback(logEntry);
+        return [];
+    }
+}
+export function createUILogger(config = {}) {
+    // By default, just print to console as JSON
+    const defaultCallback = (logEntry) => {
+        console.log(JSON.stringify(logEntry));
+    };
+    const transport = config.customTransport || new UILogTransport(defaultCallback);
+    const logger = new LogLayer({
+        transport,
+        consoleDebug: config.enableConsoleDebug ?? false,
+    });
+    logger.setLevel('debug');
+    return new UILogger(logger);
+}
+export function createUILoggerWithCallback(callback, config = {}) {
+    const transport = new UILogTransport(callback);
+    const logger = new LogLayer({
+        transport,
+        consoleDebug: config.enableConsoleDebug ?? false,
+    });
+    logger.setLevel('debug');
+    return new UILogger(logger);
+}
+//# sourceMappingURL=ui-logger-factory.js.map

package/dist/utils/ui-logger-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-logger-factory.js","sourceRoot":"","sources":["../../src/utils/ui-logger-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;GAEG;AACH,MAAM,cAAe,SAAQ,aAAkB;IAC7C,SAAS,CAA0B;IAEnC,YAAY,QAAiC;QAC3C,uCAAuC;QACvC,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,EAAE,EAAE,EAAE,qBAAqB,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/E,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED,YAAY,CAAC,MAAW;QACtB,MAAM,QAAQ,GAAG;YACf,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,KAAK,EAAE,MAAM,CAAC,QAAQ;YACtB,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;YAClC,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB,CAAC;QACF,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;CACF;AAOD,MAAM,UAAU,cAAc,CAAC,SAAyB,EAAE;IACxD,4CAA4C;IAC5C,MAAM,eAAe,GAAG,CAAC,QAAa,EAAE,EAAE;QACxC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxC,CAAC,CAAC;IACF,MAAM,SAAS,GAAG,MAAM,CAAC,eAAe,IAAI,IAAI,cAAc,CAAC,eAAe,CAAC,CAAC;IAChF,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC;QAC1B,SAAS;QACT,YAAY,EAAE,MAAM,CAAC,kBAAkB,IAAI,KAAK;KACjD,CAAC,CAAC;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACzB,OAAO,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,QAAiC,EAAE,SAAyB,EAAE;IACvG,MAAM,SAAS,GAAG,IAAI,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC;QAC1B,SAAS;QACT,YAAY,EAAE,MAAM,CAAC,kBAAkB,IAAI,KAAK;KACjD,CAAC,CAAC;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACzB,OAAO,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC","sourcesContent":["import { LogLayer } from 'loglayer';\nimport { BaseTransport } from '@loglayer/transport';\nimport { UILogger } from './ui-logger.js';\n\n/**\n * Custom LogLayer transport for capturing UI log entries.\n */\nclass UILogTransport extends BaseTransport<any> {\n  #callback: (logEntry: any) => void;\n\n  constructor(callback: (logEntry: any) => void) {\n    // Pass a dummy logger to BaseTransport\n    super({ logger: { log: () => {} }, id: 'ui-logger-transport', enabled: true });\n    this.#callback = callback;\n  }\n\n  shipToLogger(params: any) {\n    const logEntry = {\n      timestamp: new Date().toISOString(),\n      level: params.logLevel,\n      message: params.messages.join(' '),\n      data: params.data,\n      hasData: params.hasData,\n    };\n    this.#callback(logEntry);\n    return [];\n  }\n}\n\nexport interface UILoggerConfig {\n  enableConsoleDebug?: boolean;\n  customTransport?: any;\n}\n\nexport function createUILogger(config: UILoggerConfig = {}): UILogger {\n  // By default, just print to console as JSON\n  const defaultCallback = (logEntry: any) => {\n    console.log(JSON.stringify(logEntry));\n  };\n  const transport = config.customTransport || new UILogTransport(defaultCallback);\n  const logger = new LogLayer({\n    transport,\n    consoleDebug: config.enableConsoleDebug ?? false,\n  });\n  logger.setLevel('debug');\n  return new UILogger(logger);\n}\n\nexport function createUILoggerWithCallback(callback: (logEntry: any) => void, config: UILoggerConfig = {}): UILogger {\n  const transport = new UILogTransport(callback);\n  const logger = new LogLayer({\n    transport,\n    consoleDebug: config.enableConsoleDebug ?? false,\n  });\n  logger.setLevel('debug');\n  return new UILogger(logger);\n}\n"]}

package/dist/utils/ui-logger.d.ts

@@ -0,0 +1,43 @@
+import type { ILogLayer } from 'loglayer';
+/**
+ * UI Logger: Command-Level Logging for UI Display
+ *
+ * This module provides a specialized logger for capturing command-level information
+ * that can be easily parsed and displayed in a UI. It captures details about
+ * commands, data sent, data expected, and data received in a structured format.
+ *
+ * Purpose:
+ * - Captures command-level information for UI display
+ * - Provides structured JSON logging for easy parsing
+ * - Tracks command execution details including timing
+ * - Supports protocol debugging in UI environments
+ * - Maintains separation from debug logging
+ *
+ * Design Rationale:
+ * - Single log entry per command provides clean UI display
+ * - JSON structure enables easy parsing and filtering
+ * - Command-level granularity is appropriate for UI debugging
+ * - Structured data supports rich UI representations
+ * - Separate from debug logging avoids UI noise
+ */
+/**
+ * Generic protocol step interface for UI logging
+ */
+export interface UIProtocolStep {
+    [key: string]: any;
+}
+/**
+ * UI Logger for capturing command-level information for UI display
+ */
+export declare class UILogger {
+    private logger;
+    private commandStartTimes;
+    constructor(logger: ILogLayer);
+    startCommand(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep): void;
+    logCommandSuccess(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep, context: any): void;
+    logCommandFailure(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep, error: Error, context: any): void;
+    private getCommandType;
+    private getStepDescription;
+    private getExpectedData;
+}
+//# sourceMappingURL=ui-logger.d.ts.map

package/dist/utils/ui-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-logger.d.ts","sourceRoot":"","sources":["../../src/utils/ui-logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,iBAAiB,CAA6B;gBAE1C,MAAM,EAAE,SAAS;IAI7B,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAqBlG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI;IA4CrH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI;IAkCnI,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,eAAe;CAaxB"}

package/dist/utils/ui-logger.js

@@ -0,0 +1,139 @@
+/**
+ * UI Logger for capturing command-level information for UI display
+ */
+export class UILogger {
+    logger;
+    commandStartTimes = new Map();
+    constructor(logger) {
+        this.logger = logger;
+    }
+    startCommand(stepIndex, totalSteps, operation, step) {
+        const commandId = `${operation}-${stepIndex}`;
+        const startTime = Date.now();
+        this.commandStartTimes.set(commandId, startTime);
+        const commandType = this.getCommandType(step);
+        const description = this.getStepDescription(step);
+        this.logger
+            .withMetadata({
+            commandId,
+            commandType,
+            description,
+            stepIndex,
+            totalSteps,
+            operation,
+            startTime,
+        })
+            .info('Command started');
+    }
+    logCommandSuccess(stepIndex, totalSteps, operation, step, context) {
+        const commandId = `${operation}-${stepIndex}`;
+        const startTime = this.commandStartTimes.get(commandId) || Date.now();
+        const endTime = Date.now();
+        const duration = endTime - startTime;
+        const commandType = this.getCommandType(step);
+        const description = this.getStepDescription(step);
+        // Extract sent and received data from context
+        const dataSent = context.variables?.get('lastSentData');
+        const dataReceived = context.variables?.get('lastReceivedData');
+        const dataExpected = this.getExpectedData(step);
+        // For readSegment, also extract chunk logs if present
+        let dataChunks = undefined;
+        if (commandType === 'readSegment') {
+            dataChunks = context.variables?.get('lastReadSegmentChunks');
+            // For readSegment, we don't need the flattened dataSent/dataReceived since we have dataChunks
+        }
+        // Convert dataSent and dataReceived to byte array format if they exist
+        const dataSentArray = dataSent ? Array.from(dataSent) : undefined;
+        const dataReceivedArray = dataReceived ? Array.from(dataReceived) : undefined;
+        this.logger
+            .withMetadata({
+            commandType,
+            description,
+            dataSent: dataSentArray,
+            dataExpected,
+            dataReceived: dataReceivedArray,
+            dataChunks,
+            success: true,
+            startTime,
+            endTime,
+            duration,
+            stepIndex,
+            totalSteps,
+            operation,
+        })
+            .info('Command completed successfully');
+    }
+    logCommandFailure(stepIndex, totalSteps, operation, step, error, context) {
+        const commandId = `${operation}-${stepIndex}`;
+        const startTime = this.commandStartTimes.get(commandId) || Date.now();
+        const endTime = Date.now();
+        const duration = endTime - startTime;
+        const commandType = this.getCommandType(step);
+        const description = this.getStepDescription(step);
+        // Extract sent data from context
+        const dataSent = context.variables?.get('lastSentData');
+        const dataExpected = this.getExpectedData(step);
+        // Convert dataSent to byte array format if it exists
+        const dataSentArray = dataSent ? Array.from(dataSent) : undefined;
+        this.logger
+            .withMetadata({
+            commandType,
+            description,
+            dataSent: dataSentArray,
+            dataExpected,
+            error: error.message,
+            success: false,
+            startTime,
+            endTime,
+            duration,
+            stepIndex,
+            totalSteps,
+            operation,
+        })
+            .info('Command failed');
+    }
+    getCommandType(step) {
+        if ('sendReceive' in step)
+            return 'sendReceive';
+        if ('send' in step)
+            return 'send';
+        if ('receive' in step)
+            return 'receive';
+        if ('readSegment' in step)
+            return 'readSegment';
+        if ('writeSegment' in step)
+            return 'writeSegment';
+        if ('setVariable' in step)
+            return 'setVariable';
+        return 'unknown';
+    }
+    getStepDescription(step) {
+        if ('sendReceive' in step && step.sendReceive.description)
+            return step.sendReceive.description;
+        if ('send' in step && step.send.description)
+            return step.send.description;
+        if ('receive' in step && step.receive.description)
+            return step.receive.description;
+        if ('readSegment' in step && step.readSegment.description)
+            return step.readSegment.description;
+        if ('writeSegment' in step && step.writeSegment.description)
+            return step.writeSegment.description;
+        return 'No description';
+    }
+    getExpectedData(step) {
+        if ('sendReceive' in step && step.sendReceive.receive)
+            return step.sendReceive.receive;
+        if ('receive' in step)
+            return step.receive;
+        if ('readSegment' in step) {
+            // For readSegment, return both start and end chunk receive patterns
+            return {
+                startChunk: step.readSegment.startChunk.receive,
+                endChunk: step.readSegment.endChunk.receive,
+                type: 'readSegment',
+            };
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=ui-logger.js.map

package/dist/utils/ui-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-logger.js","sourceRoot":"","sources":["../../src/utils/ui-logger.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ILogLayer } from 'loglayer';\n\n/**\n * UI Logger: Command-Level Logging for UI Display\n *\n * This module provides a specialized logger for capturing command-level information\n * that can be easily parsed and displayed in a UI. It captures details about\n * commands, data sent, data expected, and data received in a structured format.\n *\n * Purpose:\n * - Captures command-level information for UI display\n * - Provides structured JSON logging for easy parsing\n * - Tracks command execution details including timing\n * - Supports protocol debugging in UI environments\n * - Maintains separation from debug logging\n *\n * Design Rationale:\n * - Single log entry per command provides clean UI display\n * - JSON structure enables easy parsing and filtering\n * - Command-level granularity is appropriate for UI debugging\n * - Structured data supports rich UI representations\n * - Separate from debug logging avoids UI noise\n */\n\n/**\n * Generic protocol step interface for UI logging\n */\nexport interface UIProtocolStep {\n  [key: string]: any;\n}\n\n/**\n * UI Logger for capturing command-level information for UI display\n */\nexport class UILogger {\n  private logger: ILogLayer;\n  private commandStartTimes = new Map<string, number>();\n\n  constructor(logger: ILogLayer) {\n    this.logger = logger;\n  }\n\n  startCommand(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep): void {\n    const commandId = `${operation}-${stepIndex}`;\n    const startTime = Date.now();\n    this.commandStartTimes.set(commandId, startTime);\n\n    const commandType = this.getCommandType(step);\n    const description = this.getStepDescription(step);\n\n    this.logger\n      .withMetadata({\n        commandId,\n        commandType,\n        description,\n        stepIndex,\n        totalSteps,\n        operation,\n        startTime,\n      })\n      .info('Command started');\n  }\n\n  logCommandSuccess(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep, context: any): void {\n    const commandId = `${operation}-${stepIndex}`;\n    const startTime = this.commandStartTimes.get(commandId) || Date.now();\n    const endTime = Date.now();\n    const duration = endTime - startTime;\n\n    const commandType = this.getCommandType(step);\n    const description = this.getStepDescription(step);\n\n    // Extract sent and received data from context\n    const dataSent = context.variables?.get('lastSentData');\n    const dataReceived = context.variables?.get('lastReceivedData');\n    const dataExpected = this.getExpectedData(step);\n\n    // For readSegment, also extract chunk logs if present\n    let dataChunks = undefined;\n    if (commandType === 'readSegment') {\n      dataChunks = context.variables?.get('lastReadSegmentChunks');\n      // For readSegment, we don't need the flattened dataSent/dataReceived since we have dataChunks\n    }\n\n    // Convert dataSent and dataReceived to byte array format if they exist\n    const dataSentArray = dataSent ? Array.from(dataSent) : undefined;\n    const dataReceivedArray = dataReceived ? Array.from(dataReceived) : undefined;\n\n    this.logger\n      .withMetadata({\n        commandType,\n        description,\n        dataSent: dataSentArray,\n        dataExpected,\n        dataReceived: dataReceivedArray,\n        dataChunks,\n        success: true,\n        startTime,\n        endTime,\n        duration,\n        stepIndex,\n        totalSteps,\n        operation,\n      })\n      .info('Command completed successfully');\n  }\n\n  logCommandFailure(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep, error: Error, context: any): void {\n    const commandId = `${operation}-${stepIndex}`;\n    const startTime = this.commandStartTimes.get(commandId) || Date.now();\n    const endTime = Date.now();\n    const duration = endTime - startTime;\n\n    const commandType = this.getCommandType(step);\n    const description = this.getStepDescription(step);\n\n    // Extract sent data from context\n    const dataSent = context.variables?.get('lastSentData');\n    const dataExpected = this.getExpectedData(step);\n\n    // Convert dataSent to byte array format if it exists\n    const dataSentArray = dataSent ? Array.from(dataSent) : undefined;\n\n    this.logger\n      .withMetadata({\n        commandType,\n        description,\n        dataSent: dataSentArray,\n        dataExpected,\n        error: error.message,\n        success: false,\n        startTime,\n        endTime,\n        duration,\n        stepIndex,\n        totalSteps,\n        operation,\n      })\n      .info('Command failed');\n  }\n\n  private getCommandType(step: UIProtocolStep): string {\n    if ('sendReceive' in step) return 'sendReceive';\n    if ('send' in step) return 'send';\n    if ('receive' in step) return 'receive';\n    if ('readSegment' in step) return 'readSegment';\n    if ('writeSegment' in step) return 'writeSegment';\n    if ('setVariable' in step) return 'setVariable';\n    return 'unknown';\n  }\n\n  private getStepDescription(step: UIProtocolStep): string {\n    if ('sendReceive' in step && step.sendReceive.description) return step.sendReceive.description;\n    if ('send' in step && step.send.description) return step.send.description;\n    if ('receive' in step && step.receive.description) return step.receive.description;\n    if ('readSegment' in step && step.readSegment.description) return step.readSegment.description;\n    if ('writeSegment' in step && step.writeSegment.description) return step.writeSegment.description;\n    return 'No description';\n  }\n\n  private getExpectedData(step: UIProtocolStep): any {\n    if ('sendReceive' in step && step.sendReceive.receive) return step.sendReceive.receive;\n    if ('receive' in step) return step.receive;\n    if ('readSegment' in step) {\n      // For readSegment, return both start and end chunk receive patterns\n      return {\n        startChunk: step.readSegment.startChunk.receive,\n        endChunk: step.readSegment.endChunk.receive,\n        type: 'readSegment',\n      };\n    }\n    return undefined;\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springfield/ham-radio-utils",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "author": "Bryan Hunt",
   "packageManager": "yarn@4.9.2",
   "readme": "README.md",
@@ -52,7 +52,7 @@
   "dependencies": {
     "@springfield/ham-radio-api": "^14.0.0",
     "fishery": "^2.3.1",
-    "loglayer": "^6.4.2",
+    "loglayer": "^6.4.3",
     "sprintf-js": "^1.1.3"
   },
   "devDependencies": {
@@ -60,7 +60,7 @@
     "@commitlint/config-conventional": "19.8.1",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/git": "10.0.1",
-    "@semantic-release/gitlab": "13.2.5",
+    "@semantic-release/gitlab": "13.2.6",
     "@types/sprintf-js": "1.1.4",
     "husky": "9.1.7",
     "oxlint": "1.1.0",

package/src/index.ts

@@ -10,3 +10,5 @@ export * from './utils/memory-channel-utils.js';
 export * from './utils/memory-data-utils.js';
 export * from './utils/number-to-bcd.js';
 export * from './utils/to-hex-words.js';
+export * from './utils/ui-logger.js';
+export * from './utils/ui-logger-factory.js';

package/src/utils/ui-logger-factory.ts

@@ -0,0 +1,57 @@
+import { LogLayer } from 'loglayer';
+import { BaseTransport } from '@loglayer/transport';
+import { UILogger } from './ui-logger.js';
+
+/**
+ * Custom LogLayer transport for capturing UI log entries.
+ */
+class UILogTransport extends BaseTransport<any> {
+  #callback: (logEntry: any) => void;
+
+  constructor(callback: (logEntry: any) => void) {
+    // Pass a dummy logger to BaseTransport
+    super({ logger: { log: () => {} }, id: 'ui-logger-transport', enabled: true });
+    this.#callback = callback;
+  }
+
+  shipToLogger(params: any) {
+    const logEntry = {
+      timestamp: new Date().toISOString(),
+      level: params.logLevel,
+      message: params.messages.join(' '),
+      data: params.data,
+      hasData: params.hasData,
+    };
+    this.#callback(logEntry);
+    return [];
+  }
+}
+
+export interface UILoggerConfig {
+  enableConsoleDebug?: boolean;
+  customTransport?: any;
+}
+
+export function createUILogger(config: UILoggerConfig = {}): UILogger {
+  // By default, just print to console as JSON
+  const defaultCallback = (logEntry: any) => {
+    console.log(JSON.stringify(logEntry));
+  };
+  const transport = config.customTransport || new UILogTransport(defaultCallback);
+  const logger = new LogLayer({
+    transport,
+    consoleDebug: config.enableConsoleDebug ?? false,
+  });
+  logger.setLevel('debug');
+  return new UILogger(logger);
+}
+
+export function createUILoggerWithCallback(callback: (logEntry: any) => void, config: UILoggerConfig = {}): UILogger {
+  const transport = new UILogTransport(callback);
+  const logger = new LogLayer({
+    transport,
+    consoleDebug: config.enableConsoleDebug ?? false,
+  });
+  logger.setLevel('debug');
+  return new UILogger(logger);
+}

package/src/utils/ui-logger.ts

@@ -0,0 +1,174 @@
+import type { ILogLayer } from 'loglayer';
+
+/**
+ * UI Logger: Command-Level Logging for UI Display
+ *
+ * This module provides a specialized logger for capturing command-level information
+ * that can be easily parsed and displayed in a UI. It captures details about
+ * commands, data sent, data expected, and data received in a structured format.
+ *
+ * Purpose:
+ * - Captures command-level information for UI display
+ * - Provides structured JSON logging for easy parsing
+ * - Tracks command execution details including timing
+ * - Supports protocol debugging in UI environments
+ * - Maintains separation from debug logging
+ *
+ * Design Rationale:
+ * - Single log entry per command provides clean UI display
+ * - JSON structure enables easy parsing and filtering
+ * - Command-level granularity is appropriate for UI debugging
+ * - Structured data supports rich UI representations
+ * - Separate from debug logging avoids UI noise
+ */
+
+/**
+ * Generic protocol step interface for UI logging
+ */
+export interface UIProtocolStep {
+  [key: string]: any;
+}
+
+/**
+ * UI Logger for capturing command-level information for UI display
+ */
+export class UILogger {
+  private logger: ILogLayer;
+  private commandStartTimes = new Map<string, number>();
+
+  constructor(logger: ILogLayer) {
+    this.logger = logger;
+  }
+
+  startCommand(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep): void {
+    const commandId = `${operation}-${stepIndex}`;
+    const startTime = Date.now();
+    this.commandStartTimes.set(commandId, startTime);
+
+    const commandType = this.getCommandType(step);
+    const description = this.getStepDescription(step);
+
+    this.logger
+      .withMetadata({
+        commandId,
+        commandType,
+        description,
+        stepIndex,
+        totalSteps,
+        operation,
+        startTime,
+      })
+      .info('Command started');
+  }
+
+  logCommandSuccess(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep, context: any): void {
+    const commandId = `${operation}-${stepIndex}`;
+    const startTime = this.commandStartTimes.get(commandId) || Date.now();
+    const endTime = Date.now();
+    const duration = endTime - startTime;
+
+    const commandType = this.getCommandType(step);
+    const description = this.getStepDescription(step);
+
+    // Extract sent and received data from context
+    const dataSent = context.variables?.get('lastSentData');
+    const dataReceived = context.variables?.get('lastReceivedData');
+    const dataExpected = this.getExpectedData(step);
+
+    // For readSegment, also extract chunk logs if present
+    let dataChunks = undefined;
+    if (commandType === 'readSegment') {
+      dataChunks = context.variables?.get('lastReadSegmentChunks');
+      // For readSegment, we don't need the flattened dataSent/dataReceived since we have dataChunks
+    }
+
+    // Convert dataSent and dataReceived to byte array format if they exist
+    const dataSentArray = dataSent ? Array.from(dataSent) : undefined;
+    const dataReceivedArray = dataReceived ? Array.from(dataReceived) : undefined;
+
+    this.logger
+      .withMetadata({
+        commandType,
+        description,
+        dataSent: dataSentArray,
+        dataExpected,
+        dataReceived: dataReceivedArray,
+        dataChunks,
+        success: true,
+        startTime,
+        endTime,
+        duration,
+        stepIndex,
+        totalSteps,
+        operation,
+      })
+      .info('Command completed successfully');
+  }
+
+  logCommandFailure(stepIndex: number, totalSteps: number, operation: string, step: UIProtocolStep, error: Error, context: any): void {
+    const commandId = `${operation}-${stepIndex}`;
+    const startTime = this.commandStartTimes.get(commandId) || Date.now();
+    const endTime = Date.now();
+    const duration = endTime - startTime;
+
+    const commandType = this.getCommandType(step);
+    const description = this.getStepDescription(step);
+
+    // Extract sent data from context
+    const dataSent = context.variables?.get('lastSentData');
+    const dataExpected = this.getExpectedData(step);
+
+    // Convert dataSent to byte array format if it exists
+    const dataSentArray = dataSent ? Array.from(dataSent) : undefined;
+
+    this.logger
+      .withMetadata({
+        commandType,
+        description,
+        dataSent: dataSentArray,
+        dataExpected,
+        error: error.message,
+        success: false,
+        startTime,
+        endTime,
+        duration,
+        stepIndex,
+        totalSteps,
+        operation,
+      })
+      .info('Command failed');
+  }
+
+  private getCommandType(step: UIProtocolStep): string {
+    if ('sendReceive' in step) return 'sendReceive';
+    if ('send' in step) return 'send';
+    if ('receive' in step) return 'receive';
+    if ('readSegment' in step) return 'readSegment';
+    if ('writeSegment' in step) return 'writeSegment';
+    if ('setVariable' in step) return 'setVariable';
+    return 'unknown';
+  }
+
+  private getStepDescription(step: UIProtocolStep): string {
+    if ('sendReceive' in step && step.sendReceive.description) return step.sendReceive.description;
+    if ('send' in step && step.send.description) return step.send.description;
+    if ('receive' in step && step.receive.description) return step.receive.description;
+    if ('readSegment' in step && step.readSegment.description) return step.readSegment.description;
+    if ('writeSegment' in step && step.writeSegment.description) return step.writeSegment.description;
+    return 'No description';
+  }
+
+  private getExpectedData(step: UIProtocolStep): any {
+    if ('sendReceive' in step && step.sendReceive.receive) return step.sendReceive.receive;
+    if ('receive' in step) return step.receive;
+    if ('readSegment' in step) {
+      // For readSegment, return both start and end chunk receive patterns
+      return {
+        startChunk: step.readSegment.startChunk.receive,
+        endChunk: step.readSegment.endChunk.receive,
+        type: 'readSegment',
+      };
+    }
+    return undefined;
+  }
+}