canopycms 0.0.67-int.90 → 0.0.67

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

@@ -4,49 +4,31 @@
  *
  * This is deliberately a *different* transform from `stripMdxImports`
  * (strip-mdx.ts): that one is tuned for AI/RAG consumption and intentionally
- * leaves JSX components intact, because their props often carry semantic
- * data a model can use. `toPlainText` has the opposite goal — it removes ALL
- * markup (JSX tags, JSX expressions, markdown syntax) and keeps only the
- * prose, so **paired custom components lose their tags but keep their
- * children's text**. That distinction is the whole reason this function
- * exists: a hand-rolled plaintext stripper that treats a paired component
- * like `<Callout>...</Callout>` as one opaque unit and deletes it wholesale
- * silently drops every word inside it from the search index. `toPlainText`
- * strips the `<Callout>`/`</Callout>` delimiters but keeps the sentence
- * between them.
+ * leaves JSX components intact. `toPlainText` has the opposite goal — it
+ * removes ALL markup (JSX tags, JSX expressions, markdown syntax) and keeps
+ * only the prose, so **paired custom components lose their tags but keep
+ * their children's text**: deleting a `<Callout>...</Callout>` wholesale
+ * would silently drop every word inside it from the search index.
  *
  * 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
  *    protects fenced code blocks from every later step.
- * 3. Mask fenced code blocks and inline code spans, capturing their content
- *    (fence markers / backticks are discarded, the code text is kept).
- * 4. Strip JSX/HTML tags — opening, closing, and self-closing — leaving
- *    whatever text sits between them in place. This is a single global
- *    replace, not a matched-pair walk: because we never need the tag name or
- *    the children as a unit (unlike `applyComponentTransforms`, which calls
- *    an adopter transform per component), deleting every tag occurrence and
- *    leaving the surrounding text untouched handles nesting for free.
+ * 3. Mask fenced code blocks and inline code spans, capturing their content.
+ * 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: headings, emphasis/strikethrough, links
- *    (keep the link text, drop the URL), images (keep alt text), blockquote
- *    markers, list markers, and thematic breaks.
+ * 6. Strip common Markdown syntax (see `stripMarkdownSyntax` below).
  * 7. Restore the masked code from step 3 as plain text.
  * 8. Collapse whitespace: trim each line, collapse runs of blank lines,
