fullstackgtm 0.10.0 → 0.11.0

package/dist/rules.js

@@ -380,6 +380,52 @@ export const duplicateContactEmailRule = {
         return { findings, operations };
     },
 };
+export const duplicateOpenDealRule = {
+    id: "duplicate-open-deal",
+    title: "Open deals duplicate the same opportunity",
+    description: "Flags multiple open deals carrying the same name (scoped to the account when linked) — " +
+        "usually an integration re-creating deals instead of upserting, which counts the same " +
+        "revenue several times in pipeline and forecast.",
+    category: "data-quality",
+    evaluate: ({ snapshot }) => {
+        const findings = [];
+        const operations = [];
+        const keyOf = (deal) => {
+            if (!isOpen(deal))
+                return undefined;
+            const name = deal.name?.trim().toLowerCase().replace(/\s+/g, " ");
+            if (!name)
+                return undefined;
+            return `${deal.accountId ?? "unlinked"}:${name}`;
+        };
+        for (const [, deals] of duplicateGroups(snapshot.deals, keyOf)) {
+            const anchor = deals[0];
+            findings.push({
+                id: auditFindingId("duplicate-open-deal", anchor.id),
+                objectType: "deal",
+                objectId: anchor.id,
+                ruleId: "duplicate-open-deal",
+                title: "Open deals duplicate the same opportunity",
+                severity: "warning",
+                summary: `${deals.length} open deals named "${anchor.name}"${anchor.accountId ? " on the same account" : ""}: ${deals.map((deal) => deal.id).join(", ")}.`,
+                recommendation: "Keep one deal, archive the copies, and fix the integration that is re-creating them.",
+            });
+            operations.push({
+                id: patchOperationId("duplicate-open-deal", anchor.id),
+                objectType: "deal",
+                objectId: anchor.id,
+                operation: "create_task",
+                field: "merge_review_task",
+                beforeValue: null,
+                afterValue: `Review ${deals.length} duplicate open deals named "${anchor.name}" — keep one, archive ${deals.length - 1}`,
+                reason: "Duplicate open deals inflate pipeline and forecast the same revenue more than once.",
+                riskLevel: "medium",
+                approvalRequired: true,
+            });
+        }
+        return { findings, operations };
+    },
+};
 export const activeDealAccountWithoutContactsRule = {
     id: "active-deal-account-without-contacts",
     title: "Account with open pipeline has no contacts",
@@ -506,6 +552,7 @@ export const builtinAuditRules = [
     missingDealAmountRule,
     duplicateAccountDomainRule,
     duplicateContactEmailRule,
+    duplicateOpenDealRule,
     activeDealAccountWithoutContactsRule,
     closingSoonInactiveRule,
     accountSingleSourceRule,

package/dist/suggest.d.ts

@@ -0,0 +1,31 @@
+import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
+/**
+ * Deterministic value suggestions for `requires_human_*` placeholder
+ * operations. The engine never invents data: every suggestion is derived
+ * from evidence already in the snapshot (account names, contact→account
+ * associations, the org's user list) and carries a confidence level plus a
+ * human-readable reason, so a reviewer — or an agent driving the CLI — can
+ * approve in bulk at a chosen confidence threshold.
+ *
+ * Born from dogfooding: an audit of a real portal produced 30
+ * `requires_human_account_selection` placeholders whose answers were all
+ * derivable from the snapshot itself.
+ */
+export type SuggestionConfidence = "high" | "low" | "create" | "none";
+export type ValueSuggestion = {
+    operationId: string;
+    objectType: string;
+    objectId: string;
+    /** Display name of the object the operation targets (e.g. the deal name). */
+    objectName?: string;
+    /** The requires_human_* placeholder being filled. */
+    placeholder: string;
+    /**
+     * The value to approve with, or null when no evidence supports one.
+     * `create:<Name>` proposes creating the missing record on apply.
+     */
+    suggestedValue: string | null;
+    confidence: SuggestionConfidence;
+    reason: string;
+};
+export declare function suggestValues(plan: PatchPlan, snapshot: CanonicalGtmSnapshot): ValueSuggestion[];

package/dist/suggest.js

@@ -0,0 +1,148 @@
+import { requiresHumanInput } from "./rules.js";
+export function suggestValues(plan, snapshot) {
+    const accountsByNorm = new Map();
+    for (const account of snapshot.accounts) {
+        accountsByNorm.set(normalize(account.name), { id: account.id, name: account.name });
+    }
+    const accountsById = new Map(snapshot.accounts.map((a) => [a.id, a]));
+    const contactsByName = new Map();
+    for (const contact of snapshot.contacts) {
+        const name = normalize(`${contact.firstName ?? ""} ${contact.lastName ?? ""}`);
+        if (name)
+            contactsByName.set(name, { id: contact.id, accountId: contact.accountId, name });
+    }
+    const dealsById = new Map(snapshot.deals.map((d) => [d.id, d]));
+    const activeUsers = snapshot.users.filter((user) => user.active !== false);
+    const suggestions = [];
+    for (const operation of plan.operations) {
+        if (!requiresHumanInput(operation.afterValue))
+            continue;
+        const placeholder = String(operation.afterValue);
+        if (placeholder === "requires_human_account_selection" && operation.objectType === "deal") {
+            suggestions.push(suggestDealAccount(operation, dealsById, accountsByNorm, accountsById, contactsByName));
+            continue;
+        }
+        if (placeholder === "requires_human_owner_selection" && activeUsers.length === 1) {
+            suggestions.push({
+                operationId: operation.id,
+                objectType: operation.objectType,
+                objectId: operation.objectId,
+                objectName: dealsById.get(operation.objectId)?.name,
+                placeholder,
+                suggestedValue: activeUsers[0].id,
+                confidence: "high",
+                reason: `${activeUsers[0].name} is the only active user in the org.`,
+            });
+            continue;
+        }
+        suggestions.push({
+            operationId: operation.id,
+            objectType: operation.objectType,
+            objectId: operation.objectId,
+            objectName: dealsById.get(operation.objectId)?.name,
+            placeholder,
+            suggestedValue: null,
+            confidence: "none",
+            reason: `No deterministic heuristic for ${placeholder}; supply --value ${operation.id}=<value>.`,
+        });
+    }
+    return suggestions;
+}
+function suggestDealAccount(operation, dealsById, accountsByNorm, accountsById, contactsByName) {
+    const deal = dealsById.get(operation.objectId);
+    const base = {
+        operationId: operation.id,
+        objectType: operation.objectType,
+        objectId: operation.objectId,
+        objectName: deal?.name,
+        placeholder: "requires_human_account_selection",
+    };
+    if (!deal) {
+        return { ...base, suggestedValue: null, confidence: "none", reason: "Deal not found in the snapshot." };
+    }
+    // Convention: "Contact Name - Company Name". Both signals below are
+    // independent; agreement upgrades confidence, conflict downgrades it.
+    const separatorIndex = deal.name.indexOf(" - ");
+    const left = separatorIndex >= 0 ? deal.name.slice(0, separatorIndex) : deal.name;
+    const right = separatorIndex >= 0 ? deal.name.slice(separatorIndex + 3).trim() : "";
+    // Signal 1: company-name match against account names.
+    let nameMatch = null;
+    let nameMatchKind = "";
+    if (right) {
+        nameMatch = accountsByNorm.get(normalize(right)) ?? null;
+        nameMatchKind = nameMatch ? "exact name match" : "";
+        if (!nameMatch) {
+            const rightNorm = normalize(right);
+            const candidates = [...accountsByNorm.entries()].filter(([norm]) => norm.includes(rightNorm) || rightNorm.includes(norm));
+            if (candidates.length === 1) {
+                nameMatch = candidates[0][1];
+                nameMatchKind = "partial name match";
+            }
+            else if (candidates.length > 1) {
+                return {
+                    ...base,
+                    suggestedValue: null,
+                    confidence: "none",
+                    reason: `"${right}" matches ${candidates.length} accounts ambiguously: ${candidates.slice(0, 4).map(([, a]) => a.name).join(", ")}.`,
+                };
+            }
+        }
+    }
+    // Signal 2: the deal's named contact already belongs to an account.
+    const contact = contactsByName.get(normalize(left));
+    const contactAccount = contact?.accountId ? accountsById.get(contact.accountId) ?? null : null;
+    if (nameMatch && contactAccount) {
+        if (nameMatch.id === contactAccount.id) {
+            return {
+                ...base,
+                suggestedValue: nameMatch.id,
+                confidence: "high",
+                reason: `${nameMatchKind} on "${nameMatch.name}", confirmed by contact "${left}"'s account association.`,
+            };
+        }
+        return {
+            ...base,
+            suggestedValue: null,
+            confidence: "none",
+            reason: `Signals conflict: name matches "${nameMatch.name}" but contact "${left}" belongs to "${contactAccount.name}".`,
+        };
+    }
+    if (nameMatch) {
+        return {
+            ...base,
+            suggestedValue: nameMatch.id,
+            confidence: nameMatchKind === "exact name match" ? "high" : "low",
+            reason: `${nameMatchKind} on "${nameMatch.name}" (no contact signal to confirm).`,
+        };
+    }
+    if (contactAccount) {
+        return {
+            ...base,
+            suggestedValue: contactAccount.id,
+            confidence: "low",
+            reason: `Contact "${left}" belongs to "${contactAccount.name}" (no account-name match to confirm).`,
+        };
+    }
+    if (contact && !contact.accountId && right) {
+        return {
+            ...base,
+            suggestedValue: `create:${right}`,
+            confidence: "create",
+            reason: `No account named "${right}" exists and contact "${left}" has none — approving creates the company, then links.`,
+        };
+    }
+    return {
+        ...base,
+        suggestedValue: null,
+        confidence: "none",
+        reason: right
+            ? `No account matches "${right}" and "${left}" is not a known contact. Supply --value ${operation.id}=<accountId> or --value ${operation.id}=create:<Company Name>.`
+            : `Deal name "${deal.name}" has no "Contact - Company" pattern to derive a company from. Supply --value ${operation.id}=<accountId> or create:<Company Name>.`,
+    };
+}
+function normalize(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}

package/docs/api.md

@@ -57,7 +57,8 @@ release.
 
 ## CLI
 
-Commands: `login` / `logout`, `snapshot`, `audit`, `diff`, `merge`, `plans`, `apply`, `rules`.
+Commands: `login` / `logout`, `snapshot`, `audit`, `report`, `diff`, `merge`, `plans`,
+`apply`, `rules`, `profiles`, `doctor`.
 Exit codes: `0` success · `1` error · `2` findings/regressions at the requested gate
 (`--fail-on`, `--fail-on-new-findings`). `--json` everywhere; JSON output shapes are stable.
 
@@ -66,6 +67,17 @@ Credential resolution ladder: explicit `--token-env` → ambient env
 `STRIPE_SECRET_KEY`) → stored login (`~/.fullstackgtm`, `FSGTM_HOME` override)
 → broker pairing (`login --via`).
 
+Profiles: the global `--profile <name>` flag (or `FULLSTACKGTM_PROFILE`) scopes
+stored logins and stored plans to `profiles/<name>/` under the home directory,
+so one operator can work across several organizations' CRMs without mixing
+credentials or applying one org's plan through another's connection. The
+default profile keeps the historical flat layout.
+
+`report` renders an audit (or an existing plan via `--plan`) as a client-ready
+deliverable in markdown or self-contained HTML: severity counts, prose summary,
+per-rule detail with capped examples, and next steps. `auditReportToMarkdown` /
+`auditReportToHtml` expose the same rendering programmatically.
+
 ## MCP
 
 Tools: `fullstackgtm_audit`, `fullstackgtm_rules`, `fullstackgtm_apply`

package/docs/roadmap-to-1.0.md

@@ -106,11 +106,39 @@ The original thesis: GTM data disagrees across systems.
 - Docs site with the operating-model registry as browsable reference.
 - Performance pass: streaming snapshots for very large orgs.
 
-## 1.0.0 — The contract (reached)
+## Known real-portal gaps to close before 1.0
+
+Found by exercising the published package as a fresh RevOps user with a real
+CRM (2026-06):
+
+- **Pipeline-aware closed-deal detection (HubSpot).** `isClosed`/`isWon` are
+  derived by substring-matching the raw `dealstage` value against
+  `closedwon`/`closedlost`. Custom pipelines use opaque stage ids, so closed
+  deals read as open and flood stale-deal/past-close findings. Fix: resolve
+  stage metadata from `/crm/v3/pipelines` once per snapshot.
+- **Rate-limit resilience.** No 429/retry/backoff handling anywhere; a
+  mid-size portal snapshot is ~1,000+ sequential page requests and one
+  transient failure aborts the run. Fix: honor `Retry-After`, retry
+  idempotent reads with backoff.
+- **`fetchChanges` 10k truncation.** The HubSpot search API caps at 10,000
+  results; the connector stops silently at MAX_PAGES. Fix: detect the cap
+  and fall back to (or instruct) a full snapshot, loudly.
+- **MCP plan hand-off.** `fullstackgtm_audit` can only return the full plan
+  inline (200KB+ on real data) while `fullstackgtm_apply` requires a file
+  path. Fix: an `outPath` option on the audit tool plus a summary-only
+  output mode.
+- **Scope-complete login validation.** `login hubspot` validates against the
+  owners endpoint only, so an under-scoped token passes login and fails
+  mid-audit. Fix: probe each required object endpoint at login and report
+  missing scopes up front.
+
+## 1.0.0 — The contract (not yet declared)
 
 Semver stability commitment on the canonical model, rule interface, connector
-contract, plan format, CLI, and MCP tools. From here, new providers and new
-rules are minor releases; the model only breaks at 2.0.
+contract, plan format, CLI, and MCP tools. Declared only after the API
+surface has survived external usage and the real-portal gaps above are
+closed. From there, new providers and new rules are minor releases; the
+model only breaks at 2.0.
 
 ## Deliberately out of scope until after 1.0
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM",