fullstackgtm 0.10.0

package/src/mappings.ts

@@ -0,0 +1,157 @@
+export type CrmObjectType = "owners" | "accounts" | "contacts" | "deals";
+
+export type FieldMappings = Partial<
+  Record<CrmObjectType | string, Record<string, string>>
+>;
+
+export const HUBSPOT_DEFAULT_FIELD_MAPPINGS: Record<
+  Exclude<CrmObjectType, "owners">,
+  Record<string, string>
+> = {
+  accounts: {
+    name: "name",
+    domain: "domain",
+    industry: "industry",
+    employeeCount: "numberofemployees",
+    annualRevenue: "annualrevenue",
+    ownerId: "hubspot_owner_id",
+  },
+  contacts: {
+    firstName: "firstname",
+    lastName: "lastname",
+    email: "email",
+    phone: "phone",
+    title: "jobtitle",
+    ownerId: "hubspot_owner_id",
+  },
+  deals: {
+    name: "dealname",
+    amount: "amount",
+    closeDate: "closedate",
+    stage: "dealstage",
+    dealType: "dealtype",
+    ownerId: "hubspot_owner_id",
+    probability: "hs_deal_stage_probability",
+    lastActivityAt: "hs_last_sales_activity_timestamp",
+    nextStep: "hs_next_step",
+  },
+};
+
+export const SALESFORCE_DEFAULT_FIELD_MAPPINGS: Record<
+  CrmObjectType,
+  Record<string, string>
+> = {
+  owners: {
+    id: "Id",
+    name: "Name",
+    email: "Email",
+    title: "Title",
+    isActive: "IsActive",
+  },
+  accounts: {
+    id: "Id",
+    name: "Name",
+    domain: "Website",
+    industry: "Industry",
+    employeeCount: "NumberOfEmployees",
+    annualRevenue: "AnnualRevenue",
+    ownerId: "OwnerId",
+  },
+  contacts: {
+    id: "Id",
+    firstName: "FirstName",
+    lastName: "LastName",
+    email: "Email",
+    phone: "Phone",
+    title: "Title",
+    accountId: "AccountId",
+    ownerId: "OwnerId",
+  },
+  deals: {
+    id: "Id",
+    name: "Name",
+    amount: "Amount",
+    closeDate: "CloseDate",
+    stage: "StageName",
+    dealType: "Type",
+    probability: "Probability",
+    isClosed: "IsClosed",
+    isWon: "IsWon",
+    ownerId: "OwnerId",
+    accountId: "AccountId",
+    lastActivityAt: "LastActivityDate",
+    forecastCategoryName: "ForecastCategory",
+    nextStep: "NextStep",
+  },
+};
+
+const OBJECT_ALIASES: Record<CrmObjectType, string[]> = {
+  owners: ["owners", "users"],
+  accounts: ["accounts", "companies"],
+  contacts: ["contacts"],
+  deals: ["deals", "opportunities"],
+};
+
+export function normalizeFieldMappings(value: unknown): FieldMappings {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const normalized: FieldMappings = {};
+  for (const [objectName, mapping] of Object.entries(value)) {
+    if (!mapping || typeof mapping !== "object" || Array.isArray(mapping)) {
+      continue;
+    }
+    const clean: Record<string, string> = {};
+    for (const [targetField, providerField] of Object.entries(mapping)) {
+      if (typeof providerField === "string" && providerField.trim()) {
+        clean[targetField] = providerField.trim();
+      }
+    }
+    if (Object.keys(clean).length > 0) normalized[objectName] = clean;
+  }
+  return normalized;
+}
+
+export function mappedField(
+  mappings: FieldMappings | undefined,
+  objectType: CrmObjectType,
+  targetField: string,
+  fallbackField: string,
+): string {
+  const normalized = normalizeFieldMappings(mappings);
+  for (const alias of OBJECT_ALIASES[objectType]) {
+    const mapped = normalized[alias]?.[targetField];
+    if (mapped) return mapped;
+  }
+  return fallbackField;
+}
+
+export function mappedFields(
+  mappings: FieldMappings | undefined,
+  objectType: CrmObjectType,
+  defaults: Record<string, string>,
+): string[] {
+  const fields = Object.entries(defaults).map(([targetField, fallbackField]) =>
+    mappedField(mappings, objectType, targetField, fallbackField),
+  );
+  return Array.from(new Set(fields)).filter(Boolean);
+}
+
+export function readMappedValue(
+  source: Record<string, unknown>,
+  mappings: FieldMappings | undefined,
+  objectType: CrmObjectType,
+  targetField: string,
+  fallbackField: string,
+): unknown {
+  return readPath(
+    source,
+    mappedField(mappings, objectType, targetField, fallbackField),
+  );
+}
+
+function readPath(source: Record<string, unknown>, path: string): unknown {
+  if (Object.prototype.hasOwnProperty.call(source, path)) return source[path];
+  return path.split(".").reduce<unknown>((value, segment) => {
+    if (!value || typeof value !== "object") return undefined;
+    return (value as Record<string, unknown>)[segment];
+  }, source);
+}

