@backstage/cli 0.36.0-next.1 → 0.36.0

package/config/nodeTransformHooks.mjs

@@ -14,281 +14,7 @@
  * limitations under the License.
  */
 
-import { dirname, extname, resolve as resolvePath } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { transformFile } from '@swc/core';
-import { isBuiltin } from 'node:module';
-import { readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-
-// @ts-check
-
-// No explicit file extension, no type in package.json
-const DEFAULT_MODULE_FORMAT = 'commonjs';
-
-// Source file extensions to look for when using bundle resolution strategy
-const SRC_EXTS = ['.ts', '.js'];
-const TS_EXTS = ['.ts', '.mts', '.cts'];
-const moduleTypeTable = {
-  '.mjs': 'module',
-  '.mts': 'module',
-  '.cjs': 'commonjs',
-  '.cts': 'commonjs',
-  '.ts': undefined,
-  '.js': undefined,
-};
-
-/** @type {import('module').ResolveHook} */
-export async function resolve(specifier, context, nextResolve) {
-  // Built-in modules are handled by the default resolver
-  if (isBuiltin(specifier)) {
-    return nextResolve(specifier, context);
-  }
-
-  const ext = extname(specifier);
-
-  // Unless there's an explicit import attribute, JSON files are loaded with our custom loader that's defined below.
-  if (ext === '.json' && !context.importAttributes?.type) {
-    const jsonResult = await nextResolve(specifier, context);
-    return {
-      ...jsonResult,
-      format: 'commonjs',
-      importAttributes: { type: 'json' },
-    };
-  }
-
-  // Anything else with an explicit extension is handled by the default
-  // resolver, except that we help determine the module type where needed.
-  if (ext !== '') {
-    return withDetectedModuleType(await nextResolve(specifier, context));
-  }
-
-  // Other external modules are handled by the default resolver, but again we
-  // help determine the module type where needed.
-  if (!specifier.startsWith('.')) {
-    return withDetectedModuleType(await nextResolve(specifier, context));
-  }
-
-  // The rest of this function handles the case of resolving imports that do not
-  // specify any extension and might point to a directory with an `index.*`
-  // file. We resolve those using the same logic as most JS bundlers would, with
-  // the addition of checking if there's an explicit module format listed in the
-  // closest `package.json` file.
-  //
-  // We use a bundle resolution strategy in order to keep code consistent across
-  // Backstage codebases that contains code both for Web and Node.js, and to
-  // support packages with common code that can be used in both environments.
-  try {
-    // This is expected to throw, but in the event that this module specifier is
-    // supported we prefer to use the default resolver.
-    return await nextResolve(specifier, context);
-  } catch (error) {
-    if (error.code === 'ERR_UNSUPPORTED_DIR_IMPORT') {
-      const spec = `${specifier}${specifier.endsWith('/') ? '' : '/'}index`;
-      const resolved = await resolveWithoutExt(spec, context, nextResolve);
-      if (resolved) {
-        return withDetectedModuleType(resolved);
-      }
-    } else if (error.code === 'ERR_MODULE_NOT_FOUND') {
-      const resolved = await resolveWithoutExt(specifier, context, nextResolve);
-      if (resolved) {
-        return withDetectedModuleType(resolved);
-      }
-    }
-
-    // Unexpected error or no resolution found
-    throw error;
-  }
-}
-
-/**
- * Populates the `format` field in the resolved object based on the closest `package.json` file.
- *
- * @param {import('module').ResolveFnOutput} resolved
- * @returns {Promise<import('module').ResolveFnOutput>}
- */
-async function withDetectedModuleType(resolved) {
-  // Already has an explicit format
-  if (resolved.format) {
-    return resolved;
-  }
-  // Happens in Node.js v22 when there's a package.json without an explicit "type" field. Use the default.
-  if (resolved.format === null) {
-    return { ...resolved, format: DEFAULT_MODULE_FORMAT };
-  }
-
-  const ext = extname(resolved.url);
-
-  const explicitFormat = moduleTypeTable[ext];
-  if (explicitFormat) {
-    return {
-      ...resolved,
-      format: explicitFormat,
-    };
-  }
-
-  // Under normal circumstances .js files should reliably have a format and so
-  // we should only reach this point for .ts files. However, if additional
-  // custom loaders are being used the format may not be detected for .js files
-  // either. As such we don't restrict the file format at this point.
-
-  // TODO(Rugvip): Does this need caching? kept it simple for now but worth exploring
-  const packageJsonPath = await findPackageJSON(fileURLToPath(resolved.url));
-  if (!packageJsonPath) {
-    return resolved;
-  }
-
-  const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8'));
-  return {
-    ...resolved,
-    format: packageJson.type ?? DEFAULT_MODULE_FORMAT,
-  };
-}
-
-/**
- * Find the closest package.json file from the given path.
- *
- * TODO(Rugvip): This can be replaced with the Node.js built-in with the same name once it is stable.
- * @param {string} startPath
- * @returns {Promise<string | undefined>}
- */
-async function findPackageJSON(startPath) {
-  let path = startPath;
-
-  // Some confidence check to avoid infinite loop
-  for (let i = 0; i < 1000; i++) {
-    const packagePath = resolvePath(path, 'package.json');
-    if (existsSync(packagePath)) {
-      return packagePath;
-    }
-
-    const newPath = dirname(path);
-    if (newPath === path) {
-      return undefined;
-    }
-    path = newPath;
-  }
-
-  throw new Error(
-    `Iteration limit reached when searching for package.json at ${startPath}`,
-  );
-}
-
-/** @type {import('module').ResolveHook} */
-async function resolveWithoutExt(specifier, context, nextResolve) {
-  for (const tryExt of SRC_EXTS) {
-    try {
-      const resolved = await nextResolve(specifier + tryExt, {
-        ...context,
-        format: 'commonjs',
-      });
-      return {
-        ...resolved,
-        format: moduleTypeTable[tryExt] ?? resolved.format,
-      };
-    } catch {
-      /* ignore */
-    }
-  }
-  return undefined;
-}
-
-/** @type {import('module').LoadHook} */
-export async function load(url, context, nextLoad) {
-  // Non-file URLs are handled by the default loader
-  if (!url.startsWith('file://')) {
-    return nextLoad(url, context);
-  }
-
-  // JSON files loaded as CommonJS are handled by this custom loader, because
-  // the default one doesn't work. For JSON loading to work we'd need the
-  // synchronous hooks that aren't supported yet, or avoid using the CommonJS
-  // compatibility.
-  if (
-    context.format === 'commonjs' &&
-    context.importAttributes?.type === 'json'
-  ) {
-    try {
-      // TODO(Rugvip): Make sure this is valid JSON
-      const content = await readFile(fileURLToPath(url), 'utf8');
-      return {
-        source: `module.exports = (${content})`,
-        format: 'commonjs',
-        shortCircuit: true,
-      };
-    } catch {
-      // Let the default loader generate the error
-      return nextLoad(url, context);
-    }
-  }
-
-  const ext = extname(url);
-
-  // Non-TS files are handled by the default loader
-  if (!TS_EXTS.includes(ext)) {
-    return nextLoad(url, context);
-  }
-
-  const format = context.format ?? DEFAULT_MODULE_FORMAT;
-
-  // We have two choices at this point, we can either transform CommonJS files
-  // and return the transformed source code, or let the default loader handle
-  // them. If we transform them ourselves we will enter CommonJS compatibility
-  // mode in the new module system in Node.js, this effectively means all
-  // CommonJS loaded via `require` calls from this point will all be treated as
-  // if it was loaded via `import` calls from modules.
-  //
-  // The CommonJS compatibility layer will try to identify named exports and
-  // make them available directly, which is convenient as it avoids things like
-  // `import(...).then(m => m.default.foo)`, allowing you to instead write
-  // `import(...).then(m => m.foo)`. The compatibility layer doesn't always work
-  // all that well though, and can lead to module loading issues in many cases,
-  // especially for older code.
-
-  // This `if` block opts-out of using CommonJS compatibility mode by default,
-  // and instead leaves it to our existing loader to transform CommonJS. We do
-  // however use compatibility mode for the more explicit .cts file extension,
-  // allows for a way to opt-in to the new behavior.
-  //
-  // TODO(Rugvip): Once the synchronous hooks API is available for us to use, we might be able to adopt that instead
-  if (format === 'commonjs' && ext !== '.cts') {
-    return nextLoad(url, { ...context, format });
-  }
-
-  // If the Node.js version we're running supports TypeScript, i.e. type
-  // stripping, we hand over to the default loader. This is done for all cases
-  // except if we're loading a .ts file that's been resolved to CommonJS format.
-  // This is because these files aren't actually CommonJS in the Backstage build
-  // system, and need to be transformed to CommonJS.
-  if (
-    format === 'module-typescript' ||
-    (format === 'module-commonjs' && ext !== '.ts')
-  ) {
-    return nextLoad(url, { ...context, format });
-  }
-
-  const transformed = await transformFile(fileURLToPath(url), {
-    sourceMaps: 'inline',
-    module: {
-      type: format === 'module' ? 'es6' : 'commonjs',
-      ignoreDynamic: true,
-
-      // This helps the Node.js CommonJS compat layer identify named exports.
-      exportInteropAnnotation: true,
-    },
-    jsc: {
-      target: 'es2023',
-      parser: {
-        syntax: 'typescript',
-      },
-    },
-  });
-
-  return {
-    ...context,
-    shortCircuit: true,
-    source: transformed.code,
-    format,
-    responseURL: url,
-  };
-}
+export {
+  resolve,
+  load,
+} from '@backstage/cli-node/config/nodeTransformHooks.mjs';

package/config/webpack-public-path.js

@@ -14,18 +14,14 @@
  * 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 <base> 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;
+try {
+  require('@backstage/cli-module-build/config/webpack-public-path');
+} catch (e) {
+  if (e.code === 'MODULE_NOT_FOUND') {
+    throw new Error(
+      '@backstage/cli-module-build is required to use the webpack public path configuration. ' +
+        'Please install it as a dependency.',
+    );
+  }
+  throw e;
 }

package/dist/cli-internal/src/InternalCliModule.cjs.js

@@ -0,0 +1,11 @@
+'use strict';
+
+var OpaqueType = require('../../opaque-internal/src/OpaqueType.cjs.js');
+
+const OpaqueCliModule = OpaqueType.OpaqueType.create({
+  type: "@backstage/CliModule",
+  versions: ["v1"]
+});
+
+exports.OpaqueCliModule = OpaqueCliModule;
+//# sourceMappingURL=InternalCliModule.cjs.js.map

package/dist/cli-internal/src/InternalCommandNode.cjs.js

@@ -0,0 +1,25 @@
+'use strict';
+
+var OpaqueType = require('../../opaque-internal/src/OpaqueType.cjs.js');
+
+const OpaqueCommandTreeNode = OpaqueType.OpaqueType.create({
+  type: "@backstage/CommandTreeNode",
+  versions: ["v1"]
+});
+const OpaqueCommandLeafNode = OpaqueType.OpaqueType.create({
+  type: "@backstage/CommandLeafNode",
+  versions: ["v1"]
+});
+function isCommandNodeHidden(node) {
+  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));
+}
+
+exports.OpaqueCommandLeafNode = OpaqueCommandLeafNode;
+exports.OpaqueCommandTreeNode = OpaqueCommandTreeNode;
+exports.isCommandNodeHidden = isCommandNodeHidden;
+//# sourceMappingURL=InternalCommandNode.cjs.js.map

