@cat-factory/app 0.115.3 → 0.116.0

package/app/components/panels/inspector/ServiceTestConfig.vue

@@ -3,11 +3,13 @@ import { computed, onMounted, ref, watch } from 'vue'
 import type {
   Block,
   CloudProvider,
+  EnvironmentTestStage,
   InstanceSize,
   ProvisionType,
   ServiceProvisioning,
 } from '~/types/domain'
 import type {
+  ConflictReason,
   KubernetesManifestSource,
   KubernetesRenderer,
   ProvisioningComposeServiceCandidate,
@@ -19,6 +21,7 @@ import type {
 import RepoTreeBrowser from '~/components/github/RepoTreeBrowser.vue'
 import InspectorSection from '~/components/panels/inspector/InspectorSection.vue'
 import { apiErrorEnvelope } from '~/composables/api/errors'
+import { parseConflict } from '~/composables/usePipelineErrorToast'
 
 // Service-level (frame) configuration: the service-owned PROVISIONING — the provision
 // TYPE this service produces (`infraless` / `docker-compose` / `kubernetes` / `custom`)
@@ -44,7 +47,7 @@ const services = useServicesStore()
 const infra = useInfraConfigStore()
 const agentRuns = useAgentRunsStore()
 const ui = useUiStore()
-const { t } = useI18n()
+const { t, te } = useI18n()
 
 // The custom-manifest-type catalog feeds the `custom` picker. Cheap + shared (coalesced).
 // The repo list backs the detect-from-repo affordance (owner/name lookup).
@@ -247,6 +250,80 @@ async function generateOrFixManifest() {
   }
 }
 
+// Ephemeral-environment self-test: run the whole create-branch → provision → tear-down →
+// delete-branch cycle against this service's provisioning config and report success / the stage
+// it failed at. The returned run is tracked live (by frame id) via the workspace stream store.
+const envTest = useEnvironmentTestStore()
+const envTestStarting = ref(false)
+const envTestError = ref<string | null>(null)
+// The newest self-test run for this frame — re-attaches after a reconnect (the run is carried in
+// the snapshot while running), so the live stage keeps showing without a locally-held id.
+const envTestRun = computed(() => envTest.runForBlock(props.block.id))
+const envTestRunning = computed(() => envTestRun.value?.status === 'running')
+// Nothing to provision for an `infraless` service, so there is nothing to test.
+const canTestEnv = computed(() => provisionType.value !== 'infraless')
+
+// Per-stage label KEYS, exhaustive over the contracts `EnvironmentTestStage` union: a new
+// backend stage fails THIS typecheck until mapped (the key is resolved at runtime, so the
+// typed-message-keys check can't see the `t()` lookup — the map's exhaustiveness is the
+// drift guard, same pattern as `CONFLICT_TITLE_KEYS`).
+const ENV_TEST_STAGE_KEYS: Record<EnvironmentTestStage, string> = {
+  creating_branch: 'inspector.testConfig.envTest.stage.creating_branch',
+  provisioning: 'inspector.testConfig.envTest.stage.provisioning',
+  tearing_down: 'inspector.testConfig.envTest.stage.tearing_down',
+  deleting_branch: 'inspector.testConfig.envTest.stage.deleting_branch',
+  done: 'inspector.testConfig.envTest.stage.done',
+}
+
+function envTestStageLabel(stage: EnvironmentTestStage): string {
+  const key = ENV_TEST_STAGE_KEYS[stage]
+  // `te`-guarded so a locale missing the key shows the raw stage id, never a raw message key.
+  return te(key) ? t(key) : stage
+}
+
+// The start preflight's machine-readable 409 reasons, mapped to their localized titles —
+// exhaustive over the contracts `env_test_*` conflict reasons (same drift guard as above).
+// The raw backend `message` is only the last-resort fallback for unmapped/non-conflict errors.
+const ENV_TEST_CONFLICT_KEYS: Record<Extract<ConflictReason, `env_test_${string}`>, string> = {
+  env_test_not_a_frame: 'errors.conflict.title.env_test_not_a_frame',
+  env_test_infraless: 'errors.conflict.title.env_test_infraless',
+  env_test_not_provisionable: 'errors.conflict.title.env_test_not_provisionable',
+  env_test_no_vcs: 'errors.conflict.title.env_test_no_vcs',
+}
+
+function envTestErrorText(e: unknown): string {
+  const reason = parseConflict(e)?.reason
+  const key =
+    reason && reason in ENV_TEST_CONFLICT_KEYS
+      ? ENV_TEST_CONFLICT_KEYS[reason as keyof typeof ENV_TEST_CONFLICT_KEYS]
+      : undefined
+  if (key && te(key)) return t(key)
+  return apiErrorEnvelope(e)?.message ?? (e instanceof Error ? e.message : String(e))
+}
+
+async function startEnvTest() {
+  if (!canTestEnv.value || envTestStarting.value || envTestRunning.value) return
+  envTestStarting.value = true
+  envTestError.value = null
+  try {
+    await envTest.start(props.block.id)
+  } catch (e) {
+    envTestError.value = envTestErrorText(e)
+  } finally {
+    envTestStarting.value = false
+  }
+}
+
+async function stopEnvTest() {
+  const run = envTestRun.value
+  if (!run || run.status !== 'running') return
+  try {
+    await envTest.stop(run.id)
+  } catch (e) {
+    envTestError.value = envTestErrorText(e)
+  }
+}
+
 // The provisioning hints (cloud provider + instance size) are advisory inputs to the
 // ephemeral-environment provisioner, not commonly tuned — keep them collapsed by default.
 const showProvisioning = ref(false)
@@ -923,5 +1000,80 @@ function setSize(value: InstanceSize) {
         </div>
       </div>
     </InspectorSection>
+
+    <!-- Ephemeral-environment self-test: exercise the whole provisioning lifecycle against a
+         throwaway branch and report success / the failing stage. Disabled for `infraless`. -->
+    <div class="mt-3 space-y-2 border-t border-white/5 pt-3" data-testid="env-test-section">
+      <div class="flex items-center justify-between gap-2">
+        <div class="min-w-0">
+          <p class="text-[11px] font-medium text-slate-300">
+            {{ t('inspector.testConfig.envTest.title') }}
+          </p>
+          <p class="text-[11px] text-slate-400">{{ t('inspector.testConfig.envTest.hint') }}</p>
+        </div>
+        <UButton
+          v-if="!envTestRunning"
+          icon="i-lucide-flask-conical"
+          size="xs"
+          color="primary"
+          variant="soft"
+          data-testid="env-test-start"
+          :loading="envTestStarting"
+          :disabled="!canTestEnv"
+          @click="startEnvTest"
+        >
+          {{ t('inspector.testConfig.envTest.start') }}
+        </UButton>
+        <UButton
+          v-else
+          icon="i-lucide-square"
+          size="xs"
+          color="neutral"
+          variant="ghost"
+          data-testid="env-test-stop"
+          @click="stopEnvTest"
+        >
+          {{ t('inspector.testConfig.envTest.stop') }}
+        </UButton>
+      </div>
+
+      <p v-if="!canTestEnv" class="text-[11px] text-slate-500">
+        {{ t('inspector.testConfig.envTest.infraless') }}
+      </p>
+
+      <!-- Live stage + terminal outcome of the tracked run (pushed via the workspace stream). -->
+      <p
+        v-if="envTestRun"
+        class="text-[11px]"
+        :class="{
+          'text-sky-300/80': envTestRun.status === 'running',
+          'text-emerald-300/80': envTestRun.status === 'succeeded',
+          'text-rose-300/80': envTestRun.status === 'failed',
+        }"
+        data-testid="env-test-status"
+      >
+        <template v-if="envTestRun.status === 'running'">
+          {{
+            t('inspector.testConfig.envTest.running', {
+              stage: envTestStageLabel(envTestRun.stage),
+            })
+          }}
+        </template>
+        <template v-else-if="envTestRun.status === 'succeeded'">
+          {{ t('inspector.testConfig.envTest.succeeded') }}
+        </template>
+        <template v-else>
+          {{ t('inspector.testConfig.envTest.failed') }}
+          <template v-if="envTestRun.failedStage">
+            ({{ envTestStageLabel(envTestRun.failedStage) }})
+          </template>
+          <span v-if="envTestRun.error" class="block text-rose-300/70">{{ envTestRun.error }}</span>
+        </template>
+      </p>
+
+      <p v-if="envTestError" class="text-[11px] text-rose-400" data-testid="env-test-error">
+        {{ envTestError }}
+      </p>
+    </div>
   </InspectorSection>
 </template>

package/app/composables/api/environments.ts

@@ -1,4 +1,10 @@
-import { listEnvironmentsContract, provisionEnvironmentContract } from '@cat-factory/contracts'
+import {
+  getEnvironmentTestContract,
+  listEnvironmentsContract,
+  provisionEnvironmentContract,
+  startEnvironmentTestContract,
+  stopEnvironmentTestContract,
+} from '@cat-factory/contracts'
 import type { ProvisionEnvironmentInput } from '@cat-factory/contracts'
 import type { ApiContext } from './context'
 
@@ -12,5 +18,14 @@ export function environmentsApi({ send, ws }: ApiContext) {
     // wizard's "trial provision" against the just-saved config. Returns the resulting handle.
     provisionEnvironment: (workspaceId: string, body: ProvisionEnvironmentInput) =>
       send(provisionEnvironmentContract, { pathPrefix: ws(workspaceId), body }),
+
+    // Ephemeral-environment self-test: start a full create-branch → provision → tear-down →
+    // delete-branch cycle against a service frame, then read / stop its run.
+    startEnvironmentTest: (workspaceId: string, blockId: string) =>
+      send(startEnvironmentTestContract, { pathPrefix: ws(workspaceId), pathParams: { blockId } }),
+    getEnvironmentTest: (workspaceId: string, id: string) =>
+      send(getEnvironmentTestContract, { pathPrefix: ws(workspaceId), pathParams: { id } }),
+    stopEnvironmentTest: (workspaceId: string, id: string) =>
+      send(stopEnvironmentTestContract, { pathPrefix: ws(workspaceId), pathParams: { id } }),
   }
 }

