@meltstudio/meltctl 2.0.3 → 2.2.0

package/README.md

@@ -70,6 +70,18 @@ Updates your project templates to the latest version. This command:
 - Verifies .melt/ workspace migration status
 - Handles version compatibility automatically
 
+### Clean Project
+
+```bash
+meltctl project clean
+```
+
+Safely removes all Melt-generated files from your project while preserving user-created content. This command:
+- Removes the entire `.melt/` directory (all Melt-generated content)
+- Selectively removes only Melt commands from `.cursor/commands/`
+- Preserves user-created files in `.cursor/commands/`
+- Provides interactive confirmation before deletion
+
 ## 🛠️ Requirements
 
 - Node.js 22+ (works with Node.js 18+ but 22+ recommended)
@@ -120,12 +132,13 @@ This tool is part of the Melt Development Process. For issues or contributions:
 The CLI uses a bundled template system organized in:
 
 ```
-packages/cli/templates/
-├── cursor-commands/     # All 8 Cursor AI command templates
-├── melt-memory/        # Project context templates with dynamic timestamps
-└── melt-scripts/       # Utility scripts for sh and PowerShell
-    ├── sh/            # Bash/zsh utility scripts
-    └── ps/            # PowerShell utility scripts
+packages/cli/
+├── memory/            # Project context and standards
+├── scripts/           # Utility scripts for sh and PowerShell
+│   ├── sh/            # Bash/zsh utility scripts
+│   └── ps/            # PowerShell utility scripts
+└── templates/
+    └── cursor-commands/ # All 8 Cursor AI command templates
 ```
 
 Templates support dynamic content replacement (like timestamps) and are copied to your project during initialization.

package/dist/commands/project/clean.d.ts

@@ -0,0 +1,5 @@
+interface CleanOptions {
+    placeholder?: never;
+}
+export declare function cleanCommand(_options?: CleanOptions): Promise<void>;
+export {};

package/dist/commands/project/clean.js

