fullstackgtm 0.10.0 → 0.11.0

package/src/cli.ts

@@ -19,11 +19,15 @@ import {
   validateSalesforceToken,
 } from "./connectors/salesforceAuth.ts";
 import {
+  activeProfile,
   credentialsPath,
+  DEFAULT_PROFILE,
   deleteCredential,
   getCredential,
+  listProfiles,
   resolveHubspotConnection,
   resolveSalesforceConnection,
+  setActiveProfile,
   storeCredential,
   type StoredCredential,
 } from "./credentials.ts";
@@ -31,8 +35,10 @@ import { generateDemoSnapshot } from "./demo.ts";
 import { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
 import { mergeSnapshots } from "./merge.ts";
 import { createFilePlanStore } from "./planStore.ts";
+import { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./report.ts";
 import { builtinAuditRules } from "./rules.ts";
 import { sampleSnapshot } from "./sampleData.ts";
+import { suggestValues, type ValueSuggestion } from "./suggest.ts";
 import type { FieldMappings } from "./mappings.ts";
 import type {
   AuditFindingSeverity,
@@ -60,14 +66,28 @@ Usage:
     echo "$HUBSPOT_TOKEN" | fullstackgtm login hubspot
   fullstackgtm snapshot [source options] [--since <iso>] [--out <path> | --archive <dir>]
   fullstackgtm audit [source options] [audit options] [--save]
+  fullstackgtm report [source options] [audit options] [report options]
   fullstackgtm diff --before <a.json> --after <b.json> [--json] [--fail-on-new-findings]
   fullstackgtm merge --input <a.json> --input <b.json> [...] --out <merged.json> [--json]
-  fullstackgtm plans list [--status <s>] | show <id> | approve <id> --operations <ids|all> | reject <id>
+  fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
+                                               derive values for requires_human_* placeholders
+                                               from snapshot evidence, with confidence + reasons
+  fullstackgtm plans list [--status <s>] | show <id> | reject <id>
+  fullstackgtm plans approve <id> --operations <ids|all> [--value <opId>=<v>]
+  fullstackgtm plans approve <id> --values-from <suggestions.json> [--min-confidence high|low] [--include-creates]
   fullstackgtm apply --plan-id <id> --provider <name>
   fullstackgtm apply --plan <path> --provider <name> --approve <ids|all> [options]
   fullstackgtm rules [--json]
+  fullstackgtm profiles [--json]               list credential profiles
   fullstackgtm doctor [--json]                 check install, credentials, and next step
 
+Profiles (multi-organization use):
+  --profile <name>       Scope credentials AND stored plans to a named profile
+                         (also: FULLSTACKGTM_PROFILE). One profile per client
+                         org keeps logins isolated and prevents a plan proposed
+                         against one CRM from being applied through another's
+                         credentials. Omitted = the default profile.
+
 Plan lifecycle:
   audit --save persists the dry-run plan to ~/.fullstackgtm/plans. Approve
   specific operations (optionally with --value <opId>=<v> for placeholders),
@@ -104,6 +124,17 @@ Audit options:
   --stale-days <n>       Days without activity before an open deal is stale
   --fail-on <severity>   Exit 2 if any finding is at or above info|warning|critical
 
+Report options (report renders the audit as a client-ready deliverable):
+  --plan <path>          Render an existing plan JSON instead of re-auditing
+                         (add --input <snapshot.json> for record counts)
+  --client <name>        Organization name shown in the heading and summary
+  --title <text>         Report heading (default "GTM Data Health Report")
+  --prepared-by <name>   Attribution shown in the footer
+  --format <fmt>         markdown (default) or html (self-contained, printable;
+                         inferred from an --out path ending in .html)
+  --max-examples <n>     Example records listed per rule (default 10)
+  --out <path>           Write the report to a file instead of stdout
+
 Apply options:
   --plan <path>          Patch plan JSON produced by \`audit --out\`
   --provider hubspot     Connector to apply through
@@ -157,7 +188,7 @@ async function hubspotConnection(args: string[]) {
   const stored = await resolveHubspotConnection();
   if (stored) return stored;
   throw new Error(
-    "No HubSpot credentials. Run `fullstackgtm login hubspot`, pair with a hosted deployment via `fullstackgtm login --via <url>`, or set HUBSPOT_ACCESS_TOKEN.",
+    "No HubSpot credentials. Run `fullstackgtm login hubspot`, pair with a hosted deployment via `fullstackgtm login --via <url>`, or set HUBSPOT_ACCESS_TOKEN. (`fullstackgtm doctor` shows credential status; see the README's \"Connect your CRM\" section for the private-app scopes to grant.)",
   );
 }
 
@@ -171,7 +202,7 @@ async function salesforceConnection() {
   const stored = await resolveSalesforceConnection();
   if (stored) return stored;
   throw new Error(
-    "No Salesforce credentials. Run `fullstackgtm login salesforce`, pair with a hosted deployment via `fullstackgtm login --via <url>`, or set SALESFORCE_ACCESS_TOKEN and SALESFORCE_INSTANCE_URL.",
+    "No Salesforce credentials. Run `fullstackgtm login salesforce`, pair with a hosted deployment via `fullstackgtm login --via <url>`, or set SALESFORCE_ACCESS_TOKEN and SALESFORCE_INSTANCE_URL. (`fullstackgtm doctor` shows credential status; device-flow login needs an admin-created Connected App — see the README's \"Connect your CRM\" section.)",
   );
 }
 
@@ -198,7 +229,7 @@ async function connectorFor(provider: string, args: string[]): Promise<GtmConnec
       process.env.STRIPE_SECRET_KEY ?? getCredential("stripe")?.accessToken;
     if (!key) {
       throw new Error(
-        "No Stripe credentials. Run `fullstackgtm login stripe --token sk_...` or set STRIPE_SECRET_KEY.",
+        "No Stripe credentials. Run `echo \"$STRIPE_KEY\" | fullstackgtm login stripe` or set STRIPE_SECRET_KEY. A restricted key with read access to Customers and Subscriptions is enough. (`fullstackgtm doctor` shows credential status.)",
       );
     }
     return createStripeConnector({ getApiKey: () => key });
@@ -334,6 +365,64 @@ async function audit(args: string[]) {
   }
 }
 
