✨ feat(watchers): add next run metadata to watcher API and UI (#288)

Author: s-b-e-n-s-o-n

app/agent/api/index.ts

@@ -160,6 +160,7 @@ export async function init() {
   app.get('/api/containers/:id/logs', containerApi.getContainerLogs);
   app.delete('/api/containers/:id', containerApi.deleteContainer);
   app.get('/api/watchers', watcherApi.getWatchers);
+  app.get('/api/watchers/:type/:name', watcherApi.getWatcher);
   app.get('/api/triggers', triggerApi.getTriggers);
   app.get('/api/events', eventApi.subscribeEvents);
   app.post('/api/triggers/:type/:name', triggerApi.runTrigger);

app/agent/api/watcher.test.ts

@@ -13,6 +13,13 @@ vi.mock('../../registry/index.js', () => ({
 
 vi.mock('../../api/component.js', () => ({
   mapComponentsToList: vi.fn().mockReturnValue([]),
+  mapComponentToItem: vi.fn().mockImplementation((key, component) => ({
+    id: key,
+    type: component.type,
+    name: component.name,
+    configuration: component.configuration ?? {},
+    metadata: component.metadata,
+  })),
 }));
 
 vi.mock('../../store/container.js', () => ({
@@ -95,6 +102,45 @@ describe('agent API watcher', () => {
     });
   });
 
+  describe('getWatcher', () => {
+    test('should return a specific watcher', () => {
+      req.params = { type: 'docker', name: 'local' };
+      registry.getState.mockReturnValue({
+        watcher: {
+          'docker.local': {
+            type: 'docker',
+            name: 'local',
+            configuration: { cron: '0 * * * *' },
+            metadata: { nextRunAt: '2026-04-09T13:00:00.000Z' },
+          },
+        },
+      });
+
+      watcherApi.getWatcher(req, res);
+
+      expect(res.status).toHaveBeenCalledWith(200);
+      expect(res.json).toHaveBeenCalledWith({
+        id: 'docker.local',
+        type: 'docker',
+        name: 'local',
+        configuration: { cron: '0 * * * *' },
+        metadata: { nextRunAt: '2026-04-09T13:00:00.000Z' },
+      });
+    });
+
+    test('should return 404 when the watcher detail is missing', () => {
+      req.params = { type: 'docker', name: 'missing' };
+      registry.getState.mockReturnValue({ watcher: {} });
+
+      watcherApi.getWatcher(req, res);
+
+      expect(res.status).toHaveBeenCalledWith(404);
+      expect(res.json).toHaveBeenCalledWith(
+        expect.objectContaining({ error: 'Watcher missing not found' }),
+      );
+    });
+  });
+
   describe('watchContainer', () => {
     test('should return 404 when watcher is not found', async () => {
       req.params = { type: 'docker', name: 'local', id: 'c1' };

app/agent/api/watcher.ts

@@ -1,5 +1,5 @@
 import type { Request, Response } from 'express';
-import { mapComponentsToList } from '../../api/component.js';
+import { mapComponentsToList, mapComponentToItem } from '../../api/component.js';
 import { sendErrorResponse } from '../../api/error-response.js';
 import logger from '../../log/index.js';
 import { sanitizeLogParam } from '../../log/sanitize.js';
@@ -40,6 +40,23 @@ export function getWatchers(req: Request, res: Response) {
   res.json(items);
 }
 
+/**
+ * Get a specific watcher.
+ */
+export function getWatcher(req: Request, res: Response) {
+  const type = req.params.type as string;
+  const name = req.params.name as string;
+  const watcherId = `${type.toLowerCase()}.${name.toLowerCase()}`;
+  const watcher = registry.getState().watcher[watcherId];
+
+  if (!watcher) {
+    sendErrorResponse(res, 404, `Watcher ${name} not found`);
+    return;
+  }
+
+  res.status(200).json(mapComponentToItem(watcherId, watcher, 'watcher'));
+}
+
 /**
  * Watch a specific watcher.
  */

app/api/watcher.test.ts

@@ -1,18 +1,153 @@
-vi.mock('./component', () => ({
-  init: vi.fn(() => 'watcher-router'),
+import * as agentManager from '../agent/manager.js';
+import * as registry from '../registry/index.js';
+import * as watcherRouter from './watcher.js';
+
+vi.mock('../registry/index.js', () => ({
+  getState: vi.fn(),
 }));
 
-import * as component from './component.js';
-import * as watcherRouter from './watcher.js';
+vi.mock('../agent/manager.js', () => ({
+  getAgent: vi.fn(),
+}));
+
+function createMockResponse() {
+  return {
+    status: vi.fn().mockReturnThis(),
+    json: vi.fn(),
+  };
+}
 
 describe('Watcher Router', () => {
   beforeEach(() => {
     vi.clearAllMocks();
   });
 
-  test('should init component router with watcher kind', () => {
-    const router = watcherRouter.init();
-    expect(component.init).toHaveBeenCalledWith('watcher');
-    expect(router).toBe('watcher-router');
+  test('getWatchers should return local watcher metadata', async () => {
+    registry.getState.mockReturnValue({
+      watcher: {
+        'docker.local': {
+          type: 'docker',
+          name: 'local',
+          configuration: { cron: '0 * * * *' },
+          maskConfiguration: vi.fn(() => ({ cron: '0 * * * *' })),
+          getMetadata: vi.fn(() => ({ nextRunAt: '2026-04-09T13:00:00.000Z' })),
+        },
+      },
+    });
+
+    const res = createMockResponse();
+    await watcherRouter.getWatchers({ query: {} }, res);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith({
+      data: [
+        {
+          id: 'docker.local',
+          type: 'docker',
+          name: 'local',
+          configuration: { cron: '0 * * * *' },
+          agent: undefined,
+          metadata: { nextRunAt: '2026-04-09T13:00:00.000Z' },
+        },
+      ],
+      total: 1,
+      limit: 0,
+      offset: 0,
+      hasMore: false,
+    });
+  });
+
+  test('getWatchers should merge fresh metadata from agent-backed watchers', async () => {
+    registry.getState.mockReturnValue({
+      watcher: {
+        'edge.docker.remote': {
+          type: 'docker',
+          name: 'remote',
+          agent: 'edge',
+          configuration: { cron: '0 * * * *' },
+          maskConfiguration: vi.fn(() => ({ cron: '0 * * * *' })),
+          getMetadata: vi.fn(() => ({})),
+        },
+      },
+    });
+    agentManager.getAgent.mockReturnValue({
+      getWatcher: vi.fn().mockResolvedValue({
+        id: 'docker.remote',
+        type: 'docker',
+        name: 'remote',
+        configuration: { cron: '*/15 * * * *' },
+        metadata: { nextRunAt: '2026-04-09T12:45:00.000Z' },
+      }),
+    });
+
+    const res = createMockResponse();
+    await watcherRouter.getWatchers({ query: {} }, res);
+
+    expect(res.json).toHaveBeenCalledWith({
+      data: [
+        {
+          id: 'edge.docker.remote',
+          type: 'docker',
+          name: 'remote',
+          configuration: { cron: '*/15 * * * *' },
+          agent: 'edge',
+          metadata: { nextRunAt: '2026-04-09T12:45:00.000Z' },
+        },
+      ],
+      total: 1,
+      limit: 0,
+      offset: 0,
+      hasMore: false,
+    });
+  });
+
+  test('getWatcher should return a specific agent-backed watcher with refreshed metadata', async () => {
+    registry.getState.mockReturnValue({
+      watcher: {
+        'edge.docker.remote': {
+          type: 'docker',
+          name: 'remote',
+          agent: 'edge',
+          configuration: { cron: '0 * * * *' },
+          maskConfiguration: vi.fn(() => ({ cron: '0 * * * *' })),
+          getMetadata: vi.fn(() => ({})),
+        },
+      },
+    });
+    agentManager.getAgent.mockReturnValue({
+      getWatcher: vi.fn().mockResolvedValue({
+        id: 'docker.remote',
+        type: 'docker',
+        name: 'remote',
+        configuration: { cron: '*/15 * * * *' },
+        metadata: { nextRunAt: '2026-04-09T12:45:00.000Z' },
+      }),
+    });
+
+    const res = createMockResponse();
+    await watcherRouter.getWatcher(
+      { params: { type: 'docker', name: 'remote', agent: 'edge' } },
+      res,
+    );
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith({
+      id: 'edge.docker.remote',
+      type: 'docker',
+      name: 'remote',
+      configuration: { cron: '*/15 * * * *' },
+      agent: 'edge',
+      metadata: { nextRunAt: '2026-04-09T12:45:00.000Z' },
+    });
+  });
+
+  test('getWatcher should return 404 when watcher is missing', async () => {
+    registry.getState.mockReturnValue({ watcher: {} });
+
+    const res = createMockResponse();
+    await watcherRouter.getWatcher({ params: { type: 'docker', name: 'missing' } }, res);
+
+    expect(res.status).toHaveBeenCalledWith(404);
+    expect(res.json).toHaveBeenCalledWith({ error: 'Component not found' });
   });
 });

app/api/watcher.ts

@@ -1,9 +1,128 @@
-import * as component from './component.js';
+import express, { type Request, type Response } from 'express';
+import nocache from 'nocache';
+import { byString, byValues } from 'sort-es';
+import { getAgent } from '../agent/manager.js';
+import logger from '../log/index.js';
+import * as registry from '../registry/index.js';
+import { getErrorMessage } from '../util/error.js';
+import type Watcher from '../watchers/Watcher.js';
+import { type ApiComponent, mapComponentToItem } from './component.js';
+import { normalizeLimitOffsetPagination } from './container/request-helpers.js';
+import { sendErrorResponse } from './error-response.js';
+
+const log = logger.child({ component: 'api-watcher' });
+const WATCHER_LIST_MAX_LIMIT = 200;
+
+interface WatcherRouteParams {
+  agent?: string;
+  type: string;
+  name: string;
+}
+
+function resolveWatcherId(params: WatcherRouteParams): string {
+  return params.agent
+    ? `${params.agent}.${params.type}.${params.name}`
+    : `${params.type}.${params.name}`;
+}
+
+function paginateWatcherItems(
+  watchers: ApiComponent[],
+  pagination: { limit: number; offset: number },
+): ApiComponent[] {
+  if (pagination.offset >= watchers.length) {
+    return [];
+  }
+
+  if (pagination.limit === 0) {
+    return watchers.slice(pagination.offset);
+  }
+
+  return watchers.slice(pagination.offset, pagination.offset + pagination.limit);
+}
+
+function sortWatcherItems(watchers: ApiComponent[]): ApiComponent[] {
+  return [...watchers].sort(
+    byValues([
+      [(watcher) => watcher.type, byString()],
+      [(watcher) => watcher.name, byString()],
+    ]),
+  );
+}
+
+async function resolveWatcherItem(id: string, watcher: Watcher): Promise<ApiComponent> {
+  const fallback = mapComponentToItem(id, watcher, 'watcher');
+
+  if (!watcher.agent) {
+    return fallback;
+  }
+
+  const agentClient = getAgent(watcher.agent);
+  if (!agentClient) {
+    return fallback;
+  }
+
+  try {
+    const remoteWatcher = await agentClient.getWatcher(watcher.type, watcher.name);
+    return {
+      ...fallback,
+      configuration: remoteWatcher.configuration ?? fallback.configuration,
+      metadata: remoteWatcher.metadata ?? fallback.metadata,
+    };
+  } catch (error: unknown) {
+    log.debug(
+      `Unable to refresh watcher ${watcher.agent}.${watcher.type}.${watcher.name} (${getErrorMessage(error)})`,
+    );
+    return fallback;
+  }
+}
+
+export async function getWatchers(req: Request, res: Response): Promise<void> {
+  const watchers = registry.getState().watcher || {};
+  const items = await Promise.all(
+    Object.entries(watchers).map(([id, watcher]) => resolveWatcherItem(id, watcher)),
+  );
+  const allItems = sortWatcherItems(items);
+  const pagination = normalizeLimitOffsetPagination(req.query, {
+    maxLimit: WATCHER_LIST_MAX_LIMIT,
+  });
+  const data = paginateWatcherItems(allItems, pagination);
+
+  res.status(200).json({
+    data,
+    total: allItems.length,
+    limit: pagination.limit,
+    offset: pagination.offset,
+    hasMore: pagination.limit > 0 && pagination.offset + data.length < allItems.length,
+  });
+}
+
+export async function getWatcher(req: Request<WatcherRouteParams>, res: Response): Promise<void> {
+  const watcherId = resolveWatcherId(req.params);
+  const watcher = registry.getState().watcher[watcherId];
+
+  if (!watcher) {
+    sendErrorResponse(res, 404, 'Component not found');
+    return;
+  }
+
+  const item = await resolveWatcherItem(watcherId, watcher);
+  res.status(200).json(item);
+}
 
 /**
  * Init Router.
- * @returns {*}
  */
 export function init() {
-  return component.init('watcher');
+  const router = express.Router();
+  router.use(nocache());
+  router.get('/', (req: Request, res: Response) => {
+    void getWatchers(req, res);
+  });
+  router.get('/:type/:name', (req: Request<WatcherRouteParams>, res: Response) => {
+    void getWatcher(req, res);
+  });
+  router.get('/:type/:name/:agent', (req: Request<WatcherRouteParams>, res: Response) => {
+    void getWatcher(req, res);
+  });
+  return router;
 }