@lexibase/rdx-next 1.0.0-beta.1 → 1.0.0-beta.10

package/README.md

@@ -1,6 +1,41 @@
-# `@rdx/next`
+# `@lexibase/rdx-next`
 
 The official Next.js runtime for RDX documentation projects.
 
+Requires Node.js 20.9 or newer; use a currently supported Node.js LTS release.
+The MDX renderer keeps JavaScript expression blocking enabled. Markdown, fenced
+code and registered JSX components with literal props remain supported, but
+expressions such as `{value}` or `style={{ ... }}` are not evaluated. Documentation
+must still be trusted project-owned content, not untrusted uploads.
+
 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,
+validates the result before saving it without creating backups, 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, Base UI version dropdown, mobile/desktop
+sidebar, landing page, MDX styles and theme provider. The adapter owns content
+and route data; it does not implement a parallel UI theme.
+
+Use `homepage: { enabled: true }` in `rdx.config.ts` for the centered-logo
+homepage, or import a project-owned React component with `homepage.component`.
+Without the option, `/` redirects to `/docs`. Additional content sources from
+explicitly configured plugins enable the shared navbar dropdown.
+
+`.rdx/` is generated. Configure the site or edit a project-owned `home.tsx`
+instead of modifying files inside `.rdx/`.
+
+Place images, favicon and downloads in the project-root `public/` directory.
+The CLI links `.rdx/public` to it using a junction on Windows or a directory
+symlink elsewhere. `/images/logo.svg` serves `public/images/logo.svg` in dev and
+production. No asset copies are cached and original files are never removed.
+Restart/redeploy production after adding/removing assets. Documentation versions
+share this directory; snapshots do not copy its contents.

package/bin/add-plugin.mjs

@@ -0,0 +1,229 @@
+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`)
+  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) {
+      await rename(temporary, filename)
+      log('Versioning activated in rdx.config.ts.')
+    } else
+      log('Versioning is already configured; no configuration changes needed.')
+  } finally {
+    await unlink(temporary).catch((error) => {
+      if (error.code !== 'ENOENT') throw error
+    })
+  }
+  return { 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/public-assets.mjs

@@ -0,0 +1,58 @@
+import { lstat, mkdir, realpath, symlink, unlink } from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+
+async function inspect(filePath) {
+  try {
+    return await lstat(filePath)
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+}
+
+/** Link generated Next public/ to project-owned assets; never copy or delete them. */
+export async function preparePublicAssets(projectRoot, runtimeDirectory) {
+  const runtime = await inspect(runtimeDirectory)
+  if (!runtime?.isDirectory() || runtime.isSymbolicLink())
+    throw new Error(
+      '.rdx/ must be a real directory, not a symbolic link or junction.'
+    )
+
+  const publicDirectory = path.join(projectRoot, 'public')
+  const existing = await inspect(publicDirectory)
+  if (existing && (!existing.isDirectory() || existing.isSymbolicLink()))
+    throw new Error('public/ must be a real directory in the project root.')
+  await mkdir(publicDirectory, { recursive: true })
+
+  const destination = path.join(runtimeDirectory, 'public')
+  const link = await inspect(destination)
+  if (link) {
+    if (!link.isSymbolicLink())
+      throw new Error(
+        'Cannot prepare .rdx/public: a file or directory already exists there. Move any assets to the project public/ directory, then remove the conflicting .rdx/public entry and retry. RDX has not removed it.'
+      )
+    let target
+    try {
+      target = await realpath(destination)
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error
+    }
+    if (target === (await realpath(publicDirectory))) return
+    // Only unlink the internal pointer, never its old target or the user's files.
+    await unlink(destination)
+  }
+
+  const target = process.platform === 'win32' ? publicDirectory : '../public'
+  try {
+    await symlink(
+      target,
+      destination,
+      process.platform === 'win32' ? 'junction' : 'dir'
+    )
+  } catch (error) {
+    throw new Error(
+      `Could not link .rdx/public to public/: ${error.message}. Use a filesystem that supports directory links (junctions on Windows); your public files have not been removed.`
+    )
+  }
+}

package/bin/rdx.mjs

@@ -2,13 +2,18 @@
 
 import { spawn } from 'node:child_process'
 import { createRequire } from 'node:module'
-import { cp, mkdir } from 'node:fs/promises'
+import { access, cp, mkdir } from 'node:fs/promises'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import process from 'node:process'
 
+import { createRdxProject } from '@lexibase/rdx-core/config'
+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(
@@ -20,31 +25,100 @@ const runtimeDirectory = path.join(projectRoot, '.rdx')
 
 async function prepareRuntime() {
   await mkdir(runtimeDirectory, { recursive: true })
+  await preparePublicAssets(projectRoot, runtimeDirectory)
   await cp(runtimeTemplate, runtimeDirectory, { force: true, recursive: true })
 }
 
-if (command === 'prepare') {
-  await prepareRuntime()
-  console.log('RDX runtime prepared in .rdx/')
-  process.exit(0)
-}
+async function main() {
+  if (!command || command === 'help' || command === '--help') {
+    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 || !supportedCommands.has(command)) {
-  console.error('Usage: rdx <dev|build|start|prepare>')
-  process.exit(1)
-}
+  if (command === 'add') {
+    const { addVersioning, parseAddArguments } =
+      await import('./add-plugin.mjs')
+    const options = parseAddArguments(commandArgs)
+    await addVersioning(projectRoot, options)
+    command = 'prepare'
+  }
 
-await prepareRuntime()
+  const configPath = path.join(projectRoot, 'rdx.config.ts')
+  try {
+    await access(configPath)
+  } catch {
+    throw new Error(
+      `Missing ${configPath}. Run rdx from the documentation project root.`
+    )
+  }
 
-const projectRequire = createRequire(path.join(projectRoot, 'package.json'))
-const nextCli = projectRequire.resolve('next/dist/bin/next')
-const child = spawn(
-  process.execPath,
-  [nextCli, command, runtimeDirectory, ...commandArgs],
-  { cwd: projectRoot, stdio: 'inherit' }
-)
+  const jiti = createJiti(import.meta.url, {
+    moduleCache: false,
+    fsCache: false,
+    jsx: { runtime: 'automatic' },
+  })
+  let input
+  try {
+    input = await jiti.import(configPath, { default: true })
+  } catch (error) {
+    const hint =
+      error.code === 'MODULE_NOT_FOUND' || error.code === 'ERR_MODULE_NOT_FOUND'
+        ? ' If a configured plugin cannot be resolved, install its package in this project.'
+        : ''
+    throw new Error(`Could not load rdx.config.ts: ${error.message}${hint}`)
+  }
 
-child.on('exit', (code, signal) => {
-  if (signal) process.kill(process.pid, signal)
-  process.exit(code ?? 1)
-})
+  const project = await createRdxProject(input, {
+    rootDir: projectRoot,
+    command,
+  })
+  if (command === 'prepare') {
+    await prepareRuntime()
+    console.log('RDX runtime prepared in .rdx/')
+    return
+  }
+  if (!supportedCommands.has(command)) {
+    const pluginCommand = project.commands.find(
+      (entry) => entry.name === command
+    )
+    if (!pluginCommand)
+      throw new Error(
+        `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,
+      config: project.config,
+      command,
+      args: commandArgs,
+    })
+    return
+  }
+
+  await prepareRuntime()
+  const projectRequire = createRequire(path.join(projectRoot, 'package.json'))
+  const nextCli = projectRequire.resolve('next/dist/bin/next')
+  const child = spawn(
+    process.execPath,
+    [nextCli, command, runtimeDirectory, ...commandArgs],
+    { cwd: projectRoot, stdio: 'inherit' }
+  )
+  child.on('error', (error) => {
+    console.error(`[RDX] Could not start Next.js: ${error.message}`)
+    process.exitCode = 1
+  })
+  child.on('exit', (code, signal) => {
+    if (signal) process.kill(process.pid, signal)
+    process.exit(code ?? 1)
+  })
+}
+
+try {
+  await main()
+} catch (error) {
+  console.error(`[RDX] ${error.message}`)
+  process.exitCode = 1
+}

