Address Copilot review feedback

- Handle --inspect/--inspect-brk optional host value by extracting
  them from raw args before passing to cleye (supports both bare
  --inspect and --inspect=host:port forms)
- Change require flag from [String] to String in package start since
  downstream only accepts a single value
- Preserve legacy --alwaysYarnPack alias in build-workspace command
- Update changeset to mention camelCase → kebab-case flag changes

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

.changeset/migrate-cli-commands-to-cleye.md

@@ -2,4 +2,4 @@
 '@backstage/cli': patch
 ---
 
-Migrated remaining CLI command handlers from `commander` to `cleye` for argument parsing.
+Migrated remaining CLI command handlers from `commander` to `cleye` for argument parsing. A few CLI flags that were previously camelCase have been normalized to kebab-case to match standard CLI conventions. Affected flags: `--baseVersion` → `--base-version`, `--successCache` → `--success-cache`, `--successCacheDir` → `--success-cache-dir`, `--alwaysPack` → `--always-pack`.

packages/cli/cli-report.md

@@ -310,8 +310,6 @@ Options:
   --check
   --config <string>
   --entrypoint <string>
-  --inspect <string>
-  --inspect-brk <string>
   --link <string>
   --require <string>
   --role <string>
@@ -515,8 +513,6 @@ Usage: backstage-cli repo start
 
 Options:
   --config <string>
-  --inspect <string>
-  --inspect-brk <string>
   --link <string>
   --plugin <string>
   --require <string>

packages/cli/src/modules/build/commands/buildWorkspace.ts

@@ -20,6 +20,11 @@ import { createDistWorkspace } from '../lib/packager';
 import type { CommandContext } from '../../../wiring/types';
 
 export default async ({ args, info }: CommandContext) => {
+  // Support legacy --alwaysYarnPack alias
+  const normalizedArgs = args.map(a =>
+    a === '--alwaysYarnPack' ? '--always-pack' : a,
+  );
+
   const {
     flags: { alwaysPack },
     _: positionals,
@@ -36,7 +41,7 @@ export default async ({ args, info }: CommandContext) => {
       },
     },
     undefined,
-    args,
+    normalizedArgs,
   );
 
   const [dir, ...packages] = positionals;

packages/cli/src/modules/build/commands/package/start/command.ts

@@ -22,17 +22,11 @@ import { targetPaths } from '@backstage/cli-common';
 import type { CommandContext } from '../../../../../wiring/types';
 
 export default async ({ args, info }: CommandContext) => {
+  const { inspectEnabled, inspectBrkEnabled, filteredArgs } =
+    extractInspectFlags(args);
+
   const {
-    flags: {
-      config,
-      role,
-      check,
-      inspect,
-      inspectBrk,
-      require: requirePaths,
-      link,
-      entrypoint,
-    },
+    flags: { config, role, check, require: requirePath, link, entrypoint },
   } = cli(
     {
       help: info,
@@ -50,17 +44,8 @@ export default async ({ args, info }: CommandContext) => {
           type: Boolean,
           description: 'Enable type checking and linting if available',
         },
-        inspect: {
-          type: String,
-          description: 'Enable debugger in Node.js environments',
-        },
-        inspectBrk: {
-          type: String,
-          description:
-            'Enable debugger in Node.js environments, breaking before code starts',
-        },
         require: {
-          type: [String],
+          type: String,
           description: 'Add a --require argument to the node process',
         },
         link: {
@@ -75,7 +60,7 @@ export default async ({ args, info }: CommandContext) => {
       },
     },
     undefined,
-    args,
+    filteredArgs,
   );
 
   await startPackage({
@@ -85,8 +70,38 @@ export default async ({ args, info }: CommandContext) => {
     configPaths: config,
     checksEnabled: Boolean(check),
     linkedWorkspace: await resolveLinkedWorkspace(link),
-    inspectEnabled: inspect,
-    inspectBrkEnabled: inspectBrk,
-    require: requirePaths?.[0],
+    inspectEnabled,
+    inspectBrkEnabled,
+    require: requirePath,
   });
 };
+
+// --inspect and --inspect-brk accept an optional host value, which cleye
+// can't express (it only supports required or no value). We extract them
+// from the raw args before passing the rest to cleye.
+function extractInspectFlags(args: string[]) {
+  let inspectEnabled: boolean | string | undefined;
+  let inspectBrkEnabled: boolean | string | undefined;
+  const filteredArgs: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--inspect' || arg === '--inspect-brk') {
+      const next = args[i + 1];
+      const value = next && !next.startsWith('-') ? args[++i] : true;
+      if (arg === '--inspect') {
+        inspectEnabled = value;
+      } else {
+        inspectBrkEnabled = value;
+      }
+    } else if (arg.startsWith('--inspect=')) {
+      inspectEnabled = arg.slice('--inspect='.length);
+    } else if (arg.startsWith('--inspect-brk=')) {
+      inspectBrkEnabled = arg.slice('--inspect-brk='.length);
+    } else {
+      filteredArgs.push(arg);
+    }
+  }
+
+  return { inspectEnabled, inspectBrkEnabled, filteredArgs };
+}

