sfcc-dev-mcp 1.0.19 → 1.0.21

package/ai-instructions/skills/sfcc-logging/SKILL.md

@@ -1,352 +0,0 @@
----
-name: sfcc-logging
-description: Guide for implementing logging in Salesforce B2C Commerce scripts
----
-
-# Logging Skill
-
-This skill guides you through implementing logging in B2C Commerce using the Logger and Log classes.
-
-## Overview
-
-B2C Commerce provides a logging framework with:
-
-| Feature | Description |
-|---------|-------------|
-| **Log Levels** | debug, info, warn, error, fatal |
-| **Categories** | Organize logs by functional area |
-| **Custom Files** | Write to dedicated log files |
-| **NDC** | Nested Diagnostic Context for tracing |
-| **BM Configuration** | Enable/disable levels per category |
-
-## Log Levels
-
-| Level | Method | Description | Default State |
-|-------|--------|-------------|---------------|
-| `debug` | `debug()` | Detailed debugging information | Disabled (never on production) |
-| `info` | `info()` | General information | Disabled by default |
-| `warn` | `warn()` | Warning conditions | Always enabled |
-| `error` | `error()` | Error conditions | Always enabled |
-| `fatal` | `fatal()` | Critical failures | Always enabled, can send email |
-
-## Basic Logging
-
-### Using Logger (Static Methods)
-
-The `Logger` class provides static methods for quick logging:
-
-```javascript
-var Logger = require('dw/system/Logger');
-
-// Simple messages
-Logger.debug('Debug message');
-Logger.info('Info message');
-Logger.warn('Warning message');
-Logger.error('Error message');
-
-// Messages with parameters (Java MessageFormat syntax)
-Logger.info('Processing order {0} for customer {1}', orderNo, customerEmail);
-Logger.error('Failed to process {0}: {1}', productId, errorMessage);
-```
-
-### Using Log (Instance Methods)
-
-The `Log` class provides instance-based logging with categories:
-
-```javascript
-var Logger = require('dw/system/Logger');
-
-// Get logger for a category
-var log = Logger.getLogger('checkout');
-
-log.debug('Cart contents: {0}', JSON.stringify(cart));
-log.info('Checkout started for basket {0}', basketId);
-log.warn('Inventory low for product {0}', productId);
-log.error('Payment failed: {0}', errorMessage);
-log.fatal('Critical checkout failure: {0}', errorMessage);
-```
-
-## Categories
-
-Categories help organize and filter log messages:
-
-```javascript
-var Logger = require('dw/system/Logger');
-
-// Different categories for different areas
-var checkoutLog = Logger.getLogger('checkout');
-var paymentLog = Logger.getLogger('payment');
-var inventoryLog = Logger.getLogger('inventory');
-var integrationLog = Logger.getLogger('integration');
-
-// Use appropriate logger
-checkoutLog.info('Order {0} submitted', orderNo);
-paymentLog.info('Payment authorized: {0}', transactionId);
-inventoryLog.warn('Stock level below threshold for {0}', productId);
-integrationLog.error('API call failed: {0}', serviceName);
-```
-
-Categories are configured in Business Manager under **Administration > Operations > Custom Log Settings**.
-
-## Custom Named Log Files
-
-Write to dedicated log files instead of the standard custom log files:
-
-```javascript
-var Logger = require('dw/system/Logger');
-
-// Get logger with custom file prefix
-var orderExportLog = Logger.getLogger('export', 'orderexport');
-var feedLog = Logger.getLogger('feed', 'productfeed');
-
-// Messages go to custom-orderexport-*.log
-orderExportLog.info('Exporting order {0}', orderNo);
-
-// Messages go to custom-productfeed-*.log
-feedLog.info('Processing product {0}', productId);
-```
-
-### File Name Rules
-
-The `fileNamePrefix` parameter must follow these rules:
-
-| Rule | Requirement |
-|------|-------------|
-| Length | 3-25 characters |
-| Characters | a-z, A-Z, 0-9, `-`, `_` |
-| Start/End | Must start and end with alphanumeric |
-| Not allowed | Cannot start or end with `-` or `_` |
-
-### File Naming Pattern
-
-Custom log files follow this pattern:
-```
-custom-<prefix>-<hostname>-appserver-<date>.log
-```
-
-Example: `custom-orderexport-blade0-1-appserver-20240115.log`
-
-### Quota
-
-Maximum 200 different log file names per day per appserver.
-
-## Checking Log Level Status
-
-Check if a log level is enabled before expensive operations:
-
-```javascript
-var Logger = require('dw/system/Logger');
-var log = Logger.getLogger('myCategory');
-
-// Check before expensive string building
-if (log.isDebugEnabled()) {
-    log.debug('Full cart contents: {0}', JSON.stringify(cart));
-}
-
-// Check before expensive calculations
-if (log.isInfoEnabled()) {
-    var stats = calculateDetailedStats(); // expensive
-    log.info('Statistics: {0}', JSON.stringify(stats));
-}
-
-// Available checks
-log.isDebugEnabled();  // true if debug logging enabled
-log.isInfoEnabled();   // true if info logging enabled
-log.isWarnEnabled();   // true if warn logging enabled
-log.isErrorEnabled();  // true if error logging enabled
-```
-
-### Static Level Checks
-
-```javascript
-var Logger = require('dw/system/Logger');
-
-if (Logger.isDebugEnabled()) {
-    Logger.debug('Debug message');
-}
-```
-
-## Message Formatting
-
-Messages support Java MessageFormat syntax:
-
-```javascript
-var Logger = require('dw/system/Logger');
-var log = Logger.getLogger('order');
-
-// Positional parameters
-log.info('Order {0} has {1} items totaling {2}', orderNo, itemCount, total);
-
-// Same parameter multiple times
-log.info('Product {0}: {0} is out of stock', productId);
-
-// Complex objects (use JSON.stringify for objects)
-log.debug('Request: {0}', JSON.stringify(requestData));
-```
-
-## Nested Diagnostic Context (NDC)
-
-NDC helps trace related log messages across a request:
-
-```javascript
-var Logger = require('dw/system/Logger');
-var Log = require('dw/system/Log');
-
-var log = Logger.getLogger('checkout');
-var ndc = Log.getNDC();
-
-function processOrder(orderId) {
-    // Push context onto the stack
-    ndc.push('Order:' + orderId);
-
-    try {
-        log.info('Starting order processing');
-        processPayment();
-        processShipping();
-        log.info('Order processing complete');
-    } finally {
-        // Always pop context when leaving scope
-        ndc.pop();
-    }
-}
-
-function processPayment() {
-    ndc.push('Payment');
-    try {
-        log.info('Processing payment'); // NDC shows: Order:123 Payment
-    } finally {
-        ndc.pop();
-    }
-}
-```
-
-### NDC Methods
-
-| Method | Description |
-|--------|-------------|
-| `push(message)` | Add context to the stack |
-| `pop()` | Remove and return top context |
-| `peek()` | View top context without removing |
-| `remove()` | Clear entire context |
-
-## Best Practices
-
-### 1. Use Categories
-
-```javascript
-// Good: Organized by functional area
-var log = Logger.getLogger('payment.processor');
-var log = Logger.getLogger('inventory.sync');
-var log = Logger.getLogger('order.export');
-
-// Avoid: No category
-Logger.info('Something happened');
-```
-
-### 2. Check Level Before Expensive Operations
-
-```javascript
-// Good: Check before building expensive string
-if (log.isDebugEnabled()) {
-    log.debug('Full response: {0}', JSON.stringify(largeObject));
-}
-
-// Avoid: Always building expensive strings
-log.debug('Full response: {0}', JSON.stringify(largeObject));
-```
-
-### 3. Include Context in Messages
-
-```javascript
-// Good: Includes relevant context
-log.error('Payment failed for order {0}, customer {1}: {2}',
-    orderNo, customerId, errorMessage);
-
-// Avoid: Missing context
-log.error('Payment failed');
-```
-
-### 4. Use Appropriate Levels
-
-```javascript
-// debug: Detailed technical information
-log.debug('SQL query: {0}', query);
-log.debug('API request body: {0}', JSON.stringify(body));
-
-// info: Notable events
-log.info('Order {0} placed successfully', orderNo);
-log.info('Customer {0} logged in', customerId);
-
-// warn: Potential issues
-log.warn('Inventory low for product {0}: {1} remaining', productId, qty);
-log.warn('Slow API response: {0}ms', responseTime);
-
-// error: Failures that need attention
-log.error('Payment declined for order {0}: {1}', orderNo, reason);
-log.error('Failed to connect to service {0}: {1}', serviceName, error);
-
-// fatal: Critical system failures
-log.fatal('Database connection lost');
-log.fatal('Critical configuration missing: {0}', configKey);
-```
-
-### 5. Use Custom Log Files for Integration
-
-```javascript
-// Dedicated files for each integration
-var erpLog = Logger.getLogger('erp-sync', 'erp');
-var omsLog = Logger.getLogger('oms-export', 'oms');
-var crmLog = Logger.getLogger('crm-sync', 'crm');
-```
-
-### 6. Don't Log Sensitive Data
-
-```javascript
-// Good: Mask sensitive data
-log.info('Payment processed for card ending in {0}', cardNumber.slice(-4));
-
-// Avoid: Logging sensitive data
-log.info('Payment processed for card {0}', cardNumber);
-```
-
-## Business Manager Configuration
-
-Configure custom logging in **Administration > Operations > Custom Log Settings**:
-
-| Setting | Description |
-|---------|-------------|
-| **Log to File** | Enable file logging for each level |
-| **Receive Email** | Email addresses for fatal notifications |
-| **Root Category** | Default settings for all categories |
-| **Custom Categories** | Override settings per category |
-
-### Configuring Categories
-
-1. Go to **Custom Log Settings**
-2. Click **Add Category**
-3. Enter category name (e.g., `checkout`, `payment`)
-4. Set log levels to enable
-
-## Log Output Format
-
-Log entries follow this format:
-```
-[timestamp] [level] [category] message
-```
-
-Example:
-```
-[2024-01-15 10:30:45.123 GMT] [INFO] [checkout] Order ORD123 placed successfully
-```
-
-## Detailed Reference
-
-- [Log Files](references/LOG-FILES.md) - Log file types, locations, and retention
-
-## Script API Classes
-
-| Class | Description |
-|-------|-------------|
-| `dw.system.Logger` | Static logging methods and logger factory |
-| `dw.system.Log` | Logger instance with category support |
-| `dw.system.LogNDC` | Nested Diagnostic Context for tracing |

