fullstackgtm 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -5,6 +5,112 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md).
 
+## [0.11.0] — 2026-06-11
+
+Canonicalizes the paths discovered dogfooding against a real portal: the
+suggest chain (every `requires_human_account_selection` answer was derivable
+from the snapshot but required ad-hoc scripting), governed record creation,
+client-ready reports, and multi-org profiles.
+
+### Added
+
+- **`fullstackgtm suggest --plan-id <id> | --plan <path> [source options]`**:
+  deterministic value suggestions for `requires_human_*` placeholder
+  operations, derived from snapshot evidence — account-name matching
+  cross-checked against contact→account associations, plus the
+  only-active-user case for owner selection. Every suggestion carries a
+  confidence level (`high`/`low`/`create`/`none`) and a written reason;
+  conflicting or ambiguous evidence yields no suggestion, never a guess.
+  `--out` writes a suggestions file; `--json` for agents. Exposed
+  programmatically as `suggestValues` and over MCP as `fullstackgtm_suggest`.
+- **`plans approve <id> --values-from <suggestions.json>`**: bulk-approve
+  with suggested values — high-confidence only by default,
+  `--min-confidence low` and `--include-creates` widen the bar explicitly.
+  Explicit `--value` flags still win.
+- **`create:<Name>` link values**: approving a `link_record` operation with
+  `--value <op>=create:Acme` creates the company (HubSpot) / account
+  (Salesforce) and links to it in one audited operation — record creation
+  stays inside the typed, human-approved model instead of a side channel.
+- New builtin rule `duplicate-open-deal` (data-quality): flags multiple open
+  deals sharing a normalized name, scoped to the account when linked —
+  typically an integration re-creating deals instead of upserting, which
+  counts the same revenue several times in pipeline and forecast. Emits one
+  finding and one approval-gated merge-review task per duplicate group.
+  Found dogfooding: an outreach-tool sync had tripled five open deals in our
+  own portal and no existing rule caught it.
+- `fullstackgtm report` — render an audit (or an existing plan via `--plan`)
+  as a client-ready deliverable in markdown or self-contained HTML:
+  at-a-glance metrics, prose summary, per-rule detail with capped example
+  records (`--max-examples`), and recommended next steps. `--client`,
+  `--title`, `--prepared-by`, and `--format` customize the output;
+  `--out report.html` infers HTML. Exposed programmatically as
+  `auditReportToMarkdown` / `auditReportToHtml`.
+- Credential profiles for multi-organization use: the global
+  `--profile <name>` flag (or `FULLSTACKGTM_PROFILE`) scopes stored logins
+  AND stored plans to `profiles/<name>/` under the fullstackgtm home, so one
+  operator can hold several clients' credentials without mixing them — and a
+  plan proposed against one org's CRM can never be applied through
+  another's. New `profiles` command lists them; `doctor` reports the active
+  profile. The default profile keeps the existing flat layout, so current
+  installs are unaffected. Exposed programmatically as `setActiveProfile`,
+  `activeProfile`, `listProfiles`, and `DEFAULT_PROFILE`.
+
+### Fixed
+
+- `validateHubspotToken` / `validateSalesforceToken` no longer echo the
+  provider's raw error body into the login failure message (observed live: a
+  HubSpot 401 body printed to the terminal). Status line only, matching the
+  no-body-interpolation rule applied elsewhere in 1.0.1.
+- Unreachable hosts during `login salesforce --instance-url` and
+  `login --via <url>` now name the target and what to check, completing the
+  0.10.1 fix that only covered the audit/connector path.
+
+## [0.10.1] — 2026-06-11
+
+Fixes from a full fresh-user journey audit (install → demo → MCP → real CRM),
+focused on the first-contact experience.
+
+### Added
+
+- **`fullstackgtm --version`** (also `-v` / `version`) — previously exited 1
+  with a usage dump.
+- **README "Connect your CRM" section**: HubSpot private-app walkthrough with
+  the exact read scopes the audit needs (`crm.objects.{owners,companies,contacts,deals}.read`)
+  and the write scopes `apply` needs; Salesforce Connected App prerequisites
+  (admin-created, device flow enabled, `api` + `refresh_token` scopes,
+  propagation delay); Stripe restricted-key guidance. Previously the word
+  "scope" appeared nowhere in the docs.
+- Roadmap: documented the known real-portal gaps to close before 1.0
+  (pipeline-aware closed-deal detection, 429/retry, fetchChanges 10k
+  truncation, MCP plan hand-off, scope-complete login validation).
+
+### Fixed
+
+- **`FSGTM_NO_BROWSER=1` suppresses OS browser opens** in all login flows
+  (broker pairing, Salesforce device flow, HubSpot OAuth) — for agent
+  sandboxes, CI, and headless use; verification URLs are always printed.
+  The broker test suite sets it, so running `npm test` no longer pops a
+  real browser tab at a mock pairing URL on every run.
+- **MCP server now works from inside existing projects.** When launched via
+  `npx -p ... fullstackgtm-mcp` from a directory whose node_modules already
+  contains the peers (but not fullstackgtm), npx skips installing them into
+  its cache and module resolution failed; the server now falls back to
+  resolving the peers from the working directory — peer-dependency semantics.
+  Previously this made the README's `claude mcp add` setup produce a dead
+  server in most agent-tooling repos.
+- **README auth examples matched the CLI again**: `login salesforce --token ...`
+  and `login hubspot --oauth ... --client-secret ...` showed argv-secret forms
+  the CLI deliberately rejects; both now use stdin.
+- The no-credentials Stripe error suggested `login stripe --token sk_...`,
+  which the CLI itself refuses — it now shows the stdin form and mentions
+  restricted keys.
+- Unreachable hosts no longer surface as a bare `fetch failed`: HubSpot and
+  Salesforce connection errors name the target URL and (for Salesforce) point
+  at SALESFORCE_INSTANCE_URL.
+- Credential errors now point at `fullstackgtm doctor` and the README scope
+  guide; the MCP audit tool description now mentions the `demo` source;
+  README rule count corrected (11 built-ins, not five).
+
 ## [0.10.0] — 2026-06-10
 
 **Versioning reset to reflect beta status.** The 1.x numbering below

