Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Make create-operation semantics consistent across all project-scoped catalog entities (create-or-fail vs upsert)

Aperta
  • Qualcosa non va?
#1,266 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
42/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
typescript
Ambito
api, backend-api-design, full-stack

Direzione di ricerca

Start by re-confirming the listed create behaviors for each catalog entity across the API, portal, and CLI. Decide whether each entity should use create-or-fail or an explicitly documented upsert path, then align the affected clients and add duplicate-create tests and documentation for every entity. Done means the convention, exceptions, API responses, portal behavior, and CLI handling are consistent and covered.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

author: cedricvidal design enhancement

Original author: @cedricvidal

Summary

Create (POST) operations across our project-scoped catalog entities are inconsistent: some behave as create-or-update-if-exists (silent upsert / overwrite), others as create-or-fail-if-exists (409 on duplicate). We should pick one convention and apply it uniformly across the API, portal, and CLI.

This was surfaced while fixing the MCP "Add Server" duplicate-slug bug (PR #1241), where the create flow was silently overwriting an existing server. MCP was moved to create-or-fail (409) there; this issue tracks reconciling the rest.

Current behavior (audit)

Entity API create behavior Portal client-side guard?
mcp-servers CREATE-OR-FAIL (409) — fixed in #1241 Yes (inline + toast)
criteria CREATE-OR-FAIL Yes
prompt-features CREATE-OR-FAIL (409) No — API rejects but portal doesn't pre-check
report-templates CREATE-OR-FAIL (409) Unverified
codebases CREATE-OR-FAIL (unique-index E11000) n/a
skills UPSERT (findOne → updateOne/insertOne, 200/201) n/a
extensions UPSERT (same pattern as skills) n/a
agents UPSERT (explicit "upsert" semantics, 200/201) —
agent-versions UPSERT (by agentVersion) —
task-prompts findOrCreate (always 201) —

File:line citations were gathered during the audit and can be reattached in the implementing PR. Treat the table as the starting inventory; each row should be re-confirmed before changing.

Problems

  1. Inconsistent, surprising semantics — the same "create" verb silently overwrites for some entities and rejects for others. A user re-adding an existing skill silently mutates it; re-adding an MCP server now errors.
  2. Data-loss risk — silent upsert on create can overwrite a record a user didn't intend to touch (the exact MCP bug).
  3. API/portal mismatch — prompt-features returns 409 from the API but the portal offers no client-side duplicate guard, so the user only discovers the conflict after submitting.

Proposed direction (to be decided)

Adopt create-or-fail (409) as the standard for user-facing catalog creates, with updates done explicitly via PUT. Rationale: least-surprise, no accidental overwrite, matches the MCP + criteria pattern.

  • Some entities may have intentional idempotent re-import semantics (skills/extensions re-import, agent-version registration from workers). Those need an explicit decision: keep upsert (and document it) OR split into distinct create vs. update paths. Do not blanket-change without confirming each intent.
  • Wherever the API is create-or-fail, add a matching portal client-side duplicate guard (inline error + disabled submit) for parity, and ensure the CLI surfaces the 409 cleanly.

Scope

  • Out of scope for PR #1241 (per-project data organization). This is a follow-up.
  • Deliverables: decision on the standard, per-entity reconciliation (API + portal + CLI), tests, and docs.

Acceptance criteria

  • A documented, agreed convention for create-vs-update across catalog entities.
  • Each entity's POST conforms (or its deviation is explicitly justified and documented).
  • Portal and CLI behavior matches the API for every entity (no silent-overwrite where the API 409s; no 409-only-after-submit where a pre-check is feasible).
  • Tests cover the duplicate-create path per entity.
Lingua principale
TypeScript
Stelle
7
Fork
13
Merge medio
3g 5h
PR unite (30g)
26

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di microsoft/scope

Tutte le issue di microsoft/scope

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.