@kennethsolomon/shipkit 1.0.0

package/skills/sk:setup-optimizer/lib/discover.py

@@ -0,0 +1,221 @@
+"""Intelligent project structure, documentation, and workflow discovery."""
+
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+
+# Directories to exclude from discovery
+EXCLUDE_DIRS = {
+    'node_modules', '.next', 'dist', 'build', 'out',
+    '.venv', 'venv', 'env', '__pycache__',
+    '.git', '.github/actions', 'vendor',
+    '.pytest_cache', '.mypy_cache', '.tox',
+    'coverage', '.coverage', 'htmlcov',
+    'egg-info', '.eggs', '*.egg-info',
+}
+
+# Documentation patterns to look for
+DOC_PATTERNS = {
+    'README.md': 'Project overview',
+    'CONTRIBUTING.md': 'How to contribute',
+    'CODE_OF_CONDUCT.md': 'Code of conduct',
+    'CHANGELOG.md': 'Version history',
+    'LICENSE': 'License information',
+}
+
+
+def discover_directories(root_path: Path) -> Dict[str, str]:
+    """Auto-discover key project directories and their purposes.
+
+    Args:
+        root_path: Project root directory
+
+    Returns:
+        Dict mapping directory names to descriptions
+    """
+    found_dirs = {}
+
+    # Define directory patterns and their descriptions
+    dir_patterns = {
+        'src': 'Application source code',
+        'lib': 'Library utilities and helpers',
+        'app': 'Application code',
+        'source': 'Source code',
+        'tests': 'Test suite',
+        'test': 'Test suite',
+        '__tests__': 'Test suite',
+        'spec': 'Test specifications',
+        'docs': 'Documentation',
+        'public': 'Static assets and public files',
+        'static': 'Static assets',
+        'assets': 'Project assets',
+        'scripts': 'Utility and build scripts',
+        'config': 'Configuration files',
+        'migrations': 'Database migrations',
+        'prisma': 'Prisma database schema',
+        'alembic': 'SQLAlchemy migrations',
+        '.github': 'GitHub configuration and workflows',
+        'infra': 'Infrastructure as code',
+        'terraform': 'Terraform configuration',
+        'docker': 'Docker configuration',
+    }
+
+    for dir_name, description in dir_patterns.items():
+        dir_path = root_path / dir_name
+        if dir_path.exists() and dir_path.is_dir():
+            # Skip if in exclude list
+            if dir_name not in EXCLUDE_DIRS:
+                found_dirs[dir_name] = description
+
+    return found_dirs
+
+
+def discover_documentation(root_path: Path) -> Dict[str, str]:
+    """Find documentation files and link them.
+
+    Args:
+        root_path: Project root directory
+
+    Returns:
+        Dict mapping doc file paths to descriptions
+    """
+    found_docs = {}
+
+    # Check root level documentation
+    for pattern, description in DOC_PATTERNS.items():
+        doc_path = root_path / pattern
+        if doc_path.exists() and doc_path.is_file():
+            found_docs[pattern] = description
+
+    # Check docs/ directory for additional documentation
+    docs_dir = root_path / 'docs'
+    if docs_dir.exists() and docs_dir.is_dir():
+        # Look for common subdirectories and files
+        doc_files = {
+            'API.md': 'API documentation',
+            'api.md': 'API documentation',
+            'ARCHITECTURE.md': 'Architecture overview',
+            'architecture.md': 'Architecture overview',
+            'DEPLOYMENT.md': 'Deployment guide',
+            'deployment.md': 'Deployment guide',
+            'SETUP.md': 'Setup instructions',
+            'setup.md': 'Setup instructions',
+            'TROUBLESHOOTING.md': 'Troubleshooting guide',
+            'troubleshooting.md': 'Troubleshooting guide',
+        }
+
+        for filename, description in doc_files.items():
+            doc_file = docs_dir / filename
+            if doc_file.exists() and doc_file.is_file():
+                found_docs[f'docs/{filename}'] = description
+
+        # Check for subdirectories
+        try:
+            for item in docs_dir.iterdir():
+                if item.is_dir() and item.name not in EXCLUDE_DIRS:
+                    found_docs[f'docs/{item.name}/'] = f'{item.name.capitalize()} documentation'
+        except PermissionError:
+            pass
+
+    # Check .github for documentation
+    github_dir = root_path / '.github'
+    if github_dir.exists() and github_dir.is_dir():
+        contributing = github_dir / 'CONTRIBUTING.md'
+        if contributing.exists():
+            found_docs['.github/CONTRIBUTING.md'] = 'GitHub contribution guidelines'
+
+    return found_docs
+
+
+def discover_workflows(root_path: Path) -> Dict[str, List[str]]:
+    """Discover build workflows, scripts, and common commands.
+
+    Args:
+        root_path: Project root directory
+
+    Returns:
+        Dict mapping workflow type to list of commands/targets
+    """
+    workflows = {}
+
+    # Check Makefile for targets
+    makefile_targets = _extract_makefile_targets(root_path)
+    if makefile_targets:
+        workflows['make'] = makefile_targets
+
+    # Check package.json for npm/yarn scripts
+    npm_scripts = _extract_npm_scripts(root_path)
+    if npm_scripts:
+        workflows['npm'] = npm_scripts
+
+    # Check for GitHub Actions workflows
+    github_workflows = _find_github_workflows(root_path)
+    if github_workflows:
+        workflows['workflows'] = github_workflows
+
+    return workflows
+
+
+def _extract_makefile_targets(root_path: Path) -> List[str]:
+    """Extract targets from Makefile."""
+    makefile = root_path / 'Makefile'
+    if not makefile.exists():
+        return []
+
+    targets = []
+    try:
+        content = makefile.read_text()
+        for line in content.split('\n'):
+            if line.startswith('.PHONY'):
+                # Extract targets from .PHONY line
+                targets_str = line.split(':')[1].strip()
+                targets.extend(targets_str.split())
+            elif ':' in line and not line.startswith('\t') and not line.startswith(' '):
+                target = line.split(':')[0].strip()
+                if target and not target.startswith('.'):
+                    targets.append(target)
+    except Exception:
+        pass
+
+    return list(set(targets))[:10]  # Limit to 10 targets
+
+
+def _extract_npm_scripts(root_path: Path) -> List[str]:
+    """Extract scripts from package.json."""
+    import json
+
+    package_json = root_path / 'package.json'
+    if not package_json.exists():
+        return []
+
+    scripts = []
+    try:
+        content = json.loads(package_json.read_text())
+        if 'scripts' in content:
+            # Include common scripts, exclude default ones
+            exclude = {'test', 'start', 'dev', 'build'}
+            for script_name in content['scripts'].keys():
+                if script_name not in exclude:
+                    scripts.append(script_name)
+    except Exception:
+        pass
+
+    return scripts[:8]  # Limit to 8 scripts
+
+
+def _find_github_workflows(root_path: Path) -> List[str]:
+    """Find GitHub Actions workflows."""
+    workflows_dir = root_path / '.github' / 'workflows'
+    if not workflows_dir.exists():
+        return []
+
+    workflows = []
+    try:
+        for workflow_file in workflows_dir.glob('*.yml'):
+            workflows.append(workflow_file.stem)
+        for workflow_file in workflows_dir.glob('*.yaml'):
+            workflows.append(workflow_file.stem)
+    except Exception:
+        pass
+
+    return workflows[:5]  # Limit to 5 workflows

