@backstage/cli 0.36.0-next.1 → 0.36.0-next.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @backstage/cli
 
+## 0.36.0-next.2
+
+### Minor Changes
+
+- d0f4cd2: Added new `auth` command group for authenticating the CLI with Backstage instances using OAuth 2.0 with a pre-registered client metadata document. Commands include `login`, `logout`, `list`, `show`, `print-token`, and `select` for managing multiple authenticated instances.
+
+### Patch Changes
+
+- a4e5902: Internal refactor of the CLI command registration
+- ff4a45a: Migrated remaining CLI command handlers from `commander` to `cleye` for argument parsing. Several camelCase CLI flags have been deprecated in favor of their kebab-case equivalents (e.g. `--successCache` → `--success-cache`). The old camelCase forms still work but will now log a deprecation warning. Please update any scripts or CI configurations to use the kebab-case versions.
+- 4a75544: Updated dependency `react-refresh` to `^0.18.0`.
+- Updated dependencies
+  - @backstage/cli-common@0.2.0-next.2
+  - @backstage/integration@2.0.0-next.2
+
 ## 0.36.0-next.1
 
 ### Minor Changes

package/dist/index.cjs.js

@@ -14,6 +14,7 @@ var CliInitializer = require('./wiring/CliInitializer.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'));
+  initializer.add(import('./modules/auth/index.cjs.js'));
   await initializer.run();
 })();
 //# sourceMappingURL=index.cjs.js.map

package/dist/modules/auth/commands/list.cjs.js

