canopycms 0.0.67-int.90 → 0.0.67

package/dist/utils/content-write-lock.js

@@ -1,60 +1,32 @@
 /**
- * [SYNC-C1] Cross-host mutual exclusion between the worker's rebase loop and
- * content writes against the same branch working tree.
- *
- * Production runs a Lambda (API) and an EC2 worker over one EFS filesystem.
- * `ContentStore`'s write/delete/rename critical sections were guarded only by
- * the in-process mutex (`utils/async-mutex`), which does not cross that
- * boundary, while the worker's rebase loop (`rebaseOneBranch` in
- * worker/rebase.ts) rewrites the very same
- * working tree. A write landing after `git rebase` started is destroyed two
- * ways -- `git checkout --theirs <file>` overwrites it with the branch's
- * committed version (and the rebase then SUCCEEDS, logging nothing), and
- * `git rebase --abort` hard-resets the tree. Either way the editor already got
- * its 200. This lock is what serializes the two.
- *
- * **Asymmetric by design.** The worker retries every branch on its next sync
- * cycle (~5 minutes) while the editor is a person waiting on a save, so the
- * worker yields and the writer waits:
- *
- * - Worker: {@link tryAcquireContentWriteLock} -- zero retries. On contention
- *   it skips that branch this cycle (an extension of the existing
- *   skip-dirty-branches behavior) and picks it up next cycle.
- * - Writers: {@link withContentWriteLock} -- a short bounded wait, then a
- *   retriable failure the API surfaces as a 409.
- *
- * **Reads never take this lock.** An extra EFS round-trip on every read is not
- * an acceptable price, and a read racing a rebase gets a consistent-enough
- * older or newer file, never a destroyed one.
- *
- * ## Why the lock marker lives under `{branchRoot}/.canopy-meta`
- *
- * proper-lockfile keys its module-level `locks{}` bookkeeping (refresh timer,
- * release function) by the **target path** passed to `lock()`, NOT by
- * `lockfilePath`. `provisioning-lock.ts` now anchors every lock on its own
- * marker path, so the registry key equals the on-disk lock identity and two
- * live locks can no longer share a key -- aliasing is structurally impossible
- * rather than merely avoided by convention. Keeping the content lock under
- * `{branchRoot}/.canopy-meta` still buys:
- *
- * - a per-branch marker, so one branch's content lock is independent of every
- *   other branch's and of that branch's provisioning lock; and
- * - no deadlock potential: the two locks are never both required, and the only
- *   possible acquisition order (provision, then write) is consistent.
- *
- * `.canopy-meta/` is git-excluded in every branch clone (`ensureGitExclude`),
- * so the lock directory can never dirty the working tree or be swept into
- * `git add .` at publish time.
- *
- * ## Honest caveat (do not oversell this)
- *
- * `proper-lockfile` decides a holder is dead by reading the lock directory's
- * mtime with `fs.stat`, which on EFS is served through the NFS attribute
- * cache. A live holder refreshes every `stale/2`, but a waiter can read a
- * cached mtime and conclude the lock is stale when it is not, taking it over.
- * The failure mode of a bad takeover is exactly today's behavior (two
- * unsynchronized writers), so this is a strict improvement -- not a proof of
- * mutual exclusion. See docs/concurrency.md.
+ * [SYNC-C1] Cross-host mutual exclusion between the worker's rebase loop and content writes
+ * against the same branch working tree. docs/concurrency.md has the layering.
+ *
+ * Production runs a Lambda (API) and an EC2 worker over one EFS filesystem, so `ContentStore`'s
+ * in-process mutex (`utils/async-mutex`) does not cover the worker's rebase (`rebaseOneBranch` in
+ * worker/rebase.ts) rewriting the same tree. A write landing after `git rebase` started is
+ * destroyed either way -- `git checkout --theirs` overwrites it and the rebase then SUCCEEDS
+ * silently, or `git rebase --abort` hard-resets the tree -- and the editor already got its 200.
+ *
+ * **Asymmetric by design.** The worker retries every branch on its next sync cycle (~5 minutes)
+ * while the editor is a person waiting on a save, so the worker yields and the writer waits:
+ *
+ * - Worker: {@link tryAcquireContentWriteLock} -- zero retries, skips the branch this cycle.
+ * - Writers: {@link withContentWriteLock} -- a short bounded wait, then
+ *   {@link ContentWriteLockBusyError}, which `ContentStore` maps to `BranchSyncingError` and the
+ *   API to a 409.
+ *
+ * **Reads never take this lock.** An extra EFS round-trip on every read is not an acceptable
+ * price, and a read racing a rebase gets an older or newer file, never a destroyed one.
+ *
+ * The marker lives under `{branchRoot}/.canopy-meta` and the lock anchors on that marker path like
+ * every other lock (see provisioning-lock.ts), so it can never alias the branch's provisioning
+ * lock; the two are never both required and the only possible order (provision, then write) is
+ * consistent, so they cannot deadlock. `.canopy-meta/` is git-excluded in every branch clone
+ * (`ensureGitExclude`), so the lock directory cannot dirty the tree or be swept into `git add .`.
+ *
+ * Mutual exclusion is not proven: on EFS a stale cached mtime lets a waiter take over a live lock,
+ * leaving two unsynchronized writers -- the unlocked behaviour, so still a strict improvement.
  */
 import path from 'node:path';
 import { getErrorMessage, isNodeError } from './error.js';