+/**
+ * Render an audit as a client-facing deliverable. Same sources and audit
+ * options as `audit`; `--plan` instead renders an existing plan JSON without
+ * re-fetching (useful for a plan produced earlier or by another machine).
+ */
+async function reportCommand(args: string[]) {
+  const loaded = loadConfig(option(args, "--config") ?? undefined);
+  const configuredRules = await resolveConfiguredRules(loaded);
+
+  let plan: PatchPlan;
+  let snapshot: CanonicalGtmSnapshot | undefined;
+  const planPath = option(args, "--plan");
+  if (planPath) {
+    plan = JSON.parse(readFileSync(resolve(process.cwd(), planPath), "utf8")) as PatchPlan;
+    const input = option(args, "--input");
+    if (input) {
+      snapshot = JSON.parse(
+        readFileSync(resolve(process.cwd(), input), "utf8"),
+      ) as CanonicalGtmSnapshot;
+    }
+  } else {
+    snapshot = await readSnapshot(args);
+    const policy = mergePolicy(defaultPolicy(), loaded?.config);
+    const today = option(args, "--today");
+    if (today) policy.today = today;
+    const staleDealDays = numericOption(args, "--stale-days");
+    if (staleDealDays !== undefined) policy.staleDealDays = staleDealDays;
+    plan = auditSnapshot(snapshot, policy, selectedRules(args, configuredRules));
+  }
+
+  const reportOptions: ReportOptions = {
+    title: option(args, "--title") ?? undefined,
+    clientName: option(args, "--client") ?? undefined,
+    preparedBy: option(args, "--prepared-by") ?? undefined,
+    date: option(args, "--today") ?? undefined,
+    maxExamplesPerRule: numericOption(args, "--max-examples"),
+    rules: configuredRules,
+    snapshot,
+  };
+
+  const out = option(args, "--out");
+  const format = option(args, "--format") ?? (out?.endsWith(".html") ? "html" : "markdown");
+  if (format !== "markdown" && format !== "html") {
+    throw new Error("--format must be markdown or html");
+  }
+  const rendered =
+    format === "html"
+      ? auditReportToHtml(plan, reportOptions)
+      : auditReportToMarkdown(plan, reportOptions);
+
+  if (out) {
+    writeFileSync(resolve(process.cwd(), out), rendered);
+    console.log(`Wrote ${format} report (${plan.findings.length} findings) to ${out}`);
+  } else {
+    console.log(rendered.trimEnd());
+  }
+}
+
 async function rulesCommand(args: string[]) {
   const loaded = loadConfig(option(args, "--config") ?? undefined);
   const rules = await resolveConfiguredRules(loaded);
@@ -376,6 +465,83 @@ function parseValueOverrides(args: string[]) {
   return valueOverrides;
 }
 
+async function suggest(args: string[]) {
+  const planId = option(args, "--plan-id");
+  const planPath = option(args, "--plan");
+  if (!planId && !planPath) throw new Error("suggest requires --plan <path> or --plan-id <id>");
+  let plan: PatchPlan;
+  if (planId) {
+    const stored = await createFilePlanStore().get(planId);
+    if (!stored) throw new Error(`No stored plan with id ${planId}.`);
+    plan = stored.plan;
+  } else {
+    plan = JSON.parse(readFileSync(resolve(process.cwd(), planPath!), "utf8")) as PatchPlan;
+  }
+
+  const snapshot = await readSnapshot(args);
+  const suggestions = suggestValues(plan, snapshot);
+  const payload = { planId: planId ?? planPath, suggestions };
+
+  const outPath = option(args, "--out");
+  if (outPath) writeFileSync(resolve(process.cwd(), outPath), `${JSON.stringify(payload, null, 2)}\n`);
+
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (suggestions.length === 0) {
+    console.log("No requires_human_* placeholder operations in this plan — nothing to suggest.");
+    return;
+  }
+  const byConfidence: Record<string, number> = {};
+  for (const s of suggestions) byConfidence[s.confidence] = (byConfidence[s.confidence] ?? 0) + 1;
+  console.log(`Suggestions for ${suggestions.length} placeholder operation(s):\n`);
+  for (const s of suggestions) {
+    const marker =
+      s.confidence === "high" ? "✓" : s.confidence === "low" ? "~" : s.confidence === "create" ? "+" : "✗";
+    console.log(`${marker} [${s.confidence}] ${s.operationId} ${s.objectName ?? s.objectId}`);
+    console.log(`    ${s.suggestedValue ? `→ ${s.suggestedValue}` : "(no suggestion)"} — ${s.reason}`);
+  }
+  console.log(`\n${Object.entries(byConfidence).map(([k, v]) => `${k}: ${v}`).join(" · ")}`);
+  if (planId && (byConfidence.high ?? 0) > 0 && !outPath) {
+    console.log(
+      `\nChain it:\n  fullstackgtm suggest --plan-id ${planId} ${snapshotSourceHint(args)}--out suggestions.json\n  fullstackgtm plans approve ${planId} --values-from suggestions.json\n  fullstackgtm apply --plan-id ${planId} --provider <name>`,
+    );
+  }
+}
+
+function snapshotSourceHint(args: string[]) {
+  const provider = option(args, "--provider");
+  if (provider) return `--provider ${provider} `;
+  const input = option(args, "--input");
+  if (input) return `--input ${input} `;
+  return "";
+}
+
+function readSuggestionValues(path: string, minConfidence: string, includeCreates: boolean) {
+  const raw = JSON.parse(readFileSync(resolve(process.cwd(), path), "utf8")) as {
+    suggestions?: ValueSuggestion[];
+  };
+  if (!Array.isArray(raw.suggestions)) {
+    throw new Error(
+      `${path} is not a suggestions file (expected { suggestions: [...] } from \`fullstackgtm suggest --out\`).`,
+    );
+  }
+  const accepted = new Set(minConfidence === "low" ? ["high", "low"] : ["high"]);
+  const overrides: Record<string, string> = {};
+  let skipped = 0;
+  for (const s of raw.suggestions) {
+    if (!s.suggestedValue) continue;
+    if (accepted.has(s.confidence) || (includeCreates && s.confidence === "create")) {
+      overrides[s.operationId] = s.suggestedValue;
+    } else {
+      skipped += 1;
+    }
+  }
+  return { overrides, skipped };
+}
+
 async function apply(args: string[]) {
   const provider = option(args, "--provider");
   if (!provider) throw new Error("apply requires --provider <name>");
@@ -565,16 +731,50 @@ async function plansCommand(args: string[]) {
 
   if (subcommand === "approve") {
     const planId = rest.find((arg) => !arg.startsWith("--") && !isOptionValue(rest, arg));
-    if (!planId) throw new Error("Usage: fullstackgtm plans approve <planId> --operations <ids|all>");
+    if (!planId) throw new Error("Usage: fullstackgtm plans approve <planId> --operations <ids|all> | --values-from <suggestions.json>");
     const operations = option(rest, "--operations");
-    if (!operations) throw new Error("plans approve requires --operations <ids|all>");
+    const valuesFrom = option(rest, "--values-from");
+    if (!operations && !valuesFrom) {
+      throw new Error("plans approve requires --operations <ids|all> and/or --values-from <suggestions.json>");
+    }
     const stored = await store.get(planId);
     if (!stored) throw new Error(`No stored plan with id ${planId}.`);
+
+    // Values from a `fullstackgtm suggest --out` file. High-confidence only by
+    // default; widen with --min-confidence low, opt into record-creating
+    // values (create:<Name>) with --include-creates. Explicit --value wins.
+    let fileOverrides: Record<string, string> = {};
+    if (valuesFrom) {
+      const minConfidence = option(rest, "--min-confidence") ?? "high";
+      if (!["high", "low"].includes(minConfidence)) {
+        throw new Error("--min-confidence must be high or low");
+      }
+      const { overrides, skipped } = readSuggestionValues(
+        valuesFrom,
+        minConfidence,
+        rest.includes("--include-creates"),
+      );
+      fileOverrides = overrides;
+      if (Object.keys(overrides).length === 0) {
+        throw new Error(
+          `No suggestions in ${valuesFrom} meet the confidence bar (${skipped} below it). Re-run with --min-confidence low or --include-creates, or pass explicit --value overrides.`,
+        );
+      }
+      if (skipped > 0) {
+        console.log(`Skipped ${skipped} suggestion(s) below the confidence bar (widen with --min-confidence low / --include-creates).`);
+      }
+    }
+    const explicitOverrides = parseValueOverrides(rest);
     const operationIds =
       operations === "all"
         ? stored.plan.operations.map((operation) => operation.id)
-        : operations.split(",").map((id) => id.trim()).filter(Boolean);
-    const updated = await store.approveOperations(planId, operationIds, parseValueOverrides(rest));
+        : operations
+          ? operations.split(",").map((id) => id.trim()).filter(Boolean)
+          : Object.keys(fileOverrides);
+    const updated = await store.approveOperations(planId, operationIds, {
+      ...fileOverrides,
+      ...explicitOverrides,
+    });
     console.log(
       `Approved ${updated.approvedOperationIds.length} operation(s) on ${planId}. Apply with \`fullstackgtm apply --plan-id ${planId} --provider <name>\`.`,
     );
@@ -656,11 +856,17 @@ async function brokerLogin(baseUrl: string) {
   // Self-reported, shown to the approver so they can recognize this request
   // and refuse one they didn't initiate.
   const requesterLabel = `${os.hostname()} (${process.platform}, ${os.userInfo().username})`;
-  const startResponse = await fetch(`${base}/api/cli/auth/start`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ requesterLabel }),
-  });
+  let startResponse: Response;
+  try {
+    startResponse = await fetch(`${base}/api/cli/auth/start`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ requesterLabel }),
+    });
+  } catch (error) {
+    const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+    throw new Error(`Cannot reach the hosted deployment at ${base}${cause}. Check the --via URL and network access.`);
+  }
   if (!startResponse.ok) {
     throw new Error(
       `Could not start pairing with ${base} (${startResponse.status}). Is this a FullStackGTM deployment?`,
@@ -926,6 +1132,7 @@ export function doctorReport(env: Record<string, string | undefined> = process.e
   return {
     package: packageInfo,
     node: { version: process.versions.node, ok: nodeMajor >= 20, required: ">=20" },
+    profile: activeProfile(),
     credentialStore: { path: storePath, exists: existsSync(storePath) },
     config: { path: configPath, exists: existsSync(configPath) },
     providers,
@@ -967,6 +1174,7 @@ function doctorCommand(args: string[]) {
   const lines = [
     `Package:    ${report.package.name} ${report.package.version}`,
     `Node:       v${report.node.version} (${report.node.required} required) ${mark(report.node.ok)}`,
+    `Profile:    ${report.profile}${report.profile === DEFAULT_PROFILE ? "" : " (named profile — credentials and plans are scoped to it)"}`,
     `Cred store: ${report.credentialStore.path} (${report.credentialStore.exists ? "present" : "not created yet — created on first login"})`,
     `Config:     ${report.config.exists ? report.config.path : "none — defaults apply"}`,
     "",
@@ -987,12 +1195,49 @@ function doctorCommand(args: string[]) {
   if (!report.node.ok) process.exitCode = 1;
 }
 
+/**
+ * Pull the global `--profile <name>` flag out of argv (it may appear before
+ * or after the command) and activate it. Stripping it keeps positional
+ * detection in subcommands — `login <provider>`, `plans show <id>` — simple.
+ */
+function extractProfile(argv: string[]): string[] {
+  const index = argv.indexOf("--profile");
+  if (index === -1) return argv;
+  const name = argv[index + 1];
+  if (!name) throw new Error("--profile requires a name, e.g. --profile acme");
+  setActiveProfile(name);
+  return [...argv.slice(0, index), ...argv.slice(index + 2)];
+}
+
+function profilesCommand(args: string[]) {
+  const profiles = listProfiles();
+  const current = activeProfile();
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({ active: current, profiles }, null, 2));
+    return;
+  }
+  for (const profile of profiles) {
+    console.log(`${profile === current ? "*" : " "} ${profile}`);
+  }
+  if (!profiles.includes(current)) {
+    console.log(`* ${current} (selected; created on first login)`);
+  }
+  console.log(
+    "\nSelect with --profile <name> on any command, or set FULLSTACKGTM_PROFILE. " +
+      "Each profile keeps its own credentials and stored plans.",
+  );
+}
+
 export async function runCli(argv: string[]) {
-  const [command, ...args] = argv;
+  const [command, ...args] = extractProfile(argv);
   if (!command || command === "--help" || command === "-h") {
     console.log(usage());
     return;
   }
+  if (command === "--version" || command === "-v" || command === "version") {
+    console.log(readPackageInfo().version);
+    return;
+  }
 
   if (command === "login") {
     await login(args);
@@ -1010,6 +1255,10 @@ export async function runCli(argv: string[]) {
     await audit(args);
     return;
   }
+  if (command === "report") {
+    await reportCommand(args);
+    return;
+  }
   if (command === "rules") {
     await rulesCommand(args);
     return;
@@ -1018,6 +1267,14 @@ export async function runCli(argv: string[]) {
     doctorCommand(args);
     return;
   }
+  if (command === "suggest") {
+    await suggest(args);
+    return;
+  }
+  if (command === "profiles") {
+    profilesCommand(args);
+    return;
+  }
   if (command === "diff") {
     await diffCommand(args);
     return;

package/src/connectors/hubspot.ts

@@ -57,14 +57,20 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
 
   async function request(path: string, init: RequestInit = {}): Promise<any> {
     const token = await options.getAccessToken();
-    const response = await fetchImpl(`${baseUrl}${path}`, {
-      ...init,
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "Content-Type": "application/json",
-        ...(init.headers ?? {}),
-      },
-    });
+    let response: Response;
+    try {
+      response = await fetchImpl(`${baseUrl}${path}`, {
+        ...init,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+          ...(init.headers ?? {}),
+        },
+      });
+    } catch (error) {
+      const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+      throw new Error(`Cannot reach HubSpot at ${baseUrl}${cause}. Check network access.`);
+    }
     if (!response.ok) {
       const body = await response.text();
       throw new Error(`HubSpot API error ${response.status}: ${body}`);
@@ -374,10 +380,26 @@ 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>` creates the company first, then links — the approved
+    // value spells out exactly what will happen, so creation stays inside
+    // the typed, human-approved operation model.
+    let createdCompanyName: string | null = null;
+    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 created = await request(`/crm/v3/objects/companies`, {
+        method: "POST",
+        body: JSON.stringify({ properties: { name } }),
+      });
+      companyId = String(created.id);
+      createdCompanyName = name;
+    }
     await request(
       `/crm/v4/objects/${fromPath}/${encodeURIComponent(operation.objectId)}/associations/default/companies/${encodeURIComponent(companyId)}`,
       { method: "PUT" },
@@ -385,8 +407,10 @@ 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.`
+        : `Linked ${fromPath}/${operation.objectId} to company ${companyId}.`,
+      providerData: { companyId, ...(createdCompanyName ? { createdCompany: true } : {}) },
     };
   }
 

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(
@@ -212,6 +216,9 @@ export async function runHubspotLoopbackLogin(
 }
 
 export async function openInBrowser(url: string) {
+  // Headless contexts (agent sandboxes, CI, tests) suppress the OS browser;
+  // every flow that opens a URL also prints it for manual use.
+  if (process.env.FSGTM_NO_BROWSER) return;
   // The URL may come from an external source (e.g. a broker deployment's
   // verification URL). Only ever hand a well-formed http(s) URL to the OS
   // opener — this prevents a leading `-` from being read as a flag by

package/src/connectors/salesforce.ts

@@ -69,14 +69,22 @@ export function createSalesforceConnector(
     const url = path.startsWith("http")
       ? path
       : `${connection.instanceUrl.replace(/\/$/, "")}${path}`;
-    const response = await fetchImpl(url, {
-      ...init,
-      headers: {
-        Authorization: `Bearer ${connection.accessToken}`,
-        "Content-Type": "application/json",
-        ...(init.headers ?? {}),
-      },
-    });
+    let response: Response;
+    try {
+      response = await fetchImpl(url, {
+        ...init,
+        headers: {
+          Authorization: `Bearer ${connection.accessToken}`,
+          "Content-Type": "application/json",
+          ...(init.headers ?? {}),
+        },
+      });
+    } catch (error) {
+      const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+      throw new Error(
+        `Cannot reach Salesforce at ${connection.instanceUrl}${cause}. Check SALESFORCE_INSTANCE_URL (your My Domain URL, e.g. https://yourco.my.salesforce.com) and network access.`,
+      );
+    }
     if (!response.ok) {
       const body = await response.text();
       throw new Error(`Salesforce API error ${response.status}: ${body}`);
@@ -355,8 +363,26 @@ 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>` creates the Account first, then links — creation
+          // stays inside the typed, human-approved operation model.
+          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 created = await request(`/services/data/${apiVersion}/sobjects/Account`, {
+              method: "POST",
+              body: JSON.stringify({ Name: name }),
+            });
+            const result = await setField({ ...operation, operation: "set_field", afterValue: String(created.id) });
+            return result.status === "applied"
+              ? { ...result, detail: `Created account "${name}" (${created.id}) and linked ${operation.objectType}/${operation.objectId} to it.`, providerData: { accountId: String(created.id), 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(),
+  };
 }