fullstackgtm 0.43.0 → 0.45.0

package/src/index.ts

@@ -107,6 +107,38 @@ export {
   type ScaffoldFile,
   type ScaffoldOptions,
 } from "./init.ts";
+export {
+  appendCoverage,
+  classifyAccount,
+  classifyCoverage,
+  computeCoverage,
+  coverageCountsFromSnapshot,
+  coveredAccounts,
+  coverageToText,
+  crmCheckableCriteria,
+  deriveAcvFromClosedWon,
+  deriveBuyersPerAccount,
+  estimateTam,
+  loadTamModel,
+  projectEta,
+  readCoverageTimeline,
+  saveTamModel,
+  tamDir,
+  tamReportToMarkdown,
+  type AccountTamClass,
+  type AcvBasis,
+  type DerivedAcv,
+  type DerivedBuyers,
+  type EstimateTamInput,
+  type TamClassified,
+  type TamCoverage,
+  type TamCoverageCounts,
+  type TamCrossCheck,
+  type TamEta,
+  type TamModel,
+  type TamTargeting,
+  type TamUniverse,
+} from "./tam.ts";
 export {
   apolloPullKeysForAppend,
   apolloPullKeysForRefresh,

package/src/init.ts

@@ -45,6 +45,9 @@ export function starterIcp(): Icp {
       industries: ["software", "saas"],
       employeeBands: ["51-200", "201-500", "501-1000"],
       geos: ["us"],
+      // Technographic targeting (the real RevOps signal): companies that USE a
+      // CRM/MAP. Drives `tam estimate|accounts --source theirstack`.
+      technologies: ["salesforce", "hubspot", "pipedrive"],
     },
     persona: {
       jobLevels: ["vp", "director", "manager"],

package/src/judge.ts

@@ -612,6 +612,8 @@ export async function judgeSignals(opts: {
   promptTemplate?: string;
   llm?: LlmCallOptions;
   now?: Date;
+  /** Per-account progress (presentation only — a throwing callback never fails the run). */
+  onAccount?: (done: number, total: number, domain: string) => void;
 }): Promise<JudgeDecision[]> {
   const now = opts.now ?? new Date();
   const signalsById = new Map(opts.signals.map((s) => [s.id, s]));
@@ -629,6 +631,11 @@ export async function judgeSignals(opts: {
 
   const decisions: JudgeDecision[] = [];
   for (const [domain, signals] of byAccount) {
+    try {
+      opts.onAccount?.(decisions.length, byAccount.size, domain);
+    } catch {
+      // progress is presentation-only
+    }
     // Memory + fit stay gated on --with-history (scoring semantics unchanged).
     const recentlyTouched =
       opts.withHistory && opts.snapshot ? accountRecentlyTouched(domain, opts.snapshot, now) : false;

package/src/judgeEval.ts

@@ -205,7 +205,14 @@ export function defaultJudgeFn(opts: { config?: SignalsConfig; icp?: Icp; now?:
 // ---------------------------------------------------------------------------
 // The default golden set (ships inline so `icp eval --golden default` is free)
 
-const GOLD_NOW_ISO = "2026-06-23T12:00:00.000Z";
+/**
+ * The default golden set's clock. Every `firstSeen` below is relative to this
+ * instant, so grading MUST pin `now: new Date(DEFAULT_GOLDEN_NOW_ISO)` —
+ * grading against wall time lets freshness decay rot the "fresh → send" rows,
+ * and the gate starts failing on a calendar date instead of a code change.
+ */
+export const DEFAULT_GOLDEN_NOW_ISO = "2026-06-23T12:00:00.000Z";
+const GOLD_NOW_ISO = DEFAULT_GOLDEN_NOW_ISO;
 
 function goldSignal(over: {
   accountDomain: string;

package/src/marketClassify.ts

@@ -113,6 +113,8 @@ export type ClassifyMarketOptions = {
   /** Captures directory override (tests); defaults to the profile market home. */
   capturesDir?: string;
   now?: () => Date;
+  /** Per-vendor progress (presentation only — a throwing callback never fails the run). */
+  onVendor?: (done: number, total: number, vendorId: string) => void;
 };
 
 export type ClassifyMarketResult = {
@@ -143,7 +145,12 @@ export async function classifyMarket(
   const observations: MarketObservation[] = [];
   const retriedVendorIds: string[] = [];
 
-  for (const vendorId of vendorIds) {
+  for (const [vendorIndex, vendorId] of vendorIds.entries()) {
+    try {
+      options.onVendor?.(vendorIndex, vendorIds.length, vendorId);
+    } catch {
+      // progress is presentation-only
+    }
     const vendor = config.vendors.find((candidate) => candidate.id === vendorId);
     if (!vendor) throw new Error(`Unknown vendor "${vendorId}"`);
     const vendorEntries = runEntries.filter((entry) => entry.vendorId === vendorId);

package/src/mcp-bin.ts

@@ -9,8 +9,8 @@ const MISSING_PEER_HELP = `The MCP server needs the optional peer dependencies @
 In a project:
   npm install fullstackgtm @modelcontextprotocol/sdk zod
 
-Zero-install:
-  npx -p fullstackgtm -p @modelcontextprotocol/sdk -p zod fullstackgtm-mcp`;
+Zero-install (the fullstackgtm-mcp wrapper package bundles the peers):
+  npx -y fullstackgtm-mcp`;
 
 function isMissingPeerError(error: unknown): boolean {
   if (!(error instanceof Error)) return false;

package/src/mcp.ts

@@ -38,6 +38,8 @@ const { StdioServerTransport } = await importPeer<typeof import("@modelcontextpr
 );
 const { z } = await importPeer<typeof import("zod/v4")>("zod/v4");
 import { auditSnapshot, defaultPolicy } from "./audit.ts";
+import { assertCanonicalSnapshot } from "./cli/shared.ts";
+import { nearest } from "./cli/suggest.ts";
 import { loadConfig, mergePolicy, resolveConfiguredRules } from "./config.ts";
 import { applyPatchPlan } from "./connector.ts";
 import { createHubspotConnector } from "./connectors/hubspot.ts";
@@ -123,8 +125,10 @@ async function connectorFor(provider: string): Promise<GtmConnector> {
     }
     return createStripeConnector({ getApiKey: () => key });
   }
+  const providerSuggestion = nearest(provider.toLowerCase(), ["hubspot", "salesforce", "stripe"], 3);
   throw new Error(
-    `Unknown provider: ${provider}. Supported providers: hubspot, salesforce, stripe`,
+    `Unknown provider: ${provider}.${providerSuggestion ? ` Did you mean ${providerSuggestion}?` : ""} ` +
+      "Supported providers: hubspot, salesforce, stripe",
   );
 }
 
@@ -138,9 +142,10 @@ async function readSnapshot(
     return connector.fetchSnapshot();
   }
   if (!inputPath) return sampleSnapshot;
-  return JSON.parse(
-    readFileSync(resolve(process.cwd(), inputPath), "utf8"),
-  ) as CanonicalGtmSnapshot;
+  return assertCanonicalSnapshot(
+    JSON.parse(readFileSync(resolve(process.cwd(), inputPath), "utf8")),
+    inputPath,
+  );
 }
 
 function packageVersion() {
@@ -152,15 +157,29 @@ function packageVersion() {
   }
 }
 
-export async function startMcpServer() {
-  const server = new McpServer({
-    name: "fullstackgtm",
-    version: packageVersion(),
-  });
+type ToolDefinition = {
+  name: string;
+  // Whether the tool can write to a CRM. Everything else reads, or writes
+  // only local workspace state (market_observe appends to the local
+  // observation store).
+  writesCrm: boolean;
+  config: { title: string; description: string; inputSchema?: Record<string, unknown> };
+  // Args are validated by the SDK against config.inputSchema before the
+  // handler runs; the loose typing here is what lets one table drive a
+  // registration loop instead of per-call generics.
+  handler: (args: any) => Promise<ReturnType<typeof content>> | ReturnType<typeof content>;
+};
 
-  server.registerTool(
-    "fullstackgtm_audit",
-    {
+// Single registration table. startMcpServer() registers exactly this list,
+// and fullstackgtm_capabilities reports its names from the same array — the
+// advertised inventory cannot drift from what is actually registered.
+// (A hand-written parallel tool list was a core defect of the first pass at
+// a capabilities tool, which reported 4 of the 8 registered tools.)
+const toolDefinitions: ToolDefinition[] = [
+  {
+    name: "fullstackgtm_audit",
+    writesCrm: false,
+    config: {
       title: "GTM Ops Audit",
       description:
         "Run a dry-run GTM hygiene audit and return a reviewable patch plan. " +
@@ -176,23 +195,23 @@ export async function startMcpServer() {
         staleDealDays: z.number().int().positive().optional(),
       },
     },
-    async ({ provider, inputPath, configPath, rules, output, today, staleDealDays }) => {
+    handler: async ({ provider, inputPath, configPath, rules, output, today, staleDealDays }) => {
       const loaded = configPath ? loadConfig(configPath) : null;
       const policy = mergePolicy(defaultPolicy(today), loaded?.config);
       if (today) policy.today = today;
       if (staleDealDays !== undefined) policy.staleDealDays = staleDealDays;
       const ruleSet = await resolveConfiguredRules(loaded);
       const selected = rules?.length
-        ? ruleSet.filter((rule) => rules.includes(rule.id))
+        ? ruleSet.filter((rule: { id: string }) => rules.includes(rule.id))
         : ruleSet;
       const plan = auditSnapshot(await readSnapshot(provider, inputPath), policy, selected);
       return content(output === "markdown" ? patchPlanToMarkdown(plan) : plan);
     },
-  );
-
-  server.registerTool(
-    "fullstackgtm_suggest",
-    {
+  },
+  {
+    name: "fullstackgtm_suggest",
+    writesCrm: false,
+    config: {
       title: "Suggest Placeholder Values",
       description:
         "Derive values for a plan's requires_human_* placeholder operations from snapshot " +
@@ -204,16 +223,16 @@ export async function startMcpServer() {
         inputPath: z.string().optional(),
       },
     },
-    async ({ planPath, provider, inputPath }) => {
+    handler: async ({ planPath, provider, inputPath }) => {
       const plan = JSON.parse(readFileSync(resolve(process.cwd(), planPath), "utf8")) as PatchPlan;
       const snapshot = await readSnapshot(provider, inputPath);
       return content({ suggestions: suggestValues(plan, snapshot) });
     },
-  );
-
-  server.registerTool(
-    "fullstackgtm_call_parse",
-    {
+  },
+  {
+    name: "fullstackgtm_call_parse",
+    writesCrm: false,
+    config: {
       title: "Parse Call Transcript",
       description:
         "Parse a call transcript (Speaker:/[Speaker]: lines or Granola utterance JSON) into " +
@@ -230,7 +249,7 @@ export async function startMcpServer() {
         model: z.string().optional(),
       },
     },
-    async ({ transcript, transcriptPath, title, source, extractor, model }) => {
+    handler: async ({ transcript, transcriptPath, title, source, extractor, model }) => {
       const raw =
         transcript ??
         (transcriptPath ? readFileSync(resolve(process.cwd(), transcriptPath), "utf8") : null);
@@ -255,11 +274,11 @@ export async function startMcpServer() {
       }
       return content(parseCall(raw, { title, sourceSystem: source }));
     },
-  );
-
-  server.registerTool(
-    "fullstackgtm_resolve",
-    {
+  },
+  {
+    name: "fullstackgtm_resolve",
+    writesCrm: false,
+    config: {
       title: "Resolve Record (create gate)",
       description:
         "Before creating a CRM record, check whether it already exists. Returns a verdict " +
@@ -276,29 +295,29 @@ export async function startMcpServer() {
         inputPath: z.string().optional(),
       },
     },
-    async ({ objectType, name, domain, email, accountId, provider, inputPath }) => {
+    handler: async ({ objectType, name, domain, email, accountId, provider, inputPath }) => {
       const snapshot = await readSnapshot(provider, inputPath);
       return content(resolveRecord(snapshot, { objectType, name, domain, email, accountId }));
     },
-  );
-
-  server.registerTool(
-    "fullstackgtm_rules",
-    {
+  },
+  {
+    name: "fullstackgtm_rules",
+    writesCrm: false,
+    config: {
       title: "List Audit Rules",
       description: "List the built-in deterministic audit rules with ids and descriptions.",
       inputSchema: {},
     },
-    async () => {
+    handler: async () => {
       return content(
         builtinAuditRules.map(({ id, title, description }) => ({ id, title, description })),
       );
     },
-  );
-
-  server.registerTool(
-    "fullstackgtm_apply",
-    {
+  },
+  {
+    name: "fullstackgtm_apply",
+    writesCrm: true,
+    config: {
       title: "Apply Approved Patch Operations",
       description:
         "Apply explicitly approved operations from a patch plan through a provider " +
@@ -312,7 +331,7 @@ export async function startMcpServer() {
         output: z.enum(["json", "markdown"]).optional(),
       },
     },
-    async ({ provider, planPath, approvedOperationIds, valueOverrides, output }) => {
+    handler: async ({ provider, planPath, approvedOperationIds, valueOverrides, output }) => {
       const plan = JSON.parse(
         readFileSync(resolve(process.cwd(), planPath), "utf8"),
       ) as PatchPlan;
@@ -322,11 +341,11 @@ export async function startMcpServer() {
       });
       return content(output === "markdown" ? formatPatchPlanRun(run) : run);
     },
-  );
-
-  server.registerTool(
-    "fullstackgtm_market_worksheet",
-    {
+  },
+  {
+    name: "fullstackgtm_market_worksheet",
+    writesCrm: false,
+    config: {
       title: "Market Map Classification Worksheet",
       description:
         "Get everything needed to classify ONE vendor's messaging intensity for a market map: " +
@@ -341,15 +360,15 @@ export async function startMcpServer() {
         captureRun: z.string().optional(),
       },
     },
-    async ({ vendorId, configPath, captureRun }) => {
+    handler: async ({ vendorId, configPath, captureRun }) => {
       const config = loadMarketConfigOrHint(resolve(process.cwd(), configPath ?? "market.config.json"));
       return content(buildWorksheet(config, vendorId, { captureRun }));
     },
-  );
-
-  server.registerTool(
-    "fullstackgtm_market_observe",
-    {
+  },
+  {
+    name: "fullstackgtm_market_observe",
+    writesCrm: false,
+    config: {
       title: "Submit Market Map Observations",
       description:
         "Submit a complete ObservationSet (every vendor × claim cell) for a market map run. " +
@@ -361,7 +380,7 @@ export async function startMcpServer() {
         configPath: z.string().optional().describe("Path to market.config.json (default ./market.config.json)"),
       },
     },
-    async ({ observationsPath, configPath }) => {
+    handler: async ({ observationsPath, configPath }) => {
       const config = loadMarketConfigOrHint(resolve(process.cwd(), configPath ?? "market.config.json"));
       const set = JSON.parse(readFileSync(resolve(process.cwd(), observationsPath), "utf8")) as ObservationSet;
       const problems = validateObservationSet(config, set);
@@ -377,7 +396,61 @@ export async function startMcpServer() {
       const fronts = computeFrontStates(config, set);
       return content({ accepted: true, runLabel: set.runLabel, observations: set.observations.length, fronts });
     },
-  );
+  },
+];
+
+// Registered first so agents that list tools see the contract entry up top.
+// Its payload closes over the registration table, so the reported inventory
+// is derived, not hand-maintained.
+toolDefinitions.unshift({
+  name: "fullstackgtm_capabilities",
+  writesCrm: false,
+  config: {
+    title: "FullStackGTM Capabilities",
+    description:
+      "Machine-readable contract for this MCP server: the tool inventory (derived from the " +
+      "server's own registration table, with per-tool CRM-write flags), safety defaults, and " +
+      "the CLI entrypoints for everything the tools don't cover.",
+  },
+  handler: async () =>
+    content({
+      ok: true,
+      tool: "fullstackgtm",
+      version: packageVersion(),
+      planFirst: true,
+      mcpTools: toolDefinitions.map(({ name, writesCrm, config }) => ({
+        name,
+        title: config.title,
+        writesCrm,
+      })),
+      safety:
+        "Only tools flagged writesCrm can reach a CRM; fullstackgtm_apply writes only operations " +
+        "listed in approvedOperationIds and never writes requires_human_* placeholders without a value override.",
+      server: { command: "npx -y fullstackgtm-mcp" },
+      cli: {
+        command: "npx fullstackgtm <command> [--json]",
+        capabilities: "npx fullstackgtm capabilities --json",
+        agentGuide: "npx fullstackgtm robot-docs",
+      },
+      examples: [
+        "npx -y fullstackgtm-mcp",
+        "npx fullstackgtm capabilities --json",
+        "npx fullstackgtm audit --demo --json",
+      ],
+    }),
+});
+
+export async function startMcpServer() {
+  const server = new McpServer({
+    name: "fullstackgtm",
+    version: packageVersion(),
+  });
+
+  for (const tool of toolDefinitions) {
+    // The table is loosely typed so it can drive one loop; the SDK still
+    // validates every call against the zod inputSchema at runtime.
+    server.registerTool(tool.name, tool.config as never, tool.handler as never);
+  }
 
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/src/runReport.ts

@@ -11,7 +11,34 @@ import { getCredential } from "./credentials.ts";
 
 type RunEvent = { ts: number; type: string; detail?: string };
 
+/**
+ * Per-row finding for the hosted run timeline. IDs + issue type ONLY — no field
+ * values ever leave the CLI, keeping the audit's row data on the operator's side
+ * while still giving the dashboard navigable, filterable detail.
+ */
+export type RunFinding = {
+  objectType: string;
+  objectId: string;
+  severity: string;
+  ruleId: string;
+  field?: string;
+  operation?: string;
+};
+
+/**
+ * Where a run's findings live in the source CRM, so the dashboard can deep-link
+ * each record. `recordUrlBase` is the provider's record URL prefix; the
+ * dashboard appends the per-object path. Just an URL prefix — no record data.
+ */
+export type RunCrm = { provider: string; recordUrlBase: string };
+
+// Bound the fire-and-forget POST: a pathological audit could surface thousands
+// of findings; cap what we ship (counts still carry the true total).
+const MAX_REPORTED_FINDINGS = 2000;
+
 let counts: Record<string, unknown> | undefined;
+let findings: RunFinding[] | undefined;
+let crm: RunCrm | undefined;
 const events: RunEvent[] = [];
 
 /** A command annotates its headline metrics (merged). */
@@ -19,6 +46,16 @@ export function reportCounts(values: Record<string, unknown>): void {
   counts = { ...(counts ?? {}), ...values };
 }
 
+/** A command reports per-row findings (IDs + issue type, no values). */
+export function reportFindings(values: RunFinding[]): void {
+  findings = values.slice(0, MAX_REPORTED_FINDINGS);
+}
+
+/** A command reports the source CRM's record-URL base for dashboard deep-links. */
+export function reportCrm(value: RunCrm): void {
+  crm = value;
+}
+
 /** A command annotates a structured event (plan saved, meter charged, …). */
 export function reportEvent(type: string, detail?: string): void {
   events.push({ ts: Date.now(), type, detail });
@@ -65,6 +102,8 @@ export async function flushRunReport(
         finishedAt,
         durationMs: finishedAt - startedAt,
         counts,
+        findings: findings?.length ? findings : undefined,
+        crm,
         events: events.length ? events : undefined,
         error,
       }),