sfcc-dev-mcp 1.0.15 → 1.0.19

package/src/core/handlers/job-log-handler.ts

@@ -1,21 +1,32 @@
-import { AbstractLogToolHandler } from './abstract-log-tool-handler.js';
-import { HandlerContext } from './base-handler.js';
-import { GenericToolSpec } from './base-handler.js';
-import { ToolArguments } from './base-handler.js';
+import { GenericToolSpec, ToolArguments, HandlerContext } from './base-handler.js';
+import { AbstractClientHandler } from './abstract-client-handler.js';
+import { ClientFactory } from './client-factory.js';
+import { SFCCLogClient } from '../../clients/logs/index.js';
 import { JOB_LOG_TOOL_CONFIG } from '../../tool-configs/job-log-tool-config.js';
 import { JOB_LOG_TOOL_NAMES_SET, JobLogToolName } from '../../utils/log-tool-constants.js';
 
 /**
  * Handler for job-specific log tools using config-driven dispatch
- * Separates job log operations from standard log operations for better maintainability
  */
-export class JobLogToolHandler extends AbstractLogToolHandler<JobLogToolName> {
+export class JobLogToolHandler extends AbstractClientHandler<JobLogToolName, SFCCLogClient> {
   constructor(context: HandlerContext, subLoggerName: string) {
     super(context, subLoggerName);
   }
 
-  canHandle(toolName: string): boolean {
-    return JOB_LOG_TOOL_NAMES_SET.has(toolName as JobLogToolName);
+  protected createClient(): SFCCLogClient | null {
+    return this.clientFactory.createLogClient();
+  }
+
+  protected getClientContextKey(): string {
+    return 'logClient';
+  }
+
+  protected getClientDisplayName(): string {
+    return 'Log';
+  }
+
+  protected getClientRequiredError(): string {
+    return ClientFactory.getClientRequiredError('Log');
   }
 
   protected getToolNameSet(): Set<JobLogToolName> {

package/src/core/handlers/log-handler.ts

@@ -1,21 +1,32 @@
-import { AbstractLogToolHandler } from './abstract-log-tool-handler.js';
-import { HandlerContext } from './base-handler.js';
-import { GenericToolSpec } from './base-handler.js';
-import { ToolArguments } from './base-handler.js';
+import { GenericToolSpec, ToolArguments, HandlerContext } from './base-handler.js';
+import { AbstractClientHandler } from './abstract-client-handler.js';
+import { ClientFactory } from './client-factory.js';
+import { SFCCLogClient } from '../../clients/logs/index.js';
 import { LOG_TOOL_CONFIG } from '../../tool-configs/log-tool-config.js';
 import { LOG_TOOL_NAMES_SET, LogToolName } from '../../utils/log-tool-constants.js';
 
 /**
  * Handler for standard log tools using config-driven dispatch
- * Handles log reading, searching, and analysis operations
  */
-export class LogToolHandler extends AbstractLogToolHandler<LogToolName> {
+export class LogToolHandler extends AbstractClientHandler<LogToolName, SFCCLogClient> {
   constructor(context: HandlerContext, subLoggerName: string) {
     super(context, subLoggerName);
   }
 
-  canHandle(toolName: string): boolean {
-    return LOG_TOOL_NAMES_SET.has(toolName as LogToolName);
+  protected createClient(): SFCCLogClient | null {
+    return this.clientFactory.createLogClient();
+  }
+
+  protected getClientContextKey(): string {
+    return 'logClient';
+  }
+
+  protected getClientDisplayName(): string {
+    return 'Log';
+  }
+
+  protected getClientRequiredError(): string {
+    return ClientFactory.getClientRequiredError('Log');
   }
 
   protected getToolNameSet(): Set<LogToolName> {

package/src/core/handlers/script-debugger-handler.ts

@@ -0,0 +1,46 @@
+import { GenericToolSpec, ToolArguments, HandlerContext } from './base-handler.js';
+import { AbstractClientHandler } from './abstract-client-handler.js';
+import { ClientFactory } from './client-factory.js';
+import { ScriptDebuggerClient } from '../../clients/script-debugger/index.js';
+import {
+  SCRIPT_DEBUGGER_TOOL_CONFIG,
+  ScriptDebuggerToolName,
+  SCRIPT_DEBUGGER_TOOL_NAMES_SET,
+} from '../../tool-configs/script-debugger-tool-config.js';
+
+/**
+ * Handler for script debugger tools using config-driven dispatch.
+ * Provides script evaluation capabilities via the SFCC Script Debugger API.
+ */
+export class ScriptDebuggerToolHandler extends AbstractClientHandler<
+  ScriptDebuggerToolName,
+  ScriptDebuggerClient
+> {
+  constructor(context: HandlerContext, subLoggerName: string) {
+    super(context, subLoggerName);
+  }
+
+  protected createClient(): ScriptDebuggerClient | null {
+    return this.clientFactory.createScriptDebuggerClient();
+  }
+
+  protected getClientContextKey(): string {
+    return 'scriptDebuggerClient';
+  }
+
+  protected getClientDisplayName(): string {
+    return 'Script Debugger';
+  }
+
+  protected getClientRequiredError(): string {
+    return ClientFactory.getClientRequiredError('ScriptDebugger');
+  }
+
+  protected getToolNameSet(): Set<ScriptDebuggerToolName> {
+    return SCRIPT_DEBUGGER_TOOL_NAMES_SET;
+  }
+
+  protected getToolConfig(): Record<ScriptDebuggerToolName, GenericToolSpec<ToolArguments, any>> {
+    return SCRIPT_DEBUGGER_TOOL_CONFIG;
+  }
+}

package/src/core/handlers/sfra-handler.ts

@@ -1,4 +1,5 @@
-import { BaseToolHandler, ToolExecutionContext, GenericToolSpec, HandlerContext, ToolArguments } from './base-handler.js';
+import { HandlerContext } from './base-handler.js';
+import { SimpleClientHandler } from './simple-client-handler.js';
 import { SFRAClient } from '../../clients/sfra-client.js';
 import {
   SFRA_TOOL_CONFIG,
@@ -7,49 +8,16 @@ import {
 } from '../../tool-configs/sfra-tool-config.js';
 
 /**
- * Handler for SFRA documentation tools using config-driven dispatch
- * Provides access to Storefront Reference Architecture documentation
+ * Handler for SFRA documentation tools
  */
-export class SFRAToolHandler extends BaseToolHandler<SFRAToolName> {
-  private sfraClient: SFRAClient | null = null;
-
-  constructor(context: HandlerContext, subLoggerName: string) {
-    super(context, subLoggerName);
-  }
-
-  protected async onInitialize(): Promise<void> {
-    if (!this.sfraClient) {
-      this.sfraClient = new SFRAClient();
-      this.logger.debug('SFRA client initialized');
-    }
-  }
-
-  protected async onDispose(): Promise<void> {
-    this.sfraClient = null;
-    this.logger.debug('SFRA client disposed');
-  }
-
-  canHandle(toolName: string): boolean {
-    return SFRA_TOOL_NAMES_SET.has(toolName as SFRAToolName);
-  }
-
-  protected getToolNameSet(): Set<SFRAToolName> {
-    return SFRA_TOOL_NAMES_SET;
-  }
-
-  protected getToolConfig(): Record<string, GenericToolSpec<ToolArguments, any>> {
-    return SFRA_TOOL_CONFIG;
-  }
-
-  protected async createExecutionContext(): Promise<ToolExecutionContext> {
-    if (!this.sfraClient) {
-      throw new Error('SFRA client not initialized');
-    }
-
-    return {
-      handlerContext: this.context,
-      logger: this.logger,
-      sfraClient: this.sfraClient,
-    };
+export class SFRAToolHandler extends SimpleClientHandler<SFRAToolName, SFRAClient> {
+  constructor(context: HandlerContext) {
+    super(context, 'SFRA', {
+      toolConfig: SFRA_TOOL_CONFIG,
+      toolNameSet: SFRA_TOOL_NAMES_SET,
+      clientContextKey: 'sfraClient',
+      clientDisplayName: 'SFRA',
+      createClient: () => new SFRAClient(),
+    });
   }
 }

package/src/core/handlers/simple-client-handler.ts

@@ -0,0 +1,78 @@
+import { BaseToolHandler, ToolExecutionContext, GenericToolSpec, ToolArguments, HandlerContext } from './base-handler.js';
+
+/**
+ * Configuration for creating a simple client handler
+ * Reduces boilerplate for handlers that just wrap a single client
+ */
+export interface SimpleClientConfig<TToolName extends string, TClient> {
+  /** Tool configuration mapping tool names to specs */
+  toolConfig: Record<TToolName, GenericToolSpec<ToolArguments, any>>;
+  /** Set of tool names for O(1) lookup */
+  toolNameSet: Set<TToolName>;
+  /** Key name for the client in the execution context */
+  clientContextKey: string;
+  /** Human-readable client name for logging/errors */
+  clientDisplayName: string;
+  /** Factory function to create the client */
+  createClient: () => TClient;
+}
+
+/**
+ * Generic handler for tools that use a single stateless client
+ * Eliminates boilerplate for simple documentation-style handlers
+ *
+ * @example
+ * const handler = createSimpleClientHandler({
+ *   toolConfig: DOCS_TOOL_CONFIG,
+ *   toolNameSet: DOC_TOOL_NAMES_SET,
+ *   clientContextKey: 'docsClient',
+ *   clientDisplayName: 'Documentation',
+ *   createClient: () => new SFCCDocumentationClient(),
+ * });
+ */
+export class SimpleClientHandler<TToolName extends string, TClient> extends BaseToolHandler<TToolName> {
+  private client: TClient | null = null;
+  private readonly config: SimpleClientConfig<TToolName, TClient>;
+
+  constructor(
+    context: HandlerContext,
+    subLoggerName: string,
+    config: SimpleClientConfig<TToolName, TClient>,
+  ) {
+    super(context, subLoggerName);
+    this.config = config;
+  }
+
+  protected async onInitialize(): Promise<void> {
+    if (!this.client) {
+      this.client = this.config.createClient();
+      this.logger.debug(`${this.config.clientDisplayName} client initialized`);
+    }
+  }
+
+  protected async onDispose(): Promise<void> {
+    this.client = null;
+    this.logger.debug(`${this.config.clientDisplayName} client disposed`);
+  }
+
+  protected getToolNameSet(): Set<TToolName> {
+    return this.config.toolNameSet;
+  }
+
+  protected getToolConfig(): Record<string, GenericToolSpec<ToolArguments, any>> {
+    return this.config.toolConfig;
+  }
+
+  protected async createExecutionContext(): Promise<ToolExecutionContext> {
+    if (!this.client) {
+      throw new Error(`${this.config.clientDisplayName} client not initialized`);
+    }
+
+    return {
+      handlerContext: this.context,
+      logger: this.logger,
+      [this.config.clientContextKey]: this.client,
+    };
+  }
+}
+

package/src/core/handlers/system-object-handler.ts

@@ -1,6 +1,7 @@
-import { BaseToolHandler, ToolExecutionContext, GenericToolSpec, HandlerContext, ToolArguments } from './base-handler.js';
-import { OCAPIClient } from '../../clients/ocapi-client.js';
+import { GenericToolSpec, ToolArguments, HandlerContext } from './base-handler.js';
+import { AbstractClientHandler } from './abstract-client-handler.js';
 import { ClientFactory } from './client-factory.js';
+import { OCAPIClient } from '../../clients/ocapi-client.js';
 import {
   SYSTEM_OBJECT_TOOL_CONFIG,
   SystemObjectToolName,
@@ -8,51 +9,35 @@ import {
 } from '../../tool-configs/system-object-tool-config.js';
 
 /**
- * Handler for system object tools using config-driven dispatch
- * Provides access to SFCC system object definitions, attributes, and site preferences
+ * Handler for system object tools using config-driven dispatch.
+ * Provides access to SFCC system object definitions, attributes, and site preferences.
  */
-export class SystemObjectToolHandler extends BaseToolHandler<SystemObjectToolName> {
-  private ocapiClient: OCAPIClient | null = null;
-  private clientFactory: ClientFactory;
-
+export class SystemObjectToolHandler extends AbstractClientHandler<SystemObjectToolName, OCAPIClient> {
   constructor(context: HandlerContext, subLoggerName: string) {
     super(context, subLoggerName);
-    this.clientFactory = new ClientFactory(context, this.logger);
   }
 
-  protected async onInitialize(): Promise<void> {
-    this.ocapiClient = this.clientFactory.createOCAPIClient();
-    if (this.ocapiClient) {
-      this.logger.debug('OCAPI client initialized for system objects');
-    }
+  protected createClient(): OCAPIClient | null {
+    return this.clientFactory.createOCAPIClient();
+  }
+
+  protected getClientContextKey(): string {
+    return 'ocapiClient';
   }
 
-  protected async onDispose(): Promise<void> {
-    this.ocapiClient = null;
-    this.logger.debug('OCAPI client disposed');
+  protected getClientDisplayName(): string {
+    return 'OCAPI (System Objects)';
   }
 
-  canHandle(toolName: string): boolean {
-    return SYSTEM_OBJECT_TOOL_NAMES_SET.has(toolName as SystemObjectToolName);
+  protected getClientRequiredError(): string {
+    return ClientFactory.getClientRequiredError('OCAPI');
   }
 
   protected getToolNameSet(): Set<SystemObjectToolName> {
     return SYSTEM_OBJECT_TOOL_NAMES_SET;
   }
 
-  protected getToolConfig(): Record<string, GenericToolSpec<ToolArguments, any>> {
+  protected getToolConfig(): Record<SystemObjectToolName, GenericToolSpec<ToolArguments, any>> {
     return SYSTEM_OBJECT_TOOL_CONFIG;
   }
-
-  protected async createExecutionContext(): Promise<ToolExecutionContext> {
-    if (!this.ocapiClient) {
-      throw new Error(ClientFactory.getClientRequiredError('OCAPI'));
-    }
-
-    return {
-      handlerContext: this.context,
-      logger: this.logger,
-      ocapiClient: this.ocapiClient,
-    };
-  }
 }

package/src/core/handlers/validation-helpers.ts

@@ -3,6 +3,7 @@
  */
 
 import { HandlerError, ToolArguments } from './base-handler.js';
+import { isValidLogLevel, LogLevelValues } from '../../utils/log-tool-constants.js';
 
 export interface ValidationRule<T = any> {
   field: string;
@@ -61,44 +62,6 @@ export class ValidationHelpers {
     }
   }
 
-  /**
-   * Quick validation for required string fields
-   * @deprecated Use CommonValidations.requiredString() with validateArguments() instead
-   * @example
-   * // Old way
-   * ValidationHelpers.requireStrings(args, ['fieldName'], 'tool_name');
-   *
-   * // New way
-   * ValidationHelpers.validateArguments(args, CommonValidations.requiredString('fieldName'), 'tool_name');
-   */
-  static requireStrings(args: ToolArguments, fields: string[], toolName: string): void {
-    const rules: ValidationRule[] = fields.map(field => ({
-      field,
-      required: true,
-      type: 'string' as const,
-      errorMessage: `${field} is required for ${toolName}`,
-    }));
-    this.validateArguments(args, rules, toolName);
-  }
-
-  /**
-   * Validate a single field with custom validator
-   */
-  static validateField<T>(
-    args: ToolArguments,
-    field: string,
-    validator: (value: T) => boolean,
-    errorMessage: string,
-    toolName: string,
-  ): void {
-    const rules: ValidationRule[] = [{
-      field,
-      validator,
-      errorMessage,
-    }];
-    this.validateArguments(args, rules, toolName);
-  }
-
   private static validateType(value: any, type: ValidationRule['type']): boolean {
     switch (type) {
       case 'string':
@@ -121,9 +84,7 @@ export class ValidationHelpers {
  * Common validation rules factory
  */
 export const CommonValidations = {
-  /**
-   * Create a required string field validation
-   */
+  /** Create a required string field validation */
   requiredString: (field: string, customMessage?: string): ValidationRule[] => [{
     field,
     required: true,
@@ -132,9 +93,7 @@ export const CommonValidations = {
     errorMessage: customMessage ?? `${field} must be a non-empty string`,
   }],
 
-  /**
-   * Create a required field validation with custom validator
-   */
+  /** Create a required field validation with custom validator */
   requiredField: (
     field: string,
     type: ValidationRule['type'],
@@ -148,9 +107,7 @@ export const CommonValidations = {
     errorMessage,
   }],
 
-  /**
-   * Create an optional field validation
-   */
+  /** Create an optional field validation */
   optionalField: (
     field: string,
     type: ValidationRule['type'],
@@ -164,3 +121,86 @@ export const CommonValidations = {
     errorMessage,
   }],
 };
+
+// =============================================================================
+// Log-specific validators (consolidated from log-validation.ts)
+// =============================================================================
+
+/** Validate log level parameter */
+export function validateLogLevel(level: string, toolName: string): void {
+  if (!isValidLogLevel(level)) {
+    const validLevels = Object.values(LogLevelValues).join(', ');
+    throw new Error(`Invalid log level '${level}' for ${toolName}. Valid levels: ${validLevels}`);
+  }
+}
+
+/** Validate limit parameter */
+export function validateLimit(limit: number | undefined, toolName: string): void {
+  if (limit === undefined) { return; }
+  if (typeof limit !== 'number' || isNaN(limit)) {
+    throw new Error(`Invalid limit '${limit}' for ${toolName}. Must be a valid number`);
+  }
+  if (limit <= 0 || limit > 1000) {
+    throw new Error(`Invalid limit '${limit}' for ${toolName}. Must be between 1 and 1000`);
+  }
+}
+
+/** Validate maxBytes parameter */
+export function validateMaxBytes(maxBytes: number | undefined, toolName: string): void {
+  if (maxBytes === undefined) { return; }
+  if (typeof maxBytes !== 'number' || isNaN(maxBytes)) {
+    throw new Error(`Invalid maxBytes '${maxBytes}' for ${toolName}. Must be a valid number`);
+  }
+  if (maxBytes <= 0 || maxBytes > 10_000_000) {
+    throw new Error(`Invalid maxBytes '${maxBytes}' for ${toolName}. Must be between 1 and 10,000,000`);
+  }
+}
+
+/** Validate filename parameter */
+export function validateFilename(filename: string, toolName: string): void {
+  if (!filename || filename.trim().length === 0) {
+    throw new Error(`Filename is required for ${toolName}`);
+  }
+  // Check for path traversal attempts
+  if (filename.includes('..') || filename.includes('\\')) {
+    throw new Error(`Invalid filename '${filename}' for ${toolName}. Path traversal not allowed`);
+  }
+  // Check for null byte injection
+  if (filename.includes('\0') || filename.includes('\x00')) {
+    throw new Error(`Invalid filename for ${toolName}. Contains invalid characters`);
+  }
+  // Check for absolute path attempts
+  if (filename.startsWith('/') && !filename.startsWith('/Logs/') && !filename.startsWith('/jobs/')) {
+    throw new Error(`Invalid filename '${filename}' for ${toolName}. Absolute paths outside /Logs/ are not allowed`);
+  }
+  // Check filename length to prevent DoS
+  if (filename.length > 1024) {
+    throw new Error(`Invalid filename for ${toolName}. Filename too long`);
+  }
+}
+
+/** Format log operation message */
+export function formatLogMessage(
+  operation: string,
+  params: {
+    level?: string;
+    limit?: number;
+    date?: string;
+    pattern?: string;
+    jobName?: string;
+    filename?: string;
+    maxBytes?: number;
+    tailOnly?: boolean;
+  } = {},
+): string {
+  const parts = [operation];
+  if (params.jobName) { parts.push(`jobName=${params.jobName}`); }
+  if (params.level) { parts.push(`level=${params.level}`); }
+  if (params.limit !== undefined) { parts.push(`limit=${params.limit}`); }
+  if (params.date) { parts.push(`date=${params.date}`); }
+  if (params.pattern) { parts.push(`pattern="${params.pattern}"`); }
+  if (params.filename) { parts.push(`filename=${params.filename}`); }
+  if (params.maxBytes !== undefined) { parts.push(`maxBytes=${params.maxBytes}`); }
+  if (params.tailOnly !== undefined) { parts.push(`tailOnly=${params.tailOnly}`); }
+  return parts.join(' ');
+}

package/src/core/instruction-advisor.ts

@@ -0,0 +1,122 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { AgentInstructionsClient } from '../clients/agent-instructions-client.js';
+import { Logger } from '../utils/logger.js';
+
+export interface McpDevConfig {
+  disableAgentSync?: boolean;
+}
+
+/**
+ * Provides gentle, one-time guidance when AGENTS.md or skills are missing.
+ * Respects mcp-dev.json configuration to permanently disable sync suggestions.
+ */
+export class InstructionAdvisor {
+  private readonly client: AgentInstructionsClient;
+  private readonly logger: Logger;
+
+  constructor(client: AgentInstructionsClient, logger: Logger) {
+    this.client = client;
+    this.logger = logger;
+  }
+
+  /**
+   * Check if agent sync is disabled via mcp-dev.json in the workspace root.
+   */
+  async isAgentSyncDisabled(workspaceRoot: string): Promise<boolean> {
+    try {
+      const configPath = path.join(workspaceRoot, 'mcp-dev.json');
+      const content = await fs.readFile(configPath, 'utf-8');
+      const config: McpDevConfig = JSON.parse(content);
+      return config.disableAgentSync === true;
+    } catch {
+      // File doesn't exist or is invalid - sync is not disabled
+      return false;
+    }
+  }
+
+  /**
+   * Create or update mcp-dev.json to disable agent sync suggestions.
+   */
+  async disableAgentSync(workspaceRoot: string): Promise<{ success: boolean; message: string }> {
+    try {
+      const configPath = path.join(workspaceRoot, 'mcp-dev.json');
+      let config: McpDevConfig = {};
+
+      // Try to read existing config
+      try {
+        const content = await fs.readFile(configPath, 'utf-8');
+        config = JSON.parse(content);
+      } catch {
+        // File doesn't exist, start with empty config
+      }
+
+      config.disableAgentSync = true;
+      await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
+
+      return {
+        success: true,
+        message: `Created/updated ${configPath} with disableAgentSync: true. Agent sync suggestions are now disabled for this workspace.`,
+      };
+    } catch (error) {
+      const errMsg = error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        message: `Failed to create mcp-dev.json: ${errMsg}`,
+      };
+    }
+  }
+
+  async getNotice(): Promise<string | undefined> {
+    try {
+      const status = await this.client.getStatus();
+
+      this.logger.debug('[InstructionAdvisor] Status', {
+        workspaceRoot: status.workspaceRoot,
+        hasAgents: status.hasAgents,
+        hasSkills: status.hasSkills,
+        detectedSkillsDir: status.detectedSkillsDir,
+        missingSkills: status.missingSkills,
+        sourceSkills: status.sourceSkills,
+      });
+
+      // If we cannot determine a workspace root, skip the notice (can't reliably detect presence)
+      if (!status.workspaceRoot) { return undefined; }
+
+      // Check if agent sync is disabled via mcp-dev.json
+      const syncDisabled = await this.isAgentSyncDisabled(status.workspaceRoot);
+      if (syncDisabled) {
+        this.logger.debug('[InstructionAdvisor] Agent sync disabled via mcp-dev.json');
+        return undefined;
+      }
+
+      if (status.hasAgents && status.hasSkills) { return undefined; }
+
+      const missingParts = [];
+      if (!status.hasAgents) { missingParts.push('AGENTS.md'); }
+      if (!status.hasSkills) { missingParts.push('skills'); }
+      const missingSkills = status.missingSkills?.length
+        ? `Missing skills: ${status.missingSkills.join(', ')}`
+        : 'All skills will be installed.';
+
+      this.logger.debug('[InstructionAdvisor] Issuing workspace-root notice');
+      return [
+        '📋 Agent instructions available for this SFCC project.',
+        `Missing: ${missingParts.join(' + ')}`,
+        missingSkills,
+        '',
+        '👉 ASK THE USER: "Would you like me to install AGENTS.md and SFCC development skills into your project?"',
+        '',
+        'If YES: Run sync_agent_instructions with dryRun=false',
+        'If NO: Create mcp-dev.json with {"disableAgentSync": true} to permanently disable this suggestion.',
+      ].join('\n');
+    } catch (error) {
+      this.logger.debug('InstructionAdvisor failed to evaluate status', error);
+      return undefined;
+    }
+  }
+
+  reset(): void {
+    // no-op for now; retained for potential future stateful notice throttling
+  }
+}