thumbgate 1.7.0 → 1.9.0

package/scripts/mailer/resend-mailer.js

@@ -15,12 +15,14 @@
  *    address, and a functional unsubscribe method.
  */
 
+const dns = require('node:dns').promises;
+
 const PRODUCT_NAME = 'ThumbGate Pro';
 const DASHBOARD_URL = 'https://thumbgate-production.up.railway.app/dashboard';
-const SUPPORT_EMAIL = 'hello@thumbgate.app';
+const DEFAULT_CONTACT_EMAIL = 'igor.ganapolsky@gmail.com';
 const DEFAULT_FROM = 'onboarding@resend.dev';
-const DEFAULT_REPLY_TO = 'hello@thumbgate.app';
-const DEFAULT_UNSUBSCRIBE_EMAIL = 'unsubscribe@thumbgate.app';
+const DEFAULT_REPLY_TO = DEFAULT_CONTACT_EMAIL;
+const DEFAULT_UNSUBSCRIBE_EMAIL = DEFAULT_CONTACT_EMAIL;
 const DEFAULT_BUSINESS_NAME = 'Max Smith KDP LLC';
 // CAN-SPAM requires a physical mailing address. Override via THUMBGATE_BUSINESS_ADDRESS.
 const DEFAULT_BUSINESS_ADDRESS = '2261 Market Street #4242, San Francisco, CA 94114';
@@ -28,9 +30,23 @@ const DEFAULT_BUSINESS_ADDRESS = '2261 Market Street #4242, San Francisco, CA 94
 const BRAND_MARK_URL = 'https://thumbgate-production.up.railway.app/thumbgate-icon.png';
 const RESEND_ENDPOINT = 'https://api.resend.com/emails';
 const TRIAL_LENGTH_DAYS = 7;
