stacksherpa 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alex Stein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# stacksherpa
+
+Intelligent API recommendation engine for Claude Code. Silently picks the best APIs for your stack based on your project profile, constraints, and past experiences.
+
+## Install
+
+```bash
+claude plugin add github:alexstein/stacksherpa
+```
+
+That's it. The skill loads automatically and the MCP server starts on first use.
+
+## What happens
+
+When you ask Claude to implement something that needs an external API (email, payments, auth, etc.), stacksherpa:
+
+1. Checks the shared provider catalog (50+ providers across 13 categories)
+2. Scores providers against your project profile (stack, scale, compliance, budget)
+3. Applies taste learned from your past decisions across all projects
+4. Returns the best match with confidence level
+
+Claude uses the recommendation silently — you just get the right API without having to research it.
+
+## How it works
+
+**Scoring factors:**
+- Compliance match (SOC2, HIPAA, GDPR, PCI-DSS)
+- Scale fit (hobby → enterprise)
+- Strength alignment with your priorities (DX, reliability, cost, performance)
+- Ecosystem affinity (prefers providers in ecosystems you already use)
+- Past experience (positive/negative outcomes across projects)
+- Pattern inference (learns your preferences over time)
+
+**Categories:** email, payments, auth, sms, storage, database, analytics, search, monitoring, ai, push, financial-data, trading, prediction-markets
+
+## Tools
+
+The MCP server exposes these tools:
+
+| Tool | Description |
+|------|-------------|
+| `recommend` | Get instant recommendation for a category |
+| `get_profile` | View merged project profile + taste |
+| `update_project_profile` | Surgical profile updates (set/append/remove) |
+| `record_decision` | Record an API selection outcome |
+| `get_provider` | Detailed provider info (pricing, issues, benchmarks) |
+| `list_categories` | All categories with provider counts |
+| `get_search_strategy` | Tailored search queries for research |
+| `report_outcome` | Report integration success/failure |
+
+## Data
+
+- **Shared catalog**: Hosted on Turso (read-only from clients). Providers, pricing, issues, benchmarks.
+- **Local data**: `~/.stacksherpa/` stores your profiles, decisions, and project registry. Never leaves your machine.
+
+## Configuration
+
+### Project profile
+
+Create `.stacksherpa/profile.json` in your project:
+
+```json
+{
+  "project": {
+    "name": "my-app",
+    "stack": { "language": "TypeScript", "framework": "Next.js" },
+    "scale": "startup"
+  },
+  "constraints": {
+    "compliance": ["SOC2"]
+  },
+  "preferences": {
+    "prioritize": ["dx", "reliability"]
+  }
+}
+```
+
+Or let Claude update it for you via the `update_project_profile` tool.
+
+### Global defaults
+
+Set defaults for all projects in `~/.stacksherpa/defaults.json`. Local project profiles override globals.
+
+## Advanced
+
+### Self-hosting the catalog
+
+Set environment variables to point at your own Turso database:
+
+```bash
+TURSO_DATABASE_URL=libsql://your-db.turso.io
+TURSO_AUTH_TOKEN=your-read-token
+```
+
+### Seeding the catalog
+
+```bash
+TURSO_WRITE_TOKEN=your-write-token npm run seed:turso
+```
+
+### Running scrapers
+
+Scrapers update pricing, issues, and benchmarks. They require write access to Turso and API keys for data sources:
+
+```bash
+FIRECRAWL_API_KEY=... TURSO_WRITE_TOKEN=... npm run cron:daily
+```

package/dist/db/client.js

