mikser-io-git 2.1.0 → 2.2.0

package/README.md

@@ -193,15 +193,28 @@ Both forges have *some* direct-merge concept, but they're not the same feature a
 
 Pull requests, by contrast, are nearly identical between the two — `POST .../pulls { title, head, base }` creates one on both GitHub and Gitea. And a PR gives you something the direct-merge endpoints don't: a real conflict surface. A `/merges` 409 is a status code with nowhere to look; a conflicted PR is a page that names the exact files in conflict and offers to resolve them in the forge's own UI. That's a better fit for "leave it open, let a human resolve it" than either forge's direct-merge shortcut.
 
+## Requirements
+
+- **git 2.31 or newer** on the machine running mikser. The auth token is
+  delivered to git through `GIT_CONFIG_COUNT` / `GIT_CONFIG_KEY_n` /
+  `GIT_CONFIG_VALUE_n`, which older git ignores — it would fall back to
+  unauthenticated access and fail against a private repo. 2.31 shipped in
+  March 2021; `git --version` if unsure.
+- No runtime npm dependencies. Everything goes through the `git` binary.
+
 ## Security
 
-- **The auth token is never written to disk.** It's passed as a one-off `http.extraheader` on the specific git command that needs it (`clone`/`fetch`/`push`), never embedded in the remote URL — an embedded `https://token@host/...` remote persists into `.git/config` in plaintext and leaks into `git remote -v` output and any log line that happens to echo the remote.
+- **The auth token is never written to disk, and never appears in the process's arguments.** It's passed as a one-off `http.extraheader` for the specific git command that needs it (`clone`/`fetch`/`push`/`ls-remote`), delivered through the environment (`GIT_CONFIG_COUNT` / `GIT_CONFIG_KEY_0` / `GIT_CONFIG_VALUE_0`, git 2.31+) rather than as a `-c` argument, and never embedded in the remote URL.
+
+  Three places a credential can leak, and what each avoids: an embedded `https://token@host/...` remote persists into `.git/config` in plaintext and shows up in `git remote -v` and any log line echoing the remote; a `-c http.extraheader=...` argument lands in the process's argument list, which is world-readable on Linux (`/proc/<pid>/cmdline` is `-r--r--r--`, while `/proc/<pid>/environ` is `-r--------`) and can surface in an `err.stderr` a caller then logs; the environment form has neither property and the same one-command lifetime. Note that base64 here is encoding, not encryption — it is the HTTP Basic wire format, so keeping it out of world-readable places is the whole protection.
 - **Every git invocation goes through `execFile` with an argv array — never a shell string.** Commit messages are built from a file count, not raw content, but nothing here ever risks passing arbitrary content through a shell regardless.
+- **A timer body can never end the process.** Both schedulers here — the debounced sync pass and the inbound poll — run for the life of a watch server, and Node has treated an unhandled rejection as fatal since v15 while mikser installs no process-level handler. `pullInbound` returns a result shape for every outcome including a failed `fetch`, and both callbacks are wrapped besides: a transient remote failure must not take down the build and the site, least of all in a supervisor restart loop.
+- **Git operations are serialised per instance.** The sync pass and the inbound poll share one checkout; without a queue they overlap and lose to `index.lock`, or worse, commit while an inbound merge is in progress.
 - **The write branch is force-pushed only after a successful promotion**, using `--force-with-lease` (refuses if the remote moved unexpectedly since the last fetch) rather than a bare `--force`. This is safe specifically because `mikser`/`writeBranch` is a branch this plugin owns exclusively — nothing else's history is ever at risk on it.
 
 ## Verified end-to-end
 
