@moxxy/sdk 0.12.0 → 0.14.0

package/src/frontmatter.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest';
+import { parseFrontmatter, parseFrontmatterFile, renderFrontmatter } from './frontmatter.js';
+
+// Golden tests for the canonical frontmatter parser. This module replaced two
+// previously-copy-pasted copies (packages/core/src/skills/parse.ts and
+// packages/plugin-memory/src/parse.ts). The cases below pin the EXACT prior
+// behavior of the more-correct `core` copy: parse output fields, missing/blank
+// frontmatter handling, body offset, and the inline-array/scalar typing where
+// the two copies had diverged.
+describe('parseFrontmatterFile', () => {
+  it('returns empty frontmatter and original body when no fence present', () => {
+    const { frontmatter, body } = parseFrontmatterFile('hello world');
+    expect(frontmatter).toEqual({});
+    expect(body).toBe('hello world');
+  });
+
+  it('returns the original content unchanged when the closing fence is missing', () => {
+    const input = '---\nname: foo\nbody but no close';
+    const { frontmatter, body } = parseFrontmatterFile(input);
+    expect(frontmatter).toEqual({});
+    expect(body).toBe(input);
+  });
+
+  it('parses simple frontmatter and offsets the body past the closing fence', () => {
+    const { frontmatter, body } = parseFrontmatterFile(`---
+name: foo
+description: bar
+---
+body text`);
+    expect(frontmatter).toEqual({ name: 'foo', description: 'bar' });
+    expect(body).toBe('body text');
+  });
+
+  it('preserves a multiline body verbatim after the --- fence', () => {
+    const md = `---\nname: foo\ndescription: d\n---\nline 1\n\nline 2`;
+    const { body } = parseFrontmatterFile(md);
+    expect(body).toBe('line 1\n\nline 2');
+  });
+
+  it('treats an empty body after the fence as an empty string', () => {
+    const { frontmatter, body } = parseFrontmatterFile(`---\nname: foo\n---`);
+    expect(frontmatter).toEqual({ name: 'foo' });
+    expect(body).toBe('');
+  });
+
+  it('handles CRLF opening + closing fences', () => {
+    const { frontmatter, body } = parseFrontmatterFile('---\r\nname: foo\r\n---\r\nbody');
+    expect(frontmatter).toEqual({ name: 'foo' });
+    expect(body).toBe('body');
+  });
+
+  it('does not treat a leading "---" without a newline as a fence', () => {
+    const { frontmatter, body } = parseFrontmatterFile('---not a fence');
+    expect(frontmatter).toEqual({});
+    expect(body).toBe('---not a fence');
+  });
+});
+
+describe('parseFrontmatter', () => {
+  it('parses inline arrays with quoted commas (canonical splitArray behavior)', () => {
+    const fm = parseFrontmatter('triggers: [a, b, "c d"]');
+    expect(fm.triggers).toEqual(['a', 'b', 'c d']);
+  });
+
+  it('keeps a quoted comma inside one inline-array element (divergence fix)', () => {
+    // The diverged plugin-memory copy split on bare commas; the canonical
+    // (core) copy must keep "a, b" as a single element.
+    const fm = parseFrontmatter('tags: ["a, b", c]');
+    expect(fm.tags).toEqual(['a, b', 'c']);
+  });
+
+  it('parses nested inline arrays', () => {
+    const fm = parseFrontmatter('matrix: [[1, 2], [3, 4]]');
+    expect(fm.matrix).toEqual([
+      [1, 2],
+      [3, 4],
+    ]);
+  });
+
+  it('parses empty inline arrays', () => {
+    expect(parseFrontmatter('items: []').items).toEqual([]);
+  });
+
+  it('parses block-list arrays', () => {
+    const fm = parseFrontmatter('allowed-tools:\n  - Read\n  - Edit\n  - Bash');
+    expect(fm['allowed-tools']).toEqual(['Read', 'Edit', 'Bash']);
+  });
+
+  it('parses numbers, floats, booleans, and null', () => {
+    const fm = parseFrontmatter('count: 3\nratio: 1.5\nbig: true\nzero: false\nempty: null\ntwiddle: ~');
+    expect(fm.count).toBe(3);
+    expect(fm.ratio).toBe(1.5);
+    expect(fm.big).toBe(true);
+    expect(fm.zero).toBe(false);
+    expect(fm.empty).toBeNull();
+    expect(fm.twiddle).toBeNull();
+  });
+
+  it('strips quotes and tolerates colons inside quoted values', () => {
+    const fm = parseFrontmatter('description: "a: b"');
+    expect(fm.description).toBe('a: b');
+  });
+
+  it('skips blank lines, comments, and lines without a colon', () => {
+    const fm = parseFrontmatter('# a comment\n\nname: foo\nnocolon\ndescription: bar');
+    expect(fm).toEqual({ name: 'foo', description: 'bar' });
+  });
+
+  it('returns an empty object for blank frontmatter text', () => {
+    expect(parseFrontmatter('')).toEqual({});
+    expect(parseFrontmatter('   \n   ')).toEqual({});
+  });
+});
+
+describe('renderFrontmatter', () => {
+  it('renders scalars, arrays, and quotes values that need it', () => {
+    const rendered = renderFrontmatter({
+      name: 'foo',
+      tags: ['a', 'b'],
+      desc: 'a: b',
+      count: 3,
+    });
+    expect(rendered).toBe('---\nname: foo\ntags: [a, b]\ndesc: "a: b"\ncount: 3\n---');
+  });
+
+  it('skips null and undefined values', () => {
+    const rendered = renderFrontmatter({ name: 'foo', gone: null, missing: undefined });
+    expect(rendered).toBe('---\nname: foo\n---');
+  });
+
+  it('round-trips a representative document through render -> parse', () => {
+    const fm = { name: 'foo', description: 'a thing', tags: ['x', 'y'] };
+    const doc = `${renderFrontmatter(fm)}\n\nbody content\n`;
+    const parsed = parseFrontmatterFile(doc);
+    expect(parsed.frontmatter).toEqual(fm);
+    // The closing fence regex consumes `\n---\n`, so the blank line authored
+    // between the fence and the body survives in the body offset (unchanged
+    // historical behavior).
+    expect(parsed.body).toBe('\nbody content\n');
+  });
+});

