feat(rpk-docs): refresh a single plugin's docs with --plugin

CLI_REFERENCE.adoc

@@ -490,6 +490,7 @@ display help for command
 * `migrate-rpcn-metadata` - One-time migration of inline connector == Metadata blocks into regenerated partials. Dry run unless --write is given.
 * `property-docs` - Generate JSON and consolidated AsciiDoc partials for Redpanda configuration properties. Defaults to branch "dev" if neither --tag nor --branch is specified.
 * `rpk-docs` - Generate rpk CLI documentation from source. Builds rpk and parses source for platform detection.
+* `rpk-plugin-stubs` - Reconcile single-source stub pages and nav against the docs repo's rpk plugin partials. Run from the consumer repo root.
 * `rpk-overrides` - Validate rpk-overrides.json against schema and check for common issues
 * `helm-spec` - Generate AsciiDoc documentation for Helm charts. Requires either --tag or --branch for GitHub URLs.
 * `cloud-regions` - Generate Markdown table of cloud regions and tiers from GitHub YAML file
@@ -693,6 +694,18 @@ Path to local rpk source (src/go/rpk directory)
 `--from-json <path>`::
 Regenerate docs from an existing versioned JSON file (skips building)
 
+`--plugin <name>`::
+Refresh a single rpk plugin's docs (ai, connect, k8s, check). Requires --from-json. Installs the plugin, splices its fresh subtree into the snapshot, and re-renders.
+
+`--plugin-version <version>`::
+Plugin version to install and record (for example, 4.102.0). Defaults to the latest published version.
+
+`--plugin-pin <name=version>`::
+Pin a plugin version for the installs during full generation (repeatable, for example --plugin-pin k8s=26.3.1-beta.1). Required for pre-GA plugins with no promoted latest version. (default: {})
+
+`--rpk-bin <path>`::
+Path to an existing rpk binary for the plugin refresh (skips download/build)
+
 `--overrides <path>`::
 Path to overrides JSON file (default: "docs-data/rpk-overrides.json")
 

__tests__/tools/rpk-docs/plugin-flags.test.js

