wave-agent-sdk 0.0.6 → 0.0.8

package/src/utils/commandPathResolver.ts

@@ -0,0 +1,189 @@
+import { relative, basename } from "path";
+
+/**
+ * Command path resolver utilities for nested command discovery
+ * Handles conversion between file paths and command IDs with colon syntax
+ */
+
+export interface CommandIdParts {
+  namespace?: string; // e.g., "openspec" for "openspec:apply"
+  commandName: string; // e.g., "apply" for "openspec:apply"
+  isNested: boolean; // true if command has namespace
+  depth: number; // 0 for root, 1 for nested
+  segments: string[]; // Path components array
+}
+
+/**
+ * Generate command ID from file path
+ * @param filePath - Absolute path to markdown file
+ * @param rootDir - Root commands directory path
+ * @returns Command identifier string (e.g., "openspec:apply")
+ * @throws Error on invalid path structure
+ */
+export function generateCommandId(filePath: string, rootDir: string): string {
+  // Handle null/undefined inputs
+  if (filePath == null || rootDir == null) {
+    throw new Error("File path and root directory must be provided");
+  }
+
+  // Handle empty root directory (for root level commands)
+  const relativePath = rootDir === "" ? filePath : relative(rootDir, filePath);
+
+  // Handle edge cases
+  if (!relativePath || relativePath === ".") {
+    throw new Error("Command filename cannot be empty");
+  }
+
+  const segments = relativePath.split("/").filter((segment) => segment !== "");
+
+  // Remove .md extension from the last segment
+  const lastSegment = segments[segments.length - 1];
+  if (!lastSegment.endsWith(".md")) {
+    throw new Error(`Command files must have .md extension`);
+  }
+
+  segments[segments.length - 1] = basename(lastSegment, ".md");
+
+  // Handle empty filename after removing extension
+  if (segments[segments.length - 1] === "") {
+    throw new Error("Command filename cannot be empty");
+  }
+
+  // Validate depth (max 1 level of nesting)
+  if (segments.length > 2) {
+    throw new Error(
+      `Command nesting too deep: ${relativePath}. Maximum depth is 1 level.`,
+    );
+  }
+
+  // Validate segments
+  for (const segment of segments) {
+    if (!validateSegment(segment)) {
+      throw new Error(
+        `Invalid command path segment: "${segment}" in ${relativePath}. Must match pattern /^[a-zA-Z][a-zA-Z0-9_.-]*$/`,
+      );
+    }
+  }
+
+  // Generate command ID
+  if (segments.length === 1) {
+    return segments[0]; // Flat command
+  } else {
+    return segments.join(":"); // Nested command with colon syntax
+  }
+}
+
+/**
+ * Parse command ID into components
+ * @param commandId - Command identifier (e.g., "openspec:apply")
+ * @returns Object with namespace and command name
+ * @throws Error on malformed command ID
+ */
+export function parseCommandId(commandId: string): CommandIdParts {
+  // Handle null/undefined inputs
+  if (commandId == null) {
+    throw new Error("Command ID cannot be null or undefined");
+  }
+
+  if (commandId === "") {
+    throw new Error("Command ID cannot be empty");
+  }
+
+  if (!validateCommandId(commandId)) {
+    throw new Error(
+      `Invalid command ID format: "${commandId}". Must match pattern /^[a-zA-Z0-9_-]+(?::[a-zA-Z0-9_-]+)?$/`,
+    );
+  }
+
+  const parts = commandId.split(":");
+
+  if (parts.length === 1) {
+    // Flat command
+    return {
+      namespace: undefined,
+      commandName: parts[0],
+      isNested: false,
+      depth: 0,
+      segments: [parts[0]],
+    };
+  } else if (parts.length === 2) {
+    // Nested command
+    return {
+      namespace: parts[0],
+      commandName: parts[1],
+      isNested: true,
+      depth: 1,
+      segments: [parts[0], parts[1]],
+    };
+  } else {
+    throw new Error(
+      `Invalid command ID format: "${commandId}". Too many colon separators.`,
+    );
+  }
+}
+
+/**
+ * Validate command ID format
+ * @param commandId - Command identifier to validate
+ * @returns Boolean indicating validity
+ */
+export function validateCommandId(commandId: string): boolean {
+  // Handle null/undefined inputs
+  if (commandId == null) {
+    return false;
+  }
+
+  // Command ID can have multiple colons (though generateCommandId enforces max 1 level)
+  // This validates the format but doesn't enforce depth limits
+  const pattern = /^[a-zA-Z][a-zA-Z0-9_-]*(?::[a-zA-Z][a-zA-Z0-9_-]*)*$/;
+  return pattern.test(commandId);
+}
+
+/**
+ * Validate individual path segment
+ * @param segment - Path segment to validate
+ * @returns Boolean indicating validity
+ */
+function validateSegment(segment: string): boolean {
+  // Segments should start with letters and can contain letters, numbers, dashes, underscores, dots
+  const pattern = /^[a-zA-Z][a-zA-Z0-9_.-]*$/;
+  return pattern.test(segment);
+}
+
+/**
+ * Convert file path to command segments array
+ * @param filePath - Absolute path to markdown file
+ * @param rootDir - Root commands directory path
+ * @returns Array of path segments
+ */
+export function getCommandSegments(
+  filePath: string,
+  rootDir: string,
+): string[] {
+  const relativePath = relative(rootDir, filePath);
+  const segments = relativePath.split("/").filter((segment) => segment !== "");
+
+  // Remove .md extension from the last segment
+  const lastSegment = segments[segments.length - 1];
+  segments[segments.length - 1] = basename(lastSegment, ".md");
+
+  return segments;
+}
+
+/**
+ * Get namespace from command segments
+ * @param segments - Command path segments
+ * @returns Namespace string or undefined for flat commands
+ */
+export function getNamespace(segments: string[]): string | undefined {
+  return segments.length > 1 ? segments[0] : undefined;
+}
+
+/**
+ * Get command depth from segments
+ * @param segments - Command path segments
+ * @returns Depth number (0 for root, 1 for nested)
+ */
+export function getDepth(segments: string[]): number {
+  return Math.max(0, segments.length - 1);
+}

