thumbgate 0.9.10

package/scripts/social-analytics/digest.js

@@ -0,0 +1,256 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { initDb, queryMetrics, topContent, getFollowerHistory } = require('./store');
+
+const PLATFORMS = ['instagram', 'tiktok', 'github'];
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const DEFAULT_OUTPUT_DIR = path.join(REPO_ROOT, '.artifacts', 'social', 'digests');
+
+/**
+ * Formats a Date to YYYY-MM-DD in local time.
+ * @param {Date} date
+ * @returns {string}
+ */
+function toDateString(date) {
+  return date.toISOString().slice(0, 10);
+}
+
+/**
+ * Calculates the follower delta for each platform over the given window.
+ * Returns the difference between the most recent snapshot and the oldest
+ * snapshot within the window. Returns 0 if fewer than 2 snapshots exist.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {number} days
+ * @returns {{ instagram: number, tiktok: number, github: number }}
+ */
+function buildFollowerDelta(db, days) {
+  const delta = {};
+  for (const platform of PLATFORMS) {
+    const history = getFollowerHistory(db, { platform, days });
+    if (history.length >= 2) {
+      delta[platform] = history[history.length - 1].follower_count - history[0].follower_count;
+    } else if (history.length === 1) {
+      delta[platform] = 0;
+    } else {
+      delta[platform] = 0;
+    }
+  }
+  return delta;
+}
+
+/**
+ * Builds per-platform aggregated metrics map.
+ *
+ * @param {object[]} rows - Rows from queryMetrics (all platforms).
+ * @returns {object}
+ */
+function buildByPlatform(rows) {
+  const byPlatform = {};
+  for (const platform of PLATFORMS) {
+    const row = rows.find((r) => r.platform === platform);
+    if (row) {
+      byPlatform[platform] = {
+        post_count: row.post_count,
+        total_impressions: row.total_impressions,
+        total_reach: row.total_reach,
+        total_likes: row.total_likes,
+        total_comments: row.total_comments,
+        total_shares: row.total_shares,
+        total_saves: row.total_saves,
+        total_clicks: row.total_clicks,
+        total_video_views: row.total_video_views,
+        avg_impressions: row.avg_impressions,
+        avg_likes: row.avg_likes,
+      };
+    } else {
+      byPlatform[platform] = {
+        post_count: 0,
+        total_impressions: 0,
+        total_reach: 0,
+        total_likes: 0,
+        total_comments: 0,
+        total_shares: 0,
+        total_saves: 0,
+        total_clicks: 0,
+        total_video_views: 0,
+        avg_impressions: 0,
+        avg_likes: 0,
+      };
+    }
+  }
+  return byPlatform;
+}
+
+/**
+ * Generates a weekly digest object from the SQLite database.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {{ days?: number }} options
+ * @returns {object} digest
+ */
+function generateDigest(db, { days = 7 } = {}) {
+  const end = new Date();
+  const start = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+
+  const allMetrics = queryMetrics(db, { days });
+  const top = topContent(db, { days, limit: 10 });
+  const followerDelta = buildFollowerDelta(db, days);
+  const byPlatform = buildByPlatform(allMetrics);
+
+  // Aggregate totals across all platforms.
+  let totalImpressions = 0;
+  let totalLikes = 0;
+  let totalComments = 0;
+  let totalShares = 0;
+
+  for (const row of allMetrics) {
+    totalImpressions += row.total_impressions || 0;
+    totalLikes += row.total_likes || 0;
+    totalComments += row.total_comments || 0;
+    totalShares += row.total_shares || 0;
+  }
+
+  const engagementRaw =
+    totalImpressions > 0
+      ? (((totalLikes + totalComments + totalShares) / totalImpressions) * 100).toFixed(1)
+      : '0.0';
+
+  const topContent_ = top.map((row) => ({
+    platform: row.platform,
+    post_id: row.post_id,
+    post_url: row.post_url || null,
+    total_engagement: row.total_engagement,
+    impressions: row.total_impressions,
+  }));
+
+  return {
+    period: {
+      start: toDateString(start),
+      end: toDateString(end),
+    },
+    summary: {
+      total_impressions: totalImpressions,
+      total_likes: totalLikes,
+      total_comments: totalComments,
+      total_shares: totalShares,
+      engagement_rate: `${engagementRaw}%`,
+      follower_delta: followerDelta,
+    },
+    by_platform: byPlatform,
+    top_content: topContent_,
+  };
+}
+
+/**
+ * Converts a digest object to a readable markdown string.
+ *
+ * @param {object} digest
+ * @returns {string}
+ */
+function renderDigestMarkdown(digest) {
+  const { period, summary, by_platform, top_content } = digest;
+
+  const lines = [];
+
+  lines.push(`# Weekly Social Digest: ${period.start} → ${period.end}`);
+  lines.push('');
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`| Metric | Value |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Total Impressions | ${summary.total_impressions.toLocaleString()} |`);
+  lines.push(`| Total Likes | ${summary.total_likes.toLocaleString()} |`);
+  lines.push(`| Total Comments | ${summary.total_comments.toLocaleString()} |`);
+  lines.push(`| Total Shares | ${summary.total_shares.toLocaleString()} |`);
+  lines.push(`| Engagement Rate | ${summary.engagement_rate} |`);
+  lines.push('');
+  lines.push('### Follower Delta');
+  lines.push('');
+  lines.push(`| Platform | Change |`);
+  lines.push(`|----------|--------|`);
+  for (const [platform, delta] of Object.entries(summary.follower_delta)) {
+    const sign = delta >= 0 ? '+' : '';
+    lines.push(`| ${platform} | ${sign}${delta} |`);
+  }
+
+  lines.push('');
+  lines.push('## By Platform');
+  lines.push('');
+
+  for (const [platform, stats] of Object.entries(by_platform)) {
+    lines.push(`### ${platform.charAt(0).toUpperCase() + platform.slice(1)}`);
+    lines.push('');
+    lines.push(`| Metric | Value |`);
+    lines.push(`|--------|-------|`);
+    lines.push(`| Posts | ${stats.post_count} |`);
+    lines.push(`| Impressions | ${stats.total_impressions.toLocaleString()} |`);
+    lines.push(`| Reach | ${stats.total_reach.toLocaleString()} |`);
+    lines.push(`| Likes | ${stats.total_likes.toLocaleString()} |`);
+    lines.push(`| Comments | ${stats.total_comments.toLocaleString()} |`);
+    lines.push(`| Shares | ${stats.total_shares.toLocaleString()} |`);
+    lines.push(`| Saves | ${stats.total_saves.toLocaleString()} |`);
+    lines.push(`| Clicks | ${stats.total_clicks.toLocaleString()} |`);
+    lines.push(`| Video Views | ${stats.total_video_views.toLocaleString()} |`);
+    lines.push('');
+  }
+
+  lines.push('## Top Content');
+  lines.push('');
+
+  if (top_content.length === 0) {
+    lines.push('_No content recorded in this period._');
+  } else {
+    lines.push(`| # | Platform | Post ID | Engagement | Impressions | URL |`);
+    lines.push(`|---|----------|---------|------------|-------------|-----|`);
+    top_content.forEach((item, idx) => {
+      const url = item.post_url ? `[link](${item.post_url})` : '—';
+      lines.push(
+        `| ${idx + 1} | ${item.platform} | ${item.post_id} | ${item.total_engagement} | ${item.impressions.toLocaleString()} | ${url} |`
+      );
+    });
+  }
+
+  lines.push('');
+  lines.push(`_Generated at ${new Date().toISOString()}_`);
+
+  return lines.join('\n');
+}
+
+/**
+ * Writes digest.json and digest.md to the given output directory.
+ *
+ * @param {object} digest
+ * @param {string} outputDir
+ * @returns {{ jsonPath: string, mdPath: string }}
+ */
+function writeDigest(digest, outputDir) {
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  const jsonPath = path.join(outputDir, 'digest.json');
+  const mdPath = path.join(outputDir, 'digest.md');
+
+  fs.writeFileSync(jsonPath, JSON.stringify(digest, null, 2), 'utf8');
+  fs.writeFileSync(mdPath, renderDigestMarkdown(digest), 'utf8');
+
+  return { jsonPath, mdPath };
+}
+
+module.exports = {
+  generateDigest,
+  renderDigestMarkdown,
+  writeDigest,
+};
+
+// Run as main: generate and write a 7-day digest.
+if (require.main === module) {
+  const db = initDb();
+  const digest = generateDigest(db, { days: 7 });
+  const { jsonPath, mdPath } = writeDigest(digest, DEFAULT_OUTPUT_DIR);
+  console.log(`Digest written:\n  JSON: ${jsonPath}\n  MD:   ${mdPath}`);
+  console.log(`\nSummary: ${JSON.stringify(digest.summary, null, 2)}`);
+  db.close();
+}

