canopycms 0.0.68-int.107 → 0.0.68-int.109

package/README.md

@@ -442,7 +442,7 @@ export function PostView({ data }: { data: PostContent }) {
 - `data`: The current content data (initial data on first render, then live updates from editor)
 - `isLoading`: Object mirroring your data structure with boolean loading states for reference fields
 - `highlightEnabled`: Boolean indicating if field highlighting is active in the editor
-- `fieldProps`: Helper function to add `data-canopy-path` attributes for editor integration
+- `fieldProps`: marks the element rendering a field (`data-canopy-path`), with the path typed against your content; `fieldAttrs` and `scopeFieldProps` from `canopycms` thread it through section components (see the root README's Live Preview)
 
 **Reference fields and loading states:**
 

package/dist/api/branch-status.js

@@ -11,6 +11,7 @@ import { getErrorMessage, redactCredentials, sanitizeErrorMessage } from '../uti
 import { isNonFastForwardRejection } from '../utils/git.js';
 import { ContentWriteLockBusyError } from '../utils/content-write-lock.js';
 import { submissionEditorFromUser } from '../submission-attribution.js';
+import { NothingToSubmitError } from '../services.js';
 const getBranchStatusHandler = async (gc, _ctx, _req, _params) => {
     const { branchContext } = gc;
     return { ok: true, status: 200, data: { branch: branchContext.branch } };
@@ -38,9 +39,8 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
     // (merged) branch could be re-submitted by its creator, re-stamping it
     // 'submitted' and overwriting the merged PR's title/body.
     //
-    // Fails closed on a missing status (branch.json is read with a bare
-    // JSON.parse, no schema validation, so a damaged file can yield
-    // `undefined`) -- same as runWritableBranchGuard's unreadable-status arm.
+    // Fails closed on a missing status, same as runWritableBranchGuard's
+    // unreadable-status arm.
     const status = branchContext.branch.status;
     if (status !== 'editing') {
         return {
@@ -59,6 +59,9 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
         ({ changedPaths } = await ctx.services.submitBranch({ context: branchContext, submitter }));
     }
     catch (err) {
+        if (err instanceof NothingToSubmitError) {
+            return { ok: false, status: 400, error: err.message };
+        }
         // Retriable either way: a resubmit commits nothing new and pushes only
         // what has not reached the remote.
         if (err instanceof ContentWriteLockBusyError) {
@@ -107,13 +110,33 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
         };
     }
     // Create or update PR (sync via githubService, or async via task queue)
-    const prResult = await syncSubmitPr(ctx, branchContext, { submitter, changedPaths });
-    // Update metadata with status and PR info
+    const submittedAt = new Date().toISOString();
+    const prResult = await syncSubmitPr(ctx, branchContext, {
+        submitter,
+        changedPaths,
+        submittedAt,
+    });
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
+    const pushed = prResult.pushedToGitHub ? { pushedToGitHubAt: submittedAt } : {};
+    // GitHub found nothing between the pushed branch and its base, though the diff above found
+    // changes: GitHub's base can already hold them, or the diff could not be computed. The branch
+    // stays editable; the stamp records that it is now on GitHub, for delete.
+    if (prResult.nothingToSubmit) {
+        await meta.save({ branch: { name: branchContext.branch.name, ...pushed } });
+        const base = branchContext.branch.baseBranch ?? ctx.services.config.defaultBaseBranch ?? 'main';
+        return {
+            ok: false,
+            status: 400,
+            error: new NothingToSubmitError(branchContext.branch.name, base).message,
+        };
+    }
     const updated = await meta.save({
         branch: {
             name: branchContext.branch.name,
             status: 'submitted',
+            submittedAt,
+            ...pushed,
+            syncFailureReason: prResult.syncFailureReason,
             pullRequestUrl: prResult.prUrl ?? branchContext.branch.pullRequestUrl,
             pullRequestNumber: prResult.prNumber ?? branchContext.branch.pullRequestNumber,
             ...(prResult.syncStatus !== undefined ? { syncStatus: prResult.syncStatus } : {}),

package/dist/api/content.d.ts

@@ -104,14 +104,14 @@ export declare const CONTENT_ROUTES: {
         expectedVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, "strip", z.ZodTypeAny, {
         format: "mdx" | "md" | "json" | "yaml";
+        data?: Record<string, unknown> | undefined;
         expectedVersion?: number | null | undefined;
         body?: string | undefined;
-        data?: Record<string, unknown> | undefined;
     }, {
         format: "mdx" | "md" | "json" | "yaml";
+        data?: Record<string, unknown> | undefined;
         expectedVersion?: number | null | undefined;
         body?: string | undefined;
-        data?: Record<string, unknown> | undefined;
     }>, ContentWriteResponse>;
     readonly validateReferences: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;

package/dist/api/content.js

@@ -5,11 +5,13 @@ import { SchemaUnavailableError } from '../schema/schema-unavailable-error.js';
 import { ReferenceValidator } from '../validation/reference-validator.js';
 import { findUnknownKeys, mergeBodyIntoData, normalizeReferenceValues, validateEntryData, } from '../validation/entry-validator.js';
 import { validateEntryLinks } from '../validation/entry-link-validator.js';
+import { findMarkdownSafetyIssues, splitByStored } from '../validation/markdown-safety.js';
 import { collectReferenceIds } from '../validation/field-traversal.js';
 import { branchNameSchema, logicalPathSchema, slugSchema } from './validators.js';
 import { entryLogicalPath, parseSlug } from '../paths/index.js';
 import { getErrorMessage, isNotFoundError, sanitizeErrorMessage } from '../utils/error.js';
 import { isDataOnlyFormat } from '../utils/format.js';
+import { findBodyFieldName } from '../utils/body-field.js';
 /**
  * Parse an API path into logical path segments, prepending the content root if needed.
  * Shared by all content API handlers.
@@ -123,6 +125,23 @@ const storedReferenceSites = async (store, collectionPath, slug, fields) => {
     const doc = await store.read(collectionPath, slug, { resolveReferences: false });
     return new Set(collectReferenceIds(fields, doc.data).map((ref) => referenceSite(ref.path, ref.id)));
 };
+function withoutKey(record, key) {
+    if (!(key in record))
+        return record;
+    const { [key]: _dropped, ...rest } = record;
+    return rest;
+}
+/** The policy's issues in the stored entry, which a save may keep. */
+const storedMarkdownSafetyIssues = async (store, collectionPath, slug, fields, siteAllow) => {
+    // A stored file that does not read keeps nothing, so the save's code is refused, not a 500.
+    const doc = await store
+        .read(collectionPath, slug, { resolveReferences: false })
+        .catch(() => undefined);
+    if (doc === undefined)
+        return [];
+    const data = 'body' in doc ? mergeBodyIntoData(fields, doc.data, doc.body) : doc.data;
+    return findMarkdownSafetyIssues(fields, doc.format, data, siteAllow);
+};
 const writeContentHandler = async (gc, ctx, req, params, body) => {
     const { branchContext } = gc;
     const flatSchema = branchContext.flatSchema;
@@ -216,15 +235,20 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
     if (resolvedEntryType?.unavailable) {
         throw new SchemaUnavailableError(resolvedEntryType.name, resolvedEntryType.unavailable);
     }
-    const data = body.data ?? {};
     const isDataOnly = isDataOnlyFormat(body.format);
+    // An md/mdx file's body field is its body, so a frontmatter key of that name is dropped: no
+    // check would see it, and a read or a resolved reference would serve it as the body.
+    const requestData = isDataOnly || body.data === undefined
+        ? body.data
+        : withoutKey(body.data, findBodyFieldName(fields));
+    const data = requestData ?? {};
     // The store's own `undefined` (blind write) is never reachable from here: an omitted token is
     // a create, so an update that lost its token 409s instead of overwriting unchecked.
     const expectedVersion = body.expectedVersion ?? null;
     const createConflictError = body.expectedVersion === null
         ? `An entry with slug "${slug}" already exists`
         : `An entry with slug "${slug}" already exists; an update must send the expectedVersion from its last read`;
-    const danglingWarnings = [];
+    const keptWarnings = [];
     try {
         const exists = await store.documentExists(schemaItem.logicalPath, slug);
         // Create guard: a create against a slug that already has content must never silently
@@ -276,6 +300,24 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
             // as the schema's isBody field.
             const dataForValidation = isDataOnly ? data : mergeBodyIntoData(fields, data, body.body ?? '');
             const fieldErrors = validateEntryData(fields, dataForValidation);
+            // Code in markdown or MDX (validation/markdown-safety.ts). A field the stored entry held
+            // with code is kept, with a warning, when saved unchanged; any other code is refused.
+            const { mdxAllow } = ctx.services.config;
+            const unsafe = findMarkdownSafetyIssues(fields, body.format, dataForValidation, mdxAllow);
+            if (unsafe.length > 0) {
+                const stored = exists
+                    ? await storedMarkdownSafetyIssues(store, schemaItem.logicalPath, slug, fields, mdxAllow)
+                    : [];
+                const { refused, kept } = splitByStored(unsafe, stored);
+                fieldErrors.push(...refused);
+                for (const e of kept) {
+                    keptWarnings.push({
+                        level: 'warning',
+                        fieldPath: e.fieldPath,
+                        message: `holds content this field refuses, kept because the saved entry already had it: ${e.message}. Ask a developer to move it into a component, or to allow it.`,
+                    });
+                }
+            }
             // Reference existence (server-only: reads the content ID index). Editor
             // payloads may still carry resolved `{ id, ... }` objects from a prior
             // read, so collapse them to id strings before checking.
@@ -292,7 +334,7 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
                     : new Set();
                 for (const e of refResult.errors) {
                     if (e.dangling && storedSites.has(referenceSite(e.fieldPath, e.id))) {
-                        danglingWarnings.push({
+                        keptWarnings.push({
                             level: 'warning',
                             fieldPath: e.fieldPath,
                             message: `references a missing entry (${e.id}). It is kept as it was; repoint or clear it.`,
@@ -323,7 +365,7 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
     // Adopter save-time validation, run BEFORE the file is written: 'error' issues
     // refuse the save (e.g. a body that would break the site's production build),
     // 'warning' issues are returned alongside the successful write.
-    let validationWarnings = danglingWarnings.length > 0 ? danglingWarnings : undefined;
+    let validationWarnings = keptWarnings.length > 0 ? keptWarnings : undefined;
     const validateEntry = ctx.services.config.validateEntry;
     // Collapse resolved reference objects back to bare ID strings before persisting (the reference
     // validator above gets its own copy). The editor's GET resolves references by default, so form
@@ -331,7 +373,7 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
     // left unnormalized, a save would freeze that snapshot into the file (resolution only
     // re-resolves plain ID strings), permanently severing the reference from its target. Idempotent:
     // a payload that already holds ID strings is unchanged.
-    const normalizedData = body.data === undefined ? undefined : normalizeReferenceValues(fields, body.data);
+    const normalizedData = requestData === undefined ? undefined : normalizeReferenceValues(fields, requestData);
     // Computed before the validateEntry hook and the entry-link scan too, not just the write, so
     // every consumer agrees on the same bytes — otherwise an adopter's hook could see a resolved
     // object while the file got an ID string, depending on whether the post came from the editor.
@@ -366,7 +408,9 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
             issues = await validateEntry({
                 entryPath: logicalPathSegments.join('/'),
                 branch: params.branch,
-                ...(params.entryType ? { entryType: params.entryType } : {}),
+                // The type the store writes with, so a request that omits `entryType` can't skip a
+                // type-gated rule.
+                ...(entryTypeName ? { entryType: entryTypeName } : {}),
                 format: body.format,
                 data: normalizedData ?? {},
                 body: body.body,

package/dist/api/github-sync.d.ts

@@ -8,11 +8,19 @@ export interface GitHubSyncResult {
     prUrl?: string;
     prNumber?: number;
     syncStatus?: SyncStatus;
+    /** Client-safe reason a direct GitHub call failed, recorded as the branch's syncFailureReason. */
+    syncFailureReason?: string;
+    /** GitHub refused the PR because the pushed branch has no commits its base lacks. */
+    nothingToSubmit?: boolean;
+    /** The direct path, whose submit pushes to GitHub itself: the branch is there whatever the PR call did. */
+    pushedToGitHub?: boolean;
 }
 /** What the PR body records about a submit. */
 export interface SubmissionRecord {
     submitter?: SubmissionEditor;
     changedPaths: readonly string[];
+    /** The submit's `submittedAt`, carried to the worker so its failure handling targets this submit. */
+    submittedAt?: string;
 }
 /**
  * Uses githubService directly if available, otherwise queues a task for the worker.
@@ -28,9 +36,9 @@ export declare function syncSubmitPr(ctx: ApiContext, context: BranchContext, su
 export declare function syncConvertToDraft(ctx: ApiContext, context: BranchContext): Promise<void>;
 /**
  * Used by delete, after the local delete succeeded. Deletes the branch on GitHub when the CMS
- * put it there: a content branch reaches GitHub only through submit, which always opens a PR,
- * so a recorded PR number is the proof. Without one, a same-named GitHub branch is someone
- * else's (the create-time collision check is best-effort) and is never touched.
+ * put it there: a recorded PR number or `pushedToGitHubAt` stamp is the proof (a submit whose PR
+ * GitHub refused pushed the branch but has no PR number). Without either, a same-named GitHub
+ * branch is someone else's (the create-time collision check is best-effort) and is never touched.
  *
  * Returns a client-facing warning when the delete could not be done or queued; never throws.
  */

package/dist/api/github-sync.js

@@ -1,10 +1,10 @@
 import { enqueueTask } from '../task-queue/cms-task-queue.js';
 import { getTaskQueueDir } from '../task-queue/task-queue-config.js';
 import { clientOperatingStrategy } from '../operating-mode/index.js';
-import { getErrorMessage } from '../utils/error.js';
+import { getErrorMessage, sanitizeErrorMessage } from '../utils/error.js';
 import { sanitizeBranchName } from '../paths/branch-name.js';
 import { buildPrSection, mergePrSection } from '../submission-attribution.js';
-import { isRefAlreadyGoneError } from '../github-service.js';
+import { isNoCommitsBetweenError, isRefAlreadyGoneError } from '../github-service.js';
 /**
  * Uses githubService directly if available, otherwise queues a task for the worker.
  *
@@ -65,6 +65,7 @@ export async function syncSubmitPr(ctx, context, submission) {
                     prUrl: context.branch.pullRequestUrl,
                     prNumber: context.branch.pullRequestNumber,
                     syncStatus: 'synced',
+                    pushedToGitHub: true,
                 };
             }
             else {
@@ -92,16 +93,21 @@ export async function syncSubmitPr(ctx, context, submission) {
                     prUrl: result.url,
                     prNumber: result.number,
                     syncStatus: 'synced',
+                    pushedToGitHub: true,
                 };
             }
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : 'Unknown error';
+            const message = getErrorMessage(err);
             console.error(`CanopyCMS: Failed to create/update PR for ${context.branch.name}:`, message);
+            if (isNoCommitsBetweenError(err))
+                return { nothingToSubmit: true, pushedToGitHub: true };
             return {
                 prUrl: context.branch.pullRequestUrl,
                 prNumber: context.branch.pullRequestNumber,
                 syncStatus: 'sync-failed',
+                syncFailureReason: sanitizeErrorMessage(message),
+                pushedToGitHub: true,
             };
         }
     }
@@ -124,6 +130,7 @@ export async function syncSubmitPr(ctx, context, submission) {
             // A content submit is an explicit "ready for review" action: convert a
             // pre-existing draft PR to ready.
             markReadyIfDraft: true,
+            submittedAt: submission.submittedAt,
         },
     });
 }
@@ -159,14 +166,15 @@ export async function syncConvertToDraft(ctx, context) {
 }
 /**
  * Used by delete, after the local delete succeeded. Deletes the branch on GitHub when the CMS
- * put it there: a content branch reaches GitHub only through submit, which always opens a PR,
- * so a recorded PR number is the proof. Without one, a same-named GitHub branch is someone
- * else's (the create-time collision check is best-effort) and is never touched.
+ * put it there: a recorded PR number or `pushedToGitHubAt` stamp is the proof (a submit whose PR
+ * GitHub refused pushed the branch but has no PR number). Without either, a same-named GitHub
+ * branch is someone else's (the create-time collision check is best-effort) and is never touched.
  *
  * Returns a client-facing warning when the delete could not be done or queued; never throws.
  */
 export async function syncDeleteRemoteBranch(ctx, context) {
-    if (!context.branch.pullRequestNumber)
+    const { pullRequestNumber, pushedToGitHubAt } = context.branch;
+    if (!pullRequestNumber && !pushedToGitHubAt)
         return undefined;
     const { githubService } = ctx.services;
     const branch = context.branch.name;
@@ -187,7 +195,7 @@ export async function syncDeleteRemoteBranch(ctx, context) {
         return undefined;
     const result = await enqueueGitHubTask(ctx, context, {
         action: 'delete-remote-branch',
-        payload: { branch, pullRequestNumber: context.branch.pullRequestNumber },
+        payload: { branch, pullRequestNumber, pushedToGitHubAt },
     });
     return result.syncStatus === 'sync-failed'
         ? 'Deleting the branch on GitHub could not be queued; delete it there by hand'

package/dist/api/guards.js

@@ -3,6 +3,8 @@
  * error response (404/403/500) to short-circuit, or produce a guard context (e.g. branch context
  * with schema) for the handler. See api/AGENTS.md for the full guard reference.
  */
+import { BRANCH_METADATA_CORRUPT_MESSAGE, BranchMetadataCorruptError, } from '../branch-metadata-error.js';
+import { canopyLogError } from '../utils/logger.js';
 import { isAdmin, isReviewer, isPrivileged } from '../authorization/helpers.js';
 import { getBranchProtection, getBranchWriteProtection } from '../authorization/protected-branch.js';
 function extractBranchName(params) {
@@ -117,8 +119,8 @@ const runWritableBranchGuard = async (ctx, _req, params, accumulated) => {
         const branchStatus = context.branch.status;
         const error = branchStatus === 'submitted'
             ? `Branch "${context.branch.name}" is submitted for review and cannot be edited. Withdraw it or request changes to resume editing.`
-            : // Unreadable status: branch.json parses without schema validation, so a
-                // damaged file reaches here with no status. Refuse rather than guess.
+            : // A branch.json without a status is refused as corrupt before this
+                // point; a context built elsewhere can still lack one. Refuse rather than guess.
                 branchStatus === undefined
                     ? `Branch "${context.branch.name}" has no readable workflow status and cannot be edited until its metadata is repaired.`
                     : `Branch "${context.branch.name}" is ${branchStatus} and cannot be edited.`;
@@ -196,7 +198,21 @@ export async function executeGuards(guards, ctx, req, params) {
     const accumulated = {};
     for (const guardId of guards) {
         const runner = GUARD_RUNNERS[guardId];
-        const result = await runner(ctx, req, params, accumulated);
+        let result;
+        try {
+            result = await runner(ctx, req, params, accumulated);
+        }
+        catch (err) {
+            // Every branch guard resolves the branch from its branch.json, and a
+            // corrupt one has no status or ACL anyone can trust: deny, whatever the guard.
+            if (!(err instanceof BranchMetadataCorruptError))
+                throw err;
+            canopyLogError(`CanopyCMS: ${err.message}`);
+            return {
+                ok: false,
+                response: { ok: false, status: 500, error: BRANCH_METADATA_CORRUPT_MESSAGE },
+            };
+        }
         if (!result.ok) {
             return { ok: false, response: result.response };
         }

package/dist/api/types.d.ts

@@ -53,6 +53,7 @@ export interface ApiResponse<TData = unknown> {
 }
 /**
  * `SCHEMA_UNAVAILABLE`: the entry's type names an entry schema the running code lacks (a 503,
- * see `SchemaUnavailableError`).
+ * see `SchemaUnavailableError`). `WORKER_FAILED`: the CMS worker recorded that its latest start
+ * failed, so a retry will not help until an admin fixes it (a 503 with no `Retry-After`).
  */
-export type ApiErrorCode = 'SCHEMA_UNAVAILABLE';
+export type ApiErrorCode = 'SCHEMA_UNAVAILABLE' | 'WORKER_FAILED';

package/dist/authorization/protected-branch.d.ts

@@ -76,9 +76,10 @@ export declare function getBranchProtection(config: Pick<CanopyConfig, 'mode' |
  * branches-list wire flag and the editor.
  *
  * `status` is REQUIRED and admits `undefined` because a missing status must
- * FAIL CLOSED: `branch.json` is read with a bare `JSON.parse(...) as
- * BranchMetadataFile` (branch-metadata.ts), so it can be absent at runtime.
- * Required, not optional, so "argument omitted" and "file had no status" stay
- * distinguishable -- the safe answer differs.
+ * FAIL CLOSED. A branch.json without one never gets this far (its read
+ * boundary, branch-metadata-file.ts, rejects it as corrupt), but a status can
+ * still arrive unset from a context built anywhere else. Required, not
+ * optional, so "argument omitted" and "status unknown" stay distinguishable --
+ * the safe answer differs.
  */
 export declare function getBranchWriteProtection(config: Pick<CanopyConfig, 'mode' | 'defaultBaseBranch'>, branchName: string, recordedBaseBranch: string | undefined, status: BranchStatus | undefined): BranchWriteProtection;

package/dist/authorization/protected-branch.js

@@ -47,10 +47,11 @@ export function getBranchProtection(config, branchName, recordedBaseBranch) {
  * branches-list wire flag and the editor.
  *
  * `status` is REQUIRED and admits `undefined` because a missing status must
- * FAIL CLOSED: `branch.json` is read with a bare `JSON.parse(...) as
- * BranchMetadataFile` (branch-metadata.ts), so it can be absent at runtime.
- * Required, not optional, so "argument omitted" and "file had no status" stay
- * distinguishable -- the safe answer differs.
+ * FAIL CLOSED. A branch.json without one never gets this far (its read
+ * boundary, branch-metadata-file.ts, rejects it as corrupt), but a status can
+ * still arrive unset from a context built anywhere else. Required, not
+ * optional, so "argument omitted" and "status unknown" stay distinguishable --
+ * the safe answer differs.
  */
 export function getBranchWriteProtection(config, branchName, recordedBaseBranch, status) {
     const protection = getBranchProtection(config, branchName, recordedBaseBranch);

package/dist/branch-health.js

@@ -100,13 +100,14 @@ export async function scanBranchHealth(baseRoot, opts) {
         }
         if (loadErr) {
             // Every loadOnly failure lands here — BranchMetadataCorruptError for bad
-            // JSON, EACCES/EISDIR and the rest for everything else — since all of
-            // them need admin attention and none may throw out of the scan.
+            // JSON or a failed schema check, EACCES/EISDIR and the rest for
+            // everything else — since all of them need admin attention and none may
+            // throw out of the scan.
             //
             // [REDACT] parseError reaches the browser through the admin branch-health
             // endpoint, so it must never carry the absolute workspace path.
-            // BranchMetadataCorruptError's `parseCause` is the path-free JSON.parse
-            // message for exactly this, while its `message` embeds branchRoot and is
+            // BranchMetadataCorruptError's `parseCause` is the path-free cause
+            // for exactly this, while its `message` embeds branchRoot and is
             // for server logs only. Node errors embed the path in `message` too, so
             // only their `code` is safe to surface.
             const parseError = loadErr instanceof BranchMetadataCorruptError

package/dist/branch-metadata-error.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The corrupt-`branch.json` error and what the API says about it. Free of
+ * node built-ins, so the API guards, which the client bundle reaches, can
+ * recognize the error without pulling in the reader (branch-metadata-file.ts).
+ */
+/** What the editor API answers for a branch whose branch.json is corrupt. */
+export declare const BRANCH_METADATA_CORRUPT_MESSAGE = "This branch's metadata file is damaged, so the branch can't be opened or edited. An admin can repair it in System health.";
+/**
+ * branch.json exists but is not valid JSON, or fails the schema in branch-metadata-file.ts.
+ * Distinguished from provisioning and IO failures so callers can degrade instead
+ * of failing hard: the registry scan quarantines the branch, the API answers
+ * {@link BRANCH_METADATA_CORRUPT_MESSAGE}, and the request handler keeps serving
+ * (with empty internal groups) when the BASE branch is the corrupt one —
+ * otherwise the admin recovery surface is unreachable exactly when it is needed.
+ */
+export declare class BranchMetadataCorruptError extends Error {
+    readonly branchRoot: string;
+    /**
+     * [REDACT] What is wrong with the file, with no embedded path: the JSON.parse
+     * failure, or the fields that failed the schema.
+     * `message` above keeps the `branchRoot`-qualified text for server logs;
+     * `parseCause` is the one callers surface to clients (branch-health.ts's
+     * `parseError`), so no scan leaks the absolute workspace path.
+     */
+    readonly parseCause: string;
+    constructor(branchRoot: string, cause: string);
+}

package/dist/branch-metadata-error.js

@@ -0,0 +1,23 @@
+/**
+ * The corrupt-`branch.json` error and what the API says about it. Free of
+ * node built-ins, so the API guards, which the client bundle reaches, can
+ * recognize the error without pulling in the reader (branch-metadata-file.ts).
+ */
+/** What the editor API answers for a branch whose branch.json is corrupt. */
+export const BRANCH_METADATA_CORRUPT_MESSAGE = "This branch's metadata file is damaged, so the branch can't be opened or edited. An admin can repair it in System health.";
+/**
+ * branch.json exists but is not valid JSON, or fails the schema in branch-metadata-file.ts.
+ * Distinguished from provisioning and IO failures so callers can degrade instead
+ * of failing hard: the registry scan quarantines the branch, the API answers
+ * {@link BRANCH_METADATA_CORRUPT_MESSAGE}, and the request handler keeps serving
+ * (with empty internal groups) when the BASE branch is the corrupt one —
+ * otherwise the admin recovery surface is unreachable exactly when it is needed.
+ */
+export class BranchMetadataCorruptError extends Error {
+    constructor(branchRoot, cause) {
+        super(`Corrupt branch metadata in '${branchRoot}': ${cause}`);
+        this.name = 'BranchMetadataCorruptError';
+        this.branchRoot = branchRoot;
+        this.parseCause = cause;
+    }
+}