claude-code-workflow 6.1.4 → 6.2.1

package/src/tools/storage-manager.ts

@@ -0,0 +1,455 @@
+/**
+ * Storage Manager - Centralized storage management for CCW
+ * Provides info, cleanup, and configuration for ~/.ccw/ storage
+ */
+
+import { existsSync, readdirSync, statSync, rmSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, resolve } from 'path';
+import { homedir } from 'os';
+import { createRequire } from 'module';
+import { StoragePaths, CCW_HOME, getProjectId } from '../config/storage-paths.js';
+
+// Create require for loading CJS modules in ESM context
+const require = createRequire(import.meta.url);
+
+/**
+ * Storage statistics for a single project
+ */
+export interface ProjectStorageStats {
+  projectId: string;
+  totalSize: number;
+  cliHistory: { exists: boolean; size: number; recordCount?: number };
+  memory: { exists: boolean; size: number };
+  cache: { exists: boolean; size: number };
+  config: { exists: boolean; size: number };
+  lastModified: Date | null;
+}
+
+/**
+ * Global storage statistics
+ */
+export interface StorageStats {
+  rootPath: string;
+  totalSize: number;
+  globalDb: { exists: boolean; size: number };
+  projects: ProjectStorageStats[];
+  projectCount: number;
+}
+
+/**
+ * Storage configuration
+ */
+export interface StorageConfig {
+  dataDir: string;
+  isCustom: boolean;
+  envVar: string | undefined;
+}
+
+/**
+ * Calculate directory size recursively
+ */
+function getDirSize(dirPath: string): number {
+  if (!existsSync(dirPath)) return 0;
+
+  let totalSize = 0;
+  try {
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        totalSize += getDirSize(fullPath);
+      } else {
+        try {
+          totalSize += statSync(fullPath).size;
+        } catch {
+          // Skip files we can't read
+        }
+      }
+    }
+  } catch {
+    // Skip directories we can't read
+  }
+  return totalSize;
+}
+
+/**
+ * Get file size safely
+ */
+function getFileSize(filePath: string): number {
+  try {
+    return existsSync(filePath) ? statSync(filePath).size : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Get latest modification time in a directory
+ */
+function getLatestModTime(dirPath: string): Date | null {
+  if (!existsSync(dirPath)) return null;
+
+  let latest: Date | null = null;
+  try {
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dirPath, entry.name);
+      try {
+        const stat = statSync(fullPath);
+        const mtime = stat.mtime;
+        if (!latest || mtime > latest) {
+          latest = mtime;
+        }
+        if (entry.isDirectory()) {
+          const subLatest = getLatestModTime(fullPath);
+          if (subLatest && (!latest || subLatest > latest)) {
+            latest = subLatest;
+          }
+        }
+      } catch {
+        // Skip files we can't read
+      }
+    }
+  } catch {
+    // Skip directories we can't read
+  }
+  return latest;
+}
+
+/**
+ * Get record count from SQLite database
+ */
+function getDbRecordCount(dbPath: string, tableName: string): number {
+  if (!existsSync(dbPath)) return 0;
+  try {
+    // Dynamic import to handle ESM module
+    const Database = require('better-sqlite3');
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    const stmt = db.prepare(`SELECT COUNT(*) as count FROM ${tableName}`);
+    const result = stmt.get() as { count: number };
+    db.close();
+    return result?.count ?? 0;
+  } catch (err) {
+    // Debug: enable to see actual error
+    if (process.env.DEBUG) console.error(`[Storage] Failed to get record count from ${dbPath}: ${err}`);
+    return 0;
+  }
+}
+
+/**
+ * Check if a directory is a project data directory
+ * A project data directory contains at least one of: cli-history, memory, cache, config
+ */
+function isProjectDataDirectory(dirPath: string): boolean {
+  const dataMarkers = ['cli-history', 'memory', 'cache', 'config'];
+  return dataMarkers.some(marker => existsSync(join(dirPath, marker)));
+}
+
+/**
+ * Get storage statistics for a specific project by path
+ * @param projectId - Project ID (can be hierarchical like "parent/child")
+ * @param projectDir - Actual directory path in storage
+ */
+function getProjectStats(projectId: string, projectDir: string): ProjectStorageStats {
+  const cliHistoryDir = join(projectDir, 'cli-history');
+  const memoryDir = join(projectDir, 'memory');
+  const cacheDir = join(projectDir, 'cache');
+  const configDir = join(projectDir, 'config');
+
+  const cliHistorySize = getDirSize(cliHistoryDir);
+  const memorySize = getDirSize(memoryDir);
+  const cacheSize = getDirSize(cacheDir);
+  const configSize = getDirSize(configDir);
+
+  let recordCount: number | undefined;
+  const historyDb = join(cliHistoryDir, 'history.db');
+  if (existsSync(historyDb)) {
+    recordCount = getDbRecordCount(historyDb, 'conversations');
+  }
+
+  return {
+    projectId,
+    totalSize: cliHistorySize + memorySize + cacheSize + configSize,
+    cliHistory: {
+      exists: existsSync(cliHistoryDir),
+      size: cliHistorySize,
+      recordCount
+    },
+    memory: {
+      exists: existsSync(memoryDir),
+      size: memorySize
+    },
+    cache: {
+      exists: existsSync(cacheDir),
+      size: cacheSize
+    },
+    config: {
+      exists: existsSync(configDir),
+      size: configSize
+    },
+    lastModified: getLatestModTime(projectDir)
+  };
+}
+
+/**
+ * Get storage statistics for a specific project by ID (legacy)
+ */
+export function getProjectStorageStats(projectId: string): ProjectStorageStats {
+  const paths = StoragePaths.projectById(projectId);
+  return getProjectStats(projectId, paths.root);
+}
+
+/**
+ * Recursively scan project directory for hierarchical structure
+ * @param basePath - Base directory to scan
+ * @param relativePath - Relative path from projects root
+ * @param results - Array to accumulate results
+ */
+function scanProjectDirectory(
+  basePath: string,
+  relativePath: string,
+  results: ProjectStorageStats[]
+): void {
+  if (!existsSync(basePath)) return;
+
+  try {
+    const entries = readdirSync(basePath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const fullPath = join(basePath, entry.name);
+      const currentRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+
+      // Check if this is a project data directory
+      if (isProjectDataDirectory(fullPath)) {
+        const projectId = currentRelPath;
+        const stats = getProjectStats(projectId, fullPath);
+        results.push(stats);
+      }
+
+      // Recursively scan subdirectories (excluding data directories)
+      const dataDirs = ['cli-history', 'memory', 'cache', 'config'];
+      if (!dataDirs.includes(entry.name)) {
+        scanProjectDirectory(fullPath, currentRelPath, results);
+      }
+    }
+  } catch (err) {
+    // Ignore read errors
+    if (process.env.DEBUG) console.error(`[Storage] Failed to scan ${basePath}: ${err}`);
+  }
+}
+
+/**
+ * Get all storage statistics
+ * Supports hierarchical project structure
+ */
+export function getStorageStats(): StorageStats {
+  const rootPath = CCW_HOME;
+  const projectsDir = join(rootPath, 'projects');
+
+  // Global database
+  const mcpTemplatesPath = StoragePaths.global.mcpTemplates();
+  const globalDbSize = getFileSize(mcpTemplatesPath);
+
+  // Projects - use recursive scanning for hierarchical structure
+  const projects: ProjectStorageStats[] = [];
+  if (existsSync(projectsDir)) {
+    scanProjectDirectory(projectsDir, '', projects);
+  }
+
+  // Sort by last modified (most recent first)
+  projects.sort((a, b) => {
+    if (!a.lastModified && !b.lastModified) return 0;
+    if (!a.lastModified) return 1;
+    if (!b.lastModified) return -1;
+    return b.lastModified.getTime() - a.lastModified.getTime();
+  });
+
+  const totalProjectSize = projects.reduce((sum, p) => sum + p.totalSize, 0);
+
+  return {
+    rootPath,
+    totalSize: globalDbSize + totalProjectSize,
+    globalDb: {
+      exists: existsSync(mcpTemplatesPath),
+      size: globalDbSize
+    },
+    projects,
+    projectCount: projects.length
+  };
+}
+
+/**
+ * Get current storage configuration
+ */
+export function getStorageConfig(): StorageConfig {
+  const envVar = process.env.CCW_DATA_DIR;
+  return {
+    dataDir: CCW_HOME,
+    isCustom: !!envVar,
+    envVar
+  };
+}
+
+/**
+ * Format bytes to human readable string
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+}
+
+/**
+ * Format date to relative time
+ */
+export function formatTimeAgo(date: Date | null): string {
+  if (!date) return 'Never';
+
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMins = Math.floor(diffMs / 60000);
+  const diffHours = Math.floor(diffMins / 60);
+  const diffDays = Math.floor(diffHours / 24);
+
+  if (diffMins < 1) return 'Just now';
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays < 30) return `${diffDays}d ago`;
+  return date.toLocaleDateString();
+}
+
+/**
+ * Clean storage for a specific project
+ */
+export function cleanProjectStorage(projectId: string, options: {
+  cliHistory?: boolean;
+  memory?: boolean;
+  cache?: boolean;
+  config?: boolean;
+  all?: boolean;
+} = { all: true }): { success: boolean; freedBytes: number; errors: string[] } {
+  const paths = StoragePaths.projectById(projectId);
+  let freedBytes = 0;
+  const errors: string[] = [];
+
+  const shouldClean = (type: keyof typeof options) => options.all || options[type];
+
+  const cleanDir = (dirPath: string, name: string) => {
+    if (existsSync(dirPath)) {
+      try {
+        const size = getDirSize(dirPath);
+        rmSync(dirPath, { recursive: true, force: true });
+        freedBytes += size;
+      } catch (err) {
+        errors.push(`Failed to clean ${name}: ${err}`);
+      }
+    }
+  };
+
+  if (shouldClean('cliHistory')) cleanDir(paths.cliHistory, 'CLI history');
+  if (shouldClean('memory')) cleanDir(paths.memory, 'Memory store');
+  if (shouldClean('cache')) cleanDir(paths.cache, 'Cache');
+  if (shouldClean('config')) cleanDir(paths.config, 'Config');
+
+  // Remove project directory if empty
+  if (existsSync(paths.root)) {
+    try {
+      const remaining = readdirSync(paths.root);
+      if (remaining.length === 0) {
+        rmSync(paths.root, { recursive: true, force: true });
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+
+  return { success: errors.length === 0, freedBytes, errors };
+}
+
+/**
+ * Clean all storage
+ */
+export function cleanAllStorage(options: {
+  cliHistory?: boolean;
+  memory?: boolean;
+  cache?: boolean;
+  config?: boolean;
+  globalDb?: boolean;
+  all?: boolean;
+} = { all: true }): { success: boolean; freedBytes: number; projectsCleaned: number; errors: string[] } {
+  const stats = getStorageStats();
+  let freedBytes = 0;
+  let projectsCleaned = 0;
+  const errors: string[] = [];
+
+  // Clean projects
+  for (const project of stats.projects) {
+    const result = cleanProjectStorage(project.projectId, options);
+    freedBytes += result.freedBytes;
+    if (result.errors.length === 0) {
+      projectsCleaned++;
+    }
+    errors.push(...result.errors);
+  }
+
+  // Clean global database if requested
+  if (options.all || options.globalDb) {
+    const mcpPath = StoragePaths.global.mcpTemplates();
+    if (existsSync(mcpPath)) {
+      try {
+        const size = getFileSize(mcpPath);
+        rmSync(mcpPath, { force: true });
+        freedBytes += size;
+      } catch (err) {
+        errors.push(`Failed to clean global database: ${err}`);
+      }
+    }
+  }
+
+  return { success: errors.length === 0, freedBytes, projectsCleaned, errors };
+}
+
+/**
+ * Get project ID from project path
+ */
+export function resolveProjectId(projectPath: string): string {
+  return getProjectId(resolve(projectPath));
+}
+
+/**
+ * Check if a project ID exists in storage
+ */
+export function projectExists(projectId: string): boolean {
+  const paths = StoragePaths.projectById(projectId);
+  return existsSync(paths.root);
+}
+
+/**
+ * Get storage location instructions for changing it
+ */
+export function getStorageLocationInstructions(): string {
+  return `
+To change the CCW storage location, set the CCW_DATA_DIR environment variable:
+
+  Windows (PowerShell):
+    $env:CCW_DATA_DIR = "D:\\custom\\ccw-data"
+
+  Windows (Command Prompt):
+    set CCW_DATA_DIR=D:\\custom\\ccw-data
+
+  Linux/macOS:
+    export CCW_DATA_DIR="/custom/ccw-data"
+
+  Permanent (add to shell profile):
+    echo 'export CCW_DATA_DIR="/custom/ccw-data"' >> ~/.bashrc
+
+Note: Existing data will NOT be migrated automatically.
+To migrate, manually copy the contents of the old directory to the new location.
+
+Current location: ${CCW_HOME}
+`;
+}

package/src/tools/write-file.ts

@@ -0,0 +1,222 @@
+/**
+ * Write File Tool - Create or overwrite files
+ *
+ * Features:
+ * - Create new files or overwrite existing
+ * - Auto-create parent directories
+ * - Support for text content with proper encoding
+ * - Optional backup before overwrite
+ */
+
+import { z } from 'zod';
+import type { ToolSchema, ToolResult } from '../types/tool.js';
+import { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync, statSync } from 'fs';
+import { resolve, isAbsolute, dirname, basename } from 'path';
+import { validatePath } from '../utils/path-validator.js';
+
+// Define Zod schema for validation
+const ParamsSchema = z.object({
+  path: z.string().min(1, 'Path is required'),
+  content: z.string(),
+  createDirectories: z.boolean().default(true),
+  backup: z.boolean().default(false),
+  encoding: z.enum(['utf8', 'utf-8', 'ascii', 'latin1', 'binary', 'hex', 'base64']).default('utf8'),
+});
+
+type Params = z.infer<typeof ParamsSchema>;
+
+// Compact result for output
+interface WriteResult {
+  path: string;
+  bytes: number;
+  message: string;
+}
+
+/**
+ * Ensure parent directory exists
+ * @param filePath - Path to file
+ */
+function ensureDir(filePath: string): void {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Create backup of existing file
+ * @param filePath - Path to file
+ * @returns Backup path or null if no backup created
+ */
+function createBackup(filePath: string): string | null {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  const dir = dirname(filePath);
+  const name = basename(filePath);
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = resolve(dir, `.${name}.${timestamp}.bak`);
+
+  try {
+    const content = readFileSync(filePath);
+    writeFileSync(backupPath, content);
+    return backupPath;
+  } catch (error) {
+    throw new Error(`Failed to create backup: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * Verify file write operation completed successfully
+ * @param filePath - Path to written file
+ * @param expectedBytes - Expected file size in bytes
+ * @param encoding - File encoding used
+ * @returns Error message if verification fails, null if successful
+ */
+function verifyFileWrite(filePath: string, expectedBytes: number, encoding: BufferEncoding): string | null {
+  // Check 1: File exists
+  if (!existsSync(filePath)) {
+    return `File verification failed: file does not exist at ${filePath}`;
+  }
+
+  try {
+    // Check 2: File size matches expected bytes
+    const stats = statSync(filePath);
+    if (stats.size !== expectedBytes) {
+      return `File verification failed: size mismatch (expected ${expectedBytes}B, actual ${stats.size}B)`;
+    }
+
+    // Check 3: File is readable (for long JSON files)
+    const readContent = readFileSync(filePath, { encoding });
+    const actualBytes = Buffer.byteLength(readContent, encoding);
+    if (actualBytes !== expectedBytes) {
+      return `File verification failed: content size mismatch after read (expected ${expectedBytes}B, read ${actualBytes}B)`;
+    }
+
+    return null; // Verification passed
+  } catch (error) {
+    return `File verification failed: ${(error as Error).message}`;
+  }
+}
+
+// Tool schema for MCP
+export const schema: ToolSchema = {
+  name: 'write_file',
+  description: `Write content to file. Auto-creates parent directories.
+
+Usage: write_file(path="file.js", content="code here")
+Options: backup=true (backup before overwrite), createDirectories=false (disable auto-creation), encoding="utf8"`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Path to the file to create or overwrite',
+      },
+      content: {
+        type: 'string',
+        description: 'Content to write to the file',
+      },
+      createDirectories: {
+        type: 'boolean',
+        description: 'Create parent directories if they do not exist (default: true)',
+        default: true,
+      },
+      backup: {
+        type: 'boolean',
+        description: 'Create backup of existing file before overwriting (default: false)',
+        default: false,
+      },
+      encoding: {
+        type: 'string',
+        description: 'File encoding (default: utf8)',
+        default: 'utf8',
+        enum: ['utf8', 'utf-8', 'ascii', 'latin1', 'binary', 'hex', 'base64'],
+      },
+    },
+    required: ['path', 'content'],
+  },
+};
+
+// Handler function
+export async function handler(params: Record<string, unknown>): Promise<ToolResult<WriteResult>> {
+  const parsed = ParamsSchema.safeParse(params);
+  if (!parsed.success) {
+    return { success: false, error: `Invalid params: ${parsed.error.message}` };
+  }
+
+  const {
+    path: filePath,
+    content,
+    createDirectories,
+    backup,
+    encoding,
+  } = parsed.data;
+
+  // Validate and resolve path
+  const resolvedPath = await validatePath(filePath);
+  const fileExists = existsSync(resolvedPath);
+
+  // Create parent directories if needed
+  if (createDirectories) {
+    ensureDir(resolvedPath);
+  } else if (!existsSync(dirname(resolvedPath))) {
+    return {
+      success: false,
+      error: `Parent directory does not exist: ${dirname(resolvedPath)}`,
+    };
+  }
+
+  // Create backup if requested and file exists
+  let backupPath: string | null = null;
+  if (backup && fileExists) {
+    try {
+      backupPath = createBackup(resolvedPath);
+    } catch (error) {
+      return {
+        success: false,
+        error: (error as Error).message,
+      };
+    }
+  }
+
+  // Write file
+  try {
+    writeFileSync(resolvedPath, content, { encoding });
+    const bytes = Buffer.byteLength(content, encoding);
+
+    // Verify write operation completed successfully
+    const verificationError = verifyFileWrite(resolvedPath, bytes, encoding as BufferEncoding);
+    if (verificationError) {
+      return {
+        success: false,
+        error: verificationError,
+      };
+    }
+
+    // Build compact message
+    let message: string;
+    if (fileExists) {
+      message = backupPath
+        ? `Overwrote (${bytes}B, backup: ${basename(backupPath)}) - verified`
+        : `Overwrote (${bytes}B) - verified`;
+    } else {
+      message = `Created (${bytes}B) - verified`;
+    }
+
+    return {
+      success: true,
+      result: {
+        path: resolvedPath,
+        bytes,
+        message,
+      },
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to write file: ${(error as Error).message}`,
+    };
+  }
+}

package/src/types/config.ts

@@ -0,0 +1,11 @@
+export interface ServerConfig {
+  port: number;
+  host: string;
+  open: boolean;
+}
+
+export interface McpConfig {
+  enabledTools: string[] | null;
+  serverName: string;
+  serverVersion: string;
+}

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from './tool.js';
+export * from './session.js';
+export * from './config.js';

package/src/types/session.ts

@@ -0,0 +1,25 @@
+export type SessionStatus = 'active' | 'paused' | 'completed' | 'archived';
+export type SessionType = 'workflow' | 'review' | 'tdd' | 'test' | 'docs' | 'lite-plan' | 'lite-fix';
+export type ContentType =
+  | 'session' | 'plan' | 'task' | 'summary'
+  | 'process' | 'chat' | 'brainstorm'
+  | 'review-dim' | 'review-iter' | 'review-fix'
+  | 'todo' | 'context';
+
+export interface SessionMetadata {
+  id: string;
+  type: SessionType;
+  status: SessionStatus;
+  description?: string;
+  project?: string;
+  created: string;
+  updated: string;
+}
+
+export interface SessionOperationResult {
+  success: boolean;
+  sessionId?: string;
+  path?: string;
+  data?: unknown;
+  error?: string;
+}