@inovus-medical/docs 0.9.0 → 0.10.0

package/bin/cli.js

@@ -29,7 +29,7 @@ const flags = parseFlags(cmd === argv[0] ? argv.slice(1) : argv)
 
 const root = path.resolve(flags.root || process.cwd())
 const inDir = flags.in // undefined -> build() auto-detects (docs/ or repo root)
-const outDir = flags.out || 'dist'
+const outDirFlag = typeof flags.out === 'string' ? flags.out : undefined
 const port = Number(flags.port || 8788)
 const theme = typeof flags.theme === 'string' ? flags.theme : undefined
 
@@ -48,6 +48,9 @@ async function run() {
       content,
       buildCommand,
       deployCommand,
+      localInstall,
+      localDev,
+      packageManager,
       coexisting
     } = result
     console.log(
@@ -55,6 +58,7 @@ async function run() {
     )
     if (content && content !== '.') console.log(`  content: ${content}/`)
     if (coexisting) console.log('  mode: coexisting with existing package.json (docs scripts are docs:*)')
+    if (packageManager) console.log(`  package manager: ${packageManager}`)
     if (created.length) console.log('  created: ' + created.join(', '))
     if (skipped.length) console.log('  kept existing (use --force to overwrite): ' + skipped.join(', '))
     for (const n of notes || []) console.log('  ⚠ ' + n)
@@ -64,21 +68,36 @@ async function run() {
       )
     }
     console.log('\nNext:')
-    console.log('  npm install')
-    console.log('  npm run docs:dev     # preview at http://localhost:8788')
+    console.log(`  ${localInstall}`)
+    console.log(`  ${localDev}     # preview at http://localhost:8788`)
     console.log('  git add -A && git commit -m "Add docs site config" && git push')
