feat(scaffolder): create custom action for adding timestamp to templates

Author: debsmita1

plugins/scaffolder-timestamp-action/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

plugins/scaffolder-timestamp-action/README.md

@@ -0,0 +1,78 @@
+# Timestamp custom action for Scaffolder Backstage
+
+The timestamp module for [@backstage/plugin-scaffolder-backend](https://www.npmjs.com/package/@backstage/plugin-scaffolder-backend).
+
+## For administrators
+
+### Installation
+
+#### Procedure
+
+1. Install the Timestamp custom action plugin using the following command:
+
+   ```console
+   yarn workspace backend add @janus-idp/backstage-scaffolder-backend-module-timestamp
+   ```
+
+2. Integrate the custom action in the `packages/backend/src/plugins/scaffolder.ts`:
+
+- Install the `@backstage/integration` package using the following command:
+
+```console
+yarn workspace backend add @backstage/integration
+```
+
+- ```ts title="packages/backend/src/plugins/scaffolder.ts"
+
+  import { CatalogClient } from '@backstage/catalog-client';
+  /* highlight-add-start */
+  import { ScmIntegrations } from '@backstage/integration';
+  import {
+  createBuiltinActions,
+  createRouter,
+  } from '@backstage/plugin-scaffolder-backend';
+  import { createTimestampAction } from '@janus-idp/backstage-scaffolder-backend-module-timestamp';
+  /* highlight-add-end */
+  ...
+
+  export default async function createPlugin(
+  const catalogClient = new CatalogClient({
+      discoveryApi: env.discovery,
+  });
+
+  /* highlight-add-start */
+  const integrations = ScmIntegrations.fromConfig(env.config);
+
+  const builtInActions = createBuiltinActions({
+      integrations: integrations as any,
+      catalogClient,
+      config: env.config,
+      reader: env.reader,
+  });
+  const actions = [...builtInActions, createTimestampAction()];
+  /* highlight-add-end */
+
+
+  return await createRouter({
+  /* highlight-add-next-line */
+  actions,
+  logger: env.logger,
+  ...
+  });
+  ```
+
+3. Add the **catalog:timestamping** custom action in your template yaml after the `Fetch Skeleton + Template` step to annotate the catalog-info.yaml skeleton with the current timestamp:
+
+   ```tsx title="template.yaml"
+   - id: template
+     name: Fetch Skeleton + Template
+     action: fetch:template
+     ...
+
+   /* highlight-add-start */
+   - id: timestamp
+     name: Add Timestamp to catalog-info.yaml
+     action: catalog:timestamping
+   /* highlight-add-end */
+
+   ```

plugins/scaffolder-timestamp-action/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@janus-idp/backstage-scaffolder-backend-module-timestamp",
+  "description": "The timestamp module for @backstage/plugin-scaffolder-backend",
+  "version": "0.1.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "private": true,
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "backend-plugin-module"
+  },
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "dependencies": {
+    "@backstage/plugin-scaffolder-node": "^0.4.2"
+  },
+  "devDependencies": {
+    "@backstage/backend-common": "^0.21.6",
+    "@backstage/cli": "0.26.2"
+  },
+  "files": [
+    "dist"
+  ]
+}

plugins/scaffolder-timestamp-action/src/actions/index.ts

@@ -0,0 +1 @@
+export * from './timestamp';

plugins/scaffolder-timestamp-action/src/actions/timestamp/getCurrentTimestamp.ts

@@ -0,0 +1,25 @@
+export const getCurrentTimestamp = () => {
+  const dateObj = new Date(Date.now());
+
+  const time =
+    dateObj.getHours() > 12
+      ? `${dateObj.getHours() - 12}:${
+          dateObj.getMinutes() < 10
+            ? '0' + dateObj.getMinutes()
+            : dateObj.getMinutes()
+        }:${
+          dateObj.getSeconds() < 10
+            ? '0' + dateObj.getSeconds()
+            : dateObj.getSeconds()
+        } PM`
+      : `${dateObj.getHours()}:${
+          dateObj.getMinutes() < 10
+            ? '0' + dateObj.getMinutes()
+            : dateObj.getMinutes()
+        }:${
+          dateObj.getSeconds() < 10
+            ? '0' + dateObj.getSeconds()
+            : dateObj.getSeconds()
+        } AM`;
+  return `${dateObj.toLocaleDateString()}, ${time}`;
+};

