canopycms 0.0.67 → 0.0.68-int.100

package/dist/github-service.d.ts

@@ -76,6 +76,7 @@ export interface PullRequestDetails {
     state: 'open' | 'closed';
     merged: boolean;
     draft: boolean;
+    body: string;
 }
 export interface CreateOrUpdatePullRequestParams {
     octokit: Octokit;
@@ -87,6 +88,11 @@ export interface CreateOrUpdatePullRequestParams {
     body: string;
     /** Convert a pre-existing draft PR to ready-for-review after updating it. */
     markReadyIfDraft?: boolean;
+    /**
+     * `body` is the canopycms PR section: an existing PR keeps the text outside
+     * its section (see mergePrSection) instead of having its body replaced.
+     */
+    mergeSectionIntoBody?: boolean;
     /** Forwarded to all GitHub requests (worker task-timeout abort). */
     signal?: AbortSignal;
 }
@@ -128,6 +134,8 @@ export declare class GitHubService {
         body: string;
         /** Convert a pre-existing draft PR to ready-for-review after updating it. */
         markReadyIfDraft?: boolean;
+        /** See {@link CreateOrUpdatePullRequestParams.mergeSectionIntoBody}. */
+        mergeSectionIntoBody?: boolean;
     }): Promise<{
         number: number;
         url: string;

package/dist/github-service.js

@@ -7,6 +7,7 @@ import { getErrorMessage } from './utils/error.js';
 // or CloudWatch folds it into the previous event. Under Lambda/dev the helper
 // is plain console. See utils/logger.ts.
 import { canopyLogWarn } from './utils/logger.js';
+import { mergePrSection } from './submission-attribution.js';
 const ThrottledOctokit = Octokit.plugin(throttling);
 /**
  * Retry primary rate limits at most twice and only for short waits; beyond
@@ -67,6 +68,7 @@ export function createCanopyOctokit(options) {
  */
 export async function createOrUpdatePullRequest(params) {
     const { octokit, owner, repo, head, base, title, body, markReadyIfDraft, signal } = params;
+    const mergeSection = params.mergeSectionIntoBody === true;
     // CONDITIONAL spread: with no signal, the request objects below carry no
     // `request` key at all (github-service.test.ts asserts on their exact shape).
     const requestOption = signal ? { request: { signal } } : {};
@@ -92,7 +94,7 @@ export async function createOrUpdatePullRequest(params) {
             repo,
             pull_number: existing.number,
             title,
-            body,
+            body: mergeSection ? mergePrSection(existing.body, body) : body,
             ...requestOption,
         });
         // Only a pre-existing PR can be a draft on this path — pulls.create
@@ -185,6 +187,7 @@ export class GitHubService {
             title: options.title,
             body: options.body,
             markReadyIfDraft: options.markReadyIfDraft,
+            mergeSectionIntoBody: options.mergeSectionIntoBody,
         });
         return { number: result.number, url: result.url };
     }
