thumbgate 1.18.0 → 1.19.0

package/scripts/activation-tracker.js

@@ -0,0 +1,127 @@
+'use strict';
+
+/**
+ * Activation tracker — fires `activation_first_rule_promoted` exactly once
+ * per install, the first time a prevention rule auto-promotes from feedback.
+ *
+ * Why: v1.17.0 opened the free tier (5 active rules, unlimited captures).
+ * The metric that decides whether that worked is the % of `npx thumbgate init`
+ * runs that produce a first auto-promoted prevention rule within 24h. Without
+ * this telemetry, every funnel decision is guessing. This is improvement #1
+ * from the 2026-05-13 revenue-ROI critique.
+ *
+ * Payload (anonymous):
+ *   - eventType: 'activation_first_rule_promoted'
+ *   - installId: stable random UUID (from cli-telemetry.getInstallId)
+ *   - daysToFirstRule: days between INSTALL_ID_PATH creation and now
+ *   - visitorType: ci | owner | real_user (from cli-telemetry.classifyInstall)
+ *
+ * No personal data, no rule content, no feedback text. Just the activation
+ * signal. Respects THUMBGATE_NO_TELEMETRY=1 / DO_NOT_TRACK=1 opt-out via
+ * the underlying trackEvent helper.
+ *
+ * Idempotency: writes a marker file. After the first firing the function
+ * is a no-op for the lifetime of that install.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { trackEvent, getInstallId, classifyInstall, INSTALL_ID_PATH } = require('./cli-telemetry');
+
+const MARKER_DIR = path.join(path.dirname(INSTALL_ID_PATH), 'activation');
+const MARKER_PATH = path.join(MARKER_DIR, 'first-rule-promoted.json');
+
+function readMarker() {
+  try {
+    if (!fs.existsSync(MARKER_PATH)) return null;
+    return JSON.parse(fs.readFileSync(MARKER_PATH, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeMarker(record) {
+  try {
+    if (!fs.existsSync(MARKER_DIR)) fs.mkdirSync(MARKER_DIR, { recursive: true });
+    fs.writeFileSync(MARKER_PATH, JSON.stringify(record, null, 2));
+  } catch {
+    // non-fatal: worst case we double-fire on a future run; the telemetry
+    // backend can dedup by installId. Better to be silent than to throw.
+  }
+}
+
+function computeDaysSinceInstall() {
+  try {
+    if (!fs.existsSync(INSTALL_ID_PATH)) return null;
+    const installed = fs.statSync(INSTALL_ID_PATH).mtimeMs;
+    if (!Number.isFinite(installed) || installed <= 0) return null;
+    const diffMs = Date.now() - installed;
+    if (diffMs < 0) return 0;
+    // 1 decimal of precision; the metric uses 24h buckets but a finer-grained
+    // number lets analytics chart same-day vs. 1d / 2d / week-of activation.
+    return Math.round((diffMs / 86_400_000) * 10) / 10;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fire the activation event if this is the first rule promotion for this
+ * install. Returns true if an event was actually emitted, false if skipped
+ * (already fired before, or environment opted out of telemetry).
+ *
+ * Always synchronous and never throws — safe to call from any side-effect
+ * site without try/catch wrapping. The underlying telemetry call is itself
+ * fire-and-forget over HTTPS with a 3s timeout.
+ */
+function recordFirstRulePromotion(metadata = {}) {
+  if (readMarker()) return false; // already fired
+
+  if (process.env.THUMBGATE_NO_TELEMETRY === '1' || process.env.DO_NOT_TRACK === '1') {
+    // Still write the marker so a later run with telemetry re-enabled does not
+    // fire stale activation data weeks after the actual first promotion.
+    writeMarker({
+      installId: getInstallId(),
+      promotedAt: new Date().toISOString(),
+      telemetryOptOut: true,
+    });
+    return false;
+  }
+
+  const installId = getInstallId();
+  const daysToFirstRule = computeDaysSinceInstall();
+  const visitorType = classifyInstall();
+
+  writeMarker({
+    installId,
+    promotedAt: new Date().toISOString(),
+    daysToFirstRule,
+    visitorType,
+    ...metadata,
+  });
+
+  trackEvent('activation_first_rule_promoted', {
+    daysToFirstRule,
+    visitorType,
+    ...metadata,
+  });
+  return true;
+}
+
+function resetForTesting() {
+  // Test-only helper. Removes the marker so a subsequent recordFirstRulePromotion
+  // call re-fires. Never used in production code paths.
+  try {
+    if (fs.existsSync(MARKER_PATH)) fs.unlinkSync(MARKER_PATH);
+  } catch {}
+}
+
+module.exports = {
+  recordFirstRulePromotion,
+  computeDaysSinceInstall,
+  readMarker,
+  writeMarker,
+  MARKER_PATH,
+  resetForTesting,
+};

