canopycms 0.0.68-int.98 → 0.1.0

package/dist/ai/resolve-branch.js

@@ -4,6 +4,8 @@
  */
 import { loadOrCreateBranchContext } from '../branch-workspace.js';
 import { readsFromCheckout } from '../build-mode.js';
+import { GitManager } from '../git-manager.js';
+import { baseBranchOf } from '../utils/base-branch.js';
 import { detectHeadBranch } from '../utils/git.js';
 /**
  * Resolve the branch root directory for reading content.
@@ -15,6 +17,11 @@ export async function resolveBranchRoot(config) {
     if (readsFromCheckout(config)) {
         return process.cwd();
     }
+    // Prod reads an unset base branch from the remote's HEAD, as services does; provisioning
+    // needs it even when the active branch is configured.
+    const resolved = config.mode === 'prod' && !config.defaultBaseBranch
+        ? { ...config, defaultBaseBranch: await GitManager.detectBaseBranch(config, 'throw') }
+        : config;
     let activeBranch;
     if (config.defaultActiveBranch) {
         activeBranch = config.defaultActiveBranch;
@@ -23,10 +30,10 @@ export async function resolveBranchRoot(config) {
         activeBranch = await detectHeadBranch(process.cwd(), config.defaultBaseBranch ?? 'main');
     }
     else {
-        activeBranch = config.defaultBaseBranch ?? 'main';
+        activeBranch = baseBranchOf(resolved);
     }
     const context = await loadOrCreateBranchContext({
-        config,
+        config: resolved,
         branchName: activeBranch,
         mode: config.mode,
         createdBy: 'canopycms-ai',

package/dist/ai/to-plain-text.d.ts

@@ -10,22 +10,31 @@
  * their children's text**: deleting a `<Callout>...</Callout>` wholesale
  * would silently drop every word inside it from the search index.
  *
+ * The input is an entry body, with its front matter already split off, as
+ * the content store returns it. There is no front-matter step: a body may
+ * open with a `---` thematic break, which a front-matter parser would read as
+ * the start of a block and swallow the prose after it.
+ *
  * Pipeline (each step operates on the previous step's output):
- * 1. Strip YAML frontmatter (via `gray-matter`, the same parser
- *    `content-store.ts` uses for `.md`/`.mdx` bodies).
- * 2. Strip `import`/`export` statements (via `stripMdxImports`), which also
+ * 1. Strip `import`/`export` statements (via `stripMdxImports`), which also
  *    protects fenced code blocks from every later step.
- * 3. Mask fenced code blocks and inline code spans, capturing their content.
+ * 2. Mask fenced code blocks and inline code spans, capturing their content.
+ * 3. Strip HTML/MDX comments (see `stripHtmlComments` below).
  * 4. Strip JSX/HTML tags via a single global replace (see `TAG_RE` below).
  * 5. Strip JSX expressions (`{...}`, including nested braces) — these are
  *    code, not prose.
  * 6. Strip common Markdown syntax (see `stripMarkdownSyntax` below).
- * 7. Restore the masked code from step 3 as plain text.
+ * 7. Restore the masked code from step 2 as plain text.
  * 8. Collapse whitespace: trim each line, collapse runs of blank lines,
  *    trim the result. Paragraph breaks (single blank lines) are preserved.
  */
 /**
- * Convert MDX/Markdown body content to plain prose text.
+ * Convert an MDX/Markdown entry body to plain prose text.
+ *
+ * Pass the body only: the value of the entry's body field, such as
+ * `entry.data.body` when the schema names that field `body`. Front matter
+ * in the input is treated as prose, so a caller holding a whole file splits
+ * it first, for example with `matter(file, {}).content`.
  *
  * See the module doc above for the full pipeline and why this exists as a
  * distinct transform from `stripMdxImports`.
@@ -37,6 +46,6 @@
  * Output preserves paragraph breaks (blank lines) but is not further
  * chunked, weighted, or field-selected — composing that into a search
  * document is left to the caller, since that logic is where adopter search
- * indexes genuinely diverge (see docs/adopter-migration.md).
+ * indexes genuinely diverge (see CHANGELOG.md).
  */
-export declare function toPlainText(markdown: string): string;
+export declare function toPlainText(body: string): string;

package/dist/ai/to-plain-text.js