package/ai-instructions/skills/sfcc-logging/references/LOG-FILES.md

@@ -1,282 +0,0 @@
-# Log Files Reference
-
-Complete reference for B2C Commerce log file types, locations, and management.
-
-## Log File Types
-
-### Custom Log Files
-
-Custom log files are generated by script logging:
-
-| Log File | Trigger | Default State |
-|----------|---------|---------------|
-| `customdebug` | `Logger.debug()` or `log.debug()` | Disabled |
-| `custominfo` | `Logger.info()` or `log.info()` | Disabled |
-| `customwarn` | `Logger.warn()` or `log.warn()` | Always enabled |
-| `customerror` | `Logger.error()` or `log.error()` | Always enabled |
-| `customfatal` | `log.fatal()` | Always enabled |
-
-### System Log Files
-
-System log files are generated by the platform:
-
-| Log File | Description |
-|----------|-------------|
-| `error` | System errors in scripts, templates, and platform |
-| `warn` | Lock status, slot warnings, servlet warnings |
-| `info` | System information from scripts and platform |
-| `debug` | Debug information (only when debug flag enabled) |
-| `fatal` | Critical system failures |
-| `api` | API problems and violations |
-| `deprecation` | Usage of deprecated APIs |
-| `jobs` | Job status information |
-| `staging` | Replication process information |
-| `quota` | Quota warnings and limits |
-| `sql` | SQL and replication issues |
-| `syslog` | API processing, staging, import/export info |
-| `sysevent` | Appserver registration, cartridge logs |
-| `analytics` | Analytics activity and errors |
-| `performance` | Internal performance data |
-| `console` | Internal console entries |
-| `migration` | Internal migration data |
-| `dbinit-sql` | SQL used during database initialization |
-
-### Custom Named Log Files
-
-Files created with `Logger.getLogger(prefix, category)`:
-
-```
-custom-<prefix>-<hostname>-appserver-<date>.log
-```
-
-Example: `custom-orderexport-blade0-1-appserver-20240115.log`
-
-## Log File Locations
-
-### WebDAV Access
-
-**Logs Directory:**
-```
-https://<instance>.demandware.net/on/demandware.servlet/webdav/Sites/Logs
-```
-
-**Security Logs:**
-```
-https://<instance>.demandware.net/on/demandware.servlet/webdav/Sites/Securitylogs
-```
-
-**Import/Export Logs:**
-```
-https://<instance>.demandware.net/on/demandware.servlet/webdav/Sites/Impex/log
-```
-
-### Business Manager Access
-
-1. **Administration > Site Development > Development Setup**
-2. Scroll to **WebDAV Access** section
-3. Click **Log files** link
-
-## Log Retention
-
-| Environment | Retention | Notes |
-|-------------|-----------|-------|
-| Production | 30 days | Auto-deleted after retention |
-| Staging | 30 days | Auto-deleted after retention |
-| Development | Not defined | Manual cleanup recommended |
-| Sandbox | Not defined | Manual cleanup recommended |
-
-**Security logs** are retained for 90 days.
-
-### Archive Process
-
-- After 3 days, logs move to `log_archive` directory
-- Archived logs are compressed to gzip format
-- Download logs locally for longer retention
-
-## Storage Limits
-
-### Custom Log Size Limits
-
-| Limit | Value |
-|-------|-------|
-| Per log level per day | 10 MB |
-| Per application server | Per log type |
-| Custom named log files | Same 10 MB limit |
-
-When the limit is reached:
-```
-+++++++++++ Maximum log file size per day reached, logging suspended. +++++++++++
-```
-
-Logging resumes at 00:00 GMT the next day.
-
-### File Count Limits
-
-- Maximum 100,000 files per folder
-- Excess files deleted starting with oldest
-- Applies per folder, not across subfolders
-
-### Custom Log File Quota
-
-- Maximum 200 different log file prefixes per day
-- Per application server
-- Hard limit (throws exception when exceeded)
-
-## Log Entry Format
-
-### Standard Format
-
-```
-[timestamp GMT] [level] [category] message
-```
-
-Example:
-```
-[2024-01-15 10:30:45.123 GMT] [INFO] [checkout] Order ORD123 submitted
-```
-
-### With NDC
-
-```
-[timestamp GMT] [level] [category] [ndc-context] message
-```
-
-Example:
-```
-[2024-01-15 10:30:45.123 GMT] [INFO] [checkout] [Order:123 Payment] Processing payment
-```
-
-## Redundancy Tracking
-
-Error and Warning messages are tracked for redundancy:
-
-- Messages appearing > 10 times in 3 minutes are suppressed
-- Suppression lasts 3 minutes
-- Suppression message:
-
-```
-The following message was generated more than 10 times within the last 180 seconds.
-It will be suppressed for 180 seconds:
-<original message>
-```
-
-## Quota Log Format
-
-Quota logs show when thresholds or limits are exceeded:
-
-```
-[timestamp] [thread-info] Quota quota.name (enforced, warn threshold, limit):
-warn threshold exceeded N time(s), max actual was X, current location: details
-```
-
-Example:
-```
-[2024-01-15 13:00:22.577 GMT] [RequestHandlerServlet|14320460|Sites-MySite|Product-Show|...]
-Quota api.jsStringLength (enforced, warn 600000, limit 1000000): warn threshold exceeded 1 time(s),
-max actual was 600010, current location: request/site Sites-MySite/top pipeline Product-Show/
-interaction node/template default.CustomDisplay
-```
-
-## Security Log Format
-
-```
-[timestamp GMT][dw-sec] (User: 'username' (realm), IP: x.x.x.x [ACTION] : details)
-```
-
-Example:
-```
-[2024-01-15 02:23:19.139 GMT][dw-sec] (User: 'admin' (Sites), IP: 192.168.1.1 [LOGIN] : logged in.)
-```
-
-Actions logged:
-- LOGIN
-- LOGOUT
-- LOGIN_FAILED
-- PASSWORD_CHANGED
-- Re-login (session timeout)
-
-## Import/Export Logs
-
-Located in `/Impex/log/`:
-
-| Log Type | Description |
-|----------|-------------|
-| Catalog | Catalog import/export logs |
-| Customer | Customer batch processing logs |
-| Inventory | Inventory import logs |
-| Price Book | Price book import/validation logs |
-| Promotion | Promotion validation logs |
-| Metadata | Metadata validation logs |
-| Coupon | Coupon validation logs |
-
-Example path:
-```
-/Impex/log/Batch-Customer-20240115192425062.log
-```
-
-## Accessing Logs Programmatically
-
-### Via WebDAV Client
-
-Configure your WebDAV client with:
-- URL: `https://<instance>/on/demandware.servlet/webdav/Sites/Logs`
-- User: Business Manager username
-- Password: Business Manager password
-
-### Via MCP Tools
-
-Use the SFCC Dev MCP Server log tools:
-- `get_latest_error` - Recent error messages
-- `get_latest_debug` - Recent debug messages
-- `get_latest_info` - Recent info messages
-- `get_latest_warn` - Recent warning messages
-- `search_logs` - Search for patterns in logs
-- `summarize_logs` - Health overview of log activity
-
-## Debug Logging on Production
-
-Debug logging is **never enabled on production instances**.
-
-On non-production instances:
-- Debug logs are "in-memory" by default
-- Enables "Show Request Log" feature
-- Does not generate log files unless explicitly enabled
-
-## Best Practices
-
-### 1. Monitor Log File Sizes
-
-Check log sizes regularly to avoid hitting limits:
-- 10 MB per custom log type per day
-- Monitor during high-traffic periods
-
-### 2. Use Custom Named Logs for Integrations
-
-```javascript
-// Separate files for each integration
-var erpLog = Logger.getLogger('erp-sync', 'erp');
-var paymentLog = Logger.getLogger('payment-gateway', 'payment');
-```
-
-### 3. Clean Up Old Logs
-
-- Delete unnecessary logs promptly
-- Don't exceed 100,000 files per folder
-- Download and archive important logs locally
-
-### 4. Configure Categories in Business Manager
-
-1. Go to **Administration > Operations > Custom Log Settings**
-2. Add categories for your code areas
-3. Enable appropriate log levels per category
-4. Set up fatal email notifications
-
-### 5. Use Appropriate Log Levels
-
-| Level | Use For |
-|-------|---------|
-| debug | Development debugging only |
-| info | Notable events, job progress |
-| warn | Recoverable issues, slow operations |
-| error | Failures requiring attention |
-| fatal | Critical failures, email notification |