plugins/scaffolder-timestamp-action/src/actions/timestamp/index.ts

@@ -0,0 +1 @@
+export * from './timestamp';

plugins/scaffolder-timestamp-action/src/actions/timestamp/mocks/catalog-info.yaml

@@ -0,0 +1,13 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: ${{values.component_id | dump}}
+  description: ${{values.description | dump}}
+  annotations:
+    github.com/project-slug: ${{values.destination.owner + "/" + values.destination.repo}}
+    backstage.io/techdocs-ref: dir:.
+    backstage.io/createdAt: 4/26/2024, 3:22:25 PM
+spec:
+  type: website
+  lifecycle: experimental
+  owner: ${{values.owner | dump}}

plugins/scaffolder-timestamp-action/src/actions/timestamp/timestamp.test.ts

@@ -0,0 +1,33 @@
+import { getVoidLogger } from '@backstage/backend-common';
+
+import { PassThrough } from 'stream';
+
+import { createTimestampAction } from './timestamp';
+
+describe('catalog:timestamping', () => {
+  afterEach(() => {
+    jest.resetAllMocks();
+  });
+
+  it('should call action', async () => {
+    const action = createTimestampAction();
+
+    const logger = getVoidLogger();
+    jest.spyOn(logger, 'info');
+
+    await action.handler({
+      workspacePath: 'src/actions/timestamp/mocks',
+      logger,
+      logStream: new PassThrough(),
+      output: jest.fn(),
+      createTemporaryDirectory() {
+        // Usage of createMockDirectory is recommended for testing of filesystem operations
+        throw new Error('Not implemented');
+      },
+    } as any);
+
+    expect(logger.info).toHaveBeenCalledWith(
+      'Annotating catalog-info.yaml with current timestamp',
+    );
+  });
+});

plugins/scaffolder-timestamp-action/src/actions/timestamp/timestamp.ts

@@ -0,0 +1,47 @@
+import { resolveSafeChildPath } from '@backstage/backend-common';
+import { Entity } from '@backstage/catalog-model';
+import { createTemplateAction } from '@backstage/plugin-scaffolder-node';
+
+import * as fs from 'fs-extra';
+import * as yaml from 'yaml';
+
+import { getCurrentTimestamp } from './getCurrentTimestamp';
+
+/**
+ * Creates a new `catalog:timestamping` Scaffolder action to annotate catalog-info.yaml with creation timestamp.
+ *
+ */
+
+export const createTimestampAction = () => {
+  return createTemplateAction({
+    id: 'catalog:timestamping',
+    description:
+      'Creates a new `catalog:timestamping` Scaffolder action to annotate scaffolded entities with creation timestamp.',
+
+    async handler(ctx) {
+      const entitySkeleton = await fs.readFile(
+        resolveSafeChildPath(ctx.workspacePath, './catalog-info.yaml'),
+        'utf8',
+      );
+
+      const entity: Entity = yaml.parse(entitySkeleton);
+
+      var result = yaml.stringify({
+        ...entity,
+        metadata: {
+          ...entity.metadata,
+          annotations: {
+            ...entity.metadata.annotations,
+            'backstage.io/createdAt': getCurrentTimestamp(),
+          },
+        },
+      });
+      ctx.logger.info(`Annotating catalog-info.yaml with current timestamp`);
+      await fs.writeFile(
+        resolveSafeChildPath(ctx.workspacePath, './catalog-info.yaml'),
+        result,
+        'utf8',
+      );
+    },
+  });
+};

plugins/scaffolder-timestamp-action/src/index.ts

@@ -0,0 +1,8 @@
+/***/
+/**
+ * The timestamp module for @backstage/plugin-scaffolder-backend.
+ *
+ * @packageDocumentation
+ */
+
+export * from './actions';