+const SENDER_DNS_CACHE_MS = 10 * 60 * 1000;
+// Bounded to RFC 5321 limits (local-part ≤ 64, domain ≤ 255) to prevent
+// super-linear backtracking on malformed input (Sonar javascript:S5852).
+const ANGLE_EMAIL_RE = /<([^<>@\s]{1,64}@[^<>@\s]{1,255})>/;
+const BARE_EMAIL_RE = /([^\s<>@]{1,64}@[^\s<>@]{1,255})/;
+const DKIM_PUBLIC_KEY_RE = /^p=/i;
+const AMAZON_SES_MX_RE = /feedback-smtp\..*amazonaws\.com\.?$/i;
+const AMAZON_SES_SPF_RE = /include:amazonses\.com/i;
+const TRAILING_EMAIL_DOMAIN_PUNCTUATION = new Set(['>', ')', ',', '.', ';']);
+const senderDnsCache = new Map();
 
 function getApiKey() {
-  return process.env.RESEND_API_KEY || '';
+  // Accept both `RESEND_API_KEY` (Railway default, matches provider docs) and
+  // the `THUMBGATE_`-prefixed variant that `scripts/billing.js` already honors.
+  // Keeping the two readers in sync prevents a silent "skipped: no_api_key"
+  // regression if an operator sets only the prefixed name.
+  return process.env.RESEND_API_KEY || process.env.THUMBGATE_RESEND_API_KEY || '';
 }
 
 function getFromAddress() {
@@ -41,6 +57,10 @@ function getReplyTo() {
   return process.env.THUMBGATE_TRIAL_EMAIL_REPLY_TO || DEFAULT_REPLY_TO;
 }
 
+function getSupportEmail() {
+  return process.env.THUMBGATE_SUPPORT_EMAIL || getReplyTo();
+}
+
 function getUnsubscribeEmail() {
   return process.env.THUMBGATE_UNSUBSCRIBE_EMAIL || DEFAULT_UNSUBSCRIBE_EMAIL;
 }
@@ -57,32 +77,193 @@ function isNonEmptyString(value) {
   return typeof value === 'string' && value.trim().length > 0;
 }
 
-/**
- * Low-level send. Posts to the Resend API or no-ops when RESEND_API_KEY is
- * missing. Never throws on network errors; returns a structured result instead.
- */
-async function sendEmail({ to, subject, html, text, from, replyTo, fetchImpl } = {}) {
+function isTrueEnv(value) {
+  return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+function extractEmailAddress(value) {
+  const text = String(value || '').trim();
+  const angleMatch = ANGLE_EMAIL_RE.exec(text);
+  if (angleMatch) return angleMatch[1];
+  const bareMatch = BARE_EMAIL_RE.exec(text);
+  return bareMatch ? bareMatch[1] : '';
+}
+
+function getEmailDomain(value) {
+  const email = extractEmailAddress(value);
+  const at = email.lastIndexOf('@');
+  if (at === -1) return '';
+  let domain = email.slice(at + 1).trim();
+  while (domain && TRAILING_EMAIL_DOMAIN_PUNCTUATION.has(domain.at(-1))) {
+    domain = domain.slice(0, -1);
+  }
+  return domain.toLowerCase();
+}
+
+function splitCsv(value) {
+  return String(value || '')
+    .split(',')
+    .map((part) => part.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function getVerifiedSenderDomains() {
+  return new Set(splitCsv(process.env.THUMBGATE_VERIFIED_SENDER_DOMAINS));
+}
+
+function flattenTxt(records) {
+  return (records || []).map((chunks) => Array.isArray(chunks) ? chunks.join('') : String(chunks));
+}
+
+function getCachedSenderDnsReadiness(cacheKey) {
+  if (!cacheKey) return null;
+  const cached = senderDnsCache.get(cacheKey);
+  return cached && cached.expiresAt > Date.now() ? cached.ready : null;
+}
+
+function setCachedSenderDnsReadiness(cacheKey, ready) {
+  if (cacheKey) senderDnsCache.set(cacheKey, { ready, expiresAt: Date.now() + SENDER_DNS_CACHE_MS });
+  return ready;
+}
+
+async function readResendDnsRecords(domain, resolver) {
+  try {
+    const [dkimRecords, mxRecords, spfRecords] = await Promise.all([
+      resolver.resolveTxt(`resend._domainkey.${domain}`),
+      resolver.resolveMx(`send.${domain}`),
+      resolver.resolveTxt(`send.${domain}`),
+    ]);
+    return { dkimRecords, mxRecords, spfRecords, errorCode: null };
+  } catch (error) {
+    return {
+      dkimRecords: [],
+      mxRecords: [],
+      spfRecords: [],
+      errorCode: error && error.code ? error.code : 'dns_lookup_failed',
+    };
+  }
+}
+
+function recordsHaveResendDns({ dkimRecords, mxRecords, spfRecords }) {
+  const dkim = flattenTxt(dkimRecords);
+  const spf = flattenTxt(spfRecords);
+  return dkim.some((record) => DKIM_PUBLIC_KEY_RE.exec(record.trim()) !== null) &&
+    (mxRecords || []).some((record) => AMAZON_SES_MX_RE.exec(record.exchange || '') !== null) &&
+    spf.some((record) => AMAZON_SES_SPF_RE.exec(record) !== null);
+}
+
+async function hasResendSenderDns(domain, { dnsResolver } = {}) {
+  if (!domain || domain === 'resend.dev') return true;
+  if (isTrueEnv(process.env.THUMBGATE_ALLOW_UNVERIFIED_SENDER)) return true;
+  if (getVerifiedSenderDomains().has(domain)) return true;
+
+  const cacheKey = dnsResolver ? null : domain;
+  const cached = getCachedSenderDnsReadiness(cacheKey);
+  if (cached !== null) return cached;
+
+  const records = await readResendDnsRecords(domain, dnsResolver || dns);
+  return setCachedSenderDnsReadiness(cacheKey, !records.errorCode && recordsHaveResendDns(records));
+}
+
+async function resolveSenderAddress(requestedFrom, { dnsResolver } = {}) {
+  const from = requestedFrom || getFromAddress();
+  const domain = getEmailDomain(from);
+  const ready = await hasResendSenderDns(domain, { dnsResolver });
+  if (ready) return { from, senderFallback: null };
+
+  return {
+    from: DEFAULT_FROM,
+    senderFallback: {
+      requestedFrom: from,
+      fallbackFrom: DEFAULT_FROM,
+      domain,
+      reason: 'resend_dns_not_ready',
+    },
+  };
+}
+
+function validateSendEmailInput({ to, subject, html, text }) {
   if (!isNonEmptyString(to)) throw new Error('sendEmail: `to` is required');
   if (!isNonEmptyString(subject)) throw new Error('sendEmail: `subject` is required');
   if (!isNonEmptyString(html) && !isNonEmptyString(text)) {
     throw new Error('sendEmail: at least one of `html` or `text` is required');
   }
+}
 
-  const apiKey = getApiKey();
-  if (!apiKey) {
-    // eslint-disable-next-line no-console
-    console.warn('[mailer] RESEND_API_KEY not set — skipping send to', to);
-    return { sent: false, reason: 'no_api_key' };
-  }
+function warnSenderFallback(senderFallback) {
+  if (!senderFallback) return;
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[mailer] Sender domain ${senderFallback.domain || '(unknown)'} is missing Resend DNS; ` +
+    `falling back to ${senderFallback.fallbackFrom}`,
+  );
+}
 
+function buildEmailPayload({ to, subject, html, text, replyTo, sender }) {
   const payload = {
-    from: from || getFromAddress(),
+    from: sender.from,
     to: Array.isArray(to) ? to : [to],
     subject,
     reply_to: replyTo || getReplyTo(),
   };
   if (isNonEmptyString(html)) payload.html = html;
   if (isNonEmptyString(text)) payload.text = text;
+  return payload;
+}
+
+function parseJsonOrNull(bodyText) {
+  if (!bodyText) return null;
+  try {
+    return JSON.parse(bodyText);
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+    return null;
+  }
+}
+
+async function postResendEmail({ fetcher, apiKey, payload }) {
+  const res = await fetcher(RESEND_ENDPOINT, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify(payload),
+  });
+  const bodyText = typeof res.text === 'function' ? await res.text() : '';
+  return { res, bodyText, bodyJson: parseJsonOrNull(bodyText) };
+}
+
+function formatSendFailure(error) {
+  return error && error.message ? error.message : String(error);
+}
+
+function buildSendSuccess({ bodyJson, status, senderFallback }) {
+  return {
+    sent: true,
+    id: bodyJson?.id || null,
+    status,
+    ...(senderFallback ? { senderFallback } : {}),
+  };
+}
+
+/**
+ * Low-level send. Posts to the Resend API or no-ops when RESEND_API_KEY is
+ * missing. Never throws on network errors; returns a structured result instead.
+ */
+async function sendEmail({ to, subject, html, text, from, replyTo, fetchImpl, dnsResolver } = {}) {
+  validateSendEmailInput({ to, subject, html, text });
+
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    // eslint-disable-next-line no-console
+    console.warn('[mailer] RESEND_API_KEY not set — skipping send to', to);
+    return { sent: false, reason: 'no_api_key' };
+  }
+
+  const sender = await resolveSenderAddress(from || getFromAddress(), { dnsResolver });
+  warnSenderFallback(sender.senderFallback);
+  const payload = buildEmailPayload({ to, subject, html, text, replyTo, sender });
 
   const fetcher = fetchImpl || globalThis.fetch;
   if (typeof fetcher !== 'function') {
@@ -92,32 +273,17 @@ async function sendEmail({ to, subject, html, text, from, replyTo, fetchImpl } =
   }
 
   try {
-    const res = await fetcher(RESEND_ENDPOINT, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${apiKey}`,
-      },
-      body: JSON.stringify(payload),
-    });
-
-    const bodyText = typeof res.text === 'function' ? await res.text() : '';
-    let bodyJson = null;
-    if (bodyText) {
-      try { bodyJson = JSON.parse(bodyText); } catch (_) { /* leave as text */ }
-    }
-
+    const { res, bodyText, bodyJson } = await postResendEmail({ fetcher, apiKey, payload });
     if (!res.ok) {
       // eslint-disable-next-line no-console
       console.warn(`[mailer] Resend returned ${res.status}:`, bodyText);
       return { sent: false, reason: 'api_error', status: res.status, body: bodyJson || bodyText };
     }
-
-    return { sent: true, id: bodyJson && bodyJson.id ? bodyJson.id : null, status: res.status };
+    return buildSendSuccess({ bodyJson, status: res.status, senderFallback: sender.senderFallback });
   } catch (err) {
     // eslint-disable-next-line no-console
-    console.warn('[mailer] send failed:', err && err.message ? err.message : err);
-    return { sent: false, reason: 'exception', error: err && err.message ? err.message : String(err) };
+    console.warn('[mailer] send failed:', formatSendFailure(err));
+    return { sent: false, reason: 'exception', error: formatSendFailure(err) };
   }
 }
 
@@ -173,6 +339,7 @@ function renderTrialWelcomeBodies({ licenseKey, customerId, customerName, trialE
   const exampleFeedback =
     'thumbs down: the answer skipped exact files and tests; next time include paths, commands, and verification evidence.';
   const proofUrl = 'https://github.com/IgorGanapolsky/ThumbGate/blob/main/docs/VERIFICATION_EVIDENCE.md';
+  const supportEmail = getSupportEmail();
   const unsubscribeEmail = getUnsubscribeEmail();
   const businessName = getBusinessName();
   const businessAddress = getBusinessAddress();
@@ -205,7 +372,7 @@ function renderTrialWelcomeBodies({ licenseKey, customerId, customerName, trialE
     '',
     postscript,
     '',
-    `Questions? Just reply to this email or write ${SUPPORT_EMAIL}.`,
+    `Questions? Just reply to this email or write ${supportEmail}.`,
     '',
     '— Igor, founder of ThumbGate',
     '',
@@ -222,6 +389,7 @@ function renderTrialWelcomeBodies({ licenseKey, customerId, customerName, trialE
   const safeDescription = escapeHtml(description);
   const safeExample = escapeHtml(exampleFeedback);
   const safePostscript = escapeHtml(postscript);
+  const safeSupportEmail = escapeHtml(supportEmail);
   const safeBusinessName = escapeHtml(businessName);
   const safeBusinessAddress = escapeHtml(businessAddress);
   const safeUnsubscribeEmail = escapeHtml(unsubscribeEmail);
@@ -281,7 +449,7 @@ function renderTrialWelcomeBodies({ licenseKey, customerId, customerName, trialE
                 <p style="margin:0 0 4px;font-size:14px;line-height:1.6;color:#17212b;">— Igor, founder of ThumbGate</p>
                 <p style="margin:0;font-size:13px;line-height:1.55;color:#526273;">
                   Questions? Just reply to this email or write
-                  <a href="mailto:${SUPPORT_EMAIL}" style="color:#087a91;">${SUPPORT_EMAIL}</a>.
+                  <a href="mailto:${safeSupportEmail}" style="color:#087a91;">${safeSupportEmail}</a>.
                 </p>
               </td>
             </tr>
@@ -317,7 +485,7 @@ function renderTrialWelcomeBodies({ licenseKey, customerId, customerName, trialE
  * Never throws on send failures (beyond input validation); the Stripe webhook
  * must keep working even if email breaks.
  */
-async function sendTrialWelcomeEmail({ to, licenseKey, customerId, customerName, trialEndAt, fetchImpl } = {}) {
+async function sendTrialWelcomeEmail({ to, licenseKey, customerId, customerName, trialEndAt, fetchImpl, dnsResolver } = {}) {
   if (!isNonEmptyString(to)) throw new Error('sendTrialWelcomeEmail: `to` is required');
   if (!isNonEmptyString(licenseKey)) throw new Error('sendTrialWelcomeEmail: `licenseKey` is required');
 
@@ -327,17 +495,19 @@ async function sendTrialWelcomeEmail({ to, licenseKey, customerId, customerName,
     ? `${name}, your ThumbGate Pro key is inside`
     : 'Your ThumbGate Pro key is inside';
 
-  return sendEmail({ to, subject, html, text, replyTo: getReplyTo(), fetchImpl });
+  return sendEmail({ to, subject, html, text, replyTo: getReplyTo(), fetchImpl, dnsResolver });
 }
 
 module.exports = {
   sendEmail,
   sendTrialWelcomeEmail,
   renderTrialWelcomeBodies,
+  _resolveSenderAddress: resolveSenderAddress,
+  _hasResendSenderDns: hasResendSenderDns,
   _constants: {
     PRODUCT_NAME,
     DASHBOARD_URL,
-    SUPPORT_EMAIL,
+    DEFAULT_CONTACT_EMAIL,
     DEFAULT_FROM,
     DEFAULT_REPLY_TO,
     DEFAULT_UNSUBSCRIBE_EMAIL,

package/scripts/multimodal-retrieval-plan.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const DEFAULT_EVIDENCE_TYPES = ['screenshots', 'pdf_pages', 'proof_artifacts'];
+const DEFAULT_DIMS = [1024, 512, 256, 128, 64];
+
+function clampInteger(value, { min, max, fallback }) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(parsed)));
+}
+
+function normalizeEvidenceTypes(value) {
+  if (!Array.isArray(value)) return DEFAULT_EVIDENCE_TYPES;
+  const normalized = value
+    .map((item) => String(item || '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '_'))
+    .filter(Boolean);
+  return normalized.length > 0 ? [...new Set(normalized)] : DEFAULT_EVIDENCE_TYPES;
+}
+
+function dimensionPlan({ corpusItems, maxEmbeddingDim }) {
+  const dims = DEFAULT_DIMS.filter((dim) => dim <= maxEmbeddingDim);
+  const selected = dims.length > 0 ? dims : [maxEmbeddingDim];
+  return selected.map((dim) => ({
+    dim,
+    estimatedFloat32Mb: Number(((corpusItems * dim * 4) / (1024 * 1024)).toFixed(2)),
+    useWhen: dim >= 1024
+      ? 'default quality pass for launch-critical retrieval'
+      : 'cost-down pass when storage or latency dominates',
+  }));
+}
+
+function buildMultimodalRetrievalPlan(args = {}) {
+  const evidenceTypes = normalizeEvidenceTypes(args.evidenceTypes);
+  const corpusItems = clampInteger(args.corpusItems, {
+    min: 100,
+    max: 10000000,
+    fallback: 5000,
+  });
+  const maxEmbeddingDim = clampInteger(args.maxEmbeddingDim, {
+    min: 64,
+    max: 2048,
+    fallback: 1024,
+  });
+  const latencyBudgetMs = clampInteger(args.latencyBudgetMs, {
+    min: 50,
+    max: 30000,
+    fallback: 750,
+  });
+  const useReranker = args.useReranker !== false;
+  const goal = String(args.goal || 'retrieve visual proof for agent-governance decisions').trim();
+  const dims = dimensionPlan({ corpusItems, maxEmbeddingDim });
+  const defaultDim = dims.some((entry) => entry.dim === 1024) ? 1024 : dims[0].dim;
+
+  return {
+    planVersion: '2026-04-20',
+    sourcePattern: 'multimodal Sentence Transformers visual document retrieval',
+    goal,
+    evidenceTypes,
+    architecture: {
+      stage1: 'Index screenshots, PDF pages, dashboard captures, and proof artifacts with a multimodal embedding model.',
+      stage2: useReranker
+        ? 'Rerank the top candidates with a multimodal cross-encoder before using evidence in a gate, PR, or sales proof claim.'
+        : 'Skip reranking for low-latency agent recall; require stronger holdout evaluation before shipping.',
+      fallback: 'Keep text-only search as a fallback for code, logs, markdown, and plain policy docs.',
+    },
+    trainingData: {
+      pilotSchema: ['query', 'image', 'negative_0'],
+      hardNegativeStrategy: 'Pair each proof query with visually similar but wrong screenshots or PDF pages.',
+      minimumPilot: 'Start with 300 labeled evaluation queries and at least one hard negative per query before finetuning.',
+    },
+    evaluation: {
+      baseline: 'Measure current text-only retrieval before any model changes.',
+      primaryMetric: 'NDCG@10',
+      secondaryMetrics: ['Recall@5', 'MAP', 'false_positive_gate_rate'],
+      holdoutSets: [
+        'agent failure screenshots',
+        'dashboard proof captures',
+        'visual docs that contain tables or charts',
+      ],
+    },
+    deployment: {
+      latencyBudgetMs,
+      defaultEmbeddingDim: defaultDim,
+      matryoshkaDimensions: dims,
+      compressionPath: 'Use Matryoshka truncation first, then quantization only after holdout quality is stable.',
+    },
+    thumbgateUseCases: [
+      'Find the exact screenshot or proof artifact behind a completion claim.',
+      'Retrieve visual evidence before approving a workflow-hardening sprint.',
+      'Rank dashboard captures and PDF runbook pages for GEO/SEO evidence pages.',
+      'Attach visual hard negatives to Autoresearch loops so agents cannot reward-hack by deleting hard cases.',
+    ],
+    guardrails: [
+      'Never promote visual retrieval results into claims without a linked artifact URL or local path.',
+      'Keep the multimodal index read-only for agent recall; gate training and index rebuilds behind explicit workflow checks.',
+      'Evaluate retrieval on holdout screenshots/PDF pages before replacing text-only recall.',
+    ],
+    nextActions: [
+      'Create a small visual proof corpus from existing public dashboard screenshots and proof artifacts.',
+      'Log query -> correct artifact -> hard negative triples during workflow sprint reviews.',
+      'Use Autoresearch to optimize NDCG@10 and latency only after the baseline corpus exists.',
+    ],
+  };
+}
+
+module.exports = {
+  buildMultimodalRetrievalPlan,
+  dimensionPlan,
+  normalizeEvidenceTypes,
+};

package/scripts/statusline-context.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { getRuntimeDir, resolveProjectDir } = require('./feedback-paths');
+
+const FIXED_GH_BINARIES = [
+  '/usr/bin/gh',
+  '/usr/local/bin/gh',
+  '/opt/homebrew/bin/gh',
+];
+const FIXED_GIT_BINARIES = [
+  '/usr/bin/git',
+  '/usr/local/bin/git',
+  '/opt/homebrew/bin/git',
+];
+
+const CONTEXT_CACHE_MAX_AGE_MS = 120000;
+
+function contextCachePath(options = {}) {
+  return path.join(getRuntimeDir(options), 'statusline-context.json');
+}
+
+function readContextCache(options = {}) {
+  try {
+    return JSON.parse(fs.readFileSync(contextCachePath(options), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeContextCache(payload, options = {}) {
+  const targetPath = contextCachePath(options);
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, JSON.stringify(payload, null, 2) + '\n');
+  return targetPath;
+}
+
+function isFreshCache(cache, now = Date.now()) {
+  if (!cache || !cache.updatedAt) {
+    return false;
+  }
+
+  const updatedAt = Date.parse(cache.updatedAt);
+  if (!Number.isFinite(updatedAt)) {
+    return false;
+  }
+
+  return (now - updatedAt) <= CONTEXT_CACHE_MAX_AGE_MS;
+}
+
+function resolveGhBinary(accessSync = fs.accessSync) {
+  for (const candidate of FIXED_GH_BINARIES) {
+    try {
+      accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+function resolveGitBinary(options = {}) {
+  const env = options.env || process.env;
+  const configuredBinary = String(env.THUMBGATE_GIT_BIN || '').trim();
+  const candidates = configuredBinary
+    ? [configuredBinary, ...FIXED_GIT_BINARIES]
+    : FIXED_GIT_BINARIES;
+
+  for (const candidate of candidates) {
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+function runCommand(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: options.timeoutMs || 400,
+  });
+
+  if (result.status !== 0) {
+    return '';
+  }
+
+  return String(result.stdout || '').trim();
+}
+
+function getBranchName(projectDir) {
+  if (!projectDir) {
+    return '';
+  }
+
+  const gitBinary = resolveGitBinary();
+  if (!gitBinary) {
+    return '';
+  }
+
+  return runCommand(gitBinary, ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: projectDir, timeoutMs: 300 });
+}
+
+function inferWorkItemLabel(branchName = '') {
+  const normalized = String(branchName || '').trim();
+  if (!normalized) {
+    return '';
+  }
+
+  const explicitMatch = /(?:^|[/-])(AB#\d+)(?:$|[/-])/i.exec(normalized);
+  if (explicitMatch) {
+    return explicitMatch[1].toUpperCase();
+  }
+
+  const numericMatch = /(?:^|[/-])(\d{4,})(?:$|[/-])/.exec(normalized);
+  if (!numericMatch) {
+    return '';
+  }
+
+  return `AB#${numericMatch[1]}`;
+}
+
+function getPrNumber(projectDir, options = {}) {
+  if (!projectDir) {
+    return '';
+  }
+
+  const ghBinary = options.ghBinary || resolveGhBinary(options.accessSync);
+  if (!ghBinary) {
+    return '';
+  }
+
+  const prNumber = runCommand(
+    ghBinary,
+    ['pr', 'view', '--json', 'number', '--jq', '.number'],
+    { cwd: projectDir, timeoutMs: options.timeoutMs || 1000 }
+  );
+  return /^\d+$/.test(prNumber) ? prNumber : '';
+}
+
+function getStatuslineContext(options = {}) {
+  const env = options.env || process.env;
+  if (env._TEST_THUMBGATE_STATUSLINE_CONTEXT_JSON) {
+    return JSON.parse(env._TEST_THUMBGATE_STATUSLINE_CONTEXT_JSON);
+  }
+
+  const projectDir = resolveProjectDir({ env, cwd: options.cwd || process.cwd() });
+  const cache = readContextCache({ env, home: options.homeDir });
+  const branchName = (env.THUMBGATE_STATUSLINE_BRANCH || '').trim() || getBranchName(projectDir);
+  const workItemLabel = (env.THUMBGATE_STATUSLINE_WORK_ITEM || '').trim() || inferWorkItemLabel(branchName);
+
+  let prNumber = (env.THUMBGATE_STATUSLINE_PR_NUMBER || '').trim();
+  if (!prNumber && cache && cache.projectDir === projectDir && cache.branchName === branchName && isFreshCache(cache)) {
+    prNumber = String(cache.prNumber || '').trim();
+  }
+  if (!prNumber) {
+    prNumber = getPrNumber(projectDir, options);
+  }
+
+  const payload = {
+    branchName,
+    workItemLabel,
+    prNumber,
+    prLabel: prNumber ? `PR #${prNumber}` : '',
+    projectDir,
+    updatedAt: new Date().toISOString(),
+  };
+  writeContextCache(payload, { env, home: options.homeDir });
+  return payload;
+}
+
+function isCliInvocation(argv = process.argv) {
+  const invokedPath = argv[1];
+  return invokedPath ? path.resolve(invokedPath) === __filename : false;
+}
+
+if (isCliInvocation()) {
+  try {
+    process.stdout.write(JSON.stringify(getStatuslineContext()));
+  } catch {
+    process.exit(0);
+  }
+}
+
+module.exports = {
+  CONTEXT_CACHE_MAX_AGE_MS,
+  contextCachePath,
+  getBranchName,
+  getPrNumber,
+  getStatuslineContext,
+  inferWorkItemLabel,
+  isFreshCache,
+  readContextCache,
+  resolveGhBinary,
+  resolveGitBinary,
+  writeContextCache,
+};