package/src/utils/configPaths.ts

@@ -0,0 +1,163 @@
+/**
+ * Configuration Path Utilities
+ *
+ * Centralized utilities for resolving Wave configuration file paths.
+ * Supports both regular settings.json and settings.local.json with proper priority.
+ *
+ * Priority system:
+ * - User configs: ~/.wave/settings.local.json > ~/.wave/settings.json
+ * - Project configs: {workdir}/.wave/settings.local.json > {workdir}/.wave/settings.json
+ * - Project configs override user configs (existing behavior)
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync } from "fs";
+
+/**
+ * Get the user-specific configuration file path (legacy function)
+ * @deprecated Use getUserConfigPaths() for better priority support
+ */
+export function getUserConfigPath(): string {
+  return join(homedir(), ".wave", "settings.json");
+}
+
+/**
+ * Get the project-specific configuration file path (legacy function)
+ * @deprecated Use getProjectConfigPaths() for better priority support
+ */
+export function getProjectConfigPath(workdir: string): string {
+  return join(workdir, ".wave", "settings.json");
+}
+
+/**
+ * Get the user-specific configuration file paths in priority order
+ * Returns array with .local.json first, then .json
+ */
+export function getUserConfigPaths(): string[] {
+  const baseDir = join(homedir(), ".wave");
+  return [join(baseDir, "settings.local.json"), join(baseDir, "settings.json")];
+}
+
+/**
+ * Get the project-specific configuration file paths in priority order
+ * Returns array with .local.json first, then .json
+ */
+export function getProjectConfigPaths(workdir: string): string[] {
+  const baseDir = join(workdir, ".wave");
+  return [join(baseDir, "settings.local.json"), join(baseDir, "settings.json")];
+}
+
+/**
+ * Get all configuration file paths (user and project) in priority order
+ * Useful for comprehensive configuration detection
+ */
+export function getAllConfigPaths(workdir: string): {
+  userPaths: string[];
+  projectPaths: string[];
+  allPaths: string[];
+} {
+  const userPaths = getUserConfigPaths();
+  const projectPaths = getProjectConfigPaths(workdir);
+
+  return {
+    userPaths,
+    projectPaths,
+    allPaths: [...userPaths, ...projectPaths],
+  };
+}
+
+/**
+ * Get existing configuration file paths
+ * Returns only the paths that actually exist on the filesystem
+ */
+export function getExistingConfigPaths(workdir: string): {
+  userPaths: string[];
+  projectPaths: string[];
+  existingPaths: string[];
+} {
+  const allPaths = getAllConfigPaths(workdir);
+
+  const existingUserPaths = allPaths.userPaths.filter(existsSync);
+  const existingProjectPaths = allPaths.projectPaths.filter(existsSync);
+  const allExistingPaths = allPaths.allPaths.filter(existsSync);
+
+  return {
+    userPaths: existingUserPaths,
+    projectPaths: existingProjectPaths,
+    existingPaths: allExistingPaths,
+  };
+}
+
+/**
+ * Get the first existing configuration file path with the specified priority
+ * @param paths Array of paths in priority order
+ * @returns The first path that exists, or undefined if none exist
+ */
+export function getFirstExistingPath(paths: string[]): string | undefined {
+  return paths.find((path) => existsSync(path));
+}
+
+/**
+ * Get effective configuration paths (the ones that would actually be used)
+ * Returns the highest priority existing path for each category
+ */
+export function getEffectiveConfigPaths(workdir: string): {
+  userPath?: string;
+  projectPath?: string;
+  effectivePath?: string; // The path that takes final precedence
+} {
+  const userPaths = getUserConfigPaths();
+  const projectPaths = getProjectConfigPaths(workdir);
+
+  const userPath = getFirstExistingPath(userPaths);
+  const projectPath = getFirstExistingPath(projectPaths);
+
+  // Project path takes precedence over user path if both exist
+  const effectivePath = projectPath || userPath;
+
+  return {
+    userPath,
+    projectPath,
+    effectivePath,
+  };
+}
+
+/**
+ * Check if any configuration files exist
+ */
+export function hasAnyConfig(workdir: string): boolean {
+  const { existingPaths } = getExistingConfigPaths(workdir);
+  return existingPaths.length > 0;
+}
+
+/**
+ * Get configuration information for debugging and monitoring
+ */
+export function getConfigurationInfo(workdir: string): {
+  hasUser: boolean;
+  hasProject: boolean;
+  paths: string[];
+  userPaths: string[];
+  projectPaths: string[];
+  existingPaths: string[];
+  effectivePaths: {
+    userPath?: string;
+    projectPath?: string;
+    effectivePath?: string;
+  };
+} {
+  const allPaths = getAllConfigPaths(workdir);
+  const existingPaths = getExistingConfigPaths(workdir);
+  const effectivePaths = getEffectiveConfigPaths(workdir);
+
+  return {
+    hasUser: existingPaths.userPaths.length > 0,
+    hasProject: existingPaths.projectPaths.length > 0,
+    paths: allPaths.allPaths,
+    userPaths: allPaths.userPaths,
+    projectPaths: allPaths.projectPaths,
+    existingPaths: existingPaths.existingPaths,
+    effectivePaths,
+  };
+}

