💡 [REQUEST] - Expliciter l'intention de mise à jour des credentials de dépôt (API v2)

[KepoParis]

Description

Dans l'API v2 des dépôts, la mise à jour des identifiants de miroir Vault est devinée à
partir du corps de la requête au lieu d'être exprimée par le client.

parseRepositoryCredentialUpdate (apps/server-nestjs/src/modules/repository/repository.utils.ts)
infère l'intention (set / clear / keep) de la présence ou de l'absence de champs :

if (updateRepositoryInfos.isPrivate === false) return { kind: 'clear' }
if (updateRepositoryInfos.externalToken) return { kind: 'set', externalToken: ... }
return { kind: 'keep' }

C'est la reprise du comportement legacy (qui signalait « inchangé » avec un jeton factice
fakeToken), conservée telle quelle pour ne pas élargir la migration. Mais on ne devrait
jamais deviner quoi que ce soit à partir des données d'entrée : soit le client sait ce
qu'il veut, soit il doit y réfléchir avant d'envoyer sa requête. Le kind devrait être
dans la requête.

Même racine pour buildRepositoryUpdateData, dans le même fichier : les deux if
(isPrivate !== undefined, isPrivate !== false && externalUserName !== undefined)
sont fragiles parce que isPrivate y est un tri-état true | false | undefined là où
ce devrait être un booléen. La sémantique de « rendre public » (qui conserve
l'externalUserName stocké mais supprime le secret Vault) est aujourd'hui implicite et
répartie entre deux fonctions.

PRs liées

#2416 — introduit parseRepositoryCredentialUpdate et le type
RepositoryMirrorCredentialUpdate avec le comportement legacy conservé.

Issues liées

Aucune.

Exemples simples

Aujourd'hui, trois requêtes différentes produisent trois effets Vault différents sans
que le client ait exprimé la moindre intention :

// « je change le jeton »           → set (deviné par la présence du champ)
{ "externalToken": "glpat-xxx" }

// « je passe le dépôt en public »  → clear (deviné par isPrivate: false)
{ "isPrivate": false }

// « je change juste la branche »   → keep (deviné par l'absence de jeton)
{ "deployRevision": "main" }

Cible : l'intention est portée explicitement par le corps, par exemple

{ "deployRevision": "main", "credentials": { "kind": "keep" } }
{ "isPrivate": false,       "credentials": { "kind": "clear" } }
{ "isPrivate": true,        "credentials": { "kind": "set", "externalUserName": "bot", "externalToken": "glpat-xxx" } }

Spécifications techniques

Zone concernée : apps/server-nestjs/src/modules/repository/ (+ packages/shared/src/schemas/v2/repository.ts).

1. Porter le kind dans le contrat. Faire de UpdateRepositorySchema une union
   discriminée sur l'intention de credentials, comme CreateRepositorySchema l'est déjà
   sur isPrivate. parseRepositoryCredentialUpdate disparaît alors : le boundary zod
   produit directement le RepositoryMirrorCredentialUpdate, et le service se contente
   d'exécuter (« parse, don't validate »).
2. Rendre les combinaisons impossibles inexprimables. isPrivate: false avec
   kind: 'set' ne doit pas être représentable dans le type, plutôt que d'être arbitré à
   l'exécution par un ordre de if.
3. Sortir isPrivate du tri-état dans buildRepositoryUpdateData : décider
   explicitement de la sémantique du passage public → l'externalUserName stocké
   est-il conservé (legacy) ou effacé ? Cf. la question ouverte ci-dessous.
4. Impact client : la webapp (apps/client) et les consommateurs de l'API v2 devront
   envoyer l'intention. Prévoir la période de transition (l'API v1 legacy reste sur
   apps/server et n'est pas concernée).

Questions ouvertes (à trancher avant implémentation)

• Rendre un dépôt public doit-il effacer l'externalUserName en base, ou conserver le
  comportement legacy qui le laisse intact ?
• Le kind est-il un champ à part (credentials: { kind: ... }) ou porté par la même
  union que isPrivate ?

Définition du fini

• La sémantique du passage public est tranchée et documentée
• Le kind est porté explicitement par la requête, plus aucune inférence côté serveur
• isPrivate n'est plus un tri-état dans la construction de la mise à jour
• Les clients de l'API v2 (dont la webapp) sont adaptés
• Les tests liés à ce refactor ont été ajoutés