mikser-io-git 2.1.0

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "mikser-io-git",
+  "version": "2.1.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",
+  "type": "module",
+  "scripts": {
+    "test": "node --no-warnings --test --test-reporter=spec 'test/**/*.test.js'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/almero-digital-marketing/mikser-io-git.git"
+  },
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/almero-digital-marketing/mikser-io-git/issues"
+  },
+  "homepage": "https://github.com/almero-digital-marketing/mikser-io-git#readme",
+  "peerDependencies": {
+    "mikser-io": "^9.0.0"
+  }
+}

package/test/bootstrap.test.js

@@ -0,0 +1,59 @@
+// 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

@@ -0,0 +1,101 @@
+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

@@ -0,0 +1,57 @@
+// 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

@@ -0,0 +1,32 @@
+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

@@ -0,0 +1,91 @@
+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

@@ -0,0 +1,70 @@
+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

@@ -0,0 +1,220 @@
+// 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/)
+    })
+})