fullstackgtm 0.10.1 → 0.11.0

package/dist/credentials.js

@@ -1,11 +1,66 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { refreshHubspotToken } from "./connectors/hubspotAuth.js";
 import { refreshSalesforceToken } from "./connectors/salesforceAuth.js";
-export function credentialsDir() {
+/**
+ * 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 = null;
+export function validateProfileName(name) {
+    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) {
+    explicitProfile = validateProfileName(name);
+}
+export function activeProfile() {
+    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() {
     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() {
+    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 function credentialsDir() {
+    const base = baseHomeDir();
+    const profile = activeProfile();
+    return profile === DEFAULT_PROFILE ? base : join(base, "profiles", profile);
+}
 export function credentialsPath() {
     return join(credentialsDir(), "credentials.json");
 }
@@ -18,12 +73,18 @@ export function credentialsPath() {
  */
 export function ensureSecureHomeDir() {
     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/dist/index.d.ts

@@ -6,13 +6,15 @@ export { DEFAULT_LOOPBACK_PORT, DEFAULT_OAUTH_SCOPES, exchangeHubspotCode, refre
 export { createSalesforceConnector, type SalesforceConnection, type SalesforceConnectorOptions, } from "./connectors/salesforce.ts";
 export { pollSalesforceDeviceLogin, refreshSalesforceToken, startSalesforceDeviceLogin, validateSalesforceToken, type SalesforceDeviceAuthorization, type SalesforceTokenSet, } from "./connectors/salesforceAuth.ts";
 export { createStripeConnector, type StripeConnectorOptions } from "./connectors/stripe.ts";
-export { credentialsDir, credentialsPath, deleteCredential, getCredential, resolveHubspotAccessToken, resolveHubspotConnection, storeCredential, type HubspotConnection, type StoredCredential, } from "./credentials.ts";
+export { activeProfile, credentialsDir, credentialsPath, DEFAULT_PROFILE, deleteCredential, getCredential, listProfiles, resolveHubspotAccessToken, resolveHubspotConnection, setActiveProfile, storeCredential, type HubspotConnection, type StoredCredential, } from "./credentials.ts";
 export { generateDemoSnapshot, type DemoSnapshotOptions } from "./demo.ts";
 export { diffFindings, diffSnapshots, diffToMarkdown, type CollectionDiff, type FieldChange, type FindingsDrift, type RecordChange, type SnapshotDiff, } from "./diff.ts";
 export { mergeSnapshots, type MergeConflict, type MergeMatch, type MergeReport, type MergeSuggestion, } 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, mappedField, mappedFields, normalizeFieldMappings, readMappedValue, type CrmObjectType, type FieldMappings, } from "./mappings.ts";
-export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, requiresHumanInput, staleDealRule, } from "./rules.ts";
+export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, requiresHumanInput, staleDealRule, } from "./rules.ts";
 export { sampleSnapshot } from "./sampleData.ts";
+export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export type { ApprovalStatus, AuditFinding, AuditFindingSeverity, CanonicalAccount, CanonicalActivity, CanonicalContact, CanonicalDeal, CanonicalGtmSnapshot, CanonicalUser, CrmProvider, GtmAuditRule, GtmConnector, GtmEvidence, GtmEvidenceSourceSystem, GtmObjectType, GtmPolicy, GtmRuleContext, GtmRuleResult, GtmSnapshotIndex, PatchOperation, PatchOperationResult, PatchOperationType, PatchPlan, PatchPlanRun, PatchPlanRunStatus, PatchVerification, PipelineFinding, PipelineFindingStatus, PipelineFindingType, ProviderIdentity, RiskLevel, SourceFreshness, } from "./types.ts";

package/dist/index.js

