canopycms 0.0.67-int.90 → 0.0.67

package/dist/static/index.d.ts

@@ -164,13 +164,13 @@ export interface EntryWithUnknownKeys {
  *
  * The inverse of `findInvalidEntries`, and non-fatal by design: an unknown key is stale data,
  * not broken data. A build must not go red for it — the page still renders, it is just quietly
- * missing whatever the renamed field used to supply. `warnUnknownEntryKeys` is the reporting
+ * missing whatever value the renamed field would supply. `warnUnknownEntryKeys` is the reporting
  * half. Both sit at module scope alongside `findInvalidEntries`/`assertBuildEntriesValid` and
  * are deliberately NOT on `canopycms/server`, matching those two — the build wires them itself.
  *
  * Skips items with no resolved schema, and items whose schema is empty — "no schema" is not
  * "every key is unknown". Same `normalizeDatesDeep` pass as the validity scan, so a hand-authored
- * `date: 2024-01-15` is a plain value here too.
+ * `date: YYYY-MM-DD` is a plain value here too.
  */
 export declare function findEntriesWithUnknownKeys(items: readonly BuildScanItem[]): EntryWithUnknownKeys[];
 /**
@@ -203,28 +203,18 @@ type UrlScanItem = Pick<ListEntriesItem, 'entryPath' | 'urlPath'>;
 /**
  * Find every `urlPath` claimed by two or more entries.
  *
- * `listEntries` assigns each entry exactly one `urlPath` and documents it as round-trip safe with
- * `readByUrlPath`. That guarantee is per-entry, not per-URL: nothing stops two DIFFERENT entries
- * computing the same one, and when they do exactly one of them is reachable while the other
- * silently has no route at all. The known ways to get there:
+ * `listEntries` gives each entry one `urlPath`, documented round-trip safe with `readByUrlPath`
+ * — but that guarantee is per-entry, not per-URL: two different entries can compute the same
+ * one, leaving exactly one reachable and the other silently unrouted. Known causes: an entry
+ * beside a sibling collection that also has an `index` entry (collapses onto the same path —
+ * the write boundary now refuses authoring this too, but merge/PR/retrofit content bypasses it;
+ * a sibling with NO index entry is a different, uncontested shape); slugs differing only by case
+ * (`urlPath` is lowercased); or two entries sharing a slug in one collection (also
+ * write-boundary-refused via `ContentStore.buildPaths`, same bypass routes).
  *
- * - An entry whose slug matches a sibling collection that also has an `index` entry — the index
- *   collapses onto the collection's path, which is the entry's path too. The write boundary now
- *   refuses to author this too (url-collision.ts), so reaching it means the content arrived some
- *   other way — the same merge/PR/retrofit routes as the same-slug case below. (An entry beside a
- *   sibling collection with NO index entry is a different, legitimate shape: a landing page plus
- *   a folder of children, nothing contested.)
- * - Two entries whose slugs differ only by case, since `urlPath` is lowercased.
- * - Two entries with the same slug in one collection. The write boundary already refuses this
- *   (`ContentStore.buildPaths` resolves by slug across entry types, and the create-intent guard
- *   turns a hit into a conflict), but content also arrives by merge, by PR, and by adopters
- *   retrofitting an existing repo — none of which pass through that boundary.
- *
- * Exported so adopters can assert on it directly instead of hand-rolling a content-integrity
- * test; `assertNoDuplicateUrlPaths` is what the build itself uses.
- *
- * Pure. Results are sorted by `urlPath`, with each `entryPaths` sorted too, so messages are
- * stable across runs (`listEntries` resolves collections in parallel, so its own order is not).
+ * Exported for adopters to assert on directly instead of hand-rolling a content-integrity test;
+ * `assertNoDuplicateUrlPaths` is what the build uses. Pure — results and each `entryPaths` are
+ * sorted, since `listEntries` resolves collections in parallel and its own order is not stable.
  */
 export declare function findDuplicateUrlPaths(items: readonly UrlScanItem[]): DuplicateUrlPath[];
 /**
@@ -240,7 +230,7 @@ export declare function findDuplicateUrlPaths(items: readonly UrlScanItem[]): Du
  * collision at RESOLUTION time regardless of routing. `readByUrlPath` picks one of the two
  * whatever any `generateStaticParams` filter says, so the un-routed entry is not innocent; it is
  * shadowing (or being shadowed by) the routed one at the same URL. `rootPath` narrows the scan
- * because it narrows what was loaded at all; `filter` deliberately does not.
+ * because it narrows what was loaded; `filter` deliberately does not.
  *
  * Related but not redundant: `canopycms-next`'s `dedupeSitemapItems` warns on the same collision
  * at the sitemap. It stays, because it also covers entry-vs-`extraUrls` collisions (adopter-supplied
@@ -258,36 +248,20 @@ export interface UnroutableSlugEntry {
 /** What the slug-routability scan needs off a listing item. */
 type SlugScanItem = Pick<ListEntriesItem, 'entryPath' | 'urlPath' | 'slug'>;
 /**
- * Find every listed entry whose `slug` cannot pass `parseSlug` — the validation `readByUrlPath`
- * runs on every URL-resolution candidate it tries (`context.ts`).
- *
- * The filename grammar `parseTypedFilename` parses (`{type}.{slug}.{id}.{ext}`) deliberately
- * allows a slug to contain dots, anchoring the split on the type and ID instead (see that
- * function's doc comment) — and it does not run the parsed slug through `parseSlug` before
- * handing it back, by design: recovering `{type, slug, id}` structurally, without validating
- * every part, is its whole contract. `listCollectionEntries` inherits that: it lists the file and
- * computes a `urlPath` for it, same as any other entry.
- *
- * But `parseSlug` requires `^[a-z0-9][a-z0-9-]*$` — no dots — so a listed entry whose slug
- * contains one is unreachable through the one path everything else assumes works:
- * `readByUrlPath` tries the URL's last segment as a candidate slug and skips any candidate that
- * fails `parseSlug` (treating it as a miss, not an error) before it ever calls `read()`. The
- * entry still builds, still gets a `generateStaticParams` entry, still gets a sitemap `<loc>` —
- * and 404s the moment anything actually visits it. That breaks the `Round-trip safe` contract
- * `content-listing.ts` documents on `urlPath` (`readByUrlPath(item.urlPath)` resolves to the same
- * entry) and is exactly the silent-page-loss failure mode this guard's siblings
- * (`assertBuildEntriesValid`, `assertNoDuplicateUrlPaths`) exist to make loud instead.
+ * Find every listed entry whose `slug` cannot pass `parseSlug` — the check `readByUrlPath` runs
+ * on every URL-resolution candidate it tries (`context.ts`).
  *
- * The write boundary refuses to MINT such a slug: `api/content.ts` and `ContentStore.write()`
- * both run `parseSlug` on a create, and `renameEntry()` runs it on the new slug (the [SLUG]
- * guards). That enforcement is deliberately create-only — an entry that already carries a
- * non-conforming slug stays saveable and renameable, because renaming it is the only way to fix
- * this build failure, and refusing reads or edits would turn a red build into unreachable data.
+ * The filename grammar (`parseTypedFilename`) deliberately allows a slug to contain dots and
+ * hands it back unvalidated, so a listed entry can carry one. But `parseSlug` requires
+ * `^[a-z0-9][a-z0-9-]*$` — no dots — so `readByUrlPath` skips that candidate as a miss before
+ * ever calling `read()`. The entry still builds, gets a `generateStaticParams` entry and a
+ * sitemap `<loc>`, and then 404s on every visit — breaking the `Round-trip safe` contract
+ * `content-listing.ts` documents on `urlPath`.
  *
- * So this guard still fires, and is still needed, for every slug the write boundary never saw:
- * hand-authored files, scripted migrations, content merged in over git, a repo being retrofitted
- * onto CanopyCMS (this guard's intended audience, same as its siblings), and entries created
- * before the write-time rule existed.
+ * The write boundary (`parseSlug` in `api/content.ts` and `ContentStore.write`/`renameEntry`)
+ * refuses such a slug on create and rename only, so this guard covers every slug it never saw:
+ * hand-authored files, migrations, git-merged content, and a repo being retrofitted onto
+ * CanopyCMS.
  */
 export declare function findUnroutableSlugs(items: readonly SlugScanItem[]): UnroutableSlugEntry[];
 /**

package/dist/static/index.js

@@ -27,20 +27,12 @@ async function enumerateRoutableEntries(ctx, rootPath, phaseLabel, resolveRefere
     // an abandoned schema-invalid scaffold shipping into a static build silently drops that page's
     // route (or worse, renders broken), which is worse than a red build.
     //
-    // The unknown-key warning runs BEFORE all three throwing guards, so a build about to go red
-    // still prints everything it found rather than dying on the first problem.
-    //
-    // All four run on the RAW listing, before the caller's `filter` — a filtered-out entry still
-    // occupies its URL as far as every other route is concerned. `rootPath` scoping does narrow
-    // them, since that happens inside `listEntries`; that is the intended escape hatch, `filter`
-    // is not.
-    //
-    // Slug routability is asserted first, ahead of schema validity and duplicate URLs: an entry
-    // whose slug cannot round-trip through `readByUrlPath` has no URL at all as far as any OTHER
-    // guard is concerned, so it is the most fundamental of the three problems a listed entry can
-    // have. Schema validity is asserted before duplicate URLs for the same reason one level down:
-    // a schema-invalid entry is the more fundamental problem, and an adopter fixing it may remove
-    // the duplicate on the way.
+    // These four guards run in a fixed order on the RAW listing, before the caller's `filter` —
+    // `rootPath` narrows them, `filter` deliberately does not. The unknown-key warning runs first,
+    // so a build about to go red still reports everything found. Slug routability runs next: an
+    // unroutable entry has no URL at all as far as the other three are concerned, the most
+    // fundamental problem a listed entry can have. Schema validity runs before duplicate URLs for
+    // the same "most fundamental first" reason, one level down.
     if (isBuildMode()) {
         warnUnknownEntryKeys(entries, phaseLabel);
         assertRoutableSlugs(entries, phaseLabel);
@@ -109,7 +101,7 @@ export async function collectStaticPaths(ctx, options = {}) {
  * Deep-walk a plain data value (objects and arrays only — the shapes YAML/JSON parsing can
  * produce), converting every `Date` instance to its ISO string.
  *
- * gray-matter parses unquoted YAML dates in hand-authored frontmatter (`date: 2024-01-15`) into
+ * gray-matter parses unquoted YAML dates in hand-authored frontmatter (`date: YYYY-MM-DD`) into
  * JS `Date` objects rather than strings. The shared validator's datetime check requires a string
  * (see `validateScalar` in entry-validator.ts), so a legitimate hand-authored or migrated entry
  * would otherwise fail this build guard. CMS-authored entries round-trip as quoted strings, so
@@ -175,13 +167,13 @@ const UNKNOWN_KEY_REPORT_LIMIT = 20;
  *
  * The inverse of `findInvalidEntries`, and non-fatal by design: an unknown key is stale data,
  * not broken data. A build must not go red for it — the page still renders, it is just quietly
- * missing whatever the renamed field used to supply. `warnUnknownEntryKeys` is the reporting
+ * missing whatever value the renamed field would supply. `warnUnknownEntryKeys` is the reporting
  * half. Both sit at module scope alongside `findInvalidEntries`/`assertBuildEntriesValid` and
  * are deliberately NOT on `canopycms/server`, matching those two — the build wires them itself.
  *
  * Skips items with no resolved schema, and items whose schema is empty — "no schema" is not
  * "every key is unknown". Same `normalizeDatesDeep` pass as the validity scan, so a hand-authored
- * `date: 2024-01-15` is a plain value here too.
+ * `date: YYYY-MM-DD` is a plain value here too.
  */
 export function findEntriesWithUnknownKeys(items) {
     const found = [];
@@ -254,28 +246,18 @@ export function assertBuildEntriesValid(items, phaseLabel) {
 /**
  * Find every `urlPath` claimed by two or more entries.
  *
- * `listEntries` assigns each entry exactly one `urlPath` and documents it as round-trip safe with
- * `readByUrlPath`. That guarantee is per-entry, not per-URL: nothing stops two DIFFERENT entries
- * computing the same one, and when they do exactly one of them is reachable while the other
- * silently has no route at all. The known ways to get there:
- *
- * - An entry whose slug matches a sibling collection that also has an `index` entry — the index
- *   collapses onto the collection's path, which is the entry's path too. The write boundary now
- *   refuses to author this too (url-collision.ts), so reaching it means the content arrived some
- *   other way — the same merge/PR/retrofit routes as the same-slug case below. (An entry beside a
- *   sibling collection with NO index entry is a different, legitimate shape: a landing page plus
- *   a folder of children, nothing contested.)
- * - Two entries whose slugs differ only by case, since `urlPath` is lowercased.
- * - Two entries with the same slug in one collection. The write boundary already refuses this
- *   (`ContentStore.buildPaths` resolves by slug across entry types, and the create-intent guard
- *   turns a hit into a conflict), but content also arrives by merge, by PR, and by adopters
- *   retrofitting an existing repo — none of which pass through that boundary.
+ * `listEntries` gives each entry one `urlPath`, documented round-trip safe with `readByUrlPath`
+ * — but that guarantee is per-entry, not per-URL: two different entries can compute the same
+ * one, leaving exactly one reachable and the other silently unrouted. Known causes: an entry
+ * beside a sibling collection that also has an `index` entry (collapses onto the same path —
+ * the write boundary now refuses authoring this too, but merge/PR/retrofit content bypasses it;
+ * a sibling with NO index entry is a different, uncontested shape); slugs differing only by case
+ * (`urlPath` is lowercased); or two entries sharing a slug in one collection (also
+ * write-boundary-refused via `ContentStore.buildPaths`, same bypass routes).
  *
- * Exported so adopters can assert on it directly instead of hand-rolling a content-integrity
- * test; `assertNoDuplicateUrlPaths` is what the build itself uses.
- *
- * Pure. Results are sorted by `urlPath`, with each `entryPaths` sorted too, so messages are
- * stable across runs (`listEntries` resolves collections in parallel, so its own order is not).
+ * Exported for adopters to assert on directly instead of hand-rolling a content-integrity test;
+ * `assertNoDuplicateUrlPaths` is what the build uses. Pure — results and each `entryPaths` are
+ * sorted, since `listEntries` resolves collections in parallel and its own order is not stable.
  */
 export function findDuplicateUrlPaths(items) {
     const byUrl = new Map();
@@ -307,7 +289,7 @@ export function findDuplicateUrlPaths(items) {
  * collision at RESOLUTION time regardless of routing. `readByUrlPath` picks one of the two
  * whatever any `generateStaticParams` filter says, so the un-routed entry is not innocent; it is
  * shadowing (or being shadowed by) the routed one at the same URL. `rootPath` narrows the scan
- * because it narrows what was loaded at all; `filter` deliberately does not.
+ * because it narrows what was loaded; `filter` deliberately does not.
  *
  * Related but not redundant: `canopycms-next`'s `dedupeSitemapItems` warns on the same collision
  * at the sitemap. It stays, because it also covers entry-vs-`extraUrls` collisions (adopter-supplied
@@ -334,36 +316,20 @@ export function assertNoDuplicateUrlPaths(items, phaseLabel) {
         'lowercased). Rename or remove one of the colliding entries, then rebuild.');
 }
 /**
- * Find every listed entry whose `slug` cannot pass `parseSlug` — the validation `readByUrlPath`
- * runs on every URL-resolution candidate it tries (`context.ts`).
- *
- * The filename grammar `parseTypedFilename` parses (`{type}.{slug}.{id}.{ext}`) deliberately
- * allows a slug to contain dots, anchoring the split on the type and ID instead (see that
- * function's doc comment) — and it does not run the parsed slug through `parseSlug` before
- * handing it back, by design: recovering `{type, slug, id}` structurally, without validating
- * every part, is its whole contract. `listCollectionEntries` inherits that: it lists the file and
- * computes a `urlPath` for it, same as any other entry.
- *
- * But `parseSlug` requires `^[a-z0-9][a-z0-9-]*$` — no dots — so a listed entry whose slug
- * contains one is unreachable through the one path everything else assumes works:
- * `readByUrlPath` tries the URL's last segment as a candidate slug and skips any candidate that
- * fails `parseSlug` (treating it as a miss, not an error) before it ever calls `read()`. The
- * entry still builds, still gets a `generateStaticParams` entry, still gets a sitemap `<loc>` —
- * and 404s the moment anything actually visits it. That breaks the `Round-trip safe` contract
- * `content-listing.ts` documents on `urlPath` (`readByUrlPath(item.urlPath)` resolves to the same
- * entry) and is exactly the silent-page-loss failure mode this guard's siblings
- * (`assertBuildEntriesValid`, `assertNoDuplicateUrlPaths`) exist to make loud instead.
+ * Find every listed entry whose `slug` cannot pass `parseSlug` — the check `readByUrlPath` runs
+ * on every URL-resolution candidate it tries (`context.ts`).
  *
- * The write boundary refuses to MINT such a slug: `api/content.ts` and `ContentStore.write()`
- * both run `parseSlug` on a create, and `renameEntry()` runs it on the new slug (the [SLUG]
- * guards). That enforcement is deliberately create-only — an entry that already carries a
- * non-conforming slug stays saveable and renameable, because renaming it is the only way to fix
- * this build failure, and refusing reads or edits would turn a red build into unreachable data.
+ * The filename grammar (`parseTypedFilename`) deliberately allows a slug to contain dots and
+ * hands it back unvalidated, so a listed entry can carry one. But `parseSlug` requires
+ * `^[a-z0-9][a-z0-9-]*$` — no dots — so `readByUrlPath` skips that candidate as a miss before
+ * ever calling `read()`. The entry still builds, gets a `generateStaticParams` entry and a
+ * sitemap `<loc>`, and then 404s on every visit — breaking the `Round-trip safe` contract
+ * `content-listing.ts` documents on `urlPath`.
  *
- * So this guard still fires, and is still needed, for every slug the write boundary never saw:
- * hand-authored files, scripted migrations, content merged in over git, a repo being retrofitted
- * onto CanopyCMS (this guard's intended audience, same as its siblings), and entries created
- * before the write-time rule existed.
+ * The write boundary (`parseSlug` in `api/content.ts` and `ContentStore.write`/`renameEntry`)
+ * refuses such a slug on create and rename only, so this guard covers every slug it never saw:
+ * hand-authored files, migrations, git-merged content, and a repo being retrofitted onto
+ * CanopyCMS.
  */
 export function findUnroutableSlugs(items) {
     const found = [];

package/dist/{worker/task-queue.d.ts → task-queue/cms-task-queue.d.ts}

@@ -1,17 +1,15 @@
 /**
- * CanopyCMS task queue — re-exports from the generic task-queue module
- * with CMS-specific action types and a WorkerTask alias.
- */
-import type { Task, TaskQueueLogger } from '../task-queue/index.js';
-/**
- * Actions the EC2 worker can execute on behalf of Lambda.
+ * The CMS queue contract: the generic queue in ./task-queue plus the CMS
+ * action vocabulary, a WorkerTask alias and the debug logger. Published as
+ * `canopycms/worker/task-queue`.
  */
+import type { Task, TaskQueueLogger } from './types.js';
+/** Actions the EC2 worker can execute on behalf of Lambda. */
 export type TaskAction = 'push-and-create-pr' | 'push-and-update-pr' | 'push-and-create-or-update-pr' | 'convert-to-draft' | 'close-pr' | 'delete-remote-branch' | 'push-branch';
 /** A task with a CMS-specific action. */
 export type WorkerTask = Task & {
     action: TaskAction;
 };
 export declare const cmsTaskQueueLogger: TaskQueueLogger;
-export { enqueueTask, dequeueTask, completeTask, failTask, retryTask, requeueFailedTask, recoverOrphanedTasks, cleanupOldTasks, getTask, getTask as getTaskResult, // backward-compatible alias
-listTasks, getQueueStats, listCorruptTaskFiles, } from '../task-queue/index.js';
-export type { Task, TaskStatus, QueueStats, TaskQueueLogger, CorruptTaskFile } from '../task-queue/index.js';
+export { enqueueTask, dequeueTask, completeTask, failTask, retryTask, requeueFailedTask, recoverOrphanedTasks, cleanupOldTasks, getTask, listTasks, getQueueStats, listCorruptTaskFiles, } from './task-queue.js';
+export type { Task, TaskStatus, QueueStats, TaskQueueLogger, CorruptTaskFile } from './types.js';

package/dist/task-queue/cms-task-queue.js

@@ -0,0 +1,13 @@
+/**
+ * The CMS queue contract: the generic queue in ./task-queue plus the CMS
+ * action vocabulary, a WorkerTask alias and the debug logger. Published as
+ * `canopycms/worker/task-queue`.
+ */
+import { createDebugLogger } from '../utils/debug.js';
+const debugLogger = createDebugLogger({ prefix: 'TaskQueue' });
+export const cmsTaskQueueLogger = {
+    debug(message, data) {
+        debugLogger.debug('task', message, data);
+    },
+};
+export { enqueueTask, dequeueTask, completeTask, failTask, retryTask, requeueFailedTask, recoverOrphanedTasks, cleanupOldTasks, getTask, listTasks, getQueueStats, listCorruptTaskFiles, } from './task-queue.js';

package/dist/task-queue/task-queue-config.d.ts

@@ -0,0 +1,3 @@
+import type { CanopyConfig } from '../config/index.js';
+/** The task queue directory for async worker operations. */
+export declare function getTaskQueueDir(config: Pick<CanopyConfig, 'mode'>): string;

package/dist/{worker → task-queue}/task-queue-config.js

@@ -1,11 +1,6 @@
 import path from 'node:path';
 import { DEFAULT_PROD_WORKSPACE } from '../config/index.js';
-/**
- * Get the task queue directory for async worker operations.
- *
- * In prod mode: {CANOPYCMS_WORKSPACE_ROOT}/.tasks
- * In dev mode: {cwd}/.canopy-dev/.tasks
- */
+/** The task queue directory for async worker operations. */
 export function getTaskQueueDir(config) {
     switch (config.mode) {
         case 'prod': {

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

@@ -11,9 +11,9 @@
  * Designed for shared filesystems (EFS/NFS) where one process enqueues
  * and another dequeues. No external dependencies — only Node.js stdlib.
  *
- * IMPORTANT: Single-consumer only. The dequeue operation is not atomic across
- * processes — the worker lock (acquireLock) ensures only one consumer runs at
- * a time. Do not run multiple dequeue consumers concurrently.
+ * IMPORTANT: single-consumer only — dequeue is not atomic across processes;
+ * the worker lock (acquireLock) must serialize consumers, so never run more
+ * than one dequeue consumer concurrently.
  */
 import type { Task, TaskStatus, QueueStats, TaskQueueLogger, CorruptTaskFile } from './types.js';
 /**
@@ -50,28 +50,22 @@ export declare function failTask(taskDir: string, taskId: string, error: string,
  */
 export declare function retryTask(taskDir: string, taskId: string, error: string, logger?: TaskQueueLogger): Promise<void>;
 /**
- * Requeue a permanently-failed task for another attempt. Reads
- * failed/{taskId}.json and creates a BRAND NEW pending task with a fresh
- * `id` — the original ID is never reused. This matters because both
- * `dequeueTask` and `recoverOrphanedTasks` dedup against completed/failed by
- * ID: a pending file that reused the original ID would be silently deleted
- * (without running) the moment it was scanned, since its ID already exists
- * in failed/.
+ * Requeue a permanently-failed task: reads failed/{taskId}.json and creates a
+ * brand-new pending task with a fresh `id`, never the original — `dequeueTask`
+ * and `recoverOrphanedTasks` dedup completed/failed by ID, so reusing it would
+ * get the pending copy silently deleted, unrun, the moment it's scanned.
  *
- * The new task carries `payload.requeuedFrom` for provenance, starts at
- * `retryCount: 0`, and gets an honest fresh `createdAt` (it goes to the back
- * of the FIFO queue rather than jumping ahead on the original timestamp).
+ * The new task carries `payload.requeuedFrom`, `retryCount: 0`, and a fresh
+ * `createdAt` (it re-joins the back of the FIFO queue, not the original slot).
  *
- * Write-then-unlink ordering: the new pending file is written FIRST, and the
- * failed original is unlinked only after that succeeds (best-effort — unlink
- * failures are swallowed). A crash between the two steps leaves the failed
- * original in place alongside the new pending task, which is harmless
- * (duplicate history, not a lost task); the reverse order could lose the
- * task entirely if the process died after the unlink but before the write.
+ * Write-then-unlink: the new pending file is written FIRST; the failed
+ * original is unlinked only after (best-effort). A crash between the two
+ * leaves both — harmless duplication — but the reverse order could lose the
+ * task if the process dies after the unlink and before the write.
  *
- * Returns `{ error: 'not-found' }` if there is no such file in failed/, or
- * `{ error: 'unparseable' }` if the file exists but isn't valid task JSON
- * (callers should tell the admin to delete it instead of retrying it).
+ * Returns `{ error: 'not-found' }` if failed/{taskId}.json doesn't exist, or
+ * `{ error: 'unparseable' }` if it isn't valid task JSON (tell the admin to
+ * delete it rather than retry).
  */
 export declare function requeueFailedTask(taskDir: string, taskId: string, logger?: TaskQueueLogger): Promise<{
     newTaskId: string;

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

@@ -11,24 +11,20 @@
  * Designed for shared filesystems (EFS/NFS) where one process enqueues
  * and another dequeues. No external dependencies — only Node.js stdlib.
  *
- * IMPORTANT: Single-consumer only. The dequeue operation is not atomic across
- * processes — the worker lock (acquireLock) ensures only one consumer runs at
- * a time. Do not run multiple dequeue consumers concurrently.
+ * IMPORTANT: single-consumer only — dequeue is not atomic across processes;
+ * the worker lock (acquireLock) must serialize consumers, so never run more
+ * than one dequeue consumer concurrently.
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import crypto from 'node:crypto';
 const DEFAULT_MAX_RETRIES = 3;
-// Silent no-op logger
 const nullLogger = { debug: () => { } };
 import { atomicWriteFile } from '../utils/atomic-write.js';
 // Local helper — only stdlib dependency, keeps task-queue easy to extract.
 function isNotFoundError(err) {
     return err instanceof Error && 'code' in err && err.code === 'ENOENT';
 }
-// ============================================================================
-// Core queue operations
-// ============================================================================
 /**
  * Enqueue a task. Writes a JSON file to pending/{id}.json.
  * Returns the generated task ID.
@@ -219,28 +215,22 @@ export async function retryTask(taskDir, taskId, error, logger = nullLogger) {
     logger.debug('Retrying task', { id: taskId, retryCount, backoffMs });
 }
 /**
- * Requeue a permanently-failed task for another attempt. Reads
- * failed/{taskId}.json and creates a BRAND NEW pending task with a fresh
- * `id` — the original ID is never reused. This matters because both
- * `dequeueTask` and `recoverOrphanedTasks` dedup against completed/failed by
- * ID: a pending file that reused the original ID would be silently deleted
- * (without running) the moment it was scanned, since its ID already exists
- * in failed/.
+ * Requeue a permanently-failed task: reads failed/{taskId}.json and creates a
+ * brand-new pending task with a fresh `id`, never the original — `dequeueTask`
+ * and `recoverOrphanedTasks` dedup completed/failed by ID, so reusing it would
+ * get the pending copy silently deleted, unrun, the moment it's scanned.
  *
- * The new task carries `payload.requeuedFrom` for provenance, starts at
- * `retryCount: 0`, and gets an honest fresh `createdAt` (it goes to the back
- * of the FIFO queue rather than jumping ahead on the original timestamp).
+ * The new task carries `payload.requeuedFrom`, `retryCount: 0`, and a fresh
+ * `createdAt` (it re-joins the back of the FIFO queue, not the original slot).
  *
- * Write-then-unlink ordering: the new pending file is written FIRST, and the
- * failed original is unlinked only after that succeeds (best-effort — unlink
- * failures are swallowed). A crash between the two steps leaves the failed
- * original in place alongside the new pending task, which is harmless
- * (duplicate history, not a lost task); the reverse order could lose the
- * task entirely if the process died after the unlink but before the write.
+ * Write-then-unlink: the new pending file is written FIRST; the failed
+ * original is unlinked only after (best-effort). A crash between the two
+ * leaves both — harmless duplication — but the reverse order could lose the
+ * task if the process dies after the unlink and before the write.
  *
- * Returns `{ error: 'not-found' }` if there is no such file in failed/, or
- * `{ error: 'unparseable' }` if the file exists but isn't valid task JSON
- * (callers should tell the admin to delete it instead of retrying it).
+ * Returns `{ error: 'not-found' }` if failed/{taskId}.json doesn't exist, or
+ * `{ error: 'unparseable' }` if it isn't valid task JSON (tell the admin to
+ * delete it rather than retry).
  */
 export async function requeueFailedTask(taskDir, taskId, logger = nullLogger) {
     const failedPath = path.join(taskDir, 'failed', `${taskId}.json`);
@@ -272,9 +262,6 @@ export async function requeueFailedTask(taskDir, taskId, logger = nullLogger) {
     logger.debug('Requeued failed task', { originalId: taskId, newTaskId });
     return { newTaskId };
 }
-// ============================================================================
-// Recovery & maintenance
-// ============================================================================
 /**
  * Recover orphaned tasks stuck in processing/.
  * Moves tasks whose file mtime is older than maxAgeMs back to pending/.
@@ -339,15 +326,10 @@ export async function recoverOrphanedTasks(taskDir, maxAgeMs = 5 * 60_000, logge
 export async function cleanupOldTasks(taskDir, maxAgeMs = 30 * 24 * 60 * 60_000, logger = nullLogger) {
     const now = Date.now();
     let cleaned = 0;
-    // `corrupt` included: unparseable task files are quarantined there by
-    // dequeue and orphan recovery and surfaced in admin listing, but the
-    // retention sweep never covered the directory, so it grew forever with
-    // deletion available only as a manual per-file admin action. Any recurring
-    // producer of malformed task JSON -- a partial write surviving a crash, a
-    // bad deploy writing schema-drifted tasks for a week -- accumulated files no
-    // automated path removed. Same stamp-based retention as the other two: a
-    // quarantined file older than the window has long since been triaged or
-    // forgotten.
+    // `corrupt` files (quarantined by dequeue and orphan recovery, shown in
+    // the admin listing) get the same stamp-based retention as completed and
+    // failed, because a quarantined file older than the window has been
+    // triaged or forgotten.
     for (const subdir of ['completed', 'failed', 'corrupt']) {
         const dir = path.join(taskDir, subdir);
         let files;
@@ -376,9 +358,6 @@ export async function cleanupOldTasks(taskDir, maxAgeMs = 30 * 24 * 60 * 60_000,
     }
     return cleaned;
 }
-// ============================================================================
-// Query operations (for status UIs, monitoring)
-// ============================================================================
 /**
  * Get a specific task by ID. Searches all status directories.
  */
@@ -487,9 +466,6 @@ export async function listCorruptTaskFiles(taskDir, limit = 50, logger = nullLog
     entries.sort((a, b) => new Date(b.mtime).getTime() - new Date(a.mtime).getTime());
     return entries.slice(0, limit);
 }
-// ============================================================================
-// Internal helpers
-// ============================================================================
 /** Read up to `maxBytes` from the start of a file, as utf-8 text. */
 async function readSnippet(filePath, maxBytes) {
     const handle = await fs.open(filePath, 'r');

package/dist/task-queue/types.d.ts

@@ -31,7 +31,6 @@ export interface QueueStats {
 }
 /**
  * Optional logger interface.
- * Pass your own logger to `createTaskQueue()`, or omit for silent operation.
  */
 export interface TaskQueueLogger {
     debug(message: string, data?: Record<string, unknown>): void;

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

@@ -0,0 +1,35 @@
+/**
+ * worker-status.json: the CmsWorker daemon's self-reported liveness/health
+ * snapshot, written under the task queue directory
+ * (`{taskDir}/worker-status.json`) and read tolerantly by the admin API
+ * (api/admin.ts's `readWorkerStatus`). Wire shape: `WorkerStatusReport` in
+ * ../types.
+ *
+ * Single-writer by intent (only the lock-holding CmsWorker -- see
+ * cms-worker.ts's `acquireLock`, DEP-C2), but correctness does not rest on
+ * that: every write is a FULL regeneration landed by an atomic temp-file rename
+ * (utils/atomic-write.ts), never a read-modify-write, so whichever write lands
+ * last is one writer's complete, self-consistent snapshot. That covers the one
+ * window where two holders overlap -- after a lock compromise the old holder's
+ * `stop()` drains for up to `taskTimeoutMs` while a new holder is already
+ * running against the same workspace.
+ *
+ * Readers are stale-tolerant by design: this is a liveness signal, not
+ * authoritative state, and NFS/EFS attribute-cache staleness (see
+ * docs/concurrency.md) means a reader can see a snapshot a cache window old
+ * however carefully it was written.
+ */
+import type { WorkerStatusReport } from '../types.js';
+export declare const WORKER_STATUS_FILE = "worker-status.json";
+/**
+ * Write the worker's status report to `{taskDir}/worker-status.json`.
+ *
+ * Full-file regeneration, never a partial update: pass the complete report,
+ * not a delta. Stamps `updatedAt`; every other field is the caller's.
+ *
+ * Throws rather than swallowing. Callers that cannot let a status-write failure
+ * break their own operation wrap this at the call site (`syncGit`,
+ * `processTaskQueue`, `start()`); any that don't fall back on scheduleLoop's
+ * per-cycle catch, which logs and continues.
+ */
+export declare function writeWorkerStatus(taskDir: string, report: WorkerStatusReport): Promise<void>;

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

@@ -0,0 +1,40 @@
+/**
+ * worker-status.json: the CmsWorker daemon's self-reported liveness/health
+ * snapshot, written under the task queue directory
+ * (`{taskDir}/worker-status.json`) and read tolerantly by the admin API
+ * (api/admin.ts's `readWorkerStatus`). Wire shape: `WorkerStatusReport` in
+ * ../types.
+ *
+ * Single-writer by intent (only the lock-holding CmsWorker -- see
+ * cms-worker.ts's `acquireLock`, DEP-C2), but correctness does not rest on
+ * that: every write is a FULL regeneration landed by an atomic temp-file rename
+ * (utils/atomic-write.ts), never a read-modify-write, so whichever write lands
+ * last is one writer's complete, self-consistent snapshot. That covers the one
+ * window where two holders overlap -- after a lock compromise the old holder's
+ * `stop()` drains for up to `taskTimeoutMs` while a new holder is already
+ * running against the same workspace.
+ *
+ * Readers are stale-tolerant by design: this is a liveness signal, not
+ * authoritative state, and NFS/EFS attribute-cache staleness (see
+ * docs/concurrency.md) means a reader can see a snapshot a cache window old
+ * however carefully it was written.
+ */
+import path from 'node:path';
+import { atomicWriteFile } from '../utils/atomic-write.js';
+export const WORKER_STATUS_FILE = 'worker-status.json';
+/**
+ * Write the worker's status report to `{taskDir}/worker-status.json`.
+ *
+ * Full-file regeneration, never a partial update: pass the complete report,
+ * not a delta. Stamps `updatedAt`; every other field is the caller's.
+ *
+ * Throws rather than swallowing. Callers that cannot let a status-write failure
+ * break their own operation wrap this at the call site (`syncGit`,
+ * `processTaskQueue`, `start()`); any that don't fall back on scheduleLoop's
+ * per-cycle catch, which logs and continues.
+ */
+export async function writeWorkerStatus(taskDir, report) {
+    const filePath = path.join(taskDir, WORKER_STATUS_FILE);
+    const stamped = { ...report, updatedAt: new Date().toISOString() };
+    await atomicWriteFile(filePath, JSON.stringify(stamped, null, 2));
+}