@salesforce/b2c-tooling-sdk 0.2.1 → 0.4.0

package/dist/cjs/operations/logs/path-normalizer.js

@@ -0,0 +1,190 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Path normalization for B2C Commerce log files.
+ *
+ * Converts remote cartridge paths in log messages to local paths
+ * for IDE click-to-open functionality.
+ */
+import path from 'node:path';
+import { findCartridges } from '../code/cartridges.js';
+/**
+ * Patterns for matching cartridge paths in various contexts.
+ *
+ * B2C Commerce log files can contain paths in various formats:
+ * - In parentheses: (app_storefront/cartridge/controllers/Home.js:45)
+ * - In quotes: 'app_storefront/cartridge/controllers/Home.js:45'
+ * - In stack traces: at app_storefront/cartridge/controllers/Home.js:45
+ * - Plain paths: app_storefront/cartridge/controllers/Home.js:45
+ */
+const PATH_PATTERNS = [
+    // Parentheses: (cartridge_name/cartridge/path/file.js:line)
+    {
+        pattern: /\(([a-zA-Z0-9_-]+\/cartridge\/[^)]+)\)/g,
+        context: 'parentheses',
+        extractPath: (match) => match[1],
+        buildReplacement: (match, normalizedPath) => `(${normalizedPath})`,
+    },
+    // Single quotes: 'cartridge_name/cartridge/path/file.js:line'
+    {
+        pattern: /'([a-zA-Z0-9_-]+\/cartridge\/[^']+)'/g,
+        context: 'quotes',
+        extractPath: (match) => match[1],
+        buildReplacement: (match, normalizedPath) => `'${normalizedPath}'`,
+    },
+    // Double quotes: "cartridge_name/cartridge/path/file.js:line"
+    {
+        pattern: /"([a-zA-Z0-9_-]+\/cartridge\/[^"]+)"/g,
+        context: 'quotes',
+        extractPath: (match) => match[1],
+        buildReplacement: (match, normalizedPath) => `"${normalizedPath}"`,
+    },
+    // Stack trace: at cartridge_name/cartridge/path/file.js:line
+    {
+        pattern: /at\s+([a-zA-Z0-9_-]+\/cartridge\/[^\s]+)/g,
+        context: 'stacktrace',
+        extractPath: (match) => match[1],
+        buildReplacement: (match, normalizedPath) => `at ${normalizedPath}`,
+    },
+];
+/**
+ * Creates a path normalizer function for converting remote cartridge paths
+ * to local paths in log messages.
+ *
+ * Supports two modes:
+ * 1. **Cartridge mappings** (precise): Uses discovered cartridges to map each
+ *    cartridge name to its actual local path. Best for projects with cartridges
+ *    in different locations.
+ * 2. **Cartridge path** (simple): Prefixes all paths with a base directory.
+ *    Best when all cartridges are in a single directory.
+ *
+ * @param options - Normalizer options
+ * @returns Function that normalizes paths in a message string, or undefined if no options provided
+ *
+ * @example
+ * ```typescript
+ * // Using discovered cartridges (recommended)
+ * const cartridges = findCartridges('./my-project');
+ * const normalize = createPathNormalizer({ cartridges });
+ *
+ * // Using simple cartridge path
+ * const normalize = createPathNormalizer({ cartridgePath: './cartridges' });
+ *
+ * // Input: "(app_storefront/cartridge/controllers/Home.js:45)"
+ * // Output: "(./cartridges/app_storefront/cartridge/controllers/Home.js:45)"
+ * const normalized = normalize(logMessage);
+ * ```
+ */
+export function createPathNormalizer(options) {
+    const { cartridgePath, cartridges } = options;
+    // If no options provided, return undefined
+    if (!cartridgePath && (!cartridges || cartridges.length === 0)) {
+        return undefined;
+    }
+    // Build a map of cartridge names to their local paths
+    const cartridgeMap = new Map();
+    if (cartridges) {
+        for (const c of cartridges) {
+            cartridgeMap.set(c.name, c.src);
+        }
+    }
+    // Normalize the fallback cartridge path (remove trailing slash)
+    const normalizedCartridgePath = cartridgePath?.replace(/\/+$/, '');
+    return (message) => {
+        let result = message;
+        for (const { pattern, extractPath, buildReplacement } of PATH_PATTERNS) {
+            // Create a fresh regex for each message (stateful with /g flag)
+            const regex = new RegExp(pattern.source, pattern.flags);
+            result = result.replace(regex, (...args) => {
+                // The full match is the first arg, captured groups follow
+                const match = args;
+                const remotePath = extractPath(match);
+                // Extract cartridge name from the path (first segment before /cartridge/)
+                const cartridgeName = remotePath.split('/')[0];
+                const restOfPath = remotePath.substring(cartridgeName.length);
+                // Try to find the cartridge in our mappings
+                const localCartridgePath = cartridgeMap.get(cartridgeName);
+                let localPath;
+                if (localCartridgePath) {
+                    // Use the discovered cartridge's actual path
+                    localPath = `${localCartridgePath}${restOfPath}`;
+                }
+                else if (normalizedCartridgePath) {
+                    // Fall back to simple prefix mode
+                    localPath = `${normalizedCartridgePath}/${remotePath}`;
+                }
+                else {
+                    // No mapping and no fallback - return original
+                    return match[0];
+                }
+                return buildReplacement(match, localPath);
+            });
+        }
+        return result;
+    };
+}
+/**
+ * Discovers cartridges and creates a path normalizer automatically.
+ *
+ * This is a convenience function that combines `findCartridges` with
+ * `createPathNormalizer` for easy setup. Cartridge paths are converted
+ * to relative paths from the current working directory.
+ *
+ * @param directory - Directory to search for cartridges (defaults to cwd)
+ * @returns Path normalizer function, or undefined if no cartridges found
+ *
+ * @example
+ * ```typescript
+ * // Auto-discover cartridges from current directory
+ * const normalize = discoverAndCreateNormalizer();
+ *
+ * // Auto-discover from specific directory
+ * const normalize = discoverAndCreateNormalizer('./my-project');
+ * ```
+ */
+export function discoverAndCreateNormalizer(directory) {
+    const searchDir = directory ?? process.cwd();
+    const cwd = process.cwd();
+    const cartridges = findCartridges(searchDir);
+    if (cartridges.length === 0) {
+        return undefined;
+    }
+    // Convert absolute paths to relative paths from cwd
+    const relativeCartridges = cartridges.map((c) => ({
+        ...c,
+        src: './' + path.relative(cwd, c.src),
+    }));
+    return createPathNormalizer({ cartridges: relativeCartridges });
+}
+/**
+ * Extracts all cartridge paths from a message.
+ *
+ * Useful for testing or analysis of log messages.
+ *
+ * @param message - Log message to extract paths from
+ * @returns Array of extracted paths
+ *
+ * @example
+ * ```typescript
+ * const paths = extractPaths("Error at (app_storefront/cartridge/controllers/Home.js:45)");
+ * // Returns: ["app_storefront/cartridge/controllers/Home.js:45"]
+ * ```
+ */
+export function extractPaths(message) {
+    const paths = [];
+    for (const { pattern, extractPath } of PATH_PATTERNS) {
+        const regex = new RegExp(pattern.source, pattern.flags);
+        let match;
+        while ((match = regex.exec(message)) !== null) {
+            const path = extractPath(match);
+            if (!paths.includes(path)) {
+                paths.push(path);
+            }
+        }
+    }
+    return paths;
+}
+//# sourceMappingURL=path-normalizer.js.map

