Slim cli-plugin-api to only export createCliPlugin

Move error handling and lazy utilities back to @backstage/cli since they
are host-only concerns. The cli-plugin-api internals subpath provides
isCliPlugin and initializeCliPlugin for the CLI host.

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

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

@@ -2,4 +2,4 @@
 '@backstage/cli': patch
 ---
 
-Migrated CLI plugin modules to import from the new `@backstage/cli-plugin-api` package.
+Migrated CLI plugin modules to use `createCliPlugin` from the new `@backstage/cli-plugin-api` package.

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

@@ -2,4 +2,4 @@
 '@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.
+Added a new `@backstage/cli-plugin-api` package that provides the `createCliPlugin` API for building Backstage CLI plugins.

packages/cli-plugin-api/.eslintrc.js

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

packages/cli-plugin-api/package.json

@@ -6,9 +6,7 @@
     "role": "cli-plugin"
   },
   "publishConfig": {
-    "access": "public",
-    "main": "dist/index.cjs.js",
-    "types": "dist/index.d.ts"
+    "access": "public"
   },
   "homepage": "https://backstage.io",
   "repository": {
@@ -17,8 +15,23 @@
     "directory": "packages/cli-plugin-api"
   },
   "license": "Apache-2.0",
+  "exports": {
+    ".": "./src/index.ts",
+    "./internals": "./src/internals.ts",
+    "./package.json": "./package.json"
+  },
   "main": "src/index.ts",
   "types": "src/index.ts",
+  "typesVersions": {
+    "*": {
+      "internals": [
+        "src/internals.ts"
+      ],
+      "package.json": [
+        "package.json"
+      ]
+    }
+  },
   "files": [
     "dist"
   ],
@@ -31,8 +44,7 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/errors": "workspace:^",
-    "chalk": "^4.0.0"
+    "@backstage/errors": "workspace:^"
   },
   "devDependencies": {
     "@backstage/cli": "workspace:^"

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

@@ -0,0 +1,60 @@
+## 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
+// @public
+export interface BackstageCommand {
+  // (undocumented)
+  deprecated?: boolean;
+  // (undocumented)
+  description: string;
+  // (undocumented)
+  execute:
+    | CommandExecuteFn
+    | {
+        loader: () => Promise<{
+          default: CommandExecuteFn;
+        }>;
+      };
+  // (undocumented)
+  experimental?: boolean;
+  // (undocumented)
+  path: string[];
+}
+
+// @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 initializeCliPlugin(
+  plugin: CliPlugin,
+  registry: {
+    addCommand: (command: BackstageCommand) => void;
+  },
+): Promise<void>;
+
+// @public
+export function isCliPlugin(value: unknown): value is CliPlugin;
+
+// (No @packageDocumentation comment for this package)
+```

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

@@ -3,17 +3,6 @@
 > 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)
@@ -29,6 +18,8 @@ export interface BackstageCommand {
         }>;
       };
   // (undocumented)
+  experimental?: boolean;
+  // (undocumented)
   path: string[];
 }
 
@@ -65,32 +56,5 @@ export function createCliPlugin(options: {
   }) => 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/errors.ts

@@ -1,72 +0,0 @@
-/*
- * 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

@@ -15,9 +15,6 @@
  */
 
 export { createCliPlugin } from './createCliPlugin';
-export { lazy } from './lazy';
-export type { ActionExports } from './lazy';
-export { ExitCodeError, exitWithError } from './errors';
 export type {
   BackstageCommand,
   CommandContext,
@@ -25,4 +22,3 @@ export type {
   CliPlugin,
   CliFeature,
 } from './types';
-export { isCliPlugin, initializeCliPlugin } from './internals';

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

@@ -16,6 +16,13 @@
 
 import { BackstageCommand, CliPlugin, OpaqueCliPlugin } from './types';
 
+export type {
+  BackstageCommand,
+  CliPlugin,
+  CommandContext,
+  CommandExecuteFn,
+} from './types';
+
 /**
  * Checks whether a value is a {@link CliPlugin}.
  *

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

@@ -1,59 +0,0 @@
-/*
- * 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/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 '@backstage/cli-plugin-api';
+import type { CommandContext } from '../../../wiring/types';
 
 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 '@backstage/cli-plugin-api';
+import type { CommandContext } from '../../../wiring/types';
 
 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 '@backstage/cli-plugin-api';
+import type { CommandContext } from '../../../wiring/types';
 
 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 '@backstage/cli-plugin-api';
+import type { CommandContext } from '../../../wiring/types';
 
 export default async ({ args, info }: CommandContext) => {
   const {

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 '@backstage/cli-plugin-api';
+import type { CommandContext } from '../../../wiring/types';
 
 /**
  * Attempts to read package.json from node_modules for a given package name.

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

@@ -33,7 +33,7 @@ import {
   formatMessagePath,
   validatePattern,
 } from '../lib/messageFilePath';
-import type { CommandContext } from '@backstage/cli-plugin-api';
+import type { CommandContext } from '../../../wiring/types';
 
 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 '@backstage/cli-plugin-api';
+import type { CommandContext } from '../../../wiring/types';
 
 interface ManifestRefEntry {
   package: string;

packages/cli/src/wiring/CliInitializer.ts

@@ -18,13 +18,13 @@ import { CommandGraph } from './CommandGraph';
 import {
   isCliPlugin,
   initializeCliPlugin,
-  exitWithError,
-} from '@backstage/cli-plugin-api';
+} from '@backstage/cli-plugin-api/internals';
 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';
 

packages/cli/src/wiring/errors.ts

@@ -14,4 +14,49 @@
  * limitations under the License.
  */
 
-export { ExitCodeError, exitWithError } from '@backstage/cli-plugin-api';
+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);
+  }
+}

packages/cli/src/wiring/lazy.ts

@@ -14,4 +14,34 @@
  * limitations under the License.
  */
 
-export { lazy } from '@backstage/cli-plugin-api';
+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);
+    }
+  };
+}

packages/cli/src/wiring/types.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-// Re-export types from the plugin API for internal use within the CLI package.
 export type {
   CommandContext,
   CommandExecuteFn,

yarn.lock

@@ -2828,7 +2828,6 @@ __metadata:
   dependencies:
     "@backstage/cli": "workspace:^"
     "@backstage/errors": "workspace:^"
-    chalk: "npm:^4.0.0"
   languageName: unknown
   linkType: soft