package/scripts/feedback-loop.js

@@ -1398,7 +1398,20 @@ function captureFeedback(params) {
   if (feedbackEvent.signal === 'negative') {
     try {
       const autoPromote = require('./auto-promote-gates');
-      autoPromote.promote(FEEDBACK_LOG_PATH);
+      const promoteResult = autoPromote.promote(FEEDBACK_LOG_PATH);
+      // First-rule activation telemetry: anonymous ping the first time
+      // a prevention rule auto-promotes for this install. Idempotent —
+      // see scripts/activation-tracker.js. Critical for activation funnel
+      // analytics; no rule content, just install_id + days_to_first_rule.
+      if (promoteResult && Array.isArray(promoteResult.promotions) && promoteResult.promotions.length > 0) {
+        try {
+          const { recordFirstRulePromotion } = require('./activation-tracker');
+          recordFirstRulePromotion({
+            promotionCount: promoteResult.promotions.length,
+            totalGates: promoteResult.totalGates,
+          });
+        } catch { /* activation telemetry is non-critical */ }
+      }
     } catch { /* Gate promotion is non-critical */ }
   }
 

package/scripts/memory-scope-readiness.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+'use strict';
+
+const REQUIRED_SCOPE_FIELDS = ['entityId', 'projectId', 'processId', 'sessionId'];
+
+const FIELD_ALIASES = {
+  entityId: [
+    'entityId',
+    'userId',
+    'user_id',
+    'accountId',
+    'tenantId',
+    'actorId',
+    'scope.entityId',
+    'scope.userId',
+    'scope.user_id',
+    'metadata.entityId',
+    'metadata.userId',
+    'metadata.user_id',
+    'metadata.tenantId',
+    'richContext.entityId',
+    'richContext.userId',
+    'context.entityId',
+    'context.userId',
+  ],
+  projectId: [
+    'projectId',
+    'project_id',
+    'project',
+    'repoId',
+    'workspaceId',
+    'scope.projectId',
+    'scope.project_id',
+    'scope.project',
+    'metadata.projectId',
+    'metadata.project_id',
+    'metadata.project',
+    'metadata.repoId',
+    'metadata.workspaceId',
+    'richContext.projectId',
+    'richContext.project',
+    'context.projectId',
+    'context.project',
+  ],
+  processId: [
+    'processId',
+    'process_id',
+    'agentId',
+    'agent_id',
+    'role',
+    'scope.processId',
+    'scope.process_id',
+    'scope.agentId',
+    'scope.agent_id',
+    'metadata.processId',
+    'metadata.process_id',
+    'metadata.agentId',
+    'metadata.agent_id',
+    'metadata.role',
+    'richContext.processId',
+    'richContext.agentId',
+    'context.processId',
+    'context.agentId',
+  ],
+  sessionId: [
+    'sessionId',
+    'session_id',
+    'conversationId',
+    'threadId',
+    'runId',
+    'scope.sessionId',
+    'scope.session_id',
+    'metadata.sessionId',
+    'metadata.session_id',
+    'metadata.conversationId',
+    'metadata.threadId',
+    'metadata.runId',
+    'richContext.sessionId',
+    'richContext.conversationId',
+    'context.sessionId',
+    'context.conversationId',
+  ],
+};
+
+function readPath(value, dottedPath) {
+  const segments = dottedPath.split('.');
+  let current = value;
+  for (const segment of segments) {
+    if (!current || typeof current !== 'object' || !(segment in current)) {
+      return undefined;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+
+function normalizeId(value) {
+  if (value === null || value === undefined) return null;
+  const text = String(value).trim();
+  return text ? text : null;
+}
+
+function normalizeScope(input = {}) {
+  const scope = {};
+  for (const field of REQUIRED_SCOPE_FIELDS) {
+    let resolved = null;
+    for (const alias of FIELD_ALIASES[field]) {
+      resolved = normalizeId(readPath(input, alias));
+      if (resolved) break;
+    }
+    scope[field] = resolved;
+  }
+  return scope;
+}
+
+function missingScopeFields(scope) {
+  const normalized = normalizeScope(scope);
+  return REQUIRED_SCOPE_FIELDS.filter((field) => !normalized[field]);
+}
+
+function memoryScopeKey(scope) {
+  const normalized = normalizeScope(scope);
+  if (missingScopeFields(normalized).length > 0) return null;
+  return REQUIRED_SCOPE_FIELDS.map((field) => `${field}:${normalized[field]}`).join('|');
+}
+
+function isSharedMemory(record = {}) {
+  const visibility = normalizeId(
+    record.visibility
+    || record.scope?.visibility
+    || record.metadata?.visibility
+    || record.metadata?.scope
+  );
+  return record.shared === true
+    || record.scope?.shared === true
+    || record.metadata?.shared === true
+    || ['shared', 'global', 'public', 'team'].includes(String(visibility || '').toLowerCase());
+}
+
+function recordFingerprint(record = {}) {
+  const text = [
+    record.title,
+    record.content,
+    record.context,
+    record.whatWentWrong,
+    record.whatToChange,
+    record.whatWorked,
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase()
+    .replace(/\s+/g, ' ')
+    .trim();
+  return text || null;
+}
+
+function buildMemoryScopeReadinessReport(records = []) {
+  const byScope = new Map();
+  const byFingerprint = new Map();
+  const missingFieldsByRecord = [];
+  let sharedRecords = 0;
+  let readyRecords = 0;
+
+  records.forEach((record, index) => {
+    const scope = normalizeScope(record);
+    const missingFields = missingScopeFields(scope);
+    const shared = isSharedMemory(record);
+    const scopeKey = memoryScopeKey(scope);
+    const id = record.id || `record-${index}`;
+
+    if (shared) sharedRecords += 1;
+    if (missingFields.length === 0) readyRecords += 1;
+    else missingFieldsByRecord.push({ id, index, missingFields });
+
+    if (scopeKey) {
+      if (!byScope.has(scopeKey)) byScope.set(scopeKey, []);
+      byScope.get(scopeKey).push(id);
+    }
+
+    const fingerprint = recordFingerprint(record);
+    if (fingerprint && scopeKey && !shared) {
+      if (!byFingerprint.has(fingerprint)) byFingerprint.set(fingerprint, new Set());
+      byFingerprint.get(fingerprint).add(scopeKey);
+    }
+  });
+
+  const duplicateScopeKeys = [...byScope.entries()]
+    .filter(([, ids]) => ids.length > 1)
+    .map(([scopeKey, ids]) => ({ scopeKey, ids }));
+
+  const crossScopeDuplicates = [...byFingerprint.entries()]
+    .filter(([, scopeKeys]) => scopeKeys.size > 1)
+    .map(([fingerprint, scopeKeys]) => ({
+      fingerprint,
+      scopeKeys: [...scopeKeys].sort((a, b) => a.localeCompare(b)),
+    }));
+
+  const unscopedRecords = missingFieldsByRecord.length;
+  const riskLevel = unscopedRecords > 0 || crossScopeDuplicates.length > 0 ? 'high' : 'low';
+
+  return {
+    totalRecords: records.length,
+    readyRecords,
+    unscopedRecords,
+    sharedRecords,
+    isolatedScopeCount: byScope.size,
+    duplicateScopeKeys,
+    crossScopeDuplicates,
+    missingFieldsByRecord,
+    requiredFields: [...REQUIRED_SCOPE_FIELDS],
+    riskLevel,
+    ready: riskLevel === 'low',
+    recommendations: buildRecommendations({ unscopedRecords, crossScopeDuplicates }),
+  };
+}
+
+function buildRecommendations({ unscopedRecords, crossScopeDuplicates }) {
+  const recommendations = [];
+  if (unscopedRecords > 0) {
+    recommendations.push('Attach entityId, projectId, processId, and sessionId before writing memories.');
+  }
+  if (crossScopeDuplicates.length > 0) {
+    recommendations.push('Mark intentional shared memories explicitly; otherwise dedupe within the same scope only.');
+  }
+  if (recommendations.length === 0) {
+    recommendations.push('Scope posture is ready for multi-user and multi-session memory retrieval.');
+  }
+  return recommendations;
+}
+
+function selectRecordsForScope(records = [], requestedScope = {}, options = {}) {
+  const requested = normalizeScope(requestedScope);
+  const requestedKey = memoryScopeKey(requested);
+  if (!requestedKey) {
+    throw new Error(`requested scope missing fields: ${missingScopeFields(requested).join(', ')}`);
+  }
+
+  const includeShared = options.includeShared !== false;
+  const allowed = [];
+  const blocked = [];
+
+  for (const record of records) {
+    const shared = isSharedMemory(record);
+    const recordKey = memoryScopeKey(record);
+    if (recordKey === requestedKey || (includeShared && shared)) {
+      allowed.push(record);
+    } else {
+      blocked.push(record);
+    }
+  }
+
+  return {
+    requestedScope: requested,
+    requestedKey,
+    allowed,
+    blocked,
+  };
+}
+
+function buildMemoriStyleBenchmarkRecords() {
+  return [
+    {
+      id: 'alice-agent-a-session-1',
+      entityId: 'alice',
+      projectId: 'thumbgate',
+      processId: 'agent-a',
+      sessionId: 'session-1',
+      content: 'Use the paid sprint checklist before changing checkout code.',
+    },
+    {
+      id: 'bob-agent-a-session-1',
+      entityId: 'bob',
+      projectId: 'thumbgate',
+      processId: 'agent-a',
+      sessionId: 'session-1',
+      content: 'Bob private onboarding note.',
+    },
+    {
+      id: 'alice-agent-b-session-1',
+      entityId: 'alice',
+      projectId: 'thumbgate',
+      processId: 'agent-b',
+      sessionId: 'session-1',
+      content: 'Agent B should use docs-only mode.',
+    },
+    {
+      id: 'alice-agent-a-session-2',
+      entityId: 'alice',
+      projectId: 'thumbgate',
+      processId: 'agent-a',
+      sessionId: 'session-2',
+      content: 'Session 2 has a different migration plan.',
+    },
+    {
+      id: 'team-shared-checkout-rule',
+      entityId: 'alice',
+      projectId: 'thumbgate',
+      processId: 'agent-a',
+      sessionId: 'session-1',
+      visibility: 'shared',
+      content: 'Shared rule: checkout mutations require audit evidence.',
+    },
+  ];
+}
+
+module.exports = {
+  REQUIRED_SCOPE_FIELDS,
+  buildMemoriStyleBenchmarkRecords,
+  buildMemoryScopeReadinessReport,
+  isSharedMemory,
+  memoryScopeKey,
+  missingScopeFields,
+  normalizeScope,
+  selectRecordsForScope,
+};

package/scripts/plausible-server-events.js

@@ -0,0 +1,162 @@
+'use strict';
+
+/**
+ * Server-side Plausible custom event emitter.
+ *
+ * Why: CLAUDE.md anti-lying directive + the 2026-05-13 revenue-ROI
+ * critique flagged improvement #2 — "0/50 checkout sessions completed
+ * and you don't know why." The full /checkout/pro funnel already writes
+ * to local JSONL via appendBestEffortTelemetry(), but Plausible (where
+ * we actually look at funnel charts) only sees page-views, not the
+ * email-submitted / stripe-redirect-started transitions.
+ *
+ * This helper POSTs to the Plausible events API
+ *   https://plausible.io/api/event
+ * so the three funnel transitions show up alongside page-views in the
+ * same dashboard.
+ *
+ * Hard guarantees:
+ *  - Fire-and-forget. Never throws. Never blocks a 302 redirect.
+ *  - Disabled when THUMBGATE_PLAUSIBLE_DISABLE=1 (CI / tests / opt-out).
+ *  - 2-second hard timeout. The request socket is unref-ed so the
+ *    process can exit without waiting for the response.
+ *  - No PII. Only event name + UTM/CTA metadata (already public).
+ */
+
+const https = require('node:https');
+
+const DEFAULT_PLAUSIBLE_DOMAIN = 'thumbgate-production.up.railway.app';
+const PLAUSIBLE_ENDPOINT = 'https://plausible.io/api/event';
+const REQUEST_TIMEOUT_MS = 2_000;
+
+function isPlausibleDisabled() {
+  if (process.env.THUMBGATE_PLAUSIBLE_DISABLE === '1') return true;
+  if (process.env.DO_NOT_TRACK === '1') return true;
+  // NODE_ENV-based detection was tried and dropped: `node --test` does not
+  // set NODE_ENV automatically, so the check produced surprising behavior
+  // in test vs. production. Tests must opt out explicitly via the dedicated
+  // THUMBGATE_PLAUSIBLE_DISABLE flag.
+  return false;
+}
+
+function getPlausibleDomain() {
+  return process.env.THUMBGATE_PLAUSIBLE_DOMAIN || DEFAULT_PLAUSIBLE_DOMAIN;
+}
+
+/**
+ * Map raw telemetry fields onto Plausible "props" (string-only). Drop
+ * undefined values; cap each prop at 100 chars to satisfy Plausible's limits.
+ */
+function buildProps(metadata = {}) {
+  const props = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (value === undefined || value === null || value === '') continue;
+    const str = typeof value === 'string' ? value : String(value);
+    if (str.length === 0) continue;
+    props[key] = str.length > 100 ? `${str.slice(0, 97)}...` : str;
+  }
+  return props;
+}
+
+function buildPayload(eventName, options = {}) {
+  const domain = options.domain || getPlausibleDomain();
+  const pageUrl = options.pageUrl || `https://${domain}${options.page || '/'}`;
+  return {
+    name: eventName,
+    url: pageUrl,
+    domain,
+    referrer: options.referrer || undefined,
+    props: buildProps(options.props || {}),
+  };
+}
+
+/**
+ * Send a custom event to Plausible. Always returns a Promise that resolves —
+ * the caller can `void plausibleEvent(...)` and ignore. Resolved value is
+ * { sent, reason } so tests can assert the dispatch path was taken.
+ */
+function plausibleEvent(eventName, options = {}) {
+  if (isPlausibleDisabled()) {
+    return Promise.resolve({ sent: false, reason: 'disabled' });
+  }
+  if (typeof eventName !== 'string' || !eventName.trim()) {
+    return Promise.resolve({ sent: false, reason: 'invalid_event_name' });
+  }
+
+  const payload = JSON.stringify(buildPayload(eventName, options));
+  const url = new URL(PLAUSIBLE_ENDPOINT);
+  const userAgent =
+    options.userAgent ||
+    `thumbgate-server/${process.env.npm_package_version || 'unknown'} (+https://github.com/IgorGanapolsky/ThumbGate)`;
+  const xff = options.forwardedFor || options.remoteAddr;
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+
+    try {
+      const req = https.request(
+        {
+          hostname: url.hostname,
+          port: 443,
+          path: url.pathname,
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Content-Length': Buffer.byteLength(payload),
+            'User-Agent': userAgent,
+            ...(xff ? { 'X-Forwarded-For': xff } : {}),
+          },
+          timeout: REQUEST_TIMEOUT_MS,
+        },
+        (res) => {
+          // Plausible returns 202 on accept. Drain the response body so the
+          // socket can be released back to the pool, then resolve.
+          res.on('data', () => {});
+          res.on('end', () => done({ sent: true, statusCode: res.statusCode }));
+        }
+      );
+      req.on('error', () => done({ sent: false, reason: 'request_error' }));
+      req.on('timeout', () => {
+        req.destroy();
+        done({ sent: false, reason: 'timeout' });
+      });
+      req.on('socket', (s) => s.unref());
+      req.end(payload);
+    } catch {
+      done({ sent: false, reason: 'exception' });
+    }
+  });
+}
+
+/**
+ * Convenience: fire the three /checkout/pro funnel events by name without
+ * each caller having to know the canonical Plausible event labels.
+ * The labels are chosen to read cleanly in the Plausible UI's event list.
+ */
+const CHECKOUT_EVENT_NAMES = Object.freeze({
+  view: 'Checkout Pro Viewed',
+  emailSubmitted: 'Checkout Pro Email Submitted',
+  stripeRedirect: 'Checkout Pro Stripe Redirect Started',
+});
+
+function recordCheckoutFunnelEvent(stage, options = {}) {
+  const name = CHECKOUT_EVENT_NAMES[stage];
+  if (!name) return Promise.resolve({ sent: false, reason: 'unknown_stage' });
+  return plausibleEvent(name, options);
+}
+
+module.exports = {
+  plausibleEvent,
+  recordCheckoutFunnelEvent,
+  buildPayload,
+  buildProps,
+  isPlausibleDisabled,
+  getPlausibleDomain,
+  CHECKOUT_EVENT_NAMES,
+  PLAUSIBLE_ENDPOINT,
+};