package/src/mcp-bin.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+export {};
+
+// The MCP server needs the optional peer dependencies. Import dynamically so
+// a missing peer produces install guidance instead of a module-load stack
+// trace — `npx fullstackgtm-mcp` alone never installs optional peers.
+const MISSING_PEER_HELP = `The MCP server needs the optional peer dependencies @modelcontextprotocol/sdk and zod.
+
+In a project:
+  npm install fullstackgtm @modelcontextprotocol/sdk zod
+
+Zero-install:
+  npx -p fullstackgtm -p @modelcontextprotocol/sdk -p zod fullstackgtm-mcp`;
+
+function isMissingPeerError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const code = (error as NodeJS.ErrnoException).code;
+  if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") return false;
+  return error.message.includes("@modelcontextprotocol/sdk") || error.message.includes("zod");
+}
+
+try {
+  const { startMcpServer } = await import("./mcp.ts");
+  await startMcpServer();
+} catch (error) {
+  if (isMissingPeerError(error)) {
+    console.error(MISSING_PEER_HELP);
+  } else {
+    console.error(error instanceof Error ? error.message : String(error));
+  }
+  process.exitCode = 1;
+}

package/src/mcp.ts

@@ -0,0 +1,185 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod/v4";
+import { auditSnapshot, defaultPolicy } from "./audit.ts";
+import { loadConfig, mergePolicy, resolveConfiguredRules } from "./config.ts";
+import { applyPatchPlan } from "./connector.ts";
+import { createHubspotConnector } from "./connectors/hubspot.ts";
+import { createSalesforceConnector } from "./connectors/salesforce.ts";
+import { createStripeConnector } from "./connectors/stripe.ts";
+import {
+  getCredential,
+  resolveHubspotAccessToken,
+  resolveSalesforceConnection,
+} from "./credentials.ts";
+import { generateDemoSnapshot } from "./demo.ts";
+import type { FieldMappings } from "./mappings.ts";
+import { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
+import { builtinAuditRules } from "./rules.ts";
+import { sampleSnapshot } from "./sampleData.ts";
+import type { CanonicalGtmSnapshot, GtmConnector, PatchPlan } from "./types.ts";
+
+function content(value: unknown) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: typeof value === "string" ? value : JSON.stringify(value, null, 2),
+      },
+    ],
+  };
+}
+
+async function connectorFor(provider: string): Promise<GtmConnector> {
+  if (provider === "hubspot") {
+    const token = process.env.HUBSPOT_ACCESS_TOKEN ?? (await resolveHubspotAccessToken());
+    if (!token) {
+      throw new Error(
+        "No HubSpot credentials. Run `fullstackgtm login hubspot` or set HUBSPOT_ACCESS_TOKEN in the MCP server environment.",
+      );
+    }
+    return createHubspotConnector({ getAccessToken: () => token });
+  }
+  if (provider === "salesforce") {
+    const connection =
+      process.env.SALESFORCE_ACCESS_TOKEN && process.env.SALESFORCE_INSTANCE_URL
+        ? {
+            accessToken: process.env.SALESFORCE_ACCESS_TOKEN,
+            instanceUrl: process.env.SALESFORCE_INSTANCE_URL,
+          }
+        : await resolveSalesforceConnection();
+    if (!connection) {
+      throw new Error(
+        "No Salesforce credentials. Run `fullstackgtm login salesforce` or set SALESFORCE_ACCESS_TOKEN and SALESFORCE_INSTANCE_URL in the MCP server environment.",
+      );
+    }
+    return createSalesforceConnector({
+      getConnection: () => connection,
+      fieldMappings:
+        ((connection as { fieldMappings?: unknown }).fieldMappings as
+          | FieldMappings
+          | undefined) ?? undefined,
+    });
+  }
+  if (provider === "stripe") {
+    const key = process.env.STRIPE_SECRET_KEY ?? getCredential("stripe")?.accessToken;
+    if (!key) {
+      throw new Error(
+        "No Stripe credentials. Run `fullstackgtm login stripe` or set STRIPE_SECRET_KEY in the MCP server environment.",
+      );
+    }
+    return createStripeConnector({ getApiKey: () => key });
+  }
+  throw new Error(
+    `Unknown provider: ${provider}. Supported providers: hubspot, salesforce, stripe`,
+  );
+}
+
+async function readSnapshot(
+  provider?: string,
+  inputPath?: string,
+): Promise<CanonicalGtmSnapshot> {
+  if (provider === "demo") return generateDemoSnapshot();
+  if (provider && provider !== "sample") {
+    const connector = await connectorFor(provider);
+    return connector.fetchSnapshot();
+  }
+  if (!inputPath) return sampleSnapshot;
+  return JSON.parse(
+    readFileSync(resolve(process.cwd(), inputPath), "utf8"),
+  ) as CanonicalGtmSnapshot;
+}
+
+function packageVersion() {
+  try {
+    const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+    return (JSON.parse(raw) as { version?: string }).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+export async function startMcpServer() {
+  const server = new McpServer({
+    name: "fullstackgtm",
+    version: packageVersion(),
+  });
+
+  server.registerTool(
+    "fullstackgtm_audit",
+    {
+      title: "GTM Ops Audit",
+      description:
+        "Run a dry-run GTM hygiene audit and return a reviewable patch plan. " +
+        "Reads from the sample dataset, a snapshot file, or a live provider.",
+      inputSchema: {
+        provider: z.enum(["sample", "demo", "hubspot", "salesforce", "stripe"]).optional(),
+        inputPath: z.string().optional(),
+        configPath: z.string().optional(),
+        rules: z.array(z.string()).optional(),
+        output: z.enum(["json", "markdown"]).optional(),
+        today: z.string().optional(),
+        staleDealDays: z.number().int().positive().optional(),
+      },
+    },
+    async ({ provider, inputPath, configPath, rules, output, today, staleDealDays }) => {
+      const loaded = configPath ? loadConfig(configPath) : null;
+      const policy = mergePolicy(defaultPolicy(today), loaded?.config);
+      if (today) policy.today = today;
+      if (staleDealDays !== undefined) policy.staleDealDays = staleDealDays;
+      const ruleSet = await resolveConfiguredRules(loaded);
+      const selected = rules?.length
+        ? ruleSet.filter((rule) => rules.includes(rule.id))
+        : ruleSet;
+      const plan = auditSnapshot(await readSnapshot(provider, inputPath), policy, selected);
+      return content(output === "markdown" ? patchPlanToMarkdown(plan) : plan);
+    },
+  );
+
+  server.registerTool(
+    "fullstackgtm_rules",
+    {
+      title: "List Audit Rules",
+      description: "List the built-in deterministic audit rules with ids and descriptions.",
+      inputSchema: {},
+    },
+    async () => {
+      return content(
+        builtinAuditRules.map(({ id, title, description }) => ({ id, title, description })),
+      );
+    },
+  );
+
+  server.registerTool(
+    "fullstackgtm_apply",
+    {
+      title: "Apply Approved Patch Operations",
+      description:
+        "Apply explicitly approved operations from a patch plan through a provider " +
+        "connector. Operations not listed in approvedOperationIds are never written, " +
+        "and requires_human_* placeholders need a value override.",
+      inputSchema: {
+        provider: z.enum(["hubspot", "salesforce"]),
+        planPath: z.string(),
+        approvedOperationIds: z.array(z.string()).min(1),
+        valueOverrides: z.record(z.string(), z.string()).optional(),
+        output: z.enum(["json", "markdown"]).optional(),
+      },
+    },
+    async ({ provider, planPath, approvedOperationIds, valueOverrides, output }) => {
+      const plan = JSON.parse(
+        readFileSync(resolve(process.cwd(), planPath), "utf8"),
+      ) as PatchPlan;
+      const run = await applyPatchPlan(await connectorFor(provider), plan, {
+        approvedOperationIds,
+        valueOverrides,
+      });
+      return content(output === "markdown" ? formatPatchPlanRun(run) : run);
+    },
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/merge.ts

@@ -0,0 +1,235 @@
+import type {
+  CanonicalAccount,
+  CanonicalContact,
+  CanonicalGtmSnapshot,
+  CanonicalUser,
+  ProviderIdentity,
+} from "./types.ts";
+
+/**
+ * Entity resolution across systems. GTM data disagrees because the same
+ * real-world entity lives in several tools under different ids; merging
+ * collapses canonical records onto deterministic match keys (account domain,
+ * contact/user email) while every original system id survives as an identity
+ * claim. Deals and activities are never merged — they are provider-unique —
+ * but their references are re-pointed at the merged records.
+ *
+ * Merging never invents data: the first source wins for conflicting fields,
+ * and every disagreement is reported, not silently resolved.
+ */
+
+export type MergeMatch = {
+  type: "user" | "account" | "contact";
+  primaryId: string;
+  mergedIds: string[];
+  matchedBy: "email" | "domain" | "name";
+};
+
+export type MergeConflict = {
+  type: "user" | "account" | "contact";
+  recordId: string;
+  field: string;
+  values: Array<{ provider: string; value: unknown }>;
+};
+
+/**
+ * A same-name collision that was NOT auto-merged (different or absent
+ * domains). Surfaced for human review rather than silently combined —
+ * fabricating a merge between two real companies both named "Acme" would
+ * corrupt deals, contacts, and attribution.
+ */
+export type MergeSuggestion = {
+  type: "account";
+  name: string;
+  recordIds: string[];
+};
+
+export type MergeReport = {
+  sources: string[];
+  matches: MergeMatch[];
+  conflicts: MergeConflict[];
+  suggestions: MergeSuggestion[];
+};
+
+const CONFLICT_IGNORED_FIELDS = new Set([
+  "id", "provider", "crmId", "identities", "raw", "lastSyncAt", "lastActivityAt", "ownerId", "accountId",
+]);
+
+function normalizeDomain(domain?: string): string | undefined {
+  if (!domain) return undefined;
+  return domain.trim().toLowerCase().replace(/^https?:\/\//, "").replace(/^www\./, "").replace(/\/.*$/, "") || undefined;
+}
+
+function normalizeEmail(email?: string): string | undefined {
+  const normalized = email?.trim().toLowerCase();
+  return normalized || undefined;
+}
+
+function identityOf(record: { provider?: string; crmId?: string; id: string }): ProviderIdentity {
+  return { provider: record.provider ?? "unknown", externalId: record.crmId ?? record.id };
+}
+
+type Mergeable = CanonicalUser | CanonicalAccount | CanonicalContact;
+
+export function mergeSnapshots(snapshots: CanonicalGtmSnapshot[]): {
+  snapshot: CanonicalGtmSnapshot;
+  report: MergeReport;
+} {
+  if (snapshots.length === 0) throw new Error("mergeSnapshots needs at least one snapshot.");
+  const sources = snapshots.map((snapshot) => snapshot.provider);
+  const matches: MergeMatch[] = [];
+  const conflicts: MergeConflict[] = [];
+  // Original id (per source snapshot) → merged id, used to re-point references.
+  const idRemap = new Map<string, string>();
+
+  function namespaced(provider: string, id: string) {
+    return `${provider}:${id}`;
+  }
+
+  function mergeCollection<T extends Mergeable>(
+    type: MergeMatch["type"],
+    collections: Array<{ provider: string; records: T[] }>,
+    keysOf: (record: T) => Array<{ key: string; matchedBy: MergeMatch["matchedBy"] }>,
+  ): T[] {
+    const merged: T[] = [];
+    const byKey = new Map<string, T>();
+
+    for (const { provider, records } of collections) {
+      for (const record of records) {
+        const sourceId = namespaced(provider, record.id);
+        const keyed = keysOf(record);
+        const existing = keyed
+          .map((entry) => ({ ...entry, match: byKey.get(`${entry.matchedBy}:${entry.key}`) }))
+          .find((entry) => entry.match);
+
+        if (!existing?.match) {
+          const copy: T = {
+            ...record,
+            id: sourceId,
+            provider: record.provider ?? provider,
+            identities: [identityOf({ ...record, provider: record.provider ?? provider })],
+          };
+          merged.push(copy);
+          idRemap.set(sourceId, sourceId);
+          for (const entry of keyed) byKey.set(`${entry.matchedBy}:${entry.key}`, copy);
+          continue;
+        }
+
+        const primary = existing.match;
+        idRemap.set(sourceId, primary.id);
+        primary.identities = [
+          ...(primary.identities ?? []),
+          identityOf({ ...record, provider: record.provider ?? provider }),
+        ];
+        const match = matches.find(
+          (candidate) => candidate.type === type && candidate.primaryId === primary.id,
+        );
+        if (match) match.mergedIds.push(sourceId);
+        else matches.push({ type, primaryId: primary.id, mergedIds: [sourceId], matchedBy: existing.matchedBy });
+
+        // First source wins; fill gaps, report disagreements.
+        for (const [field, value] of Object.entries(record)) {
+          if (CONFLICT_IGNORED_FIELDS.has(field) || value === undefined) continue;
+          const current = (primary as Record<string, unknown>)[field];
+          if (current === undefined) {
+            (primary as Record<string, unknown>)[field] = value;
+          } else if (JSON.stringify(current) !== JSON.stringify(value)) {
+            conflicts.push({
+              type,
+              recordId: primary.id,
+              field,
+              values: [
+                { provider: primary.provider ?? "unknown", value: current },
+                { provider: record.provider ?? provider, value },
+              ],
+            });
+          }
+        }
+      }
+    }
+    return merged;
+  }
+
+  const users = mergeCollection(
+    "user",
+    snapshots.map((snapshot) => ({ provider: snapshot.provider, records: snapshot.users })),
+    (user) => {
+      const email = normalizeEmail(user.email);
+      return email ? [{ key: email, matchedBy: "email" as const }] : [];
+    },
+  );
+
+  const accounts = mergeCollection(
+    "account",
+    snapshots.map((snapshot) => ({ provider: snapshot.provider, records: snapshot.accounts })),
+    // Auto-merge accounts ONLY on a shared normalized domain. Name is a weak,
+    // collision-prone key (every "Acme Inc"); name-only collisions become
+    // review suggestions below instead of silent merges.
+    (account) => {
+      const domain = normalizeDomain(account.domain);
+      return domain ? [{ key: domain, matchedBy: "domain" as const }] : [];
+    },
+  );
+
+  const suggestions: MergeSuggestion[] = [];
+  const byName = new Map<string, string[]>();
+  for (const account of accounts) {
+    const key = account.name.trim().toLowerCase();
+    if (!key) continue;
+    byName.set(key, [...(byName.get(key) ?? []), account.id]);
+  }
+  for (const [, recordIds] of byName) {
+    if (recordIds.length > 1) {
+      const name = accounts.find((account) => account.id === recordIds[0])!.name;
+      suggestions.push({ type: "account", name, recordIds });
+    }
+  }
+
+  const contacts = mergeCollection(
+    "contact",
+    snapshots.map((snapshot) => ({ provider: snapshot.provider, records: snapshot.contacts })),
+    (contact) => {
+      const email = normalizeEmail(contact.email);
+      return email ? [{ key: email, matchedBy: "email" as const }] : [];
+    },
+  );
+
+  const remapRef = (provider: string, id?: string) =>
+    id === undefined ? undefined : idRemap.get(`${provider}:${id}`) ?? namespaced(provider, id);
+
+  const deals = snapshots.flatMap((snapshot) =>
+    snapshot.deals.map((deal) => ({
+      ...deal,
+      id: namespaced(snapshot.provider, deal.id),
+      provider: deal.provider ?? snapshot.provider,
+      identities: [identityOf({ ...deal, provider: deal.provider ?? snapshot.provider })],
+      accountId: remapRef(snapshot.provider, deal.accountId),
+      ownerId: remapRef(snapshot.provider, deal.ownerId),
+    })),
+  );
+
+  const activities = snapshots.flatMap((snapshot) =>
+    snapshot.activities.map((activity) => ({
+      ...activity,
+      id: namespaced(snapshot.provider, activity.id),
+      provider: activity.provider ?? snapshot.provider,
+      accountId: remapRef(snapshot.provider, activity.accountId),
+      contactId: remapRef(snapshot.provider, activity.contactId),
+      dealId: remapRef(snapshot.provider, activity.dealId),
+      ownerId: remapRef(snapshot.provider, activity.ownerId),
+    })),
+  );
+
+  return {
+    snapshot: {
+      generatedAt: snapshots.map((snapshot) => snapshot.generatedAt).sort().at(-1)!,
+      provider: "merged",
+      users,
+      accounts,
+      contacts,
+      deals,
+      activities,
+    },
+    report: { sources, matches, conflicts, suggestions },
+  };
+}