package/scripts/social-analytics/generate-instagram-card.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * generate-instagram-card.js
+ * Creates a 1080x1080 ThumbGate Instagram card using sharp.
+ *
+ * Usage:
+ *   node generate-instagram-card.js [--output=path/to/output.png]
+ *
+ * Output: .thumbgate/instagram-card.png (default)
+ */
+
+const fs = require('fs');
+const path = require('path');
+let sharp;
+try { sharp = require('sharp'); } catch { /* optional dependency */ }
+
+const REPO_ROOT = path.resolve(__dirname, '../..');
+const DEFAULT_OUTPUT = path.join(REPO_ROOT, '.thumbgate', 'instagram-card.png');
+
+async function generateInstagramCard(outputPath = DEFAULT_OUTPUT) {
+  const width = 1080;
+  const height = 1080;
+
+  // Create SVG markup for the card
+  const svg = `
+    <svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">
+      <!-- Background -->
+      <rect width="${width}" height="${height}" fill="#0d1117"/>
+
+      <!-- Main heading -->
+      <text x="${width / 2}" y="400" font-size="72" font-weight="bold" text-anchor="middle" fill="#ffffff" font-family="Arial, sans-serif">
+        Your AI agent
+      </text>
+      <text x="${width / 2}" y="490" font-size="72" font-weight="bold" text-anchor="middle" fill="#ffffff" font-family="Arial, sans-serif">
+        has amnesia.
+      </text>
+
+      <!-- Subheading -->
+      <text x="${width / 2}" y="620" font-size="48" text-anchor="middle" fill="#888888" font-family="Arial, sans-serif">
+        Give it memory that
+      </text>
+      <text x="${width / 2}" y="680" font-size="48" text-anchor="middle" fill="#888888" font-family="Arial, sans-serif">
+        survives restarts.
+      </text>
+
+      <!-- Brand -->
+      <text x="${width / 2}" y="950" font-size="56" font-weight="bold" text-anchor="middle" fill="#00d9ff" font-family="Arial, sans-serif">
+        ThumbGate
+      </text>
+    </svg>
+  `;
+
+  if (!sharp) {
+    throw new Error('sharp is not installed. Run: npm install sharp');
+  }
+
+  try {
+    // Ensure output directory exists
+    const outputDir = path.dirname(outputPath);
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    // Generate PNG from SVG
+    await sharp(Buffer.from(svg))
+      .png()
+      .toFile(outputPath);
+
+    console.log(`✅ Instagram card generated: ${outputPath}`);
+    console.log(`   Size: 1080x1080 PNG`);
+    console.log(`   File size: ${fs.statSync(outputPath).size} bytes`);
+    return outputPath;
+  } catch (err) {
+    console.error(`❌ Image generation failed: ${err.message}`);
+    throw err;
+  }
+}
+
+// CLI execution
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const outputArg = args.find((a) => a.startsWith('--output='));
+  const outputPath = outputArg ? outputArg.slice(9) : DEFAULT_OUTPUT;
+
+  (async () => {
+    try {
+      await generateInstagramCard(outputPath);
+      process.exit(0);
+    } catch (err) {
+      process.exit(1);
+    }
+  })();
+}
+
+module.exports = { generateInstagramCard, DEFAULT_OUTPUT };

