@lexibase/create-rdx 4.1.0 → 4.2.1

package/README.md

@@ -39,6 +39,17 @@ npm create @lexibase/rdx@latest my-docs -- --skip-install
 `.rdx/`. Otherwise the creator uses the invoking package manager and prepares
 the runtime. Follow the commands printed by the generator.
 
+The creator reports file creation, dependency installation, and runtime preparation
+as separate stages, with elapsed time and periodic activity messages during long
+operations. During pnpm installation, RDX shows a rotating activity indicator and
+a bar based on the number of packages linked. Resolution, cache and download
+counts come from pnpm's structured logs; the bar waits for a known package total.
+Warnings, errors and lifecycle output remain visible. Logs without a terminal use
+plain status lines instead of animation. npm and Yarn retain their native output.
+npm and pnpm projects
+prepare using their installed RDX executable directly; Yarn provides its project
+execution environment for Plug'n'Play compatibility.
+
 ## Recovery
 
 In a pnpm workspace, installation uses the workspace's existing dependencies and

package/bin/index.js

@@ -9,6 +9,9 @@ import prompts from 'prompts'
 
 import { parseArguments, validateProjectName } from './options.mjs'
 import { normalizePnpmRdxApprovals } from './pnpm-policy.mjs'
+import { installedRuntime } from './installed-runtime.mjs'
+import { runStep } from './progress.mjs'
+import { createPnpmProgress } from './pnpm-progress.mjs'
 
 function getPackageManager() {
   const userAgent = process.env.npm_config_user_agent || ''
@@ -19,7 +22,7 @@ function getPackageManager() {
   return 'npm'
 }
 
-function run(command, args, cwd) {
+function run(command, args, cwd, label = `${command} ${args.join(' ')}`) {
   return new Promise((resolve, reject) => {
     // Reuse the Node entry point when available. Otherwise cross-spawn
     // resolves Windows command shims and escapes their arguments.
@@ -30,15 +33,29 @@ function run(command, args, cwd) {
       /\.[cm]?js$/i.test(packageManagerEntry)
     const executable = useNodeEntry ? process.execPath : command
     const commandArgs = useNodeEntry ? [packageManagerEntry, ...args] : args
+    const progress =
+      command === 'pnpm' && args[0] === 'install'
+        ? createPnpmProgress()
+        : undefined
+    if (progress) commandArgs.push('--reporter=ndjson')
     const child = spawn(executable, commandArgs, {
       cwd,
-      stdio: 'inherit',
+      stdio: progress ? ['inherit', 'pipe', 'pipe'] : 'inherit',
+      windowsHide: true,
     })
 
-    child.on('error', reject)
-    child.on('exit', (code) => {
+    if (progress) {
+      child.stdout.setEncoding('utf8').on('data', progress.stdout)
+      child.stderr.setEncoding('utf8').on('data', progress.stderr)
+    }
+    child.on('error', (error) => {
+      progress?.finish(false)
+      reject(error)
+    })
+    child.on('close', (code) => {
+      progress?.finish(code === 0)
       if (code === 0) resolve()
-      else reject(new Error(`${command} ${args.join(' ')} exited with ${code}`))
+      else reject(new Error(`${label} exited with ${code}`))
     })
   })
 }
@@ -93,73 +110,93 @@ async function main() {
   if (relativeTarget.startsWith('..') || path.isAbsolute(relativeTarget)) {
     throw new Error('Project must be created inside the current directory.')
   }
-  try {
-    await fs.mkdir(targetDir)
-  } catch (error) {
-    if (error.code === 'EEXIST')
-      throw new Error(
-        `The path "${projectName}" already exists. Choose another name; existing files are never overwritten.`
+  await runStep(
+    `[1/${skipInstall ? 1 : 3}] Creating project files...`,
+    async () => {
+      try {
+        await fs.mkdir(targetDir)
+      } catch (error) {
+        if (error.code === 'EEXIST')
+          throw new Error(
+            `The path "${projectName}" already exists. Choose another name; existing files are never overwritten.`
+          )
+        throw error
+      }
+
+      const currentFile = fileURLToPath(import.meta.url)
+      const templateDir = path.resolve(
+        path.dirname(currentFile),
+        '../templates/default'
+      )
+      await fs.copy(templateDir, targetDir, {
+        errorOnExist: true,
+        overwrite: false,
+      })
+      await fs.ensureDir(path.join(targetDir, 'public'))
+
+      const configPath = path.join(targetDir, 'rdx.config.ts')
+      const config = await fs.readFile(configPath, 'utf8')
+      await fs.writeFile(
+        configPath,
+        config.replace(
+          'since: new Date().getFullYear(),',
+          `since: ${new Date().getFullYear()},`
+        )
       )
-    throw error
-  }
-
-  const currentFile = fileURLToPath(import.meta.url)
-  const templateDir = path.resolve(
-    path.dirname(currentFile),
-    '../templates/default'
-  )
-  await fs.copy(templateDir, targetDir, {
-    errorOnExist: true,
-    overwrite: false,
-  })
-  await fs.ensureDir(path.join(targetDir, 'public'))
-
-  const configPath = path.join(targetDir, 'rdx.config.ts')
-  const config = await fs.readFile(configPath, 'utf8')
-  await fs.writeFile(
-    configPath,
-    config.replace(
-      'since: new Date().getFullYear(),',
-      `since: ${new Date().getFullYear()},`
-    )
-  )
 
-  const gitignoreTemplatePath = path.join(targetDir, 'gitignore.template')
-  await fs.move(gitignoreTemplatePath, path.join(targetDir, '.gitignore'), {
-    overwrite: true,
-  })
-  await fs.remove(path.join(targetDir, 'gitignore'))
-  await fs.remove(path.join(targetDir, '.npmignore'))
-
-  const pkgPath = path.join(targetDir, 'package.json')
-  const pkg = await fs.readJson(pkgPath)
-  pkg.name = projectName.toLowerCase()
-  await fs.writeJson(pkgPath, pkg, { spaces: 2 })
-
-  const readmePath = path.join(targetDir, 'README.md')
-  const readme = await fs.readFile(readmePath, 'utf8')
-  await fs.writeFile(
-    readmePath,
-    readme
-      .replaceAll('{{RDX_PROJECT_NAME}}', projectName)
-      .replaceAll('__RDX_PROJECT_NAME__', projectName)
+      const gitignoreTemplatePath = path.join(targetDir, 'gitignore.template')
+      await fs.move(gitignoreTemplatePath, path.join(targetDir, '.gitignore'), {
+        overwrite: true,
+      })
+      await fs.remove(path.join(targetDir, 'gitignore'))
+      await fs.remove(path.join(targetDir, '.npmignore'))
+
+      const pkgPath = path.join(targetDir, 'package.json')
+      const pkg = await fs.readJson(pkgPath)
+      pkg.name = projectName.toLowerCase()
+      await fs.writeJson(pkgPath, pkg, { spaces: 2 })
+
+      const readmePath = path.join(targetDir, 'README.md')
+      const readme = await fs.readFile(readmePath, 'utf8')
+      await fs.writeFile(
+        readmePath,
+        readme
+          .replaceAll('{{RDX_PROJECT_NAME}}', projectName)
+          .replaceAll('__RDX_PROJECT_NAME__', projectName)
+      )
+    }
   )
 
   const packageManager = getPackageManager()
 
   if (!skipInstall) {
     try {
-      console.log(`\nInstalling dependencies with ${packageManager}...\n`)
-      if (packageManager === 'pnpm')
-        await normalizePnpmRdxApprovals(targetDir)
-      await run(packageManager, ['install'], targetDir)
-      if (packageManager === 'pnpm')
-        await normalizePnpmRdxApprovals(targetDir)
-      const prepareArgs =
-        packageManager === 'npm'
-          ? ['exec', '--', 'rdx', 'prepare']
-          : ['exec', 'rdx', 'prepare']
-      await run(packageManager, prepareArgs, targetDir)
+      await runStep(
+        `[2/3] Installing dependencies with ${packageManager}...`,
+        async () => {
+          if (packageManager === 'pnpm')
+            await normalizePnpmRdxApprovals(targetDir)
+          await run(packageManager, ['install'], targetDir)
+          if (packageManager === 'pnpm')
+            await normalizePnpmRdxApprovals(targetDir)
+        },
+        { intervalMs: packageManager === 'pnpm' ? 0 : 15_000 }
+      )
+      await runStep('[3/3] Preparing RDX...', async () => {
+        if (packageManager === 'yarn') {
+          // Yarn provides the project's Plug'n'Play loader when needed.
+          await run(packageManager, ['exec', 'rdx', 'prepare'], targetDir)
+        } else {
+          // Avoid another package-manager startup and automatic install check.
+          const executable = await installedRuntime(targetDir)
+          await run(
+            process.execPath,
+            [executable, 'prepare'],
+            targetDir,
+            'rdx prepare'
+          )
+        }
+      })
     } catch (error) {
       const runner = packageManager === 'npm' ? 'npm run' : packageManager
       throw new Error(

package/bin/installed-runtime.mjs

@@ -0,0 +1,32 @@
+import { createRequire } from 'node:module'
+import { readFile, stat } from 'node:fs/promises'
+import path from 'node:path'
+
+/** Resolve the framework installed in the new project, including hoisted workspaces. */
+export async function installedRuntime(directory) {
+  const require = createRequire(path.join(directory, 'package.json'))
+  let filename
+  try {
+    filename = require.resolve('@lexibase/rdx/package.json')
+  } catch {
+    throw new Error(
+      'Could not find @lexibase/rdx in the new project after installation.'
+    )
+  }
+  const manifest = JSON.parse(await readFile(filename, 'utf8'))
+  const entry =
+    typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.rdx
+  if (typeof entry !== 'string' || !entry)
+    throw new Error(
+      'The installed @lexibase/rdx package does not provide its rdx executable.'
+    )
+  const executable = path.resolve(path.dirname(filename), entry)
+  try {
+    if (!(await stat(executable)).isFile()) throw new Error()
+  } catch {
+    throw new Error(
+      'The installed RDX executable is missing. Run the package manager install command again.'
+    )
+  }
+  return executable
+}

package/bin/pnpm-progress.mjs

@@ -0,0 +1,193 @@
+import { performance } from 'node:perf_hooks'
+import process from 'node:process'
+
+/** Adapt pnpm's NDJSON logs; the bar measures package linking, not elapsed time. */
+export function createPnpmProgress({
+  output = process.stdout,
+  errors = process.stderr,
+  interactive = Boolean(output.isTTY) && process.env.TERM !== 'dumb',
+  intervalMs = 100,
+  heartbeatMs = 15_000,
+  now = () => performance.now(),
+} = {}) {
+  const started = now()
+  const counts = { resolved: 0, cached: 0, downloaded: 0, linked: 0 }
+  const statuses = {
+    resolved: 'resolved',
+    found_in_store: 'cached',
+    fetched: 'downloaded',
+    imported: 'linked',
+  }
+  const totals = new Map()
+  const seen = new Set()
+  let phase = 'Resolving dependencies'
+  let buffer = ''
+  let frame = 0
+  let finished = false
+  let promptOpen = false
+  let previousPhase
+  const elapsed = () => `${((now() - started) / 1000).toFixed(1)}s`
+  const clear = () => {
+    if (interactive) output.write('\r\x1b[2K')
+  }
+  function render() {
+    const total = totals.size
+      ? [...totals.values()].reduce((sum, value) => sum + value, 0)
+      : undefined
+    const width = output.columns || 100
+    const cells = width < 100 ? 10 : 16
+    const filled =
+      total > 0
+        ? Math.min(cells, Math.floor((counts.linked / total) * cells))
+        : 0
+    const bar = `[${'#'.repeat(filled)}${'-'.repeat(cells - filled)}]`
+    const packages =
+      total === undefined ? `${counts.linked}/?` : `${counts.linked}/${total}`
+    const detail = `${width >= 110 ? `resolved ${counts.resolved}, ` : ''}cached ${counts.cached}, downloaded ${counts.downloaded}`
+    const shortPhase = phase.split(' ')[0]
+    const text =
+      width < 70
+        ? `${packages} packages | ${elapsed()}`
+        : `${shortPhase} ${packages} | ${elapsed()} | ${detail}`
+    return `${['|', '/', '-', '\\'][frame++ % 4]} ${bar} ${text}`.slice(
+      0,
+      Math.max(1, width - 1)
+    )
+  }
+  function draw(force = false) {
+    if (finished || promptOpen) return
+    if (interactive) {
+      // pnpm emits many debug records per package. Paint on the timer instead
+      // of turning each record into terminal writes during large installations.
+      if (!force && intervalMs > 0 && previousPhase === phase) return
+      clear()
+      output.write(render())
+    } else if (force || previousPhase !== phase) {
+      output.write(
+        `[RDX] ${phase}: resolved ${counts.resolved}, cached ${counts.cached}, downloaded ${counts.downloaded}, linked ${counts.linked} (${elapsed()}).\n`
+      )
+    }
+    previousPhase = phase
+  }
+  function message(text, stream = output) {
+    if (!promptOpen) clear()
+    stream.write(text)
+    // Keep prompts without a newline visible and leave the cursor after them.
+    promptOpen = !text.endsWith('\n')
+    if (text.endsWith('\n')) draw(true)
+  }
+  function record(line) {
+    if (!line.trim()) {
+      if (promptOpen) message('\n')
+      return
+    }
+    let event
+    try {
+      event = JSON.parse(line)
+    } catch {
+      message(line + '\n')
+      return
+    }
+    if (
+      !event ||
+      typeof event !== 'object' ||
+      typeof event.name !== 'string' ||
+      !(event.name === 'pnpm' || event.name.startsWith('pnpm:'))
+    ) {
+      message(line + '\n')
+      return
+    }
+    if (promptOpen) {
+      output.write('\n')
+      promptOpen = false
+    }
+    if (
+      event.name === 'pnpm:progress' &&
+      Object.hasOwn(statuses, event.status)
+    ) {
+      const key = statuses[event.status]
+      const id = event.to || event.packageId
+      const identity = id && JSON.stringify([event.requester, event.status, id])
+      if (!identity || !seen.has(identity)) {
+        counts[key]++
+        if (identity) seen.add(identity)
+      }
+      if (key === 'linked') phase = 'Linking packages'
+    } else if (
+      event.name === 'pnpm:fetching-progress' &&
+      event.status === 'started' &&
+      event.size >= 1024 * 1024
+    ) {
+      message(
+        `[RDX] Downloading ${event.packageId} (${(event.size / 1024 / 1024).toFixed(1)} MB).\n`
+      )
+    } else if (event.name === 'pnpm:stats' && Number.isFinite(event.added)) {
+      totals.set(event.prefix || '', Math.max(0, event.added))
+    } else if (event.name === 'pnpm:stage') {
+      if (event.stage === 'importing_started') phase = 'Linking packages'
+      if (event.stage === 'importing_done') phase = 'Finalizing installation'
+    } else if (event.name === 'pnpm:lifecycle' && event.line) {
+      message(`[pnpm:${event.stage || 'script'}] ${event.line}\n`)
+    } else if (event.level === 'warn' || event.level === 'error') {
+      const error = event.err || event
+      const text = [
+        error.code,
+        error.message || event.message,
+        error.hint,
+        error.pkgsStack && JSON.stringify(error.pkgsStack),
+      ]
+        .filter(Boolean)
+        .join('\n')
+      message(`[pnpm] ${text || JSON.stringify(event)}\n`, errors)
+    } else if (event.name === 'pnpm:peer-dependency-issues') {
+      message(
+        `[pnpm] Peer dependency issues:\n${JSON.stringify(event.issuesByProjects || event, null, 2)}\n`,
+        errors
+      )
+    } else if (event.level === 'info' && event.message) {
+      message(`[pnpm] ${event.message}\n`)
+    }
+    draw()
+  }
+  draw(true)
+  const timer =
+    intervalMs > 0
+      ? setInterval(() => draw(true), interactive ? intervalMs : heartbeatMs)
+      : undefined
+  timer?.unref()
+  return {
+    stdout(chunk) {
+      buffer += chunk
+      let end
+      while ((end = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, end).replace(/\r$/, '')
+        buffer = buffer.slice(end + 1)
+        record(line)
+      }
+      if (buffer && !buffer.trimStart().startsWith('{')) {
+        message(buffer)
+        buffer = ''
+      }
+    },
+    stderr(chunk) {
+      message(chunk, errors)
+    },
+    finish(success) {
+      if (finished) return
+      clearInterval(timer)
+      if (buffer) {
+        record(buffer)
+        buffer = ''
+      }
+      finished = true
+      if (promptOpen) {
+        output.write('\n')
+        promptOpen = false
+      }
+      clear()
+      output.write(
+        `[RDX] ${success ? 'Dependencies installed' : 'Installation stopped'}: ${counts.linked} linked, ${counts.cached} cached, ${counts.downloaded} downloaded (${elapsed()}).\n`
+      )
+    },
+  }
+}

package/bin/progress.mjs

@@ -0,0 +1,26 @@
+import { performance } from 'node:perf_hooks'
+
+/** Show real stage timings while preserving the installer's own terminal output. */
+export async function runStep(
+  label,
+  operation,
+  { log = console.log, intervalMs = 15_000 } = {}
+) {
+  const started = performance.now()
+  const elapsed = () => ((performance.now() - started) / 1000).toFixed(1)
+  log(`\n${label}`)
+  const timer =
+    intervalMs > 0
+      ? setInterval(() => {
+          log(`[RDX] ${label} (${elapsed()}s elapsed)`)
+        }, intervalMs)
+      : undefined
+  timer?.unref()
+  try {
+    const result = await operation()
+    log(`[RDX] Completed in ${elapsed()}s.`)
+    return result
+  } finally {
+    clearInterval(timer)
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexibase/create-rdx",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "description": "Create a new RDX documentation project.",
   "license": "MIT",
   "bin": {

package/templates/default/README.md

@@ -51,7 +51,8 @@ public/images/rdx.svg        → /images/rdx.svg
 public/downloads/example.txt → /downloads/example.txt
 ```
 
-Use site-root URLs in MDX:
+Write pages as `.md` or `.mdx` inside `docs/`. Both formats support RDX's
+Markdown components. Use site-root URLs for assets:
 
 ```md
 ![RDX logo](/images/rdx.svg)

package/templates/default/docs/init/intro.mdx

@@ -6,5 +6,5 @@ link_position: 1
 
 # Welcome to your documentation
 
-RDX turns folders and `.mdx` files into a documentation site. Start by editing
+RDX turns folders and `.md` or `.mdx` files into a documentation site. Start by editing
 this page or adding new pages inside `docs/`.

package/templates/default/package.json

@@ -9,7 +9,7 @@
     "start": "rdx start"
   },
   "dependencies": {
-    "@lexibase/rdx": "4.1.0",
+    "@lexibase/rdx": "4.2.1",
     "next": "^16.4.2",
     "react": "19.3.1",
     "react-dom": "19.3.1"

package/templates/default/rdx.config.ts

@@ -32,7 +32,8 @@ export default defineConfig({
   // Optional navbar text does not change metadata.applicationName.
   navbar: {
     title: '', // Text beside the logo; empty or omitted shows only the logo.
-    // logo: Logo, // Import a React component that accepts className, not an image path.
+    // logo: '/images/logo.png', // File in public/images/; PNG, SVG and other image formats work.
+    // Or import your components/logo.tsx and set logo: Logo.
     actions: {
       github: {
         visible: true,