canopycms 0.0.67 → 0.0.68-int.101

package/dist/submission-attribution.d.ts

@@ -0,0 +1,73 @@
+import type { CanopyUser } from './user.js';
+/**
+ * Who submitted (and edited) a branch, recorded in the submit commit's trailers
+ * and the pull request body. The bot stays the commit author; these records are
+ * the only place the editing user appears.
+ *
+ * Display names, ids and emails come from the auth provider and end up in git
+ * history and in GitHub-rendered Markdown, so each passes through a sanitizer
+ * below before it is written anywhere.
+ */
+export interface SubmissionEditor {
+    userId: string;
+    name?: string;
+    email?: string;
+}
+/**
+ * The PR body region canopycms owns. On update only the text between these
+ * markers is replaced, so anything a human wrote around it survives.
+ * @internal Exported for tests.
+ */
+export declare const PR_SECTION_START = "<!-- canopycms:submission:start -->";
+/** @internal Exported for tests. */
+export declare const PR_SECTION_END = "<!-- canopycms:submission:end -->";
+/**
+ * A display name safe for a single line of git trailer or Markdown, or undefined.
+ * @internal Exported for tests.
+ */
+export declare function sanitizeDisplayName(raw: string | undefined): string | undefined;
+/**
+ * The auth user id unchanged, or undefined if it holds characters unsafe to record.
+ * @internal Exported for tests.
+ */
+export declare function sanitizeUserId(raw: string | undefined): string | undefined;
+/**
+ * The email as given if it is a plain single-address email, otherwise undefined.
+ * @internal Exported for tests.
+ */
+export declare function sanitizeEmail(raw: string | undefined): string | undefined;
+/** The submitter as a SubmissionEditor, or undefined for an anonymous user. */
+export declare function submissionEditorFromUser(user: CanopyUser): SubmissionEditor | undefined;
+export interface CommitTrailerOptions {
+    /** One `Edited-by: Name (id)` per editor. */
+    editedBy: boolean;
+    /** One `Co-authored-by: Name <email>` per editor whose email is valid. */
+    coAuthoredBy: boolean;
+}
+/** Git trailer lines for the given editors, deduplicated by user id. */
+export declare function buildEditorTrailers(editors: readonly SubmissionEditor[], options: CommitTrailerOptions): string[];
+/**
+ * `subject`, then a blank line and the trailer block when there are trailers.
+ * Git reads trailers only from the last paragraph, so the blank line is what
+ * makes them trailers rather than part of the subject.
+ */
+export declare function appendTrailers(subject: string, trailers: readonly string[]): string;
+export interface PrSectionInput {
+    /** The branch description the editor wrote; free Markdown. */
+    description?: string;
+    submitter?: SubmissionEditor;
+    /** Editors other than the submitter, when known. */
+    editors?: readonly SubmissionEditor[];
+    /** Repo-relative paths changed on the branch. */
+    changedPaths: readonly string[];
+}
+/** The canopycms-owned PR body section, including its start and end markers. */
+export declare function buildPrSection(input: PrSectionInput): string;
+/**
+ * `existing` with its canopycms section replaced by `section`, keeping every
+ * character outside the markers. The section is the first end marker together
+ * with the nearest start marker before it, so a lone start marker a human quoted
+ * earlier in the body is skipped. With no such pair, stray markers are
+ * removed and `section` is appended after the human text.
+ */
+export declare function mergePrSection(existing: string | null | undefined, section: string): string;

package/dist/submission-attribution.js

