feat(user-manager-client): stateful Counterfact mock with seed/reset + E2E (LLMO-5616)

[byteclimber]

Stacked on #1680 (foundation). Implements LLMO-5616 — a stateful mock of the Semrush User Manager API for E2E tests + local dev.

What works (17 tests, 100% coverage on src/)

• Stateful core chain (POST reflected in later GET): workspaces create-child/get/update/delete/list, members add/list/update/delete, profile get/update, resources (+ deprecated /limits alias), service-units balance.
• Seed + reset: starts in a known fixture state; POST /__reset returns to it; E2E suite resets in beforeEach.
• Run: npm run mock → :4010 under /enterprise/users/api, permissive auth (--no-validate-request).
• Generated from the spec, no stub hand-editing: regeneration preserves the hand-edited handlers.

Reviewer focus — the ~13 hand-authored files (rest of .counterfact/ is generated, marked linguist-generated)

• .counterfact/routes/_.context.ts — the store (state + seed/reset)
• .counterfact/routes/__reset.ts
• .counterfact/routes/v1/profile.ts, v1/workspaces.ts, v1/workspaces/{id}.ts, v1/workspaces/{id}/child.ts, v1/workspaces/{id}/members.ts, v1/workspaces/{id}/resources.ts, v1/workspaces/resources.ts, v1/workspaces/{id}/limits.ts, v1/workspaces/limits.ts, v1/workspaces/{id}/service-units/balance.ts, v2/workspaces/{id}.ts
• src/config.js, test/mock.test.js, README "Mock" section; package.json/.gitignore/clean/root eslint ignore.

Key architecture decision (validated, differs from the original plan)

Counterfact only compiles its own routes/ tree, so mock state lives on the Context class ($.context), not src/ — an imported external store 500s. The logic is therefore validated behaviorally by the E2E suite (the 100% gate covers src/ only). The .counterfact/ tree is committed except .cache/.

Deferred (LLMO-5615)

spacecat-api-service calls no User Manager endpoints today, so wiring it to the mock is deferred to when the client lands. The base-URL env var SEMRUSH_USERS_BASE_URL is recorded in src/config.js; re-open trigger documented in the README (incl. the http-localhost-vs-https caveat).

Known caveat

Counterfact warns of ambiguous sibling wildcards ({id} vs {workspace_id}) on some non-core paths; the core chain uses {id} and routes correctly.

🤖 Generated with Claude Code

[github-actions]

This PR will trigger a minor release when merged.

[rainer-friederich]

Heads-up now that this mock stacks on the User Manager foundation branch (feat/user-manager-client), which now carries a generation-time spec-correction overlay (spec/overlays/corrections.yaml) — the User Manager analog of the Project Engine overlay. Same class of coupling I flagged on the Project Engine mock:

#1665 (comment)

What this PR already gets right (the Project Engine mock had to be fixed for both): the mock script already passes --prefix /enterprise/users/api — so the route-prefix problem doesn't bite here (Counterfact honors a Swagger-2.0 basePath but ignores an OAS3 servers[0].url; the explicit --prefix covers it under either spec) — and --no-validate-request, which makes CR1 (the Auth-Data-Jwt removal) a no-op for the mock. Nothing needed there.

The one coupling left — CR2 (workspace-status shape). After rebasing onto the updated base to pick up the overlay (spec/overlays/corrections.yaml, scripts/apply-overlay.mjs, the spec:overlay step in npm run generate, and the js-yaml devDep — this branch predates all of them), the mock's GET /v1/workspaces/{id}/status returns the wrong shape. The committed handler is:

export const GET: workspacesStatusGet = async ($) => {
  return $.response[200].random();
};

$.response[200].random() is Counterfact's spec-derived 200. Because the mock is fed the pristine spec/usermanager_swagger.yaml, that 200 is typed as an array of WorkspaceCheckResponse — so the mock returns an array, while the corrected client and the live API return a single object { status: "created" } (CR2; the transport polls status.status === 'created'). The mock and the real contract disagree, and an E2E that polls workspace status will see the mismatch.

Two ways to fix — pick one:

• Surgical (recommended for a hand-authored stateful mock): keep feeding the swagger, but have status.ts return a single object explicitly (e.g. return { status: "created" };) rather than $.response[200].random(). CR2 is the only response-shape correction, and this route is already a committed handler, so this fully covers it without re-scaffolding.
• Spec-consistent: feed Counterfact the overlaid build/openapi3.json (run npm run generate, which now includes spec:overlay, before boot — build/ is gitignored) and regenerate the Counterfact types so .random() yields the corrected object surface. Keep --prefix /enterprise/users/api (still required — Counterfact ignores OAS3 servers). This is the broader, future-proof option but regenerates the whole scaffold, so mind the committed stateful handlers.

Context — the overlay + corrections that introduce CR2:

#1680