@@ -0,0 +1,23 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var cleye = require('cleye');
+var storage = require('../lib/storage.cjs.js');
+
+var list = async ({ args, info }) => {
+  cleye.cli({ help: info }, void 0, args);
+  const { instances, selected } = await storage.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}
+`);
+  }
+};
+
+exports.default = list;
+//# sourceMappingURL=list.cjs.js.map

package/dist/modules/auth/commands/login.cjs.js

@@ -0,0 +1,316 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var cleye = require('cleye');
+var localServer = require('../lib/localServer.cjs.js');
+var node_child_process = require('node:child_process');
+var pkce = require('../lib/pkce.cjs.js');
+var http = require('../lib/http.cjs.js');
+var storage = require('../lib/storage.cjs.js');
+var secretStore = require('../lib/secretStore.cjs.js');
+var crypto = require('node:crypto');
+var fs = require('fs-extra');
+var path = require('node:path');
+var glob = require('glob');
+var YAML = require('yaml');
+var inquirer = require('inquirer');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var crypto__default = /*#__PURE__*/_interopDefaultCompat(crypto);
+var fs__default = /*#__PURE__*/_interopDefaultCompat(fs);
+var path__default = /*#__PURE__*/_interopDefaultCompat(path);
+var glob__default = /*#__PURE__*/_interopDefaultCompat(glob);
+var YAML__default = /*#__PURE__*/_interopDefaultCompat(YAML);
+var inquirer__default = /*#__PURE__*/_interopDefaultCompat(inquirer);
+
+const TOKEN_EXCHANGE_TIMEOUT_MS = 3e4;
+var login = async ({ args, info }) => {
+  const {
+    flags: { backendUrl, noBrowser, instance: instanceFlag }
+  } = cleye.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)"
+        }
+      }
+    },
+    void 0,
+    args
+  );
+  const { instances, selected } = await storage.getAllInstances();
+  let backendBaseUrl;
+  let instanceName;
+  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(3e4)
+  });
+  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 localServer.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, selected) {
+  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__default.default.prompt([
+    {
+      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 = [];
+  const patterns = [
+    "app-config.yaml",
+    "app-config.*.yaml",
+    "packages/*/app-config.yaml",
+    "packages/*/app-config.*.yaml"
+  ];
+  const files = patterns.flatMap((p) => glob__default.default.sync(p, { cwd, nodir: true }));
+  for (const file of files) {
+    try {
+      const content = await fs__default.default.readFile(path__default.default.resolve(cwd, file), "utf8");
+      const doc = YAML__default.default.parse(content);
+      const url = doc?.backend?.baseUrl;
+      if (url) {
+        candidates.push({ url: normalizeUrl(url), file });
+      }
+    } catch {
+    }
+  }
+  const list = [...new Map(candidates.map((c) => [c.url, c])).values()];
+  if (list.length === 0) {
+    const { manual } = await inquirer__default.default.prompt([
+      { type: "input", name: "manual", message: "Enter backend base URL" }
+    ]);
+    return normalizeUrl(manual);
+  }
+  if (list.length === 1) {
+    return list[0].url;
+  }
+  const { picked } = await inquirer__default.default.prompt([
+    {
+      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__default.default.prompt([
+      { type: "input", name: "manual", message: "Enter backend base URL" }
+    ]);
+    return normalizeUrl(manual);
+  }
+  return picked;
+}
+function normalizeUrl(u) {
+  if (u === void 0) {
+    return void 0;
+  }
+  try {
+    const url = new URL(u);
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    throw new Error(`'${u}' is not a valid URL`);
+  }
+}
+function deriveInstanceName(url) {
+  return new URL(url).host;
+}
+function createPkceState() {
+  const verifier = pkce.generateVerifier();
+  const challenge = pkce.challengeFromVerifier(verifier);
+  const state = cryptoRandom();
+  return { verifier, challenge, state };
+}
+function buildAuthorizeUrl(options) {
+  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, noBrowser) {
+  if (noBrowser) {
+    process.stdout.write(`Open this URL to continue: ${url}
+`);
+  } else {
+    process.stdout.write(`Opening the following URL: ${url}
+`);
+    openInBrowser(url);
+  }
+}
+async function waitForAuthorizationCode(callback, expectedState) {
+  const { code, state } = await callback.waitForCode();
+  if (state !== expectedState) {
+    throw new Error("State mismatch");
+  }
+  return code;
+}
+async function exchangeAuthorizationCode(options) {
+  const { authBaseUrl, code, redirectUri, verifier } = options;
+  return await http.httpJson(`${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) {
+  const { instanceName, backendBaseUrl, clientId, token } = options;
+  const secretStore$1 = await secretStore.getSecretStore();
+  await storage.withMetadataLock(async () => {
+    const service = `backstage-cli:auth-instance:${instanceName}`;
+    await secretStore$1.set(service, "accessToken", token.access_token);
+    if (token.refresh_token) {
+      await secretStore$1.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;
+    try {
+      existing = await storage.getInstanceByName(instanceName);
+    } catch {
+    }
+    await storage.upsertInstance({
+      name: instanceName,
+      baseUrl: backendBaseUrl,
+      clientId,
+      issuedAt: Date.now(),
+      accessTokenExpiresAt: Date.now() + token.expires_in * 1e3,
+      selected: existing?.selected
+    });
+  });
+}
+function cryptoRandom() {
+  return crypto__default.default.randomBytes(32).toString("hex");
+}
+function openInBrowser(url) {
+  const handleError = (error) => {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    process.stderr.write(
+      `Warning: Failed to open browser automatically: ${message}
+`
+    );
+    process.stderr.write(`Please open this URL manually: ${url}
+`);
+  };
+  const spawnOpts = { detached: true, stdio: "ignore" };
+  let child;
+  try {
+    if (process.platform === "darwin") {
+      child = node_child_process.spawn("open", [url], spawnOpts);
+    } else if (process.platform === "win32") {
+      child = node_child_process.spawn(
+        "powershell",
+        ["-Command", `Start-Process '${url.replace(/'/g, "''")}'`],
+        spawnOpts
+      );
+    } else {
+      child = node_child_process.spawn("xdg-open", [url], spawnOpts);
+    }
+    child.unref();
+    child.on("error", handleError);
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+exports.default = login;
+exports.openInBrowser = openInBrowser;
+//# sourceMappingURL=login.cjs.js.map

package/dist/modules/auth/commands/logout.cjs.js

@@ -0,0 +1,55 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var cleye = require('cleye');
+var secretStore = require('../lib/secretStore.cjs.js');
+var storage = require('../lib/storage.cjs.js');
+var http = require('../lib/http.cjs.js');
+var prompt = require('../lib/prompt.cjs.js');
+
+var logout = async ({ args, info }) => {
+  const {
+    flags: { instance: instanceFlag }
+  } = cleye.cli(
+    {
+      help: info,
+      flags: {
+        instance: {
+          type: String,
+          description: "Name of the instance to log out"
+        }
+      }
+    },
+    void 0,
+    args
+  );
+  const { name: instanceName } = await prompt.pickInstance(instanceFlag);
+  await storage.withMetadataLock(async () => {
+    const instance = await storage.getInstanceByName(instanceName);
+    const secretStore$1 = await secretStore.getSecretStore();
+    const service = `backstage-cli:auth-instance:${instanceName}`;
+    const refreshToken = await secretStore$1.get(service, "refreshToken") ?? "";
+    if (refreshToken) {
+      try {
+        const authBaseUrl = new URL("/api/auth", instance.baseUrl).toString().replace(/\/$/, "");
+        await http.httpJson(`${authBaseUrl}/v1/revoke`, {
+          method: "POST",
+          body: {
+            token: refreshToken,
+            token_type_hint: "refresh_token"
+          },
+          signal: AbortSignal.timeout(3e4)
+        });
+      } catch {
+      }
+    }
+    await secretStore$1.delete(service, "accessToken");
+    await secretStore$1.delete(service, "refreshToken");
+    await storage.removeInstance(instance.name);
+  });
+  process.stdout.write("Logged out\n");
+};
+
+exports.default = logout;
+//# sourceMappingURL=logout.cjs.js.map

package/dist/modules/auth/commands/printToken.cjs.js

@@ -0,0 +1,41 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var cleye = require('cleye');
+var auth = require('../lib/auth.cjs.js');
+var storage = require('../lib/storage.cjs.js');
+var secretStore = require('../lib/secretStore.cjs.js');
+
+var printToken = async ({ args, info }) => {
+  const {
+    flags: { instance: instanceFlag }
+  } = cleye.cli(
+    {
+      help: info,
+      flags: {
+        instance: {
+          type: String,
+          description: "Name of the instance to use"
+        }
+      }
+    },
+    void 0,
+    args
+  );
+  let instance = await storage.getSelectedInstance(instanceFlag);
+  if (auth.accessTokenNeedsRefresh(instance)) {
+    instance = await auth.refreshAccessToken(instance.name);
+  }
+  const secretStore$1 = await secretStore.getSecretStore();
+  const service = `backstage-cli:auth-instance:${instance.name}`;
+  const accessToken = await secretStore$1.get(service, "accessToken");
+  if (!accessToken) {
+    throw new Error('No access token found. Run "auth login" to authenticate.');
+  }
+  process.stdout.write(`${accessToken}
+`);
+};
+
+exports.default = printToken;
+//# sourceMappingURL=printToken.cjs.js.map

package/dist/modules/auth/commands/select.cjs.js

@@ -0,0 +1,32 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var cleye = require('cleye');
+var storage = require('../lib/storage.cjs.js');
+var prompt = require('../lib/prompt.cjs.js');
+
+var select = async ({ args, info }) => {
+  const {
+    flags: { instance: instanceFlag }
+  } = cleye.cli(
+    {
+      help: info,
+      flags: {
+        instance: {
+          type: String,
+          description: "Name of the instance to select"
+        }
+      }
+    },
+    void 0,
+    args
+  );
+  const instance = await prompt.pickInstance(instanceFlag);
+  await storage.setSelectedInstance(instance.name);
+  process.stderr.write(`Selected instance '${instance.name}'
+`);
+};
+
+exports.default = select;
+//# sourceMappingURL=select.cjs.js.map

package/dist/modules/auth/commands/show.cjs.js

@@ -0,0 +1,59 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var cleye = require('cleye');
+var http = require('../lib/http.cjs.js');
+var storage = require('../lib/storage.cjs.js');
+var auth = require('../lib/auth.cjs.js');
+var secretStore = require('../lib/secretStore.cjs.js');
+
+var show = async ({ args, info }) => {
+  const {
+    flags: { instance: instanceFlag }
+  } = cleye.cli(
+    {
+      help: info,
+      flags: {
+        instance: {
+          type: String,
+          description: "Name of the instance to show"
+        }
+      }
+    },
+    void 0,
+    args
+  );
+  let instance = await storage.getSelectedInstance(instanceFlag);
+  if (auth.accessTokenNeedsRefresh(instance)) {
+    process.stdout.write("Refreshing access token...\n");
+    instance = await auth.refreshAccessToken(instance.name);
+  }
+  const authBase = new URL("/api/auth", instance.baseUrl).toString().replace(/\/$/, "");
+  const secretStore$1 = await secretStore.getSecretStore();
+  const service = `backstage-cli:auth-instance:${instance.name}`;
+  const accessToken = await secretStore$1.get(service, "accessToken");
+  if (!accessToken) {
+    throw new Error('No access token found. Run "auth login" to authenticate.');
+  }
+  const userinfo = await http.httpJson(
+    `${authBase}/v1/userinfo`,
+    {
+      headers: { Authorization: `Bearer ${accessToken}` },
+      signal: AbortSignal.timeout(3e4)
+    }
+  );
+  process.stdout.write(`User: ${userinfo.claims.sub}
+`);
+  process.stdout.write(`
+`);
+  process.stdout.write(`Ownership:
+`);
+  for (const ent of userinfo.claims.ent ?? []) {
+    process.stdout.write(`  - ${ent}
+`);
+  }
+};
+
+exports.default = show;
+//# sourceMappingURL=show.cjs.js.map

package/dist/modules/auth/index.cjs.js

@@ -0,0 +1,44 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var factory = require('../../wiring/factory.cjs.js');
+
+var index = factory.createCliPlugin({
+  pluginId: "auth",
+  init: async (reg) => {
+    reg.addCommand({
+      path: ["auth", "login"],
+      description: "Log in the CLI to a Backstage instance",
+      execute: { loader: () => import('./commands/login.cjs.js') }
+    });
+    reg.addCommand({
+      path: ["auth", "logout"],
+      description: "Log out the CLI and clear stored credentials",
+      execute: { loader: () => import('./commands/logout.cjs.js') }
+    });
+    reg.addCommand({
+      path: ["auth", "show"],
+      description: "Show details of an authenticated instance",
+      execute: { loader: () => import('./commands/show.cjs.js') }
+    });
+    reg.addCommand({
+      path: ["auth", "list"],
+      description: "List authenticated instances",
+      execute: { loader: () => import('./commands/list.cjs.js') }
+    });
+    reg.addCommand({
+      path: ["auth", "print-token"],
+      description: "Print an access token to stdout (auto-refresh if needed)",
+      execute: { loader: () => import('./commands/printToken.cjs.js') }
+    });
+    reg.addCommand({
+      path: ["auth", "select"],
+      description: "Select the default instance",
+      execute: { loader: () => import('./commands/select.cjs.js') }
+    });
+  }
+});
+
+exports.default = index;
+//# sourceMappingURL=index.cjs.js.map

package/dist/modules/auth/lib/auth.cjs.js

@@ -0,0 +1,60 @@
+'use strict';
+
+var zod = require('zod');
+var storage = require('./storage.cjs.js');
+var secretStore = require('./secretStore.cjs.js');
+var http = require('./http.cjs.js');
+
+const TokenResponseSchema = zod.z.object({
+  access_token: zod.z.string().min(1),
+  token_type: zod.z.string().min(1),
+  expires_in: zod.z.number().positive().finite(),
+  refresh_token: zod.z.string().min(1).optional()
+});
+function accessTokenNeedsRefresh(instance) {
+  return instance.accessTokenExpiresAt <= Date.now() + 2 * 6e4;
+}
+async function refreshAccessToken(instanceName) {
+  const secretStore$1 = await secretStore.getSecretStore();
+  return storage.withMetadataLock(async () => {
+    const instance = await storage.getInstanceByName(instanceName);
+    const service = `backstage-cli:auth-instance:${instanceName}`;
+    const refreshToken = await secretStore$1.get(service, "refreshToken") ?? "";
+    if (!refreshToken) {
+      throw new Error(
+        "Access token is expired and no refresh token is available"
+      );
+    }
+    const response = await http.httpJson(
+      `${instance.baseUrl}/api/auth/v1/token`,
+      {
+        method: "POST",
+        body: {
+          grant_type: "refresh_token",
+          refresh_token: refreshToken
+        },
+        signal: AbortSignal.timeout(3e4)
+      }
+    );
+    const parsed = TokenResponseSchema.safeParse(response);
+    if (!parsed.success) {
+      throw new Error(`Invalid token response: ${parsed.error.message}`);
+    }
+    const token = parsed.data;
+    await secretStore$1.set(service, "accessToken", token.access_token);
+    if (token.refresh_token) {
+      await secretStore$1.set(service, "refreshToken", token.refresh_token);
+    }
+    const newInstance = {
+      ...instance,
+      issuedAt: Date.now(),
+      accessTokenExpiresAt: Date.now() + token.expires_in * 1e3
+    };
+    await storage.upsertInstance(newInstance);
+    return newInstance;
+  });
+}
+
+exports.accessTokenNeedsRefresh = accessTokenNeedsRefresh;
+exports.refreshAccessToken = refreshAccessToken;
+//# sourceMappingURL=auth.cjs.js.map

package/dist/modules/auth/lib/http.cjs.js

@@ -0,0 +1,26 @@
+'use strict';
+
+var fetch = require('cross-fetch');
+var errors = require('@backstage/errors');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var fetch__default = /*#__PURE__*/_interopDefaultCompat(fetch);
+
+async function httpJson(url, init) {
+  const res = await fetch__default.default(url, {
+    ...init,
+    body: init?.body ? JSON.stringify(init.body) : void 0,
+    headers: {
+      ...init?.body ? { "Content-Type": "application/json" } : {},
+      ...init?.headers
+    }
+  });
+  if (!res.ok) {
+    throw await errors.ResponseError.fromResponse(res);
+  }
+  return await res.json();
+}
+
+exports.httpJson = httpJson;
+//# sourceMappingURL=http.cjs.js.map