@plutocms/docs 0.0.0-stage → 0.15.0

package/modules/pluto-docs/manifest.ts

@@ -0,0 +1,159 @@
+// The build manifest of the hybrid mode. Node code that runs at build time. It lists the
+// content files of each type with the version that the content store reports for the file
+// (`_version`). At run time the server compares the store with this list to see which pages
+// changed after the build. See the docs-setup skill.
+
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+import { readdirSync, readFileSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+
+/** Content id → version, for one type. */
+export type TypeManifest = Record<string, string>
+
+/** Type name → its manifest. */
+export type ContentManifest = Record<string, TypeManifest>
+
+/** The same dirs that the CMS fs store skips. */
+const SKIPPED_DIRS = new Set([
+  'node_modules',
+  '.nuxt',
+  '.output',
+  '.data',
+  '.nitro',
+  '.cache',
+  'dist',
+])
+const SEGMENT_PATTERN = /^(?:\d+\.)?[a-z0-9]+(?:-[a-z0-9]+)*$/
+const MAX_SEGMENTS = 6
+const MAX_ID_LENGTH = 255
+
+/** The Git blob id of a text: sha1 of `blob <byteLength>\0` and the UTF-8 bytes. Core does the same. */
+export function gitBlobSha(text: string): string {
+  const bytes = Buffer.from(text, 'utf8')
+  return createHash('sha1')
+    .update(`blob ${bytes.length}\0`)
+    .update(bytes)
+    .digest('hex')
+}
+
+/**
+ * The version of a file text for a storage.
+ *
+ * - `github`: the store reports the Git blob id. Git keeps LF in the blob, so a CRLF working file
+ *   (Windows with `core.autocrlf`) is hashed with LF. A file that really has CRLF in the repository
+ *   looks changed at run time. That is safe: the page then comes from the store.
+ * - `fs` (and `memory`): the store hashes the file as it is on the disk, so the manifest does too.
+ */
+export function versionOf(text: string, storage: string): string {
+  return gitBlobSha(storage === 'github' ? text.replace(/\r\n/g, '\n') : text)
+}
+
+/** Whether a content id is one that the CMS lists: 1 to 6 safe segments, and not excluded. */
+export function isListedId(
+  id: string,
+  exclude: readonly string[] = []
+): boolean {
+  if (id.length === 0 || id.length > MAX_ID_LENGTH) {
+    return false
+  }
+  const segments = id.split('/')
+  if (
+    segments.length > MAX_SEGMENTS ||
+    segments.some((segment) => !SEGMENT_PATTERN.test(segment))
+  ) {
+    return false
+  }
+  return !exclude.some((entry) =>
+    entry.endsWith('/') ? id.startsWith(entry) : id === entry
+  )
+}
+
+/** One file in memory: the path is relative to the type folder, with `/`. */
+export interface ManifestFile {
+  path: string
+  text: string
+}
+
+/** Builds the manifest of one type from its files. A file that is not a listed `.md` page is skipped. */
+export function buildTypeManifest(
+  files: ManifestFile[],
+  options: { storage: string; exclude?: readonly string[] }
+): TypeManifest {
+  const manifest: TypeManifest = {}
+  for (const file of [...files].sort((a, b) =>
+    a.path < b.path ? -1 : a.path > b.path ? 1 : 0
+  )) {
+    if (!file.path.endsWith('.md')) {
+      continue
+    }
+    const id = file.path.slice(0, -'.md'.length)
+    if (!isListedId(id, options.exclude)) {
+      continue
+    }
+    manifest[id] = versionOf(file.text, options.storage)
+  }
+  return manifest
+}
+
+function walkMarkdown(dir: string, out: string[]): void {
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) {
+      continue
+    }
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (!SKIPPED_DIRS.has(entry.name)) {
+        walkMarkdown(full, out)
+      }
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      out.push(full)
+    }
+  }
+}
+
+/** Reads the `.md` files under a type folder on the disk. A missing folder gives `[]`. */
+export function readTypeFiles(folder: string): ManifestFile[] {
+  const found: string[] = []
+  walkMarkdown(folder, found)
+  return found.map((full) => ({
+    path: relative(folder, full).split(sep).join('/'),
+    text: readFileSync(full, 'utf8'),
+  }))
+}
+
+export interface ManifestTypeInput {
+  name: string
+  /** The folder under the CMS content dir. `''` is the content dir itself. */
+  source: string
+  exclude?: string[]
+}
+
+/** Builds the manifest of every type. `contentDir` is the absolute path of the CMS content dir. */
+export function buildContentManifest(
+  types: ManifestTypeInput[],
+  options: { contentDir: string; storage: string }
+): ContentManifest {
+  const manifest: ContentManifest = {}
+  for (const type of types) {
+    const folder = type.source
+      ? join(options.contentDir, type.source)
+      : options.contentDir
+    manifest[type.name] = buildTypeManifest(readTypeFiles(folder), {
+      storage: options.storage,
+      exclude: type.exclude,
+    })
+  }
+  return manifest
+}
+
+/** The source of the virtual module that the server imports. */
+export function manifestModuleSource(manifest: ContentManifest): string {
+  return `export default ${JSON.stringify(manifest)}\n`
+}

