@revenexx/studio-integrations 3.1.0 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @revenexx/studio-integrations
 
+## 3.3.0
+
+### Minor Changes
+
+- 1318abe: A credential can reach its system through a VPN route instead of the public internet. For a credential type that declares which of its fields a route stands in for, both credential forms gain a Network section: public internet, or one of the tenant's VPN connections (with its status) and a route of the kind the type speaks. The fields the route replaces turn read-only and show what they reach; an HTTPS target notes that its certificate is not verified at the gateway; a tenant without connections is pointed at the VPN connections page where the host has one. A credential that goes through a VPN carries a badge in the credentials list and in a node's credential picker, naming the connection, its state when it is not active, and a route that no longer exists. A node setting of the new type `vpn-route` is drawn as the same choice and stores `{ connection, route }`, or nothing for the public internet. Needs the Integrations service's `GET /api/v1/vpn-connections` and the credential `network` field (PO-825).
+
+### Patch Changes
+
+- f73ff6c: A new credential's form starts from the defaults its system declares. A list read *Select* and a number stood empty even where the system had chosen a value — an FTP credential's encryption, its port — so the screen said nothing had been chosen; they now show that value, and saving without touching them stores it. Picking the system again after going back starts from those defaults instead of the last attempt's values. Both places a credential is added work the same: the credentials list and a node's credential setting. Opening a stored credential shows the default for a field it never stored, rather than an empty field or a switch drawn off; a value it did store still wins, and an untouched form still tests the stored credential.
+
+## 3.2.0
+
+### Minor Changes
+
+- 60e6143: A template whose requirements the platform could not answer for is no longer shown as ready to install. The template page's setup rail and the install step now say they could not check what the template needs, with the platform's reason, instead of "Everything is ready to install" and "This template needs no credentials"; installing stays possible. While the answer is still on its way, the rail claims nothing.
+  
+  For hosts: `useIntegrationsTemplates()` gains `checkRequirements(slug)`, which rejects with the platform's reason where `requirements(slug)` resolves to `null`, and `uncheckedReason(error)`, which turns that rejection into the sentence the studio shows. `requirements` still behaves as before but is now deprecated: its `null` cannot tell "could not check" from "needs nothing", so a host that reads it as an empty answer shows an unchecked template as ready. Switch to `checkRequirements`.
+
+### Patch Changes
+
+- e62ae58: A failed step now says why it failed in one sentence. The run record's step list showed the whole error the platform sends, as a block of JSON; it now shows the message. The replay's debug panel shows the message and the failure's type, and the places in the node's own code where it failed as a list that stays folded until opened.
+
 ## 3.1.0
 
 ### Minor Changes

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@revenexx/studio-integrations",
   "configKey": "studioIntegrations",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/runtime/components/Integrations/CredentialCreateDialog.vue

@@ -20,10 +20,12 @@ import {
 } from "@revenexx/studio";
 import { toast } from "vue-sonner";
 import { resolveLocalized } from "../../utils/localize";
+import { defaultsFor } from "../../utils/configDefaults";
 import { fromModelValue, toItemValue, toModelValue } from "../../utils/selectOptions";
 import { errorReason } from "../../utils/apiError";
 import { keepOpenBeside } from "../../utils/dialog";
 import { testOutcomeView } from "../../utils/credentialTest";
