refactor(cli): unify the 4 subcommand routers via defineSubcommandGroup

jdalton · jdalton · commit 5974e2fd3309 · 2026-05-08T19:53:46.000-04:00
Pre-refactor the four router files (cmd-scan, cmd-package, cmd-manifest,
cmd-organization) used three subtly different shapes — one with a
top-level config object whose flags were never consumed, one that
inlined meowWithSubcommands without a config, one that declared
hidden: false explicitly while another omitted it.

Add `defineSubcommandGroup` that takes a single declarative spec and
emits the same CliSubcommand shape every router used to build by hand.
Optional knobs preserve pre-refactor surface drift exactly:

- `hidden`: only included on the result when explicitly passed (so
  cmd-scan, which previously had no `hidden` field, stays that way).
- `passCommonFlags`: opt in to passing the shared commonFlags map to
  meowWithSubcommands (cmd-manifest used this implicitly).
- `aliases`: forwarded as-is.

Migrations:
- cmd-scan, cmd-package, cmd-manifest, cmd-organization now declare
  their spec via defineSubcommandGroup. Public surface is byte-identical
  per the existing router unit tests (51 pass with no test changes).
diff --git a/packages/cli/src/commands/manifest/cmd-manifest.mts b/packages/cli/src/commands/manifest/cmd-manifest.mts
@@ -5,59 +5,29 @@ import { cmdManifestGradle } from './cmd-manifest-gradle.mts'
 import { cmdManifestKotlin } from './cmd-manifest-kotlin.mts'
 import { cmdManifestScala } from './cmd-manifest-scala.mts'
 import { cmdManifestSetup } from './cmd-manifest-setup.mts'
-import { defineFlags } from '../../meow.mts'
-import { commonFlags } from '../../flags.mts'
-import { meowWithSubcommands } from '../../utils/cli/with-subcommands.mjs'
+import { defineSubcommandGroup } from '../../utils/cli/define-subcommand-group.mts'
 
-import type { CliCommandContext } from '../../utils/cli/with-subcommands.mjs'
+const description = 'Generate a dependency manifest for certain ecosystems'
 
