thumbgate 1.28.4 → 1.29.2

package/scripts/schedule-manager.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+const { buildAgenticDataPipelineJobSpec } = require('./agentic-data-pipeline');
+const { ensureDir } = require('./fs-utils');
+
+const SCHEDULES_DIR = path.join(os.homedir(), '.thumbgate', 'schedules');
+const PLIST_PREFIX = 'com.thumbgate.schedule';
+
+
+function escapePlistString(value) {
+  return String(value || '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Parse a simple cron-like spec into LaunchAgent calendar intervals
+ * Supports: "daily 9:00", "weekly monday 8:30", "hourly", "every 6h"
+ */
+function parseCronSpec(spec) {
+  const s = spec.toLowerCase().trim();
+
+  if (s === 'hourly') {
+    return { Minute: 0 };
+  }
+
+  const everyHMatch = s.match(/^every\s+(\d+)\s*h/);
+  if (everyHMatch) {
+    return { Minute: 0 }; // LaunchAgent doesn't support "every Nh" natively, use hourly
+  }
+
+  const dailyMatch = s.match(/^daily\s+(\d{1,2}):(\d{2})$/);
+  if (dailyMatch) {
+    return { Hour: parseInt(dailyMatch[1]), Minute: parseInt(dailyMatch[2]) };
+  }
+
+  const weeklyMatch = s.match(/^weekly\s+(monday|tuesday|wednesday|thursday|friday|saturday|sunday)\s+(\d{1,2}):(\d{2})$/);
+  if (weeklyMatch) {
+    const dayMap = { sunday: 0, monday: 1, tuesday: 2, wednesday: 3, thursday: 4, friday: 5, saturday: 6 };
+    return {
+      Weekday: dayMap[weeklyMatch[1]],
+      Hour: parseInt(weeklyMatch[2]),
+      Minute: parseInt(weeklyMatch[3]),
+    };
+  }
+
+  // Fallback: try to parse as "HH:MM" (daily)
+  const timeMatch = s.match(/^(\d{1,2}):(\d{2})$/);
+  if (timeMatch) {
+    return { Hour: parseInt(timeMatch[1]), Minute: parseInt(timeMatch[2]) };
+  }
+
+  return null;
+}
+
+function generatePlist(schedule) {
+  const label = escapePlistString(`${PLIST_PREFIX}.${schedule.id}`);
+  const interval = schedule.calendarInterval;
+
+  let intervalXml = '<dict>\n';
+  for (const [key, value] of Object.entries(interval)) {
+    intervalXml += `        <key>${key}</key>\n        <integer>${value}</integer>\n`;
+  }
+  intervalXml += '    </dict>';
+
+  const logDir = escapePlistString(path.join(os.homedir(), '.thumbgate', 'logs'));
+  const workingDirectory = escapePlistString(schedule.workingDirectory || os.homedir());
+  const command = escapePlistString(schedule.command);
+  const homeDir = escapePlistString(os.homedir());
+  const escapedScheduleId = escapePlistString(schedule.id);
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${label}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${process.execPath}</string>
+        <string>-e</string>
+        <string>${command}</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${workingDirectory}</string>
+    <key>StartCalendarInterval</key>
+    ${intervalXml}
+    <key>StandardOutPath</key>
+    <string>${logDir}/schedule-${escapedScheduleId}.log</string>
+    <key>StandardErrorPath</key>
+    <string>${logDir}/schedule-${escapedScheduleId}-error.log</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+        <key>HOME</key>
+        <string>${homeDir}</string>
+    </dict>
+</dict>
+</plist>`;
+}
+
+function buildManagedScheduleCommand(params = {}) {
+  if (!params.jobFile) {
+    throw new Error('buildManagedScheduleCommand requires jobFile');
+  }
+
+  const runnerPath = path.join(__dirname, 'async-job-runner.js');
+  const jobFile = path.resolve(params.jobFile);
+  const autoResume = params.autoResume !== false;
+
+  return [
+    `const runner = require(${JSON.stringify(runnerPath)});`,
+    `const result = runner.runJobFromFile(${JSON.stringify(jobFile)}, ${JSON.stringify({ autoResume })});`,
+    'process.stdout.write(JSON.stringify(result, null, 2) + "\\n");',
+    'if (["failed", "cancelled"].includes(result.status)) process.exit(1);',
+  ].join(' ');
+}
+
+function buildAgenticDataPipelineSchedule(params = {}) {
+  const id = params.id || params.name || 'agentic-data-pipeline';
+  const jobFile = path.resolve(
+    params.jobFile || path.join(SCHEDULES_DIR, `${id}.job.json`)
+  );
+  const jobSpec = buildAgenticDataPipelineJobSpec({
+    jobId: id,
+    feedbackDir: params.feedbackDir,
+    outDir: params.outDir,
+    window: params.window,
+    liveBilling: params.liveBilling,
+    recordWorkflowRun: params.recordWorkflowRun,
+  });
+
+  return {
+    id,
+    jobFile,
+    jobSpec,
+    command: buildManagedScheduleCommand({
+      jobFile,
+      autoResume: params.autoResume !== false,
+    }),
+  };
+}
+
+function createSchedule(params) {
+  ensureDir(SCHEDULES_DIR);
+
+  const id = params.id || params.name || `sched_${Date.now()}`;
+  const calendarInterval = parseCronSpec(params.schedule);
+  if (!calendarInterval) {
+    return { success: false, error: `Cannot parse schedule: "${params.schedule}". Use formats like "daily 9:00", "weekly monday 8:30", "hourly"` };
+  }
+
+  const jobFile = params.jobFile ? path.resolve(params.jobFile) : null;
+  const command = params.command || (jobFile ? buildManagedScheduleCommand({
+    jobFile,
+    autoResume: params.autoResume !== false,
+  }) : null);
+
+  if (!command) {
+    return { success: false, error: 'Schedule requires command or jobFile' };
+  }
+
+  const schedule = {
+    id,
+    name: params.name || id,
+    description: params.description || '',
+    schedule: params.schedule,
+    command,
+    jobFile,
+    resumePolicy: jobFile ? (params.autoResume !== false ? 'auto_resume' : 'fresh_only') : null,
+    workingDirectory: params.workingDirectory || (jobFile ? path.dirname(jobFile) : process.cwd()),
+    calendarInterval,
+    createdAt: new Date().toISOString(),
+  };
+
+  // Save schedule metadata
+  const metaPath = path.join(SCHEDULES_DIR, `${id}.json`);
+  fs.writeFileSync(metaPath, JSON.stringify(schedule, null, 2), 'utf8');
+
+  // Generate and install LaunchAgent
+  if (process.platform === 'darwin') {
+    const plistContent = generatePlist(schedule);
+    const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${PLIST_PREFIX}.${id}.plist`);
+    const logDir = path.join(os.homedir(), '.thumbgate', 'logs');
+    if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
+    fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+
+    fs.writeFileSync(plistPath, plistContent, 'utf8');
+    try {
+      execSync(`launchctl unload "${plistPath}" 2>/dev/null`, { stdio: 'pipe' });
+    } catch { /* not loaded */ }
+    try {
+      execSync(`launchctl load "${plistPath}"`, { stdio: 'pipe' });
+    } catch (e) {
+      return { success: false, error: `Failed to load LaunchAgent: ${e.message}`, schedule };
+    }
+
+    return { success: true, schedule, plistPath, message: `Schedule "${id}" created and loaded` };
+  }
+
+  // Linux keeps the schedule metadata so operators can install it via user crontab tooling.
+  return { success: true, schedule, message: `Schedule "${id}" saved for Linux crontab installation` };
+}
+
+function listSchedules() {
+  ensureDir(SCHEDULES_DIR);
+  const files = fs.readdirSync(SCHEDULES_DIR).filter(f => f.endsWith('.json'));
+  return files.map(f => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(SCHEDULES_DIR, f), 'utf8'));
+    } catch {
+      return { id: f.replace('.json', ''), error: 'corrupt' };
+    }
+  });
+}
+
+function deleteSchedule(id) {
+  const metaPath = path.join(SCHEDULES_DIR, `${id}.json`);
+  const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${PLIST_PREFIX}.${id}.plist`);
+
+  try {
+    execSync(`launchctl unload "${plistPath}" 2>/dev/null`, { stdio: 'pipe' });
+  } catch { /* not loaded */ }
+
+  if (fs.existsSync(plistPath)) fs.unlinkSync(plistPath);
+  if (fs.existsSync(metaPath)) fs.unlinkSync(metaPath);
+
+  return { success: true, message: `Schedule "${id}" deleted` };
+}
+
+module.exports = {
+  createSchedule,
+  listSchedules,
+  deleteSchedule,
+  escapePlistString,
+  generatePlist,
+  parseCronSpec,
+  buildManagedScheduleCommand,
+  buildAgenticDataPipelineSchedule,
+};

package/scripts/seo-gsd.js

@@ -2,6 +2,10 @@
 
 const fs = require('fs');
 const path = require('path');
+const {
+  buildDiagnosticBuyerUrl,
+  buildSprintBuyerUrl,
+} = require('./buyer-paths');
 
 const ROOT = path.join(__dirname, '..');
 const DEFAULT_OUTPUT_DIR = path.join(ROOT, 'docs', 'seo-gsd');
@@ -12,8 +16,8 @@ const PRODUCT = {
   repoUrl: 'https://github.com/IgorGanapolsky/ThumbGate',
   homepageUrl: 'https://thumbgate.ai',
   verificationUrl: 'https://github.com/IgorGanapolsky/ThumbGate/blob/main/docs/VERIFICATION_EVIDENCE.md',
-  sprintDiagnosticPaymentUrl: 'https://buy.stripe.com/00w14neyUcXA5pL5e33sI0e',
-  workflowSprintPaymentUrl: 'https://buy.stripe.com/fZu9AT76saPsg4pbCr3sI0f',
+  sprintDiagnosticPaymentUrl: buildDiagnosticBuyerUrl({ source: 'seo_gsd' }),
+  workflowSprintPaymentUrl: buildSprintBuyerUrl({ source: 'seo_gsd' }),
   compatibility: ['Claude Code', 'Cursor', 'Codex', 'Gemini', 'Amp', 'OpenCode'],
   proofPoints: [
     'thumbs-up/down feedback loop',
@@ -562,7 +566,7 @@ const PRETOOLUSE_HOOK_GUIDE_SPEC = Object.freeze({
     ],
     [
       'Does this run locally or call a cloud service?',
-      'Local-first. The PreToolUse decision happens in the hook process on your machine in milliseconds — no network round-trip, no cloud dependency, no data leaving the laptop. Pro adds personal recall, exports, dashboard proof, and managed adapter coverage. Enterprise adds hosted sharing for teams that want to share rules across seats.',
+      'Local-first. The PreToolUse decision happens in the hook process on your machine in milliseconds — no network round-trip, no cloud dependency, no data leaving the laptop. Pro adds personal recall, exports, dashboard proof, and managed adapter coverage. Enterprise service work is qualified after intake; hosted rule sharing and a hosted org dashboard are not generally available.',
     ],
   ],
   relatedPaths: ['/guides/mcp-tool-governance', '/guides/ai-agent-pre-action-approval-gates', '/guides/ai-coding-agent-zero-trust'],
@@ -1972,7 +1976,7 @@ const PAGE_BLUEPRINTS = [
     faq: [
       {
         question: 'Why pay $19/mo for ThumbGate Pro when disler hooks are free?',
-        answer: 'Free disler hooks are static patterns you maintain per machine — re-copying them when they change, debugging false positives alone, and re-applying them in every new project. ThumbGate Pro adds the learning loop (repeated thumbs-downs → cross-session prevention rule), the personal dashboard, lesson recall/search, DPO export, and adapter maintenance across the weekly breaking-change cycle of Claude Code, Cursor, and Cline. Free disler is the right answer if you only ever work in one project on one machine and never want to learn from past mistakes. Pro is the right answer when those assumptions stop holding; Enterprise adds shared hosted lessons across seats.',
+        answer: 'Free disler hooks are static patterns you maintain per machine — re-copying them when they change, debugging false positives alone, and re-applying them in every new project. ThumbGate Pro adds the learning loop (repeated thumbs-downs → cross-session prevention rule), the personal dashboard, lesson recall/search, DPO export, and adapter maintenance across the weekly breaking-change cycle of Claude Code, Cursor, and Cline. Free disler is the right answer if you only ever work in one project on one machine and never want to learn from past mistakes. Pro is the right answer when those assumptions stop holding; Enterprise service work is qualified after intake, and shared hosted lessons are not generally available.',
       },
       {
         question: 'Is ThumbGate just a packaged version of disler/claude-code-hooks-mastery?',

package/scripts/stripe-credentials.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const DEFAULT_SECRET_PATHS = Object.freeze([
+  path.join(os.homedir(), '.thumbgate_secrets', 'stripe_live_key.txt'),
+  path.join(os.homedir(), '.resume_secrets', 'stripe_live_key.txt'),
+]);
+
+function readSecretFile(filePath) {
+  try {
+    if (!filePath || !fs.existsSync(filePath)) return null;
+    return fs.readFileSync(filePath, 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveStripeSecretKey({ env = process.env, secretPaths = DEFAULT_SECRET_PATHS } = {}) {
+  if (String(env.STRIPE_SECRET_KEY || '').trim()) {
+    return { secretKey: env.STRIPE_SECRET_KEY.trim(), source: 'env' };
+  }
+  for (const filePath of secretPaths) {
+    const secretKey = readSecretFile(filePath);
+    if (secretKey) return { secretKey, source: 'managed_file' };
+  }
+  return { secretKey: null, source: null };
+}
+
+module.exports = {
+  DEFAULT_SECRET_PATHS,
+  readSecretFile,
+  resolveStripeSecretKey,
+};

package/scripts/stripe-revenue-catalog-audit.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  DEFAULT_SECRET_PATHS,
+  resolveStripeSecretKey,
+} = require('./stripe-credentials');
+const {
+  STRIPE_REVENUE_CATALOG_VERSION,
+  DEFAULT_STRIPE_REVENUE_CATALOG,
+  validateStripeRevenueCatalog,
+  matchStripeRevenueCatalogPrice,
+} = require('./stripe-revenue-catalog');
+
+const SCHEMA_VERSION = 1;
+const DEFAULT_STRIPE_PUBLIC_PAYMENT_RAILS = Object.freeze([
+  Object.freeze({
+    offerId: 'pro_monthly',
+    paymentLinkId: 'plink_1Tpu8xGGBpd520QY7VoUniLI',
+    url: 'https://buy.stripe.com/8x2dR91M84r4cSd9uj3sI3f',
+    priceId: 'price_1THQY7GGBpd520QYHoS7RG0J',
+    expectedActive: true,
+  }),
+  Object.freeze({
+    offerId: 'workflow_hardening_diagnostic',
+    paymentLinkId: 'plink_1TsO6lGGBpd520QYsFToXuRC',
+    url: 'https://buy.stripe.com/9B69ATbmI4r4aK5eOD3sI3k',
+    priceId: 'price_1TsO6kGGBpd520QYbbEgThb3',
+    expectedActive: true,
+  }),
+]);
+
+function parseArgs(argv = []) {
+  const options = { json: argv.includes('--json') };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--json') continue;
+    if (arg === '--out' && argv[index + 1]) {
+      options.out = argv[index + 1];
+      index += 1;
+    }
+  }
+  return options;
+}
+
+function loadStripe(requireFn = require) {
+  return requireFn('stripe');
+}
+
+function canonicalPaymentLinkUrl(value) {
+  try {
+    const url = new URL(String(value || '').trim());
+    if (url.protocol !== 'https:' || url.hostname !== 'buy.stripe.com'
+      || url.username || url.href.includes('@') || url.port) return null;
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return null;
+  }
+}
+
+function validatePublicPaymentRails(rails = DEFAULT_STRIPE_PUBLIC_PAYMENT_RAILS, catalog = DEFAULT_STRIPE_REVENUE_CATALOG) {
+  if (!Array.isArray(rails) || rails.length === 0) {
+    return { ok: false, gap: 'Stripe public payment rails must contain at least one reviewed link.' };
+  }
+  const priceIds = new Set(catalog.map((entry) => entry.priceId));
+  const offerIds = new Set(catalog.map((entry) => entry.offerId));
+  const seenLinks = new Set();
+  for (const rail of rails) {
+    const linkId = String(rail?.paymentLinkId || '').trim();
+    const priceId = String(rail?.priceId || '').trim();
+    const offerId = String(rail?.offerId || '').trim();
+    if (!/^plink_[A-Za-z0-9_]+$/.test(linkId)
+      || !canonicalPaymentLinkUrl(rail?.url)
+      || !priceIds.has(priceId)
+      || !offerIds.has(offerId)
+      || typeof rail?.expectedActive !== 'boolean') {
+      return { ok: false, gap: `Invalid Stripe public payment rail for ${offerId || 'unknown offer'}.` };
+    }
+    const catalogEntry = catalog.find((entry) => entry.offerId === offerId);
+    if (!catalogEntry || catalogEntry.priceId !== priceId) {
+      return { ok: false, gap: `Stripe public payment rail ${linkId} does not bind to its catalog offer.` };
+    }
+    if (seenLinks.has(linkId)) {
+      return { ok: false, gap: `Duplicate Stripe public payment link: ${linkId}.` };
+    }
+    seenLinks.add(linkId);
+  }
+  return { ok: true, gap: null };
+}
+
+function emptySummary(catalog = [], rails = []) {
+  return {
+    expectedOfferCount: catalog.length,
+    verifiedOfferCount: 0,
+    priceDriftCount: catalog.length,
+    expectedPublicPaymentRailCount: rails.length,
+    verifiedPublicPaymentRailCount: 0,
+    paymentRailDriftCount: rails.length,
+  };
+}
+
+async function buildStripeRevenueCatalogAudit({
+  stripe,
+  catalog = DEFAULT_STRIPE_REVENUE_CATALOG,
+  publicPaymentRails = DEFAULT_STRIPE_PUBLIC_PAYMENT_RAILS,
+  generatedAt = new Date().toISOString(),
+  requireLiveMode = true,
+} = {}) {
+  const catalogValidation = validateStripeRevenueCatalog(catalog);
+  const railValidation = catalogValidation.ok
+    ? validatePublicPaymentRails(publicPaymentRails, catalog)
+    : { ok: false, gap: 'Stripe public payment rails cannot be audited against an invalid catalog.' };
+  const gaps = [catalogValidation.gap, railValidation.gap].filter(Boolean);
+  if (!stripe?.prices?.retrieve || !stripe?.paymentLinks?.retrieve) {
+    gaps.push('Stripe client does not expose read-only price and Payment Link retrieval endpoints.');
+  }
+  if (gaps.length) {
+    return {
+      schemaVersion: SCHEMA_VERSION,
+      catalogVersion: STRIPE_REVENUE_CATALOG_VERSION,
+      generatedAt: new Date(generatedAt).toISOString(),
+      verified: false,
+      gaps,
+      summary: emptySummary(catalog, publicPaymentRails),
+      offers: [],
+      publicPaymentRails: [],
+    };
+  }
+
+  const offers = await Promise.all(catalog.map(async (entry) => {
+    let price;
+    try {
+      price = await stripe.prices.retrieve(entry.priceId, { expand: ['product'] });
+    } catch {
+      return {
+        offerId: entry.offerId,
+        priceId: entry.priceId,
+        verified: false,
+        gap: 'provider_price_retrieval_failed',
+      };
+    }
+    const match = matchStripeRevenueCatalogPrice(price, catalog);
+    const activeMatches = price.active === entry.expectedPriceActive;
+    const productActiveMatches = typeof price.product === 'object'
+      && price.product?.active === entry.expectedProductActive;
+    const liveModeMatches = !requireLiveMode || price.livemode === true;
+    return {
+      offerId: entry.offerId,
+      priceId: entry.priceId,
+      productId: entry.productId,
+      status: entry.status,
+      expectedPriceActive: entry.expectedPriceActive,
+      observedPriceActive: price.active === true,
+      expectedProductActive: entry.expectedProductActive,
+      observedProductActive: typeof price.product === 'object' ? price.product?.active === true : null,
+      liveMode: price.livemode === true,
+      exactTermsMatch: match.matched,
+      verified: match.matched && activeMatches && productActiveMatches && liveModeMatches,
+      gap: !match.matched
+        ? match.reason
+        : !activeMatches
+          ? 'price_active_state_mismatch'
+          : !productActiveMatches
+            ? 'product_active_state_mismatch'
+          : !liveModeMatches ? 'price_not_live_mode' : null,
+    };
+  }));
+
+  const publicRails = await Promise.all(publicPaymentRails.map(async (expected) => {
+    let link;
+    try {
+      link = await stripe.paymentLinks.retrieve(expected.paymentLinkId, {
+        expand: ['line_items.data.price.product'],
+      });
+    } catch {
+      return {
+        offerId: expected.offerId,
+        paymentLinkId: expected.paymentLinkId,
+        verified: false,
+        gap: 'provider_payment_link_retrieval_failed',
+      };
+    }
+    const lineItems = Array.isArray(link?.line_items?.data) ? link.line_items.data : [];
+    const priceMatches = lineItems.map((item) => matchStripeRevenueCatalogPrice(item?.price, catalog));
+    const exactSingleOffer = priceMatches.length === 1
+      && priceMatches[0].matched
+      && priceMatches[0].offerId === expected.offerId
+      && priceMatches[0].observed?.priceId === expected.priceId;
+    const urlMatches = canonicalPaymentLinkUrl(link?.url) === canonicalPaymentLinkUrl(expected.url);
+    const activeMatches = link?.active === expected.expectedActive;
+    const liveModeMatches = !requireLiveMode || link?.livemode === true;
+    const idMatches = link?.id === expected.paymentLinkId;
+    const verified = idMatches && urlMatches && activeMatches && liveModeMatches && exactSingleOffer;
+    return {
+      offerId: expected.offerId,
+      paymentLinkId: expected.paymentLinkId,
+      priceId: expected.priceId,
+      expectedActive: expected.expectedActive,
+      observedActive: link?.active === true,
+      liveMode: link?.livemode === true,
+      exactUrlMatch: urlMatches,
+      exactSingleOffer,
+      verified,
+      gap: !idMatches
+        ? 'payment_link_id_mismatch'
+        : !urlMatches
+          ? 'payment_link_url_mismatch'
+          : !activeMatches
+            ? 'payment_link_active_state_mismatch'
+            : !liveModeMatches
+              ? 'payment_link_not_live_mode'
+              : !exactSingleOffer ? 'payment_link_offer_mismatch' : null,
+    };
+  }));
+
+  for (const offer of offers) {
+    if (!offer.verified) gaps.push(`offer:${offer.offerId}:${offer.gap}`);
+  }
+  for (const rail of publicRails) {
+    if (!rail.verified) gaps.push(`payment_rail:${rail.offerId}:${rail.gap}`);
+  }
+  const verifiedOfferCount = offers.filter((offer) => offer.verified).length;
+  const verifiedPublicPaymentRailCount = publicRails.filter((rail) => rail.verified).length;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    catalogVersion: STRIPE_REVENUE_CATALOG_VERSION,
+    generatedAt: new Date(generatedAt).toISOString(),
+    verified: gaps.length === 0,
+    gaps,
+    summary: {
+      expectedOfferCount: catalog.length,
+      verifiedOfferCount,
+      priceDriftCount: catalog.length - verifiedOfferCount,
+      expectedPublicPaymentRailCount: publicPaymentRails.length,
+      verifiedPublicPaymentRailCount,
+      paymentRailDriftCount: publicPaymentRails.length - verifiedPublicPaymentRailCount,
+    },
+    offers,
+    publicPaymentRails: publicRails,
+  };
+}
+
+async function runAudit({
+  stripeClient = null,
+  stripeFactory = null,
+  secretKey = undefined,
+  env = process.env,
+  secretPaths = DEFAULT_SECRET_PATHS,
+  catalog = DEFAULT_STRIPE_REVENUE_CATALOG,
+  publicPaymentRails = DEFAULT_STRIPE_PUBLIC_PAYMENT_RAILS,
+  generatedAt = new Date().toISOString(),
+  requireLiveMode = true,
+} = {}) {
+  let credentialSource = stripeClient ? 'injected_client' : null;
+  if (!stripeClient && secretKey === undefined) {
+    const resolved = resolveStripeSecretKey({ env, secretPaths });
+    secretKey = resolved.secretKey;
+    credentialSource = resolved.source;
+  } else if (!stripeClient && secretKey) {
+    credentialSource = 'injected_secret';
+  }
+  if (!stripeClient && !secretKey) {
+    return {
+      configured: false,
+      credentialSource: null,
+      schemaVersion: SCHEMA_VERSION,
+      catalogVersion: STRIPE_REVENUE_CATALOG_VERSION,
+      generatedAt: new Date(generatedAt).toISOString(),
+      verified: false,
+      gaps: ['No Stripe credential found in STRIPE_SECRET_KEY or managed local key files.'],
+      summary: emptySummary(catalog, publicPaymentRails),
+      offers: [],
+      publicPaymentRails: [],
+    };
+  }
+  let stripe = stripeClient;
+  if (!stripe) {
+    try {
+      const factory = stripeFactory || loadStripe();
+      stripe = factory(secretKey);
+    } catch {
+      return {
+        configured: false,
+        credentialSource,
+        schemaVersion: SCHEMA_VERSION,
+        catalogVersion: STRIPE_REVENUE_CATALOG_VERSION,
+        generatedAt: new Date(generatedAt).toISOString(),
+        verified: false,
+        gaps: ['Stripe SDK could not be initialized.'],
+        summary: emptySummary(catalog, publicPaymentRails),
+        offers: [],
+        publicPaymentRails: [],
+      };
+    }
+  }
+  const report = await buildStripeRevenueCatalogAudit({
+    stripe,
+    catalog,
+    publicPaymentRails,
+    generatedAt,
+    requireLiveMode,
+  });
+  return { configured: true, credentialSource, ...report };
+}
+
+function renderMarkdown(report) {
+  const lines = [
+    '# Stripe Revenue Catalog Audit',
+    '',
+    `Generated: ${report.generatedAt}`,
+    `Status: ${report.verified ? 'VERIFIED' : 'UNVERIFIED'}`,
+    `Catalog version: ${report.catalogVersion}`,
+    `Exact live offers: ${report.summary.verifiedOfferCount}/${report.summary.expectedOfferCount}`,
+    `Exact public payment rails: ${report.summary.verifiedPublicPaymentRailCount}/${report.summary.expectedPublicPaymentRailCount}`,
+  ];
+  if (report.gaps.length) {
+    lines.push('', '## Evidence gaps', '');
+    for (const gap of report.gaps) lines.push(`- ${gap}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function writeJson(filePath, value) {
+  if (!filePath) return null;
+  const resolved = path.resolve(filePath);
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  fs.writeFileSync(resolved, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  return resolved;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  const report = await runAudit();
+  const outputPath = writeJson(options.out, report);
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify({ ...report, outputPath }, null, 2)}\n`);
+  } else {
+    process.stdout.write(renderMarkdown(report));
+  }
+  if (!report.verified) process.exitCode = 2;
+}
+
+if (path.resolve(process.argv[1] || '') === path.resolve(__filename)) {
+  main().catch(() => {
+    process.stderr.write('stripe-revenue-catalog-audit FAILED\n');
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  DEFAULT_STRIPE_PUBLIC_PAYMENT_RAILS,
+  parseArgs,
+  canonicalPaymentLinkUrl,
+  validatePublicPaymentRails,
+  buildStripeRevenueCatalogAudit,
+  runAudit,
+  renderMarkdown,
+  writeJson,
+};