codehava-agent-kit 1.0.0 → 2.0.0

package/templates/.agent/skills/apify-ultimate-scraper/reference/scripts/run_actor.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+/**
+ * Apify Actor Runner - Runs Apify actors and exports results.
+ *
+ * Usage:
+ *   # Quick answer (display in chat, no file saved)
+ *   node --env-file=.env scripts/run_actor.js --actor ACTOR_ID --input '{}'
+ *
+ *   # Export to file
+ *   node --env-file=.env scripts/run_actor.js --actor ACTOR_ID --input '{}' --output leads.csv --format csv
+ */
+
+import { parseArgs } from 'node:util';
+import { writeFileSync, statSync } from 'node:fs';
+
+// User-Agent for tracking skill usage in Apify analytics
+const USER_AGENT = 'apify-agent-skills/apify-ultimate-scraper-1.3.0';
+
+// Parse command-line arguments
+function parseCliArgs() {
+    const options = {
+        actor: { type: 'string', short: 'a' },
+        input: { type: 'string', short: 'i' },
+        output: { type: 'string', short: 'o' },
+        format: { type: 'string', short: 'f', default: 'csv' },
+        timeout: { type: 'string', short: 't', default: '600' },
+        'poll-interval': { type: 'string', default: '5' },
+        help: { type: 'boolean', short: 'h' },
+    };
+
+    const { values } = parseArgs({ options, allowPositionals: false });
+
+    if (values.help) {
+        printHelp();
+        process.exit(0);
+    }
+
+    if (!values.actor) {
+        console.error('Error: --actor is required');
+        printHelp();
+        process.exit(1);
+    }
+
+    if (!values.input) {
+        console.error('Error: --input is required');
+        printHelp();
+        process.exit(1);
+    }
+
+    return {
+        actor: values.actor,
+        input: values.input,
+        output: values.output,
+        format: values.format || 'csv',
+        timeout: parseInt(values.timeout, 10),
+        pollInterval: parseInt(values['poll-interval'], 10),
+    };
+}
+
+function printHelp() {
+    console.log(`
+Apify Actor Runner - Run Apify actors and export results
+
+Usage:
+  node --env-file=.env scripts/run_actor.js --actor ACTOR_ID --input '{}'
+
+Options:
+  --actor, -a       Actor ID (e.g., compass/crawler-google-places) [required]
+  --input, -i       Actor input as JSON string [required]
+  --output, -o      Output file path (optional - if not provided, displays quick answer)
+  --format, -f      Output format: csv, json (default: csv)
+  --timeout, -t     Max wait time in seconds (default: 600)
+  --poll-interval   Seconds between status checks (default: 5)
+  --help, -h        Show this help message
+
+Output Formats:
+  JSON (all data)     --output file.json --format json
+  CSV (all data)      --output file.csv --format csv
+  Quick answer        (no --output) - displays top 5 in chat
+
+Examples:
+  # Quick answer - display top 5 in chat
+  node --env-file=.env scripts/run_actor.js \\
+    --actor "compass/crawler-google-places" \\
+    --input '{"searchStringsArray": ["coffee shops"], "locationQuery": "Seattle, USA"}'
+
+  # Export all data to CSV
+  node --env-file=.env scripts/run_actor.js \\
+    --actor "compass/crawler-google-places" \\
+    --input '{"searchStringsArray": ["coffee shops"], "locationQuery": "Seattle, USA"}' \\
+    --output leads.csv --format csv
+`);
+}
+
+// Start an actor run and return { runId, datasetId }
+async function startActor(token, actorId, inputJson) {
+    // Convert "author/actor" format to "author~actor" for API compatibility
+    const apiActorId = actorId.replace('/', '~');
+    const url = `https://api.apify.com/v2/acts/${apiActorId}/runs?token=${encodeURIComponent(token)}`;
+
+    let data;
+    try {
+        data = JSON.parse(inputJson);
+    } catch (e) {
+        console.error(`Error: Invalid JSON input: ${e.message}`);
+        process.exit(1);
+    }
+
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'User-Agent': `${USER_AGENT}/start_actor`,
+        },
+        body: JSON.stringify(data),
+    });
+
+    if (response.status === 404) {
+        console.error(`Error: Actor '${actorId}' not found`);
+        process.exit(1);
+    }
+
+    if (!response.ok) {
+        const text = await response.text();
+        console.error(`Error: API request failed (${response.status}): ${text}`);
+        process.exit(1);
+    }
+
+    const result = await response.json();
+    return {
+        runId: result.data.id,
+        datasetId: result.data.defaultDatasetId,
+    };
+}
+
+// Poll run status until complete or timeout
+async function pollUntilComplete(token, runId, timeout, interval) {
+    const url = `https://api.apify.com/v2/actor-runs/${runId}?token=${encodeURIComponent(token)}`;
+    const startTime = Date.now();
+    let lastStatus = null;
+
+    while (true) {
+        const response = await fetch(url);
+        if (!response.ok) {
+            const text = await response.text();
+            console.error(`Error: Failed to get run status: ${text}`);
+            process.exit(1);
+        }
+
+        const result = await response.json();
+        const status = result.data.status;
+
+        // Only print when status changes
+        if (status !== lastStatus) {
+            console.log(`Status: ${status}`);
+            lastStatus = status;
+        }
+
+        if (['SUCCEEDED', 'FAILED', 'ABORTED', 'TIMED-OUT'].includes(status)) {
+            return status;
+        }
+
+        const elapsed = (Date.now() - startTime) / 1000;
+        if (elapsed > timeout) {
+            console.error(`Warning: Timeout after ${timeout}s, actor still running`);
+            return 'TIMED-OUT';
+        }
+
+        await sleep(interval * 1000);
+    }
+}
+
+// Download dataset items
+async function downloadResults(token, datasetId, outputPath, format) {
+    const url = `https://api.apify.com/v2/datasets/${datasetId}/items?token=${encodeURIComponent(token)}&format=json`;
+
+    const response = await fetch(url, {
+        headers: {
+            'User-Agent': `${USER_AGENT}/download_${format}`,
+        },
+    });
+
+    if (!response.ok) {
+        const text = await response.text();
+        console.error(`Error: Failed to download results: ${text}`);
+        process.exit(1);
+    }
+
+    const data = await response.json();
+
+    if (format === 'json') {
+        writeFileSync(outputPath, JSON.stringify(data, null, 2));
+    } else {
+        // CSV output
+        if (data.length > 0) {
+            const fieldnames = Object.keys(data[0]);
+            const csvLines = [fieldnames.join(',')];
+
+            for (const row of data) {
+                const values = fieldnames.map((key) => {
+                    let value = row[key];
+
+                    // Truncate long text fields
+                    if (typeof value === 'string' && value.length > 200) {
+                        value = value.slice(0, 200) + '...';
+                    } else if (Array.isArray(value) || (typeof value === 'object' && value !== null)) {
+                        value = JSON.stringify(value) || '';
+                    }
+
+                    // CSV escape: wrap in quotes if contains comma, quote, or newline
+                    if (value === null || value === undefined) {
+                        return '';
+                    }
+                    const strValue = String(value);
+                    if (strValue.includes(',') || strValue.includes('"') || strValue.includes('\n')) {
+                        return `"${strValue.replace(/"/g, '""')}"`;
+                    }
+                    return strValue;
+                });
+                csvLines.push(values.join(','));
+            }
+
+            writeFileSync(outputPath, csvLines.join('\n'));
+        } else {
+            writeFileSync(outputPath, '');
+        }
+    }
+
+    console.log(`Saved to: ${outputPath}`);
+}
+
+// Display top 5 results in chat format
+async function displayQuickAnswer(token, datasetId) {
+    const url = `https://api.apify.com/v2/datasets/${datasetId}/items?token=${encodeURIComponent(token)}&format=json`;
+
+    const response = await fetch(url, {
+        headers: {
+            'User-Agent': `${USER_AGENT}/quick_answer`,
+        },
+    });
+
+    if (!response.ok) {
+        const text = await response.text();
+        console.error(`Error: Failed to download results: ${text}`);
+        process.exit(1);
+    }
+
+    const data = await response.json();
+    const total = data.length;
+
+    if (total === 0) {
+        console.log('\nNo results found.');
+        return;
+    }
+
+    // Display top 5
+    console.log(`\n${'='.repeat(60)}`);
+    console.log(`TOP 5 RESULTS (of ${total} total)`);
+    console.log('='.repeat(60));
+
+    for (let i = 0; i < Math.min(5, data.length); i++) {
+        const item = data[i];
+        console.log(`\n--- Result ${i + 1} ---`);
+
+        for (const [key, value] of Object.entries(item)) {
+            let displayValue = value;
+
+            // Truncate long values
+            if (typeof value === 'string' && value.length > 100) {
+                displayValue = value.slice(0, 100) + '...';
+            } else if (Array.isArray(value) || (typeof value === 'object' && value !== null)) {
+                const jsonStr = JSON.stringify(value);
+                displayValue = jsonStr.length > 100 ? jsonStr.slice(0, 100) + '...' : jsonStr;
+            }
+
+            console.log(`  ${key}: ${displayValue}`);
+        }
+    }
+
+    console.log(`\n${'='.repeat(60)}`);
+    if (total > 5) {
+        console.log(`Showing 5 of ${total} results.`);
+    }
+    console.log(`Full data available at: https://console.apify.com/storage/datasets/${datasetId}`);
+    console.log('='.repeat(60));
+}
+
+// Report summary of downloaded data
+function reportSummary(outputPath, format) {
+    const stats = statSync(outputPath);
+    const size = stats.size;
+
+    let count;
+    try {
+        const content = require('fs').readFileSync(outputPath, 'utf-8');
+        if (format === 'json') {
+            const data = JSON.parse(content);
+            count = Array.isArray(data) ? data.length : 1;
+        } else {
+            // CSV - count lines minus header
+            const lines = content.split('\n').filter((line) => line.trim());
+            count = Math.max(0, lines.length - 1);
+        }
+    } catch {
+        count = 'unknown';
+    }
+
+    console.log(`Records: ${count}`);
+    console.log(`Size: ${size.toLocaleString()} bytes`);
+}
+
+// Helper: sleep for ms
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Main function
+async function main() {
+    // Parse args first so --help works without token
+    const args = parseCliArgs();
+
+    // Check for APIFY_TOKEN
+    const token = process.env.APIFY_TOKEN;
+    if (!token) {
+        console.error('Error: APIFY_TOKEN not found in .env file');
+        console.error('');
+        console.error('Add your token to .env file:');
+        console.error('  APIFY_TOKEN=your_token_here');
+        console.error('');
+        console.error('Get your token: https://console.apify.com/account/integrations');
+        process.exit(1);
+    }
+
+    // Start the actor run
+    console.log(`Starting actor: ${args.actor}`);
+    const { runId, datasetId } = await startActor(token, args.actor, args.input);
+    console.log(`Run ID: ${runId}`);
+    console.log(`Dataset ID: ${datasetId}`);
+
+    // Poll for completion
+    const status = await pollUntilComplete(token, runId, args.timeout, args.pollInterval);
+
+    if (status !== 'SUCCEEDED') {
+        console.error(`Error: Actor run ${status}`);
+        console.error(`Details: https://console.apify.com/actors/runs/${runId}`);
+        process.exit(1);
+    }
+
+    // Determine output mode
+    if (args.output) {
+        // File output mode
+        await downloadResults(token, datasetId, args.output, args.format);
+        reportSummary(args.output, args.format);
+    } else {
+        // Quick answer mode - display in chat
+        await displayQuickAnswer(token, datasetId);
+    }
+}
+
+main().catch((err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+});