@@ -10,21 +10,24 @@
  * their children's text**: deleting a `<Callout>...</Callout>` wholesale
  * would silently drop every word inside it from the search index.
  *
+ * The input is an entry body, with its front matter already split off, as
+ * the content store returns it. There is no front-matter step: a body may
+ * open with a `---` thematic break, which a front-matter parser would read as
+ * the start of a block and swallow the prose after it.
+ *
  * Pipeline (each step operates on the previous step's output):
- * 1. Strip YAML frontmatter (via `gray-matter`, the same parser
- *    `content-store.ts` uses for `.md`/`.mdx` bodies).
- * 2. Strip `import`/`export` statements (via `stripMdxImports`), which also
+ * 1. Strip `import`/`export` statements (via `stripMdxImports`), which also
  *    protects fenced code blocks from every later step.
- * 3. Mask fenced code blocks and inline code spans, capturing their content.
+ * 2. Mask fenced code blocks and inline code spans, capturing their content.
+ * 3. Strip HTML/MDX comments (see `stripHtmlComments` below).
  * 4. Strip JSX/HTML tags via a single global replace (see `TAG_RE` below).
  * 5. Strip JSX expressions (`{...}`, including nested braces) — these are
  *    code, not prose.
  * 6. Strip common Markdown syntax (see `stripMarkdownSyntax` below).
- * 7. Restore the masked code from step 3 as plain text.
+ * 7. Restore the masked code from step 2 as plain text.
  * 8. Collapse whitespace: trim each line, collapse runs of blank lines,
  *    trim the result. Paragraph breaks (single blank lines) are preserved.
  */
-import matter from 'gray-matter';
 import { stripMdxImports } from './strip-mdx.js';
 /**
  * Masking markers use `@` right after `<` (and before the closing `>`),
@@ -254,7 +257,12 @@ function collapseWhitespace(text) {
         .trim();
 }
 /**
- * Convert MDX/Markdown body content to plain prose text.
+ * Convert an MDX/Markdown entry body to plain prose text.
+ *
+ * Pass the body only: the value of the entry's body field, such as
+ * `entry.data.body` when the schema names that field `body`. Front matter
+ * in the input is treated as prose, so a caller holding a whole file splits
+ * it first, for example with `matter(file, {}).content`.
  *
  * See the module doc above for the full pipeline and why this exists as a
  * distinct transform from `stripMdxImports`.
@@ -266,15 +274,10 @@ function collapseWhitespace(text) {
  * Output preserves paragraph breaks (blank lines) but is not further
  * chunked, weighted, or field-selected — composing that into a search
  * document is left to the caller, since that logic is where adopter search
- * indexes genuinely diverge (see docs/adopter-migration.md).
+ * indexes genuinely diverge (see CHANGELOG.md).
  */
-export function toPlainText(markdown) {
-    // Destructures `content` only: never touches `.data` (so the shared-instance
-    // hazard cannot apply) and never needs `.matter` (so the cache-hit hazard
-    // cannot apply either).
-    // eslint-disable-next-line no-restricted-syntax
-    const { content } = matter(markdown);
-    const withoutImports = stripMdxImports(content);
+export function toPlainText(body) {
+    const withoutImports = stripMdxImports(body);
     const { masked, restore } = maskCode(withoutImports);
     let result = masked;
     result = stripHtmlComments(result);

package/dist/ai/types.d.ts

@@ -5,6 +5,33 @@
  * from CanopyCMS content, and the output manifest/metadata structures.
  */
 import type { FieldConfig } from '../config/index.js';
+import type { MissingReference, ResolvedReferenceMeta } from '../entry-schema.js';
+import type { SeoFieldLocation } from '../static/seo.js';
+/** A reference whose target this export shows: the target's own data plus where it lives. */
+export type AIResolvedReference = Record<string, unknown> & ResolvedReferenceMeta & {
+    unavailable?: undefined;
+};
+/**
+ * A reference whose target exists but is not in this export (left out by `exclude`, or its own
+ * markdown failed to render). Carries the id and nothing of the target, so no title of it can
+ * reach the output.
+ */
+export type AIExcludedReference = {
+    id: string;
+    unavailable: true;
+    reason: 'excluded';
+};
+/**
+ * A reference whose target this export does not show: a `MissingReference` when the id names no
+ * readable entry, an {@link AIExcludedReference} when the export leaves the target out.
+ */
+export type AIUnavailableReference = MissingReference | AIExcludedReference;
+/**
+ * What a `reference` field holds in {@link AIEntryMeta.data} (an array of these for
+ * `list: true`), at any depth, in place of the stored id; a cleared reference stays `''`. Branch
+ * on `unavailable` before reading anything but `id`.
+ */
+export type AIReferenceValue = AIResolvedReference | AIUnavailableReference;
 /**
  * Metadata about an entry, provided to filter/predicate functions.
  * Does not include the full data payload — use `where` predicates for
@@ -17,7 +44,11 @@ export interface AIEntryMeta {
     collectionName: string;
     entryType: string;
     format: string;
-    /** The entry's parsed data (frontmatter for MD/MDX, full data for JSON) */
+    /**
+     * The entry's parsed data (frontmatter for MD/MDX, full data for JSON), with every `reference`
+     * field holding an {@link AIReferenceValue} rather than the stored id. `exclude.where` sees a
+     * target the export leaves out in full; everything after it sees that target as unavailable.
+     */
     data: Record<string, unknown>;
 }
 /**
@@ -30,6 +61,12 @@ export interface ExcludeConfig {
     entryTypes?: string[];
     /** Custom predicate — return true to exclude the entry */
     where?: (entry: AIEntryMeta) => boolean;
+    /**
+     * Leave out entries marked `noindex`, read through `isNoindexEntry` at
+     * {@link AIContentConfig.seo}, the predicate the sitemap and robots metadata use. Default
+     * `true`; `false` exports them.
+     */
+    noindex?: boolean;
 }
 /**
  * Filter criteria for bundles. Filters are AND'd when combined.
@@ -57,7 +94,8 @@ export interface BundleConfig {
 }
 /**
  * Per-field markdown override function.
- * Return a markdown string to replace the default conversion for this field.
+ * Return a markdown string to replace the default conversion for this field. A `reference`
+ * field's value is an {@link AIReferenceValue}, or an array of them.
  */
 export type FieldTransformFn = (value: unknown, fieldConfig: FieldConfig) => string;
 /**
@@ -143,7 +181,8 @@ export interface EntryTransformContext {
     readSibling: (name: string) => Promise<string | null>;
 }
 /**
- * Per-entry-type transform. Runs once per entry at generation time (may be async). Return a
+ * Per-entry-type transform. Runs once per entry at generation time (may be async), and again if
+ * an entry it references fails to render and is masked out of its data. Return a
  * markdown string to APPEND after the entry's body/fields, or `undefined` to append nothing.
  * Append-only by design — `entryToMarkdown` remains the sole owner of base serialization.
  *
@@ -166,12 +205,52 @@ export type EntryTransformFn = (entry: AIEntry, ctx: EntryTransformContext) => P
  * Entry transform overrides, keyed by entry type name.
  */
 export type EntryTransforms = Record<string, EntryTransformFn>;
+/** What {@link AIReferenceLinkFn} knows about a target beyond its data. */
+export interface AIReferenceLinkContext {
+    /**
+     * The target's MD/MDX body as stored, `undefined` for a data-only entry. It only informs this
+     * decision: none of it reaches the entries that link to the target.
+     */
+    body: string | undefined;
+    /**
+     * The URL the export links by default: `entryLinkUrl`'s result when the site sets one, else
+     * the target's `urlPath`; `undefined` when neither gives one.
+     */
+    defaultUrl: string | undefined;
+}
+/**
+ * Where a link to an exported entry points, for every reference to it and every body `entry:`
+ * link to it. Return a URL to link there instead of `context.defaultUrl`, `false` when the target
+ * has no page (the title renders as plain text, with no page or markdown-version link), or
+ * `undefined` to keep the default. Called once per target per run, never for a missing target or
+ * one the exclusions leave out; a throw or any other return is logged and treated as `false`.
+ *
+ * @example
+ * ```ts
+ * // A person has a page only when their bio (the body) has prose
+ * referenceLink: (target, { body }) =>
+ *   target.collection === 'content/people' && !body?.trim() ? false : undefined
+ * ```
+ */
+export type AIReferenceLinkFn = (target: AIResolvedReference, context: AIReferenceLinkContext) => Promise<string | false | undefined> | string | false | undefined;
 /**
  * Main AI content configuration. Shared by route handler and build utility.
  */
 export interface AIContentConfig {
+    /**
+     * Site-relative URL path the generated files are served under, without the deployment
+     * `basePath`, as page links are. A reference links its target's markdown copy beneath it.
+     * Default `/ai`: where `canopycms init` mounts the route, and where `generate-ai-content`'s
+     * default `--output public/ai` is served. Set it when you serve the files elsewhere.
+     */
+    mountPath?: string;
     /** Opt-out exclusions — content to skip */
     exclude?: ExcludeConfig;
+    /**
+     * Where entries keep their SEO fields, when not the flat defaults. Drives the `noindex` read,
+     * so pass the same object as `createNextCanopyContext({ seo })`, or the two can disagree.
+     */
+    seo?: SeoFieldLocation;
     /** Custom bundles — filtered content subsets */
     bundles?: BundleConfig[];
     /** Per-entry-type, per-field markdown overrides */
@@ -182,6 +261,8 @@ export interface AIContentConfig {
     bodyTransforms?: BodyTransforms;
     /** Per-entry-type transforms that append markdown (e.g. folding in a colocated sibling artifact) */
     entryTransforms?: EntryTransforms;
+    /** Override or suppress the page link of a referenced or `entry:`-linked target */
+    referenceLink?: AIReferenceLinkFn;
 }
 /**
  * Identity function for type-checking AI content config.

package/dist/api/admin-branch-health.d.ts

@@ -13,9 +13,26 @@ import { z } from 'zod';
 import type { BranchAccessControl, BranchMetadata, BranchStatus } from '../types.js';
 import { type BranchHealthEntry } from '../branch-health.js';
 import type { ApiResponse } from './types.js';
+/**
+ * Wall-clock budget the opt-in duplicate-ID scan shares across every healthy
+ * branch: well inside the CMS Lambda's default 60 s timeout
+ * (`DEFAULT_CMS_LAMBDA_TIMEOUT` in canopycms-cdk), leaving the rest of the
+ * request its headroom.
+ * @internal Exported for tests.
+ */
+export declare const DUPLICATE_ID_SCAN_BUDGET_MS = 20000;
 export interface BranchHealthData {
     entries: BranchHealthEntry[];
     generatedAt: string;
+    /**
+     * Present only when the request asked for the duplicate-ID scan. `truncated`
+     * is true when the budget ran out before every healthy branch was scanned;
+     * those branches report `duplicateIdScan.state === 'unknown'`.
+     */
+    duplicateIdScan?: {
+        budgetMs: number;
+        truncated: boolean;
+    };
 }
 /** Response type for GET /admin/branch-health */
 export type BranchHealthResponse = ApiResponse<BranchHealthData>;
@@ -65,7 +82,13 @@ export type RepairContentDuplicatesResponse = ApiResponse<RepairContentDuplicate
  * router/generate-client import.
  */
 export declare const ADMIN_BRANCH_HEALTH_ROUTES: {
-    readonly branchHealth: import("./route-builder.js").RouteDefinition<undefined, undefined, BranchHealthResponse>;
+    readonly branchHealth: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+        duplicates: z.ZodOptional<z.ZodLiteral<"1">>;
+    }, "strip", z.ZodTypeAny, {
+        duplicates?: "1" | undefined;
+    }, {
+        duplicates?: "1" | undefined;
+    }>, undefined, BranchHealthResponse>;
     readonly purgeBranchDir: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         dirName: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
     }, "strip", z.ZodTypeAny, {

package/dist/api/admin-branch-health.js

@@ -17,7 +17,8 @@ import { BranchMetadataFileManager, getBranchMetadataFileManager } from '../bran
 // Same constants the reader uses, rather than a second copy of the two string
 // literals.
 import { BRANCH_META_DIR, BRANCH_META_FILE } from '../branch-metadata-file.js';
-import { scanBranchHealth } from '../branch-health.js';
+import { ORPHAN_YOUTH_THRESHOLD_MS, scanBranchHealth, } from '../branch-health.js';
+import { formatDirStamp } from '../branch-provisioning.js';
 import { ContentIdIndex } from '../content-id-index.js';
 import { invalidateContentIndexesDurable } from '../content-index-generation.js';
 import { getDefaultBranchBase, sanitizeBranchName } from '../paths/index.js';
@@ -26,10 +27,17 @@ import { branchProvisioningLockName, tryAcquireProvisioningLock } from '../utils
 import { withContentWriteLock, ContentWriteLockBusyError, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, } from '../utils/content-write-lock.js';
 import { getErrorMessage, isNodeError, isNotFoundError } from '../utils/error.js';
 import { defineEndpoint } from './route-builder.js';
+import { baseBranchOf } from '../utils/base-branch.js';
 /** [H1] A fresh (< 5 min old) init lock blocks purge -- provisioning may be running. */
 const PROVISIONING_LOCK_FRESH_MS = 5 * 60_000;
-/** An orphan dir younger than this may still be a clone in progress; corrupt dirs are exempt. */
-const ORPHAN_YOUTH_THRESHOLD_MS = 15 * 60_000;
+/**
+ * Wall-clock budget the opt-in duplicate-ID scan shares across every healthy
+ * branch: well inside the CMS Lambda's default 60 s timeout
+ * (`DEFAULT_CMS_LAMBDA_TIMEOUT` in canopycms-cdk), leaving the rest of the
+ * request its headroom.
+ * @internal Exported for tests.
+ */
+export const DUPLICATE_ID_SCAN_BUDGET_MS = 20_000;
 // Mirrors deleteTaskHandler's fileName pattern in admin.ts: conservative
 // charset plus explicit traversal/dot-prefix refinements (the regex alone
 // technically excludes '/' already, but the refinements keep intent explicit
@@ -40,13 +48,11 @@ const dirNameSchema = z
     .refine((v) => !v.includes('..'), { message: 'dirName must not contain ..' })
     .refine((v) => !v.startsWith('.'), { message: 'dirName must not be dot-prefixed' });
 const branchDirParamsSchema = z.object({ dirName: dirNameSchema });
-/** Compact UTC stamp for trash/archive names: `YYYYMMDDTHHMMSSZ` (no colons -- portability). */
-function formatTrashStamp(date) {
-    return date
-        .toISOString()
-        .replace(/[-:]/g, '')
-        .replace(/\.\d{3}Z$/, 'Z');
-}
+/**
+ * `duplicates=1` opts in to the duplicate-ID scan, a full content-tree readdir
+ * per healthy branch. The panel's 30 s poll leaves it off.
+ */
+const branchHealthParamsSchema = z.object({ duplicates: z.literal('1').optional() });
 /**
  * Re-resolve dirName under baseRoot and enforce containment (belt-and-
  * suspenders on top of the zod regex, matching deleteTaskHandler's pattern
@@ -68,19 +74,31 @@ class RepairPreconditionError extends Error {
         this.status = status;
     }
 }
-const getBranchHealthHandler = async (_gc, ctx, _req) => {
+const getBranchHealthHandler = async (_gc, ctx, _req, params) => {
     // Same derivation services.ts uses to construct the BranchRegistry --
     // admin handlers must agree with it or the scan silently looks at the
     // wrong directory.
     const baseRoot = getDefaultBranchBase(ctx.services.config.mode);
-    const baseBranchName = ctx.services.config.defaultBaseBranch ?? 'main';
+    const baseBranchName = baseBranchOf(ctx.services.config);
     const contentRootName = ctx.services.config.contentRoot || 'content';
+    const scanDuplicates = params.duplicates === '1';
     try {
-        const entries = await scanBranchHealth(baseRoot, { baseBranchName, contentRootName });
+        const entries = await scanBranchHealth(baseRoot, {
+            baseBranchName,
+            contentRootName,
+            ...(scanDuplicates ? { duplicateIdScan: { budgetMs: DUPLICATE_ID_SCAN_BUDGET_MS } } : {}),
+        });
+        const truncated = entries.some((e) => e.duplicateIdScan?.state === 'unknown' && e.duplicateIdScan.reason === 'out-of-time');
         return {
             ok: true,
             status: 200,
-            data: { entries, generatedAt: new Date().toISOString() },
+            data: {
+                entries,
+                generatedAt: new Date().toISOString(),
+                ...(scanDuplicates
+                    ? { duplicateIdScan: { budgetMs: DUPLICATE_ID_SCAN_BUDGET_MS, truncated } }
+                    : {}),
+            },
         };
     }
     catch (err) {
@@ -110,7 +128,7 @@ const getBranchHealthHandler = async (_gc, ctx, _req) => {
  */
 const purgeBranchDirHandler = async (_gc, ctx, _req, params) => {
     const baseRoot = getDefaultBranchBase(ctx.services.config.mode);
-    const baseBranchName = ctx.services.config.defaultBaseBranch ?? 'main';
+    const baseBranchName = baseBranchOf(ctx.services.config);
     const sanitizedBaseBranchName = sanitizeBranchName(baseBranchName);
     if (params.dirName === sanitizedBaseBranchName) {
         return { ok: false, status: 400, error: 'The base branch directory can never be purged' };
@@ -202,7 +220,7 @@ const purgeBranchDirHandler = async (_gc, ctx, _req, params) => {
             // [C1] The timestamp lives in the NAME, not the dir's mtime: rename()
             // preserves the original mtime, so mtime-based retention would delete
             // a months-stale orphan's trash on the very first cleanup pass.
-            const trashName = `.trash-${params.dirName}-${formatTrashStamp(new Date())}`;
+            const trashName = `.trash-${params.dirName}-${formatDirStamp(new Date())}`;
             const trashPath = path.join(baseRoot, trashName);
             try {
                 await fs.rename(dirPath, trashPath);
@@ -306,7 +324,7 @@ const repairBranchDirHandler = async (_gc, ctx, req, params) => {
                 if (recheck === 'missing') {
                     throw new RepairPreconditionError('No metadata file -- use purge for orphans', 409);
                 }
-                const archivedName = `${BRANCH_META_FILE}.corrupt-${formatTrashStamp(new Date())}`;
+                const archivedName = `${BRANCH_META_FILE}.corrupt-${formatDirStamp(new Date())}`;
                 await fs.rename(branchJsonPath, path.join(dirPath, BRANCH_META_DIR, archivedName));
                 return archivedName;
             });
@@ -420,7 +438,7 @@ async function checkStillCorrupt(dirPath) {
  * rebuild) and invalidates any ContentStore already registered in THIS
  * process for the same root.
  */
-const repairContentDuplicatesHandler = async (_gc, ctx, _req, params) => {
+const repairContentDuplicatesHandler = async (_gc, ctx, req, params) => {
     const baseRoot = getDefaultBranchBase(ctx.services.config.mode);
     const dirPath = resolveDirWithinBase(baseRoot, params.dirName);
     if (!dirPath) {
@@ -449,7 +467,7 @@ const repairContentDuplicatesHandler = async (_gc, ctx, _req, params) => {
             if (duplicates.length === 0) {
                 return { ok: false, status: 409, error: 'No duplicate content IDs found' };
             }
-            const stamp = formatTrashStamp(new Date());
+            const stamp = formatDirStamp(new Date());
             try {
                 for (const dup of duplicates) {
                     const archivedAs = [];
@@ -493,15 +511,26 @@ const repairContentDuplicatesHandler = async (_gc, ctx, _req, params) => {
                 : getErrorMessage(err),
         };
     }
+    finally {
+        // Archived files leave the branch at its next submit, a partial repair's included, so the
+        // admin is one of its editors. No `writableBranch` guard can say so: this route names a
+        // directory, not a branch.
+        if (resolved.length > 0) {
+            await ctx.services.recordBranchEditor({ branchRoot: dirPath, baseRoot }, req.user);
+        }
+    }
 };
 /**
- * Branch directory health scan (healthy/corrupt-metadata/orphan)
+ * Branch directory health scan (healthy/corrupt-metadata/orphan); `duplicates=1`
+ * adds the bounded duplicate-ID scan
  */
 const getBranchHealth = defineEndpoint({
     namespace: 'admin',
     name: 'branchHealth',
+    clientTimeout: 'long',
     method: 'GET',
     path: '/admin/branch-health',
+    params: branchHealthParamsSchema,
     responseType: 'BranchHealthResponse',
     response: {},
     defaultMockData: { entries: [], generatedAt: '2024-01-01T00:00:00.000Z' },
@@ -514,6 +543,7 @@ const getBranchHealth = defineEndpoint({
 const purgeBranchDir = defineEndpoint({
     namespace: 'admin',
     name: 'purgeBranchDir',
+    clientTimeout: 'long',
     method: 'POST',
     path: '/admin/branch-dirs/:dirName/purge',
     params: branchDirParamsSchema,
@@ -529,6 +559,7 @@ const purgeBranchDir = defineEndpoint({
 const repairBranchDir = defineEndpoint({
     namespace: 'admin',
     name: 'repairBranchDir',
+    clientTimeout: 'long',
     method: 'POST',
     path: '/admin/branch-dirs/:dirName/repair-metadata',
     params: branchDirParamsSchema,
@@ -558,6 +589,7 @@ const repairBranchDir = defineEndpoint({
 const repairContentDuplicates = defineEndpoint({
     namespace: 'admin',
     name: 'repairContentDuplicates',
+    clientTimeout: 'long',
     method: 'POST',
     path: '/admin/branch-dirs/:dirName/repair-content-duplicates',
     params: branchDirParamsSchema,

package/dist/api/admin.d.ts

@@ -10,6 +10,7 @@ import type { ApiResponse } from './types.js';
 import type { Task, QueueStats, CorruptTaskFile } from '../task-queue/cms-task-queue.js';
 import type { BuildIdentity, WorkerStatusReport } from '../types.js';
 import type { OperatingMode } from '../operating-mode/index.js';
+import type { SchemaIssue } from '../schema/types.js';
 export type { BranchHealthResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse, } from './admin-branch-health.js';
 type WorkerLivenessState = 'alive' | 'stale' | 'absent';
 export interface WorkerLiveness {
@@ -37,12 +38,23 @@ export interface AdminStatusData {
      * /admin.
      */
     settingsWorkspaceError?: string;
+    /** What the base branch's schema leaves out under this process's code; absent when nothing. */
+    schemaIssues?: SchemaIssue[];
     /** Build of the API process answering this request. */
     build: BuildIdentity;
     /** Whether `media` is configured; without it every upload returns 501. */
     assetStore: {
         configured: boolean;
     };
+    /**
+     * Whether THIS API process can load sharp. When false, any editor image not yet stored (a new
+     * crop, thumbnail or preview size, transformed on demand here) fails, and raster uploads are
+     * accepted without decode validation. Speaks only for the process that answers the request.
+     */
+    imageProcessing: {
+        available: boolean;
+        error?: string;
+    };
 }
 /** Response type for GET /admin/status */
 export type AdminStatusResponse = ApiResponse<AdminStatusData>;
@@ -66,10 +78,10 @@ declare const listAdminTasksParamsSchema: z.ZodObject<{
     status: z.ZodEnum<["pending", "processing", "completed", "failed", "corrupt"]>;
     limit: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    status: "failed" | "pending" | "processing" | "completed" | "corrupt";
+    status: "failed" | "pending" | "corrupt" | "processing" | "completed";
     limit?: number | undefined;
 }, {
-    status: "failed" | "pending" | "processing" | "completed" | "corrupt";
+    status: "failed" | "pending" | "corrupt" | "processing" | "completed";
     limit?: number | undefined;
 }>;
 export type ListAdminTasksParams = z.infer<typeof listAdminTasksParamsSchema>;
@@ -93,7 +105,13 @@ export type DeleteTaskParams = z.infer<typeof deleteTaskParamsSchema>;
  * `ADMIN_ROUTES` import.
  */
 export declare const ADMIN_ROUTES: {
-    readonly branchHealth: import("./route-builder.js").RouteDefinition<undefined, undefined, import("./admin-branch-health.js").BranchHealthResponse>;
+    readonly branchHealth: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+        duplicates: z.ZodOptional<z.ZodLiteral<"1">>;
+    }, "strip", z.ZodTypeAny, {
+        duplicates?: "1" | undefined;
+    }, {
+        duplicates?: "1" | undefined;
+    }>, undefined, import("./admin-branch-health.js").BranchHealthResponse>;
     readonly purgeBranchDir: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         dirName: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
     }, "strip", z.ZodTypeAny, {
@@ -120,10 +138,10 @@ export declare const ADMIN_ROUTES: {
         status: z.ZodEnum<["pending", "processing", "completed", "failed", "corrupt"]>;
         limit: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        status: "failed" | "pending" | "processing" | "completed" | "corrupt";
+        status: "failed" | "pending" | "corrupt" | "processing" | "completed";
         limit?: number | undefined;
     }, {
-        status: "failed" | "pending" | "processing" | "completed" | "corrupt";
+        status: "failed" | "pending" | "corrupt" | "processing" | "completed";
         limit?: number | undefined;
     }>, undefined, AdminTasksResponse>;
     readonly retryTask: import("./route-builder.js").RouteDefinition<z.ZodObject<{

package/dist/api/admin.js

@@ -14,7 +14,9 @@ import { WORKER_STATUS_FILE } from '../task-queue/worker-status.js';
 import { defineEndpoint } from './route-builder.js';
 import { getErrorMessage, isNotFoundError, redactCredentials } from '../utils/error.js';
 import { getBuildIdentity } from '../build-identity.js';
+import { loadSharp } from '../assets/sharp-loader.js';
 import { ADMIN_BRANCH_HEALTH_ROUTES } from './admin-branch-health.js';
+import { baseBranchOf } from '../utils/base-branch.js';
 /**
  * 60_000 = DEFAULT_LOCK_STALE_MS in worker/cms-worker.ts, hardcoded rather
  * than threaded through config: an adopter who overrides `lockStaleMs` skews
@@ -82,6 +84,24 @@ async function readSettingsWorkspaceError(ctx) {
         return redactCredentials(getErrorMessage(err));
     }
 }
+/**
+ * What the base branch's schema leaves out under this process's registry (see
+ * `BranchSchemaCache`). Empty when the probe cannot resolve it: that failure reaches the
+ * editor through every schema-guarded route anyway.
+ */
+async function readBaseSchemaIssues(ctx) {
+    try {
+        const { config, branchSchemaCache, entrySchemaRegistry } = ctx.services;
+        const base = await ctx.getBranchContext(baseBranchOf(config));
+        if (!base)
+            return [];
+        const { issues } = await branchSchemaCache.getSchema(base.branchRoot, entrySchemaRegistry, config.contentRoot || 'content');
+        return issues;
+    }
+    catch {
+        return [];
+    }
+}
 /** Age (ms) of the oldest file in pending/, or undefined if empty/missing. */
 async function getOldestPendingAgeMs(taskDir) {
     const pendingDir = path.join(taskDir, 'pending');
@@ -133,15 +153,27 @@ const deleteTaskParamsSchema = z.object({
         .regex(/^[A-Za-z0-9._-]{1,120}\.json$/)
         .refine((v) => !v.includes('..'), { message: 'fileName must not contain ..' }),
 });
+/** Loads sharp in this process; a failure is reported, never thrown. */
+async function probeImageProcessing() {
+    try {
+        await loadSharp();
+        return { available: true };
+    }
+    catch (err) {
+        return { available: false, error: getErrorMessage(err) };
+    }
+}
 const getAdminStatusHandler = async (_gc, ctx, _req) => {
     const taskDir = getTaskQueueDir(ctx.services.config);
     try {
-        const [queueStats, oldestPendingAgeMs, worker, { workerStatus, statusReadError }, settingsWorkspaceError,] = await Promise.all([
+        const [queueStats, oldestPendingAgeMs, worker, { workerStatus, statusReadError }, settingsWorkspaceError, imageProcessing, schemaIssues,] = await Promise.all([
             getQueueStats(taskDir),
             getOldestPendingAgeMs(taskDir),
             classifyWorkerLiveness(taskDir),
             readWorkerStatus(taskDir),
             readSettingsWorkspaceError(ctx),
+            probeImageProcessing(),
+            readBaseSchemaIssues(ctx),
         ]);
         return {
             ok: true,
@@ -157,8 +189,10 @@ const getAdminStatusHandler = async (_gc, ctx, _req) => {
                 workerStatus,
                 ...(statusReadError ? { statusReadError } : {}),
                 ...(settingsWorkspaceError ? { settingsWorkspaceError } : {}),
+                ...(schemaIssues.length > 0 ? { schemaIssues } : {}),
                 build: getBuildIdentity(),
                 assetStore: { configured: !!ctx.assetStore },
+                imageProcessing,
             },
         };
     }
@@ -271,6 +305,7 @@ const getAdminStatus = defineEndpoint({
         workerStatus: null,
         build: { canopycmsVersion: '0.0.0' },
         assetStore: { configured: false },
+        imageProcessing: { available: true },
     },
     guards: ['admin'],
     handler: getAdminStatusHandler,