@inovus-medical/docs 0.8.0 → 0.9.0

package/README.md

@@ -17,22 +17,24 @@ npm install --save-dev @inovus-medical/docs
 Put markdown in `docs/`, add a `docs.config.json`, then:
 
 ```bash
-npx inovus-docs build    # docs/ -> dist/
+npx inovus-docs build    # content -> dist/ (or --out dist-docs)
 npx inovus-docs dev      # build + serve + watch (http://localhost:8788)
 npx inovus-docs serve    # serve an existing dist/
+npx inovus-docs init     # scaffold into the current repo (safe in app repos)
 ```
 
 Flags: `--root <dir>` `--in <docs>` `--out <dist>` `--port <n>` `--theme <name>`.
+`init` also accepts `--content <dir>` and merges without overwriting app `build` scripts.
 
 ## Themes
 
-Named themes each include light and dark variants. Built-ins: `default`, `totum`.
+Named themes each include light and dark variants. Built-ins: `totum` (default), `default`.
 
 Selection (first match wins): `--theme` > `DOCS_THEME` env var > `"theme"` in
-`docs.config.json` > `default`. On Cloudflare, set `DOCS_THEME` under Worker →
+`docs.config.json` > `totum`. On Cloudflare, set `DOCS_THEME` under Worker →
 **Settings → Build → Variables** (build-time).
 
-Local preview: `npx inovus-docs dev --theme totum`.
+Local preview: `npx inovus-docs dev` (Totum) or `--theme default`.
 
 ## What it does
 

package/bin/cli.js

@@ -35,18 +35,39 @@ const theme = typeof flags.theme === 'string' ? flags.theme : undefined
 
 async function run() {
   if (cmd === 'init') {
-    const { created, skipped, name, title, visibility, repoUrl, home } = await init({ root, flags })
-    console.log(`Scaffolded "${title}" (worker: ${name}, ${visibility})${repoUrl ? ` — ${repoUrl}` : ''}`)
+    const result = await init({ root, flags })
+    const {
+      created,
+      skipped,
+      notes,
+      name,
+      title,
+      visibility,
+      repoUrl,
+      home,
+      content,
+      buildCommand,
+      deployCommand,
+      coexisting
+    } = result
+    console.log(
+      `Scaffolded "${title}" (worker: ${name}, ${visibility})${repoUrl ? ` — ${repoUrl}` : ''}`
+    )
+    if (content && content !== '.') console.log(`  content: ${content}/`)
+    if (coexisting) console.log('  mode: coexisting with existing package.json (docs scripts are docs:*)')
     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)
     if (!home) {
-      console.log('  ⚠ No home page (README.md / index.md) and --no-readme set — the site will have no page at /.')
+      console.log(
+        '  ⚠ No home page (README.md / index.md) in the content folder — add one or the site will have no page at /.'
+      )
     }
     console.log('\nNext:')
     console.log('  npm install')
-    console.log('  npm run dev        # preview at http://localhost:8788')
+    console.log('  npm run docs:dev     # preview at http://localhost:8788')
     console.log('  git add -A && git commit -m "Add docs site config" && git push')
-    console.log('  then connect the repo in Cloudflare (build: npm install && npm run build)')
+    console.log(`  Cloudflare: build \`${buildCommand}\`, deploy \`${deployCommand}\``)
     return
   }
 

package/package.json

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

package/src/build.js

@@ -31,18 +31,18 @@ async function listThemes() {
 }
 
 /**
- * Resolve theme: CLI --theme > DOCS_THEME env > docs.config.json > "default".
- * Unknown names warn and fall back to default.
+ * Resolve theme: CLI --theme > DOCS_THEME env > docs.config.json > "totum".
+ * Unknown names warn and fall back to totum.
  */
 async function resolveTheme({ themeFlag, config }) {
-  const raw = themeFlag ?? process.env.DOCS_THEME ?? config.theme ?? 'default'
-  const name = String(raw).trim().toLowerCase() || 'default'
+  const raw = themeFlag ?? process.env.DOCS_THEME ?? config.theme ?? 'totum'
+  const name = String(raw).trim().toLowerCase() || 'totum'
   const available = await listThemes()
   if (!available.has(name)) {
     console.warn(
-      `⚠ Unknown theme "${name}" — falling back to default. Available: ${[...available].sort().join(', ')}`
+      `⚠ Unknown theme "${name}" — falling back to totum. Available: ${[...available].sort().join(', ')}`
     )
-    return 'default'
+    return 'totum'
   }
   return name
 }