package/app/composables/usePipelineErrorToast.ts

@@ -55,6 +55,10 @@ const CONFLICT_TITLE_KEYS: Record<Exclude<ConflictReason, BespokeConflictReason>
   model_policy_blocked: 'errors.conflict.title.model_policy_blocked',
   model_policy_unsupported: 'errors.conflict.title.model_policy_unsupported',
   deployer_required_before_tester: 'errors.conflict.title.deployer_required_before_tester',
+  env_test_not_a_frame: 'errors.conflict.title.env_test_not_a_frame',
+  env_test_infraless: 'errors.conflict.title.env_test_infraless',
+  env_test_not_provisionable: 'errors.conflict.title.env_test_not_provisionable',
+  env_test_no_vcs: 'errors.conflict.title.env_test_no_vcs',
 }
 
 /**

package/app/composables/useWorkspaceStream.ts

@@ -18,6 +18,7 @@ export function useWorkspaceStream() {
   const execution = useExecutionStore()
   const board = useBoardStore()
   const agentRuns = useAgentRunsStore()
+  const environmentTest = useEnvironmentTestStore()
   const notifications = useNotificationsStore()
   const observability = useObservabilityStore()
   const requirements = useRequirementsStore()
@@ -102,6 +103,11 @@ export function useWorkspaceStream() {
       // the infrastructure-providers window's "repairing…" indicator updates in place
       // (then flips to ok / residual issues / a failure) without a refetch. No board block.
       agentRuns.upsertEnvConfigRepair(event.job)
+    } else if (event.type === 'envTest') {
+      // An ephemeral-environment self-test advanced a stage — patch the run so the service
+      // inspector's "Test environment creation" control shows the live stage + final
+      // outcome in place without a refetch. No board block.
+      environmentTest.upsert(event.run)
     } else if (event.type === 'notification') {
       // A PR needs a merge decision, a pipeline finished, or CI gave up — patch the
       // inbox + per-block badge in place (resolved ones drop out of the inbox).

package/app/stores/environmentTest.spec.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import type { EnvironmentTestRun } from '~/types/domain'
+import { useEnvironmentTestStore } from '~/stores/environmentTest'
+
+// The store resolves `useApi()` at setup; override the inert global stub from
+// `test/setup.ts` with a per-suite mock so the hydrate reconcile point-read is observable.
+const apiMock = { getEnvironmentTest: vi.fn() }
+vi.stubGlobal('useApi', () => apiMock)
+
+/** Minimal EnvironmentTestRun factory — only the fields the store's reconcile logic touches. */
+function run(id: string, over: Partial<EnvironmentTestRun> = {}): EnvironmentTestRun {
+  return {
+    id,
+    workspaceId: 'ws_test',
+    blockId: `blk_${id}`,
+    status: 'running',
+    stage: 'provisioning',
+    branch: null,
+    envUrl: null,
+    error: null,
+    failedStage: null,
+    createdAt: 1,
+    updatedAt: 1,
+    ...over,
+  }
+}
+
+describe('environmentTest store — monotonic run reconcile', () => {
+  let store: ReturnType<typeof useEnvironmentTestStore>
+  beforeEach(() => {
+    apiMock.getEnvironmentTest = vi.fn(async () => {
+      throw new Error('not stubbed')
+    })
+    store = useEnvironmentTestStore()
+  })
+
+  it('hydrate does NOT regress a run a newer live event already advanced', () => {
+    // A live `envTest: failed` event landed first (newer updatedAt).
+    store.upsert(run('r1', { status: 'failed', failedStage: 'provisioning', updatedAt: 5 }))
+    // A lagging `workspace.refresh()` then hydrates a STALE snapshot that still saw the run
+    // as `running` (older updatedAt) — it must NOT clobber the terminal state (terminal runs
+    // emit nothing further, so the inspector would be stuck on "testing" forever).
+    store.hydrate([run('r1', { status: 'running', updatedAt: 2 })], 'ws_test')
+    expect(store.runForBlock('blk_r1')!.status).toBe('failed')
+  })
+
+  it('hydrate does NOT drop a live-added run the stale snapshot never saw', () => {
+    // Terminal runs are omitted from the snapshot BY DESIGN, so a just-finished run the
+    // inspector still shows must survive a full refresh.
+    store.upsert(run('r1', { status: 'succeeded', stage: 'done', updatedAt: 5 }))
+    store.hydrate([], 'ws_test')
+    expect(store.runForBlock('blk_r1')!.status).toBe('succeeded')
+  })
+
+  it('hydrate point-reads a preserved RUNNING run the snapshot omitted (finished offline)', async () => {
+    // The run was still `running` when the socket dropped; it finished while disconnected, so
+    // the reconnect snapshot no longer carries it and no event replays — the hydrate must
+    // re-read it to pick up the outcome instead of stranding a stale "testing" state.
+    store.upsert(run('r1', { status: 'running', updatedAt: 5 }))
+    apiMock.getEnvironmentTest = vi.fn(async () =>
+      run('r1', { status: 'succeeded', stage: 'done', updatedAt: 9 }),
+    )
+    store.hydrate([], 'ws_test')
+    expect(apiMock.getEnvironmentTest).toHaveBeenCalledWith('ws_test', 'r1')
+    await vi.waitFor(() => expect(store.runForBlock('blk_r1')!.status).toBe('succeeded'))
+  })
+
+  it('a STALE point-read cannot regress a run a live event advanced meanwhile', async () => {
+    store.upsert(run('r1', { status: 'running', updatedAt: 5 }))
+    // The reconcile read resolves with an OLDER view of the run than the live event that
+    // lands while it is in flight — the monotonic upsert must keep the newer state.
+    apiMock.getEnvironmentTest = vi.fn(async () => run('r1', { status: 'running', updatedAt: 4 }))
+    store.hydrate([], 'ws_test')
+    store.upsert(run('r1', { status: 'failed', failedStage: 'tearing_down', updatedAt: 8 }))
+    await vi.waitFor(() => expect(apiMock.getEnvironmentTest).toHaveBeenCalled())
+    await Promise.resolve()
+    expect(store.runForBlock('blk_r1')!.status).toBe('failed')
+  })
+
+  it('hydrate DROPS a cached run from a different workspace (board switch starts clean)', () => {
+    store.upsert(run('r1', { status: 'failed', updatedAt: 5, workspaceId: 'ws_other' }))
+    store.hydrate([run('r2', { workspaceId: 'ws_test' })], 'ws_test')
+    expect(store.runs.map((r) => r.id)).toEqual(['r2'])
+  })
+
+  it('hydrate DOES apply a genuinely newer snapshot', () => {
+    store.upsert(run('r1', { status: 'running', updatedAt: 2 }))
+    store.hydrate(
+      [run('r1', { status: 'running', stage: 'tearing_down', updatedAt: 9 })],
+      'ws_test',
+    )
+    expect(store.runForBlock('blk_r1')!.stage).toBe('tearing_down')
+  })
+
+  it('upsert ignores an older/out-of-order write but applies newer/equal', () => {
+    store.upsert(run('r1', { status: 'failed', updatedAt: 5 }))
+    // e.g. a `start()` response resolving AFTER the fast-failing run's terminal event landed.
+    store.upsert(run('r1', { status: 'running', stage: 'creating_branch', updatedAt: 3 }))
+    expect(store.runForBlock('blk_r1')!.status).toBe('failed')
+    store.upsert(run('r1', { status: 'succeeded', stage: 'done', updatedAt: 5 }))
+    expect(store.runForBlock('blk_r1')!.status).toBe('succeeded')
+  })
+})

