@backstage/cli 0.28.0-next.2 → 0.29.0-next.0

package/templates/default-backend-plugin/package.json.hbs

@@ -30,19 +30,19 @@
   "dependencies": {
     "@backstage/backend-defaults": "{{versionQuery '@backstage/backend-defaults'}}",
     "@backstage/backend-plugin-api": "{{versionQuery '@backstage/backend-plugin-api'}}",
+    "@backstage/catalog-client": "{{versionQuery '@backstage/catalog-client'}}",
+    "@backstage/errors": "{{versionQuery '@backstage/errors'}}",
+    "@backstage/plugin-catalog-node": "{{versionQuery '@backstage/plugin-catalog-node'}}",
     "express": "{{versionQuery 'express' '4.17.1'}}",
     "express-promise-router": "{{versionQuery 'express-promise-router' '4.1.0'}}",
-    "node-fetch": "{{versionQuery 'node-fetch' '2.6.7'}}"
+    "zod": "{{versionQuery 'zod' '3.22.4'}}"
   },
   "devDependencies": {
     "@backstage/backend-test-utils": "{{versionQuery '@backstage/backend-test-utils'}}",
     "@backstage/cli": "{{versionQuery '@backstage/cli'}}",
-    "@backstage/plugin-auth-backend": "{{versionQuery '@backstage/plugin-auth-backend'}}",
-    "@backstage/plugin-auth-backend-module-guest-provider": "{{versionQuery '@backstage/plugin-auth-backend-module-guest-provider'}}",
     "@types/express": "{{versionQuery '@types/express' '4.17.6'}}",
     "@types/supertest": "{{versionQuery '@types/supertest' '2.0.12'}}",
-    "supertest": "{{versionQuery 'supertest' '6.2.4'}}",
-    "msw": "{{versionQuery 'msw' '2.3.1'}}"
+    "supertest": "{{versionQuery 'supertest' '6.2.4'}}"
   },
   "files": [
     "dist"

package/templates/default-backend-plugin/src/index.ts.hbs

@@ -1,2 +1 @@
-export * from './service/router';
 export { {{pluginVar}} as default } from './plugin';

package/templates/default-backend-plugin/src/plugin.test.ts.hbs

@@ -0,0 +1,85 @@
+import {
+  mockCredentials,
+  startTestBackend,
+} from '@backstage/backend-test-utils';
+import { {{pluginVar}} } from './plugin';
+import request from 'supertest';
+import { catalogServiceMock } from '@backstage/plugin-catalog-node/testUtils';
+
+// TEMPLATE NOTE:
+// Plugin tests are integration tests for your plugin, ensuring that all pieces
+// work together end-to-end. You can still mock injected backend services
+// however, just like anyone who installs your plugin might replace the
+// services with their own implementations.
+describe('plugin', () => {
+  it('should create and read TODO items', async () => {
+    const { server } = await startTestBackend({
+      features: [{{pluginVar}}],
+    });
+
+    await request(server).get('/api/{{id}}/todos').expect(200, {
+      items: [],
+    });
+
+    const createRes = await request(server)
+      .post('/api/{{id}}/todos')
+      .send({ title: 'My Todo' });
+
+    expect(createRes.status).toBe(201);
+    expect(createRes.body).toEqual({
+      id: expect.any(String),
+      title: 'My Todo',
+      createdBy: mockCredentials.user().principal.userEntityRef,
+      createdAt: expect.any(String),
+    });
+
+    const createdTodoItem = createRes.body;
+
+    await request(server)
+      .get('/api/{{id}}/todos')
+      .expect(200, {
+        items: [createdTodoItem],
+      });
+
+    await request(server)
+      .get(`/api/{{id}}/todos/${createdTodoItem.id}`)
+      .expect(200, createdTodoItem);
+  });
+
+  it('should create TODO item with catalog information', async () => {
+    const { server } = await startTestBackend({
+      features: [
+        {{pluginVar}},
+        catalogServiceMock.factory({
+          entities: [
+            {
+              apiVersion: 'backstage.io/v1alpha1',
+              kind: 'Component',
+              metadata: {
+                name: 'my-component',
+                namespace: 'default',
+                title: 'My Component',
+              },
+              spec: {
+                type: 'service',
+                owner: 'me',
+              },
+            },
+          ],
+        }),
+      ],
+    });
+
+    const createRes = await request(server)
+      .post('/api/{{id}}/todos')
+      .send({ title: 'My Todo', entityRef: 'component:default/my-component' });
+
+    expect(createRes.status).toBe(201);
+    expect(createRes.body).toEqual({
+      id: expect.any(String),
+      title: '[My Component] My Todo',
+      createdBy: mockCredentials.user().principal.userEntityRef,
+      createdAt: expect.any(String),
+    });
+  });
+});

package/templates/default-backend-plugin/src/plugin.ts.hbs

@@ -2,7 +2,9 @@ import {
   coreServices,
   createBackendPlugin,
 } from '@backstage/backend-plugin-api';
-import { createRouter } from './service/router';
+import { createRouter } from './router';
+import { catalogServiceRef } from '@backstage/plugin-catalog-node/alpha';
+import { createTodoListService } from './services/TodoListService';
 
 /**
  * {{pluginVar}} backend plugin
@@ -14,25 +16,25 @@ export const {{pluginVar}} = createBackendPlugin({
   register(env) {
     env.registerInit({
       deps: {
-        httpRouter: coreServices.httpRouter,
         logger: coreServices.logger,
-        config: coreServices.rootConfig,
+        auth: coreServices.auth,
+        httpAuth: coreServices.httpAuth,
+        httpRouter: coreServices.httpRouter,
+        catalog: catalogServiceRef,
       },
-      async init({
-        httpRouter,
-        logger,
-        config,
-      }) {
+      async init({ logger, auth, httpAuth, httpRouter, catalog }) {
+        const todoListService = await createTodoListService({
+          logger,
+          auth,
+          catalog,
+        });
+
         httpRouter.use(
           await createRouter({
-            logger,
-            config,
+            httpAuth,
+            todoListService,
           }),
         );
-        httpRouter.addAuthPolicy({
-          path: '/health',
-          allow: 'unauthenticated',
-        });
       },
     });
   },

package/templates/default-backend-plugin/src/router.test.ts

@@ -0,0 +1,67 @@
+import {
+  mockCredentials,
+  mockErrorHandler,
+  mockServices,
+} from '@backstage/backend-test-utils';
+import express from 'express';
+import request from 'supertest';
+
+import { createRouter } from './router';
+import { TodoListService } from './services/TodoListService/types';
+
+const mockTodoItem = {
+  title: 'Do the thing',
+  id: '123',
+  createdBy: mockCredentials.user().principal.userEntityRef,
+  createdAt: new Date().toISOString(),
+};
+
+// TEMPLATE NOTE:
+// Testing the router directly allows you to write a unit test that mocks the provided options.
+describe('createRouter', () => {
+  let app: express.Express;
+  let todoListService: jest.Mocked<TodoListService>;
+
+  beforeEach(async () => {
+    todoListService = {
+      createTodo: jest.fn(),
+      listTodos: jest.fn(),
+      getTodo: jest.fn(),
+    };
+    const router = await createRouter({
+      httpAuth: mockServices.httpAuth(),
+      todoListService,
+    });
+    app = express();
+    app.use(router);
+    app.use(mockErrorHandler());
+  });
+
+  it('should create a TODO', async () => {
+    todoListService.createTodo.mockResolvedValue(mockTodoItem);
+
+    const response = await request(app).post('/todos').send({
+      title: 'Do the thing',
+    });
+
+    expect(response.status).toBe(201);
+    expect(response.body).toEqual(mockTodoItem);
+  });
+
+  it('should not allow unauthenticated requests to create a TODO', async () => {
+    todoListService.createTodo.mockResolvedValue(mockTodoItem);
+
+    // TEMPLATE NOTE:
+    // The HttpAuth mock service considers all requests to be authenticated as a
+    // mock user by default. In order to test other cases we need to explicitly
+    // pass an authorization header with mock credentials.
+    const response = await request(app)
+      .post('/todos')
+      .set('Authorization', mockCredentials.none.header())
+      .send({
+        title: 'Do the thing',
+      });
+
+    expect(response.status).toBe(401);
+  });
+});

package/templates/default-backend-plugin/src/router.ts

@@ -0,0 +1,51 @@
+import { HttpAuthService } from '@backstage/backend-plugin-api';
+import { InputError } from '@backstage/errors';
+import { z } from 'zod';
+import express from 'express';
+import Router from 'express-promise-router';
+import { TodoListService } from './services/TodoListService/types';
+
+export async function createRouter({
+  httpAuth,
+  todoListService,
+}: {
+  httpAuth: HttpAuthService;
+  todoListService: TodoListService;
+}): Promise<express.Router> {
+  const router = Router();
+  router.use(express.json());
+
+  // TEMPLATE NOTE:
+  // Zod is a powerful library for data validation and recommended in particular
+  // for user-defined schemas. In this case we use it for input validation too.
+  //
+  // If you want to define a schema for your API we recommend using Backstage's
+  // OpenAPI tooling: https://backstage.io/docs/next/openapi/01-getting-started
+  const todoSchema = z.object({
+    title: z.string(),
+    entityRef: z.string().optional(),
+  });
+
+  router.post('/todos', async (req, res) => {
+    const parsed = todoSchema.safeParse(req.body);
+    if (!parsed.success) {
+      throw new InputError(parsed.error.toString());
+    }
+
+    const result = await todoListService.createTodo(parsed.data, {
+      credentials: await httpAuth.credentials(req, { allow: ['user'] }),
+    });
+
+    res.status(201).json(result);
+  });
+
+  router.get('/todos', async (_req, res) => {
+    res.json(await todoListService.listTodos());
+  });
+
+  router.get('/todos/:id', async (req, res) => {
+    res.json(await todoListService.getTodo({ id: req.params.id }));
+  });
+
+  return router;
+}

package/templates/default-backend-plugin/src/services/TodoListService/createTodoListService.ts

@@ -0,0 +1,100 @@
+import { AuthService, LoggerService } from '@backstage/backend-plugin-api';
+import { NotFoundError } from '@backstage/errors';
+import { catalogServiceRef } from '@backstage/plugin-catalog-node/alpha';
+import crypto from 'node:crypto';
+import { TodoItem, TodoListService } from './types';
+
+// TEMPLATE NOTE:
+// This is a simple in-memory todo list store. It is recommended to use a
+// database to store data in a real application. See the database service
+// documentation for more information on how to do this:
+// https://backstage.io/docs/backend-system/core-services/database
+export async function createTodoListService({
+  auth,
+  logger,
+  catalog,
+}: {
+  auth: AuthService;
+  logger: LoggerService;
+  catalog: typeof catalogServiceRef.T;
+}): Promise<TodoListService> {
+  logger.info('Initializing TodoListService');
+
+  const storedTodos = new Array<TodoItem>();
+
+  return {
+    async createTodo(input, options) {
+      let title = input.title;
+
+      // TEMPLATE NOTE:
+      // A common pattern for Backstage plugins is to pass an entity reference
+      // from the frontend to then fetch the entire entity from the catalog in the
+      // backend plugin.
+      if (input.entityRef) {
+        // TEMPLATE NOTE:
+        // Cross-plugin communication uses service-to-service authentication. The
+        // `AuthService` lets you generate a token that is valid for communication
+        // with the target plugin only. You must also provide credentials for the
+        // identity that you are making the request on behalf of.
+        //
+        // If you want to make a request using the plugin backend's own identity,
+        // you can access it via the `auth.getOwnServiceCredentials()` method.
+        // Beware that this bypasses any user permission checks.
+        const { token } = await auth.getPluginRequestToken({
+          onBehalfOf: options.credentials,
+          targetPluginId: 'catalog',
+        });
+        const entity = await catalog.getEntityByRef(input.entityRef, {
+          token,
+        });
+        if (!entity) {
+          throw new NotFoundError(
+            `No entity found for ref '${input.entityRef}'`,
+          );
+        }
+
+        // TEMPLATE NOTE:
+        // Here you could read any form of data from the entity. A common use case
+        // is to read the value of a custom annotation for your plugin. You can
+        // read more about how to add custom annotations here:
+        // https://backstage.io/docs/features/software-catalog/extending-the-model#adding-a-new-annotation
+        //
+        // In this example we just use the entity title to decorate the todo item.
+
+        const entityDisplay = entity.metadata.title ?? input.entityRef;
+        title = `[${entityDisplay}] ${input.title}`;
+      }
+
+      const id = crypto.randomUUID();
+      const createdBy = options.credentials.principal.userEntityRef;
+      const newTodo = {
+        title,
+        id,
+        createdBy,
+        createdAt: new Date().toISOString(),
+      };
+
+      storedTodos.push(newTodo);
+
+      // TEMPLATE NOTE:
+      // The second argument of the logger methods can be used to pass
+      // structured metadata. You can read more about the logger service here:
+      // https://backstage.io/docs/backend-system/core-services/logger
+      logger.info('Created new todo item', { id, title, createdBy });
+
+      return newTodo;
+    },
+
+    async listTodos() {
+      return { items: Array.from(storedTodos) };
+    },
+
+    async getTodo(request: { id: string }) {
+      const todo = storedTodos.find(item => item.id === request.id);
+      if (!todo) {
+        throw new NotFoundError(`No todo found with id '${request.id}'`);
+      }
+      return todo;
+    },
+  };
+}

package/templates/default-backend-plugin/src/services/TodoListService/index.ts

@@ -0,0 +1 @@
+export { createTodoListService } from './createTodoListService';

package/templates/default-backend-plugin/src/services/TodoListService/types.ts

@@ -0,0 +1,27 @@
+import {
+  BackstageCredentials,
+  BackstageUserPrincipal,
+} from '@backstage/backend-plugin-api';
+
+export interface TodoItem {
+  title: string;
+  id: string;
+  createdBy: string;
+  createdAt: string;
+}
+
+export interface TodoListService {
+  createTodo(
+    input: {
+      title: string;
+      entityRef?: string;
+    },
+    options: {
+      credentials: BackstageCredentials<BackstageUserPrincipal>;
+    },
+  ): Promise<TodoItem>;
+
+  listTodos(): Promise<{ items: TodoItem[] }>;
+
+  getTodo(request: { id: string }): Promise<TodoItem>;
+}

package/templates/scaffolder-module/package.json.hbs

@@ -29,10 +29,12 @@
     "postpack": "backstage-cli package postpack"
   },
   "dependencies": {
+    "@backstage/backend-plugin-api": "{{versionQuery '@backstage/backend-plugin-api'}}",
     "@backstage/plugin-scaffolder-node": "{{versionQuery '@backstage/plugin-scaffolder-node'}}"
   },
   "devDependencies": {
-    "@backstage/cli": "{{versionQuery '@backstage/cli'}}"
+    "@backstage/cli": "{{versionQuery '@backstage/cli'}}",
+    "@backstage/plugin-scaffolder-node-test-utils": "{{versionQuery '@backstage/plugin-scaffolder-node-test-utils'}}"
   },
   "files": [
     "dist"

package/templates/scaffolder-module/src/actions/example.test.ts

@@ -0,0 +1,24 @@
+import { createExampleAction } from './example';
+import {createMockActionContext} from '@backstage/plugin-scaffolder-node-test-utils'
+
+describe('createExampleAction', () => {
+  it('should call action', async () => {
+    const action = createExampleAction();
+
+    await expect(action.handler(createMockActionContext({
+      input: {
+        myParameter: 'test',
+      },
+    }))).resolves.toBeUndefined()
+  });
+
+  it('should fail when passing foo', async () => {
+    const action = createExampleAction();
+
+    await expect(action.handler(createMockActionContext({
+      input: {
+        myParameter: 'foo',
+      },
+    }))).rejects.toThrow("myParameter cannot be 'foo'")
+  });
+});

package/templates/scaffolder-module/src/actions/{example/example.ts → example.ts}

@@ -9,14 +9,14 @@ import { createTemplateAction } from '@backstage/plugin-scaffolder-node';
  *
  * @public
  */
-export function createAcmeExampleAction() {
+export function createExampleAction() {
   // For more information on how to define custom actions, see
   //   https://backstage.io/docs/features/software-templates/writing-custom-actions
   return createTemplateAction<{
     myParameter: string;
   }>({
     id: 'acme:example',
-    description: 'Runs Yeoman on an installed Yeoman generator',
+    description: 'Runs an example action',
     schema: {
       input: {
         type: 'object',
@@ -24,7 +24,7 @@ export function createAcmeExampleAction() {
         properties: {
           myParameter: {
             title: 'An example parameter',
-            description: 'This is the schema for our example parameter',
+            description: "This is an example parameter, don't set it to foo",
             type: 'string',
           },
         },
@@ -35,6 +35,10 @@ export function createAcmeExampleAction() {
         `Running example template with parameters: ${ctx.input.myParameter}`,
       );
 
+      if (ctx.input.myParameter === 'foo') {
+        throw new Error(`myParameter cannot be 'foo'`);
+      }
+
       await new Promise(resolve => setTimeout(resolve, 1000));
     },
   });

package/templates/scaffolder-module/src/index.ts.hbs

@@ -5,4 +5,4 @@
  * @packageDocumentation
  */
 
-export * from './actions';
+export { scaffolderModule as default } from './module';

package/templates/scaffolder-module/src/{actions/example/module.ts → module.ts}

@@ -1,12 +1,12 @@
 import { createBackendModule } from "@backstage/backend-plugin-api";
 import { scaffolderActionsExtensionPoint  } from '@backstage/plugin-scaffolder-node/alpha';
-import { createAcmeExampleAction } from "./example";
+import { createExampleAction } from "./actions/example";
 
 /**
  * A backend module that registers the action into the scaffolder
  */
 export const scaffolderModule = createBackendModule({
-  moduleId: 'acme:example',
+  moduleId: 'example-action',
   pluginId: 'scaffolder',
   register({ registerInit }) {
     registerInit({
@@ -14,7 +14,7 @@ export const scaffolderModule = createBackendModule({
         scaffolderActions: scaffolderActionsExtensionPoint
       },
       async init({ scaffolderActions}) {
-        scaffolderActions.addActions(createAcmeExampleAction());
+        scaffolderActions.addActions(createExampleAction());
       }
     });
   },

package/dist/lib/bundler/LinkedPackageResolvePlugin.cjs.js

@@ -1,47 +0,0 @@
-'use strict';
-
-var path = require('path');
-var cliCommon = require('@backstage/cli-common');
-
-class LinkedPackageResolvePlugin {
-  constructor(targetModules, packages) {
-    this.targetModules = targetModules;
-    this.packages = packages;
-  }
-  apply(resolver) {
-    resolver.hooks.resolve.tapAsync(
-      "LinkedPackageResolvePlugin",
-      (data, context, callback) => {
-        const pkg = this.packages.find(
-          (pkge) => data.path && cliCommon.isChildPath(pkge.dir, data.path)
-        );
-        if (!pkg) {
-          callback();
-          return;
-        }
-        const modulesLocation = path.resolve(
-          this.targetModules,
-          pkg.packageJson.name
-        );
-        const newContext = data.context?.issuer ? {
-          ...data.context,
-          issuer: data.context.issuer.replace(pkg.dir, modulesLocation)
-        } : data.context;
-        resolver.doResolve(
-          resolver.hooks.resolve,
-          {
-            ...data,
-            context: newContext,
-            path: data.path && data.path.replace(pkg.dir, modulesLocation)
-          },
-          `resolve ${data.request} in ${modulesLocation}`,
-          context,
-          callback
-        );
-      }
-    );
-  }
-}
-
-exports.LinkedPackageResolvePlugin = LinkedPackageResolvePlugin;
-//# sourceMappingURL=LinkedPackageResolvePlugin.cjs.js.map

package/dist/lib/bundler/backend.cjs.js

@@ -1,36 +0,0 @@
-'use strict';
-
-var webpack = require('webpack');
-var config = require('./config.cjs.js');
-var paths = require('./paths.cjs.js');
-
-function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
-
-var webpack__default = /*#__PURE__*/_interopDefaultCompat(webpack);
-
-async function serveBackend(options) {
-  const paths$1 = paths.resolveBundlingPaths(options);
-  const config$1 = await config.createBackendConfig(paths$1, {
-    ...options,
-    isDev: true
-  });
-  process.env.NODE_ENV = "development";
-  const compiler = webpack__default.default(config$1, (err) => {
-    if (err) {
-      console.error(err);
-    } else console.log("Build succeeded");
-  });
-  const waitForExit = async () => {
-    for (const signal of ["SIGINT", "SIGTERM"]) {
-      process.on(signal, () => {
-        compiler.close(() => process.exit());
-      });
-    }
-    return new Promise(() => {
-    });
-  };
-  return waitForExit;
-}
-
-exports.serveBackend = serveBackend;
-//# sourceMappingURL=backend.cjs.js.map

package/templates/default-backend-plugin/dev/index.ts

@@ -1,9 +0,0 @@
-import { createBackend } from '@backstage/backend-defaults';
-
-const backend = createBackend();
-
-backend.add(import('@backstage/plugin-auth-backend'));
-backend.add(import('@backstage/plugin-auth-backend-module-guest-provider'));
-backend.add(import('../src'));
-
-backend.start();

package/templates/default-backend-plugin/src/service/router.test.ts

@@ -1,30 +0,0 @@
-import { mockServices } from '@backstage/backend-test-utils';
-import express from 'express';
-import request from 'supertest';
-
-import { createRouter } from './router';
-
-describe('createRouter', () => {
-  let app: express.Express;
-
-  beforeAll(async () => {
-    const router = await createRouter({
-      logger: mockServices.logger.mock(),
-      config: mockServices.rootConfig(),
-    });
-    app = express().use(router);
-  });
-
-  beforeEach(() => {
-    jest.resetAllMocks();
-  });
-
-  describe('GET /health', () => {
-    it('returns ok', async () => {
-      const response = await request(app).get('/health');
-
-      expect(response.status).toEqual(200);
-      expect(response.body).toEqual({ status: 'ok' });
-    });
-  });
-});