feat: npm trust command

docs/lib/build.js

@@ -7,6 +7,208 @@ const parseFrontMatter = require('front-matter')
 const checkNav = require('./check-nav.js')
 const { DOC_EXT, ...transform } = require('./index.js')
 
+// Generate nav.yml from the filesystem
+const generateNav = async (contentPath, navPath) => {
+  const docsCommandsPath = join(contentPath, 'commands')
+
+  // Read all command files
+  const commandFiles = await fs.readdir(docsCommandsPath)
+  const commandDocs = commandFiles.filter(f => f.endsWith(DOC_EXT))
+
+  // Parse each command file to get title and description
+  const allCommands = await Promise.all(
+    commandDocs.map(async (file) => {
+      const content = await fs.readFile(join(docsCommandsPath, file), 'utf-8')
+      const { attributes } = parseFrontMatter(content)
+      const name = basename(file, DOC_EXT)
+      const title = (attributes.title || name).replace(/^npm-/, 'npm ')
+
+      return {
+        title,
+        url: `/commands/${name}`,
+        description: attributes.description || '',
+        name,
+      }
+    })
+  )
+
+  // Separate npm, npx, and other commands
+  const npm = allCommands.find(cmd => cmd.name === 'npm')
+  const npx = allCommands.find(cmd => cmd.name === 'npx')
+  const otherCommands = allCommands
+    .filter(cmd => cmd.name !== 'npm' && cmd.name !== 'npx')
+    .sort((a, b) => a.name.localeCompare(b.name))
+
+  // Remove the name field and arrange: npm, ...commands, npx
+  const commands = [npm, ...otherCommands, npx].filter(Boolean).map(({ name, ...rest }) => rest)
+
+  // Build the navigation structure
+  const navData = [
+    {
+      title: 'CLI Commands',
+      shortName: 'Commands',
+      url: '/commands',
+      children: commands,
+    },
+    {
+      title: 'Configuring npm',
+      shortName: 'Configuring',
+      url: '/configuring-npm',
+      children: [
+        {
+          title: 'Install',
+          url: '/configuring-npm/install',
+          description: 'Download and install node and npm',
+        },
+        {
+          title: 'Folders',
+          url: '/configuring-npm/folders',
+          description: 'Folder structures used by npm',
+        },
+        {
+          title: '.npmrc',
+          url: '/configuring-npm/npmrc',
+          description: 'The npm config files',
+        },
+        {
+          title: 'npm-shrinkwrap.json',
+          url: '/configuring-npm/npm-shrinkwrap-json',
+          description: 'A publishable lockfile',
+        },
+        {
+          title: 'package.json',
+          url: '/configuring-npm/package-json',
+          description: "Specifics of npm's package.json handling",
+        },
+        {
+          title: 'package-lock.json',
+          url: '/configuring-npm/package-lock-json',
+          description: 'A manifestation of the manifest',
+        },
+      ],
+    },
+    {
+      title: 'Using npm',
+      shortName: 'Using',
+      url: '/using-npm',
+      children: [
+        {
+          title: 'Registry',
+          url: '/using-npm/registry',
+          description: 'The JavaScript Package Registry',
+        },
+        {
+          title: 'Package spec',
+          url: '/using-npm/package-spec',
+          description: 'Package name specifier',
+        },
+        {
+          title: 'Config',
+          url: '/using-npm/config',
+          description: 'About npm configuration',
+        },
+        {
+          title: 'Logging',
+          url: '/using-npm/logging',
+          description: 'Why, What & How we Log',
+        },
+        {
+          title: 'Scope',
+          url: '/using-npm/scope',
+          description: 'Scoped packages',
+        },
+        {
+          title: 'Scripts',
+          url: '/using-npm/scripts',
+          description: 'How npm handles the "scripts" field',
+        },
+        {
+          title: 'Workspaces',
+          url: '/using-npm/workspaces',
+          description: 'Working with workspaces',
+        },
+        {
+          title: 'Organizations',
+          url: '/using-npm/orgs',
+          description: 'Working with teams & organizations',
+        },
+        {
+          title: 'Dependency Selectors',
+          url: '/using-npm/dependency-selectors',
+          description: 'Dependency Selector Syntax & Querying',
+        },
+        {
+          title: 'Developers',
+          url: '/using-npm/developers',
+          description: 'Developer guide',
+        },
+        {
+          title: 'Removal',
+          url: '/using-npm/removal',
+          description: 'Cleaning the slate',
+        },
+      ],
+    },
+  ]
+
+  const prefix = `
+# This is the navigation for the documentation pages; it is not used
+# directly within the CLI documentation.  Instead, it will be used
+# for the https://docs.npmjs.com/ site.
+`
+  await fs.writeFile(navPath, `${prefix}\n\n${yaml.stringify(navData)}`, 'utf-8')
+}
+
+// Auto-generate doc templates for commands without docs
+const autoGenerateMissingDocs = async (contentPath, navPath, commandsPath = null) => {
+  commandsPath = commandsPath || join(__dirname, '../../lib/commands')
+  const docsCommandsPath = join(contentPath, 'commands')
+
+  // Get all commands from cmd-list
+  const { commands } = require('../../lib/utils/cmd-list.js')
+
+  // Get existing doc files
+  const existingDocs = await fs.readdir(docsCommandsPath)
+  const documentedCommands = existingDocs
+    .filter(f => f.startsWith('npm-') && f.endsWith(DOC_EXT))
+    .map(f => f.replace('npm-', '').replace(DOC_EXT, ''))
+
+  // Find commands without docs
+  const missingDocs = commands.filter(cmd => !documentedCommands.includes(cmd))
+
+  // Generate docs for missing commands
+  for (const cmd of missingDocs) {
+    const Command = require(join(commandsPath, `${cmd}.js`))
+    const description = Command.description || `The ${cmd} command`
+    const docPath = join(docsCommandsPath, `npm-${cmd}${DOC_EXT}`)
+
+    const template = `---
+title: npm-${cmd}
+section: 1
+description: ${description}
+---
+
+### Synopsis
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS -->
+
+### Description
+
+${description}
+
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS -->
+
+### See Also
+
+* [npm help config](/commands/npm-config)
+`
+
+    await fs.writeFile(docPath, template, 'utf-8')
+  }
+}
+
 const mkDirs = async (paths) => {
   const uniqDirs = [...new Set(paths.map((p) => dirname(p)))]
   return Promise.all(uniqDirs.map((d) => fs.mkdir(d, { recursive: true })))
@@ -28,7 +230,15 @@ const pAll = async (obj) => {
   }, {})
 }
 