@@ -0,0 +1,180 @@
+'use strict'
+
+const { parseCobraFlags, enrichPluginTreeWithFlags } = require('../../../tools/rpk-docs/rpk-docs-handler.js')
+
+describe('parseCobraFlags', () => {
+  const HELP = [
+    'Reconcile LLM providers from one or more YAML manifests.',
+    '',
+    'Usage:',
+    '  rpk ai llm-provider apply [flags]',
+    '',
+    'Flags:',
+    '      --allow-empty            Allow applying zero manifests',
+    '  -f, --file strings           Manifest paths, - for stdin (default [])',
+    '  -h, --help                   help for apply',
+    '      --timeout duration       How long to wait for the reconcile to',
+    '                               complete before giving up (default 30s)',
+    '  -o, --format string          Output format (default "text")',
+    '',
+    'Global Flags:',
+    '  -c, --config string   rpk config file',
+    '  -v, --verbose         enable verbose logging',
+    '',
+    'Use "rpk ai llm-provider apply [command] --help" for more information.'
+  ].join('\n')
+
+  test('parses local flags with shorthand, type, and default', () => {
+    const flags = parseCobraFlags(HELP)
+    const byName = Object.fromEntries(flags.map(f => [f.name, f]))
+
+    expect(byName['allow-empty']).toMatchObject({ type: 'bool' })
+    expect(byName['file']).toMatchObject({ shorthand: 'f', type: 'strings', default: '[]' })
+    expect(byName['format']).toMatchObject({ shorthand: 'o', type: 'string', default: '"text"' })
+  })
+
+  test('joins wrapped descriptions and extracts trailing defaults', () => {
+    const flags = parseCobraFlags(HELP)
+    const timeout = flags.find(f => f.name === 'timeout')
+    expect(timeout.description).toBe('How long to wait for the reconcile to complete before giving up')
+    expect(timeout.default).toBe('30s')
+  })
+
+  test('skips --help and the Global Flags section', () => {
+    const flags = parseCobraFlags(HELP)
+    expect(flags.map(f => f.name)).not.toContain('help')
+    expect(flags.map(f => f.name)).not.toContain('config')
+    expect(flags.map(f => f.name)).not.toContain('verbose')
+  })
+
+  test('returns empty for help without a Flags section', () => {
+    expect(parseCobraFlags('Usage:\n  rpk ai\n\nUse "rpk ai --help".')).toEqual([])
+    expect(parseCobraFlags('')).toEqual([])
+  })
+})
+
+describe('enrichPluginTreeWithFlags', () => {
+  test('fills flagless commands and leaves shim flags alone', () => {
+    const node = {
+      name: 'ai',
+      commands: [
+        { name: 'install', flags: [{ name: 'ai-version', type: 'string' }], commands: [] },
+        { name: 'auth', commands: [{ name: 'login', commands: [] }] }
+      ]
+    }
+    const calls = []
+    const enriched = enrichPluginTreeWithFlags(node, (argPath) => {
+      calls.push(argPath.join(' '))
+      return 'Flags:\n      --no-browser   Print the URL instead of opening it\n'
+    })
+
+    // install already has flags: not queried
+    expect(calls).not.toContain('ai install')
+    expect(calls).toContain('ai auth login')
+    const login = node.commands[1].commands[0]
+    expect(login.flags).toHaveLength(1)
+    expect(login.flags[0]).toMatchObject({ name: 'no-browser', type: 'bool' })
+    expect(node.commands[0].flags[0].name).toBe('ai-version')
+    expect(enriched).toBeGreaterThanOrEqual(2) // root + auth + login minus empties
+  })
+
+  test('help failures are non-fatal', () => {
+    const node = { name: 'ai', commands: [{ name: 'run', commands: [] }] }
+    const enriched = enrichPluginTreeWithFlags(node, () => null)
+    expect(enriched).toBe(0)
+    expect(node.commands[0].flags).toBeUndefined()
+  })
+})
+
+describe('mergeVisibleDeprecationsIntoOverrides', () => {
+  const fs = require('fs')
+  const path = require('path')
+  const os = require('os')
+  const { mergeVisibleDeprecationsIntoOverrides } = require('../../../tools/rpk-docs/rpk-docs-handler.js')
+
+  const tree = {
+    name: 'rpk',
+    commands: [
+      { name: 'oldcmd', commands: [] },
+      { name: 'topic', commands: [] }
+    ]
+  }
+
+  let dir, overridesPath
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dep-merge-'))
+    overridesPath = path.join(dir, 'overrides.json')
+  })
+  afterEach(() => fs.rmSync(dir, { recursive: true, force: true }))
+
+  test('annotates visible deprecated commands, skips hidden ones', () => {
+    fs.writeFileSync(overridesPath, JSON.stringify({ commands: {} }))
+    mergeVisibleDeprecationsIntoOverrides({
+      'rpk oldcmd': { deprecated: true, deprecatedMessage: 'use rpk newcmd', replacement: 'See `rpk newcmd`.' },
+      'rpk hiddencmd': { deprecated: true, _note: 'Hidden: true' }
+    }, tree, overridesPath)
+
+    const result = JSON.parse(fs.readFileSync(overridesPath, 'utf8'))
+    expect(result.commands['rpk oldcmd']).toMatchObject({
+      deprecated: true,
+      deprecatedMessage: 'use rpk newcmd',
+      replacement: 'See `rpk newcmd`.'
+    })
+    // hiddencmd is not in the tree: no page to annotate
+    expect(result.commands['rpk hiddencmd']).toBeUndefined()
+  })
+
+  test('never overwrites curated deprecation overrides', () => {
+    fs.writeFileSync(overridesPath, JSON.stringify({
+      commands: { 'rpk oldcmd': { deprecated: false, deprecatedMessage: 'curated text' } }
+    }))
+    mergeVisibleDeprecationsIntoOverrides({
+      'rpk oldcmd': { deprecated: true, deprecatedMessage: 'scanner text' }
+    }, tree, overridesPath)
+
+    const result = JSON.parse(fs.readFileSync(overridesPath, 'utf8'))
+    expect(result.commands['rpk oldcmd'].deprecated).toBe(false)
+    expect(result.commands['rpk oldcmd'].deprecatedMessage).toBe('curated text')
+  })
+
+  test('no-op when nothing to annotate', () => {
+    fs.writeFileSync(overridesPath, JSON.stringify({ commands: {} }))
+    const before = fs.readFileSync(overridesPath, 'utf8')
+    mergeVisibleDeprecationsIntoOverrides({}, tree, overridesPath)
+    expect(fs.readFileSync(overridesPath, 'utf8')).toBe(before)
+  })
+})
+
+describe('parseUrfaveFlags (Redpanda Connect help format)', () => {
+  const { parseUrfaveFlags, parseHelpFlags } = require('../../../tools/rpk-docs/rpk-docs-handler.js')
+
+  const HELP = [
+    'NAME:',
+    '   redpanda-connect run - Run',
+    '',
+    'OPTIONS:',
+    '   --log.level value                     override the log level',
+    '   --set value, -s value [ --set value, -s value ]   set a field',
+    '   --chilled                             continue on lint errors (default: false)',
+    '   --watcher, -w                         watch config files (default: false)',
+    '',
+    'GLOBAL OPTIONS:',
+    '   --verbose   noisy'
+  ].join('\n')
+
+  test('parses names, shorthands, types, and defaults', () => {
+    const flags = parseUrfaveFlags(HELP)
+    const byName = Object.fromEntries(flags.map(f => [f.name, f]))
+    expect(byName['log.level']).toMatchObject({ type: 'string' })
+    expect(byName['set']).toMatchObject({ shorthand: 's', type: 'strings' })
+    expect(byName['chilled']).toMatchObject({ type: 'bool', default: 'false' })
+    expect(byName['watcher']).toMatchObject({ shorthand: 'w', type: 'bool' })
+    expect(flags.map(f => f.name)).not.toContain('verbose')
+  })
+
+  test('parseHelpFlags dispatches by section header', () => {
+    expect(parseHelpFlags(HELP).length).toBe(4)
+    expect(parseHelpFlags('Flags:\n      --no-browser   print URL\n').length).toBe(1)
+    expect(parseHelpFlags('Usage: nothing here')).toEqual([])
+  })
+})

