canopycms 0.0.68-int.93 → 0.0.68-int.94

package/README.md

@@ -104,6 +104,7 @@ export default defineCanopyConfig({
       colors: { brand: '#4f46e5' },
     },
     // previewBase: { 'content/posts': '/blog' }, // optional overrides
+    // previewPrefix: '/preview', // optional, in front of every preview URL
   },
   // For prod mode, defaultRemoteUrl is required.
   // For dev, it's optional - if omitted, uses auto-initialized local remote at .canopy-dev/remote.git
@@ -323,7 +324,7 @@ name) works, but leaves the entry's real `urlPath` as
 URL-derived surface then has to be told about one at a time. The example app in this repo used to
 do that and no longer does.
 
-Both methods return `{ data, path }`. `read` throws if the content is missing; `readByUrlPath` returns `null` instead. Pass a `branch` option when you want branch-specific data (e.g., for preview); otherwise it defaults to your configured base branch. Both enforce the same branch/path access rules as the API handlers.
+Both methods return `{ data, path }`. `read` throws if the content is missing; `readByUrlPath` returns `null` instead. Pass a `branch` option when you want branch-specific data (e.g., for preview); otherwise it defaults to the active branch: `defaultActiveBranch`, or when that is unset, git HEAD in `dev` and your base branch in `prod`. Any other branch must already exist and be readable by the current user, or it reads as not found. Both enforce the same branch/path access rules as the API handlers.
 
 **Index entries and URL resolution**
 
@@ -401,7 +402,7 @@ _TODO_ show real examples of what to do
 
 ### Preview branch awareness
 
-- When building preview URLs, include the current branch as a query param (e.g., `/?branch=feature-foo` or `/posts/hello?branch=feature-foo`) so SSR preview pages read from the same branch workspace the editor is editing. The `Editor` component appends the branch param automatically to `previewBaseByCollection`; your page loaders should read `searchParams.branch` and pass it into `createContentReader`.
+- When building preview URLs, include the current branch as a query param (e.g., `/?branch=feature-foo` or `/posts/hello?branch=feature-foo`) so SSR preview pages read from the same branch workspace the editor is editing. The `Editor` component appends the branch param automatically to `previewBaseByCollection`; your page loaders should read `searchParams.branch` and pass it as the `branch` option to `getCanopy()`'s `read`/`readByUrlPath`.
 - For public static builds, omit/ignore the branch param; this pattern is only for the editor/preview environment.
 - Likewise, include `branch` in your editor route (e.g., `/edit?branch=feature-foo`) and have your editor page pass it to `<Editor>` so reloads/links preserve the selected branch. The `Editor` will also reflect branch switches back into the query string.
 

package/dist/api/admin.d.ts

@@ -8,7 +8,7 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
 import type { Task, QueueStats, CorruptTaskFile } from '../task-queue/cms-task-queue.js';
-import type { WorkerStatusReport } from '../types.js';
+import type { BuildIdentity, WorkerStatusReport } from '../types.js';
 import type { OperatingMode } from '../operating-mode/index.js';
 export type { BranchHealthResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse, } from './admin-branch-health.js';
 type WorkerLivenessState = 'alive' | 'stale' | 'absent';
@@ -31,6 +31,18 @@ export interface AdminStatusData {
     worker: WorkerLiveness;
     workerStatus: WorkerStatusReport | null;
     statusReadError?: string;
+    /**
+     * Why this process cannot provision the settings workspace (groups and path rules), when it
+     * cannot. Its requests that resolve a user answer 503 meanwhile; bootstrap admins still reach
+     * /admin.
+     */
+    settingsWorkspaceError?: string;
+    /** Build of the API process answering this request. */
+    build: BuildIdentity;
+    /** Whether `media` is configured; without it every upload returns 501. */
+    assetStore: {
+        configured: boolean;
+    };
 }
 /** Response type for GET /admin/status */
 export type AdminStatusResponse = ApiResponse<AdminStatusData>;

package/dist/api/admin.js

