feat: publish --access=private alias for restricted (#9153)

## Summary

Adds `private` as a valid value for `--access` in `npm publish`, as an
alias for `restricted`.

## Motivation

The `--access` flag on `npm publish` currently accepts `restricted` and
`public`. However, in everyday usage, the npm community colloquially
refers to non-public packages as "private packages" — not "restricted
packages." The npm website, the npm registry, and `npm access` all use
the term "private" to describe these packages.

### `npm publish --access` vs `npm access`

These are two different commands that deal with package visibility in
different ways:

- **`npm publish --access=<public|restricted>`** sets the visibility of
a package **at publish time**. This is only relevant for scoped
packages, where the default for new packages is `public`.
- **`npm access set status=<public|private>`** changes the visibility of
an **already published** package. Notably, `npm access` already uses
`private` (not `restricted`) as its term for non-public packages.

This inconsistency means that a user who runs `npm access set
status=private` might naturally try `npm publish --access=private` and
get an error. Since everyone already calls them "private packages," the
CLI should accept that term too. This PR resolves that by accepting
`private` as a synonym for `restricted` during publish.

## Changes

- Added `private` to the valid values for the `access` config definition
- The `flatten` function maps `private` → `restricted` so the registry
always receives `restricted`
- Updated documentation to note that `private` is an alias for
`restricted`
- Added tests for the `--access=private` flow

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: reggi

tap-snapshots/test/lib/commands/publish.js.test.cjs

@@ -173,6 +173,28 @@ exports[`test/lib/commands/publish.js TAP prioritize CLI flags over publishConfi
 + @npmcli/test-package@1.0.0
 `
 
+exports[`test/lib/commands/publish.js TAP private access > must match snapshot 1`] = `
+Array [
+  "package: @npm/test-package@1.0.0",
+  "Tarball Contents",
+  "55B package.json",
+  "Tarball Details",
+  "name: @npm/test-package",
+  "version: 1.0.0",
+  "filename: npm-test-package-1.0.0.tgz",
+  "package size: {size}",
+  "unpacked size: 55 B",
+  "shasum: {sha}",
+  "integrity: {integrity}
+  "total files: 1",
+  "Publishing to https://registry.npmjs.org/ with tag latest and restricted access",
+]
+`
+
+exports[`test/lib/commands/publish.js TAP private access > new package version 1`] = `
++ @npm/test-package@1.0.0
+`
+
 exports[`test/lib/commands/publish.js TAP public access > must match snapshot 1`] = `
 Array [
   "package: @npm/test-package@1.0.0",

tap-snapshots/test/lib/docs.js.test.cjs

@@ -189,7 +189,7 @@ safer to use a registry-provided authentication bearer token stored in the
 
 * Default: 'public' for new packages, existing packages it will not change the
   current level
-* Type: null, "restricted", or "public"
+* Type: null, "restricted", "public", or "private"
 
 If you do not want your scoped package to be publicly viewable (and
 installable) set \`--access=restricted\`.
@@ -201,6 +201,8 @@ packages. Specifying a value of \`restricted\` or \`public\` during publish will
 change the access for an existing package the same way that \`npm access set
 status\` would.
 
+The value \`private\` is an alias for \`restricted\`.
+
 
 
 #### \`all\`
@@ -5416,7 +5418,7 @@ Usage:
 npm publish <package-spec>
 
 Options:
-[--tag <tag>] [--access <restricted|public>] [--dry-run] [--otp <otp>]
+[--tag <tag>] [--access <restricted|public|private>] [--dry-run] [--otp <otp>]
 [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
 [--workspaces] [--include-workspace-root] [--provenance|--provenance-file <file>]
 

test/lib/commands/publish.js

@@ -742,6 +742,27 @@ t.test('restricted access', async t => {
   t.matchSnapshot(logs.notice)
 })
 
+t.test('private access', async t => {
+  const packageJson = {
+    name: '@npm/test-package',
+    version: '1.0.0',
+  }
+  const { npm, joinedOutput, logs, registry } = await loadNpmWithRegistry(t, {
+    config: {
+      ...auth,
+      access: 'private',
+    },
+    prefixDir: {
+      'package.json': JSON.stringify(packageJson, null, 2),
+    },
+    authorization: token,
+  })
+  registry.publish('@npm/test-package', { packageJson, access: 'restricted' })
+  await npm.exec('publish', [])
+  t.matchSnapshot(joinedOutput(), 'new package version')
+  t.matchSnapshot(logs.notice)
+})
+
 t.test('public access', async t => {
   const { npm, joinedOutput, logs, registry } = await loadNpmWithRegistry(t, {
     config: {

workspaces/config/lib/definitions/definitions.js

@@ -154,7 +154,7 @@ const definitions = {
     defaultDescription: `
     'public' for new packages, existing packages it will not change the current level
   `,
-    type: [null, 'restricted', 'public'],
+    type: [null, 'restricted', 'public', 'private'],
     description: `
     If you do not want your scoped package to be publicly viewable (and
     installable) set \`--access=restricted\`.
@@ -165,8 +165,13 @@ const definitions = {
     packages.  Specifying a value of \`restricted\` or \`public\` during
     publish will change the access for an existing package the same way that
     \`npm access set status\` would.
+
+    The value \`private\` is an alias for \`restricted\`.
   `,
-    flatten,
+    flatten (key, obj, flatOptions) {
+      const value = obj[key]
+      flatOptions.access = value === 'private' ? 'restricted' : value
+    },
   }),
   all: new Definition('all', {
     default: false,

workspaces/config/tap-snapshots/test/type-description.js.test.cjs

@@ -15,6 +15,7 @@ Object {
     null,
     "restricted",
     "public",
+    "private",
   ],
   "all": Array [
     "boolean value (true or false)",

workspaces/config/test/definitions/definitions.js

@@ -33,6 +33,23 @@ t.test('basic flattening function camelCases from css-case', t => {
   t.end()
 })
 
+t.test('access flattening maps private to restricted', t => {
+  const definitions = mockDefs()
+  const flatPrivate = {}
+  definitions.access.flatten('access', { access: 'private' }, flatPrivate)
+  t.equal(flatPrivate.access, 'restricted', 'private is mapped to restricted')
+  const flatRestricted = {}
+  definitions.access.flatten('access', { access: 'restricted' }, flatRestricted)
+  t.equal(flatRestricted.access, 'restricted', 'restricted is passed through')
+  const flatPublic = {}
+  definitions.access.flatten('access', { access: 'public' }, flatPublic)
+  t.equal(flatPublic.access, 'public', 'public is passed through')
+  const flatNull = {}
+  definitions.access.flatten('access', { access: null }, flatNull)
+  t.equal(flatNull.access, null, 'null is passed through')
+  t.end()
+})
+
 t.test('editor', t => {
   t.test('has EDITOR and VISUAL, use EDITOR', t => {
     mockGlobals(t, { 'process.env': { EDITOR: 'vim', VISUAL: 'mate' } })

workspaces/config/test/index.js

@@ -412,7 +412,7 @@ loglevel = yolo
       ['warn', 'invalid config', 'omit="cucumber"', 'set in command line options'],
       ['warn', 'invalid config', 'Must be one or more of:', 'dev, optional, peer'],
       ['warn', 'invalid config', 'access="blueberry"', 'set in command line options'],
-      ['warn', 'invalid config', 'Must be one of:', 'null, restricted, public'],
+      ['warn', 'invalid config', 'Must be one of:', 'null, restricted, public, private'],
       ['warn', 'invalid config', 'multiple-numbers="what kind of fruit is not a number"',
         'set in command line options'],
       ['warn', 'invalid config', 'Must be one or more', 'numeric value'],
@@ -608,7 +608,7 @@ loglevel = yolo
       ['warn', 'invalid config', 'omit="cucumber"', 'set in command line options'],
       ['warn', 'invalid config', 'Must be one or more of:', 'dev, optional, peer'],
       ['warn', 'invalid config', 'access="blueberry"', 'set in command line options'],
-      ['warn', 'invalid config', 'Must be one of:', 'null, restricted, public'],
+      ['warn', 'invalid config', 'Must be one of:', 'null, restricted, public, private'],
       ['warn', 'invalid config', 'multiple-numbers="what kind of fruit is not a number"',
         'set in command line options'],
       ['warn', 'invalid config', 'Must be one or more', 'numeric value'],