cli: initial cli-plugin-api

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

.changeset/cli-use-cli-plugin-api.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+Migrated CLI plugin modules to import from the new `@backstage/cli-plugin-api` package.

.changeset/create-cli-plugin-api.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli-plugin-api': minor
+---
+
+Added a new `@backstage/cli-plugin-api` package that provides the public API for building Backstage CLI plugins. This includes `createCliPlugin`, `lazy`, `ExitCodeError`, `exitWithError`, and associated types.

packages/cli-plugin-api/catalog-info.yaml

@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: backstage-cli-plugin-api
+  title: '@backstage/cli-plugin-api'
+  description: API for building Backstage CLI plugins
+spec:
+  lifecycle: experimental
+  type: backstage-cli-plugin
+  owner: tooling-maintainers

packages/cli-plugin-api/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@backstage/cli-plugin-api",
+  "version": "0.1.0",
+  "description": "API for building Backstage CLI plugins",
+  "backstage": {
+    "role": "cli-plugin"
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "packages/cli-plugin-api"
+  },
+  "license": "Apache-2.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "backstage-cli package build",
+    "clean": "backstage-cli package clean",
+    "lint": "backstage-cli package lint",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack",
+    "test": "backstage-cli package test"
+  },
+  "dependencies": {
+    "@backstage/errors": "workspace:^",
+    "chalk": "^4.0.0"
+  },
+  "devDependencies": {
+    "@backstage/cli": "workspace:^"
+  }
+}

packages/cli-plugin-api/report.api.md

@@ -0,0 +1,96 @@
+## API Report File for "@backstage/cli-plugin-api"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { CustomErrorBase } from '@backstage/errors';
+
+// @public
+export type ActionExports<TModule extends object> = {
+  [KName in keyof TModule as TModule[KName] extends (
+    ...args: any[]
+  ) => Promise<void>
+    ? KName
+    : never]: TModule[KName];
+};
+
+// @public
+export interface BackstageCommand {
+  // (undocumented)
+  deprecated?: boolean;
+  // (undocumented)
+  description: string;
+  // (undocumented)
+  execute:
+    | CommandExecuteFn
+    | {
+        loader: () => Promise<{
+          default: CommandExecuteFn;
+        }>;
+      };
+  // (undocumented)
+  path: string[];
+}
+
+// @public
+export type CliFeature = CliPlugin;
+
+// @public
+export interface CliPlugin {
+  // (undocumented)
+  readonly $$type: '@backstage/CliPlugin';
+  // (undocumented)
+  readonly pluginId: string;
+}
+
+// @public
+export interface CommandContext {
+  // (undocumented)
+  args: string[];
+  // (undocumented)
+  info: {
+    usage: string;
+    description: string;
+  };
+}
+
+// @public
+export type CommandExecuteFn = (context: CommandContext) => Promise<void>;
+
+// @public
+export function createCliPlugin(options: {
+  pluginId: string;
+  init: (registry: {
+    addCommand: (command: BackstageCommand) => void;
+  }) => Promise<void>;
+}): CliPlugin;
+
+// @public
+export class ExitCodeError extends CustomErrorBase {
+  constructor(code: number, command?: string);
+  // (undocumented)
+  readonly code: number;
+}
+
+// @public
+export function exitWithError(error: unknown): never;
+
+// @public
+export function initializeCliPlugin(
+  plugin: CliPlugin,
+  registry: {
+    addCommand: (command: BackstageCommand) => void;
+  },
+): Promise<void>;
+
+// @public
+export function isCliPlugin(value: unknown): value is CliPlugin;
+
+// @public
+export function lazy<TModule extends object>(
+  moduleLoader: () => Promise<TModule>,
+  exportName: keyof ActionExports<TModule>,
+): (...args: any[]) => Promise<never>;
+
+// (No @packageDocumentation comment for this package)
+```

packages/cli-plugin-api/src/createCliPlugin.ts

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2024 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 { describeParentCallSite } from './describeParentCallSite';
+import { BackstageCommand, CliPlugin, OpaqueCliPlugin } from './types';
+
+/**
+ * Creates a new CLI plugin that provides commands to the Backstage CLI.
+ *
+ * @public
+ */
+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()}'`,
+  });
+}

packages/cli-plugin-api/src/describeParentCallSite.ts

@@ -0,0 +1,54 @@
+/*
+ * 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.
+ */
+
+const MESSAGE_MARKER = 'eHgtF5hmbrXyiEvo';
+
+/**
+ * Internal helper that describes the location of the parent caller.
+ * @internal
+ */
+export function describeParentCallSite(
+  ErrorConstructor: { new (message: string): Error } = Error,
+): string {
+  const { stack } = new ErrorConstructor(MESSAGE_MARKER);
+  if (!stack) {
+    return '<unknown>';
+  }
+
+  const startIndex = stack.includes(MESSAGE_MARKER)
+    ? stack.indexOf('\n') + 1
+    : 0;
+  const secondEntryStart =
+    stack.indexOf('\n', stack.indexOf('\n', startIndex) + 1) + 1;
+  const secondEntryEnd = stack.indexOf('\n', secondEntryStart);
+
+  const line = stack.substring(secondEntryStart, secondEntryEnd).trim();
+  if (!line) {
+    return 'unknown';
+  }
+
+  // Chrome
+  if (line.includes('(')) {
+    return line.substring(line.indexOf('(') + 1, line.indexOf(')'));
+  }
+
+  // Safari & Firefox
+  if (line.includes('@')) {
+    return line.substring(line.indexOf('@') + 1);
+  }
+
+  return line;
+}

