@revfleet/hscli 0.9.8 → 0.10.0

package/docs/COOKBOOK.md

@@ -17,6 +17,43 @@ hscli auth login
 `auth login` uses a hidden terminal prompt, so the token never enters shell
 history. Use stdin only for CI or non-interactive shells.
 
+The default auth type is `private-app`. Keep it explicit in runbooks:
+
+```bash
+hscli auth login --auth-type private-app --profile production
+```
+
+### Login with an account Service Key
+
+Service Keys are stable, scoped account credentials for REST API operations.
+They are not Personal Access Keys and hscli does not infer the type from their
+prefix.
+
+```bash
+hscli auth login --auth-type service-key --profile automation
+hscli --profile automation auth whoami
+```
+
+`whoami` reports `restOnly: true` for Service Key profiles. Webhooks, UI
+extensions, and other app-platform features need their own supported auth path.
+
+### Login with a Personal Access Key
+
+Personal Access Keys are tied to one HubSpot user and account. hscli exchanges
+the key for a short-lived access token and refreshes it automatically five
+minutes before expiry.
+
+```bash
+hscli auth login \
+  --auth-type personal-access-key \
+  --portal-id 123456 \
+  --profile local-dev
+```
+
+The expected portal ID is checked before the profile is saved and again during
+refresh. Use `hscli auth encrypt` because the PAK must remain available locally
+to mint replacement access tokens.
+
 Hublet is auto-detected from the token prefix (e.g. `pat-eu1-...` routes to `api-eu1.hubapi.com`).
 If the token does not expose enough metadata, force routing explicitly:
 
@@ -30,6 +67,13 @@ hscli --hublet eu1 --profile live account info
 
 ```bash
 echo "$HUBSPOT_TOKEN" | hscli auth login --token-stdin --profile production
+
+printf '%s' "$HUBSPOT_SERVICE_KEY" | hscli auth login \
+  --auth-type service-key --token-stdin --profile automation
+
+printf '%s' "$HUBSPOT_PERSONAL_ACCESS_KEY" | hscli auth login \
+  --auth-type personal-access-key --portal-id 123456 \
+  --token-stdin --profile local-dev
 ```
 
 ### Switch between profiles
@@ -95,8 +139,8 @@ hscli --profile oauth-prod auth whoami
 
 The access token refreshes automatically before expiry. hscli stores the
 refresh token and the client-secret environment variable name, never the
-client secret itself. Use `hscli --profile oauth-prod auth refresh` to force a
-rotation while diagnosing an OAuth installation.
+client secret itself. Use `hscli --profile oauth-prod auth refresh` to run the
+same expiry check explicitly while diagnosing an OAuth installation.
 
 ---
 

package/docs/INTERNAL-ENDPOINTS-DISCOVERY.md

@@ -811,3 +811,62 @@ Asset	Body export	Notes
 Sequence	✅ Full	GET /api/sequences/v3/sequences/{id} — includes steps, settings, email templates by ID, send window, unenrollment rules, dependencies
 Playbook	✅ Full	listPlaybooks RPC returns body + htmlBody inline. Plus questions via separate RPC.
 Caveat: Sequence steps reference templates by ID; full fidelity requires also fetching template bodies. Same for playbook questions.