-    console.log(`  Cloudflare: build \`${buildCommand}\`, deploy \`${deployCommand}\``)
+    console.log('  (Commit the lockfile too — Cloudflare installs with --frozen-lockfile.)')
+    console.log('\nCloudflare Worker (same for every repo — copy exactly):')
+    console.log(`  Build command:  ${buildCommand}`)
+    console.log(`  Deploy command: ${deployCommand}`)
     return
   }
 
   if (cmd === 'build') {
-    const { pageCount, outPath, contentDir } = await build({ root, inDir, outDir, theme })
-    console.log(`✓ Built ${pageCount} page(s) from ${contentDir === '.' ? 'repo root' : contentDir + '/'} -> ${path.relative(process.cwd(), outPath) || outPath}`)
+    const { pageCount, outPath, contentDir, outDir } = await build({
+      root,
+      inDir,
+      outDir: outDirFlag,
+      theme
+    })
+    console.log(
+      `✓ Built ${pageCount} page(s) from ${contentDir === '.' ? 'repo root' : contentDir + '/'} -> ${path.relative(process.cwd(), outPath) || outDir}`
+    )
     return
   }
 
   if (cmd === 'dev') {
-    const { pageCount, outPath, contentDir } = await build({ root, inDir, outDir, theme })
+    const { pageCount, outPath, contentDir, outDir } = await build({
+      root,
+      inDir,
+      outDir: outDirFlag,
+      theme
+    })
     console.log(`✓ Built ${pageCount} page(s) from ${contentDir === '.' ? 'repo root' : contentDir + '/'}`)
     const { port: actual } = await serve({ dir: outPath, port })
     const busy = actual !== port ? `  (port ${port} was busy)` : ''
@@ -88,6 +107,9 @@ async function run() {
   }
 
   if (cmd === 'serve') {
+    const { loadConfig } = await import('../src/config.js')
+    const config = await loadConfig(root)
+    const outDir = outDirFlag || config.outDir || 'dist'
     const outPath = path.join(root, outDir)
     const { port: actual } = await serve({ dir: outPath, port })
     const busy = actual !== port ? `  (port ${port} was busy)` : ''

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inovus-medical/docs",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Turn a folder of markdown into a themed, Cloudflare-ready docs site.",
   "type": "module",
   "bin": {

package/src/build.js

@@ -119,11 +119,12 @@ function routeToFile(outPath, route) {
   return path.join(outPath, rel, 'index.html')
 }
 
-export async function build({ root = process.cwd(), inDir, outDir = 'dist', theme: themeFlag } = {}) {
+export async function build({ root = process.cwd(), inDir, outDir, theme: themeFlag } = {}) {
   const config = await loadConfig(root)
   const theme = await resolveTheme({ themeFlag, config })
   config.theme = theme
-  const outPath = path.join(root, outDir)
+  const resolvedOut = outDir || config.outDir || 'dist'
+  const outPath = path.join(root, resolvedOut)
   const ignore = makeIgnore(config, path.basename(outPath))
 
   const contentDir = await resolveContentDir({ root, inDir, config, ignore })
@@ -235,5 +236,5 @@ export async function build({ root = process.cwd(), inDir, outDir = 'dist', them
     await fs.copyFile(file, dest)
   }
 
-  return { pageCount: pages.length, outPath, contentDir }
+  return { pageCount: pages.length, outPath, contentDir, outDir: resolvedOut }
 }

package/src/config.js

@@ -9,6 +9,8 @@ const DEFAULTS = {
   accent: null,
   // Named theme (each has light + dark). Overridden by DOCS_THEME / --theme.
   theme: 'totum',
+  // Build output directory. null → "dist". App repos usually use "dist-docs".
+  outDir: null,
   repo: null,
   editBase: null,
   visibility: 'private',

package/src/init.js

@@ -71,6 +71,34 @@ function titleCase(s) {
     .replace(/\b\w/g, (c) => c.toUpperCase())
 }
 
+/**
+ * Detect the repo's package manager from lockfiles / packageManager field.
+ * Cloudflare Workers Builds does the same (pnpm/yarn/npm from lockfile).
+ */
+async function detectPackageManager(root, pkg) {
+  if (await fileExists(path.join(root, 'pnpm-lock.yaml'))) return 'pnpm'
+  if (await fileExists(path.join(root, 'yarn.lock'))) return 'yarn'
+  if (
+    (await fileExists(path.join(root, 'bun.lockb'))) ||
+    (await fileExists(path.join(root, 'bun.lock')))
+  ) {
+    return 'bun'
+  }
+  const field = pkg && typeof pkg.packageManager === 'string' ? pkg.packageManager : ''
+  if (field.startsWith('pnpm@')) return 'pnpm'
+  if (field.startsWith('yarn@')) return 'yarn'
+  if (field.startsWith('bun@')) return 'bun'
+  if (await fileExists(path.join(root, 'package-lock.json'))) return 'npm'
+  return 'npm'
+}
+
+function runScript(pm, script) {
+  if (pm === 'yarn') return `yarn ${script}`
+  if (pm === 'bun') return `bun run ${script}`
+  if (pm === 'pnpm') return `pnpm run ${script}`
+  return `npm run ${script}`
+}
+
 const WRANGLER = (name, outDir) => `{
   "$schema": "node_modules/wrangler/config-schema.json",
   "name": "${name}",
@@ -145,10 +173,13 @@ export async function init({ root = process.cwd(), flags = {} } = {}) {
   let content = typeof flags.content === 'string' ? flags.content.trim() : null
   if (!content && (await fileExists(path.join(root, 'docs')))) content = 'docs'
 
-  // App repos often already use dist/ and wrangler.jsonc — keep docs out of their way.
+  // App repos often already use dist/ — keep docs output out of the way via config.outDir.
   const outDir = coexisting ? 'dist-docs' : 'dist'
-  const buildScript = outDir === 'dist' ? 'inovus-docs build' : `inovus-docs build --out ${outDir}`
-  const devScript = outDir === 'dist' ? 'inovus-docs dev' : `inovus-docs dev --out ${outDir}`
+  // One Cloudflare build command for every repo (npm/pnpm/yarn). Reads docs.config.json.
+  const buildCommand = 'npx inovus-docs build'
+  const pm = await detectPackageManager(root, existingPkg)
+  const localInstall = pm === 'yarn' ? 'yarn' : pm === 'bun' ? 'bun install' : `${pm} install`
+  const localDev = runScript(pm, 'docs:dev')
 
   const hasAppWrangler =
     (await fileExists(path.join(root, 'wrangler.jsonc'))) ||
@@ -160,19 +191,39 @@ export async function init({ root = process.cwd(), flags = {} } = {}) {
   const skipped = []
   const notes = []
 
-  // docs.config.json (don't clobber existing unless --force)
+  // docs.config.json — create or merge additive fields (never wipe an existing file)
   const cfgPath = path.join(root, 'docs.config.json')
   if ((await fileExists(cfgPath)) && !force) {
-    skipped.push('docs.config.json')
+    const cfg = (await readJsonIfExists(cfgPath)) || {}
+    let changed = false
+    if (content && !cfg.content) {
+      cfg.content = content
+      changed = true
+    }
+    if (coexisting && !cfg.outDir) {
+      cfg.outDir = outDir
+      changed = true
+    }
+    if (!cfg.theme) {
+      cfg.theme = 'totum'
+      changed = true
+    }
+    if (changed) {
+      await fs.writeFile(cfgPath, JSON.stringify(cfg, null, 2) + '\n')
+      created.push('docs.config.json (updated)')
+    } else {
+      skipped.push('docs.config.json')
+    }
   } else {
     const cfg = { title, description: '', visibility, theme: 'totum' }
     if (repoUrl) cfg.repo = repoUrl
     if (content) cfg.content = content
+    if (outDir !== 'dist') cfg.outDir = outDir
     await fs.writeFile(cfgPath, JSON.stringify(cfg, null, 2) + '\n')
     created.push('docs.config.json')
   }
 
-  // Wrangler config — never overwrite an app's wrangler unless --force on wrangler.jsonc path
+  // Wrangler config — never overwrite an app's wrangler unless --force on our docs file
   const wranglerPath = path.join(root, wranglerFile)
   if ((await fileExists(wranglerPath)) && !force) {
     skipped.push(wranglerFile)
@@ -190,18 +241,18 @@ export async function init({ root = process.cwd(), flags = {} } = {}) {
   const pkgPath = path.join(root, 'package.json')
   const pkg = existingPkg ? { ...existingPkg } : { name, private: true }
   pkg.scripts = { ...(pkg.scripts || {}) }
-  pkg.scripts['docs:build'] = buildScript
-  pkg.scripts['docs:dev'] = devScript
-  // Convenience aliases only when the repo doesn't already define them (pure docs repos).
+  // Local convenience scripts (CF uses `npx inovus-docs build` — not these names).
+  pkg.scripts['docs:build'] = 'inovus-docs build'
+  pkg.scripts['docs:dev'] = 'inovus-docs dev'
   if (!pkg.scripts.build) {
-    pkg.scripts.build = 'npm run docs:build'
+    pkg.scripts.build = 'inovus-docs build'
   } else {
     notes.push(
-      `Left existing "build" script alone. Cloudflare build command should be: npm install && npm run docs:build`
+      `Left existing "build" script alone (app build). Cloudflare must use: ${buildCommand}`
     )
   }
   if (!pkg.scripts.dev) {
-    pkg.scripts.dev = 'npm run docs:dev'
+    pkg.scripts.dev = 'inovus-docs dev'
   }
   if (wranglerFile !== 'wrangler.jsonc' && !pkg.scripts['docs:deploy']) {
     pkg.scripts['docs:deploy'] = `wrangler deploy -c ${wranglerFile}`
@@ -214,6 +265,17 @@ export async function init({ root = process.cwd(), flags = {} } = {}) {
   await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
   created.push(existingPkg ? 'package.json (updated)' : 'package.json')
 
+  // Update the lockfile so Cloudflare --frozen-lockfile can install the engine.
+  try {
+    console.log(`Updating lockfile (${localInstall})…`)
+    execSync(localInstall, { cwd: root, stdio: 'inherit', shell: true })
+    created.push('lockfile (updated)')
+  } catch {
+    notes.push(
+      `Could not run "${localInstall}" automatically. Run it yourself and commit the lockfile before deploying.`
+    )
+  }
+
   // .node-version — only for greenfield docs repos (apps often pin their own Node).
   const nodeVerPath = path.join(root, '.node-version')
   if (!coexisting && !(await fileExists(nodeVerPath))) {
@@ -235,7 +297,6 @@ export async function init({ root = process.cwd(), flags = {} } = {}) {
     const rel = path.join(contentRel === '.' ? '' : contentRel, 'README.md').replace(/^\//, '')
     const readmePath = path.join(root, rel || 'README.md')
     await fs.mkdir(path.dirname(readmePath), { recursive: true })
-    // Don't overwrite an existing root README when content is "."
     if (!(await fileExists(readmePath))) {
       await fs.writeFile(readmePath, starterReadme(title))
       created.push((rel || 'README.md').split(path.sep).join('/'))
@@ -245,7 +306,6 @@ export async function init({ root = process.cwd(), flags = {} } = {}) {
     }
   }
 
-  const buildCommand = 'npm install && npm run docs:build'
   const deployCommand =
     wranglerFile === 'wrangler.jsonc'
       ? 'npx wrangler deploy'
@@ -265,6 +325,9 @@ export async function init({ root = process.cwd(), flags = {} } = {}) {
     wranglerFile,
     buildCommand,
     deployCommand,
+    localInstall,
+    localDev,
+    packageManager: pm,
     coexisting
   }
 }

package/src/watch.js

@@ -2,7 +2,7 @@ import { watch } from 'node:fs'
 import path from 'node:path'
 import { build } from './build.js'
 
-const IGNORED = /(^|[\\/])(node_modules|\.git|dist)([\\/]|$)/
+const IGNORED = /(^|[\\/])(node_modules|\.git|dist-docs|dist)([\\/]|$)/
 
 /**
  * Rebuild on any change under the content directory. Debounced so a burst of
@@ -12,7 +12,7 @@ const IGNORED = /(^|[\\/])(node_modules|\.git|dist)([\\/]|$)/
  */
 export function watchAndRebuild({ root, inDir, outDir, theme }) {
   const watchPath = inDir === '.' ? root : path.join(root, inDir)
-  const outBase = path.basename(outDir)
+  const outBase = path.basename(outDir || 'dist')
   let timer = null
   let building = false
 
@@ -23,7 +23,12 @@ export function watchAndRebuild({ root, inDir, outDir, theme }) {
       if (building) return
       building = true
       try {
-        const { pageCount } = await build({ root, inDir: inDir === '.' ? '.' : inDir, outDir, theme })
+        const { pageCount } = await build({
+          root,
+          inDir: inDir === '.' ? '.' : inDir,
+          outDir,
+          theme
+        })
         console.log(`↻ Rebuilt ${pageCount} page(s)`)
       } catch (err) {
         console.error('Build failed:', err.message)