feat(scheduler): add auto_backup, auto_stop, auto_down, auto_start and delete_after_run one-shot mode (#777)

* feat(scheduler): add auto_backup, auto_stop, auto_down, auto_start actions and delete_after_run one-shot mode

Extends the scheduler with four new stack-targeted actions:

- auto_backup: backs up stack compose files and .env using the existing
  FileSystemService.backupStackFiles primitive
- auto_stop: runs compose stop (containers preserved)
- auto_down: runs compose down (containers removed)
- auto_start: runs compose up -d via deployStack (universal start for both
  stopped and down stacks)

Adds delete_after_run boolean column to scheduled_tasks. When enabled,
the task self-deletes after its first successful execution; failures keep
the task so the user can debug and retry.

All four new actions gate at Admiral tier, consistent with restart/snapshot/prune.
Migration is idempotent (maybeAddCol).

* docs(scheduler): update scheduled-operations doc with new lifecycle actions and delete-after-run

Adds the four new actions (Backup Stack Files, Stop Stack, Take Stack Down,
Start Stack) to the action table. Documents the delete-after-run one-shot mode
with its success-only deletion semantics. Adds the Stack Lifecycle Scheduling
section explaining stop-vs-down semantics and the local-execution boundary.
Adds three troubleshooting entries: auto-start on a missing compose folder,
auto-backup single-slot overwrite by design, and one-shot task disappearing
after successful run.

Updates the timeline description from four to five lanes. Refreshes
screenshots to show the new dialog layout with the Lifecycle lane visible.

backend/src/__tests__/scheduled-tasks-routes.test.ts

@@ -243,3 +243,80 @@ describe('GET /api/scheduled-tasks/:id/runs', () => {
     expect(res.body).toHaveProperty('runs');
   });
 });
+
+describe('POST /api/scheduled-tasks - new lifecycle actions', () => {
+  const stackPayload = (action: string) => ({
+    name: `test-${action}`,
+    target_type: 'stack',
+    target_id: 'my-stack',
+    node_id: 1,
+    action,
+    cron_expression: '0 3 * * *',
+    enabled: true,
+  });
+
+  for (const action of ['auto_backup', 'auto_stop', 'auto_down', 'auto_start']) {
+    it(`creates ${action} task successfully (Admiral)`, async () => {
+      const res = await request(app)
+        .post('/api/scheduled-tasks')
+        .set('Cookie', adminCookie)
+        .send(stackPayload(action));
+      expect(res.status).toBe(201);
+      expect(res.body.action).toBe(action);
+      expect(res.body.target_type).toBe('stack');
+    });
+
+    it(`rejects ${action} with target_type "system"`, async () => {
+      const res = await request(app)
+        .post('/api/scheduled-tasks')
+        .set('Cookie', adminCookie)
+        .send({ ...stackPayload(action), target_type: 'system', target_id: null });
+      expect(res.status).toBe(400);
+      expect(res.body.error).toMatch(/target_type "stack"/);
+    });
+  }
+
+  it('persists delete_after_run flag', async () => {
+    const res = await request(app)
+      .post('/api/scheduled-tasks')
+      .set('Cookie', adminCookie)
+      .send({ ...stackPayload('auto_backup'), delete_after_run: true });
+    expect(res.status).toBe(201);
+    expect(res.body.delete_after_run).toBe(1);
+  });
+
+  it('defaults delete_after_run to 0 when not provided', async () => {
+    const res = await request(app)
+      .post('/api/scheduled-tasks')
+      .set('Cookie', adminCookie)
+      .send(stackPayload('auto_stop'));
+    expect(res.status).toBe(201);
+    expect(res.body.delete_after_run).toBe(0);
+  });
+});
+
+describe('PUT /api/scheduled-tasks/:id - delete_after_run', () => {
+  it('can toggle delete_after_run via update', async () => {
+    const now = Date.now();
+    const id = DatabaseService.getInstance().createScheduledTask({
+      name: 't', target_type: 'stack', target_id: 's', node_id: 1, action: 'auto_backup',
+      cron_expression: '0 3 * * *', enabled: 1, created_by: 'admin', created_at: now, updated_at: now,
+      last_run_at: null, next_run_at: null, last_status: null, last_error: null,
+      prune_targets: null, target_services: null, prune_label_filter: null, delete_after_run: 0,
+    });
+
+    const res = await request(app)
+      .put(`/api/scheduled-tasks/${id}`)
+      .set('Cookie', adminCookie)
+      .send({ delete_after_run: true });
+    expect(res.status).toBe(200);
+    expect(res.body.delete_after_run).toBe(1);
+
+    const res2 = await request(app)
+      .put(`/api/scheduled-tasks/${id}`)
+      .set('Cookie', adminCookie)
+      .send({ delete_after_run: false });
+    expect(res2.status).toBe(200);
+    expect(res2.body.delete_after_run).toBe(0);
+  });
+});