+
+## Iteration 16 — promoted operator commands and guarded workflow replacement
+
+The following contracts were promoted from discovery notes into explicit hscli
+commands. They are intentionally not exposed as arbitrary internal HTTP calls:
+
+| Command | Endpoint | Evidence semantics |
+|---|---|---|
+| `workflows inspect <flowId>` | `GET /api/automationplatform/v1/flows/{flowId}?portalId={portalId}` | Current full editor definition; internal browser-session source. |
+| `workflows revisions <flowId>` | `GET /api/automationplatform/v1/hybrid/revisions/{flowId}?portalId={portalId}&limit=100&after=...` | Revision definitions and authors; paginated completeness is reported. |
+| `workflows errors <flowId>` | `GET /api/automationapps/v1/insights/canvas/errors/{flowId}` | Rolling seven-day canvas evidence; explicitly marked incomplete outside that window. |
+| `lists inspect-filters <listId>` | `GET /api/inbounddb-lists/v1/lists/{listId}` | Internal filter tree. |
+| `crm record-layouts ...` | `/api/crm-record-cards/v4/...` | Record-page layouts and card property configuration. |
+
+`POST /api/automationplatform/v1/hybrid/batch` is a full workflow replacement,
+not a normal CRUD update. It is available only through the CLI command
+`workflows update-internal` and is forbidden in generic `internal capture` and
+MCP. The command is plan-only by default and execution requires a disabled
+single flow, exact ID match, fresh live version, HubSpot validation, same-session
+portal proof, a private pre-write snapshot, `version = live + 1`, a sealed
+action contract, change ticket, global `--force`, experimental opt-in, and the
+exact acknowledgement `REPLACE WORKFLOW <flowId>`. The non-idempotent save is
+sent once with retries disabled, then reconciled against both current state and
+revision history. Any ambiguous result fails closed and instructs the operator
+not to retry automatically.
+
+`PUT /api/crm-record-cards/v4/crm-cards/{cardId}` is also a full replacement,
+even when the intended edit is only one property list. The promoted command
+`crm record-layouts update-card` therefore accepts only an ordered CSV of
+`propertyNames`, merges it into the freshly-read full card, and uses the same
+plan-first, portal-proof, private snapshot, sealed contract, ticket, explicit
+acknowledgement, no-retry, and post-write verification model. It is CLI-only
+and absent from the generic internal capture catalogue and MCP.
+
+The public seat-history companion is:
+
+```text
+GET /crm/v3/objects/0-115/{userId}
+  ?properties=hs_assigned_seats
+  &propertiesWithHistory=hs_assigned_seats
+  &archived=false
+```
+
+It is exposed as `settings users seat-history <userId>` and does not use
+browser credentials.
+
+Two discoveries remain documentation-only because the supplied evidence does
+not include a complete executable RPC contract:
+
+- `CrmUsagesUiService/getPageOfFilteredUsagesForDependencyNodeAndAssetDisplayType`
+  needs the exact fully-qualified Chirp service name and a redacted request
+  fixture before it can be allowlisted.
+- `UserPermissionAuditLogsRpc/getPagedLogs` needs the exact fully-qualified
+  Chirp service name. Its known body uses `{ userId, offset: {}, limit }`, and
+  the pagination cursor is an object rather than an integer.
+
+No live write was used to validate this iteration. The workflow replacement is
+covered by mocked contract and safety tests; its internal HubSpot contract must
+still be treated as unstable.

package/docs/INTERNAL-ENDPOINTS.md

@@ -69,6 +69,19 @@ Workflows
 Method	Path	Status	Notes
 GET	/api/automation/v4/flows	✅	List flows. Hard cap limit=100; paginate via after.
 GET	/api/automation/v4/flows/{id}	❌	401 from in-tab JS.
+GET	/api/automationplatform/v1/flows/{id}?portalId={portalId}	✅	Current editor definition in hybrid format; `hscli workflows inspect`.
+GET	/api/automationplatform/v1/hybrid/{id}	✅	Full hybrid action graph.
+GET	/api/automationplatform/v1/hybrid/revisions/{id}?portalId={portalId}&limit=100&after={cursor}	✅	Full revision history with definitions and authors; `after` is optional.
+POST	/api/automationplatform/v1/validation?portalId={portalId}	✅	Read-like validation preview before save.
+GET	/api/automationapps/v1/insights/canvas/errors/{id}	✅	Rolling canvas execution/enrollment errors.
+POST	/api/automationplatform/v1/hybrid/batch	⚠️	Undocumented full-flow replacement. CLI-only via `workflows update-internal`; disabled flows only, plan-first, snapshot, no retry, post-save verification, and high-risk acknowledgement. Forbidden in generic internal capture and MCP.
+PUT	/api/crm-record-cards/v4/crm-cards/{cardId}	⚠️	Undocumented full-card replacement. CLI-only via `crm record-layouts update-card`; propertyNames-only delta, plan-first, snapshot, no retry, exact post-save order verification. Forbidden in generic internal capture and MCP.
+
+Public seat-history companion: `GET /crm/v3/objects/0-115/{userId}` with
+`properties=hs_assigned_seats` and
+`propertiesWithHistory=hs_assigned_seats`, exposed as
+`hscli settings users seat-history <userId>`. This does not require a browser
+session.
 POST	/api/automation/v4/flows	✅	Create flow.
 PUT/PATCH	/api/automation/v4/flows/{id}	✅	Update.
 DELETE	/api/automation/v4/flows/{id}	✅	Soft delete; recoverable from Deleted view.

