feat(announcements): register actions for announcements

workspaces/announcements/.changeset/tame-impalas-trade.md

@@ -0,0 +1,12 @@
+---
+'@backstage-community/plugin-announcements-backend': patch
+---
+
+Added actions for announcement management.
+
+Registered four actions that expose the announcements backend via MCP and scaffolder templates:
+
+- `announcements:list-announcements` — list announcements with optional filters for category, tags, active status, and pagination
+- `announcements:get-announcement` — fetch full details of a single announcement by ID
+- `announcements:create-announcement` — create a new announcement (requires `announcement.entity.create` permission)
+- `announcements:delete-announcement` — delete an announcement by ID (requires `announcement.entity.delete` permission)

workspaces/announcements/plugins/announcements-backend/src/actions/createCreateAnnouncementAction.test.ts

@@ -0,0 +1,146 @@
+/*
+ * Copyright 2025 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { mockCredentials, mockServices } from '@backstage/backend-test-utils';
+import { NotAllowedError } from '@backstage/errors';
+import { AuthorizeResult } from '@backstage/plugin-permission-common';
+import { DateTime } from 'luxon';
+import { createCreateAnnouncementAction } from './createCreateAnnouncementAction';
+import { AnnouncementsDatabase } from '../service/persistence/AnnouncementsDatabase';
+import { PersistenceContext } from '../service/persistence';
+
+const nowIso = '2025-01-15T10:00:00.000Z';
+const now = DateTime.fromISO(nowIso);
+
+const mockInsertedAnnouncement = {
+  id: 'ann-new',
+  title: 'My New Announcement',
+  excerpt: 'An excerpt',
+  body: 'Full body',
+  publisher: 'user:default/alice',
+  active: true,
+  created_at: now,
+  start_at: now,
+  until_date: undefined,
+  updated_at: now,
+  category: undefined,
+  on_behalf_of: undefined,
+  sendNotification: false,
+};
+
+describe('createCreateAnnouncementAction', () => {
+  let mockActionsRegistry: { register: jest.Mock };
+  let mockStore: jest.Mocked<AnnouncementsDatabase>;
+  let mockPersistenceContext: PersistenceContext;
+  let mockPermissions: { authorize: jest.Mock };
+
+  beforeEach(() => {
+    mockActionsRegistry = { register: jest.fn() };
+
+    mockStore = {
+      insertAnnouncement: jest.fn().mockResolvedValue(mockInsertedAnnouncement),
+    } as any;
+
+    mockPersistenceContext = {
+      announcementsStore: mockStore,
+    } as any;
+
+    mockPermissions = {
+      authorize: jest
+        .fn()
+        .mockResolvedValue([{ result: AuthorizeResult.ALLOW }]),
+    };
+
+    createCreateAnnouncementAction({
+      actionsRegistry: mockActionsRegistry as any,
+      persistenceContext: mockPersistenceContext,
+      permissions: mockPermissions as any,
+    });
+  });
+
+  it('registers the announcements:create-announcement action', () => {
+    expect(mockActionsRegistry.register).toHaveBeenCalledTimes(1);
+    const reg = mockActionsRegistry.register.mock.calls[0][0];
+    expect(reg.name).toBe('announcements:create-announcement');
+    expect(reg.attributes.readOnly).toBe(false);
+    expect(reg.attributes.destructive).toBe(false);
+    expect(reg.attributes.idempotent).toBe(false);
+    expect(reg.visibilityPermission).toBeDefined();
+    expect(reg.visibilityPermission.name).toBe('announcement.entity.create');
+  });
+
+  it('creates an announcement and returns its details', async () => {
+    const reg = mockActionsRegistry.register.mock.calls[0][0];
+    const credentials = mockCredentials.user();
+
+    const result = await reg.action({
+      input: {
+        title: 'My New Announcement',
+        excerpt: 'An excerpt',
+        body: 'Full body',
+        publisher: 'user:default/alice',
+        active: true,
+        start_at: nowIso,
+        sendNotification: false,
+      },
+      credentials,
+      logger: mockServices.logger.mock(),
+    });
+
+    expect(mockPermissions.authorize).toHaveBeenCalledWith(
+      [
+        expect.objectContaining({
+          permission: expect.objectContaining({
+            name: 'announcement.entity.create',
+          }),
+        }),
+      ],
+      { credentials },
+    );
+    expect(mockStore.insertAnnouncement).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: 'My New Announcement',
+        publisher: 'user:default/alice',
+      }),
+    );
+    expect(result.output.id).toBe('ann-new');
+    expect(result.output.title).toBe('My New Announcement');
+    expect(result.output.created_at).toBe(nowIso);
+  });
+
+  it('throws NotAllowedError when permission is denied', async () => {
+    mockPermissions.authorize.mockResolvedValue([
+      { result: AuthorizeResult.DENY },
+    ]);
+    const reg = mockActionsRegistry.register.mock.calls[0][0];
+    const credentials = mockCredentials.user();
+
+    await expect(
+      reg.action({
+        input: {
+          title: 'Unauthorized',
+          excerpt: 'excerpt',
+          body: 'body',
+          publisher: 'user:default/alice',
+          active: true,
+          start_at: nowIso,
+          sendNotification: false,
+        },
+        credentials,
+        logger: mockServices.logger.mock(),
+      }),
+    ).rejects.toThrow(NotAllowedError);
+  });
+});

workspaces/announcements/plugins/announcements-backend/src/actions/createCreateAnnouncementAction.ts

@@ -0,0 +1,164 @@
+/*
+ * Copyright 2025 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ActionsRegistryService } from '@backstage/backend-plugin-api/alpha';
+import { PermissionsService } from '@backstage/backend-plugin-api';
+import { NotAllowedError } from '@backstage/errors';
+import { AuthorizeResult } from '@backstage/plugin-permission-common';
+import { announcementEntityPermissions } from '@backstage-community/plugin-announcements-common';
+import { DateTime } from 'luxon';
+import { v4 as uuid } from 'uuid';
+import { PersistenceContext } from '../service/persistence';
+
+const { announcementCreatePermission } = announcementEntityPermissions;
+
+/**
+ * Registers the `announcements:create-announcement` action.
+ * @internal
+ */
+export function createCreateAnnouncementAction(options: {
+  actionsRegistry: ActionsRegistryService;
+  persistenceContext: PersistenceContext;
+  permissions: PermissionsService;
+}) {
+  const { actionsRegistry, persistenceContext, permissions } = options;
+
+  actionsRegistry.register({
+    name: 'announcements:create-announcement',
+    title: 'Create Announcement',
+    description:
+      'Create a new announcement. Requires the announcement.entity.create permission.',
+    attributes: {
+      readOnly: false,
+      destructive: false,
+      idempotent: false,
+    },
+    visibilityPermission: announcementCreatePermission,
+    schema: {
+      input: z =>
+        z.object({
+          title: z.string().describe('Title of the announcement'),
+          excerpt: z.string().describe('Short summary shown in listing views'),
+          body: z.string().describe('Full body text of the announcement'),
+          publisher: z
+            .string()
+            .describe('User or team publishing the announcement'),
+          active: z
+            .boolean()
+            .default(true)
+            .describe('Whether the announcement is active'),
+          start_at: z
+            .string()
+            .describe('ISO 8601 datetime when the announcement becomes active'),
+          until_date: z
+            .string()
+            .optional()
+            .describe(
+              'ISO 8601 datetime when the announcement expires (optional)',
+            ),
+          category: z
+            .string()
+            .optional()
+            .describe('Category slug to assign to the announcement'),
+          on_behalf_of: z
+            .string()
+            .optional()
+            .describe('Optional entity ref the announcement is on behalf of'),
+          tags: z
+            .array(z.string())
+            .optional()
+            .describe('Tag slugs to attach to the announcement'),
+          sendNotification: z
+            .boolean()
+            .default(false)
+            .describe(
+              'Whether to send a notification when the announcement is created',
+            ),
+        }),
+      output: z =>
+        z.object({
+          id: z.string(),
+          title: z.string(),
+          excerpt: z.string(),
+          body: z.string(),
+          publisher: z.string(),
+          active: z.boolean(),
+          created_at: z.string(),
+          start_at: z.string(),
+          until_date: z.string().nullable().optional(),
+          updated_at: z.string(),
+          category: z
+            .object({ slug: z.string(), title: z.string() })
+            .optional(),
+          on_behalf_of: z.string().optional(),
+        }),
+    },
+    async action({ input, credentials }) {
+      const decision = await permissions.authorize(
+        [{ permission: announcementCreatePermission }],
+        { credentials },
+      );
+
+      if (decision[0].result === AuthorizeResult.DENY) {
+        throw new NotAllowedError(
+          'Unauthorized: missing announcement.entity.create permission',
+        );
+      }
+
+      const now = DateTime.now();
+      const startAt = DateTime.fromISO(input.start_at);
+      const untilDate = input.until_date
+        ? DateTime.fromISO(input.until_date)
+        : undefined;
+
+      const announcement =
+        await persistenceContext.announcementsStore.insertAnnouncement({
+          id: uuid(),
+          title: input.title,
+          excerpt: input.excerpt,
+          body: input.body,
+          publisher: input.publisher,
+          active: input.active,
+          sendNotification: input.sendNotification,
+          category: input.category,
+          on_behalf_of: input.on_behalf_of,
+          tags: input.tags,
+          created_at: now,
+          start_at: startAt,
+          until_date: untilDate,
+          updated_at: now,
+        });
+
+      return {
+        output: {
+          id: announcement.id,
+          title: announcement.title,
+          excerpt: announcement.excerpt,
+          body: announcement.body,
+          publisher: announcement.publisher,
+          active: announcement.active,
+          created_at: announcement.created_at.toUTC().toISO()!,
+          start_at: announcement.start_at.toUTC().toISO()!,
+          until_date: announcement.until_date
+            ? announcement.until_date.toUTC().toISO()
+            : undefined,
+          updated_at: announcement.updated_at.toUTC().toISO()!,
+          category: announcement.category,
+          on_behalf_of: announcement.on_behalf_of,
+        },
+      };
+    },
+  });
+}