canopycms 0.0.68-int.98 → 0.1.0

package/dist/utils/content-write-lock.js

@@ -29,6 +29,7 @@
  * Mutual exclusion is not proven: on EFS a stale cached mtime lets a waiter take over a live lock,
  * leaving two unsynchronized writers -- the unlocked behaviour, so still a strict improvement.
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import path from 'node:path';
 import { getErrorMessage, isNodeError } from './error.js';
 import { canopyLogWarn } from './logger.js';
@@ -51,7 +52,7 @@ const CONTENT_WRITE_LOCK_NAME = 'content-write.lock';
  * `next dev` and build-time provisioning across worker processes. The case to watch is a write
  * whose in-lock path triggers a full `idIndex()` rescan of a large tree over EFS, which can exceed
  * this budget and start 409ing unrelated saves. Making it configurable is tracked in
- * .claude/future-tasks/content-write-lock-tuning-and-granularity.md.
+ * safeinsights/canopycms#640.
  */
 export const DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS = 2000;
 /**
@@ -65,7 +66,7 @@ export const DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS = 2000;
  * load-bearing rather than cosmetic.
  */
 export class ContentWriteLockBusyError extends Error {
-    constructor(message = 'This branch is busy (syncing with the base branch, or another save is in flight); the change was not saved. Try again in a moment.', 
+    constructor(message = 'This branch is busy syncing or saving another change, so your change was not saved. Try again in a moment.', 
     /**
      * `'not-run'`: the lock was never acquired, so nothing happened. `'unknown'`: the work ran
      * but the lock was lost during it (see {@link withContentWriteLock}).
@@ -91,7 +92,7 @@ const CONTENT_WRITE_LOCK_STALE_MS = 30_000;
  * skips the branch and retries next cycle. Throws with `code === 'ELOCKED'` on a live holder.
  */
 export function tryAcquireContentWriteLock(branchRoot, onCompromised) {
-    return tryAcquireProvisioningLock(lockTargetDir(branchRoot), CONTENT_WRITE_LOCK_NAME, onCompromised, CONTENT_WRITE_LOCK_STALE_MS);
+    return tryAcquireProvisioningLock(lockTargetDir(branchRoot), CONTENT_WRITE_LOCK_NAME, onCompromised, CONTENT_WRITE_LOCK_STALE_MS, false);
 }
 /**
  * Acquire the branch's content-write lock with a short bounded wait.
@@ -121,6 +122,17 @@ async function acquireContentWriteLock(branchRoot, waitMs = DEFAULT_CONTENT_WRIT
         }
     }
 }
+/** The branch roots whose content-write lock the current async call chain holds. */
+const heldRoots = new AsyncLocalStorage();
+/**
+ * Throw unless the calling async chain runs inside {@link withContentWriteLock} for `branchRoot`:
+ * the check for code that writes under a lock its caller took.
+ */
+export function assertContentWriteLockHeld(branchRoot) {
+    if (heldRoots.getStore()?.has(path.resolve(branchRoot)))
+        return;
+    throw new Error(`The content-write lock for ${branchRoot} is not held by this call`);
+}
 /** Run `fn` holding the branch's content-write lock, releasing in a `finally` so a throw cannot
  * strand it. */
 export async function withContentWriteLock(branchRoot, fn, waitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS) {
@@ -135,7 +147,9 @@ export async function withContentWriteLock(branchRoot, fn, waitMs = DEFAULT_CONT
     });
     let result;
     try {
-        result = await fn();
+        const held = new Set(heldRoots.getStore());
+        held.add(path.resolve(branchRoot));
+        result = await heldRoots.run(held, fn);
     }
     finally {
         await release();
@@ -144,8 +158,9 @@ export async function withContentWriteLock(branchRoot, fn, waitMs = DEFAULT_CONT
         // Deliberately NOT the default "was not saved" message: `fn()` completed, so the write is on
         // disk and only the proof of exclusivity is lost. "Reload, then decide" rather than "retry",
         // which would resend a now-stale expectedVersion and bounce off the caller's own landed write
-        // as a phantom editor collision.
-        throw new ContentWriteLockBusyError('This branch was being synced while your change was written, so the change may or may not have been recorded. Reload the entry to see the current state before saving again.', 'unknown');
+        // as a phantom editor collision. The API marks this case `WRITE_OUTCOME_UNKNOWN` so the
+        // editor can hold further saves of the entry until it is re-read.
+        throw new ContentWriteLockBusyError("We couldn't confirm your change was saved because the branch was syncing at the same time. Reload to check before saving again (your unsaved edits will be lost).", 'unknown');
     }
     return result;
 }

package/dist/utils/debug.d.ts

@@ -41,6 +41,6 @@ export declare class DebugLogger {
 export declare function createDebugLogger(options?: DebugOptions): DebugLogger;
 /**
  * Default logger for E2E test infrastructure.
- * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
+ * @internal No importer; deletion candidate in safeinsights/canopycms#725.
  */
 export declare const testLogger: DebugLogger;

package/dist/utils/debug.js

@@ -1,3 +1,5 @@
+/** False where no `process` exists: a browser bundle with no shim for it, such as Storybook's. */
+const envFlag = (name) => typeof process !== 'undefined' && process.env[name] === 'true';
 const LOG_LEVELS = {
     DEBUG: 0,
     INFO: 1,
@@ -11,7 +13,7 @@ export class DebugLogger {
     }
     shouldLog(level) {
         // Check enabled at call time to support runtime env var changes
-        const enabled = this.options.enabled ?? process.env.CANOPYCMS_DEBUG === 'true';
+        const enabled = this.options.enabled ?? envFlag('CANOPYCMS_DEBUG');
         if (!enabled)
             return false;
         const minLevel = this.options.minLevel ?? 'DEBUG';
@@ -92,10 +94,10 @@ export function createDebugLogger(options) {
 }
 /**
  * Default logger for E2E test infrastructure.
- * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
+ * @internal No importer; deletion candidate in safeinsights/canopycms#725.
  */
 export const testLogger = createDebugLogger({
-    enabled: process.env.E2E_DEBUG === 'true',
+    enabled: envFlag('E2E_DEBUG'),
     prefix: 'E2E',
     throwOnError: false,
 });

package/dist/utils/error.js

@@ -30,11 +30,15 @@ export function getErrorMessage(err) {
  */
 export function sanitizeErrorMessage(message) {
     let result = redactCredentials(message);
+    // `file://` URLs (ESM and dev-bundle stack frames) carry an absolute path the POSIX rule below
+    // skips, since it leaves URL slashes alone.
+    result = result.replace(/\bfile:\/\/[^\s'")]*/g, '<path>');
     // Paths under the project root become relative (split/join avoids regex-escaping issues with
     // arbitrary cwd values). The bare-cwd replacement is anchored to a token boundary so a sibling
     // directory that merely shares the cwd prefix (`${cwd}-other/…`) stays absolute and is fully
-    // redacted below instead of leaking a mangled remainder.
-    const cwd = process.cwd();
+    // redacted below instead of leaking a mangled remainder. The editor calls this in a browser,
+    // where `process.cwd` may not exist.
+    const cwd = typeof process !== 'undefined' && typeof process.cwd === 'function' ? process.cwd() : '/';
     if (cwd !== '/') {
         result = result.split(`${cwd}/`).join('');
         const cwdPattern = cwd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -73,6 +77,13 @@ export function redactCredentials(message) {
     // literal `://` (leaving the scheme untouched) — a `\w+` scheme prefix backtracks
     // polynomially on long word-character runs (CodeQL js/polynomial-redos).
     result = result.replace(/(:\/\/)[^/\s@]+@/g, '$1***@');
+    // An `Authorization` header's credential: the worker's GitHub-bound git carries the token as
+    // `AUTHORIZATION: basic <base64>` (worker/github-mirror.ts).
+    result = result.replace(/(\bauthorization\s*:\s*(?:basic|bearer|token)\s+)[A-Za-z0-9+/=._~-]+/gi, '$1***');
+    // That header's base64 of `x-access-token:<token>` wherever it appears on its own, URL-encoded
+    // too. The 15-byte prefix encodes to the same 20 characters whatever the token, with no padding
+    // to shift it.
+    result = result.replace(/eC1hY2Nlc3MtdG9rZW46(?:[A-Za-z0-9+/]|%2[BbFf])*(?:=|%3[Dd]){0,2}/g, '***');
     // Bare token shapes, for messages embedding a token outside URL userinfo: GitHub token
     // prefixes and Bearer values.
     result = result.replace(/\b(?:gh[pousr]|github_pat)_[A-Za-z0-9_]{8,}/g, '***');

package/dist/utils/escape-text.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `text` on one line, every character outside printable ASCII escaped (`\n`, `\t`, `\r`, `\xHH`,
+ * `\u{H}`), and `\` doubled so an escape cannot be forged. Bidi controls and zero-width characters
+ * are outside printable ASCII too, so a branch name cannot reorder or hide part of a line. Pure,
+ * so the editor uses it too, to show a GitHub-sourced name as exactly what it is.
+ */
+export declare function escapeForLog(text: string): string;

package/dist/utils/escape-text.js

@@ -0,0 +1,27 @@
+/**
+ * `text` on one line, every character outside printable ASCII escaped (`\n`, `\t`, `\r`, `\xHH`,
+ * `\u{H}`), and `\` doubled so an escape cannot be forged. Bidi controls and zero-width characters
+ * are outside printable ASCII too, so a branch name cannot reorder or hide part of a line. Pure,
+ * so the editor uses it too, to show a GitHub-sourced name as exactly what it is.
+ */
+export function escapeForLog(text) {
+    let out = '';
+    for (const char of text) {
+        const code = char.codePointAt(0) ?? 0;
+        if (char === '\\')
+            out += '\\\\';
+        else if (code >= 0x20 && code <= 0x7e)
+            out += char;
+        else if (char === '\n')
+            out += '\\n';
+        else if (char === '\t')
+            out += '\\t';
+        else if (char === '\r')
+            out += '\\r';
+        else if (code <= 0xff)
+            out += `\\x${code.toString(16).padStart(2, '0')}`;
+        else
+            out += `\\u{${code.toString(16)}}`;
+    }
+    return out;
+}

package/dist/utils/fs.d.ts

@@ -1,8 +1,16 @@
 /** Check if a path exists on disk. */
 export declare function filePathExists(filePath: string): Promise<boolean>;
 /**
- * Read a UTF-8 file, or undefined if it does not exist. Only ENOENT is swallowed — a
- * permissions or I/O failure still throws, so a caller cannot mistake "unreadable" for
- * "not there yet".
+ * Read a UTF-8 file and its mtime from ONE open, or undefined if it does not exist. Only ENOENT
+ * is swallowed — a permissions or I/O failure still throws, so a caller cannot mistake
+ * "unreadable" for "not there yet".
+ *
+ * The mtime comes from the open handle, not a path `stat`: opening a file on NFS checks it against
+ * the server (close-to-open, nfs(5)), where a path `stat` can be answered from the client's
+ * attribute cache for a file another host has since replaced or deleted. So the mtime
+ * and the bytes describe the same file, as the server has it.
  */
-export declare function readFileIfExists(filePath: string): Promise<string | undefined>;
+export declare function readFileWithMtimeIfExists(filePath: string): Promise<{
+    content: string;
+    mtimeMs: number;
+} | undefined>;

package/dist/utils/fs.js

@@ -13,17 +13,30 @@ export async function filePathExists(filePath) {
     }
 }
 /**
- * Read a UTF-8 file, or undefined if it does not exist. Only ENOENT is swallowed — a
- * permissions or I/O failure still throws, so a caller cannot mistake "unreadable" for
- * "not there yet".
+ * Read a UTF-8 file and its mtime from ONE open, or undefined if it does not exist. Only ENOENT
+ * is swallowed — a permissions or I/O failure still throws, so a caller cannot mistake
+ * "unreadable" for "not there yet".
+ *
+ * The mtime comes from the open handle, not a path `stat`: opening a file on NFS checks it against
+ * the server (close-to-open, nfs(5)), where a path `stat` can be answered from the client's
+ * attribute cache for a file another host has since replaced or deleted. So the mtime
+ * and the bytes describe the same file, as the server has it.
  */
-export async function readFileIfExists(filePath) {
+export async function readFileWithMtimeIfExists(filePath) {
+    let handle;
     try {
-        return await fs.readFile(filePath, 'utf8');
+        handle = await fs.open(filePath, 'r');
     }
     catch (err) {
         if (isNotFoundError(err))
             return undefined;
         throw err;
     }
+    try {
+        const { mtimeMs } = await handle.stat();
+        return { content: await handle.readFile('utf8'), mtimeMs };
+    }
+    finally {
+        await handle.close();
+    }
 }

package/dist/utils/git.d.ts

@@ -47,6 +47,10 @@ export declare function isStaleLeaseRejection(message: string): boolean;
  * GitHub refuses only content it does not already hold: carrying a base-branch workflow change by
  * rebase, merge or fast-forward is accepted. Retrying the identical push can never succeed, so the
  * worker fails it fast. The text is GitHub's own, not git's, so no locale pinning is needed.
+ *
+ * A scan of each line's backquote-delimited spans, linear in the message, which is git's output of
+ * any length: this rule as a regex, with its run between lead and tail, is quadratic on a line
+ * that repeats the lead without the tail.
  */
 export declare function workflowPushRefusalFile(message: string): string | null;
 /**
@@ -76,6 +80,10 @@ export declare function isCanopyInternalPath(repoRelativePath: string): boolean;
  * {@link CANOPY_META_DIR}, including files an adopter committed there by mistake. Stage-all then
  * unstage, because git rejects `:(exclude)` pathspecs (six spellings tried) with "paths are ignored" when
  * the excluded directory is itself ignored, which `.git/info/exclude` makes it in every clone.
+ *
+ * `--sparse`: in a sparse clone a plain `add -A` fails on any file present outside the cone.
+ * With it, such a file is staged like any other, and a tracked file absent only because it is
+ * outside the cone is still not staged as a deletion. A no-op in a full clone.
  */
 export declare function stageAllExceptCanopyState(git: SimpleGit): Promise<void>;
 /**
@@ -96,12 +104,22 @@ export declare function isRebaseInProgress(repoPath: string): Promise<boolean>;
  * detached.
  */
 export declare function detectHeadBranch(repoRoot: string, fallback?: string): Promise<string>;
+/**
+ * The branch the HEAD of the repository at `gitDir` names; for a bare repo, its default branch.
+ * Throws when HEAD is detached, unreadable, or names a branch with no commit.
+ *
+ * `--git-dir` rather than cwd discovery, which `safe.bareRepository=explicit` refuses for bare
+ * repos. `git` is how the worker passes the instance it runs a shared repository with.
+ */
+export declare function readHeadBranch(gitDir: string, git?: SimpleGit): Promise<string>;
 /**
  * Resolve the base branch — the fork point for CMS editing branches and the branch workspace
  * clones are seeded from. The single definition of base-branch behavior (see ARCHITECTURE.md
  * "Branch Identity"): a configured `defaultBaseBranch` always wins in both modes; dev mode
  * otherwise detects the current git HEAD, so workspaces fork from the developer's checked-out
- * branch; otherwise 'main'.
+ * branch, falling back to 'main'; prod otherwise reads the HEAD of `remoteGitDir`, the bare repo
+ * the workspaces clone from, and throws when it is not given one or cannot read it. Prod never
+ * assumes 'main'.
  *
  * Static deployments never reach git operations, so callers on static paths must short-circuit
  * before calling this (see createCanopyServices).
@@ -111,4 +129,6 @@ export declare function resolveBaseBranch(options: {
     mode: OperatingMode;
     /** Repo root used for dev-mode HEAD detection. Defaults to process.cwd(). */
     detectFrom?: string;
+    /** Prod: the local bare remote whose HEAD names the base branch (GitManager.detectBaseBranch). */
+    remoteGitDir?: string;
 }): Promise<string>;

package/dist/utils/git.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { simpleGit } from 'simple-git';
+import { BaseBranchUnresolvedError } from './base-branch.js';
+import { getErrorMessage } from './error.js';
 const NETWORK_SCHEME_PATTERN = /^(https?|ssh|git):\/\//i;
 // git's "transport helper" syntax (`ext::sh -c ...`, `fd::7`): any `scheme::` prefix hands the
 // URL to `git-remote-<scheme>`, which can run arbitrary commands — always network/untrusted.
@@ -88,10 +90,11 @@ const STALE_LEASE_REASON = 'stale info';
 export function isStaleLeaseRejection(message) {
     return message.includes(REJECTED_MARKER) && message.includes(STALE_LEASE_REASON);
 }
-// GitHub's reason text when a push would introduce workflow content the credential may not write.
-// It names the credential kind ("a GitHub App", "an OAuth App", ...) and then the file.
-// Both classes stop at a newline, so the match stays on the one status line that carries it.
-const WORKFLOW_REFUSAL_PATTERN = /refusing to allow an? [^`\n]+? to create or update workflow `([^`\n]+)`/;
+// GitHub's reason text when a push would introduce workflow content the credential may not write:
+// `refusing to allow <credential kind> to create or update workflow `<file>``, where the kind
+// ("a GitHub App", "an OAuth App", ...) holds no backquote and the file is the next quoted span.
+const WORKFLOW_REFUSAL_LEADS = ['refusing to allow a ', 'refusing to allow an '];
+const WORKFLOW_REFUSAL_TAIL = ' to create or update workflow ';
 /**
  * The workflow file named by GitHub's refusal of a push that would add workflow content the
  * credential lacks the workflows permission for, or null if the message is not that refusal.
@@ -99,9 +102,30 @@ const WORKFLOW_REFUSAL_PATTERN = /refusing to allow an? [^`\n]+? to create or up
  * GitHub refuses only content it does not already hold: carrying a base-branch workflow change by
  * rebase, merge or fast-forward is accepted. Retrying the identical push can never succeed, so the
  * worker fails it fast. The text is GitHub's own, not git's, so no locale pinning is needed.
+ *
+ * A scan of each line's backquote-delimited spans, linear in the message, which is git's output of
+ * any length: this rule as a regex, with its run between lead and tail, is quadratic on a line
+ * that repeats the lead without the tail.
  */
 export function workflowPushRefusalFile(message) {
-    return WORKFLOW_REFUSAL_PATTERN.exec(message)?.[1] ?? null;
+    for (const line of message.split('\n')) {
+        const spans = line.split('`');
+        // The last span is closed by no backquote, so the file can be at most the one before it.
+        for (let i = 0; i + 2 < spans.length; i++) {
+            const span = spans[i];
+            const file = spans[i + 1];
+            if (file === '' || !span.endsWith(WORKFLOW_REFUSAL_TAIL))
+                continue;
+            const head = span.slice(0, -WORKFLOW_REFUSAL_TAIL.length);
+            const named = WORKFLOW_REFUSAL_LEADS.some((lead) => {
+                const at = head.indexOf(lead);
+                return at !== -1 && at + lead.length < head.length;
+            });
+            if (named)
+                return file;
+        }
+    }
+    return null;
 }
 // git's message when `git fetch <remote> <branch>` names a ref the remote does not have. Both
 // spellings occur: modern git prints the lowercase form, older versions and some transports
@@ -168,9 +192,13 @@ export function isCanopyInternalPath(repoRelativePath) {
  * {@link CANOPY_META_DIR}, including files an adopter committed there by mistake. Stage-all then
  * unstage, because git rejects `:(exclude)` pathspecs (six spellings tried) with "paths are ignored" when
  * the excluded directory is itself ignored, which `.git/info/exclude` makes it in every clone.
+ *
+ * `--sparse`: in a sparse clone a plain `add -A` fails on any file present outside the cone.
+ * With it, such a file is staged like any other, and a tracked file absent only because it is
+ * outside the cone is still not staged as a deletion. A no-op in a full clone.
  */
 export async function stageAllExceptCanopyState(git) {
-    await git.add(['-A']);
+    await git.raw(['add', '-A', '--sparse']);
     await git.raw(['reset', '-q', '--', CANOPY_META_DIR]);
 }
 /**
@@ -209,12 +237,30 @@ export async function detectHeadBranch(repoRoot, fallback = 'main') {
         return fallback;
     }
 }
+/**
+ * The branch the HEAD of the repository at `gitDir` names; for a bare repo, its default branch.
+ * Throws when HEAD is detached, unreadable, or names a branch with no commit.
+ *
+ * `--git-dir` rather than cwd discovery, which `safe.bareRepository=explicit` refuses for bare
+ * repos. `git` is how the worker passes the instance it runs a shared repository with.
+ */
+export async function readHeadBranch(gitDir, git = simpleGit()) {
+    const ref = (await git.raw(['--git-dir', gitDir, 'symbolic-ref', 'HEAD'])).trim();
+    if (!ref.startsWith('refs/heads/')) {
+        throw new Error(`its HEAD does not name a branch (${ref || 'empty'})`);
+    }
+    // No `--quiet`: simple-git rejects only on a non-zero exit WITH stderr output.
+    await git.raw(['--git-dir', gitDir, 'rev-parse', '--verify', `${ref}^{commit}`]);
+    return ref.slice('refs/heads/'.length);
+}
 /**
  * Resolve the base branch — the fork point for CMS editing branches and the branch workspace
  * clones are seeded from. The single definition of base-branch behavior (see ARCHITECTURE.md
  * "Branch Identity"): a configured `defaultBaseBranch` always wins in both modes; dev mode
  * otherwise detects the current git HEAD, so workspaces fork from the developer's checked-out
- * branch; otherwise 'main'.
+ * branch, falling back to 'main'; prod otherwise reads the HEAD of `remoteGitDir`, the bare repo
+ * the workspaces clone from, and throws when it is not given one or cannot read it. Prod never
+ * assumes 'main'.
  *
  * Static deployments never reach git operations, so callers on static paths must short-circuit
  * before calling this (see createCanopyServices).
@@ -225,5 +271,14 @@ export async function resolveBaseBranch(options) {
     if (options.mode === 'dev') {
         return detectHeadBranch(options.detectFrom ?? process.cwd());
     }
-    return 'main';
+    if (!options.remoteGitDir) {
+        throw new BaseBranchUnresolvedError('defaultBaseBranch is not set, and no remote was given to read the base branch from.');
+    }
+    try {
+        return await readHeadBranch(options.remoteGitDir);
+    }
+    catch (err) {
+        throw new BaseBranchUnresolvedError(`defaultBaseBranch is not set, and the base branch could not be read from ` +
+            `${options.remoteGitDir}: ${getErrorMessage(err)}.`);
+    }
 }

package/dist/utils/json-source-splice.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Source-preserving serialisation for JSON content files.
+ *
+ * A value `data` leaves alone keeps its bytes in the file; a value that changed is written at
+ * its own slot, in the file's indent and line ending; and anything this module cannot vouch for
+ * (a file that is not a JSON object, an edit set that does not read back as `data`) is written as
+ * `JSON.stringify(data, null, 2)`. Retained keys keep the file's order and new keys are appended.
+ */
+/**
+ * Serialise entry data as a JSON file, keeping `existingRaw`'s formatting wherever `data`
+ * leaves a value alone. Writes `JSON.stringify(data, null, 2)` plus a newline when there is
+ * no existing file or the splice cannot be trusted; a save never fails on the old content.
+ */
+export declare function serializeJson(data: Record<string, unknown>, existingRaw?: string): string;

package/dist/utils/json-source-splice.js

@@ -0,0 +1,120 @@
+/**
+ * Source-preserving serialisation for JSON content files.
+ *
+ * A value `data` leaves alone keeps its bytes in the file; a value that changed is written at
+ * its own slot, in the file's indent and line ending; and anything this module cannot vouch for
+ * (a file that is not a JSON object, an edit set that does not read back as `data`) is written as
+ * `JSON.stringify(data, null, 2)`. Retained keys keep the file's order and new keys are appended.
+ */
+import { isDeepStrictEqual } from 'node:util';
+import { applyEdits, modify } from 'jsonc-parser';
+import { createDebugLogger } from './debug.js';
+import { getErrorMessage } from './error.js';
+const log = createDebugLogger({ prefix: 'JsonSourceSplice' });
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function plainStringify(data) {
+    return `${JSON.stringify(data, null, 2)}\n`;
+}
+/** The file's own indent (from its first indented line) and line ending. */
+function detectFormatting(text) {
+    const indent = /^([ \t]+)\S/m.exec(text)?.[1];
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    if (indent?.startsWith('\t'))
+        return { insertSpaces: false, tabSize: 1, eol };
+    return { insertSpaces: true, tabSize: indent?.length ?? 2, eol };
+}
+/**
+ * Append `key: value` to the object at `path`. A formatted `modify` re-renders the object's
+ * previous last member too, so when the object's closing brace has a line of its own the member
+ * is rendered here in the object's own indent and nothing else is touched; any other layout
+ * (an empty or one-line object) takes the formatted `modify`.
+ */
+function insertMember(text, path, key, value, formattingOptions) {
+    const at = [...path, key];
+    const [edit] = modify(text, at, value, {});
+    const closing = edit ? /^[ \t]*\r?\n([ \t]*)\}/.exec(text.slice(edit.offset)) : null;
+    if (edit && closing && edit.length === 0 && edit.content.startsWith(',')) {
+        const unit = formattingOptions.insertSpaces ? ' '.repeat(formattingOptions.tabSize ?? 2) : '\t';
+        const eol = formattingOptions.eol ?? '\n';
+        const indent = closing[1] + unit;
+        const rendered = JSON.stringify(value, null, unit)
+            .split('\n')
+            .join(eol + indent);
+        return applyEdits(text, [
+            { ...edit, content: `,${eol}${indent}${JSON.stringify(key)}: ${rendered}` },
+        ]);
+    }
+    return applyEdits(text, modify(text, at, value, { formattingOptions }));
+}
+/**
+ * Remove the member at `path`. Unformatted, since a formatted removal re-renders the neighbouring
+ * member too; and an unformatted removal of an object's first member runs from the `{` to the
+ * next member, taking the whitespace in front of it, so a removal that starts in whitespace and
+ * ends at a member starts at the removed member instead.
+ */
+function removeMember(text, path) {
+    return applyEdits(text, modify(text, path, undefined, {}).map((edit) => {
+        const removed = text.slice(edit.offset, edit.offset + edit.length);
+        const lead = /^\s+/.exec(removed)?.[0].length ?? 0;
+        const atMember = /\S/.test(text.charAt(edit.offset + edit.length));
+        return edit.content === '' && lead > 0 && atMember
+            ? { ...edit, offset: edit.offset + lead, length: edit.length - lead }
+            : edit;
+    }));
+}
+/**
+ * Edit `text` so the value at `path` goes from `before` to `after`, touching only what differs.
+ * Both sides are JSON-normalised, so `undefined` never appears and a key is absent or present.
+ */
+function reconcile(text, path, before, after, formattingOptions) {
+    if (isRecord(before) && isRecord(after)) {
+        // Removing every member one by one would leave the braces on their own lines.
+        if (Object.keys(after).length === 0 && Object.keys(before).length > 0) {
+            return applyEdits(text, modify(text, path, {}, { formattingOptions }));
+        }
+        let next = text;
+        for (const key of Object.keys(before)) {
+            if (!Object.prototype.hasOwnProperty.call(after, key))
+                next = removeMember(next, [...path, key]);
+        }
+        for (const key of Object.keys(after)) {
+            next = Object.prototype.hasOwnProperty.call(before, key)
+                ? reconcile(next, [...path, key], before[key], after[key], formattingOptions)
+                : insertMember(next, path, key, after[key], formattingOptions);
+        }
+        return next;
+    }
+    if (Array.isArray(before) && Array.isArray(after) && before.length === after.length) {
+        return after.reduce((next, item, index) => reconcile(next, [...path, index], before[index], item, formattingOptions), text);
+    }
+    if (JSON.stringify(before) === JSON.stringify(after))
+        return text;
+    return applyEdits(text, modify(text, path, after, { formattingOptions }));
+}
+/**
+ * Serialise entry data as a JSON file, keeping `existingRaw`'s formatting wherever `data`
+ * leaves a value alone. Writes `JSON.stringify(data, null, 2)` plus a newline when there is
+ * no existing file or the splice cannot be trusted; a save never fails on the old content.
+ */
+export function serializeJson(data, existingRaw) {
+    if (existingRaw === undefined)
+        return plainStringify(data);
+    try {
+        const normalised = JSON.parse(JSON.stringify(data));
+        const existing = JSON.parse(existingRaw);
+        if (!isRecord(normalised) || !isRecord(existing))
+            return plainStringify(data);
+        const spliced = reconcile(existingRaw, [], existing, normalised, detectFormatting(existingRaw));
+        if (isDeepStrictEqual(JSON.parse(spliced), normalised))
+            return spliced;
+        log.debug('json-source-splice', 'splice does not read back as data; writing JSON.stringify');
+    }
+    catch (err) {
+        log.debug('json-source-splice', 'splice failed; writing JSON.stringify', {
+            error: getErrorMessage(err),
+        });
+    }
+    return plainStringify(data);
+}

package/dist/utils/markdown-body-splice.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Source-preserving save for md/mdx bodies.
+ *
+ * The editor sends a body re-serialised from its own document model, so every block comes back
+ * in the serialiser's style (bullet and emphasis markers, rule style, escapes, no blank line
+ * after the frontmatter) whether or not the user touched it. This writes the on-disk text of
+ * every block whose MEANING the edit left alone, and the editor's text only where it changed:
+ *
+ * - Top-level blocks are aligned by a position-free canonical form of their mdast, so a block
+ *   matches only when it parses to the same tree. A matched block is written from disk.
+ * - A changed block paired with an original of the same kind is spliced by its children when it
+ *   is a list (by item) or a list item (by child block), at any depth, so editing one item leaves
+ *   its siblings alone. New items take the original list's marker and numbering.
+ * - Whitespace between two output blocks that stand for adjacent on-disk blocks (an edited block
+ *   stands for the original it is paired with) is the disk's; elsewhere it is the editor's,
+ *   re-indented into the original's nesting and written in its line endings.
+ *
+ * The result is kept only if it parses to exactly the tree the editor's body parses to. A splice
+ * that fails that check is retried without descending into lists, and failing that the editor's
+ * body is written as sent: the worst case is the editor's own serialisation, never different
+ * content.
+ */
+export type MarkdownBodyFormat = 'md' | 'mdx';
+/**
+ * `text`'s top-level blocks, each as its source text and its `canonical` form, or undefined when
+ * `text` does not parse: two bodies mean the same to the splice exactly when their `meaning`
+ * lists are equal.
+ *
+ * @internal Exported for the round-trip corpus test.
+ */
+export declare function markdownBlocks(text: string, format: MarkdownBodyFormat): {
+    text: string;
+    meaning: string;
+}[] | undefined;
+/**
+ * The body to write for an edit from `original` (on disk) to `updated` (the editor's body):
+ * `updated`'s content, in `original`'s text wherever the two agree. See the module header.
+ */
+export declare function preserveMarkdownSource(original: string, updated: string, format: MarkdownBodyFormat): string;