canopycms 0.0.67 → 0.0.68-int.100

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

@@ -2,6 +2,8 @@ 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';
+/** 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. */
 export declare const SCHEMA_GENERATION_RESOURCE = "schema";
 /** @internal Exported for tests. */
@@ -18,8 +20,8 @@ export interface BranchSchemaCacheEntry {
     generation: string | null;
 }
 /**
- * Per-branch schema cache: a file at {branchRoot}/.canopy-meta/schema-cache.json
- * with no in-memory layer, so it stays coherent across Lambda invocations.
+ * Per-branch schema cache: one file in {@link schemaCacheDir} with no in-memory
+ * layer, so it stays coherent across Lambda invocations.
  *
  * Freshness follows the generation-marker protocol owned by
  * resource-generation.ts, and this is one of that protocol's durable-snapshot
@@ -39,7 +41,7 @@ export declare class BranchSchemaCache {
     /**
      * Whether to skip the on-disk cache for this branchRoot.
      *
-     * Never write `.canopy-meta/` at the project root, whichever entrypoint
+     * 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.

package/dist/branch-schema-cache.js

@@ -5,10 +5,14 @@ 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';
 /** Bump when BranchSchemaCacheEntry shape changes to auto-invalidate stale caches */
 const SCHEMA_CACHE_VERSION = 3;
 /** 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';
 /**
@@ -43,8 +47,22 @@ async function isStaleByMtime(dir, cachedAt) {
     return false;
 }
 /**
- * Per-branch schema cache: a file at {branchRoot}/.canopy-meta/schema-cache.json
- * with no in-memory layer, so it stays coherent across Lambda invocations.
+ * Directory holding a branch's schema cache: `{branchRoot}/.git/canopycms` when
+ * the branch root is a full clone (every canopycms branch workspace is), else
+ * `{branchRoot}/.canopy-meta`. Under `.git/` because nothing there is ever
+ * tracked or reported by `git status`, so the cache can neither dirty the
+ * workspace nor enter a commit, even where an adopter has committed
+ * `.canopy-meta/`. It also lives and dies with the clone, so a re-clone never
+ * reads its predecessor's snapshot.
+ */
+async function schemaCacheDir(branchRoot) {
+    const gitDir = path.join(branchRoot, '.git');
+    const isClone = await fs.stat(gitDir).then((stat) => stat.isDirectory(), () => false);
+    return isClone ? path.join(gitDir, 'canopycms') : path.join(branchRoot, CANOPY_META_DIR);
+}
+/**
+ * Per-branch schema cache: one file in {@link schemaCacheDir} with no in-memory
+ * layer, so it stays coherent across Lambda invocations.
  *
  * Freshness follows the generation-marker protocol owned by
  * resource-generation.ts, and this is one of that protocol's durable-snapshot
@@ -65,7 +83,7 @@ export class BranchSchemaCache {
     /**
      * Whether to skip the on-disk cache for this branchRoot.
      *
-     * Never write `.canopy-meta/` at the project root, whichever entrypoint
+     * 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.
@@ -75,7 +93,7 @@ export class BranchSchemaCache {
     }
     /** Get schema for a branch, from the cache when fresh, else resolved fresh. */
     async getSchema(branchRoot, entrySchemaRegistry, contentRootName = 'content') {
-        return this.loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName);
+        return timeRequestPhase('schema', () => this.loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName));
     }
     /**
      * Resolve the schema from disk. Protected rather than a direct resolveSchema
@@ -89,8 +107,7 @@ export class BranchSchemaCache {
         const contentRoot = path.join(branchRoot, contentRootName);
         const skipDiskCache = this.skipDiskCache(branchRoot);
         if (!skipDiskCache) {
-            const cacheDir = path.join(branchRoot, '.canopy-meta');
-            const cachePath = path.join(cacheDir, 'schema-cache.json');
+            const cachePath = path.join(await schemaCacheDir(branchRoot), SCHEMA_CACHE_FILE);
             let cacheData = null;
             try {
                 const cacheContent = await fs.readFile(cachePath, 'utf-8');
@@ -149,7 +166,8 @@ export class BranchSchemaCache {
         const read = skipDiskCache
             ? null
             : await readResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE);
-        const result = await this.resolveFresh(contentRoot, entrySchemaRegistry);
+        // Nested under `schema`, so a request summary names a cache miss (`…schema>resolve`).
+        const result = await timeRequestPhase('resolve', () => this.resolveFresh(contentRoot, entrySchemaRegistry));
         // Validate schema has content
         if (!isValidSchema(result.schema)) {
             throw new Error(`No schema found in ${contentRoot}. Create .collection.json files ` +
@@ -166,11 +184,11 @@ export class BranchSchemaCache {
         // Use configured contentRoot name as base path for logical paths
         const flatSchema = flattenSchema(result.schema, contentRootName);
         if (!skipDiskCache) {
-            const cacheDir = path.join(branchRoot, '.canopy-meta');
-            const cachePath = path.join(cacheDir, 'schema-cache.json');
+            const cacheDir = await schemaCacheDir(branchRoot);
+            const cachePath = path.join(cacheDir, SCHEMA_CACHE_FILE);
             // Opportunistic cleanup of the retired .stale marker file, which a
             // mid-flight deploy can leave behind. Not load-bearing.
-            await fs.unlink(path.join(cacheDir, 'schema-cache.stale')).catch(() => { });
+            await fs.unlink(path.join(branchRoot, CANOPY_META_DIR, 'schema-cache.stale')).catch(() => { });
             if (read && read.ok) {
                 const newCache = {
                     version: SCHEMA_CACHE_VERSION,
@@ -180,7 +198,7 @@ export class BranchSchemaCache {
                     generation: read.token,
                 };
                 // Temp file then rename, with the temp file unlinked on a failed
-                // rename so a transient error leaves no stray `.tmp` in `.canopy-meta/`.
+                // rename so a transient error leaves no stray `.tmp` beside the cache.
                 await fs.mkdir(cacheDir, { recursive: true });
                 const tmpPath = path.join(cacheDir, `schema-cache.tmp.${Date.now()}.${Math.random()}.json`);
                 await fs.writeFile(tmpPath, JSON.stringify(newCache, null, 2), 'utf-8');

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 does not parse
+     */
+    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';
 /**