package/docs/INTERNAL_ENDPOINTS.md

@@ -58,7 +58,7 @@ read-like surfaces into JSON backup assets:
 | `permission-access` | App users, teams, permission sets, assignment maps, roles, seats, templates, FLP, and access-audit RPCs |
 | `datasets-reporting` | Data Studio datasets, reportable sources, joins, formulas, previews, async resolve calls, and async result polling |
 | `reports-dashboards` | Report definitions, favorites, report audit/history, record-view metadata, report permissions, report template discovery, dashboard layouts, widgets, dashboard grants, and report-list views |
-| `workflows-hybrid` | Workflow inventories, hybrid action graphs, validation, output fields, action catalog, CRM object context, canvas errors, access checks, filter-description previews, and card-position RPCs |
+| `workflows-hybrid` | Workflow inventories, current hybrid action graphs, full revision history, validation previews, output fields, action catalog, CRM object context, canvas errors, access checks, filter-description previews, and card-position RPCs |
 | `properties-metadata` | Internal property metadata, legacy v1/v2 fallbacks, property groups, grouped-property listings, named property reads, recycled properties, quotas, fill rates, validation, dynamic options, and conditional options |
 | `crm-search` | Read-only CRM search, CRM GraphQL, object preview, and single-object UI payload helpers used by report builders, help desk, quotes, and object indexes |
 | `object-metadata` | Schema metadata, framework-builder metadata, portal-scoped object types, event object types, and object-type batch reads |
@@ -107,6 +107,24 @@ for research and migration design, but they are not included in
 be implemented as explicit product commands with policy checks, dry-run,
 `--force`, and audit trails.
 
+The sole promoted workflow write adapter is
+`hscli workflows update-internal <flowId>`. It targets the undocumented
+`POST /api/automationplatform/v1/hybrid/batch` editor endpoint and is never
+part of `internal capture` or MCP. It is plan-only by default and adds stronger
+gates than normal writes: one disabled flow, matching requested/input/live ID,
+same-session portal proof, live-version optimistic locking, validation,
+owner-only snapshot, one request with retries disabled, and post-save proof
+from both current state and revision history. Operators must also provide a
+change ticket, sealed action contract, explicit experimental opt-in, `--force`,
+and an ID-bound acknowledgement.
+
+Record-card writes are similarly promoted only through
+`crm record-layouts update-card`. The command reads the live card, replaces
+only `configuration.propertyNames`, snapshots the full before/after payload,
+uses one non-retried `PUT /api/crm-record-cards/v4/crm-cards/{cardId}`, and
+verifies the exact ordered property list. It is not available to generic
+capture or MCP.
+
 ## Browser Session Auth Pattern
 
 Most internal endpoints require the HubSpot browser cookies plus the modern
@@ -189,9 +207,9 @@ commands. hscli exposes only the allowlisted reads below through
 | Reports | `/api/dashboard/v2/reports/*`, `/reporting-migration/v2/reports/migrate` |
 | Reporting data | `/api/reporting/v3/dataset/resolve/async` |
 | Datasets | `/sql-reporting/v1/datasets/*`, `/sql-reporting/v1/extended-reportable-options/*` |