backend/src/__tests__/scheduler-service.test.ts

@@ -3,6 +3,7 @@
  * license gating, cron parsing, and error handling.
  */
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { ScheduledTask } from '../services/DatabaseService';
 
 // ── Hoisted mocks ──────────────────────────────────────────────────────
 
@@ -21,6 +22,10 @@ const {
   mockIsTrivyAvailable,
   mockScanAllNodeImages,
   mockGetStackAutoUpdateSettingsForNode,
+  mockDeleteScheduledTask,
+  mockRunCommand,
+  mockDeployStack,
+  mockBackupStackFiles,
 } = vi.hoisted(() => ({
   mockGetDueScheduledTasks: vi.fn().mockReturnValue([]),
   mockCreateScheduledTaskRun: vi.fn().mockReturnValue(1),
@@ -56,6 +61,10 @@ const {
     violations: [],
   }),
   mockGetStackAutoUpdateSettingsForNode: vi.fn().mockReturnValue({}),
+  mockDeleteScheduledTask: vi.fn(),
+  mockRunCommand: vi.fn().mockResolvedValue(undefined),
+  mockDeployStack: vi.fn().mockResolvedValue(undefined),
+  mockBackupStackFiles: vi.fn().mockResolvedValue(undefined),
 }));
 
 vi.mock('../services/DatabaseService', () => ({
@@ -75,6 +84,7 @@ vi.mock('../services/DatabaseService', () => ({
       markStaleRunsAsFailed: mockMarkStaleRunsAsFailed,
       deleteOldScans: mockDeleteOldScans,
       getStackAutoUpdateSettingsForNode: mockGetStackAutoUpdateSettingsForNode,
+      deleteScheduledTask: mockDeleteScheduledTask,
     }),
   },
 }));
@@ -102,6 +112,8 @@ vi.mock('../services/ComposeService', () => ({
   ComposeService: {
     getInstance: () => ({
       updateStack: mockUpdateStack,
+      runCommand: mockRunCommand,
+      deployStack: mockDeployStack,
     }),
   },
 }));
@@ -112,6 +124,7 @@ vi.mock('../services/FileSystemService', () => ({
       getStacks: mockGetStacks,
       getStackContent: mockGetStackContent,
       getEnvContent: mockGetEnvContent,
+      backupStackFiles: mockBackupStackFiles,
     }),
   },
 }));
@@ -1357,3 +1370,112 @@ describe('SchedulerService - executeUpdateRemote', () => {
     );
   });
 });