package/templates/.agent/skills/app-store-optimization/HOW_TO_USE.md

@@ -0,0 +1,281 @@
+# How to Use the App Store Optimization Skill
+
+Hey Claude—I just added the "app-store-optimization" skill. Can you help me optimize my app's presence on the App Store and Google Play?
+
+## Example Invocations
+
+### Keyword Research
+
+**Example 1: Basic Keyword Research**
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you research the best keywords for my productivity app? I'm targeting professionals who need task management and team collaboration features.
+```
+
+**Example 2: Competitive Keyword Analysis**
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you analyze keywords that Todoist, Asana, and Monday.com are using? I want to find gaps and opportunities for my project management app.
+```
+
+### Metadata Optimization
+
+**Example 3: Optimize App Title**
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you optimize my app title for the Apple App Store? My app is called "TaskFlow" and I want to rank for "task manager", "productivity", and "team collaboration". The title needs to be under 30 characters.
+```
+
+**Example 4: Full Metadata Package**
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you create optimized metadata for both Apple App Store and Google Play Store? Here's my app info:
+- Name: TaskFlow
+- Category: Productivity
+- Key features: AI task prioritization, team collaboration, calendar integration
+- Target keywords: task manager, productivity app, team tasks
+```
+
+### Competitor Analysis
+
+**Example 5: Analyze Top Competitors**
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you analyze the ASO strategies of the top 5 productivity apps in the App Store? I want to understand their title strategies, keyword usage, and visual asset approaches.
+```
+
+**Example 6: Identify Competitive Gaps**
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you compare my app's ASO performance against competitors and identify what I'm missing? Here's my current metadata: [paste metadata]
+```
+
+### ASO Score Calculation
+
+**Example 7: Calculate Overall ASO Health**
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you calculate my app's ASO health score? Here are my metrics:
+- Average rating: 4.2 stars
+- Total ratings: 3,500
+- Keywords in top 10: 3
+- Keywords in top 50: 12
+- Conversion rate: 4.5%
+```
+
+**Example 8: Identify Improvement Areas**
+```
+Hey Claude—I just added the "app-store-optimization" skill. My ASO score is 62/100. Can you tell me which areas I should focus on first to improve my rankings and downloads?
+```
+
+### A/B Testing
+
+**Example 9: Plan Icon Test**
+```
+Hey Claude—I just added the "app-store-optimization" skill. I want to A/B test two different app icons. My current conversion rate is 5%. Can you help me plan the test, calculate required sample size, and determine how long to run it?
+```
+
+**Example 10: Analyze Test Results**
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you analyze my A/B test results?
+- Variant A (control): 2,500 visitors, 125 installs
+- Variant B (new icon): 2,500 visitors, 150 installs
+Is this statistically significant? Should I implement variant B?
+```
+
+### Localization
+
+**Example 11: Plan Localization Strategy**
+```
+Hey Claude—I just added the "app-store-optimization" skill. I currently only have English metadata. Which markets should I localize for first? I'm a bootstrapped startup with moderate budget.
+```
+
+**Example 12: Translate Metadata**
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you help me translate my app metadata to Spanish for the Mexico market? Here's my English metadata: [paste metadata]. Check if it fits within character limits.
+```
+
+### Review Analysis
+
+**Example 13: Analyze User Reviews**
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you analyze my recent reviews and tell me:
+- Overall sentiment (positive/negative ratio)
+- Most common complaints
+- Most requested features
+- Bugs that need immediate fixing
+```
+
+**Example 14: Generate Review Response Templates**
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you create professional response templates for:
+- Users reporting crashes
+- Feature requests
+- Positive 5-star reviews
+- General complaints
+```
+
+### Launch Planning
+
+**Example 15: Pre-Launch Checklist**
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you generate a comprehensive pre-launch checklist for both Apple App Store and Google Play Store? My launch date is December 1, 2025.
+```
+
+**Example 16: Optimize Launch Timing**
+```
+Hey Claude—I just added the "app-store-optimization" skill. What's the best day and time to launch my fitness app? I want to maximize visibility and downloads in the first week.
+```
+
+**Example 17: Plan Seasonal Campaign**
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you identify seasonal opportunities for my fitness app? It's currently October—what campaigns should I run for the next 6 months?
+```
+
+## What to Provide
+
+### For Keyword Research
+- App name and category
+- Target audience description
+- Key features and unique value proposition
+- Competitor apps (optional)
+- Geographic markets to target
+
+### For Metadata Optimization
+- Current app name
+- Platform (Apple, Google, or both)
+- Target keywords (prioritized list)
+- Key features and benefits
+- Target audience
+- Current metadata (for optimization)
+
+### For Competitor Analysis
+- Your app category
+- List of competitor app names or IDs
+- Platform (Apple or Google)
+- Specific aspects to analyze (keywords, visuals, ratings)
+
+### For ASO Score Calculation
+- Metadata quality metrics (title length, description length, keyword density)
+- Rating data (average rating, total ratings, recent ratings)
+- Keyword rankings (top 10, top 50, top 100 counts)
+- Conversion metrics (impression-to-install rate, downloads)
+
+### For A/B Testing
+- Test type (icon, screenshot, title, description)
+- Control variant details
+- Test variant details
+- Baseline conversion rate
+- For results analysis: visitor and conversion counts for both variants
+
+### For Localization
+- Current market and language
+- Budget level (low, medium, high)
+- Target number of markets
+- Current metadata text for translation
+
+### For Review Analysis
+- Recent reviews (text, rating, date)
+- Platform (Apple or Google)
+- Time period to analyze
+- Specific focus (bugs, features, sentiment)
+
+### For Launch Planning
+- Platform (Apple, Google, or both)
+- Target launch date
+- App category
+- App information (name, features, target audience)
+
+## What You'll Get
+
+### Keyword Research Output
+- Prioritized keyword list with search volume estimates
+- Competition level analysis
+- Relevance scores
+- Long-tail keyword opportunities
+- Strategic recommendations
+
+### Metadata Optimization Output
+- Optimized titles (multiple options)
+- Optimized descriptions (short and full)
+- Keyword field optimization (Apple)
+- Character count validation
+- Keyword density analysis
+- Before/after comparison
+
+### Competitor Analysis Output
+- Ranked competitors by ASO strength
+- Common keyword patterns
+- Keyword gaps and opportunities
+- Visual asset assessment
+- Best practices identified
+- Actionable recommendations
+
+### ASO Score Output
+- Overall score (0-100)
+- Breakdown by category (metadata, ratings, keywords, conversion)
+- Strengths and weaknesses
+- Prioritized action items
+- Expected impact of improvements
+
+### A/B Test Output
+- Test design with hypothesis
+- Required sample size calculation
+- Duration estimates
+- Statistical significance analysis
+- Implementation recommendations
+- Learnings and insights
+
+### Localization Output
+- Prioritized target markets
+- Estimated translation costs
+- ROI projections
+- Character limit validation for each language
+- Cultural adaptation recommendations
+- Phased implementation plan
+
+### Review Analysis Output
+- Sentiment distribution (positive/neutral/negative)
+- Common themes and topics
+- Top issues requiring fixes
+- Most requested features
+- Response templates
+- Trend analysis over time
+
+### Launch Planning Output
+- Platform-specific checklists (Apple, Google, Universal)
+- Timeline with milestones
+- Compliance validation
+- Optimal launch timing recommendations
+- Seasonal campaign opportunities
+- Update cadence planning
+
+## Tips for Best Results
+
+1. **Be Specific**: Provide as much detail about your app as possible
+2. **Include Context**: Share your goals (increase downloads, improve ranking, boost conversion)
+3. **Provide Data**: Real metrics enable more accurate analysis
+4. **Iterate**: Start with keyword research, then optimize metadata, then test
+5. **Track Results**: Monitor changes after implementing recommendations
+6. **Stay Compliant**: Always verify recommendations against current App Store/Play Store guidelines
+7. **Test First**: Use A/B testing before making major metadata changes
+8. **Localize Strategically**: Start with highest-ROI markets first
+9. **Respond to Reviews**: Use provided templates to engage with users
+10. **Plan Ahead**: Use launch checklists and timelines to avoid last-minute rushes
+
+## Common Workflows
+
+### New App Launch
+1. Keyword research → Competitor analysis → Metadata optimization → Pre-launch checklist → Launch timing optimization
+
+### Improving Existing App
+1. ASO score calculation → Identify gaps → Metadata optimization → A/B testing → Review analysis → Implement changes
+
+### International Expansion
+1. Localization planning → Market prioritization → Metadata translation → ROI analysis → Phased rollout
+
+### Ongoing Optimization
+1. Monthly keyword ranking tracking → Quarterly metadata updates → Continuous A/B testing → Review monitoring → Seasonal campaigns
+
+## Need Help?
+
+If you need clarification on any aspect of ASO or want to combine multiple analyses, just ask! For example:
+
+```
+Hey Claude—I just added the "app-store-optimization" skill. Can you create a complete ASO strategy for my new productivity app? I need keyword research, optimized metadata for both stores, a pre-launch checklist, and launch timing recommendations.
+```
+
+The skill can handle comprehensive, multi-phase ASO projects as well as specific tactical optimizations.