package/dist/index.d.ts

@@ -1 +1,2 @@
-export { RdxRuntimeConfig } from '@lexibase/rdx-types';
+export { defineConfig } from '@lexibase/rdx-core/config';
+export { RdxConfig, RdxHomepage, RdxPlugin, RdxPluginContext, RdxRuntimeConfig } from '@lexibase/rdx-types';

package/dist/index.js

@@ -0,0 +1,5 @@
+// src/index.ts
+import { defineConfig } from "@lexibase/rdx-core/config";
+export {
+  defineConfig
+};

package/dist/runtime/index.d.ts

@@ -1,13 +1,24 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { ReactNode } from 'react';
-import { RdxRuntimeConfig } from '@lexibase/rdx-types';
+import { RdxProject, RdxRuntimeConfig } from '@lexibase/rdx-types';
+export { createRdxProject, getProjectDocsPaths } from '@lexibase/rdx-core';
 
-declare function RdxLayout({ children, config, }: {
+declare function getSearchSources(project: RdxProject): {
+    source: string;
+}[];
+declare function getSearchResponse(project: RdxProject, key: string): Response;
+
+declare function RdxLayout({ children, config, bodyClassName, }: {
     children: ReactNode;
     config: RdxRuntimeConfig;
-}): react_jsx_runtime.JSX.Element;
-declare function DocsPage({ slug }: {
+    bodyClassName?: string;
+}): react.JSX.Element;
+declare function HomePage({ project }: {
+    project: RdxProject;
+}): react.JSX.Element;
+declare function DocsPage({ slug, project, }: {
     slug?: string[];
-}): Promise<react_jsx_runtime.JSX.Element>;
+    project: RdxProject;
+}): Promise<react.JSX.Element>;
 
-export { DocsPage, RdxLayout };
+export { DocsPage, HomePage, RdxLayout, getSearchResponse, getSearchSources };