@@ -0,0 +1,221 @@
+import { canopyLogWarn } from './utils/logger.js';
+const MAX_NAME_LENGTH = 80;
+const MAX_ID_LENGTH = 128;
+const MAX_EMAIL_LENGTH = 254;
+const MAX_DESCRIPTION_LENGTH = 10_000;
+const MAX_LISTED_ENTRIES = 100;
+/**
+ * The PR body region canopycms owns. On update only the text between these
+ * markers is replaced, so anything a human wrote around it survives.
+ * @internal Exported for tests.
+ */
+export const PR_SECTION_START = '<!-- canopycms:submission:start -->';
+/** @internal Exported for tests. */
+export const PR_SECTION_END = '<!-- canopycms:submission:end -->';
+// Cc (C0/C1 controls incl. newlines), Cf (zero-width and bidi overrides), Zl/Zp
+// (Unicode line/paragraph separators) can forge a trailer line or hide text; Cs
+// (a lone surrogate) reaches git as U+FFFD, since Node encodes it so.
+const INVISIBLE_OR_CONTROL = /[\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]/gu;
+// `<>` would end a Co-authored-by email or open HTML / a section marker, `()`
+// would let a name forge the id that follows it, a backtick would close the
+// code span names render in, and a backslash is Markdown's escape character.
+const STRUCTURAL = /[<>()`\\]/g;
+function truncate(value, max) {
+    const chars = Array.from(value);
+    return chars.length > max ? `${chars.slice(0, max - 1).join('')}…` : value;
+}
+/**
+ * A changed path for a code span: only what could break out of the span or out
+ * of the section is removed, so `app/(group)/page.mdx` stays distinct from
+ * `app/page.mdx`. No NFKC, for the same reason.
+ */
+function cleanPath(raw) {
+    const cleaned = raw.replace(INVISIBLE_OR_CONTROL, ' ').replace(/[<>`]/g, '').trim();
+    return cleaned ? truncate(cleaned, 300) : undefined;
+}
+function cleanText(raw, max) {
+    if (raw === undefined)
+        return undefined;
+    const cleaned = raw
+        .normalize('NFKC')
+        .replace(INVISIBLE_OR_CONTROL, ' ')
+        .replace(STRUCTURAL, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return cleaned ? truncate(cleaned, max) : undefined;
+}
+/**
+ * A display name safe for a single line of git trailer or Markdown, or undefined.
+ * @internal Exported for tests.
+ */
+export function sanitizeDisplayName(raw) {
+    return cleanText(raw, MAX_NAME_LENGTH);
+}
+// Ids and emails are accepted as the provider issued them or rejected, never
+// cleaned: cleaning could merge two users or attribute an edit to someone else.
+// A trailer still swaps in look-alikes for display (trailerText).
+const UNSAFE_VERBATIM_CHAR = /[\s\p{Cc}\p{Cf}\p{Cs}<>()`\\]/u;
+/**
+ * The auth user id unchanged, or undefined if it holds characters unsafe to record.
+ * @internal Exported for tests.
+ */
+export function sanitizeUserId(raw) {
+    if (!raw || Array.from(raw).length > MAX_ID_LENGTH || UNSAFE_VERBATIM_CHAR.test(raw))
+        return undefined;
+    return raw;
+}
+const EMAIL_SHAPE = /^[^\s@<>()"',;:\\[\]]+@[^\s@<>()"',;:\\[\]]+\.[^\s@<>()"',;:\\[\]]+$/;
+/**
+ * The email as given if it is a plain single-address email, otherwise undefined.
+ * @internal Exported for tests.
+ */
+export function sanitizeEmail(raw) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    // `\s` misses most C0/C1 controls, and a NUL makes git's spawn throw. `#` is
+    // legal in an address but GitHub links `#12` in a commit message.
+    if (trimmed.length > MAX_EMAIL_LENGTH ||
+        UNSAFE_VERBATIM_CHAR.test(trimmed) ||
+        trimmed.includes('#'))
+        return undefined;
+    return EMAIL_SHAPE.test(trimmed) ? trimmed : undefined;
+}
+/** The submitter as a SubmissionEditor, or undefined for an anonymous user. */
+export function submissionEditorFromUser(user) {
+    if (user.type !== 'authenticated')
+        return undefined;
+    return { userId: user.userId, name: user.name, email: user.email };
+}
+function cleanEditors(editors) {
+    const seen = new Set();
+    const result = [];
+    for (const editor of editors) {
+        const userId = sanitizeUserId(editor.userId);
+        if (!userId) {
+            // The id itself stays out of the log: it is the unsafe value.
+            if (editor.userId) {
+                canopyLogWarn('CanopyCMS: Not recording an editor whose user id is unsafe to write to git');
+            }
+            continue;
+        }
+        if (seen.has(userId))
+            continue;
+        seen.add(userId);
+        result.push({
+            userId,
+            name: sanitizeDisplayName(editor.name),
+            email: sanitizeEmail(editor.email),
+        });
+    }
+    return result;
+}
+/**
+ * GitHub autolinks commit messages: `@user` mentions, `scheme://` URLs, and `#12` /
+ * `GH-12` issue references, which a closing keyword ("Closes #12") turns into an
+ * issue close once the commit reaches the default branch. A trailer value gets
+ * `@` and `#` swapped for look-alikes and the other two patterns broken. Its
+ * input is already single-line and structure-free.
+ */
+function trailerText(value) {
+    return value
+        .replace(/@/g, '＠')
+        .replace(/#/g, '＃')
+        .replace(/:\/\//g, ': //')
+        .replace(/\bGH-(?=\d)/gi, (m) => `${m.slice(0, 2)}‐`);
+}
+/** Git trailer lines for the given editors, deduplicated by user id. */
+export function buildEditorTrailers(editors, options) {
+    const trailers = [];
+    const clean = cleanEditors(editors);
+    if (options.editedBy) {
+        for (const editor of clean) {
+            trailers.push(editor.name
+                ? `Edited-by: ${trailerText(editor.name)} (${trailerText(editor.userId)})`
+                : `Edited-by: ${trailerText(editor.userId)}`);
+        }
+    }
+    if (options.coAuthoredBy) {
+        for (const editor of clean) {
+            if (!editor.email)
+                continue;
+            trailers.push(`Co-authored-by: ${trailerText(editor.name ?? editor.userId)} <${editor.email}>`);
+        }
+    }
+    return trailers;
+}
+/**
+ * `subject`, then a blank line and the trailer block when there are trailers.
+ * Git reads trailers only from the last paragraph, so the blank line is what
+ * makes them trailers rather than part of the subject.
+ */
+export function appendTrailers(subject, trailers) {
+    return trailers.length > 0 ? `${subject.trimEnd()}\n\n${trailers.join('\n')}` : subject;
+}
+/**
+ * Renders as inline code: GitHub neither autolinks, mentions nor interprets HTML
+ * inside a code span. The input is already free of backticks.
+ */
+function codeSpan(value) {
+    return `\`${value}\``;
+}
+/**
+ * Free Markdown with every HTML comment opener and closer escaped, so the text
+ * can neither close the canopycms section early nor open a comment that hides
+ * the rest of the body. Escaped comments render as their literal text.
+ */
+function neutralizeComments(text) {
+    return text.replace(/<!--/g, '&lt;!--').replace(/--!?>/g, '--&gt;');
+}
+function editorLabel(editor) {
+    return editor.name
+        ? `${codeSpan(editor.name)} (${codeSpan(editor.userId)})`
+        : codeSpan(editor.userId);
+}
+/** The canopycms-owned PR body section, including its start and end markers. */
+export function buildPrSection(input) {
+    const parts = [];
+    const [submitter] = input.submitter ? cleanEditors([input.submitter]) : [];
+    parts.push(submitter
+        ? `Submitted by ${editorLabel(submitter)} via CanopyCMS.`
+        : 'Submitted via CanopyCMS.');
+    const others = cleanEditors(input.editors ?? []).filter((e) => e.userId !== submitter?.userId);
+    if (others.length > 0) {
+        parts.push(`Also edited by: ${others.map(editorLabel).join(', ')}`);
+    }
+    const paths = [...new Set(input.changedPaths)]
+        .map(cleanPath)
+        .filter((p) => p !== undefined);
+    if (paths.length > 0) {
+        const listed = paths.slice(0, MAX_LISTED_ENTRIES).map((p) => `- ${codeSpan(p)}`);
+        if (paths.length > MAX_LISTED_ENTRIES) {
+            listed.push(`- …and ${paths.length - MAX_LISTED_ENTRIES} more`);
+        }
+        parts.push(`**Changed entries (${paths.length})**\n\n${listed.join('\n')}`);
+    }
+    // Last, so an unclosed fence or `<details>` in free Markdown cannot swallow
+    // the attribution above it.
+    const description = input.description?.trim();
+    if (description)
+        parts.push(neutralizeComments(truncate(description, MAX_DESCRIPTION_LENGTH)));
+    return `${PR_SECTION_START}\n${parts.join('\n\n')}\n${PR_SECTION_END}`;
+}
+/**
+ * `existing` with its canopycms section replaced by `section`, keeping every
+ * character outside the markers. The section is the first end marker together
+ * with the nearest start marker before it, so a lone start marker a human quoted
+ * earlier in the body is skipped. With no such pair, stray markers are
+ * removed and `section` is appended after the human text.
+ */
+export function mergePrSection(existing, section) {
+    const body = existing ?? '';
+    for (let end = body.indexOf(PR_SECTION_END); end >= 0;) {
+        const start = body.lastIndexOf(PR_SECTION_START, end - PR_SECTION_START.length);
+        if (start >= 0) {
+            return body.slice(0, start) + section + body.slice(end + PR_SECTION_END.length);
+        }
+        end = body.indexOf(PR_SECTION_END, end + PR_SECTION_END.length);
+    }
+    const human = body.split(PR_SECTION_START).join('').split(PR_SECTION_END).join('').trimEnd();
+    return human ? `${human}\n\n${section}` : section;
+}

package/dist/sync-core.d.ts

@@ -44,13 +44,24 @@ export interface PushContentToWorkspaceOptions {
     commitMessage?: string;
     /** When set, (re)tag the resulting commit as the sync base (used by `sync both` 3-way merges). */
     baseTag?: string;
+    /**
+     * When set, uncommitted workspace changes (editor saves) are first committed with this
+     * message, so the content replacement leaves them in history rather than discarding them.
+     */
+    saveEditorStateMessage?: string;
 }
 /**
  * Copy working-tree content into a branch workspace and commit it. Prompt-free — the interactive CLI
  * (`canopycms sync push`) calls this for the actual copy + commit + tag step.
  *
- * Returns the number of changed files committed (0 when content was already up to date).
+ * [SYNC-C1] Replaces the workspace's content directory wholesale, so it runs under the branch's
+ * content-write lock: an editor save landing mid-swap would go into the directory being discarded.
+ * Rejects with `ContentWriteLockBusyError` when the branch is busy.
+ *
+ * Returns the number of changed files committed (0 when content was already up to date), and
+ * whether uncommitted editor changes were committed first.
  */
 export declare function pushContentToWorkspace(options: PushContentToWorkspaceOptions): Promise<{
     fileCount: number;
+    savedEditorState: boolean;
 }>;

package/dist/sync-core.js

@@ -7,7 +7,9 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { simpleGit } from 'simple-git';
 import { invalidateBranchContentCaches } from './content-index-generation.js';
+import { withContentWriteLock } from './utils/content-write-lock.js';
 import { filePathExists } from './utils/fs.js';
+import { isCanopyInternalPath, stageAllExceptCanopyState } from './utils/git.js';
 /** Git tag marking the last known sync point, used as the merge base for `sync both` 3-way merges. */
 export const SYNC_BASE_TAG = 'canopycms-sync-base';
 /** Validate that a resolved path stays within the expected parent directory. */
@@ -132,15 +134,34 @@ export async function diffContentTrees(workingTreeDir, branchDir) {
  * Copy working-tree content into a branch workspace and commit it. Prompt-free — the interactive CLI
  * (`canopycms sync push`) calls this for the actual copy + commit + tag step.
  *
- * Returns the number of changed files committed (0 when content was already up to date).
+ * [SYNC-C1] Replaces the workspace's content directory wholesale, so it runs under the branch's
+ * content-write lock: an editor save landing mid-swap would go into the directory being discarded.
+ * Rejects with `ContentWriteLockBusyError` when the branch is busy.
+ *
+ * Returns the number of changed files committed (0 when content was already up to date), and
+ * whether uncommitted editor changes were committed first.
  */
 export async function pushContentToWorkspace(options) {
-    const { srcContentDir, branchPath, contentRoot, commitMessage, baseTag } = options;
+    const { srcContentDir, branchPath, contentRoot } = options;
     if (!(await filePathExists(srcContentDir))) {
-        return { fileCount: 0 };
+        return { fileCount: 0, savedEditorState: false };
     }
     const wsContentDir = path.join(branchPath, contentRoot);
     assertWithinDir(wsContentDir, branchPath, 'content-root');
+    return withContentWriteLock(branchPath, () => replaceWorkspaceContent(options, wsContentDir));
+}
+async function replaceWorkspaceContent(options, wsContentDir) {
+    const { srcContentDir, branchPath, commitMessage, baseTag, saveEditorStateMessage } = options;
+    const wsGit = simpleGit({ baseDir: branchPath });
+    let savedEditorState = false;
+    if (saveEditorStateMessage) {
+        const editorChanges = (await wsGit.status()).files.filter((f) => !isCanopyInternalPath(f.path));
+        if (editorChanges.length > 0) {
+            await stageAllExceptCanopyState(wsGit);
+            await wsGit.commit(saveEditorStateMessage);
+            savedEditorState = true;
+        }
+    }
     // Copy into a temp dir, then atomically swap it into place.
     const tmpDir = `${wsContentDir}.sync-tmp-${Date.now()}`;
     try {
@@ -154,23 +175,20 @@ export async function pushContentToWorkspace(options) {
     // The content dir was replaced wholesale, so ContentStore ID indexes rooted
     // at this workspace must be marked stale — in this process and (via the
     // on-disk generation marker) in every other process sharing the filesystem.
-    // Done in the finally AFTER the git add/commit below: the marker lives under
-    // .canopy-meta/ inside the clone, and writing it first would stage it into
-    // the sync commit via `add -A` (production workspaces git-exclude
-    // .canopy-meta/, but this function shouldn't depend on that).
+    // Done in the finally AFTER the git add/commit below, and staging skips
+    // .canopy-meta/, where the marker lives.
     try {
-        const wsGit = simpleGit({ baseDir: branchPath });
-        await wsGit.add('-A');
-        const postStatus = await wsGit.status();
-        if (postStatus.files.length === 0) {
+        await stageAllExceptCanopyState(wsGit);
+        const staged = (await wsGit.status()).files.filter((f) => !isCanopyInternalPath(f.path));
+        if (staged.length === 0) {
             if (baseTag)
                 await wsGit.tag(['-f', baseTag]);
-            return { fileCount: 0 };
+            return { fileCount: 0, savedEditorState };
         }
         await wsGit.commit(commitMessage ?? 'sync: update content from working tree');
         if (baseTag)
             await wsGit.tag(['-f', baseTag]);
-        return { fileCount: postStatus.files.length };
+        return { fileCount: staged.length, savedEditorState };
     }
     finally {
         await invalidateBranchContentCaches(branchPath);

package/dist/task-queue/worker-status.d.ts

@@ -32,4 +32,12 @@ export declare const WORKER_STATUS_FILE = "worker-status.json";
  * `processTaskQueue`, `start()`); any that don't fall back on scheduleLoop's
  * per-cycle catch, which logs and continues.
  */
+/**
+ * The `lastFatalError` in the current status file, or undefined when the file is
+ * missing, unreadable or has none. Tolerant for the same reason readers are.
+ * Its one caller carries the value into a full snapshot right after taking the
+ * worker lock; a write racing in between only keeps or drops one crash alert
+ * until the next write.
+ */
+export declare function readLastFatalError(taskDir: string): Promise<WorkerStatusReport['lastFatalError']>;
 export declare function writeWorkerStatus(taskDir: string, report: WorkerStatusReport): Promise<void>;

package/dist/task-queue/worker-status.js

@@ -19,6 +19,7 @@
  * docs/concurrency.md) means a reader can see a snapshot a cache window old
  * however carefully it was written.
  */
+import fs from 'node:fs/promises';
 import path from 'node:path';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 export const WORKER_STATUS_FILE = 'worker-status.json';
@@ -33,6 +34,22 @@ export const WORKER_STATUS_FILE = 'worker-status.json';
  * `processTaskQueue`, `start()`); any that don't fall back on scheduleLoop's
  * per-cycle catch, which logs and continues.
  */
+/**
+ * The `lastFatalError` in the current status file, or undefined when the file is
+ * missing, unreadable or has none. Tolerant for the same reason readers are.
+ * Its one caller carries the value into a full snapshot right after taking the
+ * worker lock; a write racing in between only keeps or drops one crash alert
+ * until the next write.
+ */
+export async function readLastFatalError(taskDir) {
+    try {
+        const content = await fs.readFile(path.join(taskDir, WORKER_STATUS_FILE), 'utf-8');
+        return JSON.parse(content).lastFatalError;
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function writeWorkerStatus(taskDir, report) {
     const filePath = path.join(taskDir, WORKER_STATUS_FILE);
     const stamped = { ...report, updatedAt: new Date().toISOString() };

package/dist/types.d.ts

@@ -102,6 +102,31 @@ export interface BranchContext extends BranchPaths {
 export interface BranchContextWithSchema extends BranchContext {
     flatSchema: import('./config/index.js').FlatSchemaItem[];
 }
+/**
+ * Outcome of the worker's per-cycle fast-forward of the base branch's own clone
+ * (worker/git-sync.ts's `refreshBaseBranchWorkspace`); the rebase loop skips
+ * that clone.
+ */
+export interface BaseRefreshReport {
+    outcome: 'refreshed' | 'up-to-date' | 'skipped-dirty' | 'skipped-locked' | 'skipped-not-provisioned' | 'failed';
+    /** Tracked files blocking the refresh, at most 10; set when `skipped-dirty`. */
+    dirtyFiles?: string[];
+    /** What went wrong, credential-redacted; set when `failed` or `skipped-dirty`. */
+    message?: string;
+    /**
+     * Files under `.canopy-meta/` the adopter's repo tracks, at most 10. canopycms
+     * rewrites that state per branch, so tracking it is an adopter misconfiguration
+     * the panel surfaces with its fix, whatever the outcome.
+     */
+    trackedCanopyMeta?: string[];
+}
+/** What a running CMS process reports about the build it was started from. */
+export interface BuildIdentity {
+    /** canopycms package version this process runs. */
+    canopycmsVersion: string;
+    /** Adopter source revision the deployed image was built from (CANOPY_SOURCE_SHA); absent when unset. */
+    sourceRevision?: string;
+}
 /**
  * Wire shape of the worker's self-reported status file (worker-status.json, under
  * the task queue dir), written by the CmsWorker daemon. Read-only here: GET
@@ -109,6 +134,7 @@ export interface BranchContextWithSchema extends BranchContext {
  */
 export interface WorkerStatusReport {
     version: 1;
+    /** canopycms version the worker runs. Optional: status files from older workers lack it. */
     workerVersion?: string;
     startedAt: string;
     updatedAt: string;
@@ -123,8 +149,9 @@ export interface WorkerStatusReport {
         rebased: string[];
         skippedDirty: string[];
         /**
-         * [SYNC-C1] Branches skipped because a content write held the branch's
-         * cross-host content-write lock (utils/content-write-lock.ts); the worker
+         * Branches skipped because another process held a lock the worker
+         * try-acquires: the [SYNC-C1] content-write lock (utils/content-write-lock.ts)
+         * or the provisioning lock (worker/provisioned-workspace.ts). The worker
          * yields and retries next cycle. Optional for the same reason as `tracked`
          * below, and readers must tolerate its absence.
          */
@@ -133,6 +160,8 @@ export interface WorkerStatusReport {
             branch: string;
             error: string;
         }[];
+        /** Optional for the same reason as `tracked` below. */
+        baseRefresh?: BaseRefreshReport;
         /**
          * Outcome of reconciling remote.git's `refs/heads/*` against GitHub's fetched
          * tips, non-destructively (worker/git-sync.ts's `reconcileTrackedBranches`).

package/dist/utils/content-serialize.d.ts

@@ -5,7 +5,9 @@
  * deletes every comment in the file, because comments live in neither the object nor that round
  * trip. So these functions re-serialise onto the file's OWN parsed document: a node whose value
  * did not change is left untouched, and an untouched node keeps its attached comments and its
- * original quoting/block style. Only what actually changed is rewritten.
+ * original quoting/block style. Only what actually changed is rewritten, and
+ * `yaml-source-splice.ts` writes it into the file's own text, so untouched lines keep their bytes
+ * wherever it can vouch for the result.
  *
  * The file gets no authority over its own content. The reconciler makes the document's key set
  * match `data` exactly — a key the caller dropped disappears, a key the caller kept survives
@@ -19,7 +21,8 @@
  *
  * Falls back to a plain stringify — byte-identical to serialising without preservation — when
  * there is nothing to preserve (a new file) or nothing trustworthy to preserve (the bytes on disk
- * do not parse). A save must not fail because the previous content was malformed.
+ * do not parse, or the reconciled document does not read back as its own data). A save must not
+ * fail because the previous content was malformed.
  */
 export declare function serializeYaml(data: Record<string, unknown>, existingRaw?: string): string;
 /**