packages/cli/src/modules/build/commands/repo/start.ts

@@ -36,8 +36,11 @@ const ACCEPTED_PACKAGE_ROLES: Array<PackageRole | undefined> = [
 ];
 
 export default async ({ args, info }: CommandContext) => {
+  const { inspectEnabled, inspectBrkEnabled, filteredArgs } =
+    extractInspectFlags(args);
+
   const {
-    flags: { plugin, config, inspect, inspectBrk, require: requirePath, link },
+    flags: { plugin, config, require: requirePath, link },
     _: namesOrPaths,
   } = cli(
     {
@@ -54,16 +57,6 @@ export default async ({ args, info }: CommandContext) => {
           description: 'Config files to load instead of app-config.yaml',
           default: [],
         },
-        inspect: {
-          type: String,
-          description:
-            'Enable debugger in Node.js environments. Applies to backend package only',
-        },
-        inspectBrk: {
-          type: String,
-          description:
-            'Enable debugger in Node.js environments, breaking before code starts. Applies to backend package only',
-        },
         require: {
           type: String,
           description:
@@ -76,7 +69,7 @@ export default async ({ args, info }: CommandContext) => {
       },
     },
     undefined,
-    args,
+    filteredArgs,
   );
 
   const targetPackages = await findTargetPackages(namesOrPaths, plugin);
@@ -84,8 +77,8 @@ export default async ({ args, info }: CommandContext) => {
   const packageOptions = await resolvePackageOptions(targetPackages, {
     plugin,
     config,
-    inspect,
-    inspectBrk,
+    inspect: inspectEnabled,
+    inspectBrk: inspectBrkEnabled,
     require: requirePath,
     link,
   });
@@ -211,8 +204,8 @@ export async function findTargetPackages(
 type CommandOptions = {
   plugin: string[];
   config: string[];
-  inspect?: string;
-  inspectBrk?: string;
+  inspect?: boolean | string;
+  inspectBrk?: boolean | string;
   require?: string;
   link?: string;
 };
@@ -270,3 +263,33 @@ async function resolvePackageOptions(
     ];
   });
 }
+
+// --inspect and --inspect-brk accept an optional host value, which cleye
+// can't express (it only supports required or no value). We extract them
+// from the raw args before passing the rest to cleye.
+function extractInspectFlags(args: string[]) {
+  let inspectEnabled: boolean | string | undefined;
+  let inspectBrkEnabled: boolean | string | undefined;
+  const filteredArgs: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--inspect' || arg === '--inspect-brk') {
+      const next = args[i + 1];
+      const value = next && !next.startsWith('-') ? args[++i] : true;
+      if (arg === '--inspect') {
+        inspectEnabled = value;
+      } else {
+        inspectBrkEnabled = value;
+      }
+    } else if (arg.startsWith('--inspect=')) {
+      inspectEnabled = arg.slice('--inspect='.length);
+    } else if (arg.startsWith('--inspect-brk=')) {
+      inspectBrkEnabled = arg.slice('--inspect-brk='.length);
+    } else {
+      filteredArgs.push(arg);
+    }
+  }
+
+  return { inspectEnabled, inspectBrkEnabled, filteredArgs };
+}