fullstackgtm 0.21.2 → 0.23.1

package/dist/suggest.js

@@ -64,11 +64,39 @@ function suggestDealAccount(operation, dealsById, accountsByNorm, accountsById,
     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() : "";
+    // Convention 1: "Contact Name - Company Name" (hyphen, en or em dash).
+    // Both signals below are independent; agreement upgrades confidence,
+    // conflict downgrades it.
+    const separator = [" - ", " – ", " — "]
+        .map((s) => ({ s, index: deal.name.indexOf(s) }))
+        .filter(({ index }) => index >= 0)
+        .sort((a, b) => a.index - b.index)[0];
+    const left = separator ? deal.name.slice(0, separator.index).trim() : deal.name;
+    const right = separator ? deal.name.slice(separator.index + separator.s.length).trim() : "";
+    // Convention 2: "Company - Deal descriptor" (e.g. "Globex – Expansion",
+    // "Hooli – New Business"). When the right side is purely deal-descriptor
+    // words, the company is on the LEFT. Only an exact account-name match
+    // counts as high; an unknown left side proposes a create — the engine
+    // never guesses at an existing record.
+    if (left && right && isDealDescriptor(right)) {
+        const leftMatch = accountsByNorm.get(normalize(left));
+        if (leftMatch) {
+            return {
+                ...base,
+                suggestedValue: leftMatch.id,
+                confidence: "high",
+                reason: `Deal name leads with the exact account name "${leftMatch.name}" ("${right}" is a deal descriptor, not a company).`,
+            };
+        }
+        if (!contactsByName.get(normalize(left))) {
+            return {
+                ...base,
+                suggestedValue: `create:${left}`,
+                confidence: "create",
+                reason: `No account named "${left}" exists ("${right}" is a deal descriptor) — approving creates the company, then links.`,
+            };
+        }
+    }
     // Signal 1: company-name match against account names.
     let nameMatch = null;
     let nameMatchKind = "";
@@ -135,6 +163,23 @@ function suggestDealAccount(operation, dealsById, accountsByNorm, accountsById,
             reason: `No account named "${right}" exists and contact "${left}" has none — approving creates the company, then links.`,
         };
     }
+    // Convention 3: "<Company> <descriptor…>" without a separator (e.g.
+    // "INITECH renewal"): strip trailing descriptor words and accept only an
+    // exact account-name match on what remains.
+    if (!separator) {
+        const words = normalize(deal.name).split(" ").filter(Boolean);
+        while (words.length > 1 && DEAL_DESCRIPTOR_WORDS.has(words[words.length - 1]))
+            words.pop();
+        const strippedMatch = words.length > 0 ? accountsByNorm.get(words.join(" ")) : undefined;
+        if (strippedMatch) {
+            return {
+                ...base,
+                suggestedValue: strippedMatch.id,
+                confidence: "high",
+                reason: `Deal name leads with the exact account name "${strippedMatch.name}" (trailing words are deal descriptors).`,
+            };
+        }
+    }
     return {
         ...base,
         suggestedValue: null,
@@ -144,6 +189,23 @@ function suggestDealAccount(operation, dealsById, accountsByNorm, accountsById,
             : `Deal name "${deal.name}" has no "Contact - Company" pattern to derive a company from. Supply --value ${operation.id}=<accountId> or create:<Company Name>.`,
     };
 }
