fullstackgtm 0.10.1 → 0.11.1

package/src/connectors/hubspot.ts

@@ -54,6 +54,10 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
   const baseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
   const fetchImpl = options.fetchImpl ?? fetch;
   const mappings = options.fieldMappings;
+  // create:<Name> dedup within one connector lifetime (one apply run): the
+  // search API is eventually consistent, so a just-created company is
+  // invisible to search — this map is the authoritative same-run record.
+  const createdCompaniesByName = new Map<string, string>();
 
   async function request(path: string, init: RequestInit = {}): Promise<any> {
     const token = await options.getAccessToken();
@@ -380,10 +384,51 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
         detail: "link_record is supported for deals and contacts (to a company).",
       };
     }
-    const companyId = String(operation.afterValue ?? "");
+    let companyId = String(operation.afterValue ?? "");
     if (!companyId) {
       return { operationId: operation.id, status: "skipped", detail: "link_record needs a target company id." };
     }
+    // `create:<Name>` is resolve-first: link to an existing company when one
+    // unambiguously matches, refuse on ambiguity, create only on a confirmed
+    // miss — and never create the same name twice within one apply run
+    // (HubSpot's search API is eventually consistent, so a just-created
+    // record is invisible to search for several seconds).
+    let createdCompanyName: string | null = null;
+    let resolvedExisting = false;
+    if (companyId.startsWith("create:")) {
+      const name = companyId.slice("create:".length).trim();
+      if (!name) {
+        return { operationId: operation.id, status: "skipped", detail: "create: needs a company name (create:<Name>)." };
+      }
+      const nameKey = name.toLowerCase();
+      const alreadyCreated = createdCompaniesByName.get(nameKey);
+      if (alreadyCreated) {
+        companyId = alreadyCreated;
+        resolvedExisting = true;
+      } else {
+        const matches = await searchCompaniesByName(name);
+        if (matches.length > 1) {
+          return {
+            operationId: operation.id,
+            status: "skipped",
+            detail: `create:${name} is ambiguous — ${matches.length} companies already named "${name}" (ids ${matches.join(", ")}). Link an explicit company id instead.`,
+          };
+        }
+        if (matches.length === 1) {
+          companyId = matches[0];
+          resolvedExisting = true;
+          createdCompaniesByName.set(nameKey, companyId);
+        } else {
+          const created = await request(`/crm/v3/objects/companies`, {
+            method: "POST",
+            body: JSON.stringify({ properties: { name } }),
+          });
+          companyId = String(created.id);
+          createdCompanyName = name;
+          createdCompaniesByName.set(nameKey, companyId);
+        }
+      }
+    }
     await request(
       `/crm/v4/objects/${fromPath}/${encodeURIComponent(operation.objectId)}/associations/default/companies/${encodeURIComponent(companyId)}`,
       { method: "PUT" },
@@ -391,11 +436,28 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     return {
       operationId: operation.id,
       status: "applied",
-      detail: `Linked ${fromPath}/${operation.objectId} to company ${companyId}.`,
-      providerData: { companyId },
+      detail: createdCompanyName
+        ? `Created company "${createdCompanyName}" (${companyId}) and linked ${fromPath}/${operation.objectId} to it.`
+        : resolvedExisting
+          ? `Linked ${fromPath}/${operation.objectId} to existing company ${companyId} (resolved by name, nothing created).`
+          : `Linked ${fromPath}/${operation.objectId} to company ${companyId}.`,
+      providerData: { companyId, ...(createdCompanyName ? { createdCompany: true } : {}) },
     };
   }
 
+  /** Exact-name company lookup for resolve-first creates. Returns matching ids (max 3 fetched). */
+  async function searchCompaniesByName(name: string): Promise<string[]> {
+    const data = await request(`/crm/v3/objects/companies/search`, {
+      method: "POST",
+      body: JSON.stringify({
+        filterGroups: [{ filters: [{ propertyName: "name", operator: "EQ", value: name }] }],
+        properties: ["name"],
+        limit: 3,
+      }),
+    });
+    return ((data?.results ?? []) as Array<{ id: string }>).map((row) => String(row.id));
+  }
+
   async function createTask(operation: PatchOperation): Promise<PatchOperationResult> {
     const associationTypeId = TASK_ASSOCIATION_TYPE_IDS[operation.objectType];
     if (associationTypeId === undefined) {
@@ -406,7 +468,33 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
       };
     }
     const subject = operation.field ? humanizeField(operation.field) : "Follow up";