-| Workflows | `/api/automationplatform/v1/hybrid/{flowId}`, validation, output fields, action catalog |
+| Workflows | `/api/automationplatform/v1/flows/{flowId}`, `/api/automationplatform/v1/hybrid/{flowId}`, `/api/automationplatform/v1/hybrid/revisions/{flowId}`, validation, canvas errors, output fields, action catalog; guarded CLI-only full replacement via `/api/automationplatform/v1/hybrid/batch` |
 | Properties | `/api/properties/v4/{typeId}`, `/api/properties/v4/groups/{typeId}`, v2 fallbacks |
-| Lists / segments | Legacy contacts lists, ILS segments, list search, and UI list views |
+| Lists / segments | Legacy contacts lists, ILS segments, list search, UI list views, and `/api/inbounddb-lists/v1/lists/{listId}` complete filter trees |
 | Sales content | `/api/templates/v1`, `/api/sales-content/v1`, `/api/sales-content-libraries/v2` |
 | Sequences | `/api/salescontentsearch/v2/search`, `/api/sequences/v3/sequences/{id}` |
 | Playbooks | Chirp RPC `com.hubspot.playbooks.rpc.PlaybooksRpc` |
@@ -206,7 +224,7 @@ commands. hscli exposes only the allowlisted reads below through
 | Social and ads | `/api/broadcast/v2/*` plus read-only `com.hubspot.ads.rpc.*` Chirp RPCs |
 | CRM search and previews | `/api/crm-search/*`, `/api/graphql/crm`, and `/inbounddb-objects/v1/*` |
 | Conditional properties | `/api/conditional-properties/v2/rules/*` plus unified RPC reads |
-| Record cards | `/api/crm-record-cards/v4/container-views/*` |
+| Record cards | `/api/crm-record-cards/v4/container-views/search`, `/get-view/CRM_RECORD_PAGE/{layoutId}`, `/api/crm-record-cards/v4/crm-cards/all`, and `/crm-cards/{cardId}` |
 | Conversations / help desk | Custom views and Chirp RPC help desk services |
 | Chatflows | Chirp RPC `com.hubspot.chatflows.rpc.*` |
 | Payments / quotes / forecast | Feature-gated internal setup and eligibility endpoints |

package/docs/MCP.md

@@ -18,6 +18,11 @@ hscli mcp                                      # minimal: essential CRM reads
 hscli mcp --surface crm                        # curated CRM reads + writes
 hscli mcp --surface migration                  # cross-product migration tools
 hscli mcp --surface full                       # all tools, including raw API
