@revfleet/hscli 0.9.8 → 0.11.0

package/docs/SAFETY_MODEL.md

@@ -9,6 +9,12 @@
 4. **Policy-first execution**: optional policy file can deny writes/deletes or require change-ticket context.
 5. **Graceful API resilience**: timeout + retry skeleton handles transient failures and rate limits.
 
+`policy validate` and `policy show-matching` are diagnostics, not execution
+authorization. A matching allow rule still has to pass every active runtime
+gate. Rules with `rateLimit.maxPerHour` fail closed with
+`POLICY_RATE_LIMIT_UNSUPPORTED` until a durable counter is available; they do
+not simulate hourly enforcement.
+
 ## Dry-run Contract
 - Applies to all mutating commands routed through `maybeWrite`.
 - In dry-run mode, command returns:
@@ -19,14 +25,24 @@
 - No network mutation request is sent.
 
 ## Rate Limit & Retry Baseline
-- Retry on: `429`, `5xx`, and network errors.
-- Honor `Retry-After` header when present.
-- Use capped exponential backoff.
+- Retry-eligible reads (`GET`, plus a `POST` explicitly marked as a read) retry
+  on `429`, `5xx`, and network errors.
+- Mutations (`POST`/`PATCH`/`PUT`/`DELETE` unless explicitly classified as a
+  read) do not retry by default, including on `429`. A non-retried mutation
+  `429` returns `HTTP_RETRY_DISABLED`; ambiguous mutation timeout, network, or
+  `5xx` outcomes return `HTTP_OUTCOME_UNKNOWN` for fresh server-state
+  reconciliation.
+- A retry-eligible read forced to `retryMode: never` returns
+  `HTTP_RETRY_DISABLED` for a `429` or `5xx` response.
+- An internal `retryMode: idempotent` opt-in is valid only with a verified
+  server-side idempotency contract. An `Idempotency-Key` header alone is not
+  that proof.
+- Retry-eligible requests honor `Retry-After`, use capped exponential backoff,
+  and can return `HTTP_RETRY_EXHAUSTED` after their retry budget.
 - Share observed HubSpot rate-limit state across clients in the same process by profile + API base URL.
 - Enforce HubSpot `X-HubSpot-RateLimit-Secondly`, rolling interval, and daily remaining headers before the next request.
 - Stop before daily quota exhaustion with `RATE_LIMIT_DAILY_EXHAUSTED`.
 - Enforce request timeout (`30s`) to prevent hung command invocations.
-- Surface retry exhaustion as `HTTP_RETRY_EXHAUSTED`.
 
 ## Profiles & Access
 - Profiles isolate tokens per environment/workspace.
@@ -38,3 +54,6 @@
 - Explicit JSON payload required for create/update.
 - Unknown command errors are structured and non-destructive.
 - API paths are constrained to approved HubSpot scopes.
+- A configured profile or stored portal ID is local metadata, not proof of the
+  live target. Confirm the target in the approved operation before sensitive
+  work.

package/docs/TUTORIALS/secure-agent-writes.md

@@ -89,7 +89,7 @@ Rules are evaluated **first-match-wins**, so order matters. `defaultAction: "den
 hscli policy validate ./policy.json
 ```
 
-This parses the file and flags structural issues (invalid actions, malformed `window.hours`, rules with no `match` block that would match everything). If `valid: true`, you're good.
+This parses the file and flags structural issues (invalid actions, malformed `window.hours`, rules with no `match` block that would match everything). `valid: true` means the static check passed; it does not authorize a future request or prove its target portal.
 
 ## Step 4 — dry-run rule matching
 
@@ -99,6 +99,7 @@ Before enforcing, confirm the right rule fires for the requests you expect:
 hscli --policy-file ./policy.json \
   policy show-matching POST /crm/v3/objects/contacts
 # → matched: allow-crm-writes-with-ticket, effectiveAction: allow
