cli: initial cli-plugin-api

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor

packages/cli/package.json

@@ -50,6 +50,7 @@
     "@backstage/catalog-model": "workspace:^",
     "@backstage/cli-common": "workspace:^",
     "@backstage/cli-node": "workspace:^",
+    "@backstage/cli-plugin-api": "workspace:^",
     "@backstage/config": "workspace:^",
     "@backstage/config-loader": "workspace:^",
     "@backstage/errors": "workspace:^",

packages/cli/src/modules/build/index.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { createCliPlugin } from '../../wiring/factory';
+import { createCliPlugin } from '@backstage/cli-plugin-api';
 
 export const buildPlugin = createCliPlugin({
   pluginId: 'build',

packages/cli/src/modules/config/commands/docs.ts

@@ -21,7 +21,7 @@ import { JSONSchema7 as JSONSchema } from 'json-schema';
 import openBrowser from 'react-dev-utils/openBrowser';
 import chalk from 'chalk';
 import { loadCliConfig } from '../lib/config';
-import type { CommandContext } from '../../../wiring/types';
+import type { CommandContext } from '@backstage/cli-plugin-api';
 
 const DOCS_URL = 'https://config.backstage.io';
 

packages/cli/src/modules/config/commands/print.ts

@@ -19,7 +19,7 @@ import { stringify as stringifyYaml } from 'yaml';
 import { AppConfig, ConfigReader } from '@backstage/config';
 import { loadCliConfig } from '../lib/config';
 import { ConfigSchema, ConfigVisibility } from '@backstage/config-loader';
-import type { CommandContext } from '../../../wiring/types';
+import type { CommandContext } from '@backstage/cli-plugin-api';
 
 export default async ({ args, info }: CommandContext) => {
   const {

packages/cli/src/modules/config/commands/schema.ts

@@ -20,7 +20,7 @@ import { stringify as stringifyYaml } from 'yaml';
 import { loadCliConfig } from '../lib/config';
 import { JsonObject } from '@backstage/types';
 import { mergeConfigSchemas } from '@backstage/config-loader';
-import type { CommandContext } from '../../../wiring/types';
+import type { CommandContext } from '@backstage/cli-plugin-api';
 
 export default async ({ args, info }: CommandContext) => {
   const {

packages/cli/src/modules/config/commands/validate.ts

@@ -16,7 +16,7 @@
 
 import { cli } from 'cleye';
 import { loadCliConfig } from '../lib/config';
-import type { CommandContext } from '../../../wiring/types';
+import type { CommandContext } from '@backstage/cli-plugin-api';
 
 export default async ({ args, info }: CommandContext) => {
   const {

packages/cli/src/modules/config/index.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createCliPlugin } from '../../wiring/factory';
+import { createCliPlugin } from '@backstage/cli-plugin-api';
 
 export const configOption = [
   '--config <path>',

packages/cli/src/modules/create-github-app/index.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createCliPlugin } from '../../wiring/factory';
+import { createCliPlugin } from '@backstage/cli-plugin-api';
 
 export default createCliPlugin({
   pluginId: 'new',

packages/cli/src/modules/info/commands/info.ts

@@ -25,7 +25,7 @@ import {
 } from '@backstage/cli-node';
 import { minimatch } from 'minimatch';
 import fs from 'fs-extra';
-import type { CommandContext } from '../../../wiring/types';
+import type { CommandContext } from '@backstage/cli-plugin-api';
 
 /**
  * Attempts to read package.json from node_modules for a given package name.

packages/cli/src/modules/info/index.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createCliPlugin } from '../../wiring/factory';
+import { createCliPlugin } from '@backstage/cli-plugin-api';
 
 export default createCliPlugin({
   pluginId: 'info',

packages/cli/src/modules/lint/index.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createCliPlugin } from '../../wiring/factory';
+import { createCliPlugin } from '@backstage/cli-plugin-api';
 
 export default createCliPlugin({
   pluginId: 'lint',

packages/cli/src/modules/maintenance/index.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createCliPlugin } from '../../wiring/factory';
+import { createCliPlugin } from '@backstage/cli-plugin-api';
 
 export default createCliPlugin({
   pluginId: 'maintenance',

packages/cli/src/modules/migrate/index.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createCliPlugin } from '../../wiring/factory';
+import { createCliPlugin } from '@backstage/cli-plugin-api';
 
 export default createCliPlugin({
   pluginId: 'migrate',

packages/cli/src/modules/new/index.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createCliPlugin } from '../../wiring/factory';
+import { createCliPlugin } from '@backstage/cli-plugin-api';
 import { NotImplementedError } from '@backstage/errors';
 
 export default createCliPlugin({

packages/cli/src/modules/test/index.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createCliPlugin } from '../../wiring/factory';
+import { createCliPlugin } from '@backstage/cli-plugin-api';
 
 export default createCliPlugin({
   pluginId: 'test',

packages/cli/src/modules/translations/commands/export.ts

@@ -33,7 +33,7 @@ import {
   formatMessagePath,
   validatePattern,
 } from '../lib/messageFilePath';
-import type { CommandContext } from '../../../wiring/types';
+import type { CommandContext } from '@backstage/cli-plugin-api';
 
 export default async ({ args, info }: CommandContext) => {
   const {

packages/cli/src/modules/translations/commands/import.ts

@@ -28,7 +28,7 @@ import {
   createMessagePathParser,
   formatMessagePath,
 } from '../lib/messageFilePath';
-import type { CommandContext } from '../../../wiring/types';
+import type { CommandContext } from '@backstage/cli-plugin-api';
 
 interface ManifestRefEntry {
   package: string;

packages/cli/src/modules/translations/index.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createCliPlugin } from '../../wiring/factory';
+import { createCliPlugin } from '@backstage/cli-plugin-api';
 
 export default createCliPlugin({
   pluginId: 'translations',

packages/cli/src/wiring/CliInitializer.ts

@@ -15,12 +15,16 @@
  */
 
 import { CommandGraph } from './CommandGraph';
-import { BackstageCommand, CliFeature, OpaqueCliPlugin } from './types';
+import {
+  isCliPlugin,
+  initializeCliPlugin,
+  exitWithError,
+} from '@backstage/cli-plugin-api';
+import type { BackstageCommand, CliFeature } from '@backstage/cli-plugin-api';
 import { CommandRegistry } from './CommandRegistry';
 import { Command } from 'commander';
 import { version } from './version';
 import chalk from 'chalk';
-import { exitWithError } from './errors';
 import { ForwardedError } from '@backstage/errors';
 import { isPromise } from 'node:util/types';
 
@@ -53,9 +57,8 @@ export class CliInitializer {
   }
 
   async #register(feature: CliFeature) {
-    if (OpaqueCliPlugin.isType(feature)) {
-      const internal = OpaqueCliPlugin.toInternal(feature);
-      await internal.init(this.commandRegistry);
+    if (isCliPlugin(feature)) {
+      await initializeCliPlugin(feature, this.commandRegistry);
     } else {
       throw new Error(`Unsupported feature type: ${(feature as any).$$type}`);
     }

packages/cli/src/wiring/describeParentCallSite.ts

@@ -1,20 +0,0 @@
-/*
- * Copyright 2023 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.
- */
-
-// Single re-export to avoid doing this import in multiple places, but still
-// avoid duplicate declarations because this one is a bit tricky.
-// eslint-disable-next-line @backstage/no-relative-monorepo-imports
-export { describeParentCallSite } from '../../../frontend-plugin-api/src/routing/describeParentCallSite';

packages/cli/src/wiring/errors.ts

@@ -14,49 +14,4 @@
  * limitations under the License.
  */
 
-import { CustomErrorBase, isError, stringifyError } from '@backstage/errors';
-import chalk from 'chalk';
-
-export class ExitCodeError extends CustomErrorBase {
-  readonly code: number;
-
-  constructor(code: number, command?: string) {
-    super(
-      command
-        ? `Command '${command}' exited with code ${code}`
-        : `Child exited with code ${code}`,
-    );
-    this.code = code;
-  }
-}
-
-function exit(message: string, code: number = 1): never {
-  process.stderr.write(`\n${chalk.red(message)}\n\n`);
-  process.exit(code);
-}
-
-export function exitWithError(error: unknown): never {
-  if (!isError(error)) {
-    process.stderr.write(`\n${chalk.red(stringifyError(error))}\n\n`);
-    process.exit(1);
-  }
-
-  switch (error.name) {
-    case 'InputError':
-      return exit(error.message, 74 /* input/output error */);
-    case 'NotFoundError':
-      return exit(error.message, 127 /* command not found */);
-    case 'NotImplementedError':
-      return exit(error.message, 64 /* command line usage error */);
-    case 'AuthenticationError':
-    case 'NotAllowedError':
-      return exit(error.message, 77 /* permissino denied */);
-    case 'ExitCodeError':
-      return exit(
-        error.message,
-        'code' in error && typeof error.code === 'number' ? error.code : 1,
-      );
-    default:
-      return exit(stringifyError(error), 1);
-  }
-}
+export { ExitCodeError, exitWithError } from '@backstage/cli-plugin-api';

packages/cli/src/wiring/factory.ts

@@ -14,18 +14,4 @@
  * limitations under the License.
  */
 
-import { describeParentCallSite } from './describeParentCallSite';
-import { BackstageCommand, CliPlugin, OpaqueCliPlugin } from './types';
-
-export function createCliPlugin(options: {
-  pluginId: string;
-  init: (registry: {
-    addCommand: (command: BackstageCommand) => void;
-  }) => Promise<void>;
-}): CliPlugin {
-  return OpaqueCliPlugin.createInstance('v1', {
-    pluginId: options.pluginId,
-    init: options.init,
-    description: `created at '${describeParentCallSite()}'`,
-  });
-}
+export { createCliPlugin } from '@backstage/cli-plugin-api';

packages/cli/src/wiring/lazy.ts

@@ -14,34 +14,4 @@
  * limitations under the License.
  */
 
-import { assertError } from '@backstage/errors';
-import { exitWithError } from './errors';
-
-type ActionFunc = (...args: any[]) => Promise<void>;
-type ActionExports<TModule extends object> = {
-  [KName in keyof TModule as TModule[KName] extends ActionFunc
-    ? KName
-    : never]: TModule[KName];
-};
-
-// Wraps an action function so that it always exits and handles errors
-export function lazy<TModule extends object>(
-  moduleLoader: () => Promise<TModule>,
-  exportName: keyof ActionExports<TModule>,
-): (...args: any[]) => Promise<never> {
-  return async (...args: any[]) => {
-    try {
-      const mod = await moduleLoader();
-      const actualModule = (
-        mod as unknown as { default: ActionExports<TModule> }
-      ).default;
-      const actionFunc = actualModule[exportName] as ActionFunc;
-      await actionFunc(...args);
-
-      process.exit(0);
-    } catch (error) {
-      assertError(error);
-      exitWithError(error);
-    }
-  };
-}
+export { lazy } from '@backstage/cli-plugin-api';

packages/cli/src/wiring/types.ts

@@ -13,53 +13,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { OpaqueType } from '@internal/opaque';
 
-export interface CommandContext {
-  args: string[];
-  info: {
-    /**
-     * The usage string of the current command, for example: "backstage-cli repo test"
-     */
-    usage: string;
-    /**
-     * The description provided for the command
-     */
-    description: string;
-  };
-}
-
-export type CommandExecuteFn = (context: CommandContext) => Promise<void>;
-
-export interface BackstageCommand {
-  path: string[];
-  description: string;
-  deprecated?: boolean;
-  experimental?: boolean;
-  execute:
-    | CommandExecuteFn
-    | {
-        loader: () => Promise<{ default: CommandExecuteFn }>;
-      };
-}
-
-export type CliFeature = CliPlugin;
-
-export interface CliPlugin {
-  readonly pluginId: string;
-  readonly $$type: '@backstage/CliPlugin';
-}
-
-export const OpaqueCliPlugin = OpaqueType.create<{
-  public: CliPlugin;
-  versions: {
-    readonly version: 'v1';
-    readonly description: string;
-    init: (registry: {
-      addCommand: (command: BackstageCommand) => void;
-    }) => Promise<void>;
-  };
-}>({
-  type: '@backstage/CliPlugin',
-  versions: ['v1'],
-});
+// Re-export types from the plugin API for internal use within the CLI package.
+export type {
+  CommandContext,
+  CommandExecuteFn,
+  BackstageCommand,
+  CliFeature,
+  CliPlugin,
+} from '@backstage/cli-plugin-api';