package/dist/cjs/operations/logs/path-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-normalizer.js","sourceRoot":"","sources":["../../../../src/operations/logs/path-normalizer.ts"],"names":[],"mappings":"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"}

package/dist/cjs/operations/logs/tail.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Log tailing operations for B2C Commerce.
+ */
+import type { B2CInstance } from '../../instance/index.js';
+import type { GetRecentLogsOptions, LogEntry, TailLogsOptions, TailLogsResult } from './types.js';
+/**
+ * Parses the first line of a log entry to extract timestamp, level, and message.
+ *
+ * Expected format: [timestamp GMT] LEVEL context - message
+ * Example: [2025-01-25 10:30:45.123 GMT] ERROR PipelineCallServlet|... - Error message
+ *
+ * The message field will contain:
+ * - The content portion from the first line (after LEVEL)
+ * - Plus any continuation lines (stack traces, etc.)
+ *
+ * @param firstLine - First line of the log entry
+ * @param file - File name the entry came from
+ * @param fullMessage - Complete raw message including all lines
+ * @param pathNormalizer - Optional function to normalize paths in the message
+ * @returns Parsed log entry
+ */
+export declare function parseLogEntry(firstLine: string, file: string, fullMessage: string, pathNormalizer?: (msg: string) => string): LogEntry;
+/**
+ * Splits content into lines, handling incomplete lines at boundaries.
+ * Uses TextDecoder with stream mode for proper UTF-8 multi-byte character handling.
+ *
+ * @param content - ArrayBuffer content
+ * @param decoder - TextDecoder instance (should be reused for streaming)
+ * @param isComplete - Whether this is the final chunk (flush decoder)
+ * @returns Array of complete lines (without trailing incomplete line)
+ */
+export declare function splitLines(content: ArrayBuffer, decoder: InstanceType<typeof TextDecoder>, isComplete?: boolean): string[];
+/**
+ * Aggregates lines into multi-line log entries.
+ *
+ * B2C log entries can span multiple lines. A new entry starts when a line
+ * begins with a timestamp pattern: [YYYY-MM-DD HH:MM:SS.mmm GMT]
+ *
+ * @param lines - Array of individual lines
+ * @param pendingLines - Lines carried over from previous chunk (incomplete entry)
+ * @returns Object with complete entries and any pending lines for next chunk
+ */
+export declare function aggregateLogEntries(lines: string[], pendingLines?: string[]): {
+    entries: string[][];
+    pending: string[];
+};
+/**
+ * Tails log files on a B2C Commerce instance.
+ *
+ * Continuously polls for new log content using HTTP Range requests for efficiency.
+ * Calls the onEntry callback for each new log line.
+ *
+ * @param instance - B2C instance to tail logs from
+ * @param options - Tailing options (filters, callbacks, polling interval)
+ * @returns Tail result with stop() control and done promise
+ *
+ * @example
+ * ```typescript
+ * const result = await tailLogs(instance, {
+ *   prefixes: ['error', 'customerror'],
+ *   onEntry: (entry) => console.log(`[${entry.file}] ${entry.message}`),
+ *   onError: (err) => console.error('Tail error:', err),
+ * });
+ *
+ * // Stop after 10 seconds
+ * setTimeout(() => result.stop(), 10000);
+ *
+ * // Wait for tailing to complete
+ * await result.done;
+ * ```
+ */
+export declare function tailLogs(instance: B2CInstance, options?: TailLogsOptions): Promise<TailLogsResult>;
+/**
+ * Gets recent log entries (one-shot retrieval).
+ *
+ * Useful for MCP server integration or programmatic access without continuous tailing.
+ * Reads the tail end of log files and returns parsed entries.
+ *
+ * @param instance - B2C instance to get logs from
+ * @param options - Retrieval options
+ * @returns Array of recent log entries
+ *
+ * @example
+ * ```typescript
+ * // Get the last 50 error entries
+ * const entries = await getRecentLogs(instance, {
+ *   prefixes: ['error'],
+ *   maxEntries: 50
+ * });
+ * ```
+ */
+export declare function getRecentLogs(instance: B2CInstance, options?: GetRecentLogsOptions): Promise<LogEntry[]>;