@@ -12,7 +12,8 @@ import { getQueueStats, listTasks, listCorruptTaskFiles, requeueFailedTask, } fr
 import { getTaskQueueDir } from '../task-queue/task-queue-config.js';
 import { WORKER_STATUS_FILE } from '../task-queue/worker-status.js';
 import { defineEndpoint } from './route-builder.js';
-import { getErrorMessage, isNotFoundError } from '../utils/error.js';
+import { getErrorMessage, isNotFoundError, redactCredentials } from '../utils/error.js';
+import { getBuildIdentity } from '../build-identity.js';
 import { ADMIN_BRANCH_HEALTH_ROUTES } from './admin-branch-health.js';
 /**
  * 60_000 = DEFAULT_LOCK_STALE_MS in worker/cms-worker.ts, hardcoded rather
@@ -72,6 +73,15 @@ async function readWorkerStatus(taskDir) {
         return { workerStatus: null, statusReadError: getErrorMessage(err) };
     }
 }
+async function readSettingsWorkspaceError(ctx) {
+    try {
+        await ctx.services.getSettingsBranchRoot();
+        return undefined;
+    }
+    catch (err) {
+        return redactCredentials(getErrorMessage(err));
+    }
+}
 /** Age (ms) of the oldest file in pending/, or undefined if empty/missing. */
 async function getOldestPendingAgeMs(taskDir) {
     const pendingDir = path.join(taskDir, 'pending');
@@ -126,11 +136,12 @@ const deleteTaskParamsSchema = z.object({
 const getAdminStatusHandler = async (_gc, ctx, _req) => {
     const taskDir = getTaskQueueDir(ctx.services.config);
     try {
-        const [queueStats, oldestPendingAgeMs, worker, { workerStatus, statusReadError }] = await Promise.all([
+        const [queueStats, oldestPendingAgeMs, worker, { workerStatus, statusReadError }, settingsWorkspaceError,] = await Promise.all([
             getQueueStats(taskDir),
             getOldestPendingAgeMs(taskDir),
             classifyWorkerLiveness(taskDir),
             readWorkerStatus(taskDir),
+            readSettingsWorkspaceError(ctx),
         ]);
         return {
             ok: true,
@@ -145,6 +156,9 @@ const getAdminStatusHandler = async (_gc, ctx, _req) => {
                 worker,
                 workerStatus,
                 ...(statusReadError ? { statusReadError } : {}),
+                ...(settingsWorkspaceError ? { settingsWorkspaceError } : {}),
+                build: getBuildIdentity(),
+                assetStore: { configured: !!ctx.assetStore },
             },
         };
     }
@@ -255,6 +269,8 @@ const getAdminStatus = defineEndpoint({
         queue: { pending: 0, processing: 0, completed: 0, failed: 0, corrupt: 0 },
         worker: { state: 'absent' },
         workerStatus: null,
+        build: { canopycmsVersion: '0.0.0' },
+        assetStore: { configured: false },
     },
     guards: ['admin'],
     handler: getAdminStatusHandler,

package/dist/api/branch-status.js

@@ -8,6 +8,7 @@ import { canPerformWorkflowAction, getBranchProtection } from '../authorization/
 import { syncSubmitPr } from './github-sync.js';
 import { getErrorMessage, redactCredentials, sanitizeErrorMessage } from '../utils/error.js';
 import { isNonFastForwardRejection } from '../utils/git.js';
+import { ContentWriteLockBusyError } from '../utils/content-write-lock.js';
 import { submissionEditorFromUser } from '../submission-attribution.js';
 const getBranchStatusHandler = async (gc, _ctx, _req, _params) => {
     const { branchContext } = gc;
@@ -57,6 +58,17 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
         ({ changedPaths } = await ctx.services.submitBranch({ context: branchContext, submitter }));
     }
     catch (err) {
+        // Retriable either way: a resubmit commits nothing new and pushes only
+        // what has not reached the remote.
+        if (err instanceof ContentWriteLockBusyError) {
+            return {
+                ok: false,
+                status: 409,
+                error: err.outcome === 'not-run'
+                    ? `Could not submit "${branchContext.branch.name}" right now: it is being synced with its base branch, or a save is in flight. Nothing was submitted; try again in a moment.`
+                    : `"${branchContext.branch.name}" was being synced while it was submitted, so the submit may not have completed. Try submitting again.`,
+            };
+        }
         const message = getErrorMessage(err);
         // Full path detail (including branchRoot, an absolute path) to server logs
         // only; the client only ever sees the sanitized form (API-H2). Credentials
@@ -66,8 +78,7 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
         // A non-fast-forward rejection means this branch and the deployment's
         // local repository have diverged. Retrying the identical push can never
         // succeed (see isNonFastForwardRejection), so surface 409 instead of the
-        // generic 500 below. Everything else (network, auth, lock contention)
-        // keeps the existing 500 path unchanged.
+        // generic 500 below. Everything else (network, auth) keeps the 500 path.
         //
         // This push targets the deployment's OWN local origin (remote.git), not
         // GitHub, so the message deliberately states only the observable fact and

package/dist/api/branch.js

@@ -10,7 +10,7 @@ import { clientOperatingStrategy } from '../operating-mode/index.js';
 import { isNotFoundError, getErrorMessage, sanitizeErrorMessage } from '../utils/error.js';
 import { filePathExists } from '../utils/fs.js';
 import { isNetworkRemoteUrl } from '../utils/git.js';
-import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, } from '../paths/index.js';
+import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, isSettingsBranchName, } from '../paths/index.js';
 import { GitManager } from '../git-manager.js';
 import { branchNameSchema, branchParamSchema } from './validators.js';
 const log = createDebugLogger({ prefix: 'BranchAPI' });
@@ -95,15 +95,12 @@ export const createBranchHandler = async (ctx, req, body) => {
             branchName,
             userId: req.user.userId,
         });
-        // Scope note: the collision guards below (settings-branch collision,
-        // reserved canopycms-settings- prefix, and the remote-mirror check
-        // further down) apply ONLY to this user-facing creation path.
-        // http/handler.ts's auto-create (base/active/settings branches) and
-        // branch-workspace.ts's loadOrCreateBranchContext (reached from run-time
-        // content reads and the AI pipeline; build-time reads return the checkout
-        // and never provision) provision system/known branch names, not
-        // user-chosen ones, and deliberately stay uncovered -- intentional, not
-        // an oversight.
+        // Scope note: the remote-mirror check further down applies ONLY to this
+        // user-facing creation path; http/handler.ts's auto-create (base/active
+        // branches) and loadOrCreateBranchContext provision known names. The two
+        // settings-branch checks below give this path a specific 400; every
+        // provisioning path, this one included, also refuses a settings branch in
+        // BranchWorkspaceManager.openOrCreateBranch.
         // Prevent git branch name collision with the settings branch. Settings
         // live in a separate directory but share the same git remote, and
         // openOrCreateBranch (branch-workspace.ts) uses the SANITIZED name as the
@@ -337,7 +334,10 @@ export const listBranchesHandler = async (ctx, req) => {
             error: 'Branch registry not initialized — ensure the workspace has been initialized',
         };
     }
-    const allBranches = await ctx.services.registry.list();
+    // A settings-branch workspace is never resolvable as a content branch (see
+    // http/handler.ts), so one left on disk is hidden rather than listed unopenable.
+    const settingsBranch = operatingStrategy(ctx.services.config.mode).getSettingsBranchName(ctx.services.config);
+    const allBranches = (await ctx.services.registry.list()).filter((context) => !isSettingsBranchName(context.branch.name, settingsBranch));
     // The branch the editor should open when none is pinned via URL/config.
     // Read per-request so dev-mode refreshActiveBranch() updates are reflected.
     // Sanitized: dev mode detects the RAW git HEAD name (e.g. 'claude/foo'),

package/dist/api/client.d.ts

@@ -28,7 +28,7 @@ export interface ApiClientOptions {
     /**
      * End request paths with `/` (by `withTrailingSlash`'s rule), matching a Next host built with
      * `trailingSlash: true`. Defaults to the value `withCanopy` inlines at build time (see
-     * `request-url.ts`), else false.
+     * `readTrailingSlashEnv`), else false.
      */
     trailingSlash?: boolean;
     /**

package/dist/api/client.js

@@ -6,8 +6,7 @@
  * (changes will be overwritten), edit the generator's templates instead.
  */
 import { computeContentSha256Hex } from './request-body-hash.js';
-import { readApiTrailingSlashEnv } from './request-url.js';
-import { withTrailingSlash } from '../utils/url-prefix.js';
+import { readTrailingSlashEnv, withTrailingSlash } from '../utils/url-prefix.js';
 /**
  * Typed client for the CanopyCMS API: one method per endpoint, grouped by namespace, each
  * returning that endpoint's ApiResponse.
@@ -262,7 +261,7 @@ export class CanopyApiClient {
         this.baseUrl = options.baseUrl ?? '/api/canopycms';
         // An unbound fetch throws "Illegal invocation" in browsers; Node has no window.
         this.fetchFn = options.fetch ?? (typeof window !== 'undefined' ? fetch.bind(window) : fetch);
-        this.trailingSlash = options.trailingSlash ?? readApiTrailingSlashEnv();
+        this.trailingSlash = options.trailingSlash ?? readTrailingSlashEnv();
         this.onUnauthorized = options.onUnauthorized;
     }
     buildPath(template, params) {

package/dist/api/content.js

@@ -91,12 +91,16 @@ const readContentHandler = async (gc, ctx, req, params) => {
         const message = err instanceof ContentStoreError ? err.message : 'Invalid content request';
         return { ok: false, status: 400, error: sanitizeErrorMessage(message) };
     }
-    const access = await ctx.services.checkContentAccess(branchContext, branchContext.branchRoot, entryLogicalPath(schemaItem.logicalPath, slug), req.user, 'read');
-    if (!access.allowed) {
+    // One checker for the entry and every reference target it resolves, so a reference cannot
+    // carry a target's data past the rules that would refuse a direct read of it.
+    const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchContext.branchRoot, req.user);
+    if (!checkAccess(entryLogicalPath(schemaItem.logicalPath, slug), 'read').allowed) {
         return { ok: false, status: 403, error: 'Forbidden' };
     }
     try {
-        const doc = await store.read(schemaItem.logicalPath, slug);
+        const doc = await store.read(schemaItem.logicalPath, slug, {
+            referenceAccess: (targetPath) => checkAccess(targetPath, 'read').allowed,
+        });
         return { ok: true, status: 200, data: doc };
     }
     catch (err) {

package/dist/api/entries.js

@@ -299,13 +299,16 @@ const deleteEntryHandler = async (gc, ctx, req, params) => {
                     // C6: order cleanup is best-effort hygiene after the entry is already deleted, so no
                     // failure here may turn an otherwise-successful delete into an error (a retry would
                     // just 404). Surface it as a warning instead (mirrors content.ts's `validationWarnings`).
-                    const reason = err instanceof SchemaStoreBusyError ? 'schema is busy' : getErrorMessage(err);
-                    log.warn('delete-entry', 'Skipped order cleanup', {
-                        collectionPath,
-                        contentId,
-                        error: getErrorMessage(err),
-                    });
-                    orderCleanupWarning = `Entry deleted, but the collection order list could not be updated (${sanitizeErrorMessage(reason)}); it will still list this entry until the next schema change.`;
+                    // An `'unknown'` outcome means the update ran to completion: nothing to warn of.
+                    if (!(err instanceof SchemaStoreBusyError && err.outcome === 'unknown')) {
+                        const reason = err instanceof SchemaStoreBusyError ? 'schema is busy' : getErrorMessage(err);
+                        log.warn('delete-entry', 'Skipped order cleanup', {
+                            collectionPath,
+                            contentId,
+                            error: getErrorMessage(err),
+                        });
+                        orderCleanupWarning = `Entry deleted, but the collection order list could not be updated (${sanitizeErrorMessage(reason)}); it will still list this entry until the next schema change.`;
+                    }
                 }
             }
         }

package/dist/api/resolve-references.js

@@ -1,10 +1,6 @@
 import { z } from 'zod';
 import { ContentStore } from '../content-store.js';
 import { defineEndpoint } from './route-builder.js';
-import { ReferenceResolver } from '../reference-resolver.js';
-import { buildResolvedReference } from '../entry-schema.js';
-import { computeEntryUrl } from '../utils/entry-url.js';
-import { entryLogicalPath } from '../paths/index.js';
 import { branchNameSchema, contentIdSchema } from './validators.js';
 /**
  * Resolution does sequential per-ID file I/O, so the request body caps how much filesystem work
@@ -21,48 +17,25 @@ const resolveReferencesBodySchema = z.object({
 const resolveReferencesHandler = async (gc, ctx, req, params, body) => {
     const { branchContext } = gc;
     const { ids } = body;
-    const flatSchema = branchContext.flatSchema;
-    const contentRootName = ctx.services.config.contentRoot || 'content';
-    const store = new ContentStore(branchContext.branchRoot, flatSchema, {
-        contentRootName,
+    const store = new ContentStore(branchContext.branchRoot, branchContext.flatSchema, {
+        contentRootName: ctx.services.config.contentRoot || 'content',
     });
-    // Get ID index (automatically loads if needed)
-    const idIndex = await store.idIndex();
-    // Resolve each ID to full document
-    const resolver = new ReferenceResolver(store, idIndex);
-    // Build the access checker once, reused for every id instead of re-loading per id in the loop.
-    // A failure here (e.g. settings workspace unavailable) surfaces as a handler error, not
-    // swallowed silently per id.
+    // Built once for every id. A failure here (e.g. settings workspace unavailable) surfaces as a
+    // handler error rather than being swallowed per id.
     const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchContext.branchRoot, req.user);
+    const access = (logicalPath) => checkAccess(logicalPath, 'read').allowed;
+    // The resolution `read()` applies to a reference field, so live preview shows this user what
+    // `read()` would: the target's data, or a `RestrictedReference` for a target they may not
+    // read. The target's own references stay ids, as in `read()`.
     const resolved = {};
     for (const id of ids) {
         try {
-            const result = await resolver.resolve(id);
-            if (result && result.exists && result.collection && result.slug) {
-                // Check path-level read permission before returning content
-                const access = checkAccess(entryLogicalPath(result.collection, result.slug), 'read');
-                if (!access.allowed)
-                    continue;
-                // `resolveReferences: false` matches the server-side resolver (content-store.ts's
-                // resolveSingleReferenceOnce), so a nested reference inside a target renders the same way
-                // in live preview as on the published site, instead of resolving one level deeper.
-                const doc = await store.read(result.collection, result.slug, { resolveReferences: false });
-                if (doc && doc.data) {
-                    // Same shape as the server-side resolver: target data first, then the reserved keys.
-                    // Order is the corruption guard (a target modelling `id` as content must not shadow the
-                    // real content ID); the extra keys (incl. `urlPath`) keep live preview and production
-                    // in sync for consumers like client-reference-resolver.ts.
-                    resolved[id] = buildResolvedReference(doc.data, {
-                        id,
-                        slug: result.slug,
-                        collection: result.collection,
-                        urlPath: computeEntryUrl(result.collection, result.slug, contentRootName),
-                    });
-                }
-            }
+            const value = await store.resolveReferenceTarget(id, access);
+            if (value)
+                resolved[id] = value;
         }
         catch (error) {
-            // Skip failed resolutions, don't block entire request
+            // An id that fails to resolve is omitted rather than failing the whole request.
             console.error(`Failed to resolve reference ID ${id}:`, error);
         }
     }
@@ -73,7 +46,8 @@ const resolveReferencesHandler = async (gc, ctx, req, params, body) => {
     };
 };
 /**
- * Resolve reference IDs to full document objects
+ * Resolve reference IDs as a reference field would: full target data, or title + URL tagged
+ * `unavailable` for a target the user may not read. An id naming no entry is omitted.
  * POST /:branch/resolve-references
  * Body: { ids: string[] }
  */

package/dist/api/user.d.ts

@@ -1,7 +1,10 @@
 import type { ApiResponse } from './types.js';
+import type { BuildIdentity } from '../types.js';
 export type UserInfoResponse = ApiResponse<{
     userId: string;
     groups: string[];
+    /** Admins only: the deployed version is reconnaissance for anyone else. */
+    build?: BuildIdentity;
 }>;
 export declare const USER_ROUTES: {
     readonly whoami: import("./route-builder.js").RouteDefinition<undefined, undefined, UserInfoResponse>;

package/dist/api/user.js

@@ -1,4 +1,6 @@
 import { defineEndpoint } from './route-builder.js';
+import { isAdmin } from '../authorization/helpers.js';
+import { getBuildIdentity } from '../build-identity.js';
 /**
  * This is a PUBLIC endpoint - no special permissions required
  */
@@ -10,6 +12,7 @@ const getUserInfoHandler = async (ctx, req) => {
         data: {
             userId: req.user.userId,
             groups: req.user.groups,
+            ...(isAdmin(req.user.groups) ? { build: getBuildIdentity() } : {}),
         },
     };
 };

package/dist/assets/factory.d.ts

@@ -3,6 +3,11 @@
  *
  * This is the one place that turns the (currently-unconsumed) `media` config
  * into a real store — see .claude/future-tasks/resolved/assets-media-system.md.
+ *
+ * The store is branch-agnostic: a local one is rooted at the dev workspace's
+ * `assets/` or at `media.directory` resolved against the process's working
+ * directory, never inside a branch clone. So asset writes take no [SYNC-C1]
+ * content-write lock — the worker's rebase never touches them.
  */
 import type { MediaConfig } from '../config/types.js';
 import type { AssetStore } from './types.js';

package/dist/assets/factory.js

@@ -3,6 +3,11 @@
  *
  * This is the one place that turns the (currently-unconsumed) `media` config
  * into a real store — see .claude/future-tasks/resolved/assets-media-system.md.
+ *
+ * The store is branch-agnostic: a local one is rooted at the dev workspace's
+ * `assets/` or at `media.directory` resolved against the process's working
+ * directory, never inside a branch clone. So asset writes take no [SYNC-C1]
+ * content-write lock — the worker's rebase never touches them.
  */
 import { LocalAssetStore } from './store-local.js';
 import { S3AssetStore } from './store-s3.js';

package/dist/branch-workspace.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { ensureBranchRoot } from './paths/index.js';
+import { BranchPathError, ensureBranchRoot, isSettingsBranchName } from './paths/index.js';
 import { getBranchMetadataFileManager, loadBranchContext } from './branch-metadata.js';
 import { readsFromCheckout } from './build-mode.js';
 import { operatingStrategy } from './operating-mode/index.js';
@@ -77,6 +77,11 @@ export class BranchWorkspaceManager {
     }
     async openOrCreateBranch(options) {
         const { branchName, mode, basePathOverride, title, description, access, createdBy, remoteUrl } = options;
+        // resolveBranchPath refuses the reserved prefix; this also refuses an adopter's
+        // configured settings branch name, which only the config knows.
+        if (isSettingsBranchName(branchName, operatingStrategy(mode).getSettingsBranchName(this.config))) {
+            throw new BranchPathError('Settings branches are not content branches');
+        }
         const { branchRoot, baseRoot, branchName: safeName, } = await ensureBranchRoot({
             mode,
             branchName,

package/dist/build-identity.d.ts

@@ -0,0 +1,3 @@
+import type { BuildIdentity } from './types.js';
+export type { BuildIdentity };
+export declare function getBuildIdentity(env?: NodeJS.ProcessEnv): BuildIdentity;

package/dist/build-identity.js

@@ -0,0 +1,13 @@
+import { CANOPYCMS_VERSION } from './version.js';
+/**
+ * Set by the image build (Dockerfile.cms `ARG`), not by the infrastructure: a Lambda env var
+ * would name the infrastructure's commit and hide an image/infrastructure skew.
+ */
+const SOURCE_REVISION_ENV = 'CANOPY_SOURCE_SHA';
+export function getBuildIdentity(env = process.env) {
+    // The Dockerfile sets the variable to the empty string when the build arg is not passed.
+    const sourceRevision = env[SOURCE_REVISION_ENV]?.trim();
+    return sourceRevision
+        ? { canopycmsVersion: CANOPYCMS_VERSION, sourceRevision }
+        : { canopycmsVersion: CANOPYCMS_VERSION };
+}