@@ -6,12 +6,14 @@ export { DEFAULT_LOOPBACK_PORT, DEFAULT_OAUTH_SCOPES, exchangeHubspotCode, refre
 export { createSalesforceConnector, } from "./connectors/salesforce.js";
 export { pollSalesforceDeviceLogin, refreshSalesforceToken, startSalesforceDeviceLogin, validateSalesforceToken, } from "./connectors/salesforceAuth.js";
 export { createStripeConnector } from "./connectors/stripe.js";
-export { credentialsDir, credentialsPath, deleteCredential, getCredential, resolveHubspotAccessToken, resolveHubspotConnection, storeCredential, } from "./credentials.js";
+export { activeProfile, credentialsDir, credentialsPath, DEFAULT_PROFILE, deleteCredential, getCredential, listProfiles, resolveHubspotAccessToken, resolveHubspotConnection, setActiveProfile, storeCredential, } from "./credentials.js";
 export { generateDemoSnapshot } from "./demo.js";
 export { diffFindings, diffSnapshots, diffToMarkdown, } from "./diff.js";
 export { mergeSnapshots, } from "./merge.js";
 export { createFilePlanStore } from "./planStore.js";
 export { formatPatchPlanRun, patchPlanToMarkdown } from "./format.js";
+export { auditReportToHtml, auditReportToMarkdown } from "./report.js";
 export { HUBSPOT_DEFAULT_FIELD_MAPPINGS, SALESFORCE_DEFAULT_FIELD_MAPPINGS, mappedField, mappedFields, normalizeFieldMappings, readMappedValue, } from "./mappings.js";
-export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, requiresHumanInput, staleDealRule, } from "./rules.js";
+export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, requiresHumanInput, staleDealRule, } from "./rules.js";
 export { sampleSnapshot } from "./sampleData.js";
+export { suggestValues } from "./suggest.js";

package/dist/mcp.js

@@ -45,6 +45,7 @@ import { generateDemoSnapshot } from "./demo.js";
 import { formatPatchPlanRun, patchPlanToMarkdown } from "./format.js";
 import { builtinAuditRules } from "./rules.js";
 import { sampleSnapshot } from "./sampleData.js";
