Init

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist-types/

README.md

@@ -1 +1,198 @@
-# backstage-pagespeed-plugin
+# @rsc-labs/highlights-plugin
+
+<img src='./docs/highlighter.png' width='100' height='150' alt='Highlights screenshot'>
+
+Backstage Highlights Plugin is configurable and customizable plugin for viewing the most important information about your entity.
+
+### Why?
+
+We have a lot information from different plugins and also in Overview tab, but sometimes:
+- we want to see some short summary from couple of plugins
+- we do not want to jump to every card to get such information
+
+The "Highlights" shall provide you possibility to create such small, useful view.
+
+# Getting started
+
+If you haven't already, check out the [Backstage docs](https://backstage.io/docs/getting-started/) and create a Backstage application with
+```
+npx @backstage/create-app
+```
+
+Then, you will need to install and configure the highlights plugins for the frontend and the backend.
+
+# Frontend plugin
+
+Install:
+```bash
+cd packages/app
+yarn add @rsc-labs/backstage-highlights-plugin
+```
+
+### Card:
+
+Add the card to `packages/app/src/components/catalog/EntityPage.tsx`:
+```jsx
+// import:
+import { EntityHighlightsCard } from '@rsc-labs/backstage-highlights-plugin';
+
+// use it in entity view
+const overviewContent = (
+  <Grid container
+  ...
+    <Grid item md={12} xs={12}>
+      <<EntityHighlightsCard />
+    </Grid>
+  </Grid>
+)
+```
+
+For the best UX we <b> strongly recommend </b> to use as much horizontal space as possible. Thanks to that you will have your highlights on top of your page as a bar.
+
+<img src='./docs/built_in_example.PNG' alt='Built-in example'>
+
+Of course, you can also make it smaller and near the other card.
+
+### Built-in fields
+
+At this moment, "highlights plugin" comes with built-in support of basic information about Git. As you can see in above picture, we support following fields:
+- latest tag
+- number of branches
+- latest commit
+- date of latest commit
+- author of latest commit
+- clone button
+
+You can click at the field and get more information. For example, when you click on latest tag you will get longer history:
+
+<img src='./docs/commit_table.PNG' alt='Built-in example'>
+
+Other fields can have similar functionality, but it depends on the provider (Github API provides more information)
+
+At this moment built-in fields supports Github and Gitlab (see: Configuration of Backend).
+
+## Frontend configuration
+
+By default, you can use EntityHighlights without any parameter - it gives you above built-in fields.
+However, you may want change a behaviour or implement your custom fields.
+Below you can find an interface:
+
+```typescript
+/** @public */
+export interface EntityHighlightsProps {
+    fields? : EHighlightFields[],
+    customFields?: HighlightCustomField[]
+}
+```
+
+1) fields - this parameter describes what built-in you would like to see and in what order
+2) customFields - this parameter can let you define your own field. Every custom field contains:
+    - fieldLabel - it is a title of the field (you can see it in built-in fields). It is optional parameter as your field can be also without a title (example: Clone button in built-in fields)
+    - field - it is simple React component
+
+# Backend plugin
+
+Install:
+```bash
+cd packages/backend
+yarn add @rsc-labs/backstage-highlights-plugin-backend
+```
+
+Create a file `packages/backend/src/plugins/highlights.ts`:
+```typescript
+import {
+    createRouter,
+  } from '@rsc-labs/backstage-highlights-plugin-backend';
+  import { Router } from 'express';
+  import { PluginEnvironment } from '../types';
+
+  export default async function createPlugin(
+    env: PluginEnvironment,
+  ): Promise<Router> {
+    return await createRouter({
+      discovery: env.discovery,
+      tokenManager: env.tokenManager,
+      logger: env.logger,
+      config: env.config
+    });
+  }
+```
+
+Add the plugin to `packages/backend/src/index.ts`:
+```typescript
+// import:
+import highlights from './plugins/highlights';
+...
+
+async function main() {
+  ...
+  // add env
+  const highlightsEnv = useHotMemoize(module, () => createEnv('highlights'));
+  ...
+  // add to router
+  apiRouter.use('/highlights', await highlights(highlightsEnv));
+  ...
+}
+```
+
+## Catalog-info.yaml
+
+Backend plugin supports two providers - Github and Gitlab. They are providing information for built-in fields mentioned in Frontend plugin.
+Plugin uses following annotations from catalog-info.yaml:
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: example-website
+  annotations:
+    github.com/project-slug: rsc-labs/backstage-changelog-plugin
+    gitlab.com/project-slug: owner/project
+```
+
+Both annotations are supported (so your component can be in github or gitlab). In theory case if you have both annotations, github takes precedence.
+
+## App-config
+
+To have properly working Github or Gitlab, you need also provide information about token and potentially about base url.
+You have two options how to provide it
+1) Custom highlights configuration
+2) Integration configuration
+
+Below you can find implemented both options:
+```yaml
+highlights:
+  gitlab:
+    token: ${GITLAB_TOKEN}
+    apiBaseUrl: https://gitlab.com/api/v4
+  github:
+    token: ${GITHUB_TOKEN}
+
+integrations:
+  gitlab:
+      - token: ${GITLAB_TOKEN}
+  github:
+      - token: ${GITHUB_TOKEN}
+```
+
+If provided, "highlights" configuration takes precendece over "integrations".
+<b>Note:</b> "highlights" configuration requires providing "apiBaseUrl", while it is not needed in "integrations" (if you are using default one)
+
+
+## TODO
+
+[ ] Unit tests
+
+[ ] More fields to support
+
+## Contribution
+
+Contributions are welcome and they are greatly appreciated!
+
+## License
+
+Licensed under the Mozilla Public License, Version 2.0: https://www.mozilla.org/en-US/MPL/2.0/
+
+---
+
+© 2023 RSC https://rsoftcon.com/

app-config.yaml

@@ -0,0 +1,107 @@
+app:
+  title: Scaffolded Backstage App
+  baseUrl: http://localhost:3000
+
+organization:
+  name: My Company
+
+backend:
+  # Used for enabling authentication, secret is shared by all backend plugins
+  # See https://backstage.io/docs/auth/service-to-service-auth for
+  # information on the format
+  # auth:
+  #   keys:
+  #     - secret: ${BACKEND_SECRET}
+  baseUrl: http://localhost:7007
+  listen:
+    port: 7007
+    # Uncomment the following host directive to bind to specific interfaces
+    # host: 127.0.0.1
+  csp:
+    connect-src: ["'self'", 'http:', 'https:']
+    # Content-Security-Policy directives follow the Helmet format: https://helmetjs.github.io/#reference
+    # Default Helmet Content-Security-Policy values can be removed by setting the key to false
+  cors:
+    origin: http://localhost:3000
+    methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
+    credentials: true
+  # This is for local development only, it is not recommended to use this in production
+  # The production database configuration is stored in app-config.production.yaml
+  database:
+    client: better-sqlite3
+    connection: ':memory:'
+  # workingDirectory: /tmp # Use this to configure a working directory for the scaffolder, defaults to the OS temp-dir
+
+highlights:
+  gitlab:
+    token: ${GITLAB_TOKEN}
+    apiBaseUrl: https://gitlab.com/api/v4
+  github:
+    token: ${GITHUB_TOKEN}
+
+integrations:
+  gitlab:
+    - host: gitlab.com
+      token: ${GITLAB_TOKEN}
+  github:
+    - host: github.com
+      token: ${GITHUB_TOKEN}
+
+proxy:
+  ### Example for how to add a proxy endpoint for the frontend.
+  ### A typical reason to do this is to handle HTTPS and CORS for internal services.
+  # endpoints:
+  #   '/test':
+  #     target: 'https://example.com'
+  #     changeOrigin: true
+
+# Reference documentation http://backstage.io/docs/features/techdocs/configuration
+# Note: After experimenting with basic setup, use CI/CD to generate docs
+# and an external cloud storage when deploying TechDocs for production use-case.
+# https://backstage.io/docs/features/techdocs/how-to-guides#how-to-migrate-from-techdocs-basic-to-recommended-deployment-approach
+techdocs:
+  builder: 'local' # Alternatives - 'external'
+  generator:
+    runIn: 'docker' # Alternatives - 'local'
+  publisher:
+    type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.
+
+auth:
+  # see https://backstage.io/docs/auth/ to learn about auth providers
+  providers: {}
+
+scaffolder:
+  # see https://backstage.io/docs/features/software-templates/configuration for software template options
+
+catalog:
+  import:
+    entityFilename: catalog-info.yaml
+    pullRequestBranchName: backstage-integration
+  rules:
+    - allow: [Component, System, API, Resource, Location]
+  locations:
+    # Local example data, file locations are relative to the backend process, typically `packages/backend`
+    - type: file
+      target: ../../examples/entities.yaml
+
+    # Local example template
+    - type: file
+      target: ../../examples/template/template.yaml
+      rules:
+        - allow: [Template]
+
+    # Local example organizational data
+    - type: file
+      target: ../../examples/org.yaml
+      rules:
+        - allow: [User, Group]
+
+    ## Uncomment these lines to add more example data
+    # - type: url
+    #   target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all.yaml
+
+    ## Uncomment these lines to add an example org
+    # - type: url
+    #   target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/acme-corp.yaml
+    #   rules:
+    #     - allow: [User, Group]

backstage.json

@@ -0,0 +1,3 @@
+{
+  "version": "1.18.0"
+}

catalog-info.yaml

@@ -0,0 +1,15 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: backstage-changelog
+  description: An example of a Backstage application.
+  annotations:
+    changelog-ref: dir:.
+  # Example for optional annotations
+  # annotations:
+  #   github.com/project-slug: backstage/backstage
+  #   backstage.io/techdocs-ref: dir:.
+spec:
+  type: website
+  owner: [email protected]
+  lifecycle: experimental

docs/highlighter.png:Zone.Identifier

@@ -0,0 +1,4 @@
+[ZoneTransfer]
+ZoneId=3
+ReferrerUrl=https://pixabay.com/pl/vectors/zakre%C5%9Blacz-znacznik-d%C5%82ugopis-156032/
+HostUrl=https://pixabay.com/get/g0fb2e49e6974c206953a57e0cc5378183a318e0ef53fb18473af7463149a0aa753b5cfca9c3e39a4e87d747dc0e2ab7c2363c7d4cf13c1bef70fdb779225e8b83643b356bf5ab0ae36127dbc055e9fcf_1280.png?attachment=

examples/entities.yaml

@@ -0,0 +1,45 @@
+---
+# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-system
+apiVersion: backstage.io/v1alpha1
+kind: System
+metadata:
+  name: examples
+spec:
+  owner: guests
+---
+# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-component
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: example-website
+  annotations:
+    github.com/project-slug: rsc-labs/backstage-changelog-plugin
+    gitlab.com/project-slug: mordivgor/backstage-gitinfo-plugin 
+
+spec:
+  type: website
+  lifecycle: experimental
+  owner: guests
+  system: examples
+  providesApis: [example-grpc-api]
+---
+# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-api
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: example-grpc-api
+spec:
+  type: grpc
+  lifecycle: experimental
+  owner: guests
+  system: examples
+  definition: |
+    syntax = "proto3";
+
+    service Exampler {
+      rpc Example (ExampleMessage) returns (ExampleMessage) {};
+    }
+
+    message ExampleMessage {
+      string example = 1;
+    };