package/dist/cli-internal/src/knownPluginPackages.cjs.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const knownBackendPluginIds = [
+  "app",
+  "auth",
+  "catalog",
+  "events",
+  "kubernetes",
+  "notifications",
+  "permission",
+  "proxy",
+  "scaffolder",
+  "search",
+  "signals",
+  "techdocs"
+];
+const knownFrontendPluginIds = [
+  "app",
+  "auth",
+  "catalog",
+  "kubernetes",
+  "notifications",
+  "scaffolder",
+  "search",
+  "signals",
+  "techdocs"
+];
+Object.fromEntries(
+  knownBackendPluginIds.map((pluginId) => [
+    pluginId,
+    `@backstage/plugin-${pluginId}-backend`
+  ])
+);
+Object.fromEntries(
+  knownFrontendPluginIds.map((pluginId) => [
+    pluginId,
+    `@backstage/plugin-${pluginId}`
+  ])
+);
+//# sourceMappingURL=knownPluginPackages.cjs.js.map

package/dist/index.cjs.js

@@ -1,19 +1,30 @@
 'use strict';
 
+var chalk = require('chalk');
 var CliInitializer = require('./wiring/CliInitializer.cjs.js');
+var discoverCliModules = require('./wiring/discoverCliModules.cjs.js');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var chalk__default = /*#__PURE__*/_interopDefaultCompat(chalk);
 
 (async () => {
   const initializer = new CliInitializer.CliInitializer();
-  initializer.add(import('./modules/build/index.cjs.js'));
-  initializer.add(import('./modules/config/index.cjs.js'));
-  initializer.add(import('./modules/create-github-app/index.cjs.js'));
-  initializer.add(import('./modules/info/index.cjs.js'));
-  initializer.add(import('./modules/lint/index.cjs.js'));
-  initializer.add(import('./modules/maintenance/index.cjs.js'));
-  initializer.add(import('./modules/migrate/index.cjs.js'));
-  initializer.add(import('./modules/new/index.cjs.js'));
-  initializer.add(import('./modules/test/index.cjs.js'));
-  initializer.add(import('./modules/translations/index.cjs.js'));
+  const discoveredModules = discoverCliModules.discoverCliModules();
+  if (discoveredModules.length > 0) {
+    for (const resolvedPath of discoveredModules) {
+      initializer.add(import(resolvedPath));
+    }
+  } else {
+    console.error(
+      chalk__default.default.yellow(
+        `No CLI modules found in the project root dependencies. Falling back to the built-in set of modules.
+This fallback will be removed in a future release. Please add @backstage/cli-defaults as a devDependency in your root package.json, or install individual @backstage/cli-module-* packages for fine-grained control.
+`
+      )
+    );
+    initializer.add(import('@backstage/cli-defaults'));
+  }
   await initializer.run();
 })();
 //# sourceMappingURL=index.cjs.js.map