package/scripts/social-analytics/instagram-thumbgate-post.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * instagram-thumbgate-post.js
+ * Posts ThumbGate Instagram card and caption via Zernio API.
+ *
+ * Usage:
+ *   node instagram-thumbgate-post.js [--image-path=path/to/image.png]
+ */
+
+const path = require('path');
+const {
+  publishPost,
+  publishToAllPlatforms,
+  getConnectedAccounts,
+} = require('./publishers/zernio');
+
+const THUMBGATE_CAPTION = `Your AI coding agent has amnesia. It forgets everything between sessions.
+
+ThumbGate gives it memory that survives restarts. Thumbs-down a mistake → it becomes a prevention rule → the agent can't repeat it.
+
+One command: npx thumbgate init
+
+Works with Claude Code, Cursor, Codex, Gemini.
+
+#AIAgents #DeveloperTools #CodingAgents #MCP #OpenSource #ClaudeCode #ThumbGate`;
+
+async function postThumbGateToInstagram() {
+  try {
+    console.log('[instagram] Fetching Zernio connected accounts...');
+    const accounts = await getConnectedAccounts();
+
+    // Find Instagram account
+    const instagramAccount = accounts.find((a) => a.platform === 'instagram');
+    if (!instagramAccount) {
+      throw new Error('No Instagram account found in Zernio. Please connect Instagram first.');
+    }
+
+    console.log(`[instagram] Found Instagram account: ${instagramAccount.accountId}`);
+
+    const platforms = [
+      {
+        platform: 'instagram',
+        accountId: instagramAccount.accountId,
+      },
+    ];
+
+    console.log('[instagram] Publishing ThumbGate caption to Instagram...');
+    const result = await publishPost(THUMBGATE_CAPTION, platforms);
+
+    console.log('✅ Post published successfully!');
+    console.log(`Post ID: ${result.id || result.data?.id || 'unknown'}`);
+    return result;
+  } catch (err) {
+    console.error(`❌ Failed to post to Instagram: ${err.message}`);
+    throw err;
+  }
+}
+
+// CLI execution
+if (require.main === module) {
+  (async () => {
+    try {
+      await postThumbGateToInstagram();
+      process.exit(0);
+    } catch (err) {
+      process.exit(1);
+    }
+  })();
+}
+
+module.exports = { postThumbGateToInstagram, THUMBGATE_CAPTION };