@@ -200,6 +203,7 @@ export class GitHubService {
             state: response.data.state,
             merged: response.data.merged ?? false,
             draft: response.data.draft ?? false,
+            body: response.data.body ?? '',
         };
     }
     async convertToDraft(prNumber) {

package/dist/http/handler.js

@@ -1,27 +1,31 @@
 import { jsonResponse, isCanopyBinaryResponse } from './types.js';
+import { workerNotReadyResponse } from './worker-not-ready.js';
 import { createCanopyRouter } from './router.js';
 import { assertAuthPluginAllowedForMode } from '../auth/plugin.js';
 import { createCanopyServices } from '../services.js';
+import { recordConfiguredSparseCone } from '../branch-sparse.js';
 import { loadBranchContext, BranchWorkspaceManager } from '../branch-workspace.js';
 import { BranchMetadataCorruptError } from '../branch-metadata.js';
 import { resolveCanopyUser } from '../resolve-canopy-user.js';
 import { authResultToCanopyUser } from '../user.js';
 import { isAdmin } from '../authorization/index.js';
+import { isSettingsBranchName } from '../paths/branch-name.js';
 import { clientOperatingStrategy, operatingStrategy } from '../operating-mode/index.js';
 import { getErrorMessage, redactCredentials, sanitizeErrorMessage } from '../utils/error.js';
 // canopyLogError, not console.error: this is shared code and not guaranteed to
 // stay out of the worker's runtime import closure, so new log lines here go
 // through the indirection (utils/logger.ts).
 import { canopyLogError } from '../utils/logger.js';
+import { runWithRequestTiming, setRequestTimingRoute, timeRequestPhase, } from '../utils/request-timing.js';
 const buildContext = async (options) => {
     const services = options.services ?? (options.config ? await createCanopyServices(options.config) : undefined);
     if (!services) {
         throw new Error('CanopyCMS: config or services is required');
     }
+    await recordConfiguredSparseCone(services.config);
     const operatingMode = services.config.mode;
-    // Derive from the strategy, which resolves deploymentName; a literal here
-    // would not match a deployment-namespaced settings branch (say
-    // canopycms-settings-acme), so getBranchContext could never auto-create it.
+    // Derived from the strategy, which resolves deploymentName; a literal here
+    // would miss a deployment-namespaced settings branch (say canopycms-settings-acme).
     const settingsBranch = operatingStrategy(operatingMode).getSettingsBranchName(services.config);
     const getBranchContext = options.getBranchContext ??
         (async (branch, opts) => {
@@ -42,7 +46,7 @@ const buildContext = async (options) => {
             const baseBranch = services.config.defaultBaseBranch ?? 'main';
             const activeBranch = services.config.defaultActiveBranch ?? baseBranch;
             const shouldAutoCreate = clientOperatingStrategy(operatingMode).supportsBranching() &&
-                (branch === baseBranch || branch === activeBranch || branch === settingsBranch);
+                (branch === baseBranch || branch === activeBranch);
             if (shouldAutoCreate) {
                 const manager = new BranchWorkspaceManager(services.config);
                 const context = await manager.openOrCreateBranch({
@@ -62,7 +66,14 @@ const buildContext = async (options) => {
     return {
         services,
         assetStore: options.assetStore,
-        getBranchContext,
+        // The settings branch lives only in the settings workspace. Resolving it as a
+        // content branch would let any request clone a content-history copy that a
+        // submit pushes under the settings name, which settings provisioning then refuses,
+        // leaving settings unavailable.
+        // Not found, like any branch the caller cannot resolve, even a workspace left on disk.
+        getBranchContext: (branch, opts) => isSettingsBranchName(branch, settingsBranch)
+            ? Promise.resolve(null)
+            : timeRequestPhase('branchContext', () => getBranchContext(branch, opts)),
         authPlugin: options.authPlugin,
     };
 };
@@ -109,10 +120,11 @@ export function createCanopyRequestHandler(options) {
         if (!match) {
             return jsonResponse({ ok: false, status: 404, error: 'Not found' }, 404);
         }
-        const apiCtx = await getContext();
+        setRequestTimingRoute(match.pattern.join('/') || '(malformed path)');
+        const apiCtx = await timeRequestPhase('context', getContext);
         // In dev mode, re-check if the developer switched git branches
-        await apiCtx.services.refreshActiveBranch();
-        const authResult = await options.authPlugin.authenticate(req);
+        await timeRequestPhase('refreshBranch', () => apiCtx.services.refreshActiveBranch());
+        const authResult = await timeRequestPhase('auth', () => options.authPlugin.authenticate(req));
         // API routes require authentication. Anonymous callers are rejected BEFORE
         // any workspace provisioning below, so they can neither trigger expensive
         // git operations nor read provisioning error details.
@@ -141,6 +153,9 @@ export function createCanopyRequestHandler(options) {
                 // (authenticated) client. Credentials, which git errors can embed, are
                 // redacted even from the server logs.
                 console.error(`CanopyCMS: Failed to provision workspace for base branch '${baseBranch}': ${redactCredentials(message)}`);
+                const notReady = workerNotReadyResponse(err);
+                if (notReady)
+                    return notReady;
                 return jsonResponse({
                     ok: false,
                     status: 503,
@@ -157,15 +172,21 @@ export function createCanopyRequestHandler(options) {
         // a silent authorization change.
         let user;
         try {
-            user = await resolveCanopyUser(authResult, {
+            user = await timeRequestPhase('user', () => resolveCanopyUser(authResult, {
                 getSettingsBranchRoot: apiCtx.services.getSettingsBranchRoot,
                 mode: apiCtx.services.config.mode,
                 bootstrapAdminIds: apiCtx.services.bootstrapAdminIds,
-            });
+            }));
         }
         catch (err) {
             const message = getErrorMessage(err);
             canopyLogError(`CanopyCMS: Failed to resolve internal groups from the settings workspace: ${redactCredentials(message)}`);
+            // No remote means no settings workspace, so /admin cannot load either:
+            // the worker has not created the remote yet, so every caller gets the
+            // not-ready 503, bootstrap admins included.
+            const notReady = workerNotReadyResponse(err);
+            if (notReady)
+                return notReady;
             // Same trade as the base-branch degradation above: /admin is the recovery
             // surface for exactly this failure (a renamed settings branch trips
             // assertSettingsWorkspaceIdentity until a human intervenes), so 503ing it
@@ -231,7 +252,7 @@ export function createCanopyRequestHandler(options) {
             if (validationResult.body !== undefined) {
                 handlerArgs.push(validationResult.body);
             }
-            const result = await match.handler(...handlerArgs);
+            const result = await timeRequestPhase('route', () => match.handler(...handlerArgs));
             // Binary routes carry their own status and headers and MUST reach the
             // adapter untouched: jsonResponse would serialize raw bytes and drop
             // contentType/contentDisposition.
@@ -242,7 +263,7 @@ export function createCanopyRequestHandler(options) {
         else {
             // Every route should use defineEndpoint; this is the safety net for one
             // that carries no validate function.
-            const result = await match.handler(apiCtx, apiReq, mergedParams);
+            const result = await timeRequestPhase('route', () => match.handler(apiCtx, apiReq, mergedParams));
             if (isCanopyBinaryResponse(result))
                 return result;
             return jsonResponse(result, result.status);
@@ -250,12 +271,15 @@ export function createCanopyRequestHandler(options) {
     };
     return async (req, pathSegments) => {
         try {
-            return await handleRequest(req, pathSegments);
+            return await runWithRequestTiming(req.method, () => handleRequest(req, pathSegments), (response) => response.status);
         }
         catch (err) {
             // Last-resort boundary (API-C1): see handleRequest's doc comment above.
             const message = getErrorMessage(err);
             console.error('CanopyCMS: Unhandled error in API request handler:', message);
+            const notReady = workerNotReadyResponse(err);
+            if (notReady)
+                return notReady;
             return jsonResponse({ ok: false, status: 500, error: sanitizeErrorMessage(message) }, 500);
         }
     };

package/dist/http/index.d.ts

@@ -4,3 +4,5 @@ export type { CanopyHandler, RouteDefinition, RouteMatch, CanopyRouter } from '.
 export { createCanopyRouter } from './router.js';
 export type { CanopyHandlerOptions, CanopyRequestHandler } from './handler.js';
 export { createCanopyRequestHandler, createCanopyRequestHandlerFromConfig } from './handler.js';
+export { RemoteNotReadyError } from '../git-manager.js';
+export { workerNotReadyResponse, WORKER_NOT_READY_MESSAGE } from './worker-not-ready.js';

package/dist/http/index.js

@@ -1,3 +1,5 @@
 export { jsonResponse, isCanopyBinaryResponse } from './types.js';
 export { createCanopyRouter } from './router.js';
 export { createCanopyRequestHandler, createCanopyRequestHandlerFromConfig } from './handler.js';
+export { RemoteNotReadyError } from '../git-manager.js';
+export { workerNotReadyResponse, WORKER_NOT_READY_MESSAGE } from './worker-not-ready.js';

package/dist/http/router.d.ts

@@ -32,6 +32,8 @@ export interface RouteDefinition {
 }
 export interface RouteMatch {
     handler: CanopyHandler;
+    /** The matched route's pattern; empty for the synthetic malformed-path match. */
+    pattern: readonly string[];
     params: Record<string, string>;
     validate?: RouteDefinition['validate'];
     bodyFormat?: RouteDefinition['bodyFormat'];

package/dist/http/router.js

@@ -122,10 +122,11 @@ export function matchRoute(routes, method, segments) {
         decodedParams = Object.fromEntries(Object.entries(best.params).map(([key, value]) => [key, decodeURIComponent(value)]));
     }
     catch {
-        return { handler: malformedPathHandler, params: {} };
+        return { handler: malformedPathHandler, pattern: [], params: {} };
     }
     return {
         handler: best.route.handler,
+        pattern: best.route.pattern,
         params: decodedParams,
         validate: best.route.validate, // Include validation function if present
         bodyFormat: best.route.bodyFormat,

package/dist/http/types.d.ts

@@ -37,6 +37,8 @@ export interface CanopyBinaryResponse {
         contentDisposition?: string;
         cacheControl?: string;
         etag?: string;
+        /** Redirect target, for a 3xx `status`; `body` is then empty. */
+        location?: string;
     };
 }
 export declare function jsonResponse<T>(body: T, status?: number, headers?: Record<string, string>): CanopyResponse<T>;

package/dist/http/worker-not-ready.d.ts

@@ -0,0 +1,10 @@
+import type { ApiResponse } from '../api/types.js';
+import { type CanopyResponse } from './types.js';
+export declare const WORKER_NOT_READY_MESSAGE = "CMS worker not ready \u2014 it may still be starting. Try again in a minute; if this persists, ask an admin to check the CMS worker.";
+/**
+ * The retriable 503 for a request that hit {@link RemoteNotReadyError} or
+ * {@link BranchProvisioningBusyError}, or `undefined` for any other error. The single mapping
+ * point for the core handler, the AI route and every framework adapter's backstop, so the
+ * message and `Retry-After` cannot diverge.
+ */
+export declare function workerNotReadyResponse(err: unknown): CanopyResponse<ApiResponse> | undefined;

package/dist/http/worker-not-ready.js

@@ -0,0 +1,24 @@
+import { BranchProvisioningBusyError } from '../branch-provisioning.js';
+import { RemoteNotReadyError } from '../git-manager.js';
+import { jsonResponse } from './types.js';
+/** Seconds a client should wait before retrying while the worker boots. */
+const RETRY_AFTER_SECONDS = '30';
+export const WORKER_NOT_READY_MESSAGE = 'CMS worker not ready — it may still be starting. Try again in a minute; if this persists, ask an admin to check the CMS worker.';
+/**
+ * The retriable 503 for a request that hit {@link RemoteNotReadyError} or
+ * {@link BranchProvisioningBusyError}, or `undefined` for any other error. The single mapping
+ * point for the core handler, the AI route and every framework adapter's backstop, so the
+ * message and `Retry-After` cannot diverge.
+ */
+export function workerNotReadyResponse(err) {
+    const message = err instanceof RemoteNotReadyError
+        ? WORKER_NOT_READY_MESSAGE
+        : err instanceof BranchProvisioningBusyError
+            ? err.message
+            : undefined;
+    if (message === undefined)
+        return undefined;
+    return jsonResponse({ ok: false, status: 503, error: message }, 503, {
+        'Retry-After': RETRY_AFTER_SECONDS,
+    });
+}

package/dist/operating-mode/client-unsafe-strategy.js

@@ -57,9 +57,6 @@ class ProdStrategy extends ProdClientSafeStrategy {
             throw new Error('gitBotAuthorName and gitBotAuthorEmail are required in prod mode');
         }
     }
-    shouldCreateSettingsPR(config) {
-        return config.autoCreateSettingsPR ?? true;
-    }
 }
 class DevStrategy extends DevClientSafeStrategy {
     getWorkspaceRoot(sourceRoot) {
@@ -107,9 +104,6 @@ class DevStrategy extends DevClientSafeStrategy {
     validateConfig(_config) {
         // No special validation for dev mode
     }
-    shouldCreateSettingsPR(_config) {
-        return false; // No real GitHub in local dev mode
-    }
 }
 const strategyCache = new Map();
 /**

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

@@ -47,7 +47,7 @@ export interface ClientSafeStrategy {
 export interface ClientUnsafeStrategy extends ClientSafeStrategy {
     /**
      * The mode's workspace root; content-branches, settings and .cache all live
-     * under it. prod: CANOPYCMS_WORKSPACE_ROOT ?? /mnt/efs/workspace.
+     * under it. prod: CANOPYCMS_WORKSPACE_ROOT ?? /mnt/efs.
      * dev: {sourceRoot ?? cwd}/.canopy-dev.
      */
     getWorkspaceRoot(sourceRoot?: string): string;
@@ -89,7 +89,4 @@ export interface ClientUnsafeStrategy extends ClientSafeStrategy {
     getSettingsRoot(sourceRoot?: string): string;
     usesSeparateSettingsBranch(): boolean;
     validateConfig(config: Partial<CanopyConfig>): void;
-    shouldCreateSettingsPR(config: {
-        autoCreateSettingsPR?: boolean;
-    }): boolean;
 }

package/dist/paths/branch-name.d.ts

@@ -29,6 +29,11 @@ export declare function sanitizeBranchName(branchName: string): SanitizedBranchN
  * branch.
  */
 export declare const RESERVED_SETTINGS_BRANCH_PREFIX = "canopycms-settings-";
+/**
+ * Whether `branchName` is a settings branch, never a content branch: the reserved prefix, or the
+ * configured name (which need not carry it). Compared sanitized, the form git and disk use.
+ */
+export declare function isSettingsBranchName(branchName: string, settingsBranchName?: string): boolean;
 /**
  * Branch names that collide with a static top-level API route namespace.
  *

package/dist/paths/branch-name.js

@@ -33,6 +33,15 @@ export function sanitizeBranchName(branchName) {
  * branch.
  */
 export const RESERVED_SETTINGS_BRANCH_PREFIX = 'canopycms-settings-';
+/**
+ * Whether `branchName` is a settings branch, never a content branch: the reserved prefix, or the
+ * configured name (which need not carry it). Compared sanitized, the form git and disk use.
+ */
+export function isSettingsBranchName(branchName, settingsBranchName) {
+    const sanitized = sanitizeBranchName(branchName);
+    return (sanitized.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX) ||
+        (settingsBranchName !== undefined && sanitized === sanitizeBranchName(settingsBranchName)));
+}
 /**
  * Branch names that collide with a static top-level API route namespace.
  *

package/dist/paths/branch.d.ts

@@ -14,11 +14,15 @@ export interface BranchPathResult {
 /** @internal Exported for tests. */
 export declare class BranchPathError extends Error {
 }
+/**
+ * True when a branch load failed because the name names no workspace: a traversal segment, a name
+ * too long for a filename, or a path through a file (ENOTDIR), as `?branch=branches.json` gives.
+ */
+export declare function namesNoWorkspace(err: unknown): boolean;
 import { sanitizeBranchName } from './branch-name.js';
 /** @internal Exported for tests. */
 export { sanitizeBranchName };
-/** Resolve a branch name to workspace paths, rejecting path traversal. */
+/** Resolve a branch name to workspace paths, rejecting traversal and settings-branch names. */
 export declare function resolveBranchPath(options: BranchPathOptions): BranchPathResult;
-export declare function ensureBranchRoot(options: BranchPathOptions): Promise<BranchPathResult>;
 export declare function getDefaultBranchBase(mode: OperatingMode, override?: string): string;
 export declare function resolveBranchPaths(branchContext: BranchContext, mode: OperatingMode, basePathOverride?: string): BranchPathResult;

package/dist/paths/branch.js

@@ -1,23 +1,34 @@
 /** Branch path resolution utilities. */
-import fs from 'node:fs/promises';
 import path from 'node:path';
 import { operatingStrategy } from '../operating-mode/index.js';
+import { isNodeError } from '../utils/error.js';
 /** @internal Exported for tests. */
 export class BranchPathError extends Error {
 }
-// Lives in ./branch-name (dependency-free); re-exported here for server-side
-// importers, who may safely reach this module's node:fs imports.
-import { sanitizeBranchName } from './branch-name.js';
+/**
+ * True when a branch load failed because the name names no workspace: a traversal segment, a name
+ * too long for a filename, or a path through a file (ENOTDIR), as `?branch=branches.json` gives.
+ */
+export function namesNoWorkspace(err) {
+    if (err instanceof BranchPathError)
+        return true;
+    return isNodeError(err) && (err.code === 'ENAMETOOLONG' || err.code === 'ENOTDIR');
+}
+// Lives in ./branch-name (dependency-free); re-exported for server-side importers.
+import { sanitizeBranchName, isSettingsBranchName } from './branch-name.js';
 /** @internal Exported for tests. */
 export { sanitizeBranchName };
 const resolveContentBranchesRoot = (mode, override) => {
     return operatingStrategy(mode).getContentBranchesRoot(override);
 };
-/** Resolve a branch name to workspace paths, rejecting path traversal. */
+/** Resolve a branch name to workspace paths, rejecting traversal and settings-branch names. */
 export function resolveBranchPath(options) {
     if (options.branchName.includes('..')) {
         throw new BranchPathError('Branch name cannot contain traversal segments');
     }
+    if (isSettingsBranchName(options.branchName)) {
+        throw new BranchPathError('Settings branches are not content branches');
+    }
     const safeBranch = sanitizeBranchName(options.branchName);
     const strategy = operatingStrategy(options.mode);
     const baseRoot = resolveContentBranchesRoot(options.mode, options.basePathOverride);
@@ -35,11 +46,6 @@ export function resolveBranchPath(options) {
     }
     return { branchRoot, baseRoot: normalizedBase, branchName: safeBranch };
 }
-export async function ensureBranchRoot(options) {
-    const result = resolveBranchPath(options);
-    await fs.mkdir(result.branchRoot, { recursive: true });
-    return result;
-}
 export function getDefaultBranchBase(mode, override) {
     return resolveContentBranchesRoot(mode, override);
 }

package/dist/paths/index.d.ts

@@ -3,9 +3,9 @@
  * because this barrel pulls in node:fs; `pnpm lint:bundle` enforces that.
  */
 export type { LogicalPath, PhysicalPath, SanitizedBranchName, BranchName, ContentId, Slug, PathValidationResult, } from './types.js';
-export { normalizeFilesystemPath, normalizeCollectionPath, hasTraversalSequence, createLogicalPath, createPhysicalPath, joinPath, trimSlashes, } from './normalize.js';
+export { normalizeFilesystemPath, normalizeCollectionPath, hasTraversalSequence, createLogicalPath, createPhysicalPath, entryLogicalPath, joinPath, trimSlashes, } from './normalize.js';
 export { validateAndNormalizePath } from './normalize-server.js';
 export { validateContentPath, isValidCollectionPath, sanitizeForPath, hasEmbeddedContentId, looksLikePhysicalPath, looksLikeLogicalPath, parseLogicalPath, parsePhysicalPath, isValidContentId, parseContentId, parseBranchName, parseSlug, } from './validation.js';
 export { resolveLogicalPath } from './resolve.js';
-export { resolveBranchPath, ensureBranchRoot, getDefaultBranchBase, resolveBranchPaths, BranchPathError, type BranchPathOptions, type BranchPathResult, } from './branch.js';
-export { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, } from './branch-name.js';
+export { resolveBranchPath, getDefaultBranchBase, resolveBranchPaths, BranchPathError, namesNoWorkspace, type BranchPathOptions, type BranchPathResult, } from './branch.js';
+export { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, isSettingsBranchName, } from './branch-name.js';

package/dist/paths/index.js

@@ -3,10 +3,10 @@
  * because this barrel pulls in node:fs; `pnpm lint:bundle` enforces that.
  */
 // Normalization utilities (client-safe)
-export { normalizeFilesystemPath, normalizeCollectionPath, hasTraversalSequence, createLogicalPath, createPhysicalPath, joinPath, trimSlashes, } from './normalize.js';
+export { normalizeFilesystemPath, normalizeCollectionPath, hasTraversalSequence, createLogicalPath, createPhysicalPath, entryLogicalPath, joinPath, trimSlashes, } from './normalize.js';
 // Normalization utilities (server-only, requires Node.js path module)
 export { validateAndNormalizePath } from './normalize-server.js';
 export { validateContentPath, isValidCollectionPath, sanitizeForPath, hasEmbeddedContentId, looksLikePhysicalPath, looksLikeLogicalPath, parseLogicalPath, parsePhysicalPath, isValidContentId, parseContentId, parseBranchName, parseSlug, } from './validation.js';
 export { resolveLogicalPath } from './resolve.js';
-export { resolveBranchPath, ensureBranchRoot, getDefaultBranchBase, resolveBranchPaths, BranchPathError, } from './branch.js';
-export { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, } from './branch-name.js';
+export { resolveBranchPath, getDefaultBranchBase, resolveBranchPaths, BranchPathError, namesNoWorkspace, } from './branch.js';
+export { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, isSettingsBranchName, } from './branch-name.js';

package/dist/paths/normalize.d.ts

@@ -25,6 +25,13 @@ export declare function normalizeCollectionPath(collectionPath: string, contentR
 export declare function hasTraversalSequence(path: string): boolean;
 /** Join segments into a LogicalPath, throwing on a traversal sequence. */
 export declare function createLogicalPath(...segments: string[]): LogicalPath;
+/**
+ * An entry's logical path: `<collection logical path>/<slug>`, e.g. `content/blog/my-post`,
+ * or `content/about` for an entry of the root collection. Path-permission rules match this
+ * form. No traversal check, unlike `createLogicalPath`: a slug read off disk may contain
+ * `..`, and listing must not throw on one.
+ */
+export declare function entryLogicalPath(collectionLogicalPath: LogicalPath | string, slug: string): LogicalPath;
 /**
  * Join segments into a PhysicalPath (segments may carry embedded content IDs,
  * e.g. `my-post.ABC123.mdx`), throwing on a traversal sequence.

package/dist/paths/normalize.js

@@ -48,6 +48,15 @@ export function createLogicalPath(...segments) {
     }
     return normalized;
 }
+/**
+ * An entry's logical path: `<collection logical path>/<slug>`, e.g. `content/blog/my-post`,
+ * or `content/about` for an entry of the root collection. Path-permission rules match this
+ * form. No traversal check, unlike `createLogicalPath`: a slug read off disk may contain
+ * `..`, and listing must not throw on one.
+ */
+export function entryLogicalPath(collectionLogicalPath, slug) {
+    return (collectionLogicalPath ? `${collectionLogicalPath}/${slug}` : slug);
+}
 /**
  * Join segments into a PhysicalPath (segments may carry embedded content IDs,
  * e.g. `my-post.ABC123.mdx`), throwing on a traversal sequence.

package/dist/paths/validation.js

@@ -186,7 +186,6 @@ export function parseSlug(slug) {
             error: 'Slug is required',
         };
     }
-    // Check length (filesystem path safety)
     if (slug.length > 64) {
         return { ok: false, error: 'Slug too long (max 64 characters)' };
     }
@@ -202,7 +201,6 @@ export function parseSlug(slug) {
             error: 'Slug cannot be a traversal sequence',
         };
     }
-    // Normalize to lowercase for case-insensitive matching
     const normalized = slug.toLowerCase();
     if (!/^[a-z0-9][a-z0-9-]*$/.test(normalized)) {
         return {

package/dist/reference-resolver.d.ts

@@ -1,30 +1,19 @@
 import type { ContentStore } from './content-store.js';
 import type { ContentIdIndex } from './content-id-index.js';
-import type { LogicalPath, PhysicalPath, Slug } from './paths/index.js';
-export interface ResolvedReference {
-    id: string;
-    exists: boolean;
-    displayValue: string;
-    collection?: LogicalPath;
-    slug?: Slug;
-}
+import { type LogicalPath } from './paths/index.js';
 export interface ReferenceOption {
     id: string;
     label: string;
     collection: string;
 }
 /**
- * ReferenceResolver resolves content IDs to display values for reference fields.
+ * Loads the options a reference field's picker offers. Resolving a stored reference to its
+ * target is `ContentStore`'s job (`read()`, `resolveReferenceTarget`).
  */
 export declare class ReferenceResolver {
     private store;
     private idIndex;
     constructor(store: ContentStore, idIndex: ContentIdIndex);
-    /**
-     * Resolve a content ID to a display value.
-     * Returns null if the ID doesn't exist or points to a collection.
-     */
-    resolve(id: string, displayField?: string): Promise<ResolvedReference | null>;
     /**
      * Load all available reference options for a reference field.
      *
@@ -32,14 +21,9 @@ export declare class ReferenceResolver {
      * At least one of `collections` or `entryTypes` should be provided.
      *
      * @param canAccess - Optional permission predicate, called with each candidate's
-     *   relative path before it is read. Returning false skips the entry entirely --
+     *   logical path (`entryLogicalPath`) before it is read. Returning false skips the entry entirely --
      *   no file I/O, no label, no option -- so a caller who can't read a path never
      *   triggers a read for content they won't be allowed to see anyway.
      */
-    loadReferenceOptions(collections?: LogicalPath[], displayField?: string, search?: string, entryTypes?: string[], canAccess?: (relativePath: PhysicalPath) => boolean): Promise<ReferenceOption[]>;
-    /**
-     * Resolve multiple IDs at once.
-     * Useful for displaying lists of referenced items.
-     */
-    resolveMany(ids: string[], displayField?: string): Promise<(ResolvedReference | null)[]>;
+    loadReferenceOptions(collections?: LogicalPath[], displayField?: string, search?: string, entryTypes?: string[], canAccess?: (logicalPath: LogicalPath) => boolean): Promise<ReferenceOption[]>;
 }