fullstackgtm 0.45.0 → 0.47.0

package/src/health.ts

@@ -2,7 +2,20 @@ import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { activeProfile, credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.ts";
-import type { AuditFindingSeverity, CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
+import type { CanonicalGtmSnapshot } from "./types.ts";
+import type { HealthEntry } from "./healthScore.ts";
+
+// Pure scoring lives in healthScore.ts (node-free, importable from V8 runtimes
+// like the hosted app's Convex queries); this module owns the fs-backed
+// profile timeline. Re-exported so existing imports keep working.
+export {
+  computeHealth,
+  summarizeHealth,
+  healthToMarkdown,
+  type HealthEntry,
+  type HealthRuleDelta,
+  type HealthRollup,
+} from "./healthScore.ts";
 
 /**
  * The engagement workspace: a per-client health timeline that accrues from the
@@ -15,218 +28,6 @@ import type { AuditFindingSeverity, CanonicalGtmSnapshot, PatchPlan } from "./ty
  * so it is stable in CI and comparable run-over-run.
  */
 
-// Severity weights: a critical finding costs ~3× a warning, ~10× an info.
-const SEVERITY_WEIGHT: Record<AuditFindingSeverity, number> = { info: 1, warning: 3, critical: 10 };
-
-export type HealthEntry = {
-  /** ISO timestamp of the audit that produced this entry. */
-  at: string;
-  /** The saved plan this entry summarizes (correlates to plans/ and snapshots/). */
-  planId: string;
-  /** Deterministic 0–100 hygiene score (higher is healthier). */
-  score: number;
-  /** Total finding count across all rules. */
-  findings: number;
-  /** Severity-weighted finding total (drives the score). */
-  weightedFindings: number;
-  /** Record counts at audit time — the denominator that normalizes the score. */
-  records: { accounts: number; contacts: number; deals: number; total: number };
-  /** Finding count per rule id. */
-  byRule: Record<string, number>;
-  /** Finding count per severity. */
-  severityCounts: Record<AuditFindingSeverity, number>;
-  /**
-   * Per-object-type breakdown — so "is my contact data clean but my pipeline
-   * messy?" is answerable without re-auditing. Each type carries its own
-   * record-normalized score (same curve as the overall score, scoped to that
-   * type's records + findings).
-   */
-  byObjectType: Record<"account" | "contact" | "deal", {
-    records: number;
-    findings: number;
-    weightedFindings: number;
-    score: number;
-  }>;
-};
-
-export type HealthRuleDelta = {
-  ruleId: string;
-  current: number;
-  previous: number;
-  /** current − previous: positive = more findings (worse), negative = fewer (better). */
-  delta: number;
-};
-
-export type HealthRollup = {
-  profile: string;
-  auditCount: number;
-  first: string;
-  latest: string;
-  current: HealthEntry;
-  previous: HealthEntry | null;
-  /** current.score − previous.score: positive = improving. null on the first audit. */
-  scoreDelta: number | null;
-  ruleDeltas: HealthRuleDelta[];
-  history: Array<{ at: string; score: number; findings: number }>;
-};
-
-/**
- * Deterministically score a saved audit. score = 100 / (1 + weighted findings
- * per record): 0 findings → 100; one weighted finding per record → 50; the
- * curve is bounded (0, 100], monotonic, and needs no clamping or magic
- * constants. A messy 50-record CRM scores worse than the same finding count
- * across 5,000 records, which is the point.
- */
-export function computeHealth(plan: PatchPlan, snapshot: CanonicalGtmSnapshot, at: string): HealthEntry {
-  const byRule: Record<string, number> = {};
-  const severityCounts: Record<AuditFindingSeverity, number> = { info: 0, warning: 0, critical: 0 };
-  const typeTally: Record<"account" | "contact" | "deal", { findings: number; weightedFindings: number }> = {
-    account: { findings: 0, weightedFindings: 0 },
-    contact: { findings: 0, weightedFindings: 0 },
-    deal: { findings: 0, weightedFindings: 0 },
-  };
-  let weightedFindings = 0;
-  for (const finding of plan.findings) {
-    byRule[finding.ruleId] = (byRule[finding.ruleId] ?? 0) + 1;
-    severityCounts[finding.severity] += 1;
-    weightedFindings += SEVERITY_WEIGHT[finding.severity];
-    const t = finding.objectType;
-    if (t === "account" || t === "contact" || t === "deal") {
-      typeTally[t].findings += 1;
-      typeTally[t].weightedFindings += SEVERITY_WEIGHT[finding.severity];
-    }
-  }
-
-  const records = {
-    accounts: snapshot.accounts.length,
-    contacts: snapshot.contacts.length,
-    deals: snapshot.deals.length,
-    total: snapshot.accounts.length + snapshot.contacts.length + snapshot.deals.length,
-  };
-
-  const scoreFor = (weighted: number, recordCount: number) =>
-    Math.round(100 / (1 + weighted / Math.max(recordCount, 1)));
-  const recordsByType = { account: records.accounts, contact: records.contacts, deal: records.deals };
-  const byObjectType = (["account", "contact", "deal"] as const).reduce(
-    (acc, t) => {
-      acc[t] = {
-        records: recordsByType[t],
-        findings: typeTally[t].findings,
-        weightedFindings: typeTally[t].weightedFindings,
-        score: scoreFor(typeTally[t].weightedFindings, recordsByType[t]),
-      };
-      return acc;
-    },
-    {} as HealthEntry["byObjectType"],
-  );
-
-  const score = scoreFor(weightedFindings, records.total);
-
-  return {
-    at,
-    planId: plan.id,
-    score,
-    findings: plan.findings.length,
-    weightedFindings,
-    records,
-    byRule,
-    severityCounts,
-    byObjectType,
-  };
-}
-
-/** Roll a timeline up into the current state, the change since last time, and per-rule deltas. */
-export function summarizeHealth(entries: HealthEntry[], profile: string): HealthRollup | null {
-  if (entries.length === 0) return null;
-  // Oldest → newest, so `current` is the last entry.
-  const sorted = [...entries].sort((a, b) => a.at.localeCompare(b.at));
-  const current = sorted[sorted.length - 1];
-  const previous = sorted.length > 1 ? sorted[sorted.length - 2] : null;
-
-  const ruleIds = new Set<string>([
-    ...Object.keys(current.byRule),
-    ...(previous ? Object.keys(previous.byRule) : []),
-  ]);
-  const ruleDeltas: HealthRuleDelta[] = [...ruleIds]
-    .map((ruleId) => {
-      const cur = current.byRule[ruleId] ?? 0;
-      const prev = previous?.byRule[ruleId] ?? 0;
-      return { ruleId, current: cur, previous: prev, delta: cur - prev };
-    })
-    .sort((a, b) => b.current - a.current || a.ruleId.localeCompare(b.ruleId));
-
-  return {
-    profile,
-    auditCount: sorted.length,
-    first: sorted[0].at,
-    latest: current.at,
-    current,
-    previous,
-    scoreDelta: previous ? current.score - previous.score : null,
-    ruleDeltas,
-    history: sorted.map((entry) => ({ at: entry.at, score: entry.score, findings: entry.findings })),
-  };
-}
-
-// Sign-based and uniform: ▲ = the number went up, ▼ = down. The reader supplies
-// the meaning (score up = good; findings up = bad) — mixing arrow direction with
-// good/bad reads as contradictory ("▲ -3").
-function arrow(delta: number): string {
-  if (delta === 0) return "·";
-  return delta > 0 ? "▲" : "▼";
-}
-
-/** Human-readable rollup: headline score + trend, then per-rule change since last audit. */
-export function healthToMarkdown(rollup: HealthRollup): string {
-  const { current, scoreDelta } = rollup;
-  const lines = [`# GTM health — profile \`${rollup.profile}\``, ""];
-
-  const deltaText =
-    scoreDelta === null
-      ? "(first audit — no prior reading)"
-      : `${arrow(scoreDelta)} ${scoreDelta >= 0 ? "+" : ""}${scoreDelta} since the previous audit`;
-  lines.push(
-    `Score: **${current.score}/100** ${deltaText}`,
-    `Audits: ${rollup.auditCount} over ${shortDate(rollup.first)} → ${shortDate(rollup.latest)}`,
-    `Findings: ${current.findings} (${current.severityCounts.critical} critical, ${current.severityCounts.warning} warning, ${current.severityCounts.info} info)`,
-    `Records: ${current.records.accounts} accounts, ${current.records.contacts} contacts, ${current.records.deals} deals`,
-    "",
-  );
-
-  lines.push("## By object type", "", "| Type | Score | Findings | Records |", "| --- | --- | --- | --- |");
-  for (const t of ["account", "contact", "deal"] as const) {
-    const b = current.byObjectType[t];
-    lines.push(`| ${t} | ${b.score}/100 | ${b.findings} | ${b.records} |`);
-  }
-  lines.push("");
-
-  if (rollup.history.length > 1) {
-    lines.push("## Trend", "");
-    for (const point of rollup.history) {
-      const marker = point.at === rollup.latest ? "  ← latest" : "";
-      lines.push(`- ${shortDate(point.at)}  score ${point.score}  (${point.findings} findings)${marker}`);
-    }
-    lines.push("");
-  }
-
-  if (rollup.ruleDeltas.length > 0) {
-    lines.push("## By rule (Δ since previous audit)", "", "| Rule | Findings | Δ |", "| --- | --- | --- |");
-    for (const rule of rollup.ruleDeltas) {
-      const sign = rule.delta > 0 ? `+${rule.delta}` : `${rule.delta}`;
-      const cell = rule.delta === 0 ? "·" : `${arrow(rule.delta)} ${sign}`;
-      lines.push(`| ${rule.ruleId} | ${rule.current} | ${cell} |`);
-    }
-    lines.push("");
-  }
-
-  lines.push("> Score is deterministic: 100 / (1 + severity-weighted findings per record). Lower findings or more clean records ⇒ higher score.");
-  return `${lines.join("\n")}\n`;
-}
-
-function shortDate(iso: string): string {
-  return iso.slice(0, 10);
-}
-
 // ── Profile-scoped storage ──────────────────────────────────────────────────
 
 /** `$FSGTM_HOME[/profiles/<name>]/health.jsonl` — append-only, one entry per audit-save. */

package/src/healthScore.ts

@@ -0,0 +1,223 @@
+import type { AuditFindingSeverity, CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
+
+/**
+ * Pure, node-free health scoring. Split from health.ts (which owns the
+ * fs-backed profile timeline) so V8-runtime consumers — the hosted app's
+ * Convex queries — can import the scoring math without pulling node built-ins,
+ * the same pattern as audit.ts/format.ts.
+ *
+ * The score is DETERMINISTIC (no LLM): same plan + same snapshot → same score,
+ * so it is stable in CI and comparable run-over-run.
+ */
+
+// Severity weights: a critical finding costs ~3× a warning, ~10× an info.
+const SEVERITY_WEIGHT: Record<AuditFindingSeverity, number> = { info: 1, warning: 3, critical: 10 };
+
+export type HealthEntry = {
+  /** ISO timestamp of the audit that produced this entry. */
+  at: string;
+  /** The saved plan this entry summarizes (correlates to plans/ and snapshots/). */
+  planId: string;
+  /** Deterministic 0–100 hygiene score (higher is healthier). */
+  score: number;
+  /** Total finding count across all rules. */
+  findings: number;
+  /** Severity-weighted finding total (drives the score). */
+  weightedFindings: number;
+  /** Record counts at audit time — the denominator that normalizes the score. */
+  records: { accounts: number; contacts: number; deals: number; total: number };
+  /** Finding count per rule id. */
+  byRule: Record<string, number>;
+  /** Finding count per severity. */
+  severityCounts: Record<AuditFindingSeverity, number>;
+  /**
+   * Per-object-type breakdown — so "is my contact data clean but my pipeline
+   * messy?" is answerable without re-auditing. Each type carries its own
+   * record-normalized score (same curve as the overall score, scoped to that
+   * type's records + findings).
+   */
+  byObjectType: Record<"account" | "contact" | "deal", {
+    records: number;
+    findings: number;
+    weightedFindings: number;
+    score: number;
+  }>;
+};
+
+export type HealthRuleDelta = {
+  ruleId: string;
+  current: number;
+  previous: number;
+  /** current − previous: positive = more findings (worse), negative = fewer (better). */
+  delta: number;
+};
+
+export type HealthRollup = {
+  profile: string;
+  auditCount: number;
+  first: string;
+  latest: string;
+  current: HealthEntry;
+  previous: HealthEntry | null;
+  /** current.score − previous.score: positive = improving. null on the first audit. */
+  scoreDelta: number | null;
+  ruleDeltas: HealthRuleDelta[];
+  history: Array<{ at: string; score: number; findings: number }>;
+};
+
+/**
+ * Deterministically score a saved audit. score = 100 / (1 + weighted findings
+ * per record): 0 findings → 100; one weighted finding per record → 50; the
+ * curve is bounded (0, 100], monotonic, and needs no clamping or magic
+ * constants. A messy 50-record CRM scores worse than the same finding count
+ * across 5,000 records, which is the point.
+ */
+export function computeHealth(plan: PatchPlan, snapshot: CanonicalGtmSnapshot, at: string): HealthEntry {
+  const byRule: Record<string, number> = {};
+  const severityCounts: Record<AuditFindingSeverity, number> = { info: 0, warning: 0, critical: 0 };
+  const typeTally: Record<"account" | "contact" | "deal", { findings: number; weightedFindings: number }> = {
+    account: { findings: 0, weightedFindings: 0 },
+    contact: { findings: 0, weightedFindings: 0 },
+    deal: { findings: 0, weightedFindings: 0 },
+  };
+  let weightedFindings = 0;
+  for (const finding of plan.findings) {
+    byRule[finding.ruleId] = (byRule[finding.ruleId] ?? 0) + 1;
+    severityCounts[finding.severity] += 1;
+    weightedFindings += SEVERITY_WEIGHT[finding.severity];
+    const t = finding.objectType;
+    if (t === "account" || t === "contact" || t === "deal") {
+      typeTally[t].findings += 1;
+      typeTally[t].weightedFindings += SEVERITY_WEIGHT[finding.severity];
+    }
+  }
+
+  const records = {
+    accounts: snapshot.accounts.length,
+    contacts: snapshot.contacts.length,
+    deals: snapshot.deals.length,
+    total: snapshot.accounts.length + snapshot.contacts.length + snapshot.deals.length,
+  };
+
+  const scoreFor = (weighted: number, recordCount: number) =>
+    Math.round(100 / (1 + weighted / Math.max(recordCount, 1)));
+  const recordsByType = { account: records.accounts, contact: records.contacts, deal: records.deals };
+  const byObjectType = (["account", "contact", "deal"] as const).reduce(
+    (acc, t) => {
+      acc[t] = {
+        records: recordsByType[t],
+        findings: typeTally[t].findings,
+        weightedFindings: typeTally[t].weightedFindings,
+        score: scoreFor(typeTally[t].weightedFindings, recordsByType[t]),
+      };
+      return acc;
+    },
+    {} as HealthEntry["byObjectType"],
+  );
+
+  const score = scoreFor(weightedFindings, records.total);
+
+  return {
+    at,
+    planId: plan.id,
+    score,
+    findings: plan.findings.length,
+    weightedFindings,
+    records,
+    byRule,
+    severityCounts,
+    byObjectType,
+  };
+}
+
+/** Roll a timeline up into the current state, the change since last time, and per-rule deltas. */
+export function summarizeHealth(entries: HealthEntry[], profile: string): HealthRollup | null {
+  if (entries.length === 0) return null;
+  // Oldest → newest, so `current` is the last entry.
+  const sorted = [...entries].sort((a, b) => a.at.localeCompare(b.at));
+  const current = sorted[sorted.length - 1];
+  const previous = sorted.length > 1 ? sorted[sorted.length - 2] : null;
+
+  const ruleIds = new Set<string>([
+    ...Object.keys(current.byRule),
+    ...(previous ? Object.keys(previous.byRule) : []),
+  ]);
+  const ruleDeltas: HealthRuleDelta[] = [...ruleIds]
+    .map((ruleId) => {
+      const cur = current.byRule[ruleId] ?? 0;
+      const prev = previous?.byRule[ruleId] ?? 0;
+      return { ruleId, current: cur, previous: prev, delta: cur - prev };
+    })
+    .sort((a, b) => b.current - a.current || a.ruleId.localeCompare(b.ruleId));
+
+  return {
+    profile,
+    auditCount: sorted.length,
+    first: sorted[0].at,
+    latest: current.at,
+    current,
+    previous,
+    scoreDelta: previous ? current.score - previous.score : null,
+    ruleDeltas,
+    history: sorted.map((entry) => ({ at: entry.at, score: entry.score, findings: entry.findings })),
+  };
+}
+
+// Sign-based and uniform: ▲ = the number went up, ▼ = down. The reader supplies
+// the meaning (score up = good; findings up = bad) — mixing arrow direction with
+// good/bad reads as contradictory ("▲ -3").
+function arrow(delta: number): string {
+  if (delta === 0) return "·";
+  return delta > 0 ? "▲" : "▼";
+}
+
+/** Human-readable rollup: headline score + trend, then per-rule change since last audit. */
+export function healthToMarkdown(rollup: HealthRollup): string {
+  const { current, scoreDelta } = rollup;
+  const lines = [`# GTM health — profile \`${rollup.profile}\``, ""];
+
+  const deltaText =
+    scoreDelta === null
+      ? "(first audit — no prior reading)"
+      : `${arrow(scoreDelta)} ${scoreDelta >= 0 ? "+" : ""}${scoreDelta} since the previous audit`;
+  lines.push(
+    `Score: **${current.score}/100** ${deltaText}`,
+    `Audits: ${rollup.auditCount} over ${shortDate(rollup.first)} → ${shortDate(rollup.latest)}`,
+    `Findings: ${current.findings} (${current.severityCounts.critical} critical, ${current.severityCounts.warning} warning, ${current.severityCounts.info} info)`,
+    `Records: ${current.records.accounts} accounts, ${current.records.contacts} contacts, ${current.records.deals} deals`,
+    "",
+  );
+
+  lines.push("## By object type", "", "| Type | Score | Findings | Records |", "| --- | --- | --- | --- |");
+  for (const t of ["account", "contact", "deal"] as const) {
+    const b = current.byObjectType[t];
+    lines.push(`| ${t} | ${b.score}/100 | ${b.findings} | ${b.records} |`);
+  }
+  lines.push("");
+
+  if (rollup.history.length > 1) {
+    lines.push("## Trend", "");
+    for (const point of rollup.history) {
+      const marker = point.at === rollup.latest ? "  ← latest" : "";
+      lines.push(`- ${shortDate(point.at)}  score ${point.score}  (${point.findings} findings)${marker}`);
+    }
+    lines.push("");
+  }
+
+  if (rollup.ruleDeltas.length > 0) {
+    lines.push("## By rule (Δ since previous audit)", "", "| Rule | Findings | Δ |", "| --- | --- | --- |");
+    for (const rule of rollup.ruleDeltas) {
+      const sign = rule.delta > 0 ? `+${rule.delta}` : `${rule.delta}`;
+      const cell = rule.delta === 0 ? "·" : `${arrow(rule.delta)} ${sign}`;
+      lines.push(`| ${rule.ruleId} | ${rule.current} | ${cell} |`);
+    }
+    lines.push("");
+  }
+
+  lines.push("> Score is deterministic: 100 / (1 + severity-weighted findings per record). Lower findings or more clean records ⇒ higher score.");
+  return `${lines.join("\n")}\n`;
+}
+
+function shortDate(iso: string): string {
+  return iso.slice(0, 10);
+}

package/src/index.ts

@@ -21,6 +21,20 @@ export {
   type LoadedConfig,
 } from "./config.ts";
 export { applyPatchPlan, type ApplyPatchPlanOptions } from "./connector.ts";
+export {
+  APPLY_STAGES,
+  BACKFILL_STRIPE_STAGES,
+  composeListeners,
+  createProgressEmitter,
+  CRM_SYNC_STAGES,
+  nullProgressEmitter,
+  SNAPSHOT_PULL_STAGES,
+  STRIPE_SNAPSHOT_STAGES,
+  type ProgressEmitter,
+  type ProgressEvent,
+  type ProgressListener,
+  type ProgressSnapshot,
+} from "./progress.ts";
 export { createHubspotConnector, type HubspotConnectorOptions } from "./connectors/hubspot.ts";
 export {
   DEFAULT_LOOPBACK_PORT,
@@ -45,7 +59,20 @@ export {
   type SalesforceDeviceAuthorization,
   type SalesforceTokenSet,
 } from "./connectors/salesforceAuth.ts";
-export { createStripeConnector, type StripeConnectorOptions } from "./connectors/stripe.ts";
+export {
+  createStripeConnector,
+  fetchStripePaidInvoices,
+  type StripeConnectorOptions,
+  type StripePaidInvoice,
+} from "./connectors/stripe.ts";
+export {
+  buildStripeBackfillPlan,
+  DEFAULT_BACKFILL_MATCH_PROPERTY,
+  type StripeBackfillCounts,
+  type StripeBackfillOptions,
+  type StripeBackfillResult,
+  type StripeBackfillUnmatched,
+} from "./backfill.ts";
 export {
   activeProfile,
   credentialsDir,