package/INSTALL_FOR_AGENTS.md

@@ -45,7 +45,15 @@ Credential resolution ladder, first match wins:
 4. Broker pairing: `fullstackgtm login --via <hosted url>` (a human approves the pairing code)
 
 In an agent sandbox, prefer rung 1 or 2. Never echo tokens into argv —
-`login` reads secrets from stdin only.
+`login` reads secrets from stdin only. Set `FSGTM_NO_BROWSER=1` in headless
+environments — login flows then print verification URLs instead of opening
+the OS browser.
+
+Provider prerequisites (what the human must create, and which scopes) are in
+the README's **"Connect your CRM"** section: HubSpot needs a private app with
+four `crm.objects.*.read` scopes (plus write scopes only for `apply`);
+Salesforce needs an admin-created Connected App with device flow enabled;
+Stripe works with a restricted key (Customers + Subscriptions read).
 
 ```bash
 HUBSPOT_ACCESS_TOKEN=$TOKEN fullstackgtm audit --provider hubspot --json --out plan.json
@@ -65,15 +73,33 @@ fullstackgtm audit --provider hubspot --save     # persists plan to ~/.fullstack
 fullstackgtm plans list                          # a human reviews and approves
 ```
 
+For `requires_human_*` placeholders, chain the deterministic suggestion engine
+instead of guessing values yourself:
+
+```bash
+fullstackgtm suggest --plan-id <id> --provider hubspot --out suggestions.json   # read-only
+fullstackgtm plans approve <id> --values-from suggestions.json                  # high-confidence only
+fullstackgtm apply --plan-id <id> --provider hubspot
+```
+
+Every suggestion carries a confidence (`high`/`low`/`create`/`none`) and a
+reason derived from snapshot evidence. Surface `low`/`create`/`none` entries
+to your human rather than widening the bar unilaterally — `create:<Name>`
+values create a new CRM record when applied.
+
 ## 6. MCP server (optional)
 
 The MCP entrypoint needs optional peers that plain `npx fullstackgtm-mcp`
 does not install:
 
 ```bash
-npx -p fullstackgtm -p @modelcontextprotocol/sdk -p zod fullstackgtm-mcp
+npx -y -p fullstackgtm -p @modelcontextprotocol/sdk -p zod fullstackgtm-mcp
 ```
 
+If the working directory's project already has the peers in its node_modules,
+the server resolves them from there (peer-dependency semantics) — so this
+works from inside existing projects too.
+
 Tools exposed over stdio: `fullstackgtm_audit` (read-only),
 `fullstackgtm_rules`, `fullstackgtm_apply` (requires `approvedOperationIds`).
 

