canopycms 0.0.68-int.98 → 0.1.0

package/dist/branch-schema-cache.d.ts

@@ -1,7 +1,7 @@
 import type { RootCollectionConfig } from './config/index.js';
 import type { FlatSchemaItem } from './config/types.js';
 import type { OperatingMode } from './operating-mode/index.js';
-import type { EntrySchemaRegistry, SchemaResolutionResult } from './schema/types.js';
+import type { EntrySchemaRegistry, SchemaIssue, SchemaResolutionResult, UnknownSchemaPolicy } from './schema/types.js';
 /** File name of the schema cache inside {@link schemaCacheDir}. */
 export declare const SCHEMA_CACHE_FILE = "schema-cache.json";
 /** resource-generation.ts resource key for the schema cache's marker. */
@@ -18,6 +18,19 @@ export interface BranchSchemaCacheEntry {
      * isGenerationCurrent) to decide freshness.
      */
     generation: string | null;
+    /**
+     * {@link registryFingerprint} of the registry this snapshot was resolved
+     * against. A deploy bumps no marker, so without it a new image would keep
+     * serving schemas resolved by the old image's registry.
+     */
+    registryFingerprint: string;
+    issues: SchemaIssue[];
+}
+/** A branch's resolved schema, plus what a degraded resolve left out of it. */
+export interface ResolvedBranchSchema {
+    schema: RootCollectionConfig;
+    flatSchema: FlatSchemaItem[];
+    issues: SchemaIssue[];
 }
 /**
  * Per-branch schema cache: one file in {@link schemaCacheDir} with no in-memory
@@ -32,6 +45,15 @@ export interface BranchSchemaCacheEntry {
  * Callers that bypass SchemaOps (api/schema.ts's invalidate endpoint, and the
  * bulk git-op bump in invalidateBranchContentCaches) accept the lazy
  * next-read regen instead.
+ *
+ * The owner of the strict/degrade split. Content read from the checkout (a
+ * build, a static deployment) shares a commit with the code, so a schema
+ * reference the registry lacks is a real bug and resolution throws. A branch
+ * workspace's content arrives by sync, which can land before the image whose
+ * registry it needs, or after an image that needs content it lacks; there an
+ * unknown schema marks only its entry type `unavailable`, an unknown reference
+ * `entryTypes` value only empties that field's options, and both are returned
+ * as `issues`.
  */
 export declare class BranchSchemaCache {
     /** Tracks when we last checked mtimes per contentRoot, to debounce rapid requests */
@@ -39,25 +61,23 @@ export declare class BranchSchemaCache {
     private readonly devMode;
     constructor(mode?: OperatingMode);
     /**
-     * Whether to skip the on-disk cache for this branchRoot.
+     * Whether this branchRoot is the checkout rather than a branch workspace,
+     * which skips the on-disk cache and resolves strictly (see the class doc).
      *
      * Never write a schema cache at the project root, whichever entrypoint
      * produced the cwd branchRoot. branchRoot equals process.cwd() only in the
      * synthetic contexts static deployments and build phases use; a real branch
      * root is always nested under the workspace.
      */
-    private skipDiskCache;
+    private readsCheckout;
     /** Get schema for a branch, from the cache when fresh, else resolved fresh. */
-    getSchema(branchRoot: string, entrySchemaRegistry: EntrySchemaRegistry, contentRootName?: string): Promise<{
-        schema: RootCollectionConfig;
-        flatSchema: FlatSchemaItem[];
-    }>;
+    getSchema(branchRoot: string, entrySchemaRegistry: EntrySchemaRegistry, contentRootName?: string): Promise<ResolvedBranchSchema>;
     /**
      * Resolve the schema from disk. Protected rather than a direct resolveSchema
      * call so tests can subclass and block it to simulate cross-process
      * interleavings — mirrors BranchRegistry's scanBranchDirectories() hook.
      */
-    protected resolveFresh(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry): Promise<SchemaResolutionResult>;
+    protected resolveFresh(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry, unknownSchema: UnknownSchemaPolicy): Promise<SchemaResolutionResult>;
     private loadFromCacheOrResolve;
     /**
      * Resolve the schema fresh from disk and persist it (subject to the
@@ -75,10 +95,7 @@ export declare class BranchSchemaCache {
      * instead return a snapshot a concurrent host wrote — possibly one embedding
      * the now-current token over ITS own stale-NFS scan — skipping that scan.
      */
-    resolveAndPersist(branchRoot: string, entrySchemaRegistry: EntrySchemaRegistry, contentRootName?: string): Promise<{
-        schema: RootCollectionConfig;
-        flatSchema: FlatSchemaItem[];
-    }>;
+    resolveAndPersist(branchRoot: string, entrySchemaRegistry: EntrySchemaRegistry, contentRootName?: string): Promise<ResolvedBranchSchema>;
     /**
      * Invalidate a branch's cache by bumping the marker; every process sharing
      * this branchRoot re-resolves at its next read. The bump must succeed —

package/dist/branch-schema-cache.js

@@ -1,20 +1,39 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { resolveSchema, isValidSchema } from './schema/resolver.js';
+import { registryFingerprint } from './schema/registry-fingerprint.js';
 import { flattenSchema } from './config/flatten.js';
 import { validateReferenceEntryTypes } from './validation/entry-type-reference-validator.js';
 import { isBuildMode } from './build-mode.js';
 import { bumpResourceGeneration, readResourceGeneration, isGenerationCurrent, } from './resource-generation.js';
 import { timeRequestPhase } from './utils/request-timing.js';
 import { CANOPY_META_DIR } from './utils/git.js';
+import { canopyLogWarn } from './utils/logger.js';
 /** Bump when BranchSchemaCacheEntry shape changes to auto-invalidate stale caches */
-const SCHEMA_CACHE_VERSION = 3;
+const SCHEMA_CACHE_VERSION = 4;
 /** Minimum interval between mtime staleness checks (ms) */
 const MTIME_CHECK_DEBOUNCE_MS = 1000;
 /** File name of the schema cache inside {@link schemaCacheDir}. */
 export const SCHEMA_CACHE_FILE = 'schema-cache.json';
 /** resource-generation.ts resource key for the schema cache's marker. */
 export const SCHEMA_GENERATION_RESOURCE = 'schema';
+const reportedIssues = new Set();
+/** Log each schema issue once per process, whether it was resolved here or read from a snapshot. */
+function reportSchemaIssues(issues) {
+    for (const issue of issues) {
+        const line = issue.kind === 'unknown-schema'
+            ? `CanopyCMS: ${issue.metaFile} names entry schema "${issue.schemaRef}", which this ` +
+                `deployment's entry schema registry does not define, so entry type ` +
+                `"${issue.entryType}" is unavailable until code defining it is deployed or the ` +
+                `content stops naming it.`
+            : `CanopyCMS: ${issue.message} That reference field offers no options until the ` +
+                `content declares the entry type.`;
+        if (reportedIssues.has(line))
+            continue;
+        reportedIssues.add(line);
+        canopyLogWarn(line);
+    }
+}
 /**
  * True when a .collection.json under `dir` is newer than `cachedAt`.
  *
@@ -73,6 +92,15 @@ async function schemaCacheDir(branchRoot) {
  * Callers that bypass SchemaOps (api/schema.ts's invalidate endpoint, and the
  * bulk git-op bump in invalidateBranchContentCaches) accept the lazy
  * next-read regen instead.
+ *
+ * The owner of the strict/degrade split. Content read from the checkout (a
+ * build, a static deployment) shares a commit with the code, so a schema
+ * reference the registry lacks is a real bug and resolution throws. A branch
+ * workspace's content arrives by sync, which can land before the image whose
+ * registry it needs, or after an image that needs content it lacks; there an
+ * unknown schema marks only its entry type `unavailable`, an unknown reference
+ * `entryTypes` value only empties that field's options, and both are returned
+ * as `issues`.
  */
 export class BranchSchemaCache {
     constructor(mode = 'prod') {
@@ -81,14 +109,15 @@ export class BranchSchemaCache {
         this.devMode = mode === 'dev';
     }
     /**
-     * Whether to skip the on-disk cache for this branchRoot.
+     * Whether this branchRoot is the checkout rather than a branch workspace,
+     * which skips the on-disk cache and resolves strictly (see the class doc).
      *
      * Never write a schema cache at the project root, whichever entrypoint
      * produced the cwd branchRoot. branchRoot equals process.cwd() only in the
      * synthetic contexts static deployments and build phases use; a real branch
      * root is always nested under the workspace.
      */
-    skipDiskCache(branchRoot) {
+    readsCheckout(branchRoot) {
         return isBuildMode() || path.resolve(branchRoot) === path.resolve(process.cwd());
     }
     /** Get schema for a branch, from the cache when fresh, else resolved fresh. */
@@ -100,13 +129,13 @@ export class BranchSchemaCache {
      * call so tests can subclass and block it to simulate cross-process
      * interleavings — mirrors BranchRegistry's scanBranchDirectories() hook.
      */
-    async resolveFresh(contentRoot, entrySchemaRegistry) {
-        return resolveSchema(contentRoot, entrySchemaRegistry);
+    async resolveFresh(contentRoot, entrySchemaRegistry, unknownSchema) {
+        return resolveSchema(contentRoot, entrySchemaRegistry, { unknownSchema });
     }
     async loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName) {
         const contentRoot = path.join(branchRoot, contentRootName);
-        const skipDiskCache = this.skipDiskCache(branchRoot);
-        if (!skipDiskCache) {
+        const fromCheckout = this.readsCheckout(branchRoot);
+        if (!fromCheckout) {
             const cachePath = path.join(await schemaCacheDir(branchRoot), SCHEMA_CACHE_FILE);
             let cacheData = null;
             try {
@@ -120,7 +149,9 @@ export class BranchSchemaCache {
             // Strict version check, not truthiness: a snapshot from an older version
             // left on EFS by a rolling deploy has no `generation` field, and an
             // `undefined` token breaks the freshness comparison below.
-            if (cacheData && cacheData.version === SCHEMA_CACHE_VERSION) {
+            if (cacheData &&
+                cacheData.version === SCHEMA_CACHE_VERSION &&
+                cacheData.registryFingerprint === registryFingerprint(entrySchemaRegistry)) {
                 const read = await readResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE);
                 if (isGenerationCurrent(cacheData.generation, read)) {
                     // Dev also walks mtimes, debounced, to catch edits made outside the CMS.
@@ -135,7 +166,12 @@ export class BranchSchemaCache {
                     else {
                         if (this.devMode)
                             this.lastMtimeCheck.set(contentRoot, now);
-                        return { schema: cacheData.schema, flatSchema: cacheData.flatSchema };
+                        reportSchemaIssues(cacheData.issues);
+                        return {
+                            schema: cacheData.schema,
+                            flatSchema: cacheData.flatSchema,
+                            issues: cacheData.issues,
+                        };
                     }
                 }
                 else {
@@ -148,7 +184,7 @@ export class BranchSchemaCache {
             }
         }
         return this.resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, {
-            skipDiskCache,
+            fromCheckout,
         });
     }
     /**
@@ -158,32 +194,36 @@ export class BranchSchemaCache {
      * cache-miss fallback and by {@link resolveAndPersist}.
      */
     async resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, options) {
-        const { skipDiskCache } = options;
+        const { fromCheckout } = options;
         const contentRoot = path.join(branchRoot, contentRootName);
         // Capture the marker strictly BEFORE resolving, so a bump landing
         // mid-resolve differs from the token persisted below and forces a
         // re-resolve on the next read.
-        const read = skipDiskCache
+        const read = fromCheckout
             ? null
             : await readResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE);
         // Nested under `schema`, so a request summary names a cache miss (`…schema>resolve`).
-        const result = await timeRequestPhase('resolve', () => this.resolveFresh(contentRoot, entrySchemaRegistry));
+        const result = await timeRequestPhase('resolve', () => this.resolveFresh(contentRoot, entrySchemaRegistry, fromCheckout ? 'throw' : 'degrade'));
         // Validate schema has content
         if (!isValidSchema(result.schema)) {
             throw new Error(`No schema found in ${contentRoot}. Create .collection.json files ` +
                 'with references to field schemas defined in your entry schema registry.');
         }
         // Reference fields may only scope themselves to entry types that exist.
-        // Checked here, before anything is cached, so a typo fails loudly and
-        // consistently instead of silently resolving to zero reference options.
+        // Checked here, before anything is cached, so a typo fails a build loudly
+        // instead of silently resolving to zero reference options.
         const entryTypeIssues = validateReferenceEntryTypes(result.schema);
-        if (entryTypeIssues.length > 0) {
+        if (entryTypeIssues.length > 0 && fromCheckout) {
             throw new Error(`Invalid reference field entryTypes in ${contentRoot}:\n` +
                 entryTypeIssues.map((issue) => `  - ${issue}`).join('\n'));
         }
+        const issues = [
+            ...result.issues,
+            ...entryTypeIssues.map((message) => ({ kind: 'reference-entry-type', message })),
+        ];
         // Use configured contentRoot name as base path for logical paths
         const flatSchema = flattenSchema(result.schema, contentRootName);
-        if (!skipDiskCache) {
+        if (!fromCheckout) {
             const cacheDir = await schemaCacheDir(branchRoot);
             const cachePath = path.join(cacheDir, SCHEMA_CACHE_FILE);
             // Opportunistic cleanup of the retired .stale marker file, which a
@@ -196,6 +236,8 @@ export class BranchSchemaCache {
                     flatSchema,
                     cachedAt: new Date().toISOString(),
                     generation: read.token,
+                    registryFingerprint: registryFingerprint(entrySchemaRegistry),
+                    issues,
                 };
                 // Temp file then rename, with the temp file unlinked on a failed
                 // rename so a transient error leaves no stray `.tmp` beside the cache.
@@ -215,7 +257,8 @@ export class BranchSchemaCache {
             // with an unattributable one would look correctly attributed to every
             // future reader. Serve the fresh result without persisting it.
         }
-        return { schema: result.schema, flatSchema };
+        reportSchemaIssues(issues);
+        return { schema: result.schema, flatSchema, issues };
     }
     /**
      * Resolve fresh from disk and persist, SKIPPING the cache read entirely.
@@ -227,9 +270,9 @@ export class BranchSchemaCache {
      * the now-current token over ITS own stale-NFS scan — skipping that scan.
      */
     async resolveAndPersist(branchRoot, entrySchemaRegistry, contentRootName = 'content') {
-        const skipDiskCache = this.skipDiskCache(branchRoot);
+        const fromCheckout = this.readsCheckout(branchRoot);
         return this.resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, {
-            skipDiskCache,
+            fromCheckout,
         });
     }
     /**
@@ -241,7 +284,7 @@ export class BranchSchemaCache {
      * No eager re-resolve here; it lives in SchemaOps (see the class doc).
      */
     async invalidate(branchRoot) {
-        if (this.skipDiskCache(branchRoot))
+        if (this.readsCheckout(branchRoot))
             return;
         await bumpResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE, { mustSucceed: true });
     }

package/dist/branch-sparse.d.ts

@@ -0,0 +1,23 @@
+import type { CanopyConfig } from './config/index.js';
+/**
+ * The cone a content branch's clone checks out for `contentRoot`, sorted as
+ * `git sparse-checkout list` prints it, or null for a full clone when the content root is the
+ * repository root.
+ */
+export declare function sparseConeFor(contentRoot: string | undefined): string[] | null;
+export declare function sameCone(a: readonly string[] | null, b: readonly string[] | null): boolean;
+export interface RecordedSparseCone {
+    cone: string[] | null;
+}
+/** The recorded cone, or undefined when none is recorded or the record does not parse. */
+export declare function readRecordedSparseCone(contentBranchesRoot: string): Promise<RecordedSparseCone | undefined>;
+/**
+ * Record `cone` unless it already is, by temp file and rename. Does not create the branches
+ * root: a deployment without one has no clones to re-apply a cone to.
+ */
+export declare function recordSparseCone(contentBranchesRoot: string, cone: string[] | null): Promise<void>;
+/**
+ * Record the cone `config` asks for, once per process start, so a changed content root reaches
+ * existing clones without waiting for a new branch. Best-effort: a failure is logged.
+ */
+export declare function recordConfiguredSparseCone(config: CanopyConfig): Promise<void>;

package/dist/branch-sparse.js

@@ -0,0 +1,118 @@
+/**
+ * Sparse checkout for content-branch clones. An editor reads and writes only under the content
+ * root, and on EFS every checked-out file costs an NFS round trip, so a content branch's clone
+ * checks out the content root and `.canopy-meta` in cone mode, which always keeps the files at
+ * the repository root (a root permissions.json among them).
+ *
+ * A cone is set only by `stageBranchWorkspace` and, on clones already sparse, by the worker
+ * (worker/sparse-cone.ts), so settings workspaces are never sparse; their orphan init also
+ * empties the index with `--sparse`, so a sparse one could not leak base content either.
+ * Sparse-index stays off: git expands it for most commands anyway.
+ *
+ * `git add` and `git rm` refuse a path outside the cone unless given `--sparse` (git >= 2.34),
+ * so every call that can name one passes it.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { readsFromCheckout } from './build-mode.js';
+import { operatingStrategy } from './operating-mode/index.js';
+import { getErrorMessage, isNodeError } from './utils/error.js';
+import { CANOPY_META_DIR } from './utils/git.js';
+import { canopyLogWarn } from './utils/logger.js';
+/**
+ * The cone a content branch's clone checks out for `contentRoot`, sorted as
+ * `git sparse-checkout list` prints it, or null for a full clone when the content root is the
+ * repository root.
+ */
+export function sparseConeFor(contentRoot) {
+    const root = (contentRoot ?? 'content')
+        .split('/')
+        .filter((segment) => segment && segment !== '.')
+        .join('/');
+    return root ? [...new Set([CANOPY_META_DIR, root])].sort() : null;
+}
+export function sameCone(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    const [left, right] = [[...a].sort(), [...b].sort()];
+    return left.length === right.length && left.every((dir, i) => dir === right[i]);
+}
+/**
+ * Beside the branch directories: the cone this deployment's config asks for, written by the
+ * processes that hold the config and read by the worker, which does not, to re-apply a changed
+ * content root to existing clones.
+ */
+const SPARSE_CONE_RECORD = '.sparse-cone.json';
+function isConeDir(dir) {
+    return (typeof dir === 'string' &&
+        dir.length > 0 &&
+        !path.isAbsolute(dir) &&
+        !dir.split('/').some((segment) => segment === '' || segment === '.' || segment === '..'));
+}
+/** The recorded cone, or undefined when none is recorded or the record does not parse. */
+export async function readRecordedSparseCone(contentBranchesRoot) {
+    let raw;
+    try {
+        raw = await fs.readFile(path.join(contentBranchesRoot, SPARSE_CONE_RECORD), 'utf8');
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null || !('cone' in parsed))
+        return undefined;
+    const { cone } = parsed;
+    if (cone === null)
+        return { cone: null };
+    return Array.isArray(cone) && cone.length > 0 && cone.every(isConeDir)
+        ? { cone: cone.filter(isConeDir) }
+        : undefined;
+}
+/**
+ * Record `cone` unless it already is, by temp file and rename. Does not create the branches
+ * root: a deployment without one has no clones to re-apply a cone to.
+ */
+export async function recordSparseCone(contentBranchesRoot, cone) {
+    const current = await readRecordedSparseCone(contentBranchesRoot);
+    if (current && sameCone(current.cone, cone))
+        return;
+    const target = path.join(contentBranchesRoot, SPARSE_CONE_RECORD);
+    const temp = `${target}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        await fs.writeFile(temp, `${JSON.stringify({ cone })}\n`, 'utf8');
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    try {
+        await fs.rename(temp, target);
+    }
+    catch (err) {
+        await fs.unlink(temp).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Record the cone `config` asks for, once per process start, so a changed content root reaches
+ * existing clones without waiting for a new branch. Best-effort: a failure is logged.
+ */
+export async function recordConfiguredSparseCone(config) {
+    try {
+        if (readsFromCheckout(config))
+            return;
+        await recordSparseCone(operatingStrategy(config.mode).getContentBranchesRoot(config.sourceRoot), sparseConeFor(config.contentRoot));
+    }
+    catch (err) {
+        canopyLogWarn(`[canopy] Could not record the sparse-checkout cone: ${getErrorMessage(err)}`);
+    }
+}

package/dist/branch-workspace.d.ts

@@ -1,4 +1,5 @@
 import type { CanopyConfig } from './config/index.js';
+import { type BlockingKind } from './branch-provisioning.js';
 import type { BranchAccessControl, BranchContext, CanopyUserId } from './types.js';
 import type { OperatingMode } from './operating-mode/index.js';
 export interface OpenBranchOptions {
@@ -12,14 +13,52 @@ export interface OpenBranchOptions {
     remoteUrl?: string;
 }
 /**
- * Manages per-branch filesystem workspace: resolves root, ensures metadata,
- * and updates the branch registry.
+ * `created`: this call published the branch. `exists`: it was already there, or another request
+ * published it first; its metadata is returned as found, never merged with this call's.
+ */
+export interface ProvisionOutcome {
+    kind: 'created' | 'exists';
+    context: BranchContext;
+}
+/** @internal Test seams around the publish step. */
+export interface ProvisioningTestHooks {
+    beforePublish?: (paths: {
+        stagingPath: string;
+        finalPath: string;
+    }) => Promise<void>;
+    inspectBlocked?: (finalPath: string) => Promise<BlockingKind>;
+}
+/** @internal Exported for tests; no argument clears them. */
+export declare function setProvisioningTestHooks(hooks?: ProvisioningTestHooks): void;
+/**
+ * Provisions per-branch workspaces under [PROV-1]: a branch's directory appears only by rename,
+ * complete with branch.json (branch-provisioning.ts).
  */
 export declare class BranchWorkspaceManager {
     private readonly config;
     constructor(config: CanopyConfig);
-    private ensureGitWorkspace;
+    /** The branch's context, provisioning it first when it does not exist. */
     openOrCreateBranch(options: OpenBranchOptions): Promise<BranchContext>;
+    /**
+     * Provision a branch workspace, or report the one already there.
+     *
+     * @throws BranchProvisioningBusyError when another process is mid-way through this branch, or
+     *   what is at its path is too fresh to judge (retriable)
+     * @throws BranchDirOccupiedError in prod, when its path holds a repository this deployment did
+     *   not create
+     * @throws BranchMetadataCorruptError when its branch.json is not valid JSON or fails its schema
+     */
+    provisionBranch(options: OpenBranchOptions): Promise<ProvisionOutcome>;
+    private provisionUnshared;
+    private stageAndPublish;
+    /**
+     * The one exception to [PROV-1]: a dev workspace that already holds real work is kept where it
+     * is, given branch.json under the branch's lock.
+     */
+    private adoptInPlace;
+    /** Whether residue at the branch path may still belong to a live process. */
+    private recentlyActive;
+    private existing;
 }
 export { loadBranchContext } from './branch-metadata.js';
 /**