fullstackgtm 0.10.0

package/dist/mcp.js

@@ -0,0 +1,140 @@
+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.js";
+import { loadConfig, mergePolicy, resolveConfiguredRules } from "./config.js";
+import { applyPatchPlan } from "./connector.js";
+import { createHubspotConnector } from "./connectors/hubspot.js";
+import { createSalesforceConnector } from "./connectors/salesforce.js";
+import { createStripeConnector } from "./connectors/stripe.js";
+import { getCredential, resolveHubspotAccessToken, resolveSalesforceConnection, } from "./credentials.js";
+import { generateDemoSnapshot } from "./demo.js";
+import { formatPatchPlanRun, patchPlanToMarkdown } from "./format.js";
+import { builtinAuditRules } from "./rules.js";
+import { sampleSnapshot } from "./sampleData.js";
+function content(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof value === "string" ? value : JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}
+async function connectorFor(provider) {
+    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.fieldMappings ?? 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, inputPath) {
+    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"));
+}
+function packageVersion() {
+    try {
+        const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+        return JSON.parse(raw).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"));
+        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/dist/merge.d.ts

@@ -0,0 +1,48 @@
+import type { CanonicalGtmSnapshot } 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[];
+};
+export declare function mergeSnapshots(snapshots: CanonicalGtmSnapshot[]): {
+    snapshot: CanonicalGtmSnapshot;
+    report: MergeReport;
+};

package/dist/merge.js

@@ -0,0 +1,145 @@
+const CONFLICT_IGNORED_FIELDS = new Set([
+    "id", "provider", "crmId", "identities", "raw", "lastSyncAt", "lastActivityAt", "ownerId", "accountId",
+]);
+function normalizeDomain(domain) {
+    if (!domain)
+        return undefined;
+    return domain.trim().toLowerCase().replace(/^https?:\/\//, "").replace(/^www\./, "").replace(/\/.*$/, "") || undefined;
+}
+function normalizeEmail(email) {
+    const normalized = email?.trim().toLowerCase();
+    return normalized || undefined;
+}
+function identityOf(record) {
+    return { provider: record.provider ?? "unknown", externalId: record.crmId ?? record.id };
+}
+export function mergeSnapshots(snapshots) {
+    if (snapshots.length === 0)
+        throw new Error("mergeSnapshots needs at least one snapshot.");
+    const sources = snapshots.map((snapshot) => snapshot.provider);
+    const matches = [];
+    const conflicts = [];
+    // Original id (per source snapshot) → merged id, used to re-point references.
+    const idRemap = new Map();
+    function namespaced(provider, id) {
+        return `${provider}:${id}`;
+    }
+    function mergeCollection(type, collections, keysOf) {
+        const merged = [];
+        const byKey = new Map();
+        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 = {
+                        ...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[field];
+                    if (current === undefined) {
+                        primary[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" }] : [];
+    });
+    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" }] : [];
+    });
+    const suggestions = [];
+    const byName = new Map();
+    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" }] : [];
+    });
+    const remapRef = (provider, id) => 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 },
+    };
+}

package/dist/planStore.d.ts

@@ -0,0 +1,31 @@
+import type { ApprovalStatus, PatchPlan, PatchPlanRun } from "./types.ts";
+/**
+ * Durable patch-plan workflow. A plan is an immutable proposal; the store
+ * tracks the mutable lifecycle around it — which operations a human approved,
+ * the concrete values they supplied, and every apply run. The hosted app's
+ * Convex tables and this file store are two implementations of the same
+ * contract.
+ */
+export type StoredPlan = {
+    plan: PatchPlan;
+    status: ApprovalStatus;
+    approvedOperationIds: string[];
+    valueOverrides: Record<string, unknown>;
+    runs: PatchPlanRun[];
+    createdAt: string;
+    updatedAt: string;
+};
+export interface PlanStore {
+    save(plan: PatchPlan): Promise<StoredPlan>;
+    get(planId: string): Promise<StoredPlan | null>;
+    list(status?: ApprovalStatus): Promise<StoredPlan[]>;
+    approveOperations(planId: string, operationIds: string[], valueOverrides?: Record<string, unknown>): Promise<StoredPlan>;
+    reject(planId: string): Promise<StoredPlan>;
+    recordRun(planId: string, run: PatchPlanRun): Promise<StoredPlan>;
+}
+/**
+ * Plans as JSON files in a directory (default `$FSGTM_HOME/plans`), one file
+ * per plan id. Filesystem-shaped on purpose: greppable, diffable, and any
+ * file-based tooling composes with it.
+ */
+export declare function createFilePlanStore(directory?: string): PlanStore;

package/dist/planStore.js

