claude-code-workflow 6.1.3 → 6.2.1

package/src/types/tool.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+// Tool parameter schema for Zod validation
+export const ToolParamSchema = z.object({
+  name: z.string(),
+  type: z.enum(['string', 'number', 'boolean', 'object', 'array']),
+  description: z.string(),
+  required: z.boolean().default(false),
+  default: z.any().optional(),
+  enum: z.array(z.string()).optional(),
+});
+
+export type ToolParam = z.infer<typeof ToolParamSchema>;
+
+// Tool Schema definition (MCP compatible)
+export interface ToolSchema {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+// Tool execution result
+export interface ToolResult<T = unknown> {
+  success: boolean;
+  result?: T;
+  error?: string;
+}
+
+// Tool handler function type
+export type ToolHandler<TParams = Record<string, unknown>, TResult = unknown> =
+  (params: TParams) => Promise<ToolResult<TResult>>;
+
+// Tool registration entry
+export interface ToolRegistration<TParams = Record<string, unknown>> {
+  schema: ToolSchema;
+  handler: ToolHandler<TParams>;
+}

package/src/utils/browser-launcher.ts

@@ -0,0 +1,62 @@
+import open from 'open';
+import { platform } from 'os';
+import { resolve } from 'path';
+
+/**
+ * Launch a URL or file in the default browser
+ * Cross-platform compatible (Windows/macOS/Linux)
+ * @param urlOrPath - HTTP URL or path to HTML file
+ * @returns Promise that resolves when browser is launched
+ */
+export async function launchBrowser(urlOrPath: string): Promise<void> {
+  // Check if it's already a URL (http:// or https://)
+  if (urlOrPath.startsWith('http://') || urlOrPath.startsWith('https://')) {
+    try {
+      await open(urlOrPath);
+      return;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to open browser: ${message}`);
+    }
+  }
+
+  // It's a file path - convert to file:// URL
+  const absolutePath = resolve(urlOrPath);
+
+  // Construct file:// URL based on platform
+  let url: string;
+  if (platform() === 'win32') {
+    // Windows: file:///C:/path/to/file.html
+    url = `file:///${absolutePath.replace(/\\/g, '/')}`;
+  } else {
+    // Unix: file:///path/to/file.html
+    url = `file://${absolutePath}`;
+  }
+
+  try {
+    // Use the 'open' package which handles cross-platform browser launching
+    await open(url);
+  } catch (error) {
+    // Fallback: try opening the file path directly
+    try {
+      await open(absolutePath);
+    } catch (fallbackError) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to open browser: ${message}`);
+    }
+  }
+}
+
+/**
+ * Check if we're running in a headless/CI environment
+ * @returns True if running in headless environment
+ */
+export function isHeadlessEnvironment(): boolean {
+  return !!(
+    process.env.CI ||
+    process.env.CONTINUOUS_INTEGRATION ||
+    process.env.GITHUB_ACTIONS ||
+    process.env.GITLAB_CI ||
+    process.env.JENKINS_URL
+  );
+}

package/src/utils/file-utils.ts

@@ -0,0 +1,48 @@
+import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Safely read a JSON file
+ * @param filePath - Path to JSON file
+ * @returns Parsed JSON or null on error
+ */
+export function readJsonFile(filePath: string): unknown | null {
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Safely read a text file
+ * @param filePath - Path to text file
+ * @returns File contents or null on error
+ */
+export function readTextFile(filePath: string): string | null {
+  if (!existsSync(filePath)) return null;
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write content to a file
+ * @param filePath - Path to file
+ * @param content - Content to write
+ */
+export function writeTextFile(filePath: string, content: string): void {
+  writeFileSync(filePath, content, 'utf8');
+}
+
+/**
+ * Check if a path exists
+ * @param filePath - Path to check
+ * @returns True if path exists
+ */
+export function pathExists(filePath: string): boolean {
+  return existsSync(filePath);
+}

package/src/utils/path-resolver.ts

@@ -0,0 +1,315 @@
+import { resolve, join, relative, isAbsolute } from 'path';
+import { existsSync, mkdirSync, realpathSync, statSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { StoragePaths, ensureStorageDir, LegacyPaths } from '../config/storage-paths.js';
+
+/**
+ * Validation result for path operations
+ */
+export interface PathValidationResult {
+  valid: boolean;
+  path: string | null;
+  error: string | null;
+}
+
+/**
+ * Options for path validation
+ */
+export interface ValidatePathOptions {
+  baseDir?: string | null;
+  mustExist?: boolean;
+  allowHome?: boolean;
+}
+
+/**
+ * Resolve a path, handling ~ for home directory
+ * @param inputPath - Path to resolve
+ * @returns Absolute path
+ */
+export function resolvePath(inputPath: string): string {
+  if (!inputPath) return process.cwd();
+
+  // Handle ~ for home directory
+  if (inputPath.startsWith('~')) {
+    return join(homedir(), inputPath.slice(1));
+  }
+
+  return resolve(inputPath);
+}
+
+/**
+ * Validate and sanitize a user-provided path
+ * Prevents path traversal attacks and validates path is within allowed boundaries
+ * @param inputPath - User-provided path
+ * @param options - Validation options
+ * @returns Validation result with path or error
+ */
+export function validatePath(inputPath: string, options: ValidatePathOptions = {}): PathValidationResult {
+  const { baseDir = null, mustExist = false, allowHome = true } = options;
+
+  // Check for empty/null input
+  if (!inputPath || typeof inputPath !== 'string') {
+    return { valid: false, path: null, error: 'Path is required' };
+  }
+
+  // Trim whitespace
+  const trimmedPath = inputPath.trim();
+
+  // Check for suspicious patterns (null bytes, control characters)
+  if (/[\x00-\x1f]/.test(trimmedPath)) {
+    return { valid: false, path: null, error: 'Path contains invalid characters' };
+  }
+
+  // Resolve the path
+  let resolvedPath: string;
+  try {
+    resolvedPath = resolvePath(trimmedPath);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { valid: false, path: null, error: `Invalid path: ${message}` };
+  }
+
+  // Check if path exists when required
+  if (mustExist && !existsSync(resolvedPath)) {
+    return { valid: false, path: null, error: `Path does not exist: ${resolvedPath}` };
+  }
+
+  // Get real path if it exists (resolves symlinks)
+  let realPath = resolvedPath;
+  if (existsSync(resolvedPath)) {
+    try {
+      realPath = realpathSync(resolvedPath);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { valid: false, path: null, error: `Cannot resolve path: ${message}` };
+    }
+  }
+
+  // Check if within base directory when specified
+  if (baseDir) {
+    const resolvedBase = resolvePath(baseDir);
+    const relativePath = relative(resolvedBase, realPath);
+
+    // Path traversal detection: relative path should not start with '..'
+    if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
+      return {
+        valid: false,
+        path: null,
+        error: `Path must be within ${resolvedBase}`
+      };
+    }
+  }
+
+  // Check home directory restriction
+  if (!allowHome) {
+    const home = homedir();
+    if (realPath === home || realPath.startsWith(home + '/') || realPath.startsWith(home + '\\')) {
+      // This is fine, we're just checking if it's explicitly the home dir itself
+    }
+  }
+
+  return { valid: true, path: realPath, error: null };
+}
+
+/**
+ * Validate output file path for writing
+ * @param outputPath - Output file path
+ * @param defaultDir - Default directory if path is relative
+ * @returns Validation result with path or error
+ */
+export function validateOutputPath(outputPath: string, defaultDir: string = process.cwd()): PathValidationResult {
+  if (!outputPath || typeof outputPath !== 'string') {
+    return { valid: false, path: null, error: 'Output path is required' };
+  }
+
+  const trimmedPath = outputPath.trim();
+
+  // Check for suspicious patterns
+  if (/[\x00-\x1f]/.test(trimmedPath)) {
+    return { valid: false, path: null, error: 'Output path contains invalid characters' };
+  }
+
+  // Resolve the path
+  let resolvedPath: string;
+  try {
+    resolvedPath = isAbsolute(trimmedPath) ? trimmedPath : join(defaultDir, trimmedPath);
+    resolvedPath = resolve(resolvedPath);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { valid: false, path: null, error: `Invalid output path: ${message}` };
+  }
+
+  // Ensure it's not a directory
+  if (existsSync(resolvedPath)) {
+    try {
+      const stat = statSync(resolvedPath);
+      if (stat.isDirectory()) {
+        return { valid: false, path: null, error: 'Output path is a directory, expected a file' };
+      }
+    } catch {
+      // Ignore stat errors
+    }
+  }
+
+  return { valid: true, path: resolvedPath, error: null };
+}
+
+/**
+ * Get potential template locations
+ * @returns Array of existing template directories
+ */
+export function getTemplateLocations(): string[] {
+  const locations = [
+    join(homedir(), '.claude', 'templates'),
+    join(process.cwd(), '.claude', 'templates')
+  ];
+
+  return locations.filter(loc => existsSync(loc));
+}
+
+/**
+ * Find a template file in known locations
+ * @param templateName - Name of template file (e.g., 'workflow-dashboard.html')
+ * @returns Path to template or null if not found
+ */
+export function findTemplate(templateName: string): string | null {
+  const locations = getTemplateLocations();
+
+  for (const loc of locations) {
+    const templatePath = join(loc, templateName);
+    if (existsSync(templatePath)) {
+      return templatePath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Ensure directory exists, creating if necessary
+ * @param dirPath - Directory path to ensure
+ */
+export function ensureDir(dirPath: string): void {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Normalize path for display (handle Windows backslashes)
+ * @param filePath - Path to normalize
+ * @returns Normalized path with forward slashes
+ */
+export function normalizePathForDisplay(filePath: string): string {
+  return filePath.replace(/\\/g, '/');
+}
+
+// Recent paths storage - uses centralized storage with backward compatibility
+const MAX_RECENT_PATHS = 10;
+
+/**
+ * Get the recent paths file location
+ * Uses new location but falls back to legacy location for backward compatibility
+ */
+function getRecentPathsFile(): string {
+  const newPath = StoragePaths.global.recentPaths();
+  const legacyPath = LegacyPaths.recentPaths();
+
+  // Backward compatibility: use legacy if it exists and new doesn't
+  if (!existsSync(newPath) && existsSync(legacyPath)) {
+    return legacyPath;
+  }
+  return newPath;
+}
+
+/**
+ * Recent paths data structure
+ */
+interface RecentPathsData {
+  paths: string[];
+}
+
+/**
+ * Get recent project paths
+ * @returns Array of recent paths
+ */
+export function getRecentPaths(): string[] {
+  try {
+    const recentPathsFile = getRecentPathsFile();
+    if (existsSync(recentPathsFile)) {
+      const content = readFileSync(recentPathsFile, 'utf8');
+      const data = JSON.parse(content) as RecentPathsData;
+      return Array.isArray(data.paths) ? data.paths : [];
+    }
+  } catch {
+    // Ignore errors, return empty array
+  }
+  return [];
+}
+
+/**
+ * Track a project path (add to recent paths)
+ * @param projectPath - Path to track
+ */
+export function trackRecentPath(projectPath: string): void {
+  try {
+    const normalized = normalizePathForDisplay(resolvePath(projectPath));
+    let paths = getRecentPaths();
+
+    // Remove if already exists (will be added to front)
+    paths = paths.filter(p => normalizePathForDisplay(p) !== normalized);
+
+    // Add to front
+    paths.unshift(normalized);
+
+    // Limit to max
+    paths = paths.slice(0, MAX_RECENT_PATHS);
+
+    // Save to new centralized location
+    const recentPathsFile = StoragePaths.global.recentPaths();
+    ensureStorageDir(StoragePaths.global.config());
+    writeFileSync(recentPathsFile, JSON.stringify({ paths }, null, 2), 'utf8');
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Clear recent paths
+ */
+export function clearRecentPaths(): void {
+  try {
+    const recentPathsFile = StoragePaths.global.recentPaths();
+    ensureStorageDir(StoragePaths.global.config());
+    writeFileSync(recentPathsFile, JSON.stringify({ paths: [] }, null, 2), 'utf8');
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Remove a specific path from recent paths
+ * @param pathToRemove - Path to remove
+ * @returns True if removed, false if not found
+ */
+export function removeRecentPath(pathToRemove: string): boolean {
+  try {
+    const normalized = normalizePathForDisplay(resolvePath(pathToRemove));
+    let paths = getRecentPaths();
+    const originalLength = paths.length;
+
+    // Filter out the path to remove
+    paths = paths.filter(p => normalizePathForDisplay(p) !== normalized);
+
+    if (paths.length < originalLength) {
+      // Save updated list to new centralized location
+      const recentPathsFile = StoragePaths.global.recentPaths();
+      ensureStorageDir(StoragePaths.global.config());
+      writeFileSync(recentPathsFile, JSON.stringify({ paths }, null, 2), 'utf8');
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}

package/src/utils/path-validator.ts

@@ -0,0 +1,153 @@
+/**
+ * Centralized Path Validation Utility
+ *
+ * Provides secure path validation and resolution for MCP tools.
+ * Prevents path traversal attacks and ensures operations stay within allowed directories.
+ *
+ * Inspired by MCP filesystem server's security model.
+ */
+
+import { resolve, isAbsolute, normalize, relative } from 'path';
+import { realpath, access } from 'fs/promises';
+import { constants } from 'fs';
+
+// Environment variable configuration
+const ENV_PROJECT_ROOT = 'CCW_PROJECT_ROOT';
+const ENV_ALLOWED_DIRS = 'CCW_ALLOWED_DIRS';
+
+/**
+ * Get project root directory
+ * Priority: CCW_PROJECT_ROOT > process.cwd()
+ */
+export function getProjectRoot(): string {
+  return process.env[ENV_PROJECT_ROOT] || process.cwd();
+}
+
+/**
+ * Get allowed directories list
+ * Priority: CCW_ALLOWED_DIRS > [getProjectRoot()]
+ */
+export function getAllowedDirectories(): string[] {
+  const envDirs = process.env[ENV_ALLOWED_DIRS];
+  if (envDirs) {
+    return envDirs.split(',').map(d => d.trim()).filter(Boolean);
+  }
+  return [getProjectRoot()];
+}
+
+/**
+ * Normalize path (unify separators to forward slash)
+ */
+export function normalizePath(p: string): string {
+  return normalize(p).replace(/\\/g, '/');
+}
+
+/**
+ * Check if path is within allowed directories
+ */
+export function isPathWithinAllowedDirectories(
+  targetPath: string,
+  allowedDirectories: string[]
+): boolean {
+  const normalizedTarget = normalizePath(targetPath);
+  return allowedDirectories.some(dir => {
+    const normalizedDir = normalizePath(dir);
+    // Check if path equals or starts with allowed directory
+    return normalizedTarget === normalizedDir ||
+           normalizedTarget.startsWith(normalizedDir + '/');
+  });
+}
+
+/**
+ * Validate and resolve path (core function)
+ *
+ * Security model:
+ * 1. Resolve to absolute path
+ * 2. Check against allowed directories
+ * 3. Resolve symlinks and re-verify
+ *
+ * @param filePath - Path to validate
+ * @param options - Validation options
+ * @returns Validated absolute path
+ * @throws Error if path is outside allowed directories or validation fails
+ */
+export async function validatePath(
+  filePath: string,
+  options: {
+    allowedDirectories?: string[];
+    mustExist?: boolean;
+  } = {}
+): Promise<string> {
+  const allowedDirs = options.allowedDirectories || getAllowedDirectories();
+
+  // 1. Resolve to absolute path
+  const absolutePath = isAbsolute(filePath)
+    ? filePath
+    : resolve(getProjectRoot(), filePath);
+  const normalizedPath = normalizePath(absolutePath);
+
+  // 2. Initial sandbox check
+  if (!isPathWithinAllowedDirectories(normalizedPath, allowedDirs)) {
+    throw new Error(
+      `Access denied: path "${normalizedPath}" is outside allowed directories. ` +
+      `Allowed: [${allowedDirs.join(', ')}]`
+    );
+  }
+
+  // 3. Try to resolve symlinks and re-verify
+  try {
+    const realPath = await realpath(absolutePath);
+    const normalizedReal = normalizePath(realPath);
+
+    if (!isPathWithinAllowedDirectories(normalizedReal, allowedDirs)) {
+      throw new Error(
+        `Access denied: symlink target "${normalizedReal}" is outside allowed directories`
+      );
+    }
+
+    return normalizedReal;
+  } catch (error: any) {
+    // File doesn't exist - validate parent directory
+    if (error.code === 'ENOENT') {
+      if (options.mustExist) {
+        throw new Error(`File not found: ${absolutePath}`);
+      }
+
+      // Validate parent directory's real path
+      const parentDir = resolve(absolutePath, '..');
+      try {
+        const realParent = await realpath(parentDir);
+        const normalizedParent = normalizePath(realParent);
+
+        if (!isPathWithinAllowedDirectories(normalizedParent, allowedDirs)) {
+          throw new Error(
+            `Access denied: parent directory "${normalizedParent}" is outside allowed directories`
+          );
+        }
+      } catch (parentError: any) {
+        if (parentError.code === 'ENOENT') {
+          // Parent directory doesn't exist either - return original absolute path
+          // Let the caller create it if needed
+          return absolutePath;
+        }
+        throw parentError;
+      }
+
+      return absolutePath;
+    }
+
+    // Re-throw access denied errors
+    if (error.message?.includes('Access denied')) {
+      throw error;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Resolve project-relative path (simplified, no strict validation)
+ * Use for cases where strict security validation is not needed
+ */
+export function resolveProjectPath(...pathSegments: string[]): string {
+  return resolve(getProjectRoot(), ...pathSegments);
+}