__tests__/tools/rpk-docs/plugin-refresh.test.js

@@ -0,0 +1,154 @@
+'use strict'
+
+const {
+  splicePluginNode,
+  preserveLinuxOnlyCommands,
+  pluginNodeHasRealCommands,
+  REFRESHABLE_PLUGINS,
+  PLUGIN_INSTALL_VERSION_FLAGS,
+  PLUGIN_MANIFEST_SLUGS
+} = require('../../../tools/rpk-docs/rpk-docs-handler.js')
+
+describe('Plugin refresh (--plugin mode)', () => {
+  const shimOnlyNode = {
+    name: 'k8s',
+    description: 'Kubernetes plugin',
+    commands: [
+      { name: 'install' },
+      { name: 'uninstall' },
+      { name: 'upgrade' }
+    ]
+  }
+
+  const installedNode = {
+    name: 'connect',
+    description: 'Redpanda Connect plugin',
+    commands: [
+      { name: 'install' },
+      { name: 'uninstall' },
+      { name: 'upgrade' },
+      { name: 'run', description: 'Run a pipeline' },
+      { name: 'lint', description: 'Lint a config' }
+    ]
+  }
+
+  const baseTree = {
+    name: 'rpk',
+    global_flags: [{ name: '--config' }],
+    commands: [
+      { name: 'topic', commands: [{ name: 'create' }] },
+      { name: 'connect', commands: [{ name: 'install' }, { name: 'run', description: 'old run' }] },
+      { name: 'cluster', commands: [{ name: 'health' }] }
+    ]
+  }
+
+  describe('pluginNodeHasRealCommands', () => {
+    test('false for a shim-only node (install/uninstall/upgrade)', () => {
+      expect(pluginNodeHasRealCommands(shimOnlyNode)).toBe(false)
+    })
+
+    test('true when real plugin commands are present', () => {
+      expect(pluginNodeHasRealCommands(installedNode)).toBe(true)
+    })
+
+    test('false for a node with no subcommands', () => {
+      expect(pluginNodeHasRealCommands({ name: 'ai' })).toBe(false)
+    })
+  })
+
+  describe('splicePluginNode', () => {
+    test('replaces the plugin node and keeps everything else', () => {
+      const result = splicePluginNode(baseTree, 'connect', installedNode)
+
+      expect(result.commands.map(c => c.name)).toEqual(['topic', 'connect', 'cluster'])
+      const connect = result.commands.find(c => c.name === 'connect')
+      expect(connect.commands.map(c => c.name)).toContain('lint')
+      expect(result.commands.find(c => c.name === 'topic')).toBe(baseTree.commands[0])
+      expect(result.global_flags).toEqual(baseTree.global_flags)
+    })
+
+    test('does not mutate the input tree', () => {
+      splicePluginNode(baseTree, 'connect', installedNode)
+      const connect = baseTree.commands.find(c => c.name === 'connect')
+      expect(connect.commands.find(c => c.name === 'run').description).toBe('old run')
+    })
+
+    test('throws when the plugin is not in the base tree', () => {
+      expect(() => splicePluginNode(baseTree, 'k8s', shimOnlyNode))
+        .toThrow(/not present in the base tree/)
+    })
+
+    test('keeps the tree linux_only_commands list through a splice', () => {
+      const treeWithMarkers = { ...baseTree, linux_only_commands: ['rpk debug bundle', 'rpk iotune'] }
+      const result = splicePluginNode(treeWithMarkers, 'connect', installedNode)
+      expect(result.linux_only_commands).toEqual(['rpk debug bundle', 'rpk iotune'])
+    })
+  })
+
+  describe('preserveLinuxOnlyCommands', () => {
+    const linuxOnly = ['rpk debug bundle', 'rpk iotune']
+
+    test('inherits the snapshot list when the working tree lacks it', () => {
+      const result = preserveLinuxOnlyCommands(baseTree, { ...baseTree, linux_only_commands: linuxOnly })
+      expect(result.linux_only_commands).toEqual(linuxOnly)
+      // Copies, not aliases: mutating the result must not touch the snapshot
+      expect(result.linux_only_commands).not.toBe(linuxOnly)
+      expect(result.commands).toBe(baseTree.commands)
+    })
+
+    test('keeps the working tree list when it already has one', () => {
+      const tree = { ...baseTree, linux_only_commands: linuxOnly }
+      const result = preserveLinuxOnlyCommands(tree, { ...baseTree, linux_only_commands: ['rpk other'] })
+      expect(result).toBe(tree)
+      expect(result.linux_only_commands).toEqual(linuxOnly)
+    })
+
+    test('is a no-op when neither tree carries the list', () => {
+      expect(preserveLinuxOnlyCommands(baseTree, baseTree)).toBe(baseTree)
+      expect(preserveLinuxOnlyCommands(baseTree, undefined)).toBe(baseTree)
+      expect(preserveLinuxOnlyCommands(null, baseTree)).toBe(null)
+    })
+
+    test('refresh persistence chain keeps markers for the saved snapshot', () => {
+      // Mirrors the --plugin save path: derive the working tree from the
+      // snapshot, splice the fresh subtree, then preserve before persisting.
+      const snapshot = {
+        raw_tree: { ...baseTree, linux_only_commands: linuxOnly },
+        tree: { ...baseTree, linux_only_commands: linuxOnly }
+      }
+      let tree = snapshot.raw_tree || snapshot.tree
+      tree = preserveLinuxOnlyCommands(tree, snapshot.tree || snapshot.raw_tree)
+      tree = splicePluginNode(tree, 'connect', installedNode)
+      tree = preserveLinuxOnlyCommands(tree, snapshot.raw_tree || snapshot.tree)
+      expect(tree.linux_only_commands).toEqual(linuxOnly)
+    })
+
+    test('refresh persistence chain restores markers when only the enhanced tree has them', () => {
+      // Older snapshots may carry the field on only one stored tree; the
+      // derivation step must inherit it so the re-saved snapshot keeps it.
+      const snapshot = {
+        raw_tree: { ...baseTree },
+        tree: { ...baseTree, linux_only_commands: linuxOnly }
+      }
+      let tree = snapshot.raw_tree || snapshot.tree
+      tree = preserveLinuxOnlyCommands(tree, snapshot.tree || snapshot.raw_tree)
+      expect(tree.linux_only_commands).toEqual(linuxOnly)
+    })
+  })
+
+  describe('plugin constants', () => {
+    test('every refreshable plugin has a version pin flag', () => {
+      for (const plugin of REFRESHABLE_PLUGINS) {
+        expect(PLUGIN_INSTALL_VERSION_FLAGS[plugin]).toMatch(/^--[a-z-]+$/)
+      }
+    })
+
+    test('oxla is not refreshable (stub with no installable binary)', () => {
+      expect(REFRESHABLE_PLUGINS).not.toContain('oxla')
+    })
+
+    test('ai maps to the rpai manifest slug', () => {
+      expect(PLUGIN_MANIFEST_SLUGS.ai).toBe('rpai')
+    })
+  })
+})