@@ -0,0 +1,116 @@
+import { chmodSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.js";
+/**
+ * Plans as JSON files in a directory (default `$FSGTM_HOME/plans`), one file
+ * per plan id. Filesystem-shaped on purpose: greppable, diffable, and any
+ * file-based tooling composes with it.
+ */
+export function createFilePlanStore(directory) {
+    const dir = directory ?? join(credentialsDir(), "plans");
+    function pathFor(planId) {
+        if (!/^[\w.-]+$/.test(planId))
+            throw new Error(`Invalid plan id: ${planId}`);
+        return join(dir, `${planId}.json`);
+    }
+    function read(planId) {
+        try {
+            return JSON.parse(readFileSync(pathFor(planId), "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    function write(stored) {
+        // Plan files contain real CRM before/after values; keep them owner-only.
+        // When the store lives under the default home, lock that down too —
+        // otherwise an `audit --save` before any `login` would create the home
+        // directory world-readable.
+        if (!directory)
+            ensureSecureHomeDir();
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        try {
+            chmodSync(dir, 0o700);
+        }
+        catch {
+            // Non-POSIX filesystems ignore chmod.
+        }
+        const next = { ...stored, updatedAt: new Date().toISOString() };
+        writeSecureFile(pathFor(stored.plan.id), `${JSON.stringify(next, null, 2)}\n`);
+        return next;
+    }
+    function mustRead(planId) {
+        const stored = read(planId);
+        if (!stored)
+            throw new Error(`No stored plan with id ${planId}.`);
+        return stored;
+    }
+    return {
+        async save(plan) {
+            const now = new Date().toISOString();
+            return write({
+                plan,
+                status: plan.status,
+                approvedOperationIds: [],
+                valueOverrides: {},
+                runs: [],
+                createdAt: now,
+                updatedAt: now,
+            });
+        },
+        async get(planId) {
+            return read(planId);
+        },
+        async list(status) {
+            let entries = [];
+            try {
+                entries = readdirSync(dir);
+            }
+            catch {
+                return [];
+            }
+            const plans = entries
+                .filter((entry) => entry.endsWith(".json"))
+                .map((entry) => read(entry.slice(0, -".json".length)))
+                .filter((stored) => stored !== null)
+                .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+            return status ? plans.filter((stored) => stored.status === status) : plans;
+        },
+        async approveOperations(planId, operationIds, valueOverrides = {}) {
+            const stored = mustRead(planId);
+            if (stored.status === "applied") {
+                throw new Error(`Plan ${planId} has already been applied.`);
+            }
+            if (stored.status === "rejected") {
+                throw new Error(`Plan ${planId} was rejected; re-run the audit for a fresh plan.`);
+            }
+            const known = new Set(stored.plan.operations.map((operation) => operation.id));
+            for (const operationId of operationIds) {
+                if (!known.has(operationId)) {
+                    throw new Error(`Plan ${planId} has no operation ${operationId}.`);
+                }
+            }
+            return write({
+                ...stored,
+                status: "approved",
+                approvedOperationIds: Array.from(new Set([...stored.approvedOperationIds, ...operationIds])),
+                valueOverrides: { ...stored.valueOverrides, ...valueOverrides },
+            });
+        },
+        async reject(planId) {
+            const stored = mustRead(planId);
+            if (stored.status === "applied") {
+                throw new Error(`Plan ${planId} has already been applied.`);
+            }
+            return write({ ...stored, status: "rejected", approvedOperationIds: [] });
+        },
+        async recordRun(planId, run) {
+            const stored = mustRead(planId);
+            return write({
+                ...stored,
+                status: run.status === "applied" || run.status === "partial" ? "applied" : stored.status,
+                runs: [...stored.runs, run],
+            });
+        },
+    };
+}

package/dist/rules.d.ts

@@ -0,0 +1,24 @@
+import type { CanonicalGtmSnapshot, GtmAuditRule, GtmSnapshotIndex } from "./types.ts";
+/**
+ * Placeholder used as `afterValue` when the right value is a human decision
+ * (e.g. which owner to assign). Apply orchestration refuses to write these
+ * unless an explicit override value is supplied at approval time.
+ */
+export declare const REQUIRES_HUMAN_PREFIX = "requires_human_";
+export declare function requiresHumanInput(value: unknown): boolean;
+export declare function auditFindingId(ruleId: string, objectId: string): string;
+export declare function patchOperationId(ruleId: string, objectId: string): string;
+export declare function stableHash(value: string): string;
+export declare function buildSnapshotIndex(snapshot: CanonicalGtmSnapshot): GtmSnapshotIndex;
+export declare const orphanAccountRule: GtmAuditRule;
+export declare const missingDealOwnerRule: GtmAuditRule;
+export declare const missingDealAccountRule: GtmAuditRule;
+export declare const pastCloseDateRule: GtmAuditRule;
+export declare const staleDealRule: GtmAuditRule;
+export declare const missingDealAmountRule: GtmAuditRule;
+export declare const duplicateAccountDomainRule: GtmAuditRule;
+export declare const duplicateContactEmailRule: GtmAuditRule;
+export declare const activeDealAccountWithoutContactsRule: GtmAuditRule;
+export declare const closingSoonInactiveRule: GtmAuditRule;
+export declare const accountSingleSourceRule: GtmAuditRule;
+export declare const builtinAuditRules: GtmAuditRule[];