package/src/config.js

@@ -5,10 +5,10 @@ const DEFAULTS = {
   title: 'Documentation',
   description: '',
   logo: null,
-  // null = use the theme's accent (base styles.css sets --accent for default).
+  // null = use the theme's accent (theme CSS / base styles set --accent).
   accent: null,
   // Named theme (each has light + dark). Overridden by DOCS_THEME / --theme.
-  theme: 'default',
+  theme: 'totum',
   repo: null,
   editBase: null,
   visibility: 'private',

package/src/init.js

@@ -6,11 +6,18 @@ import { execSync } from 'node:child_process'
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 async function fileExists(p) {
-  try { await fs.access(p); return true } catch { return false }
+  try {
+    await fs.access(p)
+    return true
+  } catch {
+    return false
+  }
 }
 
 async function readJsonIfExists(file) {
-  try { return JSON.parse(await fs.readFile(file, 'utf8')) } catch (e) {
+  try {
+    return JSON.parse(await fs.readFile(file, 'utf8'))
+  } catch (e) {
     if (e.code === 'ENOENT') return null
     throw e
   }
@@ -18,10 +25,14 @@ async function readJsonIfExists(file) {
 
 function gitRemote(root) {
   try {
-    return execSync('git config --get remote.origin.url', {
-      cwd: root,
-      stdio: ['ignore', 'pipe', 'ignore']
-    }).toString().trim() || null
+    return (
+      execSync('git config --get remote.origin.url', {
+        cwd: root,
+        stdio: ['ignore', 'pipe', 'ignore']
+      })
+        .toString()
+        .trim() || null
+    )
   } catch {
     return null
   }
@@ -44,35 +55,44 @@ function parseRemote(url) {
 
 function sanitizeName(s) {
   return (
-    String(s).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 54) ||
-    'docs-site'
+    String(s)
+      .toLowerCase()
+      .replace(/[^a-z0-9-]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 54) || 'docs-site'
   )
 }
 
 function titleCase(s) {
-  return String(s).replace(/[-_]/g, ' ').replace(/\s+/g, ' ').trim().replace(/\b\w/g, (c) => c.toUpperCase())
+  return String(s)
+    .replace(/[-_]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, (c) => c.toUpperCase())
 }
 
-const WRANGLER = (name) => `{
+const WRANGLER = (name, outDir) => `{
   "$schema": "node_modules/wrangler/config-schema.json",
   "name": "${name}",
   "compatibility_date": "2025-06-01",
   "assets": {
-    "directory": "./dist",
+    "directory": "./${outDir}",
     "html_handling": "auto-trailing-slash",
     "not_found_handling": "404-page"
   }
 }
 `
 
-async function ensureGitignore(root, created) {
+async function ensureGitignore(root, entries, created) {
   const file = path.join(root, '.gitignore')
   let body = ''
-  try { body = await fs.readFile(file, 'utf8') } catch {}
+  try {
+    body = await fs.readFile(file, 'utf8')
+  } catch {}
   const present = new Set(body.split(/\r?\n/).map((l) => l.trim()))
   let next = body
   let changed = false
-  for (const entry of ['node_modules/', 'dist/']) {
+  for (const entry of entries) {
     if (!present.has(entry)) {
       next += (next && !next.endsWith('\n') ? '\n' : '') + entry + '\n'
       changed = true
@@ -84,9 +104,10 @@ async function ensureGitignore(root, created) {
   }
 }
 
-async function hasHomePage(root) {
-  const candidates = ['README.md', 'readme.md', 'index.md', 'docs/README.md', 'docs/index.md']
-  for (const c of candidates) if (await fileExists(path.join(root, c))) return true
+async function hasHomePageIn(dir) {
+  for (const c of ['README.md', 'readme.md', 'index.md']) {
+    if (await fileExists(path.join(dir, c))) return true
+  }
   return false
 }
 
@@ -96,82 +117,154 @@ function starterReadme(title) {
 Welcome to the ${title} documentation.
 
 This is the home page of your docs site. Edit this \`README.md\` to change it, and add
-more \`.md\` files anywhere in the repo — they show up in the sidebar automatically.
+more \`.md\` files alongside it — they show up in the sidebar automatically.
 `
 }
 
-/** Scaffold the per-repo files needed to publish a markdown repo as a docs site. */
+/**
+ * Scaffold the per-repo files needed to publish markdown as a docs site.
+ * Designed to co-exist with normal app repos: never overwrites app build/dev scripts,
+ * avoids clobbering an existing Wrangler config, and uses a separate output dir when needed.
+ */
 export async function init({ root = process.cwd(), flags = {} } = {}) {
   const enginePkg = JSON.parse(await fs.readFile(path.join(__dirname, '..', 'package.json'), 'utf8'))
   const engineVersion = `^${enginePkg.version}`
 
   const remote = parseRemote(gitRemote(root))
   const folder = path.basename(root)
-  const name = sanitizeName(flags.name || remote.repo || folder)
-  const title = flags.title || titleCase(remote.repo || folder)
+  const existingPkg = await readJsonIfExists(path.join(root, 'package.json'))
+  const coexisting = Boolean(existingPkg)
+  const baseName = remote.repo || folder
+  const name = sanitizeName(flags.name || (coexisting ? `${baseName}-docs` : baseName))
+  const title = flags.title || titleCase(baseName)
   const visibility = flags.public ? 'public' : 'private'
   const repoUrl = flags.repo || remote.httpsUrl || null
   const force = flags.force === true
+
   // Content root: --content <dir>, else auto-set "docs" when docs/ exists, else omit (auto-detect at build).
   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.
+  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}`
+
+  const hasAppWrangler =
+    (await fileExists(path.join(root, 'wrangler.jsonc'))) ||
+    (await fileExists(path.join(root, 'wrangler.toml'))) ||
+    (await fileExists(path.join(root, 'wrangler.json')))
+  const wranglerFile = coexisting && hasAppWrangler ? 'wrangler.docs.jsonc' : 'wrangler.jsonc'
+
   const created = []
   const skipped = []
+  const notes = []
 
   // docs.config.json (don't clobber existing unless --force)
   const cfgPath = path.join(root, 'docs.config.json')
   if ((await fileExists(cfgPath)) && !force) {
     skipped.push('docs.config.json')
   } else {
-    const cfg = { title, description: '', visibility }
+    const cfg = { title, description: '', visibility, theme: 'totum' }
     if (repoUrl) cfg.repo = repoUrl
     if (content) cfg.content = content
     await fs.writeFile(cfgPath, JSON.stringify(cfg, null, 2) + '\n')
     created.push('docs.config.json')
   }
 
-  // wrangler.jsonc
-  const wranglerPath = path.join(root, 'wrangler.jsonc')
+  // Wrangler config — never overwrite an app's wrangler unless --force on wrangler.jsonc path
+  const wranglerPath = path.join(root, wranglerFile)
   if ((await fileExists(wranglerPath)) && !force) {
-    skipped.push('wrangler.jsonc')
+    skipped.push(wranglerFile)
   } else {
-    await fs.writeFile(wranglerPath, WRANGLER(name))
-    created.push('wrangler.jsonc')
+    await fs.writeFile(wranglerPath, WRANGLER(name, outDir))
+    created.push(wranglerFile)
+    if (wranglerFile !== 'wrangler.jsonc') {
+      notes.push(
+        `App Wrangler config left alone; docs deploy uses: npx wrangler deploy -c ${wranglerFile}`
+      )
+    }
   }
 
-  // package.json (merge if present — never remove existing fields)
+  // package.json — merge only; never replace existing build/dev
   const pkgPath = path.join(root, 'package.json')
-  const existingPkg = await readJsonIfExists(pkgPath)
-  const pkg = existingPkg || { name, private: true }
-  pkg.scripts = pkg.scripts || {}
-  if (!pkg.scripts.build) pkg.scripts.build = 'inovus-docs build'
-  if (!pkg.scripts.dev) pkg.scripts.dev = 'inovus-docs dev'
-  pkg.devDependencies = pkg.devDependencies || {}
+  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).
+  if (!pkg.scripts.build) {
+    pkg.scripts.build = 'npm run docs:build'
+  } else {
+    notes.push(
+      `Left existing "build" script alone. Cloudflare build command should be: npm install && npm run docs:build`
+    )
+  }
+  if (!pkg.scripts.dev) {
+    pkg.scripts.dev = 'npm run docs:dev'
+  }
+  if (wranglerFile !== 'wrangler.jsonc' && !pkg.scripts['docs:deploy']) {
+    pkg.scripts['docs:deploy'] = `wrangler deploy -c ${wranglerFile}`
+  }
+  pkg.devDependencies = { ...(pkg.devDependencies || {}) }
   pkg.devDependencies[enginePkg.name] = engineVersion
+  if (!pkg.devDependencies.wrangler) {
+    pkg.devDependencies.wrangler = '^4'
+  }
   await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
   created.push(existingPkg ? 'package.json (updated)' : 'package.json')
 
-  // .node-version for Cloudflare's build image (Wrangler needs Node 22)
+  // .node-version — only for greenfield docs repos (apps often pin their own Node).
   const nodeVerPath = path.join(root, '.node-version')
-  if (!(await fileExists(nodeVerPath))) {
+  if (!coexisting && !(await fileExists(nodeVerPath))) {
     await fs.writeFile(nodeVerPath, '22\n')
     created.push('.node-version')
+  } else if (coexisting && !(await fileExists(nodeVerPath))) {
+    notes.push('Set Node 22 in the Cloudflare Worker build settings (Wrangler requires it).')
   }
 
-  await ensureGitignore(root, created)
+  const ignore = ['node_modules/', `${outDir}/`]
+  await ensureGitignore(root, ignore, created)
 
-  // Guarantee a landing page: if the repo has no README/index anywhere, drop a starter.
-  let home = await hasHomePage(root)
+  // Home page inside the content root (never invent a root README over an app's README).
+  const contentRel = content || '.'
+  const contentRoot = path.join(root, contentRel)
+  let home = await hasHomePageIn(contentRoot)
   if (!home && !flags['no-readme']) {
-    const inDocsMode = await fileExists(path.join(root, 'docs'))
-    const rel = inDocsMode ? path.join('docs', 'README.md') : 'README.md'
-    const readmePath = path.join(root, rel)
+    await fs.mkdir(contentRoot, { recursive: true })
+    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 })
-    await fs.writeFile(readmePath, starterReadme(title))
-    created.push(rel.split(path.sep).join('/'))
-    home = 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('/'))
+      home = true
+    } else {
+      home = true
+    }
   }
 
-  return { created, skipped, name, title, visibility, repoUrl, home }
+  const buildCommand = 'npm install && npm run docs:build'
+  const deployCommand =
+    wranglerFile === 'wrangler.jsonc'
+      ? 'npx wrangler deploy'
+      : `npx wrangler deploy -c ${wranglerFile}`
+
+  return {
+    created,
+    skipped,
+    notes,
+    name,
+    title,
+    visibility,
+    repoUrl,
+    home,
+    content: contentRel,
+    outDir,
+    wranglerFile,
+    buildCommand,
+    deployCommand,
+    coexisting
+  }
 }

package/src/layout.js

@@ -74,7 +74,7 @@ function header(config) {
 
 function shell({ config, pageTitle, description, navHtml, main }) {
   const accent = config.accent ? `<style>:root{--accent:${esc(config.accent)}}</style>` : ''
-  const docsTheme = (config.theme && config.theme !== 'default') ? config.theme : 'default'
+  const docsTheme = config.theme || 'totum'
   const themeLink =
     docsTheme !== 'default' ? '<link rel="stylesheet" href="/_assets/theme.css">\n' : ''
   const desc = description || config.description || ''