From 37aeb5dd6f53eb5e7f2794d1059e62c690396c90 Mon Sep 17 00:00:00 2001
From: Kevin Powell Noumbissie <10553243+KepoParis@users.noreply.github.com>
Date: Mon, 27 Jul 2026 18:05:28 +0200
Subject: [PATCH] feat(client): add deployment value sources editor

---
 .../client/src/components/DeploymentModal.vue |  70 +++++---
 .../src/components/DeploymentRepoOption.vue   |  36 ++--
 .../src/components/DeploymentRepoSelect.vue   |  24 ++-
 .../DeploymentValueSourceOption.vue           | 167 ++++++++++++++++++
 .../src/components/DeploymentValueSources.vue | 104 +++++++++++
 .../client/src/utils/deployment-draft.spec.ts | 132 ++++++++++++++
 apps/client/src/utils/deployment-draft.ts     |  62 +++++++
 apps/client/src/utils/func.spec.ts            |  23 +++
 apps/client/src/utils/func.ts                 |  21 ++-
 9 files changed, 574 insertions(+), 65 deletions(-)
 create mode 100644 apps/client/src/components/DeploymentValueSourceOption.vue
 create mode 100644 apps/client/src/components/DeploymentValueSources.vue
 create mode 100644 apps/client/src/utils/deployment-draft.spec.ts
 create mode 100644 apps/client/src/utils/deployment-draft.ts

diff --git a/apps/client/src/components/DeploymentModal.vue b/apps/client/src/components/DeploymentModal.vue
index 2323b7cea9..4f974e9a12 100644
--- a/apps/client/src/components/DeploymentModal.vue
+++ b/apps/client/src/components/DeploymentModal.vue
@@ -1,19 +1,28 @@
 <script lang="ts" setup>
-import type { Cluster, Deployment, Environment, Stage, UpdateDeployment, Zone } from '@cpn-console/shared'
+import type {
+  Cluster,
+  Deployment,
+  Environment,
+  Stage,
+  UpdateDeployment,
+  UpdateDeploymentSource,
+  Zone,
+} from '@cpn-console/shared'
 import type { DsfrRadioButtonProps } from '@gouvminint/vue-dsfr'
 import type { Project } from '@/utils/project-utils.js'
-import { CreateDeploymentSchema, DeploymentSchema, longestDeploymentName } from '@cpn-console/shared'
-import { useSnackbarStore } from '@/stores/snackbar.js'
-import { scrollToFirstError } from '@/utils/func.js'
+import { CreateDeploymentSchema, DeploymentSchema, longestDeploymentName, UpdateDeploymentSchema } from '@cpn-console/shared'
+import { useSnackbarStore } from '@/stores/snackbar'
+import { toDeploymentDraft } from '@/utils/deployment-draft'
+import { scrollToFirstError } from '@/utils/func'
 
-const props = withDefaults(defineProps<{
+const props = defineProps<{
   opened: boolean
   environments: (Environment & { cluster?: Cluster, zone?: Zone, stage?: Stage })[]
   repoOptions: { text: string, value: string }[]
   deployment?: Deployment
   project: Project
-  disabled?: boolean
-}>(), { opened: false, disabled: false })
+  disabled: boolean
+}>()
 
 const emit = defineEmits<{ close: [] }>()
 
@@ -31,16 +40,16 @@ const options: ComputedRef<Omit<DsfrRadioButtonProps, 'modelValue'>[]> = compute
 )
 
 const deployment = ref<Partial<UpdateDeployment & { id: string }>>(
-  props.deployment ? { ...props.deployment } : { projectId: props.project.id, autosync: true },
+  props.deployment ? toDeploymentDraft(props.deployment) : { projectId: props.project.id, autosync: true },
 )
 
 watch(() => props.deployment, (newValue) => {
-  deployment.value = newValue ? { ...newValue } : { projectId: props.project.id, autosync: true }
+  deployment.value = newValue ? toDeploymentDraft(newValue) : { projectId: props.project.id, autosync: true }
 }, { deep: true })
 
 const deploymentSourcesModel = computed({
   get: () => deployment.value?.deploymentSources ?? [],
-  set: (value: UpdateDeployment['deploymentSources']) =>
+  set: (value: UpdateDeploymentSource[]) =>
     deployment.value = { ...deployment.value, deploymentSources: value },
 })
 
