cokit-cli 1.0.8 → 1.2.0

package/templates/repo/.github/skills/devops/scripts/docker_optimize.py

@@ -0,0 +1,332 @@
+#!/usr/bin/env python3
+"""
+Dockerfile Optimization Analyzer
+
+Analyzes Dockerfiles for optimization opportunities including multi-stage builds,
+security issues, size reduction, and best practices.
+
+Usage:
+    python docker-optimize.py Dockerfile
+    python docker-optimize.py --json Dockerfile
+    python docker-optimize.py --verbose Dockerfile
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+# Windows UTF-8 compatibility (works for both local and global installs)
+CLAUDE_ROOT = Path(__file__).parent.parent.parent.parent
+sys.path.insert(0, str(CLAUDE_ROOT / 'scripts'))
+try:
+    from win_compat import ensure_utf8_stdout
+    ensure_utf8_stdout()
+except ImportError:
+    if sys.platform == 'win32':
+        import io
+        if hasattr(sys.stdout, 'buffer'):
+            sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+
+
+class DockerfileAnalyzer:
+    """Analyze Dockerfile for optimization opportunities."""
+
+    def __init__(self, dockerfile_path: Path, verbose: bool = False):
+        """
+        Initialize analyzer.
+
+        Args:
+            dockerfile_path: Path to Dockerfile
+            verbose: Enable verbose output
+        """
+        self.dockerfile_path = Path(dockerfile_path)
+        self.verbose = verbose
+        self.lines = []
+        self.issues = []
+        self.suggestions = []
+
+    def load_dockerfile(self) -> bool:
+        """
+        Load and parse Dockerfile.
+
+        Returns:
+            True if loaded successfully
+
+        Raises:
+            FileNotFoundError: If Dockerfile doesn't exist
+        """
+        if not self.dockerfile_path.exists():
+            raise FileNotFoundError(f"Dockerfile not found: {self.dockerfile_path}")
+
+        with open(self.dockerfile_path, 'r') as f:
+            self.lines = f.readlines()
+
+        return True
+
+    def analyze_base_image(self) -> None:
+        """Check base image for optimization opportunities."""
+        for i, line in enumerate(self.lines, 1):
+            line = line.strip()
+            if line.startswith('FROM'):
+                # Check for 'latest' tag
+                if ':latest' in line or (': ' not in line and 'AS' not in line and '@' not in line):
+                    self.issues.append({
+                        'line': i,
+                        'severity': 'warning',
+                        'category': 'base_image',
+                        'message': 'Base image uses :latest or no tag',
+                        'suggestion': 'Use specific version tags for reproducibility'
+                    })
+
+                # Check for non-alpine/slim variants
+                if 'node' in line.lower() and 'alpine' not in line.lower():
+                    self.suggestions.append({
+                        'line': i,
+                        'category': 'size',
+                        'message': 'Consider using Alpine variant',
+                        'suggestion': 'node:20-alpine is ~10x smaller than node:20'
+                    })
+
+    def analyze_multi_stage(self) -> None:
+        """Check if multi-stage build is used."""
+        from_count = sum(1 for line in self.lines if line.strip().startswith('FROM'))
+
+        if from_count == 1:
+            # Check if build tools are installed
+            has_build_tools = any(
+                any(tool in line.lower() for tool in ['gcc', 'make', 'build-essential', 'npm install', 'pip install'])
+                for line in self.lines
+            )
+
+            if has_build_tools:
+                self.issues.append({
+                    'line': 0,
+                    'severity': 'warning',
+                    'category': 'optimization',
+                    'message': 'Single-stage build with build tools',
+                    'suggestion': 'Use multi-stage build to exclude build dependencies from final image'
+                })
+
+    def analyze_layer_caching(self) -> None:
+        """Check for optimal layer caching order."""
+        copy_lines = []
+        run_lines = []
+
+        for i, line in enumerate(self.lines, 1):
+            stripped = line.strip()
+            if stripped.startswith('COPY'):
+                copy_lines.append((i, stripped))
+            elif stripped.startswith('RUN'):
+                run_lines.append((i, stripped))
+
+        # Check if dependency files copied before source
+        has_package_copy = any('package.json' in line or 'requirements.txt' in line or 'go.mod' in line
+                               for _, line in copy_lines)
+        has_source_copy = any('COPY . .' in line or 'COPY ./' in line
+                              for _, line in copy_lines)
+
+        if has_source_copy and not has_package_copy:
+            self.issues.append({
+                'line': 0,
+                'severity': 'warning',
+                'category': 'caching',
+                'message': 'Source copied before dependencies',
+                'suggestion': 'Copy dependency files first (package.json, requirements.txt) then run install, then copy source'
+            })
+
+    def analyze_security(self) -> None:
+        """Check for security issues."""
+        has_user = any(line.strip().startswith('USER') and 'root' not in line.lower()
+                      for line in self.lines)
+
+        if not has_user:
+            self.issues.append({
+                'line': 0,
+                'severity': 'error',
+                'category': 'security',
+                'message': 'Container runs as root',
+                'suggestion': 'Create and use non-root user with USER instruction'
+            })
+
+        # Check for secrets in build
+        for i, line in enumerate(self.lines, 1):
+            if any(secret in line.upper() for secret in ['PASSWORD', 'SECRET', 'TOKEN', 'API_KEY']):
+                if 'ENV' in line or 'ARG' in line:
+                    self.issues.append({
+                        'line': i,
+                        'severity': 'error',
+                        'category': 'security',
+                        'message': 'Potential secret in Dockerfile',
+                        'suggestion': 'Use build-time arguments or runtime environment variables'
+                    })
+
+    def analyze_apt_cache(self) -> None:
+        """Check for apt cache cleanup."""
+        for i, line in enumerate(self.lines, 1):
+            if 'apt-get install' in line.lower() or 'apt install' in line.lower():
+                # Check if same RUN command cleans cache
+                if 'rm -rf /var/lib/apt/lists/*' not in line:
+                    self.suggestions.append({
+                        'line': i,
+                        'category': 'size',
+                        'message': 'apt cache not cleaned in same layer',
+                        'suggestion': 'Add && rm -rf /var/lib/apt/lists/* to reduce image size'
+                    })
+
+    def analyze_combine_run(self) -> None:
+        """Check for multiple consecutive RUN commands."""
+        consecutive_runs = 0
+        first_run_line = 0
+
+        for i, line in enumerate(self.lines, 1):
+            if line.strip().startswith('RUN'):
+                if consecutive_runs == 0:
+                    first_run_line = i
+                consecutive_runs += 1
+            else:
+                if consecutive_runs > 1:
+                    self.suggestions.append({
+                        'line': first_run_line,
+                        'category': 'layers',
+                        'message': f'{consecutive_runs} consecutive RUN commands',
+                        'suggestion': 'Combine related RUN commands with && to reduce layers'
+                    })
+                consecutive_runs = 0
+
+    def analyze_workdir(self) -> None:
+        """Check for WORKDIR usage."""
+        has_workdir = any(line.strip().startswith('WORKDIR') for line in self.lines)
+
+        if not has_workdir:
+            self.suggestions.append({
+                'line': 0,
+                'category': 'best_practice',
+                'message': 'No WORKDIR specified',
+                'suggestion': 'Use WORKDIR to set working directory instead of cd commands'
+            })
+
+    def analyze(self) -> Dict:
+        """
+        Run all analyses.
+
+        Returns:
+            Analysis results dictionary
+        """
+        self.load_dockerfile()
+
+        self.analyze_base_image()
+        self.analyze_multi_stage()
+        self.analyze_layer_caching()
+        self.analyze_security()
+        self.analyze_apt_cache()
+        self.analyze_combine_run()
+        self.analyze_workdir()
+
+        return {
+            'dockerfile': str(self.dockerfile_path),
+            'total_lines': len(self.lines),
+            'issues': self.issues,
+            'suggestions': self.suggestions,
+            'summary': {
+                'errors': len([i for i in self.issues if i.get('severity') == 'error']),
+                'warnings': len([i for i in self.issues if i.get('severity') == 'warning']),
+                'suggestions': len(self.suggestions)
+            }
+        }
+
+    def print_results(self, results: Dict) -> None:
+        """
+        Print analysis results in human-readable format.
+
+        Args:
+            results: Analysis results from analyze()
+        """
+        print(f"\nDockerfile Analysis: {results['dockerfile']}")
+        print(f"Total lines: {results['total_lines']}")
+        print(f"\nSummary:")
+        print(f"  Errors: {results['summary']['errors']}")
+        print(f"  Warnings: {results['summary']['warnings']}")
+        print(f"  Suggestions: {results['summary']['suggestions']}")
+
+        if results['issues']:
+            print(f"\n{'='*60}")
+            print("ISSUES:")
+            print('='*60)
+            for issue in results['issues']:
+                severity = issue.get('severity', 'info').upper()
+                line_info = f"Line {issue['line']}" if issue['line'] > 0 else "General"
+                print(f"\n[{severity}] {line_info} - {issue['category']}")
+                print(f"  {issue['message']}")
+                print(f"  → {issue['suggestion']}")
+
+        if results['suggestions']:
+            print(f"\n{'='*60}")
+            print("SUGGESTIONS:")
+            print('='*60)
+            for sugg in results['suggestions']:
+                line_info = f"Line {sugg['line']}" if sugg['line'] > 0 else "General"
+                print(f"\n{line_info} - {sugg['category']}")
+                print(f"  {sugg['message']}")
+                print(f"  → {sugg['suggestion']}")
+
+        print()
+
+
+def main():
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Analyze Dockerfile for optimization opportunities",
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+
+    parser.add_argument(
+        "dockerfile",
+        type=str,
+        help="Path to Dockerfile"
+    )
+
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output results as JSON"
+    )
+
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Enable verbose output"
+    )
+
+    args = parser.parse_args()
+
+    try:
+        analyzer = DockerfileAnalyzer(
+            dockerfile_path=args.dockerfile,
+            verbose=args.verbose
+        )
+
+        results = analyzer.analyze()
+
+        if args.json:
+            print(json.dumps(results, indent=2))
+        else:
+            analyzer.print_results(results)
+
+        # Exit with error code if issues found
+        if results['summary']['errors'] > 0:
+            sys.exit(1)
+
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/templates/repo/.github/skills/docs-seeker/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: docs-seeker
+description: Search library/framework documentation via llms.txt (context7.com). Use for API docs, GitHub repository analysis, technical documentation lookup, latest library features.
+version: 3.1.0
+---
+
+# Documentation Discovery via Scripts
+
+## Overview
+
+**Script-first** documentation discovery using llms.txt standard.
+
+Execute scripts to handle entire workflow - no manual URL construction needed.
+
+## Primary Workflow
+
+**ALWAYS execute scripts in this order:**
+
+```bash
+# 1. DETECT query type (topic-specific vs general)
+node scripts/detect-topic.js "<user query>"
+
+# 2. FETCH documentation using script output
+node scripts/fetch-docs.js "<user query>"
+
+# 3. ANALYZE results (if multiple URLs returned)
+cat llms.txt | node scripts/analyze-llms-txt.js -
+```
+
+Scripts handle URL construction, fallback chains, and error handling automatically.
+
+## Scripts
+
+**`detect-topic.js`** - Classify query type
+- Identifies topic-specific vs general queries
+- Extracts library name + topic keyword
+- Returns JSON: `{topic, library, isTopicSpecific}`
+- Zero-token execution
+
+**`fetch-docs.js`** - Retrieve documentation
+- Constructs context7.com URLs automatically
+- Handles fallback: topic → general → error
+- Outputs llms.txt content or error message
+- Zero-token execution
+
+**`analyze-llms-txt.js`** - Process llms.txt
+- Categorizes URLs (critical/important/supplementary)
+- Recommends agent distribution (1 agent, 3 agents, 7 agents, phased)
+- Returns JSON with strategy
+- Zero-token execution
+
+## Workflow References
+
+**[Topic-Specific Search](./workflows/topic-search.md)** - Fastest path (10-15s)
+
+**[General Library Search](./workflows/library-search.md)** - Comprehensive coverage (30-60s)
+
+**[Repository Analysis](./workflows/repo-analysis.md)** - Fallback strategy
+
+## References
+
+**[context7-patterns.md](./references/context7-patterns.md)** - URL patterns, known repositories
+
+**[errors.md](./references/errors.md)** - Error handling, fallback strategies
+
+**[advanced.md](./references/advanced.md)** - Edge cases, versioning, multi-language
+
+## Execution Principles
+
+1. **Scripts first** - Execute scripts instead of manual URL construction
+2. **Zero-token overhead** - Scripts run without context loading
+3. **Automatic fallback** - Scripts handle topic → general → error chains
+4. **Progressive disclosure** - Load workflows/references only when needed
+5. **Agent distribution** - Scripts recommend parallel agent strategy
+
+## Quick Start
+
+**Topic query:** "How do I use date picker in shadcn?"
+```bash
+node scripts/detect-topic.js "<query>"  # → {topic, library, isTopicSpecific}
+node scripts/fetch-docs.js "<query>"    # → 2-3 URLs
+# Read URLs with WebFetch
+```
+
+**General query:** "Documentation for Next.js"
+```bash
+node scripts/detect-topic.js "<query>"         # → {isTopicSpecific: false}
+node scripts/fetch-docs.js "<query>"           # → 8+ URLs
+cat llms.txt | node scripts/analyze-llms-txt.js -  # → {totalUrls, distribution}
+# Deploy agents per recommendation
+```
+
+## Environment
+
+Scripts load `.env`: `process.env` > `$HOME/.copilot/skills/docs-seeker/.env` > `$HOME/.copilot/skills/.env` > `$HOME/.copilot/.env`
+
+See `.env.example` for configuration options.

package/templates/repo/.github/skills/docs-seeker/references/context7-patterns.md

@@ -0,0 +1,64 @@
+# context7.com URL Patterns
+
+## Topic-Specific URLs (Priority #1)
+
+**Pattern:** `https://context7.com/{path}/llms.txt?topic={keyword}`
+
+**When to use:** User asks about specific feature/component
+
+**Examples:**
+```
+shadcn/ui date picker
+→ https://context7.com/shadcn-ui/ui/llms.txt?topic=date
+
+Next.js caching
+→ https://context7.com/vercel/next.js/llms.txt?topic=cache
+
+FFmpeg compression
+→ https://context7.com/websites/ffmpeg_doxygen_8_0/llms.txt?topic=compress
+```
+
+**Benefits:** Returns ONLY relevant docs, 10x faster, minimal tokens
+
+## General Library URLs (Priority #2)
+
+**GitHub repos:** `https://context7.com/{org}/{repo}/llms.txt`
+
+**Websites:** `https://context7.com/websites/{normalized-path}/llms.txt`
+
+## Known Repository Mappings
+
+```
+next.js → vercel/next.js
+nextjs → vercel/next.js
+astro → withastro/astro
+remix → remix-run/remix
+shadcn → shadcn-ui/ui
+shadcn/ui → shadcn-ui/ui
+```
+
+## Official Site Fallbacks
+
+Use ONLY if context7.com unavailable:
+```
+Astro: https://docs.astro.build/llms.txt
+Next.js: https://nextjs.org/llms.txt
+Remix: https://remix.run/llms.txt
+SvelteKit: https://kit.svelte.dev/llms.txt
+```
+
+## Topic Keyword Normalization
+
+**Rules:**
+- Lowercase
+- Remove special chars
+- Use first word for multi-word topics
+- Max 20 chars
+
+**Examples:**
+```
+"date picker" → "date"
+"OAuth" → "oauth"
+"Server-Side" → "server"
+"caching strategies" → "caching"
+```

package/templates/repo/.github/skills/docs-seeker/scripts/fetch-docs.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+
+/**
+ * Documentation Fetcher Script
+ * Fetches documentation from context7.com with topic support and fallback chain
+ */
+
+const https = require('https');
+const { loadEnv } = require('./utils/env-loader');
+const { detectTopic } = require('./detect-topic');
+
+// Load environment
+const env = loadEnv();
+const DEBUG = env.DEBUG === 'true';
+const API_KEY = env.CONTEXT7_API_KEY;
+
+/**
+ * Make HTTPS GET request
+ * @param {string} url - URL to fetch
+ * @returns {Promise<string>} Response body
+ */
+function httpsGet(url) {
+  return new Promise((resolve, reject) => {
+    const options = {
+      headers: API_KEY ? { 'Authorization': `Bearer ${API_KEY}` } : {},
+    };
+
+    https.get(url, options, (res) => {
+      let data = '';
+
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+
+      res.on('end', () => {
+        if (res.statusCode === 200) {
+          resolve(data);
+        } else if (res.statusCode === 404) {
+          resolve(null);
+        } else {
+          reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+        }
+      });
+    }).on('error', reject);
+  });
+}
+
+/**
+ * Construct context7.com URL
+ * @param {string} library - Library name (e.g., "next.js", "shadcn/ui")
+ * @param {string} topic - Optional topic keyword
+ * @returns {string} context7.com URL
+ */
+function buildContext7Url(library, topic = null) {
+  // Determine if GitHub repo or website
+  let basePath;
+
+  if (library.includes('/')) {
+    // GitHub repo format: org/repo
+    const [org, repo] = library.split('/');
+    basePath = `${org}/${repo}`;
+  } else {
+    // Try common patterns
+    const normalized = library.toLowerCase().replace(/[^a-z0-9-]/g, '');
+    basePath = `websites/${normalized}`;
+  }
+
+  const baseUrl = `https://context7.com/${basePath}/llms.txt`;
+
+  if (topic) {
+    return `${baseUrl}?topic=${encodeURIComponent(topic)}`;
+  }
+
+  return baseUrl;
+}
+
+/**
+ * Try multiple URL variations for a library
+ * @param {string} library - Library name
+ * @param {string} topic - Optional topic
+ * @returns {Promise<Array>} Array of URLs to try
+ */
+async function getUrlVariations(library, topic = null) {
+  const urls = [];
+
+  // Known repo mappings
+  const knownRepos = {
+    'next.js': 'vercel/next.js',
+    'nextjs': 'vercel/next.js',
+    'remix': 'remix-run/remix',
+    'astro': 'withastro/astro',
+    'shadcn': 'shadcn-ui/ui',
+    'shadcn/ui': 'shadcn-ui/ui',
+    'tailwind': 'tailwindlabs/tailwindcss',
+    'tailwindcss': 'tailwindlabs/tailwindcss',
+  };
+
+  const normalized = library.toLowerCase();
+  const repo = knownRepos[normalized] || library;
+
+  // Primary: Try with topic if available
+  if (topic) {
+    urls.push(buildContext7Url(repo, topic));
+  }
+
+  // Fallback: Try without topic
+  urls.push(buildContext7Url(repo));
+
+  return urls;
+}
+
+/**
+ * Fetch documentation from context7.com
+ * @param {string} query - User query
+ * @returns {Promise<Object>} Documentation result
+ */
+async function fetchDocs(query) {
+  const topicInfo = detectTopic(query);
+
+  if (DEBUG) {
+    console.error('[DEBUG] Topic detection result:', topicInfo);
+  }
+
+  let urls = [];
+
+  if (topicInfo && topicInfo.isTopicSpecific) {
+    // Topic-specific search
+    urls = await getUrlVariations(topicInfo.library, topicInfo.topic);
+
+    if (DEBUG) {
+      console.error('[DEBUG] Topic-specific URLs:', urls);
+    }
+  } else {
+    // Extract library from general query
+    const libraryMatch = query.match(/(?:documentation|docs|guide) (?:for )?(.+)/i);
+    if (libraryMatch) {
+      const library = libraryMatch[1].trim();
+      urls = await getUrlVariations(library);
+
+      if (DEBUG) {
+        console.error('[DEBUG] General library URLs:', urls);
+      }
+    }
+  }
+
+  // Try each URL
+  for (const url of urls) {
+    if (DEBUG) {
+      console.error(`[DEBUG] Trying URL: ${url}`);
+    }
+
+    try {
+      const content = await httpsGet(url);
+
+      if (content) {
+        return {
+          success: true,
+          source: 'context7.com',
+          url,
+          content,
+          topicSpecific: url.includes('?topic='),
+        };
+      }
+    } catch (error) {
+      if (DEBUG) {
+        console.error(`[DEBUG] Failed to fetch ${url}:`, error.message);
+      }
+    }
+  }
+
+  // No URL worked
+  return {
+    success: false,
+    source: 'context7.com',
+    error: 'Documentation not found on context7.com',
+    urls,
+    suggestion: 'Try repository analysis or web search',
+  };
+}
+
+/**
+ * CLI entry point
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error('Usage: node fetch-docs.js "<user query>"');
+    process.exit(1);
+  }
+
+  const query = args.join(' ');
+
+  try {
+    const result = await fetchDocs(query);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.success ? 0 : 1);
+  } catch (error) {
+    console.error('Error:', error.message);
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  fetchDocs,
+  buildContext7Url,
+  getUrlVariations,
+  httpsGet,
+};