fix: clarify --default-branch semantics across scan and repository

src/commands/install/socket-completion.bash

@@ -119,10 +119,10 @@ FLAGS=(
     [report create]=""
     [report view]=""
     [repos]=""
-    [repos create]="--default-branch --homepage --interactive --org --repo-description --repo-name --visibility"
+    [repos create]="--default-branch --default-branch-name --homepage --interactive --org --repo-description --repo-name --visibility"
     [repos del]="--interactive --org"
     [repos list]="--all --direction --interactive --json --markdown --org --page --per-page --sort"
-    [repos update]="--default-branch --homepage --interactive --org --repo-description --repo-name --visibility"
+    [repos update]="--default-branch --default-branch-name --homepage --interactive --org --repo-description --repo-name --visibility"
     [repos view]="--interactive --org --repo-name"
     [scan]=""
     [scan create]="--auto-manifest --branch --commit-hash --commit-message --committers --cwd --default-branch --interactive --json --markdown --org --pull-request --reach --reach-analysis-memory-limit --reach-analysis-timeout --reach-disable-analytics --reach-ecosystems --reach-exclude-paths --read-only --repo --report --set-as-alerts-page --tmp"

src/commands/repository/cmd-repository-create.mts

@@ -43,10 +43,11 @@ async function run(
     flags: {
       ...commonFlags,
       ...outputFlags,
-      defaultBranch: {
+      defaultBranchName: {
         type: 'string',
         default: 'main',
-        description: 'Repository default branch. Defaults to "main"',
+        description: 'Repository default branch name. Defaults to "main"',
+        aliases: ['defaultBranch'],
       },
       homepage: {
         type: 'string',
@@ -89,7 +90,7 @@ async function run(
 
     Examples
       $ ${command} test-repo
-      $ ${command} our-repo --homepage=socket.dev --default-branch=trunk
+      $ ${command} our-repo --homepage=socket.dev --default-branch-name=trunk
   `,
   }
 
@@ -100,6 +101,18 @@ async function run(
     importMeta,
   })
 
+  // Warn when the deprecated --default-branch alias is used. The flag was
+  // renamed to --default-branch-name to disambiguate from the boolean-toggle
+  // flag of the same name in `socket scan create`.
+  for (const arg of argv) {
+    if (typeof arg === 'string' && /^--default-branch(=|$)/.test(arg)) {
+      logger.warn(
+        '--default-branch is deprecated; use --default-branch-name instead.',
+      )
+      break
+    }
+  }
+
   const { json, markdown, org: orgFlag } = cli.flags
 
   const dryRun = !!cli.flags['dryRun']
@@ -161,7 +174,7 @@ async function run(
       repoName: String(repoName),
       description: String(cli.flags['repoDescription'] || ''),
       homepage: String(cli.flags['homepage'] || ''),
-      defaultBranch: String(cli.flags['defaultBranch'] || ''),
+      defaultBranch: String(cli.flags['defaultBranchName'] || ''),
       visibility: String(cli.flags['visibility'] || 'private'),
     },
     outputKind,

src/commands/repository/cmd-repository-create.test.mts

@@ -30,7 +30,7 @@ describe('socket repository create', async () => {
           The REPO name should be a "slug". Follows the same naming convention as GitHub.
 
           Options
-            --default-branch    Repository default branch. Defaults to "main"
+            --default-branch-name  Repository default branch name. Defaults to "main"
             --homepage          Repository url
             --interactive       Allow for interactive elements, asking for input. Use --no-interactive to prevent any input questions, defaulting them to cancel/no.
             --json              Output as JSON
@@ -41,7 +41,7 @@ describe('socket repository create', async () => {
 
           Examples
             $ socket repository create test-repo
-            $ socket repository create our-repo --homepage=socket.dev --default-branch=trunk"
+            $ socket repository create our-repo --homepage=socket.dev --default-branch-name=trunk"
       `,
       )
       expect(`\n   ${stderr}`).toMatchInlineSnapshot(`
@@ -232,4 +232,42 @@ describe('socket repository create', async () => {
       expect(code, 'dry-run should exit with code 0 on success').toBe(0)
     },
   )
+
+  cmdit(
+    [
+      'repository',
+      'create',
+      'fakerepo',
+      '--default-branch=trunk',
+      FLAG_DRY_RUN,
+      FLAG_CONFIG,
+      '{"apiToken":"fakeToken", "defaultOrg": "fakeOrg"}',
+    ],
+    'should warn when deprecated --default-branch flag is used',
+    async cmd => {
+      const { code, stderr } = await spawnSocketCli(binCliPath, cmd)
+      expect(stderr).toContain(
+        '--default-branch is deprecated; use --default-branch-name instead.',
+      )
+      expect(code, 'dry-run should still exit with code 0').toBe(0)
+    },
+  )
+
+  cmdit(
+    [
+      'repository',
+      'create',
+      'fakerepo',
+      '--default-branch-name=trunk',
+      FLAG_DRY_RUN,
+      FLAG_CONFIG,
+      '{"apiToken":"fakeToken", "defaultOrg": "fakeOrg"}',
+    ],
+    'should accept --default-branch-name without warning',
+    async cmd => {
+      const { code, stderr } = await spawnSocketCli(binCliPath, cmd)
+      expect(stderr).not.toContain('deprecated')
+      expect(code, 'dry-run should exit with code 0').toBe(0)
+    },
+  )
 })

src/commands/repository/cmd-repository-update.mts

@@ -43,11 +43,12 @@ async function run(
     flags: {
       ...commonFlags,
       ...outputFlags,
-      defaultBranch: {
+      defaultBranchName: {
         type: 'string',
         shortFlag: 'b',
         default: 'main',
-        description: 'Repository default branch',
+        description: 'Repository default branch name',
+        aliases: ['defaultBranch'],
       },
       homepage: {
         type: 'string',
@@ -102,6 +103,18 @@ async function run(
     importMeta,
   })
 
+  // Warn when the deprecated --default-branch alias is used. The flag was
+  // renamed to --default-branch-name to disambiguate from the boolean-toggle
+  // flag of the same name in `socket scan create`.
+  for (const arg of argv) {
+    if (typeof arg === 'string' && /^--default-branch(=|$)/.test(arg)) {
+      logger.warn(
+        '--default-branch is deprecated; use --default-branch-name instead.',
+      )
+      break
+    }
+  }
+
   const { json, markdown, org: orgFlag } = cli.flags
 
   const dryRun = !!cli.flags['dryRun']
@@ -163,7 +176,7 @@ async function run(
       repoName: String(repoName),
       description: String(cli.flags['repoDescription'] || ''),
       homepage: String(cli.flags['homepage'] || ''),
-      defaultBranch: String(cli.flags['defaultBranch'] || ''),
+      defaultBranch: String(cli.flags['defaultBranchName'] || ''),
       visibility: String(cli.flags['visibility'] || 'private'),
     },
     outputKind,

src/commands/repository/cmd-repository-update.test.mts

@@ -28,7 +28,7 @@ describe('socket repository update', async () => {
             - Permissions: repo:update
 
           Options
-            --default-branch    Repository default branch
+            --default-branch-name  Repository default branch name
             --homepage          Repository url
             --interactive       Allow for interactive elements, asking for input. Use --no-interactive to prevent any input questions, defaulting them to cancel/no.
             --json              Output as JSON
@@ -202,4 +202,42 @@ describe('socket repository update', async () => {
       expect(code, 'dry-run should exit with code 0 on success').toBe(0)
     },
   )
+
+  cmdit(
+    [
+      'repository',
+      'update',
+      'fakerepo',
+      '--default-branch=trunk',
+      FLAG_DRY_RUN,
+      FLAG_CONFIG,
+      '{"apiToken":"fakeToken", "defaultOrg": "fakeOrg"}',
+    ],
+    'should warn when deprecated --default-branch flag is used',
+    async cmd => {
+      const { code, stderr } = await spawnSocketCli(binCliPath, cmd)
+      expect(stderr).toContain(
+        '--default-branch is deprecated; use --default-branch-name instead.',
+      )
+      expect(code, 'dry-run should still exit with code 0').toBe(0)
+    },
+  )
+
+  cmdit(
+    [
+      'repository',
+      'update',
+      'fakerepo',
+      '--default-branch-name=trunk',
+      FLAG_DRY_RUN,
+      FLAG_CONFIG,
+      '{"apiToken":"fakeToken", "defaultOrg": "fakeOrg"}',
+    ],
+    'should accept --default-branch-name without warning',
+    async cmd => {
+      const { code, stderr } = await spawnSocketCli(binCliPath, cmd)
+      expect(stderr).not.toContain('deprecated')
+      expect(code, 'dry-run should exit with code 0').toBe(0)
+    },
+  )
 })

src/commands/scan/cmd-scan-create.mts

@@ -15,6 +15,7 @@ import { checkCommandInput } from '../../utils/check-input.mts'
 import { cmdFlagValueToArray } from '../../utils/cmd.mts'
 import { determineOrgSlug } from '../../utils/determine-org-slug.mts'
 import { getEcosystemChoicesForMeow } from '../../utils/ecosystem.mts'
+import { InputError } from '../../utils/errors.mts'
 import { getOutputKind } from '../../utils/get-output-kind.mts'
 import {
   detectDefaultBranch,
@@ -165,6 +166,17 @@ async function run(
   importMeta: ImportMeta,
   { parentName }: CliCommandContext,
 ): Promise<void> {
+  // The --default-branch flag is a boolean toggle; meow silently discards any
+  // `=value` form (e.g. --default-branch=main) and falls back to the default.
+  // Reject that form with a clear message so scans aren't silently miscategorized.
+  for (const arg of argv) {
+    if (typeof arg === 'string' && /^--default-branch=/.test(arg)) {
+      throw new InputError(
+        '--default-branch is a boolean flag and does not accept a value. Use --default-branch on its own (with --branch=<name> to name the branch), or --no-default-branch to unset it.',
+      )
+    }
+  }
+
   const config: CliCommandConfig = {
     commandName: CMD_NAME,
     description,

src/commands/scan/cmd-scan-create.test.mts

@@ -813,4 +813,34 @@ describe('socket scan create', async () => {
       expect(code, 'should exit with code 0').toBe(0)
     },
   )
+
+  cmdit(
+    [
+      'scan',
+      'create',
+      FLAG_ORG,
+      'fakeOrg',
+      'target',
+      FLAG_DRY_RUN,
+      '--repo',
+      'xyz',
+      '--branch',
+      'main',
+      '--default-branch=main',
+      FLAG_CONFIG,
+      '{"apiToken":"fakeToken"}',
+    ],
+    'should fail when --default-branch is given a value',
+    async cmd => {
+      const { code, stderr, stdout } = await spawnSocketCli(binCliPath, cmd)
+      const output = stdout + stderr
+      expect(output).toContain(
+        '--default-branch is a boolean flag and does not accept a value',
+      )
+      expect(
+        code,
+        'should exit with non-zero code when --default-branch=value is used',
+      ).not.toBe(0)
+    },
+  )
 })