homeio

1import { beforeEach, describe, expect, it, vi } from "vitest";
2import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
3import os from "node:os";
4import path from "node:path";
5import yaml from "js-yaml";
6
7vi.mock("@/lib/server/modules/store/catalog", () => ({
8  findStoreCatalogTemplateByAppId: vi.fn(),
9}));
10
11vi.mock("@/lib/server/modules/docker/compose-parser", () => ({
12  parseComposeFile: vi.fn(),
13  extractPrimaryServiceWithName: vi.fn(),
14}));
15
16vi.mock("@/lib/server/modules/docker/compose-runner", () => ({
17  cleanupComposeDataOnUninstall: vi.fn(),
18  getComposeRuntimeInfo: vi.fn(),
19  materializeInlineStackFiles: vi.fn(),
20  runComposeDown: vi.fn(),
21  runComposePull: vi.fn(),
22  runComposeRestart: vi.fn(),
23  runComposeStart: vi.fn(),
24  runComposeStop: vi.fn(),
25  runComposeUp: vi.fn(),
26  sanitizeStackName: vi.fn(() => "adguard-home"),
27}));
28
29vi.mock("@/lib/server/modules/store/custom-apps", () => ({
30  findCustomStoreTemplateByAppId: vi.fn(),
31  isCustomStoreTemplate: vi.fn(() => false),
32}));
33
34vi.mock("@/lib/server/modules/store/docker-client", () => ({}));
35
36vi.mock("@/lib/server/modules/apps/service", () => ({
37  invalidateInstalledAppsCache: vi.fn(),
38}));
39
40vi.mock("@/lib/server/modules/apps/stacks-repository", () => ({
41  createStoreOperation: vi.fn(),
42  deleteInstalledStackByAppId: vi.fn(),
43  findInstalledStackByAppId: vi.fn(),
44  findStackByWebUiPort: vi.fn(),
45  findStoreOperationById: vi.fn(),
46  markStaleOperationsAsError: vi.fn().mockResolvedValue(undefined),
47  pruneFinishedOperations: vi.fn().mockResolvedValue(undefined),
48  updateStoreOperation: vi.fn(),
49  updateStackUpdateStatus: vi.fn(),
50  upsertInstalledStack: vi.fn(),
51}));
52
53import { findStoreCatalogTemplateByAppId } from "@/lib/server/modules/store/catalog";
54import {
55  extractPrimaryServiceWithName,
56  parseComposeFile,
57} from "@/lib/server/modules/docker/compose-parser";
58import {
59  cleanupComposeDataOnUninstall,
60  getComposeRuntimeInfo,
61  materializeInlineStackFiles,
62  runComposeDown,
63  runComposePull,
64  runComposeRestart,
65  runComposeUp,
66} from "@/lib/server/modules/docker/compose-runner";
67import { findCustomStoreTemplateByAppId } from "@/lib/server/modules/store/custom-apps";
68import { invalidateInstalledAppsCache } from "@/lib/server/modules/apps/service";
69import {
70  createStoreOperation,
71  deleteInstalledStackByAppId,
72  findInstalledStackByAppId,
73  findStackByWebUiPort,
74  updateStoreOperation,
75  updateStackUpdateStatus,
76  upsertInstalledStack,
77} from "@/lib/server/modules/apps/stacks-repository";
78import {
79  _resetActiveOperationsForTesting,
80  getLatestStoreOperationEvent,
81  startStoreOperation,
82} from "@/lib/server/modules/apps/operations";
83import type { StoreOperationError } from "@/lib/server/modules/apps/operations";
84
85async function waitForLatestEventType(operationId: string, expectedType: string) {
86  for (let index = 0; index < 50; index += 1) {
87    const latest = getLatestStoreOperationEvent(operationId);
88    if (latest?.type === expectedType) {
89      return latest;
90    }
91
92    await new Promise((resolve) => {
93      setTimeout(resolve, 0);
94    });
95  }
96
97  throw new Error(`Timed out waiting for event type "${expectedType}"`);
98}
99
100async function writeCatalogComposeFile(prefix: string, composeContent: string) {
101  const tempDir = await mkdtemp(path.join(os.tmpdir(), prefix));
102  const composePath = path.join(tempDir, "docker-compose.yml");
103  await writeFile(composePath, composeContent, "utf8");
104  return { tempDir, composePath };
105}
106
107describe("store operations", () => {
108  beforeEach(() => {
109    _resetActiveOperationsForTesting();
110    vi.mocked(findStoreCatalogTemplateByAppId).mockReset();
111    vi.mocked(findCustomStoreTemplateByAppId).mockReset();
112    vi.mocked(cleanupComposeDataOnUninstall).mockReset();
113    vi.mocked(parseComposeFile).mockReset();
114    vi.mocked(extractPrimaryServiceWithName).mockReset();
115    vi.mocked(getComposeRuntimeInfo).mockReset();
116    vi.mocked(materializeInlineStackFiles).mockReset();
117    vi.mocked(runComposePull).mockReset();
118    vi.mocked(runComposeUp).mockReset();
119    vi.mocked(invalidateInstalledAppsCache).mockReset();
120    vi.mocked(createStoreOperation).mockReset();
121    vi.mocked(deleteInstalledStackByAppId).mockReset();
122    vi.mocked(findInstalledStackByAppId).mockReset();
123    vi.mocked(findStackByWebUiPort).mockReset();
124    vi.mocked(updateStoreOperation).mockReset();
125    vi.mocked(updateStackUpdateStatus).mockReset();
126    vi.mocked(upsertInstalledStack).mockReset();
127    vi.stubGlobal(
128      "fetch",
129      vi.fn().mockResolvedValue({
130        status: 200,
131      }),
132    );
133    vi.mocked(getComposeRuntimeInfo).mockResolvedValue({
134      status: "running",
135      lifecycleStatus: "running",
136      containerNames: ["app"],
137      primaryContainerName: "app",
138      condition: { condition: "running", exitCode: null },
139    });
140  });
141
142  it("rejects a second active operation for the same app", async () => {
143    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
144
145    await startStoreOperation({
146      appId: "example",
147      action: "install",
148    });
149
150    await expect(
151      startStoreOperation({
152        appId: "example",
153        action: "update",
154      }),
155    ).rejects.toMatchObject({
156      code: "operation_conflict",
157      statusCode: 409,
158    } satisfies Partial<StoreOperationError>);
159  });
160
161  it("rejects new operations when the global concurrency cap is reached", async () => {
162    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
163
164    await startStoreOperation({ appId: "one", action: "install" });
165    await startStoreOperation({ appId: "two", action: "install" });
166    await startStoreOperation({ appId: "three", action: "install" });
167
168    await expect(
169      startStoreOperation({ appId: "four", action: "install" }),
170    ).rejects.toMatchObject({
171      code: "operation_limit_reached",
172      statusCode: 429,
173    } satisfies Partial<StoreOperationError>);
174  });
175
176  it("runs install flow and completes with progress updates", async () => {
177    const { tempDir, composePath } = await writeCatalogComposeFile(
178      "store-install-",
179      `services:
180  adguard-home:
181    image: ghcr.io/example/app:latest
182`,
183    );
184
185    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
186      appId: "adguard-home",
187      templateName: "adguard-home",
188      name: "AdGuard Home",
189      description: "dns",
190      platform: "Docker",
191      note: "note",
192      categories: ["Network"],
193      logoUrl: null,
194      port: null,
195      repositoryUrl: "https://github.com/bigbeartechworld/big-bear-portainer",
196      stackFile: "Apps/adguard-home/docker-compose.yml",
197      composePath,
198      env: [{ name: "TZ", default: "UTC" }],
199      screenshots: [],
200      image: "ghcr.io/example/app:latest",
201      volumes: [],
202      scheme: "http",
203      index: "/",
204      mainServiceName: "adguard-home",
205    });
206    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
207
208    vi.mocked(findInstalledStackByAppId).mockResolvedValue(null);
209    vi.mocked(findStackByWebUiPort).mockResolvedValue(null);
210    vi.mocked(materializeInlineStackFiles).mockResolvedValue({
211      stackDir: "/tmp/store/stacks/adguard-home",
212      composePath: "/tmp/store/stacks/adguard-home/docker-compose.yml",
213      envPath: "/tmp/store/stacks/adguard-home/.env",
214      stackName: "adguard-home",
215      webUiPort: 3001,
216    });
217    vi.mocked(runComposePull).mockResolvedValue(undefined);
218
219    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
220    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
221    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
222    vi.mocked(runComposeUp).mockResolvedValue(undefined);
223    vi.mocked(upsertInstalledStack).mockResolvedValue(undefined);
224
225    let finished = false;
226    const done = new Promise<void>((resolve) => {
227      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
228        if (!finished && patch.status === "success") {
229          finished = true;
230          resolve();
231        }
232      });
233    });
234
235    const { operationId } = await startStoreOperation({
236      appId: "adguard-home",
237      action: "install",
238      webUiPort: 3001,
239      env: {
240        TZ: "Africa/Tunis",
241      },
242    });
243
244    await done;
245
246    expect(operationId).toBeTruthy();
247    expect(upsertInstalledStack).toHaveBeenCalledWith(
248      expect.objectContaining({
249        appId: "adguard-home",
250        status: "installed",
251        webUiPort: 3001,
252      }),
253    );
254    expect(materializeInlineStackFiles).toHaveBeenCalledWith(
255      expect.objectContaining({
256        appId: "adguard-home",
257        storageMappingStrategy: "app_target_path",
258      }),
259    );
260    expect(invalidateInstalledAppsCache).toHaveBeenCalledTimes(1);
261    expect(runComposeUp).toHaveBeenCalled();
262
263    const latest = await waitForLatestEventType(operationId, "operation.completed");
264    expect(latest?.status).toBe("success");
265    await rm(tempDir, { recursive: true, force: true });
266  });
267
268  it("marks operation as failed when docker pull fails", async () => {
269    const { tempDir, composePath } = await writeCatalogComposeFile(
270      "store-install-fail-",
271      `services:
272  homepage:
273    image: ghcr.io/example/homepage:latest
274`,
275    );
276
277    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
278      appId: "homepage",
279      templateName: "homepage",
280      name: "Homepage",
281      description: "dashboard",
282      platform: "Docker",
283      note: "note",
284      categories: ["Productivity"],
285      logoUrl: null,
286      port: null,
287      repositoryUrl: "https://github.com/bigbeartechworld/big-bear-portainer",
288      stackFile: "Apps/Homepage/docker-compose.yml",
289      composePath,
290      env: [],
291      screenshots: [],
292      image: "ghcr.io/example/homepage:latest",
293      volumes: [],
294      scheme: "http",
295      index: "/",
296      mainServiceName: "homepage",
297    });
298    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
299
300    vi.mocked(findInstalledStackByAppId).mockResolvedValue(null);
301    vi.mocked(findStackByWebUiPort).mockResolvedValue(null);
302    vi.mocked(materializeInlineStackFiles).mockResolvedValue({
303      stackDir: "/tmp/store/stacks/homepage",
304      composePath: "/tmp/store/stacks/homepage/docker-compose.yml",
305      envPath: "/tmp/store/stacks/homepage/.env",
306      stackName: "homepage",
307      webUiPort: null,
308    });
309    vi.mocked(runComposePull).mockRejectedValue(new Error("unauthorized"));
310    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
311    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
312    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
313
314    let failed = false;
315    const done = new Promise<void>((resolve) => {
316      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
317        if (!failed && patch.status === "error") {
318          failed = true;
319          resolve();
320        }
321      });
322    });
323
324    const { operationId } = await startStoreOperation({
325      appId: "homepage",
326      action: "install",
327    });
328
329    await done;
330
331    const latest = await waitForLatestEventType(operationId, "operation.failed");
332    expect(latest?.status).toBe("error");
333    await rm(tempDir, { recursive: true, force: true });
334  });
335
336  it("fails install when compose runtime never reaches running", async () => {
337    const { tempDir, composePath } = await writeCatalogComposeFile(
338      "store-install-health-stopped-",
339      `services:
340  grafana:
341    image: grafana/grafana:latest
342`,
343    );
344
345    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
346      appId: "grafana",
347      templateName: "grafana",
348      name: "Grafana",
349      description: "observability",
350      platform: "Docker",
351      note: "note",
352      categories: ["Developer"],
353      logoUrl: null,
354      port: 3000,
355      repositoryUrl: "https://github.com/grafana/grafana",
356      stackFile: "Apps/Grafana/docker-compose.yml",
357      composePath,
358      env: [],
359      screenshots: [],
360      image: "grafana/grafana:latest",
361      volumes: [],
362      scheme: "http",
363      index: "/",
364      mainServiceName: "grafana",
365    });
366    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
367    vi.mocked(findInstalledStackByAppId).mockResolvedValue(null);
368    vi.mocked(findStackByWebUiPort).mockResolvedValue(null);
369    vi.mocked(materializeInlineStackFiles).mockResolvedValue({
370      stackDir: "/tmp/store/stacks/grafana",
371      composePath: "/tmp/store/stacks/grafana/docker-compose.yml",
372      envPath: "/tmp/store/stacks/grafana/.env",
373      stackName: "grafana",
374      webUiPort: 3000,
375    });
376
377    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
378    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
379    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
380    vi.mocked(runComposeUp).mockResolvedValue(undefined);
381    vi.mocked(getComposeRuntimeInfo).mockResolvedValue({
382      status: "stopped",
383      lifecycleStatus: "stopped",
384      containerNames: ["grafana"],
385      primaryContainerName: "grafana",
386      condition: { condition: "stopped", exitCode: null },
387    });
388
389    let failed = false;
390    const done = new Promise<void>((resolve) => {
391      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
392        if (!failed && patch.status === "error") {
393          failed = true;
394          resolve();
395        }
396      });
397    });
398
399    const { operationId } = await startStoreOperation({
400      appId: "grafana",
401      action: "install",
402    });
403
404    await done;
405
406    expect(upsertInstalledStack).not.toHaveBeenCalled();
407    const latest = await waitForLatestEventType(operationId, "operation.failed");
408    expect(latest?.message).toBe(
409      "Deployment failed because containers never reached a running state",
410    );
411    await rm(tempDir, { recursive: true, force: true });
412  });
413
414  it("fails install when compose runtime remains unknown", async () => {
415    const { tempDir, composePath } = await writeCatalogComposeFile(
416      "store-install-health-unknown-",
417      `services:
418  kuma:
419    image: louislam/uptime-kuma:latest
420`,
421    );
422
423    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
424      appId: "uptime-kuma",
425      templateName: "uptime-kuma",
426      name: "Uptime Kuma",
427      description: "monitoring",
428      platform: "Docker",
429      note: "note",
430      categories: ["Monitoring"],
431      logoUrl: null,
432      port: 3001,
433      repositoryUrl: "https://github.com/louislam/uptime-kuma",
434      stackFile: "Apps/Uptime-Kuma/docker-compose.yml",
435      composePath,
436      env: [],
437      screenshots: [],
438      image: "louislam/uptime-kuma:latest",
439      volumes: [],
440      scheme: "http",
441      index: "/",
442      mainServiceName: "kuma",
443    });
444    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
445    vi.mocked(findInstalledStackByAppId).mockResolvedValue(null);
446    vi.mocked(findStackByWebUiPort).mockResolvedValue(null);
447    vi.mocked(materializeInlineStackFiles).mockResolvedValue({
448      stackDir: "/tmp/store/stacks/uptime-kuma",
449      composePath: "/tmp/store/stacks/uptime-kuma/docker-compose.yml",
450      envPath: "/tmp/store/stacks/uptime-kuma/.env",
451      stackName: "uptime-kuma",
452      webUiPort: 3001,
453    });
454
455    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
456    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
457    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
458    vi.mocked(runComposeUp).mockResolvedValue(undefined);
459    vi.mocked(getComposeRuntimeInfo).mockResolvedValue({
460      status: "unknown",
461      lifecycleStatus: "unknown",
462      containerNames: [],
463      primaryContainerName: null,
464      condition: { condition: "unknown", exitCode: null },
465    });
466
467    let failed = false;
468    const done = new Promise<void>((resolve) => {
469      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
470        if (!failed && patch.status === "error") {
471          failed = true;
472          resolve();
473        }
474      });
475    });
476
477    const { operationId } = await startStoreOperation({
478      appId: "uptime-kuma",
479      action: "install",
480    });
481
482    await done;
483
484    expect(upsertInstalledStack).not.toHaveBeenCalled();
485    const latest = await waitForLatestEventType(operationId, "operation.failed");
486    expect(latest?.message).toBe(
487      "Deployment failed because runtime status could not be confirmed",
488    );
489    await rm(tempDir, { recursive: true, force: true });
490  });
491
492  it("keeps install successful when containers are stable but the Web UI probe fails", async () => {
493    const { tempDir, composePath } = await writeCatalogComposeFile(
494      "store-install-health-webui-",
495      `services:
496  home-assistant:
497    image: ghcr.io/home-assistant/home-assistant:latest
498`,
499    );
500
501    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
502      appId: "home-assistant",
503      templateName: "home-assistant",
504      name: "Home Assistant",
505      description: "automation",
506      platform: "Docker",
507      note: "note",
508      categories: ["Automation"],
509      logoUrl: null,
510      port: 8123,
511      repositoryUrl: "https://github.com/home-assistant/core",
512      stackFile: "Apps/Home-Assistant/docker-compose.yml",
513      composePath,
514      env: [],
515      screenshots: [],
516      image: "ghcr.io/home-assistant/home-assistant:latest",
517      volumes: [],
518      scheme: "http",
519      index: "/",
520      mainServiceName: "home-assistant",
521    });
522    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
523    vi.mocked(findInstalledStackByAppId).mockResolvedValue(null);
524    vi.mocked(findStackByWebUiPort).mockResolvedValue(null);
525    vi.mocked(materializeInlineStackFiles).mockResolvedValue({
526      stackDir: "/tmp/store/stacks/home-assistant",
527      composePath: "/tmp/store/stacks/home-assistant/docker-compose.yml",
528      envPath: "/tmp/store/stacks/home-assistant/.env",
529      stackName: "home-assistant",
530      webUiPort: 8123,
531    });
532
533    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
534    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
535    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
536    vi.mocked(runComposeUp).mockResolvedValue(undefined);
537    vi.mocked(upsertInstalledStack).mockResolvedValue(undefined);
538    vi.stubGlobal(
539      "fetch",
540      vi.fn().mockRejectedValue(new TypeError("Failed to fetch")),
541    );
542
543    let finished = false;
544    const done = new Promise<void>((resolve) => {
545      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
546        if (!finished && patch.status === "success") {
547          finished = true;
548          resolve();
549        }
550      });
551    });
552
553    const { operationId } = await startStoreOperation({
554      appId: "home-assistant",
555      action: "install",
556    });
557
558    await done;
559
560    expect(upsertInstalledStack).toHaveBeenCalledWith(
561      expect.objectContaining({
562        appId: "home-assistant",
563      }),
564    );
565    const latest = await waitForLatestEventType(operationId, "operation.completed");
566    expect(latest?.status).toBe("success");
567    expect(updateStoreOperation).toHaveBeenCalledWith(
568      expect.any(String),
569      expect.objectContaining({
570        currentStep: "health-check",
571      }),
572    );
573    await rm(tempDir, { recursive: true, force: true });
574  });
575
576  it("hard-deletes stack record on uninstall and removes data when requested", async () => {
577    vi.mocked(findInstalledStackByAppId).mockResolvedValue({
578      appId: "2fauth",
579      templateName: "2fauth",
580      stackName: "big-bear-2fauth",
581      composePath: "/tmp/store/stacks/2fauth/docker-compose.yml",
582      status: "installed",
583      webUiPort: 8000,
584      env: {},
585      installedAt: "2026-02-24T00:00:00.000Z",
586      updatedAt: "2026-02-24T00:00:00.000Z",
587    });
588
589    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
590    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
591    vi.mocked(runComposeDown).mockResolvedValue(undefined);
592    vi.mocked(cleanupComposeDataOnUninstall).mockResolvedValue(undefined);
593    vi.mocked(deleteInstalledStackByAppId).mockResolvedValue(undefined);
594
595    let finished = false;
596    const done = new Promise<void>((resolve) => {
597      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
598        if (!finished && patch.status === "success") {
599          finished = true;
600          resolve();
601        }
602      });
603    });
604
605    const { operationId } = await startStoreOperation({
606      appId: "2fauth",
607      action: "uninstall",
608      removeVolumes: true,
609    });
610
611    await done;
612
613    expect(runComposeDown).toHaveBeenCalledWith({
614      composePath: "/tmp/store/stacks/2fauth/docker-compose.yml",
615      envPath: "/tmp/store/stacks/2fauth/.env",
616      stackName: "big-bear-2fauth",
617      removeVolumes: true,
618    });
619    expect(cleanupComposeDataOnUninstall).toHaveBeenCalledWith({
620      composePath: "/tmp/store/stacks/2fauth/docker-compose.yml",
621      removeVolumes: true,
622    });
623    expect(deleteInstalledStackByAppId).toHaveBeenCalledWith("2fauth");
624    expect(invalidateInstalledAppsCache).toHaveBeenCalledTimes(1);
625
626    const latest = await waitForLatestEventType(operationId, "operation.completed");
627    expect(latest?.status).toBe("success");
628  });
629
630  it("always cleans up installed stack files during uninstall even when data deletion is disabled", async () => {
631    vi.mocked(findInstalledStackByAppId).mockResolvedValue({
632      appId: "pingvin-share",
633      templateName: "pingvin-share",
634      stackName: "pingvin-share",
635      composePath: "/var/lib/home-server/Apps/pingvin-share/docker-compose.yml",
636      status: "installed",
637      webUiPort: 3410,
638      env: {},
639      installedAt: "2026-03-07T00:00:00.000Z",
640      updatedAt: "2026-03-07T00:00:00.000Z",
641    });
642
643    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
644    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
645    vi.mocked(runComposeDown).mockResolvedValue(undefined);
646    vi.mocked(cleanupComposeDataOnUninstall).mockResolvedValue(undefined);
647    vi.mocked(deleteInstalledStackByAppId).mockResolvedValue(undefined);
648
649    let finished = false;
650    const done = new Promise<void>((resolve) => {
651      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
652        if (!finished && patch.status === "success") {
653          finished = true;
654          resolve();
655        }
656      });
657    });
658
659    await startStoreOperation({
660      appId: "pingvin-share",
661      action: "uninstall",
662      removeVolumes: false,
663    });
664
665    await done;
666
667    expect(runComposeDown).toHaveBeenCalledWith({
668      composePath: "/var/lib/home-server/Apps/pingvin-share/docker-compose.yml",
669      envPath: "/var/lib/home-server/Apps/pingvin-share/.env",
670      stackName: "pingvin-share",
671      removeVolumes: false,
672    });
673    expect(cleanupComposeDataOnUninstall).toHaveBeenCalledWith({
674      composePath: "/var/lib/home-server/Apps/pingvin-share/docker-compose.yml",
675      removeVolumes: false,
676    });
677    expect(deleteInstalledStackByAppId).toHaveBeenCalledWith("pingvin-share");
678  });
679
680  it("uses legacy storage mapping on redeploy for existing apps", async () => {
681    const { tempDir, composePath } = await writeCatalogComposeFile(
682      "store-redeploy-",
683      `services:
684  home-assistant:
685    image: ghcr.io/example/home-assistant:latest
686`,
687    );
688
689    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
690      appId: "home-assistant",
691      templateName: "home-assistant",
692      name: "Home Assistant",
693      description: "automation",
694      platform: "Docker",
695      note: "note",
696      categories: ["Automation"],
697      logoUrl: null,
698      port: null,
699      repositoryUrl: "https://github.com/bigbeartechworld/big-bear-portainer",
700      stackFile: "Apps/home-assistant/docker-compose.yml",
701      composePath,
702      env: [],
703      screenshots: [],
704      image: "ghcr.io/example/home-assistant:latest",
705      volumes: [],
706      scheme: "http",
707      index: "/",
708      mainServiceName: "home-assistant",
709    });
710    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
711    vi.mocked(findInstalledStackByAppId).mockResolvedValue({
712      appId: "home-assistant",
713      templateName: "home-assistant",
714      stackName: "home-assistant",
715      composePath: "/tmp/store/stacks/home-assistant/docker-compose.yml",
716      status: "installed",
717      webUiPort: null,
718      env: {},
719      installedAt: "2026-02-24T00:00:00.000Z",
720      updatedAt: "2026-02-24T00:00:00.000Z",
721    });
722    vi.mocked(findStackByWebUiPort).mockResolvedValue(null);
723    vi.mocked(materializeInlineStackFiles).mockResolvedValue({
724      stackDir: "/tmp/store/stacks/home-assistant",
725      composePath: "/tmp/store/stacks/home-assistant/docker-compose.yml",
726      envPath: "/tmp/store/stacks/home-assistant/.env",
727      stackName: "home-assistant",
728      webUiPort: null,
729    });
730
731    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
732    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
733    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
734    vi.mocked(runComposeUp).mockResolvedValue(undefined);
735    vi.mocked(upsertInstalledStack).mockResolvedValue(undefined);
736
737    let finished = false;
738    const done = new Promise<void>((resolve) => {
739      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
740        if (!finished && patch.status === "success") {
741          finished = true;
742          resolve();
743        }
744      });
745    });
746
747    await startStoreOperation({
748      appId: "home-assistant",
749      action: "redeploy",
750    });
751
752    await done;
753
754    expect(materializeInlineStackFiles).toHaveBeenCalledWith(
755      expect.objectContaining({
756        appId: "home-assistant",
757        storageMappingStrategy: "legacy_named_source",
758      }),
759    );
760    expect(invalidateInstalledAppsCache).toHaveBeenCalledTimes(1);
761    await rm(tempDir, { recursive: true, force: true });
762  });
763
764  it("uses composeSource for install materialization and bypasses template env whitelist", async () => {
765    const composeSource = `services:\n  immich-server:\n    image: ghcr.io/immich-app/immich-server:v2.5.6\n    ports:\n      - \"2283:2283\"\n    environment:\n      DB_HOSTNAME: immich-postgres\n      CUSTOM_ENV: yes\n`;
766
767    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
768      appId: "immich",
769      templateName: "immich",
770      name: "Immich",
771      description: "photos",
772      platform: "Docker",
773      note: "note",
774      categories: ["Photos"],
775      logoUrl: null,
776      port: null,
777      repositoryUrl: "https://github.com/bigbeartechworld/big-bear-portainer",
778      stackFile: "Apps/immich/docker-compose.yml",
779      composePath: "/tmp/store/immich/docker-compose.yml",
780      env: [{ name: "TZ", default: "UTC" }],
781      screenshots: [],
782      image: "ghcr.io/immich-app/immich-server:v2.5.6",
783      volumes: [],
784      scheme: "http",
785      index: "/",
786      mainServiceName: "immich-server",
787    });
788    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
789    vi.mocked(findInstalledStackByAppId).mockResolvedValue(null);
790    vi.mocked(findStackByWebUiPort).mockResolvedValue(null);
791    vi.mocked(parseComposeFile).mockReturnValue({
792      services: {
793        "immich-server": {
794          image: "ghcr.io/immich-app/immich-server:v2.5.6",
795          ports: ["2283:2283"],
796          environment: {
797            DB_HOSTNAME: "immich-postgres",
798            CUSTOM_ENV: "yes",
799          },
800        },
801      },
802    });
803    vi.mocked(extractPrimaryServiceWithName).mockReturnValue({
804      name: "immich-server",
805      service: {
806        image: "ghcr.io/immich-app/immich-server:v2.5.6",
807        ports: ["2283:2283"],
808        environment: {
809          DB_HOSTNAME: "immich-postgres",
810          CUSTOM_ENV: "yes",
811        },
812      },
813    });
814    vi.mocked(materializeInlineStackFiles).mockResolvedValue({
815      stackDir: "/tmp/store/stacks/immich",
816      composePath: "/tmp/store/stacks/immich/docker-compose.yml",
817      envPath: "/tmp/store/stacks/immich/.env",
818      stackName: "immich",
819      webUiPort: 2283,
820    });
821
822    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
823    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
824    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
825    vi.mocked(runComposeUp).mockResolvedValue(undefined);
826    vi.mocked(upsertInstalledStack).mockResolvedValue(undefined);
827
828    let finished = false;
829    const done = new Promise<void>((resolve) => {
830      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
831        if (!finished && patch.status === "success") {
832          finished = true;
833          resolve();
834        }
835      });
836    });
837
838    await startStoreOperation({
839      appId: "immich",
840      action: "install",
841      composeSource,
842    });
843
844    await done;
845
846    expect(materializeInlineStackFiles).toHaveBeenCalledWith(
847      expect.objectContaining({
848        appId: "immich",
849        composeContent: composeSource,
850      }),
851    );
852    expect(upsertInstalledStack).toHaveBeenCalledWith(
853      expect.objectContaining({
854        appId: "immich",
855        env: expect.objectContaining({
856          AppID: "immich",
857          DB_HOSTNAME: "immich-postgres",
858          CUSTOM_ENV: "yes",
859        }),
860      }),
861    );
862  });
863
864  it("injects AppID into compose interpolation env during install", async () => {
865    const composeSource = `services:\n  home-assistant:\n    image: ghcr.io/home-assistant/home-assistant:latest\n    volumes:\n      - /DATA/AppData/$AppID/config:/config\n`;
866
867    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
868      appId: "home-assistant",
869      templateName: "home-assistant",
870      name: "Home Assistant",
871      description: "automation",
872      platform: "Docker",
873      note: "note",
874      categories: ["Automation"],
875      logoUrl: null,
876      port: 8123,
877      repositoryUrl: "https://github.com/home-assistant/core",
878      stackFile: "Apps/home-assistant/docker-compose.yml",
879      composePath: "/tmp/store/home-assistant/docker-compose.yml",
880      env: [],
881      screenshots: [],
882      image: "ghcr.io/home-assistant/home-assistant:latest",
883      volumes: [],
884      scheme: "http",
885      index: "/",
886      mainServiceName: "home-assistant",
887    });
888    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
889    vi.mocked(findInstalledStackByAppId).mockResolvedValue(null);
890    vi.mocked(findStackByWebUiPort).mockResolvedValue(null);
891    vi.mocked(parseComposeFile).mockReturnValue({
892      services: {
893        "home-assistant": {
894          image: "ghcr.io/home-assistant/home-assistant:latest",
895          volumes: ["/DATA/AppData/$AppID/config:/config"],
896        },
897      },
898    });
899    vi.mocked(extractPrimaryServiceWithName).mockReturnValue({
900      name: "home-assistant",
901      service: {
902        image: "ghcr.io/home-assistant/home-assistant:latest",
903        volumes: ["/DATA/AppData/$AppID/config:/config"],
904      },
905    });
906    vi.mocked(materializeInlineStackFiles).mockResolvedValue({
907      stackDir: "/tmp/store/stacks/home-assistant",
908      composePath: "/tmp/store/stacks/home-assistant/docker-compose.yml",
909      envPath: "/tmp/store/stacks/home-assistant/.env",
910      stackName: "home-assistant",
911      webUiPort: 8123,
912    });
913
914    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
915    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
916    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
917    vi.mocked(runComposeUp).mockResolvedValue(undefined);
918    vi.mocked(upsertInstalledStack).mockResolvedValue(undefined);
919
920    let finished = false;
921    const done = new Promise<void>((resolve) => {
922      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
923        if (!finished && patch.status === "success") {
924          finished = true;
925          resolve();
926        }
927      });
928    });
929
930    await startStoreOperation({
931      appId: "home-assistant",
932      action: "install",
933      composeSource,
934    });
935
936    await done;
937
938    expect(materializeInlineStackFiles).toHaveBeenCalledWith(
939      expect.objectContaining({
940        appId: "home-assistant",
941        env: expect.objectContaining({
942          AppID: "home-assistant",
943        }),
944      }),
945    );
946  });
947
948  it("updates only service images and preserves other compose fields", async () => {
949    const tempDir = await mkdtemp(path.join(os.tmpdir(), "store-update-"));
950    const composePath = path.join(tempDir, "docker-compose.yml");
951    const storeComposePath = path.join(tempDir, "store-compose.yml");
952    const initialCompose = `services:
953  app:
954    image: ghcr.io/example/app:v1
955    environment:
956      TZ: UTC
957      APP_URL: http://localhost:3100
958    ports:
959      - "3100:3100"
960  redis:
961    image: redis:6
962`;
963    await writeFile(composePath, initialCompose, "utf8");
964    await writeFile(
965      storeComposePath,
966      `services:
967  app:
968    image: ghcr.io/example/app:v2
969  redis:
970    image: redis:7
971`,
972      "utf8",
973    );
974
975    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
976      appId: "example",
977      templateName: "example",
978      name: "Example",
979      description: "example",
980      platform: "Docker",
981      note: "note",
982      categories: ["Tools"],
983      logoUrl: null,
984      port: null,
985      repositoryUrl: "https://github.com/example/store",
986      stackFile: "Apps/example/docker-compose.yml",
987      composePath: storeComposePath,
988      env: [],
989      screenshots: [],
990      image: "ghcr.io/example/app:v2",
991      volumes: [],
992      scheme: "http",
993      index: "/",
994      mainServiceName: "app",
995    });
996    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
997    vi.mocked(findInstalledStackByAppId).mockResolvedValue({
998      appId: "example",
999      templateName: "example",
1000      stackName: "example",
1001      composePath,
1002      status: "installed",
1003      webUiPort: 3100,
1004      env: {
1005        TZ: "UTC",
1006      },
1007      installedAt: "2026-02-24T00:00:00.000Z",
1008      updatedAt: "2026-02-24T00:00:00.000Z",
1009    });
1010
1011    vi.mocked(runComposeUp).mockResolvedValue(undefined);
1012    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
1013    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
1014    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
1015    vi.mocked(upsertInstalledStack).mockResolvedValue(undefined);
1016
1017    let finished = false;
1018    const done = new Promise<void>((resolve) => {
1019      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
1020        if (!finished && patch.status === "success") {
1021          finished = true;
1022          resolve();
1023        }
1024      });
1025    });
1026
1027    await startStoreOperation({
1028      appId: "example",
1029      action: "update",
1030    });
1031
1032    await done;
1033
1034    const updatedCompose = await readFile(composePath, "utf8");
1035    const parsed = yaml.load(updatedCompose) as {
1036      services: Record<string, { image?: string; environment?: Record<string, string>; ports?: string[] }>;
1037    };
1038
1039    expect(parsed.services.app.image).toBe("ghcr.io/example/app:v2");
1040    expect(parsed.services.redis.image).toBe("redis:7");
1041    expect(parsed.services.app.environment).toEqual({
1042      TZ: "UTC",
1043      APP_URL: "http://localhost:3100",
1044    });
1045    expect(parsed.services.app.ports).toEqual(["3100:3100"]);
1046    expect(runComposeUp).toHaveBeenCalledTimes(1);
1047
1048    await rm(tempDir, { recursive: true, force: true });
1049  });
1050
1051  it("treats update as no-op when installed images are already current", async () => {
1052    const tempDir = await mkdtemp(path.join(os.tmpdir(), "store-update-noop-"));
1053    const composePath = path.join(tempDir, "docker-compose.yml");
1054    const storeComposePath = path.join(tempDir, "store-compose.yml");
1055    const initialCompose = `services:\n  app:\n    image: ghcr.io/example/app:v2\n    environment:\n      TZ: UTC\n`;
1056    await writeFile(composePath, initialCompose, "utf8");
1057    await writeFile(storeComposePath, `services:\n  app:\n    image: ghcr.io/example/app:v2\n`, "utf8");
1058
1059    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
1060      appId: "example",
1061      templateName: "example",
1062      name: "Example",
1063      description: "example",
1064      platform: "Docker",
1065      note: "note",
1066      categories: ["Tools"],
1067      logoUrl: null,
1068      port: null,
1069      repositoryUrl: "https://github.com/example/store",
1070      stackFile: "Apps/example/docker-compose.yml",
1071      composePath: storeComposePath,
1072      env: [],
1073      screenshots: [],
1074      image: "ghcr.io/example/app:v2",
1075      volumes: [],
1076      scheme: "http",
1077      index: "/",
1078      mainServiceName: "app",
1079    });
1080    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
1081    vi.mocked(findInstalledStackByAppId).mockResolvedValue({
1082      appId: "example",
1083      templateName: "example",
1084      stackName: "example",
1085      composePath,
1086      status: "installed",
1087      webUiPort: 3100,
1088      env: {
1089        TZ: "UTC",
1090      },
1091      installedAt: "2026-02-24T00:00:00.000Z",
1092      updatedAt: "2026-02-24T00:00:00.000Z",
1093    });
1094    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
1095    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
1096    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
1097
1098    let finished = false;
1099    const done = new Promise<void>((resolve) => {
1100      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
1101        if (!finished && patch.status === "success") {
1102          finished = true;
1103          resolve();
1104        }
1105      });
1106    });
1107
1108    const { operationId } = await startStoreOperation({
1109      appId: "example",
1110      action: "update",
1111    });
1112
1113    await done;
1114
1115    const latest = await waitForLatestEventType(operationId, "operation.completed");
1116    expect(latest?.status).toBe("success");
1117    expect(runComposeUp).not.toHaveBeenCalled();
1118    expect(runComposePull).not.toHaveBeenCalled();
1119
1120    const composeAfterNoop = await readFile(composePath, "utf8");
1121    expect(composeAfterNoop).toBe(initialCompose);
1122
1123    await rm(tempDir, { recursive: true, force: true });
1124  });
1125
1126  it("fails update with explicit error when installed compose is missing", async () => {
1127    const { tempDir, composePath } = await writeCatalogComposeFile(
1128      "store-update-missing-",
1129      `services:
1130  app:
1131    image: ghcr.io/example/app:v2
1132`,
1133    );
1134
1135    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
1136      appId: "example",
1137      templateName: "example",
1138      name: "Example",
1139      description: "example",
1140      platform: "Docker",
1141      note: "note",
1142      categories: ["Tools"],
1143      logoUrl: null,
1144      port: null,
1145      repositoryUrl: "https://github.com/example/store",
1146      stackFile: "Apps/example/docker-compose.yml",
1147      composePath,
1148      env: [],
1149      screenshots: [],
1150      image: "ghcr.io/example/app:v2",
1151      volumes: [],
1152      scheme: "http",
1153      index: "/",
1154      mainServiceName: "app",
1155    });
1156    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
1157    vi.mocked(findInstalledStackByAppId).mockResolvedValue({
1158      appId: "example",
1159      templateName: "example",
1160      stackName: "example",
1161      composePath: "/tmp/missing-compose/docker-compose.yml",
1162      status: "installed",
1163      webUiPort: 3100,
1164      env: {},
1165      installedAt: "2026-02-24T00:00:00.000Z",
1166      updatedAt: "2026-02-24T00:00:00.000Z",
1167    });
1168    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
1169    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
1170    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
1171
1172    let failed = false;
1173    const done = new Promise<void>((resolve) => {
1174      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
1175        if (!failed && patch.status === "error") {
1176          failed = true;
1177          resolve();
1178        }
1179      });
1180    });
1181
1182    const { operationId } = await startStoreOperation({
1183      appId: "example",
1184      action: "update",
1185    });
1186
1187    await done;
1188
1189    const latest = await waitForLatestEventType(operationId, "operation.failed");
1190    expect(latest?.message).toBe("Installed compose source is unavailable");
1191    expect(runComposeUp).not.toHaveBeenCalled();
1192    await rm(tempDir, { recursive: true, force: true });
1193  });
1194
1195  it("resolves moved installed compose path before update", async () => {
1196    const tempDir = await mkdtemp(path.join(os.tmpdir(), "store-update-resolved-compose-"));
1197    const fallbackDir = path.join(tempDir, "missing-compose", "example");
1198    await mkdir(fallbackDir, { recursive: true });
1199    await writeFile(
1200      path.join(fallbackDir, "docker-compose.yml"),
1201      "services:\n  app:\n    image: ghcr.io/example/app:v1\n",
1202      "utf8",
1203    );
1204    const storeComposePath = path.join(tempDir, "store-compose.yml");
1205    await writeFile(
1206      storeComposePath,
1207      "services:\n  app:\n    image: ghcr.io/example/app:v2\n",
1208      "utf8",
1209    );
1210
1211    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
1212      appId: "example",
1213      templateName: "example",
1214      name: "Example",
1215      description: "example",
1216      platform: "Docker",
1217      note: "note",
1218      categories: ["Tools"],
1219      logoUrl: null,
1220      port: null,
1221      repositoryUrl: "https://github.com/example/store",
1222      stackFile: "Apps/example/docker-compose.yml",
1223      composePath: storeComposePath,
1224      env: [],
1225      screenshots: [],
1226      image: "ghcr.io/example/app:v2",
1227      volumes: [],
1228      scheme: "http",
1229      index: "/",
1230      mainServiceName: "app",
1231    });
1232    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
1233    vi.mocked(findInstalledStackByAppId).mockResolvedValue({
1234      appId: "example",
1235      templateName: "example",
1236      stackName: "example",
1237      composePath: path.join(tempDir, "missing-compose", "docker-compose.yml"),
1238      status: "installed",
1239      webUiPort: 3100,
1240      env: {},
1241      installedAt: "2026-02-24T00:00:00.000Z",
1242      updatedAt: "2026-02-24T00:00:00.000Z",
1243    });
1244    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
1245    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
1246    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
1247    vi.mocked(runComposeUp).mockResolvedValue();
1248    vi.mocked(getComposeRuntimeInfo).mockResolvedValue({
1249      status: "running",
1250      primaryContainerName: "example",
1251      condition: { condition: "running", exitCode: null },
1252    });
1253
1254    const { operationId } = await startStoreOperation({
1255      appId: "example",
1256      action: "update",
1257    });
1258
1259    const latest = await waitForLatestEventType(operationId, "operation.completed");
1260    expect(latest?.type).toBe("operation.completed");
1261    expect(runComposeUp).toHaveBeenCalledWith(
1262      expect.objectContaining({
1263        composePath: path.join(fallbackDir, "docker-compose.yml"),
1264      }),
1265    );
1266
1267    await rm(tempDir, { recursive: true, force: true });
1268  });
1269
1270  it("fails update when installed and store services do not match", async () => {
1271    const tempDir = await mkdtemp(path.join(os.tmpdir(), "store-update-mismatch-"));
1272    const composePath = path.join(tempDir, "docker-compose.yml");
1273    const storeComposePath = path.join(tempDir, "store-compose.yml");
1274    const initialCompose = `services:\n  app:\n    image: ghcr.io/example/app:v1\n`;
1275    await writeFile(composePath, initialCompose, "utf8");
1276    await writeFile(
1277      storeComposePath,
1278      `services:
1279  web:
1280    image: ghcr.io/example/app:v2
1281`,
1282      "utf8",
1283    );
1284
1285    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
1286      appId: "example",
1287      templateName: "example",
1288      name: "Example",
1289      description: "example",
1290      platform: "Docker",
1291      note: "note",
1292      categories: ["Tools"],
1293      logoUrl: null,
1294      port: null,
1295      repositoryUrl: "https://github.com/example/store",
1296      stackFile: "Apps/example/docker-compose.yml",
1297      composePath: storeComposePath,
1298      env: [],
1299      screenshots: [],
1300      image: "ghcr.io/example/app:v2",
1301      volumes: [],
1302      scheme: "http",
1303      index: "/",
1304      mainServiceName: "web",
1305    });
1306    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
1307    vi.mocked(findInstalledStackByAppId).mockResolvedValue({
1308      appId: "example",
1309      templateName: "example",
1310      stackName: "example",
1311      composePath,
1312      status: "installed",
1313      webUiPort: 3100,
1314      env: {},
1315      installedAt: "2026-02-24T00:00:00.000Z",
1316      updatedAt: "2026-02-24T00:00:00.000Z",
1317    });
1318    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
1319    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
1320    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
1321
1322    let failed = false;
1323    const done = new Promise<void>((resolve) => {
1324      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
1325        if (!failed && patch.status === "error") {
1326          failed = true;
1327          resolve();
1328        }
1329      });
1330    });
1331
1332    await startStoreOperation({
1333      appId: "example",
1334      action: "update",
1335    });
1336
1337    await done;
1338
1339    const composeAfterFailure = await readFile(composePath, "utf8");
1340    expect(composeAfterFailure).toBe(initialCompose);
1341    expect(runComposeUp).not.toHaveBeenCalled();
1342
1343    await rm(tempDir, { recursive: true, force: true });
1344  });
1345
1346  it("restores backup compose when update apply fails", async () => {
1347    const tempDir = await mkdtemp(path.join(os.tmpdir(), "store-update-rollback-"));
1348    const composePath = path.join(tempDir, "docker-compose.yml");
1349    const storeComposePath = path.join(tempDir, "store-compose.yml");
1350    const initialCompose = `services:\n  app:\n    image: ghcr.io/example/app:v1\n`;
1351    await writeFile(composePath, initialCompose, "utf8");
1352    await writeFile(storeComposePath, `services:\n  app:\n    image: ghcr.io/example/app:v2\n`, "utf8");
1353
1354    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
1355      appId: "example",
1356      templateName: "example",
1357      name: "Example",
1358      description: "example",
1359      platform: "Docker",
1360      note: "note",
1361      categories: ["Tools"],
1362      logoUrl: null,
1363      port: null,
1364      repositoryUrl: "https://github.com/example/store",
1365      stackFile: "Apps/example/docker-compose.yml",
1366      composePath: storeComposePath,
1367      env: [],
1368      screenshots: [],
1369      image: "ghcr.io/example/app:v2",
1370      volumes: [],
1371      scheme: "http",
1372      index: "/",
1373      mainServiceName: "app",
1374    });
1375    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
1376    vi.mocked(findInstalledStackByAppId).mockResolvedValue({
1377      appId: "example",
1378      templateName: "example",
1379      stackName: "example",
1380      composePath,
1381      status: "installed",
1382      webUiPort: 3100,
1383      env: {},
1384      installedAt: "2026-02-24T00:00:00.000Z",
1385      updatedAt: "2026-02-24T00:00:00.000Z",
1386    });
1387
1388    vi.mocked(runComposeUp)
1389      .mockRejectedValueOnce(new Error("compose up failed"))
1390      .mockResolvedValueOnce(undefined);
1391    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
1392    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
1393    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
1394
1395    let failed = false;
1396    const done = new Promise<void>((resolve) => {
1397      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
1398        if (!failed && patch.status === "error") {
1399          failed = true;
1400          resolve();
1401        }
1402      });
1403    });
1404
1405    await startStoreOperation({
1406      appId: "example",
1407      action: "update",
1408    });
1409
1410    await done;
1411
1412    const composeAfterRollback = await readFile(composePath, "utf8");
1413    expect(composeAfterRollback).toBe(initialCompose);
1414    expect(runComposeUp).toHaveBeenCalledTimes(2);
1415
1416    await rm(tempDir, { recursive: true, force: true });
1417  });
1418
1419  it("restores backup compose when update health-check fails after compose up", async () => {
1420    const tempDir = await mkdtemp(path.join(os.tmpdir(), "store-update-health-rollback-"));
1421    const composePath = path.join(tempDir, "docker-compose.yml");
1422    const storeComposePath = path.join(tempDir, "store-compose.yml");
1423    const initialCompose = `services:\n  app:\n    image: ghcr.io/example/app:v1\n`;
1424    await writeFile(composePath, initialCompose, "utf8");
1425    await writeFile(storeComposePath, `services:\n  app:\n    image: ghcr.io/example/app:v2\n`, "utf8");
1426
1427    vi.mocked(findStoreCatalogTemplateByAppId).mockResolvedValue({
1428      appId: "example",
1429      templateName: "example",
1430      name: "Example",
1431      description: "example",
1432      platform: "Docker",
1433      note: "note",
1434      categories: ["Tools"],
1435      logoUrl: null,
1436      port: 3100,
1437      repositoryUrl: "https://github.com/example/store",
1438      stackFile: "Apps/example/docker-compose.yml",
1439      composePath: storeComposePath,
1440      env: [],
1441      screenshots: [],
1442      image: "ghcr.io/example/app:v2",
1443      volumes: [],
1444      scheme: "http",
1445      index: "/",
1446      mainServiceName: "app",
1447    });
1448    vi.mocked(findCustomStoreTemplateByAppId).mockResolvedValue(null);
1449    vi.mocked(findInstalledStackByAppId).mockResolvedValue({
1450      appId: "example",
1451      templateName: "example",
1452      stackName: "example",
1453      composePath,
1454      status: "installed",
1455      webUiPort: 3100,
1456      env: {},
1457      installedAt: "2026-02-24T00:00:00.000Z",
1458      updatedAt: "2026-02-24T00:00:00.000Z",
1459    });
1460
1461    vi.mocked(runComposeUp).mockResolvedValue(undefined);
1462    vi.mocked(getComposeRuntimeInfo).mockResolvedValue({
1463      status: "stopped",
1464      lifecycleStatus: "restarting",
1465      containerNames: ["example-app-1"],
1466      primaryContainerName: "example-app-1",
1467      condition: { condition: "stopped", exitCode: null },
1468    });
1469    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
1470    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
1471    vi.mocked(updateStackUpdateStatus).mockResolvedValue(undefined);
1472
1473    let failed = false;
1474    const done = new Promise<void>((resolve) => {
1475      vi.mocked(updateStoreOperation).mockImplementation(async (_id, patch) => {
1476        if (!failed && patch.status === "error") {
1477          failed = true;
1478          resolve();
1479        }
1480      });
1481    });
1482
1483    await startStoreOperation({
1484      appId: "example",
1485      action: "update",
1486    });
1487
1488    await done;
1489
1490    const composeAfterRollback = await readFile(composePath, "utf8");
1491    expect(composeAfterRollback).toBe(initialCompose);
1492    expect(runComposeUp).toHaveBeenCalledTimes(2);
1493
1494    await rm(tempDir, { recursive: true, force: true });
1495  });
1496
1497  it("purges latestOperationEvent after the terminal-event grace window", async () => {
1498    vi.mocked(findInstalledStackByAppId).mockResolvedValue({
1499      appId: "purge-me",
1500      templateName: "purge-me",
1501      stackName: "purge-me",
1502      composePath: "/tmp/store/stacks/purge-me/docker-compose.yml",
1503      status: "installed",
1504      webUiPort: 4001,
1505      env: {},
1506      installedAt: new Date("2026-02-24T00:00:00.000Z"),
1507      updatedAt: new Date("2026-02-24T00:00:00.000Z"),
1508      isUpToDate: true,
1509    });
1510    vi.mocked(createStoreOperation).mockResolvedValue(undefined);
1511    vi.mocked(updateStoreOperation).mockResolvedValue(undefined);
1512    vi.mocked(getComposeRuntimeInfo).mockResolvedValue({
1513      status: "running",
1514      lifecycleStatus: "running",
1515      containerNames: ["purge"],
1516      primaryContainerName: "purge",
1517      condition: { condition: "running", exitCode: null },
1518    });
1519    vi.mocked(runComposeRestart).mockResolvedValue(undefined);
1520
1521    const { operationId } = await startStoreOperation({
1522      appId: "purge-me",
1523      action: "restart",
1524    });
1525
1526    const latest = await waitForLatestEventType(operationId, "operation.completed");
1527    expect(latest?.status).toBe("success");
1528
1529    // Wait past the test TTL (1s) plus a margin so the unref'd timer fires.
1530    await new Promise((resolve) => setTimeout(resolve, 1_200));
1531
1532    expect(getLatestStoreOperationEvent(operationId)).toBeNull();
1533  });
1534});
1535