feat(project-engine-client): URL-safe tag ids + id-based prompt-write mock routes

[rainer-friederich]

1. Abstract

Fixes the Project Engine mock's tag-id generation to be URL-safe (issue #1760) and adds the two id-based prompt-write mock routes (POST /aio/prompts, PUT /aio/prompts/tags) needed by the cross-repo sub-categories ID-based alignment program.

2. Reasoning

The mock derived a tag's id as tag-${encodeURIComponent(name)}, so a name like category:Running Shoes produced tag-category%3ARunning%20Shoes. That leaks into a URL path segment (PATCH /aio/tags/{tag_id}) or a query value (GET /aio/tags?parent_id=<id>), breaking round-trips for any consumer that builds real HTTP requests against the mock. Separately, two upstream endpoints the alignment program depends on — id-based prompt create and batch tag-reference update — had no mock coverage at all, and a set of production probes run against adobe-hackathon.semrush.com on 2026-07-02 (see the implementation plan linked below) surfaced live behavior the mock needs to mirror: POST /aio/tags is NOT idempotent on a same-name/same-parent duplicate (it 500s), and the id-based create/update endpoints have specific response shapes and merge/replace semantics that differ from what the vendored swagger documents.

3. High-level overview of the changes

• Tag id (issue project-engine-client mock: AIO tag ids embed %3A (name-derived) and don't round-trip through URLs — blocks nested children-drill / PATCH-by-id IT #1760): replaced the URL-unsafe tag-<url-encoded-name> id with an opaque tag-<first-16-hex-of-sha256(name)> id. Still a pure function of name (needed so a standalone tag and the same tag embedded on a prompt correlate, and so ops.tags.upsertMany stays idempotent-by-name), but never needs encoding as a path segment or query value.
• New routes: POST /aio/prompts (id-based prompt create, {items, tag_ids} → a paginated list-wrapper response, matching live rather than the vendored swagger's bare-object shape) and PUT /aio/prompts/tags (batch tag-reference update, replace: false merges references onto a prompt, replace: true replaces the full set).
• POST /aio/tags now 500s on a same-name/same-parent duplicate create, matching live — previously the mock silently reused the existing tag. ops.tags.upsertMany now does an atomic resolve-before-create check itself (nothing is written if any tag in a batch collides), which is the same discipline every real consumer of this endpoint now has to follow. A same-name tag under a different parent still resolves to the same id and is reused rather than treated as a collision — the id is derived from the name alone (not parent-aware), which is a documented, deliberate limitation of this mock rather than of the live API.

4. Required information

• Spec: https://github.com/adobe/serenity-docs/pull/24
• Implementation plan: https://github.com/adobe/serenity-docs/blob/docs/subcategories-id-alignment/docs/discovery/subcategories-implementation-plan.md
• Other: project-engine-client mock: AIO tag ids embed %3A (name-derived) and don't round-trip through URLs — blocks nested children-drill / PATCH-by-id IT #1760

5. Affected / used mysticat-workspace projects

• spacecat-api-service — consumed: its serenity proxy IT/e2e suite runs against this package's GHCR mock image; a future follow-up PR there is expected to exercise the two new id-based routes once this image is republished.
• mysticat-data-service — contract: the serenity migration CLI now writes prompts via the id-based endpoints this mock models; it currently tests against an in-process fake, not this mock, so it is unaffected by this PR directly but shares the same upstream contract.

6. Additional information outside the code

The mock's new/changed behavior was checked against a set of live production probes run on 2026-07-02 against adobe-hackathon.semrush.com (documented in the serenity-docs implementation plan linked above): the POST /aio/prompts response shape, its draft-only visibility until publish, atomic failure on an unknown tag id, PUT /aio/prompts/tags's merge-vs-replace semantics and its silent-204-on-unknown-prompt-id behavior, and the POST /aio/tags same-name-collision 500. Each of those live-verified behaviors is what this PR's mock changes mirror.

7. Test plan

(a) Ran this package's unit suite and its e2e suite (which boots the mock and exercises every route over real HTTP, including the new/changed ones and the auth/quota surfaces) locally; also ran the package's lint and test:types (tsc @ts-check) gates.
(b) No environment-specific verification applies — this package isn't deployed as a service; its only downstream effect is the GHCR mock image consumed by other repos' IT suites, which needs a version bump + republish (this repo's normal release flow) before spacecat-api-service or any other consumer picks up these changes.

8. Deployment & merge order

• Related: feat(serenity): consume nested AIO tags (parentId create, tree read, PATCH re-parent) spacecat-api-service#2737 — already merged; used sinon-based unit test fakes rather than this mock, so it did not depend on this PR to land first.
• Related: https://github.com/adobe/mysticat-data-service/pull/737 — already merged; used an in-process Python fake rather than this mock, so it did not depend on this PR to land first.
• No merge-order dependency exists on either. A future api-service follow-up PR that exercises the new id-based routes via IT tests against the real mock image WILL need this PR merged and released (new package version + GHCR image) first.

🤖 Generated with Claude Code

[MysticatBot]

Hey @rainer-friederich,

Verdict: Approve - well-scoped mock fidelity improvements with thorough live-verification discipline and strong test coverage.
Complexity: HIGH - large diff; API surface signal.
Changes: Replaces URL-unsafe tag-id encoding with an opaque SHA256-derived token, adds two id-based prompt-write mock routes (POST /aio/prompts, PUT /aio/prompts/tags), and makes POST /aio/tags collision-aware to match live behavior (11 files).

Non-blocking (5): minor issues and suggestions

• nit: docs/mock-usage.md - the createProjectTags row documents same-name/same-parent collision but omits that intra-batch duplicates (same name twice in one request) also trigger the 500. Consider adding "or appears twice in the same batch".
• suggestion: mock/counterfact/routes/.../prompts/tags.js:34 - the unknown-tag-reference fallback ({ id: tid, name: tid }) is untested. A unit test exercising this path would prevent a silent regression if the fallback is accidentally removed.
• nit: mock/counterfact/routes/.../prompts/tags.js:51 - the return { status: 204 } raw bypass diverges from sibling DELETE handlers that use $.response[204]. Consistency across the route directory reduces cognitive load.
• suggestion: Consider extracting the tag-resolution logic (build Map from ops.tags.list, validate ids, embed { id, name } pairs) into a shared helper on context - it is now duplicated across prompts.js, prompts/tags.js, and prompts/tagged.js.
• suggestion: Communicate the POST /aio/tags behavior change (was idempotent, now 500s on collision) to downstream consumers via a changelog entry or release note. Any test setup that POSTs the same tag names twice will break on the new mock image.

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 2m 7s | Cost: $5.53 | Commit: aba6c337967492f8ab18853dd266640499500af6
If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[github-actions]

This PR will trigger a minor release when merged.

[rainer-friederich]

Addressed MysticatBot's non-blocking review (4616818458) in 90a1c5af.

• nit: mock-usage.md didn't mention intra-batch duplicates also 500 — done, added "or appears twice in the same batch".
• suggestion: unresolvable-reference fallback in prompts/tags.js was untested — done, added an e2e test covering it (a reference id with no matching tag still embeds and correlates via by_tags).
• suggestion: the { status: 204 } bypass in prompts/tags.js "diverges from sibling DELETE handlers using $.response[204]" — declined, this is inaccurate. Every sibling DELETE handler in this routes directory (prompts.js, tags.js) also uses the raw { status: 204 } bypass; $.response[204] doesn't appear anywhere in mock/counterfact/routes/. My new file matches the established convention, not diverges from it.
• suggestion: extract the tag-resolution logic into a shared context helper — declined. The actual overlap is a one-line Map build (prompts.js and prompts/tags.js only — prompts/tagged.js resolves by NAME via context.tagId() directly, it doesn't build this map at all, so the "3 files" framing overstates the duplication). The two callers' resolution semantics also diverge meaningfully (atomic-500-on-unknown vs soft {id, name:id} fallback), so a shared helper would need mode parameters to cover both — more complexity than the ~1 duplicated line it would remove.
• suggestion: communicate the POST /aio/tags behavior change via a changelog/release note — declined as redundant with this repo's existing convention: semantic-release auto-generates CHANGELOG.md from conventional commit messages, and the original commit's body (aba6c337) already documents this exact behavior change in detail, which is what feeds that pipeline.

All fixes verified: lint, test:types, and both suites (unit 212 tests / e2e 62 tests, including the new one) green with 100% coverage.

[MysticatBot]

Hey @rainer-friederich,

Verdict: Approve - prior non-blocking suggestions addressed or validly declined; no new concerns from the follow-up commits.
Complexity: HIGH - large diff; API surface signal.
Changes: Follow-up commits add the intra-batch duplicate mention to mock-usage docs and a new e2e test covering unresolvable tag-reference fallback (11 files).

Previously flagged, now resolved

• Intra-batch duplicate mention added to docs/mock-usage.md (nit addressed in 90a1c5a)
• Unresolvable reference fallback now has e2e coverage via the new "PUT embeds an unresolvable reference id" test (suggestion addressed in 90a1c5a)
• { status: 204 } consistency concern withdrawn - verified that all sibling DELETE handlers in the routes directory use the same raw bypass pattern; the prior suggestion was based on an inaccurate premise
• Tag-resolution helper extraction withdrawn - the overlap is narrower than stated (2 files, 1 shared line, diverging semantics) and a helper with mode params would add more complexity than it removes
• Changelog/release-note suggestion withdrawn - semantic-release auto-generates CHANGELOG from conventional commit messages, which already document the behavior change in detail

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 7m 54s | Cost: $1.79 | Commit: ecadc46f6f685513a86161f361bb592db566f14b
If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[solaris007]

🎉 This PR is included in version @adobe/spacecat-shared-project-engine-client-v1.7.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