-    const body = String(operation.afterValue ?? operation.reason ?? "");
+    // The operation id doubles as an idempotency token: it is stamped into
+    // the task body and pre-checked so a replayed plan does not create the
+    // same task twice. Fail-open — a search hiccup must not block the apply.
+    const token = `fsgtm ${operation.id.replace(/^op_/, "")}`;
+    try {
+      const existing = await request(`/crm/v3/objects/tasks/search`, {
+        method: "POST",
+        body: JSON.stringify({
+          filterGroups: [
+            { filters: [{ propertyName: "hs_task_body", operator: "CONTAINS_TOKEN", value: token.split(" ")[1] }] },
+          ],
+          limit: 1,
+        }),
+      });
+      const hit = (existing?.results ?? [])[0] as { id?: string } | undefined;
+      if (hit?.id) {
+        return {
+          operationId: operation.id,
+          status: "skipped",
+          detail: `Task for this operation already exists (task ${hit.id}); not creating a duplicate.`,
+          providerData: { id: hit.id, existing: true },
+        };
+      }
+    } catch {
+      // fall through to create
+    }
+    const body = `${String(operation.afterValue ?? operation.reason ?? "")}\n\n[${token}]`;
     const response = await request(`/crm/v3/objects/tasks`, {
       method: "POST",
       body: JSON.stringify({
@@ -501,6 +589,15 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     if (!objectPath || !mappingType) {
       throw new Error(`Field reads are only supported for accounts, contacts, and deals.`);
     }
+    // accountId is an association in HubSpot, not a property — without this
+    // branch the compare-and-set on link_record reads null and passes blind.
+    if (field === "accountId" && (objectType === "deal" || objectType === "contact")) {
+      const data = await request(
+        `/crm/v4/objects/${objectPath}/${encodeURIComponent(objectId)}/associations/companies?limit=1`,
+      );
+      const first = (data?.results ?? [])[0] as { toObjectId?: number | string } | undefined;
+      return first?.toObjectId !== undefined ? String(first.toObjectId) : null;
+    }
     const defaults = HUBSPOT_DEFAULT_FIELD_MAPPINGS[mappingType] ?? {};
     const property = mappedField(mappings, mappingType, field, defaults[field] ?? field);
     const data = await request(

package/src/connectors/hubspotAuth.ts

@@ -63,8 +63,12 @@ export async function validateHubspotToken(
   if (response.ok) {
     return { ok: true, detail: "Token accepted by the HubSpot CRM API." };
   }
-  const body = await response.text();
-  return { ok: false, detail: `HubSpot rejected the token (${response.status}): ${body}` };
+  // Never echo the response body: provider error payloads can reflect request
+  // details and end up in logs or shell scrollback.
+  return {
+    ok: false,
+    detail: `HubSpot rejected the token: HTTP ${response.status} ${response.statusText}`.trim(),
+  };
 }
 
 async function tokenRequest(

package/src/connectors/salesforce.ts

@@ -63,6 +63,8 @@ export function createSalesforceConnector(
   const apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
   const fetchImpl = options.fetchImpl ?? fetch;
   const mappings = options.fieldMappings;
+  // create:<Name> dedup within one connector lifetime (one apply run).
+  const createdAccountsByName = new Map<string, string>();
 
   async function request(path: string, init: RequestInit = {}): Promise<any> {
     const connection = await options.getConnection();
@@ -318,11 +320,29 @@ export function createSalesforceConnector(
         detail: "Tasks can be attached to accounts, contacts, and deals.",
       };
     }
+    // Idempotency: the operation id is stamped into the Description and
+    // pre-checked, so replaying a plan does not duplicate tasks. Fail-open.
+    const token = `fsgtm:${operation.id}`;
+    try {
+      const existing = await query(
+        `SELECT Id FROM Task WHERE Description LIKE '%${token.replace(/'/g, "\\'")}%' LIMIT 1`,
+      );
+      if (existing.length > 0) {
+        return {
+          operationId: operation.id,
+          status: "skipped",
+          detail: `Task for this operation already exists (task ${existing[0].Id}); not creating a duplicate.`,
+          providerData: { id: String(existing[0].Id), existing: true },
+        };
+      }
+    } catch {
+      // fall through to create
+    }
     const response = await request(`/services/data/${apiVersion}/sobjects/Task`, {
       method: "POST",
       body: JSON.stringify({
         Subject: operation.field ? humanizeField(operation.field) : "Follow up",
-        Description: String(operation.afterValue ?? operation.reason ?? ""),
+        Description: `${String(operation.afterValue ?? operation.reason ?? "")}\n\n[${token}]`,
         Status: "Not Started",
         Priority: "Normal",
         ...reference,
@@ -363,8 +383,56 @@ export function createSalesforceConnector(
         case "clear_field":
           // link_record on a deal is just setting AccountId in Salesforce.
           return await setField(operation);
-        case "link_record":
+        case "link_record": {
+          // `create:<Name>` is resolve-first: link to an unambiguous existing
+          // Account, refuse on ambiguity, create only on a confirmed miss —
+          // and never create the same name twice within one apply run.
+          const value = String(operation.afterValue ?? "");
+          if (value.startsWith("create:")) {
+            const name = value.slice("create:".length).trim();
+            if (!name) {
+              return { operationId: operation.id, status: "skipped", detail: "create: needs an account name (create:<Name>)." };
+            }
+            const nameKey = name.toLowerCase();
+            let accountId = createdAccountsByName.get(nameKey);
+            let createdNew = false;
+            if (!accountId) {
+              const soqlName = name.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+              const matches = await query(
+                `SELECT Id FROM Account WHERE Name = '${soqlName}' LIMIT 3`,
+              );
+              if (matches.length > 1) {
+                return {
+                  operationId: operation.id,
+                  status: "skipped",
+                  detail: `create:${name} is ambiguous — ${matches.length} accounts already named "${name}". Link an explicit account id instead.`,
+                };
+              }
+              if (matches.length === 1) {
+                accountId = String(matches[0].Id);
+              } else {
+                const created = await request(`/services/data/${apiVersion}/sobjects/Account`, {
+                  method: "POST",
+                  body: JSON.stringify({ Name: name }),
+                });
+                accountId = String(created.id);
+                createdNew = true;
+              }
+              createdAccountsByName.set(nameKey, accountId);
+            }
+            const result = await setField({ ...operation, operation: "set_field", afterValue: accountId });
+            return result.status === "applied"
+              ? {
+                  ...result,
+                  detail: createdNew
+                    ? `Created account "${name}" (${accountId}) and linked ${operation.objectType}/${operation.objectId} to it.`
+                    : `Linked ${operation.objectType}/${operation.objectId} to existing account ${accountId} (resolved by name, nothing created).`,
+                  providerData: { accountId, ...(createdNew ? { createdAccount: true } : {}) },
+                }
+              : result;
+          }
           return await setField({ ...operation, operation: "set_field" });
+        }
         case "create_task":
           return await createTask(operation);
         case "archive_record":

package/src/connectors/salesforceAuth.ts

@@ -155,13 +155,26 @@ export async function validateSalesforceToken(
   instanceUrl: string,
   fetchImpl: typeof fetch = fetch,
 ): Promise<{ ok: boolean; detail: string }> {
-  const response = await fetchImpl(
-    `${instanceUrl.replace(/\/$/, "")}/services/oauth2/userinfo`,
-    { headers: { Authorization: `Bearer ${accessToken}` } },
-  );
+  let response: Response;
+  try {
+    response = await fetchImpl(
+      `${instanceUrl.replace(/\/$/, "")}/services/oauth2/userinfo`,
+      { headers: { Authorization: `Bearer ${accessToken}` } },
+    );
+  } catch (error) {
+    const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+    return {
+      ok: false,
+      detail: `Cannot reach Salesforce at ${instanceUrl}${cause}. Check the --instance-url (your My Domain URL, e.g. https://yourco.my.salesforce.com) and network access.`,
+    };
+  }
   if (response.ok) {
     return { ok: true, detail: "Token accepted by the Salesforce API." };
   }
-  const body = await response.text();
-  return { ok: false, detail: `Salesforce rejected the token (${response.status}): ${body}` };
+  // Never echo the response body: provider error payloads can reflect request
+  // details and end up in logs or shell scrollback.
+  return {
+    ok: false,
+    detail: `Salesforce rejected the token: HTTP ${response.status} ${response.statusText}`.trim(),
+  };
 }

package/src/credentials.ts

@@ -2,6 +2,7 @@ import {
   chmodSync,
   existsSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   unlinkSync,
   writeFileSync,
@@ -15,8 +16,63 @@ import { refreshSalesforceToken } from "./connectors/salesforceAuth.ts";
  * Local CLI credential store: ~/.fullstackgtm/credentials.json (0600), or
  * $FSGTM_HOME/credentials.json when set. Environment tokens always win over
  * stored credentials so CI and agent sandboxes never touch the filesystem.
+ *
+ * Profiles let one operator hold credentials for several organizations at
+ * once (a consultant working across client CRMs). The default profile keeps
+ * the historical layout; a named profile scopes the entire home — credentials
+ * AND stored plans — under `profiles/<name>/`, so a patch plan proposed
+ * against one client's CRM can never be applied through another client's
+ * credentials.
  */
 
+export const DEFAULT_PROFILE = "default";
+
+const PROFILE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+let explicitProfile: string | null = null;
+
+export function validateProfileName(name: string): string {
+  if (!PROFILE_NAME_PATTERN.test(name) || name === "." || name === "..") {
+    throw new Error(
+      `Invalid profile name: ${JSON.stringify(name)}. Use letters, numbers, dots, dashes, ` +
+        "or underscores (must start with a letter or number, max 64 characters).",
+    );
+  }
+  return name;
+}
+
+/** Select the profile for this process; wins over $FULLSTACKGTM_PROFILE. */
+export function setActiveProfile(name: string) {
+  explicitProfile = validateProfileName(name);
+}
+
+export function activeProfile(): string {
+  if (explicitProfile) return explicitProfile;
+  const fromEnv = process.env.FULLSTACKGTM_PROFILE;
+  return fromEnv ? validateProfileName(fromEnv) : DEFAULT_PROFILE;
+}
+
+/** Base home directory, shared by every profile. */
+export function baseHomeDir(): string {
+  return process.env.FSGTM_HOME ?? join(homedir(), ".fullstackgtm");
+}
+
+/**
+ * Profiles that exist on disk (have a directory), always including the
+ * default profile. Existence does not imply stored credentials.
+ */
+export function listProfiles(): string[] {
+  const names = new Set([DEFAULT_PROFILE]);
+  try {
+    for (const entry of readdirSync(join(baseHomeDir(), "profiles"), { withFileTypes: true })) {
+      if (entry.isDirectory() && PROFILE_NAME_PATTERN.test(entry.name)) names.add(entry.name);
+    }
+  } catch {
+    // No profiles directory yet.
+  }
+  return Array.from(names).sort();
+}
+
 export type StoredCredential = {
   kind: "private_app" | "oauth" | "broker";
   accessToken: string;
@@ -43,7 +99,9 @@ type CredentialsFile = {
 };
 
 export function credentialsDir(): string {
-  return process.env.FSGTM_HOME ?? join(homedir(), ".fullstackgtm");
+  const base = baseHomeDir();
+  const profile = activeProfile();
+  return profile === DEFAULT_PROFILE ? base : join(base, "profiles", profile);
 }
 
 export function credentialsPath(): string {
@@ -59,11 +117,18 @@ export function credentialsPath(): string {
  */
 export function ensureSecureHomeDir(): string {
   const dir = credentialsDir();
-  mkdirSync(dir, { recursive: true, mode: 0o700 });
-  try {
-    chmodSync(dir, 0o700);
-  } catch {
-    // Non-POSIX filesystems (e.g. Windows) ignore chmod; nothing to enforce.
+  // A named profile nests under base/profiles/<name>; lock down every level
+  // we create, not just the leaf — recursive mkdir applies `mode` (less
+  // umask) only to directories it creates, and never to pre-existing ones.
+  const levels =
+    dir === baseHomeDir() ? [dir] : [baseHomeDir(), join(baseHomeDir(), "profiles"), dir];
+  for (const level of levels) {
+    mkdirSync(level, { recursive: true, mode: 0o700 });
+    try {
+      chmodSync(level, 0o700);
+    } catch {
+      // Non-POSIX filesystems (e.g. Windows) ignore chmod; nothing to enforce.
+    }
   }
   return dir;
 }

package/src/index.ts

@@ -34,12 +34,16 @@ export {
 } from "./connectors/salesforceAuth.ts";
 export { createStripeConnector, type StripeConnectorOptions } from "./connectors/stripe.ts";
 export {
+  activeProfile,
   credentialsDir,
   credentialsPath,
+  DEFAULT_PROFILE,
   deleteCredential,
   getCredential,
+  listProfiles,
   resolveHubspotAccessToken,
   resolveHubspotConnection,
+  setActiveProfile,
   storeCredential,
   type HubspotConnection,
   type StoredCredential,
@@ -64,6 +68,7 @@ export {
 } from "./merge.ts";
 export { createFilePlanStore, type PlanStore, type StoredPlan } from "./planStore.ts";
 export { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
+export { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./report.ts";
 export {
   HUBSPOT_DEFAULT_FIELD_MAPPINGS,
   SALESFORCE_DEFAULT_FIELD_MAPPINGS,
@@ -83,6 +88,7 @@ export {
   closingSoonInactiveRule,
   duplicateAccountDomainRule,
   duplicateContactEmailRule,
+  duplicateOpenDealRule,
   missingDealAccountRule,
   missingDealAmountRule,
   missingDealOwnerRule,
@@ -93,6 +99,7 @@ export {
   staleDealRule,
 } from "./rules.ts";
 export { sampleSnapshot } from "./sampleData.ts";
+export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export type {
   ApprovalStatus,
   AuditFinding,

package/src/mcp.ts

@@ -46,6 +46,7 @@ import type { FieldMappings } from "./mappings.ts";
 import { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
 import { builtinAuditRules } from "./rules.ts";
 import { sampleSnapshot } from "./sampleData.ts";
+import { suggestValues } from "./suggest.ts";
 import type { CanonicalGtmSnapshot, GtmConnector, PatchPlan } from "./types.ts";
 
 function content(value: unknown) {
@@ -166,6 +167,27 @@ export async function startMcpServer() {
     },
   );
 
+  server.registerTool(
+    "fullstackgtm_suggest",
+    {
+      title: "Suggest Placeholder Values",
+      description:
+        "Derive values for a plan's requires_human_* placeholder operations from snapshot " +
+        "evidence (account-name matching, contact associations), with confidence levels and " +
+        "reasons. Read-only; feed accepted values into fullstackgtm_apply's valueOverrides.",
+      inputSchema: {
+        planPath: z.string(),
+        provider: z.enum(["sample", "demo", "hubspot", "salesforce", "stripe"]).optional(),
+        inputPath: z.string().optional(),
+      },
+    },
+    async ({ planPath, provider, inputPath }) => {
+      const plan = JSON.parse(readFileSync(resolve(process.cwd(), planPath), "utf8")) as PatchPlan;
+      const snapshot = await readSnapshot(provider, inputPath);
+      return content({ suggestions: suggestValues(plan, snapshot) });
+    },
+  );
+
   server.registerTool(
     "fullstackgtm_rules",
     {

package/src/merge.ts

@@ -55,7 +55,7 @@ const CONFLICT_IGNORED_FIELDS = new Set([
   "id", "provider", "crmId", "identities", "raw", "lastSyncAt", "lastActivityAt", "ownerId", "accountId",
 ]);
 
-function normalizeDomain(domain?: string): string | undefined {
+export function normalizeDomain(domain?: string): string | undefined {
   if (!domain) return undefined;
   return domain.trim().toLowerCase().replace(/^https?:\/\//, "").replace(/^www\./, "").replace(/\/.*$/, "") || undefined;
 }