package/app/stores/environmentTest.ts

@@ -0,0 +1,114 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type { EnvironmentTestRun } from '~/types/domain'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * Ephemeral-environment self-test runs. A developer starts one from a service frame's inspector
+ * (`POST …/blocks/:id/environment-test`); the backend drives the create-branch → provision →
+ * tear-down → delete-branch cycle durably and pushes live `envTest` stage events, which
+ * `useWorkspaceStream` folds in via {@link upsert}. In-flight runs also arrive in the workspace
+ * snapshot ({@link hydrate}) so the inspector re-attaches to a running test after a reconnect.
+ *
+ * Runs are keyed by their FRAME block id for the inspector's per-service lookup ({@link runForBlock}
+ * returns the newest run for a block). Terminal runs are kept in memory for the session so the
+ * inspector can show the last outcome; the snapshot only carries running ones.
+ */
+export const useEnvironmentTestStore = defineStore('environmentTest', () => {
+  const api = useApi()
+
+  /** All known runs (running + this session's terminal ones), newest first. */
+  const runs = ref<EnvironmentTestRun[]>([])
+
+  function sortByCreated(list: EnvironmentTestRun[]): EnvironmentTestRun[] {
+    return [...list].sort((a, b) => b.createdAt - a.createdAt)
+  }
+
+  /**
+   * Reconcile the cached runs with a server snapshot for `workspaceId`. A snapshot is
+   * authoritative EXCEPT where a live `envTest` event has already advanced (or ADDED) a run
+   * past what this (possibly stale) read observed — a `board`-event refresh or the on-connect
+   * resync can resolve AFTER a newer event already landed. Same two clobber hazards as
+   * `agentRuns.hydrate`, both handled here:
+   *   - REGRESS: a run present in BOTH the snapshot and the cache — keep the newer-by-`updatedAt`
+   *     version, so a lagging refresh can't revert a `failed`/`succeeded` run to `running`
+   *     (terminal runs emit nothing further, so the inspector would be stuck on "testing").
+   *   - DROP: a run a live event just ADDED that the (older) snapshot never saw — replacing from
+   *     the snapshot alone would silently drop it (and terminal runs are omitted from the
+   *     snapshot by design, so a finished run the inspector still shows would vanish).
+   *     Preserve such cached runs, scoped to `workspaceId` so a board SWITCH still starts clean.
+   *
+   * A preserved RUNNING run absent from the snapshot may also have reached terminal while the
+   * socket was down (no event replays, and the snapshot omits terminal runs) — point-read it
+   * best-effort to pick up the outcome; {@link upsert}'s monotonic guard makes the read safe
+   * against racing live events.
+   */
+  function hydrate(snapshotRuns: EnvironmentTestRun[], workspaceId: string) {
+    const incomingIds = new Set(snapshotRuns.map((r) => r.id))
+    const held = new Map(runs.value.map((r) => [r.id, r]))
+    const reconciled = snapshotRuns.map((incoming) => {
+      const current = held.get(incoming.id)
+      return current && current.updatedAt > incoming.updatedAt ? current : incoming
+    })
+    const preserved = [...held.values()].filter(
+      (r) => !incomingIds.has(r.id) && r.workspaceId === workspaceId,
+    )
+    runs.value = sortByCreated([...reconciled, ...preserved])
+    // A still-`running` preserved run wasn't in the snapshot, so either the snapshot is stale
+    // (the run is genuinely newer) or the run FINISHED while we were disconnected — resolve
+    // which by re-reading it (non-blocking; failures leave the cached state as-is).
+    for (const r of preserved) {
+      if (r.status === 'running') void reconcileRun(workspaceId, r.id)
+    }
+  }
+
+  /** Best-effort point-read of one run, folded in through the monotonic {@link upsert}. */
+  async function reconcileRun(workspaceId: string, id: string) {
+    try {
+      upsert(await api.getEnvironmentTest(workspaceId, id))
+    } catch {
+      // Best-effort: a transient fetch failure just leaves the cached state; the next
+      // snapshot/event reconciles it.
+    }
+  }
+
+  /**
+   * Fold a live-pushed (or freshly-started/stopped) run into the cache. Monotonic by
+   * `updatedAt`: never let a stale/out-of-order write regress a run a newer one already
+   * advanced — e.g. a `start()` response resolving AFTER a fast-failing run's terminal
+   * event already landed (same guard as {@link hydrate}).
+   */
+  function upsert(run: EnvironmentTestRun) {
+    const i = runs.value.findIndex((r) => r.id === run.id)
+    if (i >= 0) {
+      if (run.updatedAt >= runs.value[i]!.updatedAt) runs.value[i] = run
+    } else runs.value.unshift(run)
+  }
+
+  function runById(id: string): EnvironmentTestRun | undefined {
+    return runs.value.find((r) => r.id === id)
+  }
+
+  /** The newest run for a service frame — the inspector's per-service attach point. */
+  function runForBlock(blockId: string): EnvironmentTestRun | undefined {
+    return runs.value.find((r) => r.blockId === blockId)
+  }
+
+  /** Start a self-test against a service frame; the returned run is tracked immediately. */
+  async function start(blockId: string): Promise<EnvironmentTestRun> {
+    const ws = useWorkspaceStore()
+    const run = await api.startEnvironmentTest(ws.requireId(), blockId)
+    upsert(run)
+    return run
+  }
+
+  /** Stop a running self-test (best-effort cleanup, then failed). */
+  async function stop(id: string): Promise<EnvironmentTestRun> {
+    const ws = useWorkspaceStore()
+    const run = await api.stopEnvironmentTest(ws.requireId(), id)
+    upsert(run)
+    return run
+  }
+
+  return { runs, hydrate, upsert, runById, runForBlock, start, stop }
+})