package/dist/wiring/CliInitializer.cjs.js

@@ -1,8 +1,12 @@
 'use strict';
 
 var CommandGraph = require('./CommandGraph.cjs.js');
-var types$1 = require('./types.cjs.js');
-var CommandRegistry = require('./CommandRegistry.cjs.js');
+var InternalCliModule = require('../cli-internal/src/InternalCliModule.cjs.js');
+var InternalCommandNode = require('../cli-internal/src/InternalCommandNode.cjs.js');
+require('node:fs');
+require('node:os');
+require('node:path');
+require('../cli-internal/src/knownPluginPackages.cjs.js');
 var commander = require('commander');
 var version = require('./version.cjs.js');
 var chalk = require('chalk');
@@ -16,28 +20,56 @@ var chalk__default = /*#__PURE__*/_interopDefaultCompat(chalk);
 
 class CliInitializer {
   graph = new CommandGraph.CommandGraph();
-  commandRegistry = new CommandRegistry.CommandRegistry(this.graph);
   #uninitiazedFeatures = [];
   add(feature) {
     if (types.isPromise(feature)) {
       this.#uninitiazedFeatures.push(
-        feature.then((f) => unwrapFeature(f.default))
+        feature.then((f) => {
+          const unwrapped = unwrapFeature(f.default);
+          if (Array.isArray(unwrapped)) {
+            return unwrapped.map((m) => ({ feature: m, fromArray: true }));
+          }
+          return [{ feature: unwrapped, fromArray: false }];
+        })
+      );
+    } else if (Array.isArray(feature)) {
+      this.#uninitiazedFeatures.push(
+        Promise.resolve(feature.map((m) => ({ feature: m, fromArray: true })))
       );
     } else {
-      this.#uninitiazedFeatures.push(Promise.resolve(feature));
+      this.#uninitiazedFeatures.push(
+        Promise.resolve([{ feature, fromArray: false }])
+      );
     }
   }
   async #register(feature) {