package/skills/sk:setup-optimizer/lib/enrich.py

@@ -0,0 +1,163 @@
+"""Enrich CLAUDE.md with comprehensive project context sections."""
+
+from typing import Dict, List
+
+
+def generate_directories_section(discovered: Dict[str, str]) -> str:
+    """Generate Key Directories section from discovered structure.
+
+    Args:
+        discovered: Dict of directory_name -> description
+
+    Returns:
+        Formatted section content
+    """
+    if not discovered:
+        return ''
+
+    lines = []
+    for dir_name in sorted(discovered.keys()):
+        description = discovered[dir_name]
+        lines.append(f'- **{dir_name}/** - {description}')
+
+    return '\n'.join(lines)
+
+
+def generate_documentation_section(docs: Dict[str, str]) -> str:
+    """Generate Documentation & Resources section from discovered files.
+
+    Args:
+        docs: Dict of file_path -> description
+
+    Returns:
+        Formatted section content
+    """
+    if not docs:
+        return ''
+
+    lines = []
+
+    # Prioritize certain docs
+    priority_order = [
+        'README.md', 'CONTRIBUTING.md', 'docs/API.md', 'docs/api.md',
+        'docs/ARCHITECTURE.md', 'docs/architecture.md',
+    ]
+
+    added = set()
+
+    # Add priority docs first
+    for pattern in priority_order:
+        if pattern in docs:
+            lines.append(f'- **{pattern}** - {docs[pattern]}')
+            added.add(pattern)
+
+    # Add remaining docs
+    for doc_path in sorted(docs.keys()):
+        if doc_path not in added:
+            description = docs[doc_path]
+            lines.append(f'- **{doc_path}** - {description}')
+
+    return '\n'.join(lines)
+
+
+def generate_workflows_section(workflows: Dict[str, List[str]]) -> str:
+    """Generate Common Workflows section from discovered commands.
+
+    Args:
+        workflows: Dict of workflow_type -> list of commands
+
+    Returns:
+        Formatted section content
+    """
+    if not workflows:
+        return ''
+
+    lines = []
+
+    # npm/yarn scripts
+    if 'npm' in workflows:
+        lines.append('**Common npm scripts:**')
+        for script in workflows['npm'][:5]:
+            lines.append(f'- `npm run {script}`')
+        lines.append('')
+
+    # Makefile targets
+    if 'make' in workflows:
+        lines.append('**Makefile targets:**')
+        for target in workflows['make'][:5]:
+            lines.append(f'- `make {target}`')
+        lines.append('')
+
+    # GitHub workflows
+    if 'workflows' in workflows:
+        lines.append('**GitHub Actions workflows:**')
+        for workflow in workflows['workflows'][:3]:
+            lines.append(f'- `.github/workflows/{workflow}.yml`')
+        lines.append('')
+
+    return '\n'.join(lines).strip()
+
+
+def generate_directories_section_compact(discovered: Dict[str, str]) -> str:
+    """Generate a compact version of Key Directories section.
+
+    Args:
+        discovered: Dict of directory_name -> description
+
+    Returns:
+        Compact formatted section
+    """
+    if not discovered:
+        return ''
+
+    # For compact mode, use inline format
+    lines = []
+    items = []
+
+    for dir_name in sorted(discovered.keys()):
+        items.append(f'`{dir_name}/`')
+
+    if items:
+        lines.append('Project structure:')
+        lines.append(', '.join(items))
+
+    return '\n'.join(lines)
+
+
+def merge_into_development_section(
+    base_content: str,
+    discovered_workflows: Dict[str, List[str]],
+) -> str:
+    """Merge discovered workflows into Development section.
+
+    Args:
+        base_content: Base development section content
+        discovered_workflows: Discovered workflows
+
+    Returns:
+        Enhanced development section
+    """
+    lines = [base_content.rstrip()]
+
+    # Add discovered workflows if any
+    if discovered_workflows:
+        lines.append('')
+        lines.append('### Discovered Workflows')
+        lines.append(generate_workflows_section(discovered_workflows))
+
+    return '\n'.join(lines)
+
+
+def estimate_content_lines(section_dict: Dict[str, str]) -> int:
+    """Estimate total lines for section content.
+
+    Args:
+        section_dict: Dict of sections
+
+    Returns:
+        Approximate total line count
+    """
+    total = 0
+    for content in section_dict.values():
+        total += len(content.split('\n'))
+    return total