@@ -63,42 +35,33 @@ import { tryAcquireProvisioningLock } from './provisioning-lock.js';
 /** Directory the lock marker lives in, relative to the branch root. */
 const META_DIR = '.canopy-meta';
 /** On-disk name of the lock marker (a directory, created by mkdir). */
-export const CONTENT_WRITE_LOCK_NAME = 'content-write.lock';
+const CONTENT_WRITE_LOCK_NAME = 'content-write.lock';
 /**
  * Default bounded wait for a content write.
  *
- * Deliberately short. A rebase holds this lock for a fetch plus a replay plus
- * N conflict rounds of git subprocesses on EFS -- far longer than any wait an
- * interactive save can absorb, and longer than the API's own latency budget.
- * So the wait is not sized to outlast a rebase (nothing reasonable could); it
- * is sized to absorb lock handoff and the short holds of other writers, and to
- * turn everything longer into a fast, explicit "retry" the editor can act on
- * rather than a request that hangs toward the Lambda timeout. The worker
- * revisits the branch next cycle, so the blocked state is transient.
- *
- * This is ALSO the writer-vs-writer budget, not only the rebase one. The lock
- * is per-branch-root, so every write to one branch now serializes behind it
- * where in-process serialization used to be per-entry -- bounded on Lambda
- * (one invocation per container), but real under `next dev` and build-time
- * provisioning across worker processes. The case to watch is a write whose
- * in-lock path triggers a full `idIndex()` rescan of a large tree over EFS:
- * that can plausibly exceed this budget and start 409ing unrelated saves.
- * Making it configurable for prod tuning is tracked in
+ * Deliberately short. A rebase holds this lock for a fetch, a replay and N conflict rounds of git
+ * subprocesses on EFS -- longer than an interactive save can absorb -- so the wait is not sized to
+ * outlast one. It absorbs lock handoff and other writers' short holds, and turns everything longer
+ * into a fast, explicit "retry" rather than a request hanging toward the Lambda timeout; the
+ * worker revisits the branch next cycle, so the blocked state is transient.
+ *
+ * It is ALSO the writer-vs-writer budget: the lock is per-branch-root, so every write to one
+ * branch serializes behind it -- bounded on Lambda (one invocation per container), but real under
+ * `next dev` and build-time provisioning across worker processes. The case to watch is a write
+ * whose in-lock path triggers a full `idIndex()` rescan of a large tree over EFS, which can exceed
+ * this budget and start 409ing unrelated saves. Making it configurable is tracked in
  * .claude/future-tasks/content-write-lock-tuning-and-granularity.md.
  */
 export const DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS = 2000;
 /**
- * Thrown when the bounded wait expires with the branch's content lock still
- * held. Retriable -- callers translate this into a 409 with a message that
- * says so.
- *
- * The message says "syncing OR another save" because BOTH produce it. The
- * lock is taken by `write`/`delete`/`renameEntry` and by the admin
- * repair-content-duplicates action as well as by the worker's rebase, so a
- * message naming only the rebase was a confident claim about something that
- * may not be happening. `api/content.ts` routes this error ahead of the
- * generic conflict specifically so the editor sees this wording, which makes
- * the wording load-bearing rather than cosmetic.
+ * Thrown when the bounded wait expires with the branch's content lock still held. Retriable --
+ * callers translate it into a 409 with a message that says so.
+ *
+ * The message says "syncing OR another save" because BOTH produce it: the lock is taken by
+ * `write`/`delete`/`renameEntry` and the admin repair-content-duplicates action as well as by the
+ * worker's rebase, so naming only the rebase would claim more than is known. `api/content.ts`
+ * routes this error ahead of the generic conflict so the editor sees this wording, making it
+ * load-bearing rather than cosmetic.
  */
 export class ContentWriteLockBusyError extends Error {
     constructor(message = 'This branch is busy (syncing with the base branch, or another save is in flight); the change was not saved. Try again in a moment.') {
@@ -115,11 +78,8 @@ const sleep = (ms) => new Promise((resolve) => {
     setTimeout(resolve, ms);
 });
 /**
- * Acquire the branch's content-write lock WITHOUT waiting.
- *
- * Throws an error with `code === 'ELOCKED'` when a live holder has it. Used by
- * the worker's rebase loop (which skips the branch and retries next cycle) and
- * by tests standing in for a writer.
+ * Acquire the branch's content-write lock WITHOUT waiting, for the worker's rebase loop, which
+ * skips the branch and retries next cycle. Throws with `code === 'ELOCKED'` on a live holder.
  */
 export function tryAcquireContentWriteLock(branchRoot, onCompromised) {
     return tryAcquireProvisioningLock(lockTargetDir(branchRoot), CONTENT_WRITE_LOCK_NAME, onCompromised);
@@ -127,14 +87,13 @@ export function tryAcquireContentWriteLock(branchRoot, onCompromised) {
 /**
  * Acquire the branch's content-write lock with a short bounded wait.
  *
- * Retries ONLY on genuine contention (`ELOCKED`), the same discipline
- * `withOccFileLock` uses: proper-lockfile's own retry loop retries blindly on
- * any error, which would burn the whole budget re-hitting e.g. ENOENT after
- * the branch directory was deleted out from under the caller.
+ * Retries ONLY on genuine contention (`ELOCKED`), the same discipline `withOccFileLock` uses:
+ * proper-lockfile's own retry loop retries blindly on any error, burning the whole budget
+ * re-hitting e.g. ENOENT after the branch directory was deleted under the caller.
  *
  * @throws ContentWriteLockBusyError when the budget expires under contention.
  */
-export async function acquireContentWriteLock(branchRoot, waitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, onCompromised) {
+async function acquireContentWriteLock(branchRoot, waitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, onCompromised) {
     const startedAt = Date.now();
     for (let attempt = 0;; attempt++) {
         try {
@@ -146,23 +105,20 @@ export async function acquireContentWriteLock(branchRoot, waitMs = DEFAULT_CONTE
             const remaining = waitMs - (Date.now() - startedAt);
             if (remaining <= 0)
                 throw new ContentWriteLockBusyError();
-            // Exponential backoff with jitter, capped so a long budget still polls
-            // often enough to pick the lock up promptly when the holder releases.
+            // Exponential backoff with jitter, capped so a long budget still polls often enough to
+            // pick the lock up promptly when the holder releases.
             const base = Math.min(40 * 2 ** attempt, 250);
             await sleep(Math.min(base * (0.5 + Math.random()), remaining));
         }
     }
 }
-/**
- * Run `fn` holding the branch's content-write lock, releasing it in a
- * `finally` so a throw can never strand it.
- */
+/** Run `fn` holding the branch's content-write lock, releasing in a `finally` so a throw cannot
+ * strand it. */
 export async function withContentWriteLock(branchRoot, fn, waitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS) {
-    // A compromise means this write may no longer have been exclusive -- the
-    // worker's rebase (or another writer) could have been running against the
-    // same tree. Reporting success would silently accept a possibly-raced write,
-    // so surface the same retriable "branch busy" error contention already maps
-    // to (409) and let the caller re-save against the settled tree.
+    // A compromise means this write may not have been exclusive -- the worker's rebase, or another
+    // writer, could have been running against the same tree. Reporting success would silently
+    // accept a possibly-raced write, so surface the same retriable "branch busy" error (409) that
+    // contention maps to and let the caller re-save against the settled tree.
     let compromised = false;
     const release = await acquireContentWriteLock(branchRoot, waitMs, (err) => {
         compromised = true;
@@ -176,11 +132,10 @@ export async function withContentWriteLock(branchRoot, fn, waitMs = DEFAULT_CONT
         await release();
     }
     if (compromised) {
-        // Deliberately NOT the default "was not saved" message: `fn()` completed,
-        // so the write is on disk. What we lost is the proof it was exclusive, so
-        // the honest instruction is "reload, then decide" rather than "retry",
-        // which would resend a now-stale expectedVersion and bounce off the
-        // caller's own landed write as a phantom editor collision.
+        // Deliberately NOT the default "was not saved" message: `fn()` completed, so the write is on
+        // disk and only the proof of exclusivity is lost. "Reload, then decide" rather than "retry",
+        // which would resend a now-stale expectedVersion and bounce off the caller's own landed write
+        // as a phantom editor collision.
         throw new ContentWriteLockBusyError('This branch was being synced while your change was written, so the change may or may not have been recorded. Reload the entry to see the current state before saving again.');
     }
     return result;

package/dist/utils/debug.d.ts

@@ -15,40 +15,24 @@ export declare class DebugLogger {
     constructor(options?: DebugOptions);
     private shouldLog;
     /**
-     * The ISO-8601 timestamp leads the line BARE - not wrapped in brackets as it
-     * once was. `CANOPYCMS_DEBUG=true` can be set on the EC2 worker, whose stdout
-     * appends to /var/log/canopy-worker/worker.log; the CloudWatch agent's
-     * `multi_line_start_pattern` matches the timestamp at the START of a line
-     * (see worker/log.ts's INVARIANT and cms-service.ts's agent config), so a
-     * leading `[` meant every debug line was silently folded into the previous
-     * event instead of starting its own. The bracketed `[prefix:category]` and
-     * `[level]` fields still follow, so the human-readable shape is unchanged
-     * apart from those two characters.
+     * The ISO-8601 timestamp leads the line BARE, never bracketed. `CANOPYCMS_DEBUG=true` can
+     * be set on the EC2 worker, whose stdout appends to /var/log/canopy-worker/worker.log, and
+     * the CloudWatch agent's `multi_line_start_pattern` matches a timestamp at the START of a
+     * line (see worker/log.ts's INVARIANT and cms-service.ts's agent config): any leading
+     * character folds the line into the previous event instead of starting its own.
      */
     private formatMessage;
     debug(category: string, message: string, data?: unknown): void;
     info(category: string, message: string, data?: unknown): void;
     warn(category: string, message: string, data?: unknown): void;
     error(category: string, message: string, data?: unknown): void;
-    /**
-     * Start timing an operation
-     */
     time(label: string): void;
-    /**
-     * End timing an operation and log the duration
-     */
     timeEnd(category: string, label: string): number | undefined;
-    /**
-     * Wrap an async function with automatic timing
-     */
     timed<T>(category: string, label: string, fn: () => Promise<T>): Promise<T>;
 }
-/**
- * Create a debug logger instance
- */
 export declare function createDebugLogger(options?: DebugOptions): DebugLogger;
 /**
- * Default logger for test infrastructure (E2E tests)
- * Enabled via E2E_DEBUG=true
+ * Default logger for E2E test infrastructure.
+ * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
  */
 export declare const testLogger: DebugLogger;

package/dist/utils/debug.js

@@ -18,15 +18,11 @@ export class DebugLogger {
         return LOG_LEVELS[level] >= LOG_LEVELS[minLevel];
     }
     /**
-     * The ISO-8601 timestamp leads the line BARE - not wrapped in brackets as it
-     * once was. `CANOPYCMS_DEBUG=true` can be set on the EC2 worker, whose stdout
-     * appends to /var/log/canopy-worker/worker.log; the CloudWatch agent's
-     * `multi_line_start_pattern` matches the timestamp at the START of a line
-     * (see worker/log.ts's INVARIANT and cms-service.ts's agent config), so a
-     * leading `[` meant every debug line was silently folded into the previous
-     * event instead of starting its own. The bracketed `[prefix:category]` and
-     * `[level]` fields still follow, so the human-readable shape is unchanged
-     * apart from those two characters.
+     * The ISO-8601 timestamp leads the line BARE, never bracketed. `CANOPYCMS_DEBUG=true` can
+     * be set on the EC2 worker, whose stdout appends to /var/log/canopy-worker/worker.log, and
+     * the CloudWatch agent's `multi_line_start_pattern` matches a timestamp at the START of a
+     * line (see worker/log.ts's INVARIANT and cms-service.ts's agent config): any leading
+     * character folds the line into the previous event instead of starting its own.
      */
     formatMessage(level, category, message) {
         const timestamp = new Date().toISOString();
@@ -59,15 +55,9 @@ export class DebugLogger {
             throw new Error(errorMsg);
         }
     }
-    /**
-     * Start timing an operation
-     */
     time(label) {
         this.timers.set(label, Date.now());
     }
-    /**
-     * End timing an operation and log the duration
-     */
     timeEnd(category, label) {
         const start = this.timers.get(label);
         if (start === undefined) {
@@ -79,9 +69,6 @@ export class DebugLogger {
         this.debug(category, `${label} completed`, { durationMs: duration });
         return duration;
     }
-    /**
-     * Wrap an async function with automatic timing
-     */
     async timed(category, label, fn) {
         this.time(label);
         try {
@@ -92,15 +79,12 @@ export class DebugLogger {
         }
     }
 }
-/**
- * Create a debug logger instance
- */
 export function createDebugLogger(options) {
     return new DebugLogger(options);
 }
 /**
- * Default logger for test infrastructure (E2E tests)
- * Enabled via E2E_DEBUG=true
+ * Default logger for E2E test infrastructure.
+ * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
  */
 export const testLogger = createDebugLogger({
     enabled: process.env.E2E_DEBUG === 'true',

package/dist/utils/entry-url.d.ts

@@ -1,33 +1,21 @@
 /**
- * Shared entry URL computation — used by both server and client code.
- *
- * This module has NO server-only dependencies (no node:fs, etc.)
- * so it can be safely imported into browser bundles.
+ * Shared entry URL computation, used by server and client code alike. No server-only
+ * dependencies, so it is safe to import into browser bundles.
  */
 /**
- * Is this slug the collection-index slug?
+ * Is this slug the collection-index slug? The shared home for that decision — every forward and
+ * reverse URL rule routes through it (see utils/AGENTS.md), and it is re-exported from
+ * `canopycms/server` for adopters.
  *
- * The shared home for that decision. Six sites route through here: `computeEntryUrl` below,
- * `content-tree.ts`'s `defaultBuildPath`, `content-reader.ts`'s `buildEntryPath` and the
- * editor's `buildPreviewSrc` (the four forward-rule implementations), the reverse
- * `resolveUrlPathCandidates`, and `canopycms-next`'s `collectStaticParams`, which skips index
- * entries for a single-segment route. Re-exported from `canopycms/server` for adopters. (`content-tree.ts`'s `indexEntry` lookup still does its own
- * `slug === 'index'`; it is fed slugs already lowercased by the listing, so it is safe rather
- * than shared.) Slug matching is case-insensitive throughout
- * CanopyCMS (`parseSlug` lowercases, and `ContentStore` resolves slugs by a lowercased
- * directory scan), so this compares lowercased — a bare `slug === 'index'` is correct only
- * for callers whose input was already normalized, and silently wrong for the ones handling
- * raw URL segments or on-disk names. `resolveUrlPathCandidates` was exactly that case: its
- * strict compare left `/x/Index` resolving the index entry after `/x/index` stopped.
+ * The compare is lowercased because slug matching is case-insensitive throughout CanopyCMS
+ * (`parseSlug` lowercases; `ContentStore` resolves slugs by a lowercased directory scan): a bare
+ * `slug === 'index'` is correct only where the input is already normalized, and silently wrong
+ * for callers handling raw URL segments or on-disk names.
  */
 export declare function isIndexSlug(slug: string | undefined): boolean;
 /**
- * Compute a URL path from an entry's collection path and slug.
- *
- * Logic:
- * - Strip the contentRoot prefix (e.g., "content/") from the collection path
- * - Append the slug (unless it's "index", which collapses to the parent path)
- * - Always returns a path starting with "/"
+ * Compute a URL path from an entry's collection path and slug: strip the `contentRoot` prefix,
+ * append the slug unless it is an index slug, lowercase. Always starts with `/`.
  *
  * Examples:
  *   ("content/posts", "hello-world", "content") => "/posts/hello-world"

package/dist/utils/entry-url.js

@@ -1,36 +1,24 @@
 /**
- * Shared entry URL computation — used by both server and client code.
- *
- * This module has NO server-only dependencies (no node:fs, etc.)
- * so it can be safely imported into browser bundles.
+ * Shared entry URL computation, used by server and client code alike. No server-only
+ * dependencies, so it is safe to import into browser bundles.
  */
 import { trimSlashes } from '../paths/normalize.js';
 /**
- * Is this slug the collection-index slug?
+ * Is this slug the collection-index slug? The shared home for that decision — every forward and
+ * reverse URL rule routes through it (see utils/AGENTS.md), and it is re-exported from
+ * `canopycms/server` for adopters.
  *
- * The shared home for that decision. Six sites route through here: `computeEntryUrl` below,
- * `content-tree.ts`'s `defaultBuildPath`, `content-reader.ts`'s `buildEntryPath` and the
- * editor's `buildPreviewSrc` (the four forward-rule implementations), the reverse
- * `resolveUrlPathCandidates`, and `canopycms-next`'s `collectStaticParams`, which skips index
- * entries for a single-segment route. Re-exported from `canopycms/server` for adopters. (`content-tree.ts`'s `indexEntry` lookup still does its own
- * `slug === 'index'`; it is fed slugs already lowercased by the listing, so it is safe rather
- * than shared.) Slug matching is case-insensitive throughout
- * CanopyCMS (`parseSlug` lowercases, and `ContentStore` resolves slugs by a lowercased
- * directory scan), so this compares lowercased — a bare `slug === 'index'` is correct only
- * for callers whose input was already normalized, and silently wrong for the ones handling
- * raw URL segments or on-disk names. `resolveUrlPathCandidates` was exactly that case: its
- * strict compare left `/x/Index` resolving the index entry after `/x/index` stopped.
+ * The compare is lowercased because slug matching is case-insensitive throughout CanopyCMS
+ * (`parseSlug` lowercases; `ContentStore` resolves slugs by a lowercased directory scan): a bare
+ * `slug === 'index'` is correct only where the input is already normalized, and silently wrong
+ * for callers handling raw URL segments or on-disk names.
  */
 export function isIndexSlug(slug) {
     return slug?.toLowerCase() === 'index';
 }
 /**
- * Compute a URL path from an entry's collection path and slug.
- *
- * Logic:
- * - Strip the contentRoot prefix (e.g., "content/") from the collection path
- * - Append the slug (unless it's "index", which collapses to the parent path)
- * - Always returns a path starting with "/"
+ * Compute a URL path from an entry's collection path and slug: strip the `contentRoot` prefix,
+ * append the slug unless it is an index slug, lowercase. Always starts with `/`.
  *
  * Examples:
  *   ("content/posts", "hello-world", "content") => "/posts/hello-world"
@@ -39,7 +27,6 @@ export function isIndexSlug(slug) {
  */
 export function computeEntryUrl(collection, slug, contentRoot) {
     const root = trimSlashes(contentRoot);
-    // Strip contentRoot prefix
     let stripped = collection;
     if (root && collection.startsWith(`${root}/`)) {
         stripped = collection.slice(root.length + 1);
@@ -47,9 +34,7 @@ export function computeEntryUrl(collection, slug, contentRoot) {
     else if (collection === root) {
         stripped = '';
     }
-    // Build URL segments
     const segments = stripped.split('/').filter(Boolean);
-    // Append slug unless it's an index slug (index entries collapse to parent)
     if (slug && !isIndexSlug(slug)) {
         segments.push(slug);
     }

package/dist/utils/error.d.ts

@@ -1,103 +1,38 @@
-/**
- * Error handling utilities for type-safe error handling.
- *
- * These utilities help convert `catch (err: unknown)` to usable error information
- * without using `any` types.
- */
-/**
- * Extract a message string from an unknown error value.
- *
- * @param err - The caught error (unknown type)
- * @returns A string message suitable for logging or user display
- *
- * @example
- * ```ts
- * try {
- *   await riskyOperation()
- * } catch (err: unknown) {
- *   canopyLogError('Operation failed:', getErrorMessage(err))
- * }
- * ```
- */
+/** Reading a `catch (err: unknown)` value as usable error information, without `any`. */
+/** Message string for an unknown thrown value. */
 export declare function getErrorMessage(err: unknown): string;
 /**
- * Redact sensitive material from an error message before sending it to API
- * clients. Log the ORIGINAL message server-side; send the sanitized one.
+ * Redact sensitive material from an error message before it reaches an API client. Log the
+ * ORIGINAL message server-side; send the sanitized one.
  *
- * Git/filesystem errors are unbounded (stderr varies by git version, locale,
- * and hooks can print anything), so enumerating safe messages is not
- * feasible. Instead, redact the known-sensitive SHAPES that can appear in
- * any of them:
- * - credentials embedded in URLs (`https://x-access-token:tok@github.com/…`)
- * - absolute filesystem paths (workspace roots, EFS mounts, home directories)
+ * Git/filesystem error text is unbounded (stderr varies by git version and locale, and hooks
+ * print anything), so this redacts the known-sensitive SHAPES rather than enumerating safe
+ * messages: credentials embedded in URLs (`https://x-access-token:tok@github.com/…`) and
+ * absolute filesystem paths (workspace roots, EFS mounts, home directories). Paths under the
+ * current working directory are shortened to relative form (CMS-internal layout like
+ * `.canopy-dev/remote.git` helps debugging and is not sensitive); absolute paths outside it
+ * become `<path>`.
  *
- * Paths under the current working directory are shortened to relative form
- * (CMS-internal layout like `.canopy-dev/remote.git` is useful for debugging
- * and not sensitive); absolute paths outside it are replaced with `<path>`.
- */
-/**
- * TAG: `[REDACT]`
- *
- * Grep `[REDACT]` to find every site that persists or surfaces raw error text on
- * a path that reaches a browser — worker task errors folded into
- * `worker-status.json`, `branch.json` parse failures served by the admin
- * branch-health endpoint, rebase-failure messages, and their tests.
- *
- * Those sites carried the tag `[HIGH-1]`/`[MEDIUM-2]` until 2026-08-23, IDs from
- * a review pass whose findings list was never committed — 13 occurrences across
- * 6 files resolving to nothing. Renamed rather than deleted because the
- * underlying rule is real and genuinely cross-file: a Node error embeds absolute
- * paths, and a git remote URL can embed a token, so anything on that path is
- * redacted through the function below.
- *
- * The tag is a grep aid, not the rule. The rule is stated at each site.
+ * TAG: `[REDACT]` — grep it for every site that persists or surfaces raw error text on a path
+ * reaching a browser (worker task errors folded into `worker-status.json`, `branch.json` parse
+ * failures served by the admin branch-health endpoint, rebase-failure messages, and their
+ * tests). A Node error embeds absolute paths and a git remote URL can embed a token, so
+ * everything on such a path goes through this function. The tag is a grep aid; the rule itself
+ * is stated at each site.
  */
 export declare function sanitizeErrorMessage(message: string): string;
 /**
- * Redact only credential material from a message, leaving filesystem paths
- * intact. For server-side log lines that deliberately keep full path detail
- * (server logs only, useful for debugging) but must never persist a live
- * token — client-facing messages go through sanitizeErrorMessage instead,
- * which calls this and then also redacts paths.
+ * Redact only credential material, leaving filesystem paths intact — for server-side log lines
+ * that deliberately keep full path detail for debugging but must never persist a live token.
+ * Client-facing messages go through `sanitizeErrorMessage` instead, which calls this and then
+ * also redacts paths.
  */
 export declare function redactCredentials(message: string): string;
-/**
- * Type guard to check if an error is a Node.js system error with a code property.
- *
- * @param err - The caught error (unknown type)
- * @returns True if the error has a `code` property (like ENOENT, EACCES, etc.)
- *
- * @example
- * ```ts
- * try {
- *   await fs.readFile(path)
- * } catch (err: unknown) {
- *   if (isNodeError(err) && err.code === 'ENOENT') {
- *     return null // File not found is expected
- *   }
- *   throw err
- * }
- * ```
- */
+/** True for a Node system error — an `Error` carrying a `code` (ENOENT, EACCES, …). */
 export declare function isNodeError(err: unknown): err is NodeJS.ErrnoException;
-/**
- * Check if an error indicates a "file not found" condition.
- *
- * @param err - The caught error (unknown type)
- * @returns True if the error is ENOENT (file/directory not found)
- */
+/** True for ENOENT. */
 export declare function isNotFoundError(err: unknown): boolean;
-/**
- * Check if an error indicates a "permission denied" condition.
- *
- * @param err - The caught error (unknown type)
- * @returns True if the error is EACCES (permission denied)
- */
+/** True for EACCES. */
 export declare function isPermissionError(err: unknown): boolean;
-/**
- * Check if an error indicates a "file already exists" condition.
- *
- * @param err - The caught error (unknown type)
- * @returns True if the error is EEXIST (file already exists)
- */
+/** True for EEXIST. */
 export declare function isFileExistsError(err: unknown): boolean;