canopycms 0.0.61-int.75 → 0.0.61

package/dist/utils/git.d.ts

@@ -18,6 +18,44 @@ import type { OperatingMode } from '../operating-mode';
  * `@`-required heuristic for scp-like syntax.
  */
 export declare function isNetworkRemoteUrl(url: string): boolean;
+/**
+ * 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.
+ *
+ * Deliberately narrow: ordinary transient push failures -- network drops,
+ * auth/permission denial, lock contention -- must keep retrying with backoff
+ * (see worker/cms-worker.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.
+ *
+ * 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.
+ */
+export declare function isNonFastForwardRejection(message: string): boolean;
+/**
+ * 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.
+ *
+ * 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`).
+ */
+export declare function isStaleLeaseRejection(message: string): boolean;
 /**
  * Detect the current HEAD branch name for a given repository root.
  * Returns the branch name, or the provided fallback (default 'main')

package/dist/utils/git.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/utils/git.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAmBtD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOvD;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAe,GACxB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,IAAI,EAAE,aAAa,CAAA;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAMlB"}
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/utils/git.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAmBtD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOvD;AAyBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAKlE;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAe,GACxB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,IAAI,EAAE,aAAa,CAAA;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAMlB"}

package/dist/utils/git.js

@@ -46,6 +46,75 @@ 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.
+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).
+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,
+// 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.
+ *
+ * Deliberately narrow: ordinary transient push failures -- network drops,
+ * auth/permission denial, lock contention -- must keep retrying with backoff
+ * (see worker/cms-worker.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.
+ *
+ * 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.
+ */
+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>`.
+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.
+ *
+ * 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`).
+ */
+export function isStaleLeaseRejection(message) {
+    return message.includes(REJECTED_MARKER) && message.includes(STALE_LEASE_REASON);
+}
 /**
  * Detect the current HEAD branch name for a given repository root.
  * Returns the branch name, or the provided fallback (default 'main')

package/dist/utils/git.js.map

@@ -1 +1 @@
-{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/utils/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAItC,wEAAwE;AACxE,MAAM,sBAAsB,GAAG,yBAAyB,CAAA;AACxD,6EAA6E;AAC7E,8EAA8E;AAC9E,6DAA6D;AAC7D,MAAM,wBAAwB,GAAG,uBAAuB,CAAA;AACxD,4EAA4E;AAC5E,4EAA4E;AAC5E,MAAM,sBAAsB,GAAG,IAAI,CAAA;AACnC,uEAAuE;AACvE,6EAA6E;AAC7E,8EAA8E;AAC9E,uEAAuE;AACvE,8BAA8B;AAC9B,MAAM,qBAAqB,GAAG,iBAAiB,CAAA;AAC/C,MAAM,0BAA0B,GAAG,aAAa,CAAA;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAA;IACzC,IAAI,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACjD,IAAI,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACnD,IAAI,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACjD,IAAI,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAA;IACjD,OAAO,0BAA0B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAgB,EAChB,WAAmB,MAAM;IAEzB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAA;QAC5C,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,QAAQ,CAAC,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAClE,OAAO,IAAI,IAAI,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAA;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAA;IACjB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAKvC;IACC,IAAI,OAAO,CAAC,iBAAiB;QAAE,OAAO,OAAO,CAAC,iBAAiB,CAAA;IAC/D,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QAC3B,OAAO,gBAAgB,CAAC,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;IAC9D,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/utils/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAItC,wEAAwE;AACxE,MAAM,sBAAsB,GAAG,yBAAyB,CAAA;AACxD,6EAA6E;AAC7E,8EAA8E;AAC9E,6DAA6D;AAC7D,MAAM,wBAAwB,GAAG,uBAAuB,CAAA;AACxD,4EAA4E;AAC5E,4EAA4E;AAC5E,MAAM,sBAAsB,GAAG,IAAI,CAAA;AACnC,uEAAuE;AACvE,6EAA6E;AAC7E,8EAA8E;AAC9E,uEAAuE;AACvE,8BAA8B;AAC9B,MAAM,qBAAqB,GAAG,iBAAiB,CAAA;AAC/C,MAAM,0BAA0B,GAAG,aAAa,CAAA;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAA;IACzC,IAAI,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACjD,IAAI,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACnD,IAAI,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACjD,IAAI,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAA;IACjD,OAAO,0BAA0B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC7C,CAAC;AAED,4EAA4E;AAC5E,8EAA8E;AAC9E,wEAAwE;AACxE,sEAAsE;AACtE,8EAA8E;AAC9E,+DAA+D;AAC/D,8EAA8E;AAC9E,4EAA4E;AAC5E,wCAAwC;AACxC,MAAM,eAAe,GAAG,YAAY,CAAA;AACpC,8EAA8E;AAC9E,kEAAkE;AAClE,8EAA8E;AAC9E,0EAA0E;AAC1E,0EAA0E;AAC1E,oEAAoE;AACpE,MAAM,wBAAwB,GAAG,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAA;AACpE,wEAAwE;AACxE,yEAAyE;AACzE,sEAAsE;AACtE,6CAA6C;AAC7C,MAAM,cAAc,GAAG,+BAA+B,CAAA;AAEtD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAe;IACvD,MAAM,0BAA0B,GAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;QACjC,wBAAwB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAA;IACrE,OAAO,0BAA0B,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAA;AACvE,CAAC;AAED,4EAA4E;AAC5E,wCAAwC;AACxC,MAAM,kBAAkB,GAAG,YAAY,CAAA;AAEvC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,OAAO,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAA;AAClF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAgB,EAChB,WAAmB,MAAM;IAEzB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAA;QAC5C,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,QAAQ,CAAC,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAClE,OAAO,IAAI,IAAI,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAA;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAA;IACjB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAKvC;IACC,IAAI,OAAO,CAAC,iBAAiB;QAAE,OAAO,OAAO,CAAC,iBAAiB,CAAA;IAC/D,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QAC3B,OAAO,gBAAgB,CAAC,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;IAC9D,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+/** The three levels the shared modules use. Structurally satisfied by `console`. */
+export interface CanopyLogger {
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/**
+ * Route subsequent `canopyLog*` calls through `logger`. Idempotent, and safe to
+ * 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. */
+export declare function resetCanopyLogger(): void;
+/** The logger currently installed. Exported for assertions; prefer the helpers below. */
+export declare function getCanopyLogger(): CanopyLogger;
+/** Informational. Routes to stdout (or the worker's timestamped stdout). */
+export declare function canopyLog(...args: unknown[]): void;
+/** Recoverable problem - the caller carries on. Routes to stderr. */
+export declare function canopyLogWarn(...args: unknown[]): void;
+/** Failure worth alerting on. Routes to stderr. */
+export declare function canopyLogError(...args: unknown[]): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC7B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CAChC;AAWD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAE1D;AAED,qGAAqG;AACrG,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,yFAAyF;AACzF,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAElD;AAED,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAEtD;AAED,mDAAmD;AACnD,wBAAgB,cAAc,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAEvD"}

package/dist/utils/logger.js

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+let active = console;
+/**
+ * Route subsequent `canopyLog*` calls through `logger`. Idempotent, and safe to
+ * call after the modules that use the helpers have already been imported.
+ */
+export function setCanopyLogger(logger) {
+    active = logger;
+}
+/** Restore the default (`console`). Exists for tests; production installs once and never reverts. */
+export function resetCanopyLogger() {
+    active = console;
+}
+/** The logger currently installed. Exported for assertions; prefer the helpers below. */
+export function getCanopyLogger() {
+    return active;
+}
+/** Informational. Routes to stdout (or the worker's timestamped stdout). */
+export function canopyLog(...args) {
+    active.log(...args);
+}
+/** Recoverable problem - the caller carries on. Routes to stderr. */
+export function canopyLogWarn(...args) {
+    active.warn(...args);
+}
+/** Failure worth alerting on. Routes to stderr. */
+export function canopyLogError(...args) {
+    active.error(...args);
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AASH;;;;;;GAMG;AACH,IAAI,MAAM,GAAiB,OAAO,CAAA;AAElC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAoB;IAClD,MAAM,GAAG,MAAM,CAAA;AACjB,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,iBAAiB;IAC/B,MAAM,GAAG,OAAO,CAAA;AAClB,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,eAAe;IAC7B,OAAO,MAAM,CAAA;AACf,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,SAAS,CAAC,GAAG,IAAe;IAC1C,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAA;AACrB,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,aAAa,CAAC,GAAG,IAAe;IAC9C,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;AACtB,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,cAAc,CAAC,GAAG,IAAe;IAC/C,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAA;AACvB,CAAC"}

package/dist/validation/entry-type-reference-validator.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Validates that every reference field's `entryTypes` names an entry type that
+ * actually exists in the resolved schema.
+ *
+ * Without this, a typo (`entryTypes: ['parter']` for `'partner'`) is accepted
+ * silently and surfaces much later as a reference picker that returns zero
+ * results, with nothing pointing at the cause.
+ *
+ * This runs after schema resolution rather than at config-validation time on
+ * purpose: entry types are declared per-collection in `.collection.json` files
+ * on disk, so the set of valid names only exists once a branch's schema has
+ * been resolved. `config/validation.ts`'s `ensureReferenceFieldsHaveScope` runs
+ * at entry-schema *registration* (entry-schema-registry.ts), before any branch
+ * schema exists, and so cannot perform this check.
+ */
+import type { RootCollectionConfig } from '../config';
+/**
+ * Collect every entry type name defined anywhere in the schema.
+ *
+ * Entry types are scoped per collection, and the same name may legitimately
+ * appear in several collections, so this is a flat set of names: a reference
+ * field's `entryTypes` is matched against entries across all collections
+ * (see reference-resolver.ts, which filters resolved entries by entry type name
+ * without regard to which collection defined it).
+ */
+export declare const collectEntryTypeNames: (schema: RootCollectionConfig) => Set<string>;
+/**
+ * Check every reference field's `entryTypes` against the schema's entry types.
+ *
+ * @returns One human-readable message per offending value; empty when valid.
+ */
+export declare const validateReferenceEntryTypes: (schema: RootCollectionConfig) => string[];
+//# sourceMappingURL=entry-type-reference-validator.d.ts.map

package/dist/validation/entry-type-reference-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-type-reference-validator.d.ts","sourceRoot":"","sources":["../../src/validation/entry-type-reference-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAqC,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAyDxF;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,oBAAoB,KAAG,GAAG,CAAC,MAAM,CAQ9E,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,GAAI,QAAQ,oBAAoB,KAAG,MAAM,EA8BhF,CAAA"}

package/dist/validation/entry-type-reference-validator.js

@@ -0,0 +1,110 @@
+/**
+ * Validates that every reference field's `entryTypes` names an entry type that
+ * actually exists in the resolved schema.
+ *
+ * Without this, a typo (`entryTypes: ['parter']` for `'partner'`) is accepted
+ * silently and surfaces much later as a reference picker that returns zero
+ * results, with nothing pointing at the cause.
+ *
+ * This runs after schema resolution rather than at config-validation time on
+ * purpose: entry types are declared per-collection in `.collection.json` files
+ * on disk, so the set of valid names only exists once a branch's schema has
+ * been resolved. `config/validation.ts`'s `ensureReferenceFieldsHaveScope` runs
+ * at entry-schema *registration* (entry-schema-registry.ts), before any branch
+ * schema exists, and so cannot perform this check.
+ */
+import { forEachReferenceField } from '../config/validation.js';
+/**
+ * Levenshtein edit distance, bounded use only (short identifier strings).
+ * Kept local and tiny rather than pulling in a runtime dependency purely to
+ * produce a "did you mean" hint in an error message.
+ */
+const editDistance = (a, b) => {
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const curr = [i];
+        for (let j = 1; j <= b.length; j++) {
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = curr;
+    }
+    return prev[b.length];
+};
+/** Closest known name within a small edit distance, if there is one. */
+const closestName = (name, known) => {
+    let best;
+    let bestDistance = Infinity;
+    for (const candidate of known) {
+        const distance = editDistance(name.toLowerCase(), candidate.toLowerCase());
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    // Allow a little more slack for longer names, but never suggest something
+    // that shares almost nothing with what was written.
+    const threshold = Math.max(2, Math.floor(name.length / 3));
+    return best !== undefined && bestDistance <= threshold ? best : undefined;
+};
+/** Walk the collection tree, visiting every entry type with its collection path. */
+const forEachEntryType = (schema, visit) => {
+    const walk = (node, nodePath) => {
+        for (const entryType of node.entries ?? []) {
+            visit(entryType, nodePath);
+        }
+        for (const child of node.collections ?? []) {
+            walk(child, child.path ?? (nodePath ? `${nodePath}/${child.name}` : child.name));
+        }
+    };
+    walk(schema, '');
+};
+/**
+ * Collect every entry type name defined anywhere in the schema.
+ *
+ * Entry types are scoped per collection, and the same name may legitimately
+ * appear in several collections, so this is a flat set of names: a reference
+ * field's `entryTypes` is matched against entries across all collections
+ * (see reference-resolver.ts, which filters resolved entries by entry type name
+ * without regard to which collection defined it).
+ */
+export const collectEntryTypeNames = (schema) => {
+    const names = new Set();
+    forEachEntryType(schema, (entryType) => {
+        if (typeof entryType.name === 'string' && entryType.name.length > 0) {
+            names.add(entryType.name);
+        }
+    });
+    return names;
+};
+/**
+ * Check every reference field's `entryTypes` against the schema's entry types.
+ *
+ * @returns One human-readable message per offending value; empty when valid.
+ */
+export const validateReferenceEntryTypes = (schema) => {
+    const known = collectEntryTypeNames(schema);
+    const knownList = [...known].sort();
+    const issues = [];
+    forEachEntryType(schema, (entryType, collectionPath) => {
+        const location = collectionPath ? `${collectionPath}/${entryType.name}` : entryType.name;
+        forEachReferenceField(entryType.schema, (field) => {
+            const entryTypes = field.entryTypes;
+            if (!Array.isArray(entryTypes))
+                return;
+            const fieldName = typeof field.name === 'string' ? field.name : 'unknown';
+            for (const value of entryTypes) {
+                if (typeof value !== 'string' || known.has(value))
+                    continue;
+                const suggestion = closestName(value, knownList);
+                issues.push(`Reference field "${fieldName}" in "${location}" specifies entryType ` +
+                    `"${value}", which is not defined in any collection.` +
+                    (suggestion ? ` Did you mean "${suggestion}"?` : '') +
+                    (knownList.length > 0
+                        ? ` Known entry types: ${knownList.join(', ')}.`
+                        : ' No entry types are defined in this schema.'));
+            }
+        });
+    });
+    return issues;
+};
+//# sourceMappingURL=entry-type-reference-validator.js.map

package/dist/validation/entry-type-reference-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-type-reference-validator.js","sourceRoot":"","sources":["../../src/validation/entry-type-reference-validator.ts"],"names":[],"mappings":"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"}