canopycms 0.0.67-int.90 → 0.0.67

package/dist/operating-mode/deployment-name.js

@@ -1,54 +1,41 @@
 /**
- * Single resolution point for `deploymentName`.
+ * Single resolution point for `deploymentName`, which namespaces the settings
+ * branch (`canopycms-settings-{deploymentName}`) so two CanopyCMS deployments
+ * can share one GitHub repo without fighting over the same orphan branch.
  *
- * `deploymentName` namespaces the settings branch
- * (`canopycms-settings-{deploymentName}`) so two CanopyCMS deployments can
- * share one GitHub repo without both resolving to `canopycms-settings-prod`
- * and fighting over the same orphan branch.
+ * Precedence: `process.env.CANOPYCMS_DEPLOYMENT_NAME` (trimmed, empty ignored),
+ * then `config.deploymentName`, then `modeDefault` (the caller's mode-specific
+ * fallback, e.g. 'prod'/'local').
  *
- * Precedence (highest wins):
- *   1. `process.env.CANOPYCMS_DEPLOYMENT_NAME` (trimmed; empty string ignored)
- *   2. `config.deploymentName`
- *   3. `modeDefault` (the caller's mode-specific fallback, e.g. 'prod'/'local')
- *
- * Env wins over config DELIBERATELY. The env var is stamped per-stack by
- * infrastructure (CDK's `CanopyCmsServiceProps.deploymentName` ->
- * `CANOPYCMS_DEPLOYMENT_NAME`), so it is the value GUARANTEED TO DIFFER
- * between two deployments sharing a repo. `config.deploymentName` lives in
- * the shared repo's `canopycms.config.ts`, so it is the value GUARANTEED TO
- * BE IDENTICAL across both deployments (both Lambdas run the same checked-out
- * config). If config won instead, an adopter who already wrote
- * `deploymentName` into their shared config would find the CDK
- * `deploymentName` prop silently doing nothing — exactly the two-stacks-one-repo
- * case this feature exists to fix.
+ * Env wins over config DELIBERATELY. Infrastructure stamps the env var
+ * per-stack (CDK's `CanopyCmsServiceProps.deploymentName`), so it is the value
+ * GUARANTEED TO DIFFER between two deployments sharing a repo, while
+ * `config.deploymentName` lives in the shared repo's `canopycms.config.ts` and
+ * is GUARANTEED TO BE IDENTICAL across both. If config won, an adopter who had
+ * already written `deploymentName` into their shared config would find the CDK
+ * prop silently doing nothing — the two-stacks-one-repo case this exists to fix.
  */
 import { canopyLogWarn } from '../utils/logger.js';
 let warned = false;
 /**
  * Conservative charset for a deployment name. The resolved value is
  * interpolated straight into a git ref (`canopycms-settings-{name}`), and the
- * env var route bypasses the config schema entirely — nothing else validates
- * an infra-stamped value before it becomes a branch name. Rejecting anything
- * outside this set keeps the result a single, well-formed ref component:
- * no `/` (would add a ref hierarchy level and break sanitizeBranchName
- * round-trips), no whitespace, no `..`/`~`/`^`/`:` (git-forbidden), no
- * leading `-` (would parse as a git option).
- *
- * The charset alone is not sufficient: `..`, a trailing `.`, and a `.lock`
- * suffix are all built from allowed characters but are still rejected by
- * git's own ref rules (git-check-ref-format), so they are excluded separately.
+ * env var route bypasses the config schema entirely — nothing else validates an
+ * infra-stamped value before it becomes a branch name. So the result must stay
+ * a single well-formed ref component: no `/` (would add a ref hierarchy level
+ * and break sanitizeBranchName round-trips), no whitespace, no `..`/`~`/`^`/`:`
+ * (git-forbidden), no leading `-` (would parse as a git option). `..`, a
+ * trailing `.` and a `.lock` suffix are built from allowed characters but are
+ * still rejected by git-check-ref-format, so they are excluded separately below.
  */
 const VALID_DEPLOYMENT_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 /**
- * Exported so `canopycms-cdk`'s suite can assert that its own synth-time copy
- * of this rule (constructs/cms-service.ts) still agrees with this one. The
- * construct deliberately does not import this directly — see
- * `isValidDeploymentName`'s doc comment in cms-service.ts for the real reason
- * (not, as this comment used to say, that the published construct lacks a
- * runtime dependency on `canopycms` — it doesn't: `canopycms` is a
- * non-optional peerDependency there, and the package's own main entry already
- * imports it at runtime). The drift check is therefore test-only — see
- * `deployment-name-fixtures.ts`.
+ * Exported so `canopycms-cdk`'s suite can assert that its own synth-time copy of
+ * this rule (constructs/cms-service.ts) still agrees with this one. The
+ * construct deliberately does not import this directly — see its own
+ * `isValidDeploymentName` doc comment. The drift check is therefore test-only,
+ * over `deployment-name-fixtures.ts`.
+ * @internal Exported for tests.
  */
 export const isValidDeploymentName = (name) => VALID_DEPLOYMENT_NAME.test(name) &&
     !name.includes('..') &&