+
+// ── Lifecycle actions (auto_backup, auto_stop, auto_down, auto_start) ───
+
+function makeLifecycleTask(action: ScheduledTask['action'], overrides: Partial<ScheduledTask> = {}): ScheduledTask {
+  return {
+    id: 300,
+    name: `lifecycle-${action}`,
+    action,
+    target_type: 'stack',
+    target_id: 'my-stack',
+    node_id: 1,
+    cron_expression: '0 2 * * *',
+    enabled: 1,
+    created_by: 'admin',
+    created_at: 0,
+    updated_at: 0,
+    last_run_at: null,
+    next_run_at: null,
+    last_status: null,
+    last_error: null,
+    prune_targets: null,
+    target_services: null,
+    prune_label_filter: null,
+    delete_after_run: 0,
+    ...overrides,
+  };
+}
+
+describe('SchedulerService - lifecycle actions', () => {
+  it('auto_stop calls runCommand with "stop"', async () => {
+    mockGetScheduledTask.mockReturnValue(makeLifecycleTask('auto_stop'));
+    await SchedulerService.getInstance().triggerTask(300);
+    expect(mockRunCommand).toHaveBeenCalledWith('my-stack', 'stop');
+    expect(mockUpdateScheduledTaskRun).toHaveBeenCalledWith(1, expect.objectContaining({ status: 'success' }));
+  });
+
+  it('auto_down calls runCommand with "down"', async () => {
+    mockGetScheduledTask.mockReturnValue(makeLifecycleTask('auto_down'));
+    await SchedulerService.getInstance().triggerTask(300);
+    expect(mockRunCommand).toHaveBeenCalledWith('my-stack', 'down');
+    expect(mockUpdateScheduledTaskRun).toHaveBeenCalledWith(1, expect.objectContaining({ status: 'success' }));
+  });
+
+  it('auto_start calls deployStack', async () => {
+    mockGetScheduledTask.mockReturnValue(makeLifecycleTask('auto_start'));
+    await SchedulerService.getInstance().triggerTask(300);
+    expect(mockDeployStack).toHaveBeenCalledWith('my-stack');
+    expect(mockUpdateScheduledTaskRun).toHaveBeenCalledWith(1, expect.objectContaining({ status: 'success' }));
+  });
+
+  it('auto_backup calls backupStackFiles', async () => {
+    mockGetScheduledTask.mockReturnValue(makeLifecycleTask('auto_backup'));
+    await SchedulerService.getInstance().triggerTask(300);
+    expect(mockBackupStackFiles).toHaveBeenCalledWith('my-stack');
+    expect(mockUpdateScheduledTaskRun).toHaveBeenCalledWith(1, expect.objectContaining({ status: 'success' }));
+  });
+
+  it('auto_stop records failure when target_id is missing', async () => {
+    mockGetScheduledTask.mockReturnValue(makeLifecycleTask('auto_stop', { target_id: null }));
+    await SchedulerService.getInstance().triggerTask(300);
+    expect(mockRunCommand).not.toHaveBeenCalled();
+    expect(mockUpdateScheduledTaskRun).toHaveBeenCalledWith(1, expect.objectContaining({ status: 'failure' }));
+  });
+
+  it('auto_backup records failure when node_id is missing', async () => {
+    mockGetScheduledTask.mockReturnValue(makeLifecycleTask('auto_backup', { node_id: null }));
+    await SchedulerService.getInstance().triggerTask(300);
+    expect(mockBackupStackFiles).not.toHaveBeenCalled();
+    expect(mockUpdateScheduledTaskRun).toHaveBeenCalledWith(1, expect.objectContaining({ status: 'failure' }));
+  });
+
+  it('non-admiral paid tier skips lifecycle actions', async () => {
+    mockGetTier.mockReturnValue('paid');
+    mockGetVariant.mockReturnValue('standard');
+    mockGetScheduledTask.mockReturnValue(makeLifecycleTask('auto_stop'));
+    mockGetDueScheduledTasks.mockReturnValue([makeLifecycleTask('auto_stop')]);
+
+    const svc = SchedulerService.getInstance();
+    await (svc as any).tick();
+
+    expect(mockRunCommand).not.toHaveBeenCalled();
+  });
+});
+
+// ── delete_after_run ────────────────────────────────────────────────────
+
+describe('SchedulerService - delete_after_run', () => {
+  it('deletes task after successful run when delete_after_run is 1', async () => {
+    mockGetScheduledTask.mockReturnValue(makeLifecycleTask('auto_backup', { delete_after_run: 1 }));
+    await SchedulerService.getInstance().triggerTask(300);
+    expect(mockDeleteScheduledTask).toHaveBeenCalledWith(300);
+    expect(mockUpdateScheduledTaskRun).toHaveBeenCalledWith(1, expect.objectContaining({ status: 'success' }));
+  });
+
+  it('does not delete task when run fails even if delete_after_run is 1', async () => {
+    mockBackupStackFiles.mockRejectedValueOnce(new Error('disk full'));
+    mockGetScheduledTask.mockReturnValue(makeLifecycleTask('auto_backup', { delete_after_run: 1 }));
+    await SchedulerService.getInstance().triggerTask(300);
+    expect(mockDeleteScheduledTask).not.toHaveBeenCalled();
+    expect(mockUpdateScheduledTaskRun).toHaveBeenCalledWith(1, expect.objectContaining({ status: 'failure' }));
+  });
+
+  it('does not delete task when delete_after_run is 0', async () => {
+    mockGetScheduledTask.mockReturnValue(makeLifecycleTask('auto_backup', { delete_after_run: 0 }));
+    await SchedulerService.getInstance().triggerTask(300);
+    expect(mockDeleteScheduledTask).not.toHaveBeenCalled();
+    expect(mockUpdateScheduledTask).toHaveBeenCalledWith(300, expect.objectContaining({ last_status: 'success' }));
+  });
+});