@@ -67,31 +76,29 @@ const environmentErrorMessage = computed(() => {
 function upsertDeployment() {
   if (isLoading.value) return
 
-  const body = CreateDeploymentSchema.safeParse(deployment.value)
+  const id = deployment.value.id
+  const body = id
+    ? UpdateDeploymentSchema.safeParse(deployment.value)
+    : CreateDeploymentSchema.safeParse(deployment.value)
+
   if (!body.success) {
     isDirty.value = true
     scrollToFirstError(formContainer)
     return
   }
 
+  const request = id
+    ? props.project.Deployments.update(id, body.data)
+    : props.project.Deployments.create(body.data)
+
   isLoading.value = true
-  if (deployment.value.id) {
-    props.project.Deployments.update(deployment.value.id, body.data)
-      .then(() => {
-        closeModal()
-        snackbarStore.setMessage('Déploiement enregistré, opérations en cours en arrière-plan...')
-      })
-      .catch(error => snackbarStore.setMessage(error, 'error'))
-      .finally(() => isLoading.value = false)
-  } else {
-    props.project.Deployments.create(body.data)
-      .then(() => {
-        closeModal()
-        snackbarStore.setMessage('Déploiement enregistré, opérations en cours en arrière-plan...')
-      })
-      .catch(error => snackbarStore.setMessage(error, 'error'))
-      .finally(() => isLoading.value = false)
-  }
+  request
+    .then(() => {
+      closeModal()
+      snackbarStore.setMessage('Déploiement enregistré, opérations en cours en arrière-plan...')
+    })
+    .catch((error: string) => snackbarStore.setMessage(error, 'error'))
+    .finally(() => isLoading.value = false)
 }
 
 function deleteDeployment() {
@@ -158,7 +165,12 @@ function closeModal() {
       <h6 class="fr-mb-0">
         Dépôts à inclure
       </h6>
-      <DeploymentRepoSelect v-model="deploymentSourcesModel" :is-dirty :repo-options="repoOptions" :disabled="props.disabled" />
+      <DeploymentRepoSelect
+        v-model="deploymentSourcesModel"
+        :is-dirty
+        :repo-options="repoOptions"
+        :disabled="props.disabled"
+      />
     </div>
     <div class="w-full flex justify-end gap-4">
       <DsfrButton
diff --git a/apps/client/src/components/DeploymentRepoOption.vue b/apps/client/src/components/DeploymentRepoOption.vue
index 0aba4f3fc3..450406365a 100644
--- a/apps/client/src/components/DeploymentRepoOption.vue
+++ b/apps/client/src/components/DeploymentRepoOption.vue
@@ -1,32 +1,29 @@
 <script setup lang="ts">
-import type { UpdateDeployment } from '@cpn-console/shared'
+import type { UpdateDeploymentSource } from '@cpn-console/shared'
 import { DeploymentSourceSchema } from '@cpn-console/shared'
 
-withDefaults(defineProps<{
+type DeploymentSourceDraft = Partial<UpdateDeploymentSource>
+
+const props = withDefaults(defineProps<{
   cantDelete: boolean
   options: { text: string, value: string }[]
-  disabled?: boolean
-  isDirty?: boolean
+  disabled: boolean
+  isDirty: boolean
 }>(), {
   options: () => [],
-  cantDelete: false,
-  disabled: false,
-  isDirty: false,
 })
 defineEmits<{ delete: [] }>()
 
-const model = defineModel<Partial<UpdateDeployment['deploymentSources'][0]>>(
+const model = defineModel<DeploymentSourceDraft>(
   {
     default: {
-      id: undefined,
       type: 'git',
-      repositoryId: undefined,
-      targetRevision: undefined,
-      path: undefined,
-      helmValuesFiles: undefined,
+      valueSources: [],
     },
   },
 )
+
+const valueSourceRepoOptions = computed(() => props.options.filter(option => option.value !== model.value.repositoryId))
 </script>
 
 <template>
@@ -51,16 +48,11 @@ const model = defineModel<Partial<UpdateDeployment['deploymentSources'][0]>>(
       label-visible
       :disabled="$props.disabled"
     />
-    <DsfrInputGroup
-      v-model="model.helmValuesFiles"
-      class="mb-2"
-      is-textarea
-      label="Fichiers values (Helm)"
-      label-visible
-      hint="Un fichier par ligne, chemin relatif par rapport au répertoire à déployer. L'ordre des fichiers est déterminant pour la surcharge des valeurs communes. Champ optionnel."
-      placeholder="values/extra.yaml
-values-<env>/custom.yaml"
+    <DeploymentValueSources
+      v-model="model.valueSources"
+      :repo-options="valueSourceRepoOptions"
       :disabled="$props.disabled"
+      :is-dirty="$props.isDirty"
     />
   </div>
 </template>
diff --git a/apps/client/src/components/DeploymentRepoSelect.vue b/apps/client/src/components/DeploymentRepoSelect.vue
index 9af01fb8c6..3cf8c79173 100644
--- a/apps/client/src/components/DeploymentRepoSelect.vue
+++ b/apps/client/src/components/DeploymentRepoSelect.vue
@@ -1,13 +1,15 @@
 <script lang="ts" setup>
-import type { UpdateDeployment } from '@cpn-console/shared'
+import type { UpdateDeploymentSource } from '@cpn-console/shared'
 
-withDefaults(defineProps<{
+type DeploymentSourceDraft = Partial<UpdateDeploymentSource>
+
+defineProps<{
   repoOptions: { text: string, value: string }[]
-  disabled?: boolean
-  isDirty?: boolean
-}>(), { disabled: false, isDirty: false })
+  disabled: boolean
+  isDirty: boolean
+}>()
 
-const depots = defineModel<Partial<UpdateDeployment['deploymentSources'][0]>[]>({ default: [] })
+const depots = defineModel<DeploymentSourceDraft[]>({ default: [] })
 
 if (depots.value.length === 0) {
   addDepot()
@@ -17,12 +19,8 @@ function addDepot() {
   depots.value = [
     ...depots.value,
     {
-      id: undefined,
       type: 'git',
-      repositoryId: undefined,
-      targetRevision: undefined,
-      path: undefined,
-      helmValuesFiles: undefined,
+      valueSources: [],
     },
   ]
 }
@@ -31,7 +29,7 @@ function removeDepot(index: number) {
   depots.value = depots.value.filter((_, i) => i !== index)
 }
 
-function updateDepot(index: number, value: Partial<UpdateDeployment['deploymentSources'][0]>) {
+function updateDepot(index: number, value: DeploymentSourceDraft) {
   depots.value[index] = value
 }
 </script>
@@ -48,7 +46,7 @@ function updateDepot(index: number, value: Partial<UpdateDeployment['deploymentS
         :cant-delete="index === 0"
         :disabled="$props.disabled"
         :is-dirty="$props.isDirty"
-        @update:model-value="(value :Partial<UpdateDeployment['deploymentSources'][0]>) => updateDepot(index, value)"
+        @update:model-value="(value: DeploymentSourceDraft) => updateDepot(index, value)"
         @delete="removeDepot(index)"
       />
     </div>
diff --git a/apps/client/src/components/DeploymentValueSourceOption.vue b/apps/client/src/components/DeploymentValueSourceOption.vue
new file mode 100644
index 0000000000..d98781bdae
--- /dev/null
+++ b/apps/client/src/components/DeploymentValueSourceOption.vue
@@ -0,0 +1,167 @@
+<script setup lang="ts">
+import type { UpdateDeploymentValueSource } from '@cpn-console/shared'
+import { getRandomId, toStringValue } from '@/utils/func'
+
+const props = defineProps<{
+  repoOptions: { text: string, value: string }[]
+  position: number
+  disabled: boolean
+  isDirty: boolean
+  canDelete: boolean
+  canMoveUp: boolean
+  canMoveDown: boolean
+  externalDisabled: boolean
+}>()
+
+defineEmits<{ delete: [], moveUp: [], moveDown: [] }>()
+
+const model = defineModel<UpdateDeploymentValueSource>({ required: true })
+
+// Unique radio group name so several segmented sets on the page don't interfere.
+const typeName = getRandomId('value-source-type')
+
+// The "Externe" choice is disabled once another source already uses it: a deployment may only carry a single external source.
+const typeOptions = computed(() => [
+  { label: 'Interne', value: 'internal' },
+  { label: 'Externe', value: 'external', disabled: props.externalDisabled },
+])
+
+function setType(value: string | number) {
+  if (value === 'external' && props.externalDisabled) {
+    return
+  }
+  model.value = value === 'external'
+    ? { type: 'external', id: model.value.id, path: model.value.path, ref: '', targetRevision: '', repositoryId: '' }
+    : { type: 'internal', id: model.value.id, path: model.value.path }
+}
+
+// Field patches never change the discriminant, so `type` is intentionally excluded:
+// spreading it over the union keeps each variant's `type` literal intact (use
+// setType to switch variants).
+type ValueSourcePatch = Partial<Pick<Extract<UpdateDeploymentValueSource, { type: 'external' }>, 'path' | 'ref' | 'targetRevision' | 'repositoryId'>>
+
+function update(patch: ValueSourcePatch): void {
+  model.value = { ...model.value, ...patch }
+}
+</script>
+
+<template>
+  <div class="w-full py-3 px-4 border border-solid border-gray-200 flex flex-col gap-2">
+    <div class="flex items-center justify-between gap-2 flex-wrap">
+      <div class="flex items-start gap-2">
+        <span class="fr-text--sm fr-text-mention--grey font-bold mb-0">Sources #{{ props.position }}</span>
+      </div>
+      <div v-if="!props.disabled" class="flex items-center gap-1">
+        <DsfrButton
+          icon-only
+          icon="ri:arrow-up-line"
+          size="sm"
+          tertiary
+          no-outline
+          title="Monter"
+          :disabled="!props.canMoveUp"
+          @click="$emit('moveUp')"
+        />
+        <DsfrButton
+          icon-only
+          icon="ri:arrow-down-line"
+          size="sm"
+          tertiary
+          no-outline
+          title="Descendre"
+          :disabled="!props.canMoveDown"
+          @click="$emit('moveDown')"
+        />
+        <DsfrButton
+          icon-only
+          icon="ri:delete-bin-7-line"
+          size="sm"
+          secondary
+          title="Supprimer"
+          :disabled="!props.canDelete"
+          @click="$emit('delete')"
+        />
+      </div>
+    </div>
+
+    <div class="flex items-center justify-center gap-2 w-full">
+      <DsfrSegmentedSet
+        :model-value="model.type"
+        :name="typeName"
+        :options="typeOptions"
+        inline
+        legend=""
+        :disabled="props.disabled"
+        class="w-full"
+        @update:model-value="setType"
+      />
+    </div>
+
+    <p v-if="props.externalDisabled" class="fr-text--xs fr-text-mention--grey fr-mb-0">
+      Une source externe est déjà définie : une seule est autorisée par déploiement.
+    </p>
+
+    <template v-if="model.type === 'external'">
+      <DsfrSelect
+        :model-value="model.repositoryId ?? undefined"
+        label="Dépôt de valeurs"
+        :options="props.repoOptions"
+        required
+        :disabled="props.disabled"
+        :error-message="props.isDirty && !model.repositoryId ? 'Le dépôt de valeurs est requis' : undefined"
+        @update:model-value="(value: string | number) => update({ repositoryId: toStringValue(value) })"
+      />
+      <DsfrInputGroup
+        :model-value="model.ref"
+        label="Nom de la source (ref)"
+        label-visible
+        placeholder="infra-values"
+        hint="Nom court (ref) donné à cette source pour qu'ArgoCD la référence. Unique par déploiement."
+        required
+        :disabled="props.disabled"
+        :error-message="props.isDirty && !model.ref ? 'Le nom de la référence est requis' : undefined"
+        @update:model-value="(value: string | number | undefined) => update({ ref: toStringValue(value) })"
+      />
+      <DsfrInputGroup
+        :model-value="model.targetRevision"
+        label="Révision (branche, tag, commit)"
+        label-visible
+        placeholder="HEAD"
+        :disabled="props.disabled"
+        @update:model-value="(value: string | number | undefined) => update({ targetRevision: toStringValue(value) })"
+      />
+    </template>
+
+    <DsfrInputGroup
+      :model-value="model.path"
+      label="Chemin du fichier de valeurs"
+      label-visible
+      :placeholder="model.type === 'external' ? 'values-&lt;env&gt;.yaml' : 'values.yaml'"
+      hint="Chemin du fichier relatif à la racine du dépôt. Le motif <env> est remplacé par le nom de l'environnement."
+      required
+      :disabled="props.disabled"
+      :error-message="props.isDirty && !model.path ? 'Le chemin du fichier est requis' : undefined"
+      @update:model-value="(value: string | number | undefined) => update({ path: toStringValue(value) })"
+    />
+  </div>
+</template>
+
+<style lang="css" scoped>
+.fr-select-group,
+.fr-input-group {
+  margin-bottom: .5rem;
+}
+
+.fr-form-group :deep(.fr-segmented),
+.fr-form-group :deep(.fr-segmented__elements) {
+  width: 100%;
+}
+
+.fr-form-group :deep(.fr-segmented__element) {
+  flex-grow: 1;
+}
+
+.fr-form-group :deep(.fr-segmented__element label) {
+  justify-content: center;
+}
+</style>
diff --git a/apps/client/src/components/DeploymentValueSources.vue b/apps/client/src/components/DeploymentValueSources.vue
new file mode 100644
index 0000000000..2cbe72067f
--- /dev/null
+++ b/apps/client/src/components/DeploymentValueSources.vue
@@ -0,0 +1,104 @@
+<script setup lang="ts">
+import type { UpdateDeploymentValueSource } from '@cpn-console/shared'
+import { hasExternalValueSource, newInternalValueSource } from '@/utils/deployment-draft'
+import { getRandomId, swapItems } from '@/utils/func'
+
+const props = defineProps<{
+  repoOptions: { text: string, value: string }[]
+  disabled: boolean
+  isDirty: boolean
+}>()
+
+const valueSources = defineModel<UpdateDeploymentValueSource[]>({ default: () => [] })
+
+// Stable per-row keys, kept in lockstep with the array so reordering swaps rendered
+// rows instead of relying on positional (index) keys, which break reactivity on move.
+const rowKeys = ref<string[]>([])
+function freshKey() {
+  return getRandomId('value-source')
+}
+
+// Rebuild keys only when the array is replaced from the outside (initial load / edit),
+// detected by a length mismatch. In-component mutations keep the lengths aligned.
+watch(valueSources, (sources) => {
+  if (rowKeys.value.length !== sources.length) {
+    rowKeys.value = sources.map(freshKey)
+  }
+}, { immediate: true })
+
+function addValueSource() {
+  valueSources.value = [...valueSources.value, newInternalValueSource()]
+  rowKeys.value = [...rowKeys.value, freshKey()]
+}
+
+function remove(index: number) {
+  valueSources.value = valueSources.value.filter((_, i) => i !== index)
+  rowKeys.value = rowKeys.value.filter((_, i) => i !== index)
+}
+
+function move(index: number, direction: -1 | 1) {
+  const nextSources = swapItems(valueSources.value, index, direction)
+  // Same reference means the move fell off either end of the list: nothing to do.
+  if (nextSources === valueSources.value) {
+    return
+  }
+
+  // Swap the source and its key together so the row keeps its identity as it moves.
+  valueSources.value = nextSources
+  rowKeys.value = swapItems(rowKeys.value, index, direction)
+}
+
+function update(index: number, value: UpdateDeploymentValueSource) {
+  valueSources.value = valueSources.value.map((valueSource, i) => i === index ? value : valueSource)
+}
+
+// Only one external source is allowed per deployment; internal sources are unlimited.
+// Once a source is external, the "Externe" choice is disabled on every other row.
+const hasExternal = computed(() => hasExternalValueSource(valueSources.value))
+</script>
+
+<template>
+  <div class="w-full flex flex-col gap-2">
+    <div class="flex flex-col gap-0">
+      <h6 class="fr-mb-0 fr-text--sm">
+        Sources de valeurs (Helm)
+      </h6>
+      <p class="fr-text--xs fr-text-mention--grey fr-mb-1v">
+        Liste ordonnée, optionnelle : chaque source surcharge les précédentes. Une seule source externe autorisée.
+      </p>
+    </div>
+
+    <p v-if="valueSources.length === 0" class="fr-text--xs fr-text-mention--grey fr-mb-0">
+      Aucune source : le fichier <code class="fr-text--xs fr-mb-0">values.yaml</code> du dépôt est utilisé par défaut.
+    </p>
+
+    <DeploymentValueSourceOption
+      v-for="(valueSource, index) in valueSources"
+      :key="rowKeys[index]"
+      :model-value="valueSource"
+      :position="index + 1"
+      :repo-options="props.repoOptions"
+      :disabled="props.disabled"
+      :is-dirty="props.isDirty"
+      :external-disabled="valueSource.type !== 'external' && hasExternal"
+      :can-delete="true"
+      :can-move-up="index > 0"
+      :can-move-down="index < valueSources.length - 1"
+      @update:model-value="(value: UpdateDeploymentValueSource) => update(index, value)"
+      @delete="remove(index)"
+      @move-up="move(index, -1)"
+      @move-down="move(index, 1)"
+    />
+
+    <div v-if="!props.disabled" class="w-full flex justify-end gap-2 mt-2">
+      <DsfrButton
+        type="button"
+        label="Ajouter une source de valeurs"
+        icon="ri:add-line"
+        secondary
+        size="sm"
+        @click="addValueSource"
+      />
+    </div>
+  </div>
+</template>
diff --git a/apps/client/src/utils/deployment-draft.spec.ts b/apps/client/src/utils/deployment-draft.spec.ts
new file mode 100644
index 0000000000..940be128d0
--- /dev/null
+++ b/apps/client/src/utils/deployment-draft.spec.ts
@@ -0,0 +1,132 @@
+import type { Deployment, DeploymentSource, DeploymentValueSource } from '@cpn-console/shared'
+import { faker } from '@faker-js/faker'
+import { describe, expect, it } from 'vitest'
+import {
+  hasExternalValueSource,
+  newInternalValueSource,
+  toDeploymentDraft,
+  toDeploymentSourceDraft,
+  toValueSourceDraft,
+} from './deployment-draft.js'
+
+type ReadSource = Pick<DeploymentSource, 'id' | 'type' | 'repositoryId' | 'targetRevision' | 'path' | 'helmValuesFiles' | 'valueSources'>
+
+function makeInternalValueSource(order: number, path = `values-${order}.yaml`): DeploymentValueSource {
+  return { type: 'internal', id: faker.string.uuid(), order, path }
+}
+
+function makeExternalValueSource(order: number): DeploymentValueSource {
+  return { type: 'external', id: faker.string.uuid(), order, path: 'ext.yaml', ref: 'infra', targetRevision: 'main', repositoryId: faker.string.uuid() }
+}
+
+function makeReadSource(overrides: Partial<ReadSource> = {}): ReadSource {
+  return {
+    id: faker.string.uuid(),
+    type: 'git',
+    repositoryId: faker.string.uuid(),
+    targetRevision: 'main',
+    path: '/app',
+    helmValuesFiles: 'values.yaml',
+    valueSources: [],
+    ...overrides,
+  }
+}
+
+describe('deploymentDraft', () => {
+  describe('toValueSourceDraft', () => {
+    it('should drop the persistence `order` from an internal source and keep its id', () => {
+      const valueSource = makeInternalValueSource(3, 'a.yaml')
+
+      expect(toValueSourceDraft(valueSource)).toEqual({ type: 'internal', id: valueSource.id, path: 'a.yaml' })
+    })
+
+    it('should keep every external field except `order`', () => {
+      const valueSource = makeExternalValueSource(1)
+
+      expect(toValueSourceDraft(valueSource)).toEqual({
+        type: 'external',
+        id: valueSource.id,
+        path: 'ext.yaml',
+        ref: 'infra',
+        targetRevision: 'main',
+        repositoryId: valueSource.repositoryId,
+      })
+    })
+  })
+
+  describe('toDeploymentSourceDraft', () => {
+    it('should map the value sources in order and keep the writable fields', () => {
+      // The API returns value sources already ordered; the editor keeps that order.
+      const internal = makeInternalValueSource(0, 'a.yaml')
+      const external = makeExternalValueSource(1)
+      const source = makeReadSource({ valueSources: [internal, external] })
+
+      expect(toDeploymentSourceDraft(source)).toEqual({
+        id: source.id,
+        type: 'git',
+        repositoryId: source.repositoryId,
+        targetRevision: 'main',
+        path: '/app',
+        helmValuesFiles: 'values.yaml',
+        valueSources: [
+          { type: 'internal', id: internal.id, path: 'a.yaml' },
+          {
+            type: 'external',
+            id: external.id,
+            path: 'ext.yaml',
+            ref: 'infra',
+            targetRevision: 'main',
+            repositoryId: external.repositoryId,
+          },
+        ],
+      })
+    })
+  })
+
+  describe('toDeploymentDraft', () => {
+    it('should map top-level fields and every deployment source', () => {
+      const deployment = {
+        id: faker.string.uuid(),
+        projectId: faker.string.uuid(),
+        name: 'mydeployment',
+        environmentId: faker.string.uuid(),
+        autosync: true,
+        deploymentSources: [makeReadSource(), makeReadSource()],
+      } satisfies Pick<
+        Deployment,
+        'id'
+        | 'projectId'
+        | 'name'
+        | 'environmentId'
+        | 'autosync'
+      > & { deploymentSources: ReadSource[] }
+
+      const draft = toDeploymentDraft(deployment)
+
+      expect(draft).toMatchObject({
+        id: deployment.id,
+        projectId: deployment.projectId,
+        name: 'mydeployment',
+        environmentId: deployment.environmentId,
+        autosync: true,
+      })
+      expect(draft.deploymentSources).toHaveLength(2)
+    })
+  })
+
+  describe('newInternalValueSource', () => {
+    it('should default to an internal source with an empty path', () => {
+      expect(newInternalValueSource()).toEqual({ type: 'internal', path: '' })
+    })
+  })
+
+  describe('hasExternalValueSource', () => {
+    it('should be true when at least one source is external', () => {
+      expect(hasExternalValueSource([{ type: 'internal' }, { type: 'external' }])).toBe(true)
+    })
+
+    it('should be false when every source is internal', () => {
+      expect(hasExternalValueSource([{ type: 'internal' }, { type: 'internal' }])).toBe(false)
+    })
+  })
+})
diff --git a/apps/client/src/utils/deployment-draft.ts b/apps/client/src/utils/deployment-draft.ts
new file mode 100644
index 0000000000..f2ca07c781
--- /dev/null
+++ b/apps/client/src/utils/deployment-draft.ts
@@ -0,0 +1,62 @@
+import type {
+  Deployment,
+  DeploymentSource,
+  DeploymentValueSource,
+  UpdateDeployment,
+  UpdateDeploymentSource,
+  UpdateDeploymentValueSource,
+} from '@cpn-console/shared'
+
+type ReadDeploymentSource = Pick<
+  DeploymentSource,
+'id' | 'type' | 'repositoryId' | 'targetRevision' | 'path' | 'helmValuesFiles' | 'valueSources'
+>
+type ReadDeployment = Pick<
+  Deployment,
+'id' | 'projectId' | 'name' | 'environmentId' | 'autosync'
+> & { deploymentSources: ReadDeploymentSource[] }
+
+export function toValueSourceDraft(valueSource: DeploymentValueSource): UpdateDeploymentValueSource {
+  return valueSource.type === 'external'
+    ? {
+        type: 'external',
+        id: valueSource.id,
+        path: valueSource.path,
+        ref: valueSource.ref,
+        targetRevision: valueSource.targetRevision,
+        repositoryId: valueSource.repositoryId,
+      }
+    : { type: 'internal', id: valueSource.id, path: valueSource.path }
+}
+
+export function toDeploymentSourceDraft(source: ReadDeploymentSource): UpdateDeploymentSource {
+  return {
+    id: source.id,
+    type: source.type,
+    repositoryId: source.repositoryId,
+    targetRevision: source.targetRevision,
+    path: source.path,
+    helmValuesFiles: source.helmValuesFiles,
+    valueSources: source.valueSources.map(toValueSourceDraft),
+  }
+}
+
+export function toDeploymentDraft(deployment: ReadDeployment): Partial<UpdateDeployment & { id: string }> {
+  return {
+    id: deployment.id,
+    projectId: deployment.projectId,
+    name: deployment.name,
+    environmentId: deployment.environmentId,
+    autosync: deployment.autosync,
+    deploymentSources: deployment.deploymentSources.map(toDeploymentSourceDraft),
+  }
+}
+
+export function newInternalValueSource(): UpdateDeploymentValueSource {
+  return { type: 'internal', path: '' }
+}
+
+// At most one external value source is allowed per deployment source.
+export function hasExternalValueSource(valueSources: Pick<UpdateDeploymentValueSource, 'type'>[]): boolean {
+  return valueSources.some(valueSource => valueSource.type === 'external')
+}
diff --git a/apps/client/src/utils/func.spec.ts b/apps/client/src/utils/func.spec.ts
index 75ef96cead..a0204e6793 100644
--- a/apps/client/src/utils/func.spec.ts
+++ b/apps/client/src/utils/func.spec.ts
@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { swapItems } from './func'
 
 describe('localeParseFloat EN tests', () => {
   let localeParseFloatEN: (s: string) => number
@@ -42,3 +43,25 @@ describe('localeParseFloat FR tests', () => {
     expect(result).toBe(4.25)
   })
 })
+
+describe('swapItems', () => {
+  it('should swap the item with its neighbour in the given direction', () => {
+    expect(swapItems(['a', 'b', 'c'], 0, 1)).toEqual(['b', 'a', 'c'])
+    expect(swapItems(['a', 'b', 'c'], 2, -1)).toEqual(['a', 'c', 'b'])
+  })
+
+  it('should return the same array reference when the move falls off either end', () => {
+    const items = ['a', 'b', 'c']
+
+    expect(swapItems(items, 0, -1)).toBe(items)
+    expect(swapItems(items, 2, 1)).toBe(items)
+  })
+
+  it('should not mutate the input array', () => {
+    const items = ['a', 'b', 'c']
+
+    swapItems(items, 0, 1)
+
+    expect(items).toEqual(['a', 'b', 'c'])
+  })
+})
diff --git a/apps/client/src/utils/func.ts b/apps/client/src/utils/func.ts
index 71f1a61b5e..159a7c8dcf 100644
--- a/apps/client/src/utils/func.ts
+++ b/apps/client/src/utils/func.ts
@@ -1,5 +1,5 @@
 import type { Ref } from 'vue'
-import { useSnackbarStore } from '@/stores/snackbar.js'
+import { useSnackbarStore } from '@/stores/snackbar'
 
 const LOCALE = navigator.language.slice(0, 2)
 // Get the thousands and decimal separator characters used in the locale.
@@ -87,6 +87,25 @@ export function localeParseFloat(s: string): number {
   return Number.parseFloat(delocalizedInput)
 }
 
+// DSFR inputs emit `string | number | undefined`; coerce to a plain string for
+// string-typed form fields (empty string when the value is cleared).
+export function toStringValue(value: string | number | undefined): string {
+  return value === undefined ? '' : String(value)
+}
+
+// Swaps an item with its neighbour and returns a new array. Out-of-bounds moves are
+// a no-op, returning the original array so callers can skip the update.
+export function swapItems<T>(items: T[], index: number, direction: -1 | 1): T[] {
+  const target = index + direction
+  if (target < 0 || target >= items.length) return items
+
+  const reordered = [...items]
+  const moved = reordered[index]
+  reordered[index] = reordered[target]
+  reordered[target] = moved
+  return reordered
+}
+
 export async function scrollToFirstError(container: Ref<HTMLDivElement | null>) {
   await nextTick()