package/app/stores/workspace.spec.ts

@@ -15,6 +15,7 @@ const INERT_STORES = [
   'useClarityStore',
   'useConsensusStore',
   'useDocInterviewStore',
+  'useEnvironmentTestStore',
   'useExecutionStore',
   'useFragmentsStore',
   'useGitHubStore',

package/app/stores/workspace.ts

@@ -12,6 +12,7 @@ import { useBoardStore } from '~/stores/board'
 import { usePipelinesStore } from '~/stores/pipelines'
 import { useExecutionStore } from '~/stores/execution'
 import { useAgentRunsStore } from '~/stores/agentRuns'
+import { useEnvironmentTestStore } from '~/stores/environmentTest'
 import { useNotificationsStore } from '~/stores/notifications'
 import { useRiskPoliciesStore } from '~/stores/riskPolicies'
 import { useSharedStacksStore } from '~/stores/sharedStacks'
@@ -120,6 +121,7 @@ export const useWorkspaceStore = defineStore(
       useExecutionStore().hydrate(snapshot.executions, snapshot.workspace.id)
       useAgentRunsStore().hydrate(snapshot.bootstrapJobs ?? [], snapshot.workspace.id)
       useAgentRunsStore().hydrateEnvConfigRepair(snapshot.envConfigRepairJobs ?? [])
+      useEnvironmentTestStore().hydrate(snapshot.environmentTestRuns ?? [], snapshot.workspace.id)
       useNotificationsStore().hydrate(snapshot.notifications ?? [])
       useRiskPoliciesStore().hydrate(
         snapshot.riskPolicies ?? [],

package/app/types/domain.ts

@@ -39,6 +39,9 @@ export type {
   FrontendBackendSource,
   ResolvedFrontendBinding,
   EnvironmentHandle,
+  EnvironmentTestRun,
+  EnvironmentTestStage,
+  EnvironmentTestStatus,
   ServiceConnection,
   FrontendBranch,
   FrontendPackageManager,

package/i18n/locales/de.json

@@ -1093,6 +1093,23 @@
         "title": "Einrichtung der Compose-Umgebung",
         "hint": "Konfiguriere das Rezept, die Preflights und den Handler, damit der Deployer diesen Stack bereitstellt.",
         "open": "Assistent öffnen"
+      },
+      "envTest": {
+        "title": "Umgebungserstellung testen",
+        "hint": "Führt den gesamten Lebenszyklus gegen einen Wegwerf-Branch aus: Branch erstellen, bereitstellen, abbauen, Branch löschen.",
+        "start": "Umgebungserstellung testen",
+        "stop": "Stopp",
+        "infraless": "Konfiguriere oben einen Bereitstellungstyp, um die Umgebungserstellung zu testen.",
+        "running": "Wird getestet: {stage}",
+        "succeeded": "Test bestanden: Die Umgebung wurde erstellt und abgebaut, und der Branch wurde gelöscht.",
+        "failed": "Test fehlgeschlagen",
+        "stage": {
+          "creating_branch": "Branch wird erstellt",
+          "provisioning": "Umgebung wird bereitgestellt",
+          "tearing_down": "Umgebung wird abgebaut",
+          "deleting_branch": "Branch wird gelöscht",
+          "done": "fertig"
+        }
       }
     },
     "agentConfig": {
@@ -3786,7 +3803,11 @@
         "visual_pipeline_no_frontend": "Kein Frontend zum Testen",
         "model_policy_blocked": "Modell durch Kontorichtlinie blockiert",
         "model_policy_unsupported": "Modellrichtlinie hier nicht verfügbar",
-        "deployer_required_before_tester": "Füge einen Deployer vor dem Tester hinzu"
+        "deployer_required_before_tester": "Füge einen Deployer vor dem Tester hinzu",
+        "env_test_not_a_frame": "Kein Dienst",
+        "env_test_infraless": "Nichts zu testen",
+        "env_test_not_provisionable": "Umgebungs-Handler nicht konfiguriert",
+        "env_test_no_vcs": "Git-Anbieter nicht verbunden"
       },
       "fallbackMessage": "Diese Aktion steht im Konflikt mit dem aktuellen Zustand.",
       "providersUnconfigured": {

package/i18n/locales/en.json

@@ -475,7 +475,11 @@
         "visual_pipeline_no_frontend": "No frontend to test",
         "model_policy_blocked": "Model blocked by account policy",
         "model_policy_unsupported": "Model policy not available here",
-        "deployer_required_before_tester": "Add a Deployer before the Tester"
+        "deployer_required_before_tester": "Add a Deployer before the Tester",
+        "env_test_not_a_frame": "Not a service",
+        "env_test_infraless": "Nothing to test",
+        "env_test_not_provisionable": "Environment handler not configured",
+        "env_test_no_vcs": "Git provider not connected"
       },
       "fallbackMessage": "This action conflicts with the current state.",
       "providersUnconfigured": {
@@ -837,6 +841,23 @@
         "title": "Compose environment setup",
         "hint": "Configure the recipe, preflights, and handler so the Deployer provisions this stack.",
         "open": "Open wizard"
+      },
+      "envTest": {
+        "title": "Test environment creation",
+        "hint": "Runs the whole lifecycle against a throwaway branch: create branch, provision, tear down, delete branch.",
+        "start": "Test environment creation",
+        "stop": "Stop",
+        "infraless": "Configure a provision type above to test environment creation.",
+        "running": "Testing: {stage}",
+        "succeeded": "Test passed: the environment was created and torn down, and the branch was deleted.",
+        "failed": "Test failed",
+        "stage": {
+          "creating_branch": "creating branch",
+          "provisioning": "provisioning environment",
+          "tearing_down": "tearing down environment",
+          "deleting_branch": "deleting branch",
+          "done": "done"
+        }
       }
     },
     "agentConfig": {

package/i18n/locales/es.json

@@ -436,7 +436,11 @@
         "visual_pipeline_no_frontend": "No hay frontend que probar",
         "model_policy_blocked": "Modelo bloqueado por la política de la cuenta",
         "model_policy_unsupported": "La política de modelos no está disponible aquí",
-        "deployer_required_before_tester": "Añade un Deployer antes del Tester"
+        "deployer_required_before_tester": "Añade un Deployer antes del Tester",
+        "env_test_not_a_frame": "No es un servicio",
+        "env_test_infraless": "Nada que probar",
+        "env_test_not_provisionable": "Gestor de entorno no configurado",
+        "env_test_no_vcs": "Proveedor de Git no conectado"
       },
       "fallbackMessage": "Esta acción entra en conflicto con el estado actual.",
       "providersUnconfigured": {
@@ -783,6 +787,23 @@
         "title": "Configuración de entorno Compose",
         "hint": "Configura la receta, las comprobaciones previas y el gestor para que el Deployer aprovisione este stack.",
         "open": "Abrir asistente"
+      },
+      "envTest": {
+        "title": "Probar la creación del entorno",
+        "hint": "Ejecuta todo el ciclo de vida sobre una rama desechable: crear rama, aprovisionar, desmontar, eliminar rama.",
+        "start": "Probar la creación del entorno",
+        "stop": "Detener",
+        "infraless": "Configura arriba un tipo de aprovisionamiento para probar la creación del entorno.",
+        "running": "Probando: {stage}",
+        "succeeded": "Prueba superada: el entorno se creó y se desmontó, y la rama se eliminó.",
+        "failed": "La prueba falló",
+        "stage": {
+          "creating_branch": "creando rama",
+          "provisioning": "aprovisionando entorno",
+          "tearing_down": "desmontando entorno",
+          "deleting_branch": "eliminando rama",
+          "done": "listo"
+        }
       }
     },
     "agentConfig": {

package/i18n/locales/fr.json

@@ -436,7 +436,11 @@
         "visual_pipeline_no_frontend": "Aucun frontend à tester",
         "model_policy_blocked": "Modèle bloqué par la politique du compte",
         "model_policy_unsupported": "La politique de modèles n'est pas disponible ici",
-        "deployer_required_before_tester": "Ajoutez un Deployer avant le Testeur"
+        "deployer_required_before_tester": "Ajoutez un Deployer avant le Testeur",
+        "env_test_not_a_frame": "Pas un service",
+        "env_test_infraless": "Rien à tester",
+        "env_test_not_provisionable": "Gestionnaire d'environnement non configuré",
+        "env_test_no_vcs": "Fournisseur Git non connecté"
       },
       "fallbackMessage": "Cette action est en conflit avec l’état actuel.",
       "providersUnconfigured": {
@@ -783,6 +787,23 @@
         "title": "Configuration d'environnement Compose",
         "hint": "Configurez la recette, les vérifications préalables et le gestionnaire pour que le Deployer provisionne cette stack.",
         "open": "Ouvrir l'assistant"
+      },
+      "envTest": {
+        "title": "Tester la création de l'environnement",
+        "hint": "Exécute tout le cycle de vie sur une branche jetable : créer la branche, provisionner, démonter, supprimer la branche.",
+        "start": "Tester la création de l'environnement",
+        "stop": "Arrêter",
+        "infraless": "Configurez un type de provisionnement ci-dessus pour tester la création de l'environnement.",
+        "running": "Test en cours : {stage}",
+        "succeeded": "Test réussi : l'environnement a été créé puis démonté, et la branche a été supprimée.",
+        "failed": "Échec du test",
+        "stage": {
+          "creating_branch": "création de la branche",
+          "provisioning": "provisionnement de l'environnement",
+          "tearing_down": "démontage de l'environnement",
+          "deleting_branch": "suppression de la branche",
+          "done": "terminé"
+        }
       }
     },
     "agentConfig": {

package/i18n/locales/he.json

@@ -436,7 +436,11 @@
         "visual_pipeline_no_frontend": "אין frontend לבדיקה",
         "model_policy_blocked": "המודל נחסם על ידי מדיניות החשבון",
         "model_policy_unsupported": "מדיניות המודלים אינה זמינה כאן",
-        "deployer_required_before_tester": "הוסף Deployer לפני ה-Tester"
+        "deployer_required_before_tester": "הוסף Deployer לפני ה-Tester",
+        "env_test_not_a_frame": "לא שירות",
+        "env_test_infraless": "אין מה לבדוק",
+        "env_test_not_provisionable": "מטפל הסביבה אינו מוגדר",
+        "env_test_no_vcs": "ספק Git אינו מחובר"
       },
       "fallbackMessage": "פעולה זו מתנגשת עם המצב הנוכחי.",
       "providersUnconfigured": {
@@ -783,6 +787,23 @@
         "title": "הגדרת סביבת Compose",
         "hint": "הגדירו את המתכון, בדיקות המוכנות והמטפל כדי שה-Deployer יקצה את הסטאק הזה.",
         "open": "פתיחת אשף"
+      },
+      "envTest": {
+        "title": "בדיקת יצירת סביבה",
+        "hint": "מריץ את כל מחזור החיים על ענף חד-פעמי: יצירת ענף, הקצאה, פירוק ומחיקת הענף.",
+        "start": "בדיקת יצירת סביבה",
+        "stop": "עצירה",
+        "infraless": "הגדירו סוג הקצאה למעלה כדי לבדוק את יצירת הסביבה.",
+        "running": "בבדיקה: {stage}",
+        "succeeded": "הבדיקה עברה: הסביבה נוצרה ופורקה, והענף נמחק.",
+        "failed": "הבדיקה נכשלה",
+        "stage": {
+          "creating_branch": "יוצר ענף",
+          "provisioning": "מקצה סביבה",
+          "tearing_down": "מפרק סביבה",
+          "deleting_branch": "מוחק ענף",
+          "done": "הושלם"
+        }
       }
     },
     "agentConfig": {

package/i18n/locales/it.json

@@ -1093,6 +1093,23 @@
         "title": "Configurazione ambiente Compose",
         "hint": "Configura la ricetta, i preflight e l'handler affinche' il Deployer provisioni questo stack.",
         "open": "Apri la procedura guidata"
+      },
+      "envTest": {
+        "title": "Prova la creazione dell'ambiente",
+        "hint": "Esegue l'intero ciclo di vita su un branch usa e getta: crea branch, provisiona, smonta, elimina branch.",
+        "start": "Prova la creazione dell'ambiente",
+        "stop": "Ferma",
+        "infraless": "Configura sopra un tipo di provisioning per provare la creazione dell'ambiente.",
+        "running": "Prova in corso: {stage}",
+        "succeeded": "Prova superata: l'ambiente è stato creato e smontato, e il branch è stato eliminato.",
+        "failed": "Prova fallita",
+        "stage": {
+          "creating_branch": "creazione del branch",
+          "provisioning": "provisioning dell'ambiente",
+          "tearing_down": "smontaggio dell'ambiente",
+          "deleting_branch": "eliminazione del branch",
+          "done": "completato"
+        }
       }
     },
     "agentConfig": {
@@ -3786,7 +3803,11 @@
         "visual_pipeline_no_frontend": "Nessun frontend da testare",
         "model_policy_blocked": "Modello bloccato dalla policy dell'account",
         "model_policy_unsupported": "Policy dei modelli non disponibile qui",
-        "deployer_required_before_tester": "Aggiungi un Deployer prima del Tester"
+        "deployer_required_before_tester": "Aggiungi un Deployer prima del Tester",
+        "env_test_not_a_frame": "Non è un servizio",
+        "env_test_infraless": "Niente da testare",
+        "env_test_not_provisionable": "Handler dell'ambiente non configurato",
+        "env_test_no_vcs": "Provider Git non connesso"
       },
       "fallbackMessage": "Questa azione è in conflitto con lo stato attuale.",
       "providersUnconfigured": {

package/i18n/locales/ja.json

@@ -436,7 +436,11 @@
         "visual_pipeline_no_frontend": "テスト対象のフロントエンドがありません",
         "model_policy_blocked": "アカウントのポリシーによりモデルがブロックされています",
         "model_policy_unsupported": "モデルポリシーはここでは利用できません",
-        "deployer_required_before_tester": "テスターの前にDeployerを追加してください"
+        "deployer_required_before_tester": "テスターの前にDeployerを追加してください",
+        "env_test_not_a_frame": "サービスではありません",
+        "env_test_infraless": "テストする対象がありません",
+        "env_test_not_provisionable": "環境ハンドラーが設定されていません",
+        "env_test_no_vcs": "Git プロバイダーが未接続です"
       },
       "fallbackMessage": "この操作は現在の状態と競合します。",
       "providersUnconfigured": {
@@ -783,6 +787,23 @@
         "title": "Compose 環境のセットアップ",
         "hint": "レシピ・プリフライト・ハンドラーを設定して、Deployer がこのスタックをプロビジョニングできるようにします。",
         "open": "ウィザードを開く"
+      },
+      "envTest": {
+        "title": "環境作成のテスト",
+        "hint": "使い捨てブランチに対してライフサイクル全体を実行します。ブランチ作成、プロビジョニング、破棄、ブランチ削除の順に行います。",
+        "start": "環境作成のテスト",
+        "stop": "停止",
+        "infraless": "環境作成をテストするには、上でプロビジョニングの種類を設定してください。",
+        "running": "テスト中: {stage}",
+        "succeeded": "テスト成功: 環境が作成されて破棄され、ブランチが削除されました。",
+        "failed": "テスト失敗",
+        "stage": {
+          "creating_branch": "ブランチを作成中",
+          "provisioning": "環境をプロビジョニング中",
+          "tearing_down": "環境を破棄中",
+          "deleting_branch": "ブランチを削除中",
+          "done": "完了"
+        }
       }
     },
     "agentConfig": {

package/i18n/locales/pl.json

@@ -436,7 +436,11 @@
         "visual_pipeline_no_frontend": "Brak frontendu do przetestowania",
         "model_policy_blocked": "Model zablokowany przez politykę konta",
         "model_policy_unsupported": "Polityka modeli jest tu niedostępna",
-        "deployer_required_before_tester": "Dodaj Deployer przed Testerem"
+        "deployer_required_before_tester": "Dodaj Deployer przed Testerem",
+        "env_test_not_a_frame": "To nie usługa",
+        "env_test_infraless": "Nie ma czego testować",
+        "env_test_not_provisionable": "Handler środowiska nie jest skonfigurowany",
+        "env_test_no_vcs": "Dostawca Git nie jest połączony"
       },
       "fallbackMessage": "Ta akcja jest sprzeczna z bieżącym stanem.",
       "providersUnconfigured": {
@@ -783,6 +787,23 @@
         "title": "Konfiguracja środowiska Compose",
         "hint": "Skonfiguruj przepis, kontrole wstępne i handler, aby Deployer udostępnił ten stos.",
         "open": "Otwórz kreatora"
+      },
+      "envTest": {
+        "title": "Testowanie tworzenia środowiska",
+        "hint": "Uruchamia cały cykl życia na jednorazowej gałęzi: utworzenie gałęzi, udostępnienie, usunięcie zasobów, usunięcie gałęzi.",
+        "start": "Testowanie tworzenia środowiska",
+        "stop": "Zatrzymaj",
+        "infraless": "Skonfiguruj powyżej typ udostępniania, aby przetestować tworzenie środowiska.",
+        "running": "Testowanie: {stage}",
+        "succeeded": "Test zaliczony: środowisko zostało utworzone i usunięte, a gałąź została skasowana.",
+        "failed": "Test nie powiódł się",
+        "stage": {
+          "creating_branch": "tworzenie gałęzi",
+          "provisioning": "udostępnianie środowiska",
+          "tearing_down": "usuwanie środowiska",
+          "deleting_branch": "usuwanie gałęzi",
+          "done": "gotowe"
+        }
       }
     },
     "agentConfig": {

package/i18n/locales/tr.json

@@ -436,7 +436,11 @@
         "visual_pipeline_no_frontend": "Test edilecek bir frontend yok",
         "model_policy_blocked": "Model, hesap politikası tarafından engellendi",
         "model_policy_unsupported": "Model politikası burada kullanılamıyor",
-        "deployer_required_before_tester": "Tester’dan önce bir Deployer ekleyin"
+        "deployer_required_before_tester": "Tester’dan önce bir Deployer ekleyin",
+        "env_test_not_a_frame": "Bir hizmet değil",
+        "env_test_infraless": "Test edilecek bir şey yok",
+        "env_test_not_provisionable": "Ortam işleyicisi yapılandırılmamış",
+        "env_test_no_vcs": "Git sağlayıcısı bağlı değil"
       },
       "fallbackMessage": "Bu eylem mevcut durumla çelişiyor.",
       "providersUnconfigured": {
@@ -783,6 +787,23 @@
         "title": "Compose ortam kurulumu",
         "hint": "Tarifi, ön kontrolleri ve işleyiciyi yapılandırın; böylece Deployer bu yığını sağlar.",
         "open": "Sihirbazı aç"
+      },
+      "envTest": {
+        "title": "Ortam oluşturmayı test et",
+        "hint": "Tek kullanımlık bir dal üzerinde tüm yaşam döngüsünü çalıştırır: dal oluştur, sağla, kaldır, dalı sil.",
+        "start": "Ortam oluşturmayı test et",
+        "stop": "Durdur",
+        "infraless": "Ortam oluşturmayı test etmek için yukarıdan bir sağlama türü yapılandırın.",
+        "running": "Test ediliyor: {stage}",
+        "succeeded": "Test başarılı: ortam oluşturuldu ve kaldırıldı, dal silindi.",
+        "failed": "Test başarısız",
+        "stage": {
+          "creating_branch": "dal oluşturuluyor",
+          "provisioning": "ortam sağlanıyor",
+          "tearing_down": "ortam kaldırılıyor",
+          "deleting_branch": "dal siliniyor",
+          "done": "tamamlandı"
+        }
       }
     },
     "agentConfig": {

package/i18n/locales/uk.json

@@ -436,7 +436,11 @@
         "visual_pipeline_no_frontend": "Немає фронтенду для тестування",
         "model_policy_blocked": "Модель заблоковано політикою облікового запису",
         "model_policy_unsupported": "Політика моделей тут недоступна",
-        "deployer_required_before_tester": "Додайте Deployer перед Tester"
+        "deployer_required_before_tester": "Додайте Deployer перед Tester",
+        "env_test_not_a_frame": "Не є сервісом",
+        "env_test_infraless": "Немає чого тестувати",
+        "env_test_not_provisionable": "Обробник середовища не налаштовано",
+        "env_test_no_vcs": "Провайдер Git не підключено"
       },
       "fallbackMessage": "Ця дія суперечить поточному стану.",
       "providersUnconfigured": {
@@ -783,6 +787,23 @@
         "title": "Налаштування середовища Compose",
         "hint": "Налаштуйте рецепт, попередні перевірки та обробник, щоб Deployer забезпечив цей стек.",
         "open": "Відкрити майстер"
+      },
+      "envTest": {
+        "title": "Тестування створення середовища",
+        "hint": "Виконує весь життєвий цикл на одноразовій гілці: створити гілку, забезпечити, згорнути, видалити гілку.",
+        "start": "Тестування створення середовища",
+        "stop": "Зупинити",
+        "infraless": "Налаштуйте тип забезпечення вище, щоб протестувати створення середовища.",
+        "running": "Тестування: {stage}",
+        "succeeded": "Тест пройдено: середовище було створено та згорнуто, а гілку видалено.",
+        "failed": "Тест не пройдено",
+        "stage": {
+          "creating_branch": "створення гілки",
+          "provisioning": "забезпечення середовища",
+          "tearing_down": "згортання середовища",
+          "deleting_branch": "видалення гілки",
+          "done": "готово"
+        }
       }
     },
     "agentConfig": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.115.3",
+  "version": "0.116.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "valibot": "^1.4.2",
     "vue": "3.5.39",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.127.1"
+    "@cat-factory/contracts": "0.128.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",