-// meowWithSubcommands renders its own help text from the subcommand list,
-// so this command-level config doesn't need a help builder.
-const config = {
-  commandName: 'manifest',
-  description: 'Generate a dependency manifest for certain ecosystems',
+export const cmdManifest = defineSubcommandGroup({
+  name: 'manifest',
+  description,
   hidden: false,
-  flags: defineFlags({
-    ...commonFlags,
-  }),
-}
-
-export const cmdManifest = {
-  description: config.description,
-  hidden: config.hidden,
-  run,
-}
-
-async function run(
-  argv: string[] | readonly string[],
-  importMeta: ImportMeta,
-  { parentName }: CliCommandContext,
-): Promise<void> {
-  await meowWithSubcommands(
-    {
-      argv,
-      name: `${parentName} ${config.commandName}`,
-      importMeta,
-      subcommands: {
-        auto: cmdManifestAuto,
-        cdxgen: cmdManifestCdxgen,
-        conda: cmdManifestConda,
-        gradle: cmdManifestGradle,
-        kotlin: cmdManifestKotlin,
-        scala: cmdManifestScala,
-        setup: cmdManifestSetup,
-      },
-    },
-    {
-      aliases: {
-        yolo: {
-          description: config.description,
-          hidden: true,
-          argv: ['auto'],
-        },
-      },
-      description: config.description,
-      flags: config.flags,
+  passCommonFlags: true,
+  subcommands: {
+    auto: cmdManifestAuto,
+    cdxgen: cmdManifestCdxgen,
+    conda: cmdManifestConda,
+    gradle: cmdManifestGradle,
+    kotlin: cmdManifestKotlin,
+    scala: cmdManifestScala,
+    setup: cmdManifestSetup,
+  },
+  aliases: {
+    yolo: {
+      description,
+      hidden: true,
+      argv: ['auto'],
     },
-  )
-}
+  },
+})
diff --git a/packages/cli/src/commands/organization/cmd-organization.mts b/packages/cli/src/commands/organization/cmd-organization.mts
@@ -4,48 +4,33 @@ import { cmdOrganizationPolicyLicense } from './cmd-organization-policy-license.
 import { cmdOrganizationPolicySecurity } from './cmd-organization-policy-security.mts'
 import { cmdOrganizationPolicy } from './cmd-organization-policy.mts'
 import { cmdOrganizationQuota } from './cmd-organization-quota.mts'
-import { meowWithSubcommands } from '../../utils/cli/with-subcommands.mjs'
+import { defineSubcommandGroup } from '../../utils/cli/define-subcommand-group.mts'
 
-import type { CliSubcommand } from '../../utils/cli/with-subcommands.mjs'
-
-const description = 'Manage Socket organization account details'
-
-export const cmdOrganization: CliSubcommand = {
-  description,
+export const cmdOrganization = defineSubcommandGroup({
+  name: 'organization',
+  description: 'Manage Socket organization account details',
   hidden: false,
-  async run(argv, importMeta, { parentName }) {
-    await meowWithSubcommands(
-      {
-        argv,
-        name: `${parentName} organization`,
-        importMeta,
-        subcommands: {
-          dependencies: cmdOrganizationDependencies,
-          list: cmdOrganizationList,
-          quota: cmdOrganizationQuota,
-          policy: cmdOrganizationPolicy,
-        },
-      },
-      {
-        aliases: {
-          deps: {
-            description: cmdOrganizationDependencies.description,
-            hidden: true,
-            argv: ['dependencies'],
-          },
-          license: {
-            description: cmdOrganizationPolicyLicense.description,
-            hidden: true,
-            argv: ['policy', 'license'],
-          },
-          security: {
-            description: cmdOrganizationPolicySecurity.description,
-            hidden: true,
-            argv: ['policy', 'security'],
-          },
-        },
-        description,
-      },
-    )
+  subcommands: {
+    dependencies: cmdOrganizationDependencies,
+    list: cmdOrganizationList,
+    quota: cmdOrganizationQuota,
+    policy: cmdOrganizationPolicy,
+  },
+  aliases: {
+    deps: {
+      description: cmdOrganizationDependencies.description,
+      hidden: true,
+      argv: ['dependencies'],
+    },
+    license: {
+      description: cmdOrganizationPolicyLicense.description,
+      hidden: true,
+      argv: ['policy', 'license'],
+    },
+    security: {
+      description: cmdOrganizationPolicySecurity.description,
+      hidden: true,
+      argv: ['policy', 'security'],
+    },
   },
-}
+})
diff --git a/packages/cli/src/commands/package/cmd-package.mts b/packages/cli/src/commands/package/cmd-package.mts
@@ -1,35 +1,22 @@
 import { cmdPackageScore } from './cmd-package-score.mts'
 import { cmdPackageShallow } from './cmd-package-shallow.mts'
-import { meowWithSubcommands } from '../../utils/cli/with-subcommands.mjs'
-
-import type { CliSubcommand } from '../../utils/cli/with-subcommands.mjs'
+import { defineSubcommandGroup } from '../../utils/cli/define-subcommand-group.mts'
 
 const description = 'Look up published package details'
 
-export const cmdPackage: CliSubcommand = {
+export const cmdPackage = defineSubcommandGroup({
+  name: 'package',
   description,
   hidden: false,
-  async run(argv, importMeta, { parentName }) {
-    await meowWithSubcommands(
-      {
-        argv,
-        name: `${parentName} package`,
-        importMeta,
-        subcommands: {
-          score: cmdPackageScore,
-          shallow: cmdPackageShallow,
-        },
-      },
-      {
-        aliases: {
-          deep: {
-            description,
-            hidden: true,
-            argv: ['score'],
-          },
-        },
-        description,
-      },
-    )
+  subcommands: {
+    score: cmdPackageScore,
+    shallow: cmdPackageShallow,
+  },
+  aliases: {
+    deep: {
+      description,
+      hidden: true,
+      argv: ['score'],
+    },
   },
-}
+})
diff --git a/packages/cli/src/commands/scan/cmd-scan.mts b/packages/cli/src/commands/scan/cmd-scan.mts
@@ -8,48 +8,33 @@ import { cmdScanReach } from './cmd-scan-reach.mts'
 import { cmdScanReport } from './cmd-scan-report.mts'
 import { cmdScanSetup } from './cmd-scan-setup.mts'
 import { cmdScanView } from './cmd-scan-view.mts'
-import { meowWithSubcommands } from '../../utils/cli/with-subcommands.mjs'
+import { defineSubcommandGroup } from '../../utils/cli/define-subcommand-group.mts'
 
-import type { CliSubcommand } from '../../utils/cli/with-subcommands.mjs'
-
-const description = 'Manage Socket scans'
-
-export const cmdScan: CliSubcommand = {
-  description,
-  async run(argv, importMeta, { parentName }) {
-    await meowWithSubcommands(
-      {
-        argv,
-        name: `${parentName} scan`,
-        importMeta,
-        subcommands: {
-          create: cmdScanCreate,
-          del: cmdScanDel,
-          diff: cmdScanDiff,
-          github: cmdScanGithub,
-          list: cmdScanList,
-          metadata: cmdScanMetadata,
-          reach: cmdScanReach,
-          report: cmdScanReport,
-          setup: cmdScanSetup,
-          view: cmdScanView,
-        },
-      },
-      {
-        aliases: {
-          meta: {
-            description: cmdScanMetadata.description,
-            hidden: true,
-            argv: ['metadata'],
-          },
-          reachability: {
-            description: cmdScanReach.description,
-            hidden: true,
-            argv: ['reach'],
-          },
-        },
-        description,
-      },
-    )
+export const cmdScan = defineSubcommandGroup({
+  name: 'scan',
+  description: 'Manage Socket scans',
+  subcommands: {
+    create: cmdScanCreate,
+    del: cmdScanDel,
+    diff: cmdScanDiff,
+    github: cmdScanGithub,
+    list: cmdScanList,
+    metadata: cmdScanMetadata,
+    reach: cmdScanReach,
+    report: cmdScanReport,
+    setup: cmdScanSetup,
+    view: cmdScanView,
+  },
+  aliases: {
+    meta: {
+      description: cmdScanMetadata.description,
+      hidden: true,
+      argv: ['metadata'],
+    },
+    reachability: {
+      description: cmdScanReach.description,
+      hidden: true,
+      argv: ['reach'],
+    },
   },
-}
+})
diff --git a/packages/cli/src/utils/cli/define-subcommand-group.mts b/packages/cli/src/utils/cli/define-subcommand-group.mts
