Enhance profile list and validate commands with better UX

[gregpriday]

Summary

The profile:list and profile:validate commands work but could provide better user experience with improved output formatting, source provenance display, and more actionable validation error messages.

Problem Statement

While the commands are functional, they could be more helpful:

Current Limitations:

• profile:list shows basic information but no source indication (built-in vs user vs project)
• Validation errors could be more specific with suggested fixes
• No visual distinction between profile types
• Output format not optimized for quick scanning
• Missing metadata (version, author, last modified)
• No search/filter capabilities

This affects:

• Users trying to find the right profile
• Debugging profile issues
• Understanding profile precedence
• Developer experience

Current State

Existing Functionality:

• bin/copytree.js - profile:list command
• bin/copytree.js - profile:validate command
• src/profiles/ProfileLoader.js - Profile loading with precedence
• src/ui/components/ProfileListView.js - List UI (20% coverage)

Profile Search Order (Already Implemented):

1. Project: .copytree/profiles/
2. User: ~/.copytree/profiles/
3. Built-in: profiles/

Current Output:

Available Profiles:

Built-in Profiles:
  default          General-purpose profile with comprehensive exclusions for
                   common build artifacts

To use a profile: copytree --profile <name>

Proposed Solution

Enhanced List Output

Available Profiles:

Built-in Profiles (1):
  default         v1.0.0    General-purpose profile with comprehensive exclusions
                            Source: <copytree>/profiles/default.yml

User Profiles (2):
  minimal         v1.0.0    Minimal profile for quick outputs
                            Source: ~/.copytree/profiles/minimal.yml
  documentation   v1.0.0    Profile optimized for documentation
                            Source: ~/.copytree/profiles/documentation.yml

Project Profiles (0):
  (none - create profiles in .copytree/profiles/)

Usage:
  copytree --profile <name>
  copytree profile:validate <name>

Enhanced Validation Output

Validating profile: my-profile
Source: .copytree/profiles/my-profile.yml

✗ Validation Failed (3 errors, 1 warning)

Errors:
  1. Invalid field 'transformer.pdf.maxPages'
     Expected: number
     Got: string ("50")
     Fix: Change to maxPages: 50

  2. Missing required field 'name'
     Location: Root object
     Fix: Add name: "my-profile"

  3. Invalid pattern in exclude[2]
     Pattern: "**/*.{test,spec.js"
     Error: Unclosed brace
     Fix: Use "**/*.{test,spec}.js"

Warnings:
  1. Deprecated field 'options.gitignore'
     Suggestion: Use 'options.respectGitignore' instead

Profile is invalid and cannot be used.

Affected Components

• src/ui/components/ProfileListView.js - List display
• src/ui/components/ValidationView.js - Validation display (4% coverage)
• src/profiles/ProfileLoader.js - Profile discovery
• src/profiles/ProfileValidator.js - Validation logic

Implementation Approach

1. Enhance ProfileListView

• Show source path for each profile
• Display version and description
• Group by source (built-in, user, project)
• Add count per section
• Show last modified time (optional)
• Support --json flag for machine-readable output

2. Enhance ValidationView

• Parse schema validation errors
• Show specific field path (e.g., transformers.pdf.options.maxPages)
• Show expected vs received types
• Provide suggested fixes
• Group by severity (errors vs warnings)
• Show line numbers if schema supports it

3. Add Features

• --json flag for both commands
• Filter by source: --source built-in|user|project
• Search by name pattern: --search docs*
• Show all validation issues, not just first failure

Tasks

• Update ProfileListView.js to show source paths
• Add version column to profile list
• Group profiles by source (built-in, user, project)
• Add profile count per section
• Support --json flag in profile:list command
• Enhance ValidationView.js to show detailed error paths
• Parse schema validation errors for specific field identification
• Add expected vs received type comparison
• Generate suggested fixes for common errors
• Group validation messages by severity
• Show all errors, not just first failure
• Add --json flag to profile:validate command
• Improve error messages for missing profiles
• Add hints about profile search order in errors
• Increase test coverage for ProfileListView (currently 20%)
• Increase test coverage for ValidationView (currently 4%)
• Add unit tests for enhanced formatting
• Add integration tests for both commands with various profile states
• Update documentation in docs/profiles/profile-overview.md
• Add examples of validation errors and fixes to docs

Acceptance Criteria

• profile:list shows source path for each profile
• Profiles grouped by source (built-in, user, project)
• Version and description displayed for each profile
• --json flag outputs machine-readable format
• profile:validate shows specific field paths for errors
• Validation errors include suggested fixes
• All validation issues shown, not just first one
• Error messages are actionable and clear
• Test coverage > 80% for both ProfileListView and ValidationView
• Documentation includes examples of enhanced output
• No visual regressions in terminal output

Additional Context

Profile Sources (Already Working):

Project:  ./.copytree/profiles/*.yml
User:     ~/.copytree/profiles/*.yml
Built-in: <install-dir>/profiles/*.yml

Common Validation Errors to Improve:

1. Type mismatches (string vs number)
2. Missing required fields
3. Invalid glob patterns
4. Unknown transformer names
5. Deprecated options
6. Invalid regex in patterns

JSON Output Example:

{
  "profiles": [
    {
      "name": "default",
      "version": "1.0.0",
      "source": "built-in",
      "path": "/usr/local/lib/node_modules/copytree/profiles/default.yml",
      "description": "General-purpose profile..."
    }
  ],
  "counts": {
    "built-in": 1,
    "user": 2,
    "project": 0
  }
}

References:

• Prettier's config listing - Config file search
• ESLint's config cascade - Precedence display
• Jest's config - Validation error formatting

Related Issues:

• Complements the profile system documentation
• Improves developer experience when creating profiles
• Makes debugging profile issues easier