-    if (types$1.OpaqueCliPlugin.isType(feature)) {
-      const internal = types$1.OpaqueCliPlugin.toInternal(feature);
-      await internal.init(this.commandRegistry);
+    if (InternalCliModule.OpaqueCliModule.isType(feature)) {
+      for (const command of await InternalCliModule.OpaqueCliModule.toInternal(feature).commands) {
+        this.graph.add(command, feature);
+      }
     } else {
       throw new Error(`Unsupported feature type: ${feature.$$type}`);
     }
   }
   async #doInit() {
-    const features = await Promise.all(this.#uninitiazedFeatures);
-    for (const feature of features) {
+    const resolvedGroups = await Promise.all(this.#uninitiazedFeatures);
+    const allFeatures = resolvedGroups.flat();
+    const individualPaths = /* @__PURE__ */ new Set();
+    for (const { feature, fromArray } of allFeatures) {
+      if (!fromArray && InternalCliModule.OpaqueCliModule.isType(feature)) {
+        const cmds = await InternalCliModule.OpaqueCliModule.toInternal(feature).commands;
+        for (const cmd of cmds) {
+          individualPaths.add(cmd.path.join(" "));
+        }
+      }
+    }
+    for (const { feature, fromArray } of allFeatures) {
+      if (fromArray && InternalCliModule.OpaqueCliModule.isType(feature)) {
+        const cmds = await InternalCliModule.OpaqueCliModule.toInternal(feature).commands;
+        if (cmds.some((cmd) => individualPaths.has(cmd.path.join(" ")))) {
+          continue;
+        }
+      }
       await this.#register(feature);
     }
   }
@@ -55,23 +87,29 @@ class CliInitializer {
     }));
     while (queue.length) {
       const { node, argParser } = queue.shift();
-      if (node.$$type === "@tree/root") {
-        const treeParser = argParser.command(`${node.name} [command]`).description(node.name);
+      if (InternalCommandNode.OpaqueCommandTreeNode.isType(node)) {
+        const internal = InternalCommandNode.OpaqueCommandTreeNode.toInternal(node);
+        const treeParser = argParser.command(`${internal.name} [command]`, {
+          hidden: InternalCommandNode.isCommandNodeHidden(node)
+        }).description(internal.name);
         queue.push(
-          ...node.children.map((child) => ({
+          ...internal.children.map((child) => ({
             node: child,
             argParser: treeParser
           }))
         );
       } else {
-        argParser.command(node.name, { hidden: !!node.command.deprecated }).description(node.command.description).helpOption(false).allowUnknownOption(true).allowExcessArguments(true).action(async () => {
+        const internal = InternalCommandNode.OpaqueCommandLeafNode.toInternal(node);
+        argParser.command(internal.name, {
+          hidden: !!internal.command.deprecated || !!internal.command.experimental
+        }).description(internal.command.description).helpOption(false).allowUnknownOption(true).allowExcessArguments(true).action(async () => {
           try {
             const args = program.parseOptions(process.argv);
             const nonProcessArgs = args.operands.slice(2);
             const positionalArgs = [];
             let index = 0;
             for (let argIndex = 0; argIndex < nonProcessArgs.length; argIndex++) {
-              if (argIndex === index && node.command.path[argIndex] === nonProcessArgs[argIndex]) {
+              if (argIndex === index && internal.command.path[argIndex] === nonProcessArgs[argIndex]) {
                 index += 1;
                 continue;
               }
@@ -80,14 +118,14 @@ class CliInitializer {
             const context = {
               args: [...positionalArgs, ...args.unknown],
               info: {
-                usage: [programName, ...node.command.path].join(" "),
-                description: node.command.description
+                usage: [programName, ...internal.command.path].join(" "),
+                name: internal.command.path.join(" ")
               }
             };
-            if (typeof node.command.execute === "function") {
-              await node.command.execute(context);
+            if (typeof internal.command.execute === "function") {
+              await internal.command.execute(context);
             } else {
-              const mod = await node.command.execute.loader();
+              const mod = await internal.command.execute.loader();
               const fn = typeof mod.default === "function" ? mod.default : mod.default.default;
               await fn(context);
             }
@@ -112,6 +150,9 @@ class CliInitializer {
   }
 }
 function unwrapFeature(feature) {
+  if (Array.isArray(feature)) {
+    return feature;
+  }
   if ("$$type" in feature) {
     return feature;
   }