fullstackgtm 0.10.0 → 0.11.0

package/dist/cli.js

@@ -9,13 +9,15 @@ import { DEFAULT_LOOPBACK_PORT, openInBrowser, runHubspotLoopbackLogin, validate
 import { createSalesforceConnector } from "./connectors/salesforce.js";
 import { createStripeConnector } from "./connectors/stripe.js";
 import { pollSalesforceDeviceLogin, startSalesforceDeviceLogin, validateSalesforceToken, } from "./connectors/salesforceAuth.js";
-import { credentialsPath, deleteCredential, getCredential, resolveHubspotConnection, resolveSalesforceConnection, storeCredential, } from "./credentials.js";
+import { activeProfile, credentialsPath, DEFAULT_PROFILE, deleteCredential, getCredential, listProfiles, resolveHubspotConnection, resolveSalesforceConnection, setActiveProfile, storeCredential, } from "./credentials.js";
 import { generateDemoSnapshot } from "./demo.js";
 import { formatPatchPlanRun, patchPlanToMarkdown } from "./format.js";
 import { mergeSnapshots } from "./merge.js";
 import { createFilePlanStore } from "./planStore.js";
+import { auditReportToHtml, auditReportToMarkdown } from "./report.js";
 import { builtinAuditRules } from "./rules.js";
 import { sampleSnapshot } from "./sampleData.js";
+import { suggestValues } from "./suggest.js";
 function usage() {
     return `FullStackGTM — audit GTM data across providers, propose reviewable patch plans,
 and apply only explicitly approved operations.
@@ -35,14 +37,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),
@@ -79,6 +95,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
@@ -132,7 +159,7 @@ async function hubspotConnection(args) {
     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.");
+    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. (`fullstackgtm doctor` shows credential status; see the README's \"Connect your CRM\" section for the private-app scopes to grant.)");
 }
 async function salesforceConnection() {
     if (process.env.SALESFORCE_ACCESS_TOKEN && process.env.SALESFORCE_INSTANCE_URL) {
@@ -144,7 +171,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.");
+    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. (`fullstackgtm doctor` shows credential status; device-flow login needs an admin-created Connected App — see the README's \"Connect your CRM\" section.)");
 }
 async function connectorFor(provider, args) {
     if (provider === "hubspot") {
@@ -164,7 +191,7 @@ async function connectorFor(provider, args) {
     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 --token sk_...` or set STRIPE_SECRET_KEY.");
+            throw new Error("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 });
     }
@@ -288,6 +315,60 @@ async function audit(args) {
         process.exitCode = 2;
     }
 }
+/**
+ * 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) {
+    const loaded = loadConfig(option(args, "--config") ?? undefined);
+    const configuredRules = await resolveConfiguredRules(loaded);
+    let plan;
+    let snapshot;
+    const planPath = option(args, "--plan");
+    if (planPath) {
+        plan = JSON.parse(readFileSync(resolve(process.cwd(), planPath), "utf8"));
+        const input = option(args, "--input");
+        if (input) {
+            snapshot = JSON.parse(readFileSync(resolve(process.cwd(), input), "utf8"));
+        }
+    }
+    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 = {
+        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) {
     const loaded = loadConfig(option(args, "--config") ?? undefined);
     const rules = await resolveConfiguredRules(loaded);
@@ -322,6 +403,78 @@ function parseValueOverrides(args) {
     }
     return valueOverrides;
 }
+async function suggest(args) {
+    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;
+    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"));
+    }
+    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 = {};
+    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) {
+    const provider = option(args, "--provider");
+    if (provider)
+        return `--provider ${provider} `;
+    const input = option(args, "--input");
+    if (input)
+        return `--input ${input} `;
+    return "";
+}
+function readSuggestionValues(path, minConfidence, includeCreates) {
+    const raw = JSON.parse(readFileSync(resolve(process.cwd(), path), "utf8"));
+    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 = {};
+    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) {
     const provider = option(args, "--provider");
     if (!provider)
@@ -484,17 +637,43 @@ async function plansCommand(args) {
     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>");
+            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 = {};
+        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>\`.`);
         return;
     }
@@ -566,11 +745,18 @@ async function brokerLogin(baseUrl) {
     // 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;
+    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?`);
     }
@@ -806,6 +992,7 @@ export function doctorReport(env = process.env) {
     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,
@@ -844,6 +1031,7 @@ function doctorCommand(args) {
     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"}`,
         "",
@@ -862,12 +1050,47 @@ function doctorCommand(args) {
     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) {
+    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) {
+    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) {
-    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);
         return;
@@ -884,6 +1107,10 @@ export async function runCli(argv) {
         await audit(args);
         return;
     }
+    if (command === "report") {
+        await reportCommand(args);
+        return;
+    }
     if (command === "rules") {
         await rulesCommand(args);
         return;
@@ -892,6 +1119,14 @@ export async function runCli(argv) {
         doctorCommand(args);
         return;
     }
+    if (command === "suggest") {
+        await suggest(args);
+        return;
+    }
+    if (command === "profiles") {
+        profilesCommand(args);
+        return;
+    }
     if (command === "diff") {
         await diffCommand(args);
         return;

package/dist/connectors/hubspot.js

@@ -24,14 +24,21 @@ export function createHubspotConnector(options) {
     const mappings = options.fieldMappings;
     async function request(path, init = {}) {
         const token = await options.getAccessToken();
-        const response = await fetchImpl(`${baseUrl}${path}`, {
-            ...init,
-            headers: {
-                Authorization: `Bearer ${token}`,
-                "Content-Type": "application/json",
-                ...(init.headers ?? {}),
-            },
-        });
+        let 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}`);
@@ -275,16 +282,34 @@ export function createHubspotConnector(options) {
                 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 = 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" });
         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 } : {}) },
         };
     }
     async function createTask(operation) {

package/dist/connectors/hubspotAuth.js

@@ -49,8 +49,12 @@ export async function validateHubspotToken(token, fetchImpl = fetch) {
     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(params, fetchImpl) {
     const response = await fetchImpl(HS_TOKEN_URL, {
@@ -154,6 +158,10 @@ export async function runHubspotLoopbackLogin(options) {
     });
 }
 export async function openInBrowser(url) {
+    // 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/dist/connectors/salesforce.js

@@ -28,14 +28,21 @@ export function createSalesforceConnector(options) {
         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;
+        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}`);
@@ -261,8 +268,26 @@ export function createSalesforceConnector(options) {
                 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/dist/connectors/salesforceAuth.js

@@ -111,10 +111,24 @@ export async function refreshSalesforceToken(options) {
     };
 }
 export async function validateSalesforceToken(accessToken, instanceUrl, fetchImpl = fetch) {
-    const response = await fetchImpl(`${instanceUrl.replace(/\/$/, "")}/services/oauth2/userinfo`, { headers: { Authorization: `Bearer ${accessToken}` } });
+    let 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/dist/credentials.d.ts

@@ -2,7 +2,26 @@
  * 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 declare const DEFAULT_PROFILE = "default";
+export declare function validateProfileName(name: string): string;
+/** Select the profile for this process; wins over $FULLSTACKGTM_PROFILE. */
+export declare function setActiveProfile(name: string): void;
+export declare function activeProfile(): string;
+/** Base home directory, shared by every profile. */
+export declare function baseHomeDir(): string;
+/**
+ * Profiles that exist on disk (have a directory), always including the
+ * default profile. Existence does not imply stored credentials.
+ */
+export declare function listProfiles(): string[];
 export type StoredCredential = {
     kind: "private_app" | "oauth" | "broker";
     accessToken: string;