node-autotask 0.17.0 → 0.19.0

package/docs/API.md

@@ -93,7 +93,7 @@ auto-retry on all legs — plus a concurrency guard (`maxConcurrent`, default 10
 allows <= 10 concurrent), one correlation id per request (surfaced on every
 error and to `onAudit`), and the opt-in client-side hourly budget tracker
 (`rateLimit.perHour`, default off — a sliding one-hour window that waits for a slot within the call deadline, else throws `RateLimitError` with `retryAfter`; the API allows 10,000 req/hour). The tracker is PER PROCESS: it counts only this client's attempts and cannot see other instances or integrations on the tenant (`thresholdInformation.get()` is the only cross-integration signal; the local count is `client.hourlyBudget()`, section 3.2.1). Under the `agent` config profile the exhaustion `suggestedAction` says stop or narrow the query — never raise the limit.
-Redirects are never followed (a 3xx throws `REDIRECT_BLOCKED`, so auth headers cannot leave the configured origin). Retry waits are capped at 60 s and never outlast the call deadline: a larger `Retry-After` (or one that exceeds the remaining budget) throws the `RateLimitError` immediately. `RequestOptions` adds `signal` (caller `AbortSignal`, combined with the deadline; aborting throws `AutotaskAbortError`, code `ABORTED`, and cancels retry sleeps) and `idempotent` (retry a non-GET method on 5xx/network errors; set on the `/query` and `/query/count` POST reads; on a mutation it is the issue #105 opt-back into the pre-#105 auto-retry — never set on real writes by the SDK). `client.withSignal(signal, () => ...)` applies a caller `AbortSignal` to every request (and retry wait) made inside the callback — the way to propagate MCP request cancellation through `invoke` without a signal parameter on each method. A real write clears the read cache. A non-JSON 2xx body is typed by the response `Content-Type` (section 2.1): a non-JSON-ish header throws the retryable `UNEXPECTED_CONTENT_TYPE` (the edge/maintenance page — a maintenance notice is waited out up to `maintenanceMaxWaitMs`, default 1 h, for reads and writes; otherwise a GET or idempotent-flagged call retries and a write makes one call: section 2.1); a JSON-ish or ABSENT header keeps `INVALID_RESPONSE` (the #13/W-A7 shape-drift key); JSON under any other header still decodes (the decode attempt is unconditional). A blank 2xx on a call that expects a result (every method but `DELETE` by default — `RequestOptions.expectBody`) throws the typed `EMPTY_RESPONSE` (`DELETE` and 204 keep returning `undefined`). A response above `maxResponseBytes` throws `RESPONSE_TOO_LARGE`; HTTP 412 maps to `ConflictError` (category `conflict`).
+Redirects are never followed (a 3xx throws `REDIRECT_BLOCKED`, so auth headers cannot leave the configured origin). Retry waits are capped at 60 s and never outlast the call deadline: a larger `Retry-After` (or one that exceeds the remaining budget) throws the `RateLimitError` immediately. `RequestOptions` adds `signal` (caller `AbortSignal`, combined with the deadline; aborting throws `AutotaskAbortError`, code `ABORTED`, and cancels retry sleeps) and `idempotent` (retry a non-GET method on 5xx/network errors; set on the `/query` and `/query/count` POST reads; on a mutation it is the issue #105 opt-back into the pre-#105 auto-retry — never set on real writes by the SDK). `client.withSignal(signal, () => ...)` applies a caller `AbortSignal` to every request (and retry wait) made inside the callback — the way to propagate MCP request cancellation through `invoke` without a signal parameter on each method. A real write clears the read cache. A non-JSON 2xx body is typed by the response `Content-Type` (section 2.1): a non-JSON-ish header throws the retryable `UNEXPECTED_CONTENT_TYPE` (the edge/maintenance page — a maintenance notice is waited out up to `maintenanceMaxWaitMs`, default 1 h, for reads and writes; the same wait recognises the page at any status for calls safe to re-send (a GET or an explicitly idempotent-flagged call — an unflagged mutation makes ONE send with `details.maintenanceDetected`): section 2.1; otherwise a GET or idempotent-flagged call retries and a write makes one call); a JSON-ish or ABSENT header keeps `INVALID_RESPONSE` (the #13/W-A7 shape-drift key); JSON under any other header still decodes (the decode attempt is unconditional). A blank 2xx on a call that expects a result (every method but `DELETE` by default — `RequestOptions.expectBody`) throws the typed `EMPTY_RESPONSE` (`DELETE` and 204 keep returning `undefined`). A response above `maxResponseBytes` throws `RESPONSE_TOO_LARGE`; HTTP 412 maps to `ConflictError` (category `conflict`).
 Per-tenant 429 cooldown gate (`cooldown`, ON by default): once a 429 surfaces from the transport (retries spent, a `Retry-After` too long to wait out, or a non-retriable method), the client records a cooldown deadline for that tenant (lowercased `UserName` + lowercased host — impersonation does not change the key), and every further call for that tenant fails LOCALLY — before the semaphore, the hourly limiter and fetch, with zero upstream calls — with a `RateLimitError` (`code: 'RATE_LIMITED_COOLDOWN'`, `notSent: true`, `retryAfter` = remaining seconds; no credentials appear in the message) until the deadline passes. Duration is `Retry-After` clamped to `cooldown.maxMs` (default 15 minutes), or `cooldown.defaultMs` (default 60 s) when the header is missing or unparseable; the thread-threshold 429 (vendor code `Itgenatr005`, which clears in seconds) arms only a short window: min(`Retry-After`, 10 s), default 5 s. A 2xx from a call that got through clears the gate early; expiry is lazy (the first call after the deadline deletes the entry and proceeds); a hostile `Retry-After` (huge, zero, negative, non-numeric) is clamped to the cap or falls back to the default, so a lock-out is always bounded. `thresholdInformation.get()` bypasses the gate so a throttled tenant can still read its own headroom (a 2xx from it clears the gate; a 429 re-arms it). The default store is the in-process in-memory map shared by every client instance (capped at 1024 entries, evicting the earliest deadline first — failing open); `cooldown: { enabled: false }` disables the gate and `cooldown.store` injects a custom `CooldownStore` (the interface leaves room for a shared/Redis-backed store). Gated calls emit an audit event marked `notSent` and do not count toward `rateLimit.perHour`. Limits worth knowing: the gate is per process — other processes and integrations on the same tenant are invisible to it (`thresholdInformation` is the only cross-integration signal); it can mask early recovery if the vendor window clears before `Retry-After`; a process that loads both the ESM and the CJS build gets two default stores (the default store is deliberately not anchored on `globalThis`) — inject one shared `CooldownStore` if you need cross-build sharing.
 
 Credential-shaped fields are redacted in audit payloads by default.
@@ -166,8 +166,10 @@ served payload verbatim).
 
 `buildFilter(conditions)` wraps caller conditions (multiple top-level
 conditions are `and`-wrapped); `validateFilter` enforces the vendor caps
-(section 5 below). `buildQueryRequest` produces the `QueryModel` wire body
-(`{ MaxRecords, IncludeFields?, filter }`). `normalizedConditions` is the
+(section 5 below). `buildQueryBody` produces the `QueryModel` wire body
+(`{ MaxRecords, IncludeFields?, filter }`, `id` appended to a caller
+`includeFields`), shared by page 1 (`buildQueryRequest`) and every cursor
+continuation of a walk (issue #118). `normalizedConditions` is the
 shared filter-shape gate of the query family (every query-family entry
 point routes through it pre-request): the `filter` param accepts a
 conditions array or `{ filter: [...] }`, and `undefined`/`null` are the
@@ -257,7 +259,7 @@ status → what the vendor does that triggers it.
 | `RateLimitError` | `RATE_LIMITED` | rate_limit | 429 | hourly/secondly budget exceeded — `retryAfter` from `Retry-After` — retryable |
 | `RateLimitError` | `RATE_LIMITED_COOLDOWN` | rate_limit | — (call not sent) | per-tenant cooldown after a surfaced 429 (issue #6) — `notSent: true`, `retryAfter` = remaining seconds — not retryable before the deadline |
 | `ServerError` | `SERVER_ERROR` | server | 5xx | vendor 5xx — retryable — EXCEPT a deterministic field-validation 500 (a known phrase, `isDeterministicVendor500`): same class/code/status, `retryable: false` + `details.deterministic: true` (issue #23) |
-| `UnexpectedContentTypeError` | `UNEXPECTED_CONTENT_TYPE` | server | 2xx (non-JSON body + a non-JSON-ish `Content-Type`) | the edge serves a non-JSON page (maintenance) — the vendor never processed the request; `details = { httpStatus, contentType, bodySnippet (256 B) }` — retryable (advisory). A maintenance-notice page is waited out up to `maintenanceMaxWaitMs` (default 1 h) for reads AND writes; on exhaustion `details.maintenance` reports the wait (section 2.1) |
+| `UnexpectedContentTypeError` | `UNEXPECTED_CONTENT_TYPE` | server | 2xx (non-JSON body + a non-JSON-ish `Content-Type`) | the edge serves a non-JSON page (maintenance) — the vendor never processed the request; `details = { httpStatus, contentType, bodySnippet (256 B) }` — retryable (advisory). A non-JSON `2xx` maintenance page is waited out up to `maintenanceMaxWaitMs` (default 1 h) for reads AND writes; at `4xx`/`5xx` the page is waited out only for calls safe to re-send (GET / explicitly idempotent-flagged) — an unflagged mutation makes one send and carries `details.maintenanceDetected` (issue #114); a wait that ran is reported on the surfaced error as `details.maintenance` (section 2.1) |
 | `EmptyResponseError` | `EMPTY_RESPONSE` | server | 2xx (empty body, `expectBody`) | a blank 2xx on a call that expects a result (non-DELETE by default — section 2.1); `details = { httpStatus, method }` — retryable for non-DELETE (advisory: the loop never retries 2xx) |
 | `CircuitBreakerError` | `CIRCUIT_BREAKER_OPEN` | policy | — (call not sent) | the host circuit breaker (issue #26, opt-in) is open — refused LOCALLY before the request (zero upstream calls, no hourly stamp) — `notSent: true`, `retryAfter` = remaining open seconds — **retryable: true** (the deliberate divergence from #6's not-retryable cooldown refusal: the open period is bounded and advertised; section 3.2.2) |
 | `ResolutionError` | `RESOLUTION_AMBIGUOUS` / `RESOLUTION_TRUNCATED` / `NOT_FOUND` | resolution | — | `resolve`: multiple exact matches (candidates in `resourceIds`, labeled in `details.idRefs`); a cap-tripped bounded client scan (`resolution.scanOnMiss` only; never a silent `null`); a numeric-id miss |
@@ -340,21 +342,41 @@ transport `RequestOptions` flag) or raises `maxRetries`. An
 contract break is not transient.
 
 **Maintenance-window auto-retry (weekly window).** Autotask runs a weekly
-maintenance window (typically under 30 minutes) during which the edge answers
-an HTML page — the non-JSON 2xx above — before the application ever sees the
-request. When that page reads as a maintenance notice, the transport waits
-`maintenancePollMs` (default 30 s) and retries, for up to
-`maintenanceMaxWaitMs` (default 1 hour) from the first such response. This
-applies to **reads and writes**: the page is a pre-execution edge signal, which
-is the one case where a bounded auto-retry of a write is safe — the general
-rule is untouched (a 5xx / network / timeout error never auto-retries a write;
-§2.2). The wait does not consume `maxRetries`, each post-wait attempt gets a
-fresh `timeoutMs`, and a caller `AbortSignal` interrupts the wait. A page that
-does not look like a maintenance notice (for example a wrong `baseUrl` serving
-a web site) is surfaced at once. On exhaustion the error carries
-`details.maintenance = { waits, waitedMs, maxWaitMs, exhausted: true }` and a
-suggestedAction naming the window. Disable with `maintenanceMaxWaitMs: 0`
-(config or per call).
+maintenance window during which the edge answers an HTML page before the
+application ever sees the request. The transport recognises that page from the
+**first 256 bytes** of its body at any status (`2xx`, `4xx`, `5xx`) — issue
+#114: the edge picks the status line, and a 503/404 HTML page used to burn the
+retry budget or surface as `NOT_FOUND`. The gate is the body: a **JSON** body
+never enters (a JSON 503 is the application answering; it keeps the normal
+rules, and a write still makes one send). When the page reads as a maintenance
+notice:
+
+- a non-JSON **`2xx`** page is waited out and retried for **reads and writes**
+  (a 2xx HTML page is edge-served before execution — the 0.16.0 premise);
+- a non-JSON **`4xx`/`5xx`** page is waited out and retried only for calls that
+  are **safe to re-send** (`retriable5xx`: a `GET` or an explicitly
+  `idempotent`-flagged call). An UNFLAGGED mutation answered with such a page
+  makes **exactly one send** and surfaces the status's own error with
+  `details.maintenanceDetected = true` and a verify-before-reissuing action — a
+  proxy can serve that page AFTER forwarding the write, so the outcome is
+  unknown (the §2.2 write rule is intact).
+
+The wait polls `maintenancePollMs` (default 30 s) for up to
+`maintenanceMaxWaitMs` (default 1 hour) from the first such response. The
+observed ceiling is 4 h (`MAINTENANCE_WINDOW_MAX_MS`; 19 live windows:
+30–240 min, median ≈ 2 h) — an unattended worker should pass
+`maintenanceMaxWaitMs: MAINTENANCE_WINDOW_MAX_MS`. The wait does not consume
+`maxRetries`, each post-wait attempt gets a fresh `timeoutMs`, and a caller
+`AbortSignal` interrupts the wait. A non-JSON HTML-ish page that does not look
+like a maintenance notice (for example a wrong `baseUrl` serving a web site, or
+a stock proxy page) is surfaced at once with
+`details.maintenancePatternMiss = true` and the 256-byte snippet logged at
+`debug` (issue #114 — the next occurrence supplies the wording). When a wait
+ran, the surfaced error always carries
+`details.maintenance = { waits, waitedMs, maxWaitMs, exhausted }` (`exhausted`
+is true when the budget was spent; a wording change on a later page surfaces
+that page's own error with `exhausted: false`). Disable with
+`maintenanceMaxWaitMs: 0` (config or per call).
 Zone discovery rides the same transport, so a startup failure during
 maintenance is recognisable by the code. `details.bodySnippet` is the first
 256 BYTES of the raw body — TRUNCATION ONLY (the name-based redaction is a
@@ -386,7 +408,10 @@ write that answered nothing is now a typed failure (strict default: no
 
 **Deterministic validation 500 (#23).** A 500 whose `errors[]` entries match
 the documented heuristic phrases (`isDeterministicVendor500` — `exceeds
-maximum length` to start) is PERMANENT: the transport makes exactly ONE
+maximum length`, `Missing Required Field`, `Value does not exist for the
+required field`, and since issue #119 `Unable to find <field> in the <entity>
+Entity.` — the live field-existence signature of an unknown `includeFields`
+name) is PERMANENT: the transport makes exactly ONE
 upstream call (it breaks out before the retry decision — the parsed body is
 already in hand at the retry site), and the mapped error keeps the
 `ServerError` class + `SERVER_ERROR` code + status 500 but carries
@@ -486,7 +511,7 @@ Host form: `https://<name>.autotask.net/atservicesrest` (lowercase
 | `pageSize` | 10 | 500 (vendor max) | page size for query walks; `maxRecords` on the wire |
 | `timeoutMs` | 30 000 | — | whole-call budget, incl. retries |
 | `maxRetries` | 3 | — | the client's retry budget, overridable per call (`InvokeOptions.maxRetries` / `MutationOpts.maxRetries`; `0` = exactly one send per request the call performs). The budget caps three legs (issues #105/#109): the 429 leg (retried on GET/PUT/DELETE + flagged calls — unchanged) and the 5xx/network + non-JSON 2xx legs (GET + flagged only) |
-| `maintenanceMaxWaitMs` | 3 600 000 (1 h) | — | **maintenance-window auto-retry** (weekly Autotask window): when the edge answers a non-JSON HTML page that reads as a maintenance notice, the transport waits `maintenancePollMs` and retries for up to this long from the FIRST such page — for reads AND writes (the edge answered before the vendor application saw the request; the weekly window is typically under 30 min). Does not consume `maxRetries`; each post-wait attempt gets a fresh `timeoutMs`. `0` disables the wait. A page that does not look like maintenance (e.g. a wrong `baseUrl`) never enters the loop |
+| `maintenanceMaxWaitMs` | 3 600 000 (1 h) | — | **maintenance-window auto-retry** (weekly Autotask window): when the first 256 bytes of a non-JSON body read as a maintenance notice, the transport waits `maintenancePollMs` and retries for up to this long from the FIRST such page. A `2xx` page is waited out for reads AND writes (edge-served before execution); a `4xx`/`5xx` page only for calls safe to re-send (GET / explicitly idempotent-flagged) — an unflagged mutation makes ONE send and carries `details.maintenanceDetected` (a proxy can serve the page after forwarding). JSON bodies never enter. Does not consume `maxRetries`; each post-wait attempt gets a fresh `timeoutMs`. `0` disables the wait. A non-matching HTML-ish page stamps `details.maintenancePatternMiss`. Observed ceiling 4 h: `MAINTENANCE_WINDOW_MAX_MS` (19 windows: 30–240 min, median ≈ 2 h) |
 | `maintenancePollMs` | 30 000 | — | poll interval while waiting out a maintenance page |
 | `maxConcurrent` | 10 | 10 (vendor) | concurrency guard |
 | `profile` | `library` | — | `library` = today's defaults (changes nothing); `agent` = the conservative `AGENT_PROFILE` limits for LLM-driven workloads (below). Resolution: explicit config > profile > library default |
@@ -675,9 +700,16 @@ carry paging parameters.
 
 - **Page walk — cursor-follow on `pageDetails.nextPageUrl`** (node-style): page 1
   POSTs the `QueryModel` body (`MaxRecords = pageSize`) to `/V1.0/<E>/query`;
-  later pages POST the preserved filter to the ABSOLUTE `nextPageUrl`, rebased
-  to the client base URL (same-origin cursors verbatim; cross-origin re-based —
-  the node's custom-zone behaviour).
+  later pages POST the SAME body (`buildQueryBody` — `MaxRecords`,
+  `IncludeFields` with the `id` append, the preserved `filter`) to the ABSOLUTE
+  `nextPageUrl`, rebased to the client base URL (same-origin cursors verbatim;
+  cross-origin re-based — the node's custom-zone behaviour). Issue #118: before
+  the fix later pages POSTed `{ filter }` alone and returned the FULL vendor
+  model (live-reproduced 2026-10-19: page 1 of a three-field subset walk —
+  `id`, `title`, `status` — carried 4 keys, page 2 carried 76). The vendor HONOURS `IncludeFields` on a continuation and
+  IGNORES `MaxRecords` (it serves its own 500-row page; the walk slices to its
+  limit, so the RESULT is exact and the wire page size on page 2+ is the
+  vendor's).
 - `Page<T>`: `{ items, page (1-based), pageSize, requestCount (the vendor
   value verbatim — the MaxRecords echo, not a total), hasMore (nextPageUrl
   !== null), totalPages }`. `totalPages` is the pages KNOWN so far —
@@ -926,6 +958,12 @@ the mode pinned (§7.4). The governor rules (pinned):
   the SDK; the caller passes `limit` as the TOTAL cap (default 500, max
   2500) and never owns a stream. `queryAll` keeps its raw behavior (the
   unbounded walk; the catalog text steers the caller away for normal work);
+- a query's `includeFields` NAMES are validated **pre-request** (issue
+  #119b): the live field metadata is the authority (the vendored spec when
+  that read faults), every unknown name is named in one typed
+  `CONFIG_ERROR` before the query POST, and `fieldCheck: false` in the query
+  bag disables the name check (the `string[]` / non-empty shape check always
+  runs);
 - `dryRun` must be a real boolean: anything else (`'true'`, `0`, `null`) is
   refused before any request — only an explicit `false` applies a write;
 - `<resource>.createIfNotExists` takes its match fields as an optional
@@ -1426,6 +1464,16 @@ drift). Records exist only for plan rows that are implemented/tested; the
 plan (`capabilities.plan.json`) is the single source of truth and the
 registry is its compiled form.
 
+**Consumer-defaulted arguments (issue #115).** A manifest CONSUMER may fill an
+argument this registry marks required when the caller omits it — the manifest
+describes the SDK operation, not the consumer's tool contract. The one
+instance today is `contracts.profitability`: the SDK requires
+`dateFrom`/`dateTo`, and iit-mcp-autotask defaults both to the last full
+calendar month (UTC) when the caller omits them. The served
+`metadata.args`/`metadata.usage` and the record's
+`inputSchema.opts.description` state the caveat; a consumer that trusts the
+raw manifest should apply the same contract.
+
 ### 9.1 Generated artifact #5: `src/relationships.ts` (the relationship map + zone facts)
 
 The regen chain's 5th generated module (plan S12 §2.4: the 4 generated
@@ -1648,7 +1696,8 @@ retrying with the same body fails identically; fix the field instead
 httpStatus >= 500). **Resolution (issue #23):** the *deterministic*
 validation 500 is no longer labelled retryable — a 500 whose `errors[]` text
 matches the documented heuristic phrases (`isDeterministicVendor500`:
-`exceeds maximum length`, `Missing Required Field`, `Value does not exist for the required field`) makes exactly ONE upstream call (the
+`exceeds maximum length`, `Missing Required Field`, `Value does not exist for the required field`,
+`Unable to find <field> in the <entity> Entity.` — issue #119, live-verified 2026-10-19) makes exactly ONE upstream call (the
 transport skips the retry), keeps the `ServerError` class + `SERVER_ERROR`
 code + status 500, but carries `retryable: false`, `details.deterministic:
 true`, and a `suggestedAction` pointing at the field catalog
@@ -2027,7 +2076,11 @@ the TTL is the other expiry path.
 
 **The on-demand op:** `operations.fieldCatalog(client, opts?)`
 (`{ resources?, include?, fields?, labels?, fresh? }` — `fields` filters the
-fields-kind rows to the named fields and reports `unmatchedFields`; `labels`
+fields-kind rows to the named fields and reports `unmatchedFields`; a
+projected row is marked `projected: true` (issue #121 — the four derived
+lists then describe the PROJECTED set only, so a consumer can never read a
+projected `required`/`queryable` list as the resource's full picture; a full
+row omits the key); `labels`
 adds the picklist labels; default: the five workflow
 resources, `include: ['fields']`; the closed opts bag is documented in
 the registry record). One bounded entityInformation GET per resource ×
@@ -2630,6 +2683,19 @@ query-verb-ONLY and zero-wire or vendor-column-selection-only:
   billing item to its company / ticket / project / time entry / contract
   service / contract / billing code / expense item, plus the date and the
   amount fields — the "common narrow read" the issue's example targets.
+- **`fieldCheck: false` — the includeFields NAME check's opt-out (issue
+  #119b).** By default the bounded `query` op validates every `includeFields`
+  name BEFORE the query POST: the authority is the entity's LIVE field
+  metadata (`getFieldInfo()` through the cache-aware channel of section
+  11.14 — warm = zero wire), degrading to the vendored spec
+  (`src/field-sets.ts`) when the metadata read faults; with neither an
+  authority the check is skipped. The live set wins when present — a
+  live-only field (`time_entries.postedDate`) is accepted and a
+  vendored-only field the tenant no longer has is refused. Every unknown
+  name is named in ONE typed `CONFIG_ERROR` (zero query wire), with
+  `fieldCheck: false` as the escape hatch and `operations.fieldCatalog` as
+  the discovery pointer. The shape check (`string[]`, non-empty entries)
+  always runs.
 - **The live check (the AC test for the presets).** Each preset's fields
   are asserted to EXIST on the live resource against the LIVE field
   catalogue (`operations.fieldCatalog` — the entityInformation/fields

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-autotask",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Fully-typed TypeScript SDK for the Autotask (Datto) PSA REST API. Zero runtime dependencies. Built for building MCP servers and integrations.",
   "type": "module",
   "sideEffects": false,
@@ -87,6 +87,7 @@
     "bin",
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "ARCHITECTURE.md",
     "capabilities.json",
@@ -112,7 +113,7 @@
     "coverage": "vitest run --coverage",
     "lint": "eslint src test",
     "lint:fix": "eslint src test --fix",
-    "verify": "npm run typecheck && npm run lint && npm run generate:check && npm run build && node scripts/check-capabilities.mjs --ship && npm run mcp:project:check && npm run n8n:project:check && npm run catalog:check && npm run mcp:check-surface && npm run public-surface && npm run verify:pack && npm test",
+    "verify": "npm run lockfile:check && npm run typecheck && npm run lint && npm run generate:check && npm run build && node scripts/check-capabilities.mjs --ship && npm run mcp:project:check && npm run n8n:project:check && npm run catalog:check && npm run mcp:check-surface && npm run public-surface && npm run verify:pack && npm test",
     "plan:derive": "node scripts/derive-plan.mjs",
     "generate:check": "node scripts/generate-batch.mjs --check && node scripts/generate-batch.mjs --check --group B",
     "capabilities:build": "node scripts/generate-capabilities.mjs",
@@ -131,6 +132,7 @@
     "n8n:project:check": "node scripts/project-n8n-mcp.mjs --check",
     "verify:pack": "node scripts/verify-pack.mjs",
     "release:check": "node scripts/check-release-plan-hash.mjs",
+    "lockfile:check": "node scripts/check-lockfile-sync.mjs",
     "capabilities:check:ship": "node scripts/check-capabilities.mjs --ship",
     "prepack": "npm run build",
     "prepublishOnly": "npm run release:check && npm run clean && npm run verify && npm run capabilities:check:ship",