@lexibase/rdx-next 1.0.0-beta.8 → 1.0.0-beta.9

package/README.md

@@ -5,6 +5,15 @@ The official Next.js runtime for RDX documentation projects.
 It exposes the `rdx` command used by generated projects to create their
 internal `.rdx` application and run Next.js.
 
+Run `pnpm rdx add versioning` (or `npm exec -- rdx add versioning`) from a
+documentation project to install and activate the official optional plugin.
+The command detects the package manager, preserves config and plugin options,
+creates a config backup when changing it, validates the result and prepares
+the runtime. Repeating it does not duplicate or upgrade an installed plugin.
+Use `--package-manager npm|pnpm|yarn` to resolve ambiguous lockfiles. Dynamic
+configurations receive manual instructions and are not automatically edited.
+Installing a package with npm/pnpm/yarn alone never edits `rdx.config.ts`.
+
 Generated sites use the same theme and components as the development website,
 through `@lexibase/rdx-ui`: logo, navbar, Radix version dropdown, mobile/desktop
 sidebar, landing page, MDX styles and theme provider. The adapter owns content

package/bin/add-plugin.mjs

@@ -0,0 +1,234 @@
+import { randomUUID } from 'node:crypto'
+import { createRequire } from 'node:module'
+import { lstat, readFile, writeFile, rename, unlink } from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+
+import { createRdxProject, resolveConfig } from '@lexibase/rdx-core/config'
+import spawn from 'cross-spawn'
+import { createJiti } from 'jiti'
+
+import { activateVersioning, versioningPackage } from './plugin-config.mjs'
+
+const managers = new Set(['npm', 'pnpm', 'yarn'])
+
+export function parseAddArguments(args) {
+  const [plugin, ...rest] = args
+  if (plugin !== 'versioning')
+    throw new Error(
+      'Usage: rdx add versioning [--package-manager npm|pnpm|yarn]. Only the official versioning plugin is currently supported.'
+    )
+  if (!rest.length) return {}
+  if (
+    rest.length === 2 &&
+    rest[0] === '--package-manager' &&
+    managers.has(rest[1])
+  )
+    return { packageManager: rest[1] }
+  throw new Error(
+    'Usage: rdx add versioning [--package-manager npm|pnpm|yarn].'
+  )
+}
+
+async function exists(filename) {
+  try {
+    await lstat(filename)
+    return true
+  } catch (error) {
+    if (error.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+export async function detectPackageManager(
+  rootDir,
+  pkg,
+  env = process.env,
+  explicit
+) {
+  if (explicit) {
+    if (!managers.has(explicit)) throw new Error('Unsupported package manager.')
+    return explicit
+  }
+  if (
+    pkg.packageManager !== undefined &&
+    typeof pkg.packageManager !== 'string'
+  )
+    throw new Error('packageManager in package.json must be a string.')
+  const declared = pkg.packageManager?.split('@')[0]
+  if (declared && !managers.has(declared))
+    throw new Error(
+      'Unsupported packageManager in package.json. Choose --package-manager npm, pnpm or yarn explicitly.'
+    )
+  const locks = []
+  for (const [manager, filenames] of [
+    ['npm', ['package-lock.json', 'npm-shrinkwrap.json']],
+    ['pnpm', ['pnpm-lock.yaml']],
+    ['yarn', ['yarn.lock']],
+  ]) {
+    if (
+      (
+        await Promise.all(
+          filenames.map((filename) => exists(path.join(rootDir, filename)))
+        )
+      ).some(Boolean)
+    )
+      locks.push(manager)
+  }
+  if (locks.length > 1 || (declared && locks.length && locks[0] !== declared))
+    throw new Error(
+      'Conflicting package managers. Keep the intended lockfile or choose --package-manager npm, pnpm or yarn explicitly.'
+    )
+  const agent = env.npm_config_user_agent?.split('/')[0]
+  return declared ?? locks[0] ?? (managers.has(agent) ? agent : 'npm')
+}
+
+export function installPackage(manager, rootDir, env = process.env) {
+  return new Promise((resolve, reject) => {
+    const args = [
+      manager === 'npm' ? 'install' : 'add',
+      `${versioningPackage}@beta`,
+    ]
+    const nodeEntry =
+      env.npm_config_user_agent?.startsWith(`${manager}/`) &&
+      env.npm_execpath &&
+      /\.[cm]?js$/i.test(env.npm_execpath)
+    const child = spawn(
+      nodeEntry ? process.execPath : manager,
+      nodeEntry ? [env.npm_execpath, ...args] : args,
+      { cwd: rootDir, env, stdio: 'inherit' }
+    )
+    child.once('error', (error) =>
+      reject(
+        new Error(
+          `Could not run ${manager}: ${error.message}. Install it or choose --package-manager explicitly.`
+        )
+      )
+    )
+    child.once('exit', (code, signal) => {
+      if (code === 0) resolve()
+      else
+        reject(
+          new Error(
+            `${manager} installation failed (${signal ?? code}). rdx.config.ts was not changed. Package/lock files may have changed; inspect them before retrying. If pnpm reports a release-age policy error, approve only the trusted RDX release in your project policy.`
+          )
+        )
+    })
+  })
+}
+
+async function validateCandidate(filename) {
+  const jiti = createJiti(import.meta.url, {
+    moduleCache: false,
+    fsCache: false,
+    jsx: { runtime: 'automatic' },
+  })
+  const input = await jiti.import(filename, { default: true })
+  const config = resolveConfig(input)
+  // Validate paths and command registrations without running plugin setup hooks.
+  await createRdxProject(
+    {
+      ...config,
+      plugins: config.plugins.map((plugin) => ({
+        ...plugin,
+        setup: undefined,
+      })),
+    },
+    { rootDir: path.dirname(filename), command: 'prepare' }
+  )
+  if (
+    config.plugins.filter((plugin) => plugin.name === versioningPackage)
+      .length !== 1
+  )
+    throw new Error(
+      'Expected exactly one official versioning plugin in the resulting configuration.'
+    )
+}
+
+export async function addVersioning(rootDir, options = {}) {
+  const {
+    install = installPackage,
+    log = console.log,
+    env = process.env,
+  } = options
+  const filename = path.join(rootDir, 'rdx.config.ts')
+  let info
+  try {
+    info = await lstat(filename)
+  } catch (error) {
+    if (error.code === 'ENOENT')
+      throw new Error(
+        'Missing rdx.config.ts. Run rdx add from the documentation project root.'
+      )
+    throw error
+  }
+  if (!info.isFile() || info.isSymbolicLink())
+    throw new Error('rdx.config.ts must be a regular project file, not a link.')
+  const original = await readFile(filename, 'utf8')
+  // Refuse unsupported configurations before running the package manager.
+  const updated = activateVersioning(original)
+  const pkg = JSON.parse(
+    await readFile(path.join(rootDir, 'package.json'), 'utf8')
+  )
+  const manager = await detectPackageManager(
+    rootDir,
+    pkg,
+    env,
+    options.packageManager
+  )
+  const declared =
+    pkg.dependencies?.[versioningPackage] ??
+    pkg.devDependencies?.[versioningPackage]
+  let installed = false
+  try {
+    createRequire(path.join(rootDir, 'package.json')).resolve(versioningPackage)
+    installed = true
+  } catch (error) {
+    // The official package exposes ESM imports only. require.resolve can find
+    // its manifest but reject the require condition; validation below uses Jiti.
+    if (error.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') installed = true
+    else if (!['MODULE_NOT_FOUND', 'ERR_MODULE_NOT_FOUND'].includes(error.code))
+      throw error
+  }
+  if (!declared || !installed) {
+    log(`Installing ${versioningPackage}@beta with ${manager}...`)
+    await install(manager, rootDir, env)
+  } else
+    log(`${versioningPackage} is already installed; preserving its version.`)
+
+  const temporary = path.join(rootDir, `rdx.config.add-${randomUUID()}.ts`)
+  let backup
+  try {
+    await writeFile(temporary, updated, { flag: 'wx', mode: info.mode })
+    try {
+      await validateCandidate(temporary)
+    } catch (error) {
+      throw new Error(
+        `Plugin configuration validation failed: ${error.message}. rdx.config.ts was not changed. Installed dependencies were kept; fix the error and retry.`
+      )
+    }
+    if ((await readFile(filename, 'utf8')) !== original)
+      throw new Error(
+        'rdx.config.ts changed during installation. No configuration was overwritten; retry after reviewing your edits.'
+      )
+    const currentInfo = await lstat(filename)
+    if (!currentInfo.isFile() || currentInfo.isSymbolicLink())
+      throw new Error(
+        'rdx.config.ts was replaced during installation. No configuration was overwritten.'
+      )
+    if (updated !== original) {
+      backup = path.join(rootDir, `rdx.config.ts.${randomUUID()}.bak`)
+      await writeFile(backup, original, { flag: 'wx', mode: info.mode })
+      await rename(temporary, filename)
+      log(
+        `Versioning activated. Original configuration saved to ${path.basename(backup)}.`
+      )
+    } else
+      log('Versioning is already configured; no configuration changes needed.')
+  } finally {
+    await unlink(temporary).catch((error) => {
+      if (error.code !== 'ENOENT') throw error
+    })
+  }
+  return { backup, changed: updated !== original }
+}

package/bin/plugin-config.mjs

@@ -0,0 +1,155 @@
+import ts from 'typescript'
+
+export const versioningPackage = '@lexibase/rdx-versioning'
+const manual = `Cannot safely edit rdx.config.ts. Add "import { versioning } from '${versioningPackage}'" and versioning() to plugins manually, then run rdx prepare.`
+
+function unwrap(node) {
+  while (
+    ts.isParenthesizedExpression(node) ||
+    ts.isAsExpression(node) ||
+    ts.isSatisfiesExpression(node)
+  )
+    node = node.expression
+  return node
+}
+
+// Edit only known literal shapes; never print/reconstruct the user's entire file.
+export function activateVersioning(source) {
+  const file = ts.createSourceFile(
+    'rdx.config.ts',
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  )
+  if (file.parseDiagnostics.length) throw new Error(manual)
+  const imports = file.statements.filter(ts.isImportDeclaration)
+  const definitions = new Set()
+  let factory
+  for (const entry of imports) {
+    const name = entry.moduleSpecifier.text
+    const clause = entry.importClause
+    if (!clause || clause.isTypeOnly) continue
+    const bindings = clause.namedBindings
+    if (bindings && ts.isNamedImports(bindings)) {
+      for (const specifier of bindings.elements) {
+        if (specifier.isTypeOnly) continue
+        const imported = (specifier.propertyName ?? specifier.name).text
+        if (
+          ['@lexibase/rdx-next', '@lexibase/rdx-core/config'].includes(name) &&
+          imported === 'defineConfig'
+        )
+          definitions.add(specifier.name.text)
+        if (name === versioningPackage && imported === 'versioning') {
+          if (factory) throw new Error(manual)
+          factory = specifier.name.text
+        }
+      }
+    } else if (
+      bindings &&
+      ts.isNamespaceImport(bindings) &&
+      name === versioningPackage
+    ) {
+      if (factory) throw new Error(manual)
+      factory = `${bindings.name.text}.versioning`
+    }
+  }
+  const exports = file.statements.filter(ts.isExportAssignment)
+  if (exports.length !== 1 || exports[0].isExportEquals) throw new Error(manual)
+  let config = unwrap(exports[0].expression)
+  if (ts.isCallExpression(config)) {
+    if (
+      !ts.isIdentifier(config.expression) ||
+      !definitions.has(config.expression.text) ||
+      config.arguments.length !== 1
+    )
+      throw new Error(manual)
+    config = unwrap(config.arguments[0])
+  }
+  if (!ts.isObjectLiteralExpression(config)) throw new Error(manual)
+  const properties = config.properties
+  if (
+    properties.some(
+      (entry) =>
+        !ts.isPropertyAssignment(entry) || ts.isComputedPropertyName(entry.name)
+    )
+  )
+    throw new Error(manual)
+  const pluginsProperties = properties.filter(
+    (entry) => entry.name.text === 'plugins'
+  )
+  if (pluginsProperties.length > 1) throw new Error(manual)
+  const plugins = pluginsProperties.length
+    ? unwrap(pluginsProperties[0].initializer)
+    : undefined
+  if (
+    plugins &&
+    (!ts.isArrayLiteralExpression(plugins) ||
+      plugins.elements.some(ts.isSpreadElement))
+  )
+    throw new Error(manual)
+  if (plugins && factory) {
+    const matches = plugins.elements.filter(
+      (entry) =>
+        ts.isCallExpression(unwrap(entry)) &&
+        unwrap(entry).expression.getText(file) === factory
+    )
+    if (matches.length > 1)
+      throw new Error(
+        'Versioning is configured more than once. Remove the duplicate plugin before retrying.'
+      )
+    if (matches.length === 1) return source
+  }
+  const newline = source.includes('\r\n') ? '\r\n' : '\n'
+  const edits = []
+  if (!factory) {
+    const identifiers = new Set()
+    function visit(node) {
+      if (ts.isIdentifier(node)) identifiers.add(node.text)
+      ts.forEachChild(node, visit)
+    }
+    visit(file)
+    factory = 'versioning'
+    let suffix = 1
+    while (identifiers.has(factory)) factory = `rdxVersioning${suffix++}`
+    const specifier =
+      factory === 'versioning' ? 'versioning' : `versioning as ${factory}`
+    let position = imports.length
+      ? imports.at(-1).end
+      : file.statements[0].getStart(file)
+    if (!imports.length) {
+      for (const statement of file.statements) {
+        if (
+          !ts.isExpressionStatement(statement) ||
+          !ts.isStringLiteral(statement.expression)
+        )
+          break
+        position = statement.end
+      }
+    }
+    edits.push({
+      position,
+      text: `${newline}import { ${specifier} } from '${versioningPackage}'${newline}`,
+    })
+  }
+  if (plugins) {
+    const position = plugins.elements.length
+      ? plugins.elements.at(-1).end
+      : plugins.getStart(file) + 1
+    edits.push({
+      position,
+      text: `${plugins.elements.length ? ',' : ''} ${factory}()`,
+    })
+  } else {
+    if (properties.length && !properties.hasTrailingComma)
+      edits.push({ position: properties.at(-1).end, text: ',' })
+    edits.push({
+      position: config.end - 1,
+      text: `${newline}  plugins: [${factory}()],${newline}`,
+    })
+  }
+  for (const edit of edits.sort((a, b) => b.position - a.position))
+    source =
+      source.slice(0, edit.position) + edit.text + source.slice(edit.position)
+  return source
+}

package/bin/rdx.mjs

@@ -13,7 +13,7 @@ import { createJiti } from 'jiti'
 import { preparePublicAssets } from './public-assets.mjs'
 
 const supportedCommands = new Set(['dev', 'build', 'start'])
-const command = process.argv[2]
+let command = process.argv[2]
 const commandArgs = process.argv.slice(3)
 const projectRoot = process.cwd()
 const packageRoot = path.resolve(
@@ -31,13 +31,23 @@ async function prepareRuntime() {
 
 async function main() {
   if (!command || command === 'help' || command === '--help') {
-    console.log('Usage: rdx <dev|build|start|prepare|plugin-command>')
+    console.log('Usage: rdx <dev|build|start|prepare|add|plugin-command>')
+    console.log('  rdx add versioning [--package-manager npm|pnpm|yarn]')
     console.log(
       'Plugin commands are registered through plugins in rdx.config.ts.'
     )
     return
   }
 
+  if (command === 'add') {
+    const { addVersioning, parseAddArguments } = await import(
+      './add-plugin.mjs'
+    )
+    const options = parseAddArguments(commandArgs)
+    await addVersioning(projectRoot, options)
+    command = 'prepare'
+  }
+
   const configPath = path.join(projectRoot, 'rdx.config.ts')
   try {
     await access(configPath)
@@ -78,7 +88,7 @@ async function main() {
     )
     if (!pluginCommand)
       throw new Error(
-        `Unknown command "${command}". Available: dev, build, start, prepare${project.commands.map((entry) => `, ${entry.name}`).join('')}. Install and configure the plugin that provides this command.`
+        `Unknown command "${command}". Available: dev, build, start, prepare, add${project.commands.map((entry) => `, ${entry.name}`).join('')}. Install and configure the plugin that provides this command.`
       )
     await pluginCommand.run({
       rootDir: projectRoot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexibase/rdx-next",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0-beta.9",
   "description": "The Next.js runtime for RDX documentation projects.",
   "license": "MIT",
   "type": "module",
@@ -28,11 +28,13 @@
     "README.md"
   ],
   "dependencies": {
+    "cross-spawn": "^7.0.6",
+    "typescript": "5.9.2",
     "jiti": "^2.6.1",
     "next-mdx-remote": "^5.0.0",
     "@lexibase/rdx-ui": "1.0.0-beta.1",
     "@lexibase/rdx-types": "1.0.0-beta.4",
-    "@lexibase/rdx-core": "1.0.0-beta.5"
+    "@lexibase/rdx-core": "1.0.0-beta.6"
   },
   "peerDependencies": {
     "next": "^15.5.0",
@@ -59,9 +61,8 @@
     "next": "^15.5.0",
     "react": "19.1.0",
     "react-dom": "19.1.0",
-    "typescript": "5.9.2",
-    "@rdx/typescript-config": "1.0.0",
-    "@rdx/eslint-config": "1.0.0"
+    "@rdx/eslint-config": "1.0.0",
+    "@rdx/typescript-config": "1.0.0"
   },
   "scripts": {
     "build": "tsup src/index.ts src/runtime/index.tsx --format esm --dts --clean --external @lexibase/rdx-core --external @lexibase/rdx-types --external next --external react --external react-dom --external next-mdx-remote",