@@ -58,14 +45,9 @@ export function resolveDeploymentName(config, modeDefault) {
     const envValue = process.env.CANOPYCMS_DEPLOYMENT_NAME?.trim();
     const configValue = config.deploymentName;
     if (envValue && configValue && envValue !== configValue && !warned) {
-        // canopyLogWarn, not console.warn: cms-worker.ts imports this module and
-        // resolves through it inside start(), so this line lands in worker.log,
-        // where an unprefixed line is folded into the previous CloudWatch event.
-        // The mismatch this reports is exactly what an operator would be grepping
-        // for. Plain console under Lambda/dev, as everywhere else. See
-        // utils/logger.ts. (Missed by the worker-log sweep, which went by directory
-        // name and by the modules the finding named, rather than by the worker's
-        // real import graph.)
+        // canopyLogWarn, not console.warn: cms-worker.ts resolves through this
+        // inside start(), so the line lands in worker.log, where an unprefixed line
+        // is folded into the previous CloudWatch event (utils/logger.ts).
         canopyLogWarn(`CanopyCMS: CANOPYCMS_DEPLOYMENT_NAME ("${envValue}") differs from config.deploymentName ` +
             `("${configValue}") — using the env var (infra-stamped env wins over shared-repo config ` +
             `by design; see resolveDeploymentName's doc comment). Update config.deploymentName to ` +

package/dist/operating-mode/index.d.ts

@@ -1,32 +1,11 @@
 /**
- * Operating Mode Strategy Pattern - Public API
- *
- * Two-layer architecture:
- * 1. Client-safe strategies - safe for 'use client' React components (no Node.js imports)
- * 2. Client-unsafe strategies - full server-side functionality (uses fs, path, process)
- *
- * Usage:
- *
- * Client components:
- *   import { clientOperatingStrategy } from '@/operating-mode'
- *   const strategy = clientOperatingStrategy(mode)
- *   if (strategy.supportsBranching()) { ... }
- *
- * Server code:
- *   import { operatingStrategy } from '@/operating-mode'
- *   const strategy = operatingStrategy(mode)
- *   // contentRoot is REQUIRED: pass config.contentRoot (falling back to 'content'
- *   // at the call site), never a bare call — see getContentRoot's doc comment in
- *   // types.ts for why a default here would silently disarm a caller.
- *   const contentRoot = strategy.getContentRoot(config.contentRoot ?? 'content')
- *   const branchesRoot = strategy.getContentBranchesRoot()
- *   const branchRoot = strategy.getContentBranchRoot('my-branch')
- *   const settingsRoot = strategy.getSettingsRoot()
- *   if (strategy.supportsBranching()) { ... } // can also use client-safe methods
+ * Operating mode strategies, in two layers: client-safe ones carry no Node.js
+ * imports and are usable from 'use client' components; client-unsafe ones add
+ * the server-side surface (fs, path, process) and must stay off the client.
  */
 export { clientOperatingStrategy, clearClientStrategyCache } from './client-safe-strategy.js';
 export { operatingStrategy, clearStrategyCache } from './client-unsafe-strategy.js';
 export { resolveDeploymentName, isValidDeploymentName } from './deployment-name.js';
-export { resolveOperatingMode, SERVER_MODE_ENV_VAR, BROWSER_MODE_ENV_VAR } from './mode-env.js';
+export { resolveOperatingMode } from './mode-env.js';
 export type OperatingMode = 'prod' | 'dev';
 export type { ClientSafeStrategy, ClientUnsafeStrategy, ResolveRemoteUrlOptions } from './types.js';

package/dist/operating-mode/index.js

@@ -1,36 +1,14 @@
 /**
- * Operating Mode Strategy Pattern - Public API
- *
- * Two-layer architecture:
- * 1. Client-safe strategies - safe for 'use client' React components (no Node.js imports)
- * 2. Client-unsafe strategies - full server-side functionality (uses fs, path, process)
- *
- * Usage:
- *
- * Client components:
- *   import { clientOperatingStrategy } from '@/operating-mode'
- *   const strategy = clientOperatingStrategy(mode)
- *   if (strategy.supportsBranching()) { ... }
- *
- * Server code:
- *   import { operatingStrategy } from '@/operating-mode'
- *   const strategy = operatingStrategy(mode)
- *   // contentRoot is REQUIRED: pass config.contentRoot (falling back to 'content'
- *   // at the call site), never a bare call — see getContentRoot's doc comment in
- *   // types.ts for why a default here would silently disarm a caller.
- *   const contentRoot = strategy.getContentRoot(config.contentRoot ?? 'content')
- *   const branchesRoot = strategy.getContentBranchesRoot()
- *   const branchRoot = strategy.getContentBranchRoot('my-branch')
- *   const settingsRoot = strategy.getSettingsRoot()
- *   if (strategy.supportsBranching()) { ... } // can also use client-safe methods
+ * Operating mode strategies, in two layers: client-safe ones carry no Node.js
+ * imports and are usable from 'use client' components; client-unsafe ones add
+ * the server-side surface (fs, path, process) and must stay off the client.
  */
-// Client-safe factory and strategy (safe for client bundles)
 export { clientOperatingStrategy, clearClientStrategyCache } from './client-safe-strategy.js';
-// Client-unsafe factory and strategy (server-side only)
+// Server-side only.
 export { operatingStrategy, clearStrategyCache } from './client-unsafe-strategy.js';
-// Single resolution point for deploymentName (env > config > mode default) —
-// server-only (reads process.env), used by the strategies' getSettingsBranchName.
+// Single resolution point for deploymentName — server-only (reads process.env),
+// used by the strategies' getSettingsBranchName.
 export { resolveDeploymentName, isValidDeploymentName } from './deployment-name.js';
-// Single resolution point for `mode` (env > config.mode) — isomorphic, applied
-// inside validateCanopyConfig so every config-authoring path gets it.
-export { resolveOperatingMode, SERVER_MODE_ENV_VAR, BROWSER_MODE_ENV_VAR } from './mode-env.js';
+// Single resolution point for `mode` — isomorphic, applied inside
+// validateCanopyConfig so every config-authoring path gets it.
+export { resolveOperatingMode } from './mode-env.js';

package/dist/operating-mode/mode-env.d.ts

@@ -1,62 +1,40 @@
 /**
- * Single resolution point for the operating `mode`.
- *
- * `mode` is required in `canopycms.config.ts` (SEC-C1) and that file lives in
- * the adopter's repo — the SAME file is loaded by `next dev` locally, by
- * `next build` inside the image builder, and by the deployed Lambda. Those
- * three want different answers, so a literal in the config file cannot be
- * right for all of them:
- *
- *   - `next dev` must be `dev` (workspace at `<cwd>/.canopy-dev`).
- *   - `next build` should stay `dev` too. Build-time reads come from the
- *     working tree in either mode (`readsFromCheckout` in `build-mode.ts`), so
- *     nothing in a build needs prod, while prod mode would hold the image
- *     builder to checks it has no reason to meet: `gitBotAuthorName`/
- *     `gitBotAuthorEmail` (the prod strategy's `validateConfig`, run by
- *     `createCanopyServices`) and an auth plugin that verifies credentials
- *     (`assertAuthPluginAllowedForMode`). See the note in
- *     `cli/template-files/Dockerfile.cms.template`.
- *   - The deployed Lambda must be `prod`: dev mode resolves the workspace to
- *     `<cwd>/.canopy-dev`, and Lambda's filesystem is read-only outside /tmp,
- *     so the first write fails with EROFS.
- *
- * Only a value resolved at RUN time can satisfy all three, which is why this
- * is an environment override rather than a flag baked into the generated
- * config file. `CANOPY_MODE` is the name the deployment templates already
- * referred to; before this module existed nothing read it.
- *
- * Precedence (highest wins):
- *   1. the environment value for the current runtime (see `readModeEnv`)
- *   2. `config.mode` (the literal in `canopycms.config.ts`)
- *
- * ## Two variable names, on purpose
- *
- * Server code reads `CANOPY_MODE`, which the CDK construct stamps onto the
- * Lambda (`CanopyCmsService` sets `CANOPY_MODE=prod`). It is deliberately NOT
- * set during `next build` (see above).
- *
- * Browser code cannot read a runtime environment at all — the editor page
- * imports `canopycms.config.ts` directly (`config.client()`), so the browser's
- * copy of `mode` is whatever was inlined when the bundle was built. Next.js
- * only inlines `NEXT_PUBLIC_*`, so the browser reads
- * `NEXT_PUBLIC_CANOPY_MODE`, which the generated CDK stack passes as a Docker
- * build arg. Both names must be spelled as literal `process.env.X` member
- * expressions here or the bundler cannot substitute them.
- *
- * An unrecognized value throws rather than falling back. Falling back would
+ * Single resolution point for the operating `mode`: the environment value for
+ * the current runtime wins (see `readModeEnv`), else `config.mode`.
+ *
+ * One `canopycms.config.ts` (where `mode` is required, SEC-C1) is loaded by
+ * `next dev`, by `next build` in the image builder and by the deployed Lambda,
+ * and those three need different answers, so only a RUN-time value works:
+ *   - `next dev` and `next build` are both `dev`. Build-time reads come from
+ *     the working tree in either mode (`readsFromCheckout` in build-mode.ts),
+ *     while prod would hold the image builder to checks it has no reason to
+ *     meet: `gitBotAuthorName`/`gitBotAuthorEmail` (the prod strategy's
+ *     `validateConfig`) and a credential-verifying auth plugin
+ *     (`assertAuthPluginAllowedForMode`). See Dockerfile.cms.template.
+ *   - The Lambda is `prod`: dev resolves the workspace to `<cwd>/.canopy-dev`,
+ *     and Lambda's filesystem is read-only outside /tmp, so the first write
+ *     fails with EROFS.
+ *
+ * Two variable names, on purpose. Server code reads `CANOPY_MODE`, stamped on
+ * the Lambda by `CanopyCmsService` and deliberately NOT set during
+ * `next build`. Browser code has no runtime environment — the editor page
+ * imports the config directly (`config.client()`), so its `mode` is whatever
+ * was inlined at build time, and Next inlines only `NEXT_PUBLIC_*`. Both names
+ * MUST appear as literal `process.env.X` member expressions here or the
+ * bundler cannot substitute them.
+ *
+ * An unrecognized value throws rather than falling back: falling back would
  * turn a typo (`CANOPY_MODE=production`) into a silent dev-mode deployment
- * running header-trusting dev auth semantics — the exact failure SEC-C1 made
- * `mode` required to prevent.
+ * running header-trusting dev auth semantics.
  */
 import type { OperatingMode } from './types.js';
-export declare const SERVER_MODE_ENV_VAR = "CANOPY_MODE";
-export declare const BROWSER_MODE_ENV_VAR = "NEXT_PUBLIC_CANOPY_MODE";
-/** Reset the once-per-process warning latch. Test-only. */
+/**
+ * Reset the once-per-process warning latch. Test-only.
+ * @internal Exported for tests.
+ */
 export declare function resetModeWarning(): void;
 /**
- * Resolve the effective operating mode from the environment and the config
- * literal. Called from `validateCanopyConfig`, the one point every documented
- * config-authoring path (`defineCanopyConfig`, `composeCanopyConfig`) funnels
- * through.
+ * Called from `validateCanopyConfig`, the one point every config-authoring path
+ * (`defineCanopyConfig`, `composeCanopyConfig`) funnels through.
  */
 export declare function resolveOperatingMode(configMode: OperatingMode): OperatingMode;

package/dist/operating-mode/mode-env.js

@@ -1,67 +1,47 @@
 /**
- * Single resolution point for the operating `mode`.
+ * Single resolution point for the operating `mode`: the environment value for
+ * the current runtime wins (see `readModeEnv`), else `config.mode`.
  *
- * `mode` is required in `canopycms.config.ts` (SEC-C1) and that file lives in
- * the adopter's repo — the SAME file is loaded by `next dev` locally, by
- * `next build` inside the image builder, and by the deployed Lambda. Those
- * three want different answers, so a literal in the config file cannot be
- * right for all of them:
+ * One `canopycms.config.ts` (where `mode` is required, SEC-C1) is loaded by
+ * `next dev`, by `next build` in the image builder and by the deployed Lambda,
+ * and those three need different answers, so only a RUN-time value works:
+ *   - `next dev` and `next build` are both `dev`. Build-time reads come from
+ *     the working tree in either mode (`readsFromCheckout` in build-mode.ts),
+ *     while prod would hold the image builder to checks it has no reason to
+ *     meet: `gitBotAuthorName`/`gitBotAuthorEmail` (the prod strategy's
+ *     `validateConfig`) and a credential-verifying auth plugin
+ *     (`assertAuthPluginAllowedForMode`). See Dockerfile.cms.template.
+ *   - The Lambda is `prod`: dev resolves the workspace to `<cwd>/.canopy-dev`,
+ *     and Lambda's filesystem is read-only outside /tmp, so the first write
+ *     fails with EROFS.
  *
- *   - `next dev` must be `dev` (workspace at `<cwd>/.canopy-dev`).
- *   - `next build` should stay `dev` too. Build-time reads come from the
- *     working tree in either mode (`readsFromCheckout` in `build-mode.ts`), so
- *     nothing in a build needs prod, while prod mode would hold the image
- *     builder to checks it has no reason to meet: `gitBotAuthorName`/
- *     `gitBotAuthorEmail` (the prod strategy's `validateConfig`, run by
- *     `createCanopyServices`) and an auth plugin that verifies credentials
- *     (`assertAuthPluginAllowedForMode`). See the note in
- *     `cli/template-files/Dockerfile.cms.template`.
- *   - The deployed Lambda must be `prod`: dev mode resolves the workspace to
- *     `<cwd>/.canopy-dev`, and Lambda's filesystem is read-only outside /tmp,
- *     so the first write fails with EROFS.
+ * Two variable names, on purpose. Server code reads `CANOPY_MODE`, stamped on
+ * the Lambda by `CanopyCmsService` and deliberately NOT set during
+ * `next build`. Browser code has no runtime environment — the editor page
+ * imports the config directly (`config.client()`), so its `mode` is whatever
+ * was inlined at build time, and Next inlines only `NEXT_PUBLIC_*`. Both names
+ * MUST appear as literal `process.env.X` member expressions here or the
+ * bundler cannot substitute them.
  *
- * Only a value resolved at RUN time can satisfy all three, which is why this
- * is an environment override rather than a flag baked into the generated
- * config file. `CANOPY_MODE` is the name the deployment templates already
- * referred to; before this module existed nothing read it.
- *
- * Precedence (highest wins):
- *   1. the environment value for the current runtime (see `readModeEnv`)
- *   2. `config.mode` (the literal in `canopycms.config.ts`)
- *
- * ## Two variable names, on purpose
- *
- * Server code reads `CANOPY_MODE`, which the CDK construct stamps onto the
- * Lambda (`CanopyCmsService` sets `CANOPY_MODE=prod`). It is deliberately NOT
- * set during `next build` (see above).
- *
- * Browser code cannot read a runtime environment at all — the editor page
- * imports `canopycms.config.ts` directly (`config.client()`), so the browser's
- * copy of `mode` is whatever was inlined when the bundle was built. Next.js
- * only inlines `NEXT_PUBLIC_*`, so the browser reads
- * `NEXT_PUBLIC_CANOPY_MODE`, which the generated CDK stack passes as a Docker
- * build arg. Both names must be spelled as literal `process.env.X` member
- * expressions here or the bundler cannot substitute them.
- *
- * An unrecognized value throws rather than falling back. Falling back would
+ * An unrecognized value throws rather than falling back: falling back would
  * turn a typo (`CANOPY_MODE=production`) into a silent dev-mode deployment
- * running header-trusting dev auth semantics — the exact failure SEC-C1 made
- * `mode` required to prevent.
+ * running header-trusting dev auth semantics.
  */
 import { canopyLogWarn } from '../utils/logger.js';
-export const SERVER_MODE_ENV_VAR = 'CANOPY_MODE';
-export const BROWSER_MODE_ENV_VAR = 'NEXT_PUBLIC_CANOPY_MODE';
+const SERVER_MODE_ENV_VAR = 'CANOPY_MODE';
+const BROWSER_MODE_ENV_VAR = 'NEXT_PUBLIC_CANOPY_MODE';
 let warned = false;
-/** Reset the once-per-process warning latch. Test-only. */
+/**
+ * Reset the once-per-process warning latch. Test-only.
+ * @internal Exported for tests.
+ */
 export function resetModeWarning() {
     warned = false;
 }
 /**
- * The environment value for the current runtime, or undefined when unset.
- *
  * Guarded with `typeof process` because a non-Next bundler may leave no
- * `process` shim in the browser at all; the member expressions themselves stay
- * literal so Next's DefinePlugin substitution still applies.
+ * `process` shim in the browser; the member expressions stay literal so Next's
+ * DefinePlugin substitution still applies.
  */
 function readModeEnv() {
     if (typeof process === 'undefined' || typeof process.env === 'undefined')
@@ -73,10 +53,8 @@ function readModeEnv() {
     return value ? { name, value } : undefined;
 }
 /**
- * Resolve the effective operating mode from the environment and the config
- * literal. Called from `validateCanopyConfig`, the one point every documented
- * config-authoring path (`defineCanopyConfig`, `composeCanopyConfig`) funnels
- * through.
+ * Called from `validateCanopyConfig`, the one point every config-authoring path
+ * (`defineCanopyConfig`, `composeCanopyConfig`) funnels through.
  */
 export function resolveOperatingMode(configMode) {
     const env = readModeEnv();
@@ -88,9 +66,9 @@ export function resolveOperatingMode(configMode) {
             `(${JSON.stringify(configMode)}): a typo here would silently deploy dev auth semantics.`);
     }
     if (env.value !== configMode && !warned) {
-        // canopyLogWarn, not console.warn: shared modules can run inside the
-        // worker daemon, where an unprefixed line is folded into the previous
-        // CloudWatch event (see utils/logger.ts).
+        // canopyLogWarn, not console.warn: shared modules can run inside the worker
+        // daemon, where an unprefixed line is folded into the previous CloudWatch
+        // event (utils/logger.ts).
         canopyLogWarn(`CanopyCMS: ${env.name}="${env.value}" overrides config.mode="${configMode}". ` +
             `The environment wins by design — it is the per-deployment value, while ` +
             `canopycms.config.ts is shared by local dev, the image build and the deployment. ` +

package/dist/operating-mode/types.d.ts

@@ -1,16 +1,8 @@
-/**
- * Operating Mode Strategy Types
- *
- * This module defines the two-layer strategy pattern for operating modes:
- * - ClientSafeStrategy: Methods safe for client-side bundles (no Node.js APIs)
- * - ClientUnsafeStrategy: Full strategy with Node.js APIs (server-side only)
- */
+/** Operating-mode strategy types. */
 import type { OperatingMode as OM } from './index.js';
 import type { CanopyConfig } from '../config/index.js';
 export type OperatingMode = OM;
-/**
- * Options for resolving git remote URL
- */
+/** @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md. */
 export interface ResolveRemoteUrlOptions {
     mode: OperatingMode;
     remoteUrl?: string;
@@ -18,41 +10,29 @@ export interface ResolveRemoteUrlOptions {
     baseBranch?: string;
     sourceRoot?: string;
 }
-/**
- * Configuration for remote URL resolution
- * Strategies return this data; GitManager executes the logic
- */
+/** Strategies return this data; GitManager executes the logic. */
 export interface RemoteUrlConfig {
-    /** Whether to auto-initialize a local remote */
     shouldAutoInitLocal: boolean;
     /** Default path for local remote (e.g., '.canopycms/remote.git') */
     defaultRemotePath: string;
-    /** Environment variable name for remote URL */
     envVarName: string;
     /**
-     * Absolute path to check for auto-detection of a pre-existing local remote.
-     * If this path exists on disk, it's used as the remote URL (file:// protocol).
-     * Used in prod mode where the EC2 worker creates remote.git on EFS.
-     * Unlike shouldAutoInitLocal, this does NOT create the remote — just detects it.
+     * If this absolute path exists on disk it becomes the remote URL (file://).
+     * Set in prod, where the EC2 worker creates remote.git on EFS. Unlike
+     * shouldAutoInitLocal, this only DETECTS a remote; it never creates one.
      */
     autoDetectRemotePath?: string;
 }
 /**
- * Client-Safe Strategy
- *
- * Methods that can be safely imported in 'use client' React components.
- * NO Node.js APIs (fs, path, process, etc.) - only pure logic and simple data.
+ * Methods safe to import in 'use client' React components: pure logic and
+ * simple data, NO Node.js APIs (fs, path, process).
  */
 export interface ClientSafeStrategy {
-    /** The operating mode this strategy represents */
     readonly mode: OperatingMode;
     /** Whether this mode supports multiple branch workspaces */
     supportsBranching(): boolean;
-    /** Whether to show status badge in UI */
     supportsStatusBadge(): boolean;
-    /** Whether comments/collaboration features are enabled */
     supportsComments(): boolean;
-    /** Whether pull request features are available */
     supportsPullRequests(): boolean;
     /** Get the permissions file name (e.g., 'permissions.json' or 'permissions.local.json') */
     getPermissionsFileName(): string;
@@ -63,80 +43,52 @@ export interface ClientSafeStrategy {
     /** Whether git pushes should be made in this mode */
     shouldPush(): boolean;
 }
-/**
- * Client-Unsafe Strategy
- *
- * Full strategy including Node.js APIs. Can only be imported server-side.
- * Extends ClientSafeStrategy, so all client-safe methods are available.
- */
+/** The full strategy, including Node.js APIs. Server-side imports only. */
 export interface ClientUnsafeStrategy extends ClientSafeStrategy {
     /**
-     * Get the root directory for this mode's workspace.
-     * All mode-specific subdirectories (content-branches, settings, .cache, etc.) live under this.
-     * - prod: CANOPYCMS_WORKSPACE_ROOT ?? /mnt/efs/workspace
-     * - dev: {sourceRoot ?? cwd}/.canopy-dev
+     * The mode's workspace root; content-branches, settings and .cache all live
+     * under it. prod: CANOPYCMS_WORKSPACE_ROOT ?? /mnt/efs/workspace.
+     * dev: {sourceRoot ?? cwd}/.canopy-dev.
      */
     getWorkspaceRoot(sourceRoot?: string): string;
     /**
-     * Get the content directory path (at project/workspace root).
-     * - dev: {sourceRoot ?? cwd}/{contentRoot}
-     * - prod (in workspaces): {sourceRoot ?? cwd}/{contentRoot}
+     * The content directory, `{sourceRoot ?? cwd}/{contentRoot}` in both modes.
      *
      * `contentRoot` is REQUIRED and must be the caller's already-resolved
      * `config.contentRoot` (falling back to 'content' at the call site, not here).
-     * A default here is deliberately not provided: this method used to hardcode
-     * the literal 'content', which silently disarmed callers configured with a
-     * non-default contentRoot (e.g. dev-content-watcher.ts's divergence watcher
-     * resolved a content directory that never existed, hit its existsSync guard,
-     * and permanently no-op'd — with no error, since a missing directory looks
-     * like "nothing to watch yet"). Making the parameter required means a future
-     * caller cannot silently reintroduce that bug by omitting it.
+     * Defaulting it here would silently disarm any caller configured with a
+     * non-default contentRoot: it would resolve a directory that never exists,
+     * and a missing content directory reads as "nothing to do" rather than as an
+     * error. Requiring the parameter makes that mistake impossible.
      */
     getContentRoot(contentRoot: string, sourceRoot?: string): string;
     /**
-     * Get the parent directory of all content branch workspaces (contains branches.json and branch directories).
-     * - dev: {cwd}/.canopy-dev/content-branches
-     * - prod: $CANOPYCMS_WORKSPACE_ROOT/content-branches or /mnt/efs/workspace/content-branches
+     * `{workspaceRoot}/content-branches`: the parent of every content branch
+     * workspace, and the home of branches.json.
      */
     getContentBranchesRoot(sourceRoot?: string): string;
-    /**
-     * Get individual content branch workspace directory.
-     * Returns: {contentBranchesRoot}/{branchName}
-     */
+    /** `{contentBranchesRoot}/{branchName}`. */
     getContentBranchRoot(branchName: string, sourceRoot?: string): string;
     /**
-     * Get the git exclude pattern for runtime metadata (e.g., '.canopy-meta/').
-     * Used by GitManager to add to .git/info/exclude in content branch workspaces.
+     * Runtime-metadata pattern (e.g. '.canopy-meta/') that GitManager adds to
+     * .git/info/exclude in every content branch workspace.
      */
     getGitExcludePattern(): string;
-    /** Get the full path to the permissions file */
     getPermissionsFilePath(root: string): string;
-    /** Get the full path to the groups file */
     getGroupsFilePath(root: string): string;
-    /** Get configuration for remote URL resolution (GitManager executes the logic) */
     getRemoteUrlConfig(): RemoteUrlConfig;
     /** Whether this mode requires an existing git repository */
     requiresExistingRepo(): boolean;
-    /**
-     * Get the branch name to use for settings (permissions/groups).
-     * Returns: canopycms-settings-{deploymentName}
-     */
+    /** The permissions/groups branch: `canopycms-settings-{deploymentName}`. */
     getSettingsBranchName(config: {
         settingsBranch?: string;
         deploymentName?: string;
         defaultBaseBranch?: string;
     }): string;
-    /**
-     * Get the root directory for settings storage.
-     * - prod: $CANOPYCMS_WORKSPACE_ROOT/settings or /mnt/efs/workspace/settings
-     * - dev: {cwd}/.canopy-dev/settings
-     */
+    /** `{workspaceRoot}/settings`, where settings storage lives. */
     getSettingsRoot(sourceRoot?: string): string;
-    /** Whether settings should be stored in a separate branch */
     usesSeparateSettingsBranch(): boolean;
-    /** Validate configuration for this mode */
     validateConfig(config: Partial<CanopyConfig>): void;
-    /** Whether PRs should be auto-created for permissions/groups changes */
     shouldCreateSettingsPR(config: {
         autoCreateSettingsPR?: boolean;
     }): boolean;

package/dist/operating-mode/types.js

@@ -1,8 +1,2 @@
-/**
- * Operating Mode Strategy Types
- *
- * This module defines the two-layer strategy pattern for operating modes:
- * - ClientSafeStrategy: Methods safe for client-side bundles (no Node.js APIs)
- * - ClientUnsafeStrategy: Full strategy with Node.js APIs (server-side only)
- */
+/** Operating-mode strategy types. */
 export {};