package/src/frontmatter.ts

@@ -0,0 +1,159 @@
+/**
+ * Canonical minimal Markdown + YAML-subset frontmatter parser.
+ *
+ * Pure string work, zero dependencies (node builtins only). This is the single
+ * home for the mini-parser that was previously copy-pasted into
+ * `packages/core/src/skills/parse.ts` and `packages/plugin-memory/src/parse.ts`.
+ * The plugin-memory copy had diverged (its inline-array scalar split on bare
+ * commas and dropped null/float typing); this module keeps the more-correct
+ * `core` behavior — depth/quote-aware inline arrays via {@link splitArray},
+ * `null`/`~`, and float parsing — so both packages share one source of truth.
+ *
+ * Supports a deliberately tiny YAML subset:
+ *   - `key: value` scalars (string/number/float/bool/null, with quote stripping)
+ *   - inline arrays `key: [a, b, "c d"]` (depth- and quote-aware)
+ *   - block-list arrays (`key:` followed by `  - item` lines)
+ * Comments (`#`) and blank lines are skipped. Anything not recognized is left
+ * out of the frontmatter object.
+ */
+
+export interface ParsedFrontmatter {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+const FRONTMATTER_FENCE = '---';
+const OPENING_FENCE_LF = FRONTMATTER_FENCE + '\n';
+const OPENING_FENCE_CRLF = FRONTMATTER_FENCE + '\r\n';
+
+/**
+ * Split a `---`-fenced Markdown document into its parsed frontmatter and body.
+ *
+ * If the content does not open with a `---` fence (LF or CRLF), or the closing
+ * `---` is missing, returns `{ frontmatter: {}, body: <original content> }`
+ * unchanged. The body excludes the closing fence and its trailing newline.
+ */
+export function parseFrontmatterFile(content: string): ParsedFrontmatter {
+  if (!content.startsWith(OPENING_FENCE_LF) && !content.startsWith(OPENING_FENCE_CRLF)) {
+    return { frontmatter: {}, body: content };
+  }
+  const fenceLen = content.startsWith(OPENING_FENCE_CRLF) ? OPENING_FENCE_CRLF.length : OPENING_FENCE_LF.length;
+  const rest = content.slice(fenceLen);
+  const endMatch = /\r?\n---(?:\r?\n|$)/.exec(rest);
+  if (!endMatch) return { frontmatter: {}, body: content };
+  return {
+    frontmatter: parseFrontmatter(rest.slice(0, endMatch.index)),
+    body: rest.slice(endMatch.index + endMatch[0].length),
+  };
+}
+
+/** Parse the inner text of a frontmatter block into a key/value object. */
+export function parseFrontmatter(text: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = (lines[i] ?? '').trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const colon = trimmed.indexOf(':');
+    if (colon === -1) continue;
+    const key = trimmed.slice(0, colon).trim();
+    const raw = trimmed.slice(colon + 1).trim();
+
+    if (raw === '' && i + 1 < lines.length && /^\s*-\s/.test(lines[i + 1] ?? '')) {
+      const items: unknown[] = [];
+      while (i + 1 < lines.length && /^\s*-\s/.test(lines[i + 1] ?? '')) {
+        i += 1;
+        items.push(parseScalar((lines[i] ?? '').replace(/^\s*-\s*/, '').trim()));
+      }
+      result[key] = items;
+      continue;
+    }
+
+    result[key] = parseScalar(raw);
+  }
+  return result;
+}
+
+function parseScalar(v: string): unknown {
+  if (!v) return '';
+  if (v.startsWith('[') && v.endsWith(']')) {
+    const inner = v.slice(1, -1).trim();
+    if (!inner) return [];
+    return splitArray(inner).map((s) => parseScalar(s.trim()));
+  }
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  if (v === 'null' || v === '~') return null;
+  if (/^-?\d+$/.test(v)) return Number(v);
+  if (/^-?\d+\.\d+$/.test(v)) return Number(v);
+  return stripQuotes(v);
+}
+
+function stripQuotes(s: string): string {
+  if (s.length >= 2 && ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'")))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+/** Split a comma-separated inline-array body, honoring nesting and quotes. */
+function splitArray(s: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let buf = '';
+  let inStr: '"' | "'" | null = null;
+  for (const c of s) {
+    if (inStr) {
+      buf += c;
+      if (c === inStr) inStr = null;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      inStr = c;
+      buf += c;
+      continue;
+    }
+    if (c === '[' || c === '{') depth++;
+    if (c === ']' || c === '}') depth--;
+    if (c === ',' && depth === 0) {
+      out.push(buf);
+      buf = '';
+      continue;
+    }
+    buf += c;
+  }
+  if (buf.trim()) out.push(buf);
+  return out;
+}
+
+/**
+ * Render a frontmatter object back into a `---`-fenced YAML-subset block.
+ * Inverse-ish of {@link parseFrontmatter}; `undefined`/`null` values are
+ * skipped. (Used by callers that round-trip Markdown documents, e.g. the
+ * memory store.)
+ */
+export function renderFrontmatter(frontmatter: Record<string, unknown>): string {
+  const out: string[] = ['---'];
+  for (const [k, v] of Object.entries(frontmatter)) {
+    if (v === undefined || v === null) continue;
+    out.push(`${k}: ${renderValue(v)}`);
+  }
+  out.push('---');
+  return out.join('\n');
+}
+
+function renderValue(v: unknown): string {
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'string') {
+    return needsQuoting(v) ? `"${v.replace(/"/g, '\\"')}"` : v;
+  }
+  if (typeof v === 'boolean' || typeof v === 'number') return String(v);
+  if (Array.isArray(v)) {
+    return `[${v.map((x) => renderValue(x)).join(', ')}]`;
+  }
+  return JSON.stringify(v);
+}
+
+function needsQuoting(s: string): boolean {
+  return s.includes(':') || s.includes('#') || s.includes('"') || s.startsWith(' ') || s.endsWith(' ');
+}

package/src/fs-utils.test.ts

@@ -2,7 +2,7 @@ import { mkdtemp, readFile, readdir, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { moxxyHome, moxxyPath, writeFileAtomic } from './fs-utils.js';
+import { moxxyHome, moxxyPath, writeFileAtomic, writeFileAtomicSync } from './fs-utils.js';
 
 describe('writeFileAtomic', () => {
   let dir: string;
@@ -41,6 +41,52 @@ describe('writeFileAtomic', () => {
   });
 });
 
+describe('writeFileAtomicSync', () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'moxxy-fss-'));
+  });
+
+  it('writes content and creates missing parent dirs', async () => {
+    const target = join(dir, 'nested', 'deep', 'file.json');
+    writeFileAtomicSync(target, '{"a":1}');
+    expect(await readFile(target, 'utf8')).toBe('{"a":1}');
+  });
+
+  it('overwrites an existing file and leaves no temp file behind', async () => {
+    const target = join(dir, 'file.txt');
+    writeFileAtomicSync(target, 'first');
+    writeFileAtomicSync(target, 'second');
+    expect(await readFile(target, 'utf8')).toBe('second');
+    const leftovers = (await readdir(dir)).filter((n) => n.includes('.tmp'));
+    expect(leftovers).toEqual([]);
+  });
+
+  it('enforces the requested mode past umask', async () => {
+    const target = join(dir, 'secret.json');
+    writeFileAtomicSync(target, 'shh', { mode: 0o600 });
+    const mode = (await stat(target)).mode & 0o777;
+    expect(mode).toBe(0o600);
+  });
+
+  it('writes binary data unchanged', async () => {
+    const target = join(dir, 'bytes.bin');
+    writeFileAtomicSync(target, new Uint8Array([0, 1, 2, 255]));
+    expect(Array.from(await readFile(target))).toEqual([0, 1, 2, 255]);
+  });
+
+  it('cleans up the temp file and throws when rename fails', async () => {
+    // A directory in place of the final file makes renameSync fail; the temp
+    // file must be removed and the error surfaced rather than swallowed.
+    const { mkdir } = await import('node:fs/promises');
+    const target = join(dir, 'as-dir');
+    await mkdir(target);
+    expect(() => writeFileAtomicSync(target, 'nope')).toThrow();
+    const leftovers = (await readdir(dir)).filter((n) => n.includes('.tmp'));
+    expect(leftovers).toEqual([]);
+  });
+});
+
 describe('moxxyHome / moxxyPath', () => {
   const original = process.env.MOXXY_HOME;
   afterEach(() => {

package/src/fs-utils.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { chmod, mkdir, rename, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -40,6 +41,36 @@ export async function writeFileAtomic(
   }
 }
 
+/**
+ * Synchronous twin of {@link writeFileAtomic}, for the few call sites that
+ * cannot be async — boot/bootstrap and self-update gates that run before the
+ * event loop is the right tool. Same crash-atomic guarantee: write a unique
+ * sibling temp file, then `rename` it over the target. Hand-rolled
+ * `mkdirSync + writeFileSync(tmp) + renameSync` copies should call this instead.
+ */
+export function writeFileAtomicSync(
+  target: string,
+  data: string | Uint8Array,
+  opts: WriteFileAtomicOptions = {},
+): void {
+  mkdirSync(dirname(target), { recursive: true });
+  const tmp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(tmp, data, { encoding: opts.encoding ?? 'utf8' });
+    // chmod explicitly: writeFileSync's mode option is masked by umask, but a
+    // 0o600 secret file must be exactly 0o600 regardless of the host umask.
+    if (opts.mode != null) chmodSync(tmp, opts.mode);
+    renameSync(tmp, target);
+  } catch (err) {
+    try {
+      rmSync(tmp, { force: true });
+    } catch {
+      /* best-effort cleanup */
+    }
+    throw err;
+  }
+}
+
 /**
  * The moxxy home directory: `$MOXXY_HOME` when set, else `~/.moxxy`. Single
  * source of truth so the env override is honored uniformly — previously half

package/src/index.ts

@@ -173,7 +173,7 @@ export type {
   ViewTagSpec,
   ViewRendererDef,
 } from './view-renderer.js';
-export { VIEW_PRIMITIVES, VIEW_COMPONENTS, DEFAULT_VIEW_TAGS, isSafeViewUrl } from './view-renderer.js';
+export { VIEW_PRIMITIVES, VIEW_COMPONENTS, DEFAULT_VIEW_TAGS, isSafeViewUrl, countNodes } from './view-renderer.js';
 export type {
   TunnelProviderDef,
   TunnelHandle,
@@ -183,8 +183,21 @@ export type {
 } from './tunnel.js';
 export { spawnCliTunnel, isCliTunnelAvailable } from './tunnel.js';
 export { isRetryableError, toFriendlyError, zodToJsonSchema, estimateTextTokens, type StopReason } from './provider-utils.js';
-export { writeFileAtomic, moxxyHome, moxxyPath, type WriteFileAtomicOptions } from './fs-utils.js';
+export {
+  writeFileAtomic,
+  writeFileAtomicSync,
+  moxxyHome,
+  moxxyPath,
+  type WriteFileAtomicOptions,
+} from './fs-utils.js';
 export { createMutex, type Mutex } from './mutex.js';
+export {
+  createJsonFileStore,
+  type JsonFileStore,
+  type JsonFileStoreOptions,
+} from './json-file-store.js';
+export { assertNever } from './assert.js';
+export { compareSemver, parseSemverCore } from './semver.js';
 export { readRequestBody, bearerTokenMatches } from './http-utils.js';
 export {
   resolveChannelToken,
@@ -435,6 +448,13 @@ export {
   type MoxxyPackageInput,
 } from './schemas.js';
 
+export {
+  parseFrontmatterFile,
+  parseFrontmatter,
+  renderFrontmatter,
+  type ParsedFrontmatter,
+} from './frontmatter.js';
+
 export {
   getInstallHint,
   type InstallHint,

package/src/json-file-store.test.ts

@@ -0,0 +1,207 @@
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { createJsonFileStore } from './json-file-store.js';
+
+interface Item {
+  id: string;
+  n: number;
+}
+
+const itemSchema = z.object({ id: z.string(), n: z.number() });
+const fileSchema = z.object({ version: z.literal(1), items: z.array(itemSchema) });
+
+/** A `load` that mirrors the scheduler policy: corrupt/invalid -> empty. */
+function lenientLoad(raw: string | null): Item[] {
+  if (raw === null) return [];
+  try {
+    const parsed = fileSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? [...parsed.data.items] : [];
+  } catch {
+    return [];
+  }
+}
+
+describe('createJsonFileStore', () => {
+  let dir: string;
+  let file: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'moxxy-jfs-'));
+    file = join(dir, 'sub', 'store.json');
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  function store() {
+    return createJsonFileStore<Item>({ file, load: lenientLoad });
+  }
+
+  it('returns an empty list when the file is missing (ENOENT)', async () => {
+    expect(await store().read()).toEqual([]);
+  });
+
+  it('persists { version: 1, items } pretty-printed and creates parent dirs', async () => {
+    const s = store();
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }]);
+    const raw = await readFile(file, 'utf8');
+    expect(JSON.parse(raw)).toEqual({ version: 1, items: [{ id: 'a', n: 1 }] });
+    // pretty-printed with 2-space indent
+    expect(raw).toContain('\n  "version": 1');
+    // a fresh instance reads the persisted state back
+    expect(await store().read()).toEqual([{ id: 'a', n: 1 }]);
+  });
+
+  it('get() finds by id and returns null for misses', async () => {
+    const s = store();
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }, { id: 'b', n: 2 }]);
+    expect(await s.get('b')).toEqual({ id: 'b', n: 2 });
+    expect(await s.get('zzz')).toBeNull();
+  });
+
+  it('read() and the mutator each get a fresh copy (caller cannot mutate cache)', async () => {
+    const s = store();
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }]);
+
+    // Mutating the array returned by read() must not affect the store.
+    const snap = await s.read();
+    snap.push({ id: 'evil', n: 99 });
+    expect(await s.read()).toEqual([{ id: 'a', n: 1 }]);
+
+    // The mutator receives a fresh slice; pushing into it then returning a
+    // DIFFERENT array means the push is discarded (proves it's a copy, not the
+    // live cache).
+    await s.mutate((items) => {
+      items.push({ id: 'discarded', n: -1 });
+      return [{ id: 'a', n: 2 }];
+    });
+    expect(await s.read()).toEqual([{ id: 'a', n: 2 }]);
+  });
+
+  it('serializes concurrent mutate() calls so neither clobbers the other', async () => {
+    const s = store();
+    // Fire many overlapping appends. Without the mutex these read the same
+    // baseline and the last write wins, dropping entries.
+    await Promise.all(
+      Array.from({ length: 25 }, (_, i) =>
+        s.mutate((items) => [...items, { id: `k${i}`, n: i }]),
+      ),
+    );
+    const all = await s.read();
+    expect(all).toHaveLength(25);
+    expect(new Set(all.map((x) => x.id)).size).toBe(25);
+    // The on-disk file agrees (every write landed atomically).
+    const onDisk = JSON.parse(await readFile(file, 'utf8')) as { items: Item[] };
+    expect(onDisk.items).toHaveLength(25);
+  });
+
+  it('leaves the prior file intact when serializing the new state throws', async () => {
+    const s = store();
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }]);
+    const before = await readFile(file, 'utf8');
+
+    // A value JSON.stringify cannot serialize (BigInt) makes the persist throw
+    // before any bytes hit disk; the previously-persisted file must survive.
+    await expect(
+      s.mutate(() => [{ id: 'bad', n: 1n as unknown as number }]),
+    ).rejects.toThrow();
+
+    expect(await readFile(file, 'utf8')).toBe(before);
+    const leftovers = (await readdir(join(dir, 'sub'))).filter((n) => n.includes('.tmp'));
+    expect(leftovers).toEqual([]);
+  });
+
+  it('leaves the prior file intact when the atomic rename fails mid-write', async () => {
+    const s = store();
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }]);
+    const before = await readFile(file, 'utf8');
+
+    // Replace the parent dir's write path: make the TARGET a directory so the
+    // temp-file rename throws. We can't do that to `file` itself without losing
+    // the prior copy, so use a sibling store whose target is a directory and
+    // assert no temp file is orphaned. The original store's file is untouched.
+    const sib = join(dir, 'sub', 'sibling');
+    await mkdir(sib, { recursive: true });
+    const s2 = createJsonFileStore<Item>({ file: sib, load: lenientLoad });
+    await expect(s2.mutate((items) => [...items, { id: 'x', n: 1 }])).rejects.toThrow();
+
+    // No orphaned temp files, and the unrelated prior file is intact.
+    const leftovers = (await readdir(join(dir, 'sub'))).filter((n) => n.includes('.tmp'));
+    expect(leftovers).toEqual([]);
+    expect(await readFile(file, 'utf8')).toBe(before);
+  });
+
+  it('lenient load resets a corrupt file to empty (scheduler policy)', async () => {
+    await mkdir(join(dir, 'sub'), { recursive: true });
+    await writeFile(file, '{ not json', 'utf8');
+    const s = store();
+    expect(await s.read()).toEqual([]);
+    // The bad file is left in place until the next write.
+    expect(await readFile(file, 'utf8')).toBe('{ not json');
+  });
+
+  it('lenient load resets a schema-mismatched file to empty', async () => {
+    await mkdir(join(dir, 'sub'), { recursive: true });
+    await writeFile(file, JSON.stringify({ version: 99, items: [] }), 'utf8');
+    expect(await store().read()).toEqual([]);
+  });
+
+  it('onReadError lets a store refuse to operate on a non-ENOENT read error', async () => {
+    // Point the store at a directory so readFile throws EISDIR (not ENOENT).
+    const asDir = join(dir, 'as-dir');
+    await mkdir(asDir, { recursive: true });
+    const s = createJsonFileStore<Item>({
+      file: asDir,
+      load: lenientLoad,
+      onReadError: (err) => {
+        throw new Error(`refusing: ${(err as NodeJS.ErrnoException).code}`);
+      },
+    });
+    await expect(s.read()).rejects.toThrow(/refusing:/);
+  });
+
+  it('re-throws a non-ENOENT read error by default (no onReadError)', async () => {
+    const asDir = join(dir, 'as-dir2');
+    await mkdir(asDir, { recursive: true });
+    const s = createJsonFileStore<Item>({ file: asDir, load: lenientLoad });
+    await expect(s.read()).rejects.toThrow();
+  });
+
+  it('honors a custom itemsKey, fileFields, stringify and writeOptions', async () => {
+    const f = join(dir, 'custom.json');
+    const s = createJsonFileStore<Item>({
+      file: f,
+      itemsKey: 'rows',
+      fileFields: {},
+      stringify: (obj) => JSON.stringify(obj) + '\n',
+      writeOptions: { mode: 0o600 },
+      load: (raw) => {
+        if (raw === null) return [];
+        const obj = JSON.parse(raw) as { rows: Item[] };
+        return obj.rows;
+      },
+    });
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }]);
+    const raw = await readFile(f, 'utf8');
+    // versionless, name-key `rows`, compact, trailing newline
+    expect(raw).toBe('{"rows":[{"id":"a","n":1}]}\n');
+    const { stat } = await import('node:fs/promises');
+    expect((await stat(f)).mode & 0o777).toBe(0o600);
+  });
+
+  it('invalidate() forces a re-read from disk', async () => {
+    const s = store();
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }]);
+    // Write a second entry directly to disk behind the store's back.
+    await writeFile(file, JSON.stringify({ version: 1, items: [{ id: 'b', n: 2 }] }), 'utf8');
+    // Stale cache still shows the first entry…
+    expect(await s.read()).toEqual([{ id: 'a', n: 1 }]);
+    s.invalidate();
+    // …until invalidated.
+    expect(await s.read()).toEqual([{ id: 'b', n: 2 }]);
+  });
+});