packages/cli-plugin-api/src/errors.ts

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2020 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 { CustomErrorBase, isError, stringifyError } from '@backstage/errors';
+import chalk from 'chalk';
+
+/**
+ * An error that indicates a child process exited with a specific code.
+ *
+ * @public
+ */
+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);
+}
+
+/**
+ * Exits the process with an appropriate error code based on the error type.
+ *
+ * @public
+ */
+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 /* permission denied */);
+    case 'ExitCodeError':
+      return exit(
+        error.message,
+        'code' in error && typeof error.code === 'number' ? error.code : 1,
+      );
+    default:
+      return exit(stringifyError(error), 1);
+  }
+}

packages/cli-plugin-api/src/index.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 The Backstage Authors
+ * Copyright 2024 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.
@@ -14,7 +14,15 @@
  * 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';
+export { createCliPlugin } from './createCliPlugin';
+export { lazy } from './lazy';
+export type { ActionExports } from './lazy';
+export { ExitCodeError, exitWithError } from './errors';
+export type {
+  BackstageCommand,
+  CommandContext,
+  CommandExecuteFn,
+  CliPlugin,
+  CliFeature,
+} from './types';
+export { isCliPlugin, initializeCliPlugin } from './internals';

packages/cli-plugin-api/src/internals.ts

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2024 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 { BackstageCommand, CliPlugin, OpaqueCliPlugin } from './types';
+
+/**
+ * Checks whether a value is a {@link CliPlugin}.
+ *
+ * @public
+ */
+export function isCliPlugin(value: unknown): value is CliPlugin {
+  return OpaqueCliPlugin.isType(value);
+}
+
+/**
+ * Initializes a CLI plugin by calling its init function with the provided
+ * command registry.
+ *
+ * @public
+ */
+export async function initializeCliPlugin(
+  plugin: CliPlugin,
+  registry: { addCommand: (command: BackstageCommand) => void },
+): Promise<void> {
+  const internal = OpaqueCliPlugin.toInternal(plugin);
+  await internal.init(registry);
+}

packages/cli-plugin-api/src/lazy.ts

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2024 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 { assertError } from '@backstage/errors';
+import { exitWithError } from './errors';
+
+/**
+ * A mapped type that extracts keys of a module whose values are async action functions.
+ *
+ * @public
+ */
+export type ActionExports<TModule extends object> = {
+  [KName in keyof TModule as TModule[KName] extends (
+    ...args: any[]
+  ) => Promise<void>
+    ? KName
+    : never]: TModule[KName];
+};
+
+/**
+ * Wraps an action function so that it always exits and handles errors.
+ *
+ * @public
+ */
+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 (
+        ...args: any[]
+      ) => Promise<void>;
+      await actionFunc(...args);
+
+      process.exit(0);
+    } catch (error) {
+      assertError(error);
+      exitWithError(error);
+    }
+  };
+}

packages/cli-plugin-api/src/types.ts

@@ -0,0 +1,91 @@
+/*
+ * Copyright 2024 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 { OpaqueType } from '@internal/opaque';
+
+/**
+ * The context provided to a CLI command when it is executed.
+ *
+ * @public
+ */
+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;
+  };
+}
+
+/**
+ * A function that executes a CLI command.
+ *
+ * @public
+ */
+export type CommandExecuteFn = (context: CommandContext) => Promise<void>;
+
+/**
+ * A command definition for a Backstage CLI plugin.
+ *
+ * @public
+ */
+export interface BackstageCommand {
+  path: string[];
+  description: string;
+  deprecated?: boolean;
+  experimental?: boolean;
+  execute:
+    | CommandExecuteFn
+    | {
+        loader: () => Promise<{ default: CommandExecuteFn }>;
+      };
+}
+
+/**
+ * A CLI feature, currently always a CLI plugin.
+ *
+ * @public
+ */
+export type CliFeature = CliPlugin;
+
+/**
+ * A Backstage CLI plugin.
+ *
+ * @public
+ */
+export interface CliPlugin {
+  readonly pluginId: string;
+  readonly $$type: '@backstage/CliPlugin';
+}
+
+/** @internal */
+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'],
+});

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/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';

yarn.lock

@@ -2822,6 +2822,16 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@backstage/cli-plugin-api@workspace:^, @backstage/cli-plugin-api@workspace:packages/cli-plugin-api":
+  version: 0.0.0-use.local
+  resolution: "@backstage/cli-plugin-api@workspace:packages/cli-plugin-api"
+  dependencies:
+    "@backstage/cli": "workspace:^"
+    "@backstage/errors": "workspace:^"
+    chalk: "npm:^4.0.0"
+  languageName: unknown
+  linkType: soft
+
 "@backstage/cli@workspace:*, @backstage/cli@workspace:^, @backstage/cli@workspace:packages/cli":
   version: 0.0.0-use.local
   resolution: "@backstage/cli@workspace:packages/cli"
@@ -2832,6 +2842,7 @@ __metadata:
     "@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/core-app-api": "workspace:^"