+hscli --json mcp manifest --surface minimal    # protocol + transport + tool metadata
+hscli --profile prod --json mcp doctor         # local profile and safety diagnostics
+hscli --profile prod --json mcp doctor --all   # external checks, clearly marked not live-run
+hscli --profile prod --json mcp setup --client codex  # plan only; no credential/config write
+hscli --json mcp matrix                        # intended use + trust boundaries
 ```
 
 The default `minimal` surface keeps agent context and write exposure small.
@@ -26,10 +31,12 @@ pass command arguments.
 
 ## Profile isolation and safety defaults
 
-- **Profile isolation**: set `HSCLI_MCP_PROFILE=<profile>` to hard-lock the MCP server to one auth profile.
+- **Profile isolation**: `hscli --profile <profile> mcp serve` hard-locks the server to that startup profile by default.
   - If a tool call requests a different profile, the server rejects it.
+  - Cross-profile selection is available only with the operator-controlled `--allow-cross-profile` startup flag.
 - **Write tools are dry-run by default**:
-  - `force: true` is required to execute actual writes.
+  - `force: true` on the tool call is necessary but not sufficient.
+  - The operator must also start the server with `--allow-writes` (or explicitly set `HSCLI_MCP_ALLOW_WRITES=1`).
   - Without `force`, write tools return a dry-run payload (`{ dryRun: true, method, path, body }`).
 - **Lifecycle coverage for CRM objects**:
   - standard object tools now include delete, merge, batch read/upsert/archive.
@@ -39,6 +46,20 @@ pass command arguments.
   - Pipeline object types: `deals`, `tickets`
 - **Secrets redaction**:
   - Token-like fields and bearer strings are redacted in MCP tool outputs and errors.
+- **Conservative tool annotations**:
+  - Every registered tool publishes `readOnlyHint`, `destructiveHint`,
+    `idempotentHint`, and `openWorldHint`.
+  - Unknown or mixed-operation tools default to write/destructive metadata.
+  - `manage_crm_objects` and raw `hub_api_request` are destructive because
+    their runtime arguments can select delete operations.
+- **Stable diagnostic schemas**:
+  - `hscli_mcp_manifest` and `hscli_mcp_doctor` publish MCP `outputSchema`
+    declarations and return validated structured content.
+  - The 11-tool HubSpot name-compatible subset also publishes object-level
+    output schemas so clients can rely on structured content without assuming
+    HubSpot Remote MCP authorization or transport equivalence.
+  - Raw HubSpot tools deliberately do not claim stable output schemas because
+    their response shapes vary by endpoint, product tier, and portal state.
 
 ## Claude Desktop setup
 
@@ -84,14 +105,29 @@ If your client accepts env vars, set:
 - `HSCLI_HOME` to the auth profile directory containing `auth.json`
 - `HSCLI_MCP_PROFILE` to force strict profile isolation
 
+## Three-server setup
+
+The products are complementary and should be configured side by side:
+
+| Server | Transport / auth | Best use |
+|---|---|---|
+| HubSpot Remote MCP | Streamable HTTP, OAuth 2.1 + PKCE, HubSpot user permissions | User-authorized CRM, activities, content, and marketing operations |
+| HubSpot Developer MCP | stdio via HubSpot CLI 8.2+ | HubSpot app and CMS development (`hs mcp setup`) |
+| hscli MCP | local stdio, hscli profile | Bulk operations, migrations, backups, internal adapters, policy, tickets, audit evidence |
+
+Run `hscli --profile <name> --json mcp setup --client <client>` for a
+secret-free plan. The command does not perform OAuth, write client config, or
+store credentials. Run `mcp doctor --all` afterward; external checks remain
+`external-check-required` until the owning client completes them.
+
 ## Tool surfaces
 
 | Surface | Tools | Intended use | Raw API |
 |---|---:|---|---|
-| `minimal` | 29 | Agent discovery and essential CRM reads | No |
-| `crm` | 136 | CRM objects, schemas, properties, associations, imports | No |
-| `migration` | 179 | Curated cross-product backup and migration work | No |
-| `full` | 180 | Explicit operator access to every registered tool | Yes |
+| `minimal` | 31 | Agent diagnostics, discovery, and essential CRM reads | No |
+| `crm` | 138 | CRM objects, schemas, properties, associations, imports | No |
+| `migration` | 181 | Curated cross-product backup and migration work | No |
+| `full` | 182 | Explicit operator access to every registered tool | Yes |
 
 The exact catalog is generated from runtime registration metadata, including
 domain, inferred risk, surfaces, and description:
@@ -107,5 +143,11 @@ npm run docs:mcp:check
 ## Notes
 
 - MCP transport is stdio only in this implementation.
+- The packaged SDK currently negotiates MCP `2025-11-25`. Streamable HTTP,
+  MCP Tasks, MCP Apps, and explicit `2026-07-28` opt-in are not enabled.
+  They require a separate SDK-v2 migration and transport compatibility gate.
 - Existing auth + HTTP core logic is reused (`getToken`, `HubSpotClient`, `maybeWrite`, redaction).
 - `hub_api_request` is exposed only by `--surface full`.
+- MCP writes use the startup write gate, dry-run, force, policy, portal-pin, and change-ticket gates,
+  but are not yet bound to sealed `hscli agent contract` prepare/apply/verify
+  workflows. `mcp doctor` reports this limitation explicitly.