package/README.md

@@ -1,5 +1,7 @@
 # fullstackgtm
 
+[![CI](https://github.com/fullstackgtm/core/actions/workflows/ci.yml/badge.svg)](https://github.com/fullstackgtm/core/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/fullstackgtm)](https://www.npmjs.com/package/fullstackgtm) [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
+
 **Plan/apply for your GTM stack.** An open-source framework for managing disparate go-to-market data spread across third-party systems: a canonical CRM/GTM data model, deterministic hygiene audits, reviewable dry-run patch plans, and approval-gated write-back to providers.
 
 Think `terraform plan` for your CRM: agents and scripts may *read* everything, but every proposed change becomes a typed patch operation — object, field, before, after, reason, risk — that a human approves before any provider write happens.
@@ -45,6 +47,39 @@ HUBSPOT_ACCESS_TOKEN=pat-... npx fullstackgtm apply \
 
 Nothing is ever written without an explicit `--approve`. Operations whose value is a human decision (`requires_human_*` placeholders, e.g. which owner to assign) are refused unless you supply a concrete `--value` override.
 
+## From findings to fixes: the suggest chain
+
+Most placeholder answers are already derivable from your own CRM data. `suggest` computes them deterministically — account-name matching cross-checked against contact associations — with a confidence level and a written reason per operation, so you (or an agent) approve evidence, not guesses:
+
+```bash
+fullstackgtm audit --provider hubspot --save        # → Saved plan patch_plan_abc123
+fullstackgtm suggest --plan-id patch_plan_abc123 --provider hubspot --out suggestions.json
+# review suggestions.json: every value carries confidence (high/low/create/none) + a reason
+fullstackgtm plans approve patch_plan_abc123 --values-from suggestions.json   # high-confidence only by default
+fullstackgtm apply --plan-id patch_plan_abc123 --provider hubspot
+```
+
+Widen the bar deliberately: `--min-confidence low` accepts single-signal matches; `--include-creates` accepts `create:<Name>` values — approving one **creates the missing company/account record and links to it** in a single audited operation, so even record creation stays inside the typed, human-approved model. Conflicting or ambiguous evidence always yields *no* suggestion with an explanation, never a guess.
+
+```bash
+# 3. Hand the findings to whoever owns the CRM: a client-ready report
+npx fullstackgtm report --provider hubspot --client "Acme" --out acme-health.html
+```
+
+`report` renders the same audit as a deliverable — severity counts up front, a prose summary, per-rule detail with example records, and next steps — as markdown or self-contained HTML (printable, emailable, no external assets).
+
+### Working across organizations
+
+Consultants and fractional operators hold credentials for several CRMs at once. A profile scopes stored logins *and* stored plans to one organization:
+
+```bash
+fullstackgtm --profile acme login hubspot
+fullstackgtm --profile acme audit --provider hubspot --save
+fullstackgtm profiles            # list profiles, * marks the active one
+```
+
+Set `FULLSTACKGTM_PROFILE=acme` to pin a shell (or agent sandbox) to one client. Plans saved under a profile are invisible to every other profile, so a patch plan proposed against one client's CRM can never be applied through another client's credentials.
+
 ## Built for agents (and the RevOps humans they work for)
 
 Every command is designed to compose in an agent loop — deterministic output, machine-readable everywhere, meaningful exit codes:
@@ -93,28 +128,61 @@ fullstackgtm login hubspot
 
 # HubSpot, bring-your-own-app OAuth. The browser is used exactly once — the
 # consent grant — captured on a 127.0.0.1 loopback (RFC 8252); the CLI
-# exchanges the code itself and refreshes silently from then on.
-fullstackgtm login hubspot --oauth --client-id <id> --client-secret <secret>
+# exchanges the code itself and refreshes silently from then on. The client
+# secret is read from stdin or an interactive prompt — never as a flag.
+echo "$CLIENT_SECRET" | fullstackgtm login hubspot --oauth --client-id <id>
 #   (register http://localhost:8763/callback as a redirect URL on your app)
 
 # Salesforce: native device flow — confirm a code on any device, no localhost
 # server, no client secret, silent refresh. Needs a Connected App consumer key
-# with device flow enabled.
+# with device flow enabled (see "Connect your CRM" below).
 fullstackgtm login salesforce --device --client-id <consumer key>
-# ...or a session token directly:
-fullstackgtm login salesforce --token <t> --instance-url https://yourorg.my.salesforce.com
+# ...or a session token directly (token on stdin, never as a flag):
+echo "$SF_SESSION_TOKEN" | fullstackgtm login salesforce --instance-url https://yourorg.my.salesforce.com
 
 fullstackgtm logout hubspot   # or: salesforce | broker
 ```
 
 A direct `login hubspot` always wins over a broker pairing, so an operator can override the team default. HubSpot does not support the device-authorization grant or secretless public clients, which is why the bring-your-own-app OAuth path requires client credentials; they are stored locally for silent refresh, the same model as `gcloud` and `aws` CLI profiles.
 
+## Connect your CRM
+
+What each provider actually requires before `audit --provider <name>` works on your data.
+
+### HubSpot: create a private app (~2 minutes, needs super-admin)
+
+1. In HubSpot: **Settings → Integrations → Private Apps → Create a private app.**
+2. On the **Scopes** tab, grant the read scopes the audit needs:
+   - `crm.objects.owners.read`
+   - `crm.objects.companies.read`
+   - `crm.objects.contacts.read`
+   - `crm.objects.deals.read`
+3. If you plan to **apply** approved operations (not just audit), also grant write scopes for the objects you'll let it touch: `crm.objects.deals.write` (covers `deal.next_step` and other deal fields), plus `crm.objects.contacts.write` / `crm.objects.companies.write` for contact/company patches, and the **Tasks** write scope for `create_task` operations (search "tasks" in the scope picker; naming varies by portal).
+4. Create the app, copy the token (`pat-...`), then: `echo "$TOKEN" | fullstackgtm login hubspot`.
+
+If a scope is missing you'll see a `403` mid-run whose body names the exact missing scope (`requiredGranularScopes`) — add it to the private app and re-run. Note that `login` only validates the token itself; it can't tell whether every scope you'll need is granted.
+
+### Salesforce: a Connected App (one-time, usually needs an admin)
+
+Device-flow login requires a Connected App in your org — if you're not an admin, this is the step to ask one for:
+
+1. **Setup → App Manager → New Connected App**, enable OAuth settings.
+2. Check **Enable Device Flow**.
+3. OAuth scopes: **Manage user data via APIs (`api`)** and **Perform requests at any time (`refresh_token`)** — the CLI requests exactly these.
+4. Save (Salesforce can take ~2–10 minutes to propagate a new Connected App), copy the **Consumer Key**, then: `fullstackgtm login salesforce --device --client-id <consumer key>`.
+
+Writeback needs no extra OAuth scope — applies are gated by the logged-in user's normal object/field permissions.
+
+### Stripe: a restricted key is enough (read-only connector)
+
+The Stripe connector only reads customers and subscriptions, and `apply` is read-only by construction. Create a **restricted key** with just **Customers: Read** and **Subscriptions: Read** (Developers → API keys → Create restricted key) instead of pasting a full-access secret key: `echo "$KEY" | fullstackgtm login stripe`.
+
 ## Concepts
 
 | Concept | What it is |
 |---|---|
 | **Canonical snapshot** | Provider-independent view of users, accounts, contacts, deals, activities. Records carry `identities` — `(provider, externalId)` claims — so the same real-world entity can be tracked across several systems. |
-| **Audit rule** | A deterministic function `(context) => { findings, operations }`. Five built-ins cover orphan accounts, ownerless deals, unlinked deals, past close dates, and stale pipeline. Write your own in ~10 lines. |
+| **Audit rule** | A deterministic function `(context) => { findings, operations }`. Eleven built-ins cover orphan accounts, ownerless/unlinked/amount-less deals, past close dates, stale pipeline, duplicates, and more — `fullstackgtm rules` lists them all. Write your own in ~10 lines. |
 | **Patch plan** | The dry-run output of an audit: findings plus typed patch operations with before/after values, reasons, risk levels, and approval flags. Always a proposal, never a mutation. |
 | **Connector** | A provider adapter: `fetchSnapshot()` for reads, optional `applyOperation()` for writes. HubSpot and Salesforce reference connectors ship in the package; connectors never drop records they can't fully resolve — the audit flags them instead. |
 | **Patch plan run** | The audit record of one apply attempt: per-operation applied/failed/skipped results. |

package/dist/cli.d.ts

@@ -12,6 +12,7 @@ export declare function doctorReport(env?: Record<string, string | undefined>):
         ok: boolean;
         required: string;
     };
+    profile: string;
     credentialStore: {
         path: string;
         exists: boolean;