fix!: upgrade to commander@12 and fix some conflicting short option names #7008

serhalp · 2025-01-21T18:41:01Z

Summary

This upgrades commander from v10 to v12. (The latest is v13, but we'll cross that bridge later.)

This revealed some errors in some command options, which this PR also fixes.

Details

The two main updates in this PR are due to tj/commander.js#2055, which no longer allows redefining the same option twice on the same command:

We were doing this intentionally by defining a few options in the BaseCommand with the option hidden from help and then redefining it in some specific commands. I decided to bite the bullet here and just refactored these three problematic options:
- I moved --json and --offline entirely out of BaseCommand. This uncovered that we weren't exhaustively redeclaring this on all the commands that use it. I fixed those.
- I moved --auth entirely into BaseCommand. It's intended as an alternative authentication mechanism to ntl login and NETLIFY_AUTH_TOKEN, so I believe this is reasonable.
We were doing this unintentionally in a few places, where we were using the same short flag for two options on the same command, resulting in the last registered one being quietly not registered. I chose new flags for these. You could argue this is a breaking change, but these options seemingly never worked. This will be in a major anyway so it's fine.

This did result in some docs/help changes, but IMO they're good changes. It did result in a handful of commands now having a documented --auth option that doesn't make much sense, but I'm not sure it's worth the effort to find some way to hide those.

Breaking changes

[netlify blobs:get]: the --output short variant has changed from -o to -O
- this shouldn't be strictly breaking as -o did not actually work
[netlify deploy]: the --open short variant has changed from -o to -O
- this shouldn't be strictly breaking as -o did not actually work

src/commands/base-command.ts

serhalp · 2025-01-21T18:54:06Z

src/lib/functions/runtimes/js/builders/netlify-lambda.ts

@@ -27,6 +27,7 @@ export const detectNetlifyLambda = async function ({ packageJson } = {}) {
      .option('-b, --babelrc [file]')
      .option('-t, --timeout [delay]')

+    program.allowExcessArguments()


The default behaviour changed in the commander upgrade. This opts back into the previous behaviour. We might consider changing at some point, but it didn't seem right to include this in this PR (and require us to cut a major).

(To be clear here, I ended up only upgrading to commander@12 after all. This behavioural change is in commander@13, but I left this here so we're ready for it, since it doesn't hurt.)

serhalp · 2025-01-21T19:03:55Z

src/commands/blobs/blobs.ts

-    .option('-o, --output <path>', 'Defines the filesystem path where the blob data should be persisted')
+    .option('-O, --output <path>', 'Defines the filesystem path where the blob data should be persisted')


-o is already used for --offline, so this was being quietly ignored (I tested it locally).

Sort of a bummer--I think -o for output is a somewhat universal convention. Maybe something for us to change in future release? I think I'd opt for making --offline a long option only.

src/commands/blobs/blobs.ts

serhalp · 2025-01-22T13:59:18Z

src/commands/deploy/index.ts

-    .option('-o, --open', 'Open site after deploy', false)
+    .option('-O, --open', 'Open site after deploy', false)


Same here, there's already -o for --offline, so deploy -o wasn't working as intended. It just started an offline deploy which of course didn't work.

github-actions · 2025-01-23T20:27:23Z

📊 Benchmark results

Comparing with 5435e79

Dependency count: 1,217 ⬆️ 0.16% increase vs. 5435e79
Package size: 318 MB ⬆️ 0.14% increase vs. 5435e79
Number of ts-expect-error directives: 729 (no change)

serhalp · 2025-02-21T16:51:58Z

src/lib/functions/runtimes/js/builders/netlify-lambda.ts

  // @ts-expect-error TS(2571) FIXME: Object is of type 'unknown'.
  const matchingScripts = Object.entries(scripts).filter(([, script]) => script.match(/netlify-lambda\s+build/))

  for (const [key, script] of matchingScripts) {
    // E.g. ["netlify-lambda", "build", "functions/folder"]
    // these are all valid options for netlify-lambda
-    program


because this is in a loop it was redeclaring these options over and over, which is no longer allowed

serhalp · 2025-02-21T16:52:40Z

src/lib/functions/runtimes/js/builders/netlify-lambda.ts

@@ -14,19 +14,21 @@ export const detectNetlifyLambda = async function ({ packageJson } = {}) {
    return false
  }

+  const program = new Command()


using this constructor is also cleaner since it avoids mutating the exported singleton

`-o` is already used in the base command for `--offline`, so this was being quietly ignored This can't be considered a breaking change as it has never worked. (I just tried it to be sure.) See tj/commander.js#2055.

See tj/commander.js#2055.

It's already used in the BaseCommand for `--offline`. This is not a breaking change, because this never worked as is. Same issue as in 9280c55.

It's already defined in the BaseCommand for `--offline`.

`-r` was already used globally so this was being ignored

It was redefining the options over and over and over. The latest commander throws.

and centralize `--auth` only in `BaseCommand` commander@12 doesn't allow redefining the same option, so this pattern was no longer viable This was a pure refactor, but it uncovered some commands that weren't declaring options they were using, so I fixed those too.

serhalp · 2025-02-21T19:20:17Z

docs/commands/login.md

@@ -21,6 +21,7 @@ netlify login

 - `new` (*boolean*) - Login to new Netlify account
 - `debug` (*boolean*) - Print debugging information
+- `auth` (*string*) - Netlify auth token - can be used to run this command without logging in


🤔 I guess this one's pretty weird, huh?

serhalp · 2025-02-21T19:21:10Z

docs/commands/switch.md

@@ -19,6 +19,7 @@ netlify switch
 **Flags**

 - `debug` (*boolean*) - Print debugging information
+- `auth` (*string*) - Netlify auth token - can be used to run this command without logging in


🤔 does ntl switch make sense with a token?

serhalp · 2025-02-21T19:21:33Z

docs/commands/unlink.md

@@ -20,6 +20,7 @@ netlify unlink

 - `filter` (*string*) - For monorepos, specify the name of the application to run the command in
 - `debug` (*boolean*) - Print debugging information
+- `auth` (*string*) - Netlify auth token - can be used to run this command without logging in


arguably slightly weird

serhalp · 2025-02-21T19:22:13Z

site/scripts/util/generate-command-data.js

@@ -3,13 +3,13 @@ import { sortOptions } from '../../../dist/utils/command-helpers.js'

 const program = createMainCommand()

-/** @type {Array<import('../../src/commands/base-command.js').default>} */
+/** @type {Array<import('../../../src/commands/base-command.js').default>} */


this is totally unrelated, but I happened to notice this was wrong 😬

src/commands/env/env.ts

serhalp · 2025-02-21T19:25:58Z

docs/commands/completion.md

@@ -20,6 +20,7 @@ netlify completion
 **Flags**

 - `debug` (*boolean*) - Print debugging information
+- `auth` (*string*) - Netlify auth token - can be used to run this command without logging in


arguably this one's slightly weird too

ndhoule · 2025-02-21T19:47:58Z

tests/integration/commands/help/__snapshots__/help.test.ts.snap

+  --auth <token>         Netlify auth token - can be used to run this command
+                         without logging in


I'm not sure I fully understand this, but:

If the auth option was previously undocumented, you might consider continuing hiding it. That'd let us kick the can down the road on hiding it from the commands where it doesn't make semantic sense (and I think I agree with all the ones you pointed out).

...Although, when we remove this undocumented flag from those commands, it'll be a breaking change anyway. So... either way is fine, I suppose.

The challenge is that --auth was documented on only a handful of commands, but existed on all of them and actually did something on some subset of them. Now it will be documented on all of them.

The challenge is that AFAICT there's no built-in way with commander to mutate the config (to change hideHelp) of an already registered option on a command, so we'd have to refactor to come up with some solution here to allow for it, or to follow the same pattern I did for --json and --offline, which requires adding --auth explicitly to ~50 commands (i.e. all but 2-3) and then possibly deciding to .hideHelp()on the ones where it currently isn't documented (if want want to not change what is currently documented).

My inclination is to merge this as is, since none of the above seems worth the effort.

ndhoule

Looks great! I trust your judgment on things like whether or not to hide the --auth flag, but I would err on the side of documenting what already exists. It's the shorter path and we can remove these flags where they make no semantic sense as part of a future breaking change.

serhalp commented Jan 21, 2025

View reviewed changes

src/commands/base-command.ts Outdated Show resolved Hide resolved

serhalp commented Jan 21, 2025

View reviewed changes

src/commands/blobs/blobs.ts Outdated Show resolved Hide resolved

serhalp force-pushed the fix/upgrade-misc-deps branch 3 times, most recently from c3cdea8 to b807744 Compare January 21, 2025 21:30

serhalp commented Jan 22, 2025

View reviewed changes

serhalp mentioned this pull request Jan 22, 2025

chore: replatform docs site to Astro + Starlight #7012

Merged

serhalp force-pushed the fix/upgrade-misc-deps branch from b807744 to 4727ceb Compare January 23, 2025 20:26

serhalp force-pushed the fix/upgrade-misc-deps branch 3 times, most recently from 04372e6 to 0d11dde Compare January 23, 2025 22:10

talentlessguy mentioned this pull request Jan 29, 2025

Cleanup of the Netlify CLI e18e/ecosystem-issues#156

Open

serhalp mentioned this pull request Jan 31, 2025

fix(deps): upgrade 23 outdated dependencies #7019

Merged

serhalp force-pushed the fix/upgrade-misc-deps branch from 0d11dde to 6aa83f2 Compare February 4, 2025 22:45

serhalp changed the title ~~fix(deps): upgrade 23 outdated dependencies~~ fix(deps): upgrade commander Feb 4, 2025

serhalp changed the base branch from main to fix/upgrade-misc-deps-except-commander February 4, 2025 22:46

serhalp force-pushed the fix/upgrade-misc-deps branch from 1fb55f2 to ad03c5f Compare February 4, 2025 23:11

Base automatically changed from fix/upgrade-misc-deps-except-commander to main February 6, 2025 00:03

serhalp force-pushed the fix/upgrade-misc-deps branch 2 times, most recently from 4585705 to ab73b05 Compare February 21, 2025 16:47

serhalp commented Feb 21, 2025

View reviewed changes

serhalp force-pushed the fix/upgrade-misc-deps branch 3 times, most recently from 1ee9305 to 2f59a2a Compare February 21, 2025 18:40

serhalp changed the title ~~fix(deps): upgrade commander~~ fix!(deps): upgrade to commander@12 and fix some conflicting short option names Feb 21, 2025

serhalp changed the title ~~fix!(deps): upgrade to commander@12 and fix some conflicting short option names~~ fix!: upgrade to commander@12 and fix some conflicting short option names Feb 21, 2025

serhalp added 11 commits February 21, 2025 14:11

fix: use a valid short flag for blobs:get output

59dfb06

`-o` is already used in the base command for `--offline`, so this was being quietly ignored This can't be considered a breaking change as it has never worked. (I just tried it to be sure.) See tj/commander.js#2055.

fix: avoid redefining --json option in commands

d8ab3fb

See tj/commander.js#2055.

fix: fix duplicate -o option for deploy command

3addebd

It's already used in the BaseCommand for `--offline`. This is not a breaking change, because this never worked as is. Same issue as in 9280c55.

fix: fix duplicate -a option in deploy command

32c2984

It's already defined in the BaseCommand for `--offline`.

fix: fix still more --json option overrides

cbd2f4e

fix: fix env:import options

250fa2e

`-r` was already used globally so this was being ignored

fix: don't mutate the commander singleton

1f9c4aa

It was redefining the options over and over and over. The latest commander throws.

chore(deps): bump astro in docs site

f5b9a23

fix(deps): upgrade to commander@12

c9287c6

types(site): fix jsdoc types in docs script

01d3324

serhalp force-pushed the fix/upgrade-misc-deps branch from 2f59a2a to e68a091 Compare February 21, 2025 19:13

serhalp commented Feb 21, 2025

View reviewed changes

src/commands/env/env.ts Outdated Show resolved Hide resolved

serhalp commented Feb 21, 2025

View reviewed changes

serhalp marked this pull request as ready for review February 21, 2025 19:27

serhalp requested review from a team as code owners February 21, 2025 19:27

serhalp requested a review from ndhoule February 21, 2025 19:27

ndhoule reviewed Feb 21, 2025

View reviewed changes

ndhoule approved these changes Feb 21, 2025

View reviewed changes

serhalp added 2 commits February 21, 2025 15:17

fix: undo unnecessary short flag change

2decd3f

Merge branch 'main' into fix/upgrade-misc-deps

e25f9de

serhalp enabled auto-merge (squash) February 21, 2025 20:18

serhalp merged commit 42b4a6c into main Feb 21, 2025
49 checks passed

serhalp deleted the fix/upgrade-misc-deps branch February 21, 2025 20:57

token-generator-app bot mentioned this pull request Feb 21, 2025

chore(main): release 19.0.0 #7042

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix!: upgrade to commander@12 and fix some conflicting short option names #7008

fix!: upgrade to commander@12 and fix some conflicting short option names #7008

serhalp commented Jan 21, 2025 •

edited

Loading

serhalp Jan 21, 2025

serhalp Jan 22, 2025

serhalp Jan 21, 2025 •

edited

Loading

ndhoule Feb 21, 2025

serhalp Jan 22, 2025 •

edited

Loading

github-actions bot commented Jan 23, 2025 •

edited

Loading

serhalp Feb 21, 2025

serhalp Feb 21, 2025

serhalp Feb 21, 2025

serhalp Feb 21, 2025

serhalp Feb 21, 2025

serhalp Feb 21, 2025

serhalp Feb 21, 2025

ndhoule Feb 21, 2025

serhalp Feb 21, 2025

ndhoule left a comment

		.option('-o, --output <path>', 'Defines the filesystem path where the blob data should be persisted')
		.option('-O, --output <path>', 'Defines the filesystem path where the blob data should be persisted')

		.option('-o, --open', 'Open site after deploy', false)
		.option('-O, --open', 'Open site after deploy', false)

		--auth <token> Netlify auth token - can be used to run this command
		without logging in

fix!: upgrade to commander@12 and fix some conflicting short option names #7008

fix!: upgrade to commander@12 and fix some conflicting short option names #7008

Conversation

serhalp commented Jan 21, 2025 • edited Loading

Summary

Details

Breaking changes

Choose a reason for hiding this comment

Choose a reason for hiding this comment

serhalp Jan 21, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

serhalp Jan 22, 2025 • edited Loading

Choose a reason for hiding this comment

github-actions bot commented Jan 23, 2025 • edited Loading

📊 Benchmark results

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ndhoule left a comment

Choose a reason for hiding this comment

serhalp commented Jan 21, 2025 •

edited

Loading

serhalp Jan 21, 2025 •

edited

Loading

serhalp Jan 22, 2025 •

edited

Loading

github-actions bot commented Jan 23, 2025 •

edited

Loading