@@ -0,0 +1,444 @@
+/**
+ * Database Client (Turso / libSQL)
+ *
+ * Reads provider catalog from a shared Turso database.
+ * All queries are async. Write methods are only available
+ * when TURSO_WRITE_TOKEN is set (for scrapers/admin).
+ */
+import { createClient } from '@libsql/client';
+import { SCHEMA } from './schema.js';
+// Turso connection — defaults to shared read-only catalog
+const TURSO_URL = process.env.TURSO_DATABASE_URL ?? 'libsql://api-broker-astein91.aws-us-west-2.turso.io';
+const TURSO_READ_TOKEN = process.env.TURSO_AUTH_TOKEN ?? 'eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJhIjoicm8iLCJpYXQiOjE3NzA5MTg3OTUsImlkIjoiYjA4YmZkNTUtZjhhNi00ODU5LThjNzMtYjg4NzIzMmI4YmYyIiwicmlkIjoiMWJjN2NhMTgtMDU1OC00NjI2LWJjY2YtOGVmMWIwZjQ1ZDAxIn0.aZ4gR9f0I9Qq8T_tkQp-uXwL-4LzUPGaGCDATirOFBBu9kHmuFs5cfXXJ162RzfX2Nrsn-HEAx_H8-uSSfiKBA';
+const TURSO_WRITE_TOKEN = process.env.TURSO_WRITE_TOKEN;
+let client = null;
+export function getClient() {
+    if (!client) {
+        client = createClient({
+            url: TURSO_URL,
+            authToken: TURSO_READ_TOKEN || undefined,
+        });
+    }
+    return client;
+}
+/**
+ * Initialize the database schema (for local/embedded use or first-time Turso setup).
+ * In production, schema is managed via Turso CLI.
+ */
+export async function ensureSchema() {
+    const db = getClient();
+    // Split SCHEMA into individual statements and execute each
+    const statements = SCHEMA
+        .split(';')
+        .map(s => s.trim())
+        .filter(s => s.length > 0);
+    for (const stmt of statements) {
+        await db.execute(stmt);
+    }
+}
+// ============================================
+// Query Methods (for MCP server)
+// ============================================
+/**
+ * Get all providers in a category
+ */
+export async function getProvidersByCategory(category) {
+    const db = getClient();
+    const result = await db.execute({
+        sql: `SELECT * FROM providers WHERE category = ? AND status = 'active'`,
+        args: [category],
+    });
+    return result.rows.map(row => rowToProvider(row));
+}
+/**
+ * Get a single provider by ID with all related data
+ */
+export async function getProviderById(id) {
+    const db = getClient();
+    const result = await db.execute({
+        sql: `SELECT * FROM providers WHERE id = ?`,
+        args: [id],
+    });
+    if (result.rows.length === 0)
+        return null;
+    const row = result.rows[0];
+    const provider = rowToProvider(row);
+    // Get latest pricing
+    const pricingResult = await db.execute({
+        sql: `SELECT * FROM latest_pricing WHERE provider_id = ?`,
+        args: [id],
+    });
+    if (pricingResult.rows.length > 0) {
+        provider.pricing = rowToPricing(pricingResult.rows[0]);
+    }
+    // Get known issues
+    const issuesResult = await db.execute({
+        sql: `SELECT * FROM active_issues WHERE provider_id = ?`,
+        args: [id],
+    });
+    if (issuesResult.rows.length > 0) {
+        provider.knownIssues = issuesResult.rows.map(r => rowToKnownIssue(r));
+    }
+    // Get AI benchmarks if applicable
+    if (row.category === 'ai') {
+        const benchResult = await db.execute({
+            sql: `SELECT * FROM latest_ai_benchmarks WHERE provider_id = ?`,
+            args: [id],
+        });
+        if (benchResult.rows.length > 0) {
+            provider.aiBenchmarks = rowToAiBenchmarks(benchResult.rows[0]);
+        }
+    }
+    return provider;
+}
+/**
+ * Search providers with filters
+ */
+export async function searchProviders(filters) {
+    const db = getClient();
+    let sql = `
+    SELECT DISTINCT p.* FROM providers p
+    LEFT JOIN latest_pricing pr ON p.id = pr.provider_id
+    WHERE p.status = 'active'
+  `;
+    const args = [];
+    if (filters.category) {
+        sql += ` AND p.category = ?`;
+        args.push(filters.category);
+    }
+    if (filters.compliance && filters.compliance.length > 0) {
+        for (const c of filters.compliance) {
+            sql += ` AND EXISTS (SELECT 1 FROM json_each(p.compliance) WHERE json_each.value = ?)`;
+            args.push(c);
+        }
+    }
+    if (filters.scale) {
+        sql += ` AND EXISTS (SELECT 1 FROM json_each(p.best_for) WHERE json_each.value = ?)`;
+        args.push(filters.scale);
+    }
+    if (filters.hasFreeTier) {
+        sql += ` AND pr.free_tier_included IS NOT NULL`;
+    }
+    if (filters.maxPricePerUnit !== undefined) {
+        sql += ` AND (pr.unit_price IS NULL OR pr.unit_price <= ?)`;
+        args.push(filters.maxPricePerUnit);
+    }
+    const result = await db.execute({ sql, args });
+    return result.rows.map(row => rowToProvider(row));
+}
+/**
+ * Get active issues for a provider
+ */
+export async function getActiveIssues(providerId) {
+    const db = getClient();
+    const result = await db.execute({
+        sql: `SELECT * FROM active_issues WHERE provider_id = ?`,
+        args: [providerId],
+    });
+    return result.rows.map(r => rowToKnownIssue(r));
+}
+/**
+ * Get all categories with provider counts
+ */
+export async function getCategories() {
+    const db = getClient();
+    const result = await db.execute(`
+    SELECT category, COUNT(*) as count
+    FROM providers
+    WHERE status = 'active'
+    GROUP BY category
+    ORDER BY count DESC
+  `);
+    return result.rows.map(r => ({
+        category: r.category,
+        count: Number(r.count),
+    }));
+}
+/**
+ * Get a map of provider name (lowercase) -> ecosystem for all providers that have one.
+ * Used for ecosystem affinity scoring without loading all providers.
+ */
+export async function getProviderEcosystems() {
+    const db = getClient();
+    const result = await db.execute(`
+    SELECT LOWER(name) as name, ecosystem
+    FROM providers
+    WHERE ecosystem IS NOT NULL AND ecosystem != '' AND status = 'active'
+  `);
+    return new Map(result.rows.map(r => [r.name, r.ecosystem]));
+}
+/**
+ * Get providers needing updates (stale data)
+ */
+export async function getStaleProviders(daysSinceUpdate = 30) {
+    const db = getClient();
+    const cutoff = new Date(Date.now() - daysSinceUpdate * 24 * 60 * 60 * 1000).toISOString();
+    const result = await db.execute({
+        sql: `
+      SELECT * FROM providers
+      WHERE last_verified < ? OR last_verified IS NULL
+      ORDER BY last_verified ASC NULLS FIRST
+    `,
+        args: [cutoff],
+    });
+    return result.rows;
+}
+// ============================================
+// Write Methods (for scrapers/admin — requires TURSO_WRITE_TOKEN)
+// ============================================
+function getWriteClient() {
+    if (!TURSO_WRITE_TOKEN) {
+        throw new Error('TURSO_WRITE_TOKEN is required for write operations');
+    }
+    return createClient({
+        url: TURSO_URL,
+        authToken: TURSO_WRITE_TOKEN,
+    });
+}
+/**
+ * Upsert a provider (requires write token)
+ */
+export async function upsertProvider(provider) {
+    const db = getWriteClient();
+    await db.execute({
+        sql: `
+      INSERT INTO providers (
+        id, name, description, category, subcategories, status,
+        website, docs_url, package, package_alt_names,
+        compliance, data_residency, self_hostable, on_prem_option,
+        strengths, weaknesses, best_for,
+        avoid_if, requires, best_when, alternatives,
+        ecosystem, updated_at, last_verified
+      ) VALUES (
+        ?, ?, ?, ?, ?, ?,
+        ?, ?, ?, ?,
+        ?, ?, ?, ?,
+        ?, ?, ?,
+        ?, ?, ?, ?,
+        ?, CURRENT_TIMESTAMP, ?
+      )
+      ON CONFLICT(id) DO UPDATE SET
+        name = excluded.name,
+        description = excluded.description,
+        category = excluded.category,
+        subcategories = excluded.subcategories,
+        status = excluded.status,
+        website = excluded.website,
+        docs_url = excluded.docs_url,
+        package = excluded.package,
+        package_alt_names = excluded.package_alt_names,
+        compliance = excluded.compliance,
+        data_residency = excluded.data_residency,
+        self_hostable = excluded.self_hostable,
+        on_prem_option = excluded.on_prem_option,
+        strengths = excluded.strengths,
+        weaknesses = excluded.weaknesses,
+        best_for = excluded.best_for,
+        avoid_if = excluded.avoid_if,
+        requires = excluded.requires,
+        best_when = excluded.best_when,
+        alternatives = excluded.alternatives,
+        ecosystem = excluded.ecosystem,
+        updated_at = CURRENT_TIMESTAMP,
+        last_verified = excluded.last_verified
+    `,
+        args: [
+            provider.id ?? provider.name.toLowerCase().replace(/\s+/g, '-'),
+            provider.name,
+            provider.description ?? null,
+            provider.category ?? 'unknown',
+            JSON.stringify(provider.subcategories ?? []),
+            provider.status ?? 'active',
+            provider.website ?? null,
+            provider.docsUrl ?? null,
+            provider.package ?? null,
+            JSON.stringify(provider.packageAltNames ?? {}),
+            JSON.stringify(provider.compliance ?? []),
+            JSON.stringify(provider.dataResidency ?? []),
+            provider.selfHostable ? 1 : 0,
+            provider.onPremOption ? 1 : 0,
+            JSON.stringify(provider.strengths ?? []),
+            JSON.stringify(provider.weaknesses ?? []),
+            JSON.stringify(provider.bestFor ?? provider.scale ?? []),
+            JSON.stringify(provider.avoidIf ?? []),
+            JSON.stringify(provider.requires ?? []),
+            JSON.stringify(provider.bestWhen ?? []),
+            JSON.stringify(provider.alternatives ?? []),
+            provider.ecosystem ?? null,
+            provider.lastVerified ?? null,
+        ],
+    });
+}
+/**
+ * Insert pricing data (append-only for history, requires write token)
+ */
+export async function insertPricing(providerId, pricing) {
+    const db = getWriteClient();
+    await db.execute({
+        sql: `
+      INSERT INTO pricing (
+        provider_id, pricing_type, currency,
+        free_tier_included, free_tier_limitations,
+        unit, unit_price, volume_discounts,
+        plans, source_url, scraped_at, confidence
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `,
+        args: [
+            providerId,
+            pricing.type,
+            pricing.currency,
+            pricing.freeTier?.included ?? null,
+            JSON.stringify(pricing.freeTier?.limitations ?? []),
+            pricing.unitPricing?.unit ?? null,
+            pricing.unitPricing?.price ?? null,
+            JSON.stringify(pricing.unitPricing?.volumeDiscounts ?? []),
+            JSON.stringify(pricing.plans ?? []),
+            pricing.source ?? null,
+            pricing.lastVerified,
+            'medium',
+        ],
+    });
+}
+/**
+ * Upsert a known issue (requires write token)
+ */
+export async function upsertKnownIssue(providerId, issue) {
+    const db = getWriteClient();
+    await db.execute({
+        sql: `
+      INSERT INTO known_issues (
+        id, provider_id, symptom, scope, workaround, severity,
+        affected_versions, github_issue_url,
+        reported_at, resolved_at, confidence, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+      ON CONFLICT(id) DO UPDATE SET
+        symptom = excluded.symptom,
+        scope = excluded.scope,
+        workaround = excluded.workaround,
+        severity = excluded.severity,
+        affected_versions = excluded.affected_versions,
+        resolved_at = excluded.resolved_at,
+        confidence = excluded.confidence,
+        updated_at = CURRENT_TIMESTAMP
+    `,
+        args: [
+            issue.id,
+            providerId,
+            issue.symptom,
+            issue.scope ?? null,
+            issue.workaround ?? null,
+            issue.severity,
+            issue.affectedVersions ?? null,
+            issue.githubIssue ?? null,
+            issue.reportedAt ?? null,
+            issue.resolvedAt ?? null,
+            issue.confidence,
+        ],
+    });
+}
+// ============================================
+// Row to Type Converters
+// ============================================
+function parseJson(json) {
+    if (!json)
+        return undefined;
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+}
+function str(val) {
+    if (val === null || val === undefined)
+        return null;
+    return String(val);
+}
+function num(val) {
+    if (val === null || val === undefined)
+        return null;
+    return Number(val);
+}
+function rowToProvider(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        description: row.description ?? undefined,
+        category: row.category,
+        subcategories: parseJson(row.subcategories),
+        status: row.status,
+        website: row.website ?? undefined,
+        docsUrl: row.docs_url ?? undefined,
+        package: row.package ?? undefined,
+        packageAltNames: parseJson(row.package_alt_names),
+        compliance: parseJson(row.compliance),
+        dataResidency: parseJson(row.data_residency),
+        selfHostable: row.self_hostable === 1,
+        onPremOption: row.on_prem_option === 1,
+        strengths: parseJson(row.strengths),
+        weaknesses: parseJson(row.weaknesses),
+        bestFor: parseJson(row.best_for),
+        avoidIf: parseJson(row.avoid_if),
+        requires: parseJson(row.requires),
+        bestWhen: parseJson(row.best_when),
+        alternatives: parseJson(row.alternatives),
+        ecosystem: row.ecosystem ?? undefined,
+        lastVerified: row.last_verified ?? undefined,
+    };
+}
+function rowToPricing(row) {
+    return {
+        type: row.pricing_type ?? 'usage',
+        currency: row.currency,
+        freeTier: row.free_tier_included ? {
+            included: row.free_tier_included,
+            limitations: parseJson(row.free_tier_limitations),
+        } : undefined,
+        unitPricing: row.unit ? {
+            unit: row.unit,
+            price: row.unit_price ?? 0,
+            volumeDiscounts: parseJson(row.volume_discounts),
+        } : undefined,
+        plans: parseJson(row.plans),
+        lastVerified: row.scraped_at,
+        source: row.source_url ?? undefined,
+    };
+}
+function rowToKnownIssue(row) {
+    return {
+        id: row.id,
+        symptom: row.symptom,
+        scope: row.scope ?? '',
+        workaround: row.workaround ?? undefined,
+        severity: row.severity,
+        affectedVersions: row.affected_versions ?? undefined,
+        githubIssue: row.github_issue_url ?? undefined,
+        reportedAt: row.reported_at ?? '',
+        resolvedAt: row.resolved_at ?? undefined,
+        confidence: row.confidence,
+    };
+}
+function rowToAiBenchmarks(row) {
+    return {
+        lmArena: row.lmarena_elo ? {
+            elo: Number(row.lmarena_elo),
+            rank: num(row.lmarena_rank) ?? undefined,
+            category: str(row.lmarena_category) ?? undefined,
+            measuredAt: str(row.measured_at) ?? '',
+        } : undefined,
+        artificialAnalysis: row.aa_quality_index ? {
+            qualityIndex: Number(row.aa_quality_index),
+            speedIndex: num(row.aa_speed_index) ?? undefined,
+            pricePerMToken: num(row.aa_price_per_m_token) ?? undefined,
+            tokensPerSecond: num(row.aa_tokens_per_second) ?? undefined,
+            ttft: num(row.aa_ttft_ms) ?? undefined,
+            measuredAt: str(row.measured_at) ?? '',
+        } : undefined,
+        contextWindow: row.context_max_tokens ? {
+            maxTokens: Number(row.context_max_tokens),
+            effectiveTokens: num(row.context_effective_tokens) ?? undefined,
+        } : undefined,
+        capabilities: parseJson(str(row.capabilities)),
+        benchmarks: parseJson(str(row.benchmarks)),
+    };
+}