- *    trim the result. Paragraph breaks (single blank lines) are preserved —
- *    this does not flatten the output to one line.
+ *    trim the result. Paragraph breaks (single blank lines) are preserved.
  */
 /**
  * Convert MDX/Markdown body content to plain prose text.
  *
  * See the module doc above for the full pipeline and why this exists as a
- * distinct transform from `stripMdxImports`. In short: frontmatter, code
- * fences, inline code, JSX tags/expressions, and Markdown syntax are all
- * stripped down to their human-readable text — code content and link/image
- * text are kept, everything else is discarded. Paired custom components
- * lose only their tags; the prose between them survives.
+ * distinct transform from `stripMdxImports`.
  *
  * HTML/MDX comments (`<!-- ... -->`) are removed along with their contents:
  * an authoring note is text the author marked as not-for-readers, so it does

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

@@ -4,39 +4,25 @@
  *
  * This is deliberately a *different* transform from `stripMdxImports`
  * (strip-mdx.ts): that one is tuned for AI/RAG consumption and intentionally
- * leaves JSX components intact, because their props often carry semantic
- * data a model can use. `toPlainText` has the opposite goal — it removes ALL
- * markup (JSX tags, JSX expressions, markdown syntax) and keeps only the
- * prose, so **paired custom components lose their tags but keep their
- * children's text**. That distinction is the whole reason this function
- * exists: a hand-rolled plaintext stripper that treats a paired component
- * like `<Callout>...</Callout>` as one opaque unit and deletes it wholesale
- * silently drops every word inside it from the search index. `toPlainText`
- * strips the `<Callout>`/`</Callout>` delimiters but keeps the sentence
- * between them.
+ * leaves JSX components intact. `toPlainText` has the opposite goal — it
+ * removes ALL markup (JSX tags, JSX expressions, markdown syntax) and keeps
+ * only the prose, so **paired custom components lose their tags but keep
+ * their children's text**: deleting a `<Callout>...</Callout>` wholesale
+ * would silently drop every word inside it from the search index.
  *
  * 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
  *    protects fenced code blocks from every later step.
- * 3. Mask fenced code blocks and inline code spans, capturing their content
- *    (fence markers / backticks are discarded, the code text is kept).
- * 4. Strip JSX/HTML tags — opening, closing, and self-closing — leaving
- *    whatever text sits between them in place. This is a single global
- *    replace, not a matched-pair walk: because we never need the tag name or
- *    the children as a unit (unlike `applyComponentTransforms`, which calls
- *    an adopter transform per component), deleting every tag occurrence and
- *    leaving the surrounding text untouched handles nesting for free.
+ * 3. Mask fenced code blocks and inline code spans, capturing their content.
+ * 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: headings, emphasis/strikethrough, links
- *    (keep the link text, drop the URL), images (keep alt text), blockquote
- *    markers, list markers, and thematic breaks.
+ * 6. Strip common Markdown syntax (see `stripMarkdownSyntax` below).
  * 7. Restore the masked code from step 3 as plain text.
  * 8. Collapse whitespace: trim each line, collapse runs of blank lines,
- *    trim the result. Paragraph breaks (single blank lines) are preserved —
- *    this does not flatten the output to one line.
+ *    trim the result. Paragraph breaks (single blank lines) are preserved.
  */
 import matter from 'gray-matter';
 import { stripMdxImports } from './strip-mdx.js';
@@ -271,11 +257,7 @@ function collapseWhitespace(text) {
  * Convert MDX/Markdown body content to plain prose text.
  *
  * See the module doc above for the full pipeline and why this exists as a
- * distinct transform from `stripMdxImports`. In short: frontmatter, code
- * fences, inline code, JSX tags/expressions, and Markdown syntax are all
- * stripped down to their human-readable text — code content and link/image
- * text are kept, everything else is discarded. Paired custom components
- * lose only their tags; the prose between them survives.
+ * distinct transform from `stripMdxImports`.
  *
  * HTML/MDX comments (`<!-- ... -->`) are removed along with their contents:
  * an authoring note is text the author marked as not-for-readers, so it does

package/dist/ai/transform-components.d.ts

@@ -14,13 +14,11 @@ import type { ComponentProps, ComponentTransforms } from './types.js';
  * Parse JSX attribute string into a props object.
  *
  * Handles: `key="value"`, `key='value'`, `key={expr}`, and boolean `key` (→ "true").
+ * @internal Exported for tests.
  */
 export declare function parseComponentProps(attrString: string): ComponentProps;
 /**
- * Apply component transforms to a body string.
- *
  * For each registered component name, finds JSX tags in the body and calls
- * the corresponding transform function. Processes via convergence loop to
- * handle nesting (inner components first, outer on subsequent passes).
+ * the corresponding transform function.
  */
 export declare function applyComponentTransforms(body: string, transforms: ComponentTransforms): string;

package/dist/ai/transform-components.js

@@ -13,12 +13,12 @@
  * Parse JSX attribute string into a props object.
  *
  * Handles: `key="value"`, `key='value'`, `key={expr}`, and boolean `key` (→ "true").
+ * @internal Exported for tests.
  */
 export function parseComponentProps(attrString) {
     const props = {};
     if (!attrString)
         return props;
-    // Match attribute patterns: name="value", name='value', name={expr}, or bare name
     // eslint-disable-next-line security/detect-unsafe-regex
     const attrRegex = /(\w+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|\{([^}]*)\}))?/g;
     let match;