+/**
+ * Words that describe the deal rather than name a company. Used to recognize
+ * the "Company - Deal descriptor" naming convention: a segment counts as a
+ * descriptor only when EVERY word is in this list, so any real company name
+ * ("Brand New Startup") falls through to the contact/company conventions.
+ */
+const DEAL_DESCRIPTOR_WORDS = new Set([
+    "renewal", "expansion", "pilot", "annual", "monthly", "platform", "new", "business",
+    "add", "on", "addon", "upsell", "upgrade", "trial", "poc", "proof", "concept",
+    "subscription", "license", "licence", "contract", "opportunity", "deal", "engagement",
+    "implementation", "onboarding", "services", "inbound", "outbound",
+    "q1", "q2", "q3", "q4",
+]);
+function isDealDescriptor(segment) {
+    const words = normalize(segment).split(" ").filter(Boolean);
+    return words.length > 0 && words.every((word) => DEAL_DESCRIPTOR_WORDS.has(word));
+}
 /**
  * Survivor selection for merge_records. Ranking is deterministic and
  * evidence-based: most complete record first (count of populated canonical

package/llms.txt

@@ -47,6 +47,21 @@ report; `refresh` = capture → classify → drift → report in one command.
 Storage is profile-scoped under `<home>/market/<category>`. MCP:
 `fullstackgtm_market_worksheet`, `fullstackgtm_market_observe`.
 
+## Key invariants (enrich)
+
+`fullstackgtm enrich` is governed enrichment: `append` pulls (Apollo, BYO key
+via `login apollo`/APOLLO_API_KEY) or reads data staged by `ingest` (Clay CSV
+exports / webhook payload JSON), matches source records to CRM records via
+ordered keys in `enrich.config.json` (unique hit wins; ambiguity skips or
+becomes `requires_human_record_selection` placeholders — never a coin flip),
+and emits a fill-blanks-only patch plan through the normal dry-run → approve →
+apply gate. No `--save` = dry-run diff, nothing written. `refresh` re-checks
+stale fields the run-store ledger proves enrich stamped, proposing ops only
+where the source value changed (beforeValue = current CRM value → apply-time
+CAS). Conflict policy MVP is `never`; `system-only`/`always` are phase 2 and
+refused explicitly. Run store (checkpoint + staleness ledger + `status`) is
+profile-scoped under `<home>/enrich/runs`. No cron — scheduling is horizontal.
+
 ## Key invariants
 
 - Reads are safe by default; nothing is written without explicit `--approve`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.21.2",
+  "version": "0.23.1",
   "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",

package/src/bulkUpdate.ts

@@ -27,6 +27,7 @@
  * `account.ownerId`, `account.contactCount`; accounts get `contactCount`
  * and `openDealCount`.
  */