-The unit suite (59 tests) covers every pure module directly, the forge adapters via an injected `fetchImpl` mock, and — critically for the working-folder-as-checkout model — the pathspec scope itself against a real temp git repo (`test/git.test.js`'s "pathspec scoping" suite: a config-file edit and a whole new out-of-scope directory are both proven invisible to a `paths`-scoped add, while an in-scope file commits normally). Beyond the unit suite, this has been run against **real GitHub repos and mikser's own example blog** — not just mocks:
+The unit suite (73 tests) covers every pure module directly, the forge adapters via an injected `fetchImpl` mock, and — critically for the working-folder-as-checkout model — the pathspec scope itself against a real temp git repo (`test/git.test.js`'s "pathspec scoping" suite: a config-file edit and a whole new out-of-scope directory are both proven invisible to a `paths`-scoped add, while an in-scope file commits normally). Beyond the unit suite, this has been run against **real GitHub repos and mikser's own example blog** — not just mocks:
 
 - **The "adopt an existing non-empty folder" recipe** (see [First connect](#first-connect--and-why-it-can-refuse-to-guess)), run by hand exactly as documented, against the real blog's working folder — `mikser.config.js`, `node_modules/`, `layouts/`, `documents/`, everything — and a fresh throwaway GitHub repo. `refuse` fired correctly on the very first connect attempt (confirming that's now the expected first-run path, not an edge case); the manual recipe attached history without touching a file; `git status` afterward showed exactly the expected divergence.
 - **The `paths` scope boundary, live, not just unit-tested.** With `paths: ['documents', 'layouts']` on that same checkout: a build with only a `mikser.config.js`/`LICENSE` edit produced **zero commits** — no `git: committed + pushed` line at all; a build with a real `layouts/` edit committed, pushed, and promoted normally. A fresh clone of the repo afterward showed the tree contained **only** `documents/`, `layouts/`, and the seed file — no `mikser.config.js`, no `node_modules`, nothing leaked from outside `paths`.

package/index.js

@@ -53,9 +53,24 @@ import { gatherFolderState, decideBootstrap, performClone, performVerify } from
 import { commitAndPushWriteBranch, promote } from './lib/sync.js'
 import { pullInbound } from './lib/inbound.js'
 import { reduceDebounce, IDLE_DEBOUNCE_STATE } from './lib/debounce.js'
+import { createGitQueue } from './lib/queue.js'
 
 const REANNOUNCE_MS = 30 * 60 * 1000   // re-log a still-open conflict at most every 30 min
 
+// Run a timer body so that nothing it does can end the process.
+//
+// Both schedulers here fire for the life of a watch server, and an async
+// callback that rejects is fatal — Node has treated an unhandled rejection
+// as process-ending since v15, and mikser core installs no handler. The
+// failure mode this prevents is a transient remote error taking down the
+// build AND the site, and looping under a supervisor.
+function withGuard(logger, what, fn) {
+    Promise.resolve()
+        .then(fn)
+        .catch(err => logger?.error('git: %s failed — %s', what, err?.stderr || err?.message || err))
+}
+
+
 export function git(options = {}) {
     const {
         url, paths, forge, targetBranch, writeBranch,
@@ -69,6 +84,7 @@ export function git(options = {}) {
         // scopes this instance's reach within it.
         const folder = runtime.options.workingFolder
 
+        const enqueueGit = createGitQueue()
         let debounceState = IDLE_DEBOUNCE_STATE
         let timer = null
         let pollTimer = null
@@ -111,7 +127,7 @@ export function git(options = {}) {
         function scheduleFire(logger) {
             if (timer) clearTimeout(timer)
             const delay = Math.max(0, debounceState.fireAt - Date.now())
-            timer = setTimeout(() => runSyncPass(logger), delay)
+            timer = setTimeout(() => withGuard(logger, 'sync pass', () => enqueueGit(() => runSyncPass(logger))), delay)
             timer.unref?.()
         }
 
@@ -148,9 +164,17 @@ export function git(options = {}) {
             // "later" to pull into. Webhook delivery is not implemented
             // (see README); poll is the only supported inbound trigger.
             if (runtime.options.watch && pollIntervalMs > 0) {
-                pollTimer = setInterval(async () => {
+                pollTimer = setInterval(() => {
                     if (inert) return
-                    await pullInbound(folder, { writeBranch, targetBranch, token, logger })
+                    // Belt AND braces. pullInbound is written not to throw,
+                    // but a timer callback is the one place where being
+                    // wrong about that is fatal rather than noisy: Node has
+                    // treated an unhandled rejection as process-ending since
+                    // v15, and mikser installs no handler. Anything reaching
+                    // here is a bug worth logging, not worth killing the
+                    // build server for.
+                    withGuard(logger, 'inbound poll', () => enqueueGit(() =>
+                        pullInbound(folder, { writeBranch, targetBranch, token, logger })))
                 }, pollIntervalMs)
                 pollTimer.unref?.()
             }
@@ -180,7 +204,7 @@ export function git(options = {}) {
                     logger.warn('git: build had failures (%s) — not syncing', culprits.join(', '))
                     return
                 }
-                await runSyncPass(logger)
+                await enqueueGit(() => runSyncPass(logger))
                 return
             }
 

package/lib/git.js

@@ -49,32 +49,49 @@ export async function remoteUrl(folder, remote = 'origin') {
     }
 }
 
-// Auth via a short-lived per-request header, never embedded in the
-// remote URL or written to .git/config — an embedded
-// `https://token@host/...` remote leaks the token into `git remote -v`
-// output and any log/error that echoes the URL. `http.extraheader` is
-// passed as a one-off `-c` flag on the specific command that needs it
-// (fetch/pull/push/clone), so it never persists to disk.
-function authArgs(token) {
-    if (!token) return []
+// Auth via a short-lived per-command header, never embedded in the remote
+// URL or written to .git/config — an embedded `https://token@host/...`
+// remote leaks the token into `git remote -v` output and any log or error
+// that echoes the URL.
+//
+// Delivered through the ENVIRONMENT rather than as a `-c` argument.
+// Same semantics, same one-command lifetime, same no-persistence — but a
+// process's arguments are world-readable and its environment is not:
+//
+//     -r--r--r--   /proc/<pid>/cmdline
+//     -r--------   /proc/<pid>/environ
+//
+// As a `-c http.extraheader=...` argument the base64 credential is
+// readable by any local user for as long as the git subprocess runs
+// (base64 is encoding, not encryption), and it can surface in an
+// `err.stderr` that a caller then logs. GIT_CONFIG_COUNT / _KEY_n /
+// _VALUE_n is git's own supported equivalent (2.31+) and keeps it out of
+// both places.
+function authEnv(token) {
+    if (!token) return undefined
     const b64 = Buffer.from(`x-access-token:${token}`).toString('base64')
-    return ['-c', `http.extraheader=AUTHORIZATION: basic ${b64}`]
+    return {
+        ...process.env,
+        GIT_CONFIG_COUNT: '1',
+        GIT_CONFIG_KEY_0: 'http.extraheader',
+        GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${b64}`,
+    }
 }
 
 export async function clone(url, folder, { branch, token } = {}) {
-    const args = [...authArgs(token), 'clone', ...(branch ? ['--branch', branch] : []), url, folder]
+    const args = ['clone', ...(branch ? ['--branch', branch] : []), url, folder]
     // clone's cwd doesn't matter (destination is a full path); run from
     // the parent so a not-yet-existing `folder` isn't required as cwd.
-    await run('.', args)
+    await run('.', args, { env: authEnv(token) })
 }
 
 export async function fetch(folder, { remote = 'origin', token } = {}) {
-    await run(folder, [...authArgs(token), 'fetch', remote])
+    await run(folder, ['fetch', remote], { env: authEnv(token) })
 }
 
 export async function push(folder, refspec, { remote = 'origin', token, force = false } = {}) {
-    const args = [...authArgs(token), 'push', ...(force ? ['--force-with-lease'] : []), remote, refspec]
-    await run(folder, args)
+    const args = ['push', ...(force ? ['--force-with-lease'] : []), remote, refspec]
+    await run(folder, args, { env: authEnv(token) })
 }
 
 // Non-fast-forward pushes throw with stderr containing "non-fast-forward"
@@ -164,7 +181,7 @@ export async function branchExistsLocal(folder, branch) {
 export async function branchExistsRemote(folder, branch, { remote = 'origin', token } = {}) {
     // ls-remote hits the network but needs no local ref state — safe
     // to call before any fetch has happened.
-    const out = await run(folder, [...authArgs(token), 'ls-remote', '--heads', remote, branch])
+    const out = await run(folder, ['ls-remote', '--heads', remote, branch], { env: authEnv(token) })
     return out.length > 0
 }
 

package/lib/inbound.js

@@ -23,14 +23,48 @@
 
 import * as git from './git.js'
 
+// Never throws. Every caller is a timer, and a timer callback that
+// rejects takes the whole process down: Node has treated an unhandled
+// rejection as fatal since v15, mikser installs no process-level handler,
+// and the poll runs every few minutes for the life of a watch server. A
+// network blip, a DNS failure or an expired token would kill the build and
+// the site, and under a supervisor it becomes a restart loop.
+//
+// So the outcome is always a returned shape. A fetch that fails is the same
+// class of event as a merge that conflicts — remote trouble, reported, try
+// again next tick — and it is reported the same way.
 export async function pullInbound(folder, { writeBranch, targetBranch, token, logger }) {
-    await git.fetch(folder, { token })
+    try {
+        await git.fetch(folder, { token })
+    } catch (err) {
+        // Nothing was touched: fetch writes only to remote-tracking refs,
+        // and a failed one leaves even those alone.
+        logger?.warn(
+            'git: inbound fetch failed — %s. Working folder untouched; retrying on the next poll.',
+            err.stderr || err.message,
+        )
+        return { merged: false, fetchFailed: true, reason: err.stderr || err.message }
+    }
 
     for (const ref of [writeBranch, targetBranch]) {
         try {
             await git.mergeBranch(folder, `origin/${ref}`)
         } catch (err) {
-            await git.abortMerge(folder)
+            // A failed abort would throw straight past this handler and
+            // become the fatal rejection the fetch guard above exists to
+            // prevent. Report it instead: the folder is then in a merge
+            // state a human has to look at, which is worth saying loudly.
+            try {
+                await git.abortMerge(folder)
+            } catch (abortErr) {
+                logger?.error(
+                    'git: inbound merge of origin/%s conflicted AND `git merge --abort` failed — %s. ' +
+                    'The working folder is mid-merge and may contain conflict markers; mikser will render them as content. '
+                    + 'Resolve manually before the next cycle.',
+                    ref, abortErr.stderr || abortErr.message,
+                )
+                return { merged: false, conflictedRef: ref, abortFailed: true, reason: abortErr.stderr || abortErr.message }
+            }
             logger?.error(
                 'git: inbound merge of origin/%s conflicted — aborted, working folder left untouched. ' +
                 'Resolve manually: cd <folder> && git merge origin/%s (or origin/%s) and fix the conflicts. %s',

package/lib/queue.js

@@ -0,0 +1,24 @@
+// One git operation at a time, per plugin instance.
+//
+// The sync pass and the inbound poll are independent timers — debounced
+// seconds after a green cycle, and every few minutes — over the SAME
+// checkout. Nothing stopped them overlapping, and git serialises through
+// `index.lock`: the loser fails with "Another git process seems to be
+// running", which surfaces as an intermittent sync failure that retries
+// and looks like nothing. The worse shape is a commit landing while an
+// inbound merge is in progress, which commits the merge rather than the
+// intended change.
+//
+// A promise chain rather than a lock: each caller waits for the previous
+// operation to settle, in order, and a rejection cannot break the chain
+// because the guard already turned every body into a resolved promise.
+export function createGitQueue() {
+    let tail = Promise.resolve()
+    return function enqueue(fn) {
+        const next = tail.then(fn, fn)
+        // Swallow here only — the caller's own guard reports. Without this
+        // the chain itself would carry an unhandled rejection.
+        tail = next.catch(() => {})
+        return next
+    }
+}

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "mikser-io-git",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Two-way git sync for mikser-io. The working folder itself is the checkout, on a dedicated `mikser` branch (durable write log for API/MCP/agent edits). `paths` (optional) scopes auto-commits to specific collection folders (documents, layouts, files, ...) as a hard pathspec; omit it and the whole working folder is committed, subject to .gitignore. Every green cycle commits + pushes whatever's in scope and attempts to merge into the target branch (`main`) via a pull request; a red cycle (any render/postprocess failure) holds the merge and leaves the PR open for a human to resolve. Inbound changes on the target branch merge back into the working copy via poll. Forge-portable: GitHub and Gitea adapters, plus a no-forge fast-forward-only floor for any bare remote.",
   "main": "index.js",
+  "files": [
+    "index.js",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
   "type": "module",
   "scripts": {
     "test": "node --no-warnings --test --test-reporter=spec 'test/**/*.test.js'"

package/test/bootstrap.test.js

@@ -1,59 +0,0 @@
-// decideBootstrap is pure — plain facts in, a decision out — so every
-// folder-state combination is directly testable without touching a
-// filesystem or a git binary.
-
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { decideBootstrap } from '../lib/bootstrap.js'
-
-const EXPECTED = 'https://github.com/org/content.git'
-
-describe('decideBootstrap', () => {
-    it('clones into a folder that does not exist yet', () => {
-        const d = decideBootstrap({ folderExists: false, folderEmpty: true, isRepo: false, remoteUrl: null, expectedUrl: EXPECTED })
-        assert.equal(d.action, 'clone')
-    })
-
-    it('clones into an existing empty folder', () => {
-        const d = decideBootstrap({ folderExists: true, folderEmpty: true, isRepo: false, remoteUrl: null, expectedUrl: EXPECTED })
-        assert.equal(d.action, 'clone')
-    })
-
-    it('refuses a non-empty folder that is not a git repo — the destructive case', () => {
-        const d = decideBootstrap({ folderExists: true, folderEmpty: false, isRepo: false, remoteUrl: null, expectedUrl: EXPECTED })
-        assert.equal(d.action, 'refuse')
-        assert.match(d.reason, /not a git repository/i)
-        assert.match(d.reason, /git init/)   // the manual recipe must be in the message
-    })
-
-    it('verifies an existing checkout whose remote matches', () => {
-        const d = decideBootstrap({ folderExists: true, folderEmpty: false, isRepo: true, remoteUrl: EXPECTED, expectedUrl: EXPECTED })
-        assert.equal(d.action, 'verify')
-    })
-
-    it('verify tolerates a trailing-slash / missing .git cosmetic difference', () => {
-        const d = decideBootstrap({
-            folderExists: true, folderEmpty: false, isRepo: true,
-            remoteUrl: 'https://github.com/org/content',   // no .git suffix
-            expectedUrl: EXPECTED,                          // has .git suffix
-        })
-        assert.equal(d.action, 'verify')
-    })
-
-    it('refuses an existing repo with no origin remote at all', () => {
-        const d = decideBootstrap({ folderExists: true, folderEmpty: false, isRepo: true, remoteUrl: null, expectedUrl: EXPECTED })
-        assert.equal(d.action, 'refuse')
-        assert.match(d.reason, /no "origin" remote/i)
-    })
-
-    it('refuses an existing repo whose remote points somewhere else', () => {
-        const d = decideBootstrap({
-            folderExists: true, folderEmpty: false, isRepo: true,
-            remoteUrl: 'https://github.com/someone-else/other-repo.git',
-            expectedUrl: EXPECTED,
-        })
-        assert.equal(d.action, 'refuse')
-        assert.match(d.reason, /does not match the configured repo/i)
-    })
-})

package/test/config.test.js

@@ -1,101 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { resolveConfig } from '../lib/config.js'
-
-describe('resolveConfig', () => {
-    it('requires url', () => {
-        assert.throws(() => resolveConfig({}), /`url` is required/)
-    })
-
-    it('rejects an unknown forge', () => {
-        assert.throws(
-            () => resolveConfig({ url: 'https://github.com/org/repo.git', forge: 'bitbucket' }),
-            /must be "github", "gitea", or "none"/,
-        )
-    })
-
-    it('rejects an empty paths array', () => {
-        assert.throws(
-            () => resolveConfig({ url: 'https://example.com/org/repo.git', paths: [] }),
-            /`paths` must be a non-empty/,
-        )
-    })
-
-    it('normalizes a single path string to a one-element array', () => {
-        const cfg = resolveConfig({ url: 'https://example.com/org/repo.git', paths: 'layouts' })
-        assert.deepEqual(cfg.paths, ['layouts'])
-    })
-
-    it('accepts an array of paths for multiple collections sharing one checkout', () => {
-        const cfg = resolveConfig({ url: 'https://example.com/org/repo.git', paths: ['documents', 'layouts', 'files'] })
-        assert.deepEqual(cfg.paths, ['documents', 'layouts', 'files'])
-    })
-
-    it('omitting paths means "no scope" — the whole working folder, not a narrower default', () => {
-        // Deliberately distinct from '[\'documents\']': the zero-config
-        // case should match the model's own framing ("the working
-        // folder is the checkout"), not silently narrow to one
-        // collection nobody asked for.
-        const cfg = resolveConfig({ url: 'https://example.com/org/repo.git' })
-        assert.equal(cfg.paths, null)
-    })
-
-    it('applies sane defaults for a minimal forge:none config', () => {
-        const cfg = resolveConfig({ url: 'https://example.com/org/repo.git' })
-        assert.equal(cfg.forge, 'none')
-        assert.equal(cfg.paths, null)
-        assert.equal(cfg.targetBranch, 'main')
-        assert.equal(cfg.writeBranch, 'mikser')
-        assert.equal(cfg.afterMs, 60_000)
-        assert.equal(cfg.maxWaitMs, 600_000)
-        assert.equal(cfg.pollIntervalMs, 300_000)
-        // forge:none never needs owner/repo/apiBase — no API involved.
-        assert.equal(cfg.owner, undefined)
-        assert.equal(cfg.repo, undefined)
-        assert.equal(cfg.apiBase, undefined)
-    })
-
-    it('derives owner/repo/apiBase from the url when forge is github', () => {
-        const cfg = resolveConfig({ url: 'https://github.com/almero-digital-marketing/gpoint-content.git', forge: 'github', token: 'x' })
-        assert.equal(cfg.owner, 'almero-digital-marketing')
-        assert.equal(cfg.repo, 'gpoint-content')
-        assert.equal(cfg.apiBase, 'https://api.github.com')
-    })
-
-    it('derives owner/repo/apiBase from the url when forge is gitea', () => {
-        const cfg = resolveConfig({ url: 'https://git.almero.bg/org/content.git', forge: 'gitea', token: 'x' })
-        assert.equal(cfg.owner, 'org')
-        assert.equal(cfg.repo, 'content')
-        assert.equal(cfg.apiBase, 'https://git.almero.bg')
-    })
-
-    it('explicit owner/repo/apiBase override the url-derived values', () => {
-        const cfg = resolveConfig({
-            url: 'https://github.com/org/repo.git', forge: 'github', token: 'x',
-            owner: 'other-org', repo: 'other-repo', apiBase: 'https://ghe.example.com/api/v3',
-        })
-        assert.equal(cfg.owner, 'other-org')
-        assert.equal(cfg.repo, 'other-repo')
-        assert.equal(cfg.apiBase, 'https://ghe.example.com/api/v3')
-    })
-
-    it('respects custom branch names, paths, and durations', () => {
-        const cfg = resolveConfig({
-            url: 'https://example.com/org/repo.git',
-            branch: 'live', writeBranch: 'agents', paths: ['content'],
-            after: '30s', maxWait: '5m', pollInterval: '1m',
-        })
-        assert.equal(cfg.targetBranch, 'live')
-        assert.equal(cfg.writeBranch, 'agents')
-        assert.deepEqual(cfg.paths, ['content'])
-        assert.equal(cfg.afterMs, 30_000)
-        assert.equal(cfg.maxWaitMs, 300_000)
-        assert.equal(cfg.pollIntervalMs, 60_000)
-    })
-
-    it('the default message builder includes the file count', () => {
-        const cfg = resolveConfig({ url: 'https://example.com/org/repo.git' })
-        assert.equal(cfg.message({ fileCount: 3 }), 'content: 3 file(s) via mikser')
-    })
-})

package/test/debounce.test.js

@@ -1,57 +0,0 @@
-// reduceDebounce is pure — feed a sequence of green/red events with
-// explicit timestamps, assert the resulting fireAt. Covers both halves
-// of the design: the short debounce after a green cycle, and the
-// maxWait ceiling that keeps a steady stream of green cycles from
-// starving the sync forever.
-
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { reduceDebounce, IDLE_DEBOUNCE_STATE } from '../lib/debounce.js'
-
-const CFG = { afterMs: 60_000, maxWaitMs: 600_000 }   // 1m / 10m, matches the plugin's defaults
-
-describe('reduceDebounce', () => {
-    it('a single green event fires after `after`', () => {
-        const s = reduceDebounce(IDLE_DEBOUNCE_STATE, { type: 'green', now: 1000 }, CFG)
-        assert.equal(s.pendingSince, 1000)
-        assert.equal(s.fireAt, 1000 + CFG.afterMs)
-    })
-
-    it('a red event clears the window outright', () => {
-        const afterGreen = reduceDebounce(IDLE_DEBOUNCE_STATE, { type: 'green', now: 1000 }, CFG)
-        const afterRed = reduceDebounce(afterGreen, { type: 'red', now: 2000 }, CFG)
-        assert.deepEqual(afterRed, IDLE_DEBOUNCE_STATE)
-    })
-
-    it('a later green event pushes fireAt out again (trailing debounce)', () => {
-        let s = reduceDebounce(IDLE_DEBOUNCE_STATE, { type: 'green', now: 0 }, CFG)
-        s = reduceDebounce(s, { type: 'green', now: 30_000 }, CFG)
-        // pendingSince stays at the FIRST green (0); fireAt tracks the latest green + after,
-        // capped by pendingSince + maxWait (0 + 600_000 = 600_000, not yet reached).
-        assert.equal(s.pendingSince, 0)
-        assert.equal(s.fireAt, 30_000 + CFG.afterMs)
-    })
-
-    it('a steady stream of green events is bounded by maxWait — never starves forever', () => {
-        let s = reduceDebounce(IDLE_DEBOUNCE_STATE, { type: 'green', now: 0 }, CFG)
-        // Green every 30s, well under the 60s `after` window, for 20 minutes —
-        // a pure trailing debounce would never fire.
-        for (let now = 30_000; now <= 1_200_000; now += 30_000) {
-            s = reduceDebounce(s, { type: 'green', now }, CFG)
-        }
-        // fireAt must never exceed pendingSince + maxWait (0 + 600_000).
-        assert.ok(s.fireAt <= CFG.maxWaitMs, `fireAt ${s.fireAt} exceeded the maxWait ceiling ${CFG.maxWaitMs}`)
-        assert.equal(s.fireAt, CFG.maxWaitMs)
-    })
-
-    it('a red event after being interrupted then going green again starts a FRESH window', () => {
-        let s = reduceDebounce(IDLE_DEBOUNCE_STATE, { type: 'green', now: 0 }, CFG)
-        s = reduceDebounce(s, { type: 'red', now: 100_000 }, CFG)
-        s = reduceDebounce(s, { type: 'green', now: 200_000 }, CFG)
-        // pendingSince resets to the new green's timestamp, not the original 0 —
-        // otherwise the maxWait ceiling would already be looming from unrelated history.
-        assert.equal(s.pendingSince, 200_000)
-        assert.equal(s.fireAt, 200_000 + CFG.afterMs)
-    })
-})

package/test/duration.test.js

@@ -1,32 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { parseDuration } from '../lib/duration.js'
-
-describe('parseDuration', () => {
-    it('passes a plain number through unchanged', () => {
-        assert.equal(parseDuration(5000), 5000)
-    })
-
-    it('returns the fallback for null/undefined', () => {
-        assert.equal(parseDuration(undefined, 42), 42)
-        assert.equal(parseDuration(null, 42), 42)
-    })
-
-    it('parses each unit', () => {
-        assert.equal(parseDuration('500ms'), 500)
-        assert.equal(parseDuration('30s'), 30_000)
-        assert.equal(parseDuration('1m'), 60_000)
-        assert.equal(parseDuration('10m'), 600_000)
-        assert.equal(parseDuration('2h'), 7_200_000)
-        assert.equal(parseDuration('1d'), 86_400_000)
-    })
-
-    it('is case-insensitive on the unit', () => {
-        assert.equal(parseDuration('1M'), 60_000)
-    })
-
-    it('throws on an unparseable string', () => {
-        assert.throws(() => parseDuration('soon'), /invalid duration/i)
-    })
-})

package/test/forge/gitea.test.js

@@ -1,91 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { ensurePR, mergePR } from '../../lib/forge/gitea.js'
-
-function fakeResponse({ ok = true, status = 200, body = {} } = {}) {
-    return {
-        ok,
-        status,
-        statusText: ok ? 'OK' : 'Error',
-        json: async () => body,
-    }
-}
-
-const CTX = { apiBase: 'https://git.almero.bg', owner: 'org', repo: 'content', head: 'mikser', base: 'main', title: 'Promote', token: 'tok' }
-
-describe('gitea forge adapter', () => {
-    it('ensurePR reuses an existing open PR matched by head/base ref', async () => {
-        const calls = []
-        const fetchImpl = async (url, opts) => {
-            calls.push({ url, method: opts?.method ?? 'GET' })
-            return fakeResponse({
-                body: [
-                    { number: 3, head: { ref: 'some-other-branch' }, base: { ref: 'main' } },
-                    { number: 5, head: { ref: 'mikser' }, base: { ref: 'main' }, html_url: 'https://git.almero.bg/org/content/pulls/5' },
-                ],
-            })
-        }
-        const pr = await ensurePR({ ...CTX, fetchImpl })
-        assert.deepEqual(pr, { number: 5, url: 'https://git.almero.bg/org/content/pulls/5' })
-        assert.equal(calls.length, 1)
-        assert.match(calls[0].url, /\/api\/v1\/repos\/org\/content\/pulls\?state=open/)
-    })
-
-    it('ensurePR creates a new PR when the open list has no head/base match', async () => {
-        const calls = []
-        const fetchImpl = async (url, opts) => {
-            calls.push({ url, method: opts?.method ?? 'GET' })
-            if (!opts?.method || opts.method === 'GET') return fakeResponse({ body: [] })
-            return fakeResponse({ status: 201, body: { number: 11, html_url: 'https://git.almero.bg/org/content/pulls/11' } })
-        }
-        const pr = await ensurePR({ ...CTX, fetchImpl })
-        assert.deepEqual(pr, { number: 11, url: 'https://git.almero.bg/org/content/pulls/11' })
-        assert.equal(calls[1].method, 'POST')
-    })
-
-    it('ensurePR posts the correct body shape when creating', async () => {
-        let capturedBody = null
-        const fetchImpl = async (url, opts) => {
-            if (!opts?.method || opts.method === 'GET') return fakeResponse({ body: [] })
-            capturedBody = JSON.parse(opts.body)
-            return fakeResponse({ status: 201, body: { number: 1, html_url: 'x' } })
-        }
-        await ensurePR({ ...CTX, fetchImpl })
-        assert.deepEqual(capturedBody, { title: 'Promote', head: 'mikser', base: 'main' })
-    })
-
-    it('mergePR posts { Do: "merge" } — Gitea-specific field name and casing', async () => {
-        let capturedBody = null
-        let capturedMethod = null
-        const fetchImpl = async (url, opts) => {
-            capturedMethod = opts.method
-            capturedBody = JSON.parse(opts.body)
-            return fakeResponse({ body: {} })
-        }
-        const result = await mergePR({ apiBase: 'https://git.almero.bg', owner: 'org', repo: 'content', number: 5, token: 'tok', fetchImpl })
-        assert.deepEqual(result, { merged: true })
-        assert.equal(capturedMethod, 'POST')   // NOT PUT — differs from the GitHub adapter
-        assert.deepEqual(capturedBody, { Do: 'merge' })
-    })
-
-    it('mergePR reports merged:false with a reason on failure', async () => {
-        const fetchImpl = async () => fakeResponse({ ok: false, status: 409, body: { message: 'merge conflict' } })
-        const result = await mergePR({ apiBase: 'https://git.almero.bg', owner: 'org', repo: 'content', number: 5, token: 'tok', fetchImpl })
-        assert.equal(result.merged, false)
-        assert.match(result.reason, /merge conflict/)
-    })
-
-    it('auth header uses the Gitea "token" scheme, not Bearer', async () => {
-        const seenHeaders = []
-        const fetchImpl = async (url, opts) => {
-            seenHeaders.push(opts.headers)
-            return fakeResponse({ body: [] })   // empty list → falls through to create, also hit by this fetchImpl
-        }
-        await ensurePR({ ...CTX, fetchImpl })
-        assert.ok(seenHeaders.length > 0)
-        for (const headers of seenHeaders) {
-            assert.equal(headers.Authorization, 'token tok')
-        }
-    })
-})

package/test/forge/github.test.js

@@ -1,70 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { ensurePR, mergePR } from '../../lib/forge/github.js'
-
-function fakeResponse({ ok = true, status = 200, body = {} } = {}) {
-    return {
-        ok,
-        status,
-        statusText: ok ? 'OK' : 'Error',
-        json: async () => body,
-    }
-}
-
-const CTX = { owner: 'org', repo: 'content', head: 'mikser', base: 'main', title: 'Promote', token: 'tok' }
-
-describe('github forge adapter', () => {
-    it('ensurePR reuses an existing open PR instead of creating a new one', async () => {
-        const calls = []
-        const fetchImpl = async (url, opts) => {
-            calls.push({ url, method: opts?.method ?? 'GET' })
-            return fakeResponse({ body: [{ number: 7, html_url: 'https://github.com/org/content/pull/7' }] })
-        }
-        const pr = await ensurePR({ ...CTX, fetchImpl })
-        assert.deepEqual(pr, { number: 7, url: 'https://github.com/org/content/pull/7' })
-        assert.equal(calls.length, 1, 'must not call the create endpoint when one already exists')
-        assert.match(calls[0].url, /head=org:mikser&base=main&state=open/)
-    })
-
-    it('ensurePR creates a new PR when none is open', async () => {
-        const calls = []
-        const fetchImpl = async (url, opts) => {
-            calls.push({ url, method: opts?.method ?? 'GET' })
-            if (!opts?.method || opts.method === 'GET') return fakeResponse({ body: [] })
-            return fakeResponse({ status: 201, body: { number: 9, html_url: 'https://github.com/org/content/pull/9' } })
-        }
-        const pr = await ensurePR({ ...CTX, fetchImpl })
-        assert.deepEqual(pr, { number: 9, url: 'https://github.com/org/content/pull/9' })
-        assert.equal(calls.length, 2)
-        assert.equal(calls[1].method, 'POST')
-    })
-
-    it('ensurePR throws with a readable message when creation fails', async () => {
-        const fetchImpl = async (url, opts) => {
-            if (!opts?.method) return fakeResponse({ body: [] })
-            return fakeResponse({ ok: false, status: 422, body: { message: 'Validation failed' } })
-        }
-        await assert.rejects(ensurePR({ ...CTX, fetchImpl }), /Validation failed/)
-    })
-
-    it('mergePR reports merged:true on success', async () => {
-        const fetchImpl = async () => fakeResponse({ body: { merged: true, sha: 'abc' } })
-        const result = await mergePR({ owner: 'org', repo: 'content', number: 7, token: 'tok', fetchImpl })
-        assert.deepEqual(result, { merged: true })
-    })
-
-    it('mergePR reports merged:false with a reason on conflict', async () => {
-        const fetchImpl = async () => fakeResponse({ ok: false, status: 405, body: { message: 'Pull Request is not mergeable' } })
-        const result = await mergePR({ owner: 'org', repo: 'content', number: 7, token: 'tok', fetchImpl })
-        assert.equal(result.merged, false)
-        assert.match(result.reason, /not mergeable/)
-    })
-
-    it('mergePR falls back to statusText when the error body is not JSON', async () => {
-        const fetchImpl = async () => ({ ok: false, status: 500, statusText: 'Internal Server Error', json: async () => { throw new Error('not json') } })
-        const result = await mergePR({ owner: 'org', repo: 'content', number: 7, token: 'tok', fetchImpl })
-        assert.equal(result.merged, false)
-        assert.equal(result.reason, 'Internal Server Error')
-    })
-})

package/test/git.test.js

@@ -1,220 +0,0 @@
-// isNonFastForwardError is pure string-matching, tested directly.
-// Everything else in lib/git.js is a thin execFile wrapper — real
-// confidence there comes from exercising it against an actual git
-// repo in a temp directory. This only covers the LOCAL-only
-// operations (init, add, commit, status, branch) — clone/fetch/push
-// need a real remote and are exercised by hand against a real forge,
-// not in this suite.
-
-import { describe, it, before, after } from 'node:test'
-import assert from 'node:assert/strict'
-import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import path from 'node:path'
-
-import * as git from '../lib/git.js'
-
-describe('isNonFastForwardError', () => {
-    it('recognizes the common rejection messages', () => {
-        assert.ok(git.isNonFastForwardError({ stderr: '! [rejected] main -> main (non-fast-forward)' }))
-        assert.ok(git.isNonFastForwardError({ message: 'failed to push some refs (fetch first)' }))
-        assert.ok(git.isNonFastForwardError({ stderr: 'Updates were rejected because the tip of your current branch is behind' }))
-    })
-
-    it('does not misclassify an unrelated error', () => {
-        assert.equal(git.isNonFastForwardError({ message: 'fatal: repository not found' }), false)
-    })
-
-    it('handles a bare/malformed error object without throwing', () => {
-        assert.equal(git.isNonFastForwardError({}), false)
-        assert.equal(git.isNonFastForwardError(null), false)
-    })
-})
-
-describe('git.js against a real local repo', () => {
-    let dir
-
-    before(async () => {
-        dir = await mkdtemp(path.join(tmpdir(), 'mikser-git-'))
-        await git.run(dir, ['init', '-b', 'main'])
-        // Local-only identity so commit() works in a sandboxed CI
-        // environment with no global git user configured.
-        await git.run(dir, ['config', 'user.email', 'test@example.com'])
-        await git.run(dir, ['config', 'user.name', 'Test'])
-    })
-
-    after(async () => {
-        await rm(dir, { recursive: true, force: true })
-    })
-
-    it('an empty repo has no changes', async () => {
-        assert.equal(await git.hasChanges(dir), false)
-    })
-
-    it('a new file registers as a change', async () => {
-        await writeFile(path.join(dir, 'a.md'), 'hello')
-        assert.equal(await git.hasChanges(dir), true)
-        const status = await git.statusPorcelain(dir)
-        assert.match(status, /a\.md/)
-    })
-
-    it('addAll stages it, then commit records it', async () => {
-        await git.addAll(dir)
-        assert.equal(await git.hasStagedChanges(dir), true)
-        await git.commit(dir, 'first commit')
-        assert.equal(await git.hasChanges(dir), false)
-        assert.equal(await git.hasStagedChanges(dir), false)
-    })
-
-    it('currentBranch reports the init branch', async () => {
-        assert.equal(await git.currentBranch(dir), 'main')
-    })
-
-    it('checkoutBranch creates and switches to a new branch', async () => {
-        await git.checkoutBranch(dir, 'mikser', { create: true })
-        assert.equal(await git.currentBranch(dir), 'mikser')
-        assert.equal(await git.branchExistsLocal(dir, 'mikser'), true)
-        assert.equal(await git.branchExistsLocal(dir, 'nonexistent'), false)
-    })
-
-    it('a second file + commit round-trips through the same flow on the new branch', async () => {
-        await writeFile(path.join(dir, 'b.md'), 'world')
-        await git.addAll(dir)
-        await git.commit(dir, 'second commit')
-        assert.equal(await git.hasChanges(dir), false)
-        assert.equal(await git.revParse(dir, 'HEAD') !== '', true)
-    })
-
-    it('resetHard moves the branch tip and the working tree together', async () => {
-        const beforeReset = await git.revParse(dir, 'HEAD')
-        await writeFile(path.join(dir, 'c.md'), 'discard me')
-        await git.addAll(dir)
-        await git.commit(dir, 'to be discarded')
-        assert.notEqual(await git.revParse(dir, 'HEAD'), beforeReset)
-        await git.resetHard(dir, beforeReset)
-        assert.equal(await git.revParse(dir, 'HEAD'), beforeReset)
-    })
-})
-
-// The hard scope boundary the working-folder-as-checkout model depends
-// on: mikser.config.js, node_modules/, runtime/, out/, .env can live in
-// the SAME checkout this plugin manages, alongside collections it
-// SHOULD auto-commit (documents/, layouts/), as long as every git
-// operation is scoped to `paths`. Proven directly here, not assumed.
-describe('git.js pathspec scoping (paths param)', () => {
-    let dir
-
-    before(async () => {
-        dir = await mkdtemp(path.join(tmpdir(), 'mikser-git-scope-'))
-        await git.run(dir, ['init', '-b', 'main'])
-        await git.run(dir, ['config', 'user.email', 'test@example.com'])
-        await git.run(dir, ['config', 'user.name', 'Test'])
-        await mkdir(path.join(dir, 'documents'))
-        await mkdir(path.join(dir, 'node_modules'))
-        await writeFile(path.join(dir, 'mikser.config.js'), 'export default {}')
-        await writeFile(path.join(dir, 'documents', 'post.md'), 'hello')
-        await writeFile(path.join(dir, 'node_modules', 'dep.js'), 'module.exports = {}')
-        await git.addAll(dir)   // baseline commit — everything present so far
-        await git.commit(dir, 'baseline')
-    })
-
-    after(async () => {
-        await rm(dir, { recursive: true, force: true })
-    })
-
-    it('statusPorcelain with paths only reports changes inside the scope', async () => {
-        await writeFile(path.join(dir, 'documents', 'post.md'), 'edited')          // in scope
-        await writeFile(path.join(dir, 'mikser.config.js'), 'export default { x: 1 }')  // OUT of scope
-        await writeFile(path.join(dir, 'node_modules', 'dep.js'), 'changed')        // OUT of scope
-
-        const scoped = await git.statusPorcelain(dir, ['documents'])
-        assert.match(scoped, /post\.md/)
-        assert.doesNotMatch(scoped, /mikser\.config\.js/)
-        assert.doesNotMatch(scoped, /dep\.js/)
-
-        // Unscoped status proves the OTHER files really were dirty —
-        // the scoped call above wasn't just quiet because nothing changed.
-        const unscoped = await git.statusPorcelain(dir)
-        assert.match(unscoped, /mikser\.config\.js/)
-        assert.match(unscoped, /dep\.js/)
-    })
-
-    it('addAll with paths stages only the in-scope file — the config edit stays untracked', async () => {
-        await git.addAll(dir, ['documents'])
-        assert.equal(await git.hasStagedChanges(dir, ['documents']), true)
-        // Prove mikser.config.js's edit was NOT staged: the unscoped
-        // status must still show it as an unstaged modification (' M'),
-        // not staged ('M ').
-        const status = await git.statusPorcelain(dir)
-        assert.match(status, / M mikser\.config\.js/)
-        assert.doesNotMatch(status, /^M {2}mikser\.config\.js/m)
-
-        await git.commit(dir, 'documents-only change')
-
-        // The committed tree must NOT include the config edit or the
-        // node_modules change — only documents/post.md's new content.
-        const committed = await git.run(dir, ['show', '--stat', 'HEAD'])
-        assert.match(committed, /documents\/post\.md/)
-        assert.doesNotMatch(committed, /mikser\.config\.js/)
-        assert.doesNotMatch(committed, /dep\.js/)
-    })
-
-    it('a brand-new directory outside paths is invisible to a scoped add, even with --untracked-files=all', async () => {
-        await mkdir(path.join(dir, 'layouts'))
-        await writeFile(path.join(dir, 'layouts', 'post.hbs'), '<html></html>')
-
-        await git.addAll(dir, ['documents'])   // layouts/ deliberately not in scope
-        assert.equal(await git.hasStagedChanges(dir, ['documents']), false, 'nothing new in documents/ this round')
-        assert.equal(await git.hasStagedChanges(dir, ['layouts']), false, 'layouts/ was never staged — out of scope')
-
-        const unscoped = await git.statusPorcelain(dir)
-        assert.match(unscoped, /layouts\//)   // still genuinely untracked, just untouched by the scoped add
-    })
-})
-
-// The zero-config default (index.js's `paths` config omitted → resolveConfig
-// gives `null`): with NO pathspec at all, git.js's functions operate on the
-// whole repo. This proves the actual behavior that default implies —
-// something outside any collection folder DOES get staged when no `paths`
-// was configured, and .gitignore (not a pathspec) is what would keep
-// node_modules/.env out in that case. Distinct from the scoped-paths suite
-// above, which proves the OPPOSITE guarantee when paths IS given.
-describe('git.js with paths=null (the no-`paths`-configured default)', () => {
-    let dir
-
-    before(async () => {
-        dir = await mkdtemp(path.join(tmpdir(), 'mikser-git-noscope-'))
-        await git.run(dir, ['init', '-b', 'main'])
-        await git.run(dir, ['config', 'user.email', 'test@example.com'])
-        await git.run(dir, ['config', 'user.name', 'Test'])
-        await writeFile(path.join(dir, '.gitignore'), 'ignored-dir/\n')
-        await mkdir(path.join(dir, 'documents'))
-        await mkdir(path.join(dir, 'ignored-dir'))
-        await writeFile(path.join(dir, 'documents', 'post.md'), 'hello')
-        await writeFile(path.join(dir, 'mikser.config.js'), 'export default {}')
-        await writeFile(path.join(dir, 'ignored-dir', 'dep.js'), 'x')
-        await git.addAll(dir)   // no paths arg — baseline covers everything not gitignored
-        await git.commit(dir, 'baseline')
-    })
-
-    after(async () => {
-        await rm(dir, { recursive: true, force: true })
-    })
-
-    it('with no paths arg, an edit OUTSIDE any collection folder still gets staged', async () => {
-        await writeFile(path.join(dir, 'mikser.config.js'), 'export default { changed: true }')
-        await git.addAll(dir)   // no paths — the default-config behavior
-        assert.equal(await git.hasStagedChanges(dir), true)
-        const status = await git.statusPorcelain(dir)
-        assert.match(status, /^M {2}mikser\.config\.js/m)   // staged, not just modified
-    })
-
-    it('.gitignore, not a pathspec, is what keeps an ignored directory out — even unscoped', async () => {
-        await writeFile(path.join(dir, 'ignored-dir', 'dep.js'), 'changed')
-        await git.addAll(dir)
-        // The gitignored file's change never shows up at all, scoped or not —
-        // this is .gitignore doing the work, since there's no pathspec here.
-        const status = await git.statusPorcelain(dir)
-        assert.doesNotMatch(status, /dep\.js/)
-    })
-})

package/test/repo-url.test.js

@@ -1,35 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { parseRepoUrl } from '../lib/repo-url.js'
-
-describe('parseRepoUrl', () => {
-    it('parses a github.com URL and defaults apiOrigin to api.github.com', () => {
-        const r = parseRepoUrl('https://github.com/almero-digital-marketing/gpoint-content.git')
-        assert.deepEqual(r, { owner: 'almero-digital-marketing', repo: 'gpoint-content', apiOrigin: 'https://api.github.com' })
-    })
-
-    it('parses without the .git suffix identically', () => {
-        const r = parseRepoUrl('https://github.com/org/repo')
-        assert.equal(r.owner, 'org')
-        assert.equal(r.repo, 'repo')
-    })
-
-    it('a self-hosted Gitea URL uses its own origin as apiOrigin (adapter appends /api/v1)', () => {
-        const r = parseRepoUrl('https://git.almero.bg/org/content.git')
-        assert.deepEqual(r, { owner: 'org', repo: 'content', apiOrigin: 'https://git.almero.bg' })
-    })
-
-    it('tolerates a trailing slash', () => {
-        const r = parseRepoUrl('https://git.almero.bg/org/content/')
-        assert.equal(r.repo, 'content')
-    })
-
-    it('throws on a URL with no owner/repo path', () => {
-        assert.throws(() => parseRepoUrl('https://github.com/'), /cannot derive owner\/repo/)
-    })
-
-    it('throws on garbage input', () => {
-        assert.throws(() => parseRepoUrl('not a url'), /not a valid URL/)
-    })
-})