package/scripts/social-analytics/mcp-server.js

@@ -0,0 +1,289 @@
+'use strict';
+
+/**
+ * MCP stdio server for social analytics.
+ *
+ * Exposes social metrics from SQLite as queryable tools for Claude.
+ * Uses a simple JSON-RPC 2.0 over stdio pattern — no external MCP SDK required.
+ *
+ * Protocol:
+ *   - Reads newline-delimited JSON-RPC 2.0 requests from stdin.
+ *   - Writes newline-delimited JSON-RPC 2.0 responses to stdout.
+ *   - Supported methods: tools/list, tools/call
+ */
+
+const readline = require('readline');
+
+const { initDb, queryMetrics, topContent, getFollowerHistory } = require('./store');
+const { generateDigest } = require('./digest');
+
+const VALID_PLATFORMS = ['instagram', 'tiktok', 'github', 'all'];
+
+// Tool definitions exposed to Claude.
+const TOOLS = [
+  {
+    name: 'query_social_metrics',
+    description:
+      'Returns aggregated engagement metrics from the social analytics database for the given platform and time window.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: {
+          type: 'string',
+          enum: VALID_PLATFORMS,
+          description: 'Platform to query. Use "all" for all platforms combined.',
+        },
+        days: {
+          type: 'number',
+          description: 'Number of past days to include in the query.',
+          default: 7,
+        },
+      },
+      required: ['platform'],
+    },
+  },
+  {
+    name: 'top_social_content',
+    description:
+      'Returns top content items ranked by total engagement (likes + comments + shares + saves) over the past N days.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: {
+          type: 'number',
+          description: 'Number of past days to consider.',
+          default: 7,
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results to return.',
+          default: 10,
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'follower_growth',
+    description: 'Returns follower count snapshots for a platform over the past N days.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: {
+          type: 'string',
+          enum: ['instagram', 'tiktok', 'github'],
+          description: 'Platform to query follower history for.',
+        },
+        days: {
+          type: 'number',
+          description: 'Number of past days to include.',
+          default: 7,
+        },
+      },
+      required: ['platform'],
+    },
+  },
+  {
+    name: 'social_digest',
+    description:
+      'Returns a full digest object summarising all social metrics, follower deltas, and top content for the past N days.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: {
+          type: 'number',
+          description: 'Number of past days to summarise.',
+          default: 7,
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+/**
+ * Validates that a value is a positive integer (or coerces a numeric string).
+ *
+ * @param {*} value
+ * @param {number} defaultVal
+ * @returns {number}
+ */
+function asPositiveInt(value, defaultVal) {
+  const n = value == null ? defaultVal : Number(value);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new Error(`Expected a positive number, got: ${value}`);
+  }
+  return Math.floor(n);
+}
+
+/**
+ * Dispatches a tools/call request and returns the result payload.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} toolName
+ * @param {object} toolArgs
+ * @returns {object}
+ */
+function callTool(db, toolName, toolArgs) {
+  const args = toolArgs || {};
+
+  switch (toolName) {
+    case 'query_social_metrics': {
+      const platform = args.platform;
+      if (!VALID_PLATFORMS.includes(platform)) {
+        throw new Error(`Invalid platform "${platform}". Must be one of: ${VALID_PLATFORMS.join(', ')}`);
+      }
+      const days = asPositiveInt(args.days, 7);
+      const opts = platform === 'all' ? { days } : { platform, days };
+      const rows = queryMetrics(db, opts);
+      return { rows };
+    }
+
+    case 'top_social_content': {
+      const days = asPositiveInt(args.days, 7);
+      const limit = asPositiveInt(args.limit, 10);
+      const rows = topContent(db, { days, limit });
+      return { rows };
+    }
+
+    case 'follower_growth': {
+      const platform = args.platform;
+      if (!platform || !['instagram', 'tiktok', 'github'].includes(platform)) {
+        throw new Error(`Invalid platform "${platform}". Must be one of: instagram, tiktok, github`);
+      }
+      const days = asPositiveInt(args.days, 7);
+      const rows = getFollowerHistory(db, { platform, days });
+      return { rows };
+    }
+
+    case 'social_digest': {
+      const days = asPositiveInt(args.days, 7);
+      const digest = generateDigest(db, { days });
+      return digest;
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${toolName}`);
+  }
+}
+
+/**
+ * Builds a JSON-RPC 2.0 success response.
+ *
+ * @param {string|number|null} id
+ * @param {*} result
+ * @returns {object}
+ */
+function successResponse(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+
+/**
+ * Builds a JSON-RPC 2.0 error response.
+ *
+ * @param {string|number|null} id
+ * @param {number} code
+ * @param {string} message
+ * @returns {object}
+ */
+function errorResponse(id, code, message) {
+  return { jsonrpc: '2.0', id, error: { code, message } };
+}
+
+/**
+ * Handles a single parsed JSON-RPC request object and returns a response object.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {object} request
+ * @returns {object}
+ */
+function handleRequest(db, request) {
+  const { id = null, method, params } = request;
+
+  try {
+    if (method === 'tools/list') {
+      return successResponse(id, { tools: TOOLS });
+    }
+
+    if (method === 'tools/call') {
+      const { name: toolName, arguments: toolArgs } = params || {};
+      if (!toolName) {
+        return errorResponse(id, -32602, 'Missing required param: name');
+      }
+      const result = callTool(db, toolName, toolArgs);
+      return successResponse(id, {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      });
+    }
+
+    // Method not found.
+    return errorResponse(id, -32601, `Method not found: ${method}`);
+  } catch (err) {
+    return errorResponse(id, -32603, err.message);
+  }
+}
+
+/**
+ * Starts the MCP stdio server. Reads newline-delimited JSON from stdin,
+ * writes newline-delimited JSON to stdout.
+ */
+function startServer() {
+  const db = initDb();
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: null,
+    terminal: false,
+  });
+
+  process.stderr.write('[social-analytics mcp-server] Listening on stdin...\n');
+
+  rl.on('line', (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    let request;
+    try {
+      request = JSON.parse(trimmed);
+    } catch (_) {
+      const resp = errorResponse(null, -32700, 'Parse error: invalid JSON');
+      process.stdout.write(JSON.stringify(resp) + '\n');
+      return;
+    }
+
+    const response = handleRequest(db, request);
+    process.stdout.write(JSON.stringify(response) + '\n');
+  });
+
+  rl.on('close', () => {
+    db.close();
+    process.stderr.write('[social-analytics mcp-server] stdin closed, shutting down.\n');
+  });
+
+  process.on('SIGINT', () => {
+    db.close();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    db.close();
+    process.exit(0);
+  });
+}
+
+module.exports = {
+  TOOLS,
+  callTool,
+  handleRequest,
+  startServer,
+};
+
+// Run as main: start the stdio server.
+if (require.main === module) {
+  startServer();
+}