+import { normalizeDomain } from "./merge.ts";
 import { stableHash } from "./rules.ts";
 import type {
   CanonicalGtmSnapshot,
@@ -40,10 +41,23 @@ export type BulkUpdateOptions = {
   objectType: "account" | "contact" | "deal";
   /** raw --where expressions, AND-ed together; at least one is required */
   where: string[];
-  /** canonical field → new value; one action only */
+  /**
+   * canonical field → new value; one action only. A value of the form
+   * `from:<sourceField>` is resolved PER RECORD from the filter view at
+   * plan time (relational pseudo-fields like account.ownerId included);
+   * records whose source value is empty are skipped, not failed, and
+   * counted in the plan summary.
+   */
   set?: Record<string, string>;
   /** propose archive_record instead of field writes */
   archive?: boolean;
+  /**
+   * bypass the archive duplicate guard: by default --archive refuses when a
+   * matched account/contact shares its identity key (normalized domain /
+   * lowercased email) with another record — those are duplicates, and
+   * archiving a duplicate discards its data where merging preserves it
+   */
+  forceArchiveDuplicates?: boolean;
   /** propose create_task on each matched record with this subject/body text */
   createTask?: string;
   /** explicit preconditions (field=value), re-verified at apply time */
@@ -131,6 +145,14 @@ const VALID_FIELDS: Record<BulkUpdateOptions["objectType"], Set<string>> = {
   deal: new Set(["id", "crmId", "accountId", "ownerId", "name", "amount", "currency", "stage", "closeDate", "dealType", "forecastCategory", "nextStep", "probability", "isClosed", "isWon", "lastActivityAt", "lastSyncAt", ...RELATIONAL_FIELDS]),
 };
 
+/** True when `field` is filterable for this object type (relational pseudo-fields included). */
+export function isFilterableField(
+  objectType: BulkUpdateOptions["objectType"],
+  field: string,
+): boolean {
+  return VALID_FIELDS[objectType].has(field);
+}
+
 function assertValidFields(objectType: BulkUpdateOptions["objectType"], clauses: WhereClause[], context: string): void {
   for (const clause of clauses) {
     if (!VALID_FIELDS[objectType].has(clause.field)) {
@@ -251,10 +273,25 @@ export function buildBulkUpdatePlan(
   const clauses = options.where.map(parseWhere);
   assertValidFields(options.objectType, clauses, "--where");
   const WRITABLE_BLOCKLIST = new Set(["id", "crmId", "contactCount", "openDealCount", "openDealStages"]);
-  for (const field of Object.keys(options.set ?? {})) {
+  // `from:<sourceField>` values resolve per record from the filter view —
+  // the source is validated with the same strictness as filters (relational
+  // pseudo-fields allowed; the WRITTEN field still must be canonical).
+  const assignments: Array<{ field: string; literal?: string; fromField?: string }> = [];
+  for (const [field, value] of Object.entries(options.set ?? {})) {
     if (!VALID_FIELDS[options.objectType].has(field) || WRITABLE_BLOCKLIST.has(field) || field.includes(".")) {
       throw new Error(`Cannot --set "${field}" on ${options.objectType}s — not a writable canonical field.`);
     }
+    if (value.startsWith("from:")) {
+      const fromField = value.slice("from:".length);
+      if (!VALID_FIELDS[options.objectType].has(fromField)) {
+        throw new Error(
+          `Cannot --set ${field}=from:${fromField} on ${options.objectType}s — unknown source field "${fromField}". Valid fields: ${[...VALID_FIELDS[options.objectType]].join(", ")}.`,
+        );
+      }
+      assignments.push({ field, fromField });
+    } else {
+      assignments.push({ field, literal: value });
+    }
   }
   const views = buildViews(snapshot, options.objectType);
   const matched = views.filter(({ view }) => clauses.every((c) => matches(view, c)));
@@ -264,6 +301,45 @@ export function buildBulkUpdatePlan(
     );
   }
 
+  // Archive duplicate guard: archiving a record that shares its identity key
+  // with another active record discards data a merge would preserve. Refuse
+  // and point at `dedupe` unless explicitly overridden. Deals are exempt —
+  // they carry no identity key.
+  if (options.archive && options.objectType !== "deal" && !options.forceArchiveDuplicates) {
+    const keyName = options.objectType === "account" ? "domain" : "email";
+    const keyOf = (record: Record<string, unknown>): string | undefined =>
+      options.objectType === "account"
+        ? normalizeDomain(record.domain as string | undefined)
+        : ((record.email as string | undefined)?.trim().toLowerCase() || undefined);
+    const allRecords = snapshot[COLLECTIONS[options.objectType]] as Array<Record<string, unknown>>;
+    const byKey = new Map<string, Array<Record<string, unknown>>>();
+    for (const record of allRecords) {
+      const key = keyOf(record);
+      if (!key) continue;
+      const existing = byKey.get(key) ?? [];
+      existing.push(record);
+      byKey.set(key, existing);
+    }
+    const collisions: string[] = [];
+    for (const { record } of matched) {
+      const key = keyOf(record);
+      if (!key) continue;
+      const others = (byKey.get(key) ?? []).filter((other) => other.id !== record.id);
+      if (others.length === 0) continue;
+      const label = (record.name as string | undefined) ?? (record.email as string | undefined) ?? "";
+      collisions.push(
+        `${options.objectType} ${record.id}${label ? ` "${label}"` : ""} shares ${keyName} "${key}" with ${others
+          .map((other) => `${other.id}${other.name ? ` "${other.name}"` : ""}`)
+          .join(", ")}`,
+      );
+    }
+    if (collisions.length > 0) {
+      throw new Error(
+        `Refusing to archive: ${collisions.length} matched record(s) look like duplicates of other records — archiving a duplicate DISCARDS its data, merging preserves it. Use \`fullstackgtm dedupe ${options.objectType} --key ${keyName}\` (merge_records) instead, or pass --force-archive-duplicates to archive anyway.\n  - ${collisions.join("\n  - ")}`,
+      );
+    }
+  }
+
   // Preconditions: explicit --require, plus every equality filter on a real
   // (re-readable, non-relational) field. The premise the plan was built on
   // is re-verified per record at apply time.
@@ -295,7 +371,9 @@ export function buildBulkUpdatePlan(
   const reason = options.reason ?? `bulk-update: ${action} where ${whereText}`;
 
   const operations: PatchOperation[] = [];
-  for (const { record } of matched) {
+  // records skipped because a from:<sourceField> value was empty, per source
+  const skippedBySource = new Map<string, number>();
+  for (const { record, view } of matched) {
     const objectId = String(record.id);
     const groupId = `grp_${options.objectType}_${objectId}`;
     const preconditions = preconditionSpecs.map((p) => ({
@@ -338,7 +416,29 @@ export function buildBulkUpdatePlan(
       });
       continue;
     }
-    for (const [field, value] of Object.entries(options.set!)) {
+    // Resolve every assignment for this record BEFORE emitting any of its
+    // operations: a record whose from:<sourceField> resolves empty is
+    // skipped whole (its operations share a groupId — half a record's
+    // updates is exactly what grouping exists to prevent).
+    const resolved: Array<{ field: string; value: string }> = [];
+    let emptySource: string | null = null;
+    for (const assignment of assignments) {
+      if (assignment.fromField !== undefined) {
+        const value = fieldValue(view, assignment.fromField);
+        if (value === "") {
+          emptySource = assignment.fromField;
+          break;
+        }
+        resolved.push({ field: assignment.field, value });
+      } else {
+        resolved.push({ field: assignment.field, value: assignment.literal! });
+      }
+    }
+    if (emptySource !== null) {
+      skippedBySource.set(emptySource, (skippedBySource.get(emptySource) ?? 0) + 1);
+      continue;
+    }
+    for (const { field, value } of resolved) {
       operations.push({
         ...shared,
         id: `op_${stableHash(`bulk-set:${options.objectType}:${objectId}:${field}:${value}`)}`,
@@ -360,13 +460,16 @@ export function buildBulkUpdatePlan(
     if (failure) throw new Error(`${failure} The guard already fails against the current snapshot — the plan would never apply.`);
   }
 
+  const skippedText = [...skippedBySource.entries()]
+    .map(([sourceField, count]) => ` ${count} skipped: empty ${sourceField}.`)
+    .join("");
   return {
-    id: `patch_plan_${stableHash(`bulk:${snapshot.provider}:${snapshot.generatedAt}:${whereText}:${action}:${operations.length}`)}`,
+    id: `patch_plan_${stableHash(`bulk:${snapshot.provider}:${snapshot.generatedAt}:${options.objectType}:${whereText}:${action}:${operations.length}`)}`,
     title: `Bulk update: ${options.objectType}s where ${whereText}`,
     createdAt: snapshot.generatedAt,
     status: operations.length > 0 ? "needs_approval" : "draft",
     dryRun: true,
-    summary: `${matched.length} ${COLLECTIONS[options.objectType]} matched (${whereText}); ${operations.length} proposed dry-run operations (${action}).${guards.length > 0 ? ` ${guards.length} apply-time guard(s).` : ""}`,
+    summary: `${matched.length} ${COLLECTIONS[options.objectType]} matched (${whereText}); ${operations.length} proposed dry-run operations (${action}).${skippedText}${guards.length > 0 ? ` ${guards.length} apply-time guard(s).` : ""}`,
     findings: [],
     operations,
     filter: { objectType: options.objectType, where: options.where },