+# Diagnostic only: the real command still needs every runtime gate.
 
 hscli --policy-file ./policy.json \
   policy show-matching DELETE /crm/v3/objects/contacts/123
@@ -117,7 +118,7 @@ Either pass `--policy-file` on every invocation, or set it globally:
 export HSCLI_POLICY_FILE=$PWD/policy.json
 ```
 
-From now on, every `hscli` command (and every MCP tool call) runs through the policy. A denied write fails *before* the HTTP request is issued.
+From now on, hscli write paths wired to the policy control evaluate the active policy before their HTTP request. A denied guarded write fails *before* that request is issued. This is not a claim that every read, local command, or MCP tool is policy-enforced. An allowed diagnostic match remains subject to `--force`, tickets, approvals, time windows, and all other runtime controls.
 
 Try a denied operation:
 

package/docs/VALIDATION_BOUNDARIES.md

@@ -0,0 +1,101 @@
+# Validation Boundaries and Operational Limits
+
+hscli is designed to make evidence visible, not to turn a local configuration
+or a green test suite into proof about a HubSpot portal. This page records the
+boundary between local checks, CI, and a separately approved live rehearsal.
+
+| Evidence layer | Can establish | Does not establish |
+| --- | --- | --- |
+| Source and local gates | Command parsing, deterministic behavior under synthetic fixtures, type safety, lint, build output, and locked dependency resolution | HubSpot endpoint availability, portal state, scopes, subscriptions, or browser-session access |
+| CI from a clean checkout | That the declared automated gates reproduce from the committed inputs | That an operator's local profile, policy file, cookies, or target portal are current |
+| Approved live rehearsal | The specific read or write path, credential, portal, and time-window actually exercised | A blanket guarantee for other portals, identities, plans, feature flags, or later HubSpot changes |
+
+Keep these layers separate in release notes and handoffs. A successful local or
+CI check is never a substitute for an approved live rehearsal, and a live
+rehearsal must be reported with its scope rather than generalized to all
+portals.
+
+## Profile and portal identity
+
+`--profile` selects a local credential configuration. A stored or displayed
+`portalId` is local metadata and must not be treated as attestation of the
+currently authenticated target. `auth whoami` reads that saved local profile,
+including its historical `identityVerified` value; it does not call HubSpot and
+is not live identity proof. Before a sensitive live operation, use only a
+remote target check explicitly supported and authorized by that operation,
+compare it with the approved target, and keep source, sandbox, and production
+profiles distinct.
+
+This applies equally to agent-run evidence: a profile name and declared policy
+path describe local execution context. They do not prove a live target, and
+they do not cryptographically authenticate older local artifacts.
+
+## Agent resume migration
+
+Resumable agent runs require a manifest and checkpoint carrying the same run
+ID, plus the retained stdout/stderr files and matching completion events for
+every step that would be skipped. Historical checkpoints without that run-ID
+binding are intentionally not resumable. Preserve them as legacy evidence if
+needed, then start a new output directory without `--resume`; do not add a run
+ID by hand or relabel the old steps as fresh evidence.
+
+## Policy diagnostics and enforcement
+
+`hscli policy validate` parses and statically checks a policy file. `hscli
+policy show-matching` evaluates a hypothetical method/path against that file.
+They are useful diagnostics, but neither command executes the request or grants
+permission. In particular, an `effectiveAction: allow` result still needs the
+actual command to pass all execution-time controls: canonical path handling,
+the active policy, `--force` for writes, tickets, approvals, windows, and any
+other applicable gates.
+
+Policy rules that declare `rateLimit.maxPerHour` are not backed by a durable
+hourly counter. The reviewed implementation fails closed with
+`POLICY_RATE_LIMIT_UNSUPPORTED` rather than pretending that the limit was
+enforced. Operators must remove that rule only after choosing and reviewing an
+appropriate external or durable rate-control mechanism.
+
+Built-in policy templates are starting points. Extracting a template creates a
+separate local policy file; later changes to a template, including a newly
+covered HTTP method such as `PUT`, do not retrofit an already extracted or
+active policy. Re-extract or edit the intended policy, then validate and review
+it before use.
+
+## Backup completeness
+
+`hscli backup plan` is plan-only: it makes no HubSpot request and creates no
+archive. Its coverage model is a checklist, not proof that every asset was
+captured. Capture execution still has known limitations: some reads materialize
+pages in memory, and a complete durable pagination/resume reconciliation is not
+yet guaranteed across every backup surface.
+
+Treat a backup as partial until the operator reconciles object counts and
+cursors, records unavailable or permission-blocked surfaces, and verifies the
+resulting capture manifest. Do not call a plan, a successful command, or an
+archive complete merely because no local error was emitted.
+
+The record `crm sync pull` fields have deliberately narrower meanings:
+
+- `complete` and `captureScope.paginationExhausted` mean this traversal reached
+  the end of its pagination cursor; they do not prove a complete portal archive.
+- `captureScope.objectSnapshotComplete` means a fresh, unfiltered list
+  traversal started at the initial cursor and exhausted pagination for that
+  object. It does not prove every property, association, file, report, or other
+  portal surface was captured.
+- The backup plan's `--full-snapshot --max-pages all` record commands retain all
+  fetched pages in memory. A full snapshot refuses an existing state file or
+  output file rather than silently mixing old and new results.
+
+Sync checkpoint reuse is separate from agent resume. A reusable sync state is
+bound to the configured `portalId`, local profile name, object type, mode,
+`since` value, limit, and query fingerprint. Legacy states without that binding
+are refused; this prevents cursor reuse across a different declared scope but
+does not attest a live target.
+
+## Release language
+
+Use precise, time-bounded claims. For example, “`npm audit` reported zero
+advisories at verification time” describes an observed result; it does not mean
+that future advisory databases will remain empty. Likewise, a reviewed source
+diff is not merged, deployed, published, or live-tested until those separate
+actions have been explicitly authorized and evidenced.

package/docs/policy-templates/compliance-strict.json

@@ -29,6 +29,13 @@
           "action": "allow",
           "requireChangeTicket": true,
           "window": { "tz": "US/Eastern", "hours": "09-17", "days": "mon-fri" }
+        },
+        {
+          "name": "puts-require-change-ticket-and-hours",
+          "match": { "method": "PUT", "path": "**" },
+          "action": "allow",
+          "requireChangeTicket": true,
+          "window": { "tz": "US/Eastern", "hours": "09-17", "days": "mon-fri" }
         }
       ]
     }

package/examples/cloud-run-mcp-caller.mjs

@@ -0,0 +1,71 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const READ_ONLY_TOOLS = new Set([
+  "hscli_service_info",
+  "crm_properties_list",
+  "crm_pipelines_list",
+]);
+
+function serviceEndpoint(cloudRunServiceUrl, label) {
+  const service = new URL(cloudRunServiceUrl);
+  if (service.protocol !== "https:" || service.pathname !== "/" || service.search || service.hash || service.username || service.password || service.port) {
+    throw new Error(`${label} must be an HTTPS base URL without a path`);
+  }
+  return service.origin;
+}
+
+/**
+ * Server-only example: its authenticatedSubject and portalId must come from the
+ * web service's own authenticated request context, not from browser headers,
+ * query parameters or tool arguments. resolveAuthorizedPortal is responsible
+ * for authorizing that pair and obtaining short-lived server-held HubSpot data.
+ */
+export async function callAuthorizedHostedMcp({
+  cloudRunServiceUrl,
+  mcpTargetUrl,
+  authenticatedSubject,
+  portalId,
+  toolName,
+  toolArguments,
+  resolveAuthorizedPortal,
+  getGoogleIdToken,
+  fetch,
+}) {
+  // `cloudRunServiceUrl` is the canonical service URL for the Google ID-token
+  // audience. `mcpTargetUrl` is the freshly checked tagged candidate URL; do
+  // not infer it from a shared tag without checking it still names this revision.
+  const audience = serviceEndpoint(cloudRunServiceUrl, "Cloud Run service URL");
+  const mcpUrl = new URL("/mcp", serviceEndpoint(mcpTargetUrl, "MCP target URL"));
+  if (!READ_ONLY_TOOLS.has(toolName)) throw new Error("HOSTED_TOOL_NOT_ALLOWED");
+
+  // Do this before requesting a Google token or constructing an HTTP transport.
+  const hubSpotContext = await resolveAuthorizedPortal({ authenticatedSubject, portalId });
+  if (!hubSpotContext || hubSpotContext.portalId !== portalId) throw new Error("PORTAL_NOT_AUTHORIZED");
+  if (!/^[0-9]+$/.test(hubSpotContext.portalId) || !["eu1", "na1"].includes(hubSpotContext.hublet) || !hubSpotContext.accessToken) {
+    throw new Error("INVALID_AUTHORIZED_PORTAL_CONTEXT");
+  }
+
+  // An attached Cloud Run identity normally implements this with ADC's
+  // google-auth-library.getIdTokenClient(audience). The ID token is not a
+  // HubSpot credential and is sent in a distinct Cloud Run IAM header.
+  const googleIdToken = await getGoogleIdToken(audience);
+  if (!googleIdToken) throw new Error("GOOGLE_ID_TOKEN_REQUIRED");
+  const client = new Client({ name: "authorized-web-backend", version: "example" });
+  try {
+    await client.connect(new StreamableHTTPClientTransport(mcpUrl, {
+      fetch,
+      requestInit: {
+        headers: {
+          "X-Serverless-Authorization": `Bearer ${googleIdToken}`,
+          "X-HubSpot-Access-Token": hubSpotContext.accessToken,
+          "X-HubSpot-Portal-Id": hubSpotContext.portalId,
+          "X-HubSpot-Hublet": hubSpotContext.hublet,
+        },
+      },
+    }));
+    return await client.callTool({ name: toolName, arguments: toolArguments });
+  } finally {
+    await client.close();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revfleet/hscli",
-  "version": "0.9.8",
+  "version": "0.11.0",
   "description": "HubSpot operations and migration control plane for humans and agents, with deterministic runbooks, policy guardrails, and auditable evidence.",
   "type": "module",
   "bin": {
@@ -18,9 +18,9 @@
     "docs:mcp": "npm run build && node scripts/generate-mcp-catalog.mjs",
     "docs:mcp:check": "npm run build && node scripts/generate-mcp-catalog.mjs --check",
     "release:checksums": "node scripts/release-checksums.mjs",
-    "audit": "npm audit --audit-level=high",
+    "audit": "npm audit --audit-level=low",
     "release:verify": "npm run typecheck && npm run lint && npm test && npm run audit && npm run build && npm run release:checksums && shasum -a 256 -c release/checksums.sha256",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "prepublishOnly": "npm run release:verify",
     "clean": "rm -rf dist"
   },
   "keywords": [
@@ -62,6 +62,7 @@
     "docs/TUTORIALS/*.md",
     "docs/POLICY_EXAMPLE.json",
     "docs/policy-templates",
+    "examples/cloud-run-mcp-caller.mjs",
     "brand/readme-hero.svg",
     "README.md",
     "CONTRIBUTING.md",
@@ -73,20 +74,22 @@
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "commander": "^14.0.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.5.0",
-    "eslint": "^10.0.3",
-    "tsx": "^4.19.2",
+    "@types/node": "^26.1.1",
+    "eslint": "^10.7.0",
+    "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.57.0",
+    "typescript-eslint": "^8.64.0",
     "vitest": "^4.1.0"
   },
   "overrides": {
+    "hono": "^4.13.0",
+    "ip-address": "^10.4.0",
     "path-to-regexp": "^8.4.2"
   }
 }