@@ -30,10 +30,6 @@ export function parseComponentProps(attrString) {
     }
     return props;
 }
-/**
- * Mask fenced code blocks so component transforms don't touch them.
- * Returns the masked string and a restore function.
- */
 /** Regex fragment matching JSX attribute content, skipping quoted strings containing '>'. */
 const ATTR_CONTENT = `(?:[^>"']|"[^"]*"|'[^']*')*`;
 const BLOCK_PREFIX = '<<CODEBLOCK';
@@ -50,12 +46,12 @@ function isFenceCloseLine(line, marker) {
 }
 /**
  * Mask fenced code blocks (` ``` `/`~~~`), capturing each block's raw text (fence lines
- * included) exactly as `maskCodeBlocks` used to via `/^(```|~~~).*\n[\s\S]*?\n\1\s*$/gm`.
+ * included).
  *
- * A hand-rolled line scan, not that regex: it is a polynomial-ReDoS shape (measured ~9s on
- * ~530KB of body text with many unclosed fence openers — an ordinary authoring accident, not a
- * crafted payload) that CodeQL and three review rounds both missed elsewhere in this package
- * (see `ai/to-plain-text.ts`'s identical fix). The lazy `[\s\S]*?` has no bound on how far it
+ * A hand-rolled line scan, not a lazy regex like `/^(```|~~~).*\n[\s\S]*?\n\1\s*$/gm`: that
+ * shape is a polynomial-ReDoS hazard (measured ~9s on ~530KB of body text with many unclosed
+ * fence openers — an ordinary authoring accident, not a crafted payload; see
+ * `ai/to-plain-text.ts`'s identical fix). The lazy `[\s\S]*?` has no bound on how far it
  * must scan looking for a closing `\1` that, for an unclosed fence, never arrives — it exhausts
  * to the end of the string before giving up on that starting line, and `/gm` retries the same
  * exhaustive scan at every subsequent fence-opener line.
@@ -118,9 +114,8 @@ function maskFencedCodeBlocks(body, blocks) {
 function maskCodeBlocks(body) {
     const blocks = [];
     const inlines = [];
-    // 1. Mask fenced code blocks
     let masked = maskFencedCodeBlocks(body, blocks);
-    // 2. Mask inline code spans (double-backtick first, then single-backtick)
+    // Mask inline code spans (double-backtick first, then single-backtick)
     masked = masked.replace(/``[^`]+``|`[^`]+`/g, (span) => {
         const idx = inlines.length;
         inlines.push(span);
@@ -137,17 +132,13 @@ function maskCodeBlocks(body) {
     };
 }
 /**
- * Apply component transforms to a body string.
- *
  * For each registered component name, finds JSX tags in the body and calls
- * the corresponding transform function. Processes via convergence loop to
- * handle nesting (inner components first, outer on subsequent passes).
+ * the corresponding transform function.
  */
 export function applyComponentTransforms(body, transforms) {
     const names = Object.keys(transforms);
     if (names.length === 0)
         return body;
-    // Mask code blocks to protect them from transformation
     const { masked, restore } = maskCodeBlocks(body);
     let result = masked;
     const MAX_PASSES = 10;
@@ -175,7 +166,6 @@ export function applyComponentTransforms(body, transforms) {
                 const openStart = openMatch.index;
                 const openEnd = openStart + openMatch[0].length;
                 const attrStr = openMatch[1]?.trim() ?? '';
-                // Find matching close tag, accounting for nesting
                 const closeTag = `</${name}>`;
                 const closeIdx = findMatchingClose(result, openEnd, name, closeTag);
                 if (closeIdx === -1)
@@ -207,7 +197,6 @@ export function applyComponentTransforms(body, transforms) {
 function findMatchingClose(body, startFrom, name, closeTag) {
     let depth = 1;
     const pos = startFrom;
-    // Regex to find either an opening or closing tag for this component
     // eslint-disable-next-line security/detect-non-literal-regexp
     const tagRegex = new RegExp(`<${escapeRegex(name)}(?:\\s${ATTR_CONTENT})?>|<${escapeRegex(name)}(?:\\s${ATTR_CONTENT})?\\s*/>|${escapeRegex(closeTag)}`, 'g');
     tagRegex.lastIndex = pos;

package/dist/ai/types.d.ts

@@ -216,16 +216,11 @@ export interface AIManifestBundle {
 /** Top-level manifest for AI content */
 export interface AIManifest {
     /**
-     * When this content was generated, ISO-8601.
-     *
-     * OPTIONAL, and absent whenever the manifest carries a `buildId` and no usable
-     * `SOURCE_DATE_EPOCH` (unset, blank, or malformed — a rejected value does not fall back to a
-     * live clock, it leaves the field absent):
-     * under build-once-promote one artifact is built once and may be served months later, so a
-     * build clock describes the runner that produced it rather than the content, and anything
-     * reading it as "how fresh is this?" is misled by design. An adopter who has declared a build
-     * id has told us the date is not the identifying fact, so it is omitted rather than filled in
-     * with something arbitrary. Present unconditionally when neither env var is set.
+     * When this content was generated, ISO-8601. Absent when the manifest carries a `buildId`
+     * and no usable `SOURCE_DATE_EPOCH` (unset, blank, or malformed values are never replaced
+     * with a live clock): under build-once-promote a build clock describes the runner, not the
+     * content, and is misleading read as freshness once `buildId` says the artifact — not the
+     * date — is the identifying fact. Present unconditionally when neither env var is set.
      */
     generated?: string;
     /**

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

@@ -19,13 +19,13 @@ export interface BranchHealthData {
 }
 /** Response type for GET /admin/branch-health */
 export type BranchHealthResponse = ApiResponse<BranchHealthData>;
-export interface PurgeBranchDirData {
+interface PurgeBranchDirData {
     /** The dot-prefixed name the directory was renamed to, e.g. `.trash-foo-20260101T000000Z`. */
     trashedAs: string;
 }
 /** Response type for POST /admin/branch-dirs/:dirName/purge */
 export type PurgeBranchDirResponse = ApiResponse<PurgeBranchDirData>;
-export interface RepairBranchDirData {
+interface RepairBranchDirData {
     branch: BranchMetadata;
     /** The archived corrupt file's name, e.g. `branch.json.corrupt-20260101T000000Z`. */
     archivedAs: string;
@@ -48,26 +48,18 @@ export interface RepairBranchDirData {
 }
 /** Response type for POST /admin/branch-dirs/:dirName/repair-metadata */
 export type RepairBranchDirResponse = ApiResponse<RepairBranchDirData>;
-export interface RepairedContentDuplicate {
+interface RepairedContentDuplicate {
     id: string;
     /** The path that was kept (the deterministic winner) -- untouched by this repair. */
     keptPath: string;
     /** Archived names the quarantined duplicate(s) were renamed to, dot-prefixed so future scans skip them. */
     archivedAs: string[];
 }
-export interface RepairContentDuplicatesData {
+interface RepairContentDuplicatesData {
     resolved: RepairedContentDuplicate[];
 }
 /** Response type for POST /admin/branch-dirs/:dirName/repair-content-duplicates */
 export type RepairContentDuplicatesResponse = ApiResponse<RepairContentDuplicatesData>;
-declare const branchDirParamsSchema: z.ZodObject<{
-    dirName: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
-}, "strip", z.ZodTypeAny, {
-    dirName: string;
-}, {
-    dirName: string;
-}>;
-export type BranchDirParams = z.infer<typeof branchDirParamsSchema>;
 /**
  * Exported routes, merged into ADMIN_ROUTES in admin.ts for a single
  * router/generate-client import.

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

@@ -15,7 +15,7 @@ import { z } from 'zod';
 import { simpleGit } from 'simple-git';
 import { BranchMetadataFileManager, getBranchMetadataFileManager } from '../branch-metadata.js';
 // Same constants the reader uses, rather than a second copy of the two string
-// literals -- they were declared independently here until 2026-08-23.
+// literals.
 import { BRANCH_META_DIR, BRANCH_META_FILE } from '../branch-metadata-file.js';
 import { scanBranchHealth } from '../branch-health.js';
 import { ContentIdIndex } from '../content-id-index.js';
@@ -26,16 +26,10 @@ import { tryAcquireProvisioningLock } from '../utils/provisioning-lock.js';
 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';
-// ============================================================================
-// Constants
-// ============================================================================
 /** [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;
-// ============================================================================
-// Zod schemas
-// ============================================================================
 // 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
@@ -46,9 +40,6 @@ 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 });
-// ============================================================================
-// Shared helpers
-// ============================================================================
 /** Compact UTC stamp for trash/archive names: `YYYYMMDDTHHMMSSZ` (no colons -- portability). */
 function formatTrashStamp(date) {
     return date
@@ -77,9 +68,6 @@ class RepairPreconditionError extends Error {
         this.status = status;
     }
 }
-// ============================================================================
-// Handlers
-// ============================================================================
 const getBranchHealthHandler = async (_gc, ctx, _req) => {
     // Same derivation services.ts uses to construct the BranchRegistry --
     // admin handlers must agree with it or the scan silently looks at the
@@ -105,7 +93,7 @@ const getBranchHealthHandler = async (_gc, ctx, _req) => {
  * sweeps trash older than 30 days, see cleanupTrashedBranchDirs in
  * worker/rebase.ts).
  *
- * Safety rails (see the PR's design review for the finding IDs):
+ * Safety rails:
  * - [always] the base branch directory can never be purged.
  * - Server re-derives live/corrupt/orphan state itself -- never trusts the
  *   client's view of the world.
@@ -131,7 +119,7 @@ const purgeBranchDirHandler = async (_gc, ctx, _req, params) => {
     if (!dirPath) {
         return { ok: false, status: 400, error: 'Invalid directory name' };
     }
-    // [MEDIUM-1 rider] The directory must actually exist -- otherwise
+    // The directory must actually exist -- otherwise
     // withOccFileLock's `mkdir -p` below would CREATE it, and purge would
     // "succeed" with a phantom `.trash-*` entry for a directory that was
     // never there. Must run before anything below treats "no branch.json" as
@@ -238,50 +226,29 @@ const purgeBranchDirHandler = async (_gc, ctx, _req, params) => {
 };
 /**
  * Repair a corrupt branch.json by archiving it (forensics preserved as
- * `branch.json.corrupt-{STAMP}`, ignored by future scans since it doesn't
- * match the exact `branch.json` name) and recreating defaults via the
- * normal save() path. Unlike purge, the base branch IS a valid target here
- * -- a corrupt BASE branch.json is exactly the degraded-service scenario
- * this handler exists to fix.
+ * `branch.json.corrupt-{STAMP}`) and recreating defaults via save(). Unlike
+ * purge, the base branch IS a valid target -- a corrupt BASE branch.json is
+ * exactly the degraded-service scenario this handler exists to fix.
  *
- * [M4] Lock sequence: withOccFileLock is NOT reentrant, and save() takes it
- * internally, so the rename must happen and the lock must be RELEASED
- * (exiting the withOccFileLock callback) before save() runs -- calling
- * save() while still holding the lock would deadlock against itself.
+ * Lock sequence: withOccFileLock is NOT reentrant and save() takes its own
+ * hold, so the archive rename must complete and the lock must be RELEASED
+ * before save() runs, or save() would deadlock against itself. The
+ * provisioning lock stays held across the whole archive+save sequence, same
+ * order as purge (provisioning -> branch.json) so the two operations can
+ * never deadlock each other; without that hold, a concurrent purge could
+ * trash the directory mid-sequence and have save() resurrect a
+ * metadata-only ghost of it.
  *
- * The provisioning lock is held across the ENTIRE archive+save
- * sequence (acquired before withOccFileLock, released only after save()
- * completes), same lock order as purge (provisioning -> branch.json) so the
- * two can never deadlock against each other. Without this, a concurrent
- * purge could trash the directory in the window between this handler
- * releasing withOccFileLock (required before save(), per [M4] above) and
- * save() actually running -- save() would then resurrect a metadata-only
- * ghost of a directory purge just moved to trash.
- *
- * ## Reset, not recovered -- and why (August 2026 baseline review)
- *
- * save()'s defaults-merge sees no existing record once branch.json is
- * archived out of the way, so a `submitted` (write-locked) branch comes back
- * `editing` (unlocked), `access` ACLs are dropped to `{}`, and `createdBy`
- * becomes the ADMIN RUNNING THIS REPAIR, not the branch's real creator. This
- * handler deliberately does NOT attempt to recover those three fields from
- * the corrupt file, even though it is sometimes technically "partially
- * parseable" (e.g. valid JSON with a truncated tail, or a stray character
- * breaking otherwise-valid JSON): branch.json is written via
- * `writeOccJsonFile`, which is atomic (temp-file + rename/link, see
- * utils/occ-json-write.ts), so a genuinely corrupt file on disk is not
- * ordinary truncated-write debris -- it got that way some other, less
- * predictable way. `status`/`access` are security-adjacent (branch
- * protection and per-path ACLs); silently reinstating a best-effort guess
- * parsed out of a file that failed strict JSON.parse risks resurrecting
- * WRONG security state with no human review, which is worse than a clean,
- * clearly-reported reset. The archived file (`archivedAs`) is preserved
- * precisely so a human CAN recover the real values with full context (open
- * it, cross-check the GitHub PR, ask the editor) -- that is the safe
- * recovery path, not automation. What was missing before this fix was any
- * signal that a reset happened at all; the `reset` field on the response
- * closes that gap by always reporting the (new, defaulted) values for these
- * three fields, so the admin knows to re-apply the ACL and re-submit.
+ * Reset, not recovered: save()'s defaults-merge sees no existing record once
+ * branch.json is archived, so `status`/`access`/`createdBy` reset to
+ * `editing`/`{}`/the admin running this repair, even when the corrupt file
+ * is partially parseable. `status`/`access` are security-adjacent, and a
+ * genuinely corrupt branch.json (writes are atomic, so it didn't get that
+ * way from an ordinary truncated write) is not safe to best-effort-parse: a
+ * wrong guess with no human review is worse than a clean reset. The archived
+ * file lets a human recover the real values with full context instead. The
+ * response's `reset` field reports that a reset happened, so an admin never
+ * mistakes the new defaults for recovered data.
  */
 const repairBranchDirHandler = async (_gc, ctx, req, params) => {
     const baseRoot = getDefaultBranchBase(ctx.services.config.mode);
@@ -289,7 +256,7 @@ const repairBranchDirHandler = async (_gc, ctx, req, params) => {
     if (!dirPath) {
         return { ok: false, status: 400, error: 'Invalid directory name' };
     }
-    // [MEDIUM-1 rider] Same stat guard as purge: the directory must actually
+    // Same stat guard as purge: the directory must actually
     // exist, otherwise withOccFileLock's `mkdir -p` below would CREATE it.
     const dirExists = await fs
         .stat(dirPath)
@@ -522,12 +489,8 @@ const repairContentDuplicatesHandler = async (_gc, ctx, _req, params) => {
         };
     }
 };
-// ============================================================================
-// Route definitions
-// ============================================================================
 /**
  * Branch directory health scan (healthy/corrupt-metadata/orphan)
- * GET /admin/branch-health
  */
 const getBranchHealth = defineEndpoint({
     namespace: 'admin',
@@ -542,7 +505,6 @@ const getBranchHealth = defineEndpoint({
 });
 /**
  * Purge a corrupt-metadata or orphan branch directory (reversible trash-rename)
- * POST /admin/branch-dirs/:dirName/purge
  */
 const purgeBranchDir = defineEndpoint({
     namespace: 'admin',
@@ -558,7 +520,6 @@ const purgeBranchDir = defineEndpoint({
 });
 /**
  * Repair a corrupt branch.json by archiving it and recreating defaults
- * POST /admin/branch-dirs/:dirName/repair-metadata
  */
 const repairBranchDir = defineEndpoint({
     namespace: 'admin',
@@ -586,9 +547,8 @@ const repairBranchDir = defineEndpoint({
 /**
  * Repair duplicate content IDs in a healthy branch's content tree by
  * archiving the quarantined (losing) file(s) with a dot-prefixed name --
- * see content-id-index.ts's "Duplicate-ID quarantine" section and
+ * see the `ContentIdIndex` class doc and
  * repairContentDuplicatesHandler's doc comment.
- * POST /admin/branch-dirs/:dirName/repair-content-duplicates
  */
 const repairContentDuplicates = defineEndpoint({
     namespace: 'admin',

package/dist/api/admin.d.ts

@@ -7,11 +7,11 @@
  */
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
-import type { Task, QueueStats, CorruptTaskFile } from '../worker/task-queue.js';
+import type { Task, QueueStats, CorruptTaskFile } from '../task-queue/cms-task-queue.js';
 import type { WorkerStatusReport } from '../types.js';
 import type { OperatingMode } from '../operating-mode/index.js';
 export type { BranchHealthResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse, } from './admin-branch-health.js';
-export type WorkerLivenessState = 'alive' | 'stale' | 'absent';
+type WorkerLivenessState = 'alive' | 'stale' | 'absent';
 export interface WorkerLiveness {
     /**
      * 'absent' — the lock dir is removed on clean release, so this also covers
@@ -40,12 +40,12 @@ export interface AdminTasksData {
 }
 /** Response type for GET /admin/tasks/:status */
 export type AdminTasksResponse = ApiResponse<AdminTasksData>;
-export interface AdminRetryTaskData {
+interface AdminRetryTaskData {
     newTaskId: string;
 }
 /** Response type for POST /admin/tasks/:taskId/retry */
 export type AdminRetryTaskResponse = ApiResponse<AdminRetryTaskData>;
-export interface AdminDeleteTaskData {
+interface AdminDeleteTaskData {
     deleted: true;
 }
 /** Response type for DELETE /admin/tasks/:status/:fileName */
@@ -61,14 +61,6 @@ declare const listAdminTasksParamsSchema: z.ZodObject<{
     limit?: number | undefined;
 }>;
 export type ListAdminTasksParams = z.infer<typeof listAdminTasksParamsSchema>;
-declare const retryTaskParamsSchema: z.ZodObject<{
-    taskId: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    taskId: string;
-}, {
-    taskId: string;
-}>;
-export type RetryTaskParams = z.infer<typeof retryTaskParamsSchema>;
 declare const deleteTaskParamsSchema: z.ZodObject<{
     status: z.ZodEnum<["pending", "failed", "corrupt"]>;
     fileName: z.ZodEffects<z.ZodString, string, string>;

package/dist/api/admin.js

@@ -8,23 +8,20 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { z } from 'zod';
-import { getQueueStats, listTasks, listCorruptTaskFiles, requeueFailedTask, } from '../worker/task-queue.js';
-import { getTaskQueueDir } from '../worker/task-queue-config.js';
-import { WORKER_STATUS_FILE } from '../worker/worker-status.js';
+import { getQueueStats, listTasks, listCorruptTaskFiles, requeueFailedTask, } from '../task-queue/cms-task-queue.js';
+import { getTaskQueueDir } from '../task-queue/task-queue-config.js';
+import { WORKER_STATUS_FILE } from '../task-queue/worker-status.js';
 import { defineEndpoint } from './route-builder.js';
 import { getErrorMessage, isNotFoundError } from '../utils/error.js';
 import { ADMIN_BRANCH_HEALTH_ROUTES } from './admin-branch-health.js';
-// ============================================================================
-// Worker lock liveness
-// ============================================================================
 /**
- * 60_000 = DEFAULT_LOCK_STALE_MS in worker/cms-worker.ts, hardcoded here
- * rather than imported/threaded through config: an adopter overriding
- * `lockStaleMs` on their worker will skew this classification (documented
- * limitation — the observability endpoint doesn't know the worker's actual
- * config). +90_000 absorbs the EFS/NFS attribute-cache staleness window: a
- * freshly-refreshed heartbeat can still appear up to ~60s old to a reader on
- * a different host, since NFS clients cache file attributes.
+ * 60_000 = DEFAULT_LOCK_STALE_MS in worker/cms-worker.ts, hardcoded rather
+ * than threaded through config: an adopter who overrides `lockStaleMs` skews
+ * this classification (the endpoint doesn't know the worker's actual
+ * config). +90_000 absorbs the EFS/NFS attribute-cache staleness window (see
+ * docs/concurrency.md's "Residual staleness windows" (A)), large enough that
+ * a freshly-refreshed heartbeat won't misreport as stale to a reader on a
+ * different host.
  */
 const LIVENESS_THRESHOLD_MS = 60_000 + 90_000;
 const DEFAULT_ADMIN_TASKS_LIMIT = 50;
@@ -103,9 +100,6 @@ async function getOldestPendingAgeMs(taskDir) {
     }
     return oldestMtimeMs === undefined ? undefined : Math.max(0, Date.now() - oldestMtimeMs);
 }
-// ============================================================================
-// Zod Schemas for Validation
-// ============================================================================
 const adminTaskStatusSchema = z.enum(['pending', 'processing', 'completed', 'failed', 'corrupt']);
 const listAdminTasksParamsSchema = z.object({
     status: adminTaskStatusSchema,
@@ -129,9 +123,6 @@ const deleteTaskParamsSchema = z.object({
         .regex(/^[A-Za-z0-9._-]{1,120}\.json$/)
         .refine((v) => !v.includes('..'), { message: 'fileName must not contain ..' }),
 });
-// ============================================================================
-// Handlers
-// ============================================================================
 const getAdminStatusHandler = async (_gc, ctx, _req) => {
     const taskDir = getTaskQueueDir(ctx.services.config);
     try {
@@ -248,12 +239,8 @@ const deleteTaskHandler = async (_gc, ctx, _req, params) => {
         return { ok: false, status: 500, error: getErrorMessage(err) };
     }
 };
-// ============================================================================
-// Route Definitions with defineEndpoint
-// ============================================================================
 /**
  * Task queue stats + worker liveness snapshot
- * GET /admin/status
  */
 const getAdminStatus = defineEndpoint({
     namespace: 'admin',
@@ -274,7 +261,6 @@ const getAdminStatus = defineEndpoint({
 });
 /**
  * List task files for a given status (or quarantined corrupt/ files)
- * GET /admin/tasks/:status
  */
 const listAdminTasks = defineEndpoint({
     namespace: 'admin',
@@ -290,7 +276,6 @@ const listAdminTasks = defineEndpoint({
 });
 /**
  * Requeue a failed task as a fresh pending task
- * POST /admin/tasks/:taskId/retry
  */
 const retryTask = defineEndpoint({
     namespace: 'admin',
@@ -306,7 +291,6 @@ const retryTask = defineEndpoint({
 });
 /**
  * Delete a task file from pending/, failed/, or corrupt/
- * DELETE /admin/tasks/:status/:fileName
  */
 const deleteTask = defineEndpoint({
     namespace: 'admin',