package/src/utils/configResolver.ts

@@ -1,6 +1,7 @@
 /**
  * Configuration resolver utilities for Agent Constructor Configuration
  * Resolves configuration from constructor arguments with environment fallbacks
+ * Supports live configuration updates and cache invalidation
  */
 
 import {
@@ -9,32 +10,111 @@ import {
   ConfigurationError,
   CONFIG_ERRORS,
 } from "../types/index.js";
+import { DEFAULT_TOKEN_LIMIT } from "./constants.js";
+import { loadMergedWaveConfig } from "../services/hook.js";
+import { getGlobalLogger } from "./globalLogger.js";
+
+/**
+ * Live configuration cache and invalidation support
+ */
+interface ConfigurationCache {
+  workdir?: string;
+  lastUpdated: number;
+  environmentVars: Record<string, string>;
+  isValid: boolean;
+}
+
+let configCache: ConfigurationCache | null = null;
+
+/**
+ * Initialize configuration cache with current environment variables from settings.json
+ */
+function initializeConfigurationCache(workdir?: string): void {
+  try {
+    const waveConfig = workdir ? loadMergedWaveConfig(workdir) : null;
+    const envVars = waveConfig?.env || {};
+
+    configCache = {
+      workdir,
+      lastUpdated: Date.now(),
+      environmentVars: envVars,
+      isValid: true,
+    };
+
+    const logger = getGlobalLogger();
+    logger?.debug(
+      `Live Config: Configuration cache initialized with ${Object.keys(envVars).length} environment variables`,
+    );
+  } catch (error) {
+    const logger = getGlobalLogger();
+    logger?.error(
+      `Live Config: Failed to initialize configuration cache: ${(error as Error).message}`,
+    );
+    configCache = {
+      workdir,
+      lastUpdated: Date.now(),
+      environmentVars: {},
+      isValid: false,
+    };
+  }
+}
+
+/**
+ * Get current environment variable value with live configuration support
+ */
+function getCurrentEnvironmentValue(
+  key: string,
+  workdir?: string,
+): string | undefined {
+  // Initialize cache if not present or workdir changed
+  if (!configCache || configCache.workdir !== workdir) {
+    initializeConfigurationCache(workdir);
+  }
+
+  // Use cached environment variables if available and valid
+  if (configCache && configCache.isValid) {
+    const cachedValue = configCache.environmentVars[key];
+    if (cachedValue !== undefined) {
+      const logger = getGlobalLogger();
+      logger?.debug(
+        `Live Config: Using cached environment variable ${key}=${cachedValue}`,
+      );
+      return cachedValue;
+    }
+  }
+
+  // Fallback to process environment
+  return process.env[key];
+}
 
 export class ConfigResolver {
   /**
-   * Resolves gateway configuration from constructor args and environment
+   * Resolves gateway configuration from constructor args and environment with live config support
    * @param apiKey - API key from constructor (optional)
    * @param baseURL - Base URL from constructor (optional)
+   * @param workdir - Working directory for loading live configuration (optional)
    * @returns Resolved gateway configuration
    * @throws ConfigurationError if required configuration is missing after fallbacks
    */
   static resolveGatewayConfig(
     apiKey?: string,
     baseURL?: string,
+    workdir?: string,
   ): GatewayConfig {
-    // Resolve API key: constructor > environment variable
+    // Resolve API key: constructor > live configuration > environment variable
     // Note: Explicitly provided empty strings should be treated as invalid, not fall back to env
     let resolvedApiKey: string;
     if (apiKey !== undefined) {
       resolvedApiKey = apiKey;
     } else {
-      resolvedApiKey = process.env.AIGW_TOKEN || "";
+      resolvedApiKey = getCurrentEnvironmentValue("AIGW_TOKEN", workdir) || "";
     }
 
     if (!resolvedApiKey && apiKey === undefined) {
+      const envValue = getCurrentEnvironmentValue("AIGW_TOKEN", workdir);
       throw new ConfigurationError(CONFIG_ERRORS.MISSING_API_KEY, "apiKey", {
         constructor: apiKey,
-        environment: process.env.AIGW_TOKEN,
+        environment: envValue,
       });
     }
 
@@ -46,19 +126,20 @@ export class ConfigResolver {
       );
     }
 
-    // Resolve base URL: constructor > environment variable
+    // Resolve base URL: constructor > live configuration > environment variable
     // Note: Explicitly provided empty strings should be treated as invalid, not fall back to env
     let resolvedBaseURL: string;
     if (baseURL !== undefined) {
       resolvedBaseURL = baseURL;
     } else {
-      resolvedBaseURL = process.env.AIGW_URL || "";
+      resolvedBaseURL = getCurrentEnvironmentValue("AIGW_URL", workdir) || "";
     }
 
     if (!resolvedBaseURL && baseURL === undefined) {
+      const envValue = getCurrentEnvironmentValue("AIGW_URL", workdir);
       throw new ConfigurationError(CONFIG_ERRORS.MISSING_BASE_URL, "baseURL", {
         constructor: baseURL,
-        environment: process.env.AIGW_URL,
+        environment: envValue,
       });
     }
 
@@ -77,26 +158,37 @@ export class ConfigResolver {
   }
 
   /**
-   * Resolves model configuration with fallbacks
+   * Resolves model configuration with fallbacks and live config support
    * @param agentModel - Agent model from constructor (optional)
    * @param fastModel - Fast model from constructor (optional)
+   * @param workdir - Working directory for loading live configuration (optional)
    * @returns Resolved model configuration with defaults
    */
   static resolveModelConfig(
     agentModel?: string,
     fastModel?: string,
+    workdir?: string,
   ): ModelConfig {
     // Default values as per data-model.md
     const DEFAULT_AGENT_MODEL = "claude-sonnet-4-20250514";
     const DEFAULT_FAST_MODEL = "gemini-2.5-flash";
 
-    // Resolve agent model: constructor > environment > default
+    // Resolve agent model: constructor > live configuration > environment > default
     const resolvedAgentModel =
-      agentModel || process.env.AIGW_MODEL || DEFAULT_AGENT_MODEL;
+      agentModel ||
+      getCurrentEnvironmentValue("AIGW_MODEL", workdir) ||
+      DEFAULT_AGENT_MODEL;
 
-    // Resolve fast model: constructor > environment > default
+    // Resolve fast model: constructor > live configuration > environment > default
     const resolvedFastModel =
-      fastModel || process.env.AIGW_FAST_MODEL || DEFAULT_FAST_MODEL;
+      fastModel ||
+      getCurrentEnvironmentValue("AIGW_FAST_MODEL", workdir) ||
+      DEFAULT_FAST_MODEL;
+
+    const logger = getGlobalLogger();
+    logger?.debug(
+      `Live Config: Resolved models - agent: ${resolvedAgentModel}, fast: ${resolvedFastModel}`,
+    );
 
     return {
       agentModel: resolvedAgentModel,
@@ -105,23 +197,29 @@ export class ConfigResolver {
   }
 
   /**
-   * Resolves token limit with fallbacks
+   * Resolves token limit with fallbacks and live config support
    * @param constructorLimit - Token limit from constructor (optional)
+   * @param workdir - Working directory for loading live configuration (optional)
    * @returns Resolved token limit
    */
-  static resolveTokenLimit(constructorLimit?: number): number {
-    const DEFAULT_TOKEN_LIMIT = 64000;
-
+  static resolveTokenLimit(
+    constructorLimit?: number,
+    workdir?: string,
+  ): number {
     // If constructor value provided, use it
     if (constructorLimit !== undefined) {
       return constructorLimit;
     }
 
-    // Try environment variable
-    const envTokenLimit = process.env.TOKEN_LIMIT;
+    // Try live configuration then environment variable
+    const envTokenLimit = getCurrentEnvironmentValue("TOKEN_LIMIT", workdir);
     if (envTokenLimit) {
       const parsed = parseInt(envTokenLimit, 10);
       if (!isNaN(parsed)) {
+        const logger = getGlobalLogger();
+        logger?.debug(
+          `Live Config: Resolved token limit from configuration: ${parsed}`,
+        );
         return parsed;
       }
     }
@@ -129,14 +227,76 @@ export class ConfigResolver {
     // Use default
     return DEFAULT_TOKEN_LIMIT;
   }
+
+  /**
+   * Invalidate configuration cache to force reload from settings.json
+   * @param workdir - Working directory to invalidate cache for (optional)
+   */
+  static invalidateCache(workdir?: string): void {
+    if (
+      configCache &&
+      (workdir === undefined || configCache.workdir === workdir)
+    ) {
+      const logger = getGlobalLogger();
+      logger?.info(
+        `Live Config: Configuration cache invalidated for workdir: ${workdir || "global"}`,
+      );
+      configCache = null;
+    }
+  }
+
+  /**
+   * Refresh configuration cache by reloading from settings.json
+   * @param workdir - Working directory to refresh cache for (optional)
+   */
+  static refreshCache(workdir?: string): void {
+    const logger = getGlobalLogger();
+    logger?.info(
+      `Live Config: Refreshing configuration cache for workdir: ${workdir || "global"}`,
+    );
+    initializeConfigurationCache(workdir);
+  }
+
+  /**
+   * Get current cache status for monitoring
+   * @returns Cache information or null if no cache
+   */
+  static getCacheStatus(): {
+    workdir?: string;
+    lastUpdated: number;
+    envVarCount: number;
+    isValid: boolean;
+  } | null {
+    if (!configCache) {
+      return null;
+    }
+
+    return {
+      workdir: configCache.workdir,
+      lastUpdated: configCache.lastUpdated,
+      envVarCount: Object.keys(configCache.environmentVars).length,
+      isValid: configCache.isValid,
+    };
+  }
 }
 
 /**
  * Static configuration resolver instance
- * Implements ConfigurationResolver interface from types.ts
+ * Implements ConfigurationResolver interface from types.ts with backward compatibility
  */
 export const configResolver = {
-  resolveGatewayConfig: ConfigResolver.resolveGatewayConfig,
-  resolveModelConfig: ConfigResolver.resolveModelConfig,
-  resolveTokenLimit: ConfigResolver.resolveTokenLimit,
+  resolveGatewayConfig: (apiKey?: string, baseURL?: string, workdir?: string) =>
+    ConfigResolver.resolveGatewayConfig(apiKey, baseURL, workdir),
+  resolveModelConfig: (
+    agentModel?: string,
+    fastModel?: string,
+    workdir?: string,
+  ) => ConfigResolver.resolveModelConfig(agentModel, fastModel, workdir),
+  resolveTokenLimit: (constructorLimit?: number, workdir?: string) =>
+    ConfigResolver.resolveTokenLimit(constructorLimit, workdir),
+
+  // Live configuration management methods
+  invalidateCache: ConfigResolver.invalidateCache,
+  refreshCache: ConfigResolver.refreshCache,
+  getCacheStatus: ConfigResolver.getCacheStatus,
 };

package/src/utils/constants.ts

@@ -29,7 +29,7 @@ export const USER_MEMORY_FILE = path.join(DATA_DIRECTORY, "user-memory.md");
 /**
  * AI related constants
  */
-export const DEFAULT_TOKEN_LIMIT = 64000; // Default token limit
+export const DEFAULT_TOKEN_LIMIT = 96000; // Default token limit
 
 /**
  * @deprecated These constants are now legacy. Use ModelConfig through Agent constructor instead.