claude-code-workflow 6.1.4 → 6.2.2

package/ccw/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/ccw/src/utils/{browser-launcher.js → browser-launcher.ts}

@@ -5,17 +5,18 @@ import { resolve } from 'path';
 /**
  * Launch a URL or file in the default browser
  * Cross-platform compatible (Windows/macOS/Linux)
- * @param {string} urlOrPath - HTTP URL or path to HTML file
- * @returns {Promise<void>}
+ * @param urlOrPath - HTTP URL or path to HTML file
+ * @returns Promise that resolves when browser is launched
  */
-export async function launchBrowser(urlOrPath) {
+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) {
-      throw new Error(`Failed to open browser: ${error.message}`);
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to open browser: ${message}`);
     }
   }
 
@@ -23,7 +24,7 @@ export async function launchBrowser(urlOrPath) {
   const absolutePath = resolve(urlOrPath);
 
   // Construct file:// URL based on platform
-  let url;
+  let url: string;
   if (platform() === 'win32') {
     // Windows: file:///C:/path/to/file.html
     url = `file:///${absolutePath.replace(/\\/g, '/')}`;
@@ -40,16 +41,17 @@ export async function launchBrowser(urlOrPath) {
     try {
       await open(absolutePath);
     } catch (fallbackError) {
-      throw new Error(`Failed to open browser: ${error.message}`);
+      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 {boolean}
+ * @returns True if running in headless environment
  */
-export function isHeadlessEnvironment() {
+export function isHeadlessEnvironment(): boolean {
   return !!(
     process.env.CI ||
     process.env.CONTINUOUS_INTEGRATION ||

package/ccw/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/ccw/src/utils/{path-resolver.js → path-resolver.ts}

@@ -1,13 +1,32 @@
 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 {string} inputPath - Path to resolve
- * @returns {string} - Absolute path
+ * @param inputPath - Path to resolve
+ * @returns Absolute path
  */
-export function resolvePath(inputPath) {
+export function resolvePath(inputPath: string): string {
   if (!inputPath) return process.cwd();
 
   // Handle ~ for home directory
@@ -21,14 +40,11 @@ export function resolvePath(inputPath) {
 /**
  * Validate and sanitize a user-provided path
  * Prevents path traversal attacks and validates path is within allowed boundaries
- * @param {string} inputPath - User-provided path
- * @param {Object} options - Validation options
- * @param {string} options.baseDir - Base directory to restrict paths within (optional)
- * @param {boolean} options.mustExist - Whether path must exist (default: false)
- * @param {boolean} options.allowHome - Whether to allow home directory paths (default: true)
- * @returns {Object} - { valid: boolean, path: string|null, error: string|null }
+ * @param inputPath - User-provided path
+ * @param options - Validation options
+ * @returns Validation result with path or error
  */
-export function validatePath(inputPath, options = {}) {
+export function validatePath(inputPath: string, options: ValidatePathOptions = {}): PathValidationResult {
   const { baseDir = null, mustExist = false, allowHome = true } = options;
 
   // Check for empty/null input
@@ -45,11 +61,12 @@ export function validatePath(inputPath, options = {}) {
   }
 
   // Resolve the path
-  let resolvedPath;
+  let resolvedPath: string;
   try {
     resolvedPath = resolvePath(trimmedPath);
   } catch (err) {
-    return { valid: false, path: null, error: `Invalid path: ${err.message}` };
+    const message = err instanceof Error ? err.message : String(err);
+    return { valid: false, path: null, error: `Invalid path: ${message}` };
   }
 
   // Check if path exists when required
@@ -63,7 +80,8 @@ export function validatePath(inputPath, options = {}) {
     try {
       realPath = realpathSync(resolvedPath);
     } catch (err) {
-      return { valid: false, path: null, error: `Cannot resolve path: ${err.message}` };
+      const message = err instanceof Error ? err.message : String(err);
+      return { valid: false, path: null, error: `Cannot resolve path: ${message}` };
     }
   }
 
@@ -95,11 +113,11 @@ export function validatePath(inputPath, options = {}) {
 
 /**
  * Validate output file path for writing
- * @param {string} outputPath - Output file path
- * @param {string} defaultDir - Default directory if path is relative
- * @returns {Object} - { valid: boolean, path: string|null, error: string|null }
+ * @param outputPath - Output file path
+ * @param defaultDir - Default directory if path is relative
+ * @returns Validation result with path or error
  */
-export function validateOutputPath(outputPath, defaultDir = process.cwd()) {
+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' };
   }
@@ -112,12 +130,13 @@ export function validateOutputPath(outputPath, defaultDir = process.cwd()) {
   }
 
   // Resolve the path
-  let resolvedPath;
+  let resolvedPath: string;
   try {
     resolvedPath = isAbsolute(trimmedPath) ? trimmedPath : join(defaultDir, trimmedPath);
     resolvedPath = resolve(resolvedPath);
   } catch (err) {
-    return { valid: false, path: null, error: `Invalid output path: ${err.message}` };
+    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
@@ -137,9 +156,9 @@ export function validateOutputPath(outputPath, defaultDir = process.cwd()) {
 
 /**
  * Get potential template locations
- * @returns {string[]} - Array of existing template directories
+ * @returns Array of existing template directories
  */
-export function getTemplateLocations() {
+export function getTemplateLocations(): string[] {
   const locations = [
     join(homedir(), '.claude', 'templates'),
     join(process.cwd(), '.claude', 'templates')
@@ -150,10 +169,10 @@ export function getTemplateLocations() {
 
 /**
  * Find a template file in known locations
- * @param {string} templateName - Name of template file (e.g., 'workflow-dashboard.html')
- * @returns {string|null} - Path to template or null if not found
+ * @param templateName - Name of template file (e.g., 'workflow-dashboard.html')
+ * @returns Path to template or null if not found
  */
-export function findTemplate(templateName) {
+export function findTemplate(templateName: string): string | null {
   const locations = getTemplateLocations();
 
   for (const loc of locations) {
@@ -168,45 +187,58 @@ export function findTemplate(templateName) {
 
 /**
  * Ensure directory exists, creating if necessary
- * @param {string} dirPath - Directory path to ensure
+ * @param dirPath - Directory path to ensure
  */
-export function ensureDir(dirPath) {
+export function ensureDir(dirPath: string): void {
   if (!existsSync(dirPath)) {
     mkdirSync(dirPath, { recursive: true });
   }
 }
 
 /**
- * Get the .workflow directory path from project path
- * @param {string} projectPath - Path to project
- * @returns {string} - Path to .workflow directory
+ * Normalize path for display (handle Windows backslashes)
+ * @param filePath - Path to normalize
+ * @returns Normalized path with forward slashes
  */
-export function getWorkflowDir(projectPath) {
-  return join(resolvePath(projectPath), '.workflow');
+export function normalizePathForDisplay(filePath: string): string {
+  return filePath.replace(/\\/g, '/');
 }
 
+// Recent paths storage - uses centralized storage with backward compatibility
+const MAX_RECENT_PATHS = 10;
+
 /**
- * Normalize path for display (handle Windows backslashes)
- * @param {string} filePath - Path to normalize
- * @returns {string}
+ * Get the recent paths file location
+ * Uses new location but falls back to legacy location for backward compatibility
  */
-export function normalizePathForDisplay(filePath) {
-  return filePath.replace(/\\/g, '/');
+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 storage file
-const RECENT_PATHS_FILE = join(homedir(), '.ccw-recent-paths.json');
-const MAX_RECENT_PATHS = 10;
+/**
+ * Recent paths data structure
+ */
+interface RecentPathsData {
+  paths: string[];
+}
 
 /**
  * Get recent project paths
- * @returns {string[]} - Array of recent paths
+ * @returns Array of recent paths
  */
-export function getRecentPaths() {
+export function getRecentPaths(): string[] {
   try {
-    if (existsSync(RECENT_PATHS_FILE)) {
-      const content = readFileSync(RECENT_PATHS_FILE, 'utf8');
-      const data = JSON.parse(content);
+    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 {
@@ -217,9 +249,9 @@ export function getRecentPaths() {
 
 /**
  * Track a project path (add to recent paths)
- * @param {string} projectPath - Path to track
+ * @param projectPath - Path to track
  */
-export function trackRecentPath(projectPath) {
+export function trackRecentPath(projectPath: string): void {
   try {
     const normalized = normalizePathForDisplay(resolvePath(projectPath));
     let paths = getRecentPaths();
@@ -233,8 +265,10 @@ export function trackRecentPath(projectPath) {
     // Limit to max
     paths = paths.slice(0, MAX_RECENT_PATHS);
 
-    // Save
-    writeFileSync(RECENT_PATHS_FILE, JSON.stringify({ paths }, null, 2), 'utf8');
+    // 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
   }
@@ -243,37 +277,39 @@ export function trackRecentPath(projectPath) {
 /**
  * Clear recent paths
  */
-export function clearRecentPaths() {
+export function clearRecentPaths(): void {
   try {
-    if (existsSync(RECENT_PATHS_FILE)) {
-      writeFileSync(RECENT_PATHS_FILE, JSON.stringify({ paths: [] }, null, 2), 'utf8');
-    }
+    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 {string} pathToRemove - Path to remove
- * @returns {boolean} - True if removed, false if not found
- */
-export function removeRecentPath(pathToRemove) {
-  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
-      writeFileSync(RECENT_PATHS_FILE, JSON.stringify({ paths }, null, 2), 'utf8');
-      return true;
-    }
-    return false;
-  } catch {
-    return false;
-  }
-}
+}
+
+/**
+ * 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/ccw/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);
+}