package/skills/sk:setup-optimizer/lib/merge.py

@@ -0,0 +1,277 @@
+"""Smart merging of CLAUDE.md sections with user customization preservation."""
+
+import re
+from typing import Dict, Tuple
+
+
+def parse_claude_md(content: str) -> Dict[str, str]:
+    """Parse CLAUDE.md into sections.
+
+    Args:
+        content: CLAUDE.md content
+
+    Returns:
+        Dict mapping section names to their content
+    """
+    sections = {}
+    current_section = None
+    current_content = []
+
+    lines = content.split('\n')
+    in_code_block = False
+
+    for line in lines:
+        # Track code blocks to avoid treating ``` as section markers
+        if line.strip().startswith('```'):
+            in_code_block = not in_code_block
+
+        # Check for section headers (## level)
+        if line.startswith('## ') and not in_code_block:
+            # Save previous section
+            if current_section:
+                sections[current_section] = '\n'.join(current_content).strip()
+
+            # Start new section
+            current_section = line[3:].strip()
+            current_content = []
+        elif current_section:
+            current_content.append(line)
+
+    # Save last section
+    if current_section:
+        sections[current_section] = '\n'.join(current_content).strip()
+
+    return sections
+
+
+def detect_user_edits(current: str, generated: str) -> bool:
+    """Detect if a section has been user-customized.
+
+    Uses dual detection: content comparison + marker detection.
+
+    Args:
+        current: Current section content from file
+        generated: What we would generate from template
+
+    Returns:
+        True if section appears to be user-edited
+    """
+    current = current.strip()
+    generated = generated.strip()
+
+    # Check for user edit marker
+    if '<!-- EDITED -->' in current:
+        return True
+
+    # Check if content differs significantly from generated version
+    if current == generated:
+        return False
+
+    # If content is substantially different, mark as user-edited
+    current_len = len(current)
+    generated_len = len(generated)
+
+    # Allow small variations (formatting), but flag major differences
+    if current_len == 0 and generated_len == 0:
+        return False
+
+    if current_len == 0 or generated_len == 0:
+        return True
+
+    # Check if content matches at least 50% (allowing for additions)
+    matching_ratio = len(set(current) & set(generated)) / max(current_len, generated_len)
+    if matching_ratio < 0.5:
+        return True
+
+    return False
+
+
+def should_lock_section(section_name: str, current_content: str) -> bool:
+    """Determine if a section should be locked from regeneration.
+
+    Sections are locked if:
+    1. They have <!-- LOCK --> marker
+    2. They're in the smart default lock list AND have user content
+    3. They're marked as edited
+
+    Args:
+        section_name: Name of the section
+        current_content: Current content of the section
+
+    Returns:
+        True if section should be locked
+    """
+    # Explicit lock marker
+    if '<!-- LOCK -->' in current_content:
+        return True
+
+    # Smart defaults - auto-lock these if they have user content
+    auto_lock_sections = {
+        'Important Context': True,
+        'Known Issues': True,
+        'Notes': True,
+        'Custom Configuration': True,
+        'Recommended Workflow': True,
+    }
+
+    if section_name in auto_lock_sections and current_content.strip():
+        # Check if it looks like user content (not template boilerplate)
+        if not current_content.startswith('[') and len(current_content) > 20:
+            return True
+
+    return False
+
+
+def merge_sections(
+    existing: Dict[str, str],
+    generated: Dict[str, str],
+) -> Tuple[Dict[str, str], Dict[str, str]]:
+    """Merge existing and generated sections smartly.
+
+    Strategy:
+    - Keep generated sections as base
+    - Override with existing sections if user-edited
+    - Lock sections if needed
+    - Return (merged_sections, preservation_report)
+
+    Args:
+        existing: Current sections from file
+        generated: Newly generated sections from template
+
+    Returns:
+        Tuple of (merged sections dict, report dict of what was preserved)
+    """
+    merged = {}
+    preserved = {}
+
+    # Process all sections (both existing and generated)
+    all_sections = set(list(existing.keys()) + list(generated.keys()))
+
+    for section_name in all_sections:
+        existing_content = existing.get(section_name, '').strip()
+        generated_content = generated.get(section_name, '').strip()
+
+        # Determine if user customized this section
+        is_user_edited = (
+            existing_content and
+            detect_user_edits(existing_content, generated_content)
+        )
+
+        # Determine if section should be locked
+        is_locked = should_lock_section(section_name, existing_content)
+
+        if is_locked or is_user_edited:
+            # Preserve user content
+            merged[section_name] = existing_content
+            preserved[section_name] = 'user-edited' if is_user_edited else 'locked'
+        elif existing_content and generated_content:
+            # Both exist - prefer generated but keep structure
+            merged[section_name] = generated_content
+        elif existing_content:
+            # Only exists in current
+            merged[section_name] = existing_content
+            preserved[section_name] = 'preserved'
+        else:
+            # Only in generated or both same
+            merged[section_name] = generated_content
+
+    return merged, preserved
+
+
+def reconstruct_claude_md(
+    sections: Dict[str, str],
+    include_marker: bool = True,
+) -> str:
+    """Reconstruct CLAUDE.md from sections.
+
+    Args:
+        sections: Dict of section_name -> content
+        include_marker: Whether to add generation marker
+
+    Returns:
+        Reconstructed CLAUDE.md content
+    """
+    # Define standard section order
+    section_order = [
+        'Project Header',  # Placeholder for title/description
+        'Stack',
+        'Quick Start',
+        'Key Directories',
+        'Documentation & Resources',
+        'Development',
+        'Common Workflows',
+        'Build & Deploy',
+        'Recommended Workflow',
+        'Important Context',
+        'Environment Variables',
+        'Common Tasks',
+    ]
+
+    lines = []
+
+    # Add sections in order (putting unordered sections at end)
+    added_sections = set()
+    for section_name in section_order:
+        if section_name in sections and section_name not in added_sections:
+            content = sections[section_name].strip()
+            if content:
+                lines.append(f'## {section_name}')
+                lines.append('')
+                lines.append(content)
+                lines.append('')
+                added_sections.add(section_name)
+
+    # Add any remaining sections
+    for section_name in sorted(sections.keys()):
+        if section_name not in added_sections:
+            content = sections[section_name].strip()
+            if content:
+                lines.append(f'## {section_name}')
+                lines.append('')
+                lines.append(content)
+                lines.append('')
+
+    # Add marker
+    if include_marker:
+        lines.append('<!-- Generated by /setup-claude-tools -->')
+
+    result = '\n'.join(lines).strip()
+    return result + '\n'
+
+
+def extract_preservation_report(preserved: Dict[str, str]) -> str:
+    """Format a human-readable report of preserved content.
+
+    Args:
+        preserved: Dict of section_name -> preservation_reason
+
+    Returns:
+        Formatted report string
+    """
+    if not preserved:
+        return ''
+
+    report_lines = ['📝 Preservation Report:', '']
+
+    user_edited = [s for s, r in preserved.items() if r == 'user-edited']
+    locked = [s for s, r in preserved.items() if r == 'locked']
+    kept = [s for s, r in preserved.items() if r == 'preserved']
+
+    if user_edited:
+        report_lines.append('✅ Preserved (user-edited):')
+        for section in user_edited:
+            report_lines.append(f'   - {section}')
+        report_lines.append('')
+
+    if locked:
+        report_lines.append('🔒 Preserved (locked):')
+        for section in locked:
+            report_lines.append(f'   - {section}')
+        report_lines.append('')
+
+    if kept:
+        report_lines.append('📌 Preserved (as-is):')
+        for section in kept:
+            report_lines.append(f'   - {section}')
+
+    return '\n'.join(report_lines)