mikser-io-decap 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Almero Digital Marketing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# mikser-io-decap
+
+Mount [Decap CMS](https://decapcms.org/) inside the [mikser-io](https://github.com/almero-digital-marketing/mikser-io) Express server. One process, one port, one command — the admin runs alongside mikser's watcher so edits are picked up and rebuilt on save.
+
+## Why an in-process CMS
+
+Content sites almost always need an editorial UI — non-developer authors won't (and shouldn't) edit `.md` files in a code editor. The usual approach is to bolt a headless CMS (Sanity, Contentful, Strapi) onto the stack, which adds a vendor, a database, a sync problem, and a license cost per editor seat.
+
+Decap is mature, file-based, and ships as a static SPA — exactly the right shape for a file-based content engine. This plugin mounts it inside the same Express server mikser already runs, so the dev story is one command (`mikser --server`) and the production deploy is just static files. Editors get a familiar CMS UI; the content stays as plain `.md` and `.yml` on disk, version-controllable, portable, and free of any database dependency.
+
+## The plugin's job
+
+A thin host. You write your own `decap.yml`; the plugin serves the admin UI, mounts Decap's local-fs/git proxy backend, and (optionally) copies the admin bundle into the build output for static deployment.
+
+## Install
+
+```bash
+npm install mikser-io-decap decap-cms
+```
+
+`decap-cms` is a peer dependency — the standalone JS bundle that ships the admin UI.
+
+## Configure
+
+```js
+// mikser.config.js
+export default {
+  plugins: ['documents', 'layouts', 'render-hbs', 'decap'],
+
+  decap: {
+    base: '/admin',           // admin URL path; default '/admin'
+    proxyBase: '/decap',      // backend mount; default '/decap' → POST /decap/api/v1
+    mode: 'fs',               // 'fs' (raw filesystem) or 'git' (commits per edit)
+    configYml: 'decap.yml',   // user's Decap config, relative to working folder
+    copyToOut: true,          // copy admin into out/<base>/ on build; default true
+  },
+}
+```
+
+Then write your `decap.yml` in the working folder:
+
+```yaml
+# decap.yml — points Decap at mikser's folders
+backend:
+  name: proxy
+  proxy_url: http://localhost:3001/decap/api/v1
+  branch: main
+
+media_folder: files
+public_folder: /files
+
+collections:
+  - name: documents
+    label: Documents
+    folder: documents/en
+    create: true
+    fields:
+      - { name: title, label: Title, widget: string }
+      - { name: layout, label: Layout, widget: string }
+      - { name: date, label: Date, widget: datetime, required: false }
+      - { name: body, label: Body, widget: markdown }
+```
+
+## Run
+
+```bash
+npx mikser-io --server --watch
+```
+
+Open `http://localhost:3001/admin/`. Decap loads, talks to `/decap/api/v1` for reads/writes, and edits land directly in your `documents/` folder. The watcher catches them and rebuilds.
+
+## Modes
+
+**`fs`** (default) — Decap writes/reads files directly. No git. Best for solo dev and quick iteration.
+
+**`git`** — Decap performs a `git add` + `git commit` for each save, with branches per draft when [editorial workflow](https://decapcms.org/docs/configuration-options/#publish-mode) is enabled. Requires the working folder to be a git repo.
+
+Both modes are implemented by `decap-server` — this plugin just mounts the appropriate middleware on a sub-app under `proxyBase`.
+
+## Production deployment
+
+When you run `mikser` (no `--server`), the admin gets baked into `out/<base>/`:
+
+```
+out/
+  admin/
+    index.html
+    decap-cms.js
+    config.yml
+    ...
+```
+
+For the deployed admin to work, switch the backend in `decap.yml` away from `proxy` (which only exists locally) to `git-gateway` or `github`:
+
+```yaml
+backend:
+  name: git-gateway     # via Netlify Identity
+  # or:
+  # name: github
+  # repo: org/repo
+  # branch: main
+```
+
+Set `copyToOut: false` if you don't want the admin in your public deploy (e.g., you host it on a separate, password-protected URL).
+
+## Notes
+
+- This plugin requires `runtime.options.app`. Run mikser with `--server` for local use, or pass `app` to `setup({ app })` programmatically.
+- The proxy backend (`mode: 'fs'` / `mode: 'git'`) only works locally — production must use a remote backend (git-gateway, github, gitlab).
+- `decap-server` reads its working directory from `GIT_REPO_DIRECTORY`. The plugin sets this to mikser's `workingFolder` before registering.
+- `decap-server` adds cors, morgan logging, and a 50 MB JSON body limit (for base64-encoded media uploads) scoped to the proxy sub-app — none of that leaks into mikser's main Express app.
+
+## License
+
+MIT

package/admin/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1.0" />
+    <meta name="robots" content="noindex,nofollow" />
+    <title>Content Manager</title>
+</head>
+<body>
+    <!-- Decap CMS auto-discovers ./config.yml on load. -->
+    <script src="decap-cms.js"></script>
+</body>
+</html>

package/index.js

@@ -0,0 +1,156 @@
+import path from 'node:path'
+import fs from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+const here = path.dirname(fileURLToPath(import.meta.url))
+
+export default ({ runtime, onLoaded, onAfterRender, useLogger }) => {
+    const config = runtime.config.decap ?? {}
+
+    // Where the admin lives in the HTTP space. Default '/admin' to match
+    // every Decap CMS tutorial ever written; users can override if they
+    // want it somewhere else.
+    const adminBase = config.base ?? '/admin'
+
+    // Where decap-server's POST /api/v1 handler gets mounted. Sits
+    // OUTSIDE /api so it doesn't squat on the api plugin's namespace.
+    // Default '/decap' → endpoint becomes '/decap/api/v1'.
+    const proxyBase = config.proxyBase ?? '/decap'
+
+    // 'fs' (raw filesystem) or 'git' (commits per edit, editorial
+    // workflow). Default 'fs' — simplest for solo dev.
+    const mode = config.mode ?? 'fs'
+
+    // User-provided Decap config — relative to workingFolder. Defaults
+    // to 'decap.yml'. Served at <adminBase>/config.yml.
+    const configYml = config.configYml ?? 'decap.yml'
+
+    // Whether to also copy the admin bundle into outputFolder/admin/
+    // during builds so static deployments include it. Default true
+    // because Decap is designed to be deployed alongside the static
+    // site with a git-backed backend.
+    const copyToOut = config.copyToOut !== false
+
+    onLoaded(async () => {
+        const logger = useLogger()
+
+        // No app → no live admin route. This is the normal case for a
+        // one-shot production build (`mikser` without --server): the
+        // admin still gets baked into out/ by onAfterRender below, with
+        // a remote backend (git-gateway / github) doing the writes.
+        // Only the local proxy backend needs a running server.
+        if (!runtime.options.app) {
+            logger.info(
+                'Decap: no server (runtime.options.app) — skipping live admin mount. ' +
+                'Admin will be copied into the build output%s.',
+                copyToOut ? '' : ' (disabled: copyToOut is false)'
+            )
+            return
+        }
+
+        // Resolve the decap-cms standalone bundle path via peerDep.
+        let decapDistPath
+        try {
+            const decapPkgPath = require.resolve('decap-cms/package.json')
+            decapDistPath = path.join(path.dirname(decapPkgPath), 'dist')
+            await fs.access(path.join(decapDistPath, 'decap-cms.js'))
+        } catch {
+            throw new Error(
+                'Decap plugin: cannot find decap-cms peer dependency. ' +
+                'Install it with `npm install decap-cms`.'
+            )
+        }
+
+        // Resolve the decap-server middleware. registerLocalFs /
+        // registerLocalGit each attach a POST /api/v1 handler to a
+        // given Express app — exactly what we need. The package's
+        // built bundle is CJS, so the named exports come through the
+        // default import.
+        const { default: { registerLocalFs, registerLocalGit } } =
+            await import('decap-server/dist/middlewares.js')
+
+        // decap-server reads GIT_REPO_DIRECTORY from the environment
+        // (no per-call override). Point it at the working folder before
+        // registration. localFs uses the same env var as localGit.
+        const workingFolder = path.resolve(runtime.options.workingFolder)
+        process.env.GIT_REPO_DIRECTORY = workingFolder
+
+        // Lazy-import express through the host app's prototype so we
+        // get the same instance the engine created.
+        const expressApp = runtime.options.app
+        const express = expressApp.constructor.application ? null
+            : (await import('express')).default
+        if (!express) {
+            throw new Error('Decap plugin: express not available')
+        }
+
+        // --- Proxy backend mounted on a sub-app under <proxyBase> ---
+        // The sub-app gives us route isolation (cors / json / morgan
+        // from registerCommonMiddlewares stay scoped). The endpoint
+        // becomes <proxyBase>/api/v1.
+        const proxyApp = express()
+        if (mode === 'git') await registerLocalGit(proxyApp, { logLevel: 'info' })
+        else if (mode === 'fs') await registerLocalFs(proxyApp, { logLevel: 'info' })
+        else throw new Error(`Decap plugin: unknown mode '${mode}' (expected 'fs' or 'git')`)
+        expressApp.use(proxyBase, proxyApp)
+
+        // --- Admin UI at <adminBase> ---
+        // Order matters:
+        //   1. Our admin/index.html (the bootstrap loading decap-cms.js)
+        //   2. The user's decap.yml served as config.yml
+        //   3. The decap-cms standalone bundle (decap-cms.js + assets)
+        expressApp.use(adminBase, express.static(path.join(here, 'admin')))
+
+        const configYmlAbs = path.resolve(workingFolder, configYml)
+        expressApp.get(`${adminBase}/config.yml`, async (req, res) => {
+            try {
+                const body = await fs.readFile(configYmlAbs, 'utf8')
+                res.type('text/yaml').send(body)
+            } catch (err) {
+                logger.error('Decap config not found at %s', configYmlAbs)
+                res.status(404).send(`# decap config not found at ${configYml}`)
+            }
+        })
+
+        expressApp.use(adminBase, express.static(decapDistPath))
+
+        logger.info('Decap admin mounted: %s (mode=%s, proxy=%s/api/v1, config=%s)',
+            adminBase, mode, proxyBase, configYml)
+    })
+
+    onAfterRender(async () => {
+        if (!copyToOut) return
+        const logger = useLogger()
+
+        const outAdmin = path.join(
+            path.resolve(runtime.options.outputFolder),
+            adminBase.replace(/^\//, '')
+        )
+        await fs.mkdir(outAdmin, { recursive: true })
+
+        // Copy our admin bootstrap (index.html etc.)
+        await fs.cp(path.join(here, 'admin'), outAdmin, { recursive: true })
+
+        // Copy the user's decap config alongside the bootstrap. Decap
+        // looks for ./config.yml relative to the admin HTML.
+        const configYmlAbs = path.resolve(runtime.options.workingFolder, configYml)
+        try {
+            await fs.copyFile(configYmlAbs, path.join(outAdmin, 'config.yml'))
+        } catch {
+            logger.warn('Decap: no %s to copy into out/%s', configYml, adminBase)
+        }
+
+        // Copy decap-cms standalone bundle (decap-cms.js + maps + chunks)
+        try {
+            const decapPkgPath = require.resolve('decap-cms/package.json')
+            const decapDistPath = path.join(path.dirname(decapPkgPath), 'dist')
+            await fs.cp(decapDistPath, outAdmin, { recursive: true })
+        } catch {
+            logger.warn('Decap: peerDep decap-cms not installed, skipping bundle copy to out')
+        }
+
+        logger.info('Decap admin written: %s', outAdmin)
+    })
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "mikser-io-decap",
+  "version": "2.0.0",
+  "description": "Mount Decap CMS inside the mikser-io express server — single process admin for file-based content",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/almero-digital-marketing/mikser-io-decap.git"
+  },
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/almero-digital-marketing/mikser-io-decap/issues"
+  },
+  "homepage": "https://github.com/almero-digital-marketing/mikser-io-decap#readme",
+  "peerDependencies": {
+    "mikser-io": "^7.0.0",
+    "decap-cms": "^3.0.0"
+  },
+  "dependencies": {
+    "decap-server": "^3.7.0"
+  }
+}