+import { suggestValues } from "./suggest.js";
 function content(value) {
     return {
         content: [
@@ -140,6 +141,21 @@ export async function startMcpServer() {
         const plan = auditSnapshot(await readSnapshot(provider, inputPath), policy, selected);
         return content(output === "markdown" ? patchPlanToMarkdown(plan) : plan);
     });
+    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"));
+        const snapshot = await readSnapshot(provider, inputPath);
+        return content({ suggestions: suggestValues(plan, snapshot) });
+    });
     server.registerTool("fullstackgtm_rules", {
         title: "List Audit Rules",
         description: "List the built-in deterministic audit rules with ids and descriptions.",

package/dist/report.d.ts

@@ -0,0 +1,61 @@
+import type { AuditFinding, AuditFindingSeverity, CanonicalGtmSnapshot, GtmAuditRule, PatchPlan } from "./types.ts";
+/**
+ * Client-ready rendering of an audit patch plan: the same findings the CLI
+ * prints for operators, reshaped for the person who owns the CRM — counts up
+ * front, prose summary, per-rule detail with capped examples, and next steps.
+ * Deterministic: identical plan + options produce identical output, so a
+ * report can be regenerated and diffed across engagements.
+ */
+export type ReportOptions = {
+    /** Report heading (default "GTM Data Health Report"). */
+    title?: string;
+    /** Organization the report is about; shown in the heading and summary. */
+    clientName?: string;
+    /** Attribution line in the footer (e.g. a consultancy or team name). */
+    preparedBy?: string;
+    /** Report date (YYYY-MM-DD); defaults to the plan's creation date (UTC). */
+    date?: string;
+    /** Example records listed per rule before truncating (default 10). */
+    maxExamplesPerRule?: number;
+    /** Rule metadata used for section titles, descriptions, and categories. */
+    rules?: GtmAuditRule[];
+    /** Snapshot the plan was generated from; enables record counts and rates. */
+    snapshot?: CanonicalGtmSnapshot;
+};
+type RuleSection = {
+    ruleId: string;
+    title: string;
+    description?: string;
+    category: string;
+    severity: AuditFindingSeverity;
+    findings: AuditFinding[];
+};
+type ReportModel = {
+    title: string;
+    clientName?: string;
+    preparedBy?: string;
+    date: string;
+    provider?: string;
+    recordCounts?: {
+        label: string;
+        count: number;
+    }[];
+    totalRecords?: number;
+    severityCounts: Record<AuditFindingSeverity, number>;
+    affectedRecords: number;
+    sections: RuleSection[];
+    maxExamplesPerRule: number;
+    operationCount: number;
+    humanInputOperationCount: number;
+    recordLabels: Map<string, string>;
+    summaryText: string;
+};
+export declare function buildReportModel(plan: PatchPlan, options?: ReportOptions): ReportModel;
+export declare function auditReportToMarkdown(plan: PatchPlan, options?: ReportOptions): string;
+/**
+ * Self-contained HTML (inline styles, no external assets) so the file can be
+ * emailed or dropped into a shared drive and render anywhere, including
+ * print-to-PDF.
+ */
+export declare function auditReportToHtml(plan: PatchPlan, options?: ReportOptions): string;
+export {};

package/dist/report.js

@@ -0,0 +1,331 @@
+import { REQUIRES_HUMAN_PREFIX } from "./rules.js";
+const SEVERITY_ORDER = ["critical", "warning", "info"];
+const SEVERITY_RANK = {
+    critical: 2,
+    warning: 1,
+    info: 0,
+};
+export function buildReportModel(plan, options = {}) {
+    const ruleMeta = new Map((options.rules ?? []).map((rule) => [rule.id, rule]));
+    const byRule = new Map();
+    for (const finding of plan.findings) {
+        const findings = byRule.get(finding.ruleId) ?? [];
+        findings.push(finding);
+        byRule.set(finding.ruleId, findings);
+    }
+    const sections = Array.from(byRule.entries())
+        .map(([ruleId, findings]) => {
+        const meta = ruleMeta.get(ruleId);
+        const severity = findings.reduce((worst, finding) => SEVERITY_RANK[finding.severity] > SEVERITY_RANK[worst] ? finding.severity : worst, "info");
+        return {
+            ruleId,
+            title: meta?.title ?? ruleId,
+            description: meta?.description,
+            category: meta?.category ?? "uncategorized",
+            severity,
+            findings,
+        };
+    })
+        .sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity] ||
+        b.findings.length - a.findings.length ||
+        a.ruleId.localeCompare(b.ruleId));
+    const severityCounts = {
+        critical: 0,
+        warning: 0,
+        info: 0,
+    };
+    const affected = new Set();
+    for (const finding of plan.findings) {
+        severityCounts[finding.severity] += 1;
+        affected.add(`${finding.objectType}:${finding.objectId}`);
+    }
+    const snapshot = options.snapshot;
+    const recordCounts = snapshot
+        ? [
+            { label: "Accounts", count: snapshot.accounts.length },
+            { label: "Contacts", count: snapshot.contacts.length },
+            { label: "Deals", count: snapshot.deals.length },
+            { label: "Users", count: snapshot.users.length },
+            { label: "Activities", count: snapshot.activities.length },
+        ]
+        : undefined;
+    const totalRecords = recordCounts?.reduce((sum, entry) => sum + entry.count, 0);
+    const recordLabels = new Map();
+    if (snapshot) {
+        for (const row of snapshot.accounts)
+            recordLabels.set(`account:${row.id}`, row.name);
+        for (const row of snapshot.users)
+            recordLabels.set(`user:${row.id}`, row.name);
+        for (const row of snapshot.deals)
+            recordLabels.set(`deal:${row.id}`, row.name);
+        for (const row of snapshot.contacts) {
+            const name = [row.firstName, row.lastName].filter(Boolean).join(" ") || row.email;
+            if (name)
+                recordLabels.set(`contact:${row.id}`, name);
+        }
+    }
+    const humanInputOperationCount = plan.operations.filter((operation) => typeof operation.afterValue === "string" &&
+        operation.afterValue.startsWith(REQUIRES_HUMAN_PREFIX)).length;
+    const model = {
+        title: options.title ?? "GTM Data Health Report",
+        clientName: options.clientName,
+        preparedBy: options.preparedBy,
+        date: options.date ?? plan.createdAt.slice(0, 10),
+        provider: snapshot?.provider,
+        recordCounts,
+        totalRecords,
+        severityCounts,
+        affectedRecords: affected.size,
+        sections,
+        maxExamplesPerRule: Math.max(1, options.maxExamplesPerRule ?? 10),
+        operationCount: plan.operations.length,
+        humanInputOperationCount,
+        recordLabels,
+        summaryText: "",
+    };
+    model.summaryText = summaryText(model);
+    return model;
+}
+function summaryText(model) {
+    const subject = model.clientName ? `${model.clientName}'s CRM data` : "the CRM data";
+    if (model.sections.length === 0) {
+        return `This audit reviewed ${subject} and found no issues with the rules that ran. The checks are deterministic and can be re-run at any time to confirm the data stays healthy.`;
+    }
+    const total = model.sections.reduce((sum, section) => sum + section.findings.length, 0);
+    const severityParts = SEVERITY_ORDER.filter((severity) => model.severityCounts[severity] > 0)
+        .map((severity) => `${model.severityCounts[severity]} ${severity}`)
+        .join(", ");
+    const scope = model.totalRecords !== undefined
+        ? `${model.affectedRecords} of ${model.totalRecords} records (${percent(model.affectedRecords, model.totalRecords)}%)`
+        : `${model.affectedRecords} records`;
+    const top = model.sections[0];
+    const fixes = model.operationCount > 0
+        ? ` ${model.operationCount} of the issues have a proposed fix ready for review; nothing is changed in the CRM until each fix is explicitly approved.`
+        : "";
+    return (`This audit reviewed ${subject} and surfaced ${total} findings (${severityParts}) across ${scope}. ` +
+        `The largest issue is "${top.title}" (${top.findings.length} records).${fixes}`);
+}
+function percent(part, whole) {
+    if (whole === 0)
+        return 0;
+    return Math.round((part / whole) * 100);
+}
+function findingLabel(model, finding) {
+    const name = model.recordLabels.get(`${finding.objectType}:${finding.objectId}`);
+    return name ? `${name} (${finding.objectType})` : `${finding.objectType}/${finding.objectId}`;
+}
+export function auditReportToMarkdown(plan, options = {}) {
+    const model = buildReportModel(plan, options);
+    const lines = [];
+    lines.push(`# ${model.title}${model.clientName ? ` — ${model.clientName}` : ""}`, "");
+    const subtitle = [
+        `Prepared ${model.date}`,
+        model.provider ? `Source: ${model.provider}` : null,
+        model.preparedBy ? `By: ${model.preparedBy}` : null,
+    ].filter(Boolean);
+    lines.push(subtitle.join(" · "), "");
+    lines.push("## At a Glance", "", "| Metric | Value |", "| --- | --- |");
+    if (model.recordCounts && model.totalRecords !== undefined) {
+        lines.push(`| Records audited | ${model.totalRecords} (${model.recordCounts
+            .map((entry) => `${entry.count} ${entry.label.toLowerCase()}`)
+            .join(", ")}) |`);
+    }
+    const totalFindings = SEVERITY_ORDER.reduce((sum, severity) => sum + model.severityCounts[severity], 0);
+    lines.push(`| Findings | ${totalFindings} |`);
+    for (const severity of SEVERITY_ORDER) {
+        lines.push(`| ${capitalize(severity)} | ${model.severityCounts[severity]} |`);
+    }
+    lines.push(`| Records affected | ${model.affectedRecords}${model.totalRecords !== undefined && model.totalRecords > 0
+        ? ` (${percent(model.affectedRecords, model.totalRecords)}%)`
+        : ""} |`, `| Proposed fixes | ${model.operationCount}${model.humanInputOperationCount > 0
+        ? ` (${model.humanInputOperationCount} need a human-chosen value)`
+        : ""} |`, "");
+    lines.push("## Summary", "", model.summaryText, "");
+    if (model.sections.length > 0) {
+        lines.push("## Findings by Rule", "", "| Rule | Category | Severity | Records |", "| --- | --- | --- | --- |");
+        for (const section of model.sections) {
+            lines.push(`| ${section.title} | ${section.category} | ${section.severity} | ${section.findings.length} |`);
+        }
+        lines.push("", "## Details", "");
+        for (const section of model.sections) {
+            lines.push(`### ${section.title} (${section.findings.length} ${section.findings.length === 1 ? "record" : "records"}, ${section.severity})`, "");
+            if (section.description)
+                lines.push(section.description, "");
+            const shown = section.findings.slice(0, model.maxExamplesPerRule);
+            for (const finding of shown) {
+                lines.push(`- **${findingLabel(model, finding)}** — ${finding.summary}`);
+                lines.push(`  - Recommendation: ${finding.recommendation}`);
+            }
+            const hidden = section.findings.length - shown.length;
+            if (hidden > 0)
+                lines.push(`- … and ${hidden} more.`);
+            lines.push("");
+        }
+        lines.push("## Recommended Next Steps", "");
+        if (model.operationCount > 0) {
+            lines.push(`1. Review the ${model.operationCount} proposed fixes (\`fullstackgtm audit --save\`, then \`fullstackgtm plans show <id>\`).`, `2. Approve the operations to apply${model.humanInputOperationCount > 0
+                ? `, supplying values for the ${model.humanInputOperationCount} that need a human decision`
+                : ""} (\`fullstackgtm plans approve\`). Nothing is written without explicit approval.`, "3. Re-run the audit after applying to confirm the findings clear, and schedule it recurring to catch regressions.");
+        }
+        else {
+            lines.push("1. Address the findings above in the CRM (no automated fixes are available for them yet).", "2. Re-run the audit to confirm the findings clear, and schedule it recurring to catch regressions.");
+        }
+        lines.push("");
+    }
+    lines.push("---", "", `Generated by the fullstackgtm CLI on ${model.date}.` +
+        (model.preparedBy ? ` Prepared by ${model.preparedBy}.` : "") +
+        " Findings are deterministic and re-runnable; no CRM data was modified to produce this report.");
+    return `${lines.join("\n")}\n`;
+}
+const SEVERITY_COLORS = {
+    critical: { fg: "#991b1b", bg: "#fee2e2" },
+    warning: { fg: "#92400e", bg: "#fef3c7" },
+    info: { fg: "#1e40af", bg: "#dbeafe" },
+};
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+function severityBadge(severity) {
+    const colors = SEVERITY_COLORS[severity];
+    return `<span class="badge" style="color:${colors.fg};background:${colors.bg}">${severity}</span>`;
+}
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+/**
+ * Self-contained HTML (inline styles, no external assets) so the file can be
+ * emailed or dropped into a shared drive and render anywhere, including
+ * print-to-PDF.
+ */
+export function auditReportToHtml(plan, options = {}) {
+    const model = buildReportModel(plan, options);
+    const totalFindings = SEVERITY_ORDER.reduce((sum, severity) => sum + model.severityCounts[severity], 0);
+    const glanceRows = [];
+    if (model.recordCounts && model.totalRecords !== undefined) {
+        glanceRows.push(row("Records audited", `${model.totalRecords} (${model.recordCounts
+            .map((entry) => `${entry.count} ${entry.label.toLowerCase()}`)
+            .join(", ")})`));
+    }
+    glanceRows.push(row("Findings", String(totalFindings)));
+    for (const severity of SEVERITY_ORDER) {
+        glanceRows.push(`<tr><th>${capitalize(severity)}</th><td>${model.severityCounts[severity]} ${severityBadge(severity)}</td></tr>`);
+    }
+    glanceRows.push(row("Records affected", `${model.affectedRecords}${model.totalRecords !== undefined && model.totalRecords > 0
+        ? ` (${percent(model.affectedRecords, model.totalRecords)}%)`
+        : ""}`), row("Proposed fixes", `${model.operationCount}${model.humanInputOperationCount > 0
+        ? ` (${model.humanInputOperationCount} need a human-chosen value)`
+        : ""}`));
+    const ruleRows = model.sections
+        .map((section) => `<tr><td>${escapeHtml(section.title)}</td><td>${escapeHtml(section.category)}</td>` +
+        `<td>${severityBadge(section.severity)}</td><td class="num">${section.findings.length}</td></tr>`)
+        .join("\n");
+    const detailSections = model.sections
+        .map((section) => {
+        const shown = section.findings.slice(0, model.maxExamplesPerRule);
+        const hidden = section.findings.length - shown.length;
+        const items = shown
+            .map((finding) => `<li><strong>${escapeHtml(findingLabel(model, finding))}</strong> — ${escapeHtml(finding.summary)}` +
+            `<div class="rec">Recommendation: ${escapeHtml(finding.recommendation)}</div></li>`)
+            .join("\n");
+        return [
+            `<section>`,
+            `<h3>${escapeHtml(section.title)} <span class="count">${section.findings.length} ${section.findings.length === 1 ? "record" : "records"}</span> ${severityBadge(section.severity)}</h3>`,
+            section.description ? `<p>${escapeHtml(section.description)}</p>` : "",
+            `<ul>`,
+            items,
+            hidden > 0 ? `<li class="more">… and ${hidden} more.</li>` : "",
+            `</ul>`,
+            `</section>`,
+        ]
+            .filter(Boolean)
+            .join("\n");
+    })
+        .join("\n");
+    const nextSteps = model.sections.length === 0
+        ? ""
+        : model.operationCount > 0
+            ? `<ol>
+<li>Review the ${model.operationCount} proposed fixes (<code>fullstackgtm audit --save</code>, then <code>fullstackgtm plans show &lt;id&gt;</code>).</li>
+<li>Approve the operations to apply${model.humanInputOperationCount > 0
+                ? `, supplying values for the ${model.humanInputOperationCount} that need a human decision`
+                : ""} (<code>fullstackgtm plans approve</code>). Nothing is written without explicit approval.</li>
+<li>Re-run the audit after applying to confirm the findings clear, and schedule it recurring to catch regressions.</li>
+</ol>`
+            : `<ol>
+<li>Address the findings above in the CRM (no automated fixes are available for them yet).</li>
+<li>Re-run the audit to confirm the findings clear, and schedule it recurring to catch regressions.</li>
+</ol>`;
+    const subtitle = [
+        `Prepared ${model.date}`,
+        model.provider ? `Source: ${escapeHtml(model.provider)}` : null,
+        model.preparedBy ? `By: ${escapeHtml(model.preparedBy)}` : null,
+    ]
+        .filter(Boolean)
+        .join(" · ");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(model.title)}${model.clientName ? ` — ${escapeHtml(model.clientName)}` : ""}</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+         color: #1f2937; max-width: 860px; margin: 0 auto; padding: 2rem 1.5rem; line-height: 1.55; }
+  h1 { font-size: 1.6rem; margin-bottom: 0.25rem; }
+  h2 { font-size: 1.2rem; margin-top: 2rem; border-bottom: 1px solid #e5e7eb; padding-bottom: 0.3rem; }
+  h3 { font-size: 1.05rem; margin-top: 1.5rem; }
+  .subtitle { color: #6b7280; margin-top: 0; }
+  table { border-collapse: collapse; width: 100%; margin: 0.75rem 0; }
+  th, td { text-align: left; padding: 0.4rem 0.6rem; border-bottom: 1px solid #e5e7eb; font-size: 0.95rem; }
+  th { color: #374151; font-weight: 600; }
+  td.num { text-align: right; }
+  .badge { display: inline-block; padding: 0.05rem 0.5rem; border-radius: 999px;
+           font-size: 0.78rem; font-weight: 600; vertical-align: middle; }
+  .count { color: #6b7280; font-weight: 400; font-size: 0.9rem; }
+  ul { padding-left: 1.2rem; }
+  li { margin-bottom: 0.5rem; }
+  .rec { color: #4b5563; font-size: 0.92rem; }
+  .more { color: #6b7280; list-style: none; }
+  code { background: #f3f4f6; padding: 0.1rem 0.3rem; border-radius: 4px; font-size: 0.88rem; }
+  footer { margin-top: 2.5rem; padding-top: 1rem; border-top: 1px solid #e5e7eb;
+           color: #6b7280; font-size: 0.85rem; }
+  @media print { body { padding: 0; } }
+</style>
+</head>
+<body>
+<h1>${escapeHtml(model.title)}${model.clientName ? ` — ${escapeHtml(model.clientName)}` : ""}</h1>
+<p class="subtitle">${subtitle}</p>
+
+<h2>At a Glance</h2>
+<table>
+${glanceRows.join("\n")}
+</table>
+
+<h2>Summary</h2>
+<p>${escapeHtml(model.summaryText)}</p>
+${model.sections.length > 0
+        ? `
+<h2>Findings by Rule</h2>
+<table>
+<tr><th>Rule</th><th>Category</th><th>Severity</th><th class="num">Records</th></tr>
+${ruleRows}
+</table>
+
+<h2>Details</h2>
+${detailSections}
+
+<h2>Recommended Next Steps</h2>
+${nextSteps}`
+        : ""}
+<footer>Generated by the fullstackgtm CLI on ${model.date}.${model.preparedBy ? ` Prepared by ${escapeHtml(model.preparedBy)}.` : ""} Findings are deterministic and re-runnable; no CRM data was modified to produce this report.</footer>
+</body>
+</html>
+`;
+}
+function row(label, value) {
+    return `<tr><th>${escapeHtml(label)}</th><td>${escapeHtml(value)}</td></tr>`;
+}

package/dist/rules.d.ts

@@ -18,6 +18,7 @@ export declare const staleDealRule: GtmAuditRule;
 export declare const missingDealAmountRule: GtmAuditRule;
 export declare const duplicateAccountDomainRule: GtmAuditRule;
 export declare const duplicateContactEmailRule: GtmAuditRule;
+export declare const duplicateOpenDealRule: GtmAuditRule;
 export declare const activeDealAccountWithoutContactsRule: GtmAuditRule;
 export declare const closingSoonInactiveRule: GtmAuditRule;
 export declare const accountSingleSourceRule: GtmAuditRule;

package/dist/rules.js

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

package/dist/suggest.d.ts

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