package/modules/pluto-docs/options.ts

@@ -0,0 +1,224 @@
+/** One content type that the layer builds from a preset. */
+export interface PlutoDocsTypeOptions {
+  /** The preset that makes the type. Only `docs` exists. */
+  preset: 'docs'
+  /** The content type name. It is a URL segment: `/admin/content/<name>`. */
+  name: string
+  /**
+   * The folder of the pages, under the CMS content dir. Use `''` for the content
+   * dir itself (the usual case for a Nuxt Content site).
+   */
+  source: string
+  label?: string
+  labelPlural?: string
+  /** The Iconify name of the type in the admin (sidebar, New menu, dashboard). Default `lucide:book-open`. */
+  icon?: string
+  /** Ids that the type must not list or edit. An id (`index`), or a folder with a trailing slash (`drafts/`). */
+  exclude?: string[]
+  /** The route prefix of the pages on the public site, for the View link of the form. Default: none. */
+  routePrefix?: string
+  /**
+   * The nav group of the type in the admin sidebar and the admin bar. Default `'pages'` (core's
+   * group). A string is a group id. `false` gives the type its own sidebar item.
+   */
+  navGroup?: string | false
+}
+
+/** How the public pages get their content. See the docs-setup skill. */
+export type PlutoDocsRender = 'hybrid' | 'build' | 'runtime'
+
+export interface PlutoDocsOptions {
+  /** The content types to register. Default: none. */
+  types?: PlutoDocsTypeOptions[]
+  /**
+   * `'hybrid'` (default): the pages are built with the site, and the server reads from the content
+   * repository the pages that changed after the build. `'build'`: Nuxt Content builds the pages
+   * and nothing else. `'runtime'`: the server reads every page from the repository at request time.
+   */
+  render?: PlutoDocsRender
+  /**
+   * Seconds that a CDN may cache the answers of the layer routes (`hybrid` and `runtime`). Default 10.
+   * It is short, so a save shows soon. `0` turns the cache header into `no-store`.
+   */
+  runtimeMaxAge?: number
+}
+
+export interface PlutoDocsResolveContext {
+  /** False when the app sets `plutoGithub.enabled` to false. */
+  cmsEnabled: boolean
+}
+
+export interface PlutoDocsResolveResult {
+  enabled: boolean
+  render: PlutoDocsRender
+  runtimeMaxAge: number
+  types: PlutoDocsTypeOptions[]
+  errors: string[]
+}
+
+export const PLUTO_DOCS_PRESETS = ['docs'] as const
+export const PLUTO_DOCS_RENDER_MODES = ['hybrid', 'build', 'runtime'] as const
+export const DEFAULT_RUNTIME_MAX_AGE = 10
+
+export const CMS_OFF_ERROR =
+  'The docs layer needs the standalone CMS. Remove plutoGithub.enabled: false, or remove the layer.'
+
+const NAME_PATTERN = /^[a-z][a-z0-9-]*$/
+const SOURCE_SEGMENT = /^(?:\d+\.)?[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Whether `source` is `''` or a safe nested path (the same segment rule as the CMS). */
+export function isValidSource(source: unknown): source is string {
+  if (typeof source !== 'string') {
+    return false
+  }
+  if (source === '') {
+    return true
+  }
+  const segments = source.split('/')
+  return (
+    segments.length <= 6 &&
+    segments.every((segment) => SOURCE_SEGMENT.test(segment))
+  )
+}
+
+/** Normalizes a route prefix to `/a/b`, or `''` for none. */
+export function normalizeRoutePrefix(prefix: unknown): string {
+  if (typeof prefix !== 'string') {
+    return ''
+  }
+  const segments = prefix.split('/').filter(Boolean)
+  return segments.length > 0 ? `/${segments.join('/')}` : ''
+}
+
+/**
+ * Checks the module options. A type with a problem is dropped and gives one
+ * error. When the CMS is off, the layer is off and gives one error. This file
+ * has no Nuxt import, so plain Vitest tests it.
+ */
+export function resolvePlutoDocsOptions(
+  options: PlutoDocsOptions,
+  ctx: PlutoDocsResolveContext
+): PlutoDocsResolveResult {
+  const errors: string[] = []
+
+  if (!ctx.cmsEnabled) {
+    return {
+      enabled: false,
+      render: 'build',
+      runtimeMaxAge: DEFAULT_RUNTIME_MAX_AGE,
+      types: [],
+      errors: [CMS_OFF_ERROR],
+    }
+  }
+
+  let render: PlutoDocsRender = 'hybrid'
+  if (options.render !== undefined) {
+    if (
+      (PLUTO_DOCS_RENDER_MODES as readonly unknown[]).includes(options.render)
+    ) {
+      render = options.render
+    } else {
+      errors.push(
+        `plutoDocs.render must be one of: ${PLUTO_DOCS_RENDER_MODES.join(', ')}. Using "hybrid".`
+      )
+    }
+  }
+
+  let runtimeMaxAge = DEFAULT_RUNTIME_MAX_AGE
+  if (options.runtimeMaxAge !== undefined) {
+    if (
+      typeof options.runtimeMaxAge === 'number' &&
+      Number.isInteger(options.runtimeMaxAge) &&
+      options.runtimeMaxAge >= 0
+    ) {
+      runtimeMaxAge = options.runtimeMaxAge
+    } else {
+      errors.push(
+        `plutoDocs.runtimeMaxAge must be a whole number of seconds, 0 or more. Using ${DEFAULT_RUNTIME_MAX_AGE}.`
+      )
+    }
+  }
+
+  const types: PlutoDocsTypeOptions[] = []
+  const names = new Set<string>()
+  const entries: unknown[] = Array.isArray(options.types) ? options.types : []
+
+  for (const [index, entry] of entries.entries()) {
+    const where = `plutoDocs.types[${index}]`
+    if (!isRecord(entry)) {
+      errors.push(`${where} must be an object.`)
+      continue
+    }
+    if (!(PLUTO_DOCS_PRESETS as readonly unknown[]).includes(entry.preset)) {
+      errors.push(
+        `${where}.preset must be one of: ${PLUTO_DOCS_PRESETS.join(', ')}.`
+      )
+      continue
+    }
+    if (typeof entry.name !== 'string' || !NAME_PATTERN.test(entry.name)) {
+      errors.push(
+        `${where}.name must use lowercase letters, numbers and dashes, and start with a letter.`
+      )
+      continue
+    }
+    if (names.has(entry.name)) {
+      errors.push(`${where}.name "${entry.name}" is used twice.`)
+      continue
+    }
+    if (!isValidSource(entry.source)) {
+      errors.push(
+        `${where}.source must be '' or a folder path such as "docs" or "1.docs/api".`
+      )
+      continue
+    }
+    if (
+      entry.exclude !== undefined &&
+      !(
+        Array.isArray(entry.exclude) &&
+        entry.exclude.every((item) => typeof item === 'string')
+      )
+    ) {
+      errors.push(`${where}.exclude must be a list of strings.`)
+      continue
+    }
+    if (
+      entry.navGroup !== undefined &&
+      entry.navGroup !== false &&
+      !(typeof entry.navGroup === 'string' && entry.navGroup !== '')
+    ) {
+      errors.push(`${where}.navGroup must be a group id, or false.`)
+      continue
+    }
+    if (
+      entry.icon !== undefined &&
+      !(typeof entry.icon === 'string' && entry.icon !== '')
+    ) {
+      errors.push(`${where}.icon must be an icon name.`)
+      continue
+    }
+    names.add(entry.name)
+    types.push({
+      preset: 'docs',
+      name: entry.name,
+      source: entry.source,
+      ...(typeof entry.label === 'string' && { label: entry.label }),
+      ...(typeof entry.labelPlural === 'string' && {
+        labelPlural: entry.labelPlural,
+      }),
+      ...(typeof entry.icon === 'string' && { icon: entry.icon }),
+      ...(Array.isArray(entry.exclude) && {
+        exclude: entry.exclude as string[],
+      }),
+      routePrefix: normalizeRoutePrefix(entry.routePrefix),
+      ...((typeof entry.navGroup === 'string' || entry.navGroup === false) && {
+        navGroup: entry.navGroup,
+      }),
+    })
+  }
+
+  return { enabled: true, render, runtimeMaxAge, types, errors }
+}

package/nuxt.config.ts

@@ -0,0 +1,36 @@
+// Point PLUTO_CORE_PATH at a local checkout (e.g. `../pluto/packages/core`) to test
+// unpublished changes; unset, it resolves to the published npm package.
+const coreLayer = process.env.PLUTO_CORE_PATH || '@plutocms/core'
+
+export default defineNuxtConfig({
+  extends: [coreLayer],
+
+  modules: ['@nuxt/content'],
+
+  $meta: {
+    name: 'docs',
+  },
+
+  // Nuxt Content stores its data in SQLite. The native connector needs Node 22.5
+  // or newer and no extra package. An app can set another connector.
+  content: {
+    experimental: {
+      sqliteConnector: 'native',
+    },
+  },
+
+  // No `css` entry: the app owns the one Tailwind build, and Nuxt UI scans
+  // this layer's app/ dir. The tokens of this layer are in
+  // app/assets/css/pluto-layer.css. See the single-tailwind-build skill in pluto.
+
+  // The pages are Markdown files, so the fixed blog post type is off. A docs
+  // edit must redeploy the site, so the commit message has no `[skip ci]`
+  // marker by default. An app can change both. The other `plutoGithub` options
+  // have defaults in core (see the github-cms skill in pluto).
+  plutoGithub: {
+    postType: false,
+    commit: {
+      skipDeploy: false,
+    },
+  },
+})

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@plutocms/docs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.15.0",
+  "description": "Docs layer for Pluto: edit the Markdown pages of a Nuxt Content site in the Pluto admin",
+  "author": "Victor Ribeiro",
+  "license": "MIT",
+  "homepage": "https://github.com/plutocms/docs#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plutocms/docs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/plutocms/docs/issues"
+  },
+  "main": "./nuxt.config.ts",
+  "scripts": {
+    "prepare": "nuxt prepare",
+    "prettier": "prettier --write .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "nuxi typecheck",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@nuxt/content": "^3.16.2",
+    "@nuxtjs/mdc": "^0.23.2",
+    "@plutocms/core": ">=0.39.0 <1.0.0",
+    "@types/sortablejs": "^1.15.9",
+    "reka-ui": "^2.11.0",
+    "remark-gfm": "4.0.1",
+    "remark-mdc": "3.11.1",
+    "remark-parse": "11.0.0",
+    "sortablejs": "^1.15.7",
+    "unified": "11.0.5",
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^9.5.1",
+    "@nuxt/eslint-config": "^1.17.0",
+    "@nuxt/ui": "^4.12.0",
+    "@types/node": "^26.6.5",
+    "@vueuse/nuxt": "^15.0.0",
+    "eslint": "^10.12.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-better-tailwindcss": "^4.10.0",
+    "nuxt": "^4.6.1",
+    "prettier": "^3.9.10",
+    "vitest": "^5.0.5",
+    "vue": "3.5.44",
+    "vue-router": "5.4.0",
+    "vue-tsc": "^3.3.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/server/handlers/navigation.get.ts

@@ -0,0 +1,7 @@
+import { defineEventHandler } from 'h3'
+
+// Added by the module only when `plutoDocs.render` is `'hybrid'` or `'runtime'`. A route of the
+// public API (`/api/pluto/v1/docs/:type/navigation`): the answer is `{ data }`, like core's routes.
+export default defineEventHandler(async (event) => ({
+  data: await plutoRuntimeNavigation(event),
+}))

package/server/handlers/page.get.ts

@@ -0,0 +1,7 @@
+import { defineEventHandler } from 'h3'
+
+// Added by the module only when `plutoDocs.render` is `'hybrid'` or `'runtime'`. A route of the
+// public API (`/api/pluto/v1/docs/:type/page`): the answer is `{ data }`, like core's routes.
+export default defineEventHandler(async (event) => ({
+  data: await plutoRuntimePage(event),
+}))

package/server/handlers/surround.get.ts

@@ -0,0 +1,7 @@
+import { defineEventHandler } from 'h3'
+
+// Added by the module only when `plutoDocs.render` is `'hybrid'` or `'runtime'`. A route of the
+// public API (`/api/pluto/v1/docs/:type/surround`): the answer is `{ data }`, like core's routes.
+export default defineEventHandler(async (event) => ({
+  data: await plutoRuntimeSurround(event),
+}))

package/server/plugins/pluto-docs.ts

@@ -0,0 +1,25 @@
+import type { PlutoDocsTypeOptions } from '../../modules/pluto-docs/options'
+
+// Registers the content types of the layer with the core content registry. The
+// CMS Nitro plugin registers the adapter. The types are looked up per request,
+// so the order of the two plugins does not matter. When the layer is off (the
+// CMS is off), the module sets no config and this plugin does nothing.
+export default defineNitroPlugin(() => {
+  const config = useRuntimeConfig().public.plutoDocs as
+    | {
+        types: PlutoDocsTypeOptions[]
+        render?: string
+      }
+    | undefined
+  if (!config) {
+    return
+  }
+  for (const entry of config.types) {
+    registerContentType(
+      createDocsType({
+        ...entry,
+        liveOnSave: config.render === 'hybrid' || config.render === 'runtime',
+      })
+    )
+  }
+})