@@ -0,0 +1,239 @@
+import { intro, outro, confirm, spinner } from '@clack/prompts';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+// List of Melt-generated command files to remove
+const MELT_COMMAND_FILES = [
+    'melt-plan.md',
+    'melt-test-plan.md',
+    'melt-docs.md',
+    'melt-implement.md',
+    'melt-pr.md',
+    'melt-review.md',
+    'melt-complete.md',
+    'melt-debug.md',
+];
+export async function cleanCommand(_options = {}) {
+    intro(chalk.blue('🧹 Melt Project - Clean'));
+    const currentDir = process.cwd();
+    const meltDir = path.join(currentDir, '.melt');
+    const cursorCommandsDir = path.join(currentDir, '.cursor', 'commands');
+    // Check if this is a Melt workspace
+    const hasMeltWorkspace = await fs.pathExists(meltDir);
+    const hasCursorCommands = await fs.pathExists(cursorCommandsDir);
+    if (!hasMeltWorkspace && !hasCursorCommands) {
+        console.log(chalk.yellow('⚠️  No Melt workspace found in this directory.'));
+        console.log("This project doesn't appear to have Melt tools installed.");
+        outro(chalk.gray('Nothing to clean.'));
+        return;
+    }
+    // Analyze what will be cleaned
+    const analysisResult = await analyzeCleanupTarget(currentDir);
+    if (analysisResult.removedFiles.length === 0 && analysisResult.removedDirs.length === 0) {
+        console.log(chalk.yellow('⚠️  No Melt files found to clean.'));
+        outro(chalk.gray('Nothing to clean.'));
+        return;
+    }
+    // Show what will be cleaned
+    displayCleanupPlan(analysisResult);
+    // Get confirmation
+    const shouldProceed = await confirm({
+        message: 'Do you want to proceed with cleaning? This action cannot be undone.',
+    });
+    if (!shouldProceed) {
+        outro(chalk.gray('Clean operation cancelled.'));
+        return;
+    }
+    // Perform the cleanup
+    const s = spinner();
+    s.start('Cleaning Melt workspace...');
+    try {
+        const cleanResult = await performCleanup(currentDir);
+        s.stop('✅ Cleanup completed!');
+        displayCleanupResults(cleanResult);
+        outro(chalk.green('🎉 Melt workspace cleaned successfully!'));
+    }
+    catch (error) {
+        s.stop('❌ Cleanup failed');
+        console.error(chalk.red('Error during cleanup:'), error);
+        process.exit(1);
+    }
+}
+async function analyzeCleanupTarget(baseDir) {
+    const result = {
+        removedFiles: [],
+        removedDirs: [],
+        preservedFiles: [],
+        errors: [],
+    };
+    const meltDir = path.join(baseDir, '.melt');
+    const cursorCommandsDir = path.join(baseDir, '.cursor', 'commands');
+    try {
+        // Check .melt directory (remove entirely)
+        if (await fs.pathExists(meltDir)) {
+            result.removedDirs.push('.melt/');
+        }
+        // Check .cursor/commands directory (selective removal)
+        if (await fs.pathExists(cursorCommandsDir)) {
+            const commandFiles = await fs.readdir(cursorCommandsDir);
+            for (const file of commandFiles) {
+                const filePath = path.join(cursorCommandsDir, file);
+                const stat = await fs.stat(filePath);
+                if (stat.isFile()) {
+                    if (MELT_COMMAND_FILES.includes(file)) {
+                        result.removedFiles.push(path.join('.cursor/commands', file));
+                    }
+                    else {
+                        result.preservedFiles.push(path.join('.cursor/commands', file));
+                    }
+                }
+            }
+            // Check if .cursor/commands will be empty after cleaning
+            const meltFiles = commandFiles.filter(file => MELT_COMMAND_FILES.includes(file));
+            const nonMeltFiles = commandFiles.filter(file => !MELT_COMMAND_FILES.includes(file));
+            if (meltFiles.length > 0 && nonMeltFiles.length === 0) {
+                result.removedDirs.push('.cursor/commands/');
+                // Also check if .cursor itself would be empty
+                const cursorDir = path.join(baseDir, '.cursor');
+                const cursorContents = await fs.readdir(cursorDir);
+                if (cursorContents.length === 1 && cursorContents[0] === 'commands') {
+                    result.removedDirs.push('.cursor/');
+                }
+            }
+        }
+    }
+    catch (error) {
+        result.errors.push(`Failed to analyze cleanup target: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return result;
+}
+async function performCleanup(baseDir) {
+    const result = {
+        removedFiles: [],
+        removedDirs: [],
+        preservedFiles: [],
+        errors: [],
+    };
+    const meltDir = path.join(baseDir, '.melt');
+    const cursorCommandsDir = path.join(baseDir, '.cursor', 'commands');
+    try {
+        // Remove .melt directory entirely
+        if (await fs.pathExists(meltDir)) {
+            await fs.remove(meltDir);
+            result.removedDirs.push('.melt/');
+        }
+        // Remove Melt command files from .cursor/commands
+        if (await fs.pathExists(cursorCommandsDir)) {
+            const commandFiles = await fs.readdir(cursorCommandsDir);
+            let hasNonMeltFiles = false;
+            for (const file of commandFiles) {
+                const filePath = path.join(cursorCommandsDir, file);
+                const stat = await fs.stat(filePath);
+                if (stat.isFile()) {
+                    if (MELT_COMMAND_FILES.includes(file)) {
+                        try {
+                            await fs.remove(filePath);
+                            result.removedFiles.push(path.join('.cursor/commands', file));
+                        }
+                        catch (error) {
+                            result.errors.push(`Failed to remove ${file}: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                    else {
+                        hasNonMeltFiles = true;
+                        result.preservedFiles.push(path.join('.cursor/commands', file));
+                    }
+                }
+            }
+            // Remove empty directories if no user files remain
+            if (!hasNonMeltFiles) {
+                try {
+                    await fs.remove(cursorCommandsDir);
+                    result.removedDirs.push('.cursor/commands/');
+                    // Check if .cursor directory is now empty
+                    const cursorDir = path.join(baseDir, '.cursor');
+                    if (await fs.pathExists(cursorDir)) {
+                        const cursorContents = await fs.readdir(cursorDir);
+                        if (cursorContents.length === 0) {
+                            await fs.remove(cursorDir);
+                            result.removedDirs.push('.cursor/');
+                        }
+                    }
+                }
+                catch (error) {
+                    result.errors.push(`Failed to remove empty directories: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+    }
+    catch (error) {
+        result.errors.push(`Cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return result;
+}
+function displayCleanupPlan(result) {
+    console.log();
+    console.log(chalk.cyan('📋 Cleanup Plan:'));
+    console.log();
+    if (result.removedDirs.length > 0) {
+        console.log(chalk.yellow('Directories to be removed:'));
+        result.removedDirs.forEach(dir => {
+            console.log(`  • ${chalk.red(dir)}`);
+        });
+        console.log();
+    }
+    if (result.removedFiles.length > 0) {
+        console.log(chalk.yellow('Files to be removed:'));
+        result.removedFiles.forEach(file => {
+            console.log(`  • ${chalk.red(file)}`);
+        });
+        console.log();
+    }
+    if (result.preservedFiles.length > 0) {
+        console.log(chalk.green('Files to be preserved:'));
+        result.preservedFiles.forEach(file => {
+            console.log(`  • ${chalk.cyan(file)}`);
+        });
+        console.log();
+    }
+    if (result.errors.length > 0) {
+        console.log(chalk.red('Analysis errors:'));
+        result.errors.forEach(error => {
+            console.log(`  ⚠️  ${error}`);
+        });
+        console.log();
+    }
+}
+function displayCleanupResults(result) {
+    console.log();
+    console.log(chalk.green('🎯 Cleanup Summary:'));
+    console.log();
+    if (result.removedDirs.length > 0) {
+        console.log(chalk.green(`✅ Removed ${result.removedDirs.length} directories:`));
+        result.removedDirs.forEach(dir => {
+            console.log(`   • ${dir}`);
+        });
+        console.log();
+    }
+    if (result.removedFiles.length > 0) {
+        console.log(chalk.green(`✅ Removed ${result.removedFiles.length} files:`));
+        result.removedFiles.forEach(file => {
+            console.log(`   • ${file}`);
+        });
+        console.log();
+    }
+    if (result.preservedFiles.length > 0) {
+        console.log(chalk.cyan(`🔒 Preserved ${result.preservedFiles.length} user files:`));
+        result.preservedFiles.forEach(file => {
+            console.log(`   • ${file}`);
+        });
+        console.log();
+    }
+    if (result.errors.length > 0) {
+        console.log(chalk.red(`❌ Errors encountered (${result.errors.length}):`));
+        result.errors.forEach(error => {
+            console.log(`   • ${error}`);
+        });
+        console.log();
+    }
+}

package/dist/commands/project/init.js

@@ -119,22 +119,21 @@ async function copyTemplates(baseDir, shell) {
     if (existsSync(cursorCommandsTemplateDir)) {
         fs.copySync(cursorCommandsTemplateDir, cursorCommandsDestDir);
     }
-    // Create initial context file from template
-    const contextTemplatePath = join(templatesDir, 'melt-memory', 'context.md');
+    // Create initial context file from memory
+    const contextSourcePath = join(__dirname, '../../../memory', 'context.md');
     const contextDestPath = join(baseDir, '.melt', 'memory', 'context.md');
-    if (existsSync(contextTemplatePath)) {
-        let contextContent = readFileSync(contextTemplatePath, 'utf8');
+    if (existsSync(contextSourcePath)) {
+        let contextContent = readFileSync(contextSourcePath, 'utf8');
         // Replace timestamp placeholders
         const timestamp = new Date().toISOString();
         contextContent = contextContent.replace(/{{timestamp}}/g, timestamp);
         fs.writeFileSync(contextDestPath, contextContent, 'utf8');
     }
-    // Copy shell script from template
-    const scriptExt = shell === 'ps' ? 'ps1' : 'sh';
-    const scriptTemplatePath = join(templatesDir, 'melt-scripts', shell, `common.${scriptExt}`);
-    const scriptDestPath = join(baseDir, '.melt', 'scripts', shell, `common.${scriptExt}`);
-    if (existsSync(scriptTemplatePath)) {
-        fs.copySync(scriptTemplatePath, scriptDestPath);
+    // Copy shell scripts from CLI package
+    const scriptsSourceDir = join(__dirname, '../../../scripts', shell);
+    const scriptsDestDir = join(baseDir, '.melt', 'scripts', shell);
+    if (existsSync(scriptsSourceDir)) {
+        fs.copySync(scriptsSourceDir, scriptsDestDir);
     }
 }
 function createVersionFile(meltDir) {

package/dist/index.js

@@ -5,6 +5,7 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { initCommand } from './commands/project/init.js';
 import { updateCommand } from './commands/project/update.js';
+import { cleanCommand } from './commands/project/clean.js';
 // Read version from package.json
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -34,4 +35,10 @@ projectCommand
     .command('update')
     .description('Update project configurations to latest version')
     .action(updateCommand);
+projectCommand
+    .command('clean')
+    .description('Remove all Melt-generated files from the project')
+    .action(() => {
+    return cleanCommand();
+});
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meltstudio/meltctl",
-  "version": "2.0.3",
+  "version": "2.2.0",
   "description": "CLI tool for Melt development process automation - initialize and update project configurations",
   "main": "dist/index.js",
   "type": "module",

package/templates/cursor-commands/melt-plan.md

@@ -1,15 +1,25 @@
 ---
-description: Create implementation plan following Melt's domain-driven architecture standards
+description: Create implementation plan with User Story and RFC validation following Melt's domain-driven architecture standards
+scripts:
+  sh: .melt/scripts/sh/get-plan-context.sh --json
+  ps: .melt/scripts/ps/get-plan-context.ps1 -Json
 ---
 
 Create a comprehensive implementation plan for the requested feature. Follow these steps:
 
-1. **Analyze Requirements**:
-   - Read `.melt/memory/context.md` for project context and constraints
+1. **Collect Requirements**:
+   - Run `{SCRIPT}` from the project root and parse JSON for USER_STORY, RFC, ISSUE_ID, PLAN_FILE, and PROJECT_ROOT
+   - If script fails, prompt manually for User Story and RFC
+   - Validate that both User Story and RFC are complete and actionable
+
+2. **Analyze Requirements**:
+   - Analyze the provided User Story for clear acceptance criteria and user value
+   - Review the RFC for technical decisions, architecture, and constraints
+   - Read `.melt/memory/context.md` for additional project context
    - Identify the target domain(s) this feature belongs to
    - Determine integration points with existing domains
 
-2. **Architecture Planning**:
+3. **Architecture Planning**:
    - Design domain structure following our patterns:
      ```
      src/domains/[domain]/
@@ -23,27 +33,28 @@ Create a comprehensive implementation plan for the requested feature. Follow the
    - Plan component hierarchy and state management
    - Design data flow and API integration points
 
-3. **Technical Decisions**:
+4. **Technical Decisions**:
    - Choose appropriate React patterns (server vs client components)
    - Plan Zod schemas for data validation
    - Design TypeScript interfaces and types
    - Plan testing strategy (unit, integration, e2e)
 
-4. **Implementation Strategy**:
+5. **Implementation Strategy**:
    - Break down into atomic, testable units
    - Identify dependencies and execution order
    - Plan for error handling and edge cases
    - Consider accessibility and performance requirements
 
-5. **Create Detailed Plan**:
+6. **Create Detailed Plan**:
    - List specific files to create/modify
    - Define component interfaces and props
    - Specify API endpoints and data contracts
    - Plan test cases and coverage targets
 
-6. **Save Planning Output**:
-   - Save comprehensive plan to `.melt/outputs/plans/[timestamp]-plan.md`
-   - Update `.melt/memory/context.md` with planning decisions
-   - Create task breakdown for implementation
+7. **Save Planning Output**:
+   - Save comprehensive plan to the PLAN_FILE path provided by the script
+   - Include User Story and RFC as context sections in the plan
+   - Update `.melt/memory/context.md` with planning decisions and issue reference
+   - Create task breakdown for implementation with clear dependencies
 
 Focus on maintainable, testable code that follows our domain-driven architecture principles.

package/templates/melt-memory/context.md

@@ -1,23 +0,0 @@
-# Project Context
-
-## Project Overview
-This project uses Melt's development standards with domain-driven architecture.
-
-## Architecture Principles
-- **Domain-Driven Design**: Code organized by business domains
-- **React 2025 Standards**: Functional components, hooks, TypeScript strict
-- **Type Safety**: Zod schemas for runtime validation
-- **Testing**: 80% coverage minimum with comprehensive test strategies
-
-## Development Workflow
-1. **Plan**: Create implementation plans in `.melt/outputs/plans/`
-2. **Implement**: Follow domain architecture patterns
-3. **Review**: Ensure quality and compliance
-4. **Debug**: Systematic problem-solving approach
-
-## Current Status
-- Initialized: {{timestamp}}
-- Last Updated: {{timestamp}}
-
-## Notes
-Update this file as the project evolves to maintain context for AI assistants and team members.

package/templates/melt-scripts/ps/common.ps1

@@ -1,48 +0,0 @@
-#!/usr/bin/env pwsh
-# Common utilities for Melt development workflow
-
-function Get-ProjectRoot {
-    try {
-        git rev-parse --show-toplevel
-    }
-    catch {
-        Get-Location
-    }
-}
-
-function Get-Timestamp {
-    Get-Date -Format "yyyyMMdd-HHmmss"
-}
-
-function Test-MeltWorkspace {
-    if (-not (Test-Path ".melt" -PathType Container)) {
-        Write-Error "ERROR: .melt workspace not found. Run 'meltctl project init' first."
-        exit 1
-    }
-}
-
-function New-OutputFile {
-    param(
-        [string]$Category,
-        [string]$Name
-    )
-
-    $timestamp = Get-Timestamp
-    $filename = "$timestamp-$Name.md"
-    $filepath = ".melt/outputs/$Category/$filename"
-
-    New-Item -Path ".melt/outputs/$Category" -ItemType Directory -Force | Out-Null
-    return $filepath
-}
-
-function Update-Context {
-    param([string]$Message)
-
-    $timestamp = Get-Date -Format "yyyy-MM-ddTHH:mm:ssK"
-
-    Add-Content -Path ".melt/memory/context.md" -Value "## Update: $timestamp"
-    Add-Content -Path ".melt/memory/context.md" -Value $Message
-    Add-Content -Path ".melt/memory/context.md" -Value ""
-}
-
-Write-Output "Melt development utilities loaded."

package/templates/melt-scripts/sh/common.sh

@@ -1,44 +0,0 @@
-#!/usr/bin/env bash
-# Common utilities for Melt development workflow
-
-# Get project root directory
-get_project_root() {
-    git rev-parse --show-toplevel 2>/dev/null || pwd
-}
-
-# Get current timestamp for file naming
-get_timestamp() {
-    date '+%Y%m%d-%H%M%S'
-}
-
-# Check if .melt directory exists
-check_melt_workspace() {
-    if [[ ! -d ".melt" ]]; then
-        echo "ERROR: .melt workspace not found. Run 'meltctl project init' first."
-        exit 1
-    fi
-}
-
-# Create output file with timestamp
-create_output_file() {
-    local category="$1"
-    local name="$2"
-    local timestamp=$(get_timestamp)
-    local filename="${timestamp}-${name}.md"
-    local filepath=".melt/outputs/${category}/${filename}"
-
-    mkdir -p ".melt/outputs/${category}"
-    echo "$filepath"
-}
-
-# Update context file with new information
-update_context() {
-    local message="$1"
-    local timestamp=$(date -Iseconds)
-
-    echo "## Update: $timestamp" >> .melt/memory/context.md
-    echo "$message" >> .melt/memory/context.md
-    echo "" >> .melt/memory/context.md
-}
-
-echo "Melt development utilities loaded."