@@ -136,7 +181,6 @@ const ExternalPage = PageBlueprint.make({
loader: async () => {
const Component = () => {
const indexLink = useRouteRef(indexRouteRef);
- // const pageXLink = useRouteRef(pageXRouteRef);
return (
@@ -150,15 +194,272 @@ const ExternalPage = PageBlueprint.make({
},
});
+// Example: Page enabled only when a single feature flag is active.
+//
+// The `if` predicate is evaluated once at app startup (before the router
+// tree is built), so this page simply won't exist in the app until the flag is
+// toggled and the page is refreshed.
+//
+// To test: enable the 'experimental-features' flag in Settings, then refresh.
+const FeatureFlagPage = PageBlueprint.make({
+ name: 'featureFlagExample',
+ params: {
+ path: '/feature-flag-example',
+ loader: async () => {
+ const Component = () => {
+ const indexLink = useRouteRef(indexRouteRef);
+ return (
+
+
Feature Flag Enabled Page
+
+ This page is only present in the app when the{' '}
+ experimental-features feature flag is active.
+
+
+ It uses a simple{' '}
+
+ {'{ featureFlags: { $contains: "experimental-features" } }'}
+ {' '}
+ predicate.
+
+ {indexLink &&
Go back}
+
+ );
+ };
+ return
;
+ },
+ },
+ if: { featureFlags: { $contains: 'experimental-features' } },
+});
+
+// Example: Page enabled only when ALL of several feature flags are active.
+//
+// The $all operator requires every nested predicate to be satisfied. This page
+// won't appear unless both 'experimental-features' and 'advanced-features' are
+// enabled at the same time.
+//
+// To test: enable BOTH flags in Settings, then refresh.
+const AllFlagsPage = PageBlueprint.make({
+ name: 'allFlagsExample',
+ params: {
+ path: '/all-flags-example',
+ loader: async () => {
+ const Component = () => {
+ const indexLink = useRouteRef(indexRouteRef);
+ return (
+
+
All Flags Required Page
+
+ This page requires both{' '}
+ experimental-features and{' '}
+ advanced-features to be active simultaneously.
+
+
+ It uses a $all predicate to AND the two conditions
+ together.
+
+ {indexLink &&
Go back}
+
+ );
+ };
+ return
;
+ },
+ },
+ if: {
+ $all: [
+ { featureFlags: { $contains: 'experimental-features' } },
+ { featureFlags: { $contains: 'advanced-features' } },
+ ],
+ },
+});
+
+// Example: Page enabled when ANY one of several feature flags is active.
+//
+// The $any operator is satisfied as soon as at least one nested predicate
+// matches. Enabling either 'experimental-features' or 'beta-access' will make
+// this page appear.
+//
+// To test: enable at least one of the two flags in Settings, then refresh.
+const AnyFlagPage = PageBlueprint.make({
+ name: 'anyFlagExample',
+ params: {
+ path: '/any-flag-example',
+ loader: async () => {
+ const Component = () => {
+ const indexLink = useRouteRef(indexRouteRef);
+ return (
+
+
Any Flag Sufficient Page
+
+ This page appears when either{' '}
+ experimental-features or beta-access is
+ active.
+
+
+ It uses a $any predicate to OR the two conditions
+ together.
+
+ {indexLink &&
Go back}
+
+ );
+ };
+ return
;
+ },
+ },
+ if: {
+ $any: [
+ { featureFlags: { $contains: 'experimental-features' } },
+ { featureFlags: { $contains: 'beta-access' } },
+ ],
+ },
+});
+
+// Blueprint for cards that attach to the PermissionCardPage below.
+//
+// Each card receives a title and description and renders a simple bordered card.
+// Individual card instances can be selectively enabled via the `if`
+// predicate, so only the cards the user is allowed to see will be instantiated.
+const PermissionExampleCardBlueprint = createExtensionBlueprint({
+ kind: 'permission-example-card',
+ attachTo: { id: 'page:pages/permissionCardExample', input: 'cards' },
+ output: [coreExtensionData.reactElement],
+ *factory(params: { title: string; description: string }) {
+ yield coreExtensionData.reactElement(
+
+
{params.title}
+
{params.description}
+
,
+ );
+ },
+});
+
+// Example: Page with cards that are individually toggled by permissions.
+//
+// The page itself is always present. What changes is which cards are
+// instantiated inside it — each card declares its own `enabled` predicate
+// and is only wired into the page if that predicate is satisfied at startup.
+//
+// To test: make sure you do NOT have the catalog.entity.create permission and
+// refresh the page — the "Restricted Card" below should disappear.
+const PermissionCardPage = PageBlueprint.makeWithOverrides({
+ name: 'permissionCardExample',
+ inputs: {
+ cards: createExtensionInput([coreExtensionData.reactElement]),
+ },
+ factory(originalFactory, { inputs }) {
+ return originalFactory({
+ path: '/permission-card-example',
+ loader: async () => {
+ const Component = () => {
+ const indexLink = useRouteRef(indexRouteRef);
+ const cards = inputs.cards.map(card =>
+ card.get(coreExtensionData.reactElement),
+ );
+ return (
+
+
Permission-Gated Card Example
+
+ This page is always visible. The cards below are individually
+ gated — each one declares its own{' '}
+ {'if: { permissions: { $contains: "..." } }'}{' '}
+ predicate. Cards whose predicate fails are never instantiated,
+ so they simply won't appear here.
+
+
+ {cards.length > 0 ? (
+ cards
+ ) : (
+
+ No cards are visible — you may lack the required
+ permissions.
+
+ )}
+
+ {indexLink &&
Go back}
+
+ );
+ };
+ return
;
+ },
+ });
+ },
+});
+
+// Always-visible card — no predicate, every user sees this.
+const PublicCard = PermissionExampleCardBlueprint.make({
+ name: 'public',
+ params: {
+ title: 'Public Card',
+ description: 'This card is visible to everyone regardless of permissions.',
+ },
+});
+
+// Permission-gated card — only instantiated when the user has
+// the catalog.entity.create permission.
+const RestrictedCard = PermissionExampleCardBlueprint.make({
+ name: 'restricted',
+ params: {
+ title: 'Restricted Card',
+ description:
+ 'This card is only visible to users who have the catalog.entity.create permission.',
+ },
+ if: { permissions: { $contains: 'catalog.entity.create' } },
+});
+
+// Feature flag-gated card — only instantiated when the user has
+// the experimental-card FF enabled.
+const FeatureFlagCard = PermissionExampleCardBlueprint.make({
+ name: 'feature-flag',
+ params: {
+ title: 'Feature Flagged Card',
+ description: 'Visible only with the experimental-card FF active.',
+ },
+ if: { featureFlags: { $contains: 'experimental-card' } },
+});
+
+// Example: Page enabled only when the user is allowed to create catalog entities.
+//
+// The `if` predicate is evaluated once at app startup (after sign-in),
+// so this page simply won't exist in the router tree if the user lacks the
+// required permission.
+const PermissionGatedPage = PageBlueprint.make({
+ name: 'permissionGatedExample',
+ params: {
+ path: '/permission-gated-example',
+ loader: async () => {
+ const Component = () => {
+ const indexLink = useRouteRef(indexRouteRef);
+ return (
+
+
Permission Gated Page
+
+ This page is only present when the user has the{' '}
+ catalog.entity.create permission.
+
+ {indexLink &&
Go back}
+
+ );
+ };
+ return
;
+ },
+ },
+ if: { permissions: { $contains: 'catalog.entity.create' } },
+});
+
export const pagesPlugin = createFrontendPlugin({
pluginId: 'pages',
- // routes: {
- // index: indexRouteRef,
- // // reference in config:
- // // 'plugin.pages.routes.index'
- // // OR
- // // 'page1'
- // },
info: {
packageJson: () => import('../../package.json'),
manifest: () => import('../../catalog-info.yaml'),
@@ -170,5 +471,23 @@ export const pagesPlugin = createFrontendPlugin({
externalRoutes: {
pageX: externalPageXRouteRef,
},
- extensions: [IndexPage, Page1, ExternalPage],
+ featureFlags: [
+ { name: 'experimental-features' },
+ { name: 'advanced-features' },
+ { name: 'beta-access' },
+ { name: 'experimental-card' },
+ ],
+ extensions: [
+ IndexPage,
+ Page1,
+ ExternalPage,
+ FeatureFlagPage,
+ AllFlagsPage,
+ AnyFlagPage,
+ PermissionCardPage,
+ PublicCard,
+ RestrictedCard,
+ PermissionGatedPage,
+ FeatureFlagCard,
+ ],
});
diff --git a/packages/app/src/modules/appModuleNav.tsx b/packages/app/src/modules/appModuleNav.tsx
index a507679c73..044cd96e23 100644
--- a/packages/app/src/modules/appModuleNav.tsx
+++ b/packages/app/src/modules/appModuleNav.tsx
@@ -27,15 +27,11 @@ import {
} from '@backstage/core-components';
import SearchIcon from '@material-ui/icons/Search';
import MenuIcon from '@material-ui/icons/Menu';
-import BuildIcon from '@material-ui/icons/Build';
import { createFrontendModule } from '@backstage/frontend-plugin-api';
import { NavContentBlueprint } from '@backstage/plugin-app-react';
import { SidebarSearchModal } from '@backstage/plugin-search';
import { NotificationsSidebarItem } from '@backstage/plugin-notifications';
-import {
- Settings,
- UserSettingsSignInAvatar,
-} from '@backstage/plugin-user-settings';
+import { UserSettingsSignInAvatar } from '@backstage/plugin-user-settings';
import { makeStyles } from '@material-ui/core/styles';
const useSidebarLogoStyles = makeStyles({
@@ -111,7 +107,9 @@ export const appModuleNav = createFrontendModule({
text={item.title}
/>
));
- nav.take('page:home'); // Skip home
+ // Consume without rendering — these are handled by dedicated sidebar groups
+ nav.take('page:home');
+ nav.take('page:search');
return (
@@ -136,8 +134,8 @@ export const appModuleNav = createFrontendModule({
to="/settings"
>
-
-
+ {nav.take('page:devtools')}
+ {nav.take('page:user-settings')}
);
diff --git a/packages/backend-app-api/CHANGELOG.md b/packages/backend-app-api/CHANGELOG.md
index b07cb0869d..f46cfe28bb 100644
--- a/packages/backend-app-api/CHANGELOG.md
+++ b/packages/backend-app-api/CHANGELOG.md
@@ -1,5 +1,43 @@
# @backstage/backend-app-api
+## 1.6.1-next.1
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.9.0-next.1
+
+## 1.6.1-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.1-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+
+## 1.6.0
+
+### Minor Changes
+
+- 545557a: Registration errors should be forwarded as BackendStartupResult
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0
+
+## 1.6.0-next.1
+
+### Minor Changes
+
+- 545557a: Registration errors should be forwarded as BackendStartupResult
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0-next.1
+
## 1.5.1-next.0
### Patch Changes
diff --git a/packages/backend-app-api/package.json b/packages/backend-app-api/package.json
index 08b12d7d6d..2ebcc05941 100644
--- a/packages/backend-app-api/package.json
+++ b/packages/backend-app-api/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/backend-app-api",
- "version": "1.5.1-next.0",
+ "version": "1.6.1-next.1",
"description": "Core API used by Backstage backend apps",
"backstage": {
"role": "node-library"
diff --git a/packages/backend-defaults/CHANGELOG.md b/packages/backend-defaults/CHANGELOG.md
index 05f54be89f..f635723677 100644
--- a/packages/backend-defaults/CHANGELOG.md
+++ b/packages/backend-defaults/CHANGELOG.md
@@ -1,5 +1,88 @@
# @backstage/backend-defaults
+## 0.16.1-next.1
+
+### Patch Changes
+
+- 4559806: Added support for typed `examples` on actions registered via the actions registry. Action authors can now provide examples with compile-time-checked `input` and `output` values that match their schema definitions.
+- 5cd814f: Refactored auditor severity log level mappings to use `zod/v4` with schema-driven defaults and type inference.
+- 6e2aaab: Fixed `AwsS3UrlReader` failing to read files from S3 buckets configured with custom endpoint hosts. When an integration was configured with a specific endpoint like `https://bucket-1.s3.eu-central-1.amazonaws.com`, the URL parser incorrectly fell through to the non-AWS code path, always defaulting the region to `us-east-1` instead of extracting it from the hostname.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.9.0-next.1
+ - @backstage/plugin-auth-node@0.7.0-next.1
+ - @backstage/backend-app-api@1.6.1-next.1
+ - @backstage/plugin-events-node@0.4.21-next.1
+ - @backstage/plugin-permission-node@0.10.12-next.1
+
+## 0.16.1-next.0
+
+### Patch Changes
+
+- 79453c0: Updated dependency `wait-for-expect` to `^4.0.0`.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.1-next.0
+ - @backstage/cli-node@0.3.1-next.0
+ - @backstage/config-loader@1.10.10-next.0
+ - @backstage/backend-app-api@1.6.1-next.0
+ - @backstage/plugin-auth-node@0.6.15-next.0
+ - @backstage/plugin-permission-node@0.10.12-next.0
+ - @backstage/plugin-events-node@0.4.21-next.0
+ - @backstage/backend-dev-utils@0.1.7
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/integration@2.0.0
+ - @backstage/integration-aws-node@0.1.20
+ - @backstage/types@1.2.2
+ - @backstage/plugin-permission-common@0.9.7
+
+## 0.16.0
+
+### Minor Changes
+
+- 42960f1: The actions registry invoke endpoint now accepts direct user credentials in addition to service principals, enabling CLI and other direct user clients to invoke actions.
+- 0e7d8f9: The scheduler service now uses the metrics service to create metrics, providing plugin-scoped attribution.
+- 527cf88: **BREAKING** Removed deprecated `BitbucketUrlReader`. Use the `BitbucketCloudUrlReader` or the `BitbucketServerUrlReader` instead.
+
+### Patch Changes
+
+- cc8348e: Added permissions integration to the actions registry. Actions registered with a `visibilityPermission` field are now checked against the permissions framework when listing and invoking. Denied actions are filtered from list results, and invoking a denied action returns a `404 Not Found` as if the action does not exist. Permissions are automatically registered with the `PermissionsRegistryService` so they appear in the permission policy system.
+- dee4283: Added `pluginId` field to `ActionsServiceAction` type, populated from the registering plugin's metadata.
+- 015668c: Added `cancelTask` method to the `SchedulerService` interface and implementation, allowing cancellation of currently running scheduled tasks. For global tasks, the database lock is released and a periodic liveness check aborts the running task function. For local tasks, the task's abort signal is triggered directly. A new `POST /.backstage/scheduler/v1/tasks/:id/cancel` endpoint is also available.
+- 638e6c7: chore(deps): bump `yauzl` from 3.2.0 to 3.2.1
+- 6738cf0: build(deps): bump `minimatch` from 9.0.5 to 10.2.1
+- 62f0a53: Fixed error forwarding in the actions registry so that known errors like `InputError` and `NotFoundError` thrown by actions preserve their original status codes and messages instead of being wrapped in `ForwardedError` and coerced to 500.
+- d933f62: Add configurable throttling and retry mechanism for GitLab integration.
+- b99158a: Fixed `yarn backstage-cli config:check --strict --config app-config.yaml` config validation error by adding
+ an optional `default` type discriminator to PostgreSQL connection configuration,
+ allowing `config:check` to properly validate `default` connection configurations.
+- 1ee5b28: Adds an alpha `MetricsService` to provide a unified interface for metrics instrumentation across Backstage plugins.
+- 5fcbef2: Updated dependency `express-rate-limit` to `^8.0.0`.
+- a49a40d: Updated dependency `zod` to `^3.25.76 || ^4.0.0` & migrated to `/v3` or `/v4` imports.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0
+ - @backstage/cli-node@0.3.0
+ - @backstage/integration@2.0.0
+ - @backstage/config-loader@1.10.9
+ - @backstage/plugin-permission-common@0.9.7
+ - @backstage/plugin-permission-node@0.10.11
+ - @backstage/plugin-auth-node@0.6.14
+ - @backstage/backend-app-api@1.6.0
+ - @backstage/plugin-events-node@0.4.20
+
+## 0.16.0-next.2
+
+### Patch Changes
+
+- 015668c: Added `cancelTask` method to the `SchedulerService` interface and implementation, allowing cancellation of currently running scheduled tasks. For global tasks, the database lock is released and a periodic liveness check aborts the running task function. For local tasks, the task's abort signal is triggered directly. A new `POST /.backstage/scheduler/v1/tasks/:id/cancel` endpoint is also available.
+- 5fcbef2: Updated dependency `express-rate-limit` to `^8.0.0`.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0-next.1
+ - @backstage/integration@2.0.0-next.2
+ - @backstage/backend-app-api@1.6.0-next.1
+ - @backstage/plugin-auth-node@0.6.14-next.2
+ - @backstage/plugin-events-node@0.4.20-next.1
+ - @backstage/plugin-permission-node@0.10.11-next.1
+
## 0.16.0-next.1
### Minor Changes
diff --git a/packages/backend-defaults/package.json b/packages/backend-defaults/package.json
index 4aaf0408b4..33a262aadd 100644
--- a/packages/backend-defaults/package.json
+++ b/packages/backend-defaults/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/backend-defaults",
- "version": "0.16.0-next.1",
+ "version": "0.16.1-next.1",
"description": "Backend defaults used by Backstage backend apps",
"backstage": {
"role": "node-library"
@@ -144,6 +144,7 @@
"@backstage/integration-aws-node": "workspace:^",
"@backstage/plugin-auth-node": "workspace:^",
"@backstage/plugin-events-node": "workspace:^",
+ "@backstage/plugin-permission-common": "workspace:^",
"@backstage/plugin-permission-node": "workspace:^",
"@backstage/types": "workspace:^",
"@google-cloud/storage": "^7.0.0",
@@ -164,7 +165,7 @@
"cron": "^3.0.0",
"express": "^4.22.0",
"express-promise-router": "^4.1.0",
- "express-rate-limit": "^7.5.0",
+ "express-rate-limit": "^8.2.2",
"fs-extra": "^11.2.0",
"git-url-parse": "^15.0.0",
"helmet": "^6.0.0",
@@ -193,9 +194,9 @@
"uuid": "^11.0.0",
"winston": "^3.2.1",
"winston-transport": "^4.5.0",
- "yauzl": "^3.0.0",
+ "yauzl": "^3.2.1",
"yn": "^4.0.0",
- "zod": "^3.25.76",
+ "zod": "^3.25.76 || ^4.0.0",
"zod-to-json-schema": "^3.25.1"
},
"devDependencies": {
@@ -220,7 +221,7 @@
"msw": "^1.0.0",
"node-mocks-http": "^1.0.0",
"supertest": "^7.0.0",
- "wait-for-expect": "^3.0.2"
+ "wait-for-expect": "^4.0.0"
},
"peerDependencies": {
"@google-cloud/cloud-sql-connector": "^1.4.0",
diff --git a/packages/backend-defaults/src/alpha/entrypoints/actions/actionsServiceFactory.test.ts b/packages/backend-defaults/src/alpha/entrypoints/actions/actionsServiceFactory.test.ts
index dbce47bea4..3f600dcbbc 100644
--- a/packages/backend-defaults/src/alpha/entrypoints/actions/actionsServiceFactory.test.ts
+++ b/packages/backend-defaults/src/alpha/entrypoints/actions/actionsServiceFactory.test.ts
@@ -66,6 +66,7 @@ describe('actionsServiceFactory', () => {
const mockActionsDefinition: ActionsServiceAction = {
description: 'my mock description',
id: 'my-plugin:test',
+ pluginId: 'my-plugin',
name: 'testy',
title: 'Test',
schema: {
@@ -755,6 +756,7 @@ describe('actionsServiceFactory', () => {
{
description: 'Test',
id: 'plugin-with-action:with-validation',
+ pluginId: 'plugin-with-action',
name: 'with-validation',
schema: {
input: {
diff --git a/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/DefaultActionsRegistryService.ts b/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/DefaultActionsRegistryService.ts
index ffe74f81d9..1f6f108589 100644
--- a/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/DefaultActionsRegistryService.ts
+++ b/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/DefaultActionsRegistryService.ts
@@ -16,19 +16,25 @@
import {
AuthService,
+ BackstageCredentials,
HttpAuthService,
LoggerService,
+ PermissionsRegistryService,
+ PermissionsService,
PluginMetadataService,
} from '@backstage/backend-plugin-api';
import PromiseRouter from 'express-promise-router';
import { Router, json } from 'express';
-import { z, AnyZodObject } from 'zod';
+import { z, AnyZodObject } from 'zod/v3';
import zodToJsonSchema from 'zod-to-json-schema';
import {
ActionsRegistryActionOptions,
ActionsRegistryService,
} from '@backstage/backend-plugin-api/alpha';
import { InputError, NotAllowedError, NotFoundError } from '@backstage/errors';
+import { AuthorizeResult } from '@backstage/plugin-permission-common';
+
+type ActionEntry = [string, ActionsRegistryActionOptions
];
export class DefaultActionsRegistryService implements ActionsRegistryService {
private actions: Map> =
@@ -38,17 +44,23 @@ export class DefaultActionsRegistryService implements ActionsRegistryService {
private readonly httpAuth: HttpAuthService;
private readonly auth: AuthService;
private readonly metadata: PluginMetadataService;
+ private readonly permissions: PermissionsService;
+ private readonly permissionsRegistry: PermissionsRegistryService;
private constructor(
logger: LoggerService,
httpAuth: HttpAuthService,
auth: AuthService,
metadata: PluginMetadataService,
+ permissions: PermissionsService,
+ permissionsRegistry: PermissionsRegistryService,
) {
this.logger = logger;
this.httpAuth = httpAuth;
this.auth = auth;
this.metadata = metadata;
+ this.permissions = permissions;
+ this.permissionsRegistry = permissionsRegistry;
}
static create({
@@ -56,24 +68,46 @@ export class DefaultActionsRegistryService implements ActionsRegistryService {
logger,
auth,
metadata,
+ permissions,
+ permissionsRegistry,
}: {
httpAuth: HttpAuthService;
logger: LoggerService;
auth: AuthService;
metadata: PluginMetadataService;
+ permissions: PermissionsService;
+ permissionsRegistry: PermissionsRegistryService;
}): DefaultActionsRegistryService {
- return new DefaultActionsRegistryService(logger, httpAuth, auth, metadata);
+ return new DefaultActionsRegistryService(
+ logger,
+ httpAuth,
+ auth,
+ metadata,
+ permissions,
+ permissionsRegistry,
+ );
}
createRouter(): Router {
const router = PromiseRouter();
router.use(json());
- router.get('/.backstage/actions/v1/actions', (_, res) => {
+ router.get('/.backstage/actions/v1/actions', async (req, res) => {
+ const credentials = await this.httpAuth.credentials(req);
+ const entries = Array.from(this.actions.entries());
+
+ const allowedActions = await this.filterByPermissions(
+ entries,
+ credentials,
+ );
+
return res.json({
- actions: Array.from(this.actions.entries()).map(([id, action]) => ({
+ actions: allowedActions.map(([id, action]) => ({
id,
- ...action,
+ name: action.name,
+ title: action.title,
+ description: action.description,
+ pluginId: this.metadata.getId(),
attributes: {
// Inspired by the @modelcontextprotocol/sdk defaults for the hints.
// https://github.com/modelcontextprotocol/typescript-sdk/blob/dd69efa1de8646bb6b195ff8d5f52e13739f4550/src/types.ts#L777-L812
@@ -81,6 +115,7 @@ export class DefaultActionsRegistryService implements ActionsRegistryService {
idempotent: action.attributes?.idempotent ?? false,
readOnly: action.attributes?.readOnly ?? false,
},
+ examples: action.examples,
schema: {
input: action.schema?.input
? zodToJsonSchema(action.schema.input(z))
@@ -97,15 +132,9 @@ export class DefaultActionsRegistryService implements ActionsRegistryService {
'/.backstage/actions/v1/actions/:actionId/invoke',
async (req, res) => {
const credentials = await this.httpAuth.credentials(req);
- if (this.auth.isPrincipal(credentials, 'user')) {
- if (!credentials.principal.actor) {
- throw new NotAllowedError(
- `Actions must be invoked by a service, not a user`,
- );
- }
- } else if (this.auth.isPrincipal(credentials, 'none')) {
+ if (this.auth.isPrincipal(credentials, 'none')) {
throw new NotAllowedError(
- `Actions must be invoked by a service, not an anonymous request`,
+ `Actions must be invoked by an authenticated principal, not an anonymous request`,
);
}
@@ -115,6 +144,18 @@ export class DefaultActionsRegistryService implements ActionsRegistryService {
throw new NotFoundError(`Action "${req.params.actionId}" not found`);
}
+ if (action.visibilityPermission) {
+ const [decision] = await this.permissions.authorize(
+ [{ permission: action.visibilityPermission }],
+ { credentials },
+ );
+ if (decision.result !== AuthorizeResult.ALLOW) {
+ throw new NotFoundError(
+ `Action "${req.params.actionId}" not found`,
+ );
+ }
+ }
+
const input = action.schema?.input
? action.schema.input(z).safeParse(req.body)
: ({ success: true, data: undefined } as const);
@@ -159,6 +200,38 @@ export class DefaultActionsRegistryService implements ActionsRegistryService {
throw new Error(`Action with id "${id}" is already registered`);
}
+ if (options.visibilityPermission) {
+ this.permissionsRegistry.addPermissions([options.visibilityPermission]);
+ }
+
this.actions.set(id, options);
}
+
+ private async filterByPermissions(
+ entries: ActionEntry[],
+ credentials: BackstageCredentials,
+ ): Promise {
+ const permissionedEntries = entries.filter(
+ ([_, action]) => action.visibilityPermission,
+ );
+
+ if (permissionedEntries.length === 0) {
+ return entries;
+ }
+
+ const decisions = await this.permissions.authorize(
+ permissionedEntries.map(([_, action]) => ({
+ permission: action.visibilityPermission!,
+ })),
+ { credentials },
+ );
+
+ const deniedIds = new Set(
+ permissionedEntries
+ .filter((_, index) => decisions[index].result !== AuthorizeResult.ALLOW)
+ .map(([id]) => id),
+ );
+
+ return entries.filter(([id]) => !deniedIds.has(id));
+ }
}
diff --git a/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.test.ts b/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.test.ts
index 1e7c27960e..39392c101c 100644
--- a/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.test.ts
+++ b/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.test.ts
@@ -24,6 +24,10 @@ import request from 'supertest';
import { actionsRegistryServiceFactory } from './actionsRegistryServiceFactory';
import { InputError, NotFoundError } from '@backstage/errors';
import { actionsRegistryServiceRef } from '@backstage/backend-plugin-api/alpha';
+import {
+ AuthorizeResult,
+ createPermission,
+} from '@backstage/plugin-permission-common';
describe('actionsRegistryServiceFactory', () => {
const defaultServices = [
@@ -107,6 +111,57 @@ describe('actionsRegistryServiceFactory', () => {
expect(true).toBe(true);
});
+
+ it('should enforce types on example input and output', () => {
+ createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'test',
+ title: 'Test',
+ description: 'Test',
+ schema: {
+ input: z =>
+ z.object({
+ name: z.string(),
+ }),
+ output: z =>
+ z.object({
+ ok: z.boolean(),
+ }),
+ },
+ examples: [
+ {
+ title: 'Valid example',
+ input: { name: 'test' },
+ output: { ok: true },
+ },
+ {
+ title: 'Bad input',
+ // @ts-expect-error - name must be a string
+ input: { name: 123 },
+ },
+ {
+ title: 'Bad output',
+ input: { name: 'test' },
+ // @ts-expect-error - ok must be a boolean
+ output: { ok: 'yes' },
+ },
+ ],
+ action: async () => ({ output: { ok: true } }),
+ });
+ },
+ });
+ },
+ });
+
+ expect(true).toBe(true);
+ });
});
describe('/.backstage/actions/v1/actions', () => {
@@ -282,6 +337,79 @@ describe('actionsRegistryServiceFactory', () => {
});
});
+ it('should return examples in the action list', async () => {
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'test',
+ title: 'Test',
+ description: 'Test',
+ schema: {
+ input: z =>
+ z.object({
+ name: z.string(),
+ }),
+ output: z =>
+ z.object({
+ ok: z.boolean(),
+ }),
+ },
+ examples: [
+ {
+ title: 'Basic usage',
+ description: 'A simple example',
+ input: { name: 'world' },
+ output: { ok: true },
+ },
+ {
+ title: 'Without output',
+ input: { name: 'test' },
+ },
+ ],
+ action: async () => ({ output: { ok: true } }),
+ });
+ },
+ });
+ },
+ });
+
+ const { server } = await startTestBackend({
+ features: [pluginSubject, ...defaultServices],
+ });
+
+ const { body, status } = await request(server).get(
+ '/api/my-plugin/.backstage/actions/v1/actions',
+ );
+
+ expect(status).toBe(200);
+
+ expect(body).toMatchObject({
+ actions: [
+ {
+ name: 'test',
+ examples: [
+ {
+ title: 'Basic usage',
+ description: 'A simple example',
+ input: { name: 'world' },
+ output: { ok: true },
+ },
+ {
+ title: 'Without output',
+ input: { name: 'test' },
+ },
+ ],
+ },
+ ],
+ });
+ });
+
it('should forces registration of input and output schema as objects', async () => {
const pluginSubject = createBackendPlugin({
pluginId: 'my-plugin',
@@ -439,7 +567,7 @@ describe('actionsRegistryServiceFactory', () => {
});
});
- it('should throw an error if the action is invoked by a user', async () => {
+ it('should allow actions to be invoked by a user', async () => {
const testServices = [
actionsRegistryServiceFactory,
httpRouterServiceFactory,
@@ -460,12 +588,8 @@ describe('actionsRegistryServiceFactory', () => {
name: 'test',
});
- expect(status).toBe(403);
- expect(body).toMatchObject({
- error: {
- message: 'Actions must be invoked by a service, not a user',
- },
- });
+ expect(status).toBe(200);
+ expect(body).toMatchObject({ output: { ok: true } });
});
it('should validate the output of the action if provided', async () => {
@@ -558,4 +682,311 @@ describe('actionsRegistryServiceFactory', () => {
});
});
});
+
+ describe('permissions', () => {
+ const testPermission = createPermission({
+ name: 'test.action.use',
+ attributes: {},
+ });
+
+ it('should filter out actions with denied permissions when listing', async () => {
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'public-action',
+ title: 'Public Action',
+ description: 'No permission required',
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({}),
+ },
+ action: async () => ({ output: {} }),
+ });
+ actionsRegistry.register({
+ name: 'protected-action',
+ title: 'Protected Action',
+ description: 'Permission required',
+ visibilityPermission: testPermission,
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({}),
+ },
+ action: async () => ({ output: {} }),
+ });
+ },
+ });
+ },
+ });
+
+ const { server } = await startTestBackend({
+ features: [
+ pluginSubject,
+ actionsRegistryServiceFactory,
+ httpRouterServiceFactory,
+ mockServices.httpAuth.factory({
+ defaultCredentials: mockCredentials.service('user:default/mock'),
+ }),
+ mockServices.permissions.factory({
+ result: AuthorizeResult.DENY,
+ }),
+ ],
+ });
+
+ const { body, status } = await request(server).get(
+ '/api/my-plugin/.backstage/actions/v1/actions',
+ );
+
+ expect(status).toBe(200);
+ expect(body.actions).toHaveLength(1);
+ expect(body.actions[0].name).toBe('public-action');
+ });
+
+ it('should include actions with allowed permissions when listing', async () => {
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'protected-action',
+ title: 'Protected Action',
+ description: 'Permission required',
+ visibilityPermission: testPermission,
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({}),
+ },
+ action: async () => ({ output: {} }),
+ });
+ },
+ });
+ },
+ });
+
+ const { server } = await startTestBackend({
+ features: [
+ pluginSubject,
+ actionsRegistryServiceFactory,
+ httpRouterServiceFactory,
+ mockServices.httpAuth.factory({
+ defaultCredentials: mockCredentials.service('user:default/mock'),
+ }),
+ mockServices.permissions.factory({
+ result: AuthorizeResult.ALLOW,
+ }),
+ ],
+ });
+
+ const { body, status } = await request(server).get(
+ '/api/my-plugin/.backstage/actions/v1/actions',
+ );
+
+ expect(status).toBe(200);
+ expect(body.actions).toHaveLength(1);
+ expect(body.actions[0].name).toBe('protected-action');
+ });
+
+ it('should return 404 when invoking an action with denied permission', async () => {
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'protected-action',
+ title: 'Protected Action',
+ description: 'Permission required',
+ visibilityPermission: testPermission,
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({}),
+ },
+ action: async () => ({ output: {} }),
+ });
+ },
+ });
+ },
+ });
+
+ const { server } = await startTestBackend({
+ features: [
+ pluginSubject,
+ actionsRegistryServiceFactory,
+ httpRouterServiceFactory,
+ mockServices.httpAuth.factory({
+ defaultCredentials: mockCredentials.service('user:default/mock'),
+ }),
+ mockServices.permissions.factory({
+ result: AuthorizeResult.DENY,
+ }),
+ ],
+ });
+
+ const { body, status } = await request(server).post(
+ '/api/my-plugin/.backstage/actions/v1/actions/my-plugin:protected-action/invoke',
+ );
+
+ expect(status).toBe(404);
+ expect(body).toMatchObject({
+ error: {
+ message: 'Action "my-plugin:protected-action" not found',
+ },
+ });
+ });
+
+ it('should allow invoking an action when permission is granted', async () => {
+ const mockAction = jest.fn().mockResolvedValue({ output: { ok: true } });
+
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'protected-action',
+ title: 'Protected Action',
+ description: 'Permission required',
+ visibilityPermission: testPermission,
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({ ok: z.boolean() }),
+ },
+ action: mockAction,
+ });
+ },
+ });
+ },
+ });
+
+ const { server } = await startTestBackend({
+ features: [
+ pluginSubject,
+ actionsRegistryServiceFactory,
+ httpRouterServiceFactory,
+ mockServices.httpAuth.factory({
+ defaultCredentials: mockCredentials.service('user:default/mock'),
+ }),
+ mockServices.permissions.factory({
+ result: AuthorizeResult.ALLOW,
+ }),
+ ],
+ });
+
+ const { body, status } = await request(server).post(
+ '/api/my-plugin/.backstage/actions/v1/actions/my-plugin:protected-action/invoke',
+ );
+
+ expect(status).toBe(200);
+ expect(body).toMatchObject({ output: { ok: true } });
+ expect(mockAction).toHaveBeenCalled();
+ });
+
+ it('should pass the correct permission to the authorize call', async () => {
+ const permissionsMock = mockServices.permissions.mock({
+ authorize: async () => [{ result: AuthorizeResult.ALLOW }],
+ });
+
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'protected-action',
+ title: 'Protected Action',
+ description: 'Permission required',
+ visibilityPermission: testPermission,
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({}),
+ },
+ action: async () => ({ output: {} }),
+ });
+ },
+ });
+ },
+ });
+
+ const { server } = await startTestBackend({
+ features: [
+ pluginSubject,
+ actionsRegistryServiceFactory,
+ httpRouterServiceFactory,
+ mockServices.httpAuth.factory({
+ defaultCredentials: mockCredentials.service('user:default/mock'),
+ }),
+ permissionsMock.factory,
+ ],
+ });
+
+ await request(server).get('/api/my-plugin/.backstage/actions/v1/actions');
+
+ expect(permissionsMock.authorize).toHaveBeenCalledWith(
+ [{ permission: testPermission }],
+ expect.objectContaining({ credentials: expect.anything() }),
+ );
+ });
+
+ it('should register the permission with the permissions registry', async () => {
+ const permissionsRegistryMock = mockServices.permissionsRegistry.mock();
+
+ const pluginSubject = createBackendPlugin({
+ pluginId: 'my-plugin',
+ register(reg) {
+ reg.registerInit({
+ deps: {
+ actionsRegistry: actionsRegistryServiceRef,
+ },
+ async init({ actionsRegistry }) {
+ actionsRegistry.register({
+ name: 'protected-action',
+ title: 'Protected Action',
+ description: 'Permission required',
+ visibilityPermission: testPermission,
+ schema: {
+ input: z => z.object({}),
+ output: z => z.object({}),
+ },
+ action: async () => ({ output: {} }),
+ });
+ },
+ });
+ },
+ });
+
+ await startTestBackend({
+ features: [
+ pluginSubject,
+ actionsRegistryServiceFactory,
+ httpRouterServiceFactory,
+ mockServices.httpAuth.factory({
+ defaultCredentials: mockCredentials.service('user:default/mock'),
+ }),
+ permissionsRegistryMock.factory,
+ ],
+ });
+
+ expect(permissionsRegistryMock.addPermissions).toHaveBeenCalledWith([
+ testPermission,
+ ]);
+ });
+ });
});
diff --git a/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.ts b/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.ts
index 8c19b8148c..4ac6b2c782 100644
--- a/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.ts
+++ b/packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.ts
@@ -32,13 +32,25 @@ export const actionsRegistryServiceFactory = createServiceFactory({
httpAuth: coreServices.httpAuth,
logger: coreServices.logger,
auth: coreServices.auth,
+ permissions: coreServices.permissions,
+ permissionsRegistry: coreServices.permissionsRegistry,
},
- factory: ({ metadata, httpRouter, httpAuth, logger, auth }) => {
+ factory: ({
+ metadata,
+ httpRouter,
+ httpAuth,
+ logger,
+ auth,
+ permissions,
+ permissionsRegistry,
+ }) => {
const actionsRegistryService = DefaultActionsRegistryService.create({
httpAuth,
logger,
auth,
metadata,
+ permissions,
+ permissionsRegistry,
});
httpRouter.use(actionsRegistryService.createRouter());
diff --git a/packages/backend-defaults/src/entrypoints/auditor/utils.ts b/packages/backend-defaults/src/entrypoints/auditor/utils.ts
index 719a227bf9..0513aa84b2 100644
--- a/packages/backend-defaults/src/entrypoints/auditor/utils.ts
+++ b/packages/backend-defaults/src/entrypoints/auditor/utils.ts
@@ -16,8 +16,20 @@
import type { Config } from '@backstage/config';
import { InputError } from '@backstage/errors';
-import { z } from 'zod';
-import { CONFIG_ROOT_KEY, severityLogLevelMappingsSchema } from './types';
+import { z } from 'zod/v4';
+
+const CONFIG_ROOT_KEY = 'backend.auditor';
+
+const logLevel = z.enum(['debug', 'info', 'warn', 'error']);
+
+const severityLogLevelMappingsSchema = z.object({
+ low: logLevel.default('debug'),
+ medium: logLevel.default('info'),
+ high: logLevel.default('info'),
+ critical: logLevel.default('info'),
+});
+
+type SeverityLogLevelMappings = z.infer;
/**
* Gets the `backend.auditor.severityLogLevelMappings` configuration.
@@ -26,41 +38,32 @@ import { CONFIG_ROOT_KEY, severityLogLevelMappingsSchema } from './types';
* @returns The validated severity-to-log-level mappings.
* @throws error - {@link @backstage/errors#InputError} if the mapping configuration is invalid.
*/
-export function getSeverityLogLevelMappings(config: Config) {
+export function getSeverityLogLevelMappings(
+ config: Config,
+): SeverityLogLevelMappings {
const auditorConfig = config.getOptionalConfig(CONFIG_ROOT_KEY);
- const severityLogLevelMappings = {
- low:
- auditorConfig?.getOptionalString('severityLogLevelMappings.low') ??
- 'debug',
- medium:
- auditorConfig?.getOptionalString('severityLogLevelMappings.medium') ??
- 'info',
- high:
- auditorConfig?.getOptionalString('severityLogLevelMappings.high') ??
- 'info',
- critical:
- auditorConfig?.getOptionalString('severityLogLevelMappings.critical') ??
- 'info',
- } as Required>;
+ const input = {
+ low: auditorConfig?.getOptionalString('severityLogLevelMappings.low'),
+ medium: auditorConfig?.getOptionalString('severityLogLevelMappings.medium'),
+ high: auditorConfig?.getOptionalString('severityLogLevelMappings.high'),
+ critical: auditorConfig?.getOptionalString(
+ 'severityLogLevelMappings.critical',
+ ),
+ };
- const res = severityLogLevelMappingsSchema.safeParse(
- severityLogLevelMappings,
- );
- if (!res.success) {
- const key = res.error.issues.at(0)?.path.at(0) as string;
- const value = (
- res.error.issues.at(0) as unknown as Record
- ).received as string;
- const validKeys = (
- res.error.issues.at(0) as unknown as Record
- ).options as string[];
+ const parsed = severityLogLevelMappingsSchema.safeParse(input);
+
+ if (!parsed.success) {
+ const issue = parsed.error.issues[0];
+ const key = issue.path[0] as keyof typeof input;
+ const receivedValue = input[key];
throw new InputError(
- `The configuration value for 'backend.auditor.severityLogLevelMappings.${key}' was given an invalid value: '${value}'. Expected one of the following valid values: '${validKeys.join(
+ `The configuration value for '${CONFIG_ROOT_KEY}.severityLogLevelMappings.${key}' was given an invalid value: '${receivedValue}'. Expected one of the following valid values: '${logLevel.options.join(
', ',
)}'.`,
);
}
- return severityLogLevelMappings;
+ return parsed.data;
}
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.test.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.test.ts
index 14fedfb3c0..04c2b17ad3 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.test.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.test.ts
@@ -16,6 +16,7 @@
import { LocalTaskWorker } from './LocalTaskWorker';
import { mockServices } from '@backstage/backend-test-utils';
+import { ConflictError } from '@backstage/errors';
import waitFor from 'wait-for-expect';
jest.setTimeout(10_000);
@@ -110,6 +111,54 @@ describe('LocalTaskWorker', () => {
controller.abort();
});
+ it('can cancel a running task', async () => {
+ let receivedSignal: AbortSignal | undefined;
+ const fn = jest.fn(async (signal: AbortSignal) => {
+ receivedSignal = signal;
+ await new Promise(r => setTimeout(r, 5000));
+ });
+ const controller = new AbortController();
+
+ const worker = new LocalTaskWorker('a', fn, logger);
+ worker.start(
+ {
+ version: 2,
+ cadence: 'PT10S',
+ timeoutAfterDuration: 'PT10S',
+ },
+ { signal: controller.signal },
+ );
+
+ await waitFor(() => {
+ expect(fn).toHaveBeenCalledTimes(1);
+ });
+
+ expect(receivedSignal?.aborted).toBe(false);
+ worker.cancel();
+ expect(receivedSignal?.aborted).toBe(true);
+
+ controller.abort();
+ });
+
+ it('cannot cancel a task that is not running', async () => {
+ const fn = jest.fn();
+ const controller = new AbortController();
+
+ const worker = new LocalTaskWorker('a', fn, logger);
+ worker.start(
+ {
+ version: 2,
+ initialDelayDuration: 'PT1000S',
+ cadence: 'PT10S',
+ timeoutAfterDuration: 'PT10S',
+ },
+ { signal: controller.signal },
+ );
+
+ expect(() => worker.cancel()).toThrow(ConflictError);
+ controller.abort();
+ });
+
it('goes through the expected states', async () => {
const fn = jest
.fn()
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.ts
index efecb1c0ed..168649436c 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/LocalTaskWorker.ts
@@ -29,6 +29,7 @@ import { delegateAbortController, serializeError, sleep } from './util';
*/
export class LocalTaskWorker {
private abortWait: AbortController | undefined;
+ private taskAbortController: AbortController | undefined;
#taskState: Exclude = {
status: 'idle',
};
@@ -93,6 +94,13 @@ export class LocalTaskWorker {
this.abortWait.abort();
}
+ cancel(): void {
+ if (!this.taskAbortController) {
+ throw new ConflictError(`Task ${this.taskId} is not running`);
+ }
+ this.taskAbortController.abort();
+ }
+
taskState(): TaskApiTasksResponse['taskState'] {
return this.#taskState;
}
@@ -134,10 +142,10 @@ export class LocalTaskWorker {
): Promise {
// Abort the task execution either if the worker is stopped, or if the
// task timeout is hit
- const taskAbortController = delegateAbortController(signal);
+ this.taskAbortController = delegateAbortController(signal);
const timeoutDuration = Duration.fromISO(settings.timeoutAfterDuration);
const timeoutHandle = setTimeout(() => {
- taskAbortController.abort();
+ this.taskAbortController?.abort();
}, timeoutDuration.as('milliseconds'));
this.#taskState = {
@@ -152,7 +160,7 @@ export class LocalTaskWorker {
};
try {
- await this.fn(taskAbortController.signal);
+ await this.fn(this.taskAbortController.signal);
this.#taskState.lastRunEndedAt = DateTime.utc().toISO()!;
this.#taskState.lastRunError = undefined;
} catch (e) {
@@ -162,7 +170,8 @@ export class LocalTaskWorker {
// release resources
clearTimeout(timeoutHandle);
- taskAbortController.abort();
+ this.taskAbortController.abort();
+ this.taskAbortController = undefined;
}
/**
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.test.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.test.ts
index 2148148c9e..cc8aac5f51 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.test.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.test.ts
@@ -399,6 +399,100 @@ describe('PluginTaskManagerImpl', () => {
);
});
+ describe('cancelTask with local scope', () => {
+ it('can cancel a running task', async () => {
+ const { manager } = await init('SQLITE_3');
+
+ const promise = createDeferred();
+
+ await manager.scheduleTask({
+ id: 'task1',
+ timeout: Duration.fromMillis(5000),
+ frequency: Duration.fromObject({ years: 1 }),
+ fn: async () => {
+ promise.resolve();
+ await new Promise(r => setTimeout(r, 20000));
+ },
+ scope: 'local',
+ });
+
+ await promise;
+ await expect(manager.cancelTask('task1')).resolves.toBeUndefined();
+ }, 60_000);
+
+ it('cannot cancel a task that is not running', async () => {
+ const { manager } = await init('SQLITE_3');
+
+ const fn = jest.fn();
+ await manager.scheduleTask({
+ id: 'task1',
+ timeout: Duration.fromMillis(5000),
+ frequency: Duration.fromObject({ years: 1 }),
+ initialDelay: Duration.fromObject({ years: 1 }),
+ fn,
+ scope: 'local',
+ });
+
+ await expect(manager.cancelTask('task1')).rejects.toThrow(ConflictError);
+ }, 60_000);
+ });
+
+ describe('cancelTask with global scope', () => {
+ it.each(databases.eachSupportedId())(
+ 'can cancel a running task, %p',
+ async databaseId => {
+ const { manager } = await init(databaseId);
+
+ const promise = createDeferred();
+
+ await manager.scheduleTask({
+ id: 'task1',
+ timeout: Duration.fromMillis(5000),
+ frequency: Duration.fromObject({ years: 1 }),
+ fn: async () => {
+ promise.resolve();
+ await new Promise(r => setTimeout(r, 20000));
+ },
+ scope: 'global',
+ });
+
+ await promise;
+ await expect(manager.cancelTask('task1')).resolves.toBeUndefined();
+ },
+ );
+
+ it.each(databases.eachSupportedId())(
+ 'cannot cancel a non-existent task, %p',
+ async databaseId => {
+ const { manager } = await init(databaseId);
+
+ await expect(manager.cancelTask('nonexistent')).rejects.toThrow(
+ NotFoundError,
+ );
+ },
+ );
+
+ it.each(databases.eachSupportedId())(
+ 'cannot cancel a task that is not running, %p',
+ async databaseId => {
+ const { manager } = await init(databaseId);
+
+ await manager.scheduleTask({
+ id: 'task1',
+ timeout: Duration.fromMillis(5000),
+ frequency: Duration.fromObject({ years: 1 }),
+ initialDelay: Duration.fromObject({ years: 1 }),
+ fn: jest.fn(),
+ scope: 'global',
+ });
+
+ await expect(manager.cancelTask('task1')).rejects.toThrow(
+ ConflictError,
+ );
+ },
+ );
+ });
+
describe('parseDuration', () => {
it('should parse durations', () => {
expect(parseDuration({ milliseconds: 5000 })).toEqual('PT5S');
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.ts
index e711744123..2aad8647fe 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/PluginTaskSchedulerImpl.ts
@@ -107,6 +107,17 @@ export class PluginTaskSchedulerImpl implements SchedulerService {
await TaskWorker.trigger(knex, id);
}
+ async cancelTask(id: string): Promise {
+ const localTask = this.localWorkersById.get(id);
+ if (localTask) {
+ localTask.cancel();
+ return;
+ }
+
+ const knex = await this.databaseFactory();
+ await TaskWorker.cancel(knex, id);
+ }
+
async scheduleTask(
task: SchedulerServiceTaskScheduleDefinition &
SchedulerServiceTaskInvocationDefinition,
@@ -206,6 +217,15 @@ export class PluginTaskSchedulerImpl implements SchedulerService {
},
);
+ router.post(
+ '/.backstage/scheduler/v1/tasks/:id/cancel',
+ async (req, res) => {
+ const { id } = req.params;
+ await this.cancelTask(id);
+ res.status(200).end();
+ },
+ );
+
return router;
}
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.test.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.test.ts
index 5bd3fb38cb..2f690ef499 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.test.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.test.ts
@@ -15,6 +15,7 @@
*/
import { TestDatabases, mockServices } from '@backstage/backend-test-utils';
+import { ConflictError, NotFoundError } from '@backstage/errors';
import { DateTime, Duration } from 'luxon';
import waitForExpect from 'wait-for-expect';
import { migrateBackendTasks } from '../database/migrateBackendTasks';
@@ -25,123 +26,154 @@ import { TaskSettingsV2 } from './types';
jest.setTimeout(60_000);
-describe('TaskWorker', () => {
+const databases = TestDatabases.create();
+
+describe.each(databases.eachSupportedId())('TaskWorker, %s', databaseId => {
const logger = mockServices.logger.mock();
- const databases = TestDatabases.create();
const testScopedSignal = createTestScopedSignal();
- beforeEach(() => {
+ let knex: Awaited>;
+
+ beforeEach(async () => {
+ knex = await databases.init(databaseId);
+ await migrateBackendTasks(knex);
jest.resetAllMocks();
});
- it.each(databases.eachSupportedId())(
- 'goes through the expected states, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ afterEach(async () => {
+ await knex?.destroy();
+ });
- const fn = jest.fn(
- async () => new Promise(resolve => setTimeout(resolve, 50)),
- );
- const settings: TaskSettingsV2 = {
- version: 2,
- cadence: '*/2 * * * * *',
- initialDelayDuration: Duration.fromObject({ seconds: 3 }).toISO()!, // over 1 second, to cover for 1-second granularity in some database timestamps
- timeoutAfterDuration: Duration.fromObject({ minutes: 1 }).toISO()!,
- };
+ it('goes through the expected states', async () => {
+ const fn = jest.fn(
+ async () => new Promise(resolve => setTimeout(resolve, 50)),
+ );
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ cadence: '*/2 * * * * *',
+ initialDelayDuration: Duration.fromObject({ seconds: 3 }).toISO()!, // over 1 second, to cover for 1-second granularity in some database timestamps
+ timeoutAfterDuration: Duration.fromObject({ minutes: 1 }).toISO()!,
+ };
- const worker = new TaskWorker('task1', fn, knex, logger);
- await worker.persistTask(settings);
+ const worker = new TaskWorker('task1', fn, knex, logger);
+ await worker.persistTask(settings);
- let row = (await knex(DB_TASKS_TABLE))[0];
- expect(row).toEqual(
- expect.objectContaining({
- id: 'task1',
- current_run_ticket: null,
- current_run_started_at: null,
- current_run_expires_at: null,
- }),
- );
- expect(JSON.parse(row.settings_json)).toEqual({
- version: 2,
- cadence: '*/2 * * * * *',
- initialDelayDuration: 'PT3S',
- timeoutAfterDuration: 'PT1M',
- });
- await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
- new Map([
- [
- 'task1',
- {
- status: 'idle',
- startsAt: expect.anything(),
- },
- ],
- ]),
- );
+ let row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row).toEqual(
+ expect.objectContaining({
+ id: 'task1',
+ current_run_ticket: null,
+ current_run_started_at: null,
+ current_run_expires_at: null,
+ }),
+ );
+ expect(JSON.parse(row.settings_json)).toEqual({
+ version: 2,
+ cadence: '*/2 * * * * *',
+ initialDelayDuration: 'PT3S',
+ timeoutAfterDuration: 'PT1M',
+ });
+ await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
+ new Map([
+ [
+ 'task1',
+ {
+ status: 'idle',
+ startsAt: expect.anything(),
+ },
+ ],
+ ]),
+ );
- // Note that this is timing sensitive - if things take too long between
- // persistTask and findReadyTask, this test will fail. We set some margin
- // of initialDelayDuration to cover for this, but if this turns out to be
- // flaky, we may have to revisit how this test is written.
+ // Note that this is timing sensitive - if things take too long between
+ // persistTask and findReadyTask, this test will fail. We set some margin
+ // of initialDelayDuration to cover for this, but if this turns out to be
+ // flaky, we may have to revisit how this test is written.
+ await expect(worker.findReadyTask()).resolves.toEqual({
+ result: 'not-ready-yet',
+ });
+
+ await waitForExpect(async () => {
await expect(worker.findReadyTask()).resolves.toEqual({
- result: 'not-ready-yet',
+ result: 'ready',
+ settings,
});
+ });
- await waitForExpect(async () => {
- await expect(worker.findReadyTask()).resolves.toEqual({
- result: 'ready',
- settings,
- });
- });
+ row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row).toEqual(
+ expect.objectContaining({
+ id: 'task1',
+ current_run_ticket: null,
+ current_run_started_at: null,
+ current_run_expires_at: null,
+ }),
+ );
- row = (await knex(DB_TASKS_TABLE))[0];
- expect(row).toEqual(
- expect.objectContaining({
- id: 'task1',
- current_run_ticket: null,
- current_run_started_at: null,
- current_run_expires_at: null,
- }),
- );
+ await expect(worker.tryClaimTask('ticket', settings)).resolves.toBe(true);
- await expect(worker.tryClaimTask('ticket', settings)).resolves.toBe(true);
+ row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row).toEqual(
+ expect.objectContaining({
+ id: 'task1',
+ current_run_ticket: 'ticket',
+ current_run_started_at: expect.anything(),
+ current_run_expires_at: expect.anything(),
+ }),
+ );
+ await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
+ new Map([
+ [
+ 'task1',
+ {
+ status: 'running',
+ startedAt: expect.anything(),
+ timesOutAt: expect.anything(),
+ },
+ ],
+ ]),
+ );
- row = (await knex(DB_TASKS_TABLE))[0];
- expect(row).toEqual(
- expect.objectContaining({
- id: 'task1',
- current_run_ticket: 'ticket',
- current_run_started_at: expect.anything(),
- current_run_expires_at: expect.anything(),
- }),
- );
- await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
- new Map([
- [
- 'task1',
- {
- status: 'running',
- startedAt: expect.anything(),
- timesOutAt: expect.anything(),
- },
- ],
- ]),
- );
+ await expect(worker.tryReleaseTask('ticket', settings)).resolves.toBe(true);
- await expect(worker.tryReleaseTask('ticket', settings)).resolves.toBe(
- true,
- );
+ row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row).toEqual(
+ expect.objectContaining({
+ id: 'task1',
+ current_run_ticket: null,
+ current_run_started_at: null,
+ current_run_expires_at: null,
+ }),
+ );
+ await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
+ new Map([
+ [
+ 'task1',
+ {
+ status: 'idle',
+ startsAt: expect.anything(),
+ lastRunEndedAt: expect.anything(),
+ },
+ ],
+ ]),
+ );
+ });
- row = (await knex(DB_TASKS_TABLE))[0];
- expect(row).toEqual(
- expect.objectContaining({
- id: 'task1',
- current_run_ticket: null,
- current_run_started_at: null,
- current_run_expires_at: null,
- }),
- );
+ it('logs error when the task throws', async () => {
+ jest.spyOn(logger, 'error');
+ const fn = jest.fn().mockRejectedValue(new Error('failed'));
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ initialDelayDuration: undefined,
+ cadence: '* * * * * *',
+ timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
+ };
+ const checkFrequency = Duration.fromObject({ milliseconds: 100 });
+ const worker = new TaskWorker('task1', fn, knex, logger, checkFrequency);
+ worker.start(settings, { signal: testScopedSignal() });
+
+ await waitForExpect(async () => {
+ expect(logger.error).toHaveBeenCalled();
await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
new Map([
[
@@ -150,438 +182,386 @@ describe('TaskWorker', () => {
status: 'idle',
startsAt: expect.anything(),
lastRunEndedAt: expect.anything(),
+ lastRunError: expect.stringContaining('failed'),
},
],
]),
);
- },
- );
+ });
+ });
- it.each(databases.eachSupportedId())(
- 'logs error when the task throws, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ it('runs tasks more than once even when the task throws', async () => {
+ const fn = jest.fn().mockRejectedValue(new Error('failed'));
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ initialDelayDuration: undefined,
+ cadence: '* * * * * *',
+ timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
+ };
+ const checkFrequency = Duration.fromObject({ milliseconds: 100 });
+ const worker = new TaskWorker('task1', fn, knex, logger, checkFrequency);
+ worker.start(settings, { signal: testScopedSignal() });
- jest.spyOn(logger, 'error');
- const fn = jest.fn().mockRejectedValue(new Error('failed'));
- const settings: TaskSettingsV2 = {
- version: 2,
- initialDelayDuration: undefined,
- cadence: '* * * * * *',
- timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
- };
- const checkFrequency = Duration.fromObject({ milliseconds: 100 });
- const worker = new TaskWorker('task1', fn, knex, logger, checkFrequency);
- worker.start(settings, { signal: testScopedSignal() });
+ await waitForExpect(() => {
+ expect(fn).toHaveBeenCalledTimes(3);
+ });
+ });
- await waitForExpect(async () => {
- expect(logger.error).toHaveBeenCalled();
- await expect(TaskWorker.taskStates(knex)).resolves.toEqual(
- new Map([
- [
- 'task1',
- {
- status: 'idle',
- startsAt: expect.anything(),
- lastRunEndedAt: expect.anything(),
- lastRunError: expect.stringContaining('failed'),
- },
- ],
- ]),
- );
+ it('does not clobber ticket lock when stolen', async () => {
+ const fn = jest.fn(
+ async () => new Promise(resolve => setTimeout(resolve, 50)),
+ );
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ initialDelayDuration: undefined,
+ cadence: '* * * * * *',
+ timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
+ };
+
+ const worker = new TaskWorker('task1', fn, knex, logger);
+ await worker.persistTask(settings);
+
+ await waitForExpect(async () => {
+ await expect(worker.findReadyTask()).resolves.toEqual({
+ result: 'ready',
+ settings,
});
- },
- );
+ });
- it.each(databases.eachSupportedId())(
- 'runs tasks more than once even when the task throws, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ await expect(worker.tryClaimTask('ticket', settings)).resolves.toBe(true);
- const fn = jest.fn().mockRejectedValue(new Error('failed'));
- const settings: TaskSettingsV2 = {
- version: 2,
- initialDelayDuration: undefined,
- cadence: '* * * * * *',
- timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
- };
- const checkFrequency = Duration.fromObject({ milliseconds: 100 });
- const worker = new TaskWorker('task1', fn, knex, logger, checkFrequency);
- worker.start(settings, { signal: testScopedSignal() });
+ let row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row).toEqual(
+ expect.objectContaining({
+ id: 'task1',
+ current_run_ticket: 'ticket',
+ current_run_started_at: expect.anything(),
+ current_run_expires_at: expect.anything(),
+ }),
+ );
- await waitForExpect(() => {
- expect(fn).toHaveBeenCalledTimes(3);
+ await knex(DB_TASKS_TABLE)
+ .where('id', '=', 'task1')
+ .update({ current_run_ticket: 'stolen' });
+
+ await expect(worker.tryReleaseTask('ticket', settings)).resolves.toBe(
+ false,
+ );
+
+ row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row).toEqual(
+ expect.objectContaining({
+ id: 'task1',
+ current_run_ticket: 'stolen',
+ current_run_started_at: expect.anything(),
+ current_run_expires_at: expect.anything(),
+ }),
+ );
+ });
+
+ it('gracefully handles a disappeared task row', async () => {
+ const fn = jest.fn(async () => {});
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ initialDelayDuration: undefined,
+ cadence: '* * * * * *',
+ timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
+ };
+
+ const worker1 = new TaskWorker('task1', fn, knex, logger);
+ await worker1.persistTask(settings);
+ await knex(DB_TASKS_TABLE).where('id', '=', 'task1').delete();
+ await expect(worker1.findReadyTask()).resolves.toEqual({
+ result: 'abort',
+ });
+
+ const worker2 = new TaskWorker('task2', fn, knex, logger);
+ await worker2.persistTask(settings);
+
+ await waitForExpect(async () => {
+ await expect(worker2.findReadyTask()).resolves.toEqual({
+ result: 'ready',
+ settings,
});
- },
- );
+ });
- it.each(databases.eachSupportedId())(
- 'does not clobber ticket lock when stolen, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ await knex(DB_TASKS_TABLE).where('id', '=', 'task2').delete();
+ await expect(worker2.tryClaimTask('ticket', settings)).resolves.toBe(false);
- const fn = jest.fn(
- async () => new Promise(resolve => setTimeout(resolve, 50)),
- );
- const settings: TaskSettingsV2 = {
- version: 2,
- initialDelayDuration: undefined,
- cadence: '* * * * * *',
- timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
- };
+ const worker3 = new TaskWorker('task3', fn, knex, logger);
+ await worker3.persistTask(settings);
- const worker = new TaskWorker('task1', fn, knex, logger);
- await worker.persistTask(settings);
-
- await waitForExpect(async () => {
- await expect(worker.findReadyTask()).resolves.toEqual({
- result: 'ready',
- settings,
- });
+ await waitForExpect(async () => {
+ await expect(worker3.findReadyTask()).resolves.toEqual({
+ result: 'ready',
+ settings,
});
+ });
- await expect(worker.tryClaimTask('ticket', settings)).resolves.toBe(true);
+ await expect(worker3.tryClaimTask('ticket', settings)).resolves.toBe(true);
+ await knex(DB_TASKS_TABLE).where('id', '=', 'task3').delete();
+ await expect(worker3.tryReleaseTask('ticket', settings)).resolves.toBe(
+ false,
+ );
+ });
- let row = (await knex(DB_TASKS_TABLE))[0];
- expect(row).toEqual(
- expect.objectContaining({
- id: 'task1',
- current_run_ticket: 'ticket',
- current_run_started_at: expect.anything(),
- current_run_expires_at: expect.anything(),
- }),
- );
+ it('respects initialDelayDuration per worker', async () => {
+ const abortFirst = new AbortController();
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ initialDelayDuration: 'PT0.3S',
+ cadence: 'PT0.1S',
+ timeoutAfterDuration: 'PT10S',
+ };
- await knex(DB_TASKS_TABLE)
- .where('id', '=', 'task1')
- .update({ current_run_ticket: 'stolen' });
+ // Start a single worker and make sure it waits and then goes to work
+ const fn1 = jest.fn(async () => {});
+ const worker1 = new TaskWorker(
+ 'task1',
+ fn1,
+ knex,
+ logger,
+ Duration.fromMillis(10),
+ );
+ await worker1.start(settings, { signal: abortFirst.signal });
- await expect(worker.tryReleaseTask('ticket', settings)).resolves.toBe(
- false,
- );
+ expect(fn1).toHaveBeenCalledTimes(0);
+ await new Promise(resolve => setTimeout(resolve, 250));
+ expect(fn1).toHaveBeenCalledTimes(0);
+ await new Promise(resolve => setTimeout(resolve, 100));
+ expect(fn1.mock.calls.length).toBeGreaterThan(0);
- row = (await knex(DB_TASKS_TABLE))[0];
- expect(row).toEqual(
- expect.objectContaining({
- id: 'task1',
- current_run_ticket: 'stolen',
- current_run_started_at: expect.anything(),
- current_run_expires_at: expect.anything(),
- }),
- );
- },
- );
+ // Start a second worker and make sure it waits but the first worker still works along
+ const fn2 = jest.fn();
+ const promise2 = new Promise(resolve => fn2.mockImplementation(resolve));
+ const worker2 = new TaskWorker(
+ 'task1',
+ fn2,
+ knex,
+ logger,
+ Duration.fromMillis(10),
+ );
+ await worker2.start(settings, { signal: testScopedSignal() });
- it.each(databases.eachSupportedId())(
- 'gracefully handles a disappeared task row, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ // We eventually abort the first worker just to make sure that the second
+ // one for sure will get a go at running the task
+ setTimeout(() => abortFirst.abort(), 1000);
- const fn = jest.fn(async () => {});
- const settings: TaskSettingsV2 = {
- version: 2,
- initialDelayDuration: undefined,
- cadence: '* * * * * *',
- timeoutAfterDuration: Duration.fromMillis(60000).toISO()!,
- };
+ const before = fn1.mock.calls.length;
+ await promise2;
+ expect(fn1.mock.calls.length).toBeGreaterThan(before);
+ });
- const worker1 = new TaskWorker('task1', fn, knex, logger);
- await worker1.persistTask(settings);
- await knex(DB_TASKS_TABLE).where('id', '=', 'task1').delete();
- await expect(worker1.findReadyTask()).resolves.toEqual({
- result: 'abort',
- });
+ it('next_run_start_at is always the min between schedule changes from cron frequency', async () => {
+ const fn = jest.fn(
+ async () => new Promise(resolve => setTimeout(resolve, 50)),
+ );
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ cadence: '*/15 * * * *',
+ initialDelayDuration: 'PT2M',
+ timeoutAfterDuration: 'PT1M',
+ };
- const worker2 = new TaskWorker('task2', fn, knex, logger);
- await worker2.persistTask(settings);
+ const worker = new TaskWorker('task99', fn, knex, logger);
+ await worker.persistTask(settings);
+ const row1 = (await knex(DB_TASKS_TABLE))[0];
- await waitForExpect(async () => {
- await expect(worker2.findReadyTask()).resolves.toEqual({
- result: 'ready',
- settings,
- });
- });
+ const settings2 = {
+ ...settings,
+ cadence: '*/2 * * * *',
+ initialDelayDuration: 'PT1M',
+ };
+ await worker.persistTask(settings2);
+ const row2 = (await knex(DB_TASKS_TABLE))[0];
- await knex(DB_TASKS_TABLE).where('id', '=', 'task2').delete();
- await expect(worker2.tryClaimTask('ticket', settings)).resolves.toBe(
- false,
- );
+ expect(row2.next_run_start_at).not.toStrictEqual(row1.next_run_start_at);
- const worker3 = new TaskWorker('task3', fn, knex, logger);
- await worker3.persistTask(settings);
+ const settings3 = { ...settings };
+ await worker.persistTask(settings3);
+ const row3 = (await knex(DB_TASKS_TABLE))[0];
- await waitForExpect(async () => {
- await expect(worker3.findReadyTask()).resolves.toEqual({
- result: 'ready',
- settings,
- });
- });
+ // The new timestamp can basically be 0 or a minute depending on how the
+ // initialDelayDuration falls right on a cron boundary. This kinda
+ // contrived check removes a test flakiness based on wall clock time.
+ expect(
+ Math.abs(
+ +new Date(row3.next_run_start_at!) - +new Date(row2.next_run_start_at!),
+ ),
+ ).toBeLessThanOrEqual(60_000);
+ });
- await expect(worker3.tryClaimTask('ticket', settings)).resolves.toBe(
- true,
- );
- await knex(DB_TASKS_TABLE).where('id', '=', 'task3').delete();
- await expect(worker3.tryReleaseTask('ticket', settings)).resolves.toBe(
- false,
- );
- },
- );
+ it('next_run_start_at is always the min between schedule changes when using human duration frequency', async () => {
+ const fn = jest.fn(
+ async () => new Promise(resolve => setTimeout(resolve, 50)),
+ );
- it.each(databases.eachSupportedId())(
- 'respects initialDelayDuration per worker, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ const initialSettings: TaskSettingsV2 = {
+ version: 2,
+ cadence: 'PT120M',
+ timeoutAfterDuration: 'PT1M',
+ };
- const abortFirst = new AbortController();
- const settings: TaskSettingsV2 = {
- version: 2,
- initialDelayDuration: 'PT0.3S',
- cadence: 'PT0.1S',
- timeoutAfterDuration: 'PT10S',
- };
+ const worker = new TaskWorker('task99', fn, knex, logger);
+ await worker.persistTask(initialSettings);
+ // replicate task running, sets next_run_start_at based on cadence
+ await worker.tryClaimTask('ticket', initialSettings);
+ await worker.tryReleaseTask('ticket', initialSettings);
- // Start a single worker and make sure it waits and then goes to work
- const fn1 = jest.fn(async () => {});
- const worker1 = new TaskWorker(
- 'task1',
- fn1,
- knex,
- logger,
- Duration.fromMillis(10),
- );
- await worker1.start(settings, { signal: abortFirst.signal });
+ // grab initial row for comparisons later
+ const rowAfterClaimAndRelease = (await knex(DB_TASKS_TABLE))[0];
- expect(fn1).toHaveBeenCalledTimes(0);
- await new Promise(resolve => setTimeout(resolve, 250));
- expect(fn1).toHaveBeenCalledTimes(0);
- await new Promise(resolve => setTimeout(resolve, 100));
- expect(fn1.mock.calls.length).toBeGreaterThan(0);
+ const settings: TaskSettingsV2 = {
+ ...initialSettings,
+ cadence: 'PT60M',
+ };
+ await worker.persistTask(settings);
+ const row1 = (await knex(DB_TASKS_TABLE))[0];
- // Start a second worker and make sure it waits but the first worker still works along
- const fn2 = jest.fn();
- const promise2 = new Promise(resolve => fn2.mockImplementation(resolve));
- const worker2 = new TaskWorker(
- 'task1',
- fn2,
- knex,
- logger,
- Duration.fromMillis(10),
- );
- await worker2.start(settings, { signal: testScopedSignal() });
+ const rowAfterClaimAndReleaseNextStartAt = DateTime.fromJSDate(
+ new Date(rowAfterClaimAndRelease.next_run_start_at!),
+ );
+ const row1NextStartAt = DateTime.fromJSDate(
+ new Date(row1.next_run_start_at!),
+ );
+ const now = DateTime.now();
+ expect(
+ rowAfterClaimAndReleaseNextStartAt.diff(row1NextStartAt).as('minutes'),
+ ).toBeCloseTo(60, 1); // ensure that next start at is sooner than initial by one hour
+ expect(row1NextStartAt.diff(now).as('minutes')).toBeCloseTo(60, 1); // ensure that next start at is later than now by one hour
+ expect(
+ rowAfterClaimAndReleaseNextStartAt.diff(now).as('minutes'),
+ ).toBeCloseTo(120, 1);
- // We eventually abort the first worker just to make sure that the second
- // one for sure will get a go at running the task
- setTimeout(() => abortFirst.abort(), 1000);
+ const settings2 = {
+ ...settings,
+ };
+ await worker.persistTask(settings2);
+ const row2 = (await knex(DB_TASKS_TABLE))[0];
- const before = fn1.mock.calls.length;
- await promise2;
- expect(fn1.mock.calls.length).toBeGreaterThan(before);
+ expect(row2.next_run_start_at).toStrictEqual(row1.next_run_start_at);
+ });
- await knex.destroy();
- },
- );
+ it('next_run_start_at is always the min between schedule changes when using human duration frequency with initial start delay', async () => {
+ const fn = jest.fn(
+ async () => new Promise(resolve => setTimeout(resolve, 50)),
+ );
- it.each(databases.eachSupportedId())(
- 'next_run_start_at is always the min between schedule changes from cron frequency, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ const initialSettings: TaskSettingsV2 = {
+ version: 2,
+ cadence: 'PT120M',
+ initialDelayDuration: 'PT2M',
+ timeoutAfterDuration: 'PT1M',
+ };
- const fn = jest.fn(
- async () => new Promise(resolve => setTimeout(resolve, 50)),
- );
- const settings: TaskSettingsV2 = {
- version: 2,
- cadence: '*/15 * * * *',
- initialDelayDuration: 'PT2M',
- timeoutAfterDuration: 'PT1M',
- };
+ const worker = new TaskWorker('task99', fn, knex, logger);
+ await worker.persistTask(initialSettings);
+ // replicate task running, sets next_run_start_at based on cadence
+ await worker.tryClaimTask('ticket', initialSettings);
+ await worker.tryReleaseTask('ticket', initialSettings);
- const worker = new TaskWorker('task99', fn, knex, logger);
- await worker.persistTask(settings);
- const row1 = (await knex(DB_TASKS_TABLE))[0];
+ // grab initial row for comparisons later
+ const rowAfterClaimAndRelease = (await knex(DB_TASKS_TABLE))[0];
- const settings2 = {
- ...settings,
- cadence: '*/2 * * * *',
- initialDelayDuration: 'PT1M',
- };
- await worker.persistTask(settings2);
- const row2 = (await knex(DB_TASKS_TABLE))[0];
+ const settings: TaskSettingsV2 = {
+ ...initialSettings,
+ cadence: 'PT60M',
+ };
+ await worker.persistTask(settings);
+ const row1 = (await knex(DB_TASKS_TABLE))[0];
- expect(row2.next_run_start_at).not.toStrictEqual(row1.next_run_start_at);
+ const rowAfterClaimAndReleaseNextStartAt = DateTime.fromJSDate(
+ new Date(rowAfterClaimAndRelease.next_run_start_at!),
+ );
+ const row1NextStartAt = DateTime.fromJSDate(
+ new Date(row1.next_run_start_at!),
+ );
+ const now = DateTime.now();
+ expect(
+ rowAfterClaimAndReleaseNextStartAt.diff(row1NextStartAt).as('minutes'),
+ ).toBeCloseTo(62, 1); // ensure that next start at is sooner than initial by one hour, plus the 2 minute delay (set my tryReleaseTask)
+ expect(row1NextStartAt.diff(now).as('minutes')).toBeCloseTo(60, 1); // ensure that next start at is later than now by one hour (2 minute delay doesn't take effect here)
+ expect(
+ rowAfterClaimAndReleaseNextStartAt.diff(now).as('minutes'),
+ ).toBeCloseTo(122, 1); // includes 2 minute start delay (which is persisted from tryReleaseTask)
- const settings3 = { ...settings };
- await worker.persistTask(settings3);
- const row3 = (await knex(DB_TASKS_TABLE))[0];
+ const settings2 = {
+ ...settings,
+ };
+ await worker.persistTask(settings2);
+ const row2 = (await knex(DB_TASKS_TABLE))[0];
- // The new timestamp can basically be 0 or a minute depending on how the
- // initialDelayDuration falls right on a cron boundary. This kinda
- // contrived check removes a test flakiness based on wall clock time.
- expect(
- Math.abs(
- +new Date(row3.next_run_start_at!) -
- +new Date(row2.next_run_start_at!),
- ),
- ).toBeLessThanOrEqual(60_000);
+ expect(row2.next_run_start_at).toStrictEqual(row1.next_run_start_at);
+ });
- await knex.destroy();
- },
- );
+ it('next_run_start_at is not set for manually-triggered tasks', async () => {
+ const fn = jest.fn(
+ async () => new Promise(resolve => setTimeout(resolve, 50)),
+ );
- it.each(databases.eachSupportedId())(
- 'next_run_start_at is always the min between schedule changes when using human duration frequency, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ const initialSettings: TaskSettingsV2 = {
+ version: 2,
+ cadence: 'manual',
+ timeoutAfterDuration: 'PT1M',
+ };
- const fn = jest.fn(
- async () => new Promise(resolve => setTimeout(resolve, 50)),
- );
+ const worker = new TaskWorker('task99', fn, knex, logger);
+ await worker.persistTask(initialSettings);
+ await worker.tryClaimTask('ticket', initialSettings);
+ await worker.tryReleaseTask('ticket', initialSettings);
- const initialSettings: TaskSettingsV2 = {
- version: 2,
- cadence: 'PT120M',
- timeoutAfterDuration: 'PT1M',
- };
+ const row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row.next_run_start_at).toBeNull();
+ });
- const worker = new TaskWorker('task99', fn, knex, logger);
- await worker.persistTask(initialSettings);
- // replicate task running, sets next_run_start_at based on cadence
- await worker.tryClaimTask('ticket', initialSettings);
- await worker.tryReleaseTask('ticket', initialSettings);
+ it('can cancel a running task', async () => {
+ const fn = jest.fn(async () => {});
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ cadence: '* * * * * *',
+ initialDelayDuration: undefined,
+ timeoutAfterDuration: Duration.fromObject({ minutes: 1 }).toISO()!,
+ };
- // grab initial row for comparisons later
- const rowAfterClaimAndRelease = (
- await knex(DB_TASKS_TABLE)
- )[0];
+ const worker = new TaskWorker('task1', fn, knex, logger);
+ await worker.persistTask(settings);
+ await worker.tryClaimTask('ticket', settings);
- const settings: TaskSettingsV2 = {
- ...initialSettings,
- cadence: 'PT60M',
- };
- await worker.persistTask(settings);
- const row1 = (await knex(DB_TASKS_TABLE))[0];
+ // Verify the task is running
+ let row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row.current_run_ticket).toBe('ticket');
- const rowAfterClaimAndReleaseNextStartAt = DateTime.fromJSDate(
- new Date(rowAfterClaimAndRelease.next_run_start_at!),
- );
- const row1NextStartAt = DateTime.fromJSDate(
- new Date(row1.next_run_start_at!),
- );
- const now = DateTime.now();
- expect(
- rowAfterClaimAndReleaseNextStartAt.diff(row1NextStartAt).as('minutes'),
- ).toBeCloseTo(60, 1); // ensure that next start at is sooner than initial by one hour
- expect(row1NextStartAt.diff(now).as('minutes')).toBeCloseTo(60, 1); // ensure that next start at is later than now by one hour
- expect(
- rowAfterClaimAndReleaseNextStartAt.diff(now).as('minutes'),
- ).toBeCloseTo(120, 1);
+ await TaskWorker.cancel(knex, 'task1');
- const settings2 = {
- ...settings,
- };
- await worker.persistTask(settings2);
- const row2 = (await knex(DB_TASKS_TABLE))[0];
+ // Verify the task is now idle with a cancellation error recorded
+ row = (await knex(DB_TASKS_TABLE))[0];
+ expect(row.current_run_ticket).toBeNull();
+ expect(row.current_run_started_at).toBeNull();
+ expect(row.current_run_expires_at).toBeNull();
+ expect(row.last_run_ended_at).not.toBeNull();
+ expect(row.last_run_error_json).toContain('Task was cancelled');
+ });
- expect(row2.next_run_start_at).toStrictEqual(row1.next_run_start_at);
+ it('cannot cancel a non-existent task', async () => {
+ await expect(TaskWorker.cancel(knex, 'nonexistent')).rejects.toThrow(
+ NotFoundError,
+ );
+ });
- await knex.destroy();
- },
- );
+ it('cannot cancel a task that is not running', async () => {
+ const fn = jest.fn(async () => {});
+ const settings: TaskSettingsV2 = {
+ version: 2,
+ cadence: '* * * * * *',
+ initialDelayDuration: undefined,
+ timeoutAfterDuration: Duration.fromObject({ minutes: 1 }).toISO()!,
+ };
- it.each(databases.eachSupportedId())(
- 'next_run_start_at is always the min between schedule changes when using human duration frequency with initial start delay, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
+ const worker = new TaskWorker('task1', fn, knex, logger);
+ await worker.persistTask(settings);
- const fn = jest.fn(
- async () => new Promise(resolve => setTimeout(resolve, 50)),
- );
-
- const initialSettings: TaskSettingsV2 = {
- version: 2,
- cadence: 'PT120M',
- initialDelayDuration: 'PT2M',
- timeoutAfterDuration: 'PT1M',
- };
-
- const worker = new TaskWorker('task99', fn, knex, logger);
- await worker.persistTask(initialSettings);
- // replicate task running, sets next_run_start_at based on cadence
- await worker.tryClaimTask('ticket', initialSettings);
- await worker.tryReleaseTask('ticket', initialSettings);
-
- // grab initial row for comparisons later
- const rowAfterClaimAndRelease = (
- await knex(DB_TASKS_TABLE)
- )[0];
-
- const settings: TaskSettingsV2 = {
- ...initialSettings,
- cadence: 'PT60M',
- };
- await worker.persistTask(settings);
- const row1 = (await knex(DB_TASKS_TABLE))[0];
-
- const rowAfterClaimAndReleaseNextStartAt = DateTime.fromJSDate(
- new Date(rowAfterClaimAndRelease.next_run_start_at!),
- );
- const row1NextStartAt = DateTime.fromJSDate(
- new Date(row1.next_run_start_at!),
- );
- const now = DateTime.now();
- expect(
- rowAfterClaimAndReleaseNextStartAt.diff(row1NextStartAt).as('minutes'),
- ).toBeCloseTo(62, 1); // ensure that next start at is sooner than initial by one hour, plus the 2 minute delay (set my tryReleaseTask)
- expect(row1NextStartAt.diff(now).as('minutes')).toBeCloseTo(60, 1); // ensure that next start at is later than now by one hour (2 minute delay doesn't take effect here)
- expect(
- rowAfterClaimAndReleaseNextStartAt.diff(now).as('minutes'),
- ).toBeCloseTo(122, 1); // includes 2 minute start delay (which is persisted from tryReleaseTask)
-
- const settings2 = {
- ...settings,
- };
- await worker.persistTask(settings2);
- const row2 = (await knex(DB_TASKS_TABLE))[0];
-
- expect(row2.next_run_start_at).toStrictEqual(row1.next_run_start_at);
-
- await knex.destroy();
- },
- );
-
- it.each(databases.eachSupportedId())(
- 'next_run_start_at is not set for manually-triggered tasks, %p',
- async databaseId => {
- const knex = await databases.init(databaseId);
- await migrateBackendTasks(knex);
-
- const fn = jest.fn(
- async () => new Promise(resolve => setTimeout(resolve, 50)),
- );
-
- const initialSettings: TaskSettingsV2 = {
- version: 2,
- cadence: 'manual',
- timeoutAfterDuration: 'PT1M',
- };
-
- const worker = new TaskWorker('task99', fn, knex, logger);
- await worker.persistTask(initialSettings);
- await worker.tryClaimTask('ticket', initialSettings);
- await worker.tryReleaseTask('ticket', initialSettings);
-
- const row = (await knex(DB_TASKS_TABLE))[0];
- expect(row.next_run_start_at).toBeNull();
-
- await knex.destroy();
- },
- );
+ await expect(TaskWorker.cancel(knex, 'task1')).rejects.toThrow(
+ ConflictError,
+ );
+ });
});
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.ts
index e47967de90..4f32dc6863 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/TaskWorker.ts
@@ -152,6 +152,36 @@ export class TaskWorker {
}
}
+ static async cancel(knex: Knex, taskId: string): Promise {
+ const [row] = await knex(DB_TASKS_TABLE)
+ .where('id', '=', taskId)
+ .select('settings_json', 'current_run_ticket');
+ if (!row) {
+ throw new NotFoundError(`Task ${taskId} does not exist`);
+ }
+ if (!row.current_run_ticket) {
+ throw new ConflictError(`Task ${taskId} is not running`);
+ }
+
+ const settings = taskSettingsV2Schema.parse(JSON.parse(row.settings_json));
+ const nextRun = TaskWorker.computeNextRunStartAt(knex, settings);
+
+ const updatedRows = await knex(DB_TASKS_TABLE)
+ .where('id', '=', taskId)
+ .where('current_run_ticket', '=', row.current_run_ticket)
+ .update({
+ next_run_start_at: nextRun,
+ current_run_ticket: knex.raw('null'),
+ current_run_started_at: knex.raw('null'),
+ current_run_expires_at: knex.raw('null'),
+ last_run_ended_at: knex.fn.now(),
+ last_run_error_json: serializeError(new Error('Task was cancelled')),
+ });
+ if (updatedRows < 1) {
+ throw new ConflictError(`Task ${taskId} is not running`);
+ }
+ }
+
static async taskStates(
knex: Knex,
): Promise> {
@@ -227,11 +257,22 @@ export class TaskWorker {
}
// Abort the task execution either if the worker is stopped, or if the
- // task timeout is hit
+ // task timeout is hit, or if the task ticket was lost (e.g. due to
+ // cancellation from another host)
const taskAbortController = delegateAbortController(signal);
const timeoutHandle = setTimeout(() => {
taskAbortController.abort();
}, Duration.fromISO(taskSettings.timeoutAfterDuration).as('milliseconds'));
+ let livenessHandle: ReturnType | undefined;
+ const scheduleLivenessCheck = () => {
+ livenessHandle = setTimeout(async () => {
+ await this.checkLiveness(ticket, taskAbortController);
+ if (!taskAbortController.signal.aborted) {
+ scheduleLivenessCheck();
+ }
+ }, this.workCheckFrequency.as('milliseconds'));
+ };
+ scheduleLivenessCheck();
try {
this.#workerState = {
@@ -248,6 +289,7 @@ export class TaskWorker {
status: 'idle',
};
clearTimeout(timeoutHandle);
+ clearTimeout(livenessHandle);
}
await this.tryReleaseTask(ticket, taskSettings);
@@ -283,7 +325,7 @@ export class TaskWorker {
// We make a conversion here to make typescript happy, because the luxon versions of the cron library and here may not be the same
const timeConverted = DateTime.fromJSDate(time.toJSDate());
- nextStartAt = this.nextRunAtRaw(timeConverted);
+ nextStartAt = TaskWorker.nextRunAtRaw(this.knex, timeConverted);
startAt ||= nextStartAt;
} else if (isManual) {
nextStartAt = this.knex.raw('null');
@@ -334,6 +376,33 @@ export class TaskWorker {
);
}
+ /**
+ * Checks whether the current task ticket is still valid in the database.
+ * If the ticket has been cleared (e.g. by cancellation or janitor cleanup),
+ * aborts the task execution.
+ */
+ private async checkLiveness(
+ ticket: string,
+ taskAbortController: AbortController,
+ ): Promise {
+ try {
+ const [row] = await this.knex(DB_TASKS_TABLE)
+ .where('id', '=', this.taskId)
+ .select('current_run_ticket');
+
+ if (!row || row.current_run_ticket !== ticket) {
+ this.logger.info(
+ `Task ticket for "${this.taskId}" is no longer valid; aborting execution`,
+ );
+ taskAbortController.abort();
+ }
+ } catch (e) {
+ this.logger.warn(
+ `Failed to check liveness for task "${this.taskId}", ${e}`,
+ );
+ }
+ }
+
/**
* Check if the task is ready to run
*/
@@ -407,48 +476,49 @@ export class TaskWorker {
return rows === 1;
}
+ private static computeNextRunStartAt(
+ knex: Knex,
+ settings: TaskSettingsV2,
+ ): Knex.Raw {
+ const isManual = settings?.cadence === 'manual';
+ const isDuration = settings?.cadence.startsWith('P');
+ const isCron = !isManual && !isDuration;
+
+ if (isCron) {
+ const time = new CronTime(settings.cadence).sendAt().toUTC();
+ const timeConverted = DateTime.fromJSDate(time.toJSDate());
+ return TaskWorker.nextRunAtRaw(knex, timeConverted);
+ }
+
+ if (isManual) {
+ return knex.raw('null');
+ }
+
+ const dt = Duration.fromISO(settings.cadence).as('seconds');
+
+ if (knex.client.config.client.includes('sqlite3')) {
+ return knex.raw(`max(datetime(next_run_start_at, ?), datetime('now'))`, [
+ `+${dt} seconds`,
+ ]);
+ }
+
+ if (knex.client.config.client.includes('mysql')) {
+ return knex.raw(
+ `greatest(next_run_start_at + interval ${dt} second, now())`,
+ );
+ }
+
+ return knex.raw(
+ `greatest(next_run_start_at + interval '${dt} seconds', now())`,
+ );
+ }
+
async tryReleaseTask(
ticket: string,
settings: TaskSettingsV2,
error?: Error,
): Promise {
- const isManual = settings?.cadence === 'manual';
- const isDuration = settings?.cadence.startsWith('P');
- const isCron = !isManual && !isDuration;
-
- let nextRun: Knex.Raw;
- if (isCron) {
- const time = new CronTime(settings.cadence).sendAt().toUTC();
- this.logger.debug(`task: ${this.taskId} will next occur around ${time}`);
- // We make a conversion here to make typescript happy, because the luxon versions of the cron library and here may not be the same
- const timeConverted = DateTime.fromJSDate(time.toJSDate());
-
- nextRun = this.nextRunAtRaw(timeConverted);
- } else if (isManual) {
- nextRun = this.knex.raw('null');
- } else {
- const dt = Duration.fromISO(settings.cadence).as('seconds');
- this.logger.debug(
- `task: ${this.taskId} will next occur around ${DateTime.now().plus({
- seconds: dt,
- })}`,
- );
-
- if (this.knex.client.config.client.includes('sqlite3')) {
- nextRun = this.knex.raw(
- `max(datetime(next_run_start_at, ?), datetime('now'))`,
- [`+${dt} seconds`],
- );
- } else if (this.knex.client.config.client.includes('mysql')) {
- nextRun = this.knex.raw(
- `greatest(next_run_start_at + interval ${dt} second, now())`,
- );
- } else {
- nextRun = this.knex.raw(
- `greatest(next_run_start_at + interval '${dt} seconds', now())`,
- );
- }
- }
+ const nextRun = TaskWorker.computeNextRunStartAt(this.knex, settings);
const rows = await this.knex(DB_TASKS_TABLE)
.where('id', '=', this.taskId)
@@ -467,12 +537,13 @@ export class TaskWorker {
return rows === 1;
}
- private nextRunAtRaw(time: DateTime): Knex.Raw {
- if (this.knex.client.config.client.includes('sqlite3')) {
- return this.knex.raw('datetime(?)', [time.toISO()]);
- } else if (this.knex.client.config.client.includes('mysql')) {
- return this.knex.raw(`?`, [time.toSQL({ includeOffset: false })]);
+ private static nextRunAtRaw(knex: Knex, time: DateTime): Knex.Raw {
+ if (knex.client.config.client.includes('sqlite3')) {
+ return knex.raw('datetime(?)', [time.toISO()]);
}
- return this.knex.raw(`?`, [time.toISO()]);
+ if (knex.client.config.client.includes('mysql')) {
+ return knex.raw(`?`, [time.toSQL({ includeOffset: false })]);
+ }
+ return knex.raw(`?`, [time.toISO()]);
}
}
diff --git a/packages/backend-defaults/src/entrypoints/scheduler/lib/types.ts b/packages/backend-defaults/src/entrypoints/scheduler/lib/types.ts
index f691ef78a0..64f7d00899 100644
--- a/packages/backend-defaults/src/entrypoints/scheduler/lib/types.ts
+++ b/packages/backend-defaults/src/entrypoints/scheduler/lib/types.ts
@@ -17,7 +17,7 @@
import { JsonObject } from '@backstage/types';
import { CronTime } from 'cron';
import { Duration } from 'luxon';
-import { z } from 'zod';
+import { z } from 'zod/v4';
function isValidOptionalDurationString(d: string | undefined): boolean {
try {
diff --git a/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.test.ts b/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.test.ts
index dc3d1e5b8e..3592b3d72b 100644
--- a/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.test.ts
+++ b/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.test.ts
@@ -128,6 +128,55 @@ describe('parseUrl', () => {
});
});
+ it('supports aws formats with custom endpoint hosts', () => {
+ expect(
+ parseUrl(
+ 'https://bucket-1.s3.eu-central-1.amazonaws.com/path/to/file.yaml',
+ {
+ host: 'bucket-1.s3.eu-central-1.amazonaws.com',
+ },
+ ),
+ ).toEqual({
+ path: 'path/to/file.yaml',
+ bucket: 'bucket-1',
+ region: 'eu-central-1',
+ });
+ expect(
+ parseUrl('https://my-bucket.s3.cn-north-1.amazonaws.com.cn/data.json', {
+ host: 'my-bucket.s3.cn-north-1.amazonaws.com.cn',
+ }),
+ ).toEqual({
+ path: 'data.json',
+ bucket: 'my-bucket',
+ region: 'cn-north-1',
+ });
+ expect(
+ parseUrl(
+ 'https://s3.eu-central-1.amazonaws.com/my-bucket/path/to/file.yaml',
+ {
+ host: 's3.eu-central-1.amazonaws.com',
+ },
+ ),
+ ).toEqual({
+ path: 'path/to/file.yaml',
+ bucket: 'my-bucket',
+ region: 'eu-central-1',
+ });
+ expect(
+ parseUrl(
+ 'https://s3.eu-central-1.amazonaws.com/my-bucket/path/to/file.yaml',
+ {
+ host: 's3.eu-central-1.amazonaws.com',
+ s3ForcePathStyle: true,
+ },
+ ),
+ ).toEqual({
+ path: 'path/to/file.yaml',
+ bucket: 'my-bucket',
+ region: 'eu-central-1',
+ });
+ });
+
it('supports all non-aws formats', () => {
expect(
parseUrl('https://my-host.com/my.bucket-3/a/puppy.jpg', {
diff --git a/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.ts b/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.ts
index cb776fc977..0b17ffe326 100644
--- a/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.ts
+++ b/packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.ts
@@ -74,7 +74,12 @@ export function parseUrl(
const host = parsedUrl.host;
// Treat Amazon hosted separately because it has special region logic
- if (config.host === 'amazonaws.com' || config.host === 'amazonaws.com.cn') {
+ if (
+ config.host === 'amazonaws.com' ||
+ config.host === 'amazonaws.com.cn' ||
+ config.host.endsWith('.amazonaws.com') ||
+ config.host.endsWith('.amazonaws.com.cn')
+ ) {
const match = host.match(
/^(?:([a-z0-9.-]+)\.)?s3(?:[.-]([a-z0-9-]+))?\.amazonaws\.com(\.cn)?$/,
);
diff --git a/packages/backend-dynamic-feature-service/CHANGELOG.md b/packages/backend-dynamic-feature-service/CHANGELOG.md
index 85387c2b74..3ea462e952 100644
--- a/packages/backend-dynamic-feature-service/CHANGELOG.md
+++ b/packages/backend-dynamic-feature-service/CHANGELOG.md
@@ -1,5 +1,93 @@
# @backstage/backend-dynamic-feature-service
+## 0.8.1-next.1
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.9.0-next.1
+ - @backstage/backend-defaults@0.16.1-next.1
+ - @backstage/plugin-catalog-backend@3.5.1-next.1
+ - @backstage/plugin-auth-node@0.7.0-next.1
+ - @backstage/backend-openapi-utils@0.6.8-next.1
+ - @backstage/plugin-app-node@0.1.44-next.1
+ - @backstage/plugin-events-backend@0.6.1-next.1
+ - @backstage/plugin-events-node@0.4.21-next.1
+ - @backstage/plugin-permission-node@0.10.12-next.1
+ - @backstage/plugin-scaffolder-node@0.13.1-next.1
+ - @backstage/plugin-search-backend-node@1.4.3-next.1
+
+## 0.8.1-next.0
+
+### Patch Changes
+
+- 79453c0: Updated dependency `wait-for-expect` to `^4.0.0`.
+- Updated dependencies
+ - @backstage/cli-common@0.2.1-next.0
+ - @backstage/plugin-catalog-backend@3.5.1-next.0
+ - @backstage/backend-defaults@0.16.1-next.0
+ - @backstage/backend-plugin-api@1.8.1-next.0
+ - @backstage/cli-node@0.3.1-next.0
+ - @backstage/config-loader@1.10.10-next.0
+ - @backstage/plugin-auth-node@0.6.15-next.0
+ - @backstage/plugin-events-backend@0.6.1-next.0
+ - @backstage/plugin-permission-node@0.10.12-next.0
+ - @backstage/plugin-search-backend-node@1.4.3-next.0
+ - @backstage/backend-openapi-utils@0.6.8-next.0
+ - @backstage/plugin-app-node@0.1.44-next.0
+ - @backstage/plugin-events-node@0.4.21-next.0
+ - @backstage/plugin-scaffolder-node@0.13.1-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+ - @backstage/plugin-permission-common@0.9.7
+ - @backstage/plugin-search-common@1.2.22
+
+## 0.8.0
+
+### Minor Changes
+
+- 0fbcf23: Migrated OpenAPI schemas to 3.1.
+
+### Patch Changes
+
+- 4074a22: Fixed `resolvePackagePath` resolution for bundled dynamic plugins. When a plugin bundles its own copy of `@backstage/backend-plugin-api` inside `node_modules`, the `CommonJSModuleLoader` fallback now correctly resolves the plugin's `package.json` by name. Previously the fallback only applied when the resolution originated from the host application; it now also applies when originating from a bundled dependency, which is the case for plugins produced by the `backstage-cli package bundle` command.
+- 70fc178: Migrated from deprecated `findPaths` to `targetPaths` and `findOwnPaths` from `@backstage/cli-common`.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0
+ - @backstage/backend-defaults@0.16.0
+ - @backstage/cli-node@0.3.0
+ - @backstage/plugin-catalog-backend@3.5.0
+ - @backstage/cli-common@0.2.0
+ - @backstage/plugin-scaffolder-node@0.13.0
+ - @backstage/plugin-events-backend@0.6.0
+ - @backstage/config-loader@1.10.9
+ - @backstage/plugin-permission-common@0.9.7
+ - @backstage/plugin-permission-node@0.10.11
+ - @backstage/plugin-auth-node@0.6.14
+ - @backstage/backend-openapi-utils@0.6.7
+ - @backstage/plugin-app-node@0.1.43
+ - @backstage/plugin-events-node@0.4.20
+ - @backstage/plugin-search-backend-node@1.4.2
+
+## 0.8.0-next.2
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0-next.1
+ - @backstage/backend-defaults@0.16.0-next.2
+ - @backstage/cli-common@0.2.0-next.2
+ - @backstage/plugin-catalog-backend@3.5.0-next.2
+ - @backstage/backend-openapi-utils@0.6.7-next.1
+ - @backstage/plugin-app-node@0.1.43-next.1
+ - @backstage/plugin-auth-node@0.6.14-next.2
+ - @backstage/plugin-events-backend@0.6.0-next.2
+ - @backstage/plugin-events-node@0.4.20-next.1
+ - @backstage/plugin-permission-node@0.10.11-next.1
+ - @backstage/plugin-scaffolder-node@0.13.0-next.2
+ - @backstage/plugin-search-backend-node@1.4.2-next.1
+
## 0.8.0-next.1
### Minor Changes
diff --git a/packages/backend-dynamic-feature-service/README.md b/packages/backend-dynamic-feature-service/README.md
index 8122810f96..914df15f65 100644
--- a/packages/backend-dynamic-feature-service/README.md
+++ b/packages/backend-dynamic-feature-service/README.md
@@ -97,7 +97,7 @@ Since this service only handles loading, you would choose a packaging approach b
**When to use:** Plugin only uses dependencies that are already provided by the main Backstage application.
-**How to apply:**
+**How to use:**
```bash
cd my-backstage-plugin
@@ -117,7 +117,7 @@ tar -xzf package.tgz -C /path/to/dynamic-plugins-root/my-backstage-plugin --stri
**When to use:** Plugin has private dependencies not available in the main Backstage application.
-**How to apply:**
+**How to use:**
```bash
# Package the plugin
@@ -136,35 +136,47 @@ yarn install # Installs all the plugin's dependencies
**Example scenario:** Plugin needs `axios@1.4.0` which isn't available in the main application.
-### 3. Custom packaging CLI tool
+### 3. Dedicated bundling CLI command
-**When to use:** When you want to produce self-contained dynamic plugin packages that can be directly extracted without any post-action, and systematically use the core `@backstage` dependencies provided by the Backstage application.
+**When to use:**
-**What a packaging CLI needs to do:**
+- When you want to produce self-contained dynamic plugin packages that can be directly extracted and loaded without any post-action,
+- especially when your plugin depends on other packages in the same monorepo.
-1. **Analyze plugin dependencies** - Identify which are Backstage core vs private dependencies
-2. **Create distribution package** - Generate a new directory with modified structure:
- - Move `@backstage/*` packages from `dependencies` to `peerDependencies` in package.json
- - Keep only private dependencies in the `dependencies` section
- - Keep the built JavaScript code unchanged
- - Include only the filtered private dependencies in `node_modules`
-3. **Result** - A self-contained package that uses the main app's `@backstage/*` packages but includes its own private dependencies
+**How to use:**
-**Benefits:**
-
-- Systematic use of main application's `@backstage/*` packages (no version conflicts), enabling the future implementation of `@backstage` dependency version checking at start time
-- Self-contained packages with only necessary private dependencies
-- No post-installation steps required (extract and run)
-- Consistent dependency structure across all dynamic plugins
-- Production-ready distribution format
-
-**Example implementation:** The [`@red-hat-developer-hub/cli`](https://github.com/redhat-developer/rhdh-cli) tool implements this approach:
+The [`backstage-cli package bundle`](../cli/cli-report.md) command automates the required steps. Run it from within a plugin directory:
```bash
cd my-backstage-plugin
-npx @red-hat-developer-hub/cli@latest plugin export
-# Creates a self-contained package with embedded dependencies in the `/dist-dynamic` sub-folder
-
-# Deploy the generated package
-cp -r dist-dynamic /path/to/dynamic-plugins-root/my-backstage-plugin
+yarn backstage-cli package bundle --output-destination /path/to/dynamic-plugins-root
+# Creates a self-contained bundle in the /path/to/dynamic-plugins-root/my-backstage-plugin/ sub-folder
```
+
+**Batch bundling:** When bundling many plugins from the same monorepo, use `--pre-packed-dir` to avoid redundant work:
+
+```bash
+# First, build a shared dist workspace
+backstage-cli build-workspace dist-workspace --alwaysPack ...plugin-packages
+
+# Then bundle each plugin using the pre-packed output
+cd plugins/my-backstage-plugin
+backstage-cli package bundle --pre-packed-dir ../../dist-workspace
+```
+
+See the full list of options in the [CLI reference](../cli/cli-report.md).
+
+**What the command does:**
+
+1. **Builds the plugin** — Produces CJS output for the backend plugin and its transitively-required monorepo packages (`*-node` or `*-common`)
+2. **Packs local packages** — Resolves `workspace:^` and `backstage:^` dependencies on both the main plugin package and its transitively-required monorepo packages (`*-node` or `*-common`)
+3. **Installs private dependencies** — Seeds a lockfile from the plugin source monorepo and prunes it, then installs a private `node_modules` containing all required dependencies
+4. **Collects configuration schemas** — Gathers plugin config schemas and writes them to `dist/.config-schema.json` so they are available for validation at load time
+
+**Benefits:**
+
+- Self-contained packages with all necessary dependencies
+- No post-installation steps required (extract and run)
+- Consistent dependency structure across all dynamic plugins
+- Automatic configuration schema collection
+- Production-ready distribution format
diff --git a/packages/backend-dynamic-feature-service/package.json b/packages/backend-dynamic-feature-service/package.json
index 0e95427ca3..fb1e5dd803 100644
--- a/packages/backend-dynamic-feature-service/package.json
+++ b/packages/backend-dynamic-feature-service/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/backend-dynamic-feature-service",
- "version": "0.8.0-next.1",
+ "version": "0.8.1-next.1",
"description": "Backstage dynamic feature service",
"backstage": {
"role": "node-library"
@@ -84,7 +84,7 @@
"@backstage/repo-tools": "workspace:^",
"@types/express": "^4.17.6",
"triple-beam": "^1.4.1",
- "wait-for-expect": "^3.0.2"
+ "wait-for-expect": "^4.0.0"
},
"configSchema": "config.d.ts"
}
diff --git a/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/dist/index.cjs.js b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/dist/index.cjs.js
new file mode 100644
index 0000000000..f3671bc0a7
--- /dev/null
+++ b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/dist/index.cjs.js
@@ -0,0 +1,28 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// This require resolves to the bundled proxy copy inside this plugin's
+// own node_modules/@backstage/backend-plugin-api, NOT the host's copy.
+var backendPluginApi = require('@backstage/backend-plugin-api');
+
+// Triggers the _resolveFilename fallback: require.resolve runs from
+// the bundled @backstage/backend-plugin-api whose mod.path is inside
+// this plugin's node_modules.
+var pkgDir = backendPluginApi.resolvePackagePath('plugin-test-backend-bundled');
+
+const testBundledPlugin = backendPluginApi.createBackendPlugin({
+ pluginId: "test-bundled",
+ register(env) {
+ env.registerInit({
+ deps: {
+ logger: backendPluginApi.coreServices.rootLogger,
+ },
+ async init({ logger }) {
+ logger.info("Bundled backend plugin loaded successfully");
+ }
+ });
+ }
+});
+
+exports.default = testBundledPlugin;
diff --git a/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/node_modules/@backstage/backend-plugin-api/index.js b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/node_modules/@backstage/backend-plugin-api/index.js
new file mode 100644
index 0000000000..70e57950be
--- /dev/null
+++ b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/node_modules/@backstage/backend-plugin-api/index.js
@@ -0,0 +1,22 @@
+'use strict';
+
+// Proxy that simulates a bundled copy of @backstage/backend-plugin-api.
+// Re-exports everything from the real workspace package, but provides a
+// local resolvePackagePath so that require.resolve() runs from THIS
+// file's context (mod.path inside node_modules/@backstage/backend-plugin-api).
+
+const nodePath = require('node:path');
+const real = require('../../../../../../../../../backend-plugin-api/src');
+
+function resolvePackagePath(name) {
+ const args = Array.prototype.slice.call(arguments, 1);
+ const pkgJson = require.resolve(name + '/package.json');
+ return nodePath.resolve.apply(
+ nodePath,
+ [nodePath.dirname(pkgJson)].concat(args),
+ );
+}
+
+module.exports = Object.assign({}, real, {
+ resolvePackagePath: resolvePackagePath,
+});
diff --git a/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/node_modules/@backstage/backend-plugin-api/package.json b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/node_modules/@backstage/backend-plugin-api/package.json
new file mode 100644
index 0000000000..f487169afe
--- /dev/null
+++ b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/node_modules/@backstage/backend-plugin-api/package.json
@@ -0,0 +1,6 @@
+{
+ "name": "@backstage/backend-plugin-api",
+ "version": "0.0.0",
+ "description": "Proxy that re-exports the real @backstage/backend-plugin-api with a local resolvePackagePath, simulating a bundled copy.",
+ "main": "index.js"
+}
diff --git a/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/package.json b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/package.json
new file mode 100644
index 0000000000..bb2dbf15a6
--- /dev/null
+++ b/packages/backend-dynamic-feature-service/src/features/__fixtures__/dynamic-plugins-root-for-bundled/test-backend-bundled-dynamic/package.json
@@ -0,0 +1,31 @@
+{
+ "name": "plugin-test-backend-bundled-dynamic",
+ "version": "0.0.0",
+ "description": "A test dynamic backend plugin that bundles its own @backstage/backend-plugin-api.",
+ "backstage": {
+ "role": "backend-plugin",
+ "pluginId": "test-bundled",
+ "pluginPackages": [
+ "plugin-test-backend-bundled"
+ ]
+ },
+ "keywords": [
+ "backstage",
+ "dynamic"
+ ],
+ "exports": {
+ ".": {
+ "require": "./dist/index.cjs.js",
+ "default": "./dist/index.cjs.js"
+ },
+ "./package.json": "./package.json"
+ },
+ "main": "./dist/index.cjs.js",
+ "files": [
+ "dist"
+ ],
+ "dependencies": {
+ "@backstage/backend-plugin-api": "0.0.0"
+ },
+ "bundleDependencies": true
+}
diff --git a/packages/backend-dynamic-feature-service/src/features/features.test.ts b/packages/backend-dynamic-feature-service/src/features/features.test.ts
index ce15964c77..ac6c6ea510 100644
--- a/packages/backend-dynamic-feature-service/src/features/features.test.ts
+++ b/packages/backend-dynamic-feature-service/src/features/features.test.ts
@@ -465,6 +465,45 @@ Require stack:
});
});
+ it('should load a backend plugin that bundles its own @backstage/backend-plugin-api', async () => {
+ const dynamicPluginsLister = new DynamicPluginLister();
+ const dynamicPluginsRootForBundled = resolvePath(
+ __dirname,
+ '__fixtures__/dynamic-plugins-root-for-bundled',
+ );
+ await startTestBackend({
+ features: [
+ mockServices.rootConfig.factory({
+ data: {
+ dynamicPlugins: {
+ rootDirectory: dynamicPluginsRootForBundled,
+ },
+ backend: {
+ baseUrl: `http://localhost:0`,
+ },
+ },
+ }),
+ dynamicPluginsFeatureLoader({
+ moduleLoader: logger =>
+ jestFreeTypescriptAwareModuleLoader({ logger }),
+ }),
+ dynamicPluginsLister.feature(),
+ ],
+ });
+
+ expect(dynamicPluginsLister.loadedPlugins).toMatchObject([
+ {
+ installer: {
+ kind: 'new',
+ },
+ name: 'plugin-test-backend-bundled-dynamic',
+ platform: 'node',
+ role: 'backend-plugin',
+ version: '0.0.0',
+ },
+ ]);
+ });
+
describe('module federation support', () => {
const createRemoteProviderPlugin = (
provider: FrontendRemoteResolverProvider,
diff --git a/packages/backend-dynamic-feature-service/src/loader/CommonJSModuleLoader.ts b/packages/backend-dynamic-feature-service/src/loader/CommonJSModuleLoader.ts
index 3cc640086f..8902decdfa 100644
--- a/packages/backend-dynamic-feature-service/src/loader/CommonJSModuleLoader.ts
+++ b/packages/backend-dynamic-feature-service/src/loader/CommonJSModuleLoader.ts
@@ -99,15 +99,21 @@ export class CommonJSModuleLoader implements ModuleLoader {
);
}
- // Are we trying to resolve a `package.json` from an originating module of the core backstage application
- // (this is mostly done by calling `@backstage/backend-plugin-api/resolvePackagePath`).
- const resolvingPackageJsonFromBackstageApplication =
+ // Is this a `resolvePackagePath` call from `@backstage/backend-plugin-api`?
+ // This covers both the host application's copy and a bundled copy living
+ // inside a dynamic plugin's own node_modules.
+ // The regex matches mod.path against the various ways the package can be resolved on disk
+ // (with optional subdirectory such as /src or /dist after the package name):
+ // - .../node_modules/@backstage/backend-plugin-api[/...] (npm-installed)
+ // - ...//node_modules/@backstage/backend-plugin-api[/...] (bundled)
+ // - .../packages/backend-plugin-api[/...] (symlinked workspace in monorepo)
+ const resolvingPackageJsonViaResolvePackagePath =
request?.endsWith('/package.json') &&
- mod?.path &&
- !dynamicPluginsPaths.some(p => mod.path.startsWith(p));
+ /[/\\](?:@backstage|packages)[/\\]backend-plugin-api(?:[/\\]|$)/.test(
+ mod?.path ?? '',
+ );
- // If not, we don't need the dedicated specific case below.
- if (!resolvingPackageJsonFromBackstageApplication) {
+ if (!resolvingPackageJsonViaResolvePackagePath) {
throw errorToThrow;
}
diff --git a/packages/backend-openapi-utils/CHANGELOG.md b/packages/backend-openapi-utils/CHANGELOG.md
index ce142b728e..8b382a3f84 100644
--- a/packages/backend-openapi-utils/CHANGELOG.md
+++ b/packages/backend-openapi-utils/CHANGELOG.md
@@ -1,5 +1,35 @@
# @backstage/backend-openapi-utils
+## 0.6.8-next.1
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.9.0-next.1
+
+## 0.6.8-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.1-next.0
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+
+## 0.6.7
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0
+
+## 0.6.7-next.1
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0-next.1
+
## 0.6.7-next.0
### Patch Changes
diff --git a/packages/backend-openapi-utils/package.json b/packages/backend-openapi-utils/package.json
index 1f5bc417a8..135af02922 100644
--- a/packages/backend-openapi-utils/package.json
+++ b/packages/backend-openapi-utils/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/backend-openapi-utils",
- "version": "0.6.7-next.0",
+ "version": "0.6.8-next.1",
"description": "OpenAPI typescript support.",
"backstage": {
"role": "node-library"
diff --git a/packages/backend-plugin-api/CHANGELOG.md b/packages/backend-plugin-api/CHANGELOG.md
index b100b47e26..bbcf28b17f 100644
--- a/packages/backend-plugin-api/CHANGELOG.md
+++ b/packages/backend-plugin-api/CHANGELOG.md
@@ -1,5 +1,87 @@
# @backstage/backend-plugin-api
+## 1.9.0-next.1
+
+### Minor Changes
+
+- 4559806: Added support for typed `examples` on actions registered via the actions registry. Action authors can now provide examples with compile-time-checked `input` and `output` values that match their schema definitions.
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/plugin-auth-node@0.7.0-next.1
+ - @backstage/plugin-permission-node@0.10.12-next.1
+
+## 1.8.1-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-common@0.2.1-next.0
+ - @backstage/plugin-auth-node@0.6.15-next.0
+ - @backstage/plugin-permission-node@0.10.12-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+ - @backstage/plugin-permission-common@0.9.7
+
+## 1.8.0
+
+### Minor Changes
+
+- cc8348e: Added optional `visibilityPermission` field to `ActionsRegistryActionOptions`, allowing actions to declare a `BasicPermission` that controls visibility and access.
+
+ ```typescript
+ import { createPermission } from '@backstage/plugin-permission-common';
+
+ const myPermission = createPermission({
+ name: 'myPlugin.myAction.use',
+ attributes: {},
+ });
+
+ actionsRegistry.register({
+ name: 'my-action',
+ title: 'My Action',
+ description: 'An action that requires permission',
+ visibilityPermission: myPermission,
+ schema: {
+ input: z => z.object({ name: z.string() }),
+ output: z => z.object({ ok: z.boolean() }),
+ },
+ action: async ({ input }) => {
+ return { output: { ok: true } };
+ },
+ });
+ ```
+
+ Actions without a `visibilityPermission` field continue to work as before.
+
+- 015668c: Added `cancelTask` method to the `SchedulerService` interface and implementation, allowing cancellation of currently running scheduled tasks. For global tasks, the database lock is released and a periodic liveness check aborts the running task function. For local tasks, the task's abort signal is triggered directly. A new `POST /.backstage/scheduler/v1/tasks/:id/cancel` endpoint is also available.
+
+### Patch Changes
+
+- dee4283: Added `pluginId` field to `ActionsServiceAction` type, populated from the registering plugin's metadata.
+- 1ee5b28: Adds an alpha `MetricsService` to provide a unified interface for metrics instrumentation across Backstage plugins.
+- a49a40d: Updated dependency `zod` to `^3.25.76 || ^4.0.0` & migrated to `/v3` or `/v4` imports.
+- Updated dependencies
+ - @backstage/cli-common@0.2.0
+ - @backstage/plugin-permission-common@0.9.7
+ - @backstage/plugin-permission-node@0.10.11
+ - @backstage/plugin-auth-node@0.6.14
+
+## 1.8.0-next.1
+
+### Minor Changes
+
+- 015668c: Added `cancelTask` method to the `SchedulerService` interface and implementation, allowing cancellation of currently running scheduled tasks. For global tasks, the database lock is released and a periodic liveness check aborts the running task function. For local tasks, the task's abort signal is triggered directly. A new `POST /.backstage/scheduler/v1/tasks/:id/cancel` endpoint is also available.
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-common@0.2.0-next.2
+ - @backstage/plugin-auth-node@0.6.14-next.2
+ - @backstage/plugin-permission-node@0.10.11-next.1
+
## 1.7.1-next.0
### Patch Changes
diff --git a/packages/backend-plugin-api/package.json b/packages/backend-plugin-api/package.json
index 6acc8a384b..5f836592c0 100644
--- a/packages/backend-plugin-api/package.json
+++ b/packages/backend-plugin-api/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/backend-plugin-api",
- "version": "1.7.1-next.0",
+ "version": "1.9.0-next.1",
"description": "Core API used by Backstage backend plugins",
"backstage": {
"role": "node-library"
@@ -66,7 +66,7 @@
"json-schema": "^0.4.0",
"knex": "^3.0.0",
"luxon": "^3.0.0",
- "zod": "^3.25.76"
+ "zod": "^3.25.76 || ^4.0.0"
},
"devDependencies": {
"@backstage/backend-test-utils": "workspace:^",
diff --git a/packages/backend-plugin-api/report-alpha.api.md b/packages/backend-plugin-api/report-alpha.api.md
index 7d6786b97e..d1db9c7eeb 100644
--- a/packages/backend-plugin-api/report-alpha.api.md
+++ b/packages/backend-plugin-api/report-alpha.api.md
@@ -3,14 +3,15 @@
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
```ts
-import { AnyZodObject } from 'zod';
+import { AnyZodObject } from 'zod/v3';
import { BackstageCredentials } from '@backstage/backend-plugin-api';
+import { BasicPermission } from '@backstage/plugin-permission-common';
import { JsonObject } from '@backstage/types';
import { JSONSchema7 } from 'json-schema';
import { JsonValue } from '@backstage/types';
import { LoggerService } from '@backstage/backend-plugin-api';
import { ServiceRef } from '@backstage/backend-plugin-api';
-import { z } from 'zod';
+import { z } from 'zod/v3';
// @alpha (undocumented)
export type ActionsRegistryActionContext = {
@@ -19,6 +20,17 @@ export type ActionsRegistryActionContext = {
credentials: BackstageCredentials;
};
+// @alpha
+export type ActionsRegistryActionExample<
+ TInputSchema extends AnyZodObject,
+ TOutputSchema extends AnyZodObject,
+> = {
+ title: string;
+ description?: string;
+ input: z.infer;
+ output?: z.infer;
+};
+
// @alpha (undocumented)
export type ActionsRegistryActionOptions<
TInputSchema extends AnyZodObject,
@@ -31,6 +43,8 @@ export type ActionsRegistryActionOptions<
input: (zod: typeof z) => TInputSchema;
output: (zod: typeof z) => TOutputSchema;
};
+ examples?: Array>;
+ visibilityPermission?: BasicPermission;
attributes?: {
destructive?: boolean;
idempotent?: boolean;
@@ -82,6 +96,7 @@ export interface ActionsService {
// @alpha (undocumented)
export type ActionsServiceAction = {
id: string;
+ pluginId: string;
name: string;
title: string;
description: string;
@@ -89,6 +104,12 @@ export type ActionsServiceAction = {
input: JSONSchema7;
output: JSONSchema7;
};
+ examples?: Array<{
+ title: string;
+ description?: string;
+ input: JsonObject;
+ output?: JsonObject;
+ }>;
attributes: {
readOnly: boolean;
destructive: boolean;
diff --git a/packages/backend-plugin-api/report.api.md b/packages/backend-plugin-api/report.api.md
index 504be97ec6..96d1a02c0a 100644
--- a/packages/backend-plugin-api/report.api.md
+++ b/packages/backend-plugin-api/report.api.md
@@ -643,6 +643,7 @@ export interface RootServiceFactoryOptions<
// @public
export interface SchedulerService {
+ cancelTask(id: string): Promise;
createScheduledTaskRunner(
schedule: SchedulerServiceTaskScheduleDefinition,
): SchedulerServiceTaskRunner;
diff --git a/packages/backend-plugin-api/src/alpha/ActionsRegistryService.ts b/packages/backend-plugin-api/src/alpha/ActionsRegistryService.ts
index 9a7820e354..65f44be051 100644
--- a/packages/backend-plugin-api/src/alpha/ActionsRegistryService.ts
+++ b/packages/backend-plugin-api/src/alpha/ActionsRegistryService.ts
@@ -13,7 +13,8 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-import { z, AnyZodObject } from 'zod';
+import { z, AnyZodObject } from 'zod/v3';
+import { BasicPermission } from '@backstage/plugin-permission-common';
import {
LoggerService,
BackstageCredentials,
@@ -28,6 +29,21 @@ export type ActionsRegistryActionContext = {
credentials: BackstageCredentials;
};
+/**
+ * An example of how to use an action registered in the actions registry.
+ *
+ * @alpha
+ */
+export type ActionsRegistryActionExample<
+ TInputSchema extends AnyZodObject,
+ TOutputSchema extends AnyZodObject,
+> = {
+ title: string;
+ description?: string;
+ input: z.infer;
+ output?: z.infer;
+};
+
/**
* @alpha
*/
@@ -42,6 +58,8 @@ export type ActionsRegistryActionOptions<
input: (zod: typeof z) => TInputSchema;
output: (zod: typeof z) => TOutputSchema;
};
+ examples?: Array>;
+ visibilityPermission?: BasicPermission;
attributes?: {
destructive?: boolean;
idempotent?: boolean;
diff --git a/packages/backend-plugin-api/src/alpha/ActionsService.ts b/packages/backend-plugin-api/src/alpha/ActionsService.ts
index 528b6cea67..7062de9c77 100644
--- a/packages/backend-plugin-api/src/alpha/ActionsService.ts
+++ b/packages/backend-plugin-api/src/alpha/ActionsService.ts
@@ -22,6 +22,7 @@ import { BackstageCredentials } from '@backstage/backend-plugin-api';
*/
export type ActionsServiceAction = {
id: string;
+ pluginId: string;
name: string;
title: string;
description: string;
@@ -29,6 +30,12 @@ export type ActionsServiceAction = {
input: JSONSchema7;
output: JSONSchema7;
};
+ examples?: Array<{
+ title: string;
+ description?: string;
+ input: JsonObject;
+ output?: JsonObject;
+ }>;
attributes: {
readOnly: boolean;
destructive: boolean;
diff --git a/packages/backend-plugin-api/src/alpha/index.ts b/packages/backend-plugin-api/src/alpha/index.ts
index c487686338..9ec7ca5b09 100644
--- a/packages/backend-plugin-api/src/alpha/index.ts
+++ b/packages/backend-plugin-api/src/alpha/index.ts
@@ -23,6 +23,7 @@ export type {
ActionsRegistryService,
ActionsRegistryActionOptions,
ActionsRegistryActionContext,
+ ActionsRegistryActionExample,
} from './ActionsRegistryService';
export type { ActionsService, ActionsServiceAction } from './ActionsService';
diff --git a/packages/backend-plugin-api/src/services/definitions/ActionsRegistryService.ts b/packages/backend-plugin-api/src/services/definitions/ActionsRegistryService.ts
index 6c0936f85c..39c62ce731 100644
--- a/packages/backend-plugin-api/src/services/definitions/ActionsRegistryService.ts
+++ b/packages/backend-plugin-api/src/services/definitions/ActionsRegistryService.ts
@@ -13,7 +13,8 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-import { z, AnyZodObject } from 'zod';
+import { z, AnyZodObject } from 'zod/v3';
+import { BasicPermission } from '@backstage/plugin-permission-common';
import { LoggerService } from './LoggerService';
import { BackstageCredentials } from './AuthService';
@@ -26,6 +27,21 @@ export type ActionsRegistryActionContext = {
credentials: BackstageCredentials;
};
+/**
+ * An example of how to use an action registered in the actions registry.
+ *
+ * @public
+ */
+export type ActionsRegistryActionExample<
+ TInputSchema extends AnyZodObject,
+ TOutputSchema extends AnyZodObject,
+> = {
+ title: string;
+ description?: string;
+ input: z.infer;
+ output?: z.infer;
+};
+
/**
* @public
*/
@@ -40,6 +56,8 @@ export type ActionsRegistryActionOptions<
input: (zod: typeof z) => TInputSchema;
output: (zod: typeof z) => TOutputSchema;
};
+ examples?: Array>;
+ visibilityPermission?: BasicPermission;
attributes?: {
destructive?: boolean;
idempotent?: boolean;
diff --git a/packages/backend-plugin-api/src/services/definitions/ActionsService.ts b/packages/backend-plugin-api/src/services/definitions/ActionsService.ts
index d595008a42..3afa131915 100644
--- a/packages/backend-plugin-api/src/services/definitions/ActionsService.ts
+++ b/packages/backend-plugin-api/src/services/definitions/ActionsService.ts
@@ -29,6 +29,12 @@ export type ActionsServiceAction = {
input: JSONSchema7;
output: JSONSchema7;
};
+ examples?: Array<{
+ title: string;
+ description?: string;
+ input: JsonObject;
+ output?: JsonObject;
+ }>;
attributes: {
readOnly: boolean;
destructive: boolean;
diff --git a/packages/backend-plugin-api/src/services/definitions/SchedulerService.ts b/packages/backend-plugin-api/src/services/definitions/SchedulerService.ts
index b1a0e17df8..2748b8fac7 100644
--- a/packages/backend-plugin-api/src/services/definitions/SchedulerService.ts
+++ b/packages/backend-plugin-api/src/services/definitions/SchedulerService.ts
@@ -304,6 +304,16 @@ export interface SchedulerService {
*/
triggerTask(id: string): Promise;
+ /**
+ * Cancels a currently running task by ID, marking it as idle.
+ *
+ * If the task doesn't exist, a NotFoundError is thrown. If the task is
+ * not currently running, a ConflictError is thrown.
+ *
+ * @param id - The task ID
+ */
+ cancelTask(id: string): Promise;
+
/**
* Schedules a task function for recurring runs.
*
diff --git a/packages/backend-test-utils/CHANGELOG.md b/packages/backend-test-utils/CHANGELOG.md
index e372736ab0..5f783d9029 100644
--- a/packages/backend-test-utils/CHANGELOG.md
+++ b/packages/backend-test-utils/CHANGELOG.md
@@ -1,5 +1,61 @@
# @backstage/backend-test-utils
+## 1.11.2-next.1
+
+### Patch Changes
+
+- 4559806: Added support for typed `examples` on actions registered via the actions registry. Action authors can now provide examples with compile-time-checked `input` and `output` values that match their schema definitions.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.9.0-next.1
+ - @backstage/backend-defaults@0.16.1-next.1
+ - @backstage/plugin-auth-node@0.7.0-next.1
+ - @backstage/backend-app-api@1.6.1-next.1
+ - @backstage/plugin-events-node@0.4.21-next.1
+
+## 1.11.2-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-defaults@0.16.1-next.0
+ - @backstage/backend-plugin-api@1.8.1-next.0
+ - @backstage/backend-app-api@1.6.1-next.0
+ - @backstage/plugin-auth-node@0.6.15-next.0
+ - @backstage/plugin-events-node@0.4.21-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/types@1.2.2
+ - @backstage/plugin-permission-common@0.9.7
+
+## 1.11.1
+
+### Patch Changes
+
+- dee4283: Added `pluginId` field to `ActionsServiceAction` type, populated from the registering plugin's metadata.
+- 164711a: Added `cancelTask` to `MockSchedulerService` and mock scheduler service factory.
+- 62f0a53: Fixed error forwarding in the actions registry so that known errors like `InputError` and `NotFoundError` thrown by actions preserve their original status codes and messages instead of being wrapped in `ForwardedError` and coerced to 500.
+- a49a40d: Updated dependency `zod` to `^3.25.76 || ^4.0.0` & migrated to `/v3` or `/v4` imports.
+- 1ee5b28: Adds a new metrics service mock to be leveraged in tests
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0
+ - @backstage/backend-defaults@0.16.0
+ - @backstage/plugin-permission-common@0.9.7
+ - @backstage/plugin-auth-node@0.6.14
+ - @backstage/backend-app-api@1.6.0
+ - @backstage/plugin-events-node@0.4.20
+
+## 1.11.1-next.2
+
+### Patch Changes
+
+- 164711a: Added `cancelTask` to `MockSchedulerService` and mock scheduler service factory.
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0-next.1
+ - @backstage/backend-defaults@0.16.0-next.2
+ - @backstage/backend-app-api@1.6.0-next.1
+ - @backstage/plugin-auth-node@0.6.14-next.2
+ - @backstage/plugin-events-node@0.4.20-next.1
+
## 1.11.1-next.1
### Patch Changes
diff --git a/packages/backend-test-utils/package.json b/packages/backend-test-utils/package.json
index c8a6fe812d..4e5bcb2074 100644
--- a/packages/backend-test-utils/package.json
+++ b/packages/backend-test-utils/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/backend-test-utils",
- "version": "1.11.1-next.1",
+ "version": "1.11.2-next.1",
"description": "Test helpers library for Backstage backends",
"backstage": {
"role": "node-library"
@@ -79,7 +79,7 @@
"text-extensions": "^2.4.0",
"uuid": "^11.0.0",
"yn": "^4.0.0",
- "zod": "^3.25.76",
+ "zod": "^3.25.76 || ^4.0.0",
"zod-to-json-schema": "^3.25.1"
},
"devDependencies": {
diff --git a/packages/backend-test-utils/report-alpha.api.md b/packages/backend-test-utils/report-alpha.api.md
index b6bf9e883d..4813f49c35 100644
--- a/packages/backend-test-utils/report-alpha.api.md
+++ b/packages/backend-test-utils/report-alpha.api.md
@@ -7,7 +7,7 @@ import { ActionsRegistryActionOptions } from '@backstage/backend-plugin-api/alph
import { ActionsRegistryService } from '@backstage/backend-plugin-api/alpha';
import { ActionsService } from '@backstage/backend-plugin-api/alpha';
import { ActionsServiceAction } from '@backstage/backend-plugin-api/alpha';
-import { AnyZodObject } from 'zod';
+import { AnyZodObject } from 'zod/v3';
import { BackstageCredentials } from '@backstage/backend-plugin-api';
import { JsonObject } from '@backstage/types';
import { JsonValue } from '@backstage/types';
diff --git a/packages/backend-test-utils/src/alpha/services/MockActionsRegistry.ts b/packages/backend-test-utils/src/alpha/services/MockActionsRegistry.ts
index 384a5e8e95..d3d94d8d9c 100644
--- a/packages/backend-test-utils/src/alpha/services/MockActionsRegistry.ts
+++ b/packages/backend-test-utils/src/alpha/services/MockActionsRegistry.ts
@@ -19,7 +19,7 @@ import {
} from '@backstage/backend-plugin-api';
import { InputError, NotFoundError } from '@backstage/errors';
import { JsonObject, JsonValue } from '@backstage/types';
-import { z, AnyZodObject } from 'zod';
+import { z, AnyZodObject } from 'zod/v3';
import zodToJsonSchema from 'zod-to-json-schema';
import { mockCredentials } from '../../services';
import {
@@ -82,6 +82,7 @@ export class MockActionsRegistry
return {
actions: Array.from(this.actions.entries()).map(([id, action]) => ({
id,
+ pluginId: 'test',
name: action.name,
title: action.title,
description: action.description,
@@ -90,6 +91,7 @@ export class MockActionsRegistry
idempotent: action.attributes?.idempotent ?? false,
readOnly: action.attributes?.readOnly ?? false,
},
+ examples: action.examples,
schema: {
input: action.schema?.input
? zodToJsonSchema(action.schema.input(z))
diff --git a/packages/backend-test-utils/src/services/MockSchedulerService.test.ts b/packages/backend-test-utils/src/services/MockSchedulerService.test.ts
index faf4e3e26d..2668fa7205 100644
--- a/packages/backend-test-utils/src/services/MockSchedulerService.test.ts
+++ b/packages/backend-test-utils/src/services/MockSchedulerService.test.ts
@@ -206,6 +206,68 @@ describe('MockSchedulerService', () => {
await expect(isDone()).resolves.toBe(true);
});
+ it('should cancel a running task and allow re-triggering with a fresh signal', async () => {
+ const scheduler = new MockSchedulerService();
+ const signals: AbortSignal[] = [];
+
+ scheduler.scheduleTask({
+ ...baseOpts,
+ id: 'test',
+ fn: async signal => {
+ signals.push(signal);
+ // Simulate long-running work that respects cancellation
+ await new Promise((resolve, reject) => {
+ if (signal.aborted) {
+ reject(new Error('aborted'));
+ return;
+ }
+ signal.addEventListener('abort', () => reject(new Error('aborted')));
+ setTimeout(1).then(resolve);
+ });
+ },
+ });
+
+ // First run completes normally
+ await scheduler.triggerTask('test');
+ expect(signals).toHaveLength(1);
+ expect(signals[0].aborted).toBe(false);
+
+ // Start a task that will block until cancelled
+ const blockingScheduler = new MockSchedulerService();
+ let resolveBlock: (() => void) | undefined;
+ blockingScheduler.scheduleTask({
+ ...baseOpts,
+ id: 'blocking',
+ fn: async signal => {
+ signals.push(signal);
+ await new Promise((resolve, reject) => {
+ signal.addEventListener('abort', () => reject(new Error('aborted')));
+ resolveBlock = resolve;
+ });
+ },
+ });
+
+ const triggerPromise = blockingScheduler.triggerTask('blocking');
+ // Give the task fn time to start
+ await setTimeout(1);
+
+ await blockingScheduler.cancelTask('blocking');
+ await triggerPromise.catch(() => {});
+
+ expect(signals).toHaveLength(2);
+ expect(signals[1].aborted).toBe(true);
+
+ // Re-trigger should get a fresh non-aborted signal
+ resolveBlock = undefined;
+ const triggerPromise2 = blockingScheduler.triggerTask('blocking');
+ await setTimeout(1);
+ resolveBlock!();
+ await triggerPromise2;
+
+ expect(signals).toHaveLength(3);
+ expect(signals[2].aborted).toBe(false);
+ });
+
it('should abort tasks when shutting down', async () => {
let taskSignal: AbortSignal | undefined;
diff --git a/packages/backend-test-utils/src/services/MockSchedulerService.ts b/packages/backend-test-utils/src/services/MockSchedulerService.ts
index aafd6d98ec..3309ebc954 100644
--- a/packages/backend-test-utils/src/services/MockSchedulerService.ts
+++ b/packages/backend-test-utils/src/services/MockSchedulerService.ts
@@ -23,6 +23,7 @@ import {
SchedulerServiceTaskRunner,
SchedulerServiceTaskScheduleDefinition,
} from '@backstage/backend-plugin-api';
+import { ConflictError, NotFoundError } from '@backstage/errors';
import { createDeferred, DeferredPromise } from '@backstage/types';
export class MockSchedulerService implements SchedulerService {
@@ -95,10 +96,22 @@ export class MockSchedulerService implements SchedulerService {
});
}
+ async cancelTask(id: string): Promise {
+ const task = this.#tasks.get(id);
+ if (!task) {
+ throw new NotFoundError(`Task ${id} not found`);
+ }
+ if (!this.#runningTasks.has(id)) {
+ throw new ConflictError(`Task ${id} is not running`);
+ }
+ task.abortControllers.abort();
+ task.abortControllers = new AbortController();
+ }
+
async triggerTask(id: string): Promise {
const task = this.#tasks.get(id);
if (!task) {
- throw new Error(`Task ${id} not found`);
+ throw new NotFoundError(`Task ${id} not found`);
}
if (this.#runningTasks.has(id)) {
return;
diff --git a/packages/backend-test-utils/src/services/mockServices.ts b/packages/backend-test-utils/src/services/mockServices.ts
index 84783f04d7..4d54269b98 100644
--- a/packages/backend-test-utils/src/services/mockServices.ts
+++ b/packages/backend-test-utils/src/services/mockServices.ts
@@ -526,6 +526,7 @@ export namespace mockServices {
getScheduledTasks: jest.fn(),
scheduleTask: jest.fn(),
triggerTask: jest.fn(),
+ cancelTask: jest.fn(),
}));
}
diff --git a/packages/backend/CHANGELOG.md b/packages/backend/CHANGELOG.md
index 8e744ff611..9e3353c8be 100644
--- a/packages/backend/CHANGELOG.md
+++ b/packages/backend/CHANGELOG.md
@@ -1,5 +1,171 @@
# example-backend
+## 0.0.49-next.1
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.9.0-next.1
+ - @backstage/backend-defaults@0.16.1-next.1
+ - @backstage/plugin-catalog-backend@3.5.1-next.1
+ - @backstage/plugin-scaffolder-backend@3.3.0-next.1
+ - @backstage/plugin-auth-node@0.7.0-next.1
+ - @backstage/plugin-app-backend@0.5.13-next.1
+ - @backstage/plugin-auth-backend@0.28.0-next.1
+ - @backstage/plugin-auth-backend-module-github-provider@0.5.2-next.1
+ - @backstage/plugin-auth-backend-module-guest-provider@0.2.18-next.1
+ - @backstage/plugin-auth-backend-module-openshift-provider@0.1.6-next.1
+ - @backstage/plugin-catalog-backend-module-backstage-openapi@0.5.13-next.1
+ - @backstage/plugin-catalog-backend-module-logs@0.1.21-next.1
+ - @backstage/plugin-catalog-backend-module-openapi@0.2.21-next.1
+ - @backstage/plugin-catalog-backend-module-scaffolder-entity-model@0.2.19-next.1
+ - @backstage/plugin-catalog-backend-module-unprocessed@0.6.10-next.1
+ - @backstage/plugin-devtools-backend@0.5.16-next.1
+ - @backstage/plugin-events-backend@0.6.1-next.1
+ - @backstage/plugin-events-backend-module-google-pubsub@0.2.2-next.1
+ - @backstage/plugin-kubernetes-backend@0.21.3-next.1
+ - @backstage/plugin-mcp-actions-backend@0.1.11-next.1
+ - @backstage/plugin-notifications-backend@0.6.4-next.1
+ - @backstage/plugin-permission-backend@0.7.11-next.1
+ - @backstage/plugin-permission-backend-module-allow-all-policy@0.2.18-next.1
+ - @backstage/plugin-permission-node@0.10.12-next.1
+ - @backstage/plugin-proxy-backend@0.6.12-next.1
+ - @backstage/plugin-scaffolder-backend-module-github@0.9.8-next.1
+ - @backstage/plugin-scaffolder-backend-module-notifications@0.1.21-next.1
+ - @backstage/plugin-search-backend@2.1.1-next.1
+ - @backstage/plugin-search-backend-module-catalog@0.3.14-next.1
+ - @backstage/plugin-search-backend-module-elasticsearch@1.8.2-next.1
+ - @backstage/plugin-search-backend-module-explore@0.3.13-next.1
+ - @backstage/plugin-search-backend-module-techdocs@0.4.13-next.1
+ - @backstage/plugin-search-backend-node@1.4.3-next.1
+ - @backstage/plugin-signals-backend@0.3.14-next.1
+ - @backstage/plugin-techdocs-backend@2.1.7-next.1
+
+## 0.0.49-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/plugin-catalog-backend@3.5.1-next.0
+ - @backstage/plugin-auth-backend@0.28.0-next.0
+ - @backstage/backend-defaults@0.16.1-next.0
+ - @backstage/plugin-events-backend-module-google-pubsub@0.2.2-next.0
+ - @backstage/plugin-scaffolder-backend@3.2.1-next.0
+ - @backstage/backend-plugin-api@1.8.1-next.0
+ - @backstage/plugin-devtools-backend@0.5.16-next.0
+ - @backstage/plugin-catalog-backend-module-logs@0.1.21-next.0
+ - @backstage/plugin-auth-backend-module-github-provider@0.5.2-next.0
+ - @backstage/plugin-auth-backend-module-openshift-provider@0.1.6-next.0
+ - @backstage/plugin-notifications-backend@0.6.4-next.0
+ - @backstage/plugin-signals-backend@0.3.14-next.0
+ - @backstage/plugin-app-backend@0.5.13-next.0
+ - @backstage/plugin-auth-node@0.6.15-next.0
+ - @backstage/plugin-events-backend@0.6.1-next.0
+ - @backstage/plugin-kubernetes-backend@0.21.3-next.0
+ - @backstage/plugin-mcp-actions-backend@0.1.11-next.0
+ - @backstage/plugin-permission-backend@0.7.11-next.0
+ - @backstage/plugin-permission-node@0.10.12-next.0
+ - @backstage/plugin-proxy-backend@0.6.12-next.0
+ - @backstage/plugin-search-backend@2.1.1-next.0
+ - @backstage/plugin-search-backend-node@1.4.3-next.0
+ - @backstage/plugin-techdocs-backend@2.1.7-next.0
+ - @backstage/plugin-auth-backend-module-guest-provider@0.2.18-next.0
+ - @backstage/plugin-catalog-backend-module-backstage-openapi@0.5.13-next.0
+ - @backstage/plugin-catalog-backend-module-openapi@0.2.21-next.0
+ - @backstage/plugin-catalog-backend-module-scaffolder-entity-model@0.2.19-next.0
+ - @backstage/plugin-catalog-backend-module-unprocessed@0.6.10-next.0
+ - @backstage/plugin-permission-backend-module-allow-all-policy@0.2.18-next.0
+ - @backstage/plugin-scaffolder-backend-module-github@0.9.8-next.0
+ - @backstage/plugin-scaffolder-backend-module-notifications@0.1.21-next.0
+ - @backstage/plugin-search-backend-module-catalog@0.3.14-next.0
+ - @backstage/plugin-search-backend-module-elasticsearch@1.8.2-next.0
+ - @backstage/plugin-search-backend-module-explore@0.3.13-next.0
+ - @backstage/plugin-search-backend-module-techdocs@0.4.13-next.0
+ - @backstage/catalog-model@1.7.7
+ - @backstage/plugin-permission-common@0.9.7
+
+## 0.0.48
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0
+ - @backstage/backend-defaults@0.16.0
+ - @backstage/plugin-catalog-backend@3.5.0
+ - @backstage/plugin-auth-backend@0.27.2
+ - @backstage/plugin-techdocs-backend@2.1.6
+ - @backstage/plugin-scaffolder-backend-module-github@0.9.7
+ - @backstage/plugin-scaffolder-backend@3.2.0
+ - @backstage/plugin-mcp-actions-backend@0.1.10
+ - @backstage/plugin-kubernetes-backend@0.21.2
+ - @backstage/plugin-events-backend@0.6.0
+ - @backstage/plugin-search-backend@2.1.0
+ - @backstage/plugin-auth-backend-module-openshift-provider@0.1.5
+ - @backstage/plugin-auth-backend-module-github-provider@0.5.1
+ - @backstage/plugin-permission-backend@0.7.10
+ - @backstage/plugin-permission-common@0.9.7
+ - @backstage/plugin-permission-node@0.10.11
+ - @backstage/catalog-model@1.7.7
+ - @backstage/plugin-auth-node@0.6.14
+ - @backstage/plugin-app-backend@0.5.12
+ - @backstage/plugin-auth-backend-module-guest-provider@0.2.17
+ - @backstage/plugin-catalog-backend-module-backstage-openapi@0.5.12
+ - @backstage/plugin-catalog-backend-module-openapi@0.2.20
+ - @backstage/plugin-catalog-backend-module-scaffolder-entity-model@0.2.18
+ - @backstage/plugin-catalog-backend-module-unprocessed@0.6.9
+ - @backstage/plugin-devtools-backend@0.5.15
+ - @backstage/plugin-events-backend-module-google-pubsub@0.2.1
+ - @backstage/plugin-notifications-backend@0.6.3
+ - @backstage/plugin-permission-backend-module-allow-all-policy@0.2.17
+ - @backstage/plugin-proxy-backend@0.6.11
+ - @backstage/plugin-scaffolder-backend-module-notifications@0.1.20
+ - @backstage/plugin-search-backend-module-catalog@0.3.13
+ - @backstage/plugin-search-backend-module-elasticsearch@1.8.1
+ - @backstage/plugin-search-backend-module-explore@0.3.12
+ - @backstage/plugin-search-backend-module-techdocs@0.4.12
+ - @backstage/plugin-search-backend-node@1.4.2
+ - @backstage/plugin-signals-backend@0.3.13
+
+## 0.0.48-next.2
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/backend-plugin-api@1.8.0-next.1
+ - @backstage/backend-defaults@0.16.0-next.2
+ - @backstage/plugin-auth-backend@0.27.1-next.2
+ - @backstage/plugin-catalog-backend@3.5.0-next.2
+ - @backstage/plugin-scaffolder-backend@3.2.0-next.2
+ - @backstage/plugin-mcp-actions-backend@0.1.10-next.2
+ - @backstage/plugin-scaffolder-backend-module-github@0.9.7-next.2
+ - @backstage/plugin-app-backend@0.5.12-next.1
+ - @backstage/plugin-auth-backend-module-github-provider@0.5.1-next.1
+ - @backstage/plugin-auth-backend-module-guest-provider@0.2.17-next.1
+ - @backstage/plugin-auth-backend-module-openshift-provider@0.1.5-next.1
+ - @backstage/plugin-auth-node@0.6.14-next.2
+ - @backstage/plugin-catalog-backend-module-backstage-openapi@0.5.12-next.1
+ - @backstage/plugin-catalog-backend-module-openapi@0.2.20-next.2
+ - @backstage/plugin-catalog-backend-module-scaffolder-entity-model@0.2.18-next.2
+ - @backstage/plugin-catalog-backend-module-unprocessed@0.6.9-next.1
+ - @backstage/plugin-devtools-backend@0.5.15-next.1
+ - @backstage/plugin-events-backend@0.6.0-next.2
+ - @backstage/plugin-events-backend-module-google-pubsub@0.2.1-next.1
+ - @backstage/plugin-kubernetes-backend@0.21.2-next.2
+ - @backstage/plugin-notifications-backend@0.6.3-next.1
+ - @backstage/plugin-permission-backend@0.7.10-next.1
+ - @backstage/plugin-permission-backend-module-allow-all-policy@0.2.17-next.1
+ - @backstage/plugin-permission-node@0.10.11-next.1
+ - @backstage/plugin-proxy-backend@0.6.11-next.1
+ - @backstage/plugin-scaffolder-backend-module-notifications@0.1.20-next.2
+ - @backstage/plugin-search-backend@2.1.0-next.2
+ - @backstage/plugin-search-backend-module-catalog@0.3.13-next.2
+ - @backstage/plugin-search-backend-module-elasticsearch@1.8.1-next.1
+ - @backstage/plugin-search-backend-module-explore@0.3.12-next.1
+ - @backstage/plugin-search-backend-module-techdocs@0.4.12-next.2
+ - @backstage/plugin-search-backend-node@1.4.2-next.1
+ - @backstage/plugin-signals-backend@0.3.13-next.1
+ - @backstage/plugin-techdocs-backend@2.1.6-next.2
+
## 0.0.48-next.1
### Patch Changes
diff --git a/packages/backend/package.json b/packages/backend/package.json
index 01de1d1626..fd2c166773 100644
--- a/packages/backend/package.json
+++ b/packages/backend/package.json
@@ -1,6 +1,6 @@
{
"name": "example-backend",
- "version": "0.0.48-next.1",
+ "version": "0.0.49-next.1",
"backstage": {
"role": "backend"
},
@@ -41,6 +41,7 @@
"@backstage/plugin-auth-node": "workspace:^",
"@backstage/plugin-catalog-backend": "workspace:^",
"@backstage/plugin-catalog-backend-module-backstage-openapi": "workspace:^",
+ "@backstage/plugin-catalog-backend-module-logs": "workspace:^",
"@backstage/plugin-catalog-backend-module-openapi": "workspace:^",
"@backstage/plugin-catalog-backend-module-scaffolder-entity-model": "workspace:^",
"@backstage/plugin-catalog-backend-module-unprocessed": "workspace:^",
@@ -66,9 +67,9 @@
"@backstage/plugin-search-backend-node": "workspace:^",
"@backstage/plugin-signals-backend": "workspace:^",
"@backstage/plugin-techdocs-backend": "workspace:^",
- "@opentelemetry/auto-instrumentations-node": "^0.67.0",
- "@opentelemetry/exporter-prometheus": "^0.211.0",
- "@opentelemetry/sdk-node": "^0.211.0",
+ "@opentelemetry/auto-instrumentations-node": "^0.71.0",
+ "@opentelemetry/exporter-prometheus": "^0.213.0",
+ "@opentelemetry/sdk-node": "^0.213.0",
"example-app": "link:../app"
},
"devDependencies": {
diff --git a/packages/backend/src/index.ts b/packages/backend/src/index.ts
index 14eb36a3a6..e77c83baac 100644
--- a/packages/backend/src/index.ts
+++ b/packages/backend/src/index.ts
@@ -50,6 +50,7 @@ backend.add(
import('@backstage/plugin-catalog-backend-module-scaffolder-entity-model'),
);
backend.add(import('@backstage/plugin-catalog-backend'));
+backend.add(import('@backstage/plugin-catalog-backend-module-logs'));
backend.add(import('@backstage/plugin-events-backend'));
backend.add(import('@backstage/plugin-devtools-backend'));
backend.add(import('@backstage/plugin-kubernetes-backend'));
diff --git a/packages/catalog-client/CHANGELOG.md b/packages/catalog-client/CHANGELOG.md
index 62b214a403..874212077b 100644
--- a/packages/catalog-client/CHANGELOG.md
+++ b/packages/catalog-client/CHANGELOG.md
@@ -1,5 +1,32 @@
# @backstage/catalog-client
+## 1.14.0
+
+### Minor Changes
+
+- 972f686: Added support for the `query` field in `getEntitiesByRefs` requests, enabling predicate-based filtering with `$all`, `$any`, `$not`, `$exists`, `$in`, `$contains`, and `$hasPrefix` operators.
+- 5d95e8e: Add an `onConflict` option to location creation that can refresh an existing location instead of throwing a conflict error.
+- 56c908e: Added support for the `query` field in `getEntityFacets` requests, enabling predicate-based filtering with `$all`, `$any`, `$not`, `$exists`, `$in`, `$contains`, and `$hasPrefix` operators.
+- 0fbcf23: Migrated OpenAPI schemas to 3.1.
+- 51e23eb: Added predicate-based entity filtering via POST /entities/by-query endpoint.
+
+ Supports `$all`, `$any`, `$not`, `$exists`, `$in`, `$hasPrefix`, and (partially) `$contains` operators for expressive entity queries. Integrated into the existing `queryEntities` flow with full cursor-based pagination, permission enforcement, and `totalItems` support.
+
+ The catalog client's `queryEntities()` method automatically routes to the POST endpoint when a `query` predicate is provided.
+
+### Patch Changes
+
+- d2494d6: Minor update to catalog client docs
+- Updated dependencies
+ - @backstage/filter-predicates@0.1.1
+ - @backstage/catalog-model@1.7.7
+
+## 1.14.0-next.2
+
+### Minor Changes
+
+- 5d95e8e: Add an `onConflict` option to location creation that can refresh an existing location instead of throwing a conflict error.
+
## 1.14.0-next.1
### Minor Changes
diff --git a/packages/catalog-client/package.json b/packages/catalog-client/package.json
index 20a68905a0..1235f4d5ca 100644
--- a/packages/catalog-client/package.json
+++ b/packages/catalog-client/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/catalog-client",
- "version": "1.14.0-next.1",
+ "version": "1.14.0",
"description": "An isomorphic client for the catalog backend",
"backstage": {
"role": "common-library"
diff --git a/packages/catalog-client/report.api.md b/packages/catalog-client/report.api.md
index c155084ccd..73eb280d87 100644
--- a/packages/catalog-client/report.api.md
+++ b/packages/catalog-client/report.api.md
@@ -15,6 +15,7 @@ export type AddLocationRequest = {
type?: string;
target: string;
dryRun?: boolean;
+ onConflict?: 'refresh' | 'reject';
};
// @public
diff --git a/packages/catalog-client/src/CatalogClient.ts b/packages/catalog-client/src/CatalogClient.ts
index a671a155d3..cf363e1823 100644
--- a/packages/catalog-client/src/CatalogClient.ts
+++ b/packages/catalog-client/src/CatalogClient.ts
@@ -567,12 +567,15 @@ export class CatalogClient implements CatalogApi {
request: AddLocationRequest,
options?: CatalogRequestOptions,
): Promise {
- const { type = 'url', target, dryRun } = request;
+ const { type = 'url', target, dryRun, onConflict } = request;
const response = await this.apiClient.createLocation(
{
body: { type, target },
- query: { dryRun: dryRun ? 'true' : undefined },
+ query: {
+ dryRun: dryRun ? 'true' : undefined,
+ onConflict,
+ },
},
options,
);
diff --git a/packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts b/packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts
index 63d55aea55..4b3e088fe2 100644
--- a/packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts
+++ b/packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts
@@ -178,6 +178,7 @@ export type CreateLocation = {
body: CreateLocationRequest;
query: {
dryRun?: string;
+ onConflict?: 'refresh' | 'reject';
};
};
/**
@@ -592,6 +593,7 @@ export class DefaultApiClient {
* Create a location for a given target.
* @param createLocationRequest -
* @param dryRun -
+ * @param onConflict - Behavior when the location already exists. \'reject\' (default) returns a 409 error, \'refresh\' triggers a refresh of the existing location entity and returns 201.
*/
public async createLocation(
// @ts-ignore
@@ -600,7 +602,7 @@ export class DefaultApiClient {
): Promise> {
const baseUrl = await this.discoveryApi.getBaseUrl(pluginId);
- const uriTemplate = `/locations{?dryRun}`;
+ const uriTemplate = `/locations{?dryRun,onConflict}`;
const uri = parser.parse(uriTemplate).expand({
...request.query,
diff --git a/packages/catalog-client/src/types/api.ts b/packages/catalog-client/src/types/api.ts
index fac4ed5928..d6d5392fcf 100644
--- a/packages/catalog-client/src/types/api.ts
+++ b/packages/catalog-client/src/types/api.ts
@@ -396,6 +396,12 @@ export type AddLocationRequest = {
* contain the entities that match the given location.
*/
dryRun?: boolean;
+ /**
+ * Behavior when the location already exists. If set to `'reject'` (the
+ * default), a conflict error is returned. If set to `'refresh'`, the
+ * existing location entity is marked for refresh and a 201 is returned.
+ */
+ onConflict?: 'refresh' | 'reject';
};
/**
diff --git a/packages/catalog-model/CHANGELOG.md b/packages/catalog-model/CHANGELOG.md
index 2fb24c4943..6d3927a404 100644
--- a/packages/catalog-model/CHANGELOG.md
+++ b/packages/catalog-model/CHANGELOG.md
@@ -1,5 +1,11 @@
# @backstage/catalog-model
+## 1.7.7
+
+### Patch Changes
+
+- a49a40d: Updated dependency `zod` to `^3.25.76 || ^4.0.0` & migrated to `/v3` or `/v4` imports.
+
## 1.7.6
### Patch Changes
diff --git a/packages/catalog-model/examples/apis/hello-world-trpc-api.yaml b/packages/catalog-model/examples/apis/hello-world-trpc-api.yaml
index f5807537b3..f1847154ce 100644
--- a/packages/catalog-model/examples/apis/hello-world-trpc-api.yaml
+++ b/packages/catalog-model/examples/apis/hello-world-trpc-api.yaml
@@ -8,7 +8,7 @@ spec:
lifecycle: experimental
owner: team-c
definition: |
- import { z } from 'zod';
+ import { z } from 'zod/v3';
import { publicProcedure, router } from '../trpc';
export const apiRouter = router({
diff --git a/packages/catalog-model/package.json b/packages/catalog-model/package.json
index 85c299e941..ddee09d18f 100644
--- a/packages/catalog-model/package.json
+++ b/packages/catalog-model/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/catalog-model",
- "version": "1.7.6",
+ "version": "1.7.7",
"description": "Types and validators that help describe the model of a Backstage Catalog",
"backstage": {
"role": "common-library"
diff --git a/packages/cli-common/CHANGELOG.md b/packages/cli-common/CHANGELOG.md
index d7a5679026..cbff8fe79c 100644
--- a/packages/cli-common/CHANGELOG.md
+++ b/packages/cli-common/CHANGELOG.md
@@ -1,5 +1,53 @@
# @backstage/cli-common
+## 0.2.1-next.0
+
+### Patch Changes
+
+- e928e73: chore(deps): bump `undici` from 7.22.0 to 7.24.0
+- Updated dependencies
+ - @backstage/errors@1.2.7
+
+## 0.2.0
+
+### Minor Changes
+
+- 56bd494: Added `targetPaths` and `findOwnPaths` as replacements for `findPaths`, with a cleaner separation between target project paths and package-relative paths.
+
+ To migrate existing `findPaths` usage:
+
+ ```ts
+ // Before
+ import { findPaths } from '@backstage/cli-common';
+ const paths = findPaths(__dirname);
+
+ // After — for target project paths (cwd-based):
+ import { targetPaths } from '@backstage/cli-common';
+ // paths.targetDir → targetPaths.dir
+ // paths.targetRoot → targetPaths.rootDir
+ // paths.resolveTarget('src') → targetPaths.resolve('src')
+ // paths.resolveTargetRoot('yarn.lock') → targetPaths.resolveRoot('yarn.lock')
+
+ // After — for package-relative paths:
+ import { findOwnPaths } from '@backstage/cli-common';
+ const own = findOwnPaths(__dirname);
+ // paths.ownDir → own.dir
+ // paths.ownRoot → own.rootDir
+ // paths.resolveOwn('config/jest.js') → own.resolve('config/jest.js')
+ // paths.resolveOwnRoot('tsconfig.json') → own.resolveRoot('tsconfig.json')
+ ```
+
+### Patch Changes
+
+- e44b6a9: The `findOwnRootDir` utility now searches for the monorepo root by traversing up the directory tree looking for a `package.json` with `workspaces`, instead of assuming a fixed `../..` relative path. If no workspaces root is found during this traversal, `findOwnRootDir` now throws to enforce stricter validation of the repository layout.
+- 9361965: Fixed `runCheck` to ignore stdio of the spawned process, preventing unwanted output from leaking to the terminal.
+
+## 0.2.0-next.2
+
+### Patch Changes
+
+- 9361965: Fixed `runCheck` to ignore stdio of the spawned process, preventing unwanted output from leaking to the terminal.
+
## 0.2.0-next.1
### Patch Changes
diff --git a/packages/cli-common/package.json b/packages/cli-common/package.json
index 7e44334900..b393335552 100644
--- a/packages/cli-common/package.json
+++ b/packages/cli-common/package.json
@@ -1,6 +1,6 @@
{
"name": "@backstage/cli-common",
- "version": "0.2.0-next.1",
+ "version": "0.2.1-next.0",
"description": "Common functionality used by cli, backend, and create-app",
"backstage": {
"role": "node-library"
@@ -51,7 +51,7 @@
"@backstage/errors": "workspace:^",
"cross-spawn": "^7.0.3",
"global-agent": "^3.0.0",
- "undici": "^7.2.3"
+ "undici": "^7.24.5"
},
"devDependencies": {
"@backstage/cli": "workspace:^",
diff --git a/packages/cli/templates/backend-plugin-module/.eslintrc.js.hbs b/packages/cli-defaults/.eslintrc.js
similarity index 100%
rename from packages/cli/templates/backend-plugin-module/.eslintrc.js.hbs
rename to packages/cli-defaults/.eslintrc.js
diff --git a/packages/cli-defaults/CHANGELOG.md b/packages/cli-defaults/CHANGELOG.md
new file mode 100644
index 0000000000..df2ea6932b
--- /dev/null
+++ b/packages/cli-defaults/CHANGELOG.md
@@ -0,0 +1,42 @@
+# @backstage/cli-defaults
+
+## 0.1.1-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-module-build@0.1.1-next.0
+ - @backstage/cli-module-config@0.1.1-next.0
+ - @backstage/cli-module-github@0.1.1-next.0
+ - @backstage/cli-module-info@0.1.1-next.0
+ - @backstage/cli-module-lint@0.1.1-next.0
+ - @backstage/cli-module-maintenance@0.1.1-next.0
+ - @backstage/cli-module-migrate@0.1.1-next.0
+ - @backstage/cli-module-new@0.1.1-next.0
+ - @backstage/cli-module-test-jest@0.1.1-next.0
+ - @backstage/cli-module-translations@0.1.1-next.0
+ - @backstage/cli-module-actions@0.0.2-next.0
+ - @backstage/cli-module-auth@0.1.1-next.0
+
+## 0.1.0
+
+### Minor Changes
+
+- 7781ae5: Introduced `@backstage/cli-defaults`, a convenience package that bundles all standard Backstage CLI modules. Install this single package as a `devDependency` to get the full default set of CLI commands without listing each module individually.
+
+### Patch Changes
+
+- 42960f1: Added `@backstage/cli-module-actions` to the default set of CLI modules.
+- Updated dependencies
+ - @backstage/cli-module-actions@0.0.1
+ - @backstage/cli-module-new@0.1.0
+ - @backstage/cli-module-maintenance@0.1.0
+ - @backstage/cli-module-build@0.1.0
+ - @backstage/cli-module-auth@0.1.0
+ - @backstage/cli-module-config@0.1.0
+ - @backstage/cli-module-github@0.1.0
+ - @backstage/cli-module-info@0.1.0
+ - @backstage/cli-module-lint@0.1.0
+ - @backstage/cli-module-migrate@0.1.0
+ - @backstage/cli-module-test-jest@0.1.0
+ - @backstage/cli-module-translations@0.1.0
diff --git a/packages/cli-defaults/README.md b/packages/cli-defaults/README.md
new file mode 100644
index 0000000000..2066aa1e35
--- /dev/null
+++ b/packages/cli-defaults/README.md
@@ -0,0 +1,26 @@
+# @backstage/cli-defaults
+
+The default set of CLI modules for the Backstage CLI. Installing this single package provides all standard CLI commands without needing to list each module individually.
+
+## Included Modules
+
+| Module | Description |
+| :----------------------------------------------------------------- | :--------------------------------------- |
+| [`@backstage/cli-module-auth`](../cli-module-auth) | Authentication commands |
+| [`@backstage/cli-module-build`](../cli-module-build) | Build, start, and packaging commands |
+| [`@backstage/cli-module-config`](../cli-module-config) | Configuration inspection commands |
+| [`@backstage/cli-module-github`](../cli-module-github) | GitHub App creation |
+| [`@backstage/cli-module-info`](../cli-module-info) | Environment and dependency info |
+| [`@backstage/cli-module-lint`](../cli-module-lint) | Linting commands |
+| [`@backstage/cli-module-maintenance`](../cli-module-maintenance) | Repository maintenance commands |
+| [`@backstage/cli-module-migrate`](../cli-module-migrate) | Migration and version management |
+| [`@backstage/cli-module-new`](../cli-module-new) | Scaffolding for new plugins and packages |
+| [`@backstage/cli-module-test-jest`](../cli-module-test-jest) | Jest-based testing commands |
+| [`@backstage/cli-module-translations`](../cli-module-translations) | Translation management commands |
+
+For fine-grained control over which CLI commands are available, you can install individual modules instead.
+
+## Documentation
+
+- [Backstage Readme](https://github.com/backstage/backstage/blob/master/README.md)
+- [Backstage Documentation](https://backstage.io/docs)
diff --git a/packages/cli-defaults/catalog-info.yaml b/packages/cli-defaults/catalog-info.yaml
new file mode 100644
index 0000000000..3cac883c36
--- /dev/null
+++ b/packages/cli-defaults/catalog-info.yaml
@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: backstage-cli-defaults
+ title: '@backstage/cli-defaults'
+ description: Default set of CLI modules for the Backstage CLI
+spec:
+ lifecycle: experimental
+ type: backstage-cli-module
+ owner: tooling-maintainers
diff --git a/packages/cli-defaults/package.json b/packages/cli-defaults/package.json
new file mode 100644
index 0000000000..63f5507729
--- /dev/null
+++ b/packages/cli-defaults/package.json
@@ -0,0 +1,49 @@
+{
+ "name": "@backstage/cli-defaults",
+ "version": "0.1.1-next.0",
+ "description": "Default set of CLI modules for the Backstage CLI",
+ "backstage": {
+ "role": "cli-module"
+ },
+ "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-defaults"
+ },
+ "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"
+ },
+ "dependencies": {
+ "@backstage/cli-module-actions": "workspace:^",
+ "@backstage/cli-module-auth": "workspace:^",
+ "@backstage/cli-module-build": "workspace:^",
+ "@backstage/cli-module-config": "workspace:^",
+ "@backstage/cli-module-github": "workspace:^",
+ "@backstage/cli-module-info": "workspace:^",
+ "@backstage/cli-module-lint": "workspace:^",
+ "@backstage/cli-module-maintenance": "workspace:^",
+ "@backstage/cli-module-migrate": "workspace:^",
+ "@backstage/cli-module-new": "workspace:^",
+ "@backstage/cli-module-test-jest": "workspace:^",
+ "@backstage/cli-module-translations": "workspace:^"
+ },
+ "devDependencies": {
+ "@backstage/cli": "workspace:^"
+ }
+}
diff --git a/packages/cli-defaults/report.api.md b/packages/cli-defaults/report.api.md
new file mode 100644
index 0000000000..573f8ee454
--- /dev/null
+++ b/packages/cli-defaults/report.api.md
@@ -0,0 +1,13 @@
+## API Report File for "@backstage/cli-defaults"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { CliModule } from '@backstage/cli-node';
+
+// @public
+const _default: CliModule[];
+export default _default;
+
+// (No @packageDocumentation comment for this package)
+```
diff --git a/packages/cli-defaults/src/index.ts b/packages/cli-defaults/src/index.ts
new file mode 100644
index 0000000000..f167c3c424
--- /dev/null
+++ b/packages/cli-defaults/src/index.ts
@@ -0,0 +1,47 @@
+/*
+ * Copyright 2025 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 actions from '@backstage/cli-module-actions';
+import auth from '@backstage/cli-module-auth';
+import build from '@backstage/cli-module-build';
+import config from '@backstage/cli-module-config';
+import github from '@backstage/cli-module-github';
+import info from '@backstage/cli-module-info';
+import lint from '@backstage/cli-module-lint';
+import maintenance from '@backstage/cli-module-maintenance';
+import migrate from '@backstage/cli-module-migrate';
+import newModule from '@backstage/cli-module-new';
+import testJest from '@backstage/cli-module-test-jest';
+import translations from '@backstage/cli-module-translations';
+
+/**
+ * The default set of CLI modules for the Backstage CLI.
+ *
+ * @public
+ */
+export default [
+ actions,
+ auth,
+ build,
+ config,
+ github,
+ info,
+ lint,
+ maintenance,
+ migrate,
+ newModule,
+ testJest,
+ translations,
+];
diff --git a/packages/cli/templates/backend-plugin/.eslintrc.js.hbs b/packages/cli-internal/.eslintrc.js
similarity index 100%
rename from packages/cli/templates/backend-plugin/.eslintrc.js.hbs
rename to packages/cli-internal/.eslintrc.js
diff --git a/packages/cli-internal/CHANGELOG.md b/packages/cli-internal/CHANGELOG.md
new file mode 100644
index 0000000000..30a090f3ef
--- /dev/null
+++ b/packages/cli-internal/CHANGELOG.md
@@ -0,0 +1,15 @@
+# @internal/cli
+
+## 0.0.3-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-node@0.3.1-next.0
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-node@0.3.0
diff --git a/packages/cli-internal/catalog-info.yaml b/packages/cli-internal/catalog-info.yaml
new file mode 100644
index 0000000000..2f2a1c837a
--- /dev/null
+++ b/packages/cli-internal/catalog-info.yaml
@@ -0,0 +1,9 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: internal-cli
+ title: '@internal/cli'
+spec:
+ lifecycle: experimental
+ type: backstage-node-library
+ owner: tooling-maintainers
diff --git a/packages/cli-internal/package.json b/packages/cli-internal/package.json
new file mode 100644
index 0000000000..79030bdbe0
--- /dev/null
+++ b/packages/cli-internal/package.json
@@ -0,0 +1,30 @@
+{
+ "name": "@internal/cli",
+ "version": "0.0.3-next.0",
+ "backstage": {
+ "role": "node-library",
+ "inline": true
+ },
+ "private": true,
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/backstage/backstage",
+ "directory": "packages/cli-internal"
+ },
+ "license": "Apache-2.0",
+ "main": "src/index.ts",
+ "types": "src/index.ts",
+ "files": [
+ "dist"
+ ],
+ "scripts": {
+ "lint": "backstage-cli package lint",
+ "test": "backstage-cli package test"
+ },
+ "dependencies": {
+ "@backstage/cli-node": "workspace:^"
+ },
+ "devDependencies": {
+ "@backstage/cli": "workspace:^"
+ }
+}
diff --git a/packages/cli-internal/src/InternalCliModule.ts b/packages/cli-internal/src/InternalCliModule.ts
new file mode 100644
index 0000000000..213e309371
--- /dev/null
+++ b/packages/cli-internal/src/InternalCliModule.ts
@@ -0,0 +1,30 @@
+/*
+ * 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 { CliCommand, CliModule } from '@backstage/cli-node';
+import { OpaqueType } from '@internal/opaque';
+
+export const OpaqueCliModule = OpaqueType.create<{
+ public: CliModule;
+ versions: {
+ readonly version: 'v1';
+ readonly packageName: string;
+ readonly commands: Promise>;
+ };
+}>({
+ type: '@backstage/CliModule',
+ versions: ['v1'],
+});
diff --git a/packages/cli-internal/src/InternalCommandNode.ts b/packages/cli-internal/src/InternalCommandNode.ts
new file mode 100644
index 0000000000..233e9128cb
--- /dev/null
+++ b/packages/cli-internal/src/InternalCommandNode.ts
@@ -0,0 +1,69 @@
+/*
+ * 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 { CliCommand, CliModule } from '@backstage/cli-node';
+import { OpaqueType } from '@internal/opaque';
+
+/** @internal */
+export interface CommandTreeNode {
+ readonly $$type: '@backstage/CommandTreeNode';
+}
+
+/** @internal */
+export interface CommandLeafNode {
+ readonly $$type: '@backstage/CommandLeafNode';
+}
+
+export type CommandNode = CommandTreeNode | CommandLeafNode;
+
+export const OpaqueCommandTreeNode = OpaqueType.create<{
+ public: CommandTreeNode;
+ versions: {
+ readonly version: 'v1';
+ readonly name: string;
+ readonly children: CommandNode[];
+ };
+}>({
+ type: '@backstage/CommandTreeNode',
+ versions: ['v1'],
+});
+
+export const OpaqueCommandLeafNode = OpaqueType.create<{
+ public: CommandLeafNode;
+ versions: {
+ readonly version: 'v1';
+ readonly name: string;
+ readonly command: CliCommand;
+ readonly module?: CliModule;
+ };
+}>({
+ type: '@backstage/CommandLeafNode',
+ versions: ['v1'],
+});
+
+/**
+ * Checks whether a command node should be hidden from help output.
+ * Leaf nodes are hidden if they are deprecated or experimental.
+ * Tree nodes are hidden if all of their children are hidden.
+ */
+export function isCommandNodeHidden(node: CommandNode): boolean {
+ if (OpaqueCommandLeafNode.isType(node)) {
+ const { command } = OpaqueCommandLeafNode.toInternal(node);
+ return !!command.deprecated || !!command.experimental;
+ }
+ const { children } = OpaqueCommandTreeNode.toInternal(node);
+ return children.every(child => isCommandNodeHidden(child));
+}
diff --git a/packages/cli-internal/src/authIdentifiers.ts b/packages/cli-internal/src/authIdentifiers.ts
new file mode 100644
index 0000000000..6b72554a4f
--- /dev/null
+++ b/packages/cli-internal/src/authIdentifiers.ts
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2025 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.
+ */
+
+/** Returns the secret-store service key for a given auth instance. */
+export function getAuthInstanceService(instanceName: string): string {
+ return `backstage-cli:auth-instance:${instanceName}`;
+}
diff --git a/packages/cli-internal/src/index.ts b/packages/cli-internal/src/index.ts
new file mode 100644
index 0000000000..dfd8968c6a
--- /dev/null
+++ b/packages/cli-internal/src/index.ts
@@ -0,0 +1,37 @@
+/*
+ * 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.
+ */
+
+export { OpaqueCliModule } from './InternalCliModule';
+export type {
+ CommandNode,
+ CommandTreeNode,
+ CommandLeafNode,
+} from './InternalCommandNode';
+export {
+ OpaqueCommandTreeNode,
+ OpaqueCommandLeafNode,
+ isCommandNodeHidden,
+} from './InternalCommandNode';
+export { getAuthInstanceService } from './authIdentifiers';
+export {
+ getSecretStore,
+ resetSecretStore,
+ type SecretStore,
+} from './secretStore';
+export {
+ knownBackendPluginPackageNameByPluginId,
+ knownFrontendPluginPackageNameByPluginId,
+} from './knownPluginPackages';
diff --git a/packages/cli-internal/src/knownPluginPackages.ts b/packages/cli-internal/src/knownPluginPackages.ts
new file mode 100644
index 0000000000..c5d13beef1
--- /dev/null
+++ b/packages/cli-internal/src/knownPluginPackages.ts
@@ -0,0 +1,65 @@
+/*
+ * Copyright 2025 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 knownBackendPluginIds = [
+ 'app',
+ 'auth',
+ 'catalog',
+ 'events',
+ 'kubernetes',
+ 'notifications',
+ 'permission',
+ 'proxy',
+ 'scaffolder',
+ 'search',
+ 'signals',
+ 'techdocs',
+];
+
+// Only includes plugin IDs that have a corresponding frontend package; some plugins are backend-only and not listed here.
+const knownFrontendPluginIds = [
+ 'app',
+ 'auth',
+ 'catalog',
+ 'kubernetes',
+ 'notifications',
+ 'scaffolder',
+ 'search',
+ 'signals',
+ 'techdocs',
+];
+
+/**
+ * Maps known plugin IDs to their corresponding backend package names.
+ */
+export const knownBackendPluginPackageNameByPluginId: Record =
+ Object.fromEntries(
+ knownBackendPluginIds.map(pluginId => [
+ pluginId,
+ `@backstage/plugin-${pluginId}-backend`,
+ ]),
+ );
+
+/**
+ * Maps known plugin IDs to their corresponding frontend package names.
+ */
+export const knownFrontendPluginPackageNameByPluginId: Record =
+ Object.fromEntries(
+ knownFrontendPluginIds.map(pluginId => [
+ pluginId,
+ `@backstage/plugin-${pluginId}`,
+ ]),
+ );
diff --git a/packages/cli-internal/src/secretStore.ts b/packages/cli-internal/src/secretStore.ts
new file mode 100644
index 0000000000..26c1e6ad2b
--- /dev/null
+++ b/packages/cli-internal/src/secretStore.ts
@@ -0,0 +1,127 @@
+/*
+ * Copyright 2025 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 { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export type SecretStore = {
+ get(service: string, account: string): Promise;
+ set(service: string, account: string, secret: string): Promise;
+ delete(service: string, account: string): Promise;
+};
+
+async function loadKeytar(): Promise {
+ try {
+ // eslint-disable-next-line import/no-extraneous-dependencies, @backstage/no-undeclared-imports
+ const keytar = require('keytar') as typeof import('keytar');
+ if (keytar && typeof keytar.getPassword === 'function') {
+ return keytar;
+ }
+ } catch {
+ // keytar not available
+ }
+ return undefined;
+}
+
+class KeytarSecretStore implements SecretStore {
+ private readonly keytar: typeof import('keytar');
+ constructor(keytar: typeof import('keytar')) {
+ this.keytar = keytar;
+ }
+ async get(service: string, account: string): Promise {
+ const result = await this.keytar.getPassword(service, account);
+ return result ?? undefined;
+ }
+ async set(service: string, account: string, secret: string): Promise {
+ await this.keytar.setPassword(service, account, secret);
+ }
+ async delete(service: string, account: string): Promise {
+ await this.keytar.deletePassword(service, account);
+ }
+}
+
+async function pathExists(p: string): Promise {
+ try {
+ await fs.stat(p);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+class FileSecretStore implements SecretStore {
+ private readonly baseDir: string;
+ constructor() {
+ const root =
+ process.env.XDG_DATA_HOME ||
+ (process.platform === 'win32'
+ ? process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming')
+ : path.join(os.homedir(), '.local', 'share'));
+ this.baseDir = path.join(root, 'backstage-cli', 'auth-secrets');
+ }
+ private filePath(service: string, account: string): string {
+ return path.join(
+ this.baseDir,
+ encodeURIComponent(service),
+ `${encodeURIComponent(account)}.secret`,
+ );
+ }
+ async get(service: string, account: string): Promise {
+ const file = this.filePath(service, account);
+ if (!(await pathExists(file))) {
+ return undefined;
+ }
+ return await fs.readFile(file, 'utf8');
+ }
+ async set(service: string, account: string, secret: string): Promise {
+ const file = this.filePath(service, account);
+ await fs.mkdir(path.dirname(file), { recursive: true });
+ await fs.writeFile(file, secret, { encoding: 'utf8', mode: 0o600 });
+ }
+ async delete(service: string, account: string): Promise {
+ const file = this.filePath(service, account);
+ try {
+ await fs.unlink(file);
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+ throw err;
+ }
+ }
+ }
+}
+
+let singleton: SecretStore | undefined;
+
+export async function getSecretStore(): Promise {
+ if (!singleton) {
+ const keytar = await loadKeytar();
+ if (keytar) {
+ singleton = new KeytarSecretStore(keytar);
+ } else {
+ singleton = new FileSecretStore();
+ }
+ }
+ return singleton;
+}
+
+/**
+ * Reset the singleton instance (for testing purposes only)
+ * @internal
+ */
+export function resetSecretStore(): void {
+ singleton = undefined;
+}
diff --git a/packages/cli/templates/catalog-provider-module/.eslintrc.js.hbs b/packages/cli-module-actions/.eslintrc.js
similarity index 100%
rename from packages/cli/templates/catalog-provider-module/.eslintrc.js.hbs
rename to packages/cli-module-actions/.eslintrc.js
diff --git a/packages/cli-module-actions/CHANGELOG.md b/packages/cli-module-actions/CHANGELOG.md
new file mode 100644
index 0000000000..3305dddb37
--- /dev/null
+++ b/packages/cli-module-actions/CHANGELOG.md
@@ -0,0 +1,17 @@
+# @backstage/cli-module-actions
+
+## 0.0.2-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-node@0.3.1-next.0
+ - @backstage/errors@1.2.7
+
+## 0.0.1
+
+### Patch Changes
+
+- 42960f1: Added `actions` CLI module for listing and executing actions from the distributed actions registry. Includes `actions list`, `actions execute`, and `actions sources` commands for managing plugin sources.
+- Updated dependencies
+ - @backstage/cli-node@0.3.0
diff --git a/packages/cli-module-actions/bin/backstage-cli-module-actions b/packages/cli-module-actions/bin/backstage-cli-module-actions
new file mode 100755
index 0000000000..59f8267233
--- /dev/null
+++ b/packages/cli-module-actions/bin/backstage-cli-module-actions
@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/*
+ * Copyright 2025 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 path = require('node:path');
+
+/* eslint-disable-next-line no-restricted-syntax */
+const isLocal = require('node:fs').existsSync(
+ path.resolve(__dirname, '../src'),
+);
+
+if (isLocal) {
+ require('@backstage/cli-node/config/nodeTransform.cjs');
+}
+
+const { runCliModule } = require('@backstage/cli-node');
+const cliModule = require(isLocal ? '../src/index' : '..').default;
+const pkg = require('../package.json');
+runCliModule({ module: cliModule, name: pkg.name, version: pkg.version });
diff --git a/packages/cli-module-actions/catalog-info.yaml b/packages/cli-module-actions/catalog-info.yaml
new file mode 100644
index 0000000000..fd282ca6a3
--- /dev/null
+++ b/packages/cli-module-actions/catalog-info.yaml
@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: backstage-cli-module-actions
+ title: '@backstage/cli-module-actions'
+ description: CLI module for executing distributed actions
+spec:
+ lifecycle: experimental
+ type: backstage-cli-module
+ owner: tooling-maintainers
diff --git a/packages/cli-module-actions/cli-report.md b/packages/cli-module-actions/cli-report.md
new file mode 100644
index 0000000000..bbbab62b3f
--- /dev/null
+++ b/packages/cli-module-actions/cli-report.md
@@ -0,0 +1,94 @@
+## CLI Report file for "@backstage/cli-module-actions"
+
+> Do not edit this file. It is a report generated by `yarn build:api-reports`
+
+### `backstage-cli-module-actions`
+
+```
+Usage: @backstage/cli-module-actions [options] [command]
+
+Options:
+ -V, --version
+ -h, --help
+
+Commands:
+ actions [command]
+ help [command]
+```
+
+### `backstage-cli-module-actions actions`
+
+```
+Usage: @backstage/cli-module-actions actions [options] [command] [command]
+
+Options:
+ -h, --help
+
+Commands:
+ execute
+ help [command]
+ list
+ sources [command]
+```
+
+### `backstage-cli-module-actions actions execute`
+
+```
+Usage: @backstage/cli-module-actions actions execute
+
+Options:
+ --instance
+ -h, --help
+```
+
+### `backstage-cli-module-actions actions list`
+
+```
+Usage: @backstage/cli-module-actions actions list
+
+Options:
+ --instance
+ -h, --help
+```
+
+### `backstage-cli-module-actions actions sources`
+
+```
+Usage: @backstage/cli-module-actions actions sources [options] [command] [command]
+
+Options:
+ -h, --help
+
+Commands:
+ add
+ help [command]
+ list
+ remove
+```
+
+### `backstage-cli-module-actions actions sources add`
+
+```
+Usage: @backstage/cli-module-actions actions sources add
+
+Options:
+ -h, --help
+```
+
+### `backstage-cli-module-actions actions sources list`
+
+```
+Usage: @backstage/cli-module-actions actions sources list
+
+Options:
+ -h, --help
+```
+
+### `backstage-cli-module-actions actions sources remove`
+
+```
+Usage: @backstage/cli-module-actions actions sources remove
+
+Options:
+ -h, --help
+```
diff --git a/packages/cli-module-actions/package.json b/packages/cli-module-actions/package.json
new file mode 100644
index 0000000000..138eff06cf
--- /dev/null
+++ b/packages/cli-module-actions/package.json
@@ -0,0 +1,45 @@
+{
+ "name": "@backstage/cli-module-actions",
+ "version": "0.0.2-next.0",
+ "description": "CLI module for executing distributed actions",
+ "backstage": {
+ "role": "cli-module"
+ },
+ "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-module-actions"
+ },
+ "license": "Apache-2.0",
+ "main": "src/index.ts",
+ "types": "src/index.ts",
+ "files": [
+ "dist",
+ "bin"
+ ],
+ "bin": "bin/backstage-cli-module-actions",
+ "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/cli-node": "workspace:^",
+ "@backstage/errors": "workspace:^",
+ "cleye": "^2.3.0",
+ "zod": "^3.25.76 || ^4.0.0"
+ },
+ "devDependencies": {
+ "@backstage/backend-test-utils": "workspace:^",
+ "@backstage/cli": "workspace:^"
+ }
+}
diff --git a/packages/cli-module-actions/report.api.md b/packages/cli-module-actions/report.api.md
new file mode 100644
index 0000000000..180186482d
--- /dev/null
+++ b/packages/cli-module-actions/report.api.md
@@ -0,0 +1,13 @@
+## API Report File for "@backstage/cli-module-actions"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { CliModule } from '@backstage/cli-node';
+
+// @public (undocumented)
+const _default: CliModule;
+export default _default;
+
+// (No @packageDocumentation comment for this package)
+```
diff --git a/packages/cli-module-actions/src/commands/execute.ts b/packages/cli-module-actions/src/commands/execute.ts
new file mode 100644
index 0000000000..f130c597ce
--- /dev/null
+++ b/packages/cli-module-actions/src/commands/execute.ts
@@ -0,0 +1,109 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import type { CliCommandContext } from '@backstage/cli-node';
+import { ActionsClient } from '../lib/ActionsClient';
+import { schemaToFlags } from '../lib/schemaToFlags';
+import { resolveAuth } from '../lib/resolveAuth';
+
+export default async ({ args, info }: CliCommandContext) => {
+ if (args.includes('--help') || args.includes('-h')) {
+ cli(
+ {
+ help: info,
+ parameters: [''],
+ flags: {
+ instance: {
+ type: String,
+ description: 'Name of the instance to use',
+ },
+ },
+ },
+ undefined,
+ args,
+ );
+ return;
+ }
+
+ const instanceIdx = args.indexOf('--instance');
+ const instanceFlag = instanceIdx !== -1 ? args[instanceIdx + 1] : undefined;
+
+ // Skip flag names, flag values (the argument after a known flag), and
+ // the --instance value position so we only pick up positional arguments.
+ const skipIndices = new Set();
+ if (instanceIdx !== -1) {
+ skipIndices.add(instanceIdx);
+ skipIndices.add(instanceIdx + 1);
+ }
+
+ let actionId: string | undefined;
+ let actionIdIdx = -1;
+ for (let i = 0; i < args.length; i++) {
+ if (!skipIndices.has(i) && !args[i].startsWith('-')) {
+ actionId = args[i];
+ actionIdIdx = i;
+ break;
+ }
+ }
+
+ if (!actionId) {
+ process.stderr.write('Usage: actions execute [flags]\n');
+ process.exit(1);
+ }
+
+ const { accessToken, baseUrl } = await resolveAuth(instanceFlag);
+
+ const client = new ActionsClient(baseUrl, accessToken);
+ const actions = await client.listForPlugin(actionId);
+ const action = actions.find(a => a.id === actionId);
+
+ if (!action) {
+ throw new Error(
+ `Action "${actionId}" not found. Run "actions list" to see available actions.`,
+ );
+ }
+
+ const schemaFlags = schemaToFlags(action.schema.input as any);
+
+ const flagArgs = args.filter((_, i) => i !== actionIdIdx);
+
+ const { flags } = cli(
+ {
+ help: info,
+ flags: {
+ instance: {
+ type: String,
+ description: 'Name of the instance to use',
+ },
+ ...schemaFlags,
+ },
+ },
+ undefined,
+ flagArgs,
+ );
+
+ const allFlags = flags as Record;
+ const input: Record = {};
+ for (const [key, value] of Object.entries(allFlags)) {
+ if (key !== 'instance' && value !== undefined) {
+ input[key] = value;
+ }
+ }
+
+ const output = await client.execute(actionId, input);
+ process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+};
diff --git a/packages/cli-module-actions/src/commands/list.ts b/packages/cli-module-actions/src/commands/list.ts
new file mode 100644
index 0000000000..2049fc3e44
--- /dev/null
+++ b/packages/cli-module-actions/src/commands/list.ts
@@ -0,0 +1,62 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import type { CliCommandContext } from '@backstage/cli-node';
+import { ActionsClient } from '../lib/ActionsClient';
+import { resolveAuth } from '../lib/resolveAuth';
+
+export default async ({ args, info }: CliCommandContext) => {
+ const {
+ flags: { instance: instanceFlag },
+ } = cli(
+ {
+ help: info,
+ flags: {
+ instance: {
+ type: String,
+ description: 'Name of the instance to use',
+ },
+ },
+ },
+ undefined,
+ args,
+ );
+
+ const { accessToken, pluginSources, baseUrl } = await resolveAuth(
+ instanceFlag,
+ );
+
+ if (!pluginSources.length) {
+ process.stderr.write(
+ 'No plugin sources configured. Run "actions sources add " to add one.\n',
+ );
+ return;
+ }
+
+ const client = new ActionsClient(baseUrl, accessToken);
+ const actions = await client.list(pluginSources);
+
+ if (!actions.length) {
+ process.stderr.write('No actions found.\n');
+ return;
+ }
+
+ for (const action of actions) {
+ const desc = action.description ? ` - ${action.description}` : '';
+ process.stdout.write(`${action.id}${desc}\n`);
+ }
+};
diff --git a/packages/cli-module-actions/src/commands/sourcesAdd.ts b/packages/cli-module-actions/src/commands/sourcesAdd.ts
new file mode 100644
index 0000000000..fee3007637
--- /dev/null
+++ b/packages/cli-module-actions/src/commands/sourcesAdd.ts
@@ -0,0 +1,50 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import { CliAuth, type CliCommandContext } from '@backstage/cli-node';
+import { z } from 'zod/v3';
+
+const pluginSourcesSchema = z.array(z.string()).default([]);
+
+export default async ({ args, info }: CliCommandContext) => {
+ const parsed = cli(
+ {
+ help: info,
+ parameters: [''],
+ },
+ undefined,
+ args,
+ );
+
+ const pluginId = parsed._[0];
+
+ const auth = await CliAuth.create();
+ const existing = pluginSourcesSchema.parse(
+ await auth.getMetadata('pluginSources'),
+ );
+
+ if (existing.includes(pluginId)) {
+ process.stderr.write(
+ `Plugin source "${pluginId}" is already configured.\n`,
+ );
+ return;
+ }
+
+ await auth.setMetadata('pluginSources', [...existing, pluginId]);
+
+ process.stdout.write(`Added plugin source "${pluginId}".\n`);
+};
diff --git a/packages/cli-module-actions/src/commands/sourcesList.ts b/packages/cli-module-actions/src/commands/sourcesList.ts
new file mode 100644
index 0000000000..7557922c06
--- /dev/null
+++ b/packages/cli-module-actions/src/commands/sourcesList.ts
@@ -0,0 +1,39 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import { CliAuth, type CliCommandContext } from '@backstage/cli-node';
+import { z } from 'zod/v3';
+
+const pluginSourcesSchema = z.array(z.string()).default([]);
+
+export default async ({ args, info }: CliCommandContext) => {
+ cli({ help: info }, undefined, args);
+
+ const auth = await CliAuth.create();
+ const sources = pluginSourcesSchema.parse(
+ await auth.getMetadata('pluginSources'),
+ );
+
+ if (!sources.length) {
+ process.stderr.write('No plugin sources configured.\n');
+ return;
+ }
+
+ for (const source of sources) {
+ process.stdout.write(`${source}\n`);
+ }
+};
diff --git a/packages/cli-module-actions/src/commands/sourcesRemove.ts b/packages/cli-module-actions/src/commands/sourcesRemove.ts
new file mode 100644
index 0000000000..9225228503
--- /dev/null
+++ b/packages/cli-module-actions/src/commands/sourcesRemove.ts
@@ -0,0 +1,51 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import { CliAuth, type CliCommandContext } from '@backstage/cli-node';
+import { z } from 'zod/v3';
+
+const pluginSourcesSchema = z.array(z.string()).default([]);
+
+export default async ({ args, info }: CliCommandContext) => {
+ const parsed = cli(
+ {
+ help: info,
+ parameters: [''],
+ },
+ undefined,
+ args,
+ );
+
+ const pluginId = parsed._[0];
+
+ const auth = await CliAuth.create();
+ const existing = pluginSourcesSchema.parse(
+ await auth.getMetadata('pluginSources'),
+ );
+
+ if (!existing.includes(pluginId)) {
+ process.stderr.write(`Plugin source "${pluginId}" is not configured.\n`);
+ return;
+ }
+
+ await auth.setMetadata(
+ 'pluginSources',
+ existing.filter(s => s !== pluginId),
+ );
+
+ process.stdout.write(`Removed plugin source "${pluginId}".\n`);
+};
diff --git a/packages/cli-module-actions/src/index.ts b/packages/cli-module-actions/src/index.ts
new file mode 100644
index 0000000000..57b2d741e3
--- /dev/null
+++ b/packages/cli-module-actions/src/index.ts
@@ -0,0 +1,49 @@
+/*
+ * Copyright 2025 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 { createCliModule } from '@backstage/cli-node';
+import packageJson from '../package.json';
+
+export default createCliModule({
+ packageJson,
+ init: async reg => {
+ reg.addCommand({
+ path: ['actions', 'list'],
+ description: 'List available actions from configured plugin sources',
+ execute: { loader: () => import('./commands/list') },
+ });
+ reg.addCommand({
+ path: ['actions', 'execute'],
+ description: 'Execute an action',
+ execute: { loader: () => import('./commands/execute') },
+ });
+ reg.addCommand({
+ path: ['actions', 'sources', 'add'],
+ description: 'Add a plugin source for action discovery',
+ execute: { loader: () => import('./commands/sourcesAdd') },
+ });
+ reg.addCommand({
+ path: ['actions', 'sources', 'list'],
+ description: 'List configured plugin sources',
+ execute: { loader: () => import('./commands/sourcesList') },
+ });
+ reg.addCommand({
+ path: ['actions', 'sources', 'remove'],
+ description: 'Remove a plugin source',
+ execute: { loader: () => import('./commands/sourcesRemove') },
+ });
+ },
+});
diff --git a/packages/cli-module-actions/src/lib/ActionsClient.test.ts b/packages/cli-module-actions/src/lib/ActionsClient.test.ts
new file mode 100644
index 0000000000..3aa2e06dc7
--- /dev/null
+++ b/packages/cli-module-actions/src/lib/ActionsClient.test.ts
@@ -0,0 +1,129 @@
+/*
+ * Copyright 2025 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 { ActionsClient } from './ActionsClient';
+import { httpJson } from './httpJson';
+
+jest.mock('./httpJson', () => ({
+ httpJson: jest.fn(),
+}));
+
+const mockHttpJson = httpJson as jest.MockedFunction;
+
+describe('ActionsClient', () => {
+ const baseUrl = 'https://backstage.example.com';
+ const accessToken = 'test-token';
+ let client: ActionsClient;
+
+ beforeEach(() => {
+ jest.clearAllMocks();
+ client = new ActionsClient(baseUrl, accessToken);
+ });
+
+ describe('list', () => {
+ it('returns empty array when no plugin sources provided', async () => {
+ const result = await client.list([]);
+ expect(result).toEqual([]);
+ expect(mockHttpJson).not.toHaveBeenCalled();
+ });
+
+ it('fetches actions from each plugin source', async () => {
+ const catalogActions = [
+ {
+ id: 'catalog:refresh',
+ name: 'refresh',
+ schema: { input: {}, output: {} },
+ },
+ ];
+ const scaffolderActions = [
+ {
+ id: 'scaffolder:run',
+ name: 'run',
+ schema: { input: {}, output: {} },
+ },
+ ];
+
+ mockHttpJson
+ .mockResolvedValueOnce({ actions: catalogActions })
+ .mockResolvedValueOnce({ actions: scaffolderActions });
+
+ const result = await client.list(['catalog', 'scaffolder']);
+
+ expect(mockHttpJson).toHaveBeenCalledTimes(2);
+ expect(mockHttpJson).toHaveBeenCalledWith(
+ 'https://backstage.example.com/api/catalog/.backstage/actions/v1/actions',
+ expect.objectContaining({
+ headers: { Authorization: 'Bearer test-token' },
+ }),
+ );
+ expect(mockHttpJson).toHaveBeenCalledWith(
+ 'https://backstage.example.com/api/scaffolder/.backstage/actions/v1/actions',
+ expect.objectContaining({
+ headers: { Authorization: 'Bearer test-token' },
+ }),
+ );
+ expect(result).toEqual([...catalogActions, ...scaffolderActions]);
+ });
+
+ it('propagates errors from httpJson', async () => {
+ mockHttpJson.mockRejectedValue(new Error('Network error'));
+
+ await expect(client.list(['catalog'])).rejects.toThrow('Network error');
+ });
+ });
+
+ describe('execute', () => {
+ it('posts to the correct invoke endpoint', async () => {
+ mockHttpJson.mockResolvedValue({ output: { result: 'ok' } });
+
+ const output = await client.execute('catalog:refresh', {
+ entityRef: 'component:default/foo',
+ });
+
+ expect(mockHttpJson).toHaveBeenCalledWith(
+ 'https://backstage.example.com/api/catalog/.backstage/actions/v1/actions/catalog%3Arefresh/invoke',
+ expect.objectContaining({
+ method: 'POST',
+ headers: { Authorization: 'Bearer test-token' },
+ body: { entityRef: 'component:default/foo' },
+ }),
+ );
+ expect(output).toEqual({ result: 'ok' });
+ });
+
+ it('sends empty object when no input provided', async () => {
+ mockHttpJson.mockResolvedValue({ output: null });
+
+ await client.execute('catalog:refresh');
+
+ expect(mockHttpJson).toHaveBeenCalledWith(
+ expect.any(String),
+ expect.objectContaining({ body: {} }),
+ );
+ });
+
+ it('extracts pluginId from actionId to build correct URL', async () => {
+ mockHttpJson.mockResolvedValue({ output: {} });
+
+ await client.execute('my-plugin:some-action');
+
+ expect(mockHttpJson).toHaveBeenCalledWith(
+ expect.stringContaining('/api/my-plugin/'),
+ expect.any(Object),
+ );
+ });
+ });
+});
diff --git a/packages/cli-module-actions/src/lib/ActionsClient.ts b/packages/cli-module-actions/src/lib/ActionsClient.ts
new file mode 100644
index 0000000000..736a3b7f37
--- /dev/null
+++ b/packages/cli-module-actions/src/lib/ActionsClient.ts
@@ -0,0 +1,98 @@
+/*
+ * Copyright 2025 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 { httpJson } from './httpJson';
+
+export type ActionDef = {
+ id: string;
+ name: string;
+ description?: string;
+ schema: {
+ input: object;
+ output: object;
+ };
+};
+
+type ListActionsResponse = {
+ actions: ActionDef[];
+};
+
+type InvokeResponse = {
+ output: unknown;
+};
+
+function extractPluginId(actionId: string): string {
+ const colonIndex = actionId.indexOf(':');
+ if (colonIndex === -1) {
+ throw new Error(
+ `Invalid action ID "${actionId}". Expected format "pluginId:actionName".`,
+ );
+ }
+ return actionId.substring(0, colonIndex);
+}
+
+function pluginActionsUrl(baseUrl: string, pluginId: string): string {
+ return new URL(
+ `/api/${encodeURIComponent(pluginId)}/.backstage/actions/v1/actions`,
+ baseUrl,
+ ).toString();
+}
+
+export class ActionsClient {
+ constructor(
+ private readonly baseUrl: string,
+ private readonly accessToken: string,
+ ) {}
+
+ async list(pluginSources: string[]): Promise {
+ const results: ActionDef[] = [];
+
+ for (const pluginId of pluginSources) {
+ const url = pluginActionsUrl(this.baseUrl, pluginId);
+
+ const response = await httpJson(url, {
+ headers: { Authorization: `Bearer ${this.accessToken}` },
+ signal: AbortSignal.timeout(30_000),
+ });
+
+ results.push(...response.actions);
+ }
+
+ return results;
+ }
+
+ async listForPlugin(actionId: string): Promise {
+ const pluginId = extractPluginId(actionId);
+ return this.list([pluginId]);
+ }
+
+ async execute(actionId: string, input?: unknown): Promise {
+ const pluginId = extractPluginId(actionId);
+ const url = `${pluginActionsUrl(
+ this.baseUrl,
+ pluginId,
+ )}/${encodeURIComponent(actionId)}/invoke`;
+
+ const response = await httpJson(url, {
+ method: 'POST',
+ headers: { Authorization: `Bearer ${this.accessToken}` },
+ body: input ?? {},
+ signal: AbortSignal.timeout(30_000),
+ });
+
+ return response.output;
+ }
+}
diff --git a/packages/ui/src/components/HeaderPage/types.ts b/packages/cli-module-actions/src/lib/httpJson.ts
similarity index 51%
rename from packages/ui/src/components/HeaderPage/types.ts
rename to packages/cli-module-actions/src/lib/httpJson.ts
index b603cb7084..0bea9dab94 100644
--- a/packages/ui/src/components/HeaderPage/types.ts
+++ b/packages/cli-module-actions/src/lib/httpJson.ts
@@ -14,34 +14,26 @@
* limitations under the License.
*/
-import type { HeaderTab } from '../PluginHeader/types';
+import { ResponseError } from '@backstage/errors';
-/**
- * Own props for the HeaderPage component.
- *
- * @public
- */
-export interface HeaderPageOwnProps {
- title?: string;
- customActions?: React.ReactNode;
- tabs?: HeaderTab[];
- breadcrumbs?: HeaderPageBreadcrumb[];
- className?: string;
-}
-
-/**
- * Props for the main HeaderPage component.
- *
- * @public
- */
-export interface HeaderPageProps extends HeaderPageOwnProps {}
-
-/**
- * Represents a breadcrumb item in the header.
- *
- * @public
- */
-export interface HeaderPageBreadcrumb {
- label: string;
- href: string;
+type HttpInit = {
+ headers?: Record;
+ method?: string;
+ body?: any;
+ signal?: AbortSignal;
+};
+
+export async function httpJson(url: string, init?: HttpInit): Promise {
+ const res = await fetch(url, {
+ ...init,
+ body: init?.body ? JSON.stringify(init.body) : undefined,
+ headers: {
+ ...(init?.body ? { 'Content-Type': 'application/json' } : {}),
+ ...init?.headers,
+ },
+ });
+ if (!res.ok) {
+ throw await ResponseError.fromResponse(res);
+ }
+ return (await res.json()) as T;
}
diff --git a/packages/cli-module-actions/src/lib/resolveAuth.test.ts b/packages/cli-module-actions/src/lib/resolveAuth.test.ts
new file mode 100644
index 0000000000..2aabefe9ea
--- /dev/null
+++ b/packages/cli-module-actions/src/lib/resolveAuth.test.ts
@@ -0,0 +1,96 @@
+/*
+ * Copyright 2025 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 { resolveAuth } from './resolveAuth';
+import { CliAuth } from '@backstage/cli-node';
+
+jest.mock('@backstage/cli-node', () => {
+ const actual = jest.requireActual('@backstage/cli-node');
+ return {
+ ...actual,
+ CliAuth: { create: jest.fn() },
+ };
+});
+
+const mockCreate = CliAuth.create as jest.MockedFunction;
+
+describe('resolveAuth', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it('resolves auth with the selected instance and stored token', async () => {
+ mockCreate.mockResolvedValue({
+ getInstanceName: jest.fn().mockReturnValue('production'),
+ getBaseUrl: jest.fn().mockReturnValue('https://backstage.example.com'),
+ getAccessToken: jest.fn().mockResolvedValue('test-access-token'),
+ getMetadata: jest.fn().mockResolvedValue(['catalog', 'scaffolder']),
+ } as unknown as CliAuth);
+
+ const result = await resolveAuth();
+
+ expect(mockCreate).toHaveBeenCalledWith({ instanceName: undefined });
+ expect(result).toEqual({
+ baseUrl: 'https://backstage.example.com',
+ instanceName: 'production',
+ accessToken: 'test-access-token',
+ pluginSources: ['catalog', 'scaffolder'],
+ });
+ });
+
+ it('passes instance name flag to CliAuth.create', async () => {
+ mockCreate.mockResolvedValue({
+ getInstanceName: jest.fn().mockReturnValue('staging'),
+ getBaseUrl: jest.fn().mockReturnValue('https://staging.example.com'),
+ getAccessToken: jest.fn().mockResolvedValue('test-access-token'),
+ getMetadata: jest.fn().mockResolvedValue([]),
+ } as unknown as CliAuth);
+
+ await resolveAuth('staging');
+
+ expect(mockCreate).toHaveBeenCalledWith({ instanceName: 'staging' });
+ });
+
+ it('throws when getAccessToken fails', async () => {
+ mockCreate.mockResolvedValue({
+ getInstanceName: jest.fn().mockReturnValue('production'),
+ getBaseUrl: jest.fn().mockReturnValue('https://backstage.example.com'),
+ getAccessToken: jest
+ .fn()
+ .mockRejectedValue(
+ new Error('No access token found. Run "auth login" to authenticate.'),
+ ),
+ getMetadata: jest.fn().mockResolvedValue([]),
+ } as unknown as CliAuth);
+
+ await expect(resolveAuth()).rejects.toThrow(
+ 'No access token found. Run "auth login" to authenticate.',
+ );
+ });
+
+ it('returns empty plugin sources when none are configured', async () => {
+ mockCreate.mockResolvedValue({
+ getInstanceName: jest.fn().mockReturnValue('production'),
+ getBaseUrl: jest.fn().mockReturnValue('https://backstage.example.com'),
+ getAccessToken: jest.fn().mockResolvedValue('test-access-token'),
+ getMetadata: jest.fn().mockResolvedValue(undefined),
+ } as unknown as CliAuth);
+
+ const result = await resolveAuth();
+
+ expect(result.pluginSources).toEqual([]);
+ });
+});
diff --git a/packages/cli-module-actions/src/lib/resolveAuth.ts b/packages/cli-module-actions/src/lib/resolveAuth.ts
new file mode 100644
index 0000000000..568bd4cdcd
--- /dev/null
+++ b/packages/cli-module-actions/src/lib/resolveAuth.ts
@@ -0,0 +1,40 @@
+/*
+ * Copyright 2025 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 { CliAuth } from '@backstage/cli-node';
+import { z } from 'zod/v3';
+
+const pluginSourcesSchema = z.array(z.string()).default([]);
+
+export async function resolveAuth(instanceFlag?: string): Promise<{
+ baseUrl: string;
+ instanceName: string;
+ accessToken: string;
+ pluginSources: string[];
+}> {
+ const auth = await CliAuth.create({ instanceName: instanceFlag });
+ const accessToken = await auth.getAccessToken();
+ const pluginSources = pluginSourcesSchema.parse(
+ await auth.getMetadata('pluginSources'),
+ );
+
+ return {
+ baseUrl: auth.getBaseUrl(),
+ instanceName: auth.getInstanceName(),
+ accessToken,
+ pluginSources,
+ };
+}
diff --git a/packages/cli-module-actions/src/lib/schemaToFlags.test.ts b/packages/cli-module-actions/src/lib/schemaToFlags.test.ts
new file mode 100644
index 0000000000..fa9f446aae
--- /dev/null
+++ b/packages/cli-module-actions/src/lib/schemaToFlags.test.ts
@@ -0,0 +1,163 @@
+/*
+ * Copyright 2025 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 { schemaToFlags } from './schemaToFlags';
+
+describe('schemaToFlags', () => {
+ it('returns empty object when schema has no properties', () => {
+ expect(schemaToFlags({})).toEqual({});
+ expect(schemaToFlags({ properties: {} })).toEqual({});
+ });
+
+ it('converts string properties to String flags', () => {
+ const flags = schemaToFlags({
+ properties: {
+ myProp: { type: 'string', description: 'A string prop' },
+ },
+ });
+
+ expect(flags).toEqual({
+ myProp: { type: String, description: 'A string prop' },
+ });
+ });
+
+ it('converts number and integer properties to Number flags', () => {
+ const flags = schemaToFlags({
+ properties: {
+ count: { type: 'integer' },
+ amount: { type: 'number', description: 'An amount' },
+ },
+ });
+
+ expect(flags.count).toEqual({ type: Number, description: undefined });
+ expect(flags.amount).toEqual({ type: Number, description: 'An amount' });
+ });
+
+ it('converts boolean properties to Boolean flags', () => {
+ const flags = schemaToFlags({
+ properties: {
+ verbose: { type: 'boolean', description: 'Enable verbose output' },
+ },
+ });
+
+ expect(flags.verbose).toEqual({
+ type: Boolean,
+ description: 'Enable verbose output',
+ });
+ });
+
+ it('skips non-primitive properties like object and array', () => {
+ const flags = schemaToFlags({
+ properties: {
+ name: { type: 'string' },
+ metadata: { type: 'object' },
+ tags: { type: 'array' },
+ },
+ });
+
+ expect(Object.keys(flags)).toEqual(['name']);
+ });
+
+ it('skips properties with no type or composite types', () => {
+ const flags = schemaToFlags({
+ properties: {
+ noType: {},
+ name: { type: 'string' },
+ },
+ });
+
+ expect(Object.keys(flags)).toEqual(['name']);
+ });
+
+ it('uses first type when type is an array', () => {
+ const flags = schemaToFlags({
+ properties: {
+ value: { type: ['string', 'null'] },
+ },
+ });
+
+ expect(flags.value).toEqual({ type: String, description: undefined });
+ });
+
+ it('appends enum values to description', () => {
+ const flags = schemaToFlags({
+ properties: {
+ color: {
+ type: 'string',
+ description: 'Pick a color',
+ enum: ['red', 'green', 'blue'],
+ },
+ bare: { type: 'string', enum: ['a', 'b'] },
+ },
+ });
+
+ expect(flags.color.description).toBe('Pick a color [red, green, blue]');
+ expect(flags.bare.description).toBe('[a, b]');
+ });
+
+ it('marks required fields in description', () => {
+ const flags = schemaToFlags({
+ properties: {
+ name: { type: 'string', description: 'The name' },
+ optional: { type: 'string', description: 'Optional field' },
+ bare: { type: 'string' },
+ },
+ required: ['name', 'bare'],
+ });
+
+ expect(flags.name.description).toBe('The name (required)');
+ expect(flags.optional.description).toBe('Optional field');
+ expect(flags.bare.description).toBe('(required)');
+ });
+
+ it('applies default values from schema', () => {
+ const flags = schemaToFlags({
+ properties: {
+ count: { type: 'number', default: 10 },
+ name: { type: 'string' },
+ },
+ });
+
+ expect(flags.count.default).toBe(10);
+ expect(flags.name.default).toBeUndefined();
+ });
+
+ it('combines enum and required in description', () => {
+ const flags = schemaToFlags({
+ properties: {
+ env: {
+ type: 'string',
+ description: 'Target env',
+ enum: ['dev', 'prod'],
+ },
+ },
+ required: ['env'],
+ });
+
+ expect(flags.env.description).toBe('Target env [dev, prod] (required)');
+ });
+
+ it('preserves camelCase property names as flag keys', () => {
+ const flags = schemaToFlags({
+ properties: {
+ targetEntityRef: { type: 'string' },
+ maxResults: { type: 'integer' },
+ },
+ });
+
+ expect(Object.keys(flags)).toEqual(['targetEntityRef', 'maxResults']);
+ });
+});
diff --git a/packages/cli-module-actions/src/lib/schemaToFlags.ts b/packages/cli-module-actions/src/lib/schemaToFlags.ts
new file mode 100644
index 0000000000..026613edaf
--- /dev/null
+++ b/packages/cli-module-actions/src/lib/schemaToFlags.ts
@@ -0,0 +1,77 @@
+/*
+ * Copyright 2025 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.
+ */
+
+type JsonSchemaProperty = {
+ type?: string | string[];
+ description?: string;
+ enum?: unknown[];
+ default?: unknown;
+};
+
+type JsonSchemaObject = {
+ properties?: Record;
+ required?: string[];
+};
+
+type CleyeFlag = {
+ type: StringConstructor | NumberConstructor | BooleanConstructor;
+ description?: string;
+ default?: unknown;
+};
+
+export function schemaToFlags(
+ schema: JsonSchemaObject,
+): Record {
+ const flags: Record = {};
+ const required = new Set(schema.required ?? []);
+
+ if (!schema.properties) {
+ return flags;
+ }
+
+ for (const [key, prop] of Object.entries(schema.properties)) {
+ const rawType = Array.isArray(prop.type) ? prop.type[0] : prop.type;
+
+ let flagType: StringConstructor | NumberConstructor | BooleanConstructor;
+ if (rawType === 'string') {
+ flagType = String;
+ } else if (rawType === 'number' || rawType === 'integer') {
+ flagType = Number;
+ } else if (rawType === 'boolean') {
+ flagType = Boolean;
+ } else {
+ continue;
+ }
+
+ let desc = prop.description ?? '';
+ if (prop.enum?.length) {
+ const values = prop.enum.map(v => String(v)).join(', ');
+ desc = desc ? `${desc} [${values}]` : `[${values}]`;
+ }
+ if (required.has(key)) {
+ desc = desc ? `${desc} (required)` : '(required)';
+ }
+
+ const flag: CleyeFlag = { type: flagType, description: desc || undefined };
+ if (prop.default !== undefined) {
+ flag.default = prop.default;
+ }
+
+ flags[key] = flag;
+ }
+
+ return flags;
+}
diff --git a/packages/cli/templates/frontend-plugin/.eslintrc.js.hbs b/packages/cli-module-auth/.eslintrc.js
similarity index 100%
rename from packages/cli/templates/frontend-plugin/.eslintrc.js.hbs
rename to packages/cli-module-auth/.eslintrc.js
diff --git a/packages/cli-module-auth/CHANGELOG.md b/packages/cli-module-auth/CHANGELOG.md
new file mode 100644
index 0000000000..f2473fb4b6
--- /dev/null
+++ b/packages/cli-module-auth/CHANGELOG.md
@@ -0,0 +1,27 @@
+# @backstage/cli-module-auth
+
+## 0.1.1-next.1
+
+### Patch Changes
+
+- 2e5c5f8: Bumped `glob` dependency from v7/v8/v11 to v13 to address security vulnerabilities in older versions. Bumped `rollup` from v4.27 to v4.59+ to fix a high severity path traversal vulnerability (GHSA-mw96-cpmx-2vgc).
+
+## 0.1.1-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-node@0.3.1-next.0
+ - @backstage/errors@1.2.7
+
+## 0.1.0
+
+### Minor Changes
+
+- 329f394: Initial release of the CLI module packages. Each module provides a set of commands that can be discovered automatically by `@backstage/cli` or executed standalone.
+
+### Patch Changes
+
+- a49a40d: Updated dependency `zod` to `^3.25.76 || ^4.0.0` & migrated to `/v3` or `/v4` imports.
+- Updated dependencies
+ - @backstage/cli-node@0.3.0
diff --git a/packages/cli-module-auth/README.md b/packages/cli-module-auth/README.md
new file mode 100644
index 0000000000..2a98761ac3
--- /dev/null
+++ b/packages/cli-module-auth/README.md
@@ -0,0 +1,19 @@
+# @backstage/cli-module-auth
+
+CLI module that provides authentication commands for the Backstage CLI, enabling login, logout, and credential management for Backstage instances.
+
+## Commands
+
+| Command | Description |
+| :----------------- | :------------------------------------------------------- |
+| `auth login` | Log in the CLI to a Backstage instance |
+| `auth logout` | Log out the CLI and clear stored credentials |
+| `auth show` | Show details of an authenticated instance |
+| `auth list` | List authenticated instances |
+| `auth print-token` | Print an access token to stdout (auto-refresh if needed) |
+| `auth select` | Select the default instance |
+
+## Documentation
+
+- [Backstage Readme](https://github.com/backstage/backstage/blob/master/README.md)
+- [Backstage Documentation](https://backstage.io/docs)
diff --git a/plugins/catalog-unprocessed-entities/src/alpha/devToolsContent.tsx b/packages/cli-module-auth/bin/backstage-cli-module-auth
old mode 100644
new mode 100755
similarity index 54%
rename from plugins/catalog-unprocessed-entities/src/alpha/devToolsContent.tsx
rename to packages/cli-module-auth/bin/backstage-cli-module-auth
index 3dcdc0ad6b..68bdc76a4a
--- a/plugins/catalog-unprocessed-entities/src/alpha/devToolsContent.tsx
+++ b/packages/cli-module-auth/bin/backstage-cli-module-auth
@@ -1,3 +1,4 @@
+#!/usr/bin/env node
/*
* Copyright 2024 The Backstage Authors
*
@@ -14,23 +15,18 @@
* limitations under the License.
*/
-import { DevToolsContentBlueprint } from '@backstage/plugin-devtools-react';
+const path = require('node:path');
-/**
- * DevTools content for catalog unprocessed entities.
- *
- * @alpha
- */
-export const unprocessedEntitiesDevToolsContent = DevToolsContentBlueprint.make(
- {
- disabled: true,
- params: {
- path: 'unprocessed-entities',
- title: 'Unprocessed Entities',
- loader: () =>
- import('../components/UnprocessedEntities').then(m => (
-
- )),
- },
- },
+/* eslint-disable-next-line no-restricted-syntax */
+const isLocal = require('node:fs').existsSync(
+ path.resolve(__dirname, '../src'),
);
+
+if (isLocal) {
+ require('@backstage/cli-node/config/nodeTransform.cjs');
+}
+
+const { runCliModule } = require('@backstage/cli-node');
+const cliModule = require(isLocal ? '../src/index' : '..').default;
+const pkg = require('../package.json');
+runCliModule({ module: cliModule, name: pkg.name, version: pkg.version });
diff --git a/packages/cli-module-auth/catalog-info.yaml b/packages/cli-module-auth/catalog-info.yaml
new file mode 100644
index 0000000000..091bcad199
--- /dev/null
+++ b/packages/cli-module-auth/catalog-info.yaml
@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: backstage-cli-module-auth
+ title: '@backstage/cli-module-auth'
+ description: CLI module for Backstage CLI
+spec:
+ lifecycle: experimental
+ type: backstage-cli-module
+ owner: tooling-maintainers
diff --git a/packages/cli-module-auth/cli-report.md b/packages/cli-module-auth/cli-report.md
new file mode 100644
index 0000000000..8b4c98766f
--- /dev/null
+++ b/packages/cli-module-auth/cli-report.md
@@ -0,0 +1,96 @@
+## CLI Report file for "@backstage/cli-module-auth"
+
+> Do not edit this file. It is a report generated by `yarn build:api-reports`
+
+### `backstage-cli-module-auth`
+
+```
+Usage: @backstage/cli-module-auth [options] [command]
+
+Options:
+ -V, --version
+ -h, --help
+
+Commands:
+ auth [command]
+ help [command]
+```
+
+### `backstage-cli-module-auth auth`
+
+```
+Usage: @backstage/cli-module-auth auth [options] [command] [command]
+
+Options:
+ -h, --help
+
+Commands:
+ help [command]
+ list
+ login
+ logout
+ print-token
+ select
+ show
+```
+
+### `backstage-cli-module-auth auth list`
+
+```
+Usage: @backstage/cli-module-auth auth list
+
+Options:
+ -h, --help
+```
+
+### `backstage-cli-module-auth auth login`
+
+```
+Usage: @backstage/cli-module-auth auth login
+
+Options:
+ --backend-url
+ --instance
+ --no-browser
+ -h, --help
+```
+
+### `backstage-cli-module-auth auth logout`
+
+```
+Usage: @backstage/cli-module-auth auth logout
+
+Options:
+ --instance
+ -h, --help
+```
+
+### `backstage-cli-module-auth auth print-token`
+
+```
+Usage: @backstage/cli-module-auth auth print-token
+
+Options:
+ --instance
+ -h, --help
+```
+
+### `backstage-cli-module-auth auth select`
+
+```
+Usage: @backstage/cli-module-auth auth select
+
+Options:
+ --instance
+ -h, --help
+```
+
+### `backstage-cli-module-auth auth show`
+
+```
+Usage: @backstage/cli-module-auth auth show
+
+Options:
+ --instance
+ -h, --help
+```
diff --git a/packages/cli-module-auth/package.json b/packages/cli-module-auth/package.json
new file mode 100644
index 0000000000..e1f0200d63
--- /dev/null
+++ b/packages/cli-module-auth/package.json
@@ -0,0 +1,55 @@
+{
+ "name": "@backstage/cli-module-auth",
+ "version": "0.1.1-next.1",
+ "description": "CLI module for Backstage CLI",
+ "backstage": {
+ "role": "cli-module"
+ },
+ "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-module-auth"
+ },
+ "license": "Apache-2.0",
+ "main": "src/index.ts",
+ "types": "src/index.ts",
+ "bin": "bin/backstage-cli-module-auth",
+ "files": [
+ "dist",
+ "bin"
+ ],
+ "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/cli-node": "workspace:^",
+ "@backstage/errors": "workspace:^",
+ "cleye": "^2.3.0",
+ "fs-extra": "^11.2.0",
+ "glob": "^13.0.0",
+ "inquirer": "^8.2.0",
+ "proper-lockfile": "^4.1.2",
+ "yaml": "^2.0.0",
+ "zod": "^3.25.76"
+ },
+ "devDependencies": {
+ "@backstage/backend-test-utils": "workspace:^",
+ "@backstage/cli": "workspace:^",
+ "@types/fs-extra": "^11.0.0",
+ "@types/proper-lockfile": "^4"
+ },
+ "optionalDependencies": {
+ "keytar": "^7.9.0"
+ }
+}
diff --git a/packages/cli-module-auth/report.api.md b/packages/cli-module-auth/report.api.md
new file mode 100644
index 0000000000..510bcaabe7
--- /dev/null
+++ b/packages/cli-module-auth/report.api.md
@@ -0,0 +1,13 @@
+## API Report File for "@backstage/cli-module-auth"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { CliModule } from '@backstage/cli-node';
+
+// @public (undocumented)
+const _default: CliModule;
+export default _default;
+
+// (No @packageDocumentation comment for this package)
+```
diff --git a/packages/cli-module-auth/src/commands/list.ts b/packages/cli-module-auth/src/commands/list.ts
new file mode 100644
index 0000000000..3da2118800
--- /dev/null
+++ b/packages/cli-module-auth/src/commands/list.ts
@@ -0,0 +1,33 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import type { CliCommandContext } from '@backstage/cli-node';
+import { getAllInstances } from '../lib/storage';
+
+export default async ({ args, info }: CliCommandContext) => {
+ cli({ help: info }, undefined, args);
+
+ const { instances, selected } = await getAllInstances();
+ if (!instances.length) {
+ process.stderr.write('No instances found\n');
+ return;
+ }
+ for (const inst of instances) {
+ const mark = inst.name === selected?.name ? '* ' : ' ';
+ process.stdout.write(`${mark}${inst.name} - ${inst.baseUrl}\n`);
+ }
+};
diff --git a/packages/cli-module-auth/src/commands/login.ts b/packages/cli-module-auth/src/commands/login.ts
new file mode 100644
index 0000000000..5320bae726
--- /dev/null
+++ b/packages/cli-module-auth/src/commands/login.ts
@@ -0,0 +1,383 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import type { CliCommandContext } from '@backstage/cli-node';
+import { startCallbackServer } from '../lib/localServer';
+import { spawn } from 'node:child_process';
+import { challengeFromVerifier, generateVerifier } from '../lib/pkce';
+import { httpJson } from '../lib/http';
+import {
+ upsertInstance,
+ withMetadataLock,
+ getAllInstances,
+ getInstanceByName,
+ StoredInstance,
+} from '../lib/storage';
+import { getSecretStore, getAuthInstanceService } from '@internal/cli';
+import crypto from 'node:crypto';
+import fs from 'fs-extra';
+import path from 'node:path';
+import { globSync } from 'glob';
+import YAML from 'yaml';
+import inquirer from 'inquirer';
+
+const TOKEN_EXCHANGE_TIMEOUT_MS = 30_000;
+
+export default async ({ args, info }: CliCommandContext) => {
+ const {
+ flags: { backendUrl, noBrowser, instance: instanceFlag },
+ } = cli(
+ {
+ help: info,
+ flags: {
+ backendUrl: { type: String, description: 'Backend base URL' },
+ noBrowser: {
+ type: Boolean,
+ description: 'Do not open browser automatically',
+ },
+ instance: {
+ type: String,
+ description: 'Name for this instance (used by other auth commands)',
+ },
+ },
+ },
+ undefined,
+ args,
+ );
+
+ const { instances, selected } = await getAllInstances();
+
+ let backendBaseUrl: string;
+ let instanceName: string;
+
+ if (instanceFlag) {
+ instanceName = instanceFlag;
+ const targetInstance = instances.find(i => i.name === instanceFlag);
+ if (targetInstance) {
+ backendBaseUrl = normalizeUrl(backendUrl) ?? targetInstance.baseUrl;
+ } else {
+ backendBaseUrl = normalizeUrl(backendUrl) ?? (await pickBaseUrl());
+ }
+ } else if (backendUrl) {
+ backendBaseUrl = normalizeUrl(backendUrl);
+ instanceName = deriveInstanceName(backendBaseUrl);
+ } else if (instances.length > 0) {
+ const choice = await promptForInstance(instances, selected);
+ if (choice === '__new__') {
+ backendBaseUrl = await pickBaseUrl();
+ instanceName = deriveInstanceName(backendBaseUrl);
+ } else {
+ const targetInstance = instances.find(i => i.name === choice);
+ if (!targetInstance) {
+ throw new Error('Instance not found');
+ }
+ backendBaseUrl = targetInstance.baseUrl;
+ instanceName = targetInstance.name;
+ }
+ } else {
+ backendBaseUrl = await pickBaseUrl();
+ instanceName = deriveInstanceName(backendBaseUrl);
+ }
+
+ const authBaseUrl = `${backendBaseUrl}/api/auth`;
+ const clientId = `${authBaseUrl}/.well-known/oauth-client/cli.json`;
+
+ const metadataResponse = await fetch(clientId, {
+ signal: AbortSignal.timeout(30_000),
+ });
+ if (!metadataResponse.ok) {
+ throw new Error(
+ `Server does not support CLI authentication. Ensure CIMD is enabled on the backend.`,
+ );
+ }
+
+ const { verifier, challenge, state } = createPkceState();
+ const callback = await startCallbackServer({ state });
+
+ try {
+ const authorizeUrl = buildAuthorizeUrl({
+ authBaseUrl,
+ clientId,
+ redirectUri: callback.url,
+ state,
+ challenge,
+ });
+
+ await openBrowserOrPrint(authorizeUrl, noBrowser);
+
+ const code = await waitForAuthorizationCode(callback, state);
+
+ const token = await exchangeAuthorizationCode({
+ authBaseUrl,
+ code,
+ redirectUri: callback.url,
+ verifier,
+ });
+
+ await persistInstance({
+ instanceName,
+ backendBaseUrl,
+ clientId,
+ token,
+ });
+
+ process.stdout.write('Login successful\n');
+ } finally {
+ await callback.close();
+ }
+};
+
+async function promptForInstance(
+ instances: StoredInstance[],
+ selected: StoredInstance | undefined,
+): Promise {
+ const choices = instances.map(i => ({
+ name: `${i.name === selected?.name ? '* ' : ' '}${i.name} (${i.baseUrl})`,
+ value: i.name,
+ }));
+
+ choices.push({
+ name: 'Add new instance...',
+ value: '__new__',
+ });
+
+ const { choice } = await inquirer.prompt<{ choice: string }>([
+ {
+ type: 'list',
+ name: 'choice',
+ message: 'Select instance to authenticate:',
+ choices,
+ default: selected?.name ?? '__new__',
+ },
+ ]);
+
+ return choice;
+}
+
+async function pickBaseUrl() {
+ const cwd = process.cwd();
+ const candidates: Array<{ url: string; file: string }> = [];
+
+ const patterns = [
+ 'app-config.yaml',
+ 'app-config.*.yaml',
+ 'packages/*/app-config.yaml',
+ 'packages/*/app-config.*.yaml',
+ ];
+ const files = patterns.flatMap(p => globSync(p, { cwd, nodir: true }));
+ for (const file of files) {
+ try {
+ const content = await fs.readFile(path.resolve(cwd, file), 'utf8');
+ const doc = YAML.parse(content);
+ const url = doc?.backend?.baseUrl as string | undefined;
+ if (url) {
+ candidates.push({ url: normalizeUrl(url), file });
+ }
+ } catch {
+ // ignore parse errors
+ }
+ }
+
+ const list = [...new Map(candidates.map(c => [c.url, c])).values()];
+ if (list.length === 0) {
+ const { manual } = await inquirer.prompt<{ manual: string }>([
+ { type: 'input', name: 'manual', message: 'Enter backend base URL' },
+ ]);
+ return normalizeUrl(manual);
+ }
+ if (list.length === 1) {
+ return list[0].url;
+ }
+
+ const { picked } = await inquirer.prompt<{ picked: string }>([
+ {
+ type: 'list',
+ name: 'picked',
+ message: 'Select backend base URL',
+ choices: [
+ ...list.map(e => ({ name: `${e.url} (${e.file})`, value: e.url })),
+ { name: 'Enter manually', value: '__manual__' },
+ ],
+ },
+ ]);
+ if (picked === '__manual__') {
+ const { manual } = await inquirer.prompt<{ manual: string }>([
+ { type: 'input', name: 'manual', message: 'Enter backend base URL' },
+ ]);
+ return normalizeUrl(manual);
+ }
+ return picked;
+}
+
+function normalizeUrl(u: string): string;
+function normalizeUrl(u: string | undefined): string | undefined;
+function normalizeUrl(u: string | undefined): string | undefined {
+ if (u === undefined) {
+ return undefined;
+ }
+ try {
+ const url = new URL(u);
+ return url.toString().replace(/\/$/, '');
+ } catch {
+ throw new Error(`'${u}' is not a valid URL`);
+ }
+}
+
+function deriveInstanceName(url: string): string {
+ return new URL(url).host;
+}
+
+function createPkceState() {
+ const verifier = generateVerifier();
+ const challenge = challengeFromVerifier(verifier);
+ const state = cryptoRandom();
+ return { verifier, challenge, state };
+}
+
+function buildAuthorizeUrl(options: {
+ authBaseUrl: string;
+ clientId: string;
+ redirectUri: string;
+ state: string;
+ challenge: string;
+}): string {
+ const { authBaseUrl, clientId, redirectUri, state, challenge } = options;
+ const authorize = new URL(`${authBaseUrl}/v1/authorize`);
+ authorize.searchParams.set('client_id', clientId);
+ authorize.searchParams.set('redirect_uri', redirectUri);
+ authorize.searchParams.set('response_type', 'code');
+ authorize.searchParams.set('scope', 'openid offline_access');
+ authorize.searchParams.set('state', state);
+ authorize.searchParams.set('code_challenge', challenge);
+ authorize.searchParams.set('code_challenge_method', 'S256');
+ return authorize.toString();
+}
+
+async function openBrowserOrPrint(url: string, noBrowser?: boolean) {
+ if (noBrowser) {
+ process.stdout.write(`Open this URL to continue: ${url}\n`);
+ } else {
+ process.stdout.write(`Opening the following URL: ${url}\n`);
+ openInBrowser(url);
+ }
+}
+
+async function waitForAuthorizationCode(
+ callback: Awaited>,
+ expectedState: string,
+) {
+ const { code, state } = await callback.waitForCode();
+ if (state !== expectedState) {
+ throw new Error('State mismatch');
+ }
+ return code;
+}
+
+async function exchangeAuthorizationCode(options: {
+ authBaseUrl: string;
+ code: string;
+ redirectUri: string;
+ verifier: string;
+}) {
+ const { authBaseUrl, code, redirectUri, verifier } = options;
+ return await httpJson<{
+ access_token: string;
+ token_type: string;
+ expires_in: number;
+ id_token?: string;
+ refresh_token?: string;
+ }>(`${authBaseUrl}/v1/token`, {
+ method: 'POST',
+ body: {
+ grant_type: 'authorization_code',
+ code,
+ redirect_uri: redirectUri,
+ code_verifier: verifier,
+ },
+ signal: AbortSignal.timeout(TOKEN_EXCHANGE_TIMEOUT_MS),
+ });
+}
+
+async function persistInstance(options: {
+ instanceName: string;
+ backendBaseUrl: string;
+ clientId: string;
+ token: { access_token: string; refresh_token?: string; expires_in: number };
+}) {
+ const { instanceName, backendBaseUrl, clientId, token } = options;
+ const secretStore = await getSecretStore();
+ await withMetadataLock(async () => {
+ const service = getAuthInstanceService(instanceName);
+ await secretStore.set(service, 'accessToken', token.access_token);
+ if (token.refresh_token) {
+ await secretStore.set(service, 'refreshToken', token.refresh_token);
+ } else {
+ process.stderr.write(
+ 'Warning: No refresh token received. You will need to re-authenticate when the access token expires.\n',
+ );
+ }
+ let existing: StoredInstance | undefined;
+ try {
+ existing = await getInstanceByName(instanceName);
+ } catch {
+ // new instance
+ }
+ await upsertInstance({
+ name: instanceName,
+ baseUrl: backendBaseUrl,
+ clientId,
+ issuedAt: Date.now(),
+ accessTokenExpiresAt: Date.now() + token.expires_in * 1000,
+ selected: existing?.selected,
+ });
+ });
+}
+
+function cryptoRandom(): string {
+ return crypto.randomBytes(32).toString('hex');
+}
+
+// The react-dev-utils/openBrowser breaks the login URL by encoding the URL parameters again
+export function openInBrowser(url: string): void {
+ const handleError = (error: unknown) => {
+ const message = error instanceof Error ? error.message : 'Unknown error';
+ process.stderr.write(
+ `Warning: Failed to open browser automatically: ${message}\n`,
+ );
+ process.stderr.write(`Please open this URL manually: ${url}\n`);
+ };
+
+ const spawnOpts = { detached: true, stdio: 'ignore' } as const;
+ let child;
+ try {
+ if (process.platform === 'darwin') {
+ child = spawn('open', [url], spawnOpts);
+ } else if (process.platform === 'win32') {
+ child = spawn(
+ 'powershell',
+ ['-Command', `Start-Process '${url.replace(/'/g, "''")}'`],
+ spawnOpts,
+ );
+ } else {
+ child = spawn('xdg-open', [url], spawnOpts);
+ }
+ child.unref();
+ child.on('error', handleError);
+ } catch (error) {
+ handleError(error);
+ }
+}
diff --git a/packages/cli-module-auth/src/commands/logout.ts b/packages/cli-module-auth/src/commands/logout.ts
new file mode 100644
index 0000000000..a02fb3580d
--- /dev/null
+++ b/packages/cli-module-auth/src/commands/logout.ts
@@ -0,0 +1,77 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import type { CliCommandContext } from '@backstage/cli-node';
+import { getSecretStore, getAuthInstanceService } from '@internal/cli';
+import {
+ removeInstance,
+ withMetadataLock,
+ getInstanceByName,
+} from '../lib/storage';
+import { httpJson } from '../lib/http';
+import { pickInstance } from '../lib/prompt';
+
+export default async ({ args, info }: CliCommandContext) => {
+ const {
+ flags: { instance: instanceFlag },
+ } = cli(
+ {
+ help: info,
+ flags: {
+ instance: {
+ type: String,
+ description: 'Name of the instance to log out',
+ },
+ },
+ },
+ undefined,
+ args,
+ );
+
+ const { name: instanceName } = await pickInstance(instanceFlag);
+
+ await withMetadataLock(async () => {
+ const instance = await getInstanceByName(instanceName);
+ const secretStore = await getSecretStore();
+ const service = getAuthInstanceService(instanceName);
+ const refreshToken = (await secretStore.get(service, 'refreshToken')) ?? '';
+
+ if (refreshToken) {
+ try {
+ const authBaseUrl = new URL('/api/auth', instance.baseUrl)
+ .toString()
+ .replace(/\/$/, '');
+ await httpJson(`${authBaseUrl}/v1/revoke`, {
+ method: 'POST',
+ body: {
+ token: refreshToken,
+ token_type_hint: 'refresh_token',
+ },
+ signal: AbortSignal.timeout(30_000),
+ });
+ } catch {
+ // ignore errors per RFC 7009
+ }
+ }
+
+ await secretStore.delete(service, 'accessToken');
+ await secretStore.delete(service, 'refreshToken');
+ await removeInstance(instance.name);
+ });
+
+ process.stdout.write('Logged out\n');
+};
diff --git a/packages/cli-module-auth/src/commands/printToken.ts b/packages/cli-module-auth/src/commands/printToken.ts
new file mode 100644
index 0000000000..45b4cfd9f6
--- /dev/null
+++ b/packages/cli-module-auth/src/commands/printToken.ts
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import { CliAuth, type CliCommandContext } from '@backstage/cli-node';
+
+export default async ({ args, info }: CliCommandContext) => {
+ const {
+ flags: { instance: instanceFlag },
+ } = cli(
+ {
+ help: info,
+ flags: {
+ instance: {
+ type: String,
+ description: 'Name of the instance to use',
+ },
+ },
+ },
+ undefined,
+ args,
+ );
+
+ const auth = await CliAuth.create({ instanceName: instanceFlag });
+ const accessToken = await auth.getAccessToken();
+
+ process.stdout.write(`${accessToken}\n`);
+};
diff --git a/packages/cli-module-auth/src/commands/select.ts b/packages/cli-module-auth/src/commands/select.ts
new file mode 100644
index 0000000000..ebce23b1cb
--- /dev/null
+++ b/packages/cli-module-auth/src/commands/select.ts
@@ -0,0 +1,43 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import type { CliCommandContext } from '@backstage/cli-node';
+import { setSelectedInstance } from '../lib/storage';
+import { pickInstance } from '../lib/prompt';
+
+export default async ({ args, info }: CliCommandContext) => {
+ const {
+ flags: { instance: instanceFlag },
+ } = cli(
+ {
+ help: info,
+ flags: {
+ instance: {
+ type: String,
+ description: 'Name of the instance to select',
+ },
+ },
+ },
+ undefined,
+ args,
+ );
+
+ const instance = await pickInstance(instanceFlag);
+
+ await setSelectedInstance(instance.name);
+ process.stderr.write(`Selected instance '${instance.name}'\n`);
+};
diff --git a/packages/cli-module-auth/src/commands/show.ts b/packages/cli-module-auth/src/commands/show.ts
new file mode 100644
index 0000000000..275b6ca66d
--- /dev/null
+++ b/packages/cli-module-auth/src/commands/show.ts
@@ -0,0 +1,59 @@
+/*
+ * Copyright 2025 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 { cli } from 'cleye';
+import { CliAuth, type CliCommandContext } from '@backstage/cli-node';
+import { httpJson } from '../lib/http';
+
+export default async ({ args, info }: CliCommandContext) => {
+ const {
+ flags: { instance: instanceFlag },
+ } = cli(
+ {
+ help: info,
+ flags: {
+ instance: {
+ type: String,
+ description: 'Name of the instance to show',
+ },
+ },
+ },
+ undefined,
+ args,
+ );
+
+ const auth = await CliAuth.create({ instanceName: instanceFlag });
+ const accessToken = await auth.getAccessToken();
+
+ const authBase = new URL('/api/auth', auth.getBaseUrl())
+ .toString()
+ .replace(/\/$/, '');
+
+ const userinfo = await httpJson<{ claims: { sub: string; ent: string[] } }>(
+ `${authBase}/v1/userinfo`,
+ {
+ headers: { Authorization: `Bearer ${accessToken}` },
+ signal: AbortSignal.timeout(30_000),
+ },
+ );
+
+ process.stdout.write(`User: ${userinfo.claims.sub}\n`);
+ process.stdout.write(`\n`);
+ process.stdout.write(`Ownership:\n`);
+ for (const ent of userinfo.claims.ent ?? []) {
+ process.stdout.write(` - ${ent}\n`);
+ }
+};
diff --git a/packages/cli-module-auth/src/index.ts b/packages/cli-module-auth/src/index.ts
new file mode 100644
index 0000000000..fef74ec8a5
--- /dev/null
+++ b/packages/cli-module-auth/src/index.ts
@@ -0,0 +1,54 @@
+/*
+ * Copyright 2025 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 { createCliModule } from '@backstage/cli-node';
+import packageJson from '../package.json';
+
+export default createCliModule({
+ packageJson,
+ init: async reg => {
+ reg.addCommand({
+ path: ['auth', 'login'],
+ description: 'Log in the CLI to a Backstage instance',
+ execute: { loader: () => import('./commands/login') },
+ });
+ reg.addCommand({
+ path: ['auth', 'logout'],
+ description: 'Log out the CLI and clear stored credentials',
+ execute: { loader: () => import('./commands/logout') },
+ });
+ reg.addCommand({
+ path: ['auth', 'show'],
+ description: 'Show details of an authenticated instance',
+ execute: { loader: () => import('./commands/show') },
+ });
+ reg.addCommand({
+ path: ['auth', 'list'],
+ description: 'List authenticated instances',
+ execute: { loader: () => import('./commands/list') },
+ });
+ reg.addCommand({
+ path: ['auth', 'print-token'],
+ description: 'Print an access token to stdout (auto-refresh if needed)',
+ execute: { loader: () => import('./commands/printToken') },
+ });
+ reg.addCommand({
+ path: ['auth', 'select'],
+ description: 'Select the default instance',
+ execute: { loader: () => import('./commands/select') },
+ });
+ },
+});
diff --git a/packages/cli-module-auth/src/lib/auth.test.ts b/packages/cli-module-auth/src/lib/auth.test.ts
new file mode 100644
index 0000000000..18e7658e92
--- /dev/null
+++ b/packages/cli-module-auth/src/lib/auth.test.ts
@@ -0,0 +1,339 @@
+/*
+ * Copyright 2025 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 { accessTokenNeedsRefresh, refreshAccessToken } from './auth';
+import * as storage from './storage';
+import * as internalCli from '@internal/cli';
+import * as http from './http';
+
+jest.mock('./storage');
+jest.mock('@internal/cli');
+jest.mock('./http');
+
+const mockStorage = storage as jest.Mocked;
+const mockInternalCli = internalCli as jest.Mocked;
+const mockHttp = http as jest.Mocked;
+
+describe('auth', () => {
+ describe('accessTokenNeedsRefresh', () => {
+ it('should return true if token expires within 2 minutes', () => {
+ const now = Date.now();
+ const instance = {
+ name: 'test',
+ baseUrl: 'http://localhost:7007',
+ clientId: 'test-client',
+ issuedAt: now,
+
+ accessTokenExpiresAt: now + 60_000, // 1 minute from now
+ };
+
+ expect(accessTokenNeedsRefresh(instance)).toBe(true);
+ });
+
+ it('should return true if token has already expired', () => {
+ const now = Date.now();
+ const instance = {
+ name: 'test',
+ baseUrl: 'http://localhost:7007',
+ clientId: 'test-client',
+ issuedAt: now - 3600_000,
+
+ accessTokenExpiresAt: now - 60_000, // expired 1 minute ago
+ };
+
+ expect(accessTokenNeedsRefresh(instance)).toBe(true);
+ });
+
+ it('should return false if token is valid for more than 2 minutes', () => {
+ const now = Date.now();
+ const instance = {
+ name: 'test',
+ baseUrl: 'http://localhost:7007',
+ clientId: 'test-client',
+ issuedAt: now,
+
+ accessTokenExpiresAt: now + 5 * 60_000, // 5 minutes from now
+ };
+
+ expect(accessTokenNeedsRefresh(instance)).toBe(false);
+ });
+
+ it('should return true at exactly 2 minutes before expiration', () => {
+ const now = Date.now();
+ const instance = {
+ name: 'test',
+ baseUrl: 'http://localhost:7007',
+ clientId: 'test-client',
+ issuedAt: now,
+
+ accessTokenExpiresAt: now + 2 * 60_000, // exactly 2 minutes from now
+ };
+
+ expect(accessTokenNeedsRefresh(instance)).toBe(true);
+ });
+ });
+
+ describe('refreshAccessToken', () => {
+ const mockSecretStoreInstance = {
+ get: jest.fn(),
+ set: jest.fn(),
+ delete: jest.fn(),
+ };
+
+ beforeEach(() => {
+ jest.clearAllMocks();
+ mockInternalCli.getSecretStore.mockResolvedValue(mockSecretStoreInstance);
+ mockInternalCli.getAuthInstanceService.mockImplementation(
+ (name: string) => `backstage-cli:auth-instance:${name}`,
+ );
+ });
+
+ it('should successfully refresh access token', async () => {
+ const now = Date.now();
+ const instance = {
+ name: 'test',
+ baseUrl: 'http://localhost:7007',
+ clientId: 'test-client-id',
+ issuedAt: now - 3600_000,
+
+ accessTokenExpiresAt: now - 60_000,
+ };
+
+ mockStorage.withMetadataLock.mockImplementation(
+ async (fn: () => Promise) => fn(),
+ );
+ mockStorage.getInstanceByName.mockResolvedValue(instance);
+ mockSecretStoreInstance.get.mockImplementation(
+ async (_service: string, account: string) => {
+ if (account === 'clientSecret') return 'test-secret';
+ if (account === 'refreshToken') return 'old-refresh-token';
+ return undefined;
+ },
+ );
+
+ const tokenResponse = {
+ access_token: 'new-access-token',
+ token_type: 'Bearer',
+ expires_in: 3600,
+ refresh_token: 'new-refresh-token',
+ };
+
+ mockHttp.httpJson.mockResolvedValue(tokenResponse);
+ mockStorage.upsertInstance.mockResolvedValue();
+
+ const result = await refreshAccessToken('test');
+
+ expect(mockStorage.getInstanceByName).toHaveBeenCalledWith('test');
+ expect(mockSecretStoreInstance.get).toHaveBeenCalledWith(
+ 'backstage-cli:auth-instance:test',
+ 'refreshToken',
+ );
+ expect(mockHttp.httpJson).toHaveBeenCalledWith(
+ 'http://localhost:7007/api/auth/v1/token',
+ {
+ signal: expect.any(AbortSignal),
+ method: 'POST',
+ body: {
+ grant_type: 'refresh_token',
+ refresh_token: 'old-refresh-token',
+ },
+ },
+ );
+ expect(mockSecretStoreInstance.set).toHaveBeenCalledWith(
+ 'backstage-cli:auth-instance:test',
+ 'accessToken',
+ 'new-access-token',
+ );
+ expect(mockSecretStoreInstance.set).toHaveBeenCalledWith(
+ 'backstage-cli:auth-instance:test',
+ 'refreshToken',
+ 'new-refresh-token',
+ );
+ expect(mockStorage.upsertInstance).toHaveBeenCalled();
+ expect(result.accessTokenExpiresAt).toBeGreaterThan(now);
+ });
+
+ it('should throw error if refresh token is missing', async () => {
+ const now = Date.now();
+ const instance = {
+ name: 'test',
+ baseUrl: 'http://localhost:7007',
+ clientId: 'test-client-id',
+ issuedAt: now - 3600_000,
+
+ accessTokenExpiresAt: now - 60_000,
+ };
+
+ mockStorage.withMetadataLock.mockImplementation(
+ async (fn: () => Promise) => fn(),
+ );
+ mockStorage.getInstanceByName.mockResolvedValue(instance);
+ mockSecretStoreInstance.get.mockResolvedValue(undefined);
+
+ await expect(refreshAccessToken('test')).rejects.toThrow(
+ 'Access token is expired and no refresh token is available',
+ );
+ });
+
+ it('should use metadata lock during refresh', async () => {
+ const now = Date.now();
+ const instance = {
+ name: 'test',
+ baseUrl: 'http://localhost:7007',
+ clientId: 'test-client-id',
+ issuedAt: now - 3600_000,
+
+ accessTokenExpiresAt: now - 60_000,
+ };
+
+ let lockAcquired = false;
+ mockStorage.withMetadataLock.mockImplementation(
+ async (fn: () => Promise) => {
+ lockAcquired = true;
+ return fn();
+ },
+ );
+ mockStorage.getInstanceByName.mockResolvedValue(instance);
+ mockSecretStoreInstance.get.mockImplementation(
+ async (_service: string, account: string) => {
+ if (account === 'clientSecret') return 'test-secret';
+ if (account === 'refreshToken') return 'refresh-token';
+ return undefined;
+ },
+ );
+
+ const tokenResponse = {
+ access_token: 'new-access-token',
+ token_type: 'Bearer',
+ expires_in: 3600,
+ refresh_token: 'new-refresh-token',
+ };
+
+ mockHttp.httpJson.mockResolvedValue(tokenResponse);
+ mockStorage.upsertInstance.mockResolvedValue();
+
+ await refreshAccessToken('test');
+
+ expect(lockAcquired).toBe(true);
+ expect(mockStorage.withMetadataLock).toHaveBeenCalled();
+ });
+
+ it('should handle HTTP and network errors during refresh', async () => {
+ const now = Date.now();
+ const instance = {
+ name: 'test',
+ baseUrl: 'http://localhost:7007',
+ clientId: 'test-client-id',
+ issuedAt: now - 3600_000,
+
+ accessTokenExpiresAt: now - 60_000,
+ };
+
+ const errorCases = [
+ new Error('Request failed with 401 Unauthorized'),
+ new Error('Network error'),
+ ];
+
+ for (const error of errorCases) {
+ mockStorage.withMetadataLock.mockImplementation(
+ async (fn: () => Promise) => fn(),
+ );
+ mockStorage.getInstanceByName.mockResolvedValue(instance);
+ mockSecretStoreInstance.get.mockImplementation(
+ async (_service: string, account: string) => {
+ if (account === 'clientSecret') return 'test-secret';
+ if (account === 'refreshToken') return 'refresh-token';
+ return undefined;
+ },
+ );
+
+ mockHttp.httpJson.mockRejectedValue(error);
+
+ await expect(refreshAccessToken('test')).rejects.toThrow(error.message);
+ }
+ });
+
+ it('should validate token response and reject malformed responses', async () => {
+ const now = Date.now();
+ const instance = {
+ name: 'test',
+ baseUrl: 'http://localhost:7007',
+ clientId: 'test-client-id',
+ issuedAt: now - 3600_000,
+
+ accessTokenExpiresAt: now - 60_000,
+ };
+
+ mockStorage.withMetadataLock.mockImplementation(
+ async (fn: () => Promise) => fn(),
+ );
+ mockStorage.getInstanceByName.mockResolvedValue(instance);
+ mockSecretStoreInstance.get.mockImplementation(
+ async (_service: string, account: string) => {
+ if (account === 'clientSecret') return 'test-secret';
+ if (account === 'refreshToken') return 'refresh-token';
+ return undefined;
+ },
+ );
+
+ // Test missing access_token
+ mockHttp.httpJson.mockResolvedValue({
+ token_type: 'Bearer',
+ expires_in: 3600,
+ refresh_token: 'new-refresh-token',
+ } as any);
+
+ await expect(refreshAccessToken('test')).rejects.toThrow(
+ 'Invalid token response',
+ );
+ await expect(refreshAccessToken('test')).rejects.toThrow('access_token');
+
+ // Test missing expires_in
+ mockHttp.httpJson.mockResolvedValue({
+ access_token: 'new-access-token',
+ token_type: 'Bearer',
+ refresh_token: 'new-refresh-token',
+ } as any);
+
+ await expect(refreshAccessToken('test')).rejects.toThrow(
+ 'Invalid token response',
+ );
+ await expect(refreshAccessToken('test')).rejects.toThrow('expires_in');
+
+ // Test missing refresh_token still succeeds and preserves existing token
+ mockHttp.httpJson.mockResolvedValue({
+ access_token: 'new-access-token',
+ token_type: 'Bearer',
+ expires_in: 3600,
+ } as any);
+
+ await expect(refreshAccessToken('test')).resolves.toBeDefined();
+
+ // Test invalid expires_in (non-positive)
+ mockHttp.httpJson.mockResolvedValue({
+ access_token: 'new-access-token',
+ token_type: 'Bearer',
+ expires_in: 0,
+ refresh_token: 'new-refresh-token',
+ } as any);
+
+ await expect(refreshAccessToken('test')).rejects.toThrow(
+ 'Invalid token response',
+ );
+ await expect(refreshAccessToken('test')).rejects.toThrow('expires_in');
+ });
+ });
+});
diff --git a/packages/cli-module-auth/src/lib/auth.ts b/packages/cli-module-auth/src/lib/auth.ts
new file mode 100644
index 0000000000..1ad108cbf1
--- /dev/null
+++ b/packages/cli-module-auth/src/lib/auth.ts
@@ -0,0 +1,85 @@
+/*
+ * Copyright 2025 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 { z } from 'zod/v3';
+import {
+ type StoredInstance,
+ upsertInstance,
+ withMetadataLock,
+ getInstanceByName,
+} from './storage';
+import { getSecretStore, getAuthInstanceService } from '@internal/cli';
+import { httpJson } from './http';
+
+const TokenResponseSchema = z.object({
+ access_token: z.string().min(1),
+ token_type: z.string().min(1),
+ expires_in: z.number().positive().finite(),
+ refresh_token: z.string().min(1).optional(),
+});
+
+export function accessTokenNeedsRefresh(instance: StoredInstance): boolean {
+ // 2 minutes before expiration
+ return instance.accessTokenExpiresAt <= Date.now() + 2 * 60_000;
+}
+
+export async function refreshAccessToken(
+ instanceName: string,
+): Promise {
+ const secretStore = await getSecretStore();
+
+ return withMetadataLock(async () => {
+ const instance = await getInstanceByName(instanceName);
+
+ const service = getAuthInstanceService(instanceName);
+ const refreshToken = (await secretStore.get(service, 'refreshToken')) ?? '';
+ if (!refreshToken) {
+ throw new Error(
+ 'Access token is expired and no refresh token is available',
+ );
+ }
+
+ const response = await httpJson(
+ `${instance.baseUrl}/api/auth/v1/token`,
+ {
+ method: 'POST',
+ body: {
+ grant_type: 'refresh_token',
+ refresh_token: refreshToken,
+ },
+ signal: AbortSignal.timeout(30_000),
+ },
+ );
+
+ const parsed = TokenResponseSchema.safeParse(response);
+ if (!parsed.success) {
+ throw new Error(`Invalid token response: ${parsed.error.message}`);
+ }
+ const token = parsed.data;
+
+ await secretStore.set(service, 'accessToken', token.access_token);
+ if (token.refresh_token) {
+ await secretStore.set(service, 'refreshToken', token.refresh_token);
+ }
+ const newInstance = {
+ ...instance,
+ issuedAt: Date.now(),
+ accessTokenExpiresAt: Date.now() + token.expires_in * 1000,
+ };
+ await upsertInstance(newInstance);
+ return newInstance;
+ });
+}
diff --git a/packages/cli-module-auth/src/lib/http.test.ts b/packages/cli-module-auth/src/lib/http.test.ts
new file mode 100644
index 0000000000..40ab7009b1
--- /dev/null
+++ b/packages/cli-module-auth/src/lib/http.test.ts
@@ -0,0 +1,270 @@
+/*
+ * Copyright 2025 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 { httpJson } from './http';
+
+const mockFetch = jest.fn() as jest.MockedFunction;
+
+beforeEach(() => {
+ global.fetch = mockFetch;
+});
+
+describe('http', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ describe('httpJson', () => {
+ it('should make successful GET request and parse JSON', async () => {
+ const mockResponse = {
+ ok: true,
+ json: jest.fn().mockResolvedValue({ data: 'test' }),
+ };
+ mockFetch.mockResolvedValue(mockResponse as any);
+
+ const result = await httpJson('https://example.com/api');
+
+ expect(mockFetch).toHaveBeenCalledWith(
+ 'https://example.com/api',
+ expect.objectContaining({
+ body: undefined,
+ }),
+ );
+ expect(result).toEqual({ data: 'test' });
+ });
+
+ it('should make POST request with JSON body', async () => {
+ const mockResponse = {
+ ok: true,
+ json: jest.fn().mockResolvedValue({ success: true }),
+ };
+ mockFetch.mockResolvedValue(mockResponse as any);
+
+ const body = { username: 'test', password: 'secret' };
+ const result = await httpJson('https://example.com/api', {
+ method: 'POST',
+ body,
+ });
+
+ expect(mockFetch).toHaveBeenCalledWith(
+ 'https://example.com/api',
+ expect.objectContaining({
+ method: 'POST',
+ body: JSON.stringify(body),
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ }),
+ );
+ expect(result).toEqual({ success: true });
+ });
+
+ it('should include and merge custom headers', async () => {
+ const mockResponse = {
+ ok: true,
+ json: jest.fn().mockResolvedValue({ data: 'test' }),
+ };
+ mockFetch.mockResolvedValue(mockResponse as any);
+
+ // Test custom headers without body
+ await httpJson('https://example.com/api', {
+ headers: {
+ Authorization: 'Bearer token',
+ 'X-Custom': 'value',
+ },
+ });
+
+ expect(mockFetch).toHaveBeenCalledWith(
+ 'https://example.com/api',
+ expect.objectContaining({
+ headers: {
+ Authorization: 'Bearer token',
+ 'X-Custom': 'value',
+ },
+ }),
+ );
+
+ // Test merging headers with content-type when body is present
+ await httpJson('https://example.com/api', {
+ method: 'POST',
+ body: { data: 'test' },
+ headers: {
+ Authorization: 'Bearer token',
+ },
+ });
+
+ expect(mockFetch).toHaveBeenCalledWith(
+ 'https://example.com/api',
+ expect.objectContaining({
+ headers: {
+ Authorization: 'Bearer token',
+ 'Content-Type': 'application/json',
+ },
+ }),
+ );
+ });
+
+ it('should throw ResponseError for non-ok responses', async () => {
+ const errorCases = [
+ { status: 404, statusText: 'Not Found' },
+ { status: 401, statusText: 'Unauthorized' },
+ { status: 500, statusText: 'Internal Server Error' },
+ ];
+
+ for (const { status, statusText } of errorCases) {
+ const mockResponse = {
+ ok: false,
+ status,
+ statusText,
+ url: 'https://example.com/api',
+ text: jest.fn().mockResolvedValue('Error'),
+ };
+ mockFetch.mockResolvedValue(mockResponse as any);
+
+ await expect(httpJson('https://example.com/api')).rejects.toThrow(
+ `Request failed with ${status} ${statusText}`,
+ );
+ }
+ });
+
+ it('should pass through abort signal from caller', async () => {
+ const abortController = new AbortController();
+ let rejectFn: (error: Error) => void;
+ const mockResponse = new Promise((_, reject) => {
+ rejectFn = reject;
+ setTimeout(() => {
+ reject(new Error('Request should have been aborted'));
+ }, 60000); // 60 seconds
+ });
+
+ mockFetch.mockImplementation((_url, options) => {
+ const signal = options?.signal as AbortSignal;
+ signal?.addEventListener('abort', () => {
+ rejectFn(new Error('The operation was aborted'));
+ });
+ return mockResponse as any;
+ });
+
+ const requestPromise = httpJson('https://example.com/api', {
+ signal: abortController.signal,
+ });
+
+ // Abort the request
+ abortController.abort();
+
+ await expect(requestPromise).rejects.toThrow('The operation was aborted');
+ });
+
+ it('should handle JSON parsing errors gracefully', async () => {
+ const mockResponse = {
+ ok: true,
+ json: jest.fn().mockRejectedValue(new Error('Invalid JSON')),
+ };
+ mockFetch.mockResolvedValue(mockResponse as any);
+
+ await expect(httpJson('https://example.com/api')).rejects.toThrow(
+ 'Invalid JSON',
+ );
+ });
+
+ it('should support different HTTP methods', async () => {
+ const mockResponse = {
+ ok: true,
+ json: jest.fn().mockResolvedValue({ success: true }),
+ };
+
+ for (const method of ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']) {
+ mockFetch.mockResolvedValue(mockResponse as any);
+
+ await httpJson('https://example.com/api', { method });
+
+ expect(mockFetch).toHaveBeenCalledWith(
+ 'https://example.com/api',
+ expect.objectContaining({
+ method,
+ }),
+ );
+ }
+ });
+
+ it('should handle various response body types', async () => {
+ const testCases = [
+ { body: null, expected: null },
+ { body: [1, 2, 3], expected: [1, 2, 3] },
+ { body: { data: 'test' }, expected: { data: 'test' } },
+ ];
+
+ for (const { body, expected } of testCases) {
+ const mockResponse = {
+ ok: true,
+ json: jest.fn().mockResolvedValue(body),
+ };
+ mockFetch.mockResolvedValue(mockResponse as any);
+
+ const result = await httpJson('https://example.com/api');
+ expect(result).toEqual(expected);
+ }
+ });
+
+ it('should handle network errors', async () => {
+ const networkError = new Error('Network error');
+ mockFetch.mockRejectedValue(networkError);
+
+ await expect(httpJson('https://example.com/api')).rejects.toThrow(
+ 'Network error',
+ );
+ });
+
+ it('should use custom abort signal if provided', async () => {
+ const mockResponse = {
+ ok: true,
+ json: jest.fn().mockResolvedValue({ data: 'test' }),
+ };
+ mockFetch.mockResolvedValue(mockResponse as any);
+
+ const customController = new AbortController();
+ await httpJson('https://example.com/api', {
+ signal: customController.signal,
+ });
+
+ expect(mockFetch).toHaveBeenCalledWith(
+ 'https://example.com/api',
+ expect.objectContaining({
+ signal: expect.any(AbortSignal),
+ }),
+ );
+ });
+
+ it('should handle malformed URLs gracefully', async () => {
+ const networkError = new TypeError('Failed to parse URL');
+ mockFetch.mockRejectedValue(networkError);
+
+ await expect(httpJson('not-a-valid-url')).rejects.toThrow();
+ });
+
+ it('should handle very large response bodies', async () => {
+ const largeData = { items: Array(10000).fill({ data: 'x'.repeat(100) }) };
+ const mockResponse = {
+ ok: true,
+ json: jest.fn().mockResolvedValue(largeData),
+ };
+ mockFetch.mockResolvedValue(mockResponse as any);
+
+ const result = await httpJson('https://example.com/api');
+ expect(result).toEqual(largeData);
+ });
+ });
+});
diff --git a/packages/cli-module-auth/src/lib/http.ts b/packages/cli-module-auth/src/lib/http.ts
new file mode 100644
index 0000000000..4daaf823fb
--- /dev/null
+++ b/packages/cli-module-auth/src/lib/http.ts
@@ -0,0 +1,39 @@
+/*
+ * Copyright 2025 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 { ResponseError } from '@backstage/errors';
+
+export type HttpInit = {
+ headers?: Record;
+ method?: string;
+ body?: any;
+ signal?: AbortSignal;
+};
+
+export async function httpJson(url: string, init?: HttpInit): Promise {
+ const res = await fetch(url, {
+ ...init,
+ body: init?.body ? JSON.stringify(init.body) : undefined,
+ headers: {
+ ...(init?.body ? { 'Content-Type': 'application/json' } : {}),
+ ...init?.headers,
+ },
+ });
+ if (!res.ok) {
+ throw await ResponseError.fromResponse(res);
+ }
+ return (await res.json()) as T;
+}
diff --git a/packages/cli-module-auth/src/lib/localServer.test.ts b/packages/cli-module-auth/src/lib/localServer.test.ts
new file mode 100644
index 0000000000..3b03331d3e
--- /dev/null
+++ b/packages/cli-module-auth/src/lib/localServer.test.ts
@@ -0,0 +1,65 @@
+/*
+ * Copyright 2025 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 { startCallbackServer } from './localServer';
+
+describe('localServer', () => {
+ it('should start on port 8055, handle requests, and resolve the code', async () => {
+ const { url, waitForCode, close } = await startCallbackServer({
+ state: 'test-state',
+ });
+
+ expect(url).toBe('http://127.0.0.1:8055/callback');
+
+ // 404 for non-callback paths
+ const notFoundResponse = await fetch(
+ url.replace('/callback', '/other-path'),
+ );
+ expect(notFoundResponse.status).toBe(404);
+
+ // 400 for missing code
+ const missingCodeResponse = await fetch(`${url}?state=test-state`);
+ expect(missingCodeResponse.status).toBe(400);
+ expect(await missingCodeResponse.text()).toBe('Missing code');
+
+ // 400 for mismatched state
+ const mismatchResponse = await fetch(
+ `${url}?code=test-code&state=wrong-state`,
+ );
+ expect(mismatchResponse.status).toBe(400);
+ expect(await mismatchResponse.text()).toBe('State mismatch');
+
+ // 200 for valid callback with matching state
+ const codePromise = waitForCode();
+ const specialCode = 'test-code+with/special=chars';
+ const successResponse = await fetch(
+ `${url}?code=${encodeURIComponent(
+ specialCode,
+ )}&state=${encodeURIComponent('test-state')}`,
+ );
+ expect(successResponse.status).toBe(200);
+ expect(await successResponse.text()).toBe('You may now close this window.');
+ expect(successResponse.headers.get('content-type')).toBe(
+ 'text/plain; charset=utf-8',
+ );
+
+ const result = await codePromise;
+ expect(result.code).toBe(specialCode);
+ expect(result.state).toBe('test-state');
+
+ await close();
+ });
+});
diff --git a/packages/cli-module-auth/src/lib/localServer.ts b/packages/cli-module-auth/src/lib/localServer.ts
new file mode 100644
index 0000000000..0b71075a5b
--- /dev/null
+++ b/packages/cli-module-auth/src/lib/localServer.ts
@@ -0,0 +1,98 @@
+/*
+ * Copyright 2025 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 http from 'node:http';
+import { URL } from 'node:url';
+
+const CALLBACK_PORT = 8055;
+
+export async function startCallbackServer(options: { state: string }): Promise<{
+ url: string;
+ waitForCode: () => Promise<{ code: string; state?: string }>;
+ close: () => Promise;
+}> {
+ const server = http.createServer();
+
+ let resolveResult:
+ | ((v: { code: string; state?: string }) => void)
+ | undefined;
+ const resultPromise = new Promise<{ code: string; state?: string }>(
+ resolve => {
+ resolveResult = resolve;
+ },
+ );
+
+ server.on('request', (req, res) => {
+ if (!req.url) {
+ res.statusCode = 400;
+ res.end('Bad Request');
+ return;
+ }
+ const u = new URL(req.url, 'http://127.0.0.1');
+ if (u.pathname !== '/callback') {
+ res.statusCode = 404;
+ res.end('Not Found');
+ return;
+ }
+ const code = u.searchParams.get('code') ?? undefined;
+ const state = u.searchParams.get('state') ?? undefined;
+ if (!code) {
+ res.statusCode = 400;
+ res.end('Missing code');
+ return;
+ }
+ if (state !== options.state) {
+ res.statusCode = 400;
+ res.end('State mismatch');
+ return;
+ }
+ res.statusCode = 200;
+ res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+ res.end('You may now close this window.');
+ resolveResult?.({ code, state });
+ });
+
+ const port = await new Promise((resolve, reject) => {
+ server.on('error', (err: NodeJS.ErrnoException) => {
+ if (err.code === 'EADDRINUSE') {
+ reject(
+ new Error(
+ `Port ${CALLBACK_PORT} is already in use. Close the application using it and try again.`,
+ ),
+ );
+ } else {
+ reject(err);
+ }
+ });
+ server.listen(CALLBACK_PORT, '127.0.0.1', () => {
+ const address = server.address();
+ if (typeof address === 'object' && address && 'port' in address) {
+ resolve(address.port);
+ } else {
+ reject(new Error('Failed to bind local server'));
+ }
+ });
+ });
+
+ return {
+ url: `http://127.0.0.1:${port}/callback`,
+ waitForCode: () => resultPromise,
+ close: async () => {
+ server.closeAllConnections();
+ return new Promise(resolve => server.close(() => resolve()));
+ },
+ };
+}
diff --git a/packages/cli-module-auth/src/lib/pkce.test.ts b/packages/cli-module-auth/src/lib/pkce.test.ts
new file mode 100644
index 0000000000..09db60745a
--- /dev/null
+++ b/packages/cli-module-auth/src/lib/pkce.test.ts
@@ -0,0 +1,178 @@
+/*
+ * Copyright 2025 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 crypto from 'node:crypto';
+import { generateVerifier, challengeFromVerifier } from './pkce';
+
+describe('pkce', () => {
+ describe('generateVerifier', () => {
+ it('should generate verifiers with proper encoding and length', () => {
+ // Test default length
+ const defaultVerifier = generateVerifier();
+ expect(defaultVerifier).toBeDefined();
+ expect(typeof defaultVerifier).toBe('string');
+ expect(defaultVerifier.length).toBeGreaterThan(0);
+
+ // Test custom lengths
+ const shortVerifier = generateVerifier(32);
+ const longVerifier = generateVerifier(96);
+ expect(shortVerifier).toBeDefined();
+ expect(longVerifier).toBeDefined();
+ expect(shortVerifier.length).toBeGreaterThan(0);
+ expect(longVerifier.length).toBeGreaterThan(shortVerifier.length);
+
+ // Test base64url encoding (no padding, proper characters)
+ const verifier = generateVerifier();
+ expect(verifier).not.toContain('=');
+ expect(verifier).not.toContain('+');
+ expect(verifier).not.toContain('/');
+ expect(verifier).toMatch(/^[A-Za-z0-9_-]+$/);
+
+ // Test uniqueness
+ const verifier1 = generateVerifier();
+ const verifier2 = generateVerifier();
+ expect(verifier1).not.toBe(verifier2);
+ });
+
+ it('should enforce minimum and maximum length constraints', () => {
+ // Test minimum length enforcement
+ const minVerifier = generateVerifier(10); // Less than minimum
+ expect(minVerifier).toBeDefined();
+ expect(minVerifier.length).toBeGreaterThanOrEqual(43); // 32 bytes = 43 base64url chars
+
+ // Test maximum length enforcement
+ const maxVerifier = generateVerifier(200); // More than maximum
+ expect(maxVerifier).toBeDefined();
+ expect(maxVerifier.length).toBeLessThanOrEqual(128); // 96 bytes = 128 base64url chars
+ });
+
+ it('should produce consistent results for same byte sequence', () => {
+ // Mock crypto.randomBytes to return predictable values
+ const mockBytes = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);
+ jest.spyOn(crypto, 'randomBytes').mockImplementation(_count => mockBytes);
+
+ const verifier1 = generateVerifier(8);
+ const verifier2 = generateVerifier(8);
+
+ expect(verifier1).toBe(verifier2);
+
+ (crypto.randomBytes as jest.Mock).mockRestore();
+ });
+ });
+
+ describe('challengeFromVerifier', () => {
+ it('should generate challenges with proper encoding and consistency', () => {
+ const verifier = 'test-verifier-string';
+ const challenge = challengeFromVerifier(verifier);
+
+ // Basic properties
+ expect(challenge).toBeDefined();
+ expect(typeof challenge).toBe('string');
+ expect(challenge.length).toBe(43); // SHA-256 = 32 bytes = 43 base64url chars
+
+ // Base64url encoding (no padding, proper characters)
+ expect(challenge).not.toContain('=');
+ expect(challenge).not.toContain('+');
+ expect(challenge).not.toContain('/');
+ expect(challenge).toMatch(/^[A-Za-z0-9_-]+$/);
+
+ // Consistency for same verifier
+ const challenge1 = challengeFromVerifier(verifier);
+ const challenge2 = challengeFromVerifier(verifier);
+ expect(challenge1).toBe(challenge2);
+ expect(challenge1).toBe(challenge);
+
+ // Different challenges for different verifiers
+ const verifier2 = 'test-verifier-2';
+ const challenge3 = challengeFromVerifier(verifier2);
+ expect(challenge3).not.toBe(challenge);
+ });
+
+ it('should handle edge cases for verifier length', () => {
+ // Empty verifier
+ const emptyChallenge = challengeFromVerifier('');
+ expect(emptyChallenge).toBeDefined();
+ expect(emptyChallenge.length).toBe(43);
+
+ // Very long verifier
+ const longVerifier = 'a'.repeat(1000);
+ const longChallenge = challengeFromVerifier(longVerifier);
+ expect(longChallenge).toBeDefined();
+ expect(longChallenge.length).toBe(43); // SHA-256 always produces 32 bytes
+ });
+
+ it('should produce RFC 7636 compliant challenge', () => {
+ // Test with a known verifier
+ const verifier = generateVerifier();
+ const challenge = challengeFromVerifier(verifier);
+
+ // Verify it's using SHA-256 correctly
+ const expectedHash = crypto
+ .createHash('sha256')
+ .update(verifier)
+ .digest();
+ const expectedChallenge = expectedHash
+ .toString('base64')
+ .replace(/=/g, '')
+ .replace(/\+/g, '-')
+ .replace(/\//g, '_');
+
+ expect(challenge).toBe(expectedChallenge);
+ });
+ });
+
+ describe('PKCE flow integration', () => {
+ it('should generate valid verifier and challenge pair', () => {
+ const verifier = generateVerifier();
+ const challenge = challengeFromVerifier(verifier);
+
+ expect(verifier).toBeDefined();
+ expect(challenge).toBeDefined();
+ expect(verifier).not.toBe(challenge);
+
+ // Verifier should be longer than challenge
+ expect(verifier.length).toBeGreaterThan(challenge.length);
+ });
+
+ it('should generate multiple unique pairs', () => {
+ const pair1 = {
+ verifier: generateVerifier(),
+ challenge: '',
+ };
+ pair1.challenge = challengeFromVerifier(pair1.verifier);
+
+ const pair2 = {
+ verifier: generateVerifier(),
+ challenge: '',
+ };
+ pair2.challenge = challengeFromVerifier(pair2.verifier);
+
+ expect(pair1.verifier).not.toBe(pair2.verifier);
+ expect(pair1.challenge).not.toBe(pair2.challenge);
+ });
+
+ it('should maintain one-to-one mapping between verifier and challenge', () => {
+ const verifier = generateVerifier();
+ const challenge1 = challengeFromVerifier(verifier);
+ const challenge2 = challengeFromVerifier(verifier);
+ const challenge3 = challengeFromVerifier(verifier);
+
+ // All challenges from same verifier should be identical
+ expect(challenge1).toBe(challenge2);
+ expect(challenge2).toBe(challenge3);
+ });
+ });
+});
diff --git a/packages/cli-module-auth/src/lib/pkce.ts b/packages/cli-module-auth/src/lib/pkce.ts
new file mode 100644
index 0000000000..fd5bba2d70
--- /dev/null
+++ b/packages/cli-module-auth/src/lib/pkce.ts
@@ -0,0 +1,36 @@
+/*
+ * Copyright 2025 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 crypto from 'node:crypto';
+
+function base64url(input: Buffer): string {
+ return input
+ .toString('base64')
+ .replace(/=/g, '')
+ .replace(/\+/g, '-')
+ .replace(/\//g, '_');
+}
+
+export function generateVerifier(length = 64): string {
+ // length in bytes ~ 48 results in 64 base64url chars; keep within 43..128 chars
+ const bytes = crypto.randomBytes(Math.max(32, Math.min(96, length)));
+ return base64url(bytes);
+}
+
+export function challengeFromVerifier(verifier: string): string {
+ const hash = crypto.createHash('sha256').update(verifier).digest();
+ return base64url(hash);
+}
diff --git a/packages/cli-module-auth/src/lib/prompt.test.ts b/packages/cli-module-auth/src/lib/prompt.test.ts
new file mode 100644
index 0000000000..acb28fc124
--- /dev/null
+++ b/packages/cli-module-auth/src/lib/prompt.test.ts
@@ -0,0 +1,191 @@
+/*
+ * Copyright 2025 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 inquirer from 'inquirer';
+import { pickInstance } from './prompt';
+import * as storage from './storage';
+
+jest.mock('inquirer');
+jest.mock('./storage');
+
+const mockStorage = storage as jest.Mocked;
+const mockInquirer = inquirer as jest.Mocked;
+
+describe('prompt', () => {
+ describe('pickInstance', () => {
+ const mockInstances = [
+ {
+ name: 'production',
+ baseUrl: 'https://backstage.example.com',
+ clientId: 'prod-client',
+ issuedAt: Date.now(),
+ accessToken: 'prod-token',
+ accessTokenExpiresAt: Date.now() + 3600_000,
+ selected: true,
+ },
+ {
+ name: 'staging',
+ baseUrl: 'https://staging.backstage.example.com',
+ clientId: 'staging-client',
+ issuedAt: Date.now(),
+ accessToken: 'staging-token',
+ accessTokenExpiresAt: Date.now() + 3600_000,
+ selected: false,
+ },
+ {
+ name: 'local',
+ baseUrl: 'http://localhost:7007',
+ clientId: 'local-client',
+ issuedAt: Date.now(),
+ accessToken: 'local-token',
+ accessTokenExpiresAt: Date.now() + 3600_000,
+ selected: false,
+ },
+ ];
+
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it('should return instance by name if provided', async () => {
+ mockStorage.getInstanceByName.mockResolvedValue(mockInstances[1]);
+
+ const result = await pickInstance('staging');
+
+ expect(result).toEqual(mockInstances[1]);
+ expect(mockStorage.getInstanceByName).toHaveBeenCalledWith('staging');
+ expect(mockInquirer.prompt).not.toHaveBeenCalled();
+ });
+
+ it('should prompt for instance and show selected instance with asterisk prefix', async () => {
+ // Test with production selected
+ mockStorage.getAllInstances.mockResolvedValue({
+ instances: mockInstances,
+ selected: mockInstances[0],
+ });
+ mockInquirer.prompt.mockResolvedValue({ choice: 'staging' });
+
+ const result = await pickInstance();
+
+ expect(mockInquirer.prompt).toHaveBeenCalledWith([
+ {
+ type: 'list',
+ name: 'choice',
+ message: 'Select instance:',
+ choices: [
+ {
+ name: '* production (https://backstage.example.com)',
+ value: 'production',
+ },
+ {
+ name: ' staging (https://staging.backstage.example.com)',
+ value: 'staging',
+ },
+ {
+ name: ' local (http://localhost:7007)',
+ value: 'local',
+ },
+ ],
+ default: 'production',
+ },
+ ]);
+ expect(result).toEqual(mockInstances[1]);
+
+ // Test with staging selected
+ mockStorage.getAllInstances.mockResolvedValue({
+ instances: mockInstances,
+ selected: mockInstances[1],
+ });
+ mockInquirer.prompt.mockResolvedValue({ choice: 'staging' });
+
+ await pickInstance();
+
+ expect(mockInquirer.prompt).toHaveBeenCalledWith([
+ expect.objectContaining({
+ choices: [
+ {
+ name: ' production (https://backstage.example.com)',
+ value: 'production',
+ },
+ {
+ name: '* staging (https://staging.backstage.example.com)',
+ value: 'staging',
+ },
+ {
+ name: ' local (http://localhost:7007)',
+ value: 'local',
+ },
+ ],
+ default: 'staging',
+ }),
+ ]);
+ });
+
+ it('should throw error if no instances are available', async () => {
+ mockStorage.getAllInstances.mockResolvedValue({
+ instances: [],
+ selected: undefined,
+ });
+
+ await expect(pickInstance()).rejects.toThrow(
+ 'No instances found. Run "auth login" to authenticate first.',
+ );
+ });
+
+ it('should throw error if selected instance is not found', async () => {
+ mockStorage.getAllInstances.mockResolvedValue({
+ instances: mockInstances,
+ selected: mockInstances[0],
+ });
+ mockInquirer.prompt.mockResolvedValue({ choice: 'non-existent' });
+
+ await expect(pickInstance()).rejects.toThrow(
+ "Instance 'non-existent' not found",
+ );
+ });
+
+ it('should handle single instance and use selected instance as default', async () => {
+ // Test single instance
+ const singleInstance = [mockInstances[0]];
+ mockStorage.getAllInstances.mockResolvedValue({
+ instances: singleInstance,
+ selected: mockInstances[0],
+ });
+ mockInquirer.prompt.mockResolvedValue({ choice: 'production' });
+
+ const result = await pickInstance();
+
+ expect(result).toEqual(mockInstances[0]);
+ expect(mockInquirer.prompt).toHaveBeenCalled();
+
+ // Test default selection matches selected instance
+ const selectedInstance = mockInstances[2];
+ mockStorage.getAllInstances.mockResolvedValue({
+ instances: mockInstances,
+ selected: selectedInstance,
+ });
+ mockInquirer.prompt.mockResolvedValue({ choice: 'local' });
+
+ await pickInstance();
+
+ expect(mockInquirer.prompt).toHaveBeenCalledWith([
+ expect.objectContaining({
+ default: 'local',
+ }),
+ ]);
+ });
+ });
+});
diff --git a/packages/cli-module-auth/src/lib/prompt.ts b/packages/cli-module-auth/src/lib/prompt.ts
new file mode 100644
index 0000000000..46a7430548
--- /dev/null
+++ b/packages/cli-module-auth/src/lib/prompt.ts
@@ -0,0 +1,58 @@
+/*
+ * Copyright 2025 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 inquirer from 'inquirer';
+import { getInstanceByName, getAllInstances, StoredInstance } from './storage';
+
+export async function pickInstance(name?: string): Promise {
+ if (name) {
+ return getInstanceByName(name);
+ }
+
+ const { instances, selected } = await getAllInstances();
+ if (instances.length === 0) {
+ throw new Error(
+ 'No instances found. Run "auth login" to authenticate first.',
+ );
+ }
+ return await promptForInstance(instances, selected);
+}
+
+async function promptForInstance(
+ instances: StoredInstance[],
+ selected: StoredInstance | undefined,
+): Promise {
+ const choices = instances.map(i => ({
+ name: `${i.name === selected?.name ? '* ' : ' '}${i.name} (${i.baseUrl})`,
+ value: i.name,
+ }));
+
+ const { choice } = await inquirer.prompt<{ choice: string }>([
+ {
+ type: 'list',
+ name: 'choice',
+ message: 'Select instance:',
+ choices,
+ default: selected?.name,
+ },
+ ]);
+
+ const instance = instances.find(i => i.name === choice);
+ if (!instance) {
+ throw new Error(`Instance '${choice}' not found`);
+ }
+ return instance;
+}
diff --git a/packages/cli-module-auth/src/lib/secretStore.test.ts b/packages/cli-module-auth/src/lib/secretStore.test.ts
new file mode 100644
index 0000000000..f27d364c7c
--- /dev/null
+++ b/packages/cli-module-auth/src/lib/secretStore.test.ts
@@ -0,0 +1,250 @@
+/*
+ * Copyright 2025 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.
+ */
+
+jest.mock('keytar', () => {
+ throw new Error('keytar not available');
+});
+
+import fs from 'fs-extra';
+import path from 'node:path';
+import { createMockDirectory } from '@backstage/backend-test-utils';
+import { getSecretStore, resetSecretStore } from '@internal/cli';
+
+const mockDir = createMockDirectory();
+
+describe('secretStore', () => {
+ beforeEach(() => {
+ mockDir.clear();
+ process.env.XDG_DATA_HOME = mockDir.resolve('data');
+ resetSecretStore();
+ });
+
+ afterEach(() => {
+ delete process.env.XDG_DATA_HOME;
+ resetSecretStore();
+ });
+
+ describe('FileSecretStore', () => {
+ it('should store and retrieve secrets', async () => {
+ const store = await getSecretStore();
+ await store.set('test-service', 'test-account', 'test-secret');
+ const result = await store.get('test-service', 'test-account');
+
+ expect(result).toBe('test-secret');
+ });
+
+ it('should return undefined for non-existent secrets', async () => {
+ const store = await getSecretStore();
+ const result = await store.get('test-service', 'test-account');
+
+ expect(result).toBeUndefined();
+ });
+
+ it('should delete secrets', async () => {
+ const store = await getSecretStore();
+ await store.set('test-service', 'test-account', 'test-secret');
+
+ let result = await store.get('test-service', 'test-account');
+ expect(result).toBe('test-secret');
+
+ await store.delete('test-service', 'test-account');
+
+ result = await store.get('test-service', 'test-account');
+ expect(result).toBeUndefined();
+ });
+
+ it('should not throw when deleting non-existent secrets', async () => {
+ const store = await getSecretStore();
+
+ await expect(
+ store.delete('non-existent-service', 'non-existent-account'),
+ ).resolves.not.toThrow();
+ });
+
+ it('should create files with correct directory structure', async () => {
+ const store = await getSecretStore();
+ await store.set('test-service', 'test-account', 'test-secret');
+
+ const expectedDir = path.join(
+ mockDir.resolve('data'),
+ 'backstage-cli',
+ 'auth-secrets',
+ encodeURIComponent('test-service'),
+ );
+ const expectedFile = path.join(
+ expectedDir,
+ `${encodeURIComponent('test-account')}.secret`,
+ );
+
+ expect(await fs.pathExists(expectedFile)).toBe(true);
+ expect(await fs.pathExists(expectedDir)).toBe(true);
+ });
+
+ it('should create files with correct permissions (0o600)', async () => {
+ // File permissions are not reliably enforced on Windows
+ if (process.platform === 'win32') {
+ return;
+ }
+
+ const store = await getSecretStore();
+ await store.set('test-service', 'test-account', 'test-secret');
+
+ const expectedFile = path.join(
+ mockDir.resolve('data'),
+ 'backstage-cli',
+ 'auth-secrets',
+ encodeURIComponent('test-service'),
+ `${encodeURIComponent('test-account')}.secret`,
+ );
+
+ const stats = await fs.stat(expectedFile);
+ const mode = stats.mode & 0o777;
+ expect(mode).toBe(0o600);
+ });
+
+ it('should encode service and account names in file path', async () => {
+ const store = await getSecretStore();
+ await store.set('my-service/test', 'my-account@test', 'test-secret');
+
+ const result = await store.get('my-service/test', 'my-account@test');
+ expect(result).toBe('test-secret');
+
+ const expectedFile = path.join(
+ mockDir.resolve('data'),
+ 'backstage-cli',
+ 'auth-secrets',
+ encodeURIComponent('my-service/test'),
+ `${encodeURIComponent('my-account@test')}.secret`,
+ );
+ expect(await fs.pathExists(expectedFile)).toBe(true);
+ });
+
+ it('should handle unicode characters in service and account names', async () => {
+ const store = await getSecretStore();
+ await store.set('service-测试', 'account-🚀', 'test-secret');
+
+ const result = await store.get('service-测试', 'account-🚀');
+ expect(result).toBe('test-secret');
+ });
+
+ it('should handle multiple secrets for same service', async () => {
+ const store = await getSecretStore();
+ await store.set('test-service', 'account1', 'secret1');
+ await store.set('test-service', 'account2', 'secret2');
+
+ const result1 = await store.get('test-service', 'account1');
+ const result2 = await store.get('test-service', 'account2');
+
+ expect(result1).toBe('secret1');
+ expect(result2).toBe('secret2');
+ });
+
+ it('should handle multiple services', async () => {
+ const store = await getSecretStore();
+ await store.set('service1', 'account', 'secret1');
+ await store.set('service2', 'account', 'secret2');
+
+ const result1 = await store.get('service1', 'account');
+ const result2 = await store.get('service2', 'account');
+
+ expect(result1).toBe('secret1');
+ expect(result2).toBe('secret2');
+ });
+
+ it('should update existing secrets', async () => {
+ const store = await getSecretStore();
+ await store.set('test-service', 'test-account', 'old-secret');
+ await store.set('test-service', 'test-account', 'new-secret');
+
+ const result = await store.get('test-service', 'test-account');
+ expect(result).toBe('new-secret');
+ });
+
+ it('should handle empty string secrets', async () => {
+ const store = await getSecretStore();
+ await store.set('test-service', 'test-account', '');
+
+ const result = await store.get('test-service', 'test-account');
+ expect(result).toBe('');
+ });
+
+ it('should handle very long secrets', async () => {
+ const store = await getSecretStore();
+ const longSecret = 'a'.repeat(10000);
+ await store.set('test-service', 'test-account', longSecret);
+
+ const result = await store.get('test-service', 'test-account');
+ expect(result).toBe(longSecret);
+ });
+
+ it('should use XDG_DATA_HOME when set', async () => {
+ const customDataHome = mockDir.resolve('custom-data');
+ process.env.XDG_DATA_HOME = customDataHome;
+ resetSecretStore();
+
+ const store = await getSecretStore();
+ await store.set('test-service', 'test-account', 'test-secret');
+
+ const expectedFile = path.join(
+ customDataHome,
+ 'backstage-cli',
+ 'auth-secrets',
+ encodeURIComponent('test-service'),
+ `${encodeURIComponent('test-account')}.secret`,
+ );
+ expect(await fs.pathExists(expectedFile)).toBe(true);
+
+ const result = await store.get('test-service', 'test-account');
+ expect(result).toBe('test-secret');
+ });
+ });
+
+ describe('getSecretStore singleton', () => {
+ it('should return the same instance on multiple calls', async () => {
+ const store1 = await getSecretStore();
+ const store2 = await getSecretStore();
+
+ expect(store1).toBe(store2);
+ });
+
+ it('should create new instance after reset', async () => {
+ const store1 = await getSecretStore();
+ resetSecretStore();
+ const store2 = await getSecretStore();
+
+ expect(store1).not.toBe(store2);
+ });
+ });
+
+ describe('fallback behavior', () => {
+ it('should fall back to FileSecretStore when keytar is not available', async () => {
+ const store = await getSecretStore();
+ await store.set('test-service', 'test-account', 'test-secret');
+
+ const result = await store.get('test-service', 'test-account');
+ expect(result).toBe('test-secret');
+
+ const expectedFile = path.join(
+ mockDir.resolve('data'),
+ 'backstage-cli',
+ 'auth-secrets',
+ encodeURIComponent('test-service'),
+ `${encodeURIComponent('test-account')}.secret`,
+ );
+ expect(await fs.pathExists(expectedFile)).toBe(true);
+ });
+ });
+});
diff --git a/packages/cli-module-auth/src/lib/storage.test.ts b/packages/cli-module-auth/src/lib/storage.test.ts
new file mode 100644
index 0000000000..042b0eb72a
--- /dev/null
+++ b/packages/cli-module-auth/src/lib/storage.test.ts
@@ -0,0 +1,485 @@
+/*
+ * Copyright 2025 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 fs from 'fs-extra';
+import path from 'node:path';
+import { NotFoundError } from '@backstage/errors';
+import { createMockDirectory } from '@backstage/backend-test-utils';
+import {
+ getAllInstances,
+ getSelectedInstance,
+ getInstanceByName,
+ getInstanceMetadata,
+ updateInstanceMetadata,
+ upsertInstance,
+ removeInstance,
+ setSelectedInstance,
+ withMetadataLock,
+ StoredInstance,
+} from './storage';
+
+const mockDir = createMockDirectory();
+
+describe('storage', () => {
+ const mockInstance1: StoredInstance = {
+ name: 'production',
+ baseUrl: 'https://backstage.example.com',
+ clientId: 'prod-client',
+ issuedAt: Date.now(),
+ accessTokenExpiresAt: Date.now() + 3600_000,
+ selected: true,
+ };
+
+ const mockInstance2: StoredInstance = {
+ name: 'staging',
+ baseUrl: 'https://staging.backstage.example.com',
+ clientId: 'staging-client',
+ issuedAt: Date.now(),
+ accessTokenExpiresAt: Date.now() + 3600_000,
+ selected: false,
+ };
+
+ beforeEach(() => {
+ mockDir.clear();
+ process.env.XDG_CONFIG_HOME = mockDir.resolve('config');
+ });
+
+ afterEach(() => {
+ delete process.env.XDG_CONFIG_HOME;
+ });
+
+ describe('getAllInstances', () => {
+ it('should return empty array if file does not exist or is empty', async () => {
+ const result1 = await getAllInstances();
+ expect(result1).toEqual({ instances: [], selected: undefined });
+
+ mockDir.setContent({
+ 'config/backstage-cli/auth-instances.yaml': '',
+ });
+
+ const result2 = await getAllInstances();
+ expect(result2).toEqual({ instances: [], selected: undefined });
+ });
+
+ it('should parse and return instances from YAML', async () => {
+ mockDir.setContent({
+ 'config/backstage-cli/auth-instances.yaml': `instances:
+ - name: production
+ baseUrl: https://backstage.example.com
+ clientId: prod-client
+ issuedAt: ${mockInstance1.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance1.accessTokenExpiresAt}
+ selected: true
+ - name: staging
+ baseUrl: https://staging.backstage.example.com
+ clientId: staging-client
+ issuedAt: ${mockInstance2.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance2.accessTokenExpiresAt}
+`,
+ });
+
+ const result = await getAllInstances();
+
+ expect(result.instances).toHaveLength(2);
+ expect(result.selected?.name).toBe('production');
+ });
+
+ it('should select first instance if none marked as selected', async () => {
+ mockDir.setContent({
+ 'config/backstage-cli/auth-instances.yaml': `instances:
+ - name: production
+ baseUrl: https://backstage.example.com
+ clientId: prod-client
+ issuedAt: ${mockInstance1.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance1.accessTokenExpiresAt}
+ - name: staging
+ baseUrl: https://staging.backstage.example.com
+ clientId: staging-client
+ issuedAt: ${mockInstance2.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance2.accessTokenExpiresAt}
+`,
+ });
+
+ const result = await getAllInstances();
+
+ expect(result.selected?.name).toBe('production');
+ });
+
+ it('should return empty array if YAML parsing fails', async () => {
+ mockDir.setContent({
+ 'config/backstage-cli/auth-instances.yaml': 'invalid: yaml: [',
+ });
+
+ const result = await getAllInstances();
+
+ expect(result).toEqual({ instances: [], selected: undefined });
+ });
+
+ it('should normalize selected property across instances', async () => {
+ mockDir.setContent({
+ 'config/backstage-cli/auth-instances.yaml': `instances:
+ - name: production
+ baseUrl: https://backstage.example.com
+ clientId: prod-client
+ issuedAt: ${mockInstance1.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance1.accessTokenExpiresAt}
+ selected: true
+ - name: staging
+ baseUrl: https://staging.backstage.example.com
+ clientId: staging-client
+ issuedAt: ${mockInstance2.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance2.accessTokenExpiresAt}
+ selected: true
+`,
+ });
+
+ const result = await getAllInstances();
+
+ const selectedCount = result.instances.filter(i => i.selected).length;
+ expect(selectedCount).toBe(1);
+ });
+ });
+
+ describe('getSelectedInstance', () => {
+ it('should return instance by name if provided', async () => {
+ mockDir.setContent({
+ 'config/backstage-cli/auth-instances.yaml': `instances:
+ - name: production
+ baseUrl: https://backstage.example.com
+ clientId: prod-client
+ issuedAt: ${mockInstance1.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance1.accessTokenExpiresAt}
+`,
+ });
+
+ const result = await getSelectedInstance('production');
+
+ expect(result.name).toBe('production');
+ });
+
+ it('should return selected instance if no name provided', async () => {
+ mockDir.setContent({
+ 'config/backstage-cli/auth-instances.yaml': `instances:
+ - name: production
+ baseUrl: https://backstage.example.com
+ clientId: prod-client
+ issuedAt: ${mockInstance1.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance1.accessTokenExpiresAt}
+ - name: staging
+ baseUrl: https://staging.backstage.example.com
+ clientId: staging-client
+ issuedAt: ${mockInstance2.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance2.accessTokenExpiresAt}
+ selected: true
+`,
+ });
+
+ const result = await getSelectedInstance();
+
+ expect(result.name).toBe('staging');
+ });
+
+ it('should throw error if no instances exist', async () => {
+ await expect(getSelectedInstance()).rejects.toThrow(
+ 'No instances found. Run "auth login" to authenticate first.',
+ );
+ });
+ });
+
+ describe('getInstanceByName', () => {
+ it('should return instance with matching name', async () => {
+ mockDir.setContent({
+ 'config/backstage-cli/auth-instances.yaml': `instances:
+ - name: production
+ baseUrl: https://backstage.example.com
+ clientId: prod-client
+ issuedAt: ${mockInstance1.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance1.accessTokenExpiresAt}
+`,
+ });
+
+ const result = await getInstanceByName('production');
+
+ expect(result.name).toBe('production');
+ });
+
+ it('should throw NotFoundError if instance does not exist', async () => {
+ await expect(getInstanceByName('nonexistent')).rejects.toThrow(
+ NotFoundError,
+ );
+ await expect(getInstanceByName('nonexistent')).rejects.toThrow(
+ "Instance 'nonexistent' not found",
+ );
+ });
+ });
+
+ describe('upsertInstance', () => {
+ it('should add new instance if it does not exist', async () => {
+ await upsertInstance(mockInstance1);
+
+ const result = await getAllInstances();
+ expect(result.instances).toHaveLength(1);
+ expect(result.instances[0].name).toBe('production');
+ });
+
+ it('should update existing instance', async () => {
+ mockDir.setContent({
+ 'config/backstage-cli/auth-instances.yaml': `instances:
+ - name: production
+ baseUrl: https://backstage.example.com
+ clientId: prod-client
+ issuedAt: ${mockInstance1.issuedAt}
+ accessTokenExpiresAt: ${mockInstance1.accessTokenExpiresAt}
+`,
+ });
+
+ const updatedInstance = {
+ ...mockInstance1,
+ clientId: 'updated-client',
+ };
+
+ await upsertInstance(updatedInstance);
+
+ const result = await getInstanceByName('production');
+ expect(result.clientId).toBe('updated-client');
+ });
+ });
+
+ describe('removeInstance', () => {
+ it('should remove instance with matching name', async () => {
+ mockDir.setContent({
+ 'config/backstage-cli/auth-instances.yaml': `instances:
+ - name: production
+ baseUrl: https://backstage.example.com
+ clientId: prod-client
+ issuedAt: ${mockInstance1.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance1.accessTokenExpiresAt}
+ - name: staging
+ baseUrl: https://staging.backstage.example.com
+ clientId: staging-client
+ issuedAt: ${mockInstance2.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance2.accessTokenExpiresAt}
+`,
+ });
+
+ await removeInstance('production');
+
+ const result = await getAllInstances();
+ expect(result.instances).toHaveLength(1);
+ expect(result.instances[0].name).toBe('staging');
+ });
+
+ it('should do nothing if instance does not exist', async () => {
+ await removeInstance('nonexistent');
+
+ const result = await getAllInstances();
+ expect(result.instances).toHaveLength(0);
+ });
+ });
+
+ describe('setSelectedInstance', () => {
+ it('should set selected instance and unselect others', async () => {
+ mockDir.setContent({
+ 'config/backstage-cli/auth-instances.yaml': `instances:
+ - name: production
+ baseUrl: https://backstage.example.com
+ clientId: prod-client
+ issuedAt: ${mockInstance1.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance1.accessTokenExpiresAt}
+ selected: true
+ - name: staging
+ baseUrl: https://staging.backstage.example.com
+ clientId: staging-client
+ issuedAt: ${mockInstance2.issuedAt}
+
+ accessTokenExpiresAt: ${mockInstance2.accessTokenExpiresAt}
+`,
+ });
+
+ await setSelectedInstance('staging');
+
+ const result = await getAllInstances();
+ expect(result.selected?.name).toBe('staging');
+
+ const prodInstance = result.instances.find(i => i.name === 'production');
+ expect(prodInstance?.selected).toBe(false);
+ });
+
+ it('should throw error if instance does not exist', async () => {
+ await expect(setSelectedInstance('nonexistent')).rejects.toThrow(
+ "Unknown instance 'nonexistent'",
+ );
+ });
+ });
+
+ describe('withMetadataLock', () => {
+ it('should acquire and release lock', async () => {
+ const callback = jest.fn().mockResolvedValue('result');
+ const result = await withMetadataLock(callback);
+
+ expect(callback).toHaveBeenCalled();
+ expect(result).toBe('result');
+ });
+
+ it('should release lock even if callback throws', async () => {
+ const error = new Error('Test error');
+ const callback = jest.fn().mockRejectedValue(error);
+
+ await expect(withMetadataLock(callback)).rejects.toThrow(error);
+
+ // Lock should still be released, allowing subsequent calls
+ const callback2 = jest.fn().mockResolvedValue('result');
+ await expect(withMetadataLock(callback2)).resolves.toBe('result');
+ });
+ });
+
+ describe('getInstanceMetadata', () => {
+ it('should return undefined when no metadata set', async () => {
+ await upsertInstance(mockInstance1);
+
+ const result = await getInstanceMetadata('production', 'someKey');
+ expect(result).toBeUndefined();
+ });
+
+ it('should return metadata value for a key', async () => {
+ await upsertInstance(mockInstance1);
+ await updateInstanceMetadata('production', 'myKey', 'myValue');
+
+ const result = await getInstanceMetadata('production', 'myKey');
+ expect(result).toBe('myValue');
+ });
+
+ it('should throw NotFoundError for unknown instance', async () => {
+ await expect(getInstanceMetadata('nonexistent', 'key')).rejects.toThrow(
+ NotFoundError,
+ );
+ });
+ });
+
+ describe('updateInstanceMetadata', () => {
+ it('should set a metadata value', async () => {
+ await upsertInstance(mockInstance1);
+ await updateInstanceMetadata('production', 'key1', 'value1');
+
+ const result = await getInstanceMetadata('production', 'key1');
+ expect(result).toBe('value1');
+ });
+
+ it('should preserve existing metadata keys', async () => {
+ await upsertInstance(mockInstance1);
+ await updateInstanceMetadata('production', 'key1', 'value1');
+ await updateInstanceMetadata('production', 'key2', 'value2');
+
+ const result1 = await getInstanceMetadata('production', 'key1');
+ const result2 = await getInstanceMetadata('production', 'key2');
+ expect(result1).toBe('value1');
+ expect(result2).toBe('value2');
+ });
+
+ it('should throw NotFoundError for unknown instance', async () => {
+ await expect(
+ updateInstanceMetadata('nonexistent', 'key', 'value'),
+ ).rejects.toThrow(NotFoundError);
+ });
+
+ it('should remove instance along with its metadata', async () => {
+ await upsertInstance(mockInstance1);
+ await updateInstanceMetadata('production', 'key1', 'value1');
+ await removeInstance('production');
+
+ const { instances } = await getAllInstances();
+ expect(instances.find(i => i.name === 'production')).toBeUndefined();
+
+ await upsertInstance(mockInstance1);
+ const result = await getInstanceMetadata('production', 'key1');
+ expect(result).toBeUndefined();
+ });
+ });
+
+ describe('file path resolution', () => {
+ it('should use XDG_CONFIG_HOME when set', async () => {
+ const customConfigHome = mockDir.resolve('custom-config');
+ process.env.XDG_CONFIG_HOME = customConfigHome;
+
+ await upsertInstance(mockInstance1);
+
+ const result = await getAllInstances();
+ expect(result.instances).toHaveLength(1);
+ expect(result.instances[0].name).toBe('production');
+
+ // Verify file was created in custom location
+ const expectedFile = path.join(
+ customConfigHome,
+ 'backstage-cli',
+ 'auth-instances.yaml',
+ );
+ expect(await fs.pathExists(expectedFile)).toBe(true);
+ });
+
+ it('should create files with correct permissions (0o600)', async () => {
+ // File permissions are not reliably enforced on Windows
+ if (process.platform === 'win32') {
+ return;
+ }
+
+ await upsertInstance(mockInstance1);
+
+ const file = path.join(
+ mockDir.resolve('config'),
+ 'backstage-cli',
+ 'auth-instances.yaml',
+ );
+ const stats = await fs.stat(file);
+ const mode = stats.mode & 0o777;
+ expect(mode).toBe(0o600);
+ });
+
+ it('should handle invalid schema and missing fields gracefully', async () => {
+ mockDir.setContent({
+ 'config/backstage-cli/auth-instances.yaml': `instances:
+ - name: ""
+ baseUrl: not-a-url
+ clientId: ""
+`,
+ });
+
+ const result1 = await getAllInstances();
+ expect(result1.instances).toHaveLength(0);
+
+ mockDir.setContent({
+ 'config/backstage-cli/auth-instances.yaml': `instances:
+ - name: production
+`,
+ });
+
+ const result2 = await getAllInstances();
+ expect(result2.instances).toHaveLength(0);
+ });
+ });
+});
diff --git a/packages/cli-module-auth/src/lib/storage.ts b/packages/cli-module-auth/src/lib/storage.ts
new file mode 100644
index 0000000000..c5d275149c
--- /dev/null
+++ b/packages/cli-module-auth/src/lib/storage.ts
@@ -0,0 +1,215 @@
+/*
+ * Copyright 2025 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 { NotFoundError } from '@backstage/errors';
+import fs from 'fs-extra';
+import os from 'node:os';
+import path from 'node:path';
+import lockfile from 'proper-lockfile';
+import YAML from 'yaml';
+import { z } from 'zod/v3';
+
+export type StoredInstance = {
+ name: string;
+ baseUrl: string;
+ clientId: string;
+ issuedAt: number;
+ accessTokenExpiresAt: number;
+ selected?: boolean;
+ metadata?: Record;
+};
+
+const METADATA_FILE = 'auth-instances.yaml';
+
+const INSTANCE_NAME_PATTERN = /^[a-zA-Z0-9._:@-]+$/;
+
+const storedInstanceSchema = z.object({
+ name: z
+ .string()
+ .min(1)
+ .regex(INSTANCE_NAME_PATTERN, 'Instance name contains invalid characters'),
+ baseUrl: z.string().url(),
+ clientId: z.string().min(1),
+ issuedAt: z.number().int().nonnegative(),
+ accessTokenExpiresAt: z.number().int().nonnegative(),
+ selected: z.boolean().optional(),
+ metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+const authYamlSchema = z.object({
+ instances: z.array(storedInstanceSchema).default([]),
+});
+
+function getMetadataFilePath(): string {
+ const root =
+ process.env.XDG_CONFIG_HOME ||
+ (process.platform === 'win32'
+ ? process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming')
+ : path.join(os.homedir(), '.config'));
+
+ return path.join(root, 'backstage-cli', METADATA_FILE);
+}
+
+async function readAll(): Promise<{ instances: StoredInstance[] }> {
+ const file = getMetadataFilePath();
+ if (!(await fs.pathExists(file))) {
+ return { instances: [] };
+ }
+ const text = await fs.readFile(file, 'utf8');
+ if (!text.trim()) {
+ return { instances: [] };
+ }
+ try {
+ const doc = YAML.parse(text);
+ const parsed = authYamlSchema.safeParse(doc);
+ if (parsed.success) {
+ return parsed.data;
+ }
+ return { instances: [] };
+ } catch {
+ return { instances: [] };
+ }
+}
+
+async function writeAll(data: { instances: StoredInstance[] }): Promise {
+ const file = getMetadataFilePath();
+ await fs.ensureDir(path.dirname(file));
+ const yaml = YAML.stringify(authYamlSchema.parse(data), { indentSeq: false });
+ await fs.writeFile(file, yaml, { encoding: 'utf8', mode: 0o600 });
+}
+
+export async function getAllInstances(): Promise<{
+ instances: StoredInstance[];
+ selected: StoredInstance | undefined;
+}> {
+ const { instances } = await readAll();
+ if (instances.length === 0) {
+ return { instances: [], selected: undefined };
+ }
+ const selected = instances.find(i => i.selected) ?? instances[0];
+ return {
+ instances: instances.map(i => ({
+ ...i,
+ selected: i.name === selected.name,
+ })),
+ selected,
+ };
+}
+
+export async function getSelectedInstance(
+ instanceName?: string,
+): Promise {
+ if (instanceName) {
+ return await getInstanceByName(instanceName);
+ }
+ const { selected } = await getAllInstances();
+ if (!selected) {
+ throw new Error(
+ 'No instances found. Run "auth login" to authenticate first.',
+ );
+ }
+ return selected;
+}
+
+export async function getInstanceByName(name: string): Promise {
+ const { instances } = await readAll();
+ const instance = instances.find(i => i.name === name);
+ if (!instance) {
+ throw new NotFoundError(`Instance '${name}' not found`);
+ }
+ return instance;
+}
+
+export async function upsertInstance(instance: StoredInstance): Promise {
+ const data = await readAll();
+ const idx = data.instances.findIndex(i => i.name === instance.name);
+ if (idx === -1) {
+ data.instances.push(instance);
+ } else {
+ data.instances[idx] = instance;
+ }
+ await writeAll(data);
+}
+
+export async function removeInstance(name: string): Promise {
+ const data = await readAll();
+ const next = data.instances.filter(i => i.name !== name);
+ if (next.length !== data.instances.length) {
+ await writeAll({ instances: next });
+ }
+}
+
+export async function setSelectedInstance(name: string): Promise {
+ return withMetadataLock(async () => {
+ const data = await readAll();
+ let found = false;
+ data.instances = data.instances.map(i => {
+ if (i.name === name) {
+ found = true;
+ return { ...i, selected: true };
+ }
+ const { selected, ...rest } = i;
+ return { ...rest, selected: false };
+ });
+ if (!found) {
+ throw new Error(`Unknown instance '${name}'`);
+ }
+ await writeAll(data);
+ });
+}
+
+export async function getInstanceMetadata(
+ instanceName: string,
+ key: string,
+): Promise {
+ const instance = await getInstanceByName(instanceName);
+ return instance.metadata?.[key];
+}
+
+export async function updateInstanceMetadata(
+ instanceName: string,
+ key: string,
+ value: unknown,
+): Promise {
+ return withMetadataLock(async () => {
+ const data = await readAll();
+ const idx = data.instances.findIndex(i => i.name === instanceName);
+ if (idx === -1) {
+ throw new NotFoundError(`Instance '${instanceName}' not found`);
+ }
+ data.instances[idx] = {
+ ...data.instances[idx],
+ metadata: { ...data.instances[idx].metadata, [key]: value },
+ };
+ await writeAll(data);
+ });
+}
+
+export async function withMetadataLock(fn: () => Promise): Promise {
+ const file = getMetadataFilePath();
+ await fs.ensureDir(path.dirname(file));
+ if (!(await fs.pathExists(file))) {
+ await fs.writeFile(file, '', { encoding: 'utf8', mode: 0o600 });
+ }
+ const release = await lockfile.lock(file, {
+ retries: { retries: 5, factor: 1.5, minTimeout: 100, maxTimeout: 1000 },
+ });
+ try {
+ return await fn();
+ } finally {
+ await release();
+ }
+}
diff --git a/packages/cli-module-build/.eslintrc.js b/packages/cli-module-build/.eslintrc.js
new file mode 100644
index 0000000000..a070dc55ee
--- /dev/null
+++ b/packages/cli-module-build/.eslintrc.js
@@ -0,0 +1,3 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname, {
+ ignorePatterns: ['config/**', 'templates/**'],
+});
diff --git a/packages/cli-module-build/CHANGELOG.md b/packages/cli-module-build/CHANGELOG.md
new file mode 100644
index 0000000000..8f8ab43726
--- /dev/null
+++ b/packages/cli-module-build/CHANGELOG.md
@@ -0,0 +1,34 @@
+# @backstage/cli-module-build
+
+## 0.1.1-next.1
+
+### Patch Changes
+
+- 2e5c5f8: Bumped `glob` dependency from v7/v8/v11 to v13 to address security vulnerabilities in older versions. Bumped `rollup` from v4.27 to v4.59+ to fix a high severity path traversal vulnerability (GHSA-mw96-cpmx-2vgc).
+
+## 0.1.1-next.0
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-common@0.2.1-next.0
+ - @backstage/cli-node@0.3.1-next.0
+ - @backstage/config-loader@1.10.10-next.0
+ - @backstage/config@1.3.6
+ - @backstage/errors@1.2.7
+ - @backstage/module-federation-common@0.1.2
+
+## 0.1.0
+
+### Minor Changes
+
+- 62d0849: Added `package bundle` command to create self-contained plugin bundles for dynamic loading, to be used by the `backend-dynamic-feature-service`. Supports backend and frontend plugins, with optional `--pre-packed-dir` for batch bundling from a pre-built workspace.
+- 329f394: Initial release of the CLI module packages. Each module provides a set of commands that can be discovered automatically by `@backstage/cli` or executed standalone.
+
+### Patch Changes
+
+- Updated dependencies
+ - @backstage/cli-node@0.3.0
+ - @backstage/cli-common@0.2.0
+ - @backstage/module-federation-common@0.1.2
+ - @backstage/config-loader@1.10.9
diff --git a/packages/cli-module-build/README.md b/packages/cli-module-build/README.md
new file mode 100644
index 0000000000..355891c907
--- /dev/null
+++ b/packages/cli-module-build/README.md
@@ -0,0 +1,23 @@
+# @backstage/cli-module-build
+
+CLI module that provides build, start, and packaging commands for the Backstage CLI.
+
+## Commands
+
+| Command | Description |
+| :----------------- | :------------------------------------------------------------------------ |
+| `package build` | Build a package for production deployment or publishing |
+| `package start` | Start a package for local development |
+| `package clean` | Delete cache directories |
+| `package prepack` | Prepares a package for packaging before publishing |
+| `package postpack` | Restores the changes made by the prepack command |
+| `repo build` | Build packages in the project, excluding bundled app and backend packages |
+| `repo start` | Starts packages in the repo for local development |
+| `repo clean` | Delete cache and output directories |
+| `build-workspace` | Builds a temporary dist workspace from the provided packages |
+
+## Documentation
+
+- [Backstage Readme](https://github.com/backstage/backstage/blob/master/README.md)
+- [Backstage Documentation](https://backstage.io/docs)
+- [Build System](https://backstage.io/docs/tooling/cli/build-system)
diff --git a/packages/cli-module-build/bin/backstage-cli-module-build b/packages/cli-module-build/bin/backstage-cli-module-build
new file mode 100755
index 0000000000..68bdc76a4a
--- /dev/null
+++ b/packages/cli-module-build/bin/backstage-cli-module-build
@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/*
+ * 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.
+ */
+
+const path = require('node:path');
+
+/* eslint-disable-next-line no-restricted-syntax */
+const isLocal = require('node:fs').existsSync(
+ path.resolve(__dirname, '../src'),
+);
+
+if (isLocal) {
+ require('@backstage/cli-node/config/nodeTransform.cjs');
+}
+
+const { runCliModule } = require('@backstage/cli-node');
+const cliModule = require(isLocal ? '../src/index' : '..').default;
+const pkg = require('../package.json');
+runCliModule({ module: cliModule, name: pkg.name, version: pkg.version });
diff --git a/packages/cli-module-build/catalog-info.yaml b/packages/cli-module-build/catalog-info.yaml
new file mode 100644
index 0000000000..65715cce2a
--- /dev/null
+++ b/packages/cli-module-build/catalog-info.yaml
@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: backstage-cli-module-build
+ title: '@backstage/cli-module-build'
+ description: CLI module for Backstage CLI
+spec:
+ lifecycle: experimental
+ type: backstage-cli-module
+ owner: tooling-maintainers
diff --git a/packages/cli-module-build/cli-report.md b/packages/cli-module-build/cli-report.md
new file mode 100644
index 0000000000..1c11022dc8
--- /dev/null
+++ b/packages/cli-module-build/cli-report.md
@@ -0,0 +1,156 @@
+## CLI Report file for "@backstage/cli-module-build"
+
+> Do not edit this file. It is a report generated by `yarn build:api-reports`
+
+### `backstage-cli-module-build`
+
+```
+Usage: @backstage/cli-module-build [options] [command]
+
+Options:
+ -V, --version
+ -h, --help
+
+Commands:
+ build-workspace
+ help [command]
+ package [command]
+ repo [command]
+```
+
+### `backstage-cli-module-build build-workspace`
+
+```
+Usage: @backstage/cli-module-build build-workspace [packages...]
+
+Options:
+ --always-pack
+ -h, --help
+```
+
+### `backstage-cli-module-build package`
+
+```
+Usage: @backstage/cli-module-build package [options] [command] [command]
+
+Options:
+ -h, --help
+
+Commands:
+ build
+ clean
+ help [command]
+ postpack
+ prepack
+ start
+```
+
+### `backstage-cli-module-build package build`
+
+```
+Usage: @backstage/cli-module-build package build
+
+Options:
+ --config
+ --minify
+ --module-federation
+ --role
+ --skip-build-dependencies
+ --stats
+ -h, --help
+```
+
+### `backstage-cli-module-build package clean`
+
+```
+Usage: @backstage/cli-module-build package clean
+
+Options:
+ -h, --help
+```
+
+### `backstage-cli-module-build package postpack`
+
+```
+Usage: @backstage/cli-module-build package postpack
+
+Options:
+ -h, --help
+```
+
+### `backstage-cli-module-build package prepack`
+
+```
+Usage: @backstage/cli-module-build package prepack
+
+Options:
+ -h, --help
+```
+
+### `backstage-cli-module-build package start`
+
+```
+Usage: @backstage/cli-module-build package start
+
+Options:
+ --check
+ --config
+ --entrypoint
+ --inspect
+ --inspect-brk
+ --link
+ --require
+ --role
+ -h, --help
+```
+
+### `backstage-cli-module-build repo`
+
+```
+Usage: @backstage/cli-module-build repo [options] [command] [command]
+
+Options:
+ -h, --help
+
+Commands:
+ build
+ clean
+ help [command]
+ start
+```
+
+### `backstage-cli-module-build repo build`
+
+```
+Usage: @backstage/cli-module-build repo build
+
+Options:
+ --all
+ --minify
+ --since
+ -h, --help
+```
+
+### `backstage-cli-module-build repo clean`
+
+```
+Usage: @backstage/cli-module-build repo clean
+
+Options:
+ -h, --help
+```
+
+### `backstage-cli-module-build repo start`
+
+```
+Usage: @backstage/cli-module-build repo start [packages...]
+
+Options:
+ --config
+ --inspect
+ --inspect-brk
+ --link
+ --plugin
+ --require
+ -h, --help
+```
diff --git a/packages/cli-module-build/config/webpack-public-path.js b/packages/cli-module-build/config/webpack-public-path.js
new file mode 100644
index 0000000000..3e14e96eb9
--- /dev/null
+++ b/packages/cli-module-build/config/webpack-public-path.js
@@ -0,0 +1,31 @@
+/*
+ * 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.
+ */
+
+// This script is used to pick up and set the public path of the Webpack bundle
+// at runtime. The meta tag is injected by the app build, but only present in
+// the `index.html.tmpl` file. The runtime value of the meta tag is populated by
+// the app backend, when it templates the final `index.html` file.
+//
+// This is needed for additional chunks to use the correct public path, and it
+// is not possible to set the `__webpack_public_path__` variable outside of the
+// build itself. The Webpack output also does not read any tags or
+// similar, this seems to be the only way to dynamically configure the public
+// path at runtime.
+const el = document.querySelector('meta[name="backstage-public-path"]');
+const path = el?.getAttribute('content');
+if (path) {
+ __webpack_public_path__ = path;
+}
diff --git a/packages/cli-module-build/package.json b/packages/cli-module-build/package.json
new file mode 100644
index 0000000000..605df9a542
--- /dev/null
+++ b/packages/cli-module-build/package.json
@@ -0,0 +1,111 @@
+{
+ "name": "@backstage/cli-module-build",
+ "version": "0.1.1-next.1",
+ "description": "CLI module for Backstage CLI",
+ "backstage": {
+ "role": "cli-module"
+ },
+ "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-module-build"
+ },
+ "license": "Apache-2.0",
+ "main": "src/index.ts",
+ "types": "src/index.ts",
+ "bin": "bin/backstage-cli-module-build",
+ "files": [
+ "dist",
+ "bin",
+ "config",
+ "templates"
+ ],
+ "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"
+ },
+ "jest": {
+ "coveragePathIgnorePatterns": [
+ "/__fixtures__/"
+ ]
+ },
+ "dependencies": {
+ "@backstage/cli-common": "workspace:^",
+ "@backstage/cli-node": "workspace:^",
+ "@backstage/config": "workspace:^",
+ "@backstage/config-loader": "workspace:^",
+ "@backstage/errors": "workspace:^",
+ "@backstage/module-federation-common": "workspace:^",
+ "@manypkg/get-packages": "^1.1.3",
+ "@module-federation/enhanced": "^0.21.6",
+ "@pmmmwh/react-refresh-webpack-plugin": "^0.6.0",
+ "@rollup/plugin-commonjs": "^26.0.0",
+ "@rollup/plugin-json": "^6.0.0",
+ "@rollup/plugin-node-resolve": "^15.0.0",
+ "@rollup/plugin-yaml": "^4.0.0",
+ "@rspack/core": "^1.4.11",
+ "@rspack/dev-server": "^1.1.4",
+ "@rspack/plugin-react-refresh": "^1.4.3",
+ "@swc/core": "^1.15.6",
+ "bfj": "^9.0.2",
+ "buffer": "^6.0.3",
+ "chalk": "^4.0.0",
+ "chokidar": "^3.3.1",
+ "cleye": "^2.3.0",
+ "cross-spawn": "^7.0.3",
+ "css-loader": "^6.5.1",
+ "ctrlc-windows": "^2.1.0",
+ "esbuild-loader": "^4.0.0",
+ "eslint-rspack-plugin": "^4.2.1",
+ "eslint-webpack-plugin": "^4.2.0",
+ "fork-ts-checker-webpack-plugin": "^9.0.0",
+ "fs-extra": "^11.2.0",
+ "glob": "^13.0.0",
+ "html-webpack-plugin": "^5.6.3",
+ "lodash": "^4.17.21",
+ "mini-css-extract-plugin": "^2.4.2",
+ "node-stdlib-browser": "^1.3.1",
+ "npm-packlist": "^5.0.0",
+ "p-queue": "^6.6.2",
+ "postcss": "^8.1.0",
+ "postcss-import": "^16.1.0",
+ "process": "^0.11.10",
+ "raw-loader": "^4.0.2",
+ "react-dev-utils": "^12.0.0-next.60",
+ "react-refresh": "^0.18.0",
+ "rollup": "^4.59.0",
+ "rollup-plugin-dts": "^6.1.0",
+ "rollup-plugin-esbuild": "^6.1.1",
+ "rollup-plugin-postcss": "^4.0.0",
+ "rollup-pluginutils": "^2.8.2",
+ "shell-quote": "^1.8.1",
+ "style-loader": "^3.3.1",
+ "swc-loader": "^0.2.3",
+ "tar": "^7.5.6",
+ "ts-checker-rspack-plugin": "^1.1.5",
+ "ts-morph": "^24.0.0",
+ "util": "^0.12.3",
+ "webpack": "~5.105.0",
+ "webpack-dev-server": "^5.0.0",
+ "yml-loader": "^2.1.0",
+ "yn": "^4.0.0"
+ },
+ "devDependencies": {
+ "@backstage/backend-test-utils": "workspace:^",
+ "@backstage/cli": "workspace:^",
+ "@types/fs-extra": "^11.0.0",
+ "@types/lodash": "^4.14.151",
+ "@types/npm-packlist": "^3.0.0",
+ "@types/shell-quote": "^1.7.5"
+ }
+}
diff --git a/packages/cli-module-build/report.api.md b/packages/cli-module-build/report.api.md
new file mode 100644
index 0000000000..34634dd448
--- /dev/null
+++ b/packages/cli-module-build/report.api.md
@@ -0,0 +1,13 @@
+## API Report File for "@backstage/cli-module-build"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { CliModule } from '@backstage/cli-node';
+
+// @public (undocumented)
+const _default: CliModule;
+export default _default;
+
+// (No @packageDocumentation comment for this package)
+```
diff --git a/packages/cli/src/modules/build/commands/buildWorkspace.ts b/packages/cli-module-build/src/commands/buildWorkspace.ts
similarity index 92%
rename from packages/cli/src/modules/build/commands/buildWorkspace.ts
rename to packages/cli-module-build/src/commands/buildWorkspace.ts
index 649171d7d8..0abd9e5307 100644
--- a/packages/cli/src/modules/build/commands/buildWorkspace.ts
+++ b/packages/cli-module-build/src/commands/buildWorkspace.ts
@@ -17,9 +17,9 @@
import fs from 'fs-extra';
import { cli } from 'cleye';
import { createDistWorkspace } from '../lib/packager';
-import type { CommandContext } from '../../../wiring/types';
+import type { CliCommandContext } from '@backstage/cli-node';
-export default async ({ args, info }: CommandContext) => {
+export default async ({ args, info }: CliCommandContext) => {
// Normalize legacy --alwaysYarnPack alias (a genuinely different name, not
// just a casing variant — type-flag handles camelCase/kebab-case natively)
const normalizedArgs = args.map(a => {
@@ -38,6 +38,7 @@ export default async ({ args, info }: CommandContext) => {
} = cli(
{
help: { ...info, usage: `${info.usage} [packages...]` },
+ booleanFlagNegation: true,
parameters: ['', '[packages...]'],
flags: {
alwaysPack: {
diff --git a/packages/cli/src/modules/build/commands/package/build/command.ts b/packages/cli-module-build/src/commands/package/build/command.ts
similarity index 96%
rename from packages/cli/src/modules/build/commands/package/build/command.ts
rename to packages/cli-module-build/src/commands/package/build/command.ts
index 8c802fe2b5..07c6e3a8d7 100644
--- a/packages/cli/src/modules/build/commands/package/build/command.ts
+++ b/packages/cli-module-build/src/commands/package/build/command.ts
@@ -29,9 +29,9 @@ import { buildFrontend } from '../../../lib/buildFrontend';
import { buildBackend } from '../../../lib/buildBackend';
import { isValidUrl } from '../../../lib/urls';
import chalk from 'chalk';
-import type { CommandContext } from '../../../../../wiring/types';
+import type { CliCommandContext } from '@backstage/cli-node';
-export default async ({ args, info }: CommandContext) => {
+export default async ({ args, info }: CliCommandContext) => {
const {
flags: {
role,
@@ -44,6 +44,7 @@ export default async ({ args, info }: CommandContext) => {
} = cli(
{
help: info,
+ booleanFlagNegation: true,
flags: {
role: {
type: String,
diff --git a/packages/cli/src/modules/build/commands/package/build/index.ts b/packages/cli-module-build/src/commands/package/build/index.ts
similarity index 100%
rename from packages/cli/src/modules/build/commands/package/build/index.ts
rename to packages/cli-module-build/src/commands/package/build/index.ts
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/.gitignore b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/.gitignore
new file mode 100644
index 0000000000..eb67c88369
--- /dev/null
+++ b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/.gitignore
@@ -0,0 +1 @@
+!dist*
\ No newline at end of file
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/packages/foo-node/dist/index.js b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/packages/foo-node/dist/index.js
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/packages/foo-node/package.json b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/packages/foo-node/package.json
new file mode 100644
index 0000000000..5c2babcbc2
--- /dev/null
+++ b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/packages/foo-node/package.json
@@ -0,0 +1,5 @@
+{
+ "name": "@scope/foo-node",
+ "version": "1.0.0",
+ "main": "dist/index.js"
+}
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/plugins/foo-backend/dist/index.js b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/plugins/foo-backend/dist/index.js
new file mode 100644
index 0000000000..b76e7a9d93
--- /dev/null
+++ b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/plugins/foo-backend/dist/index.js
@@ -0,0 +1 @@
+module.exports = { default: { $$type: '@backstage/BackendFeature' } };
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/plugins/foo-backend/package.json b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/plugins/foo-backend/package.json
new file mode 100644
index 0000000000..53ea4fbdb8
--- /dev/null
+++ b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/plugins/foo-backend/package.json
@@ -0,0 +1,8 @@
+{
+ "name": "@scope/plugin-foo-backend",
+ "version": "1.0.0",
+ "main": "dist/index.js",
+ "dependencies": {
+ "@scope/plugin-foo-common": "1.0.0"
+ }
+}
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/plugins/foo-common/dist/index.js b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/plugins/foo-common/dist/index.js
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/plugins/foo-common/package.json b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/plugins/foo-common/package.json
new file mode 100644
index 0000000000..868fad5eaf
--- /dev/null
+++ b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/backend/plugins/foo-common/package.json
@@ -0,0 +1,5 @@
+{
+ "name": "@scope/plugin-foo-common",
+ "version": "1.0.0",
+ "main": "dist/index.js"
+}
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/packages/foo-web/dist/index.js b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/packages/foo-web/dist/index.js
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/packages/foo-web/package.json b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/packages/foo-web/package.json
new file mode 100644
index 0000000000..1ae64d251d
--- /dev/null
+++ b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/packages/foo-web/package.json
@@ -0,0 +1,5 @@
+{
+ "name": "@scope/foo-web",
+ "version": "1.0.0",
+ "main": "dist/index.js"
+}
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/plugins/foo-react/dist/index.js b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/plugins/foo-react/dist/index.js
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/plugins/foo-react/package.json b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/plugins/foo-react/package.json
new file mode 100644
index 0000000000..80abb7d0b8
--- /dev/null
+++ b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/plugins/foo-react/package.json
@@ -0,0 +1,5 @@
+{
+ "name": "@scope/plugin-foo-react",
+ "version": "1.0.0",
+ "main": "dist/index.js"
+}
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/plugins/foo/dist/index.js b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/plugins/foo/dist/index.js
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/plugins/foo/package.json b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/plugins/foo/package.json
new file mode 100644
index 0000000000..e5be9d71e5
--- /dev/null
+++ b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/dist-workspace/frontend/plugins/foo/package.json
@@ -0,0 +1,8 @@
+{
+ "name": "@scope/plugin-foo",
+ "version": "1.0.0",
+ "main": "dist/index.js",
+ "dependencies": {
+ "@scope/plugin-foo-react": "1.0.0"
+ }
+}
diff --git a/packages/cli/templates/backend-plugin/src/setupTests.ts b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/dist/@mf-types/index.d.ts
similarity index 100%
rename from packages/cli/templates/backend-plugin/src/setupTests.ts
rename to packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/dist/@mf-types/index.d.ts
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/dist/index.js b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/dist/index.js
new file mode 100644
index 0000000000..8b13789179
--- /dev/null
+++ b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/dist/index.js
@@ -0,0 +1 @@
+
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/dist/remoteEntry.js b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/dist/remoteEntry.js
new file mode 100644
index 0000000000..94f616153c
--- /dev/null
+++ b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/dist/remoteEntry.js
@@ -0,0 +1 @@
+// Module Federation remote entry
diff --git a/packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/package.json b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/package.json
new file mode 100644
index 0000000000..96efb68a2f
--- /dev/null
+++ b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/package.json
@@ -0,0 +1,33 @@
+{
+ "name": "@scope/plugin-foo",
+ "version": "1.0.0",
+ "backstage": {
+ "role": "frontend-plugin",
+ "pluginId": "foo"
+ },
+ "keywords": [
+ "backstage"
+ ],
+ "license": "Apache-2.0",
+ "exports": {
+ ".": {},
+ "./alpha": {},
+ "./package.json": "./package.json"
+ },
+ "main": "src/index.ts",
+ "module": "src/index.ts",
+ "types": "src/index.ts",
+ "typesVersions": {
+ "*": {
+ "alpha": [
+ "src/alpha.ts"
+ ]
+ }
+ },
+ "dependencies": {
+ "@backstage/catalog-model": "^1.7.6"
+ },
+ "devDependencies": {
+ "typescript": "^5.0.0"
+ }
+}
diff --git a/packages/cli/src/modules/build/lib/packager/index.ts b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/src/index.ts
similarity index 84%
rename from packages/cli/src/modules/build/lib/packager/index.ts
rename to packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/src/index.ts
index 75f3fdf71d..e512e4ba83 100644
--- a/packages/cli/src/modules/build/lib/packager/index.ts
+++ b/packages/cli-module-build/src/commands/package/bundle/__fixtures__/packed/frontend/src/index.ts
@@ -1,5 +1,5 @@
/*
- * Copyright 2022 The Backstage Authors
+ * Copyright 2026 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,4 +14,4 @@
* limitations under the License.
*/
-export { createDistWorkspace } from './createDistWorkspace';
+export {};
diff --git a/packages/cli-module-build/src/commands/package/bundle/command.test.ts b/packages/cli-module-build/src/commands/package/bundle/command.test.ts
new file mode 100644
index 0000000000..642e220224
--- /dev/null
+++ b/packages/cli-module-build/src/commands/package/bundle/command.test.ts
@@ -0,0 +1,1126 @@
+/*
+ * Copyright 2026 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.
+ */
+
+/* eslint jest/expect-expect: ["warn", { "assertFunctionNames": ["expect", "expectPathExists"] }] */
+
+import { createMockDirectory } from '@backstage/backend-test-utils';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import os from 'node:os';
+import { join as joinPath } from 'node:path';
+
+import { targetPaths } from '@backstage/cli-common';
+import {
+ bundleCommand,
+ filterBundleConfigSchemas,
+ postProcessBundlePackageJson,
+} from './command';
+
+const fixturesDir = joinPath(__dirname, '__fixtures__');
+
+const mockCreateDistWorkspace = jest.fn();
+const mockPackToDirectory = jest.fn();
+const mockBuildFrontend = jest.fn();
+const mockRun = jest.fn();
+const mockRunOutput = jest.fn();
+const mockListTargetPackages = jest.fn();
+const mockLoadConfigSchema = jest.fn();
+const mockCreateRequire = jest.fn();
+
+// Mock external dependencies
+
+jest.mock('@backstage/cli-common', () => ({
+ ...jest.requireActual('@backstage/cli-common'),
+ targetPaths: {
+ dir: '',
+ rootDir: '',
+ resolve: jest.fn(),
+ },
+ run: (...args: unknown[]) => mockRun(...args),
+ runOutput: (...args: unknown[]) => mockRunOutput(...args),
+}));
+
+jest.mock('../../../lib/packager', () => ({
+ ...jest.requireActual('../../../lib/packager'),
+ createDistWorkspace: (...args: unknown[]) => mockCreateDistWorkspace(...args),
+ packToDirectory: (...args: unknown[]) => mockPackToDirectory(...args),
+}));
+
+jest.mock('../../../lib/buildFrontend', () => ({
+ buildFrontend: (...args: unknown[]) => mockBuildFrontend(...args),
+}));
+
+jest.mock('@backstage/cli-node', () => {
+ const actual = jest.requireActual('@backstage/cli-node');
+ return {
+ ...actual,
+ PackageGraph: Object.assign(actual.PackageGraph, {
+ listTargetPackages: (...args: unknown[]) =>
+ mockListTargetPackages(...args),
+ }),
+ };
+});
+
+jest.mock('@backstage/config-loader', () => ({
+ loadConfigSchema: (...args: unknown[]) => mockLoadConfigSchema(...args),
+}));
+
+jest.mock('node:module', () => ({
+ ...jest.requireActual('node:module'),
+ createRequire: (...args: unknown[]) => mockCreateRequire(...args),
+}));
+
+// Unit tests for exported pure functions (no mocks required)
+
+describe('postProcessBundlePackageJson', () => {
+ it('clears scripts and devDependencies', () => {
+ const pkg: Record = {
+ scripts: { build: 'tsc' },
+ devDependencies: { typescript: '^5.0.0' },
+ };
+ postProcessBundlePackageJson(pkg, '/tmp', 'backend', undefined, {}, false);
+ expect(pkg.scripts).toEqual({});
+ expect(pkg.devDependencies).toEqual({});
+ });
+
+ it('sets bundleDependencies for backend plugins', () => {
+ const pkg: Record = {};
+ postProcessBundlePackageJson(pkg, '/tmp', 'backend', undefined, {}, false);
+ expect(pkg.bundleDependencies).toBe(true);
+ });
+
+ it('does not set bundleDependencies for frontend plugins', () => {
+ const pkg: Record = {};
+ postProcessBundlePackageJson(pkg, '/tmp', 'frontend', undefined, {}, true);
+ expect(pkg.bundleDependencies).toBeUndefined();
+ });
+
+ it('sets MF entry points for frontend plugins', () => {
+ const pkg: Record = {
+ main: './dist/index.cjs.js',
+ exports: { '.': './dist/index.cjs.js' },
+ module: './dist/index.esm.js',
+ typesVersions: { '*': { '*': ['dist/index.d.ts'] } },
+ };
+ postProcessBundlePackageJson(pkg, '/tmp', 'frontend', undefined, {}, false);
+ expect(pkg.main).toBe('./dist/remoteEntry.js');
+ expect(pkg.exports).toBeUndefined();
+ expect(pkg.module).toBeUndefined();
+ expect(pkg.typesVersions).toBeUndefined();
+ });
+
+ it('does not set MF entry points for backend plugins', () => {
+ const pkg: Record = {
+ main: './dist/index.cjs.js',
+ };
+ postProcessBundlePackageJson(pkg, '/tmp', 'backend', undefined, {}, false);
+ expect(pkg.main).toBe('./dist/index.cjs.js');
+ });
+
+ it('merges root resolutions and strips patch prefix', () => {
+ const pkg: Record = {
+ resolutions: { existing: '3.0.0' },
+ };
+ const rootResolutions = {
+ 'some-dep': '1.0.0',
+ 'patched-dep': 'patch:patched-dep@npm%3A2.0.0#./patch',
+ };
+ postProcessBundlePackageJson(
+ pkg,
+ '/tmp',
+ 'backend',
+ rootResolutions,
+ {},
+ true,
+ );
+ expect(pkg.resolutions).toEqual({
+ 'some-dep': '1.0.0',
+ 'patched-dep': '2.0.0',
+ existing: '3.0.0',
+ });
+ });
+
+ it('does not merge resolutions when needsDependencies is false', () => {
+ const pkg: Record = {};
+ postProcessBundlePackageJson(
+ pkg,
+ '/tmp',
+ 'backend',
+ { dep: '1.0.0' },
+ {},
+ false,
+ );
+ expect(pkg.resolutions).toBeUndefined();
+ });
+});
+
+describe('filterBundleConfigSchemas', () => {
+ const mockDir = createMockDirectory();
+
+ beforeEach(() => {
+ mockCreateRequire.mockImplementation((p: string) =>
+ jest
+ .requireActual('node:module')
+ .createRequire(p),
+ );
+ });
+
+ afterEach(() => {
+ mockCreateRequire.mockReset();
+ });
+
+ function writePluginTree(
+ pluginPkg: Record,
+ deps: Record> = {},
+ ) {
+ const content: Record = {
+ 'package.json': JSON.stringify(pluginPkg),
+ };
+ for (const [name, depPkg] of Object.entries(deps)) {
+ content[`node_modules/${name}/package.json`] = JSON.stringify(depPkg);
+ }
+ mockDir.setContent(content);
+ }
+
+ function schemas(...names: string[]) {
+ return names.map(n => ({ packageName: n, value: {}, path: '' }));
+ }
+
+ it('includes the plugin itself', () => {
+ writePluginTree({ name: '@scope/my-plugin', dependencies: {} });
+ const result = filterBundleConfigSchemas(
+ schemas('@scope/my-plugin', '@other/unrelated'),
+ mockDir.path,
+ );
+ expect(result.map(s => s.packageName)).toEqual(['@scope/my-plugin']);
+ });
+
+ it('includes third-party deps without backstage metadata', () => {
+ writePluginTree(
+ { name: '@scope/my-plugin', dependencies: { lodash: '^4.0.0' } },
+ { lodash: { name: 'lodash', version: '4.17.21' } },
+ );
+ const result = filterBundleConfigSchemas(
+ schemas('@scope/my-plugin', 'lodash'),
+ mockDir.path,
+ );
+ expect(result.map(s => s.packageName)).toContain('lodash');
+ });
+
+ it('includes same-pluginId libraries', () => {
+ writePluginTree(
+ {
+ name: '@scope/my-plugin',
+ backstage: { role: 'backend-plugin', pluginId: 'foo' },
+ dependencies: { '@scope/my-lib': '^1.0.0' },
+ },
+ {
+ '@scope/my-lib': {
+ name: '@scope/my-lib',
+ backstage: { role: 'node-library', pluginId: 'foo' },
+ },
+ },
+ );
+ const result = filterBundleConfigSchemas(
+ schemas('@scope/my-plugin', '@scope/my-lib'),
+ mockDir.path,
+ );
+ expect(result.map(s => s.packageName)).toEqual([
+ '@scope/my-plugin',
+ '@scope/my-lib',
+ ]);
+ });
+
+ it('excludes library with different pluginId', () => {
+ writePluginTree(
+ {
+ name: '@scope/my-plugin',
+ backstage: { role: 'backend-plugin', pluginId: 'foo' },
+ dependencies: { '@scope/other-lib': '^1.0.0' },
+ },
+ {
+ '@scope/other-lib': {
+ name: '@scope/other-lib',
+ backstage: { role: 'node-library', pluginId: 'bar' },
+ },
+ },
+ );
+ const result = filterBundleConfigSchemas(
+ schemas('@scope/my-plugin', '@scope/other-lib'),
+ mockDir.path,
+ );
+ expect(result.map(s => s.packageName)).toEqual(['@scope/my-plugin']);
+ });
+
+ it('recursively includes depended plugin/module schemas', () => {
+ writePluginTree(
+ {
+ name: '@scope/my-plugin',
+ dependencies: { '@scope/my-module': '^1.0.0' },
+ },
+ {
+ '@scope/my-module': {
+ name: '@scope/my-module',
+ backstage: { role: 'backend-plugin-module' },
+ },
+ },
+ );
+ const result = filterBundleConfigSchemas(
+ schemas('@scope/my-plugin', '@scope/my-module'),
+ mockDir.path,
+ );
+ expect(result.map(s => s.packageName)).toEqual([
+ '@scope/my-plugin',
+ '@scope/my-module',
+ ]);
+ });
+});
+
+// Integration tests for the bundle command (require mocks)
+
+describe('bundle command', () => {
+ const mockDir = createMockDirectory();
+
+ const backendPluginDir = 'plugins/foo-backend';
+ const backendPkg = {
+ name: '@scope/plugin-foo-backend',
+ version: '1.0.0',
+ backstage: { role: 'backend-plugin' },
+ dependencies: {},
+ };
+ const backendMangledName = 'scope-plugin-foo-backend';
+
+ const frontendPluginDir = 'plugins/foo';
+ const frontendPkg = {
+ name: '@scope/plugin-foo',
+ version: '1.0.0',
+ backstage: { role: 'frontend-plugin' },
+ dependencies: {},
+ };
+
+ const defaultRootPkg = {
+ name: 'root',
+ version: '1.0.0',
+ resolutions: {
+ 'some-dep': '1.0.0',
+ 'patched-dep': 'patch:patched-dep@npm%3A2.0.0#./patch',
+ },
+ };
+
+ const defaultOpts = {
+ build: true,
+ install: true,
+ clean: false,
+ verbose: false,
+ outputDestination: undefined as string | undefined,
+ outputName: undefined as string | undefined,
+ prePackedDir: undefined as string | undefined,
+ };
+
+ function setupPlugin(
+ projectRelativeDir: string,
+ pkg: Record,
+ bundleName = 'bundle',
+ ) {
+ const pluginDir = joinPath(mockDir.path, projectRelativeDir);
+ const targetDir = joinPath(pluginDir, bundleName);
+
+ mockDir.setContent({
+ [joinPath(projectRelativeDir, 'package.json')]: JSON.stringify(pkg),
+ [joinPath(projectRelativeDir, 'yarn.lock')]: '# yarn.lock content',
+ 'package.json': JSON.stringify(defaultRootPkg),
+ 'yarn.lock': '# root yarn.lock',
+ 'tmp/.keep': '',
+ });
+ targetPaths.dir = pluginDir;
+ targetPaths.rootDir = mockDir.path;
+ (targetPaths.resolve as jest.Mock).mockImplementation((...args: string[]) =>
+ joinPath(targetPaths.dir, ...args),
+ );
+
+ return { pluginDir, targetDir, relDir: projectRelativeDir, bundleName };
+ }
+
+ function setupCreateDistWorkspaceMock(
+ pluginDir: string,
+ targets: { name: string; dir: string }[] = [],
+ invokeLogger = false,
+ ) {
+ const mainTarget = { name: backendPkg.name, dir: pluginDir };
+ mockCreateDistWorkspace.mockImplementation(async (_pkgNames, opts) => {
+ if (invokeLogger && opts.logger) {
+ opts.logger.log(`Moving ${backendPkg.name} into dist workspace`);
+ opts.logger.warn('some dist workspace warning');
+ }
+ await fs.copy(
+ joinPath(fixturesDir, 'dist-workspace', 'backend'),
+ opts.targetDir,
+ );
+ return { targets: targets.length ? targets : [mainTarget] };
+ });
+ }
+
+ function setupPackToDirectoryMock() {
+ mockPackToDirectory.mockImplementation(
+ async (opts: { targetDir: string; packageName: string }) => {
+ await fs.copy(
+ joinPath(fixturesDir, 'packed', 'frontend'),
+ opts.targetDir,
+ );
+ const pkgPath = joinPath(opts.targetDir, 'package.json');
+ const pkg = await fs.readJson(pkgPath);
+ pkg.name = opts.packageName;
+ await fs.writeJson(pkgPath, pkg);
+ },
+ );
+ }
+
+ function setupRunMock() {
+ mockRun.mockImplementation(
+ (
+ args: string[],
+ opts: { cwd: string; onStdout?: (d: Buffer) => void },
+ ) => ({
+ waitForExit: async () => {
+ if (!args.includes('update-lockfile')) {
+ await fs.ensureDir(joinPath(opts.cwd, 'node_modules'));
+ await fs.ensureDir(joinPath(opts.cwd, '.yarn'));
+ }
+ opts.onStdout?.(Buffer.from('mock yarn output\n'));
+ },
+ }),
+ );
+ }
+
+ beforeEach(() => {
+ jest.clearAllMocks();
+ jest.spyOn(os, 'tmpdir').mockReturnValue(joinPath(mockDir.path, 'tmp'));
+ mockLoadConfigSchema.mockResolvedValue({
+ serialize: () => ({ schemas: [] }),
+ });
+ mockRunOutput.mockResolvedValue('/mock-cache');
+ setupRunMock();
+ mockCreateRequire.mockImplementation((path: string) =>
+ jest.requireActual('node:module').createRequire(path),
+ );
+ jest.spyOn(console, 'log').mockImplementation();
+ jest.spyOn(console, 'warn').mockImplementation();
+ jest.spyOn(console, 'error').mockImplementation();
+ });
+
+ afterEach(() => {
+ // Clear native Node module cache for files under mockDir to prevent
+ // cross-test contamination when real createRequire loads dist/index.js.
+ const nativeModule =
+ jest.requireActual('node:module');
+ const nativeRequire = nativeModule.createRequire(__filename);
+ for (const key of Object.keys(nativeRequire.cache ?? {})) {
+ if (key.includes(mockDir.path)) {
+ delete nativeRequire.cache![key];
+ }
+ }
+ jest.restoreAllMocks();
+ });
+
+ async function expectPathExists(parts: string[], exists: boolean) {
+ expect(await fs.pathExists(joinPath(...parts))).toBe(exists);
+ }
+
+ describe('validation', () => {
+ it('throws when backstage.role is missing', async () => {
+ setupPlugin(backendPluginDir, {
+ name: '@scope/plugin-foo-backend',
+ version: '1.0.0',
+ });
+ await expect(bundleCommand(defaultOpts)).rejects.toThrow(
+ 'does not have a backstage.role defined in package.json',
+ );
+ });
+
+ it('throws when role is invalid', async () => {
+ setupPlugin(backendPluginDir, {
+ ...backendPkg,
+ backstage: { role: 'backend' },
+ });
+ await expect(bundleCommand(defaultOpts)).rejects.toThrow(
+ `only supports: ${chalk.cyan('backend-plugin')}, ${chalk.cyan(
+ 'backend-plugin-module',
+ )}, ${chalk.cyan('frontend-plugin')}, ${chalk.cyan(
+ 'frontend-plugin-module',
+ )}`,
+ );
+ });
+
+ it('throws when bundled is true', async () => {
+ setupPlugin(backendPluginDir, { ...backendPkg, bundled: true });
+ await expect(bundleCommand(defaultOpts)).rejects.toThrow(
+ 'not compatible with dynamic plugin bundling',
+ );
+ });
+ });
+
+ describe('backend', () => {
+ let ctx: ReturnType;
+ beforeEach(() => {
+ ctx = setupPlugin(backendPluginDir, backendPkg);
+ });
+
+ describe('via createDistWorkspace', () => {
+ beforeEach(() => {
+ setupCreateDistWorkspaceMock(ctx.pluginDir);
+ });
+
+ it('should produce backend bundle when build=true', async () => {
+ await bundleCommand(defaultOpts);
+ const pkg = await fs.readJson(joinPath(ctx.targetDir, 'package.json'));
+ expect(pkg.name).toBe(backendPkg.name);
+ expect(pkg.bundleDependencies).toBe(true);
+ await expectPathExists([ctx.targetDir, '.gitignore'], true);
+ await expectPathExists([ctx.targetDir, '.yarnrc.yml'], true);
+ expect(mockCreateDistWorkspace).toHaveBeenCalledWith(
+ expect.anything(),
+ expect.objectContaining({ buildDependencies: true }),
+ );
+ });
+
+ it.each(['null', 'undefined'])(
+ 'should not write yarnPath when yarn config returns "%s"',
+ async sentinel => {
+ mockRunOutput.mockImplementation(
+ (args: string[]): Promise => {
+ if (args.includes('yarnPath')) {
+ return Promise.resolve(sentinel);
+ }
+ return Promise.resolve('/mock-cache');
+ },
+ );
+ await bundleCommand(defaultOpts);
+ const yarnrc = await fs.readFile(
+ joinPath(ctx.targetDir, '.yarnrc.yml'),
+ 'utf8',
+ );
+ expect(yarnrc).not.toContain('yarnPath');
+ expect(yarnrc).toContain('nodeLinker: node-modules');
+ },
+ );
+
+ it('should write yarnPath when yarn config returns a real path', async () => {
+ mockRunOutput.mockImplementation((args: string[]): Promise => {
+ if (args.includes('yarnPath')) {
+ return Promise.resolve('/home/user/.yarn/releases/yarn-3.8.1.cjs');
+ }
+ return Promise.resolve('/mock-cache');
+ });
+ await bundleCommand(defaultOpts);
+ const yarnrc = await fs.readFile(
+ joinPath(ctx.targetDir, '.yarnrc.yml'),
+ 'utf8',
+ );
+ expect(yarnrc).toContain(
+ 'yarnPath: /home/user/.yarn/releases/yarn-3.8.1.cjs',
+ );
+ });
+
+ it('should pass buildDependencies=false when build=false', async () => {
+ await bundleCommand({ ...defaultOpts, build: false });
+ expect(mockCreateDistWorkspace).toHaveBeenCalledWith(
+ expect.anything(),
+ expect.objectContaining({ buildDependencies: false }),
+ );
+ });
+
+ it('should produce backend bundle for backend-plugin-module role', async () => {
+ ctx = setupPlugin(backendPluginDir, {
+ ...backendPkg,
+ backstage: { role: 'backend-plugin-module' },
+ });
+ setupCreateDistWorkspaceMock(ctx.pluginDir);
+ await bundleCommand(defaultOpts);
+ const pkg = await fs.readJson(joinPath(ctx.targetDir, 'package.json'));
+ expect(pkg.name).toBe(backendPkg.name);
+ expect(mockCreateDistWorkspace).toHaveBeenCalled();
+ expect(mockPackToDirectory).not.toHaveBeenCalled();
+ });
+
+ it('should assemble local deps into embedded/ and clean up .yarn', async () => {
+ const commonRelDir = 'plugins/foo-common';
+ const commonDir = joinPath(mockDir.path, commonRelDir);
+
+ ctx = setupPlugin(backendPluginDir, {
+ ...backendPkg,
+ dependencies: { '@scope/plugin-foo-common': 'workspace:^' },
+ });
+ setupCreateDistWorkspaceMock(ctx.pluginDir, [
+ { name: backendPkg.name, dir: ctx.pluginDir },
+ { name: '@scope/plugin-foo-common', dir: commonDir },
+ ]);
+
+ await bundleCommand(defaultOpts);
+
+ const pkg = await fs.readJson(joinPath(ctx.targetDir, 'package.json'));
+ expect(pkg.name).toBe(backendPkg.name);
+ await expectPathExists(
+ [ctx.targetDir, 'embedded', commonRelDir, 'package.json'],
+ true,
+ );
+ expect(pkg.resolutions['@scope/plugin-foo-common']).toBe(
+ `file:./embedded/${commonRelDir}`,
+ );
+ await expectPathExists([ctx.targetDir, '.yarn'], false);
+ });
+
+ it('should log formatted packing output when distLogger is invoked', async () => {
+ setupCreateDistWorkspaceMock(ctx.pluginDir, [], true);
+ await bundleCommand(defaultOpts);
+
+ expect(console.log).toHaveBeenCalledWith(
+ expect.stringContaining(`Packing`),
+ );
+ expect(console.log).toHaveBeenCalledWith(
+ expect.stringContaining(backendPkg.name),
+ );
+ expect(console.warn).toHaveBeenCalledWith(
+ expect.stringContaining('some dist workspace warning'),
+ );
+ });
+ });
+
+ describe('via createDistWorkspace - failure', () => {
+ it('should clean up temp dir and propagate error on createDistWorkspace failure', async () => {
+ mockCreateDistWorkspace.mockRejectedValue(new Error('pack failed'));
+ const tempBase = joinPath(mockDir.path, 'tmp');
+ jest.spyOn(os, 'tmpdir').mockReturnValue(tempBase);
+
+ await expect(bundleCommand(defaultOpts)).rejects.toThrow('pack failed');
+
+ const entries = await fs.readdir(tempBase).catch(() => []);
+ expect(
+ entries.filter((e: string) => e.startsWith('bundle-workspace-')),
+ ).toHaveLength(0);
+ });
+ });
+
+ describe('via --pre-packed-dir', () => {
+ beforeEach(() => {
+ mockCreateDistWorkspace.mockClear();
+ });
+
+ it('should copy from pre-packed dir and assemble embedded', async () => {
+ const prePackedPath = joinPath(mockDir.path, 'pre-packed');
+ await fs.copy(
+ joinPath(fixturesDir, 'dist-workspace', 'backend'),
+ prePackedPath,
+ );
+
+ mockListTargetPackages.mockResolvedValue([
+ { packageJson: { name: backendPkg.name }, dir: ctx.pluginDir },
+ ]);
+
+ await bundleCommand({ ...defaultOpts, prePackedDir: prePackedPath });
+
+ const pkg = await fs.readJson(joinPath(ctx.targetDir, 'package.json'));
+ expect(pkg.name).toBe(backendPkg.name);
+ expect(pkg.bundleDependencies).toBe(true);
+ });
+
+ it('should print warning when package not found in pre-packed dir', async () => {
+ ctx = setupPlugin(backendPluginDir, {
+ ...backendPkg,
+ dependencies: { '@scope/other-dep': 'workspace:^' },
+ });
+ mockListTargetPackages.mockResolvedValue([
+ {
+ packageJson: {
+ name: backendPkg.name,
+ version: '1.0.0',
+ dependencies: { '@scope/other-dep': 'workspace:^' },
+ },
+ dir: ctx.pluginDir,
+ },
+ {
+ packageJson: { name: '@scope/other-dep', version: '1.0.0' },
+ dir: joinPath(mockDir.path, 'packages/other-dep'),
+ },
+ ]);
+
+ const prePackedPath = joinPath(mockDir.path, 'pre-packed');
+ await fs.copy(
+ joinPath(fixturesDir, 'dist-workspace', 'backend'),
+ prePackedPath,
+ );
+
+ await bundleCommand({ ...defaultOpts, prePackedDir: prePackedPath });
+
+ expect(console.warn).toHaveBeenCalledWith(
+ chalk.yellow(
+ ` Package ${chalk.cyan(
+ '@scope/other-dep',
+ )} not found in pre-packed dir (expected at ${chalk.cyan(
+ 'packages/other-dep',
+ )})`,
+ ),
+ );
+ });
+ });
+
+ describe('lockfile and install', () => {
+ beforeEach(() => {
+ setupCreateDistWorkspaceMock(ctx.pluginDir);
+ });
+
+ it('should seed lockfile from monorepo root when plugin has no yarn.lock', async () => {
+ mockDir.setContent({
+ [joinPath(backendPluginDir, 'package.json')]:
+ JSON.stringify(backendPkg),
+ 'package.json': JSON.stringify(defaultRootPkg),
+ 'yarn.lock': '# root yarn.lock content',
+ 'tmp/.keep': '',
+ });
+
+ await bundleCommand(defaultOpts);
+
+ const lockContent = await fs.readFile(
+ joinPath(ctx.targetDir, 'yarn.lock'),
+ 'utf8',
+ );
+ expect(lockContent).toBe('# root yarn.lock content');
+ });
+
+ it('throws when no yarn.lock exists', async () => {
+ mockDir.setContent({
+ [joinPath(backendPluginDir, 'package.json')]:
+ JSON.stringify(backendPkg),
+ 'package.json': JSON.stringify(defaultRootPkg),
+ 'tmp/.keep': '',
+ });
+
+ await expect(bundleCommand(defaultOpts)).rejects.toThrow(
+ `Could not find a ${chalk.cyan(
+ 'yarn.lock',
+ )} file in either the plugin directory or the monorepo root (${chalk.cyan(
+ mockDir.path,
+ )})`,
+ );
+ });
+
+ it('should run prune and install in the bundle dir', async () => {
+ await bundleCommand(defaultOpts);
+ expect(mockRun).toHaveBeenCalledWith(
+ expect.arrayContaining([
+ 'yarn',
+ 'install',
+ '--no-immutable',
+ '--mode',
+ 'update-lockfile',
+ ]),
+ expect.objectContaining({ cwd: ctx.targetDir }),
+ );
+ expect(mockRun).toHaveBeenCalledWith(
+ expect.arrayContaining(['yarn', 'install', '--immutable']),
+ expect.objectContaining({ cwd: ctx.targetDir }),
+ );
+ });
+
+ it('throws when backend plugin has no valid BackendFeature export', async () => {
+ mockCreateRequire.mockImplementation(() =>
+ Object.assign(() => ({ default: {} }), {
+ resolve: (id: string) => {
+ if (id.includes('package.json')) {
+ return joinPath(targetPaths.dir, 'node_modules', id);
+ }
+ throw new Error(`Cannot find module '${id}'`);
+ },
+ }),
+ );
+ await expect(bundleCommand(defaultOpts)).rejects.toThrow(
+ 'Backend plugin is not valid for dynamic loading',
+ );
+ });
+ });
+
+ describe('--no-install', () => {
+ beforeEach(() => {
+ setupCreateDistWorkspaceMock(ctx.pluginDir);
+ });
+
+ it('should skip install and print warning', async () => {
+ await bundleCommand({ ...defaultOpts, install: false });
+
+ await expectPathExists([ctx.targetDir, 'package.json'], true);
+ await expectPathExists([ctx.targetDir, 'yarn.lock'], true);
+ await expectPathExists([ctx.targetDir, 'node_modules'], false);
+ expect(mockRun).toHaveBeenCalledWith(
+ expect.arrayContaining(['--mode', 'update-lockfile']),
+ expect.objectContaining({ cwd: ctx.targetDir }),
+ );
+ expect(mockRun).not.toHaveBeenCalledWith(
+ expect.arrayContaining(['--immutable']),
+ expect.objectContaining({ cwd: ctx.targetDir }),
+ );
+ expect(console.log).toHaveBeenCalledWith(
+ expect.stringContaining('Skipping dependency installation'),
+ );
+ });
+ });
+
+ describe('options', () => {
+ beforeEach(() => {
+ setupCreateDistWorkspaceMock(ctx.pluginDir);
+ });
+
+ it('should remove target when clean=true', async () => {
+ mockDir.addContent({
+ [joinPath(ctx.relDir, ctx.bundleName, 'existing-file')]: 'content',
+ });
+
+ await bundleCommand({ ...defaultOpts, clean: true });
+
+ await expectPathExists([ctx.targetDir, 'existing-file'], false);
+ await expectPathExists([ctx.targetDir, 'package.json'], true);
+ });
+
+ it('should write bundle to custom outputDestination with mangled name', async () => {
+ const customOutput = joinPath(mockDir.path, 'custom-output');
+ await bundleCommand({
+ ...defaultOpts,
+ outputDestination: customOutput,
+ });
+
+ await expectPathExists(
+ [customOutput, backendMangledName, 'package.json'],
+ true,
+ );
+ });
+
+ it('should use "bundle" as default name when output stays in package dir', async () => {
+ await bundleCommand(defaultOpts);
+ const entries = await fs.readdir(ctx.pluginDir);
+ expect(entries).toContain('bundle');
+ });
+
+ it('should use mangled package name when outputDestination is given', async () => {
+ const customOutput = joinPath(mockDir.path, 'custom-output');
+ await bundleCommand({
+ ...defaultOpts,
+ outputDestination: customOutput,
+ });
+ const entries = await fs.readdir(customOutput);
+ expect(entries).toContain(backendMangledName);
+ });
+
+ it('should use explicit outputName when provided', async () => {
+ await bundleCommand({ ...defaultOpts, outputName: 'my-custom-bundle' });
+ const entries = await fs.readdir(ctx.pluginDir);
+ expect(entries).toContain('my-custom-bundle');
+ });
+
+ it('should pipe run output to console when verbose=true', async () => {
+ await bundleCommand({ ...defaultOpts, verbose: true });
+
+ expect(mockRun).toHaveBeenCalledWith(
+ expect.arrayContaining(['yarn', 'install', '--immutable']),
+ expect.anything(),
+ );
+ expect(console.log).toHaveBeenCalledWith(
+ expect.stringContaining('mock yarn output'),
+ );
+ });
+
+ it('should write .bundle-output marker to the output directory', async () => {
+ await bundleCommand(defaultOpts);
+ await expectPathExists([ctx.targetDir, '.bundle-output'], true);
+ });
+
+ it('should remove nested dirs that have a .bundle-output marker', async () => {
+ // Leave a marked directory from a previous bundle run in the source tree.
+ const prevBundleDir = joinPath(ctx.pluginDir, 'old-bundle');
+ await fs.ensureDir(prevBundleDir);
+ await fs.writeFile(joinPath(prevBundleDir, '.bundle-output'), '');
+
+ // Simulate yarn pack pulling the stale dir into the packed output.
+ mockCreateDistWorkspace.mockImplementation(async (_pkgNames, opts) => {
+ await fs.copy(
+ joinPath(fixturesDir, 'dist-workspace', 'backend'),
+ opts.targetDir,
+ );
+ const nestedDir = joinPath(opts.targetDir, ctx.relDir, 'old-bundle');
+ await fs.ensureDir(nestedDir);
+ await fs.writeFile(joinPath(nestedDir, 'stale-file'), '');
+ return { targets: [{ name: backendPkg.name, dir: ctx.pluginDir }] };
+ });
+
+ await bundleCommand(defaultOpts);
+ await expectPathExists([ctx.targetDir, 'old-bundle'], false);
+ });
+
+ it('should not create recursive nesting when run twice without --clean', async () => {
+ await bundleCommand(defaultOpts);
+ await bundleCommand(defaultOpts);
+
+ const entries = await fs.readdir(ctx.targetDir);
+ expect(entries).not.toContain('bundle');
+ });
+ });
+
+ describe('error handling', () => {
+ it('should propagate error and show log when pruneBundleLockfile fails', async () => {
+ setupCreateDistWorkspaceMock(ctx.pluginDir);
+ mockRun
+ .mockReturnValueOnce({ waitForExit: () => Promise.resolve() })
+ .mockImplementationOnce((_args: any, opts: any) => ({
+ waitForExit: async () => {
+ (opts?.onStdout ?? opts?.onStderr)?.(
+ Buffer.from('yarn prune output line 1\nline 2\n'),
+ );
+ throw new Error('prune failed');
+ },
+ }));
+
+ await expect(bundleCommand(defaultOpts)).rejects.toThrow(
+ 'prune failed',
+ );
+ expect(console.error).toHaveBeenCalledWith(
+ expect.stringContaining('Full log available at'),
+ );
+ expect(console.error).toHaveBeenCalledWith(
+ expect.stringContaining('--- last 20 lines ---'),
+ );
+ });
+
+ it('should propagate error when installBundleDependencies fails', async () => {
+ setupCreateDistWorkspaceMock(ctx.pluginDir);
+ let callCount = 0;
+ mockRun.mockImplementation(() => ({
+ waitForExit: () =>
+ ++callCount === 2
+ ? Promise.reject(new Error('install failed'))
+ : Promise.resolve(),
+ }));
+
+ await expect(bundleCommand(defaultOpts)).rejects.toThrow(
+ 'install failed',
+ );
+ });
+ });
+
+ describe('config schema', () => {
+ beforeEach(() => {
+ setupCreateDistWorkspaceMock(ctx.pluginDir);
+ });
+
+ it('should set configSchema in package.json when schemas are found', async () => {
+ mockLoadConfigSchema.mockResolvedValue({
+ serialize: () => ({
+ schemas: [
+ {
+ packageName: backendPkg.name,
+ value: {
+ type: 'object',
+ properties: { foo: { type: 'string' } },
+ },
+ path: 'schemas/foo.json',
+ },
+ ],
+ }),
+ });
+
+ await bundleCommand(defaultOpts);
+
+ const pkg = await fs.readJson(joinPath(ctx.targetDir, 'package.json'));
+ expect(pkg.configSchema).toBe('dist/.config-schema.json');
+ const schemaFile = await fs.readJson(
+ joinPath(ctx.targetDir, 'dist', '.config-schema.json'),
+ );
+ expect(schemaFile.backstageConfigSchemaVersion).toBe(1);
+ expect(schemaFile.schemas).toHaveLength(1);
+ });
+
+ it('should not set configSchema when no schemas are found', async () => {
+ await bundleCommand(defaultOpts);
+ const pkg = await fs.readJson(joinPath(ctx.targetDir, 'package.json'));
+ expect(pkg.configSchema).toBeUndefined();
+ });
+ });
+ });
+
+ describe('frontend', () => {
+ let ctx: ReturnType;
+ beforeEach(() => {
+ ctx = setupPlugin(frontendPluginDir, frontendPkg);
+ setupPackToDirectoryMock();
+ });
+
+ describe('without --pre-packed-dir', () => {
+ it('should produce frontend bundle when build=true', async () => {
+ await bundleCommand(defaultOpts);
+ const pkg = await fs.readJson(joinPath(ctx.targetDir, 'package.json'));
+ expect(pkg.name).toBe(frontendPkg.name);
+ await expectPathExists([ctx.targetDir, '.gitignore'], true);
+ await expectPathExists([ctx.targetDir, '.yarnrc.yml'], false);
+ await expectPathExists([ctx.targetDir, 'yarn.lock'], false);
+ await expectPathExists([ctx.targetDir, 'node_modules'], false);
+ await expectPathExists([ctx.targetDir, 'src'], false);
+ expect(mockBuildFrontend).toHaveBeenCalled();
+ expect(mockPackToDirectory).toHaveBeenCalled();
+ expect(mockCreateDistWorkspace).not.toHaveBeenCalled();
+ });
+
+ it('should keep src/ when "files" explicitly includes it', async () => {
+ ctx = setupPlugin(frontendPluginDir, {
+ ...frontendPkg,
+ files: ['dist', 'src'],
+ });
+ setupPackToDirectoryMock();
+ await bundleCommand(defaultOpts);
+ await expectPathExists([ctx.targetDir, 'src'], true);
+ });
+
+ it('should produce frontend bundle when build=false', async () => {
+ await bundleCommand({ ...defaultOpts, build: false });
+ const pkg = await fs.readJson(joinPath(ctx.targetDir, 'package.json'));
+ expect(pkg.name).toBe(frontendPkg.name);
+ await expectPathExists([ctx.targetDir, 'yarn.lock'], false);
+ await expectPathExists([ctx.targetDir, 'node_modules'], false);
+ expect(mockBuildFrontend).not.toHaveBeenCalled();
+ expect(mockPackToDirectory).toHaveBeenCalled();
+ });
+
+ it('should produce frontend bundle for frontend-plugin-module role', async () => {
+ ctx = setupPlugin(frontendPluginDir, {
+ ...frontendPkg,
+ backstage: { role: 'frontend-plugin-module' },
+ });
+ await bundleCommand(defaultOpts);
+ const pkg = await fs.readJson(joinPath(ctx.targetDir, 'package.json'));
+ expect(pkg.name).toBe(frontendPkg.name);
+ expect(mockBuildFrontend).toHaveBeenCalled();
+ expect(mockPackToDirectory).toHaveBeenCalled();
+ expect(mockCreateDistWorkspace).not.toHaveBeenCalled();
+ });
+ });
+
+ describe('package.json post-processing', () => {
+ it('should apply frontend-specific and common post-processing', async () => {
+ await bundleCommand(defaultOpts);
+ const pkg = await fs.readJson(joinPath(ctx.targetDir, 'package.json'));
+ expect(pkg.main).toBe('./dist/remoteEntry.js');
+ expect(pkg.types).toBe('./dist/@mf-types/index.d.ts');
+ expect(pkg.exports).toBeUndefined();
+ expect(pkg.module).toBeUndefined();
+ expect(pkg.typesVersions).toBeUndefined();
+ expect(pkg.dependencies).toEqual({
+ '@backstage/catalog-model': '^1.7.6',
+ });
+ expect(pkg.keywords).toEqual(['backstage']);
+ expect(pkg.license).toBe('Apache-2.0');
+ expect(pkg.backstage).toEqual(
+ expect.objectContaining({ role: 'frontend-plugin' }),
+ );
+ expect(pkg.bundleDependencies).toBeUndefined();
+ expect(pkg.scripts).toEqual({});
+ expect(pkg.devDependencies).toEqual({});
+ });
+
+ it('should delete types when @mf-types/index.d.ts is absent', async () => {
+ mockPackToDirectory.mockImplementation(
+ async (opts: { targetDir: string; packageName: string }) => {
+ await fs.copy(
+ joinPath(fixturesDir, 'packed', 'frontend'),
+ opts.targetDir,
+ );
+ await fs.remove(
+ joinPath(opts.targetDir, 'dist', '@mf-types', 'index.d.ts'),
+ );
+ const pkgPath = joinPath(opts.targetDir, 'package.json');
+ const pkg = await fs.readJson(pkgPath);
+ pkg.name = opts.packageName;
+ await fs.writeJson(pkgPath, pkg);
+ },
+ );
+ await bundleCommand(defaultOpts);
+ const pkg = await fs.readJson(joinPath(ctx.targetDir, 'package.json'));
+ expect(pkg.main).toBe('./dist/remoteEntry.js');
+ expect(pkg.types).toBeUndefined();
+ });
+ });
+
+ describe('with --pre-packed-dir', () => {
+ beforeEach(async () => {
+ mockListTargetPackages.mockResolvedValue([
+ { packageJson: { name: frontendPkg.name }, dir: ctx.pluginDir },
+ ]);
+ const prePackedPath = joinPath(mockDir.path, 'pre-packed');
+ await fs.copy(
+ joinPath(fixturesDir, 'dist-workspace', 'frontend'),
+ prePackedPath,
+ );
+ mockBuildFrontend.mockImplementation(async () => {
+ const distDir = joinPath(ctx.pluginDir, 'dist');
+ await fs.ensureDir(distDir);
+ await fs.writeFile(
+ joinPath(distDir, 'remoteEntry.js'),
+ '// MF remote entry',
+ );
+ });
+ });
+
+ it('should copy from pre-packed and prune lockfile but not install', async () => {
+ await bundleCommand({
+ ...defaultOpts,
+ prePackedDir: joinPath(mockDir.path, 'pre-packed'),
+ });
+
+ await expectPathExists([ctx.targetDir, 'package.json'], true);
+ await expectPathExists([ctx.targetDir, 'yarn.lock'], true);
+ await expectPathExists([ctx.targetDir, 'node_modules'], false);
+ await expectPathExists([ctx.targetDir, 'dist', 'remoteEntry.js'], true);
+ expect(mockRun).toHaveBeenCalledWith(
+ expect.arrayContaining(['--mode', 'update-lockfile']),
+ expect.objectContaining({ cwd: ctx.targetDir }),
+ );
+ expect(mockRun).not.toHaveBeenCalledWith(
+ expect.arrayContaining(['--immutable']),
+ expect.objectContaining({ cwd: ctx.targetDir }),
+ );
+ });
+ });
+
+ describe('error handling', () => {
+ it('should propagate error when packToDirectory fails', async () => {
+ mockPackToDirectory.mockRejectedValue(new Error('pack failed'));
+
+ await expect(bundleCommand(defaultOpts)).rejects.toThrow('pack failed');
+ expect(console.error).toHaveBeenCalledWith(
+ expect.stringContaining('Full log available at'),
+ );
+ });
+
+ it('should not show last 20 lines when verbose=true on failure', async () => {
+ mockPackToDirectory.mockRejectedValue(new Error('pack failed'));
+
+ await expect(
+ bundleCommand({ ...defaultOpts, verbose: true }),
+ ).rejects.toThrow('pack failed');
+ expect(console.error).toHaveBeenCalledWith(
+ expect.stringContaining('Full log available at'),
+ );
+ expect(console.error).not.toHaveBeenCalledWith(
+ expect.stringContaining('--- last 20 lines ---'),
+ );
+ });
+ });
+ });
+});
diff --git a/packages/cli-module-build/src/commands/package/bundle/command.ts b/packages/cli-module-build/src/commands/package/bundle/command.ts
new file mode 100644
index 0000000000..ee88322733
--- /dev/null
+++ b/packages/cli-module-build/src/commands/package/bundle/command.ts
@@ -0,0 +1,979 @@
+/*
+ * Copyright 2026 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 { BackstagePackageJson, PackageGraph } from '@backstage/cli-node';
+import { run, runOutput } from '@backstage/cli-common';
+import chalk from 'chalk';
+import { cli } from 'cleye';
+import fs from 'fs-extra';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import {
+ join as joinPath,
+ resolve as resolvePath,
+ relative as relativePath,
+} from 'node:path';
+
+import { loadConfigSchema } from '@backstage/config-loader';
+import { targetPaths } from '@backstage/cli-common';
+import { buildFrontend } from '../../../lib/buildFrontend';
+import {
+ createDistWorkspace,
+ packToDirectory,
+ resolveLocalDependencies,
+} from '../../../lib/packager';
+import type { CliCommandContext } from '@backstage/cli-node';
+
+interface BundleOptions {
+ build: boolean;
+ install: boolean;
+ clean: boolean;
+ verbose: boolean;
+ outputDestination?: string;
+ outputName?: string;
+ prePackedDir?: string;
+}
+
+/**
+ * Bundle a plugin for dynamic loading.
+ *
+ * This creates a self-contained plugin bundle that can be deployed independently
+ * and loaded dynamically by a Backstage application. Supports both backend and
+ * frontend plugins.
+ *
+ * For backend plugins, `createDistWorkspace` handles building (CJS) and packing
+ * all local dependencies. The output is restructured so that the main plugin
+ * sits at the bundle root and its local dependencies live under `embedded/`.
+ * A lockfile is seeded, pruned, and used to install a private `node_modules`.
+ *
+ * For frontend plugins, a module federation remote build produces the final
+ * assets. Only the main plugin is packed into the bundle root (no `embedded/`,
+ * no lockfile, no `node_modules`).
+ *
+ * When `--pre-packed-dir` is provided, local dependencies are copied from a
+ * pre-built dist workspace instead of calling `createDistWorkspace`:
+ * - For backend plugins this is a performance optimization when many plugins from the same monorepo are being bundled.
+ * - For frontend plugins it additionally enables lockfile generation (seed + prune) for dependency tracking purposes such as SBOM generation.
+ * - The pre-built dist workspace is produced by
+ * `backstage-cli build-workspace [packages...] --alwaysPack`
+ * and `` is then passed as `--pre-packed-dir`.
+ * - The `--alwaysPack` flag is required so that `workspace:^` and `backstage:^`
+ * dependency specs are resolved to concrete versions in the packed output.
+ */
+export async function bundleCommand(opts: BundleOptions): Promise {
+ const pkgJsonPath = targetPaths.resolve('package.json');
+ const pkg = (await fs.readJson(pkgJsonPath)) as BackstagePackageJson;
+
+ const outputDestination = opts.outputDestination
+ ? resolvePath(opts.outputDestination)
+ : targetPaths.dir;
+ const mangledName = pkg.name.replace(/^@/, '').replace(/\//, '-');
+ let bundleName = 'bundle';
+ if (opts.outputName) {
+ bundleName = opts.outputName;
+ } else if (opts.outputDestination) {
+ bundleName = mangledName;
+ }
+ const target = joinPath(outputDestination, bundleName);
+
+ const role = pkg.backstage?.role;
+ if (!role) {
+ throw new Error(
+ `Package ${chalk.cyan(
+ pkg.name,
+ )} does not have a backstage.role defined in package.json`,
+ );
+ }
+
+ const validRoles = [
+ 'backend-plugin',
+ 'backend-plugin-module',
+ 'frontend-plugin',
+ 'frontend-plugin-module',
+ ];
+ if (!validRoles.includes(role)) {
+ throw new Error(
+ `Package ${chalk.cyan(pkg.name)} has role ${chalk.cyan(
+ role,
+ )}, but bundle command ` +
+ `only supports: ${validRoles.map(r => chalk.cyan(r)).join(', ')}`,
+ );
+ }
+
+ const pluginType: 'frontend' | 'backend' =
+ role === 'frontend-plugin' || role === 'frontend-plugin-module'
+ ? 'frontend'
+ : 'backend';
+
+ if (pkg.bundled) {
+ throw new Error(
+ `Package ${chalk.cyan(pkg.name)} has ${chalk.cyan(
+ 'bundled: true',
+ )} which is not ` + `compatible with dynamic plugin bundling.`,
+ );
+ }
+
+ console.log(
+ chalk.blue(`Bundling ${chalk.cyan(pkg.name)} for dynamic loading...`),
+ );
+ console.log(`${chalk.dim('Output:')} ${chalk.cyan(target)}`);
+
+ if (opts.clean) {
+ console.log(chalk.blue(`Cleaning ${chalk.cyan(target)}`));
+ await fs.remove(target);
+ }
+
+ await fs.mkdirs(target);
+
+ await fs.writeFile(joinPath(target, '.gitignore'), '*\n');
+ await fs.writeFile(joinPath(target, '.bundle-output'), '');
+
+ const rootPkg = await fs.readJson(
+ resolvePath(targetPaths.rootDir, 'package.json'),
+ );
+
+ // Backend plugins always need embedded packages, lockfile, and node_modules.
+ // Frontend plugins need them only when --pre-packed-dir is provided.
+ const needsDependencies = pluginType === 'backend' || !!opts.prePackedDir;
+
+ // Establish the bundle directory as its own Yarn project root so that
+ // the seeded yarn.lock is the one Yarn reads/writes, even when the
+ // output directory is inside another monorepo.
+ // Only needed when lockfile/install operations will run.
+ if (needsDependencies) {
+ const yarnrcLines = ['nodeLinker: node-modules'];
+ try {
+ // Include yarnPath so the same Yarn version that created the lockfile
+ // is used for pruning/installing -- lockfile formats differ across
+ // major Yarn versions (e.g. ~builtin vs optional!builtin patches).
+ const resolved = await runOutput(['yarn', 'config', 'get', 'yarnPath'], {
+ cwd: targetPaths.rootDir,
+ });
+ const yarnPathSentinels = new Set(['undefined', 'null']);
+ if (resolved && !yarnPathSentinels.has(resolved)) {
+ yarnrcLines.push(`yarnPath: ${resolved}`);
+ }
+ } catch {
+ // yarnPath not configured — check if corepack manages the version instead
+ if (!rootPkg.packageManager) {
+ console.warn(
+ chalk.yellow(
+ 'No yarnPath configured and no packageManager field found. ' +
+ 'The Yarn version in PATH will be used for lockfile operations.',
+ ),
+ );
+ }
+ }
+
+ await fs.writeFile(
+ joinPath(target, '.yarnrc.yml'),
+ `${yarnrcLines.join('\n')}\n`,
+ );
+ }
+
+ // ── Step 0 (frontend only): Module federation build ─────────────────
+ if (pluginType === 'frontend' && opts.build) {
+ console.log(chalk.blue('Building module federation remote...'));
+ await buildFrontend({
+ targetDir: targetPaths.dir,
+ configPaths: [],
+ writeStats: false,
+ isModuleFederationRemote: true,
+ });
+ }
+
+ const embeddedResolutions: Record = {};
+
+ // Detect previous bundle output directories inside the source package so
+ // they can be stripped from the yarn-pack result later. npm-packlist's
+ // basename matching on the `files` field picks up identically-named entries
+ // from prior bundle outputs, creating nested copies.
+ const bundleOutputDirs: string[] = [];
+ try {
+ const entries = await fs.readdir(targetPaths.dir, { withFileTypes: true });
+ for (const entry of entries) {
+ if (entry.isDirectory()) {
+ if (
+ await fs.pathExists(
+ joinPath(targetPaths.dir, entry.name, '.bundle-output'),
+ )
+ ) {
+ bundleOutputDirs.push(entry.name);
+ }
+ }
+ }
+ } catch {
+ /* directory may not exist yet on first run */
+ }
+
+ if (needsDependencies) {
+ // ── Step 1: Populate embedded packages ──────────────────────────────
+ const embeddedDir = joinPath(target, 'embedded');
+ let targets: { name: string; dir: string }[];
+
+ if (opts.prePackedDir) {
+ // ── Strategy A: Copy from pre-built dist workspace ───────────────
+ // Reuses output from `backstage-cli build-workspace --alwaysPack`.
+ // Works for both backend (performance optimization) and frontend
+ // (enables lockfile generation for SBOM).
+ const prePackedDir = resolvePath(opts.prePackedDir);
+ console.log(
+ chalk.blue(
+ `Using pre-packed workspace at ${chalk.cyan(prePackedDir)}...`,
+ ),
+ );
+
+ const packages = await PackageGraph.listTargetPackages();
+ targets = await resolveLocalDependencies([pkg.name], packages);
+ await fs.ensureDir(embeddedDir);
+
+ for (const dep of targets) {
+ const relDir = relativePath(targetPaths.rootDir, dep.dir);
+ const srcDir = resolvePath(prePackedDir, relDir);
+ const destDir = resolvePath(embeddedDir, relDir);
+ if (await fs.pathExists(srcDir)) {
+ await fs.copy(srcDir, destDir);
+ } else {
+ console.warn(
+ chalk.yellow(
+ ` Package ${chalk.cyan(dep.name)} not found in pre-packed ` +
+ `dir (expected at ${chalk.cyan(relDir)})`,
+ ),
+ );
+ }
+ }
+ } else {
+ // ── Strategy B: createDistWorkspace ──────────────────────────────
+ // Pack all local dependencies into a temp directory first, then
+ // move the result into target/embedded/. We must NOT pack directly
+ // into the target tree because yarn pack's basename-matching on the
+ // `files` field would pick up identically-named files from
+ // already-extracted embedded packages.
+ const tempWorkspaceDir = await fs.mkdtemp(
+ joinPath(tmpdir(), 'bundle-workspace-'),
+ );
+ console.log(chalk.blue('Packing local dependencies...'));
+
+ const distLog = createStepLogger(
+ joinPath(target, 'dist-workspace.log'),
+ opts.verbose,
+ );
+
+ const packingPattern = /^(?:Moving|Repacking) (.+) into dist workspace$/;
+ const distLogger = {
+ log(msg: string) {
+ const match = msg.match(packingPattern);
+ if (match) {
+ console.log(` ${chalk.dim('Packing')} ${chalk.cyan(match[1])}`);
+ }
+ distLog.logger.log(msg);
+ },
+ warn(msg: string) {
+ console.warn(` ${chalk.yellow(msg)}`);
+ distLog.logger.warn(msg);
+ },
+ };
+
+ try {
+ ({ targets } = await createDistWorkspace([pkg.name], {
+ targetDir: tempWorkspaceDir,
+ files: [],
+ alwaysPack: true,
+ buildDependencies: opts.build,
+ buildExcludes: opts.build ? [] : undefined,
+ logger: distLogger,
+ }));
+ await fs.remove(embeddedDir);
+ await fs.move(tempWorkspaceDir, embeddedDir);
+ } catch (err) {
+ await distLog.close();
+ await showLogOnError(distLog.path, opts.verbose);
+ throw err;
+ } finally {
+ if (await fs.pathExists(tempWorkspaceDir)) {
+ await fs.remove(tempWorkspaceDir);
+ }
+ }
+ await distLog.close();
+ await fs.remove(distLog.path);
+ }
+
+ // ── Step 2: Assemble embedded packages ──────────────────────────────
+ const mainPluginRelDir = relativePath(targetPaths.rootDir, targetPaths.dir);
+ const mainPluginEmbeddedDir = resolvePath(embeddedDir, mainPluginRelDir);
+
+ console.log(
+ chalk.blue(
+ `Moving main plugin ${chalk.cyan(pkg.name)} to bundle root...`,
+ ),
+ );
+
+ if (!(await fs.pathExists(mainPluginEmbeddedDir))) {
+ throw new Error(
+ `Main plugin ${chalk.cyan(pkg.name)} was not found in the ` +
+ `embedded workspace at ${chalk.cyan(mainPluginRelDir)}. ` +
+ `Ensure the pre-packed workspace includes this plugin.`,
+ );
+ }
+
+ const mainPluginEntries = await fs.readdir(mainPluginEmbeddedDir);
+ for (const entry of mainPluginEntries) {
+ await fs.move(
+ joinPath(mainPluginEmbeddedDir, entry),
+ joinPath(target, entry),
+ { overwrite: true },
+ );
+ }
+
+ await fs.remove(mainPluginEmbeddedDir);
+
+ // For frontend plugins, the pre-packed dist/ contains standard CJS
+ // output, not Module Federation artifacts. Overlay the MF build
+ // output from the source directory (produced by Step 0).
+ if (pluginType === 'frontend') {
+ const sourceDist = resolvePath(targetPaths.dir, 'dist');
+ if (await fs.pathExists(sourceDist)) {
+ await fs.copy(sourceDist, joinPath(target, 'dist'), {
+ overwrite: true,
+ });
+ }
+ }
+
+ const localDeps = targets.filter(t => t.name !== pkg.name);
+
+ for (const dep of localDeps) {
+ const depRelDir = relativePath(targetPaths.rootDir, dep.dir);
+ const depEmbeddedDir = resolvePath(embeddedDir, depRelDir);
+
+ if (!(await fs.pathExists(depEmbeddedDir))) {
+ continue;
+ }
+
+ embeddedResolutions[dep.name] = `file:./embedded/${depRelDir}`;
+ }
+
+ if (Object.keys(embeddedResolutions).length === 0) {
+ await fs.remove(embeddedDir);
+ }
+ } else {
+ // ── Step 1b: Pack main plugin only ──────────────────────────────────
+ // Frontend plugins without --pre-packed-dir don't need transitive
+ // local deps -- just pack the main plugin directly into the bundle root.
+ console.log(chalk.blue(`Packing main plugin ${chalk.cyan(pkg.name)}...`));
+
+ const distLog = createStepLogger(
+ joinPath(target, 'dist-workspace.log'),
+ opts.verbose,
+ );
+
+ try {
+ await packToDirectory({
+ packageDir: targetPaths.dir,
+ packageName: pkg.name,
+ targetDir: target,
+ logger: distLog.logger,
+ });
+ } catch (err) {
+ await distLog.close();
+ await showLogOnError(distLog.path, opts.verbose);
+ throw err;
+ }
+ await distLog.close();
+ await fs.remove(distLog.path);
+ }
+
+ // Remove any previous bundle output directories that were erroneously
+ // included by yarn pack (npm-packlist's basename matching on the `files`
+ // field picks up identically-named entries from prior bundle outputs).
+ for (const dir of bundleOutputDirs) {
+ const nestedPath = joinPath(target, dir);
+ if (await fs.pathExists(nestedPath)) {
+ await fs.remove(nestedPath);
+ }
+ }
+
+ // Remove src/ directory included by yarn pack because prepack's
+ // rewriteEntryPoints cannot rewrite main/types away from src/ paths
+ // when the standard dist output files are absent (MF builds).
+ // Skip if the package explicitly ships src/ via the "files" field.
+ if (pluginType === 'frontend') {
+ const srcExplicitlyIncluded = (pkg.files ?? []).some(
+ f => f === 'src' || f.startsWith('src/'),
+ );
+ if (!srcExplicitlyIncluded) {
+ const srcPath = joinPath(target, 'src');
+ if (await fs.pathExists(srcPath)) {
+ await fs.remove(srcPath);
+ }
+ }
+ }
+
+ // ── Step 3: Config schema ────────────────────────────────────────────
+ console.log(chalk.blue('Filtering config schema...'));
+
+ const schemaPath = resolvePath(target, 'dist', '.config-schema.json');
+ let schemas: Array<{ packageName: string }> = [];
+
+ if (pluginType === 'frontend' && (await fs.pathExists(schemaPath))) {
+ const existing = await fs.readJson(schemaPath);
+ schemas = existing.schemas ?? [];
+ } else {
+ const configSchema = await loadConfigSchema({
+ dependencies: [],
+ packagePaths: ['package.json'],
+ });
+ const serialized = configSchema.serialize() as {
+ schemas: typeof schemas;
+ };
+ schemas = serialized.schemas ?? [];
+ }
+
+ let schemaWritten = false;
+ if (schemas.length > 0) {
+ const filtered = filterBundleConfigSchemas(schemas, targetPaths.dir);
+ if (filtered.length > 0) {
+ await fs.ensureDir(resolvePath(target, 'dist'));
+ await fs.writeJson(
+ schemaPath,
+ { backstageConfigSchemaVersion: 1, schemas: filtered },
+ { spaces: 2 },
+ );
+ schemaWritten = true;
+ } else {
+ console.log(
+ chalk.dim(' No config schemas found for this plugin bundle'),
+ );
+ }
+ } else {
+ console.log(chalk.dim(' No config schemas found for this plugin bundle'));
+ }
+
+ // ── Step 4: Post-process package.json ────────────────────────────────
+ console.log(
+ chalk.blue(
+ `Customizing ${chalk.cyan('package.json')} for dynamic loading...`,
+ ),
+ );
+
+ const targetPkgPath = resolvePath(target, 'package.json');
+ const targetPkg = await fs.readJson(targetPkgPath);
+
+ postProcessBundlePackageJson(
+ targetPkg,
+ target,
+ pluginType,
+ needsDependencies ? rootPkg?.resolutions : undefined,
+ embeddedResolutions,
+ needsDependencies,
+ );
+
+ if (schemaWritten) {
+ targetPkg.configSchema = 'dist/.config-schema.json';
+ }
+
+ await fs.writeJson(targetPkgPath, targetPkg, { spaces: 2 });
+
+ // ── Step 5: Seed lockfile, prune, & install ──────────────────────────
+ // Runs for backend plugins (always) and frontend plugins with
+ // --pre-packed-dir (for SBOM lockfile generation).
+ if (needsDependencies) {
+ await seedBundleLockfile(target, targetPaths.dir, targetPaths.rootDir);
+
+ const sourceCacheFolder = await runOutput(
+ ['yarn', 'config', 'get', 'cacheFolder'],
+ { cwd: targetPaths.rootDir },
+ );
+ await pruneBundleLockfile(target, opts.verbose, sourceCacheFolder);
+
+ if (pluginType === 'backend') {
+ if (opts.install) {
+ await installBundleDependencies(target, opts.verbose);
+
+ // Clean up .yarn directory created during install
+ const yarnDir = joinPath(target, '.yarn');
+ if (await fs.pathExists(yarnDir)) {
+ await fs.remove(yarnDir);
+ }
+
+ console.log(chalk.blue('Validating plugin entry points...'));
+
+ // Temporarily patch module resolution so the plugin can resolve
+ // itself by name (needed by resolvePackagePath at module load
+ // time, e.g. for database migration paths). At runtime this is
+ // handled by CommonJSModuleLoader in backend-dynamic-feature-service.
+ const NodeModule =
+ require('node:module') as typeof import('node:module') & {
+ _resolveFilename: Function;
+ };
+ const origResolveFilename = NodeModule._resolveFilename;
+ NodeModule._resolveFilename = (request: string, ...args: any[]) => {
+ if (request === `${targetPkg.name}/package.json`) {
+ return resolvePath(target, 'package.json');
+ }
+ return origResolveFilename(request, ...args);
+ };
+
+ try {
+ const pluginRequire = createRequire(`${target}/package.json`);
+ const mainModule = pluginRequire(target);
+ const alphaPath = resolvePath(target, 'alpha');
+ const alphaModule = (await fs.pathExists(alphaPath))
+ ? pluginRequire(alphaPath)
+ : undefined;
+
+ const isBackendFeature = (v: unknown) =>
+ !!v &&
+ (typeof v === 'object' || typeof v === 'function') &&
+ (v as { $$type?: string }).$$type === '@backstage/BackendFeature';
+
+ const hasValidExport = [mainModule, alphaModule]
+ .filter(Boolean)
+ .some(m => isBackendFeature(m?.default));
+
+ if (!hasValidExport) {
+ throw new Error(
+ `Backend plugin is not valid for dynamic loading: ` +
+ `it must export a ${chalk.cyan(
+ 'BackendFeature',
+ )} as default export`,
+ );
+ }
+ } finally {
+ NodeModule._resolveFilename = origResolveFilename;
+ }
+ } else {
+ console.log(
+ chalk.yellow(
+ 'Skipping dependency installation and validation. ' +
+ 'Run without --no-install to validate the bundle.',
+ ),
+ );
+ }
+ }
+ }
+
+ console.log(chalk.green(`Bundle created at ${chalk.cyan(target)}`));
+}
+
+/**
+ * Mutates `targetPkg` in place to prepare it for dynamic plugin loading:
+ * clears scripts/devDependencies, applies plugin-type-specific adjustments
+ * (MF entry points for frontend, bundleDependencies for backend), and merges
+ * root + embedded resolutions when a lockfile is involved.
+ */
+export function postProcessBundlePackageJson(
+ targetPkg: Record,
+ targetDir: string,
+ pluginType: 'frontend' | 'backend',
+ rootResolutions: Record | undefined,
+ embeddedResolutions: Record,
+ needsDependencies: boolean,
+): void {
+ targetPkg.scripts = {};
+ targetPkg.devDependencies = {};
+
+ if (pluginType === 'frontend') {
+ targetPkg.main = './dist/remoteEntry.js';
+
+ const mfTypesIndex = resolvePath(
+ targetDir,
+ 'dist',
+ '@mf-types',
+ 'index.d.ts',
+ );
+ if (fs.pathExistsSync(mfTypesIndex)) {
+ targetPkg.types = './dist/@mf-types/index.d.ts';
+ } else {
+ delete targetPkg.types;
+ }
+
+ delete targetPkg.exports;
+ delete targetPkg.module;
+ delete targetPkg.typesVersions;
+ } else if (pluginType === 'backend') {
+ targetPkg.bundleDependencies = true;
+ }
+
+ if (needsDependencies) {
+ const patchVersionPattern = /^patch:.+@npm%3A([^#]+)#/;
+ const stripped: Record = {};
+ if (rootResolutions) {
+ for (const [key, value] of Object.entries(rootResolutions)) {
+ if (typeof value !== 'string') {
+ continue;
+ }
+ const patchMatch = value.match(patchVersionPattern);
+ stripped[key] = patchMatch ? patchMatch[1] : value;
+ }
+ }
+
+ targetPkg.resolutions = {
+ ...stripped,
+ ...(targetPkg.resolutions as Record | undefined),
+ ...embeddedResolutions,
+ };
+ }
+}
+
+/**
+ * Seeds the bundle's yarn.lock from the source plugin or monorepo lockfile.
+ * Looks first for a local yarn.lock in the plugin directory, then falls back
+ * to the monorepo root.
+ */
+async function seedBundleLockfile(
+ targetDir: string,
+ pluginDir: string,
+ monorepoRoot: string,
+): Promise {
+ let sourceYarnLock: string | undefined;
+ if (await fs.pathExists(joinPath(pluginDir, 'yarn.lock'))) {
+ sourceYarnLock = joinPath(pluginDir, 'yarn.lock');
+ } else if (await fs.pathExists(joinPath(monorepoRoot, 'yarn.lock'))) {
+ sourceYarnLock = joinPath(monorepoRoot, 'yarn.lock');
+ }
+
+ if (!sourceYarnLock) {
+ throw new Error(
+ `Could not find a ${chalk.cyan(
+ 'yarn.lock',
+ )} file in either the plugin directory or the monorepo root (${chalk.cyan(
+ monorepoRoot,
+ )})`,
+ );
+ }
+
+ const isMonorepoLock = sourceYarnLock === joinPath(monorepoRoot, 'yarn.lock');
+ console.log(
+ chalk.blue(
+ `Seeding bundle ${chalk.cyan('yarn.lock')} from source plugin${
+ isMonorepoLock ? ' monorepo' : ''
+ } lockfile...`,
+ ),
+ );
+
+ await fs.copyFile(sourceYarnLock, resolvePath(targetDir, 'yarn.lock'));
+}
+
+/**
+ * Prunes the bundle's yarn.lock to remove entries not required by the
+ * bundle's package.json. Runs offline to avoid network access.
+ */
+async function pruneBundleLockfile(
+ targetDir: string,
+ verbose: boolean,
+ sourceCacheFolder: string,
+): Promise {
+ console.log(
+ chalk.blue(
+ `Pruning bundle ${chalk.cyan(
+ 'yarn.lock',
+ )} to remove unused dependencies...`,
+ ),
+ );
+
+ const pruneLog = createStepLogger(
+ joinPath(targetDir, 'lockfile-prune.log'),
+ verbose,
+ '[lockfile-prune] ',
+ );
+ try {
+ await run(
+ ['yarn', 'install', '--no-immutable', '--mode', 'update-lockfile'],
+ {
+ cwd: targetDir,
+ env: {
+ YARN_ENABLE_GLOBAL_CACHE: 'false',
+ YARN_ENABLE_NETWORK: '0',
+ YARN_ENABLE_MIRROR: 'false',
+ YARN_CACHE_FOLDER: sourceCacheFolder,
+ },
+ onStdout: pruneLog.logRunOutput('out'),
+ onStderr: pruneLog.logRunOutput('err'),
+ },
+ ).waitForExit();
+ } catch (err) {
+ await pruneLog.close();
+ await showLogOnError(pruneLog.path, verbose);
+ throw err;
+ }
+ await pruneLog.close();
+ await fs.remove(pruneLog.path);
+}
+
+/**
+ * Installs the bundle's dependencies using an immutable lockfile.
+ * This creates the node_modules directory needed for backend plugin runtime.
+ */
+async function installBundleDependencies(
+ targetDir: string,
+ verbose: boolean,
+): Promise {
+ console.log(chalk.blue('Installing private dependencies...'));
+
+ const installLog = createStepLogger(
+ joinPath(targetDir, 'yarn-install.log'),
+ verbose,
+ '[yarn-install] ',
+ );
+ try {
+ await run(['yarn', 'install', '--immutable'], {
+ cwd: targetDir,
+ onStdout: installLog.logRunOutput('out'),
+ onStderr: installLog.logRunOutput('err'),
+ }).waitForExit();
+ } catch (err) {
+ await installLog.close();
+ await showLogOnError(installLog.path, verbose);
+ throw err;
+ }
+ await installLog.close();
+ await fs.remove(installLog.path);
+}
+
+/**
+ * Filters config schemas to keep only those belonging to the plugin's own
+ * family: the plugin itself, same-pluginId libraries, third-party packages,
+ * and recursively any directly-depended plugin/module (wrapper scenario).
+ */
+export function filterBundleConfigSchemas(
+ schemas: { packageName: string }[],
+ pluginDir: string,
+): { packageName: string }[] {
+ const PLUGIN_OR_MODULE_ROLES = new Set([
+ 'backend-plugin',
+ 'backend-plugin-module',
+ 'frontend-plugin',
+ 'frontend-plugin-module',
+ ]);
+ const LIBRARY_ROLES = new Set([
+ 'node-library',
+ 'common-library',
+ 'web-library',
+ ]);
+
+ const allowed = new Set();
+ const visited = new Set();
+ const localRequire = createRequire(resolvePath(pluginDir, 'package.json'));
+
+ function walk(pkg: BackstagePackageJson) {
+ if (visited.has(pkg.name)) {
+ return;
+ }
+ visited.add(pkg.name);
+ allowed.add(pkg.name);
+
+ const pluginId = pkg.backstage?.pluginId;
+
+ for (const depName of Object.keys(pkg.dependencies ?? {})) {
+ let depPkgPath: string;
+ try {
+ depPkgPath = localRequire.resolve(`${depName}/package.json`);
+ } catch {
+ continue;
+ }
+
+ let depPkg: BackstagePackageJson;
+ try {
+ depPkg = fs.readJsonSync(depPkgPath);
+ } catch {
+ continue;
+ }
+
+ const depRole = depPkg.backstage?.role;
+
+ if (!depPkg.backstage) {
+ allowed.add(depName);
+ continue;
+ }
+
+ if (depRole && PLUGIN_OR_MODULE_ROLES.has(depRole)) {
+ walk(depPkg);
+ continue;
+ }
+
+ if (
+ depRole &&
+ LIBRARY_ROLES.has(depRole) &&
+ pluginId &&
+ depPkg.backstage?.pluginId === pluginId
+ ) {
+ allowed.add(depName);
+ continue;
+ }
+ }
+ }
+
+ let rootPkg: BackstagePackageJson;
+ try {
+ rootPkg = fs.readJsonSync(resolvePath(pluginDir, 'package.json'));
+ } catch {
+ return [];
+ }
+ walk(rootPkg);
+
+ return schemas.filter(s => allowed.has(s.packageName));
+}
+
+const ansiPattern =
+ // eslint-disable-next-line no-control-regex
+ /[\x1b\x9b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><~]|\x1b]8;;[^\x07\x1b]*(?:\x07|\x1b\\)/g;
+function stripAnsi(str: string): string {
+ return str.replace(ansiPattern, '');
+}
+
+function createStepLogger(
+ logFilePath: string,
+ verbose: boolean,
+ prefix?: string,
+) {
+ const logStream = fs.createWriteStream(logFilePath);
+
+ const writeLine = (line: string, stream: 'out' | 'err') => {
+ const prefixed = prefix ? `${prefix}${line}` : line;
+ logStream.write(
+ `${stream === 'err' ? '[WARN] ' : ''}${stripAnsi(prefixed)}\n`,
+ );
+ if (verbose) {
+ const writer = stream === 'err' ? console.warn : console.log;
+ writer(chalk.dim(prefixed));
+ }
+ };
+
+ const logger = {
+ log(msg: string) {
+ writeLine(msg, 'out');
+ },
+ warn(msg: string) {
+ writeLine(msg, 'err');
+ },
+ };
+
+ const logRunOutput = (stream: 'out' | 'err') => (data: Buffer) => {
+ if (prefix) {
+ for (const line of data.toString('utf8').split(/\r?\n/)) {
+ if (line) writeLine(line, stream);
+ }
+ } else {
+ logStream.write(
+ `${stream === 'err' ? '[WARN] ' : ''}${stripAnsi(
+ data.toString('utf8'),
+ )}`,
+ );
+ if (verbose) {
+ const writer = stream === 'err' ? console.warn : console.log;
+ writer(chalk.dim(data.toString('utf8')));
+ }
+ }
+ };
+
+ const close = () => new Promise