canopycms 0.0.67-int.90 → 0.0.67

package/dist/utils/git.js

@@ -1,39 +1,30 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { simpleGit } from 'simple-git';
-// Matches scheme://... URLs (http, https, ssh, git — case-insensitive).
 const NETWORK_SCHEME_PATTERN = /^(https?|ssh|git):\/\//i;
-// Matches git's "transport helper" syntax, e.g. `ext::sh -c ...` or `fd::7`.
-// Any `scheme::` prefix hands the URL to `git-remote-<scheme>`, which can run
-// arbitrary commands — always treat it as network/untrusted.
+// git's "transport helper" syntax (`ext::sh -c ...`, `fd::7`): any `scheme::` prefix hands the
+// URL to `git-remote-<scheme>`, which can run arbitrary commands — always network/untrusted.
 const TRANSPORT_HELPER_PATTERN = /^[a-z][a-z0-9+.-]*::/i;
-// A leading `-` means the "URL" would be parsed as a command-line option by
-// git (e.g. `--upload-pack=/evil`) — argument injection, not a real remote.
+// A leading `-` makes git parse the "URL" as a command-line option (`--upload-pack=/evil`) —
+// argument injection, not a real remote.
 const LEADING_OPTION_PATTERN = /^-/;
-// Windows drive paths (`C:\...`, `C:/...`) are the one local form that
-// contains a colon before any slash; everything else with a colon before the
-// first slash is scp-like remote syntax, e.g. `git@github.com:owner/repo.git`
-// or the bare `github.com:owner/repo.git` (no `@` required — git still
-// treats `host:path` as ssh).
+// Windows drive paths (`C:\...`, `C:/...`) are the one local form carrying a colon before any
+// slash; everything else with a colon before the first slash is scp-like remote syntax
+// (`git@github.com:owner/repo.git`, or bare `github.com:owner/repo.git` — git treats `host:path`
+// as ssh with no `@` required).
 const WINDOWS_DRIVE_PATTERN = /^[a-zA-Z]:[\\/]/;
 const COLON_BEFORE_SLASH_PATTERN = /^[^/\\\s]+:/;
 /**
- * Whether a git remote URL points at a network location — http(s)://,
- * ssh://, git://, scp-like `[user@]host:path`, a transport-helper `scheme::`
- * form, or a leading-`-` value git would parse as a command-line option —
- * rather than a local filesystem path.
+ * Whether a git remote URL points at a network location rather than a local filesystem path. Only
+ * `file://` URLs, plain filesystem paths and Windows drive paths are LOCAL; the patterns above
+ * enumerate the network forms.
  *
- * `file://` URLs and plain filesystem paths are LOCAL — this is the
- * distinction GitManager's prod-mode network-remote guard relies on (see
- * `resolveRemoteUrl`): the intended prod topology only ever resolves a local
- * path (an auto-detected/auto-initialized `remote.git`), so anything network
- * flowing in via an explicit param, config, or env var is almost always a
- * misconfiguration in prod. Because the guard's job is catching prod
- * misconfig (not being a strict URL parser), this classifier treats anything
- * git could interpret as a network transport, a transport helper, or a
- * command-line option as "network". The one local carve-out beyond `file://`
- * is a Windows drive path (`C:\...` / `C:/...`), which replaces the old
- * `@`-required heuristic for scp-like syntax.
+ * The distinction GitManager's prod-mode network-remote guard relies on (see `resolveRemoteUrl`):
+ * the intended prod topology only ever resolves a local path (an auto-detected/auto-initialized
+ * `remote.git`), so anything network arriving via an explicit param, config, or env var is almost
+ * always a prod misconfiguration. Catching that is the job, not being a strict URL parser, so
+ * anything git could read as a network transport, a transport helper, or a command-line option
+ * counts as "network".
  */
 export function isNetworkRemoteUrl(url) {
     if (/^file:\/\//i.test(url))
@@ -48,106 +39,78 @@ export function isNetworkRemoteUrl(url) {
         return false;
     return COLON_BEFORE_SLASH_PATTERN.test(url);
 }
-// Matches git's per-ref push-status summary line marking a ref as rejected.
-// Present verbatim in BOTH output shapes CanopyCMS's push call sites produce:
-// the plain CLI form (`GitManager.push()`'s `.raw(['push', ...])`, e.g.
-// ` ! [rejected]        branch -> branch (non-fast-forward)`) and the
-// machine-readable `--porcelain` form simple-git's `.push()` wrapper requests
-// (`CmsWorker.pushBranchToGitHub`/`pushSettingsBranches`, e.g.
-// `!\trefs/heads/branch:refs/heads/branch\t[rejected] (non-fast-forward)`) --
-// `--porcelain` only changes the per-ref summary's leading fields, not this
-// trailing human-readable bracket text.
+// git's per-ref push-status summary marking a ref as rejected. Present verbatim in BOTH output
+// shapes CanopyCMS's push sites produce -- the plain CLI form and the `--porcelain` form
+// simple-git's `.push()` requests -- because `--porcelain` changes only the summary's leading
+// fields, not this trailing bracket text.
 const REJECTED_MARKER = '[rejected]';
-// git's two names for the SAME underlying condition: `non-fast-forward` fires
-// when the pusher's own remote-tracking ref is present but stale;
-// `fetch first` fires when no local knowledge of the remote ref exists at all
-// (e.g. it was never fetched). Both mean the remote has commits this side
-// doesn't have -- retrying the identical push can never succeed until the
-// caller fetches and integrates (or picks a different branch name).
+// git's two names for the SAME condition: `non-fast-forward` when the pusher's remote-tracking ref
+// is present but stale, `fetch first` when no local knowledge of the remote ref exists at all.
+// Both mean the remote has commits this side does not, so the identical push can never succeed
+// until the caller fetches and integrates (or picks a different branch name).
 const NON_FAST_FORWARD_REASONS = ['non-fast-forward', 'fetch first'];
-// git always prints this stderr hint immediately after a rejected push,
-// regardless of --porcelain (porcelain only affects the machine-readable
-// summary line, not the human hint text that follows it) -- a second,
+// git prints this stderr hint immediately after a rejected push, `--porcelain` or not -- a second,
 // independent signal for the same condition.
 const REJECTION_HINT = 'Updates were rejected because';
 /**
- * Whether a git push failure message is git's non-fast-forward rejection --
- * the remote has diverged (moved ahead with commits this side never fetched),
- * so retrying the IDENTICAL push can never succeed. In CanopyCMS this is the
- * signature of two CanopyCMS deployments sharing one GitHub repo and picking
- * the same content-branch name, or someone pushing directly to GitHub.
+ * Whether a git push failure message is git's non-fast-forward rejection -- the remote has
+ * diverged, so retrying the IDENTICAL push can never succeed. In CanopyCMS that means two
+ * deployments sharing one GitHub repo and picking the same content-branch name, or someone pushing
+ * directly to GitHub.
  *
- * Deliberately narrow: ordinary transient push failures -- network drops,
- * auth/permission denial, lock contention -- must keep retrying with backoff
- * (see worker/task-runner.ts's `isPermanentTaskFailure`, which treats git
- * failures as transient precisely so those cases still get retried). Only
- * this specific, structurally-unretryable shape should fail fast (worker) or
- * return 409 (API) instead.
+ * Deliberately narrow: ordinary transient push failures -- network drops, auth/permission denial,
+ * lock contention -- must keep retrying with backoff (worker/task-runner.ts's
+ * `isPermanentTaskFailure` treats git failures as transient precisely so they do). Only this
+ * structurally-unretryable shape fails fast (worker) or returns 409 (API).
  *
- * Matches git's literal (English) rejection text, which is gettext-
- * translated -- callers MUST run the underlying git command with a
- * locale-pinning env (see `gitChildEnv` in `../git-manager.ts`) or an ambient
- * LANG/LC_ALL could silently turn this into a permanent no-op.
+ * Matches git's literal English rejection text, which is gettext-translated: callers MUST run the
+ * git command with a locale-pinning env (`gitChildEnv` in `../git-manager.ts`), or an ambient
+ * LANG/LC_ALL silently turns this into a permanent no-op.
  */
 export function isNonFastForwardRejection(message) {
     const hasNonFastForwardRejection = message.includes(REJECTED_MARKER) &&
         NON_FAST_FORWARD_REASONS.some((reason) => message.includes(reason));
     return hasNonFastForwardRejection || message.includes(REJECTION_HINT);
 }
-// git's reason text when a `--force-with-lease=<ref>:<sha>` push is refused
-// because the remote is not at `<sha>`.
+// git's reason text when a `--force-with-lease=<ref>:<sha>` push is refused because the remote is
+// not at `<sha>`.
 const STALE_LEASE_REASON = 'stale info';
 /**
- * Whether a git push failure message is a refused `--force-with-lease` --
- * the remote ref is NOT at the commit the pusher expected, so the forced
- * update was declined and nothing was overwritten.
+ * Whether a git push failure message is a refused `--force-with-lease` -- the remote ref is NOT at
+ * the commit the pusher expected, so the forced update was declined and nothing overwritten.
  *
- * A SEPARATE predicate from `isNonFastForwardRejection` because git's output
- * for the two is disjoint: a refused lease prints
- * ` ! [rejected]        branch -> branch (stale info)` and, unlike an
- * ordinary rejection, emits NEITHER `non-fast-forward`/`fetch first` NOR the
- * `Updates were rejected because` hint. Without this predicate every lease
- * refusal would be classified transient and retried -- three identical,
- * guaranteed-to-fail force attempts -- instead of surfacing as the permanent,
- * human-actionable state it is.
- *
- * Same locale caveat as above: the reason text is gettext-translated, so
- * callers MUST pin the locale (`gitChildEnv`/`gitNetworkChildEnv`).
+ * A SEPARATE predicate from `isNonFastForwardRejection` because git's output for the two is
+ * disjoint: a refused lease prints `(stale info)` and emits NEITHER `non-fast-forward`/`fetch
+ * first` NOR the `Updates were rejected because` hint. Without it every lease refusal is
+ * classified transient and retried -- identical, guaranteed-to-fail force attempts -- instead of
+ * surfacing as the permanent, human-actionable state it is. Same locale caveat as above.
  */
 export function isStaleLeaseRejection(message) {
     return message.includes(REJECTED_MARKER) && message.includes(STALE_LEASE_REASON);
 }
-// git's message when `git fetch <remote> <branch>` names a ref the remote does
-// not have. Both spellings occur: modern git prints the lowercase form, older
-// versions and some transports capitalize it.
+// git's message when `git fetch <remote> <branch>` names a ref the remote does not have. Both
+// spellings occur: modern git prints the lowercase form, older versions and some transports
+// capitalize it.
 const MISSING_REMOTE_REF_REASONS = ["couldn't find remote ref", "Couldn't find remote ref"];
 /**
- * Whether a `git fetch <remote> <branch>` failure is specifically "that ref
- * doesn't exist on the remote" -- the ONLY benign fetch outcome, meaning the
- * branch has never been pushed.
- *
- * Narrow on purpose, and the narrowness is the whole point. This predicate
- * exists because a bare `catch` around the fetch classified EVERY failure --
- * unreachable remote, auth denial, permission error on the workspace, corrupt
- * object store -- as "nothing to pull", which callers then logged as normal
- * and proceeded past. Anything this does not recognize must reach the caller
- * as the genuine error it is.
+ * Whether a `git fetch <remote> <branch>` failure is specifically "that ref doesn't exist on the
+ * remote" -- the ONLY benign fetch outcome, meaning the branch has never been pushed.
  *
- * Same locale caveat as the predicates above: the text is gettext-translated,
- * so callers MUST run git with a locale-pinning env (`gitChildEnv`).
+ * Narrow on purpose, and the narrowness is the point: a bare `catch` around the fetch classifies
+ * EVERY failure -- unreachable remote, auth denial, permission error on the workspace, corrupt
+ * object store -- as "nothing to pull", which callers then log as normal and proceed past.
+ * Anything this does not recognize must reach the caller as the genuine error it is. Same locale
+ * caveat as the predicates above.
  */
 export function isMissingRemoteRefFailure(message) {
     return MISSING_REMOTE_REF_REASONS.some((reason) => message.includes(reason));
 }
 /**
- * Resolve a repository's git directory from its working-tree root, handling
- * both layouts: a real `.git` directory, and a `.git` FILE containing a
- * `gitdir: <path>` pointer (linked worktrees, submodules).
- *
- * Deliberately fs-only rather than `git rev-parse --git-dir`: the callers are
- * a per-branch sync loop and an admin-facing health scan that already walk
- * every branch directory, and neither should pay a subprocess per branch just
- * to find a path.
+ * Resolve a repository's git directory from its working-tree root, handling both layouts: a real
+ * `.git` directory, and a `.git` FILE holding a `gitdir: <path>` pointer (linked worktrees,
+ * submodules). Deliberately fs-only rather than `git rev-parse --git-dir`: the callers are a
+ * per-branch sync loop and an admin-facing health scan that already walk every branch directory,
+ * and neither should pay a subprocess per branch just to find a path.
  */
 async function resolveGitDir(repoPath) {
     const dotGit = path.join(repoPath, '.git');
@@ -173,20 +136,16 @@ async function resolveGitDir(repoPath) {
     }
 }
 /**
- * Whether a repository has an INTERRUPTED rebase on disk — the `rebase-merge`
- * (interactive/merge backend) or `rebase-apply` (am backend) state directory
- * git leaves behind when a rebase stops for conflicts or the process dies
- * mid-way.
+ * Whether a repository has an INTERRUPTED rebase on disk — the `rebase-merge` (interactive/merge
+ * backend) or `rebase-apply` (am backend) state directory git leaves when a rebase stops for
+ * conflicts or the process dies mid-way. Invisible to every other check the worker makes: a clone
+ * left mid-rebase reports uncommitted changes, so the sync loop's dirty check skips it as
+ * `skippedDirty` on every cycle forever, and `branch-health` sees valid branch.json and scans it
+ * as healthy. Nothing self-heals without it.
  *
- * This state is invisible to every other check the worker makes: a clone left
- * mid-rebase reports uncommitted changes, so the sync loop's dirty check skips
- * it as `skippedDirty` on every cycle forever, and `branch-health` sees valid
- * branch.json and scans it as healthy. Nothing self-heals, and recovery
- * previously meant an operator running `git rebase --abort` on EFS by hand.
- *
- * Never throws — a missing or unreadable repo is reported as "no rebase",
- * which is the safe direction for both callers (the worker only ever uses a
- * `true` to justify an abort it holds the content-write lock for).
+ * Never throws — a missing or unreadable repo is reported as "no rebase", the safe direction for
+ * both callers (the worker only uses a `true` to justify an abort it holds the content-write lock
+ * for).
  */
 export async function isRebaseInProgress(repoPath) {
     const gitDir = await resolveGitDir(repoPath);
@@ -199,9 +158,8 @@ export async function isRebaseInProgress(repoPath) {
     return results.some(Boolean);
 }
 /**
- * Detect the current HEAD branch name for a given repository root.
- * Returns the branch name, or the provided fallback (default 'main')
- * if detection fails or HEAD is detached.
+ * The repository's current HEAD branch name, or `fallback` when detection fails or HEAD is
+ * detached.
  */
 export async function detectHeadBranch(repoRoot, fallback = 'main') {
     try {
@@ -214,18 +172,14 @@ export async function detectHeadBranch(repoRoot, fallback = 'main') {
     }
 }
 /**
- * Resolve the base branch — the fork point for CMS editing branches and the
- * branch used to seed workspace clones.
- *
- * This is the single definition of base-branch behavior (see ARCHITECTURE.md
- * "Branch Identity"):
- * - An explicitly configured `defaultBaseBranch` always wins, in both modes.
- * - In dev mode it is detected from the current git HEAD, so workspaces fork
- *   from the branch the developer has checked out.
- * - Otherwise it is 'main'.
+ * Resolve the base branch — the fork point for CMS editing branches and the branch workspace
+ * clones are seeded from. The single definition of base-branch behavior (see ARCHITECTURE.md
+ * "Branch Identity"): a configured `defaultBaseBranch` always wins in both modes; dev mode
+ * otherwise detects the current git HEAD, so workspaces fork from the developer's checked-out
+ * branch; otherwise 'main'.
  *
- * Static deployments never reach git operations, so callers in static paths
- * must short-circuit before calling this (see createCanopyServices).
+ * Static deployments never reach git operations, so callers on static paths must short-circuit
+ * before calling this (see createCanopyServices).
  */
 export async function resolveBaseBranch(options) {
     if (options.defaultBaseBranch)

package/dist/utils/logger.d.ts

@@ -1,51 +1,27 @@
 /**
- * Process-scoped logger indirection for modules that run in BOTH the worker
- * daemon and the Lambda/dev server.
- *
- * ## Why this exists
- *
- * `worker/log.ts` documents a hard invariant: every line written to
- * `/var/log/canopy-worker/worker.log` must start with an ISO-8601 timestamp,
- * because the CloudWatch agent's `multi_line_start_pattern` is keyed on that
- * prefix (see `canopycms-cdk/src/constructs/cms-service.ts`). A line WITHOUT
- * the prefix is not a new event - it is appended to the PREVIOUS one,
- * inheriting that event's timestamp and carrying none of its own severity tag.
- *
- * The worker's own code honoured that by calling `workerLog*`. But the worker
- * process also executes shared modules that were never worker-specific and
- * called bare `console.warn`: `github-service.ts` (the throttling plugin's
- * rate-limit callbacks fire on the worker's own Octokit, and the PR
- * create/update path runs on the worker's submit task) and `branch-registry.ts`
- * (registry regeneration, reached from every worker `meta.save()`). Their
- * output landed in worker.log unprefixed, so an operationally interesting
- * warning - "GitHub throttled us" - was silently folded into a minutes-old
- * event and became invisible to `filter @message like /WARN/`. Invisible
- * locally too, since vitest intercepts console.
- *
- * ## Why process-scoped rather than a threaded parameter
- *
- * The invariant is a property of the PROCESS's stdout/stderr, not of any
- * particular call: the same `branch-registry.ts` line is correct as bare
- * console under Lambda and wrong under the worker. Threading a logger down to
- * it would mean touching every signature between `CmsWorker.rebase*` and
- * `BranchMetadataFileManager.loadOnly` to carry a logging concern. One
- * process-wide switch, set once at the worker entrypoint, expresses exactly
- * the thing that is actually true.
- *
- * Lambda and the dev server install nothing and keep plain `console`, which is
- * correct there - CloudWatch's Lambda integration stamps and delimits events
- * on its own.
- *
- * ## Usage
- *
- * Shared server-side modules call `canopyLogWarn`/`canopyLogError`/`canopyLog`
- * instead of `console.*`. The worker entrypoint calls `installWorkerLogger()`
- * (`worker/log.ts`, re-exported from `worker/cms-worker.ts`) once, before doing
- * any work.
- *
- * Not for browser/editor code: those keep `console` directly. This module is
- * dependency-free so importing it can never drag a server-only dependency into
- * a client bundle, but there is nothing for it to do in a browser.
+ * Process-scoped logger indirection for modules that run in BOTH the worker daemon and the
+ * Lambda/dev server.
+ *
+ * `worker/log.ts` holds the invariant: every line written to `/var/log/canopy-worker/worker.log`
+ * must start with an ISO-8601 timestamp, because the CloudWatch agent's `multi_line_start_pattern`
+ * is keyed on that prefix (see `canopycms-cdk/src/constructs/cms-service.ts`). A line WITHOUT the
+ * prefix is not a new event - it is appended to the PREVIOUS one, inheriting that timestamp and
+ * carrying none of its own severity tag, so an operationally interesting warning goes invisible to
+ * `filter @message like /WARN/` (and locally too, since vitest intercepts console). Shared modules
+ * the worker also executes (`github-service.ts`, `branch-registry.ts`) would otherwise emit bare
+ * `console.warn` into that log.
+ *
+ * Process-scoped rather than a threaded parameter because the invariant belongs to the PROCESS's
+ * stdout/stderr, not to any particular call: the same `branch-registry.ts` line is correct as bare
+ * console under Lambda and wrong under the worker. Lambda and the dev server install nothing and
+ * keep plain `console`, which is correct there - CloudWatch's Lambda integration stamps and
+ * delimits events on its own.
+ *
+ * So shared server-side modules call `canopyLogWarn`/`canopyLogError`/`canopyLog`, and the worker
+ * entrypoint calls `installWorkerLogger()` (`worker/log.ts`, re-exported from
+ * `worker/cms-worker.ts`) once before doing any work. Not for browser/editor code, which keeps
+ * `console`. Dependency-free, so importing it can never drag a server-only dependency into a
+ * client bundle.
  */
 /** The three levels the shared modules use. Structurally satisfied by `console`. */
 export interface CanopyLogger {
@@ -58,11 +34,20 @@ export interface CanopyLogger {
  * call after the modules that use the helpers have already been imported.
  */
 export declare function setCanopyLogger(logger: CanopyLogger): void;
-/** Restore the default (`console`). Exists for tests; production installs once and never reverts. */
+/**
+ * Restore the default (`console`). Exists for tests; production installs once and never reverts.
+ * @internal Exported for tests.
+ */
 export declare function resetCanopyLogger(): void;
-/** The logger currently installed. Exported for assertions; prefer the helpers below. */
+/**
+ * The logger currently installed. Exported for assertions; prefer the helpers below.
+ * @internal Exported for tests.
+ */
 export declare function getCanopyLogger(): CanopyLogger;
-/** Informational. Routes to stdout (or the worker's timestamped stdout). */
+/**
+ * Informational. Routes to stdout (or the worker's timestamped stdout).
+ * @internal Exported for tests.
+ */
 export declare function canopyLog(...args: unknown[]): void;
 /** Recoverable problem - the caller carries on. Routes to stderr. */
 export declare function canopyLogWarn(...args: unknown[]): void;

package/dist/utils/logger.js

@@ -1,58 +1,32 @@
 /**
- * Process-scoped logger indirection for modules that run in BOTH the worker
- * daemon and the Lambda/dev server.
+ * Process-scoped logger indirection for modules that run in BOTH the worker daemon and the
+ * Lambda/dev server.
  *
- * ## Why this exists
+ * `worker/log.ts` holds the invariant: every line written to `/var/log/canopy-worker/worker.log`
+ * must start with an ISO-8601 timestamp, because the CloudWatch agent's `multi_line_start_pattern`
+ * is keyed on that prefix (see `canopycms-cdk/src/constructs/cms-service.ts`). A line WITHOUT the
+ * prefix is not a new event - it is appended to the PREVIOUS one, inheriting that timestamp and
+ * carrying none of its own severity tag, so an operationally interesting warning goes invisible to
+ * `filter @message like /WARN/` (and locally too, since vitest intercepts console). Shared modules
+ * the worker also executes (`github-service.ts`, `branch-registry.ts`) would otherwise emit bare
+ * `console.warn` into that log.
  *
- * `worker/log.ts` documents a hard invariant: every line written to
- * `/var/log/canopy-worker/worker.log` must start with an ISO-8601 timestamp,
- * because the CloudWatch agent's `multi_line_start_pattern` is keyed on that
- * prefix (see `canopycms-cdk/src/constructs/cms-service.ts`). A line WITHOUT
- * the prefix is not a new event - it is appended to the PREVIOUS one,
- * inheriting that event's timestamp and carrying none of its own severity tag.
+ * Process-scoped rather than a threaded parameter because the invariant belongs to the PROCESS's
+ * stdout/stderr, not to any particular call: the same `branch-registry.ts` line is correct as bare
+ * console under Lambda and wrong under the worker. Lambda and the dev server install nothing and
+ * keep plain `console`, which is correct there - CloudWatch's Lambda integration stamps and
+ * delimits events on its own.
  *
- * The worker's own code honoured that by calling `workerLog*`. But the worker
- * process also executes shared modules that were never worker-specific and
- * called bare `console.warn`: `github-service.ts` (the throttling plugin's
- * rate-limit callbacks fire on the worker's own Octokit, and the PR
- * create/update path runs on the worker's submit task) and `branch-registry.ts`
- * (registry regeneration, reached from every worker `meta.save()`). Their
- * output landed in worker.log unprefixed, so an operationally interesting
- * warning - "GitHub throttled us" - was silently folded into a minutes-old
- * event and became invisible to `filter @message like /WARN/`. Invisible
- * locally too, since vitest intercepts console.
- *
- * ## Why process-scoped rather than a threaded parameter
- *
- * The invariant is a property of the PROCESS's stdout/stderr, not of any
- * particular call: the same `branch-registry.ts` line is correct as bare
- * console under Lambda and wrong under the worker. Threading a logger down to
- * it would mean touching every signature between `CmsWorker.rebase*` and
- * `BranchMetadataFileManager.loadOnly` to carry a logging concern. One
- * process-wide switch, set once at the worker entrypoint, expresses exactly
- * the thing that is actually true.
- *
- * Lambda and the dev server install nothing and keep plain `console`, which is
- * correct there - CloudWatch's Lambda integration stamps and delimits events
- * on its own.
- *
- * ## Usage
- *
- * Shared server-side modules call `canopyLogWarn`/`canopyLogError`/`canopyLog`
- * instead of `console.*`. The worker entrypoint calls `installWorkerLogger()`
- * (`worker/log.ts`, re-exported from `worker/cms-worker.ts`) once, before doing
- * any work.
- *
- * Not for browser/editor code: those keep `console` directly. This module is
- * dependency-free so importing it can never drag a server-only dependency into
- * a client bundle, but there is nothing for it to do in a browser.
+ * So shared server-side modules call `canopyLogWarn`/`canopyLogError`/`canopyLog`, and the worker
+ * entrypoint calls `installWorkerLogger()` (`worker/log.ts`, re-exported from
+ * `worker/cms-worker.ts`) once before doing any work. Not for browser/editor code, which keeps
+ * `console`. Dependency-free, so importing it can never drag a server-only dependency into a
+ * client bundle.
  */
 /**
- * Deliberately mutable module state, read at CALL time by the helpers below
- * rather than captured at import time. Module import order is not something a
- * call site controls, so a captured reference would mean whether a line got its
- * prefix depended on whether `github-service.ts` happened to be imported before
- * or after the entrypoint installed the worker logger.
+ * Deliberately mutable module state, read at CALL time rather than captured at import time. A call
+ * site does not control module import order, so a captured reference would make a line's prefix
+ * depend on whether its module was imported before or after the worker logger was installed.
  */
 let active = console;
 /**
@@ -62,15 +36,24 @@ let active = console;
 export function setCanopyLogger(logger) {
     active = logger;
 }
-/** Restore the default (`console`). Exists for tests; production installs once and never reverts. */
+/**
+ * Restore the default (`console`). Exists for tests; production installs once and never reverts.
+ * @internal Exported for tests.
+ */
 export function resetCanopyLogger() {
     active = console;
 }
-/** The logger currently installed. Exported for assertions; prefer the helpers below. */
+/**
+ * The logger currently installed. Exported for assertions; prefer the helpers below.
+ * @internal Exported for tests.
+ */
 export function getCanopyLogger() {
     return active;
 }
-/** Informational. Routes to stdout (or the worker's timestamped stdout). */
+/**
+ * Informational. Routes to stdout (or the worker's timestamped stdout).
+ * @internal Exported for tests.
+ */
 export function canopyLog(...args) {
     active.log(...args);
 }

package/dist/utils/provisioning-lock.d.ts

@@ -1,50 +1,38 @@
 /**
- * Called when proper-lockfile reports the lock was lost mid-hold (its directory
- * vanished, or a refresh failed and another holder may have taken over).
+ * Called when proper-lockfile reports the lock was lost mid-hold (its directory vanished, or a
+ * refresh failed and another holder may have taken over).
  *
- * Every call site must decide what that means for ITS critical section, which
- * is why this is a parameter rather than a fixed policy: a compromise during
- * idempotent provisioning is survivable, but a compromise during the worker's
- * rebase means a second writer may be live and the next destructive git step
- * must not run. What is NOT negotiable is that it must not throw --
- * proper-lockfile invokes it from inside the refresh timer, so a throw is an
- * uncaught exception that kills the process.
+ * A parameter rather than a fixed policy because every call site must decide what that means for
+ * ITS critical section: a compromise during idempotent provisioning is survivable, one during
+ * the worker's rebase means a second writer may be live and the next destructive git step must
+ * not run. What is NOT negotiable is that it must not throw -- proper-lockfile invokes it from
+ * inside the refresh timer, so a throw is an uncaught exception that kills the process.
  */
 export type OnLockCompromised = (err: Error) => void;
 /**
- * Acquire a cross-process filesystem lock for content provisioning.
+ * Acquire a cross-process filesystem lock for content provisioning. Returns a release function —
+ * always call it in a `finally`.
  *
- * In-memory locks only serialize work within a single process. Build tools such
- * as Next.js static generation provision content from parallel worker
- * *processes*, so two processes can otherwise race while creating the same git
- * workspace (e.g. "cannot mkdir remote.git: File exists" or "destination path
- * already exists"). proper-lockfile uses an atomic on-disk lock that holds across
- * processes, so only one provisions a given resource at a time while the others
- * wait and then find it already done.
+ * In-memory locks serialize only within one process, but build tools such as Next.js static
+ * generation provision content from parallel worker *processes*, which then race while creating
+ * the same git workspace ("cannot mkdir remote.git: File exists", "destination path already
+ * exists"). proper-lockfile's atomic on-disk lock holds across processes, so one provisions while
+ * the others wait and then find it already done.
  *
- * Returns a release function — always call it in a `finally`.
- *
- * @param lockTargetDir directory the lock marker lives in (created if missing)
- * @param lockName name of the on-disk lock marker, created inside lockTargetDir
  * @param onCompromised see {@link OnLockCompromised}; defaults to log-and-continue
  */
 export declare function acquireProvisioningLock(lockTargetDir: string, lockName: string, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;
 /**
- * Zero-retry variant of {@link acquireProvisioningLock}, for admin actions
- * running inside a synchronous request/response cycle (e.g. a Lambda-backed
- * API handler). `acquireProvisioningLock`'s ~600-retry budget waits minutes
- * for a live provisioner to finish; an admin request must fail fast on
- * contention instead (409 immediately) rather than hang the request for that
- * long.
+ * Zero-retry variant of {@link acquireProvisioningLock}, for admin actions inside a synchronous
+ * request/response cycle (a Lambda-backed API handler). `acquireProvisioningLock`'s ~600-retry
+ * budget waits minutes for a live provisioner; an admin request must fail fast instead.
  *
- * `stale: 30_000` is unchanged from the patient variant: a genuinely stale
- * lock (holder crashed more than 30s ago) is still taken over normally --
- * this only removes the RETRY loop for live contention, not the staleness
- * recovery a caller depends on (see branch-health.ts's [H1] freshness rail,
- * which reads this same lock's mtime to decide whether it is fresh or
- * stale before an admin purge/repair proceeds).
+ * `stale: 30_000` is unchanged from the patient variant: a genuinely stale lock (holder crashed
+ * more than 30s ago) is still taken over normally. Only the RETRY loop for live contention is
+ * removed, not the staleness recovery a caller depends on -- see branch-health.ts's [H1]
+ * freshness rail, which reads this lock's mtime before an admin purge/repair proceeds.
  *
- * Throws with `err.code === 'ELOCKED'` on contention (a live, non-stale
- * holder) -- callers should translate that into a 409.
+ * Throws with `err.code === 'ELOCKED'` on contention (a live, non-stale holder) -- callers
+ * translate that into a 409.
  */
 export declare function tryAcquireProvisioningLock(lockTargetDir: string, lockName: string, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;