+import { credentialNetworkPayload, replacedFieldTexts } from "../../utils/vpnRoute";
 const props = defineProps({
   open: { type: Boolean, required: true },
   credentialType: { type: [String, Array], required: false }
@@ -61,6 +63,13 @@ const sourceActive = ref(false);
 const saving = ref(false);
 const testing = ref(false);
 const testResult = ref(null);
+const { connections: vpnConnections } = useVpnConnections();
+const network = ref(null);
+const networkComplete = ref(true);
+const replaced = computed(() => replacedFieldTexts(pickedType.value, network.value, vpnConnections.value));
+function networkPayload() {
+  return pickedType.value?.network ? credentialNetworkPayload(network.value) : void 0;
+}
 function fieldsOf(t2) {
   return t2?.fields ?? [];
 }
@@ -72,10 +81,12 @@ watch(() => props.open, async (o) => {
   testResult.value = null;
   sourceActive.value = false;
   form.config = {};
+  network.value = null;
   await loadTypes();
   if (allowedTypes.value.length === 1) {
     pickedType.value = allowedTypes.value[0];
     form.name = resolveLocalized(pickedType.value.name);
+    form.config = defaultsFor(fieldsOf(pickedType.value));
   } else {
     pickedType.value = null;
     form.name = "";
@@ -83,9 +94,10 @@ watch(() => props.open, async (o) => {
 }, { immediate: true });
 function pickType(t2) {
   pickedType.value = t2;
-  form.config = {};
+  form.config = defaultsFor(fieldsOf(t2));
   testResult.value = null;
   sourceActive.value = false;
+  network.value = null;
   if (!form.name) form.name = resolveLocalized(t2.name);
 }
 function buildConfigPayload() {
@@ -101,7 +113,7 @@ async function runTest() {
   testing.value = true;
   testResult.value = null;
   try {
-    testResult.value = await testInline(pickedType.value.slug, buildConfigPayload());
+    testResult.value = await testInline(pickedType.value.slug, buildConfigPayload(), networkPayload());
   } finally {
     testing.value = false;
   }
@@ -119,7 +131,8 @@ async function submit() {
     const created = await create({
       credential_type_slug: pickedType.value.slug,
       name: form.name.trim(),
-      config: buildConfigPayload()
+      config: buildConfigPayload(),
+      network: networkPayload()
     });
     await load(true);
     toast.success(t("integration.credentials.toast.created"));
@@ -193,13 +206,28 @@ async function submit() {
           @apply="(c) => Object.assign(form.config, c)"
         />
 
+        <IntegrationsCredentialNetworkSection
+          v-model="network"
+          :type="pickedType"
+          id-prefix="create-network"
+          @update:complete="(c) => networkComplete = c"
+        />
+
         <!-- Each label names its own control (`for`/`id`): without it a screen
              reader reads the field as unlabelled, and the label text cannot be
              used to reach it at all. -->
         <div v-for="f in fieldsOf(pickedType)" v-show="!sourceActive" :key="f.key" class="space-y-1.5">
           <Label :for="`create-field-${f.key}`">{{ resolveLocalized(f.label) }}{{ f.required ? " *" : "" }}</Label>
+          <!-- stood in for by the chosen VPN route: what it reaches, not editable -->
+          <Input
+            v-if="replaced[f.key]"
+            :id="`create-field-${f.key}`"
+            :model-value="replaced[f.key]"
+            readonly
+            class="bg-muted/40"
+          />
           <Input
-            v-if="f.type === 'secret'"
+            v-else-if="f.type === 'secret'"
             :id="`create-field-${f.key}`"
             :model-value="form.config[f.key] ?? ''"
             type="password"
@@ -259,12 +287,12 @@ async function submit() {
 
       <DialogFooter v-if="pickedType">
         <div class="flex items-center gap-2">
-          <Button variant="outline" :disabled="saving || testing" @click="runTest">
+          <Button variant="outline" :disabled="saving || testing || !networkComplete" @click="runTest">
             <Loader2 v-if="testing" :size="14" class="mr-1 animate-spin" />
             <TestIcon v-else :size="14" class="mr-1" />
             {{ t("integration.credentials.shared.action.testConnection") }}
           </Button>
-          <Button :disabled="saving || !form.name.trim()" @click="submit">
+          <Button :disabled="saving || !form.name.trim() || !networkComplete" @click="submit">
             <Loader2 v-if="saving" :size="14" class="mr-1 animate-spin" />
             {{ t("integration.common.action.save") }}
           </Button>

package/dist/runtime/components/Integrations/CredentialDetailDialog.vue

@@ -33,6 +33,7 @@ import { toast } from "../../utils/notify";
 import { apiRefusal, errorReason } from "../../utils/apiError";
 import { credentialState } from "../../utils/credentialState";
 import { credentialEditDiffers } from "../../utils/credentialEdit";
+import { defaultsFor } from "../../utils/configDefaults";
 import { relativeTime } from "../../utils/relativeTime";
 import { useNow } from "../../composables/useNow";
 import { hasRevenexxSource } from "../../utils/revenexxCredentialSource";
@@ -40,6 +41,7 @@ import { resolveLocalized } from "../../utils/localize";
 import { fromModelValue, toItemValue, toModelValue } from "../../utils/selectOptions";
 import { keepOpenBeside } from "../../utils/dialog";
 import { testOutcomeView } from "../../utils/credentialTest";
+import { credentialNetworkPayload, fromCredentialNetwork, replacedFieldTexts, sameVpnRoute } from "../../utils/vpnRoute";
 const props = defineProps({
   open: { type: Boolean, required: true },
   credential: { type: [Object, null], required: true },
@@ -61,8 +63,17 @@ const deleting = ref(false);
 const testing = ref(false);
 const liveTest = ref(null);
 const saveRefusal = ref(null);
+const { connections: vpnConnections } = useVpnConnections();
+const network = ref(null);
+const networkComplete = ref(true);
+const replaced = computed(() => replacedFieldTexts(props.type, network.value, vpnConnections.value));
+const networkChanged = computed(() => !!props.type?.network && !sameVpnRoute(network.value, fromCredentialNetwork(props.credential?.network)));
+function networkPayload() {
+  return networkChanged.value ? credentialNetworkPayload(network.value) : void 0;
+}
 const drawnKeys = computed(() => [
   "name",
+  ...props.type?.network ? ["network"] : [],
   ...sourceActive.value ? [] : fieldsOf(props.type).map((f) => `config.${f.key}`)
 ]);
 const refusal = computed(() => apiRefusal(saveRefusal.value, drawnKeys.value));
@@ -80,7 +91,7 @@ async function focusFirstRefusedField() {
   await nextTick();
   const key = drawnKeys.value.find((k) => k in fieldErrors.value);
   if (!key) return;
-  const id = key === "name" ? "detail-cred-name" : `detail-field-${key.slice("config.".length)}`;
+  const id = key === "name" ? "detail-cred-name" : key === "network" ? "detail-network-public" : `detail-field-${key.slice("config.".length)}`;
   document.getElementById(id)?.focus();
 }
 function clearRefusal() {
@@ -102,14 +113,16 @@ function formatDateTime(iso) {
   }
 }
 let viewOpening = 0;
+const storedConfig = computed(() => ({ ...defaultsFor(fieldsOf(props.type)), ...props.credential?.public_config ?? {} }));
 watch(
-  [() => props.open, () => props.credential?.id],
+  [() => props.open, () => props.credential?.id, () => props.type?.slug],
   () => {
     viewOpening++;
     if (!props.open || !props.credential) return;
     tab.value = "credentials";
     form.name = props.credential.name;
-    form.config = { ...props.credential.public_config ?? {} };
+    form.config = { ...storedConfig.value };
+    network.value = fromCredentialNetwork(props.credential.network);
     sourceActive.value = false;
     liveTest.value = null;
     clearRefusal();
@@ -133,8 +146,8 @@ async function runTest() {
   clearRefusal();
   try {
     const payload = buildConfigPayload();
-    const edited = credentialEditDiffers(fieldsOf(props.type), payload, props.credential.public_config ?? {});
-    const result = await test(props.credential.id, edited ? payload : void 0);
+    const edited = credentialEditDiffers(fieldsOf(props.type), payload, storedConfig.value) || networkChanged.value;
+    const result = await test(props.credential.id, edited ? payload : void 0, edited ? networkPayload() : void 0);
     if (result.refusal) {
       if (opening !== viewOpening) return;
       saveRefusal.value = result.refusal;
@@ -161,10 +174,10 @@ async function save() {
   clearRefusal();
   const id = props.credential.id;
   const payload = buildConfigPayload();
-  const edited = credentialEditDiffers(fieldsOf(props.type), payload, props.credential.public_config ?? {});
+  const edited = credentialEditDiffers(fieldsOf(props.type), payload, storedConfig.value) || networkChanged.value;
   try {
     const wasConnected = props.credential.status !== "needs_reauth";
-    const updated = await update(id, { name: form.name.trim(), config: payload });
+    const updated = await update(id, { name: form.name.trim(), config: payload, network: networkPayload() });
     const lostConsent = wasConnected && updated.status === "needs_reauth";
     emit("changed");
     emit("update:open", false);
@@ -315,14 +328,33 @@ async function connect() {
                 @apply="(c) => Object.assign(form.config, c)"
               />
 
+              <!-- Keyed by the credential: the picker holds a half-made choice of
+                   its own, which belongs to the credential it was made on. -->
+              <IntegrationsCredentialNetworkSection
+                :key="credential.id"
+                v-model="network"
+                :type="type"
+                id-prefix="detail-network"
+                :error="fieldErrors.network"
+                @update:complete="(c) => networkComplete = c"
+              />
+
               <!-- Each label names its own control (`for`/`id`): without it a
                screen reader reads the field as unlabelled, and the label text
                cannot be used to reach it at all. -->
               <div v-for="f in fieldsOf(type)" v-show="!sourceActive" :key="f.key" class="space-y-1.5">
                 <Label :for="`detail-field-${f.key}`">{{ resolveLocalized(f.label) }}{{ f.required ? " *" : "" }}</Label>
 
+                <!-- stood in for by the chosen VPN route: what it reaches, not editable -->
+                <Input
+                  v-if="replaced[f.key]"
+                  :id="`detail-field-${f.key}`"
+                  :model-value="replaced[f.key]"
+                  readonly
+                  class="bg-muted/40"
+                />
                 <Input
-                  v-if="f.type === 'secret'"
+                  v-else-if="f.type === 'secret'"
                   :id="`detail-field-${f.key}`"
                   :model-value="form.config[f.key] ?? ''"
                   type="password"
@@ -405,12 +437,12 @@ async function connect() {
             <Button variant="ghost" :disabled="saving" @click="emit('update:open', false)">
               {{ t("integration.common.action.cancel") }}
             </Button>
-            <Button variant="outline" :disabled="testing || saving" @click="runTest">
+            <Button variant="outline" :disabled="testing || saving || !networkComplete" @click="runTest">
               <Loader2 v-if="testing" :size="14" class="mr-1 animate-spin" />
               <TestIcon v-else :size="14" class="mr-1" />
               {{ t("integration.credentials.shared.action.testConnection") }}
             </Button>
-            <Button :disabled="saving || !form.name.trim()" @click="save">
+            <Button :disabled="saving || !form.name.trim() || !networkComplete" @click="save">
               <Loader2 v-if="saving" :size="14" class="mr-1 animate-spin" />
               {{ t("integration.common.action.save") }}
             </Button>

package/dist/runtime/components/Integrations/CredentialNetworkSection.d.vue.ts

@@ -0,0 +1,21 @@
+/**
+ * The Network section of a credential form: how the credential reaches its system —
+ * over the public internet, or through a route of one of the tenant's VPN
+ * connections (specs/credential-network.md). Drawn only for a type that declares
+ * which of its fields a route stands in for; every other type has nothing to choose.
+ */
+import type { CredentialType, VpnRouteValue } from '../../types/integrations.js';
+type __VLS_Props = {
+    type: CredentialType | null;
+    modelValue: VpnRouteValue | null;
+    idPrefix: string;
+    error?: string;
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:complete": (args_0: boolean) => any;
+    "update:modelValue": (args_0: VpnRouteValue | null) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:complete"?: ((args_0: boolean) => any) | undefined;
+    "onUpdate:modelValue"?: ((args_0: VpnRouteValue | null) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/runtime/components/Integrations/CredentialNetworkSection.vue

@@ -0,0 +1,28 @@
+<script setup>
+defineProps({
+  type: { type: [Object, null], required: true },
+  modelValue: { type: [Object, null], required: true },
+  idPrefix: { type: String, required: true },
+  error: { type: String, required: false }
+});
+const emit = defineEmits(["update:modelValue", "update:complete"]);
+const t = useIntegrationsT();
+</script>
+
+<template>
+  <section
+    v-if="type?.network"
+    :aria-labelledby="`${idPrefix}-heading`"
+    class="space-y-2 rounded-lg border border-black/[0.08] p-3"
+  >
+    <h3 :id="`${idPrefix}-heading`" class="text-sm font-semibold">{{ t("integration.vpn.section.title") }}</h3>
+    <IntegrationsVpnRoutePicker
+      :model-value="modelValue"
+      :kind="type.network.kind"
+      :id-prefix="idPrefix"
+      :error="error"
+      @update:model-value="(v) => emit('update:modelValue', v)"
+      @update:complete="(c) => emit('update:complete', c)"
+    />
+  </section>
+</template>

package/dist/runtime/components/Integrations/CredentialNetworkSection.vue.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The Network section of a credential form: how the credential reaches its system —
+ * over the public internet, or through a route of one of the tenant's VPN
+ * connections (specs/credential-network.md). Drawn only for a type that declares
+ * which of its fields a route stands in for; every other type has nothing to choose.
+ */
+import type { CredentialType, VpnRouteValue } from '../../types/integrations.js';
+type __VLS_Props = {
+    type: CredentialType | null;
+    modelValue: VpnRouteValue | null;
+    idPrefix: string;
+    error?: string;
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:complete": (args_0: boolean) => any;
+    "update:modelValue": (args_0: VpnRouteValue | null) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:complete"?: ((args_0: boolean) => any) | undefined;
+    "onUpdate:modelValue"?: ((args_0: VpnRouteValue | null) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/runtime/components/Integrations/NodeConfigField.vue

@@ -20,6 +20,7 @@ import { credentialState } from "../../utils/credentialState";
 import { defaultsFor } from "../../utils/configDefaults";
 import { applyingFields, settingApplies, staleKeys } from "../../utils/settingCondition";
 import { coerceSettingValue } from "../../utils/settingValue";
+import { credentialVpnBadge, isVpnRouteValue } from "../../utils/vpnRoute";
 const props = defineProps({
   field: { type: Object, required: true },
   config: { type: Object, required: true },
@@ -110,6 +111,14 @@ const { credentials, loaded: credentialsLoaded, load: loadCredentials, refresh:
 onMounted(() => {
   void loadCredentials();
 });
+const { connections: vpnConnections, loaded: vpnLoaded, load: loadVpn } = useVpnConnections();
+watch(
+  () => props.field.type === "credentials-ref" && credsForField(props.field).some((c) => c.network),
+  (needed) => {
+    if (needed) void loadVpn();
+  },
+  { immediate: true }
+);
 function onCredentialPickerOpen(open) {
   if (open) void refreshCredentials();
 }
@@ -132,14 +141,15 @@ function credsForField(field) {
 const bound = computed(() => {
   const id = value.value;
   const c = typeof id === "string" && id ? credentials.value.find((x) => x.id === id) : void 0;
-  return c ? { credential: c, state: credentialState(c) } : null;
+  return c ? { credential: c, state: credentialState(c), vpn: credentialVpnBadge(c.network, vpnConnections.value, vpnLoaded.value) } : null;
 });
 const credOptions = computed(
-  () => credsForField(props.field).map((c) => ({ credential: c, state: credentialState(c) }))
+  () => credsForField(props.field).map((c) => ({ credential: c, state: credentialState(c), vpn: credentialVpnBadge(c.network, vpnConnections.value, vpnLoaded.value) }))
 );
 const UNKNOWN_CREDENTIAL = computed(() => t("integration.nodeConfig.credential.unknown"));
 const credTriggerLabel = computed(() => {
   const label = controlName.value;
+  if (bound.value?.vpn) return t("integration.nodeConfig.credential.trigger.boundVpn", { label, name: bound.value.credential.name, state: bound.value.state.label, vpn: bound.value.vpn.text });
   if (bound.value) return t("integration.nodeConfig.credential.trigger.bound", { label, name: bound.value.credential.name, state: bound.value.state.label });
   if (value.value && credentialsLoaded.value) return t("integration.nodeConfig.credential.trigger.unknown", { label, unknown: UNKNOWN_CREDENTIAL.value });
   return label;
@@ -394,8 +404,21 @@ function setArrayItemField(index, fieldKey, v) {
          inside string values). Wins over expressionAllowed — an object value
          in a text input would render as [object Object]. -->
     <!-- queries parameter: filter builder -->
+    <!-- vpn-route — public internet, or a route of one of the tenant's VPN
+         connections, of the kind the node asks for (specs/credential-network.md
+         AC-8). Ahead of every other branch: its value is an object, which the JSON
+         and expression branches below would otherwise claim. -->
+    <IntegrationsVpnRoutePicker
+      v-if="field.type === 'vpn-route'"
+      :model-value="isVpnRouteValue(value) ? { connection: value.connection, route: value.route } : null"
+      :kind="field.routeKind ?? 'http'"
+      :id-prefix="`vpn-${field.key}-${rowIndex ?? 0}`"
+      :label="controlName"
+      @update:model-value="(v) => emit('set', field.key, v)"
+    />
+
     <IntegrationsQueryBuilder
-      v-if="isQueryField"
+      v-else-if="isQueryField"
       :model-value="value"
       @update:model-value="(v) => write(v)"
     />
@@ -651,6 +674,13 @@ function setArrayItemField(index, fieldKey, v) {
               >
                 {{ bound.state.label }}
               </span>
+              <span
+                v-if="bound.vpn"
+                class="shrink-0 rounded-full border px-1.5 py-px text-[10px] font-medium"
+                :class="bound.vpn.tone"
+              >
+                {{ bound.vpn.text }}
+              </span>
             </span>
             <!-- A stored id the tenant's credentials no longer contain: the
                  credential was deleted, and the field would otherwise look untouched
@@ -677,6 +707,13 @@ function setArrayItemField(index, fieldKey, v) {
                 :class="o.state.toneClass"
                 :title="o.state.message ?? void 0"
               >{{ o.state.label }}</span>
+              <!-- Reached through a VPN route: the connection, and its state where it
+                   is not carrying traffic (specs/credential-network.md AC-6). -->
+              <span
+                v-if="o.vpn"
+                class="shrink-0 rounded-full border px-1.5 py-px text-[10px] font-medium"
+                :class="o.vpn.tone"
+              >{{ o.vpn.text }}</span>
             </span>
           </SelectItem>
           <div v-if="!credOptions.length" class="px-2 py-1.5 text-sm text-muted-foreground">
@@ -699,6 +736,12 @@ function setArrayItemField(index, fieldKey, v) {
       <p v-else-if="bound?.state.key === 'failed' && bound.state.message" class="text-sm break-words text-rose-600">
         {{ t("integration.nodeConfig.credential.state.failed", { message: bound.state.message }) }}
       </p>
+      <p v-if="bound?.vpn?.broken && bound.credential.network" class="text-sm break-words text-rose-600">
+        {{ t("integration.vpn.reference.missing", { connection: bound.credential.network.connection, route: bound.credential.network.route }) }}
+      </p>
+      <p v-else-if="bound?.vpn && !bound.vpn.active" class="text-sm text-amber-600">
+        {{ t("integration.nodeConfig.credential.vpnInactive") }}
+      </p>
       <IntegrationsCredentialCreateDialog
         v-model:open="credCreateOpen"
         :credential-type="field.credentialType"

package/dist/runtime/components/Integrations/RunDetailPanel.vue

@@ -4,6 +4,7 @@ import { Download as DownloadIcon, RefreshCircle as RefreshIcon } from "#solar-i
 import { Badge, Button, Dialog, DialogContent, DialogHeader, DialogTitle } from "@revenexx/studio";
 import { runStatusClass, runStatusLabel } from "../../utils/statusStyle";
 import { isSkippedStep, skipReasonMessage, stepStatusLabel } from "../../utils/skippedStep";
+import { stepError } from "../../utils/stepError";
 import { IntegrationsApiError, errorReason } from "../../utils/apiError";
 import { createPollBudget, SAFETY_POLL_MS } from "../../utils/pollBudget";
 import { formatDuration } from "../../utils/formatDuration";
@@ -764,8 +765,8 @@ async function confirmAction() {
               <span class="text-xs text-muted-foreground tabular-nums shrink-0">{{ fmtMs(st.duration_ms) }}</span>
               <span v-if="!isSkippedStep(st)" class="text-[10px] text-muted-foreground shrink-0">{{ expandedStep === stepKey(st, i) ? "\u25BC" : "\u25B6" }}</span>
             </button>
-            <div v-if="st.error" class="px-3 pb-2 -mt-1">
-              <div class="rounded-md border border-rose-500/20 bg-rose-500/5 px-2 py-1 text-xs text-rose-700 break-words">{{ st.error }}</div>
+            <div v-if="stepError(st.error)" class="px-3 pb-2 -mt-1">
+              <div class="rounded-md border border-rose-500/20 bg-rose-500/5 px-2 py-1 text-xs text-rose-700 break-words whitespace-pre-wrap" data-testid="step-error">{{ stepError(st.error).message }}</div>
             </div>
             <div v-if="expandedStep === stepKey(st, i)" class="px-3 pb-3 space-y-2">
               <template v-if="hasPayload(st)">

package/dist/runtime/components/Integrations/TemplateInstallStep.vue

@@ -20,10 +20,11 @@ const props = defineProps({
 });
 const emit = defineEmits(["installed", "update:loading", "update:installing"]);
 const t = useIntegrationsT();
-const { get, load, fetchDetail, requirements, instantiate } = useIntegrationsTemplates();
+const { get, load, fetchDetail, checkRequirements, uncheckedReason, instantiate } = useIntegrationsTemplates();
 const { keys: secretKeys, load: loadSecrets } = useIntegrationsSecrets();
 const { ofType, refresh: refreshCredentials } = useIntegrationsCredentials();
 const reqs = ref(null);
+const reqsError = ref(null);
 const loading = ref(true);
 const installing = ref(false);
 const error = ref(null);
@@ -35,40 +36,37 @@ watch(() => props.slug, async (slug) => {
   const mine = ++run;
   loading.value = true;
   reqs.value = null;
+  reqsError.value = null;
   error.value = null;
   name.value = "";
   for (const k of Object.keys(bindings)) delete bindings[k];
-  await load();
-  if (mine !== run) return;
-  if (name.value === "") name.value = get(slug)?.name ?? "";
-  await Promise.all([fetchDetail(slug), refreshCredentials(), loadSecrets()]);
-  if (mine !== run) return;
-  const answer = await requirements(slug);
+  let answer = null;
+  let failure = null;
+  try {
+    await load();
+    if (mine !== run) return;
+    if (name.value === "") name.value = get(slug)?.name ?? "";
+    await Promise.all([fetchDetail(slug), refreshCredentials(), loadSecrets()]);
+    if (mine !== run) return;
+    answer = await checkRequirements(slug);
+  } catch (e) {
+    failure = uncheckedReason(e);
+  }
   if (mine !== run) return;
   reqs.value = answer;
+  reqsError.value = failure;
   loading.value = false;
 }, { immediate: true });
 watch(loading, (v) => emit("update:loading", v), { immediate: true });
 watch(installing, (v) => emit("update:installing", v));
 onBeforeUnmount(() => emit("update:loading", false));
-const tpl = computed(() => get(props.slug));
 const credentialReqs = computed(() => reqs.value?.credentialTypes ?? []);
 const secretReqs = computed(() => reqs.value?.secrets ?? []);
-const secretChecks = computed(() => {
-  const fromApi = secretReqs.value;
-  if (fromApi.length) {
-    return fromApi.map((s) => ({
-      key: s.key,
-      label: s.key ?? t("integration.templates.detail.secrets.chosenAtInstall"),
-      present: s.exists || (s.key ? secretKeys.value.includes(s.key) : false)
-    }));
-  }
-  return (tpl.value?.requiredSecrets ?? []).map((key) => ({
-    key,
-    label: key,
-    present: secretKeys.value.includes(key)
-  }));
-});
+const secretChecks = computed(() => secretReqs.value.map((s) => ({
+  key: s.key,
+  label: s.key ?? t("integration.templates.detail.secrets.chosenAtInstall"),
+  present: s.exists || (s.key ? secretKeys.value.includes(s.key) : false)
+})));
 function slotsFor(usedBy) {
   const all = credentialReqs.value.flatMap((r) => r.usedBy);
   const seen = /* @__PURE__ */ new Set();
@@ -128,7 +126,13 @@ async function confirmInstall() {
           <div class="text-mono text-muted-foreground border-b border-black/[0.06] pb-1.5">
             {{ t("integration.templates.detail.credentials.title") }}
           </div>
-          <p v-if="!credentialReqs.length" class="text-sm text-muted-foreground italic">
+          <!-- Two lines, not one sentence around {reason}: the platform's message
+               ends in a full stop or not, and a template cannot know which. -->
+          <div v-if="reqsError" class="rounded-md border-l-2 border-amber-500/40 bg-amber-500/5 px-2.5 py-1.5 text-sm text-amber-700" data-testid="template-install-unchecked">
+            <p>{{ t("integration.templates.detail.setup.unchecked", { reason: reqsError }) }}</p>
+            <p>{{ t("integration.templates.detail.install.stillInstallable") }}</p>
+          </div>
+          <p v-else-if="!credentialReqs.length" class="text-sm text-muted-foreground italic">
             {{ t("integration.templates.detail.install.noCredentials") }}
           </p>
           <div v-for="req in credentialReqs" :key="req.slug" class="space-y-2">

package/dist/runtime/components/Integrations/VpnRoutePicker.d.vue.ts

@@ -0,0 +1,20 @@
+import type { VpnRouteKind, VpnRouteValue } from '../../types/integrations.js';
+type __VLS_Props = {
+    modelValue: VpnRouteValue | null;
+    /** The kind of route on offer — the credential type's declared kind, or the setting's `routeKind`. */
+    kind: VpnRouteKind;
+    /** Prefix for the ids of the controls, unique on the page. */
+    idPrefix: string;
+    /** The setting this picker belongs to, prefixed to every control's name; absent in the credential forms. */
+    label?: string;
+    /** Why the last save refused the choice, if it did. */
+    error?: string;
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:complete": (args_0: boolean) => any;
+    "update:modelValue": (args_0: VpnRouteValue | null) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:complete"?: ((args_0: boolean) => any) | undefined;
+    "onUpdate:modelValue"?: ((args_0: VpnRouteValue | null) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;