-const run = async ({ content, template, nav, man, html, md }) => {
+const run = async ({ content, template, nav, man, html, md, skipAutoGenerate }) => {
+  // Auto-generate docs for commands without documentation
+  if (!skipAutoGenerate) {
+    await autoGenerateMissingDocs(content, nav)
+  }
+
+  // Generate nav.yml from filesystem
+  await generateNav(content, nav)
+
   await rmAll(man, html, md)
   const [contentPaths, navFile, options] = await Promise.all([
     readDocs(content),
@@ -145,3 +355,5 @@ const run = async ({ content, template, nav, man, html, md }) => {
 }
 
 module.exports = run
+module.exports.generateNav = generateNav
+module.exports.autoGenerateMissingDocs = autoGenerateMissingDocs

docs/lib/content/commands/npm-get.md

@@ -0,0 +1,21 @@
+---
+title: npm-get
+section: 1
+description: Get a value from the npm configuration
+---
+
+### Synopsis
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS -->
+
+### Description
+
+Get a value from the npm configuration
+
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS -->
+
+### See Also
+
+* [npm help config](/commands/npm-config)

docs/lib/content/commands/npm-ll.md

@@ -0,0 +1,21 @@
+---
+title: npm-ll
+section: 1
+description: List installed packages
+---
+
+### Synopsis
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS -->
+
+### Description
+
+List installed packages
+
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS -->
+
+### See Also
+
+* [npm help config](/commands/npm-config)

docs/lib/content/commands/npm-set.md

@@ -0,0 +1,21 @@
+---
+title: npm-set
+section: 1
+description: Set a value in the npm configuration
+---
+
+### Synopsis
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS -->
+
+### Description
+
+Set a value in the npm configuration
+
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS -->
+
+### See Also
+
+* [npm help config](/commands/npm-config)

docs/lib/content/commands/npm-trust.md

@@ -0,0 +1,21 @@
+---
+title: npm-trust
+section: 1
+description: Create a trusted relationship between a package and a OIDC provider
+---
+
+### Synopsis
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS -->
+
+### Description
+
+Create a trusted relationship between a package and a OIDC provider
+
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS -->
+
+### See Also
+
+* [npm help config](/commands/npm-config)