fix(init): pass -- through npm create, document negative flags

Author: danielroe

docs/init.md

@@ -10,7 +10,7 @@ links:
 
 <!--init-cmd-->
 ```bash [Terminal]
-npm create nuxt@latest [DIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [-t, --template=<template-name>] [-f, --force] [--offline] [--preferOffline] [--install] [--gitInit] [--shell] [--packageManager=<npm|pnpm|yarn|bun|deno|aube|nub>] [-M, --modules=<module-names>] [--nightly=<dist-tag>]
+npm create nuxt@latest [DIR] -- [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [-t, --template=<template-name>] [-f, --force] [--offline] [--preferOffline] [--install] [--gitInit] [--shell] [--packageManager=<npm|pnpm|yarn|bun|deno|aube|nub>] [-M, --modules=<module-names>] [--nightly=<dist-tag>]
 ```
 <!--/init-cmd-->
 
@@ -44,6 +44,7 @@ The `create-nuxt` command initializes a fresh Nuxt project using [unjs/giget](ht
 | `--install`                                                | `true`  | Install dependencies once the project has been scaffolded                            |
 | `--no-install`                                             |         | Skip installing dependencies                                                         |
 | `--gitInit`                                                |         | Initialize git repository                                                            |
+| `--no-gitInit`                                             |         | Skip git repository initialization                                                   |
 | `--shell`                                                  |         | Start shell after installation in project directory                                  |
 | `--packageManager=<npm\|pnpm\|yarn\|bun\|deno\|aube\|nub>` |         | Package manager choice                                                               |
 | `-M, --modules=<module-names>`                             |         | Nuxt modules to install (comma separated without spaces)                             |

docs/module.md

@@ -65,16 +65,16 @@ Run it without a module name to pick from the modules compatible with your Nuxt
 
 <!--module-remove-cmd-->
 ```bash [Terminal]
-npx nuxt module remove [MODULENAME] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--skipInstall] [--skipConfig]
+npx nuxt module remove [MODULENAME...] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--skipInstall] [--skipConfig]
 ```
 <!--/module-remove-cmd-->
 
 ### Arguments
 
 <!--module-remove-args-->
-| Argument     | Description                                                        |
-|--------------|--------------------------------------------------------------------|
-| `MODULENAME` | Specify one or more modules to remove by name, separated by spaces |
+| Argument        | Description                                                        |
+|-----------------|--------------------------------------------------------------------|
+| `MODULENAME...` | Specify one or more modules to remove by name, separated by spaces |
 <!--/module-remove-args-->
 
 ### Options

packages/create-nuxt/src/init.ts

@@ -176,6 +176,7 @@ export default defineCommand({
     gitInit: {
       type: 'boolean',
       description: 'Initialize git repository',
+      negativeDescription: 'Skip git repository initialization',
     },
     shell: {
       type: 'boolean',

packages/nuxt-cli/src/commands/module/remove.ts

@@ -40,6 +40,7 @@ export default defineCommand({
       type: 'positional',
       description: 'Specify one or more modules to remove by name, separated by spaces',
       required: false,
+      multiple: true,
     },
     skipInstall: {
       type: 'boolean',
@@ -52,7 +53,7 @@ export default defineCommand({
   },
   async setup(ctx) {
     const cwd = resolve(ctx.args.cwd)
-    const modules = ctx.args._.map(e => e.trim()).filter(Boolean)
+    const modules = ctx.args.moduleName.map(e => e.trim()).filter(Boolean)
     const projectPkg = await readPackageJSON(cwd).catch(() => ({} as PackageJson))
 
     if (!await ensureNuxtDependency(cwd, projectPkg)) {

packages/nuxt-cli/src/utils/headless.ts

@@ -164,6 +164,7 @@ export function getHeadlessCommand(options: HeadlessCommandOptions): string[] {
   return [
     prefix,
     quoteArgument(dir, windows),
+    needsArgumentSeparator(prefix) ? '--' : '',
     `--template=${template}`,
     `--packageManager=${packageManager}`,
     gitInit ? '--gitInit' : '--no-gitInit',
@@ -174,6 +175,17 @@ export function getHeadlessCommand(options: HeadlessCommandOptions): string[] {
   ].filter(Boolean)
 }
 
+/**
+ * Whether the flags that follow have to be fenced off with `--`. `npm create`
+ * consumes anything flag-shaped as npm config (`npm warn Unknown cli config`)
+ * and runs the initializer with the positionals alone, so the separator is the
+ * only way through. Other package managers forward the whole tail verbatim,
+ * including a literal `--`, which citty would then treat as the end of parsing.
+ */
+function needsArgumentSeparator(prefix: string): boolean {
+  return prefix.startsWith('npm create')
+}
+
 export interface WrapOptions {
   /** Columns available for the command itself, excluding any surrounding gutter. */
   width?: number

packages/nuxt-cli/test/unit/commands/module/remove.spec.ts

@@ -80,7 +80,7 @@ describe('module remove', () => {
     await removeCommand.setup({
       args: {
         cwd: '/fake-dir',
-        _: ['content'],
+        moduleName: ['content'],
       },
     })
 
@@ -113,7 +113,7 @@ describe('module remove', () => {
     }])
 
     const removeCommand = await (commands as CommandsType).subCommands.remove()
-    await removeCommand.setup({ args: { cwd: '/fake-dir', skipConfig: true, _: ['example-module'] } })
+    await removeCommand.setup({ args: { cwd: '/fake-dir', skipConfig: true, moduleName: ['example-module'] } })
 
     expect(removeDependency).toHaveBeenCalledWith(['example'], expect.objectContaining({ cwd: '/fake-dir' }))
   })
@@ -123,7 +123,7 @@ describe('module remove', () => {
     await removeCommand.setup({
       args: {
         cwd: '/fake-dir',
-        _: ['@nuxt/content'],
+        moduleName: ['@nuxt/content'],
       },
     })
 
@@ -141,7 +141,7 @@ describe('module remove', () => {
     await removeCommand.setup({
       args: {
         cwd: '/fake-dir',
-        _: [],
+        moduleName: [],
       },
     })
 
@@ -157,7 +157,7 @@ describe('module remove', () => {
     await removeCommand.setup({
       args: {
         cwd: '/fake-dir',
-        _: [],
+        moduleName: [],
       },
     })
 
@@ -171,7 +171,7 @@ describe('module remove', () => {
       args: {
         cwd: '/fake-dir',
         skipInstall: true,
-        _: ['@nuxt/content'],
+        moduleName: ['@nuxt/content'],
       },
     })
 
@@ -185,7 +185,7 @@ describe('module remove', () => {
     await expect(removeCommand.setup({
       args: {
         cwd: '/fake-dir',
-        _: ['@nuxt/content'],
+        moduleName: ['@nuxt/content'],
       },
     })).rejects.toThrow('process.exit unexpectedly called with "1"')
 
@@ -198,7 +198,7 @@ describe('module remove', () => {
       args: {
         cwd: '/fake-dir',
         skipConfig: true,
-        _: ['@nuxt/content'],
+        moduleName: ['@nuxt/content'],
       },
     })
 
@@ -215,7 +215,7 @@ describe('module remove', () => {
     await removeCommand.setup({
       args: {
         cwd: '/fake-dir',
-        _: ['@nuxt/content'],
+        moduleName: ['@nuxt/content'],
       },
     })
 
@@ -239,7 +239,7 @@ describe('module remove', () => {
     await removeCommand.setup({
       args: {
         cwd: '/fake-dir',
-        _: ['@vee-validate/nuxt'],
+        moduleName: ['@vee-validate/nuxt'],
       },
     })
 
@@ -265,7 +265,7 @@ describe('module remove', () => {
     ))
 
     const removeCommand = await (commands as CommandsType).subCommands.remove()
-    await removeCommand.setup({ args: { cwd: '/fake-dir', _: ['@example/nuxt'] } })
+    await removeCommand.setup({ args: { cwd: '/fake-dir', moduleName: ['@example/nuxt'] } })
 
     expect(confirm).not.toHaveBeenCalled()
     expect(removeDependency).toHaveBeenCalledWith(['@example/nuxt'], expect.objectContaining({ cwd: '/fake-dir' }))
@@ -288,7 +288,7 @@ describe('module remove', () => {
     await removeCommand.setup({
       args: {
         cwd: '/fake-dir',
-        _: ['@vee-validate/nuxt'],
+        moduleName: ['@vee-validate/nuxt'],
       },
     })
 
@@ -323,7 +323,7 @@ describe('module remove', () => {
     })
 
     const removeCommand = await (commands as CommandsType).subCommands.remove()
-    await removeCommand.setup({ args: { cwd: '/fake-dir', _: ['@vee-validate/nuxt'] } })
+    await removeCommand.setup({ args: { cwd: '/fake-dir', moduleName: ['@vee-validate/nuxt'] } })
 
     expect(peak).toBeGreaterThan(1)
   })
@@ -351,7 +351,7 @@ describe('module remove', () => {
     await removeCommand.setup({
       args: {
         cwd: '/fake-dir',
-        _: ['@vee-validate/nuxt'],
+        moduleName: ['@vee-validate/nuxt'],
       },
     })
 

packages/nuxt-cli/test/unit/help.spec.ts

@@ -492,11 +492,11 @@ describe('help', () => {
     expect(await usage(await subCommand(commands.module, 'remove'), commands.module)).toMatchInlineSnapshot(`
       "Remove Nuxt modules (module remove)
 
-      USAGE module remove [OPTIONS] [MODULENAME]
+      USAGE module remove [OPTIONS] [MODULENAME...]
 
       ARGUMENTS
 
-        MODULENAME    Specify one or more modules to remove by name, separated by spaces
+        MODULENAME...    Specify one or more modules to remove by name, separated by spaces
 
       OPTIONS
 

packages/nuxt-cli/test/unit/utils/headless.spec.ts

@@ -31,6 +31,14 @@ describe('getHeadlessCommand', () => {
     expect(getHeadlessCommand({ ...base, dir: 'my app', modules: ['@nuxt/ui', '@nuxt/image'], force: true }).join(' ')).toBe('nuxt init \'my app\' --template=minimal --packageManager=pnpm --gitInit --modules=@nuxt/ui,@nuxt/image --force')
   })
 
+  it('should separate the options from an `npm create` prefix', () => {
+    expect(getHeadlessCommand({ ...base, prefix: 'npm create nuxt@latest' }).join(' ')).toBe('npm create nuxt@latest my-app -- --template=minimal --packageManager=pnpm --gitInit --no-modules')
+  })
+
+  it('should pass the options straight to other package managers', () => {
+    expect(getHeadlessCommand({ ...base, prefix: 'pnpm create nuxt@latest' }).join(' ')).toBe('pnpm create nuxt@latest my-app --template=minimal --packageManager=pnpm --gitInit --no-modules')
+  })
+
   it('should carry the nightly channel through', () => {
     expect(getHeadlessCommand({ ...base, nightly: 'latest' }).join(' ')).toContain('--nightly=latest')
   })

scripts/generate-command-docs.ts

@@ -48,6 +48,11 @@ interface DocEntry {
   cli?: 'nuxt' | 'create-nuxt'
   /** Overrides the `npx nuxt <command>` prefix of the usage line. */
   usage?: string
+  /**
+   * Fence the options off from the prefix with `--`, for a command run through
+   * `npm create`, which otherwise reads them as npm's own config.
+   */
+  separator?: boolean
 }
 
 /**
@@ -70,7 +75,7 @@ const DOCS: DocEntry[] = [
   { id: 'docs', file: 'docs.md', command: ['docs'] },
   { id: 'generate', file: 'generate.md', command: ['generate'] },
   { id: 'info', file: 'info.md', command: ['info'] },
-  { id: 'init', file: 'init.md', command: [], cli: 'create-nuxt', usage: 'npm create nuxt@latest' },
+  { id: 'init', file: 'init.md', command: [], cli: 'create-nuxt', usage: 'npm create nuxt@latest', separator: true },
   { id: 'module-add', file: 'module.md', command: ['module', 'add'] },
   { id: 'module-remove', file: 'module.md', command: ['module', 'remove'] },
   { id: 'module-search', file: 'module.md', command: ['module', 'search'] },
@@ -187,6 +192,7 @@ function render(entry: DocEntry, args: ArgsDef, inherited: ArgsDef): Blocks {
       const signature = positionalSignature(name, arg)
       return arg.required === false || arg.default !== undefined ? `[${signature}]` : `<${signature}>`
     }),
+    ...entry.separator && options.length ? ['--'] : [],
     ...options.map(([name, arg]) => `[${flagSignature(name, arg)}]`),
   ].join(' ')